Finish updating doc for function pointers.

bmad/doc/cover-page.tex

@@ -3,7 +3,7 @@
 
 \begin{flushright}
 \large
- Revision: November 1, 2023 \\
+ Revision: November 4, 2023 \\
 \end{flushright}
 
 \pdfbookmark[0]{Preamble}{Preamble} 

bmad/doc/misc-programming.tex

@@ -15,15 +15,14 @@ \section{Custom and Hook Routines}
 To enable \bmad to be able to call customized code, \vn{function pointers} are defined, one for each
 custom or hook routine. At certain places in the \bmad code, the appropriate function pointer will
 be checked. If the funtion pointer is associated with a routine, that routine will be called. By
-default, the function pointers are not associated with any functions.
-
-The function pointers are defined in the file \vn{/bmad/modules/bmad_routine_interface.f90}. The convention
-followed is that the abstract interface name has a \vn{_def} suffix and the function pointer name
-has a \vn{_ptr} suffix. For example, there is a \vn{track1_custom} routine prototype that is given
-in the in the file \vn{/bmad/custom/track1_custom.f90}. In \vn{/bmad/modules/bmad_routine_interface.f90} there
-are two interfaces for this routine. One interface defines the argument list for \vn{track1_custom} and the
-other (abstract) interface, defines the argement list for \vn{track1_custom_def} which is used to define
-the function pointer:
+default, the function pointers are not associated with any functions and the only way there will be
+an association by user code modification.
+
+The function pointers are defined in the file \vn{/bmad/modules/bmad_routine_interface.f90}. The
+convention followed is that for any given custom or hook routine there is a base name, for example,
+\vn{track1_custom}, and in \vn{bmad_routine_interface.f90} there will be an abstract interface which
+with the base name with a \vn{_def} suffix (\vn{track1_custom_def} for this example). Additionally
+the corresponding function pointer uses a \vn{_ptr} suffix and is defined like:
 \begin{example}
  procedure(track1_custom_def), pointer :: track1_custom_ptr => null()
 \end{example}
@@ -32,27 +31,45 @@ \section{Custom and Hook Routines}
 \begin{itemize}
 %
 \item 
-copy the file \vn{/bmad/custom/track1_custom.f90} to the area where the program is to be compiled.
+Copy the file \vn{/bmad/custom/track1_custom.f90} to the area where the program is to be compiled.
 %
 \item
-Code desired, 
-
-
-
-\etcetc
-
-
-Note: Custom and Hook entry points are added to \bmad on an as-needed basis. If you have a need that
-is not met by the existing set of entry points, please contact a \bmad maintainer.
-
+Customize file as desired. The name of the routine can be changed if desired as long as that name is used
+consistently throughout the program. In fact, multiple custom
+routines can be created and switched in and out as desired in the program.
+%
+\item
+In the program define an interface for the custom routine like:
+\begin{example}
+ procedure(track1_custom_def) :: track1_custom
+\end{example}
+Note: If the custom routine has been put in a module this will not be needed.
+%
+\item
+Somewhere near the beginning of the program (generally before \vn{bmad_parser} is called), set the
+function pointer to point to your custom routine:
+\begin{example}
+ track_custom_ptr => track1_custom
+\end{example}
+%
+\item
+If needed modify the compile script(s) (typically named something like ``cmake.XXX'') to compile the
+file the custom routine is in.
+%
+\item
+Compile the program using the \vn{mk} command.
+%
+\end{itemize}
 
 While coding a custom routine, it is important to remember that it is {\em not} permissible to
 modify any routine argument that does not appear in the list of output arguments shown in the
 comment section at the top of the file.
 
-Note: Remember to modify the appropriate compile script file (typically named something like
-``cmake.XXX'') so that any routines that you have added to your program area are compiled and
-linked.
+Note: Custom and hook entry points are added to \bmad on an as-needed basis. If you have a need that
+is not met by the existing set of entry points, please contact a \bmad maintainer.
+
+Note: The custom and hook routines in \vn{/bmad/custom/} are not compiled with the \bmad library. Their
+only purpose is to surve as prototypes for code development.
 
 %-----------------------------------------------------------------------------
 \section{Custom Calculations}

tao/doc/cover-page.tex

@@ -2,7 +2,7 @@
 
 \begin{flushright}
 \large
-Revision: October 28, 2023 \\
+Revision: November 4, 2023 \\
 \end{flushright}
 
 \vfill

tao/doc/customization.tex

@@ -52,12 +52,13 @@ \section{Initial Setup}
 \begin{example}
  \vn{ROOT/production/bin/custom_tao}. 
 \end{example}
-Similarly, the command \vn{mkd} will create a debug executable 
+If a debug executable is wanted, the command \vn{mkd} will create one at: 
 \begin{example}
  \vn{ROOT/debug/bin/custom_tao}
 \end{example}
  \end{enumerate}
-A debug executable only needs to be created if you a debugging the code.
+A debug executable is only needed if you are debugging the code. The debug exe will run much
+slower than the production version.
 
 %----------------------------------------------------------------
 \section{It's All a Matter of Hooks}
@@ -68,12 +69,29 @@ \section{It's All a Matter of Hooks}
 these files, copy it from \vn{tao/hook} to \vn{ROOT} and then make modifications to the copy.
 
 The reason for this golden rule is to ensure that, as time goes by, and revisions are made to the
-\tao routines to extend it's usefulness and to eliminate bugs, these changes will have a minimum
+\tao routines to extend \tao's usefulness and to eliminate bugs, these changes will have a minimum
 impact on the specialized routines you write. What happens if the modification you want to do
 cannot be accomplished by customizing a hook routine? The answer is to contact the \tao programming
 team and we will modify \tao and provide the hooks you need so that you can then do your
 customization.
 
+%----------------------------------------------------------------
+\section{Implementing a Hook Routine in Tao}
+
+Function pointers are used by \tao to call customized hook routines. \tao uses the same system as \bmad
+where an abstract interface with a \vn{_def} suffix in the name is defined along with a function
+pointer with a \vn{_ptr} suffix. See the section ``Custom and Hook Routines'' in the \bmad manual
+for more details. For example, the \vn{tao_hook_command} routine has the function pointer (defined
+in \vn{/tao/code/tao_interface.f90}):
+\begin{example}
+ procedure(tao_hook_command_def), pointer :: tao_hook_command_ptr => null()
+\end{example}
+To use a customized \vn{tao_hook_command} routine, the following can be put in the
+\vn{tao_program.f90} that was copied to your area:
+\begin{example}
+ tao_hook_command_ptr => tao_hook_command
+\end{example}
+
 %----------------------------------------------------------------
 \section{Initializing Hook Routines}