Split of a "Reference Manual" from the Users Guide. Will update the docs

and different options for this, and add its own directory once we settle
on the name of it.

Fixes Cactus/1545


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

6 files changed, 337 insertions, 20 deletions

diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex
index 23663d4a..21fb055e 100644
--- a/doc/UsersGuide/Appendices.tex
+++ b/doc/UsersGuide/Appendices.tex
@@ -7,7 +7,7 @@
 %   @enddesc
 %   @version   $Header$
 % @@*/
-\begin{cactuspart}{6}{Appendices}{$RCSfile$}{$Revision$}
+\begin{cactuspart}{5}{Appendices}{$RCSfile$}{$Revision$}
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 
 \chapter{Glossary}
@@ -19,8 +19,8 @@
   the externally-visible interface provided by some software component.
   (An API usually consists of a set of subroutine/function calls, but
   may also include data passed via Cactus key-value tables, grid arrays,
-  or other means.)  For example, part~\ref{part:FunctionReference} of
-  this manual documents most of the Cactus flesh APIs.
+  or other means.)  For example, the Reference Manual 
+  documents most of the Cactus flesh APIs.
 \item[{\tt arrangement}] A collection of thorns, normally stored
   in the Cactus \verb|arrangements| directory.
 \item[{\tt autoconf}] A GNU program which builds a configuration
diff --git a/doc/UsersGuide/FunctionReference.tex b/doc/UsersGuide/FunctionReference.tex
index bb445354..58f3d328 100644
--- a/doc/UsersGuide/FunctionReference.tex
+++ b/doc/UsersGuide/FunctionReference.tex
@@ -13,7 +13,7 @@
 %               add key/value table functions in that section
 %   @endhistory
 % @@*/
-\begin{cactuspart}{5}{FunctionReference}{$RCSfile$}{$Revision$}
+\begin{cactuspart}{1}{FunctionReference}{$RCSfile$}{$Revision$}
 \renewcommand{\thepage}{\Alph{part}\arabic{page}}
 \label{part:FunctionReference}
 
@@ -4897,7 +4897,7 @@ Returns the total number of IO methods registered with the flesh.
 % Groups.c
 
 \begin{CCTKFunc}{CCTK\_NumTimeLevels}{Gives the number of timelevels for a group}
-\label{CCTK-NumTimeLevelsFromVar}
+\label{CCTK-NumTimeLevels}
 \subroutine{int}{integer}{numlevels}
 \argument{const char *}{character*(*)}{name}
 \showargs
@@ -6254,7 +6254,7 @@ a variable argument list as a warning message to {\t stderr}.
 By default Cactus prints any warning with warning levels $\le 1$ to standard
 error, and would stop the code on a level 0 warning.
 This behaviour can be changed on the command line using
-the flags {\t -W} and {\t -E} (see \ref{sec:coliop} for full details).
+the flags {\t -W} and {\t -E} (see the Users' Guide for full details).
 
 The boolean flesh parameter {\tt cctk\_full\_warnings} determines whether all
 the details about the warning origin (processor ID, line number, source file,
@@ -7245,7 +7245,7 @@ the other.
 Note that table iterators are {\em not\/} guaranteed to sequence
 through the original and clone tables in the same order.  (This
 is a special case of the more general ``non-guarantee'' in
-section~\ref{sect-UtilityRoutines/tables/table-iterators}:
+the Section of table iterators in the Users' Guide:
 the order of table iterators may differ even between different
 tables with identical key/value contents.)
 \end{Discussion}
diff --git a/doc/UsersGuide/Reference.tex b/doc/UsersGuide/Reference.tex
new file mode 100644
index 00000000..e12c4d55
--- /dev/null
+++ b/doc/UsersGuide/Reference.tex
@@ -0,0 +1,321 @@
+% /*@@
+%   @file      Reference.tex
+%   @date      Saturday 5th July 2003
+%   @author    Gabrielle Allen
+%   @desc 
+%   Main file for the Cactus Reference Manual
+%   @enddesc 
+%   @version $Header$      
+% @@*/
+
+\documentclass{report}
+\usepackage{fancyhdr,ifthen,calc}
+\usepackage{../latex/cactus}
+
+\newif\ifpdf
+\ifx\pdfoutput\undefined
+\pdffalse % we are not running PDFLaTeX
+\else
+\pdfoutput=1 % we are running PDFLaTeX
+\pdftrue
+\fi
+
+\makeatletter
+\@addtoreset{chapter}{part}
+\makeatother
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\parskip = 0 pt
+\parindent = 0pt
+\oddsidemargin = 0 cm
+\textwidth = 16 cm
+\topmargin = -1 cm
+\textheight = 24 cm
+
+\usepackage{tocloft}
+\addtolength{\cftchapnumwidth}{0.5em}
+\addtolength{\cftsecnumwidth}{0.5em}
+\addtolength{\cftsubsecnumwidth}{0.5em}
+\addtolength{\cftsubsubsecnumwidth}{0.5em}
+
+\ifpdf
+\pdfinfo{ /Author (Gabrielle Allen, Tom Goodale, Gerd Lanfermann, Thomas Radke, David Rideout, Jonathan Thornburg) 
+          /Title (Cactus Reference Manual)
+}
+\usepackage[pdftex,plainpages=false,pdfpagelabels,hypertexnames=false,
+                   colorlinks=true,pdfstartview=FitV,
+                   linkcolor=blue,citecolor=blue,
+                   urlcolor=blue]{hyperref}
+\usepackage{graphicx}
+\usepackage{thumbpdf}
+\else
+\usepackage{graphicx}
+\fi
+
+\def\q{\bf QUERY: }
+\def\t{\tt \obeylines }
+\def\ie{\hbox{i.e.\hbox{}}}
+
+% nicely typeset "C++" (adapted from a comp.lang.C++ FAQ entry)
+\def\Cplusplus{\hbox{C\hspace{-.05em}\raisebox{.4ex}{\tiny\bf ++}}}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\newenvironment{CCTKroutine}{\newpage}{}
+\newenvironment{CCTKsyn}{\noindent\begin{tabular}{@{}p{3cm}cp{11cm}}&&\\{\bf Synopsis} \hfill&&\\}{\end{tabular}}
+% The above needs to be fixed -- sometimes it runs off the page (e.g. with cctk_complex arguments...)
+\newenvironment{CCTKpar}{\noindent\begin{tabular}{@{}p{3cm}cp{11cm}}&&\\{\bf Parameters} \hfill&&\\}{\end{tabular}}
+\newcommand{\CCTKname}[1]{\noindent{\t #1}\hrule}
+\newcommand{\CCTKdesc}[1]{\vskip .3cm \noindent #1}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%Define some saveboxes to hold data
+\newsavebox{\cctkbox}
+\newsavebox{\cctkcargbox}
+\newsavebox{\cctkfargbox}
+\newsavebox{\cctkfargdefs}
+\newsavebox{\cctkcsepbox}
+\newsavebox{\cctkfsepbox}
+\newsavebox{\cctkfdefssep}
+\newsavebox{\cctkcprefix}
+\newsavebox{\cctkfprefix}
+\newsavebox{\cctkparambox}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newenvironment{CCTKFunc}[2]
+        {\sbox{\cctkbox}{#1}
+         \newpage
+         \noindent{\t #1}\hrule 
+         \vskip .3cm \noindent #2\\
+%Clear the saveboxes - this may not be neccessary
+         \sbox{\cctkcargbox}{}
+         \sbox{\cctkfargbox}{}
+         \sbox{\cctkfargdefs}{}
+         \sbox{\cctkcsepbox}{}
+         \sbox{\cctkfsepbox}{}
+         \sbox{\cctkfdefssep}{}
+         \sbox{\cctkcprefix}{}
+         \sbox{\cctkfprefix}{}
+%A command to add an argument - takes ctype, ftype, name
+         \newcommand{\argument}[3]
+         {\sbox{\cctkcargbox}{\usebox{\cctkcargbox}\usebox{\cctkcsepbox} ##1 ##3} 
+          \sbox{\cctkcsepbox}{,}
+          \sbox{\cctkfargbox}{\usebox{\cctkfargbox}\usebox{\cctkfsepbox} ##3} 
+          \sbox{\cctkfsepbox}{,}
+          \sbox{\cctkfargdefs}{\noindent{}\vbox{\noindent\usebox{\cctkfargdefs}\noindent\usebox{\cctkfdefssep}\noindent {}  ##2 ##3}}
+          \sbox{\cctkfdefssep}{\\}
+         }
+%Use this command if it is a subroutine, same args as \argument
+         \newcommand{\subroutine}[3]
+         {\sbox{\cctkcprefix}{##1 ##3 =}
+          \sbox{\cctkfprefix}{call}
+          \sbox{\cctkfargbox}{##3\usebox{\cctkfsepbox} \usebox{\cctkfargbox}} 
+          \sbox{\cctkfsepbox}{,}
+          \sbox{\cctkfargdefs}{\noindent{}\vbox{\noindent ##2 ##3 \usebox{\cctkfdefssep}\noindent{}\usebox{\cctkfargdefs}}}
+          \sbox{\cctkfdefssep}{\\}
+         }
+
+%Use this command if it is a function, same args as \argument
+         \newcommand{\function}[3]
+         {\sbox{\cctkcprefix}{##1 ##3 =}
+          \sbox{\cctkfprefix}{##3 = }
+          \sbox{\cctkfargdefs}{\noindent{}\vbox{\noindent ##2 ##3 \usebox{\cctkfdefssep}\noindent{}\usebox{\cctkfargdefs}}}
+          \sbox{\cctkfdefssep}{\\}
+         }
+
+%Use this to display the arguments
+         \newcommand{\showargs}
+         {\noindent
+          \begin{tabular}{@{}p{3cm}cp{11cm}}&&\\
+{\bf Synopsis} \hfill&&\\ 
+\hfill {\bf C} && {\t \usebox{\cctkcprefix} \usebox{\cctkbox}(\usebox{\cctkcargbox})}\\
+\hfill {\bf Fortran} && 
+{\t \usebox{\cctkfprefix} \usebox{\cctkbox}(\usebox{\cctkfargbox} ) }\\
+&&\noindent\usebox{\cctkfargdefs}
+\end{tabular}\\
+}
+
+%Use this to display the C arguments
+         \newcommand{\showcargs}
+         {\noindent
+          \begin{tabular}{@{}p{3cm}cp{11cm}}&&\\
+{\bf Synopsis} \hfill&&\\ 
+\hfill {\bf C} && {\t \usebox{\cctkcprefix} \usebox{\cctkbox}(\usebox{\cctkcargbox})}\\
+\end{tabular}\\
+}
+
+
+%Environment for describing parameters
+          \newenvironment{params}{
+             \noindent\begin{tabular}{@{}p{3cm}cp{11cm}}&&\\{\bf Parameters} \hfill&&\\}{\end{tabular}\\}
+%Command to describe a parameter, takes name and description
+          \newcommand{\parameter}[2]{
+\\
+\hfill {\t ##1} &-&##2
+\\
+}
+%Environment for discussion
+    \newenvironment{discussion}
+    {\noindent
+     \begin{tabular}{@{}p{14cm}}
+     \\{\bf Discussion} \hfill\\
+    }
+    {
+     \end{tabular}\\
+    }
+%Environment for examples
+    \newenvironment{examples}
+    {\noindent
+     \begin{tabular}{@{}p{14cm}}
+     \\{\bf Examples} \hfill\\
+    }
+    {
+     \end{tabular}\\\\
+    }
+
+%Environment for describing errors
+     \newenvironment{errorcodes}
+    {\noindent
+     \begin{tabular}{@{}p{6cm}cp{10cm}}&&\\
+     {\bf Errors} \hfill&&\\}
+    {\end{tabular}\\}
+%Command to describe an errorcode, takes name and description
+          \newcommand{\errorcode}[2]{
+\\
+\hfill {\t ##1} &-&##2
+\\
+}
+
+}% end of \begin{CCTKFunc} expansion
+{}% \end{CCTKFunc} expansion
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% ***** \cactustitlepage *****
+%
+% Takes three arguments - the name of the document, the revision, and
+% the date.
+% Additionally there is an optional first argument with the version number
+%
+\newcommand{\cactustitlepage}[4][4.0]
+{
+\thispagestyle{empty}
+\setlength{\parindent}{0mm}
+\setlength{\parskip}{0mm}
+\vspace*{\stretch{1}}
+\rule{\linewidth}{1mm}
+\begin{flushright}
+  \Huge Cactus #1\\[5mm]
+        #2
+\end{flushright}
+\rule{\linewidth}{1mm}
+\vspace*{\stretch{2}}
+\begin{center}
+\ifpdf
+\else
+\includegraphics[angle=0,width=5cm]{bincactus2.eps}
+\fi
+\end{center}
+\vspace*{\stretch{2}}
+\begin{center}
+   \Large #3 \\[3mm]
+          #4
+\end{center}
+\newpage
+\setlength{\parindent}{0mm}
+\setlength{\parskip}{0mm}
+}
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newenvironment{cactuspart}[4]
+{
+  \clearpage
+  \renewcommand{\thepage}{\Alph{part}\arabic{page}}
+  % Redefine the plain style
+  \fancypagestyle{plain}
+  {
+    \fancyhf{} % Clear all header and footer fields
+    \lfoot{#3}
+    \cfoot{#4}
+    \rfoot{\thepage/\pageref{lastpage:\thepart}}
+    \renewcommand{\headrulewidth}{0.0pt}  
+    \renewcommand{\footrulewidth}{0.4pt}  
+    \renewcommand{\thepage}{\Alph{part}\arabic{page}}
+  }
+
+  % Make sure it's arabic numbering
+  \pagenumbering{arabic}
+  % Start the page counter at 1
+  \setcounter{page}{1}
+  % Start a new part
+  \renewcommand{\thepage}{\Alph{part}\arabic{page}}
+  \part{#2}
+  \setcounter{part}{#1}
+  % Redefine the page
+  % Set up fancy headings.
+  \lfoot{#3}
+  \cfoot{#4}
+  \rfoot{\thepage/\pageref{lastpage:\thepart}}
+  \renewcommand{\headrulewidth}{0.4pt}
+  \renewcommand{\footrulewidth}{0.4pt}
+}
+{
+  % Remember the last page of the 
+  \label{lastpage:\thepart}
+  \clearpage
+}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\begin{document}
+
+\ifpdf
+\DeclareGraphicsExtensions{.pdf, .jpg}
+\else
+\DeclareGraphicsExtensions{.eps, .jpg}
+\fi
+
+\cactustitlepage{Reference Manual}{$ $Revision$ $}{$ $Date$ $}
+
+\setcounter{page}{1}
+
+% Table of contents
+\pagenumbering{roman}
+
+\tableofcontents
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\renewcommand{\thepart}{\Alph{part}}
+\renewcommand{\thechapter}{\Alph{part}\arabic{chapter}}
+\renewcommand{\thepage}{\Alph{part}\arabic{page}}
+\pagestyle{fancy}
+\parskip = 10 pt
+\parindent = 0pt
+
+\newpage
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\include{Preface}
+
+
+\include{FunctionReference}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\end{document}
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index c940acc5..7518841c 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -1880,8 +1880,7 @@ parallelisation. The method used to provide this parallelisation
 the driver thorn provides routines which are called by standard interfaces
 from the flesh. Here we describe briefly the most important of these routines
 for the application thorn writer. A more detailed description
-of these interfaces with their arguments, is given in the Function Reference
-Guide (Part \ref{part:FunctionReference}).
+of these interfaces with their arguments, is given in the Reference Manual.
 A complete description of the
 routines a driver thorn must provide will be provided in the
 Infrastructure Thorn Writers guide (Part \ref{part:infrastructure}). The standard driver thorn is
@@ -2320,8 +2319,7 @@ routine to another!):
 %notyet \item[{\tt CCTK\_InterpRegisterOpLocalWarped()}]
 %notyet         Register a \verb|CCTK_InterpLocalWarped()| interpolation operator
 \end{Lentry}
-These are described in detail in part~\ref{part:FunctionReference}
-of this manual.
+These are described in detail in the Reference Manual.
 
 Each operator is registered under a character-string name; at
 registration the name is mapped to a unique integer handle which
@@ -2382,8 +2380,7 @@ of a one element array).
 
 The reduction interface is currently under revision, and in the future
 should closely resemble that of the new interpolator interface.
-See e.g. the description of \verb|CCTK_InterpLocalUniform()| on
-page~\pageref{CCTK-InterpLocalUniform}.
+See e.g. the description of \verb|CCTK_InterpLocalUniform()| in the Reference Manual.
 
 \vskip .24cm
 {\bf Obtaining the reduction handle}
diff --git a/doc/UsersGuide/UsersGuide.tex b/doc/UsersGuide/UsersGuide.tex
index e6e40b93..df0d06c0 100644
--- a/doc/UsersGuide/UsersGuide.tex
+++ b/doc/UsersGuide/UsersGuide.tex
@@ -315,7 +315,7 @@
 
 \include{Infrastructure}
 
-\include{FunctionReference}
+%\include{FunctionReference}
 
 \include{Appendices}
 
diff --git a/doc/UsersGuide/UtilityRoutines.tex b/doc/UsersGuide/UtilityRoutines.tex
index 9a65a78a..d14b412b 100644
--- a/doc/UsersGuide/UtilityRoutines.tex
+++ b/doc/UsersGuide/UtilityRoutines.tex
@@ -39,8 +39,7 @@ good way to do this.
 
 Key/value tables (``tables'' for short) provide a clean solution
 to these problems.  They're implemented by the \verb|Util_Table|*
-functions (described in detail in
-section~\ref{sect-FunctionReference/UtilityFunctions}).
+functions (described in detail in the Reference Manual).
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -98,7 +97,7 @@ various options, via bit flags defined in \verb|"util_Table.h"|.
 For example, the flags word can be used to control whether keys
 should be compared as case-sensitive or case-insensitive strings.
 See the detailed function description of \verb|Util_TableCreate()|
-in section~\ref{sect-FunctionReference/UtilityFunctions} for a list
+in the Reference Manual for a list
 of the possible bit flags and their semantics.  
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -110,7 +109,7 @@ Here's a simple example (in C)%%%
 \footnote{%%%
 	 All (or almost all) of the table routines
 	 are also usable from Fortran.  See the full
-	 descriptions in section~\ref{sect-FunctionReference/UtilityFunctions}
+	 descriptions in the Reference Manual
 	 for details.
 	 }%%%
 {} of how to use a table:
@@ -145,7 +144,7 @@ and only if some sort of error has occured.%%%
 	 you do, there are various error codes defined in
 	 {\t "util\_Table.h"} and {\t "util\_ErrorCodes.h"};
 	 the detailed function descriptions in
-	 section~\ref{sect-FunctionReference/UtilityFunctions}
+	 the Reference Manual
 	 say which error codes each function can return.
 	 }%%%
 {}  So, the above example should be rewritten like this:
@@ -362,7 +361,7 @@ Multiple iterators may point into the same table; they all use the
 same order, and (unlike in Perl) they're all independent.
 
 The detailed function description
-(section~\ref{sect-FunctionReference/UtilityFunctions})
+in the Reference Manual
 for \verb|Util_TableItQueryKeyValueInfo()| has an example of
 using an iterator to print out all the entries in a table.