Following an e-mail conversation with Gab, for brevity

got rid of "Adding a..." prefix to Infrastructure Guide chapter titles
preferring to explain what one adds at the beginning of the chapter text.

Also rearranged explanation of Timer functions.


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

2 files changed, 35 insertions, 23 deletions

diff --git a/doc/UsersGuide/Infrastructure.tex b/doc/UsersGuide/Infrastructure.tex
index 2dd4119e..113a4300 100644
--- a/doc/UsersGuide/Infrastructure.tex
+++ b/doc/UsersGuide/Infrastructure.tex
@@ -122,12 +122,14 @@ the schedule tree.
    \hline
  \end{tabular}
 
-\chapter{Adding a Driver}
+\chapter{Drivers}
 
 The Flesh knows nothing about memory allocation for grid variables, or about how
 to communicate data when synchronisation is called for.  It knows nothing about
 multiple patches or adaptive mesh refinement.  All this is the job of a driver.
 
+This chapter describes how to add a driver to your code.
+
 \section{Anatomy}
 
 A driver consists of a Startup routine which creates a GH extension and
@@ -396,13 +398,16 @@ they flag that communication is to be done on that group or not, and may
 initialise data structures for the communication.
 
 
-\chapter{Adding an I/O Method}
+\chapter{I/O Methods}
 \label{chap:io_methods}
 %
-The Flesh does not implement output for grid variables and other data by itself.
+The Flesh by itself does not provide output for grid variables or other data.
 Instead it provides a mechanism for thorns to register their own
 routines as I/O methods, and to invoke these I/O methods by either the
 Flesh scheduler or by other thorn routines.
+
+This chapter explains how to implement I/O your own methods and register
+them with the Flesh.
 %
 \section{I/O Method Registration}
 %
@@ -508,14 +513,17 @@ was done successfully, or a negative error code otherwise.
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\chapter{Adding a Checkpointing/Recovery Method}
+\chapter{Checkpointing/Recovery Methods}
 \label{chap:cp_recovery_methods}
 
 Like for I/O methods, checkpointing/recovery functionality must be implemented
 by thorns. The Flesh only provides specific time bins at which the scheduler
 will call thorns' routines in order to perform checkpointing and/or recovery.
 
-\section{Invocation of Checkpointing Routines}
+This chapter explains how to implement checkpointing and recovery methods
+in your thorn.
+
+\section{Checkpointing Invocation}
 
 Thorns register their checkpointing routines at {\t CCTK\_CPINITIAL} and/or
 {\t CCTK\_CHECKPOINT}. These time bins are scheduled right after all initial
@@ -537,7 +545,7 @@ state. Such information would include
 \end{itemize}
 
 
-\section{Invocation of Recovery Routines}
+\section{Recovery Invocation}
 
 Recovering from a checkpoint is a two-phase operation for which the Flesh
 provides distinct timebins for recovery routines to be scheduled at:
@@ -576,11 +584,11 @@ provides distinct timebins for recovery routines to be scheduled at:
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\chapter{Adding a timer clock}
+\chapter{Clocks for Timing}
 \label{chap:clocks}
 
-To add a Cactus timer clock you need to write several functions to provide the
-clock functionality (see Section \ref{sec:timers}), and then register these
+To add a Cactus clock you need to write several functions to provide the
+timer functionality (see Section \ref{sec:timers}), and then register these
 functions with the Flesh as a named clock.
 
 The function pointers are placed in function pointer fields of a 
@@ -616,9 +624,9 @@ The \texttt{n\_vals} field holds the number of elements in the
 used by your timer.
 
 To name and register the clock with the Flesh, call the function
-\begin{verbatim}
-	CCTK_ClockRegister( "my_clock_name", &clock_func ).
-\end{verbatim}
+\begin{alltt}
+	CCTK_ClockRegister( "\var{my_clock_name}", &\var{clock_func} ).
+\end{alltt}
 
 
 
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index a98b80f1..549e681e 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -3437,27 +3437,31 @@ from the different clocks.
 
 \subsection{Timing calls}
 
+Many of the timing calls come in two versions, one whose name ends with 
+the letter \texttt{I} and another one.  The calls whose names end in the 
+letter \texttt{I} refer to the timer by index; the other calls
+refer to a timer by name.  If a timer is created without a name, it can
+be referred to only by its index, otherwise, it can be referred to by name
+or by index.
+
 \begin{Lentry}
 
 \item[{\t CCTK\_TimerCreate}, {\t CCTK\_TimerCreateI}]
 
 Create a timer with a given name ({\t CCTK\_TimerCreate}), or with no name
-({\tt CCTK\_TimerCreateI})  and give back a timer index.
-If no name is provided for the timer, future calls
-should be made using the returned timer index.
+({\tt CCTK\_TimerCreateI}) and return a timer index.
 
 \item[{\t CCTK\_TimerDestroy}, {\t CCTK\_TimerDestroyI}]
 
-Destroy a timer using either the timer name or timer index.
+Destroy a timer.
 
 \item[{\t CCTK\_TimerStart}, {\t CCTK\_TimerStartI}]
 
-Start the given timer (identified by name or index), using all registered
-clocks.
+Start the given timer, using all registered clocks.
 
 \item[{\t CCTK\_TimerStop}, {\t CCTK\_TimerStopI}]
 
-Stop the given timer (identified by name or index) on all registered clocks.
+Stop the given timer on all registered clocks.
 
 \item[{\t CCTK\_TimerReset}, {\t CCTK\_TimerResetI}]
 
@@ -3538,7 +3542,7 @@ precedes using the timer:
 
 \begin{verbatim}
 #include "cctk_Timers.h"
-ierr = CCTK_TimerCreate(`TimeMyStuff`);
+ierr = CCTK_TimerCreate("TimeMyStuff");
 \end{verbatim}
 
 {\bf Instrumenting a section of code}
@@ -3547,10 +3551,10 @@ Code sections are instrumented using the Start, Stop and Reset functions. These
 functions are applied to the chosen timer using all the registered clocks.
 \begin{verbatim}
 #include "cctk_Timers.h"
-ierr = CCTK_TimerStart(`TimeMyStuff`);
+ierr = CCTK_TimerStart("TimeMyStuff");
 /* Piece of code to time */
 y = CalculateNewValue(y);
-ierr = CCTK_TimerStop(`TimeMyStuff`);
+ierr = CCTK_TimerStop("TimeMyStuff");
 \end{verbatim}
 
 {\bf Accessing the timer results}
@@ -3563,7 +3567,7 @@ of different types.
 cTimerData *info;
 
 info = CCTK_TimerCreateData();
-ierr = CCTK_Timer('TimeMyStuff',info);
+ierr = CCTK_Timer("TimeMyStuff",info);
 
 for (i = 0; i < info->n_vals; i++)
 {