--- 20 Feb 2009 ---------------------------------------------------------------

I've created a set of program that met my needs while writing some papers using
Cadabra. They may or may not be useful to other people (as they say, your
kilometres/litre may vary).

A fair objection to this approach is that the Xcadabra gui does a fine job
and maybe I'm wasting my time. That may well be true, but I like to write
code and I couldn't resist the opportunity to have some fun. I'm sure the
code is probably sloppy in places, probably verbose (it's the nature of
pascal, but I like that) and probably not all that efficient. Oh well,
it does the job.

You might like to read the INSTALL-?.txt file and then look at some of
the examples in the example directory. The two directories lcb09-02
and lcb09-03 contain all of my code for two papers I've recently written
and which make extensive use of Cadabra (and the tools listed here).

Please note that I take full responsibility for everything in this package
and any errors etc. fall to me. Please don't bug Kasper over any of my bugs.
I can be contaced be e-mail and I will endeavour to make corrections to bugs
(but I'm unlikely to make any major revisions). My e-mail address is
Leo.Brewin@sci.monash.edu.au

-------------------------------------------------------------------------------

The basic steps in obtaining a PDF file are as follows.

1. Create a foo.cdbp file containing standard Cadabra code augmented with the
   cdbmerge comments (as listed below).

2. Then run the followng set of commands

	cdbpreproc foo
	cadabra --xcadabra < foo.cdb > foo.xcd
	cdbmerge foo
	cdbpstproc foo
	pdflatex foo
	
	or, if you've installed the supplied shell scripts
	
	$HOME/local/sh/cdbmerge foo

Here is a brief explantion each of the programs.

cdbmerge
--------

This is the main tool. It reads the Cadabra output and produces a new latex
document that merges the original Cadabra code with the Cadabra output. It takes
its cues from comments added to the original Cadabra code in a foo.cdb file. The
set of comments (which must begin in column1) are the following

%!       : print all pending Cadabra output here
%<       : start of a block of LaTeX code, for latter processing by LaTeX
%>       : end of a LaTeX block
%%       : a single line of LaTeX code

cdbpreproc
----------

This reads .cdbp files and writes out a .cdb file. The changes made are trivial --
it converts every line in a LaTeX block so that each line begins with %%

foo.cdbp
%<
This is one line of LaTeX stuff.
This is another line.
%>

cdbpreproc foo

foo.cdb
%%This is one line of LaTeX stuff.
%%This is another line.

cdbpstproc
----------

This strips out various pieces of text from a foo.tex file and saves the result in
foo.notag. The text that it looks for are "\Btag{?}", "\Etag{?}", "\killL\left(",
"\right)\killR" an '~"?"'. The ? inside {?} denotes any word. These string are
left-over from some of the earlier processing by cdbmerge and removing them is just
a case of tidying up. This stage could be left out (but you would need to create
TeX macros for \Btag, \Etag, \killL and \killR that expand to nothing, i.e.
\def\killL{\relax} etc.). If you wish to keep the "\Btag" and "\Etag" tags then
you can use "cdbpstproc foo keep-tags". This is important if you want to use this
latex file as source for some other document (e.g. when using the cdbtags program).

cdbtags
-------

This is a tool to extract tagged sections of one file and insert them into
similarly tagged locations in another file. It can be used to extract pieces of
Cadabra output and include it directly into a latex document. The file
example/lcb09-03/Cadabra/summary.texp draws upon results computed from nine other
Cadabra documents. The cdbtags program will create a new foo.tex file from the
foo.texp file. This automates an otherwise tedious cut-and-paste job (particularily
if the major revisions are made to the Cadabra code).

cdbfile
-------

This is used to create and manage libraries of Cadabra code. It works with the
standard sytnax for exporting the result of a (single) computation. Note that there
are two files that work together to do this job, a binary cdbfile (generated from
the cdbfile.p pascal cprogram) and the shell script also called cdbfile. Both of
these are needed.

# ==============================================================================
#    creating a library and exporting Cadabra output
# ==============================================================================

# --- two results saved to separate text files

@(result1);  "result1.txt"
@(result2);  "result2.txt"

# --- create a new library save.lib

com:="open save.lib":
@run(com){"/Users/leo/local/sh/cdbfile"}:

# --- append the contents of "result1.txt" and "result2.txt"

com:="export save.lib result1.txt":
@run(com){"/Users/leo/local/sh/cdbfile"}:

com:="export save.lib result2.txt":
@run(com){"/Users/leo/local/sh/cdbfile"}:

1. The "open" command deletes the library (if it exist) before creating a new one.
2. The "export" command will delete the source files after the export. Thus in the
   above example "result1.txt" and "result2.txt" will be deleted after their
   respective "export" commands.

# ==============================================================================
#    importing Cadabra output
# ==============================================================================

# --- import two new expressions, "metric1" and "metric2" 

metric1:="import save.lib result1":
@run(metric1){"/Users/leo/local/sh/cdbfile"}:

metric2:="import save.lib result2":
@run(metric2){"/Users/leo/local/sh/cdbfile"}:

1. Note the change in name for the expression. In the library the expressions
   were name "result1" and "result2". But in the above code they will be re-named
   as "metric1" and "metric2".

