Add how you use the macros from C code. Fixes PR1077.

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinBase/ADMMacros/trunk@58 b1d164ef-f17a-46e7-89d4-021c7118ef4e

1 files changed, 29 insertions, 17 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 75d8754..dc022a6 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -25,12 +25,12 @@ Provides macros for other ADM based thorns to use
 
 This thorn provides various macros which can be used to calculate
 quantities, such as the Christoffel Symbol or Riemann Tensor
-components, using the basic variables of thorn {\tt ADMBase}.
-The macros can be used in both Fortran and C code. The macros work 
-pointwise to calculate quantities at specific grid points, which are 
-always labelled by {\tt i}, {\tt j} and {\tt k}. They are written in 
-such a way that needed quantities which are already calculated are 
-reused.
+components, using the basic variables of thorn {\tt ADMBase} (and {\tt
+  StaticConformal} if required).  The macros can be used in both
+Fortran and C code. The macros work pointwise to calculate quantities
+at specific grid points, which are always labelled by {\tt i}, {\tt j}
+and {\tt k}. They are written in such a way that needed quantities
+which are already calculated are reused.
 
 \section{Using ADM Macros}
 
@@ -40,26 +40,38 @@ files.
 \begin{itemize}
 
 \item {\tt <MACRONAME>\_declare.h} sets up the declarations for the internal macro 
-	variables. All the internal (hidden) variables have names beginning with 
+        variables. All the internal (hidden) variables have names beginning with 
         the macro name. This file should be included in the declarations section
-	of your routine.
+        of your routine.
 
 \item {\tt <MACRONAME>\_guts.h} is the actual included source code which will calculate
        the quantities.
 
 \item {\tt <MACRONAME>\_undefine.h} resets the macros. This file {\bf must be included}
-	at the end of every loop using macros. Without an undefine file, a second loop
-  	using macros will assume that quantities have already been calculated.
+        at the end of every loop using macros. Without an undefine file, a second loop
+        using macros will assume that quantities have already been calculated.
 
 \end{itemize}
 
-To use the macros, first make sure that you really want to use the macro pointwise, and 
-that you have already set the indices $i$, $j$, and $k$ to identify the correct grid point. 
-
-Find the name of the macro from the table in Section~\ref{admmacros:macros} and put the include 
-files in the correct place following the instructions above. Note that all ADMMacro include files
-are in the directory {\tt CactusEinstein/ADMMacros/src/macros}, so this means adding lines such 
-as
+To use the macros, first make sure that you really want to use the
+macro pointwise, and that you have already set the indices $i$, $j$,
+and $k$ to identify the correct grid point. If you are using the
+macros inside a Fortran function then the {\tt i}, {\tt j} and {\tt k}
+indices are used directly. If you are using the macros inside a C
+function then you should define the index {\tt ijk}, which can be
+found from {\tt i}, {\tt j} and {\tt k} using the macro {\tt
+  CCTK\_GFINDEX3D(cctkGH,i,j,k)}, and also the offsets {\tt di}, {\tt
+  dj} and {\tt dk}, so that the point $(i-1,j,k)$ is the same as {\tt
+  ijk - di} and so on. Typically this would mean that {\tt dk = 1},
+{\tt dj = cctk\_lsh[2]} and {\tt di = cctk\_lsh[1]*cctk\_lsh[2]}, where
+C-style numbering is used.
+
+Find the name of the macro from the table in
+Section~\ref{admmacros:macros} and put the include files in the
+correct place following the instructions above. Note that all ADMMacro
+include files are in the directory {\tt
+  CactusEinstein/ADMMacros/src/macros}, so this means adding lines
+such as
 
 {\tt
 \begin{verbatim}