Merge pull request #2225 from samsrabin/docs-user-guide-links

Fix placeholder links in User's Guide

doc/source/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.rst

@@ -336,7 +336,7 @@ where If :math:`{NF}_{total\_demand,j}`\ :math:`\Delta`\ *t* :math:`<` :math:`{N
 
 where :math:`{f}_{immob\_demand,j}` is the fraction of potential immobilization demand that can be met given current supply of mineral nitrogen in this layer. We also set the actual nitrification flux to be the same as the potential flux (:math:`NF_{nit}` = :math:`NF_{nit\_ demand}`).
 
-If :math:`{NF}_{total\_demand,j}`\ :math:`\Delta`\ *t :math:`\mathrm{\ge}` :math:`{NS}_{sminn,j}`, then there is not enough mineral nitrogen to meet the combined demands for plant growth and heterotrophic immobilization, immobilization is reduced proportional to the discrepancy, by :math:`f_{immob\_ demand,j}`, where
+If :math:`{NF}_{total\_demand,j} \Delta t \mathrm{\ge} {NS}_{sminn,j}`, then there is not enough mineral nitrogen to meet the combined demands for plant growth and heterotrophic immobilization, immobilization is reduced proportional to the discrepancy, by :math:`f_{immob\_ demand,j}`, where
 
 .. math::
    :label: 21.30)

doc/source/tech_note/Photosynthesis/CLM50_Tech_Note_Photosynthesis.rst

@@ -253,7 +253,7 @@ The effect is to cause the temperature optimum of :math:`V_{c\max }` and :math:`
 
    J_{\max 25} /V_{c\max 25} =2.59-0.035(T_{10} -T_{f} ).
 
-In these acclimation functions, :math:`T_{10}` is the 10-day mean air temperature (K) and :math:`T_{f}` is the freezing point of water (K). For lack of data, :math:`T_{p}` acclimates similar to :math:`V_{c\max }`. Acclimation is restricted over the temperature range :math:`T_{10} -T_{f} \ge 11`°C and :math:`T_{10} -T_{f} \le 35`°C.
+In these acclimation functions, :math:`T_{10}` is the 10-day mean air temperature (K) and :math:`T_{f}` is the freezing point of water (K). For lack of data, :math:`T_{p}` acclimates similar to :math:`V_{c\max }`. Acclimation is restricted over the temperature range :math:`T_{10} -T_{f} \ge` 11°C and :math:`T_{10} -T_{f} \le` 35°C.
 
 .. _Canopy scaling:
 

doc/source/tech_note/Surface_Albedos/CLM50_Tech_Note_Surface_Albedos.rst

@@ -530,7 +530,7 @@ For each constituent (ice, two black carbon species, two organic carbon species,
 
    \tau _{k} =\psi _{k} w_{k}
 
-The two-stream solution (:ref:`Toon et al. (1989) <Toonetal1989>`) applies a tri-diagonal matrix solution to produce upward and downward radiative fluxes at each layer interface, from which net radiation, layer absorption, and surface albedo are easily derived. Solar fluxes are computed in five spectral bands, listed in :numref:`Table Spectral bands and weights used for snow radiative transfer`. Because snow albedo varies strongly across the solar spectrum, it was determined that four bands were needed to accurately represent the near-infrared (NIR) characteristics of snow, whereas only one band was needed for the visible spectrum. Boundaries of the NIR bands were selected to capture broad radiative features and maximize accuracy and computational efficiency. We partition NIR (0.7-5.0 :math:`\mu` m) surface downwelling flux from CLM according to the weights listed in :numref:`Table Spectral bands and weights used for snow radiative transfer`, which are unique for diffuse and direct incident flux. These fixed weights were determined with offline hyperspectral radiative transfer calculations for an atmosphere typical of mid-latitude winter (:ref:`Flanner et al. (2007) <Flanneretal2007>`). The tri-diagonal solution includes intermediate terms that allow for easy interchange of two-stream techniques. We apply the Eddington solution for the visible band (following :ref:`Wiscombe and Warren 1980 <WiscombeWarren1980>`) and the hemispheric mean solution ((:ref:`Toon et al. (1989) <Toonetal1989>`) for NIR bands. These choices were made because the Eddington scheme works well for highly scattering media, but can produce negative albedo for absorptive NIR bands with diffuse incident flux. Delta scalings are applied to :math:`\tau`, :math:`\omega`, and :math:`g` (:ref:`Wiscombe and Warren 1980 <WiscombeWarren1980>`) in all spectral bands, producing effective values (denoted with *) that are applied in the two-stream solution
+The two-stream solution (:ref:`Toon et al. (1989) <Toonetal1989>`) applies a tri-diagonal matrix solution to produce upward and downward radiative fluxes at each layer interface, from which net radiation, layer absorption, and surface albedo are easily derived. Solar fluxes are computed in five spectral bands, listed in :numref:`Table Spectral bands and weights used for snow radiative transfer`. Because snow albedo varies strongly across the solar spectrum, it was determined that four bands were needed to accurately represent the near-infrared (NIR) characteristics of snow, whereas only one band was needed for the visible spectrum. Boundaries of the NIR bands were selected to capture broad radiative features and maximize accuracy and computational efficiency. We partition NIR (0.7-5.0 :math:`\mu` m) surface downwelling flux from CLM according to the weights listed in :numref:`Table Spectral bands and weights used for snow radiative transfer`, which are unique for diffuse and direct incident flux. These fixed weights were determined with offline hyperspectral radiative transfer calculations for an atmosphere typical of mid-latitude winter (:ref:`Flanner et al. (2007) <Flanneretal2007>`). The tri-diagonal solution includes intermediate terms that allow for easy interchange of two-stream techniques. We apply the Eddington solution for the visible band (following :ref:`Wiscombe and Warren 1980 <WiscombeWarren1980>`) and the hemispheric mean solution ((:ref:`Toon et al. (1989) <Toonetal1989>`) for NIR bands. These choices were made because the Eddington scheme works well for highly scattering media, but can produce negative albedo for absorptive NIR bands with diffuse incident flux. Delta scalings are applied to :math:`\tau`, :math:`\omega`, and :math:`g` (:ref:`Wiscombe and Warren 1980 <WiscombeWarren1980>`) in all spectral bands, producing effective values (denoted with :math:`*`) that are applied in the two-stream solution
 
 .. math::
    :label: 3.66

doc/source/users_guide/adding-new-resolutions/Adding-New-Resolutions-or-New-Files-to-the-build-namelist-Database.rst

@@ -1,7 +1,7 @@
-.. _adding-resolutions:
-
 .. include:: ../substitutions.rst
 
+.. _adding-resolutions:
+
 ========================
  Adding New Resolutions
 ========================

doc/source/users_guide/adding-new-resolutions/Adding-Resolution-Names.rst

@@ -1,7 +1,7 @@
-.. _adding-resolution-names:
-
 .. include:: ../substitutions.rst
 
+.. _adding-resolution-names:
+
 =========================
  Adding Resolution Names
 =========================

doc/source/users_guide/adding-new-resolutions/Adding-or-Changing-Default-Filenames.rst

@@ -1,7 +1,7 @@
-.. _changing-default-filenames:
-
 .. include:: ../substitutions.rst
 
+.. _changing-default-filenames:
+
 ============================
  Changing Default Filenames
 ============================
@@ -26,6 +26,8 @@ Different types of simulations and different types of configurations for CLM req
 
 In the following table we list the different files used by CLM, they are listed in order of importance, dependencies, and customizing. So the required files are all near the top, and the files used only under different conditions are listed later, and files with the fewest dependencies are near the top, as are the files that are least likely to be customized.
 
+.. _reqd-files-table:
+
 Table 3-1. Required Files for Different Configurations and Simulation Types
 ---------------------------------------------------------------------------
 Insert table 3-1

doc/source/users_guide/adding-new-resolutions/index.rst

@@ -3,10 +3,10 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. _adding-new-resolutions-section:
-
 .. include:: ../substitutions.rst
 
+.. _adding-new-resolutions-section:
+
 #####################################
 Adding New Resolutions
 #####################################

doc/source/users_guide/overview/getting-help.rst

@@ -1,7 +1,7 @@
-.. _getting-help:
-
 .. include:: ../substitutions.rst
 
+.. _getting-help:
+
 ==============
  Getting Help
 ==============
@@ -35,29 +35,31 @@ There is a rich and diverse set of people that use the CESM, and often it is use
 The CLM web pages
 -----------------
 
-The main CLM web page contains information on the CLM, it's history, developers, as well as downloads for previous model versions. There are also documentation text files in the $CTSMROOT/doc directory that give some quick information on using CLM.
+The main `CLM web page <http://www.cgd.ucar.edu/tss/clm/>`_ contains information on the CLM, its history, developers, as well as downloads for previous model versions. Some other links are available at the `CESM2 land component webpage <http://www.cesm.ucar.edu/models/cesm2/land>`. There are also documentation text files in the `$CTSMROOT/doc directory <https://github.com/ESCOMP/CTSM/tree/master/doc>`_ that give some quick information on using CLM.
 
-`CLM web page <http://www.cgd.ucar.edu/tss/clm/>`_
-`|cesmrelease| |version| web page <http://www.cesm.ucar.edu/models/cesm2/land/>`_
-`CLM Documentation Text Files <CLM-URL>`_
+Also note that several of the XML database files can help with namelist options, namelist defaults, or compsets. For the most recent release:
 
-Also note that several of the XML database files can be viewed in a web browser to get a nice table of namelist options, namelist defaults, or compsets. Simply view them as a local file and bring up one of the following files:
+- `$CTSMROOT/bld/namelist_files/namelist_definition_ctsm.xml <https://github.com/ESCOMP/CTSM/blob/master/bld/namelist_files/namelist_definition_ctsm.xml>`_ -- definition of latest CTSM namelist items.
+- `$CTSMROOT/bld/namelist_files/namelist_defaults_ctsm.xml <https://github.com/ESCOMP/CTSM/blob/master/bld/namelist_files/namelist_defaults_ctsm.xml>`_ -- default values for latest CTSM namelist items.
+- `$CTSMROOT/cime_config/config_component.xml <https://github.com/ESCOMP/CTSM/blob/master/cime_config/config_component.xml>`_ -- definition of all the CLM specific XML variables.
+- `$CTSMROOT/cime_config/config_compsets.xml <https://github.com/ESCOMP/CTSM/blob/master/cime_config/config_compsets.xml>`_ -- definition of all the CLM compsets.
+
+Some archives are available for previous versions:
+
+- `Archive of namelist_definition_clm4_0.xml <https://github.com/ESCOMP/CTSM/blob/clm5.0.000/bld/namelist_files/namelist_definition_clm4_0.xml>`_ -- definition of CLM4.0 namelist items.
+- `Archive of namelist_definition_clm4_5.xml <https://github.com/ESCOMP/CTSM/blob/clm5.0.000/bld/namelist_files/namelist_definition_clm4_5.xml>`_ -- definition of CLM4.5/CLM5.0 namelist items.
+- `Archive of namelist_defaults_clm4_0.xml <https://github.com/ESCOMP/CTSM/blob/clm5.0.000/bld/namelist_files/namelist_defaults_clm4_0.xml>`_ -- default values for CLM4.0 namelist items.
+- `Archive of namelist_defaults_clm4_5.xml <https://github.com/ESCOMP/CTSM/blob/clm5.0.000/bld/namelist_files/namelist_defaults_clm4_5.xml>`_ -- default values for CLM4.5/CLM5.0 namelist items.
 
-- `$CTSMROOT/bld/namelist_files/namelist_definition_clm4_0.xml <CLM-URL>`_ -- definition of CLM4.0 namelist items.
-- `$CTSMROOT/bld/namelist_files/namelist_definition_clm4_5.xml <CLM-URL>`_ -- definition of CLM4.5/CLM5.0 namelist items.
-- `$CTSMROOT/bld/namelist_files/namelist_defaults_clm4_0.xml <CLM-URL>`_ -- default values for CLM4.0 namelist items.
-- `$CTSMROOT/bld/namelist_files/namelist_defaults_clm4_5.xml <CLM-URL>`_ -- default values for CLM4.5/CLM5.0 namelist items.
-- `$CTSMROOT/cime_config/config_component.xml <CLM-URL>`_ -- definition of all the CLM specific XML variables.
-- `$CTSMROOT/cime_config/config_compsets.xml <CLM-URL>`_ -- definition of all the CLM compsets.
-- `$CTSMROOT/bld/namelist_files/history_fields_clm4_0.xml <CLM-URL>`_ -- definition of CLM4.0 history fields.
-- `$CTSMROOT/bld/namelist_files/history_fields_clm4_5.xml <CLM-URL>`_ -- definition of CLM4.5/CLM5.0 history fields.
 
 ----------------------------
 Reporting bugs in |version|
 ----------------------------
 
 If you have any problems, additional questions, bug reports, or any other feedback, please report it as an issue on GitHub https://github.com/ESCOMP/ctsm/issues or for CIME scripts and infrastructure to https://github.com/ESMCI/CIME/issues. Or send an email to <`[email protected] <[email protected]>`_> or <`[email protected] <[email protected]>`_>. If you find bad, wrong, or misleading information in this users guide report it as an issue on CTSM.
 
+.. _acronyms-and-terms:
+
 ---------------------------------------
 Some Acronym's and Terms We'll be Using
 ---------------------------------------

doc/source/users_guide/overview/index.rst

@@ -3,10 +3,10 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. _overview_section:
-
 .. include:: ../substitutions.rst
 
+.. _overview_section:
+
 #####################################
 Overview
 #####################################