The pitiful amount of documentation I did over the weekend

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

3 files changed, 103 insertions, 60 deletions

diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex
index 095aceee..8de69c5c 100644
--- a/doc/UsersGuide/Appendices.tex
+++ b/doc/UsersGuide/Appendices.tex
@@ -3,8 +3,10 @@
 \appendix
 
 \chapter{Configuration file syntax}
-    
+\label{sec:cofisy}    
+
 \section{General Concepts}
+\label{sec:geco}
 
 Each thorn is configured by three compulsory files in the top level thorn
 directory:
@@ -17,6 +19,7 @@ These files are written in the {\it Cactus Configuration Language} which is
 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 
@@ -89,6 +92,7 @@ The default value is {\t DIM=3}.
 \end{itemize} 
 
 \section{param.ccl}
+\label{sec:pa}
 
 The parameter configuration file consists of a list of 
 {\it parameter object specification items} (OSIs) giving the type and
@@ -119,6 +123,7 @@ protection or scoping class. {\t access} can take the values:
 
 
 \subsection{Parameter Object Specification Items}
+\label{sec:paobspit}
 
 {\t
 \begin{verbatim}
@@ -171,6 +176,7 @@ this number is the only acceptable value.
 
 
 \section{schedule.ccl}
+\label{sec:sc}
 
 The schedule configuration files consists of 
 \begin{itemize}
@@ -224,19 +230,24 @@ Conditional constructs cannot be used inside of a schedule block.
 
 
 \chapter{CCTK Parameters}
-
+\label{sec:ccpa}
 
 \chapter{Using GNATS}
+\label{sec:usgn}
 
 \chapter{Using CVS}
+\label{sec:uscv}
 
 \chapter{Using TAGS}
+\label{sec:usta}
 Finding your way around in the Cactus structure can be pretty
 difficult to handle. To make life easier there is support for TAGS,
 which lets you browse the code easily from within Emacs/XEmacs or vi. 
 A TAGS database can be generated with by gmake:
 
- \section{TAGS with emacs}
+\section{TAGS with emacs}
+\label{sec:tawiem}
+
 {\tt gmake TAGS} will create a database for a routine reference
 table to be used within Emacs. This database can be accessed within
 emacs if you add either of the following lines to your {\tt .emacs} file:\\
@@ -274,10 +285,10 @@ The Key strokes to use when you want to browse in read-only mode are:
 \end{enumerate}
 
 \section{TAGS with vi}
-
+\label{sec:tawivi}
 
 \chapter{Thorn-Flesh Interface}
-
+\label{sec:thflin}
 
 
 
diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex
index bcaed4ab..64b37292 100644
--- a/doc/UsersGuide/RunningCactus.tex
+++ b/doc/UsersGuide/RunningCactus.tex
@@ -1,4 +1,4 @@
-\part{Introduction}
+\part{Installation and Running}
 
 \chapter{Overview of documentation}
 
@@ -42,7 +42,10 @@ Other topics will be discussed in separate documents:
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\chapter{A Cactus history}
+\chapter{About Cactus}
+
+\section{A Cactus history}
+\label{sec:acahi}
 
 To begin with a one-phrase summary: Cactus is a numerical
 infrastructure for solving partial differential equations (typically
@@ -107,7 +110,8 @@ intended not to change again. {\q Can we realistically say any more?}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\chapter{Cactus concepts} 
+\section{Cactus concepts} 
+\label{sec:caco}
 
 Cactus is designed to solve time evolution problems in three space
 dimensions by finite differencing on a Cartesian grid. This typically
@@ -171,54 +175,72 @@ user access to all earlier versions.)
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \chapter{Installation} 
+\label{sec:in}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Required software}
+\label{sec:reqo}
 
 In general, Cactus {\em requires} the following set of software to function
 in a single processor mode. Please refer to the architecture section
-\ref{sec:architecture} for architecture specific items.
+\ref{sec:suar} for architecture specific items.
 \begin{itemize}
-\item{\tt Perl5.0} Perl is used extensively during the CCTK
-  configuration phase. Perl is available for nearly all
+\item{\tt Perl4.0} Perl is used extensively during the CCTK
+  thorn configuration phase. Perl is available for nearly all
   operating systems known to man and can be obtained at
   http://www.perl.org
-\item{\tt gmake} The GNU make utility has to be installed. The make
-  process will not work with anything else the GNU.
+\item{\tt gmake} The make
+  process works with the GNU gmake utility. While other make utilities
+  may also work, this is not guaranteed.
   Gmake can be obtained from your favorite GNU site.
-\item{\tt C/C++} A C/C++ compiler. These can be the GNU compilers as
-  well, but don't have to.
+\item{\tt C/C++} A C and C++ compiler. For example, the GNU compilers. These
+ are available for all supported platforms {\bf (QUERY: Is this right:? Gab)}.
+ Platform specific compilers should also work.
 \item{\tt CVS} The {\em ``Concurrent Versioning System''} is not needed
   to run/compile the CCTK, but you are strongly encourage to install
   this software to take advantage of the update procedures. It can be
-  downloaded from your favorite GNU site.
+  downloaded from your favorite GNU site. {(FIXME: This may need to be
+  changed when we sort out the distribution policy)}
+\end{itemize}
+
+\noindent
+To use the CCTK, with the default driver (CactusBase/PUGH) on multiple
+processes you also need:
+\begin{itemize}
+\item{\tt MPI} PUGH uses the {\it Message Passing Interface (MPI)} to 
+provide inter-processor communication. {\it (QUERY: Version Number? Gab)} 
+Supercomputering sites often supply a native MPI implementation with
+which the CCTK is very likely to be compatible. Otherwise the {\tt MPICH}
+version of MPI is available for various architectures and operating
+systems at {\tt http://www-unix.mcs.anl.gov/mpi/}. 
 \end{itemize}
 
 \noindent
-The following software is {\em optional} and not needed to get the
-basic CCTK installation on track. Its listed in the order of importance.
+If you are using any thorns containing routines 
+written in {\tt FORTRAN} you also need
+\begin{itemize}
+\item{\tt F90/F77} For routines written in F77, either an F90 or an F77
+ compiler can be used. For routines written in F90 an F90 compiler is
+ required. There is a very limited set of free F90 compilers available
+ for the different architectures.
+\end{itemize}
+
+\noindent
+While not required for compiling or running the CCTK, for thorn development
+it is useful to install
 \begin{itemize}
-\item{\tt Fortran 90} CCTK requires a F90 compiler to run modules
-  written in F77 or F90. There is no
-  GNU F90 and just a very limited set of free F90 compilers for
-  various architectures.
-\item{\tt MPI} Currently the communication layer of the CCTK uses the
-  {\em Message Passing Interface (MPI)} provide inter process
-  communication. Supercomputers very often supply a native MPI
-  implementation at their site. CCTK is very likely to work with
-  them. For local area networks we suggest installing the {\tt MPICH}
-  version, which can be obtained for various architectures and
-  operating systems at {\tt http://www-unix.mcs.anl.gov/mpi/}.
 \item{\tt TAGS}: Tags enables you browse through the calling structure
   of a program by help of function call database. Navigating the CCTK and
   packages becomes very easy. Emacs and vi both support this database. See
-  \ref{sec:tags} how to install ``tags''.
+  \ref{sec:usta} for a short guide to ``tags''.
 \end{itemize}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Supported architectures}
+\label{suar}
+
 Cactus runs on many machines, under a large number of Unix operating
 systems. Here we list all the machines we have compiled and verified
 Cactus on, including some architecture specific notes. 
@@ -243,34 +265,31 @@ Cactus on, including some architecture specific notes.
   \end{itemize}
 \item{\bf Solaris } {\q What is the status on this ??}
 \end{itemize}
-If you did not find you architecture/operating system of
-choice, see section sec\ref{sec:how_to_port} on how to port to an
-unsupported architecture.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Checkout procedure}
+\label{sec:chpr}
 
-Cactus is distributed, added to, and updated through the free CVS
+The CCTK is distributed, extended, and maintained using the free CVS
 software. CVS ({\em ``Concurrent Versioning System''}) allows many
 people to work on a large software project together without getting
-into a tangle by keeping track of changes made by the different
-users. For the beginner, we summarize the basics in appendix
-\ref{sec:CVS}, please refer to this section for small description of
+into a tangle. For the beginner, we summarize the basics in appendix
+\ref{sec:uscv}, please refer to this section for a short description of
 the CVS syntax.
 
-The installation requires about {\q HOW MANY MEGS ? }. See section
-\ref{sec:downsize_CCTK} on how to downsize CCTK installation if space is tight.
-{\q gmake small ??}
+The space required for an installation depends on the packages and
+thorns used. The flesh on its own requires less than 1 MB.
 
 \begin{itemize}
-\item{\bf Login}: Prior to any CVS operation, you need to log into the central
+\item{\bf Login}: Prior to any CVS operation, you need to log into the CCTK
   repository. For an anonymous checkout, type:\\
   {\tt
     cvs -d :pserver:cvs\_anon@hod.aei-potsdam.mpg.de:/usr/users/cactus login
     }
   You will be prompted for a password which is {\tt anon}. 
-\item{\bf Checkout}: To obtain a fresh CCTK checkout, type
+\item{\bf Checkout}: To obtain a fresh copy of the CCTK, move to a directory
+  which does not contain a previously checked out version, and type
   {\t
     cvs -d :pserver:cvs\_anon@hod.aei-potsdam.mpg.de:/usr/users/cactus checkout CCTK
     }
@@ -278,28 +297,33 @@ The installation requires about {\q HOW MANY MEGS ? }. See section
     ./CCTK} and install the CCTK inside this directory.  From now on we
   will reference all directory names relative to {\tt ./CCTK}. 
 
+\noindent
   If you want to compile the CCTK with thorns, you now need to checkout separately 
-  the required thorn packages. These should be checked out in the
-  ./CCTK/packages directory. {\bf QUERY: Should we list packages here or refer 
-  to a web page or what? The two packages currently available are CactusBase and 
-  CactusEinstein}
+  the required packages. These must be checked out in the
+  ./CCTK/packages directory. For a list of available packages check the
+web pages at http://cactus.aei-potsdam.mpg.de . The default package which 
+contains various infrastructure thorns is {\tt CactusBase}, to obtain this
+{\t
+  cd packages
+  cvs checkout CactusBase
+}
   
 \item{\bf Update}: To update an existing CCTK checkout (to patch in
   possible changes, etc.), do the following {\em within} the {\tt ./CCTK} directory.
   {\t
-    cvs -d :pserver:cvs\_anon@hod.aei-potsdam.mpg.de:/usr/users/cactus update
+    cvs update
     }
-  The update process will operate downwards relative to you current position
+  The update process will operate downwards relative to your current position
   within the CCTK tree. To update only certain directories, change
   into these directories and issue the update command.
 \item{\bf CVS status}: to obtain a status report on the ``age'' of your
   CCTK or package routines (from your current directory position
   downward), type
   {\t
-    cvs -d :pserver:cvs\_anon@hod.aei-potsdam.mpg.de:/usr/users/cactus status
+    cvs status
     }
 \item{\bf non-anonymous CVS}: if you have an account at the central
-  repository and you would like to perform any of the operation above
+  repository and would like to perform any of the operation above
   {\em non-anonymously}, replace {\tt cvs\_anon} by your login name
   and provide the appropriate password during the CVS login
   process. Depending on your permissions, you may then make commits to the CCTK
@@ -307,12 +331,14 @@ The installation requires about {\q HOW MANY MEGS ? }. See section
 \item{\bf Commits}: you need to perform a personalized login and have
   proper permissions to commit code to the repository. 
 \end{itemize}
-For more CVS commands on how to add files, etc. please refer to appendix \ref{sec:CVS}.
+For more CVS commands on how to add files, etc. please refer to appendix 
+\ref{sec:uscv}.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Directory structure}
+\label{sec:dist}
 
 A fresh CCTK checkout creates a directory {\tt ./CCTK} with the
 following files substructure:
@@ -402,8 +428,9 @@ what is in libraries.}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Getting help}
+\label{sec:gehe}
 
-Cactus Maint and GNATS
+{\bf FIXME: This is for Gerd to fill in} GNATS
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -432,6 +459,7 @@ system.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \section{Compilation and configuartions of the CCTK and its Packages}
+\label{sec:coancoof}
 
 Building the code with GNU make is easy. Use gmake with the following syntax:
 {\t gmake [configuration options] <CONF>}
@@ -501,6 +529,7 @@ structure is
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{gmake targets}
+\label{sec:gmta}
 
 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
@@ -536,10 +565,10 @@ is to do.
 \item {\tt gmake help} lists all make options
 
 \item {\tt gmake tags} creates a {\tt vi} style tags file. See section
-  \ref{sec:TAGS} for using TAGS within Cactus.
+  \ref{sec:usta} for using TAGS within Cactus.
 
 \item {\tt gmake TAGS} creates an Emacs style TAGS file. See section
-  \ref{sec:TAGS} for using TAGS within Cactus.
+  \ref{sec:usta} for using TAGS within Cactus.
 
 \item {\tt gmake distclean} nukes your configs directory.
 
@@ -551,6 +580,7 @@ is to do.
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Compiling in thorns}
+\label{sec:cointh}
 
 {\q This is way to specific for the section ``Compile'' in my opinion.
 This shoudl go with the thorn writing.}
@@ -616,6 +646,7 @@ files should end up if they need to be seen by other thorns.
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Testing} 
+\label{sec:te}
 
 simple make and test suite
 
@@ -650,6 +681,7 @@ simple make and test suite
       h) Environment variables
 
 \section{Command Line Options}
+\label{sec:coliop}
 
 \begin{tabular}{ll}
 {\t -O, -describe-all-parameters} &List all parameters and their descriptions\\
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index 4856c90c..441d7f81 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -48,7 +48,7 @@ Cactus creates the following files in {\tt ./package/<package\_name>/<thorn\_nam
 \begin{itemize}
 \item{\tt README}: please fill out 
 \item{\tt interface.ccl}: the cactus interface, which defined the grid 
-fucntions, variables, etc. See \ref{inteface.ccl}.
+fucntions, variables, etc. See \ref{sec:in}.
 \item{\tt param.ccl}: the parameter introduced by your thorn. See
 \ref{param.ccl}.
 \item{\tt schedule.ccl}: schedules the routines provided by your thorn 
@@ -90,7 +90,7 @@ the parameter's default value ?
 \end{enumerate}
 The {\em cactus computational language} lets you specify these
 information in a straight forward manner. (For the actual syntax of the 
-{\tt param.ccl} see \ref{syntax_param.ccl}.)
+{\tt param.ccl} see \ref{sec:pa}.)
 The parameters you define can be grouped in four classes: {\tt
 private}, {\tt public},  {\tt protected} and {\tt friend}:{\em
 thorn\_name}.  We'll go over them one by one: 
@@ -221,7 +221,7 @@ just used at a certain instance, for example for analysis.}
 \end{enumerate}
 
 The {\tt interface.ccl} defines all these specific information. The
-syntax is described in appendix \ref{syntax_interface.ccl}, please see 
+syntax is described in appendix \ref{sec:in}, please see 
 there for all possible options. Here we will introduce the general
 idea behind the interface.ccl.
 
@@ -323,9 +323,9 @@ in the example above.
 \item{}All-time memory can turned on depending on parameter
 settings. This can be done in the same way, the parameters are acessed 
 within a C or Fortran code: by explicit use of the parameter variables 
-in the case of integer/real/logical (see \ref{sec:parameter_types}) or
+in the case of integer/real/logical (see \ref{????}) or
 by use of the {\tt CCTK\_Equals()} function (see
-\ref{sec:CCTK_Equals}). For example:
+\ref{????}). For example:
 \begin{verbatim}
 # reserve memory for the group ``shift'' if parameter 
 # shift NOT set to ``none'' 
@@ -412,7 +412,7 @@ between system keywords and user keywords  ? better yes}
 
 The scheduling together with the storage options in {\tt schedule.ccl}
 is described here in examples (please the ccl-syntax
-\ref{syntax_schedule.ccl} for all possible options).
+\ref{sec:sc} for all possible options).
 \begin{verbatim}
 
 schedule initial at CACTUS_INITIAL