--- manual/s_phys_pkgs/text/packages.tex	2004/02/12 16:40:28	1.3
+++ manual/s_phys_pkgs/text/packages.tex	2010/07/26 15:48:56	1.7
@@ -1,7 +1,11 @@
-% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/text/packages.tex,v 1.3 2004/02/12 16:40:28 edhill Exp $
+% $Header: /home/ubuntu/mnt/e9_copy/manual/s_phys_pkgs/text/packages.tex,v 1.7 2010/07/26 15:48:56 jmc Exp $
 % $Name:  $
 
 \section{Using MITgcm Packages}
+\label{sec:pkg:using}
+\begin{rawhtml}
+<!-- CMIREDIR:package_using: -->
+\end{rawhtml}
 
 The set of packages that will be used within a partiucular model can
 be configured using a combination of both ``compile--time'' and
@@ -37,8 +41,9 @@
   automatically obtains all packages in that group.
 
 \item By default (that is, if a \texttt{packages.conf} file is not
-  found), the \texttt{genmake2} program will use the contents of the
-  \texttt{pkg/pkg\_default} file to obtain a list of packages.
+  found), the \texttt{genmake2} program will use the
+  package group default ``\texttt{default\_pkg\_list}'' as defined 
+  in \texttt{pkg/pkg\_groups} file.
 
 \item To help prevent users from creating unusable package groups, the
   \texttt{genmake2} program will parse the contents of the
@@ -75,12 +80,12 @@
 still be aware of the dependency.
 
 
-\section{Package Coding Standards}
+\subsection{Package Coding Standards}
 
 The following sections describe how to modify and/or create new MITgcm
 packages.
 
-\subsection{Packages are Not Libraries}
+\subsubsection{Packages are Not Libraries}
 
 To a beginner, the MITgcm packages may resemble libraries as used in
 myriad software projects.  While future versions are likely to
@@ -224,7 +229,7 @@
 
         #ifdef ALLOW_${PKG}
           if ( use${Pkg} )
-     &       CALL ${PKG}_DIAGS( )
+     &       CALL ${PKG}_OUTPUT( )
         #endif
 
      7. S/R PACKAGES_WRITE_PICKUP()
@@ -236,5 +241,21 @@
 }
 
 
-\subsubsection{Package Startup or Boot Sequence}
+\subsubsection{Adding a package to PARAMS.h and  packages\_boot()}
+
+An MITgcm package directory contains all the code needed for that package apart
+from one variable for each package. This variable is the {\tt use\$\{Pkg\} } 
+flag. This flag, which is of type logical, {\bf must} be declared in the 
+shared header file {\it PARAMS.h} in the {\it PARM\_PACKAGES} block. This 
+convention is used to support a single runtime control file {\it data.pkg} 
+which is read by the startup routine {\it packages\_boot()} and that sets a 
+flag controlling the runtime use of a package. This routine needs to be able to 
+read the flags for packages that were not built at compile time. Therefore
+when adding a new package, in addition to creating the per-package directory
+in the {\it pkg/} subdirectory a developer should add a {\tt use\$\{Pkg\} }
+flag to {\it PARAMS.h} and a {\tt use\$\{Pkg\} } entry to the 
+{\it packages\_boot()} {\it PACKAGES} namelist.
+The only other package specific code that should appear outside the individual 
+package directory are calls to the specific package API.
+