More updates and changes

git-svn-id: http://svn.cactuscode.org/flesh/trunk@998 17b73243-c579-4c4c-a9d2-2d5706c11dac

5 files changed, 281 insertions, 181 deletions

diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex
index 4b421e46..ad632ef2 100644
--- a/doc/UsersGuide/Appendices.tex
+++ b/doc/UsersGuide/Appendices.tex
@@ -6,43 +6,45 @@
 \begin{Lentry}
 
 \item[{\tt arrangement}] A collection of thorns.
-\item[{\tt autoconf}]
-\item[{\tt Cactus}]
+\item[{\tt autoconf}] A GNU program which builds a configuration 
+   script which can be used to make a Makefile
+\item[{\tt Cactus}] A green fleshy plant with lots of thorns, usually painful if touched.
 \item[{\tt CCTK}] Cactus Computational Tool Kit (The Cactus flesh and
             computational thorns).
 \item[{\tt CCL}] The {\tt Cactus Configuration Language}, this is the language
 that the thorn configuration files are written in.
-\item[{\tt configuration}]
-\item[{\tt checkout}]
-\item[{\tt checkpointing}]
-\item[{\tt convergence}]
-\item[{\tt CVS}] The {\em ``Concurrent Versioning System''} is the
+\item[{\tt configuration}] 
+\item[{\tt checkout}] Get a copy of the code or thorns from CVS
+\item[{\tt checkpointing}] Save the entire state of a run to file so that it can be restarted at a later time
+\item[{\tt convergence}] 
+\item[{\tt CVS}] The {\em "Concurrent Versioning System"} is the
   favoured distribution system for Cactus and can be
   downloaded from your favorite GNU site.  
 \item[{\tt driver}] A thorn which creates and handles grid hierachies
 \item[{\tt flesh}] The routines which hold all the thorns together, this 
 is what you get if you check out {\tt Cactus} from our CVS repository.
-\item[{\tt friend}]
+\item[{\tt friend}] 
 \item[{\tt GF}] Shorthand for a {\tt grid function}
 \item[{\tt gmake}] 
 \item[{\tt ghostzone}]
-\item[{\tt grid function}]
+\item[{\tt grid function}] 
 \item[{\tt grid hierachy}] A computational grid, and the grid variables associated with it.
-\item[{\tt grid scalar}]
+\item[{\tt grid scalar}] 
 \item[{\tt grid variable}]
 \item[{\tt GNATS}] The GNU program we use for reporting and tracking bugs, 
   comments and suggestions.
 \item[{\tt HDF5}] Hierarchical Data Format version 5
 \item[{\tt implementation}]
-\item[{\tt inherit}]
+\item[{\tt inherit}] 
 \item[{\tt interpolation}]
-\item[{\tt MPI}]
+\item[{\tt MPI}] 
 \item[{\tt parameter}] A variable which remains unchanged throughout the executation of a Cactus executable. Parameters all have default values which can be changed in a parameter file.
 \item[{\tt processor topology}]
 \item[{\tt PUGH}] The default parallel driver for Cactus which uses MPI.
-\item[{\tt PVM}]
+\item[{\tt PVM}]  {\tt Parallel Virtual Machine}, provides interprocessor
+  communication
 \item[{\tt reduction}]
-\item[{\tt TAGS}]
+\item[{\tt TAGS}] 
 \item[{\tt target}]
 \item[{\tt thorn}] A collection of subroutines with a definite interface 
              and purpose.
@@ -70,9 +72,18 @@ case insensitive.
 \section{interface.ccl}
 \label{sec:in}
 
-The interface configuration file consists of a header block giving details 
-of the thorns relationship with other thorns, and then a series of blocks 
+The interface configuration file consists of 
+\begin{itemize}
+\item a header block giving details 
+of the thorns relationship with other thorns
+\item a series of blocks 
 listing the thorn's global variables.
+\item details of other interations with thorns:
+\begin{itemize}
+\item building include files
+\end{itemize}
+\end{itemize} 
+
 The header block has the form:
 {\t 
 \begin{verbatim}
@@ -100,32 +111,40 @@ where
         of all your thorns friend's friends.
 \end{itemize} 
 
+The thorn's variables are collected into groups. This is not only
+for convenience, but for collecting like variables together. 
+Storage assignment, communication assignment and ghostzone synchronization
+takes place for groups only.
+
+
 The thorn's variables are defined by:
 {\t
 \begin{verbatim}
 [<access>:]
 
-VTYPE <group name> [TYPE=<gtype>] [DIM=<dim>] 
+<data_type> <group_name> [TYPE=<group_type>] [DIM=<dim>] [TIMELEVELS=<num>]
 [{
-   <variable name>[,]<variable name>
-   <variable name>
-}] [``<group description>'']
+   <variable_name>[,]<variable_name>
+   <variable_name>
+}] ["<group_description>"]
 \end{verbatim}}
 
 \begin{itemize}
-\item{} {\t access} defines which thorns have  use the following 
-        groups, and can be either {\t public}, {\t protected} or {\t private}.
-\item{} {\t VTYPE} defines the data type of the variables in the group.
+\item{} {\t access} defines which thorns can use the following 
+        groups of variables. {\t access} can be either 
+        {\t public}, {\t protected} or {\t private}.
+\item{} {\t data\_type} defines the data type of the variables in the group.
 Supported data types are {\t BOOLEAN}, {\t INTEGER}, {\t CHAR} and {\t REAL}.
 (In the future {\t COMPLEX} will also be supported.)
-\item{} {\t group name} must be a alpha-numeric name (which may also 
+\item{} {\t group\_name} must be a alpha-numeric name (which may also 
 contain underscores) which is unique 
 within the scope of the thorn. A group name is compulsory.
 \item{} {\t TYPE} designates the kind of variables held by the group.
 The choices are {\t GF}, {\t ARRAY} or {\t SCALAR}. This field is 
 optional, with the default variable type being {\t SCALAR}.
-\item{} {\t DIM} defines the spatial dimension if the group is of type
-{\t ARRAY} or {\t GF}, and can take the value {\t 1}, {\t 2}, or {\t 3}.
+\item{} {\t DIM} defines the spatial dimension if the group is 
+	of type {\t ARRAY} or {\t GF}, and can take the value 
+	{\t 1}, {\t 2}, or {\t 3}.
 The default value is {\t DIM=3}.
 \item{} The block following the group declaration line contains a list of
         variables contained in the group. All variables in a group have 
@@ -149,7 +168,7 @@ range of the parameter separated by optional
 {\it parameter data scoping items} (DSIs) which detail access to the
 parameter.
 
-\subsection{Parameter Data Scoping Items}
+\subsection{Parameter data scoping items}
 {\t
 \begin{verbatim}
 <access>:
@@ -158,61 +177,61 @@ parameter.
 The key word {\t access} designates that all parameter object specification
 items up to the next parameter data scoping item are in the same 
 protection or scoping class. {\t access} can take the values:
-\begin{itemize}
-\item{} {\t global} --- all thorns have access to global parameters
-\item{} {\t restricted} --- other thorns can have access to these 
+\begin{Lentry}
+\item[{\t global}] all thorns have access to global parameters
+\item[{\t restricted}] other thorns can have access to these 
                            parameters if they specifically request
                            it in their own param.ccl
-\item{} {\t private} --- only your thorn has access to private parameters
-\item{} {\t uses} --- in this case an {\t implementation} name must follow
+\item[{\t private}] only your thorn has access to private parameters
+\item[{\t uses}] in this case an {\t implementation} name must follow
                         the colon. It declare that all the parameters in 
                         the following scoping block are restricted variables
                         from the specified {\t implementation}.
-\end{itemize}
+\end{Lentry}
 
 
-\subsection{Parameter Object Specification Items}
+\subsection{Parameter object specification items}
 \label{sec:paobspit}
 
 {\t
 \begin{verbatim}
-[EXTENDS|USES] <parameter type> <parameter name> ``<parameter description>'' 
+[EXTENDS|USES] <parameter_type> <parameter name> "<parameter description>" 
 {
-  <PARAMETER VALUES>
+  <PARAMETER_VALUES>
 } <default value>
 \end{verbatim}
 }
 \begin{itemize}
-\item{} Allowed {\t parameter types} are 
-  \begin{itemize}
-     \item{} {\t INTEGER} The specification of parameter values takes 
+\item{} Allowed {\t parameter\_type}s are 
+  \begin{Lentry}
+     \item[{\t INTEGER}] The specification of {\t parameter\_value}s takes 
      the form of any number of comma-separated blocks of the form:
 {\t
 \begin{verbatim}
-[<low-range>][:[<high-range>][:[<step>]]][::``<range description>'']
+[<low-range>][:[<high-range>][:[<step>]]][::"<range description>"]
 \end{verbatim}
 }
 Where an empty field, or a {\t *} in the place of {\t low-range} or
 {\t high-range} indicates $-\infty$ and $\infty$ respectively. The 
 default value for {\t step} is 1. A number by itself denotes that
 this number is the only acceptable value.
-     \item{} {\t REAL} The range specification is the same as integers,
+     \item[{\t REAL}] The range specification is the same as integers,
              except that here, no {\t step} implies a continuum of values.
-     \item{} {\t KEYWORD} Each entry in the list of acceptable values 
+     \item[{\t KEYWORD}] Each entry in the list of acceptable values 
              for a keyword has the form 
 {\t
 \begin{verbatim}
 "<keyword value>", "<keyword value>" :: "<description>"
 \end{verbatim}
 }
-     \item{} {\t STRING}  Allowed values for strings should be specified using regular expressions. To allow any string, the regular expression ".*" should be used.
-     \item{} {\t BOOLEAN} No allowed values should be specified for a boolean
+     \item[{\t STRING}]  Allowed values for strings should be specified using regular expressions. To allow any string, the regular expression ".*" should be used.
+     \item[{\t BOOLEAN}] No {\t PARAMETER\_VALUES} should be specified for a boolean
              parameter. The default value for a boolean can be 
         \begin{itemize}
            \item{} True: {\t 1}, {\t yes}, {\t y}, {\t t}, {\t true}
            \item{} False: {\t 0}, {\t no}, {\t n}, {\t f}, {\t false}
         \end{itemize}
-  \end{itemize}
+  \end{Lentry}
 
 \item{} The {\t parameter name} must be unique within the scope of the thorn.
 
@@ -256,7 +275,7 @@ schedule <function name> at <time>
   [STORAGE: <group>,<group>]
   [COMMUNICATION: <group>,<group>]
   [TRIGGER: <grid function>,<grid function>]
-} ``Description of function''
+} "Description of function"
 \end{verbatim}
 }
 
@@ -277,10 +296,48 @@ if (CCTK_Equals(<parameter>,<string>))
 Conditional constructs cannot be used inside of a schedule block.
 
 
-\chapter{CCTK Parameters}
+\chapter{Flesh parameters}
 \label{sec:ccpa}
 
-\chapter{Using GNATS}
+The flesh parameters are defined in the file {\tt src/par/param.ccl}.
+
+\section{Private parameters}
+
+\begin{Lentry} 
+
+\item[{\tt cctk\_full\_warnings}] 
+Give detailed information for each warning statement [{\tt yes}]
+
+\item[{\tt cctk\_strong\_param\_check}] 
+Die on parameter errors in {\tt CCTK\_PARAMCHECK} [{\tt yes}]
+
+\item [{\tt cctk\_show\_schedule}] 
+Print the scheduling tree to standard output [{\tt yes}]
+
+\item [{\tt cctk\_show\_banners}]
+Show any registered banners for the different thorns [{\tt yes}]
+ 
+\item [{\tt cctk\_brief\_output}]
+Give only brief output [{\tt no}]
+
+\end{Lentry}
+
+\section{Restricted parameters}
+
+\begin{Lentry}
+
+\item[{\tt cctk\_initial\_time}] 
+Initial time for evolution [{\tt 0.0}]
+ 
+\item [{\tt cctk\_final\_time}] Final time for evolution, overriden by
+{\tt cctk\_itlast} unless it is positive [{\tt -1.0}] 
+
+\item [{\tt cctk\_itlast}]
+Final iteration number [{\tt 10}]
+
+\end{Lentry}
+
+\chapter{Using {\tt GNATS}}
 GNATS is a freely redistributable set of tools for tracking bug
 reports. It allows users to categorize their problem report and submit 
 them to the GNATS. The bugtracker will assign appropriate maintainers
@@ -308,18 +365,20 @@ problem you are dealing with.
 
 \item[{\bf submitter ID}] Unused
 
-\item[{\bf Originator}] Your name
+\item[{\bf Originator}] Your name. Anonymous is OK, but you real name 
+   would be best.
 
-\item[{\bf Release}] The Cactus release your are using.
+\item[{\bf Release}] The Cactus release you are using. You can find this
+   out, for example, from an executable by typing {\tt cactus\_<config> -v}.
 
-\item[{\bf Environment}] Very important: specify the environment:
-e.g. {\tt uname -a}, MPI/non-MPI, etc.
+\item[{\bf Environment}] Very important: specify the environment,
+e.g. {\tt uname -a}, {\tt MPI}/non-{\tt MPI}, etc.
 
 \item[{\bf Description}] Describe your problem precisely, if you get a 
 core dump, include the stack trace, give the minimal number of thorns, 
 this problems occurs with.
 
-\item[{\bf How-To-Repeat}] Tell us how to repeat the problem, if it is
+\item[{\bf How-To-Repeat}] Tell us how to repeat the problem if it is
 software related.
 
 \item[{\bf Fix}] If you can provide a fix, let us know.
@@ -332,21 +391,22 @@ reports in your shell and from within emacs, respectively.
 
 \label{sec:usgn}
 
-\chapter{Using CVS}
+\chapter{Using {\tt CVS}}
 \label{sec:uscv}
-CVS is a version control system, which allows you to  keep
-old versions of files (usually source code), keep a log of
-who, when, and why changes occurred,  etc.
-Unlike the simpler systems, CVS does not just operate on one file at a
+{\tt CVS} is a version control system, which allows you to  keep
+old versions of files (usually source code), log of
+when, and why changes occurred, and who made them,  etc.
+Unlike the simpler systems, {\tt CVS} does not just operate on one file at a
 time or one directory at a time,  but 
 operates  on  hierarchical collections of directories consisting of
-version controlled files.  CVS helps to  manage 
+version controlled files.  {\tt CVS} helps to  manage 
 releases  and  to control the concurrent editing of source
-files among multiple  authors. CVS can be obtained from 
+files among multiple  authors. {\tt CVS} can be obtained from 
 {\tt http://www.cyclic.com}. 
 
-A {\em CVS repository}located on a {\em server} may consist of an arbitrary
-number of {\em modules}, which can be checked out independently. The Cactus
+A {\em CVS repository} located on a {\em server} may consist of an arbitrary
+number of {\em modules}, which can be checked out (thst is downloaded) 
+independently. The Cactus flesh and the Cactus
 arrangements are organized as modules, their {\em CVS server} is {\tt cvs.cactuscode.org}.
 
 \subsection{Essential CVS commands}
@@ -358,9 +418,9 @@ password}. This cvs command leaves a file {\tt .cvs-pass} in your
 home directory. There is no need to login every time you issue a cvs 
 command, as long as this file exists. For a Cactus checkout, you have
 to log into the CVS server, using the cvs option {\bf -d} to specify CVSROOT:\\
-{\tt cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/usr/users/cactus login}
+{\tt cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus login}
 
-Note, that there is no ``logout'' command: if you log in with
+{\tt Note}: that there is no "logout" command: if you log in with
 administrative rights from an arbitrary account, you should be aware
 that the password file enables subsequent administrative logins from
 that account. {\em Delete the file if necessary}.
@@ -371,8 +431,9 @@ your private copy of the source for {\em modules}. You can work
 with this copy  without  interfering  with  others'
 work.   At  least  one subdirectory level is always created: it does
 not write all files into your current directory but creates a
-directory. For Cactus, you need to include the {\bf -d} options to
-specify the CVSROOT directory and the CVS server (see below). Once you 
+directory. For Cactus, you need to either include the {\bf -d} options to
+specify the CVSROOT directory and the CVS server, or specify them
+with an environment variable (see below). Once you 
 have checked out the repository there is no need to include the {\bf
 -d} option and its rather lengthy argument: the necessary information
 is contained in the local {\tt CVS/} directories.
@@ -383,8 +444,8 @@ source  directory  when  you  wish  to  update your
 copies of source  files  from  changes  that  other
 developers have made to the source in the repository.
 Merges are performed automatically when possible, a warning is issued
-if manual  resolution  is  required  for conflicting  changes. If you
-local copy is several version behind the actual repository copy, CVS
+if manual  resolution  is  required  for conflicting  changes. If your
+local copy is several versions behind the actual repository copy, CVS
 will {\em refetch} the whole file instead of applying multiple
 patches.
 
@@ -401,41 +462,60 @@ checkouts and updates by other users. You cannot commit a
 newly created file unless you have {\it added} it.
 
 \item[{\bf cvs diff} {\tt file}]
-Show differences between files in working directory
-and  source repository, or between two revisions in
+Show differences between a file in your working directory
+and  a file in the source repository, or between two revisions in
 source repository.  (Does not change either repository or working
-directory.) 
+directory.) For example, to see the difference between versions
+{\tt 1.8} and {\tt 1.9} of a file {\tt foobar.c}:
+
+{\tt 
+\begin{verbatim}
+cvs diff -r 1.8 1.9 foobar.c
+\end{verbatim}
+}
 
 \item[{\bf cvs remove} {\tt file}]
 Remove files from the source repository, pending  a {\tt cvs commit} on
 the same files.  
 
-\item[{\bf cvs status}] 
+\item[{\bf cvs status} [file]] 
 This command returns the current status of your local copy relative to 
 the repository: e.g. it indicates local modifications and possible
 updates.
 
 \item[{\bf cvs import} {\tt repository tag1 tag2}]
-Import adds an entire source distribution to the repository directory.
+Import adds an entire source distribution (starting from the
+directory you issue the command in) to the repository directory.
 Use this command to add new arrangements to the Cactus4.0 repository. The
-{\tt repository} argument gives a directory name (or a path to a
+{\tt repository} argument is a directory name (or a path to a
 directory) and the CVS root directory for repositories; to obtain this 
 directory on the CVS server, send a request to {\tt
 cactus@cactuscode.org}. {\tt tag1} and {\tt tag2} are two tags (vendor 
- and release tags) that have to be supplied.
+ and release tags) that have to be supplied. For example, to add {\tt MyThorn}
+to the {\tt MyArrangement} arrangement, which may or maynot already exist on
+the CVS repository
+
+{\tt
+\begin{verbatim}
+cvs -d :pserver:<name>@cvs.cactuscode.org:/cactus import MyArrangement/MyThorn start v1
+\end{verbatim}
+}
+
+After you import a thorn, you should check it out from the repository straight
+away, and only edit this version.
 
 \end{Lentry}
 
 \subsection{CVS Options}
 The CVS command line can include the following:
-\begin{itemize}
-\item{\bf cvs options}, which apply to the overall cvs program
-\item{\bf a cvs command}, which defines a particular task carried out by
+\begin{Lentry}
+\item[{\bf cvs options}] which apply to the overall cvs program
+\item[{\bf a cvs command}]  which defines a particular task carried out by
 cvs
-\item{\bf command options} to specify certain working modes for the cvs
+\item[{\bf command options}] to specify certain working modes for the cvs
 command.
-\item{\bf command arguments} to specify which file to act on.
-\end{itemize}
+\item[{\bf command arguments}] to specify which file to act on.
+\end{Lentry}
 
 The options must be put {\em relative} to the {\it cvs command} as the
 same option name can mean different things: {\em cvs options} go to the
@@ -449,8 +529,8 @@ Use {\em cvs\_root\_directory} as the root directory  pathname  of
 the  master source repository.  Overrides 
 the setting of the  {\em CVSROOT}  environment  variable.
 This value should be specified as an absolute pathname. 
-In the Cactus4.0 checkout procedure, you specify the Cactus CVS server:\\
-{\tt -d :pserver:cvs\_anon@cvs.cactuscode.org:/usr/users/cactus/}
+In the Cactus checkout procedure, you specify the Cactus CVS server:\\
+{\tt -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus/}
 
 \item[{\bf -z} {\em compression-level}]
 When transferring files across the network use {\tt gzip}
@@ -506,13 +586,13 @@ We list some sample CVS commands to treat the most typical Cactus4.0
 CVS situations. 
 \begin{description}
 \item\textbf{Logging into the server}\newline
-{\tt cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/usr/users/cactus
+{\tt cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus
 login} \\ You will be asked for the password for user {\em cvs\_anon}, which is {\tt anon}.
 
 \item\textbf{Checking out the code}\newline
 {\tt cvs -d :pserver:cvs\_anon@cvs.cactuscode.org:/cactus
 checkout Cactus}\\
-check out a CVS module named ``Cactus'', in this case it checks out the
+check out a CVS module named "Cactus", in this case it checks out the
 Cactus Computational Toolkit. A directory {\tt ./Cactus} is created if  
 it doesn't already exits. If you perform a checkout on an already
 existing and locally modified copy of the module, CVS will try to merge the files
@@ -526,7 +606,7 @@ to inform yourself about the necessary updates, etc. To update the
 file issue \\
 {\tt cvs update ./foobar}\\
 If that was file was locally modified, CVS will try to merge the
-changes.Manual merging might be necessary and will be indicated by a
+changes. Manual merging might be necessary and will be indicated by a
 CVS warning.
 
 \item\textbf{Updating a directory}\newline
@@ -541,14 +621,14 @@ To commit changes you have applied to your local copy, your file must be in
 sync with the repository: your changes must be done to the
 latest version, otherwise CVS will instruct you to perform an {\bf
 update} first. To commit changes made to a file {\tt ./foobar}, type\\
-{\tt cvs commit -m ``Reason for the change'' ./foobar}\\
+{\tt cvs commit -m "Reason for the change" ./foobar}\\
 You may specify several files to commit.
 
 \item\textbf{Adding and committing a new file}\newline
 Adding a new file to the repository is a two fold procedure you first
 schedule the file for addition, then you commit it:\\
 {\tt cvs add ./newfoo}\\
-{\tt cvs commit -m ``new few message'' ./newfoo}
+{\tt cvs commit -m "new few message" ./newfoo}
 
 \item\textbf{Creating a new thorn}\newline
 To add a new module to the Cactus repository, (e.g. an additional Cactus
@@ -559,7 +639,7 @@ CVS steps apply as well to adding to a locally hosted CVS repository (except
 that the CVSROOT option has to be changed to your local host).
 To perform the addition, type\\
 {\tt cvs -d :pserver:}{\em your\_login}{\tt
-@cvs.cactuscode.org:/usr/users/cactus }{\em arrangement\_name} {\tt start V1}\\
+@cvs.cactuscode.org:/cactus }{\em arrangement\_name} {\tt start V1}\\
 where {\tt start} and {\tt V1} are the vendor and release tags, which
 have to be supplied. 
 \end{description}
@@ -583,7 +663,7 @@ emacs if you add either of the following lines to your {\tt .emacs} file:\\
 where {\tt CACTUS\_HOME } is your Cactus directory.\\
 
 You can now easily navigate your Cactus Flesh and Toolkits by searching for
-functions or ``tags'':
+functions or "tags":
 \begin{enumerate}
 \item \textbf{ Alt.} will find a tag
 \item \textbf{ Alt,} will find the next matching tag
diff --git a/doc/UsersGuide/Infrastructure.tex b/doc/UsersGuide/Infrastructure.tex
index 5ef50aa8..44bc0aa6 100644
--- a/doc/UsersGuide/Infrastructure.tex
+++ b/doc/UsersGuide/Infrastructure.tex
@@ -2,7 +2,6 @@
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 
 \chapter{Introduction} 
-\label{sec:in}
 
 \begin{itemize}
  \item{} Concepts and terminology (Overloading and registration of functions)
diff --git a/doc/UsersGuide/Preface.tex b/doc/UsersGuide/Preface.tex
index 8801e2f6..8652eada 100644
--- a/doc/UsersGuide/Preface.tex
+++ b/doc/UsersGuide/Preface.tex
@@ -71,6 +71,15 @@ arrangements and thorns making up the standard Cactus Computation Tool Kit
 
 {\bf Typographical Conventions}
 
+\begin{Lentry}
+
+\item[{\tt Typewriter}] Is currently used for everything you type,
+	for program names, and code extracts.
+\item[{\tt < ... >}] Indicates a compulsory argument.
+\item[{\tt [ ... ]}] Indicates an optional argument.
+
+\end{Lentry}
+ 
 \vskip .5cm
 
 {\bf How to Contact Us}
@@ -100,6 +109,6 @@ Germany
 Hearty thanks to all those who have helped with documentation for the
 Cactus Code. Special thanks to those who struggled with the earliest
 sparce versions of this guide and sent in mistakes and suggestions,
-in particular John Baker, Ginny Hudak-David, Sai Iyer, Paul Lamping,
-Nancy Tran and Ed Seidel. 
+in particular John Baker, Carsten Gundlach, Ginny Hudak-David, 
+Sai Iyer, Paul Lamping, Nancy Tran and Ed Seidel. 
 
diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex
index e9f13140..dfe5074b 100644
--- a/doc/UsersGuide/RunningCactus.tex
+++ b/doc/UsersGuide/RunningCactus.tex
@@ -7,7 +7,7 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \chapter{Installation} 
-\label{sec:in}
+\label{cha:in}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -636,7 +636,7 @@ targets and options which are detailed in the following sections.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{gmake targets for building and adminstering configurations}
-\label{sec:gmta}
+\label{sec:gmtafobuanadco}
 
 A target for {\tt gmake} can be naively thought of as an argument
 that tells it which of several things listed in the {\tt Makefile} it
@@ -672,7 +672,7 @@ is to do. The command {\tt gmake help} lists all gmake targets.
 \item [{\tt gmake <config>-thornlist}] regenerates the ThornList for a configuration.
 
 \item [{\tt gmake <config>-testsuite}] runs the test programs associated with
- each thorn. See section \ref{sec:????} for information about the 
+ each thorn. See section \ref{sec:te} for information about the 
  test suite mechanism.
 
 \item [{\tt gmake <config>-thornparfiles}] copies all the example parameter files relevant for this configuration to the directory {\tt thornparfiles} in the Cactus home directory. If a file of the same name is already there, it will not overwrite it.
@@ -718,7 +718,7 @@ Instead of using the editor to specify the thorns you want to
 \end{itemize}
 
 \subsection{gmake options for building configurations}
-\label{sec:gmta}
+\label{sec:gmopfobuco}
 
 An {\it option} for gmake can be thought of as an argument which tells
 it how it should make a {\tt target}. Note that the final result is always
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index 157c06f1..acfd5962 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -15,12 +15,12 @@
 Thorns are grouped into {\em arrangements}.  This is a logical grouping of
 thorns which is purely for organisational purposes. For example, 
 you might wish to keep all your initial data thorns in one arrangement,
-and all your evolution thorns in another arrangement, or to have
-separate arrangements for your development, private and shared 
+and all your evolution thorns in another arrangement, or you may want 
+to have separate arrangements for your developmentsl, private and shared 
 thorns. 
 
 The arrangements live in the {\tt arrangements} directory off the main 
-Cactus directory.  Arrangement names must be unique, and cannot start 
+Cactus directory.  Arrangement names must be unique, and cannot sta 
 with a `\#', or finish
 with `\~{}' or `.bak'.
 
@@ -74,29 +74,30 @@ administrative files
 \begin{Lentry}
 \item[{\tt interface.ccl}] the cactus interface, which defines the grid 
 functions, variables, etc. See \ref{sec:in}.
-\item[{\tt param.ccl}] the parameters introduced by the thorn. See
-\ref{sec:thpa}.
+\item[{\tt param.ccl}] the parameters introduced by this thorn, and the
+parameters needed from other thorns. See
+\ref{sec:pa}.
 \item[{\tt schedule.ccl}] scheduling information for routines called by
-the flesh. See \ref{sec:thsc}
+the flesh. See \ref{sec:sc}
 \end{Lentry}
 
 Thorns can also contain  
 \begin{itemize}
 \item a subdirectory called {\tt src}, which should hold source files
+	and compilation instructions for the thorn
 \item a subdirectory {\tt src/include} for include files 
 \item a {\tt README} containing a brief description of the thorn
 \item a {\tt doc} directory for documentation
 \item a {\tt par} directory for example parameter files
-\item a {\tt test} subdirectory may also be added.  See \ref{sec:testsuites} for details.
+\item a {\tt test} subdirectory may also be added, to hold the thorn's
+    testsuite. See \ref{sec:adatesu} for details.
 \end{itemize}
 
 \section{Creating a thorn}
 
 
 To simplify the creation of a thorn, a make target {\tt
-gmake newthorn} has been provided.
-
-When this is run:
+gmake newthorn} has been provided. When this is run:
 
 \begin{enumerate} 
 \item{} You will be prompted for the name of the new thorn.
@@ -126,7 +127,7 @@ with their visibility to other implementations.
 
 \item [{\tt schedule.ccl}]
 This defines which functions from the thorn are called and when they are 
-called.
+called. It also handles memory and communication assigment for grid variables.
 
 \end{Lentry}
 
@@ -135,13 +136,12 @@ called.
 CCL {\bf Cactus Configuration Language} files are simple text files
 used to define configuration information for a thorn.  CCL files are
 case independent, and may contain comments introduced by the `\#' character,
-which marks the rest of the line to the right of its appearance as a comment.
+which indicates that the rest of the line is a comment.
 
 \subsection{The {\tt interface.ccl}}
 
 The {\tt interface.ccl} file is used to declare the implementation 
 provided by the thorn, and to define the variables provided by it.
-
 The implementation is declared by a single line at the top of the file
 
 \begin{verbatim}
@@ -149,35 +149,34 @@ implements: <name>
 \end{verbatim}
 
 Where {\tt <name>} can be any combination of alphanumeric 
-characters and underscores, and is case independent (as is everything in a CCL file).
-
+characters and underscores, and is case independent.
 There are three different access levels available for variables
 
-\begin{itemize}
-\item {\tt Public}
+\begin{Lentry}
+\item[{\tt Public}]
 Can be `inherited' by other implementations (see below).
-\item {\tt Protected}
+\item[{\tt Protected}]
 Can be shared with other implementations which declare themselves to
 be friends of this one (see below).
-\item {\tt Private}
+\item[{\tt Private}]
 Can only be seen by this thorn.
-\end{itemize}
+\end{Lentry}
 
 Corresponding to the first two access levels there are two relationship
 statements that can be used to get variables from other thorns.
 
-\begin{itemize}
-\item {\tt Inherits: <name>}
-This gets all {\tt Public} variables from implementation {\tt <name>}, plus all
-variables it has in turn inherited.  An implementation may inherit from as
-many thorns as it likes.
-\item {\tt Friend: <name>}
+\begin{Lentry}
+\item [{\tt Inherits: <name>}]
+This gets all {\tt Public} variables from implementation {\tt <name>}, and all
+variables that {\tt <name>} has in turn inherited.  
+An implementation may inherit from any number of thorns.
+\item [{\tt Friend: <name>}]
 This gets all {\tt Protected} variables from implementation {\tt <name>}, but, 
-unlike {\tt inherits} it pushes this implementations {\tt Protected}
+unlike {\tt inherits} it also pushes its own implementations {\tt Protected}
 variables onto implementation {\tt <name>}.  This keyword is used to define
 a group of implementations which all end up with the same {\tt Protected}
 variables.
-\end{itemize}
+\end{Lentry}
 
 So, for example, an interface.ccl starting
 
@@ -188,37 +187,41 @@ friend:     wave_extract
 \end{verbatim}
 
 declares that the thorn provides an implementation called `wavetoy', gets
-all {\tt public} variables declared by an implementation called `grid', and
-shares all {\tt protected} variables with `wave\_extract' and its friends.
+all the {\tt public} variables declared by an implementation called `grid', and
+shares all {\tt protected} variables with {\tt wave\_extract} and its friends.
 
-For convenience variables are placed in groups.  Currently, names of groups
+For convenience variables are placed in groups of homogeneous variables.  
+Currently, names of groups
 and variables must be distinct. The group has several
 attributes:
 
-\begin{itemize}
+\begin{Lentry}
 
-\item {\tt variable type}
+\item [{\tt variable type}]
 e.g. REAL, INT, COMPLEX
 
-\item {\tt name}
+\item [{\tt name}]
 The name of the group
 
-\item {\tt group type}
-\begin{itemize}
-\item {\tt SCALAR}
+\item [{\tt group type}]
+This indicates the kind of variables help by the group (each group can
+only hold one kind of variable).
+\begin{Lentry}
+\item [{\tt SCALAR}]
 This is a single number.
-\item {\tt GF}
-This is an array of the default grid size.
-\item {\tt ARRAY}
+\item [{\tt GF}]
+This is an array with the default grid size (a {\it grid function}).
+\item [{\tt ARRAY}]
 This is an array of any size.
-\end{itemize}
+\end{Lentry}
 
-\item {\tt Dim}
-This is the dimension of the group.  (Meaningless for scalars.)
+\item [{\tt Dim}]
+This is the dimension of the arrays in a group.  (Meaningless for scalars.)
+This defaults to 3
 
-\item {TimeLevels}
-This is the number of timelevels the group has.
-\end{itemize}
+\item [{TimeLevels}]
+This is the number of timelevels the group has. This defaults to 1.
+\end{Lentry}
 
 A group specification consists of the variable type, followed by
 the name of the group, then a space separated list of the form
@@ -239,7 +242,7 @@ REAL fields type=GF TimeLevels=3 Dim=3
 
 \end{verbatim}
 
-defines a group of real GFs of dimension 3 each of which exists on
+defines a group of real grid functions of dimension 3 each of which exists on
 three time levels.
 
 By default all groups are {\tt private}, to change this an access
@@ -251,11 +254,13 @@ All variables seen by any one thorn must have distinct names.
 
 \subsection{The {\tt param.ccl}}
 
-Users control the operation of thorns via parameters.  The {\tt param.ccl}
+Users control the operation of thorns via parameters given in a file
+at runtime.  The {\tt param.ccl}
 is used to specify the parameters used to control an individual thorn, and
 to specify the values these parameters are allowed to take.  When the code
 is run it reads a parameter file and sets the parameters if they fall
-within the allowed values.
+within the allowed values. If a parameter is not assigned in a parameter
+file, it is given its default value.
 
 There are three access levels available for parameters:
 
@@ -271,7 +276,7 @@ These are only seen by this thorn.
 A parameter specification consists of:
 \begin{itemize}
 
-\item the parameter type
+\item the parameter type (each may have an optional {\t CCTL\_} in front)
 \begin{Lentry}
 \item [{\tt REAL}]
 \item [{\tt INT}]
@@ -284,7 +289,7 @@ A boolean type which can take values 1, `t', `true', `yes' or
 0, `f', `false', `no'.
 \end{Lentry}
 
-\item a description of the parameter
+\item a {\tt description} of the parameter
 
 \item an allowed value block
 This consists of a brace delimited block of lines
@@ -297,7 +302,8 @@ This must be one of the allowed values.
 
 \end{itemize}
 
-For the numeric types INT and REAL, a range consists of a string of the
+For the numeric types {\tt INT} and {\tt REAL}, a range consists 
+of a string of the
 forms lower-bound:upper-bound:step where a missing number or a \* denotes
 anything (i.e. infinite bounds or an infinitesimal step).
 
@@ -335,13 +341,13 @@ changes the access level for any parameter defined in the file from that point o
 To access {\tt restricted} parameters from another implementation, a line
 containing {\tt shares: <name>} declares that all parameters mentioned in
 the file from now until the next access specification originate in 
-implementation <name>.  
+implementation {\tt <name>}.  
 
 In contrast to parameter declarations in other access blocks, the default
 value must be omitted - it is impossible to set the default value of any
 parameter not originating in this thorn.
-
-For example
+For example, the following block adds possible values to the keyword
+{\tt initial\_data} originally defined in the implementation {\tt einstein}.
 
 \begin{verbatim}
 
@@ -356,12 +362,14 @@ KEYWORD initial_data ""
 
 \end{verbatim}
 
+Note that you must compile at least one thorn which implements {\tt einstein}.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \subsection{The {\tt schedule.ccl}}
 
-By default no routine of a thorn will be run.  The schedule.ccl file
+By default no routine of a thorn will be run.  The {\tt schedule.ccl} file
 defines those that should be run and when they should be run.
 
 The specification of this is via a schedule block which consists of
@@ -379,6 +387,7 @@ schedule <name> at <time bin> [other options]
 \end{verbatim}
 
 where {\tt <name>} is the name of the routine, and {\tt <time bin>} is one of
+(in the following the initial {\tt CCTK\_} is optional):
 
 \begin{Lentry}
 
@@ -435,8 +444,9 @@ Convergence stuff.
 These time bins can be given in the {\tt schedule.ccl} file with
 or without the initial {\tt CCTK\_}, and in any case.
 
-The {\tt STORAGE} and {\tt COMM} keywords specify any groups which must have memory 
-allocated for them or communication enabled for the duration of that routine.
+The {\tt STORAGE} and {\tt COMM} keywords specify any groups for 
+which  memory should be
+allocated or communication enabled for the duration of the routine.
 The storage or communication status reverts to its previous status after the 
 routine returns.
 
@@ -486,8 +496,7 @@ a thorn could explicitly switch the storage off.
 \label{nacofosofi}
 
 The make system uses file extensions
-to designate coding language. The following extensions are
-can be handled:
+to designate coding language. The following extensions can be handled:
 
 \begin{center}
 \begin{tabular}{|c|c|}
@@ -508,9 +517,8 @@ Extension & Coding Language \\
 
 The following restrictions apply to file names:
 \begin{itemize}
-\item Root names within each directory must be unique. For example, it is not possible 
-      to have the files {\tt InitialData.c} and {\tt InitialData.F} in the same directory.
-\item Currently all files within a thorn must have distinct names.  We hope
+\item Currently all source files in different subroutines within a 
+thorn must have distinct names.  We hope
 to relax this in future.  Different thorns can have files with the same names. 
 \end{itemize}
 
@@ -526,16 +534,14 @@ yourself.
 
 \subsection{{\tt make.code.defn} based thorn building}
 
-This is the standard way to do it.
-
-If there is no file called {\tt Makefile} in the {\tt src} directory,
-the CCTK make system looks for a file called {\tt make.code.defn} in that
-directory.  At its simplest, this file contains two lines
+This is the standard way to do compile your thorn's source files.
+The Cactus make system looks for a file called {\tt make.code.defn} in that
+directory (if there is no file called {\tt Makefile} in the {\tt src} directory).  At its simplest, this file contains two lines
 
 \begin{itemize}
-\item {\t SRCS = <list of all source files {\em in this directory}>}
+\item {\t SRCS = <list of all source files in this directory>}
 
-\item {\t SUBDIRS = <list of all subdirectories, {\em including subdirectories of subdirectories}>}
+\item {\t SUBDIRS = <list of all subdirectories, including subdirectories of subdirectories>}
 
 \end{itemize}
 
@@ -545,21 +551,22 @@ be ignored.
 
 In addition, each directory can have a {\tt make.code.deps} file, which,
 for files in that directory, can contain additional make rules and dependencies
-for files in that directory.  See the GNU Make documentation for details of the
+for files in that directory.  See the GNU Make documentation for complete details of the
 syntax.
 
 \subsection{{\tt Makefile} based thorn building}
 
-This method gives you ultimate responsibility.  The only requirement is that
-a library called {\tt \$NAME} be created by the Makefile.
+This method gives you the ultimate responsibility.  
+The only requirement is that
+a library called {\tt \$NAME} be created by the {\tt Makefile}.
 
 The makefile is passed the following variables
 
 \begin{Lentry}
 
-\item [{\tt \$(CCTK\_HOME)}]  the main CCTK directory
+\item [{\tt \$(CCTK\_HOME)}]  the main Cactus directory
 
-\item [{\tt \$(TOP)}] the CONF directory
+\item [{\tt \$(TOP)}] the configuration directory
 
 \item [{\tt \$(SRCDIR)}] the directory in which the source files can be found
 
@@ -595,16 +602,21 @@ and has a working directory of {\tt <config>/build/<thorn\_name>} .
 
 \section{What the Flesh provides}
 
-The flesh provides various things to thorns.
+The flesh provides for thorns.
+\begin{Lentry}
+\item [{\tt Variables}]
+\item [{\tt Parameters}]
+\item [{\tt Cactus Functions}]
+
 \begin{itemize}
-\item {\tt Variables}
-\item {\tt Parameters}
-\item {\tt Driver functions}
-\item {\tt IO functions}
-\item {\tt Information functions}
-\item {\tt Reduction}
-\item {\tt Interpolation}
+  \item{} driver (parallelisation) utilities
+  \item{} IO utilities
+  \item{} Coordinates utilities
+  \item{} Reduction utilities
+  \item{} Interpolation utilities
+  \item{} Information utilities
 \end{itemize}
+\end{Lentry}
 
 
 \subsection{Fortran Routines}
@@ -911,7 +923,7 @@ is declared in the {\tt interface.ccl} as {\tt CCTK\_REAL}.
 
 Declaring {\tt local\_var} to have a non-Cactus data type, e.g.
 {\tt REAL*4}, or using one of the other Cactus real data types
-described in Section~\ref{datyansi} could give problems for 
+described in Section~\ref{sec:datyansi} could give problems for 
 different architectures or configurations.