--- MITgcm/doc/devel_HOWTO.sgml	2004/04/06 04:12:00	1.7
+++ MITgcm/doc/devel_HOWTO.sgml	2005/01/05 03:45:24	1.8
@@ -886,6 +886,9 @@
    Package runtime config. options are imported
    into a common block held in a header file
    called "${PKG}.h".
+   Note: In some packages, the header file "${PKG}.h" is splitted 
+   into "${PKG}_PARAMS.h" that contains the package parameters and 
+   ${PKG}_VARS.h" for the field arrays.
 
 o  The core driver part of the model can check
    for runtime enabling or disabling of individual packages
@@ -908,12 +911,14 @@
     1. Within the core driver code flags of the form
        ALLOW_${PKG} are used to include or exclude
        whole packages. The ALLOW_${PKG} flags are included
-       from a PKG_CPP_OPTIONS block which is currently
+       from a PACKAGES_CONFIG.h file that is automatically 
+       generated by genmake2 (see genmake2 section).
        held in-line in the CPP_OPTIONS.h header file.
        e.g.
 
        Core model code .....
 
+       #include "PACKAGES_CONFIG.h"
        #include "CPP_OPTIONS.h"
          :
          :
@@ -925,8 +930,8 @@
 
     2. Within an individual package a header file,
        "${PKG}_OPTIONS.h", is used to set CPP flags
-       specific to that package. It is not recommended
-       to include this file in "CPP_OPTIONS.h".
+       specific to that package. It also includes 
+       "PACKAGES_CONFIG.h" and "CPP_OPTIONS.h".
 
 
 Package Boot Sequence
@@ -978,7 +983,7 @@
 
         #ifdef ALLOW_${PKG}
           if ( use${Pkg} )
-     &       CALL ${PKG}_DIAGS( )
+     &       CALL ${PKG}_DIAGS( )     [ or CALL ${PKG}_OUTPUT( ) ]
         #endif
 
      7. S/R PACKAGES_WRITE_PICKUP()
@@ -994,7 +999,7 @@
       - ${PKG}_READPARMS() 
     is responsible for reading
     in the package parameters file data.${pkg}, and storing
-    the package parameters in "${PKG}.h".
+    the package parameters in "${PKG}.h" (or in "${PKG}_PARAMS.h").
     -> called from INITIALISE_FIXED in PACKAGES_READPARMS
 
      - ${PKG}_INIT_FIXED() 
@@ -1024,14 +1029,16 @@
      use for e.g. ${PKG}_INI_VARS, ${PKG}_INIT_VARIABLES, or the old 
      form ${PKG}_INIT
 
-     - ${PKG}_DIAGS() 
-     is responsible for writing time-average diagnostics to output
-     files (but the cumulating step is done within the package main S/R).
+     - ${PKG}_DIAGS()      [or ${PKG}_OUTPUT( ) ]
+     is responsible for writing time-average fields to output files
+     (but the cumulating step is done within the package main S/R).
      Can also contain other diagnostics (.e.g. CALL ${PKG}_MONITOR) 
      and write snap-shot fields that are hold in common blocks. Other 
      temporary fields are directly dump to file where they are available.
-     NOTE: this part does not yet have a standard form and should be called
-       from a package dedicated S/R such as PACKAGE_WRITE_DIAGS
+     NOTE: 1) ${PKG}_OUTPUT is progressively replacing ${PKG}_DIAGS()
+              to avoid confusion with pkg/diagnostics functionality.
+           2) the output part is not yet in a standard form and might still
+              evolve a lot.
     -> called within DO_THE_MODEL_IO
 
      - ${PKG}_WRITE_PICKUP() 
@@ -1058,6 +1065,8 @@
   -----------------------
   * ${PKG}_OPTIONS.h     has further package-specific CPP options
   * ${PKG}.h             package-specific common block variables, fields
+   or  ${PKG}_PARAMS.h   package-specific common block parameters
+   and ${PKG}_VARS.h     package-specific common block fields
 
 - FORTRAN source files
   -----------------------
@@ -1066,9 +1075,14 @@
   * ${pkg}_check.F        checks package dependencies and consistencies
   * ${pkg}_init_varia.F   initialises package-related fields
   * ${pkg}_... .F         package source code
-  * ${pkg}_diags.F        write diagnostics to file.
+  * ${pkg}_diags.F        write output to file.
+   or ${pkg}_output.F     write output to file.
   * ${pkg}_write_pickup.F write a package pickup file to restart the model
 
+  New: Subroutine in one package (pkgA) that only contains code which 
+       is connected to a 2nd package (pkgB) (e.g.: gmredi_diagnostics_init.F)
+       will be named: pkgA_pkgB_something.F
+
 - parameter file
   -----------------------
   * data.${pkg}          parameter file