* put Boundary/ prefix on latex labels so they'll be unique across thorns

  when producing thorn guides for an entire arrangement
* document the return value of
     Boundary_SelectVarforBC()
     Boundary_SelectVarforBCI()
     Boundary_SelectGroupforBC()
     Boundary_SelectGroupforBCI()
* break an excessively-long paragraph right after the description of
  that return value


git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/Boundary/trunk@286 6a38eb6e-646e-4a02-a296-d141613ad6c4

1 files changed, 41 insertions, 32 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 6cd40aa..e3539d5 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -121,12 +121,12 @@ functions%\footnote{See appendix \ref{apx:fn_aliasing} for some notes
 register routines which provide a particular physical boundary
 condition, and also to select variables or groups of variables to have
 boundary conditions applied to whenever the \texttt{ApplyBCs} schedule
-group is scheduled (see section \ref{schedule_groups}).  In addition,
+group is scheduled (see section \ref{Boundary/sec:schedule_groups}).  In addition,
 an aliased function is provided which returns a list of grid variables
-selected for a boundary condition (see appendix \ref{apx:symmetry}).
+selected for a boundary condition (see appendix \ref{Boundary/apx:symmetry}).
 
 \subsection{Boundary condition registration}
-\label{sec:bc_registration}
+\label{Boundary/sec:bc_registration}
 
 To register a routine to provide some physical boundary condition, use
 \begin{verbatim}
@@ -154,7 +154,7 @@ long argument name\= description\=\kill
 \texttt{num\_vars} \> number of entries passed in the following three arrays\\
 \texttt{var\_indices} \> array of \texttt{num\_vars} variable indices selected for this boundary condition\\
 \texttt{faces} \> array of \texttt{num\_vars} faces specifications
-(see section \ref{faces})\\
+(see section \ref{Boundary/sec:faces})\\
 \texttt{widths} \> array of \texttt{num\_vars} boundary widths (see below)\\
 \texttt{table\_handles} \> array of \texttt{num\_vars} table handles%, which hold extra arguments for each application of the boundary condition to a grid variable
 \end{tabbing}
@@ -169,7 +169,7 @@ clear how face information should be considered in the sorting, so it
 is not.)  A null pointer can be passed for \texttt{function\_pointer},
 in which case no routine is executed when
 \texttt{Boundary\_ApplyPhysicalBCs} is called (see section
-\ref{schedule_groups}).
+\ref{Boundary/sec:schedule_groups}).
 
 \subsection{Boundary condition selection}
 
@@ -218,14 +218,22 @@ long argument name\= description\=\kill
 \texttt{group\_index} \> index of group of grid variables
 \end{tabbing}
 
-The first two select a single grid variable for a boundary condition,
-using either the variable name or index respectively.  The second two
-select an entire variable group, using either its name or index.  Each
-takes a faces specification, a boundary width, and a table handle as additional arguments.
+Each of these functions returns 0 for success, or a negative error
+code if something went wrong.
+
+\verb|Boundary_SelectVarForBC()| and \verb|Boundary_SelectVarForBCI()|
+select a single grid variable for a boundary condition,
+using either the variable name or index respectively.
+\verb|Boundary_SelectGroupForBC()| and \verb|Boundary_SelectGroupForBCI()|
+select an entire variable group, using either its name or index.
+
+Each of these functions takes a faces specification, a boundary width,
+and a table handle as additional arguments.
 The faces specification is a single integer which identifies a set of
 faces to which to apply the boundary condition.  See section
-\ref{faces} for details.  The boundary width is the thickness, in grid
-points, of the boundaries.  
+\ref{Boundary/sec:faces} for details.  The boundary width is the thickness,
+in grid points, of the boundaries.  
+
 The table handle identifies a table which
 holds extra arguments for the particular boundary condition that is
 requested.  
@@ -235,28 +243,29 @@ array, which holds the width of each face of the boundary (for a $d$
 dimensional grid variable).  (The first element of the array holds the
 width of the `-x' face, the second the `+x' face, the third the `-y'
 face, etc.)
-In some cases the table handle is required, so the
-boundary condition, when it is called within the
-\texttt{BoundaryConditions} schedule group (see section
-\ref{schedule_groups}), will return an error code.  However, in most
-cases it is optional.  If one uses an invalid table handle here (such
-as -1), commonly used default values will be assumed for all arguments
-(besides the explicit faces specification and boundary widths).  Note that you, the user,
-will be creating the table, so you may choose whatever options (such
-as case sensitivity) you like.  The case of the keys for which the
-boundary conditions implemented in this thorn search are as given in the
-documentation, which is currently all capitals.  To be safe you may
-choose to create case-insensitive tables, however cases sensitive
-tables are slightly faster.
+
+In some cases the table handle is required, so the boundary condition,
+when it is called within the \texttt{BoundaryConditions} schedule
+group (see section \ref{Boundary/sec:schedule_groups}), will return
+an error code.  However, in most cases it is optional.  If one uses
+an invalid table handle here (such as -1), commonly used default
+values will be assumed for all arguments (besides the explicit faces
+specification and boundary widths).  Note that you, the user, will
+be creating the table, so you may choose whatever options (such as
+case sensitivity) you like.  The case of the keys for which the
+boundary conditions implemented in this thorn search are as given
+in the documentation, which is currently all capitals.  To be safe
+you may choose to create case-insensitive tables, however cases
+sensitive tables are slightly faster.
 
 The name of the boundary condition must match that with which the
 boundary condition providing function was registered.  These names are
-case insensitive.  See section \ref{sec:provided_bcs} for a list of
+case insensitive.  See section \ref{Boundary/sec:provided_bcs} for a list of
 boundary conditions provided by thorn \texttt{Boundary}.
 
 
 \subsection{Schedule groups}
-\label{schedule_groups}
+\label{Boundary/sec:schedule_groups}
 
 Implementation \texttt{Boundary} creates two schedule groups
 \begin{verbatim}
@@ -281,7 +290,7 @@ gets executed exactly once for each selected grid variable.
 
 
 \subsection{Faces}
-\label{faces}
+\label{Boundary/sec:faces}
 
 The computational domain is assumed to be in the shape of a
 $n$-dimensional `rectangle', which has $2n$ $n-1$ dimensional faces.  (Usually $n$
@@ -304,7 +313,7 @@ its argument), and $e_j$ represents the `$j$-direction' on the grid.
 
 
 \section{Provided boundary conditions}
-\label{sec:provided_bcs}
+\label{Boundary/sec:provided_bcs}
 Thorn \texttt{Boundary} also provides seven standard boundary
 conditions, which can be applied to one, two, or three dimensional
 grid variables.  The boundary conditions available are
@@ -615,7 +624,7 @@ direction.
 
 The radiative boundary condition that is implemented is
 \begin{equation}
-\label{eqrad}
+\label{Boundary/eq:eqrad}
 f = f_0 + \frac{u(r-vt)}{r}+\frac{h(r+vt)}{r}
 \end{equation}
 That is, outgoing radial waves with a $1/r$
@@ -623,7 +632,7 @@ fall off, and the correct asymptotic value $f_0$ are assumed, including
 the possibility of incoming waves
 (these incoming waves should be modeled somehow).
 
-Condition~\ref{eqrad} above leads to the differential equation:
+Condition~\ref{Boundary/eq:eqrad} above leads to the differential equation:
 \begin{equation}
 \frac{x^i}{r}\frac{\partial f}{\partial t}
 + v \frac{\partial f}{\partial x^i}
@@ -1107,7 +1116,7 @@ There is no old interface to this boundary condition.
 
 
 \section{Appendix: Symmetry and non-local boundary conditions}
-\label{apx:symmetry}
+\label{Boundary/apx:symmetry}
 
 An additional aliased function is provided to allow one to retrieve a
 list of grid variables which are selected for any particular boundary
@@ -1144,7 +1153,7 @@ int Boundary_SelectedGVs(CCTK_POINTER cctkGH,
 \end{tabbing}
 This function places a list of up to \texttt{array\_size} grid
 variable indices, sorted as described in section
-\ref{sec:bc_registration}, into the array \texttt{var\_indices}.  The
+\ref{Boundary/sec:bc_registration}, into the array \texttt{var\_indices}.  The
 corresponding (up to \texttt{array\_size}) faces specifications,
 boundary widths, and table handles are placed into the arrays
 \texttt{faces}, \texttt{boundary\_widths}, and