[release/v1] Fourth major update in v1 branch: Rename long_name --> description, expand list of abbreviations, update descriptions

.github/workflows/pull_request_ci.yml

@@ -19,8 +19,10 @@ jobs:
             sudo apt-get update
             sudo apt-get -y install libxml2-utils
 
-      - name: Check for duplicate standard names
-        run: tools/check_xml_unique.py standard_names.xml
+      - name: Check for duplicate standard names, descriptions
+        run: |
+            tools/check_xml_unique.py standard_names.xml
+            tools/check_xml_unique.py standard_names.xml --field="description"
 
   check-name-rules:
     name: Check standard names against rules

StandardNamesRules.rst

@@ -64,7 +64,7 @@ ESM Standard Name Rules
    In the latter example, ``ln`` is operating on the quantity ``water_vapor_partial_pressure_assuming_saturation``,
    while ``derivative_of`` is a combined transformation of ``water_vapor_partial_pressure_assuming_saturation``
    and ``air_temperature``. When multiple transformations are present, a more detailed description
-   should be provided in the ``long_name`` field to prevent any possible ambiguity.
+   should be provided in the ``description`` field to prevent any possible ambiguity.
 
 #. Variables are current and instantaneous unless specified. Variables that are not
    current (e.g., previous timestep) or non-instantaneous (e.g., accumulated values)
@@ -94,7 +94,7 @@ ESM Standard Name Rules
    ``[variable]_at_top_interfaces`` is defined on `n` points, and
    ``[variable]_at_bottom_interfaces`` is defined on `n` points.
 
-#. By default, *mixing_ratio* refers to mass mixing ratios. The long name should
+#. By default, *mixing_ratio* refers to mass mixing ratios. The description should
    explicitly specify that it refers to the *mass* mixing ratio.
    Mass mixing ratios should contain information regarding
    with respect to what quantity they are defined, and options are *wrt_dry_air*,
@@ -146,7 +146,7 @@ ESM Standard Name Rules
 #. Spell out acronyms unless they are obvious to a vast majority of
    scientists/developers who may come across them. A list of currently-used
    aliases is below. Whenever such an alias exist, use the alias in the
-   standard name and the full term in the long name.
+   standard name and the full term in the description.
 
 #. For control-oriented variables, if the variable is a Fortran logical,
    use flag_for ``_X``. If it is any other data type, use control_for ``_X``. All flags
@@ -165,23 +165,27 @@ Technical specifications
 ========================
 
 #. The standard name dictionary consists of a number of individual XML elements:
-   one "standard_name" element for each entry. A standard name entry consist of a "name" attribute
-   that represents the variable name, and (optionally) a "long_name" attribute that gives
-   a detailed description of what that name represents. The standard_name XML entry also contains a nested
-   "type" entry, indicating the data type that a standard_name should represent, and as attributes the
+   one ``standard_name`` element for each entry. A standard name entry consist of a ``name`` attribute
+   that represents the variable name, and (optionally) a ``description`` attribute that gives
+   a detailed description of what that name represents. Note that the ``description`` field is only
+   provided for information and disambiguation only (though it should be unique), and does not need to be included for
+   individual implementations of the standard names. It is not the same as ``long_name`` entries
+   used in CCPP and other standards, but it can be used to inform the contents of that field. The
+   ``standard_name`` XML entry also contains a nested
+   ``type`` entry, indicating the data type that a ``standard_name`` should represent, and as attributes the
    physical units of that variable quantity (see the `section on Units <#units>`_) and the FORTRAN "kind"
    of the variable quantity. For example, the element
    for the variable name ``exner_function`` may look similar to this:
 
     <standard_name name="exner_function"
-                   long_name="exner function, (p/p0)^(Rd/cp), where p0 is 1000 hPa">
+                   description="exner function, (p/p0)^(Rd/cp), where p0 is 1000 hPa">
       <type kind="kind_phys" units="1">real</type>
     </standard_name>
 
-   This XML element indicates that the variable ``exner_function`` represents the quantity described by the ``long_name``
+   This XML element indicates that the variable ``exner_function`` represents the quantity described by the ``description``
    attribute. It is a real variable of "kind_phys" kind, and units of "1", meaning it is non-dimensional and
    does not correspond to a more descriptive non-dimensional type such as "fraction"; see the `section on Units <#units>`_
-   for more details
+   for more details.
 
    These standard_name elements can optionally be separated by "section" elements. These are parsed out into human-readable sections in the generated markdown file (``Metadata-standard-names.md``).
 
@@ -628,10 +632,16 @@ Acronyms, Abbreviations, and Aliases
 +---------------------+---------------------------------------------------------+
 | **Short**           |  **Meaning**                                            |
 +=====================+=========================================================+
+| cnvc90              | GFS Convective Cloud Diagnostics                        |
++---------------------+---------------------------------------------------------+
 | edmf                | eddy-diffusivity/mass-flux                              |
 +---------------------+---------------------------------------------------------+
 | gwd                 | gravity wave drag                                       |
 +---------------------+---------------------------------------------------------+
+| gfdl                | Geophysical Fluid Dynamics Laboratory                   |
++---------------------+---------------------------------------------------------+
+| gfs                 | Global Forecast System                                  |
++---------------------+---------------------------------------------------------+
 | ir                  | infrared                                                |
 +---------------------+---------------------------------------------------------+
 | lwe                 | liquid water equivalent                                 |
@@ -646,10 +656,14 @@ Acronyms, Abbreviations, and Aliases
 +---------------------+---------------------------------------------------------+
 | nir                 | near-infrared part of the EM spectrum (radiation)       |
 +---------------------+---------------------------------------------------------+
+| nsstm               | GFS near-surface sea temperature scheme                 |
++---------------------+---------------------------------------------------------+
 | pbl                 | planetary boundary layer                                |
 +---------------------+---------------------------------------------------------+
 | pdf                 | probability density function                            |
 +---------------------+---------------------------------------------------------+
+| sas                 | simplified Arakawa-Schubert scheme                      |
++---------------------+---------------------------------------------------------+
 | skeb                | stochastic kinetic energy backscatter                   |
 +---------------------+---------------------------------------------------------+
 | shoc                | simplified higher-order closure stochastic scheme       |
@@ -664,6 +678,8 @@ Acronyms, Abbreviations, and Aliases
 +---------------------+---------------------------------------------------------+
 | toa                 | top of atmosphere                                       |
 +---------------------+---------------------------------------------------------+
+| ugwp                | Unified Gravity Wave Physics                            |
++---------------------+---------------------------------------------------------+
 | uv                  | ultraviolet part of the EM spectrum (radiation)         |
 +---------------------+---------------------------------------------------------+
 | vis                 | visible part of the EM spectrum (radiation)             |