Add Chapter 9 and make formatting consistent (#200)

Add new version of Listing 6.3 and make formatting consistent in Chapter 6
Add reference to Chapter 9 from Chapter 3
Clean up README file

Build of html and pdf files successful.

doc/CCPPtechnical/README

@@ -1,20 +1,4 @@
-Steps to build and use the Sphinx documentation tool:
-
-1) Get Sphinx and sphinxcontrib-bibtex installed on your desktop from
-    http://www.sphinx-doc.org/en/master/usage/installation.html
-    https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#installation
-
-2) Create a Sphinx documentation root directory:
-   % mkdir docs
-   % cd docs
-
-3) Initialize your Sphinx project (set up an initial directory structure) using
-   % sphinx-quickstart
-
-   See http://www.sphinx-doc.org/en/master/usage/quickstart.html or
-       https://sphinx-rtd-tutorial.readthedocs.io/en/latest/sphinx-quickstart.html
-
-    for help.  You can answer (ENTER) to most of the questions.
+Steps to build the CCPP Technical Documentation:
 
 To build html:
 

doc/CCPPtechnical/source/AddingNewSchemes.rst

@@ -6,11 +6,13 @@ Tips for Adding a New Scheme
 
 This chapter contains a brief description on how to add a new scheme to the *CCPP-Physics* pool.
 
-* Identify the variables required for the new scheme and check if they are already available for use in the CCPP by checking the metadata tables in ``GFS_typedefs.F90`` or by perusing file ``ccpp-framework/doc/DevelopersGuide/CCPP_VARIABLES_XYZ.pdf`` generated by ``ccpp_prebuild.py``.
+* Identify the variables required for the new scheme and check if they are already available for use in the CCPP by checking the metadata tables in ``GFS_typedefs.F90`` or by perusing file ``ccpp-framework/doc/DevelopersGuide/CCPP_VARIABLES_{FV3,SCM}.pdf`` generated by ``ccpp_prebuild.py``.
 
     * If the variables are already available, they can be invoked in the scheme’s metadata table and one can skip the rest of this subsection. If the variable required is not available, consider if it can be calculated from the existing variables in the CCPP. If so, an interstitial scheme (such as ``scheme_pre``; see more in :numref:`Chapter %s <CompliantPhysParams>`) can be created to calculate the variable. However, the variable must be defined but not initialized in the host model as the memory for this variable must be allocated on the host model side.  Instructions for how to add variables to the host model side is described in :numref:`Chapter %s <Host-side Coding>`.
 
-    * It is important to note that not all data types are persistent in memory. The interstitial data type is erased every time step and does not persist from one set to another or from one group to another. The diagnostic data type is periodically erased because it is used to accumulate variables for given time intervals.
+    * It is important to note that not all data types are persistent in memory. Most variables in the interstitial data type are reset (to zero or other initial values) at the beginning of a physics group and do not persist from one set to another or from one group to another. The diagnostic data type is periodically reset because it is used to accumulate variables for given time intervals.  However, there is a small subset of interstitial variables that are set at creation time and are not reset; these are typically dimensions used in other interstitial variables. 
+
+     .. note:: If the value of a variable must be remembered from one call to the next, it should not be in the interstitial or diagnostic data types.
 
     * If information from the previous timestep is needed, it is important to identify if the host model readily provides this information. For example, in the Model for Prediction Across Scales (MPAS), variables containing the values of several quantities in the preceding timesteps are available. When that is not the case, as in the UFS Atmosphere, interstitial schemes are needed to compute these variables. As an example, the reader is referred to the GF convective scheme, which makes use of interstitials to obtain the previous timestep information.
 
@@ -23,7 +25,8 @@ This chapter contains a brief description on how to add a new scheme to the *CCP
     * ``NEMSfv3gfs/ccpp/config/ccpp_prebuild_config.py`` for the UFS Atmosphere
     * ``gmtb-scm/ccpp/config/ccpp_prebuild_config.py`` for the SCM
 
-* Add the new scheme to the list of schemes in ``ccpp_prebuild_config.py`` using the same path as the existing schemes:
+* Add the new scheme to the Python dictionary in ``ccpp_prebuild_config.py`` using the same path
+  as the existing schemes:
 
   .. code-block:: console
 
@@ -52,15 +55,15 @@ This chapter contains a brief description on how to add a new scheme to the *CCP
     * ``NEMSfv3gfs/ccpp/suites`` for the UFS Atmosphere
     * ``gmtb-scm/ccpp/suites`` for the SCM
 
-* Before running, check for consistency between the namelist and the SDF. There is no default consistency check between the SDF and the namelist unless the developer adds one. Errors may result in segment faults in running something you did not intend to run if the arrays are not allocated.
+* Before running, check for consistency between the namelist and the SDF. There is no default consistency check between the SDF and the namelist unless the developer adds one. Errors may result in segmentation faults in running something you did not intend to run if the arrays are not allocated.
 
 * Test and debug the new scheme:
 
     * Typical problems include segment faults related to variables and array allocation.
     * Make sure SDF and namelist are compatible. Inconsistencies may result in segmentation faults because arrays are not allocated or in unintended scheme(s) being executed.
     * A scheme called GFS_debug (``GFS_debug.F90``) may be added to the SDF where needed to print state variables and interstitial variables. If needed, edit the scheme beforehand to add new variables that need to be printed.
-    * Check *prebuild* script.
-    * Compile code in DEBUG mode, run through debugger if necessary (gdb, Allinea DDT, totalview, ...).
+    * Check *prebuild* script for success/failure and associated messages.
+    * Compile code in DEBUG mode, run through debugger if necessary (gdb, Allinea DDT, totalview, ...).  See :numref:`Chapter %s <BuildingRunningHostModels>` for information on debugging.
     * Use memory check utilities such as valgrind.
     * Double-check the metadata table in your scheme to make sure that the standard names correspond to the correct local variables.
 

doc/CCPPtechnical/source/AutoGenPhysCaps.rst

@@ -15,7 +15,7 @@ while the host model *caps* are described in :numref:`Chapter %s <Host-side Codi
 which can be used with the SCM and with the UFS Atmosphere, produces individual 
 physics scheme *caps*, while the static build (for UFS Atmosphere only) produces group 
 and suite *caps*. The physics *caps* autogenerated by ``ccpp_prebuild.py`` reside in the directory 
-defined by the ``CAPS_DIR`` variable.
+defined by the ``CAPS_DIR`` variable (see example in :ref:`Listing 8.1 <ccpp_prebuild_example>`).
 
 .. _DynamicBuildCaps: