From b731a18ca507d3080a7304193860b8724d84cb9e Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Mon, 21 Sep 2026 15:56:31 -0600
Subject: [PATCH 01/21] Update rules per discussion on #150

---
 StandardNamesRules.rst | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/StandardNamesRules.rst b/StandardNamesRules.rst
index 44e8d66..5f3d596 100644
--- a/StandardNamesRules.rst
+++ b/StandardNamesRules.rst
@@ -139,6 +139,21 @@ Variable scope
 Terminology
 -----------
 
+   `annotated image detailing some of the terminology in this section <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_terms.png>`_
+
+#. A "layer" is a vertical level of a model, as defined by the host. An "interface" is the boundary above or below a layer.
+
+#. By default, *surface* refers to the liquid or solid substance immediately beneath the atmosphere
+   for a given vertical column. This can be land, ocean, ice, lake, etc.
+
+   For "surface" variables describing properties of the atmosphere, near/adjacent to the actual surface,
+   care should be taken to specify the specific "surface variable" quantity needed for a specific application:
+
+   *  ``[variable]_at_boa`` ("bottom of atmosphere") is the lowest point of the atmosphere, adjacent to the surface.
+      This is equivalent to the bottom interface (as described above).
+   *  ``[variable]_at_surface_adjacent_layer`` is the bottom layer of the atmospheric model
+   *  ``[variable]_at_[level]`` for variables defined at specific height above the surface, e.g. ``temperature_at_2m``, ``wind_at_10m``
+
 #. 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
@@ -178,9 +193,8 @@ Terminology
    of clouds the variable represents (e.g. *ice_cloud* if only including glaciated clouds, or
    *cloud_at_500hPa* if only including clouds that exist at 500 hPa).
 
-#. 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
+#. Spell out acronyms unless they are defined in the list of "Acronyms, Abbreviations, and Aliases"
+   below. Whenever such an alias exist, use the alias in the
    standard name and the full term in the description.
 
 #. Chemical species in standard names should be denoted by chemical formulae (e.g. ``co2``,
@@ -292,7 +306,8 @@ Prefixes
 None. Note that this is a departure from the CF conventions, which in
 many cases - but not all - use surface_ as a prefix. This departure from
 the CF convention is to maintain consistency with all other level
-qualifiers that are used as _at_level-qualifier (i.e. as suffix).
+qualifiers that are used as _at_level-qualifier (i.e. as suffix), as well as
+reducing ambiguity between different uses of the word "surface" (see above).
 
 Suffixes
 ^^^^^^^^
@@ -311,6 +326,7 @@ Suffixes
 | at_top_of_atmosphere_model
 | at_top_of_dry_convection
 | at_interfaces
+| at_boa
 | at_toa
 | at_tropopause
 | at_surface
@@ -578,6 +594,8 @@ Special phrases
 +------------------------+-------------------------------------------------------------------------------------+
 | specific               | per unit mass unless otherwise stated                                               |
 +------------------------+-------------------------------------------------------------------------------------+
+| surface                | The top of the solid or liquid medium below the bottom of the atmosphere            |
++------------------------+-------------------------------------------------------------------------------------+
 | unfrozen_water         | liquid and vapor                                                                    |
 +------------------------+-------------------------------------------------------------------------------------+
 | water                  | water in all phases if not otherwise qualified                                      |
@@ -599,6 +617,8 @@ Acronyms, Abbreviations, and Aliases
 +---------------------+---------------------------------------------------------+
 | **Short**           |  **Meaning**                                            |
 +=====================+=========================================================+
+| boa                 | bottom of atmosphere (atmosphere interface with surface)|
++---------------------+---------------------------------------------------------+
 | cnvc90              | GFS Convective Cloud Diagnostics                        |
 +---------------------+---------------------------------------------------------+
 | edmf                | eddy-diffusivity/mass-flux                              |

From 2a1cdb74c0efa9d746cf936e6fc0f952742e07af Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Mon, 21 Sep 2026 16:58:27 -0600
Subject: [PATCH 02/21] Starting update of "surface" variables; give a more
 detailed "surface_skin_temperature" definition, and return proper skin
 temperature naming accordingly

---
 standard_names.xml | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/standard_names.xml b/standard_names.xml
index 92723cc..5027df8 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -21,7 +21,7 @@
       <standard_name name="energy">
         <type units="J">real</type>
       </standard_name>
-      <standard_name name="energy_content" description="Total energy within some surface">
+      <standard_name name="energy_content" description="Total energy within some ideal surface">
         <type units="J m-2">real</type>
       </standard_name>
       <standard_name name="energy_density" description="Total energy within some volume">
@@ -196,7 +196,7 @@
         <cfname>air_temperature</cfname>
         <type units="K">real</type>
       </standard_name>
-      <standard_name name="albedo" description="The fraction of incident radiation reflected by a surface">
+      <standard_name name="albedo" description="The fraction of incident radiation reflected by a physical surface">
         <type units="1">real</type>
       </standard_name>
       <standard_name name="atmosphere_heat_diffusivity">
@@ -228,7 +228,7 @@
       <standard_name name="diffuse_vis_albedo" description="Albedo of diffuse incident visible radiation">
         <type units="1">real</type>
       </standard_name>
-      <standard_name name="dimensionless_exner_function" description="Dimensionless formulation of the Exner function with respect to 1000 hPa" comment="The formulation of the exner function in an NWP context is (p/p0)^(Rd/cp), where p0 is some reference pressure. For the purposes of the standard names, this reference pressure is assumed as 1000 hPa unless specified otherwise; i.e. dimensionless_exner_function_wrt_air_pressure_at_surface would use the pressure at the surface as P0. Note that this is numerically equivalent to T/theta (temperature divided by potential temperature), where again theta is calculated with respect to 1000 hPa if not specified. Note that this definition is distinct from the dimensional exner_function standard name; see that entry for further comments. ">
+      <standard_name name="dimensionless_exner_function" description="Dimensionless formulation of the Exner function with respect to 1000 hPa" comment="The formulation of the exner function in an NWP context is (p/p0)^(Rd/cp), where p0 is some reference pressure. For the purposes of the standard names, this reference pressure is assumed as 1000 hPa unless specified otherwise; i.e. dimensionless_exner_function_wrt_air_pressure_at_boa would use the pressure at the surface (bottom of atmosphere) as P0. Note that this is numerically equivalent to T/theta (temperature divided by potential temperature), where again theta is calculated with respect to 1000 hPa if not specified. Note that this definition is distinct from the dimensional exner_function standard name; see that entry for further comments. ">
         <cfname>dimensionless_exner_function</cfname>
         <type units="1">real</type>
       </standard_name>
@@ -338,7 +338,7 @@
         <cfname>solar_zenith_angle</cfname>
         <type units="degrees">real</type>
       </standard_name>
-      <standard_name name="surface_skin_temperature" description="The temperature of the topmost layer of the surface">
+      <standard_name name="surface_skin_temperature" description="The temperature of the interface of the surface and the atmosphere" comment="Usage of the term 'surface skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'surface_skin_temperature': the temperature of the interface of the atmosphere and the surface below. This may be considered equivalent to the radiometric temperature derived from satellite or airborne radiometers, provided a known surface_emissivity. This definition derives from discussion in Chapter 4 of 'Introduction to Micrometeorology' by S. Pal Arya.">
         <cfname>surface_skin_temperature</cfname>
         <type units="K">real</type>
       </standard_name>
@@ -3481,16 +3481,16 @@
       <cfname>sea_ice_thickness</cfname>
       <type units="m">real</type>
     </standard_name>
-    <standard_name name="skin_temperature_at_surface_over_ice" description="Skin temperature at surface over (or where) ice">
+    <standard_name name="surface_skin_temperature_over_ice" description="Surface skin temperature over (or where) ice">
       <type units="K">real</type>
     </standard_name>
-    <standard_name name="skin_temperature_at_surface_over_land" description="Skin temperature at surface over (or where) land">
+    <standard_name name="surface_skin_temperature_over_land" description="Surface skin temperature over (or where) land">
       <type units="K">real</type>
     </standard_name>
-    <standard_name name="skin_temperature_at_surface_over_ocean" description="Skin temperature at surface over (or where) ocean">
+    <standard_name name="surface_skin_temperature_over_ocean" description="Surface skin temperatura over (or where) ocean">
       <type units="K">real</type>
     </standard_name>
-    <standard_name name="skin_temperature_at_surface_over_snow" description="Skin temperature at surface over (or where) snow">
+    <standard_name name="surface_skin_temperature_over_snow" description="Surface skin temperature over (or where) snow">
       <type units="K">real</type>
     </standard_name>
     <standard_name name="slow_soil_pool_mass_content_of_carbon">
@@ -3868,4 +3868,4 @@
       <type units="various">real</type>
     </standard_name>
   </section>
-</standard_names>
\ No newline at end of file
+</standard_names>

From 8be6a3b49f9a707c4a3c428c1f53573eee7c026c Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Mon, 21 Sep 2026 18:50:32 -0600
Subject: [PATCH 03/21] Converting atmospheric references to 'at_surface' to
 'at_boa'. We'll see if this sticks...

---
 standard_names.xml | 76 +++++++++++++++++++++++-----------------------
 1 file changed, 38 insertions(+), 38 deletions(-)

diff --git a/standard_names.xml b/standard_names.xml
index 5027df8..fffec74 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -568,7 +568,7 @@
       <cfname>air_pressure_at_mean_sea_level</cfname>
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="air_pressure_at_surface" description="Air pressure at local surface">
+    <standard_name name="air_pressure_at_boa" description="Air pressure at bottom of atmosphere; i.e. surface pressure">
       <cfname>surface_air_pressure</cfname>
       <type units="Pa">real</type>
     </standard_name>
@@ -655,7 +655,7 @@
     <standard_name name="dimensionless_exner_function_at_surface_adjacent_layer" description="Dimensionless exner function (p/p0)^(Rd/cp), where p0 is 1000 hPa and p is the pressure at the surface-adjacent layer">
       <type units="1">real</type>
     </standard_name>
-    <standard_name name="dimensionless_exner_function_wrt_surface_pressure" description="Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp)">
+    <standard_name name="dimensionless_exner_function_wrt_pressure_at_boa" description="Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp)">
       <type units="1">real</type>
     </standard_name>
     <standard_name name="dry_static_energy" description="Dry static energy content of atmosphere layer">
@@ -785,16 +785,16 @@
     <standard_name name="reciprocal_of_air_pressure_thickness_of_dry_air">
       <type units="Pa-1">real</type>
     </standard_name>
-    <standard_name name="reciprocal_of_dimensionless_exner_function_wrt_air_pressure_at_surface" description="inverse dimensionless exner function with respect to surface pressure; (ps/p)^(R/cp)">
+    <standard_name name="reciprocal_of_dimensionless_exner_function_wrt_air_pressure_at_boa" description="inverse dimensionless exner function with respect to air pressure at bottom of atmosphere (surface pressure); (ps/p)^(R/cp)">
       <type units="1">real</type>
     </standard_name>
-    <standard_name name="reference_air_pressure_normalized_by_air_pressure_at_surface" description="reference pressure normalized by surface pressure">
+    <standard_name name="reference_air_pressure_normalized_by_air_pressure_at_boa" description="reference pressure normalized by surface pressure">
       <type units="1">real</type>
     </standard_name>
     <standard_name name="reference_pressure_in_atmosphere_layer">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="reference_pressure_in_atmosphere_layer_normalized_by_surface_reference_pressure" description="Reference pressure in atmosphere layer normalized by surface reference pressure">
+    <standard_name name="reference_pressure_in_atmosphere_layer_normalized_by_reference_pressure_at_boa" description="Reference pressure in atmosphere layer normalized by reference pressure at bottom of atmosphere (surface reference pressure)">
       <type units="1">real</type>
     </standard_name>
     <standard_name name="relative_humidity_at_2m">
@@ -812,10 +812,10 @@
     <standard_name name="subgrid_scale_cloud_liquid_water_mixing_ratio_wrt_moist_air" description="Subgrid-scale cloud liquid water mass mixing ratio with respect to moist air">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="surface_pressure_of_dry_air">
+    <standard_name name="pressure_of_dry_air_at_boa" description="pressure of dry air at bottom of atmosphere (surface pressure)">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="surface_reference_pressure" description="Reference pressure used in definition of some other quantity (e.g. potential temperature, Exner function, etc.)">
+    <standard_name name="reference_pressure_at_boa" description="Reference air pressure at bottom of atmosphere (surface) used in definition of some other quantity (e.g. potential temperature, Exner function, etc.)">
       <type units="Pa">real</type>
     </standard_name>
     <standard_name name="timestep_for_physics">
@@ -825,7 +825,7 @@
       <cfname>atmosphere_upward_absolute_vorticity</cfname>
       <type units="s-1">real</type>
     </standard_name>
-    <standard_name name="upward_heat_flux_in_air_at_surface">
+    <standard_name name="upward_heat_flux_in_air_at_boa" description="Upward heat flux in air at bottom of atmosphere (surface)">
       <cfname>surface_upward_heat_flux_in_air</cfname>
       <type units="W m-2">real</type>
     </standard_name>
@@ -859,7 +859,7 @@
     <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_on_previous_timestep_in_xyz_dimensioned_restart_array" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) on previous timestep in XYZ-dimensioned restart array">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps back">
+    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps before the current timestep">
       <type units="kg kg-1">real</type>
     </standard_name>
     <standard_name name="wind_from_direction_at_10m" description="Direction (clockwise from north) wind vector is pointing away from, at 10 meters above surface.">
@@ -1167,10 +1167,10 @@
       <standard_name name="aerosol_aware_multiplicative_rain_conversion_parameter_for_shallow_convection">
         <type units="1">real</type>
       </standard_name>
-      <standard_name name="cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_ice" description="Cloud condensed water mass mixing ratio with respect to moist air at surface over ice">
+      <standard_name name="cloud_condensed_water_mixing_ratio_wrt_moist_air_at_boa_over_ice" description="Cloud condensed water mass mixing ratio with respect to moist air at bottom of atmosphere (surface) over ice">
         <type units="kg kg-1">real</type>
       </standard_name>
-      <standard_name name="cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_land" description="Cloud condensed water mass mixing ratio with respect to moist air at surface over land">
+      <standard_name name="cloud_condensed_water_mixing_ratio_wrt_moist_air_at_boa_over_land" description="Cloud condensed water mass mixing ratio with respect to moist air at bottom of atmosophere (surface) over land">
         <type units="kg kg-1">real</type>
       </standard_name>
       <standard_name name="cloud_ice_mixing_ratio_wrt_dry_air" description="Ratio of the mass of cloud ice to the mass of dry air">
@@ -1916,7 +1916,7 @@
     <standard_name name="control_for_vegetation_dataset">
       <type units="1">integer</type>
     </standard_name>
-    <standard_name name="control_for_vertical_index_direction" description="control flag for direction of vertical index; 0 indicates index from toa to surface, 1 indicates index from surface to toa">
+    <standard_name name="control_for_vertical_index_direction" description="control flag for direction of vertical index; 0 indicates index from top of atmosphere to surface, 1 indicates index from surface to toa">
       <type units="1">integer</type>
     </standard_name>
     <standard_name name="do_aerosol_physics">
@@ -2389,10 +2389,10 @@
     <standard_name name="cumulative_min_vertical_index_at_cloud_base_between_sw_radiation_calls">
       <type units="1">real</type>
     </standard_name>
-    <standard_name name="index_of_air_pressure_at_surface_on_previous_timestep_in_xyz_dimensioned_restart_array">
+    <standard_name name="index_of_air_pressure_at_boa_on_previous_timestep_in_xyz_dimensioned_restart_array" description="Index of air pressure at bottom of atmosphere (surface pressure) on previous timestep in xyz-dimensioned restart array">
       <type units="index">integer</type>
     </standard_name>
-    <standard_name name="index_of_air_pressure_at_surface_two_timesteps_back_in_xyz_dimensioned_tracer_array">
+    <standard_name name="index_of_air_pressure_at_boa_two_timesteps_back_in_xyz_dimensioned_tracer_array" description="Index of air pressure at bottom of atmosphere (surface pressure) two timesteps before the current timestep in xyz-dimensioned tracer array">
       <type units="index">integer</type>
     </standard_name>
     <standard_name name="index_of_air_temperature_on_previous_timestep_in_xyz_dimensioned_restart_array">
@@ -2506,7 +2506,7 @@
     <standard_name name="index_of_water_vapor_mixing_ratio_wrt_moist_air_on_previous_timestep_in_xyz_dimensioned_restart_array" description="Index of specific humidity (water vapor mass mixing ratio with respect to moist air) on previous timestep in xyz dimensioned restart array">
       <type units="index">integer</type>
     </standard_name>
-    <standard_name name="index_of_water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back_in_xyz_dimensioned_restart_array" description="Index of specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps back in xyz dimensioned restart array">
+    <standard_name name="index_of_water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back_in_xyz_dimensioned_restart_array" description="Index of specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps before the current timestep in xyz dimensioned restart array">
       <type units="index">integer</type>
     </standard_name>
     <standard_name name="index_of_water_vegetation_category">
@@ -2619,7 +2619,7 @@
     <standard_name name="coefficient_w_d">
       <type units="1">real</type>
     </standard_name>
-    <standard_name name="critical_relative_humidity_at_surface">
+    <standard_name name="critical_relative_humidity_at_boa" description="Critical relative humidity at the bottom of the atmosphere (surface)">
       <type units="fraction">real</type>
     </standard_name>
     <standard_name name="critical_relative_humidity_at_toa" description="Critical relative humidity at the top of the atmosphere">
@@ -3090,7 +3090,7 @@
     <standard_name name="solar_constant">
       <type units="W m-2">real</type>
     </standard_name>
-    <standard_name name="surface_lw_fluxes_assuming_total_and_clear_sky_on_radiation_timestep">
+    <standard_name name="lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep" description="longwave total sky fluxes at surface, assuming clear sky, on radiation timestep">
       <type units="W m-2">ddt</type>
     </standard_name>
     <standard_name name="upwelling_diffuse_nir_shortwave_flux_at_surface_on_radiation_timestep" description="upwelling diffuse near-infrared shortwave flux at the surface level on the radiation timestep">
@@ -3113,13 +3113,13 @@
     </standard_name>
   </section>
   <section name="Atmospheric surface and boundary layer">
-    <standard_name name="air_pressure_at_surface_for_coupling">
+    <standard_name name="air_pressure_at_boa_for_coupling" description="air pressure at bottom of atmosphere (surface pressure) for coupling">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="air_pressure_at_surface_on_previous_timestep">
+    <standard_name name="air_pressure_at_boa_on_previous_timestep" description="air pressure at bottom of atmosphere (surface pressure) on previous timestep">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="air_pressure_at_surface_two_timesteps_back">
+    <standard_name name="air_pressure_at_boa_two_timesteps_back" description="air pressure at bottom of atmosphere (surface pressure) two timesteps before the current timestep">
       <type units="Pa">real</type>
     </standard_name>
     <standard_name name="critical_relative_humidity_at_top_of_atmosphere_boundary_layer">
@@ -3176,10 +3176,10 @@
     <standard_name name="updraft_area_fraction_in_scale_aware_tke_moist_edmf_pbl_scheme" description="Updraft area fraction in scale-aware turbulent kinetic energy moist eddy-diffusivity/mass-flux planetary boundary layer scheme">
       <type units="fraction">real</type>
     </standard_name>
-    <standard_name name="upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface" description="Upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface">
+    <standard_name name="upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_boa" description="Upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at bottom of atmosphere (surface)">
       <type units="kg kg-1 m s-1">real</type>
     </standard_name>
-    <standard_name name="upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_surface_layer_scheme" description="Upward flux of specific humidity (water vapor mass mixing ratio with respect to moist air) at surface for MYJ surface layer scheme">
+    <standard_name name="upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_boa_for_myj_surface_layer_scheme" description="Upward flux of specific humidity (water vapor mass mixing ratio with respect to moist air) at bottom of atmosphere (surface) for MYJ surface layer scheme">
       <type units="m s-1 kg kg-1">real</type>
     </standard_name>
     <standard_name name="upward_latent_heat_flux_at_surface_for_coupling">
@@ -3206,19 +3206,19 @@
     <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_2m_for_coupling" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at 2 meters above surface used for coupling">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_surface" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface">
+    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_boa" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at bottom of atmosphere (surface)">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_schemes" description="Surface specific humidity (water vapor mass mixing ratio with respect to moist air) for Mellor-Yamada-Janjic physics schemes">
+    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_boa_for_myj_schemes" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at bottom of atmosphere (surface) for Mellor-Yamada-Janjic physics schemes">
       <type units="kg kg-1">real</type>
     </standard_name>
     <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_top_of_viscous_sublayer" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at the top of the viscous sublayer">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="x_momentum_flux_at_surface_for_coupling">
+    <standard_name name="x_momentum_flux_at_boa_for_coupling" description="Momentum flux in the x-direction at the bottom of the atmosphere (surface) for coupling">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="x_momentum_flux_at_surface_from_coupled_process">
+    <standard_name name="x_momentum_flux_at_boa_from_coupled_process" description="Momentum flux in the x-direction at the bottom of the atmosphere (surface) from a coupled process">
       <type units="Pa">real</type>
     </standard_name>
     <standard_name name="x_wind_at_10m_for_coupling">
@@ -3227,10 +3227,10 @@
     <standard_name name="x_wind_at_top_of_viscous_sublayer">
       <type units="m s-1">real</type>
     </standard_name>
-    <standard_name name="y_momentum_flux_at_surface_for_coupling">
+    <standard_name name="y_momentum_flux_at_boa_for_coupling" description="Momentum flux in the y-direction at the bottom of the atmosphere (surface) for coupling">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="y_momentum_flux_at_surface_from_coupled_process">
+    <standard_name name="y_momentum_flux_at_boa_from_coupled_process" description="Momentum flux in the y-direction at the bottom of the atmosphere (surface) from a coupled process">
       <type units="Pa">real</type>
     </standard_name>
     <standard_name name="y_wind_at_10m_for_coupling">
@@ -3403,10 +3403,10 @@
       <cfname>lwe_snowfall_rate</cfname>
       <type units="mm s-1">real</type>
     </standard_name>
-    <standard_name name="lwe_surface_snow" description="Liquid water equivalent surface snow">
+    <standard_name name="lwe_surface_snow" description="Liquid water equivalent of snow accumulated on surface">
       <type units="mm">real</type>
     </standard_name>
-    <standard_name name="lwe_surface_snow_from_coupled_process" description="Liquid water equivalent surface snow from coupled process">
+    <standard_name name="lwe_surface_snow_from_coupled_process" description="Liquid water equivalent of snow accumulated on surface from coupled process">
       <type units="m">real</type>
     </standard_name>
     <standard_name name="lwe_thickness_of_convective_precipitation_on_previous_timestep" description="Liquid water equivalent thickness of convective precipitation amount on previous timestep">
@@ -3418,13 +3418,13 @@
     <standard_name name="lwe_thickness_of_graupel_on_previous_timestep" description="Liquid water equivalent thickness of graupel amount on previous timestep">
       <type units="m">real</type>
     </standard_name>
-    <standard_name name="lwe_thickness_of_ice_in_surface_snow" description="Liquid water equivalent thickness of ice in surface snow">
+    <standard_name name="lwe_thickness_of_ice_in_surface_snow" description="Liquid water equivalent thickness of ice in snow accumulated on surface">
       <type units="mm">real</type>
     </standard_name>
     <standard_name name="lwe_thickness_of_ice_precipitation_on_previous_timestep" description="Liquid water equivalent thickness of ice precipitation amount on previous timestep">
       <type units="m">real</type>
     </standard_name>
-    <standard_name name="lwe_thickness_of_liquid_water_in_surface_snow" description="Liquid water equivalent thickness of liquid water in surface snow">
+    <standard_name name="lwe_thickness_of_liquid_water_in_surface_snow" description="Liquid water equivalent thickness of liquid water in snow accumulated on surface">
       <type units="mm">real</type>
     </standard_name>
     <standard_name name="lwe_thickness_of_rain_on_dynamics_timestep_for_coupling" description="Liquid water equivalent thickness of rain amount on dynamics timestep for coupling">
@@ -3436,7 +3436,7 @@
     <standard_name name="lwe_thickness_of_snowfall_on_previous_timestep" description="Liquid water equivalent thickness of snowfall amount on previous timestep">
       <type units="mm">real</type>
     </standard_name>
-    <standard_name name="lwe_thickness_of_surface_snow" description="Liquid water equivalent thickness of surface snow amount">
+    <standard_name name="lwe_thickness_of_surface_snow" description="Liquid water equivalent thickness of snow accumulated on surface">
       <cfname>lwe_thickness_of_surface_snow_amount</cfname>
       <type units="mm">real</type>
     </standard_name>
@@ -3512,10 +3512,10 @@
     <standard_name name="soil_temperature_for_lsm" description="Soil temperature for land surface model">
       <type units="K">real</type>
     </standard_name>
-    <standard_name name="specified_upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface" description="Specified upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface">
+    <standard_name name="specified_upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_boa" description="Specified upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at bottom of atmosphere (surface)">
       <type units="kg kg-1 m s-1">real</type>
     </standard_name>
-    <standard_name name="specified_upward_temperature_flux_at_surface">
+    <standard_name name="specified_upward_temperature_flux_at_boa" description="Specified upward temperature flux at bottom of atmosphere (surface)">
       <type units="K m s-1">real</type>
     </standard_name>
     <standard_name name="standard_deviation_of_subgrid_orography">
@@ -3585,7 +3585,7 @@
     <standard_name name="upper_bound_of_max_albedo_assuming_deep_snow" description="Upper bound of maximum albedo assuming deep snow">
       <type units="fraction">real</type>
     </standard_name>
-    <standard_name name="upward_latent_heat_flux_at_surface">
+    <standard_name name="upward_latent_heat_flux_at_boa" description="Upward latent heat flux at bottom of atmosphere (surface)">
       <cfname>surface_upward_latent_heat_flux</cfname>
       <type units="W m-2">real</type>
     </standard_name>
@@ -3657,10 +3657,10 @@
     <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_2m" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at two meters above surface">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_ice" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface over ice">
+    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_boa_over_ice" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at bottom of atmosphere (surface) over ice">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_land" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface over land">
+    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_boa_over_land" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at bottom of atmosphere (surface) over land">
       <type units="kg kg-1">real</type>
     </standard_name>
     <standard_name name="weak_cosz_area_fraction" description="Area fraction for albedo with weak dependence on cosine of zenith angle">

From 82609b277f0cfe9c031f3681eabda72be8b5c1ea Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Mon, 21 Sep 2026 18:51:28 -0600
Subject: [PATCH 04/21] "Surface friction velocity" is redundant...can just use
 "friction velocity"

---
 standard_names.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/standard_names.xml b/standard_names.xml
index fffec74..df21eee 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -3533,10 +3533,10 @@
     <standard_name name="strong_cosz_area_fraction" description="Area fraction for albedo with strong dependence on cosine of zenith angle">
       <type units="fraction">real</type>
     </standard_name>
-    <standard_name name="surface_friction_velocity">
+    <standard_name name="friction_velocity">
       <type units="m s-1">real</type>
     </standard_name>
-    <standard_name name="surface_friction_velocity_for_momentum">
+    <standard_name name="friction_velocity_for_momentum">
       <type units="m s-1">real</type>
     </standard_name>
     <standard_name name="surface_longwave_emissivity">

From de4de4959abdc79dea41721207b052d34e16e5fd Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Mon, 21 Sep 2026 20:16:21 -0600
Subject: [PATCH 05/21] rename strangely named "surface temperature scale" to
 the better-defined "friction-temperature", including definition and citation.

---
 standard_names.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/standard_names.xml b/standard_names.xml
index df21eee..d3120d6 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -3561,7 +3561,7 @@
     <standard_name name="surface_sw_fluxes_assuming_total_and_clear_sky_on_radiation_timestep">
       <type units="W m-2">ddt</type>
     </standard_name>
-    <standard_name name="surface_temperature_scale">
+    <standard_name name="friction_temperature" description="Friction temperature, a.k.a. temperature scale" comment="Defined in Olson et al. 2021 'A Description of the MYNN Surface-Layer Scheme' as negative sensible heat flux divided by the product of density, specific heat Cp, and friction velocity u*">
       <type units="K">real</type>
     </standard_name>
     <standard_name name="temperature_in_ice_layer">

From 9ffbdfa53dfd813cdf306d5612cd33e59faec15e Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 08:55:22 -0600
Subject: [PATCH 06/21] Reverting "boa" definitions...this is not an acceptable
 substitute for "at_surface_interface" due to existing conflicting definition
 of "bottom-of-atmosphere" in radiation community. Will stick with the
 slightly more ambiguous but overall less confusing "at_surface" as a synonym
 for "at_surface_interface", with appropriate definitions.

---
 StandardNamesRules.rst | 13 ++++-----
 standard_names.xml     | 62 +++++++++++++++++++++---------------------
 2 files changed, 36 insertions(+), 39 deletions(-)

diff --git a/StandardNamesRules.rst b/StandardNamesRules.rst
index 5f3d596..bbba40f 100644
--- a/StandardNamesRules.rst
+++ b/StandardNamesRules.rst
@@ -141,16 +141,16 @@ Terminology
 
    `annotated image detailing some of the terminology in this section <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_terms.png>`_
 
-#. A "layer" is a vertical level of a model, as defined by the host. An "interface" is the boundary above or below a layer.
+#. A "layer" is a vertical level of a model. A variable for a given layer is either at the vertical centerpoint of a level, or the vertical average of a level, as defined by the host (see above). An "interface" is the boundary above or below a layer. A variable specified at a given interface
 
 #. By default, *surface* refers to the liquid or solid substance immediately beneath the atmosphere
    for a given vertical column. This can be land, ocean, ice, lake, etc.
 
-   For "surface" variables describing properties of the atmosphere, near/adjacent to the actual surface,
+   For variables describing properties of the atmosphere near/adjacent to the actual surface,
    care should be taken to specify the specific "surface variable" quantity needed for a specific application:
 
-   *  ``[variable]_at_boa`` ("bottom of atmosphere") is the lowest point of the atmosphere, adjacent to the surface.
-      This is equivalent to the bottom interface (as described above).
+   *  ``[variable]_at_surface`` is the lowest interface of the atmospheric model, adjacent to the surface.
+      This is equivalent to the surface-adjacent/bottom interface (as described above).
    *  ``[variable]_at_surface_adjacent_layer`` is the bottom layer of the atmospheric model
    *  ``[variable]_at_[level]`` for variables defined at specific height above the surface, e.g. ``temperature_at_2m``, ``wind_at_10m``
 
@@ -326,7 +326,6 @@ Suffixes
 | at_top_of_atmosphere_model
 | at_top_of_dry_convection
 | at_interfaces
-| at_boa
 | at_toa
 | at_tropopause
 | at_surface
@@ -594,7 +593,7 @@ Special phrases
 +------------------------+-------------------------------------------------------------------------------------+
 | specific               | per unit mass unless otherwise stated                                               |
 +------------------------+-------------------------------------------------------------------------------------+
-| surface                | The top of the solid or liquid medium below the bottom of the atmosphere            |
+| surface                | The top of the solid or liquid medium below the atmosphere                          |
 +------------------------+-------------------------------------------------------------------------------------+
 | unfrozen_water         | liquid and vapor                                                                    |
 +------------------------+-------------------------------------------------------------------------------------+
@@ -617,8 +616,6 @@ Acronyms, Abbreviations, and Aliases
 +---------------------+---------------------------------------------------------+
 | **Short**           |  **Meaning**                                            |
 +=====================+=========================================================+
-| boa                 | bottom of atmosphere (atmosphere interface with surface)|
-+---------------------+---------------------------------------------------------+
 | cnvc90              | GFS Convective Cloud Diagnostics                        |
 +---------------------+---------------------------------------------------------+
 | edmf                | eddy-diffusivity/mass-flux                              |
diff --git a/standard_names.xml b/standard_names.xml
index d3120d6..7ddef69 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -228,7 +228,7 @@
       <standard_name name="diffuse_vis_albedo" description="Albedo of diffuse incident visible radiation">
         <type units="1">real</type>
       </standard_name>
-      <standard_name name="dimensionless_exner_function" description="Dimensionless formulation of the Exner function with respect to 1000 hPa" comment="The formulation of the exner function in an NWP context is (p/p0)^(Rd/cp), where p0 is some reference pressure. For the purposes of the standard names, this reference pressure is assumed as 1000 hPa unless specified otherwise; i.e. dimensionless_exner_function_wrt_air_pressure_at_boa would use the pressure at the surface (bottom of atmosphere) as P0. Note that this is numerically equivalent to T/theta (temperature divided by potential temperature), where again theta is calculated with respect to 1000 hPa if not specified. Note that this definition is distinct from the dimensional exner_function standard name; see that entry for further comments. ">
+      <standard_name name="dimensionless_exner_function" description="Dimensionless formulation of the Exner function with respect to 1000 hPa" comment="The formulation of the exner function in an NWP context is (p/p0)^(Rd/cp), where p0 is some reference pressure. For the purposes of the standard names, this reference pressure is assumed as 1000 hPa unless specified otherwise; i.e. dimensionless_exner_function_wrt_air_pressure_at_surface would use the surface pressure as P0. Note that this is numerically equivalent to T/theta (temperature divided by potential temperature), where again theta is calculated with respect to 1000 hPa if not specified. Note that this definition is distinct from the dimensional exner_function standard name; see that entry for further comments. ">
         <cfname>dimensionless_exner_function</cfname>
         <type units="1">real</type>
       </standard_name>
@@ -568,7 +568,7 @@
       <cfname>air_pressure_at_mean_sea_level</cfname>
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="air_pressure_at_boa" description="Air pressure at bottom of atmosphere; i.e. surface pressure">
+    <standard_name name="air_pressure_at_surface" description="Air pressure at surface; i.e. surface pressure">
       <cfname>surface_air_pressure</cfname>
       <type units="Pa">real</type>
     </standard_name>
@@ -655,7 +655,7 @@
     <standard_name name="dimensionless_exner_function_at_surface_adjacent_layer" description="Dimensionless exner function (p/p0)^(Rd/cp), where p0 is 1000 hPa and p is the pressure at the surface-adjacent layer">
       <type units="1">real</type>
     </standard_name>
-    <standard_name name="dimensionless_exner_function_wrt_pressure_at_boa" description="Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp)">
+    <standard_name name="dimensionless_exner_function_wrt_pressure_at_surface" description="Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp)">
       <type units="1">real</type>
     </standard_name>
     <standard_name name="dry_static_energy" description="Dry static energy content of atmosphere layer">
@@ -785,16 +785,16 @@
     <standard_name name="reciprocal_of_air_pressure_thickness_of_dry_air">
       <type units="Pa-1">real</type>
     </standard_name>
-    <standard_name name="reciprocal_of_dimensionless_exner_function_wrt_air_pressure_at_boa" description="inverse dimensionless exner function with respect to air pressure at bottom of atmosphere (surface pressure); (ps/p)^(R/cp)">
+    <standard_name name="reciprocal_of_dimensionless_exner_function_wrt_air_pressure_at_surface" description="inverse dimensionless exner function with respect to surface pressure; (ps/p)^(R/cp)">
       <type units="1">real</type>
     </standard_name>
-    <standard_name name="reference_air_pressure_normalized_by_air_pressure_at_boa" description="reference pressure normalized by surface pressure">
+    <standard_name name="reference_air_pressure_normalized_by_air_pressure_at_surface" description="reference pressure normalized by surface pressure">
       <type units="1">real</type>
     </standard_name>
     <standard_name name="reference_pressure_in_atmosphere_layer">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="reference_pressure_in_atmosphere_layer_normalized_by_reference_pressure_at_boa" description="Reference pressure in atmosphere layer normalized by reference pressure at bottom of atmosphere (surface reference pressure)">
+    <standard_name name="reference_pressure_in_atmosphere_layer_normalized_by_reference_pressure_at_surface" description="Reference pressure in atmosphere layer normalized by surface reference pressure">
       <type units="1">real</type>
     </standard_name>
     <standard_name name="relative_humidity_at_2m">
@@ -812,10 +812,10 @@
     <standard_name name="subgrid_scale_cloud_liquid_water_mixing_ratio_wrt_moist_air" description="Subgrid-scale cloud liquid water mass mixing ratio with respect to moist air">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="pressure_of_dry_air_at_boa" description="pressure of dry air at bottom of atmosphere (surface pressure)">
+    <standard_name name="pressure_of_dry_air_at_surface" description="surface pressure of dry air">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="reference_pressure_at_boa" description="Reference air pressure at bottom of atmosphere (surface) used in definition of some other quantity (e.g. potential temperature, Exner function, etc.)">
+    <standard_name name="reference_pressure_at_surface" description="Reference surface air pressure used in definition of some other quantity (e.g. potential temperature, Exner function, etc.)">
       <type units="Pa">real</type>
     </standard_name>
     <standard_name name="timestep_for_physics">
@@ -825,7 +825,7 @@
       <cfname>atmosphere_upward_absolute_vorticity</cfname>
       <type units="s-1">real</type>
     </standard_name>
-    <standard_name name="upward_heat_flux_in_air_at_boa" description="Upward heat flux in air at bottom of atmosphere (surface)">
+    <standard_name name="upward_heat_flux_in_air_at_surface" description="Upward heat flux in air at surface interface">
       <cfname>surface_upward_heat_flux_in_air</cfname>
       <type units="W m-2">real</type>
     </standard_name>
@@ -1167,10 +1167,10 @@
       <standard_name name="aerosol_aware_multiplicative_rain_conversion_parameter_for_shallow_convection">
         <type units="1">real</type>
       </standard_name>
-      <standard_name name="cloud_condensed_water_mixing_ratio_wrt_moist_air_at_boa_over_ice" description="Cloud condensed water mass mixing ratio with respect to moist air at bottom of atmosphere (surface) over ice">
+      <standard_name name="cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_ice" description="Cloud condensed water mass mixing ratio with respect to moist air at surface interface over ice">
         <type units="kg kg-1">real</type>
       </standard_name>
-      <standard_name name="cloud_condensed_water_mixing_ratio_wrt_moist_air_at_boa_over_land" description="Cloud condensed water mass mixing ratio with respect to moist air at bottom of atmosophere (surface) over land">
+      <standard_name name="cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_land" description="Cloud condensed water mass mixing ratio with respect to moist air at surface interface over land">
         <type units="kg kg-1">real</type>
       </standard_name>
       <standard_name name="cloud_ice_mixing_ratio_wrt_dry_air" description="Ratio of the mass of cloud ice to the mass of dry air">
@@ -2389,10 +2389,10 @@
     <standard_name name="cumulative_min_vertical_index_at_cloud_base_between_sw_radiation_calls">
       <type units="1">real</type>
     </standard_name>
-    <standard_name name="index_of_air_pressure_at_boa_on_previous_timestep_in_xyz_dimensioned_restart_array" description="Index of air pressure at bottom of atmosphere (surface pressure) on previous timestep in xyz-dimensioned restart array">
+    <standard_name name="index_of_air_pressure_at_surface_on_previous_timestep_in_xyz_dimensioned_restart_array" description="Index of surface pressure on previous timestep in xyz-dimensioned restart array">
       <type units="index">integer</type>
     </standard_name>
-    <standard_name name="index_of_air_pressure_at_boa_two_timesteps_back_in_xyz_dimensioned_tracer_array" description="Index of air pressure at bottom of atmosphere (surface pressure) two timesteps before the current timestep in xyz-dimensioned tracer array">
+    <standard_name name="index_of_air_pressure_at_surface_two_timesteps_back_in_xyz_dimensioned_tracer_array" description="Index of surface pressure two timesteps before the current timestep in xyz-dimensioned tracer array">
       <type units="index">integer</type>
     </standard_name>
     <standard_name name="index_of_air_temperature_on_previous_timestep_in_xyz_dimensioned_restart_array">
@@ -2619,7 +2619,7 @@
     <standard_name name="coefficient_w_d">
       <type units="1">real</type>
     </standard_name>
-    <standard_name name="critical_relative_humidity_at_boa" description="Critical relative humidity at the bottom of the atmosphere (surface)">
+    <standard_name name="critical_relative_humidity_at_surface" description="Critical relative humidity at the surface interface">
       <type units="fraction">real</type>
     </standard_name>
     <standard_name name="critical_relative_humidity_at_toa" description="Critical relative humidity at the top of the atmosphere">
@@ -3090,7 +3090,7 @@
     <standard_name name="solar_constant">
       <type units="W m-2">real</type>
     </standard_name>
-    <standard_name name="lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep" description="longwave total sky fluxes at surface, assuming clear sky, on radiation timestep">
+    <standard_name name="lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep" description="longwave total sky fluxes at surface interface, assuming clear sky, on radiation timestep">
       <type units="W m-2">ddt</type>
     </standard_name>
     <standard_name name="upwelling_diffuse_nir_shortwave_flux_at_surface_on_radiation_timestep" description="upwelling diffuse near-infrared shortwave flux at the surface level on the radiation timestep">
@@ -3113,13 +3113,13 @@
     </standard_name>
   </section>
   <section name="Atmospheric surface and boundary layer">
-    <standard_name name="air_pressure_at_boa_for_coupling" description="air pressure at bottom of atmosphere (surface pressure) for coupling">
+    <standard_name name="air_pressure_at_surface_for_coupling" description="Surface pressure for coupling">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="air_pressure_at_boa_on_previous_timestep" description="air pressure at bottom of atmosphere (surface pressure) on previous timestep">
+    <standard_name name="air_pressure_at_surface_on_previous_timestep" description="Surface pressure on previous timestep">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="air_pressure_at_boa_two_timesteps_back" description="air pressure at bottom of atmosphere (surface pressure) two timesteps before the current timestep">
+    <standard_name name="air_pressure_at_surface_two_timesteps_back" description="Surface pressure two timesteps before the current timestep">
       <type units="Pa">real</type>
     </standard_name>
     <standard_name name="critical_relative_humidity_at_top_of_atmosphere_boundary_layer">
@@ -3176,10 +3176,10 @@
     <standard_name name="updraft_area_fraction_in_scale_aware_tke_moist_edmf_pbl_scheme" description="Updraft area fraction in scale-aware turbulent kinetic energy moist eddy-diffusivity/mass-flux planetary boundary layer scheme">
       <type units="fraction">real</type>
     </standard_name>
-    <standard_name name="upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_boa" description="Upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at bottom of atmosphere (surface)">
+    <standard_name name="upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface" description="Upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface interface">
       <type units="kg kg-1 m s-1">real</type>
     </standard_name>
-    <standard_name name="upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_boa_for_myj_surface_layer_scheme" description="Upward flux of specific humidity (water vapor mass mixing ratio with respect to moist air) at bottom of atmosphere (surface) for MYJ surface layer scheme">
+    <standard_name name="upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_surface_layer_scheme" description="Upward flux of specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface for MYJ surface layer scheme">
       <type units="m s-1 kg kg-1">real</type>
     </standard_name>
     <standard_name name="upward_latent_heat_flux_at_surface_for_coupling">
@@ -3206,19 +3206,19 @@
     <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_2m_for_coupling" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at 2 meters above surface used for coupling">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_boa" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at bottom of atmosphere (surface)">
+    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_surface" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_boa_for_myj_schemes" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at bottom of atmosphere (surface) for Mellor-Yamada-Janjic physics schemes">
+    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_schemes" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface for Mellor-Yamada-Janjic physics schemes">
       <type units="kg kg-1">real</type>
     </standard_name>
     <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_top_of_viscous_sublayer" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at the top of the viscous sublayer">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="x_momentum_flux_at_boa_for_coupling" description="Momentum flux in the x-direction at the bottom of the atmosphere (surface) for coupling">
+    <standard_name name="x_momentum_flux_at_surface_for_coupling" description="Momentum flux in the x-direction at the surface interface for coupling">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="x_momentum_flux_at_boa_from_coupled_process" description="Momentum flux in the x-direction at the bottom of the atmosphere (surface) from a coupled process">
+    <standard_name name="x_momentum_flux_at_surface_from_coupled_process" description="Momentum flux in the x-direction at the surface interface from a coupled process">
       <type units="Pa">real</type>
     </standard_name>
     <standard_name name="x_wind_at_10m_for_coupling">
@@ -3227,10 +3227,10 @@
     <standard_name name="x_wind_at_top_of_viscous_sublayer">
       <type units="m s-1">real</type>
     </standard_name>
-    <standard_name name="y_momentum_flux_at_boa_for_coupling" description="Momentum flux in the y-direction at the bottom of the atmosphere (surface) for coupling">
+    <standard_name name="y_momentum_flux_at_surface_for_coupling" description="Momentum flux in the y-direction at the surface interface for coupling">
       <type units="Pa">real</type>
     </standard_name>
-    <standard_name name="y_momentum_flux_at_boa_from_coupled_process" description="Momentum flux in the y-direction at the bottom of the atmosphere (surface) from a coupled process">
+    <standard_name name="y_momentum_flux_at_surface_from_coupled_process" description="Momentum flux in the y-direction at the surface interface from a coupled process">
       <type units="Pa">real</type>
     </standard_name>
     <standard_name name="y_wind_at_10m_for_coupling">
@@ -3512,10 +3512,10 @@
     <standard_name name="soil_temperature_for_lsm" description="Soil temperature for land surface model">
       <type units="K">real</type>
     </standard_name>
-    <standard_name name="specified_upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_boa" description="Specified upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at bottom of atmosphere (surface)">
+    <standard_name name="specified_upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface" description="Specified upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface interface">
       <type units="kg kg-1 m s-1">real</type>
     </standard_name>
-    <standard_name name="specified_upward_temperature_flux_at_boa" description="Specified upward temperature flux at bottom of atmosphere (surface)">
+    <standard_name name="specified_upward_temperature_flux_at_surface" description="Specified upward temperature flux at surface interface">
       <type units="K m s-1">real</type>
     </standard_name>
     <standard_name name="standard_deviation_of_subgrid_orography">
@@ -3585,7 +3585,7 @@
     <standard_name name="upper_bound_of_max_albedo_assuming_deep_snow" description="Upper bound of maximum albedo assuming deep snow">
       <type units="fraction">real</type>
     </standard_name>
-    <standard_name name="upward_latent_heat_flux_at_boa" description="Upward latent heat flux at bottom of atmosphere (surface)">
+    <standard_name name="upward_latent_heat_flux_at_surface" description="Upward latent heat flux at surface interface">
       <cfname>surface_upward_latent_heat_flux</cfname>
       <type units="W m-2">real</type>
     </standard_name>
@@ -3657,10 +3657,10 @@
     <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_2m" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at two meters above surface">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_boa_over_ice" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at bottom of atmosphere (surface) over ice">
+    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_ice" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface over ice">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_boa_over_land" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at bottom of atmosphere (surface) over land">
+    <standard_name name="water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_land" description="Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface over land">
       <type units="kg kg-1">real</type>
     </standard_name>
     <standard_name name="weak_cosz_area_fraction" description="Area fraction for albedo with weak dependence on cosine of zenith angle">

From 996bb24d70c9ad03f2f644f132ac144be2beef01 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 08:56:49 -0600
Subject: [PATCH 07/21] Sort xml and generate new Metadata

---
 Metadata-standard-names.md   |  92 +++++++++++++-------------
 Metadata-standard-names.yaml | 124 ++++++++++++++++++-----------------
 standard_names.xml           |  62 +++++++++---------
 3 files changed, 142 insertions(+), 136 deletions(-)

diff --git a/Metadata-standard-names.md b/Metadata-standard-names.md
index 2d3458a..1913173 100644
--- a/Metadata-standard-names.md
+++ b/Metadata-standard-names.md
@@ -41,7 +41,7 @@ The following names are too general to be chosen as standard names, but they can
     * `real`: units = kg m-3
 * `energy`: Energy
     * `real`: units = J
-* `energy_content`: Total energy within some surface
+* `energy_content`: Total energy within some ideal surface
     * `real`: units = J m-2
 * `energy_density`: Total energy within some volume
     * `real`: units = J m-3
@@ -151,7 +151,7 @@ These names are used as bases for other names, but may also be considered standa
 * `air_temperature`: The temperature of air
     * Equivalent CF name: `air_temperature`
     * `real`: units = K
-* `albedo`: The fraction of incident radiation reflected by a surface
+* `albedo`: The fraction of incident radiation reflected by a physical surface
     * `real`: units = 1
 * `atmosphere_heat_diffusivity`: Atmosphere heat diffusivity
     * Equivalent CF name: `atmosphere_heat_diffusivity`
@@ -245,7 +245,7 @@ These names are used as bases for other names, but may also be considered standa
 * `solar_zenith_angle`: The angle between the direction to the sun and the local zenith (vertical direction)
     * Equivalent CF name: `solar_zenith_angle`
     * `real`: units = degrees
-* `surface_skin_temperature`: The temperature of the topmost layer of the surface
+* `surface_skin_temperature`: The temperature of the interface of the surface and the atmosphere
     * Equivalent CF name: `surface_skin_temperature`
     * `real`: units = K
 * `temperature_flux`: Flux of temperature across a unit surface
@@ -401,7 +401,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts
 * `air_pressure_at_mean_sea_level`: Air pressure at mean sea level
     * Equivalent CF name: `air_pressure_at_mean_sea_level`
     * `real`: units = Pa
-* `air_pressure_at_surface`: Air pressure at local surface
+* `air_pressure_at_surface`: Air pressure at surface; i.e. surface pressure
     * Equivalent CF name: `surface_air_pressure`
     * `real`: units = Pa
 * `air_pressure_at_surface_adjacent_layer`: Air pressure at surface adjacent layer
@@ -460,7 +460,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts
     * `real`: units = 1
 * `dimensionless_exner_function_at_surface_adjacent_layer`: Dimensionless exner function (p/p0)^(Rd/cp), where p0 is 1000 hPa and p is the pressure at the surface-adjacent layer
     * `real`: units = 1
-* `dimensionless_exner_function_wrt_surface_pressure`: Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp)
+* `dimensionless_exner_function_wrt_pressure_at_surface`: Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp)
     * `real`: units = 1
 * `dry_static_energy`: Dry static energy content of atmosphere layer
     * Equivalent CF name: `dry_static_energy_content_of_atmosphere_layer`
@@ -555,7 +555,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts
     * `real`: units = 1
 * `reference_pressure_in_atmosphere_layer`: Reference pressure in atmosphere layer
     * `real`: units = Pa
-* `reference_pressure_in_atmosphere_layer_normalized_by_surface_reference_pressure`: Reference pressure in atmosphere layer normalized by surface reference pressure
+* `reference_pressure_in_atmosphere_layer_normalized_by_reference_pressure_at_surface`: Reference pressure in atmosphere layer normalized by surface reference pressure
     * `real`: units = 1
 * `relative_humidity_at_2m`: Relative humidity at 2m
     * `real`: units = fraction
@@ -567,16 +567,16 @@ Variables defining or relating to timing, dates, calendar, and related concepts
     * `real`: units = kg kg-1
 * `subgrid_scale_cloud_liquid_water_mixing_ratio_wrt_moist_air`: Subgrid-scale cloud liquid water mass mixing ratio with respect to moist air
     * `real`: units = kg kg-1
-* `surface_pressure_of_dry_air`: Surface pressure of dry air
+* `pressure_of_dry_air_at_surface`: surface pressure of dry air
     * `real`: units = Pa
-* `surface_reference_pressure`: Reference pressure used in definition of some other quantity (e.g. potential temperature, Exner function, etc.)
+* `reference_pressure_at_surface`: Reference surface air pressure used in definition of some other quantity (e.g. potential temperature, Exner function, etc.)
     * `real`: units = Pa
 * `timestep_for_physics`: Timestep for physics
     * `integer`: units = s
 * `upward_absolute_vorticity_of_air`: The upward (kth) component of the curl of the vector wind field
     * Equivalent CF name: `atmosphere_upward_absolute_vorticity`
     * `real`: units = s-1
-* `upward_heat_flux_in_air_at_surface`: Upward heat flux in air at surface
+* `upward_heat_flux_in_air_at_surface`: Upward heat flux in air at surface interface
     * Equivalent CF name: `surface_upward_heat_flux_in_air`
     * `real`: units = W m-2
 * `us_standard_air_pressure_at_mean_sea_level`: US Standard Atmospheric pressure at sea level
@@ -599,7 +599,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts
     * `real`: units = kg kg-1
 * `water_vapor_mixing_ratio_wrt_moist_air_on_previous_timestep_in_xyz_dimensioned_restart_array`: Specific humidity (water vapor mass mixing ratio with respect to moist air) on previous timestep in XYZ-dimensioned restart array
     * `real`: units = kg kg-1
-* `water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back`: Specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps back
+* `water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back`: Specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps before the current timestep
     * `real`: units = kg kg-1
 * `wind_from_direction_at_10m`: Direction (clockwise from north) wind vector is pointing away from, at 10 meters above surface.
     * `real`: units = degrees
@@ -809,9 +809,9 @@ Tracers are numerically zero-mass particles advected in fluid flow, typically re
     * `real`: units = 1
 * `aerosol_aware_multiplicative_rain_conversion_parameter_for_shallow_convection`: Aerosol aware multiplicative rain conversion parameter for shallow convection
     * `real`: units = 1
-* `cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_ice`: Cloud condensed water mass mixing ratio with respect to moist air at surface over ice
+* `cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_ice`: Cloud condensed water mass mixing ratio with respect to moist air at surface interface over ice
     * `real`: units = kg kg-1
-* `cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_land`: Cloud condensed water mass mixing ratio with respect to moist air at surface over land
+* `cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_land`: Cloud condensed water mass mixing ratio with respect to moist air at surface interface over land
     * `real`: units = kg kg-1
 * `cloud_ice_mixing_ratio_wrt_dry_air`: Ratio of the mass of cloud ice to the mass of dry air
     * Equivalent CF name: `cloud_ice_mixing_ratio`
@@ -1313,7 +1313,7 @@ Variables that indicate or control some action.
     * `real`: units = 1
 * `control_for_vegetation_dataset`: Control for vegetation dataset
     * `integer`: units = 1
-* `control_for_vertical_index_direction`: control flag for direction of vertical index; 0 indicates index from toa to surface, 1 indicates index from surface to toa
+* `control_for_vertical_index_direction`: control flag for direction of vertical index; 0 indicates index from top of atmosphere to surface, 1 indicates index from surface to toa
     * `integer`: units = 1
 * `do_aerosol_physics`: Do aerosol physics
     * `logical`: units = flag
@@ -1629,9 +1629,9 @@ Values indicating the index of some array or other data structure
     * `real`: units = 1
 * `cumulative_min_vertical_index_at_cloud_base_between_sw_radiation_calls`: Cumulative min vertical index at cloud base between sw radiation calls
     * `real`: units = 1
-* `index_of_air_pressure_at_surface_on_previous_timestep_in_xyz_dimensioned_restart_array`: Index of air pressure at surface on previous timestep in xyz dimensioned restart array
+* `index_of_air_pressure_at_surface_on_previous_timestep_in_xyz_dimensioned_restart_array`: Index of surface pressure on previous timestep in xyz-dimensioned restart array
     * `integer`: units = index
-* `index_of_air_pressure_at_surface_two_timesteps_back_in_xyz_dimensioned_tracer_array`: Index of air pressure at surface two timesteps back in xyz dimensioned tracer array
+* `index_of_air_pressure_at_surface_two_timesteps_back_in_xyz_dimensioned_tracer_array`: Index of surface pressure two timesteps before the current timestep in xyz-dimensioned tracer array
     * `integer`: units = index
 * `index_of_air_temperature_on_previous_timestep_in_xyz_dimensioned_restart_array`: Index of air temperature on previous timestep in xyz dimensioned restart array
     * `integer`: units = index
@@ -1707,7 +1707,7 @@ Values indicating the index of some array or other data structure
     * `integer`: units = index
 * `index_of_water_vapor_mixing_ratio_wrt_moist_air_on_previous_timestep_in_xyz_dimensioned_restart_array`: Index of specific humidity (water vapor mass mixing ratio with respect to moist air) on previous timestep in xyz dimensioned restart array
     * `integer`: units = index
-* `index_of_water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back_in_xyz_dimensioned_restart_array`: Index of specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps back in xyz dimensioned restart array
+* `index_of_water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back_in_xyz_dimensioned_restart_array`: Index of specific humidity (water vapor mass mixing ratio with respect to moist air) two timesteps before the current timestep in xyz dimensioned restart array
     * `integer`: units = index
 * `index_of_water_vegetation_category`: Index of water vegetation category
     * `integer`: units = index
@@ -1783,7 +1783,7 @@ Coefficients includes scaling factors, tunable parameters, and other similar var
     * `real`: units = 1
 * `coefficient_w_d`: Coefficient w d
     * `real`: units = 1
-* `critical_relative_humidity_at_surface`: Critical relative humidity at surface
+* `critical_relative_humidity_at_surface`: Critical relative humidity at the surface interface
     * `real`: units = fraction
 * `critical_relative_humidity_at_toa`: Critical relative humidity at the top of the atmosphere
     * `real`: units = fraction
@@ -2097,7 +2097,7 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = 1
 * `solar_constant`: Solar constant
     * `real`: units = W m-2
-* `surface_lw_fluxes_assuming_total_and_clear_sky_on_radiation_timestep`: Surface lw fluxes assuming total and clear sky on radiation timestep
+* `lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep`: longwave total sky fluxes at surface interface, assuming clear sky, on radiation timestep
     * `ddt`: units = W m-2
 * `upwelling_diffuse_nir_shortwave_flux_at_surface_on_radiation_timestep`: upwelling diffuse near-infrared shortwave flux at the surface level on the radiation timestep
     * `real`: units = W m-2
@@ -2112,11 +2112,11 @@ Thresholds represent some value at which the behavior of some process changes, i
 * `upwelling_longwave_flux_at_surface_on_radiation_timestep`: Upwelling longwave flux at surface on radiation timestep
     * `real`: units = W m-2
 ## Atmospheric surface and boundary layer
-* `air_pressure_at_surface_for_coupling`: Air pressure at surface for coupling
+* `air_pressure_at_surface_for_coupling`: Surface pressure for coupling
     * `real`: units = Pa
-* `air_pressure_at_surface_on_previous_timestep`: Air pressure at surface on previous timestep
+* `air_pressure_at_surface_on_previous_timestep`: Surface pressure on previous timestep
     * `real`: units = Pa
-* `air_pressure_at_surface_two_timesteps_back`: Air pressure at surface two timesteps back
+* `air_pressure_at_surface_two_timesteps_back`: Surface pressure two timesteps before the current timestep
     * `real`: units = Pa
 * `critical_relative_humidity_at_top_of_atmosphere_boundary_layer`: Critical relative humidity at top of atmosphere boundary layer
     * `real`: units = fraction
@@ -2154,9 +2154,9 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = m
 * `updraft_area_fraction_in_scale_aware_tke_moist_edmf_pbl_scheme`: Updraft area fraction in scale-aware turbulent kinetic energy moist eddy-diffusivity/mass-flux planetary boundary layer scheme
     * `real`: units = fraction
-* `upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface
+* `upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface interface
     * `real`: units = kg kg-1 m s-1
-* `upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_surface_layer_scheme`: Upward flux of specific humidity (water vapor mass mixing ratio with respect to moist air) at surface for MYJ surface layer scheme
+* `upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_surface_layer_scheme`: Upward flux of specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface for MYJ surface layer scheme
     * `real`: units = m s-1 kg kg-1
 * `upward_latent_heat_flux_at_surface_for_coupling`: Upward latent heat flux at surface for coupling
     * `real`: units = W m-2
@@ -2174,23 +2174,23 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = K m s-1
 * `water_vapor_mixing_ratio_wrt_moist_air_at_2m_for_coupling`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at 2 meters above surface used for coupling
     * `real`: units = kg kg-1
-* `water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface
+* `water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface
     * `real`: units = kg kg-1
-* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_schemes`: Surface specific humidity (water vapor mass mixing ratio with respect to moist air) for Mellor-Yamada-Janjic physics schemes
+* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_schemes`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface for Mellor-Yamada-Janjic physics schemes
     * `real`: units = kg kg-1
 * `water_vapor_mixing_ratio_wrt_moist_air_at_top_of_viscous_sublayer`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at the top of the viscous sublayer
     * `real`: units = kg kg-1
-* `x_momentum_flux_at_surface_for_coupling`: X momentum flux at surface for coupling
+* `x_momentum_flux_at_surface_for_coupling`: Momentum flux in the x-direction at the surface interface for coupling
     * `real`: units = Pa
-* `x_momentum_flux_at_surface_from_coupled_process`: X momentum flux at surface from coupled process
+* `x_momentum_flux_at_surface_from_coupled_process`: Momentum flux in the x-direction at the surface interface from a coupled process
     * `real`: units = Pa
 * `x_wind_at_10m_for_coupling`: X wind at 10m for coupling
     * `real`: units = m s-1
 * `x_wind_at_top_of_viscous_sublayer`: X wind at top of viscous sublayer
     * `real`: units = m s-1
-* `y_momentum_flux_at_surface_for_coupling`: Y momentum flux at surface for coupling
+* `y_momentum_flux_at_surface_for_coupling`: Momentum flux in the y-direction at the surface interface for coupling
     * `real`: units = Pa
-* `y_momentum_flux_at_surface_from_coupled_process`: Y momentum flux at surface from coupled process
+* `y_momentum_flux_at_surface_from_coupled_process`: Momentum flux in the y-direction at the surface interface from a coupled process
     * `real`: units = Pa
 * `y_wind_at_10m_for_coupling`: Y wind at 10m for coupling
     * `real`: units = m s-1
@@ -2308,9 +2308,9 @@ Thresholds represent some value at which the behavior of some process changes, i
 * `lwe_snowfall_rate`: Liquid water equivalent snowfall rate
     * Equivalent CF name: `lwe_snowfall_rate`
     * `real`: units = mm s-1
-* `lwe_surface_snow`: Liquid water equivalent surface snow
+* `lwe_surface_snow`: Liquid water equivalent of snow accumulated on surface
     * `real`: units = mm
-* `lwe_surface_snow_from_coupled_process`: Liquid water equivalent surface snow from coupled process
+* `lwe_surface_snow_from_coupled_process`: Liquid water equivalent of snow accumulated on surface from coupled process
     * `real`: units = m
 * `lwe_thickness_of_convective_precipitation_on_previous_timestep`: Liquid water equivalent thickness of convective precipitation amount on previous timestep
     * `real`: units = m
@@ -2318,11 +2318,11 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = m
 * `lwe_thickness_of_graupel_on_previous_timestep`: Liquid water equivalent thickness of graupel amount on previous timestep
     * `real`: units = m
-* `lwe_thickness_of_ice_in_surface_snow`: Liquid water equivalent thickness of ice in surface snow
+* `lwe_thickness_of_ice_in_surface_snow`: Liquid water equivalent thickness of ice in snow accumulated on surface
     * `real`: units = mm
 * `lwe_thickness_of_ice_precipitation_on_previous_timestep`: Liquid water equivalent thickness of ice precipitation amount on previous timestep
     * `real`: units = m
-* `lwe_thickness_of_liquid_water_in_surface_snow`: Liquid water equivalent thickness of liquid water in surface snow
+* `lwe_thickness_of_liquid_water_in_surface_snow`: Liquid water equivalent thickness of liquid water in snow accumulated on surface
     * `real`: units = mm
 * `lwe_thickness_of_rain_on_dynamics_timestep_for_coupling`: Liquid water equivalent thickness of rain amount on dynamics timestep for coupling
     * `real`: units = m
@@ -2330,7 +2330,7 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = m
 * `lwe_thickness_of_snowfall_on_previous_timestep`: Liquid water equivalent thickness of snowfall amount on previous timestep
     * `real`: units = mm
-* `lwe_thickness_of_surface_snow`: Liquid water equivalent thickness of surface snow amount
+* `lwe_thickness_of_surface_snow`: Liquid water equivalent thickness of snow accumulated on surface
     * Equivalent CF name: `lwe_thickness_of_surface_snow_amount`
     * `real`: units = mm
 * `mass_content_of_water_in_top_soil_layer`: mass per unit area of water in top layer of soil
@@ -2361,13 +2361,13 @@ Thresholds represent some value at which the behavior of some process changes, i
 * `sea_ice_thickness`: Sea ice thickness
     * Equivalent CF name: `sea_ice_thickness`
     * `real`: units = m
-* `skin_temperature_at_surface_over_ice`: Skin temperature at surface over (or where) ice
+* `surface_skin_temperature_over_ice`: Surface skin temperature over (or where) ice
     * `real`: units = K
-* `skin_temperature_at_surface_over_land`: Skin temperature at surface over (or where) land
+* `surface_skin_temperature_over_land`: Surface skin temperature over (or where) land
     * `real`: units = K
-* `skin_temperature_at_surface_over_ocean`: Skin temperature at surface over (or where) ocean
+* `surface_skin_temperature_over_ocean`: Surface skin temperatura over (or where) ocean
     * `real`: units = K
-* `skin_temperature_at_surface_over_snow`: Skin temperature at surface over (or where) snow
+* `surface_skin_temperature_over_snow`: Surface skin temperature over (or where) snow
     * `real`: units = K
 * `slow_soil_pool_mass_content_of_carbon`: Slow soil pool mass content of carbon
     * Equivalent CF name: `slow_soil_pool_mass_content_of_carbon`
@@ -2382,9 +2382,9 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = mm s-1
 * `soil_temperature_for_lsm`: Soil temperature for land surface model
     * `real`: units = K
-* `specified_upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Specified upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface
+* `specified_upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface`: Specified upward specific humidity (water vapor mass mixing ratio with respect to moist air) flux at surface interface
     * `real`: units = kg kg-1 m s-1
-* `specified_upward_temperature_flux_at_surface`: Specified upward temperature flux at surface
+* `specified_upward_temperature_flux_at_surface`: Specified upward temperature flux at surface interface
     * `real`: units = K m s-1
 * `standard_deviation_of_subgrid_orography`: Standard deviation of subgrid orography
     * `real`: units = m
@@ -2396,9 +2396,9 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = g m-2
 * `strong_cosz_area_fraction`: Area fraction for albedo with strong dependence on cosine of zenith angle
     * `real`: units = fraction
-* `surface_friction_velocity`: Surface friction velocity
+* `friction_velocity`: Friction velocity
     * `real`: units = m s-1
-* `surface_friction_velocity_for_momentum`: Surface friction velocity for momentum
+* `friction_velocity_for_momentum`: Friction velocity for momentum
     * `real`: units = m s-1
 * `surface_longwave_emissivity`: Surface longwave emissivity
     * Equivalent CF name: `surface_longwave_emissivity`
@@ -2415,7 +2415,7 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = kg m-2
 * `surface_sw_fluxes_assuming_total_and_clear_sky_on_radiation_timestep`: Surface sw fluxes assuming total and clear sky on radiation timestep
     * `ddt`: units = W m-2
-* `surface_temperature_scale`: Surface temperature scale
+* `friction_temperature`: Friction temperature, a.k.a. temperature scale
     * `real`: units = K
 * `temperature_in_ice_layer`: Temperature in ice layer
     * `real`: units = K
@@ -2431,7 +2431,7 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = s
 * `upper_bound_of_max_albedo_assuming_deep_snow`: Upper bound of maximum albedo assuming deep snow
     * `real`: units = fraction
-* `upward_latent_heat_flux_at_surface`: Upward latent heat flux at surface
+* `upward_latent_heat_flux_at_surface`: Upward latent heat flux at surface interface
     * Equivalent CF name: `surface_upward_latent_heat_flux`
     * `real`: units = W m-2
 * `urban_area_fraction_of_cell_area`: fraction of horizontal area of grid cell that is urban
@@ -2480,9 +2480,9 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = kg kg-1
 * `water_vapor_mixing_ratio_wrt_moist_air_at_2m`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at two meters above surface
     * `real`: units = kg kg-1
-* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_ice`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface over ice
+* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_ice`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface over ice
     * `real`: units = kg kg-1
-* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_land`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface over land
+* `water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_land`: Specific humidity (water vapor mass mixing ratio with respect to moist air) at surface interface over land
     * `real`: units = kg kg-1
 * `weak_cosz_area_fraction`: Area fraction for albedo with weak dependence on cosine of zenith angle
     * `real`: units = fraction
diff --git a/Metadata-standard-names.yaml b/Metadata-standard-names.yaml
index 8879757..70bdeb1 100644
--- a/Metadata-standard-names.yaml
+++ b/Metadata-standard-names.yaml
@@ -37,7 +37,7 @@ section:
       type: real
       units: J
     - name: energy_content
-      description: Total energy within some surface
+      description: Total energy within some ideal surface
       type: real
       units: J m-2
     - name: energy_density
@@ -266,7 +266,7 @@ section:
       type: real
       units: K
     - name: albedo
-      description: The fraction of incident radiation reflected by a surface
+      description: The fraction of incident radiation reflected by a physical surface
       type: real
       units: 1
     - name: atmosphere_heat_diffusivity
@@ -457,7 +457,7 @@ section:
       units: degrees
     - name: surface_skin_temperature
       cfname: surface_skin_temperature
-      description: The temperature of the topmost layer of the surface
+      description: The temperature of the interface of the surface and the atmosphere
       type: real
       units: K
     - name: temperature_flux
@@ -765,7 +765,7 @@ section:
     units: Pa
   - name: air_pressure_at_surface
     cfname: surface_air_pressure
-    description: Air pressure at local surface
+    description: Air pressure at surface; i.e. surface pressure
     type: real
     units: Pa
   - name: air_pressure_at_surface_adjacent_layer
@@ -882,7 +882,7 @@ section:
       and p is the pressure at the surface-adjacent layer
     type: real
     units: 1
-  - name: dimensionless_exner_function_wrt_surface_pressure
+  - name: dimensionless_exner_function_wrt_pressure_at_surface
     description: Dimensionless exner function with respect to surface pressure, (p/ps)^(Rd/cp)
     type: real
     units: 1
@@ -1072,7 +1072,7 @@ section:
     description: Reference pressure in atmosphere layer
     type: real
     units: Pa
-  - name: reference_pressure_in_atmosphere_layer_normalized_by_surface_reference_pressure
+  - name: reference_pressure_in_atmosphere_layer_normalized_by_reference_pressure_at_surface
     description: Reference pressure in atmosphere layer normalized by surface reference
       pressure
     type: real
@@ -1098,13 +1098,13 @@ section:
       moist air
     type: real
     units: kg kg-1
-  - name: surface_pressure_of_dry_air
-    description: Surface pressure of dry air
+  - name: pressure_of_dry_air_at_surface
+    description: surface pressure of dry air
     type: real
     units: Pa
-  - name: surface_reference_pressure
-    description: Reference pressure used in definition of some other quantity (e.g.
-      potential temperature, Exner function, etc.)
+  - name: reference_pressure_at_surface
+    description: Reference surface air pressure used in definition of some other quantity
+      (e.g. potential temperature, Exner function, etc.)
     type: real
     units: Pa
   - name: timestep_for_physics
@@ -1118,7 +1118,7 @@ section:
     units: s-1
   - name: upward_heat_flux_in_air_at_surface
     cfname: surface_upward_heat_flux_in_air
-    description: Upward heat flux in air at surface
+    description: Upward heat flux in air at surface interface
     type: real
     units: W m-2
   - name: us_standard_air_pressure_at_mean_sea_level
@@ -1167,7 +1167,7 @@ section:
     units: kg kg-1
   - name: water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back
     description: Specific humidity (water vapor mass mixing ratio with respect to
-      moist air) two timesteps back
+      moist air) two timesteps before the current timestep
     type: real
     units: kg kg-1
   - name: wind_from_direction_at_10m
@@ -1607,12 +1607,12 @@ section:
       units: 1
     - name: cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_ice
       description: Cloud condensed water mass mixing ratio with respect to moist air
-        at surface over ice
+        at surface interface over ice
       type: real
       units: kg kg-1
     - name: cloud_condensed_water_mixing_ratio_wrt_moist_air_at_surface_over_land
       description: Cloud condensed water mass mixing ratio with respect to moist air
-        at surface over land
+        at surface interface over land
       type: real
       units: kg kg-1
     - name: cloud_ice_mixing_ratio_wrt_dry_air
@@ -2671,7 +2671,7 @@ section:
     units: 1
   - name: control_for_vertical_index_direction
     description: control flag for direction of vertical index; 0 indicates index from
-      toa to surface, 1 indicates index from surface to toa
+      top of atmosphere to surface, 1 indicates index from surface to toa
     type: integer
     units: 1
   - name: do_aerosol_physics
@@ -3329,13 +3329,13 @@ section:
     type: real
     units: 1
   - name: index_of_air_pressure_at_surface_on_previous_timestep_in_xyz_dimensioned_restart_array
-    description: Index of air pressure at surface on previous timestep in xyz dimensioned
+    description: Index of surface pressure on previous timestep in xyz-dimensioned
       restart array
     type: integer
     units: index
   - name: index_of_air_pressure_at_surface_two_timesteps_back_in_xyz_dimensioned_tracer_array
-    description: Index of air pressure at surface two timesteps back in xyz dimensioned
-      tracer array
+    description: Index of surface pressure two timesteps before the current timestep
+      in xyz-dimensioned tracer array
     type: integer
     units: index
   - name: index_of_air_temperature_on_previous_timestep_in_xyz_dimensioned_restart_array
@@ -3513,7 +3513,8 @@ section:
     units: index
   - name: index_of_water_vapor_mixing_ratio_wrt_moist_air_two_timesteps_back_in_xyz_dimensioned_restart_array
     description: Index of specific humidity (water vapor mass mixing ratio with respect
-      to moist air) two timesteps back in xyz dimensioned restart array
+      to moist air) two timesteps before the current timestep in xyz dimensioned restart
+      array
     type: integer
     units: index
   - name: index_of_water_vegetation_category
@@ -3667,7 +3668,7 @@ section:
     type: real
     units: 1
   - name: critical_relative_humidity_at_surface
-    description: Critical relative humidity at surface
+    description: Critical relative humidity at the surface interface
     type: real
     units: fraction
   - name: critical_relative_humidity_at_toa
@@ -4365,8 +4366,9 @@ section:
     description: Solar constant
     type: real
     units: W m-2
-  - name: surface_lw_fluxes_assuming_total_and_clear_sky_on_radiation_timestep
-    description: Surface lw fluxes assuming total and clear sky on radiation timestep
+  - name: lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep
+    description: longwave total sky fluxes at surface interface, assuming clear sky,
+      on radiation timestep
     type: ddt
     units: W m-2
   - name: upwelling_diffuse_nir_shortwave_flux_at_surface_on_radiation_timestep
@@ -4401,15 +4403,15 @@ section:
   comment: null
   standard_names:
   - name: air_pressure_at_surface_for_coupling
-    description: Air pressure at surface for coupling
+    description: Surface pressure for coupling
     type: real
     units: Pa
   - name: air_pressure_at_surface_on_previous_timestep
-    description: Air pressure at surface on previous timestep
+    description: Surface pressure on previous timestep
     type: real
     units: Pa
   - name: air_pressure_at_surface_two_timesteps_back
-    description: Air pressure at surface two timesteps back
+    description: Surface pressure two timesteps before the current timestep
     type: real
     units: Pa
   - name: critical_relative_humidity_at_top_of_atmosphere_boundary_layer
@@ -4491,12 +4493,12 @@ section:
     units: fraction
   - name: upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface
     description: Upward specific humidity (water vapor mass mixing ratio with respect
-      to moist air) flux at surface
+      to moist air) flux at surface interface
     type: real
     units: kg kg-1 m s-1
   - name: upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_surface_layer_scheme
     description: Upward flux of specific humidity (water vapor mass mixing ratio with
-      respect to moist air) at surface for MYJ surface layer scheme
+      respect to moist air) at surface interface for MYJ surface layer scheme
     type: real
     units: m s-1 kg kg-1
   - name: upward_latent_heat_flux_at_surface_for_coupling
@@ -4534,12 +4536,12 @@ section:
     units: kg kg-1
   - name: water_vapor_mixing_ratio_wrt_moist_air_at_surface
     description: Specific humidity (water vapor mass mixing ratio with respect to
-      moist air) at surface
+      moist air) at surface interface
     type: real
     units: kg kg-1
   - name: water_vapor_mixing_ratio_wrt_moist_air_at_surface_for_myj_schemes
-    description: Surface specific humidity (water vapor mass mixing ratio with respect
-      to moist air) for Mellor-Yamada-Janjic physics schemes
+    description: Specific humidity (water vapor mass mixing ratio with respect to
+      moist air) at surface interface for Mellor-Yamada-Janjic physics schemes
     type: real
     units: kg kg-1
   - name: water_vapor_mixing_ratio_wrt_moist_air_at_top_of_viscous_sublayer
@@ -4548,11 +4550,12 @@ section:
     type: real
     units: kg kg-1
   - name: x_momentum_flux_at_surface_for_coupling
-    description: X momentum flux at surface for coupling
+    description: Momentum flux in the x-direction at the surface interface for coupling
     type: real
     units: Pa
   - name: x_momentum_flux_at_surface_from_coupled_process
-    description: X momentum flux at surface from coupled process
+    description: Momentum flux in the x-direction at the surface interface from a
+      coupled process
     type: real
     units: Pa
   - name: x_wind_at_10m_for_coupling
@@ -4564,11 +4567,12 @@ section:
     type: real
     units: m s-1
   - name: y_momentum_flux_at_surface_for_coupling
-    description: Y momentum flux at surface for coupling
+    description: Momentum flux in the y-direction at the surface interface for coupling
     type: real
     units: Pa
   - name: y_momentum_flux_at_surface_from_coupled_process
-    description: Y momentum flux at surface from coupled process
+    description: Momentum flux in the y-direction at the surface interface from a
+      coupled process
     type: real
     units: Pa
   - name: y_wind_at_10m_for_coupling
@@ -4801,11 +4805,12 @@ section:
     type: real
     units: mm s-1
   - name: lwe_surface_snow
-    description: Liquid water equivalent surface snow
+    description: Liquid water equivalent of snow accumulated on surface
     type: real
     units: mm
   - name: lwe_surface_snow_from_coupled_process
-    description: Liquid water equivalent surface snow from coupled process
+    description: Liquid water equivalent of snow accumulated on surface from coupled
+      process
     type: real
     units: m
   - name: lwe_thickness_of_convective_precipitation_on_previous_timestep
@@ -4823,7 +4828,7 @@ section:
     type: real
     units: m
   - name: lwe_thickness_of_ice_in_surface_snow
-    description: Liquid water equivalent thickness of ice in surface snow
+    description: Liquid water equivalent thickness of ice in snow accumulated on surface
     type: real
     units: mm
   - name: lwe_thickness_of_ice_precipitation_on_previous_timestep
@@ -4832,7 +4837,8 @@ section:
     type: real
     units: m
   - name: lwe_thickness_of_liquid_water_in_surface_snow
-    description: Liquid water equivalent thickness of liquid water in surface snow
+    description: Liquid water equivalent thickness of liquid water in snow accumulated
+      on surface
     type: real
     units: mm
   - name: lwe_thickness_of_rain_on_dynamics_timestep_for_coupling
@@ -4852,7 +4858,7 @@ section:
     units: mm
   - name: lwe_thickness_of_surface_snow
     cfname: lwe_thickness_of_surface_snow_amount
-    description: Liquid water equivalent thickness of surface snow amount
+    description: Liquid water equivalent thickness of snow accumulated on surface
     type: real
     units: mm
   - name: mass_content_of_water_in_top_soil_layer
@@ -4912,20 +4918,20 @@ section:
     description: Sea ice thickness
     type: real
     units: m
-  - name: skin_temperature_at_surface_over_ice
-    description: Skin temperature at surface over (or where) ice
+  - name: surface_skin_temperature_over_ice
+    description: Surface skin temperature over (or where) ice
     type: real
     units: K
-  - name: skin_temperature_at_surface_over_land
-    description: Skin temperature at surface over (or where) land
+  - name: surface_skin_temperature_over_land
+    description: Surface skin temperature over (or where) land
     type: real
     units: K
-  - name: skin_temperature_at_surface_over_ocean
-    description: Skin temperature at surface over (or where) ocean
+  - name: surface_skin_temperature_over_ocean
+    description: Surface skin temperatura over (or where) ocean
     type: real
     units: K
-  - name: skin_temperature_at_surface_over_snow
-    description: Skin temperature at surface over (or where) snow
+  - name: surface_skin_temperature_over_snow
+    description: Surface skin temperature over (or where) snow
     type: real
     units: K
   - name: slow_soil_pool_mass_content_of_carbon
@@ -4955,11 +4961,11 @@ section:
     units: K
   - name: specified_upward_flux_of_water_vapor_mixing_ratio_wrt_moist_air_at_surface
     description: Specified upward specific humidity (water vapor mass mixing ratio
-      with respect to moist air) flux at surface
+      with respect to moist air) flux at surface interface
     type: real
     units: kg kg-1 m s-1
   - name: specified_upward_temperature_flux_at_surface
-    description: Specified upward temperature flux at surface
+    description: Specified upward temperature flux at surface interface
     type: real
     units: K m s-1
   - name: standard_deviation_of_subgrid_orography
@@ -4983,12 +4989,12 @@ section:
       angle
     type: real
     units: fraction
-  - name: surface_friction_velocity
-    description: Surface friction velocity
+  - name: friction_velocity
+    description: Friction velocity
     type: real
     units: m s-1
-  - name: surface_friction_velocity_for_momentum
-    description: Surface friction velocity for momentum
+  - name: friction_velocity_for_momentum
+    description: Friction velocity for momentum
     type: real
     units: m s-1
   - name: surface_longwave_emissivity
@@ -5020,8 +5026,8 @@ section:
     description: Surface sw fluxes assuming total and clear sky on radiation timestep
     type: ddt
     units: W m-2
-  - name: surface_temperature_scale
-    description: Surface temperature scale
+  - name: friction_temperature
+    description: Friction temperature, a.k.a. temperature scale
     type: real
     units: K
   - name: temperature_in_ice_layer
@@ -5054,7 +5060,7 @@ section:
     units: fraction
   - name: upward_latent_heat_flux_at_surface
     cfname: surface_upward_latent_heat_flux
-    description: Upward latent heat flux at surface
+    description: Upward latent heat flux at surface interface
     type: real
     units: W m-2
   - name: urban_area_fraction_of_cell_area
@@ -5153,12 +5159,12 @@ section:
     units: kg kg-1
   - name: water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_ice
     description: Specific humidity (water vapor mass mixing ratio with respect to
-      moist air) at surface over ice
+      moist air) at surface interface over ice
     type: real
     units: kg kg-1
   - name: water_vapor_mixing_ratio_wrt_moist_air_at_surface_over_land
     description: Specific humidity (water vapor mass mixing ratio with respect to
-      moist air) at surface over land
+      moist air) at surface interface over land
     type: real
     units: kg kg-1
   - name: weak_cosz_area_fraction
diff --git a/standard_names.xml b/standard_names.xml
index 7ddef69..2e4f831 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -776,6 +776,9 @@
     <standard_name name="potentially_advected_quantities">
       <type units="various">real</type>
     </standard_name>
+    <standard_name name="pressure_of_dry_air_at_surface" description="surface pressure of dry air">
+      <type units="Pa">real</type>
+    </standard_name>
     <standard_name name="ratio_of_water_vapor_gas_constant_to_composition_dependent_dry_air_gas_constant_minus_one" description="Ratio of gas constants of water vapor to composition-dependent dry air minus one; (Rwv / Rdair) - 1.0">
       <type units="1">real</type>
     </standard_name>
@@ -791,6 +794,9 @@
     <standard_name name="reference_air_pressure_normalized_by_air_pressure_at_surface" description="reference pressure normalized by surface pressure">
       <type units="1">real</type>
     </standard_name>
+    <standard_name name="reference_pressure_at_surface" description="Reference surface air pressure used in definition of some other quantity (e.g. potential temperature, Exner function, etc.)">
+      <type units="Pa">real</type>
+    </standard_name>
     <standard_name name="reference_pressure_in_atmosphere_layer">
       <type units="Pa">real</type>
     </standard_name>
@@ -812,12 +818,6 @@
     <standard_name name="subgrid_scale_cloud_liquid_water_mixing_ratio_wrt_moist_air" description="Subgrid-scale cloud liquid water mass mixing ratio with respect to moist air">
       <type units="kg kg-1">real</type>
     </standard_name>
-    <standard_name name="pressure_of_dry_air_at_surface" description="surface pressure of dry air">
-      <type units="Pa">real</type>
-    </standard_name>
-    <standard_name name="reference_pressure_at_surface" description="Reference surface air pressure used in definition of some other quantity (e.g. potential temperature, Exner function, etc.)">
-      <type units="Pa">real</type>
-    </standard_name>
     <standard_name name="timestep_for_physics">
       <type units="s">integer</type>
     </standard_name>
@@ -3009,6 +3009,9 @@
     <standard_name name="downwelling_shortwave_flux_at_surface_on_radiation_timestep">
       <type units="W m-2">real</type>
     </standard_name>
+    <standard_name name="lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep" description="longwave total sky fluxes at surface interface, assuming clear sky, on radiation timestep">
+      <type units="W m-2">ddt</type>
+    </standard_name>
     <standard_name name="net_downwelling_diffuse_nir_shortwave_flux_at_surface_for_coupling" description="net downwelling diffuse near-infrared shortwave flux at the surface level for coupling">
       <type units="W m-2">real</type>
     </standard_name>
@@ -3090,9 +3093,6 @@
     <standard_name name="solar_constant">
       <type units="W m-2">real</type>
     </standard_name>
-    <standard_name name="lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep" description="longwave total sky fluxes at surface interface, assuming clear sky, on radiation timestep">
-      <type units="W m-2">ddt</type>
-    </standard_name>
     <standard_name name="upwelling_diffuse_nir_shortwave_flux_at_surface_on_radiation_timestep" description="upwelling diffuse near-infrared shortwave flux at the surface level on the radiation timestep">
       <type units="W m-2">real</type>
     </standard_name>
@@ -3363,6 +3363,15 @@
     <standard_name name="fine_root_mass_content">
       <type units="g m-2">real</type>
     </standard_name>
+    <standard_name name="friction_temperature" description="Friction temperature, a.k.a. temperature scale" comment="Defined in Olson et al. 2021 'A Description of the MYNN Surface-Layer Scheme' as negative sensible heat flux divided by the product of density, specific heat Cp, and friction velocity u*">
+      <type units="K">real</type>
+    </standard_name>
+    <standard_name name="friction_velocity">
+      <type units="m s-1">real</type>
+    </standard_name>
+    <standard_name name="friction_velocity_for_momentum">
+      <type units="m s-1">real</type>
+    </standard_name>
     <standard_name name="frozen_precipitation_density">
       <type units="kg m-3">real</type>
     </standard_name>
@@ -3481,18 +3490,6 @@
       <cfname>sea_ice_thickness</cfname>
       <type units="m">real</type>
     </standard_name>
-    <standard_name name="surface_skin_temperature_over_ice" description="Surface skin temperature over (or where) ice">
-      <type units="K">real</type>
-    </standard_name>
-    <standard_name name="surface_skin_temperature_over_land" description="Surface skin temperature over (or where) land">
-      <type units="K">real</type>
-    </standard_name>
-    <standard_name name="surface_skin_temperature_over_ocean" description="Surface skin temperatura over (or where) ocean">
-      <type units="K">real</type>
-    </standard_name>
-    <standard_name name="surface_skin_temperature_over_snow" description="Surface skin temperature over (or where) snow">
-      <type units="K">real</type>
-    </standard_name>
     <standard_name name="slow_soil_pool_mass_content_of_carbon">
       <cfname>slow_soil_pool_mass_content_of_carbon</cfname>
       <type units="g m-2">real</type>
@@ -3533,12 +3530,6 @@
     <standard_name name="strong_cosz_area_fraction" description="Area fraction for albedo with strong dependence on cosine of zenith angle">
       <type units="fraction">real</type>
     </standard_name>
-    <standard_name name="friction_velocity">
-      <type units="m s-1">real</type>
-    </standard_name>
-    <standard_name name="friction_velocity_for_momentum">
-      <type units="m s-1">real</type>
-    </standard_name>
     <standard_name name="surface_longwave_emissivity">
       <cfname>surface_longwave_emissivity</cfname>
       <type units="fraction">real</type>
@@ -3552,6 +3543,18 @@
     <standard_name name="surface_sensible_heat_due_to_rainfall">
       <type units="W">real</type>
     </standard_name>
+    <standard_name name="surface_skin_temperature_over_ice" description="Surface skin temperature over (or where) ice">
+      <type units="K">real</type>
+    </standard_name>
+    <standard_name name="surface_skin_temperature_over_land" description="Surface skin temperature over (or where) land">
+      <type units="K">real</type>
+    </standard_name>
+    <standard_name name="surface_skin_temperature_over_ocean" description="Surface skin temperatura over (or where) ocean">
+      <type units="K">real</type>
+    </standard_name>
+    <standard_name name="surface_skin_temperature_over_snow" description="Surface skin temperature over (or where) snow">
+      <type units="K">real</type>
+    </standard_name>
     <standard_name name="surface_snow_mass_content_over_ice">
       <type units="kg m-2">real</type>
     </standard_name>
@@ -3561,9 +3564,6 @@
     <standard_name name="surface_sw_fluxes_assuming_total_and_clear_sky_on_radiation_timestep">
       <type units="W m-2">ddt</type>
     </standard_name>
-    <standard_name name="friction_temperature" description="Friction temperature, a.k.a. temperature scale" comment="Defined in Olson et al. 2021 'A Description of the MYNN Surface-Layer Scheme' as negative sensible heat flux divided by the product of density, specific heat Cp, and friction velocity u*">
-      <type units="K">real</type>
-    </standard_name>
     <standard_name name="temperature_in_ice_layer">
       <type units="K">real</type>
     </standard_name>
@@ -3868,4 +3868,4 @@
       <type units="various">real</type>
     </standard_name>
   </section>
-</standard_names>
+</standard_names>
\ No newline at end of file

From 6a246149d3efac4c55eb727d28996433d1ac2e65 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 09:02:56 -0600
Subject: [PATCH 08/21] Resolve issue 156 per discussion there

---
 Metadata-standard-names.md   | 44 +++++++++---------
 Metadata-standard-names.yaml | 88 ++++++++++++++++++------------------
 StandardNamesRules.rst       | 12 +++++
 standard_names.xml           |  4 +-
 4 files changed, 80 insertions(+), 68 deletions(-)

diff --git a/Metadata-standard-names.md b/Metadata-standard-names.md
index 1913173..d0ea6ec 100644
--- a/Metadata-standard-names.md
+++ b/Metadata-standard-names.md
@@ -543,6 +543,8 @@ Variables defining or relating to timing, dates, calendar, and related concepts
     * `real`: units = K
 * `potentially_advected_quantities`: Potentially advected quantities
     * `real`: units = various
+* `pressure_of_dry_air_at_surface`: surface pressure of dry air
+    * `real`: units = Pa
 * `ratio_of_water_vapor_gas_constant_to_composition_dependent_dry_air_gas_constant_minus_one`: Ratio of gas constants of water vapor to composition-dependent dry air minus one; (Rwv / Rdair) - 1.0
     * `real`: units = 1
 * `reciprocal_of_air_pressure_thickness`: Reciprocal of air pressure thickness
@@ -553,6 +555,8 @@ Variables defining or relating to timing, dates, calendar, and related concepts
     * `real`: units = 1
 * `reference_air_pressure_normalized_by_air_pressure_at_surface`: reference pressure normalized by surface pressure
     * `real`: units = 1
+* `reference_pressure_at_surface`: Reference surface air pressure used in definition of some other quantity (e.g. potential temperature, Exner function, etc.)
+    * `real`: units = Pa
 * `reference_pressure_in_atmosphere_layer`: Reference pressure in atmosphere layer
     * `real`: units = Pa
 * `reference_pressure_in_atmosphere_layer_normalized_by_reference_pressure_at_surface`: Reference pressure in atmosphere layer normalized by surface reference pressure
@@ -567,10 +571,6 @@ Variables defining or relating to timing, dates, calendar, and related concepts
     * `real`: units = kg kg-1
 * `subgrid_scale_cloud_liquid_water_mixing_ratio_wrt_moist_air`: Subgrid-scale cloud liquid water mass mixing ratio with respect to moist air
     * `real`: units = kg kg-1
-* `pressure_of_dry_air_at_surface`: surface pressure of dry air
-    * `real`: units = Pa
-* `reference_pressure_at_surface`: Reference surface air pressure used in definition of some other quantity (e.g. potential temperature, Exner function, etc.)
-    * `real`: units = Pa
 * `timestep_for_physics`: Timestep for physics
     * `integer`: units = s
 * `upward_absolute_vorticity_of_air`: The upward (kth) component of the curl of the vector wind field
@@ -1895,7 +1895,7 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = m s-1
 * `cloud_phase_transition_threshold_temperature`: Cloud phase transition threshold temperature
     * `real`: units = K
-* `lower_bound_for_depth_of_sea_temperature_for_nsstm`: Lower bound for depth of sea temperature for GFS near-surface sea temperature scheme
+* `lower_bound_for_depth_of_ocean_temperature_for_nsstm`: Lower bound for depth of sea temperature for GFS near-surface sea temperature scheme
     * `integer`: units = mm
 * `max_critical_relative_humidity`: Maximum critical relative humidity
     * `real`: units = fraction
@@ -1935,7 +1935,7 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = fraction
 * `sigma_pressure_threshold_at_upper_extent_of_background_diffusion`: Sigma pressure threshold at upper extent of background diffusion
     * `real`: units = 1
-* `upper_bound_for_depth_of_sea_temperature_for_nsstm`: Upper bound for depth of sea temperature for GFS near-surface sea temperature scheme
+* `upper_bound_for_depth_of_ocean_temperature_for_nsstm`: Upper bound for depth of sea temperature for GFS near-surface sea temperature scheme
     * `integer`: units = mm
 ## Stochastic physics variables
 * `atmosphere_heat_diffusivity_from_shoc`: Atmospheric heat diffusivity from Simplified Higher-Order Closure stochastic physics scheme
@@ -2043,6 +2043,8 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = W m-2
 * `downwelling_shortwave_flux_at_surface_on_radiation_timestep`: Downwelling shortwave flux at surface on radiation timestep
     * `real`: units = W m-2
+* `lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep`: longwave total sky fluxes at surface interface, assuming clear sky, on radiation timestep
+    * `ddt`: units = W m-2
 * `net_downwelling_diffuse_nir_shortwave_flux_at_surface_for_coupling`: net downwelling diffuse near-infrared shortwave flux at the surface level for coupling
     * `real`: units = W m-2
 * `net_downwelling_diffuse_uv_and_vis_shortwave_flux_at_surface_for_coupling`: net downwelling diffuse ultraviolet and visible shortwave flux at the surface level for coupling
@@ -2097,8 +2099,6 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = 1
 * `solar_constant`: Solar constant
     * `real`: units = W m-2
-* `lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep`: longwave total sky fluxes at surface interface, assuming clear sky, on radiation timestep
-    * `ddt`: units = W m-2
 * `upwelling_diffuse_nir_shortwave_flux_at_surface_on_radiation_timestep`: upwelling diffuse near-infrared shortwave flux at the surface level on the radiation timestep
     * `real`: units = W m-2
 * `upwelling_diffuse_uv_and_vis_shortwave_flux_at_surface_on_radiation_timestep`: upwelling diffuse ultraviolet and visible shortwave flux at the surface level on the radiation timestep
@@ -2280,6 +2280,12 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = g m-2
 * `fine_root_mass_content`: Fine root mass content
     * `real`: units = g m-2
+* `friction_temperature`: Friction temperature, a.k.a. temperature scale
+    * `real`: units = K
+* `friction_velocity`: Friction velocity
+    * `real`: units = m s-1
+* `friction_velocity_for_momentum`: Friction velocity for momentum
+    * `real`: units = m s-1
 * `frozen_precipitation_density`: Frozen precipitation density
     * `real`: units = kg m-3
 * `graupel_precipitation_rate_on_previous_timestep`: Graupel precipitation rate on previous timestep
@@ -2361,14 +2367,6 @@ Thresholds represent some value at which the behavior of some process changes, i
 * `sea_ice_thickness`: Sea ice thickness
     * Equivalent CF name: `sea_ice_thickness`
     * `real`: units = m
-* `surface_skin_temperature_over_ice`: Surface skin temperature over (or where) ice
-    * `real`: units = K
-* `surface_skin_temperature_over_land`: Surface skin temperature over (or where) land
-    * `real`: units = K
-* `surface_skin_temperature_over_ocean`: Surface skin temperatura over (or where) ocean
-    * `real`: units = K
-* `surface_skin_temperature_over_snow`: Surface skin temperature over (or where) snow
-    * `real`: units = K
 * `slow_soil_pool_mass_content_of_carbon`: Slow soil pool mass content of carbon
     * Equivalent CF name: `slow_soil_pool_mass_content_of_carbon`
     * `real`: units = g m-2
@@ -2396,10 +2394,6 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = g m-2
 * `strong_cosz_area_fraction`: Area fraction for albedo with strong dependence on cosine of zenith angle
     * `real`: units = fraction
-* `friction_velocity`: Friction velocity
-    * `real`: units = m s-1
-* `friction_velocity_for_momentum`: Friction velocity for momentum
-    * `real`: units = m s-1
 * `surface_longwave_emissivity`: Surface longwave emissivity
     * Equivalent CF name: `surface_longwave_emissivity`
     * `real`: units = fraction
@@ -2409,14 +2403,20 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = fraction
 * `surface_sensible_heat_due_to_rainfall`: Surface sensible heat due to rainfall
     * `real`: units = W
+* `surface_skin_temperature_over_ice`: Surface skin temperature over (or where) ice
+    * `real`: units = K
+* `surface_skin_temperature_over_land`: Surface skin temperature over (or where) land
+    * `real`: units = K
+* `surface_skin_temperature_over_ocean`: Surface skin temperatura over (or where) ocean
+    * `real`: units = K
+* `surface_skin_temperature_over_snow`: Surface skin temperature over (or where) snow
+    * `real`: units = K
 * `surface_snow_mass_content_over_ice`: Surface snow mass content over ice
     * `real`: units = kg m-2
 * `surface_snow_mass_content_over_land`: Surface snow mass content over land
     * `real`: units = kg m-2
 * `surface_sw_fluxes_assuming_total_and_clear_sky_on_radiation_timestep`: Surface sw fluxes assuming total and clear sky on radiation timestep
     * `ddt`: units = W m-2
-* `friction_temperature`: Friction temperature, a.k.a. temperature scale
-    * `real`: units = K
 * `temperature_in_ice_layer`: Temperature in ice layer
     * `real`: units = K
 * `temperature_in_surface_snow`: Temperature in surface snow
diff --git a/Metadata-standard-names.yaml b/Metadata-standard-names.yaml
index 70bdeb1..c2ad91b 100644
--- a/Metadata-standard-names.yaml
+++ b/Metadata-standard-names.yaml
@@ -1046,6 +1046,10 @@ section:
     description: Potentially advected quantities
     type: real
     units: various
+  - name: pressure_of_dry_air_at_surface
+    description: surface pressure of dry air
+    type: real
+    units: Pa
   - name: ratio_of_water_vapor_gas_constant_to_composition_dependent_dry_air_gas_constant_minus_one
     description: Ratio of gas constants of water vapor to composition-dependent dry
       air minus one; (Rwv / Rdair) - 1.0
@@ -1068,6 +1072,11 @@ section:
     description: reference pressure normalized by surface pressure
     type: real
     units: 1
+  - name: reference_pressure_at_surface
+    description: Reference surface air pressure used in definition of some other quantity
+      (e.g. potential temperature, Exner function, etc.)
+    type: real
+    units: Pa
   - name: reference_pressure_in_atmosphere_layer
     description: Reference pressure in atmosphere layer
     type: real
@@ -1098,15 +1107,6 @@ section:
       moist air
     type: real
     units: kg kg-1
-  - name: pressure_of_dry_air_at_surface
-    description: surface pressure of dry air
-    type: real
-    units: Pa
-  - name: reference_pressure_at_surface
-    description: Reference surface air pressure used in definition of some other quantity
-      (e.g. potential temperature, Exner function, etc.)
-    type: real
-    units: Pa
   - name: timestep_for_physics
     description: Timestep for physics
     type: integer
@@ -3912,7 +3912,7 @@ section:
     description: Cloud phase transition threshold temperature
     type: real
     units: K
-  - name: lower_bound_for_depth_of_sea_temperature_for_nsstm
+  - name: lower_bound_for_depth_of_ocean_temperature_for_nsstm
     description: Lower bound for depth of sea temperature for GFS near-surface sea
       temperature scheme
     type: integer
@@ -3999,7 +3999,7 @@ section:
     description: Sigma pressure threshold at upper extent of background diffusion
     type: real
     units: 1
-  - name: upper_bound_for_depth_of_sea_temperature_for_nsstm
+  - name: upper_bound_for_depth_of_ocean_temperature_for_nsstm
     description: Upper bound for depth of sea temperature for GFS near-surface sea
       temperature scheme
     type: integer
@@ -4247,6 +4247,11 @@ section:
     description: Downwelling shortwave flux at surface on radiation timestep
     type: real
     units: W m-2
+  - name: lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep
+    description: longwave total sky fluxes at surface interface, assuming clear sky,
+      on radiation timestep
+    type: ddt
+    units: W m-2
   - name: net_downwelling_diffuse_nir_shortwave_flux_at_surface_for_coupling
     description: net downwelling diffuse near-infrared shortwave flux at the surface
       level for coupling
@@ -4366,11 +4371,6 @@ section:
     description: Solar constant
     type: real
     units: W m-2
-  - name: lw_fluxes_at_surface_assuming_total_and_clear_sky_on_radiation_timestep
-    description: longwave total sky fluxes at surface interface, assuming clear sky,
-      on radiation timestep
-    type: ddt
-    units: W m-2
   - name: upwelling_diffuse_nir_shortwave_flux_at_surface_on_radiation_timestep
     description: upwelling diffuse near-infrared shortwave flux at the surface level
       on the radiation timestep
@@ -4752,6 +4752,18 @@ section:
     description: Fine root mass content
     type: real
     units: g m-2
+  - name: friction_temperature
+    description: Friction temperature, a.k.a. temperature scale
+    type: real
+    units: K
+  - name: friction_velocity
+    description: Friction velocity
+    type: real
+    units: m s-1
+  - name: friction_velocity_for_momentum
+    description: Friction velocity for momentum
+    type: real
+    units: m s-1
   - name: frozen_precipitation_density
     description: Frozen precipitation density
     type: real
@@ -4918,22 +4930,6 @@ section:
     description: Sea ice thickness
     type: real
     units: m
-  - name: surface_skin_temperature_over_ice
-    description: Surface skin temperature over (or where) ice
-    type: real
-    units: K
-  - name: surface_skin_temperature_over_land
-    description: Surface skin temperature over (or where) land
-    type: real
-    units: K
-  - name: surface_skin_temperature_over_ocean
-    description: Surface skin temperatura over (or where) ocean
-    type: real
-    units: K
-  - name: surface_skin_temperature_over_snow
-    description: Surface skin temperature over (or where) snow
-    type: real
-    units: K
   - name: slow_soil_pool_mass_content_of_carbon
     cfname: slow_soil_pool_mass_content_of_carbon
     description: Slow soil pool mass content of carbon
@@ -4989,14 +4985,6 @@ section:
       angle
     type: real
     units: fraction
-  - name: friction_velocity
-    description: Friction velocity
-    type: real
-    units: m s-1
-  - name: friction_velocity_for_momentum
-    description: Friction velocity for momentum
-    type: real
-    units: m s-1
   - name: surface_longwave_emissivity
     cfname: surface_longwave_emissivity
     description: Surface longwave emissivity
@@ -5014,6 +5002,22 @@ section:
     description: Surface sensible heat due to rainfall
     type: real
     units: W
+  - name: surface_skin_temperature_over_ice
+    description: Surface skin temperature over (or where) ice
+    type: real
+    units: K
+  - name: surface_skin_temperature_over_land
+    description: Surface skin temperature over (or where) land
+    type: real
+    units: K
+  - name: surface_skin_temperature_over_ocean
+    description: Surface skin temperatura over (or where) ocean
+    type: real
+    units: K
+  - name: surface_skin_temperature_over_snow
+    description: Surface skin temperature over (or where) snow
+    type: real
+    units: K
   - name: surface_snow_mass_content_over_ice
     description: Surface snow mass content over ice
     type: real
@@ -5026,10 +5030,6 @@ section:
     description: Surface sw fluxes assuming total and clear sky on radiation timestep
     type: ddt
     units: W m-2
-  - name: friction_temperature
-    description: Friction temperature, a.k.a. temperature scale
-    type: real
-    units: K
   - name: temperature_in_ice_layer
     description: Temperature in ice layer
     type: real
diff --git a/StandardNamesRules.rst b/StandardNamesRules.rst
index bbba40f..22e5ceb 100644
--- a/StandardNamesRules.rst
+++ b/StandardNamesRules.rst
@@ -154,6 +154,18 @@ Terminology
    *  ``[variable]_at_surface_adjacent_layer`` is the bottom layer of the atmospheric model
    *  ``[variable]_at_[level]`` for variables defined at specific height above the surface, e.g. ``temperature_at_2m``, ``wind_at_10m``
 
+#. By default, `water` refers to all types of water in any phase (e.g. solid, liquid, gas,
+   fresh water, salt water, etc.). The terms `sea` and `ocean` are synonymous, though new names
+   should default to using `ocean` unless part of one of the following phrases:
+   * sea_water
+   * sea_ice
+   * sea_level
+   * sea_salt
+   * sea_surface
+   * sea_floor
+   * sea_binary_mask
+   * sea_area 
+
 #. 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
diff --git a/standard_names.xml b/standard_names.xml
index 2e4f831..0b66315 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -2786,7 +2786,7 @@
     <standard_name name="cloud_phase_transition_threshold_temperature">
       <type units="K">real</type>
     </standard_name>
-    <standard_name name="lower_bound_for_depth_of_sea_temperature_for_nsstm" description="Lower bound for depth of sea temperature for GFS near-surface sea temperature scheme">
+    <standard_name name="lower_bound_for_depth_of_ocean_temperature_for_nsstm" description="Lower bound for depth of sea temperature for GFS near-surface sea temperature scheme">
       <type units="mm">integer</type>
     </standard_name>
     <standard_name name="max_critical_relative_humidity" description="Maximum critical relative humidity">
@@ -2846,7 +2846,7 @@
     <standard_name name="sigma_pressure_threshold_at_upper_extent_of_background_diffusion">
       <type units="1">real</type>
     </standard_name>
-    <standard_name name="upper_bound_for_depth_of_sea_temperature_for_nsstm" description="Upper bound for depth of sea temperature for GFS near-surface sea temperature scheme">
+    <standard_name name="upper_bound_for_depth_of_ocean_temperature_for_nsstm" description="Upper bound for depth of sea temperature for GFS near-surface sea temperature scheme">
       <type units="mm">integer</type>
     </standard_name>
   </section>

From ca4b78eb7255f22ca8477e1833c569f5aee9e199 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 09:10:37 -0600
Subject: [PATCH 09/21] Missed one abbreviation in description

---
 Metadata-standard-names.md   | 2 +-
 Metadata-standard-names.yaml | 2 +-
 standard_names.xml           | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Metadata-standard-names.md b/Metadata-standard-names.md
index d0ea6ec..e30da85 100644
--- a/Metadata-standard-names.md
+++ b/Metadata-standard-names.md
@@ -1313,7 +1313,7 @@ Variables that indicate or control some action.
     * `real`: units = 1
 * `control_for_vegetation_dataset`: Control for vegetation dataset
     * `integer`: units = 1
-* `control_for_vertical_index_direction`: control flag for direction of vertical index; 0 indicates index from top of atmosphere to surface, 1 indicates index from surface to toa
+* `control_for_vertical_index_direction`: control flag for direction of vertical index; 0 indicates index from top-of-atmosphere to surface, 1 indicates index from surface to top-of-atmosphere
     * `integer`: units = 1
 * `do_aerosol_physics`: Do aerosol physics
     * `logical`: units = flag
diff --git a/Metadata-standard-names.yaml b/Metadata-standard-names.yaml
index c2ad91b..62e8cf7 100644
--- a/Metadata-standard-names.yaml
+++ b/Metadata-standard-names.yaml
@@ -2671,7 +2671,7 @@ section:
     units: 1
   - name: control_for_vertical_index_direction
     description: control flag for direction of vertical index; 0 indicates index from
-      top of atmosphere to surface, 1 indicates index from surface to toa
+      top-of-atmosphere to surface, 1 indicates index from surface to top-of-atmosphere
     type: integer
     units: 1
   - name: do_aerosol_physics
diff --git a/standard_names.xml b/standard_names.xml
index 0b66315..177ee86 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -1916,7 +1916,7 @@
     <standard_name name="control_for_vegetation_dataset">
       <type units="1">integer</type>
     </standard_name>
-    <standard_name name="control_for_vertical_index_direction" description="control flag for direction of vertical index; 0 indicates index from top of atmosphere to surface, 1 indicates index from surface to toa">
+    <standard_name name="control_for_vertical_index_direction" description="control flag for direction of vertical index; 0 indicates index from top-of-atmosphere to surface, 1 indicates index from surface to top-of-atmosphere">
       <type units="1">integer</type>
     </standard_name>
     <standard_name name="do_aerosol_physics">

From 23d782dcff121395f0528603f8012817a5e24c50 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 09:23:06 -0600
Subject: [PATCH 10/21] Remove duplicate "friction_velocity" entry, clarify
 description of base name

---
 Metadata-standard-names.md   | 4 +---
 Metadata-standard-names.yaml | 8 ++------
 standard_names.xml           | 5 +----
 3 files changed, 4 insertions(+), 13 deletions(-)

diff --git a/Metadata-standard-names.md b/Metadata-standard-names.md
index e30da85..38a6e31 100644
--- a/Metadata-standard-names.md
+++ b/Metadata-standard-names.md
@@ -195,7 +195,7 @@ These names are used as bases for other names, but may also be considered standa
     * `character`: units = none
 * `forecast_time`: Forecast time
     * `real`: units = h
-* `friction_velocity`: A measure of shear stress within a fluid layer with units of distance per time
+* `friction_velocity`: A measure of shear stress within a fluid layer due to friction against a surface, with units of distance per time
     * `real`: units = m s-1
 * `geopotential`: Gravitational potential energy of a unit mass relative to sea level
     * Equivalent CF name: `geopotential`
@@ -2282,8 +2282,6 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = g m-2
 * `friction_temperature`: Friction temperature, a.k.a. temperature scale
     * `real`: units = K
-* `friction_velocity`: Friction velocity
-    * `real`: units = m s-1
 * `friction_velocity_for_momentum`: Friction velocity for momentum
     * `real`: units = m s-1
 * `frozen_precipitation_density`: Frozen precipitation density
diff --git a/Metadata-standard-names.yaml b/Metadata-standard-names.yaml
index 62e8cf7..7e55311 100644
--- a/Metadata-standard-names.yaml
+++ b/Metadata-standard-names.yaml
@@ -355,8 +355,8 @@ section:
       type: real
       units: h
     - name: friction_velocity
-      description: A measure of shear stress within a fluid layer with units of distance
-        per time
+      description: A measure of shear stress within a fluid layer due to friction
+        against a surface, with units of distance per time
       type: real
       units: m s-1
     - name: geopotential
@@ -4756,10 +4756,6 @@ section:
     description: Friction temperature, a.k.a. temperature scale
     type: real
     units: K
-  - name: friction_velocity
-    description: Friction velocity
-    type: real
-    units: m s-1
   - name: friction_velocity_for_momentum
     description: Friction velocity for momentum
     type: real
diff --git a/standard_names.xml b/standard_names.xml
index 177ee86..55226e1 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -262,7 +262,7 @@
       <standard_name name="forecast_time">
         <type units="h">real</type>
       </standard_name>
-      <standard_name name="friction_velocity" description="A measure of shear stress within a fluid layer with units of distance per time">
+      <standard_name name="friction_velocity" description="A measure of shear stress within a fluid layer due to friction against a surface, with units of distance per time">
         <type units="m s-1">real</type>
       </standard_name>
       <standard_name name="geopotential" description="Gravitational potential energy of a unit mass relative to sea level">
@@ -3366,9 +3366,6 @@
     <standard_name name="friction_temperature" description="Friction temperature, a.k.a. temperature scale" comment="Defined in Olson et al. 2021 'A Description of the MYNN Surface-Layer Scheme' as negative sensible heat flux divided by the product of density, specific heat Cp, and friction velocity u*">
       <type units="K">real</type>
     </standard_name>
-    <standard_name name="friction_velocity">
-      <type units="m s-1">real</type>
-    </standard_name>
     <standard_name name="friction_velocity_for_momentum">
       <type units="m s-1">real</type>
     </standard_name>

From 3a2f92cf30228121bd6a39bebd5f4cbe9805df47 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 13:01:24 -0600
Subject: [PATCH 11/21] More clarity and additional "skin temperature"
 definitions

---
 Metadata-standard-names.md   |  5 +++++
 Metadata-standard-names.yaml | 11 +++++++++++
 StandardNamesRules.rst       |  5 +++++
 standard_names.xml           |  9 ++++++++-
 4 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/Metadata-standard-names.md b/Metadata-standard-names.md
index 38a6e31..5cd6878 100644
--- a/Metadata-standard-names.md
+++ b/Metadata-standard-names.md
@@ -655,6 +655,9 @@ Variables defining or relating to timing, dates, calendar, and related concepts
     * `real`: units = m
 * `reference_sea_surface_temperature`: Foundation/reference temperature for calculating diurnal ocean temperature changes
     * `real`: units = K
+* `sea_surface_skin_temperature`: The temperature of the upper layer of sea surface, typically ~10-100 micrometers, as measured by an infrared radiometer
+    * Equivalent CF name: `sea_surface_skin_temperature`
+    * `real`: units = K
 * `sea_surface_temperature`: Sea surface temperature
     * Equivalent CF name: `sea_surface_temperature`
     * `real`: units = K
@@ -2097,6 +2100,8 @@ Thresholds represent some value at which the behavior of some process changes, i
     * `real`: units = W m-2
 * `sine_of_solar_declination_angle`: Sine of solar declination angle
     * `real`: units = 1
+* `skin_temperature_at_toa`: The temperature that a theoretical infinitely thin air layer above the atmosphere would have in radiative equilibrium
+    * `real`: units = K
 * `solar_constant`: Solar constant
     * `real`: units = W m-2
 * `upwelling_diffuse_nir_shortwave_flux_at_surface_on_radiation_timestep`: upwelling diffuse near-infrared shortwave flux at the surface level on the radiation timestep
diff --git a/Metadata-standard-names.yaml b/Metadata-standard-names.yaml
index 7e55311..732bf1f 100644
--- a/Metadata-standard-names.yaml
+++ b/Metadata-standard-names.yaml
@@ -1287,6 +1287,12 @@ section:
       changes
     type: real
     units: K
+  - name: sea_surface_skin_temperature
+    cfname: sea_surface_skin_temperature
+    description: The temperature of the upper layer of sea surface, typically ~10-100
+      micrometers, as measured by an infrared radiometer
+    type: real
+    units: K
   - name: sea_surface_temperature
     cfname: sea_surface_temperature
     description: Sea surface temperature
@@ -4367,6 +4373,11 @@ section:
     description: Sine of solar declination angle
     type: real
     units: 1
+  - name: skin_temperature_at_toa
+    description: The temperature that a theoretical infinitely thin air layer above
+      the atmosphere would have in radiative equilibrium
+    type: real
+    units: K
   - name: solar_constant
     description: Solar constant
     type: real
diff --git a/StandardNamesRules.rst b/StandardNamesRules.rst
index 22e5ceb..b85ff45 100644
--- a/StandardNamesRules.rst
+++ b/StandardNamesRules.rst
@@ -154,6 +154,11 @@ Terminology
    *  ``[variable]_at_surface_adjacent_layer`` is the bottom layer of the atmospheric model
    *  ``[variable]_at_[level]`` for variables defined at specific height above the surface, e.g. ``temperature_at_2m``, ``wind_at_10m``
 
+   Note that some commonly used terms with a prefix ``surface_`` are unavoidable due to the common
+   definition being fundamentally different from unqualified ``X``. For example, ``surface_skin_temperature``
+   is a fundamentally different quantity than the unqualified ``skin_temperature``. In cases such as these,
+   a comment should be included noting this special usage of the word "surface".
+
 #. By default, `water` refers to all types of water in any phase (e.g. solid, liquid, gas,
    fresh water, salt water, etc.). The terms `sea` and `ocean` are synonymous, though new names
    should default to using `ocean` unless part of one of the following phrases:
diff --git a/standard_names.xml b/standard_names.xml
index 55226e1..b6575c3 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -338,7 +338,7 @@
         <cfname>solar_zenith_angle</cfname>
         <type units="degrees">real</type>
       </standard_name>
-      <standard_name name="surface_skin_temperature" description="The temperature of the interface of the surface and the atmosphere" comment="Usage of the term 'surface skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'surface_skin_temperature': the temperature of the interface of the atmosphere and the surface below. This may be considered equivalent to the radiometric temperature derived from satellite or airborne radiometers, provided a known surface_emissivity. This definition derives from discussion in Chapter 4 of 'Introduction to Micrometeorology' by S. Pal Arya.">
+      <standard_name name="surface_skin_temperature" description="The temperature of the interface of the surface and the atmosphere" comment="Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'surface_skin_temperature': the temperature of the interface of the atmosphere and the surface below. This may be considered equivalent to the radiometric temperature derived from satellite or airborne radiometers, provided a known surface_emissivity, though for water specifically there may be special considerations for measured quantities (see comment on 'sea_surface_skin_temperature'). This definition derives from discussion in Chapter 4 of 'Introduction to Micrometeorology' by S. Pal Arya. This quantity should not be confused with 'skin_temperature_at_toa' or 'sea_surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.">
         <cfname>surface_skin_temperature</cfname>
         <type units="K">real</type>
       </standard_name>
@@ -942,6 +942,10 @@
     <standard_name name="reference_sea_surface_temperature" description="Foundation/reference temperature for calculating diurnal ocean temperature changes">
       <type units="K">real</type>
     </standard_name>
+    <standard_name name="sea_surface_skin_temperature" description="The temperature of the upper layer of sea surface, typically ~10-100 micrometers, as measured by an infrared radiometer" comment="Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'sea_surface_skin_temperature', derived from the CF Standard Names. While there may be some dependence on the IR wavelength used for a measurement, per Donlon et al. (2002) 'Toward Improved Validation of Satellite Sea Surface Skin Temperature Measurements for Climate Research', the difference should not be significant. This quantity should not be confused with 'skin_temperature_at_toa' or 'surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.">
+      <cfname>sea_surface_skin_temperature</cfname>
+      <type units="K">real</type>
+    </standard_name>
     <standard_name name="sea_surface_temperature">
       <cfname>sea_surface_temperature</cfname>
       <type units="K">real</type>
@@ -3090,6 +3094,9 @@
     <standard_name name="sine_of_solar_declination_angle">
       <type units="1">real</type>
     </standard_name>
+    <standard_name name="skin_temperature_at_toa" description="The temperature that a theoretical infinitely thin air layer above the atmosphere would have in radiative equilibrium" comment="Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'skin_temperature_at_toa', which is commonly referred to as simply 'skin_temperature' but top-of-atmosphere is included in the name for clarity and disambiguation. This definition is taken directly from Goessling and  Bathiany (2016) 'Why CO2 cools the middle atmosphere – a consolidating model perspective', but very similar definitions can be found broadly in the literature. This quantity should not be confused with 'surface_skin_temperature' or 'sea_surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.">
+      <type units="K">real</type>
+    </standard_name>
     <standard_name name="solar_constant">
       <type units="W m-2">real</type>
     </standard_name>

From 36899d195b1e5f4dff5c0674f97e51470ff637f1 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 13:04:09 -0600
Subject: [PATCH 12/21] Fix non-ASCII character

---
 standard_names.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/standard_names.xml b/standard_names.xml
index b6575c3..6792042 100644
--- a/standard_names.xml
+++ b/standard_names.xml
@@ -3094,7 +3094,7 @@
     <standard_name name="sine_of_solar_declination_angle">
       <type units="1">real</type>
     </standard_name>
-    <standard_name name="skin_temperature_at_toa" description="The temperature that a theoretical infinitely thin air layer above the atmosphere would have in radiative equilibrium" comment="Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'skin_temperature_at_toa', which is commonly referred to as simply 'skin_temperature' but top-of-atmosphere is included in the name for clarity and disambiguation. This definition is taken directly from Goessling and  Bathiany (2016) 'Why CO2 cools the middle atmosphere – a consolidating model perspective', but very similar definitions can be found broadly in the literature. This quantity should not be confused with 'surface_skin_temperature' or 'sea_surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.">
+    <standard_name name="skin_temperature_at_toa" description="The temperature that a theoretical infinitely thin air layer above the atmosphere would have in radiative equilibrium" comment="Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'skin_temperature_at_toa', which is commonly referred to as simply 'skin_temperature' but top-of-atmosphere is included in the name for clarity and disambiguation. This definition is taken directly from Goessling and  Bathiany (2016) 'Why CO2 cools the middle atmosphere - a consolidating model perspective', but very similar definitions can be found broadly in the literature. This quantity should not be confused with 'surface_skin_temperature' or 'sea_surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.">
       <type units="K">real</type>
     </standard_name>
     <standard_name name="solar_constant">

From efce0411ccbb5fb0d88c8e94dde96a0ea136429d Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 13:13:54 -0600
Subject: [PATCH 13/21] Fix abandoned sentence fragment

---
 StandardNamesRules.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/StandardNamesRules.rst b/StandardNamesRules.rst
index b85ff45..97a2227 100644
--- a/StandardNamesRules.rst
+++ b/StandardNamesRules.rst
@@ -141,7 +141,9 @@ Terminology
 
    `annotated image detailing some of the terminology in this section <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_terms.png>`_
 
-#. A "layer" is a vertical level of a model. A variable for a given layer is either at the vertical centerpoint of a level, or the vertical average of a level, as defined by the host (see above). An "interface" is the boundary above or below a layer. A variable specified at a given interface
+#. A "layer" is a vertical level of a model. A variable for a given layer is either at the vertical
+   centerpoint of a level, or the vertical average of a level, as defined by the host (see above).
+   An "interface" is the boundary above or below a layer.
 
 #. By default, *surface* refers to the liquid or solid substance immediately beneath the atmosphere
    for a given vertical column. This can be land, ocean, ice, lake, etc.

From 2805c26a90f15f234f83d40bd35b7524c5f349f6 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 15:08:05 -0600
Subject: [PATCH 14/21] Fix write_standard_name_table.py to write comments for
 standard_name entries

---
 Metadata-standard-names.md         |  8 +++++
 Metadata-standard-names.yaml       | 52 ++++++++++++++++++++++++++++++
 tools/write_standard_name_table.py |  7 +++-
 3 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/Metadata-standard-names.md b/Metadata-standard-names.md
index 5cd6878..5360554 100644
--- a/Metadata-standard-names.md
+++ b/Metadata-standard-names.md
@@ -64,6 +64,7 @@ The following names are too general to be chosen as standard names, but they can
 * `mass_transport`: Movement of some specified mass by advection
     * `real`: units = kg s-1
 * `mixing_ratio`: A ratio of the amount of one substance to another; when unqualified refers to the ratio of the mass of one substance to the total mass in a given volume
+* `comment`: See Standard Name Rules for further details about disambiguation of this term
     * `real`: units = kg kg-1
 * `mole_flux`: The number of molecules or atoms of a substance traveling through an area per unit time
     * `real`: units = mol m-2 s-1
@@ -173,6 +174,7 @@ These names are used as bases for other names, but may also be considered standa
 * `diffuse_vis_albedo`: Albedo of diffuse incident visible radiation
     * `real`: units = 1
 * `dimensionless_exner_function`: Dimensionless formulation of the Exner function with respect to 1000 hPa
+* `comment`: The formulation of the exner function in an NWP context is (p/p0)^(Rd/cp), where p0 is some reference pressure. For the purposes of the standard names, this reference pressure is assumed as 1000 hPa unless specified otherwise; i.e. dimensionless_exner_function_wrt_air_pressure_at_surface would use the surface pressure as P0. Note that this is numerically equivalent to T/theta (temperature divided by potential temperature), where again theta is calculated with respect to 1000 hPa if not specified. Note that this definition is distinct from the dimensional exner_function standard name; see that entry for further comments. 
     * Equivalent CF name: `dimensionless_exner_function`
     * `real`: units = 1
 * `direct_nir_albedo`: Albedo of direct incident near-infrared radiation
@@ -190,6 +192,7 @@ These names are used as bases for other names, but may also be considered standa
 * `dry_air_enthalpy_at_constant_pressure`: Specific enthalpy of dry air, h = Cp*T; Cp = Specific heat of dry air at constant pressure, T = temperature
     * `real`: units = J kg-1
 * `exner_function`: Exner function, cp * (p/p0)^(Rd/cp), where p0 is some reference pressure (1000 hPa if not specified), Rd is the dry air specific gas constant, and cp is the dry air specific heat capacity.
+* `comment`: The formulation for the exner function comes in two forms: a dimensional form cp * (p/p0)^(Rd/cp) = cp * (T/theta), and a dimensionless form (p/p0)^(Rd/cp) = (T/theta). In the standard names, we use the unqualified exner_function to refer to the dimensional form, and dimensionless_exner_function to refer to the dimensionless form. See the base name entry for dimensionless_exner_function for further comments.
     * `real`: units = 1
 * `filename`: Filename
     * `character`: units = none
@@ -246,6 +249,7 @@ These names are used as bases for other names, but may also be considered standa
     * Equivalent CF name: `solar_zenith_angle`
     * `real`: units = degrees
 * `surface_skin_temperature`: The temperature of the interface of the surface and the atmosphere
+* `comment`: Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'surface_skin_temperature': the temperature of the interface of the atmosphere and the surface below. This may be considered equivalent to the radiometric temperature derived from satellite or airborne radiometers, provided a known surface_emissivity, though for water specifically there may be special considerations for measured quantities (see comment on 'sea_surface_skin_temperature'). This definition derives from discussion in Chapter 4 of 'Introduction to Micrometeorology' by S. Pal Arya. This quantity should not be confused with 'skin_temperature_at_toa' or 'sea_surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.
     * Equivalent CF name: `surface_skin_temperature`
     * `real`: units = K
 * `temperature_flux`: Flux of temperature across a unit surface
@@ -273,6 +277,7 @@ These names are used as bases for other names, but may also be considered standa
 ## Dimensions
 Names indicating the size, extent, or bounds of data structures in a model.
 * `horizontal_dimension`: Length of the horizontal dimension
+* `comment`: In CCPP, horizontal_dimension refers to all horizontal grid columns that an MPI process owns/is responsible for
     * `integer`: units = count
 * `horizontal_loop_extent`: The horizontal extent of data passed to CCPP physics from the host model during time integration (i.e. in the *run* phase)
     * `integer`: units = count
@@ -656,6 +661,7 @@ Variables defining or relating to timing, dates, calendar, and related concepts
 * `reference_sea_surface_temperature`: Foundation/reference temperature for calculating diurnal ocean temperature changes
     * `real`: units = K
 * `sea_surface_skin_temperature`: The temperature of the upper layer of sea surface, typically ~10-100 micrometers, as measured by an infrared radiometer
+* `comment`: Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'sea_surface_skin_temperature', derived from the CF Standard Names. While there may be some dependence on the IR wavelength used for a measurement, per Donlon et al. (2002) 'Toward Improved Validation of Satellite Sea Surface Skin Temperature Measurements for Climate Research', the difference should not be significant. This quantity should not be confused with 'skin_temperature_at_toa' or 'surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.
     * Equivalent CF name: `sea_surface_skin_temperature`
     * `real`: units = K
 * `sea_surface_temperature`: Sea surface temperature
@@ -2101,6 +2107,7 @@ Thresholds represent some value at which the behavior of some process changes, i
 * `sine_of_solar_declination_angle`: Sine of solar declination angle
     * `real`: units = 1
 * `skin_temperature_at_toa`: The temperature that a theoretical infinitely thin air layer above the atmosphere would have in radiative equilibrium
+* `comment`: Usage of the term 'skin temperature' varies among different fields in the literature. In the Standard Names we have adopted what we deem the most common definition for 'skin_temperature_at_toa', which is commonly referred to as simply 'skin_temperature' but top-of-atmosphere is included in the name for clarity and disambiguation. This definition is taken directly from Goessling and  Bathiany (2016) 'Why CO2 cools the middle atmosphere - a consolidating model perspective', but very similar definitions can be found broadly in the literature. This quantity should not be confused with 'surface_skin_temperature' or 'sea_surface_skin_temperature', which are both sometimes referred to simply as 'skin_temperature'.
     * `real`: units = K
 * `solar_constant`: Solar constant
     * `real`: units = W m-2
@@ -2286,6 +2293,7 @@ Thresholds represent some value at which the behavior of some process changes, i
 * `fine_root_mass_content`: Fine root mass content
     * `real`: units = g m-2
 * `friction_temperature`: Friction temperature, a.k.a. temperature scale
+* `comment`: Defined in Olson et al. 2021 'A Description of the MYNN Surface-Layer Scheme' as negative sensible heat flux divided by the product of density, specific heat Cp, and friction velocity u*
     * `real`: units = K
 * `friction_velocity_for_momentum`: Friction velocity for momentum
     * `real`: units = m s-1
diff --git a/Metadata-standard-names.yaml b/Metadata-standard-names.yaml
index 732bf1f..c3f56d5 100644
--- a/Metadata-standard-names.yaml
+++ b/Metadata-standard-names.yaml
@@ -84,6 +84,8 @@ section:
       description: A ratio of the amount of one substance to another; when unqualified
         refers to the ratio of the mass of one substance to the total mass in a given
         volume
+      comment: See Standard Name Rules for further details about disambiguation of
+        this term
       type: real
       units: kg kg-1
     - name: mole_flux
@@ -309,6 +311,15 @@ section:
       cfname: dimensionless_exner_function
       description: Dimensionless formulation of the Exner function with respect to
         1000 hPa
+      comment: 'The formulation of the exner function in an NWP context is (p/p0)^(Rd/cp),
+        where p0 is some reference pressure. For the purposes of the standard names,
+        this reference pressure is assumed as 1000 hPa unless specified otherwise;
+        i.e. dimensionless_exner_function_wrt_air_pressure_at_surface would use the
+        surface pressure as P0. Note that this is numerically equivalent to T/theta
+        (temperature divided by potential temperature), where again theta is calculated
+        with respect to 1000 hPa if not specified. Note that this definition is distinct
+        from the dimensional exner_function standard name; see that entry for further
+        comments. '
       type: real
       units: 1
     - name: direct_nir_albedo
@@ -344,6 +355,12 @@ section:
       description: Exner function, cp * (p/p0)^(Rd/cp), where p0 is some reference
         pressure (1000 hPa if not specified), Rd is the dry air specific gas constant,
         and cp is the dry air specific heat capacity.
+      comment: 'The formulation for the exner function comes in two forms: a dimensional
+        form cp * (p/p0)^(Rd/cp) = cp * (T/theta), and a dimensionless form (p/p0)^(Rd/cp)
+        = (T/theta). In the standard names, we use the unqualified exner_function
+        to refer to the dimensional form, and dimensionless_exner_function to refer
+        to the dimensionless form. See the base name entry for dimensionless_exner_function
+        for further comments.'
       type: real
       units: 1
     - name: filename
@@ -458,6 +475,17 @@ section:
     - name: surface_skin_temperature
       cfname: surface_skin_temperature
       description: The temperature of the interface of the surface and the atmosphere
+      comment: 'Usage of the term ''skin temperature'' varies among different fields
+        in the literature. In the Standard Names we have adopted what we deem the
+        most common definition for ''surface_skin_temperature'': the temperature of
+        the interface of the atmosphere and the surface below. This may be considered
+        equivalent to the radiometric temperature derived from satellite or airborne
+        radiometers, provided a known surface_emissivity, though for water specifically
+        there may be special considerations for measured quantities (see comment on
+        ''sea_surface_skin_temperature''). This definition derives from discussion
+        in Chapter 4 of ''Introduction to Micrometeorology'' by S. Pal Arya. This
+        quantity should not be confused with ''skin_temperature_at_toa'' or ''sea_surface_skin_temperature'',
+        which are both sometimes referred to simply as ''skin_temperature''.'
       type: real
       units: K
     - name: temperature_flux
@@ -509,6 +537,8 @@ section:
   standard_names:
   - name: horizontal_dimension
     description: Length of the horizontal dimension
+    comment: In CCPP, horizontal_dimension refers to all horizontal grid columns that
+      an MPI process owns/is responsible for
     type: integer
     units: count
   - name: horizontal_loop_extent
@@ -1291,6 +1321,15 @@ section:
     cfname: sea_surface_skin_temperature
     description: The temperature of the upper layer of sea surface, typically ~10-100
       micrometers, as measured by an infrared radiometer
+    comment: Usage of the term 'skin temperature' varies among different fields in
+      the literature. In the Standard Names we have adopted what we deem the most
+      common definition for 'sea_surface_skin_temperature', derived from the CF Standard
+      Names. While there may be some dependence on the IR wavelength used for a measurement,
+      per Donlon et al. (2002) 'Toward Improved Validation of Satellite Sea Surface
+      Skin Temperature Measurements for Climate Research', the difference should not
+      be significant. This quantity should not be confused with 'skin_temperature_at_toa'
+      or 'surface_skin_temperature', which are both sometimes referred to simply as
+      'skin_temperature'.
     type: real
     units: K
   - name: sea_surface_temperature
@@ -4376,6 +4415,16 @@ section:
   - name: skin_temperature_at_toa
     description: The temperature that a theoretical infinitely thin air layer above
       the atmosphere would have in radiative equilibrium
+    comment: Usage of the term 'skin temperature' varies among different fields in
+      the literature. In the Standard Names we have adopted what we deem the most
+      common definition for 'skin_temperature_at_toa', which is commonly referred
+      to as simply 'skin_temperature' but top-of-atmosphere is included in the name
+      for clarity and disambiguation. This definition is taken directly from Goessling
+      and  Bathiany (2016) 'Why CO2 cools the middle atmosphere - a consolidating
+      model perspective', but very similar definitions can be found broadly in the
+      literature. This quantity should not be confused with 'surface_skin_temperature'
+      or 'sea_surface_skin_temperature', which are both sometimes referred to simply
+      as 'skin_temperature'.
     type: real
     units: K
   - name: solar_constant
@@ -4765,6 +4814,9 @@ section:
     units: g m-2
   - name: friction_temperature
     description: Friction temperature, a.k.a. temperature scale
+    comment: Defined in Olson et al. 2021 'A Description of the MYNN Surface-Layer
+      Scheme' as negative sensible heat flux divided by the product of density, specific
+      heat Cp, and friction velocity u*
     type: real
     units: K
   - name: friction_velocity_for_momentum
diff --git a/tools/write_standard_name_table.py b/tools/write_standard_name_table.py
index 72a5f80..526c936 100755
--- a/tools/write_standard_name_table.py
+++ b/tools/write_standard_name_table.py
@@ -135,10 +135,13 @@ def parse_section(snl, sec, level='##'):
             continue
         stdn_name = std_name.get('name')
         stdn_description = std_name.get('description')
+        stdn_comment = std_name.get('comment')
         if stdn_description is None:
             sdict = {'standard_name': stdn_name}
             stdn_description = standard_name_to_description(sdict)
         snl.write(f"* `{stdn_name}`: {stdn_description}\n")
+        if stdn_comment is not None:
+            snl.write(f"* `comment`: {stdn_comment}\n")
         # Should only be type or cfname as subelements of standard_name
         for item in std_name:
             if item.tag == 'cfname':
@@ -194,12 +197,14 @@ def parse_section_for_yaml(section):
             stdn_description = standard_name_to_description(sdict)
 
         std_type = std_name.find('type')
-
+        std_comment = std_name.get('comment')
         std_name_data = OrderedDict()
         std_name_data['name'] = stdn_name
         if stdn_cfname:
             std_name_data['cfname'] = stdn_cfname
         std_name_data['description'] = stdn_description
+        if std_comment is not None:
+            std_name_data['comment'] = std_comment
         if std_type is not None:
             std_name_data['type'] = std_type.text
 

From cef758f8c47bef7cbbb42c5f2bf15b86c022e90d Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 15:22:45 -0600
Subject: [PATCH 15/21] Reorganize StandardNamesRules.rst into a chaptered
 Sphinx/ReadTheDocs site

Splits the single StandardNamesRules.rst file verbatim into per-chapter
files under docs/chapters/, adds Sphinx scaffolding (conf.py, index.rst,
requirements.txt) and a top-level .readthedocs.yaml so the rules can be
built and published on Read the Docs. StandardNamesRules.rst is replaced
with a stub pointing to the new docs/ location, and README.md is updated
to match.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .gitignore                                 |   1 +
 .readthedocs.yaml                          |  17 +
 README.md                                  |   5 +-
 StandardNamesRules.rst                     | 743 +--------------------
 docs/_static/.gitkeep                      |   0
 docs/chapters/aliases.rst                  |  67 ++
 docs/chapters/common_components.rst        |  57 ++
 docs/chapters/naming_rules.rst             | 245 +++++++
 docs/chapters/qualifiers.rst               | 261 ++++++++
 docs/chapters/technical_specifications.rst |  45 ++
 docs/chapters/units.rst                    |  38 ++
 docs/conf.py                               |  18 +
 docs/index.rst                             |  28 +
 docs/requirements.txt                      |   2 +
 14 files changed, 798 insertions(+), 729 deletions(-)
 create mode 100644 .readthedocs.yaml
 create mode 100644 docs/_static/.gitkeep
 create mode 100644 docs/chapters/aliases.rst
 create mode 100644 docs/chapters/common_components.rst
 create mode 100644 docs/chapters/naming_rules.rst
 create mode 100644 docs/chapters/qualifiers.rst
 create mode 100644 docs/chapters/technical_specifications.rst
 create mode 100644 docs/chapters/units.rst
 create mode 100644 docs/conf.py
 create mode 100644 docs/index.rst
 create mode 100644 docs/requirements.txt

diff --git a/.gitignore b/.gitignore
index 0d20b64..073067c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 *.pyc
+docs/_build/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 0000000..0f4624e
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,17 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
diff --git a/README.md b/README.md
index f7bf2e1..2f7f352 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,10 @@
 
 The Earth System Modeling Standard Names Repository contains community-accepted Standard Names, publishing tools, and search tools.
 
-Rules governing the designation and format of standard names can be found in [StandardNamesRules.rst](https://github.com/ESCOMP/ESMStandardNames/blob/main/StandardNamesRules.rst).
+Rules governing the designation and format of standard names are published as a chaptered
+Sphinx/Read the Docs site built from the [docs/](docs/) directory; see
+[docs/index.rst](https://github.com/ESCOMP/ESMStandardNames/blob/main/docs/index.rst) for the
+table of contents, or build it locally with `sphinx-build -b html docs docs/_build/html`.
 
 A [Markdown file describing the standard names is included](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.md), as well as a [YAML version of the XML file](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.yaml).
 
diff --git a/StandardNamesRules.rst b/StandardNamesRules.rst
index 97a2227..a5bc6a5 100644
--- a/StandardNamesRules.rst
+++ b/StandardNamesRules.rst
@@ -1,733 +1,20 @@
-.. # define a hard line break for HTML
-.. |br| raw:: html
+Standard Name Rules Have Moved
+===============================
 
-   <br />
+The ESM Standard Name rules have moved into a proper `Sphinx <https://www.sphinx-doc.org/>`_
+documentation set, built by `Read the Docs <https://readthedocs.org/>`_, so that they can be
+organized into browsable chapters instead of one long file.
 
-*******************
-Earth System Modeling (ESM) Standard Names
-*******************
+The source for the rules now lives under `docs/chapters/ <docs/chapters/>`_ in this repository:
 
-This document contains information about the rules used to create Standard Names
-for use with Earth System Models. It describes the
+* `docs/chapters/naming_rules.rst <docs/chapters/naming_rules.rst>`_ -- ESM Standard Name rules
+* `docs/chapters/technical_specifications.rst <docs/chapters/technical_specifications.rst>`_ -- Technical specifications
+* `docs/chapters/qualifiers.rst <docs/chapters/qualifiers.rst>`_ -- Qualifiers
+* `docs/chapters/common_components.rst <docs/chapters/common_components.rst>`_ -- Other common standard name components
+* `docs/chapters/aliases.rst <docs/chapters/aliases.rst>`_ -- Acronyms, abbreviations, and aliases
+* `docs/chapters/units.rst <docs/chapters/units.rst>`_ -- Units
 
-* ESM Standard Name rules
-* Standard Name qualifiers
-* Other common standard name components
-* Acronyms, abbreviations, and aliases
-* Units
+See `docs/index.rst <docs/index.rst>`_ for the table of contents, or build the docs locally with::
 
-.. _Rules
-
-ESM Standard Name Rules
-========================
-
-Constructing names
-------------------
-
-#. Standard names should be identical to those from the latest version
-   of the `Climate and Forecast (CF) metadata
-   conventions <https://cfconventions.org/standard-names.html>`_ unless
-   an appropriate name does not exist in that standard, or the adoption
-   of said names leads to inconsistencies in the naming convention.
-
-#. When no suitable standard name exists in the CF conventions, the following guidelines should be followed for constructing a new name.
-   The phrases in brackets are optional. The words in *italic* appear explicitly as stated,
-   while the words in ``this font`` indicate other words or phrases to be substituted.
-   The new standard name is constructed by joining the base standard name to the qualifiers using underscores.
-
-   [``transformation``] [``component``] [``non-instant time``] base_name [*in*/*of* ``medium``] [*at* ``level``] [*due_to* ``process``] [``non-current time``] [*assuming* ``condition``]
-
-   This construction was originally based on rules set forth in the
-   `CF guidelines <http://cfconventions.org/Data/cf-standard-names/docs/guidelines.html>`_,
-   but have since evolved for better consistency and generality across a broader set of fields
-   than was originally envisioned by the CF conventions. "``medium``" should be specified when
-   the variable in question is a substance or other quantity contained within some other medium
-   (e.g. for ``mole_fraction_of_ozone_in_air``, the base name is "ozone", while the medium is "air").
-   "Transformation" refers to descriptors such as "``tendency_of``", "``log10``", or other operations or processes describing some transformation or adjustment of a variable; a detailed list of possible transformations can be found `later in this document <#transformations>`_.
-   Other parts of the construction provide information about a variable's horizontal surface
-   (e.g. ``at_cloud_base``), component (i.e. direction of variable, e.g. ``downward``), process (e.g.
-   ``due_to_deep_convection``), or condition (e.g., ``assuming_clear_sky``). These qualifications do not
-   change the units of the quantity. This is not an exhaustive list of qualifiers that may be needed for a given standard name;
-   see subsequent rules below for more information.
-
-   The following table provides a few concrete examples of standard names and how they are constructed
-   with respect to the guideline template.
-
-   `image of table providing standard name construction examples <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_construction_examples.png>`_
-
-   Note that "transformations" are a special case, where multiple transformations may be applied,
-   and multiple quantities may be compared, operated on, etc. For transformations involving
-   multiple quantities (e.g. ``ratio_of_X_to_Y``; see the `section on Transformations <#transformations>`_
-   for more information), the above formula may be extended around multiple base names.
-
-   `image of table providing standard name construction examples with multiple transformations <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_transformation_examples.png>`_
-
-   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 ``description`` field to prevent any possible ambiguity.
-
-Variable scope
---------------
-
-#. Variables are current and instantaneous unless specified. Variables that are not
-   current (e.g., previous timestep) or non-instantaneous (e.g., accumulated values)
-   should have qualifiers in the standard name to describe what they represent.
-
-#. For accumulated variables, or variables representing a change over some period of time, the
-   following suffixes are available":
-
-   * ``over_[time]`` indicates an accumulation or other change over the previous duration/time
-   * ``reset_every_[date/time]`` an accumulation or other change reset every set duration/time
-     since the start of the simulation
-   * ``since_[date/time]`` indicates an accumulation or other change since a given date/time.
-
-   Dates, times, and durations should follow the `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`
-   international standard, modified only to use lowercase rather than uppercase letters. Note that
-   the standard is slightly different for dates and times vs durations. For example:
-
-   * ``accumulated_precipitation_over_pt3h`` accumulated precipitation over the last 3 hours
-   * ``accumulated_precipitation_over_p1dt12h`` accumulated precipitation over the last 1 day 12 hours
-   * ``accumulated_precipitation_reset_every_pt1h`` accumulated precipitation reset every 1 hour
-   * ``accumulated_precipitation_reset_every_p1y`` accumulated precipitation reset every 1 year
-   * ``accumulated_precipitation_reset_every_p2dt12h`` accumulated precipitation reset every 2 days, 12 hours
-   * ``accumulated_precipitation_since_20230522t120000`` accumulated precipitation since May 22, 2023 at 12:00
-   * ``accumulated_precipitation_since_20251225`` accumulated precipitation since December 25, 2025
-   * ``accumulated_precipitation_since_t00`` accumulated precipitation since 00:00:00 (midnight)
-
-#. By default (when not specified otherwise), variables are grid means or centers
-   (defined by the host). If a variable is defined at a different physical location,
-   a qualifier should be used to denote this. For example, to specify the vertical
-   location of a variable with respect to vertical grid cells, the following variants
-   are possible:
-
-   * ``[variable]``, with no location suffix, is defined at vertical-cell centers or
-     as vertical-cell averages.
-
-   * ``[variable]_at_interfaces`` is defined at the interfaces between grid cells
-     vertically, including the bottom-most and top-most interfaces.
-   * ``[variable]_at_top_interfaces`` is defined at the interfaces between grid cells
-     vertically, including the top-most interface *but excluding the bottom-most
-     interface*.
-
-   * ``[variable]_at_bottom_interfaces`` is defined at the interfaces between grid
-     cells vertically, including the bottom-most interface *but excluding the
-     top-most interface*.
-
-   This implies that if ``[variable]`` is defined on ``n`` points vertically,
-   ``[variable]_at_interfaces`` is defined on ``n+1`` points,
-   ``[variable]_at_top_interfaces`` is defined on ``n`` points, and
-   ``[variable]_at_bottom_interfaces`` is defined on ``n`` points.
-
-#. If possible, qualifiers should be limited in order to allow for a wide
-   applicability of the variable. In other words, don't qualify with ``_for_specific_context``
-   unless a variable could not conceivably be used outside of the more
-   narrowly-defined context or a variable without the scope-narrowing qualifiers
-   already exists and cannot be reused.
-
-   **Discouraged:** upward_virtual_potential_temperature_flux_for_mellor_yamada_janjic_surface_layer_scheme
-
-   **Preferred:** upward_virtual_potential_temperature_flux
-
-#. If there are two identical quantities from different schemes/processes that
-   need to be kept apart, suitable qualifiers are added to the names of the processes.
-   If one process is already established and more common than the other, then it is
-   sufficient to only prefix the new process with a suitable qualifier. Example:
-   ``due_to_convective_GWD`` and ``due_to_convective_whole_atmosphere_GWD``
-   as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79.
-
-Terminology
------------
-
-   `annotated image detailing some of the terminology in this section <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_terms.png>`_
-
-#. A "layer" is a vertical level of a model. A variable for a given layer is either at the vertical
-   centerpoint of a level, or the vertical average of a level, as defined by the host (see above).
-   An "interface" is the boundary above or below a layer.
-
-#. By default, *surface* refers to the liquid or solid substance immediately beneath the atmosphere
-   for a given vertical column. This can be land, ocean, ice, lake, etc.
-
-   For variables describing properties of the atmosphere near/adjacent to the actual surface,
-   care should be taken to specify the specific "surface variable" quantity needed for a specific application:
-
-   *  ``[variable]_at_surface`` is the lowest interface of the atmospheric model, adjacent to the surface.
-      This is equivalent to the surface-adjacent/bottom interface (as described above).
-   *  ``[variable]_at_surface_adjacent_layer`` is the bottom layer of the atmospheric model
-   *  ``[variable]_at_[level]`` for variables defined at specific height above the surface, e.g. ``temperature_at_2m``, ``wind_at_10m``
-
-   Note that some commonly used terms with a prefix ``surface_`` are unavoidable due to the common
-   definition being fundamentally different from unqualified ``X``. For example, ``surface_skin_temperature``
-   is a fundamentally different quantity than the unqualified ``skin_temperature``. In cases such as these,
-   a comment should be included noting this special usage of the word "surface".
-
-#. By default, `water` refers to all types of water in any phase (e.g. solid, liquid, gas,
-   fresh water, salt water, etc.). The terms `sea` and `ocean` are synonymous, though new names
-   should default to using `ocean` unless part of one of the following phrases:
-   * sea_water
-   * sea_ice
-   * sea_level
-   * sea_salt
-   * sea_surface
-   * sea_floor
-   * sea_binary_mask
-   * sea_area 
-
-#. 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*,
-   *wrt_moist_air*, or *wrt_moist_air_and_condensed_water*, where *moist_air*
-   refers to dry air plus vapor and *moist_air_and_condensed_water* refers
-   to dry air plus vapor and hydrometeors.
-
-   Use of the term *specific_humidity* should be avoided, as there is no consensus on
-   whether it refers to *water_vapor_mixing_ratio_wrt_moist_air* or
-   *water_vapor_mixing_ratio_wrt_moist_air_and_condensed_water*.
-   *total_water* can be used to designate water in every form, i.e. water
-   vapor plus condensed water.
-
-   Volume mixing ratios should be qualified as *volume_mixing_ratio*.
-
-#. By default, *mole_fraction_of_X_in_Y* refers to the total amount of *Y*. So, for example,
-   *mole_fraction_of_ozone_in_air* refers to the total amount of (moist) air. (In the case of air,
-   the default meaning is moist air, as described in the *mixing ratio* rule.) When this is not
-   the case, a qualifier should be used to denote this. *e.g.*, *mole_fraction_of_ozone_in_dry_air*.
-
-#. When referring to soil quantities,
-   *volume_fraction* should be used to express the volumetric soil moisture.
-
-#. Number concentration should appear as a prefix, that is, *number_concentration_of*. By default,
-   number concentrations are specified per unit of volume. When they are specified per
-   unit of mass, they should be written as *mass_number_concentration_of*.
-
-#. By default, *precipitation* refers to the sum of all phases of precipitating hydrometeors,
-   for example rain plus graupel plus hail.  The term *frozen_precipitation* refers to the
-   sum of all frozen precipitating hydrometers, for example graupel plus hail (but not rain).
-   Otherwise the standard name should explicitly state the type of hydrometeor(s) the
-   named quantity represents (e.g. *graupel*).
-
-#. By default, the term *cloud* refers to all cloud phases and cloud types. Otherwise
-   an additional prefix or suffix should be added to the standard name specifying what kind(s)
-   of clouds the variable represents (e.g. *ice_cloud* if only including glaciated clouds, or
-   *cloud_at_500hPa* if only including clouds that exist at 500 hPa).
-
-#. Spell out acronyms unless they are defined in the list of "Acronyms, Abbreviations, and Aliases"
-   below. Whenever such an alias exist, use the alias in the
-   standard name and the full term in the description.
-
-#. Chemical species in standard names should be denoted by chemical formulae (e.g. ``co2``,
-   ``ch4``, ``c5h8``) or commonly accepted designations (e.g. ``cfc12``); generally when there are
-   multiple options the shorter name is preferred. A few species with well-established and
-   unambiguous common names (e.g. water, ozone) are also included. In all cases, the standard name
-   should include specific details about the substance's chemical makeup, as well as the
-   phase/state of matter if relevant; e.g. ``water_vapor``, ``liquid_h2so4``
-
-#. If the ionization of the chemical species is relevant, "ionized" should be included in the standard
-   name as a prefix to the substance; e.g. ``number_density_of_ionized_he`` for ionized helium. If
-   relevant, the net ionization charge should be included as a prefix (in words, because +/- are
-   not valid standard name characters); e.g. ``number_density_of_plus_1_ionized_he``
-
-#. For control-oriented variables, there are a few different prefixes that should be used depending on
-   the use case for that specific variable:
-
-   +-------------------+-----------+-----------------------------------------------------------------------------------------------+
-   | **Prefix**        |  **Type** | **Use case**                    | **Example**                                                 |
-   +===================+===========+=================================+=============================================================+
-   | `is_`             | `logical` | A flag indicating some state or | `is_mpi_root` indicates whether or not the code is running  |
-   |                   |           | condition is true or false      | on the MPI root process                                     |
-   +-------------------+-----------+-------------------------------- +-------------------------------------------------------------+
-   | `do_`             | `logical` | A flag whose value directs some | `do_chemical_tracer_diagnostics` indicates to a physics     |
-   |                   |           | behavior                        | scheme that it should compute chemical tracer diagnostics   |
-   +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
-   | `identifier_for_` | `integer` | A parameter indicating some     | `identifier_for_noah_land_surface_scheme` is an integer     |
-   |                   |           | state or condition              | identifying the Noah land surface model                     |
-   +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
-   | `control_for_`    | `integer` | A control whose value directs   | `control_for_land_surface_scheme` is an integer identifying |
-   |                   |           | some behavior                   | the land surface scheme type                                |
-   +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
-   | `index_of_`       | `integer` | An index entry for an array     | `index_of_ice_vegetation_category` is an index describing   |
-   |                   |           |                                 | the location of the ice vegetation category in the array of |
-   |                   |           |                                 | vegetation categories                                       |
-   +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
-
-#. The ``direction`` of a vector, unless noted otherwise, is the geographical bearing measured in the positive clockwise direction from due north. For example, ``wind_to_direction = 90`` is the same as ``wind_from_direction = 270``, meaning wind blowing towards the east.
-
-#. **Disallowed terms:** A few terms are disallowed as standard name components for various reasons; mostly due to
-   ambiguity.
-
-   - ``specific_humidity`` Disallowed due to ambiguity and different definitions between different fields. See above section describing ``mixing_ratio`` for more information.
-   - ``amount`` In most contexts this word is superfluous, and in all contexts it is non-descriptive. Consider a more specific term such as ``mass_content``
-
-#. **Reserved names:** The prefix ``ccpp_`` is reserved for CCPP framework-provided variables.
-   All other standard names should avoid the use of ``ccpp`` in their name.
-
-
-.. _tech_specs:
-
-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 ``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. This is not necessarily the same as the ``long_name`` entry as described
-   in the `CCPP Technical Documentation <https://ccpp-techdoc.readthedocs.io/en/latest/CompliantPhysicsParams.html#ccpp-arg-table>`_,
-   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 an attribute the
-   physical units of that variable quantity (see the `section on Units <#units>`_). For example, the element
-   for the variable name ``exner_function`` may look similar to this:
-
-    <standard_name name="exner_function"
-                   description="exner function, (p/p0)^(Rd/cp), where p0 is 1000 hPa">
-      <type units="1">real</type>
-    </standard_name>
-
-   This XML element indicates that the variable ``exner_function`` represents the quantity described by the ``description``
-   attribute. It is a real variable with 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.
-
-   The standard_name elements are grouped into sections by "section" elements. These are parsed out into human-readable sections
-   in the generated markdown file (``Metadata-standard-names.md``). Sections can contain nested sections for further categorization.
-   Standard Names should be sorted alphabetically by name within a given section. A python tool ``tools/sort_standard_names.py`` is
-   provided to sort the names automatically.
-
-#. Only alphanumeric, punctuation, and whitespace characters from the ASCII character set may be used in the standard_names dictionary.
-   The "name" attributes of ``standard_name`` entries (i.e. the standard names themselves) are further restricted to the character set of capital/lowercase letters, numerals, and ``_`` (underscore).
-
-#. The `<type>` element should include a value that is one of the following valid Fortran types:
-
-   - ``integer``
-   - ``real``
-   - ``logical``
-   - ``character``
-   - ``complex``
-   - ``ddt`` (derived data type)
-
-#. The standard name dictionary XML file should validate according to the schema file ``standard_names.xsd`` All of the above specifications should be coded into this schema file as is appropriate.
-
-.. _qualifiers:
-
-Qualifiers
-========================
-
-``this font`` = words or phrases to be substituted
-
-XY-surface
-----------
-
-Prefixes
-^^^^^^^^
-
-None. Note that this is a departure from the CF conventions, which in
-many cases - but not all - use surface_ as a prefix. This departure from
-the CF convention is to maintain consistency with all other level
-qualifiers that are used as _at_level-qualifier (i.e. as suffix), as well as
-reducing ambiguity between different uses of the word "surface" (see above).
-
-Suffixes
-^^^^^^^^
-
-| at_adiabatic_condensation_level
-| at_cloud_top
-| at_convective_cloud_top
-| at_cloud_base
-| at_convective_cloud_base
-| at_freezing_level
-| at_ground_level
-| at_maximum_wind_speed_level
-| at_sea_ice_base
-| at_sea_level
-| at_top_of_atmosphere_boundary_layer
-| at_top_of_atmosphere_model
-| at_top_of_dry_convection
-| at_interfaces
-| at_toa
-| at_tropopause
-| at_surface
-| at_surface_adjacent_layer
-| at_2m
-| at_10m
-| at_bottom_interface
-| at_pressure_levels
-| at_top_of_viscous_sublayer
-| at_various_atmosphere_layers
-| extended_up_by_1
-
-
-Component
----------
-
-Prefixes
-^^^^^^^^
-
-| upward
-| downward
-| northward
-| southward
-| eastward
-| westward
-| x
-| y
-
-Special Radiation Component
----------------------------
-
-Prefixes
-^^^^^^^^
-
-| net
-| upwelling
-| downwelling
-| incoming
-| outgoing
-
-Medium
-------
-
-Suffixes
-^^^^^^^^
-
-| in_air
-| in_atmosphere_boundary_layer
-| in_mesosphere
-| in_sea_ice
-| in_sea_water
-| in_soil
-| in_soil_water
-| in_stratosphere
-| in_thermosphere
-| in_troposphere
-| in_atmosphere
-| in_surface_snow
-| in_diurnal_thermocline
-| in_canopy
-| in_lake
-| in_aquifer
-| in_aquifer_and_saturated_soil
-| in_convective_tower
-| between_soil_bottom_and_water_table
-
-Process
--------
-
-Suffixes
-^^^^^^^^
-
-| due_to_advection
-| due_to_convection
-| due_to_deep_convection
-| due_to_diabatic_processes
-| due_to_diffusion
-| due_to_dry_convection
-| due_to_gwd
-| due_to_convective_gwd
-| due_to_convective_whole_atmosphere_gwd
-| due_to_orographic_gwd
-| due_to_gyre
-| due_to_isostatic_adjustment
-| due_to_large_scale_precipitation
-| due_to_longwave_heating
-| due_to_moist_convection
-| due_to_overturning
-| due_to_shallow_convection
-| due_to_pbl_processes
-| due_to_shortwave_heating
-| due_to_thermodynamics
-| due_to_background
-| due_to_subgrid_scale_vertical_mixing
-| due_to_convective_microphysics
-| due_to_model_physics
-| due_to_shoc
-| due_to_dynamics
-
-Condition
----------
-
-Suffixes
-^^^^^^^^
-
-| assuming_clear_sky
-| assuming_deep_snow
-| assuming_no_snow
-| over_land
-| over_ocean
-| over_ice
-| for_momentum
-| for_heat
-| for_moisture
-| for_heat_and_moisture
-| assuming_shallow
-| assuming_deep
-
-Time
-----
-
-Suffixes
-^^^^^^^^
-
-| of_new_state
-| on_physics_timestep
-| on_dynamics_timestep
-
-| on_radiation_timestep
-| on_previous_timestep
-| ``N`` _timesteps_back
-| since_ ``T``
-| over_ ``T``
-| reset_every_ ``T``
-
-Computational
--------------
-
-Prefixes
-^^^^^^^^
-
-| lower_bound_of
-| upper_bound_of
-| unfiltered
-| nonnegative
-| is
-| do
-| identifier_for
-| control_for
-| number_of
-| index_of
-| vertical_index_at
-| vertical_dimension_of
-| cumulative
-| iounit_of
-| filename_of
-| frequency_of
-| period_of
-| XYZ_dimensioned
-| tendency_of ``X``
-| generic_tendency
-| one_way_coupling_of ``_X`` _to ``_Y``
-| tunable_parameter[s]_for ``_X``
-| map_of
-
-
-Infixes
-^^^^^^^
-
-| directory_for ``_X`` _source_code
-
-Suffixes
-^^^^^^^^
-
-| for_coupling
-| for_chemistry_coupling
-| from_coupled_process
-| from_wave_model
-| collection_array
-| multiplied_by_timestep
-| for_current_mpi_rank
-| for_current_cubed_sphere_tile
-| plus_one
-| minus_one
-| for_radiation
-| for_deep_convection
-| for_microphysics
-
-Transformations
----------------
-
-Prefixes
-^^^^^^^^
-| change_over_time_in ``_X``
-| convergence_of ``_X`` or horizontal_convergence_of ``_X``
-| correlation_of ``_X`` _and ``_Y`` [_over ``_Z``]
-| cosine_of ``_X``
-| covariance_of ``_X`` _and ``_Y`` [_over ``_Z``]
-| component_derivative_of ``_X``
-| derivative_of ``_X`` _wrt ``_Y``
-| direction_of ``_X``
-| divergence_of ``_X`` or horizontal_divergence_of ``_X``
-| histogram_of ``_X`` [_over ``_Z``]
-| integral_of ``_Y`` _wrt ``_X``
-| ln ``_X``
-| log10 ``_X``
-| lwe_thickness_of ``_X``
-| magnitude_of ``_X``
-| probability_distribution_of ``_X`` [_over ``_Z``]
-| probability_density_function_of ``_X`` [_over ``_Z``]
-| product_of ``_X`` _and ``_Y``
-| ratio_of ``_X`` _to ``_Y``
-| reciprocal_of ``_X``
-| sine_of ``_X``
-| square_of ``_X``
-| standard_deviation_of ``_X``
-| tendency_of ``_X``
-| variance_of ``_X``
-| volume_mixing_ratio_of ``_X``
-
-Suffixes
-^^^^^^^^
-| ``X_`` mixing_ratio_wrt ``_Y``
-
-Other common standard name components
-=====================================
-
-Reserved phrase
----------------
-
-These words/phrases should not be used outside of the described context
-
-+------------------------+-------------------------------------------------------------------------------------+
-| **Phrase**             |  **Usage**                                                                          |
-+========================+=====================================================================================+
-| ccpp                   | Variable names provided by the CCPP framework                                       |
-+------------------------+-------------------------------------------------------------------------------------+
-
-
-Special phrases
----------------
-
-+------------------------+-------------------------------------------------------------------------------------+
-| **Phrase**             |  **Meaning**                                                                        |
-+========================+=====================================================================================+
-| anomaly                | difference from climatology                                                         |
-+------------------------+-------------------------------------------------------------------------------------+
-| area                   | horizontal area unless otherwise stated                                             |
-+------------------------+-------------------------------------------------------------------------------------+
-| atmosphere             | used instead of in_air for quantities which are large-scale rather than local       |
-+------------------------+-------------------------------------------------------------------------------------+
-| condensed_water        | liquid and ice                                                                      |
-+------------------------+-------------------------------------------------------------------------------------+
-| frozen_water           | ice                                                                                 |
-+------------------------+-------------------------------------------------------------------------------------+
-| interface              | The vertical boundary of a model layer.                                             |
-+------------------------+-------------------------------------------------------------------------------------+
-| longwave               | Longwave radiation. Defined as thermal emission of radiation from the planet.       |
-+------------------------+-------------------------------------------------------------------------------------+
-| moisture               | water in all phases contained in soil                                               |
-+------------------------+-------------------------------------------------------------------------------------+
-| ocean                  | used instead of in_sea_water for quantities which are large-scale rather than local |
-+------------------------+-------------------------------------------------------------------------------------+
-| shortwave              | Shortwave radiation. Defined as electromagnetic emissions from the sun              |
-+------------------------+-------------------------------------------------------------------------------------+
-| specific               | per unit mass unless otherwise stated                                               |
-+------------------------+-------------------------------------------------------------------------------------+
-| surface                | The top of the solid or liquid medium below the atmosphere                          |
-+------------------------+-------------------------------------------------------------------------------------+
-| unfrozen_water         | liquid and vapor                                                                    |
-+------------------------+-------------------------------------------------------------------------------------+
-| water                  | water in all phases if not otherwise qualified                                      |
-+------------------------+-------------------------------------------------------------------------------------+
-| dimensionless          | lacking units                                                                       |
-+------------------------+-------------------------------------------------------------------------------------+
-| kinematic              | refers to surface fluxes in "native" units (K m s-1 and kg kg-1 m s-1)              |
-+------------------------+-------------------------------------------------------------------------------------+
-| direct                 | used in radiation (as opposed to diffuse)                                           |
-+------------------------+-------------------------------------------------------------------------------------+
-| diffuse                | used in radiation (as opposed to direct)                                            |
-+------------------------+-------------------------------------------------------------------------------------+
-
-.. _Aliases:
-
-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                                 |
-+---------------------+---------------------------------------------------------+
-| max                 | maximum                                                 |
-+---------------------+---------------------------------------------------------+
-| min                 | minimum                                                 |
-+---------------------+---------------------------------------------------------+
-| myj                 | Mellor-Yamada-Janjic scheme                             |
-+---------------------+---------------------------------------------------------+
-| mynn                | Mellor-Yamada-Nakanishi-Niino scheme                    |
-+---------------------+---------------------------------------------------------+
-| nir                 | near-infrared part of the EM spectrum (radiation)       |
-+---------------------+---------------------------------------------------------+
-| nrl                 | Naval Research Lab                                      |
-+---------------------+---------------------------------------------------------+
-| nsstm               | GFS near-surface sea temperature scheme                 |
-+---------------------+---------------------------------------------------------+
-| pbl                 | planetary boundary layer                                |
-+---------------------+---------------------------------------------------------+
-| pdf                 | probability density function                            |
-+---------------------+---------------------------------------------------------+
-| rrtmgp              | Rapid Radiative Transfer Model for General circulation  |
-|                     | model applications - Parallel                           |
-+---------------------+---------------------------------------------------------+
-| sas                 | simplified Arakawa-Schubert scheme                      |
-+---------------------+---------------------------------------------------------+
-| skeb                | stochastic kinetic energy backscatter                   |
-+---------------------+---------------------------------------------------------+
-| shoc                | simplified higher-order closure stochastic scheme       |
-+---------------------+---------------------------------------------------------+
-| shum                | stochastically perturbed boundary-layer humidity scheme |
-+---------------------+---------------------------------------------------------+
-| sppt                | stochastically perturbed physics tendencies             |
-+---------------------+---------------------------------------------------------+
-| stp                 | standard temperature (0 degC) and pressure (101325 Pa)  |
-+---------------------+---------------------------------------------------------+
-| tke                 | turbulent kinetic energy                                |
-+---------------------+---------------------------------------------------------+
-| 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)             |
-+---------------------+---------------------------------------------------------+
-| wrt                 | with respect to                                         |
-+---------------------+---------------------------------------------------------+
-
-Units
-=====
-
-Entries in the Standard Names dictionary contain a "units" property that serves to indicate the
-typical/recommended units for a given variable. It is not mandatory to use the indicated units exactly,
-but any use of a given standard name variable should have units of the same dimensionality.
-
-When adding a new standard name, units should follow the `International System of Units (SI/metric system) <http://nist.gov/pml/owm/metric-si/si-units>`_.
-If the new standard name has an existing match in the `Climate and Forecast (CF) metadata
-conventions <https://cfconventions.org/standard-names.html>`_, the units should be identical to the canonical units listed there
-
-For dimensionless variables, the following units can be used:
-
-+------------------------+-----------------------------------------------------------------------------------------------+
-| **Unit**               |  **Use case**                                                                                 |
-+========================+===============================================================================================+
-| count                  | integers that describe the dimension/length of an array                                       |
-+------------------------+-----------------------------------------------------------------------------------------------+
-| flag                   | logicals/booleans that can be either true or false                                            |
-+------------------------+-----------------------------------------------------------------------------------------------+
-| index                  | integers that can be an index in an array                                                     |
-+------------------------+-----------------------------------------------------------------------------------------------+
-| kg kg-1                | mass mixing ratios                                                                            |
-+------------------------+-----------------------------------------------------------------------------------------------+
-| m3 m-3                 | volume fraction (e.g. for soil moisture)                                                      |
-+------------------------+-----------------------------------------------------------------------------------------------+
-| mol mol-1              | molar mixing ratios (also volumetric mixing ratio for gases)                                  |
-+------------------------+-----------------------------------------------------------------------------------------------+
-| none                   | strings and character arrays                                                                  |
-+------------------------+-----------------------------------------------------------------------------------------------+
-| fraction               | fractions not listed above, typically valid in the range [0,1]                                |
-+------------------------+-----------------------------------------------------------------------------------------------+
-| percent                | fractions expressed in percent, typically ranging from 0% to 100%                             |
-+------------------------+-----------------------------------------------------------------------------------------------+
-| 1                      | any number (integer, real, complex) not listed above, e.g. scaling factors, error codes, etc. |
-+------------------------+-----------------------------------------------------------------------------------------------+
+    python -m pip install -r docs/requirements.txt
+    sphinx-build -b html docs docs/_build/html
diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/docs/chapters/aliases.rst b/docs/chapters/aliases.rst
new file mode 100644
index 0000000..ad4684c
--- /dev/null
+++ b/docs/chapters/aliases.rst
@@ -0,0 +1,67 @@
+.. _Aliases:
+
+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                                 |
++---------------------+---------------------------------------------------------+
+| max                 | maximum                                                 |
++---------------------+---------------------------------------------------------+
+| min                 | minimum                                                 |
++---------------------+---------------------------------------------------------+
+| myj                 | Mellor-Yamada-Janjic scheme                             |
++---------------------+---------------------------------------------------------+
+| mynn                | Mellor-Yamada-Nakanishi-Niino scheme                    |
++---------------------+---------------------------------------------------------+
+| nir                 | near-infrared part of the EM spectrum (radiation)       |
++---------------------+---------------------------------------------------------+
+| nrl                 | Naval Research Lab                                      |
++---------------------+---------------------------------------------------------+
+| nsstm               | GFS near-surface sea temperature scheme                 |
++---------------------+---------------------------------------------------------+
+| pbl                 | planetary boundary layer                                |
++---------------------+---------------------------------------------------------+
+| pdf                 | probability density function                            |
++---------------------+---------------------------------------------------------+
+| rrtmgp              | Rapid Radiative Transfer Model for General circulation  |
+|                     | model applications - Parallel                           |
++---------------------+---------------------------------------------------------+
+| sas                 | simplified Arakawa-Schubert scheme                      |
++---------------------+---------------------------------------------------------+
+| skeb                | stochastic kinetic energy backscatter                   |
++---------------------+---------------------------------------------------------+
+| shoc                | simplified higher-order closure stochastic scheme       |
++---------------------+---------------------------------------------------------+
+| shum                | stochastically perturbed boundary-layer humidity scheme |
++---------------------+---------------------------------------------------------+
+| sppt                | stochastically perturbed physics tendencies             |
++---------------------+---------------------------------------------------------+
+| stp                 | standard temperature (0 degC) and pressure (101325 Pa)  |
++---------------------+---------------------------------------------------------+
+| tke                 | turbulent kinetic energy                                |
++---------------------+---------------------------------------------------------+
+| 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)             |
++---------------------+---------------------------------------------------------+
+| wrt                 | with respect to                                         |
++---------------------+---------------------------------------------------------+
diff --git a/docs/chapters/common_components.rst b/docs/chapters/common_components.rst
new file mode 100644
index 0000000..f6dca9c
--- /dev/null
+++ b/docs/chapters/common_components.rst
@@ -0,0 +1,57 @@
+Other common standard name components
+=====================================
+
+Reserved phrase
+---------------
+
+These words/phrases should not be used outside of the described context
+
++------------------------+-------------------------------------------------------------------------------------+
+| **Phrase**             |  **Usage**                                                                          |
++========================+=====================================================================================+
+| ccpp                   | Variable names provided by the CCPP framework                                       |
++------------------------+-------------------------------------------------------------------------------------+
+
+
+Special phrases
+---------------
+
++------------------------+-------------------------------------------------------------------------------------+
+| **Phrase**             |  **Meaning**                                                                        |
++========================+=====================================================================================+
+| anomaly                | difference from climatology                                                         |
++------------------------+-------------------------------------------------------------------------------------+
+| area                   | horizontal area unless otherwise stated                                             |
++------------------------+-------------------------------------------------------------------------------------+
+| atmosphere             | used instead of in_air for quantities which are large-scale rather than local       |
++------------------------+-------------------------------------------------------------------------------------+
+| condensed_water        | liquid and ice                                                                      |
++------------------------+-------------------------------------------------------------------------------------+
+| frozen_water           | ice                                                                                 |
++------------------------+-------------------------------------------------------------------------------------+
+| interface              | The vertical boundary of a model layer.                                             |
++------------------------+-------------------------------------------------------------------------------------+
+| longwave               | Longwave radiation. Defined as thermal emission of radiation from the planet.       |
++------------------------+-------------------------------------------------------------------------------------+
+| moisture               | water in all phases contained in soil                                               |
++------------------------+-------------------------------------------------------------------------------------+
+| ocean                  | used instead of in_sea_water for quantities which are large-scale rather than local |
++------------------------+-------------------------------------------------------------------------------------+
+| shortwave              | Shortwave radiation. Defined as electromagnetic emissions from the sun              |
++------------------------+-------------------------------------------------------------------------------------+
+| specific               | per unit mass unless otherwise stated                                               |
++------------------------+-------------------------------------------------------------------------------------+
+| surface                | The top of the solid or liquid medium below the atmosphere                          |
++------------------------+-------------------------------------------------------------------------------------+
+| unfrozen_water         | liquid and vapor                                                                    |
++------------------------+-------------------------------------------------------------------------------------+
+| water                  | water in all phases if not otherwise qualified                                      |
++------------------------+-------------------------------------------------------------------------------------+
+| dimensionless          | lacking units                                                                       |
++------------------------+-------------------------------------------------------------------------------------+
+| kinematic              | refers to surface fluxes in "native" units (K m s-1 and kg kg-1 m s-1)              |
++------------------------+-------------------------------------------------------------------------------------+
+| direct                 | used in radiation (as opposed to diffuse)                                           |
++------------------------+-------------------------------------------------------------------------------------+
+| diffuse                | used in radiation (as opposed to direct)                                            |
++------------------------+-------------------------------------------------------------------------------------+
diff --git a/docs/chapters/naming_rules.rst b/docs/chapters/naming_rules.rst
new file mode 100644
index 0000000..c1ca6b5
--- /dev/null
+++ b/docs/chapters/naming_rules.rst
@@ -0,0 +1,245 @@
+.. _Rules
+
+ESM Standard Name Rules
+========================
+
+Constructing names
+------------------
+
+#. Standard names should be identical to those from the latest version
+   of the `Climate and Forecast (CF) metadata
+   conventions <https://cfconventions.org/standard-names.html>`_ unless
+   an appropriate name does not exist in that standard, or the adoption
+   of said names leads to inconsistencies in the naming convention.
+
+#. When no suitable standard name exists in the CF conventions, the following guidelines should be followed for constructing a new name.
+   The phrases in brackets are optional. The words in *italic* appear explicitly as stated,
+   while the words in ``this font`` indicate other words or phrases to be substituted.
+   The new standard name is constructed by joining the base standard name to the qualifiers using underscores.
+
+   [``transformation``] [``component``] [``non-instant time``] base_name [*in*/*of* ``medium``] [*at* ``level``] [*due_to* ``process``] [``non-current time``] [*assuming* ``condition``]
+
+   This construction was originally based on rules set forth in the
+   `CF guidelines <http://cfconventions.org/Data/cf-standard-names/docs/guidelines.html>`_,
+   but have since evolved for better consistency and generality across a broader set of fields
+   than was originally envisioned by the CF conventions. "``medium``" should be specified when
+   the variable in question is a substance or other quantity contained within some other medium
+   (e.g. for ``mole_fraction_of_ozone_in_air``, the base name is "ozone", while the medium is "air").
+   "Transformation" refers to descriptors such as "``tendency_of``", "``log10``", or other operations or processes describing some transformation or adjustment of a variable; a detailed list of possible transformations can be found :ref:`later in this document <transformations>`.
+   Other parts of the construction provide information about a variable's horizontal surface
+   (e.g. ``at_cloud_base``), component (i.e. direction of variable, e.g. ``downward``), process (e.g.
+   ``due_to_deep_convection``), or condition (e.g., ``assuming_clear_sky``). These qualifications do not
+   change the units of the quantity. This is not an exhaustive list of qualifiers that may be needed for a given standard name;
+   see subsequent rules below for more information.
+
+   The following table provides a few concrete examples of standard names and how they are constructed
+   with respect to the guideline template.
+
+   `image of table providing standard name construction examples <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_construction_examples.png>`_
+
+   Note that "transformations" are a special case, where multiple transformations may be applied,
+   and multiple quantities may be compared, operated on, etc. For transformations involving
+   multiple quantities (e.g. ``ratio_of_X_to_Y``; see the :ref:`section on Transformations <transformations>`
+   for more information), the above formula may be extended around multiple base names.
+
+   `image of table providing standard name construction examples with multiple transformations <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_transformation_examples.png>`_
+
+   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 ``description`` field to prevent any possible ambiguity.
+
+Variable scope
+--------------
+
+#. Variables are current and instantaneous unless specified. Variables that are not
+   current (e.g., previous timestep) or non-instantaneous (e.g., accumulated values)
+   should have qualifiers in the standard name to describe what they represent.
+
+#. For accumulated variables, or variables representing a change over some period of time, the
+   following suffixes are available":
+
+   * ``over_[time]`` indicates an accumulation or other change over the previous duration/time
+   * ``reset_every_[date/time]`` an accumulation or other change reset every set duration/time
+     since the start of the simulation
+   * ``since_[date/time]`` indicates an accumulation or other change since a given date/time.
+
+   Dates, times, and durations should follow the `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`
+   international standard, modified only to use lowercase rather than uppercase letters. Note that
+   the standard is slightly different for dates and times vs durations. For example:
+
+   * ``accumulated_precipitation_over_pt3h`` accumulated precipitation over the last 3 hours
+   * ``accumulated_precipitation_over_p1dt12h`` accumulated precipitation over the last 1 day 12 hours
+   * ``accumulated_precipitation_reset_every_pt1h`` accumulated precipitation reset every 1 hour
+   * ``accumulated_precipitation_reset_every_p1y`` accumulated precipitation reset every 1 year
+   * ``accumulated_precipitation_reset_every_p2dt12h`` accumulated precipitation reset every 2 days, 12 hours
+   * ``accumulated_precipitation_since_20230522t120000`` accumulated precipitation since May 22, 2023 at 12:00
+   * ``accumulated_precipitation_since_20251225`` accumulated precipitation since December 25, 2025
+   * ``accumulated_precipitation_since_t00`` accumulated precipitation since 00:00:00 (midnight)
+
+#. By default (when not specified otherwise), variables are grid means or centers
+   (defined by the host). If a variable is defined at a different physical location,
+   a qualifier should be used to denote this. For example, to specify the vertical
+   location of a variable with respect to vertical grid cells, the following variants
+   are possible:
+
+   * ``[variable]``, with no location suffix, is defined at vertical-cell centers or
+     as vertical-cell averages.
+
+   * ``[variable]_at_interfaces`` is defined at the interfaces between grid cells
+     vertically, including the bottom-most and top-most interfaces.
+   * ``[variable]_at_top_interfaces`` is defined at the interfaces between grid cells
+     vertically, including the top-most interface *but excluding the bottom-most
+     interface*.
+
+   * ``[variable]_at_bottom_interfaces`` is defined at the interfaces between grid
+     cells vertically, including the bottom-most interface *but excluding the
+     top-most interface*.
+
+   This implies that if ``[variable]`` is defined on ``n`` points vertically,
+   ``[variable]_at_interfaces`` is defined on ``n+1`` points,
+   ``[variable]_at_top_interfaces`` is defined on ``n`` points, and
+   ``[variable]_at_bottom_interfaces`` is defined on ``n`` points.
+
+#. If possible, qualifiers should be limited in order to allow for a wide
+   applicability of the variable. In other words, don't qualify with ``_for_specific_context``
+   unless a variable could not conceivably be used outside of the more
+   narrowly-defined context or a variable without the scope-narrowing qualifiers
+   already exists and cannot be reused.
+
+   **Discouraged:** upward_virtual_potential_temperature_flux_for_mellor_yamada_janjic_surface_layer_scheme
+
+   **Preferred:** upward_virtual_potential_temperature_flux
+
+#. If there are two identical quantities from different schemes/processes that
+   need to be kept apart, suitable qualifiers are added to the names of the processes.
+   If one process is already established and more common than the other, then it is
+   sufficient to only prefix the new process with a suitable qualifier. Example:
+   ``due_to_convective_GWD`` and ``due_to_convective_whole_atmosphere_GWD``
+   as discussed in https://github.com/ESCOMP/ESMStandardNames/issues/79.
+
+Terminology
+-----------
+
+   `annotated image detailing some of the terminology in this section <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_terms.png>`_
+
+#. A "layer" is a vertical level of a model. A variable for a given layer is either at the vertical
+   centerpoint of a level, or the vertical average of a level, as defined by the host (see above).
+   An "interface" is the boundary above or below a layer.
+
+#. By default, *surface* refers to the liquid or solid substance immediately beneath the atmosphere
+   for a given vertical column. This can be land, ocean, ice, lake, etc.
+
+   For variables describing properties of the atmosphere near/adjacent to the actual surface,
+   care should be taken to specify the specific "surface variable" quantity needed for a specific application:
+
+   *  ``[variable]_at_surface`` is the lowest interface of the atmospheric model, adjacent to the surface.
+      This is equivalent to the surface-adjacent/bottom interface (as described above).
+   *  ``[variable]_at_surface_adjacent_layer`` is the bottom layer of the atmospheric model
+   *  ``[variable]_at_[level]`` for variables defined at specific height above the surface, e.g. ``temperature_at_2m``, ``wind_at_10m``
+
+   Note that some commonly used terms with a prefix ``surface_`` are unavoidable due to the common
+   definition being fundamentally different from unqualified ``X``. For example, ``surface_skin_temperature``
+   is a fundamentally different quantity than the unqualified ``skin_temperature``. In cases such as these,
+   a comment should be included noting this special usage of the word "surface".
+
+#. By default, `water` refers to all types of water in any phase (e.g. solid, liquid, gas,
+   fresh water, salt water, etc.). The terms `sea` and `ocean` are synonymous, though new names
+   should default to using `ocean` unless part of one of the following phrases:
+   * sea_water
+   * sea_ice
+   * sea_level
+   * sea_salt
+   * sea_surface
+   * sea_floor
+   * sea_binary_mask
+   * sea_area 
+
+#. 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*,
+   *wrt_moist_air*, or *wrt_moist_air_and_condensed_water*, where *moist_air*
+   refers to dry air plus vapor and *moist_air_and_condensed_water* refers
+   to dry air plus vapor and hydrometeors.
+
+   Use of the term *specific_humidity* should be avoided, as there is no consensus on
+   whether it refers to *water_vapor_mixing_ratio_wrt_moist_air* or
+   *water_vapor_mixing_ratio_wrt_moist_air_and_condensed_water*.
+   *total_water* can be used to designate water in every form, i.e. water
+   vapor plus condensed water.
+
+   Volume mixing ratios should be qualified as *volume_mixing_ratio*.
+
+#. By default, *mole_fraction_of_X_in_Y* refers to the total amount of *Y*. So, for example,
+   *mole_fraction_of_ozone_in_air* refers to the total amount of (moist) air. (In the case of air,
+   the default meaning is moist air, as described in the *mixing ratio* rule.) When this is not
+   the case, a qualifier should be used to denote this. *e.g.*, *mole_fraction_of_ozone_in_dry_air*.
+
+#. When referring to soil quantities,
+   *volume_fraction* should be used to express the volumetric soil moisture.
+
+#. Number concentration should appear as a prefix, that is, *number_concentration_of*. By default,
+   number concentrations are specified per unit of volume. When they are specified per
+   unit of mass, they should be written as *mass_number_concentration_of*.
+
+#. By default, *precipitation* refers to the sum of all phases of precipitating hydrometeors,
+   for example rain plus graupel plus hail.  The term *frozen_precipitation* refers to the
+   sum of all frozen precipitating hydrometers, for example graupel plus hail (but not rain).
+   Otherwise the standard name should explicitly state the type of hydrometeor(s) the
+   named quantity represents (e.g. *graupel*).
+
+#. By default, the term *cloud* refers to all cloud phases and cloud types. Otherwise
+   an additional prefix or suffix should be added to the standard name specifying what kind(s)
+   of clouds the variable represents (e.g. *ice_cloud* if only including glaciated clouds, or
+   *cloud_at_500hPa* if only including clouds that exist at 500 hPa).
+
+#. Spell out acronyms unless they are defined in the list of "Acronyms, Abbreviations, and Aliases"
+   below. Whenever such an alias exist, use the alias in the
+   standard name and the full term in the description.
+
+#. Chemical species in standard names should be denoted by chemical formulae (e.g. ``co2``,
+   ``ch4``, ``c5h8``) or commonly accepted designations (e.g. ``cfc12``); generally when there are
+   multiple options the shorter name is preferred. A few species with well-established and
+   unambiguous common names (e.g. water, ozone) are also included. In all cases, the standard name
+   should include specific details about the substance's chemical makeup, as well as the
+   phase/state of matter if relevant; e.g. ``water_vapor``, ``liquid_h2so4``
+
+#. If the ionization of the chemical species is relevant, "ionized" should be included in the standard
+   name as a prefix to the substance; e.g. ``number_density_of_ionized_he`` for ionized helium. If
+   relevant, the net ionization charge should be included as a prefix (in words, because +/- are
+   not valid standard name characters); e.g. ``number_density_of_plus_1_ionized_he``
+
+#. For control-oriented variables, there are a few different prefixes that should be used depending on
+   the use case for that specific variable:
+
+   +-------------------+-----------+-----------------------------------------------------------------------------------------------+
+   | **Prefix**        |  **Type** | **Use case**                    | **Example**                                                 |
+   +===================+===========+=================================+=============================================================+
+   | `is_`             | `logical` | A flag indicating some state or | `is_mpi_root` indicates whether or not the code is running  |
+   |                   |           | condition is true or false      | on the MPI root process                                     |
+   +-------------------+-----------+-------------------------------- +-------------------------------------------------------------+
+   | `do_`             | `logical` | A flag whose value directs some | `do_chemical_tracer_diagnostics` indicates to a physics     |
+   |                   |           | behavior                        | scheme that it should compute chemical tracer diagnostics   |
+   +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
+   | `identifier_for_` | `integer` | A parameter indicating some     | `identifier_for_noah_land_surface_scheme` is an integer     |
+   |                   |           | state or condition              | identifying the Noah land surface model                     |
+   +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
+   | `control_for_`    | `integer` | A control whose value directs   | `control_for_land_surface_scheme` is an integer identifying |
+   |                   |           | some behavior                   | the land surface scheme type                                |
+   +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
+   | `index_of_`       | `integer` | An index entry for an array     | `index_of_ice_vegetation_category` is an index describing   |
+   |                   |           |                                 | the location of the ice vegetation category in the array of |
+   |                   |           |                                 | vegetation categories                                       |
+   +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
+
+#. The ``direction`` of a vector, unless noted otherwise, is the geographical bearing measured in the positive clockwise direction from due north. For example, ``wind_to_direction = 90`` is the same as ``wind_from_direction = 270``, meaning wind blowing towards the east.
+
+#. **Disallowed terms:** A few terms are disallowed as standard name components for various reasons; mostly due to
+   ambiguity.
+
+   - ``specific_humidity`` Disallowed due to ambiguity and different definitions between different fields. See above section describing ``mixing_ratio`` for more information.
+   - ``amount`` In most contexts this word is superfluous, and in all contexts it is non-descriptive. Consider a more specific term such as ``mass_content``
+
+#. **Reserved names:** The prefix ``ccpp_`` is reserved for CCPP framework-provided variables.
+   All other standard names should avoid the use of ``ccpp`` in their name.
diff --git a/docs/chapters/qualifiers.rst b/docs/chapters/qualifiers.rst
new file mode 100644
index 0000000..bc781cf
--- /dev/null
+++ b/docs/chapters/qualifiers.rst
@@ -0,0 +1,261 @@
+.. _qualifiers:
+
+Qualifiers
+========================
+
+``this font`` = words or phrases to be substituted
+
+XY-surface
+----------
+
+Prefixes
+^^^^^^^^
+
+None. Note that this is a departure from the CF conventions, which in
+many cases - but not all - use surface_ as a prefix. This departure from
+the CF convention is to maintain consistency with all other level
+qualifiers that are used as _at_level-qualifier (i.e. as suffix), as well as
+reducing ambiguity between different uses of the word "surface" (see above).
+
+Suffixes
+^^^^^^^^
+
+| at_adiabatic_condensation_level
+| at_cloud_top
+| at_convective_cloud_top
+| at_cloud_base
+| at_convective_cloud_base
+| at_freezing_level
+| at_ground_level
+| at_maximum_wind_speed_level
+| at_sea_ice_base
+| at_sea_level
+| at_top_of_atmosphere_boundary_layer
+| at_top_of_atmosphere_model
+| at_top_of_dry_convection
+| at_interfaces
+| at_toa
+| at_tropopause
+| at_surface
+| at_surface_adjacent_layer
+| at_2m
+| at_10m
+| at_bottom_interface
+| at_pressure_levels
+| at_top_of_viscous_sublayer
+| at_various_atmosphere_layers
+| extended_up_by_1
+
+
+Component
+---------
+
+Prefixes
+^^^^^^^^
+
+| upward
+| downward
+| northward
+| southward
+| eastward
+| westward
+| x
+| y
+
+Special Radiation Component
+---------------------------
+
+Prefixes
+^^^^^^^^
+
+| net
+| upwelling
+| downwelling
+| incoming
+| outgoing
+
+Medium
+------
+
+Suffixes
+^^^^^^^^
+
+| in_air
+| in_atmosphere_boundary_layer
+| in_mesosphere
+| in_sea_ice
+| in_sea_water
+| in_soil
+| in_soil_water
+| in_stratosphere
+| in_thermosphere
+| in_troposphere
+| in_atmosphere
+| in_surface_snow
+| in_diurnal_thermocline
+| in_canopy
+| in_lake
+| in_aquifer
+| in_aquifer_and_saturated_soil
+| in_convective_tower
+| between_soil_bottom_and_water_table
+
+Process
+-------
+
+Suffixes
+^^^^^^^^
+
+| due_to_advection
+| due_to_convection
+| due_to_deep_convection
+| due_to_diabatic_processes
+| due_to_diffusion
+| due_to_dry_convection
+| due_to_gwd
+| due_to_convective_gwd
+| due_to_convective_whole_atmosphere_gwd
+| due_to_orographic_gwd
+| due_to_gyre
+| due_to_isostatic_adjustment
+| due_to_large_scale_precipitation
+| due_to_longwave_heating
+| due_to_moist_convection
+| due_to_overturning
+| due_to_shallow_convection
+| due_to_pbl_processes
+| due_to_shortwave_heating
+| due_to_thermodynamics
+| due_to_background
+| due_to_subgrid_scale_vertical_mixing
+| due_to_convective_microphysics
+| due_to_model_physics
+| due_to_shoc
+| due_to_dynamics
+
+Condition
+---------
+
+Suffixes
+^^^^^^^^
+
+| assuming_clear_sky
+| assuming_deep_snow
+| assuming_no_snow
+| over_land
+| over_ocean
+| over_ice
+| for_momentum
+| for_heat
+| for_moisture
+| for_heat_and_moisture
+| assuming_shallow
+| assuming_deep
+
+Time
+----
+
+Suffixes
+^^^^^^^^
+
+| of_new_state
+| on_physics_timestep
+| on_dynamics_timestep
+
+| on_radiation_timestep
+| on_previous_timestep
+| ``N`` _timesteps_back
+| since_ ``T``
+| over_ ``T``
+| reset_every_ ``T``
+
+Computational
+-------------
+
+Prefixes
+^^^^^^^^
+
+| lower_bound_of
+| upper_bound_of
+| unfiltered
+| nonnegative
+| is
+| do
+| identifier_for
+| control_for
+| number_of
+| index_of
+| vertical_index_at
+| vertical_dimension_of
+| cumulative
+| iounit_of
+| filename_of
+| frequency_of
+| period_of
+| XYZ_dimensioned
+| tendency_of ``X``
+| generic_tendency
+| one_way_coupling_of ``_X`` _to ``_Y``
+| tunable_parameter[s]_for ``_X``
+| map_of
+
+
+Infixes
+^^^^^^^
+
+| directory_for ``_X`` _source_code
+
+Suffixes
+^^^^^^^^
+
+| for_coupling
+| for_chemistry_coupling
+| from_coupled_process
+| from_wave_model
+| collection_array
+| multiplied_by_timestep
+| for_current_mpi_rank
+| for_current_cubed_sphere_tile
+| plus_one
+| minus_one
+| for_radiation
+| for_deep_convection
+| for_microphysics
+
+.. _transformations:
+
+Transformations
+---------------
+
+Prefixes
+^^^^^^^^
+| change_over_time_in ``_X``
+| convergence_of ``_X`` or horizontal_convergence_of ``_X``
+| correlation_of ``_X`` _and ``_Y`` [_over ``_Z``]
+| cosine_of ``_X``
+| covariance_of ``_X`` _and ``_Y`` [_over ``_Z``]
+| component_derivative_of ``_X``
+| derivative_of ``_X`` _wrt ``_Y``
+| direction_of ``_X``
+| divergence_of ``_X`` or horizontal_divergence_of ``_X``
+| histogram_of ``_X`` [_over ``_Z``]
+| integral_of ``_Y`` _wrt ``_X``
+| ln ``_X``
+| log10 ``_X``
+| lwe_thickness_of ``_X``
+| magnitude_of ``_X``
+| probability_distribution_of ``_X`` [_over ``_Z``]
+| probability_density_function_of ``_X`` [_over ``_Z``]
+| product_of ``_X`` _and ``_Y``
+| ratio_of ``_X`` _to ``_Y``
+| reciprocal_of ``_X``
+| sine_of ``_X``
+| square_of ``_X``
+| standard_deviation_of ``_X``
+| tendency_of ``_X``
+| variance_of ``_X``
+| volume_mixing_ratio_of ``_X``
+
+Suffixes
+^^^^^^^^
+| ``X_`` mixing_ratio_wrt ``_Y``
diff --git a/docs/chapters/technical_specifications.rst b/docs/chapters/technical_specifications.rst
new file mode 100644
index 0000000..7e09537
--- /dev/null
+++ b/docs/chapters/technical_specifications.rst
@@ -0,0 +1,45 @@
+.. _tech_specs:
+
+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 ``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. This is not necessarily the same as the ``long_name`` entry as described
+   in the `CCPP Technical Documentation <https://ccpp-techdoc.readthedocs.io/en/latest/CompliantPhysicsParams.html#ccpp-arg-table>`_,
+   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 an attribute the
+   physical units of that variable quantity (see the :ref:`section on Units <units_section>`). For example, the element
+   for the variable name ``exner_function`` may look similar to this:
+
+    <standard_name name="exner_function"
+                   description="exner function, (p/p0)^(Rd/cp), where p0 is 1000 hPa">
+      <type units="1">real</type>
+    </standard_name>
+
+   This XML element indicates that the variable ``exner_function`` represents the quantity described by the ``description``
+   attribute. It is a real variable with units of "1", meaning it is non-dimensional and
+   does not correspond to a more descriptive non-dimensional type such as "fraction"; see the :ref:`section on Units <units_section>`
+   for more details.
+
+   The standard_name elements are grouped into sections by "section" elements. These are parsed out into human-readable sections
+   in the generated markdown file (``Metadata-standard-names.md``). Sections can contain nested sections for further categorization.
+   Standard Names should be sorted alphabetically by name within a given section. A python tool ``tools/sort_standard_names.py`` is
+   provided to sort the names automatically.
+
+#. Only alphanumeric, punctuation, and whitespace characters from the ASCII character set may be used in the standard_names dictionary.
+   The "name" attributes of ``standard_name`` entries (i.e. the standard names themselves) are further restricted to the character set of capital/lowercase letters, numerals, and ``_`` (underscore).
+
+#. The `<type>` element should include a value that is one of the following valid Fortran types:
+
+   - ``integer``
+   - ``real``
+   - ``logical``
+   - ``character``
+   - ``complex``
+   - ``ddt`` (derived data type)
+
+#. The standard name dictionary XML file should validate according to the schema file ``standard_names.xsd`` All of the above specifications should be coded into this schema file as is appropriate.
diff --git a/docs/chapters/units.rst b/docs/chapters/units.rst
new file mode 100644
index 0000000..1a24552
--- /dev/null
+++ b/docs/chapters/units.rst
@@ -0,0 +1,38 @@
+.. _units_section:
+
+Units
+=====
+
+Entries in the Standard Names dictionary contain a "units" property that serves to indicate the
+typical/recommended units for a given variable. It is not mandatory to use the indicated units exactly,
+but any use of a given standard name variable should have units of the same dimensionality.
+
+When adding a new standard name, units should follow the `International System of Units (SI/metric system) <http://nist.gov/pml/owm/metric-si/si-units>`_.
+If the new standard name has an existing match in the `Climate and Forecast (CF) metadata
+conventions <https://cfconventions.org/standard-names.html>`_, the units should be identical to the canonical units listed there
+
+For dimensionless variables, the following units can be used:
+
++------------------------+-----------------------------------------------------------------------------------------------+
+| **Unit**               |  **Use case**                                                                                 |
++========================+===============================================================================================+
+| count                  | integers that describe the dimension/length of an array                                       |
++------------------------+-----------------------------------------------------------------------------------------------+
+| flag                   | logicals/booleans that can be either true or false                                            |
++------------------------+-----------------------------------------------------------------------------------------------+
+| index                  | integers that can be an index in an array                                                     |
++------------------------+-----------------------------------------------------------------------------------------------+
+| kg kg-1                | mass mixing ratios                                                                            |
++------------------------+-----------------------------------------------------------------------------------------------+
+| m3 m-3                 | volume fraction (e.g. for soil moisture)                                                      |
++------------------------+-----------------------------------------------------------------------------------------------+
+| mol mol-1              | molar mixing ratios (also volumetric mixing ratio for gases)                                  |
++------------------------+-----------------------------------------------------------------------------------------------+
+| none                   | strings and character arrays                                                                  |
++------------------------+-----------------------------------------------------------------------------------------------+
+| fraction               | fractions not listed above, typically valid in the range [0,1]                                |
++------------------------+-----------------------------------------------------------------------------------------------+
+| percent                | fractions expressed in percent, typically ranging from 0% to 100%                             |
++------------------------+-----------------------------------------------------------------------------------------------+
+| 1                      | any number (integer, real, complex) not listed above, e.g. scaling factors, error codes, etc. |
++------------------------+-----------------------------------------------------------------------------------------------+
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..c3ad2ac
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,18 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+project = "ESM Standard Names"
+copyright = "ESCOMP"
+author = "ESCOMP"
+
+extensions = []
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..774e25a
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,28 @@
+.. # define a hard line break for HTML
+.. |br| raw:: html
+
+   <br />
+
+*******************
+Earth System Modeling (ESM) Standard Names
+*******************
+
+This document contains information about the rules used to create Standard Names
+for use with Earth System Models. It describes the
+
+* ESM Standard Name rules
+* Standard Name qualifiers
+* Other common standard name components
+* Acronyms, abbreviations, and aliases
+* Units
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   chapters/naming_rules
+   chapters/technical_specifications
+   chapters/qualifiers
+   chapters/common_components
+   chapters/aliases
+   chapters/units
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..0126369
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinx>=7.0
+sphinx_rtd_theme>=2.0

From 3064c8c7002dea78ad0335d37183bd788b905e28 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 15:24:37 -0600
Subject: [PATCH 16/21] Fix RST markup bugs surfaced by strict Sphinx build

- naming_rules.rst: repair a malformed grid table (missing column
  divider in the top border, a stray space instead of a dash in a row
  separator) that was merging/misrendering the control-oriented
  variables table; also add the missing colon on the ".. _Rules"
  target.
- qualifiers.rst: escape trailing underscores in "surface_", "since_",
  "over_", and "reset_every_" so they render as plain text instead of
  being parsed as broken hyperlink references.
- technical_specifications.rst: use "::" instead of ":" to introduce
  the exner_function XML snippet so it renders as a code block instead
  of a garbled block quote/definition list.
- index.rst: lengthen the title over/underline to match the title
  text length.

No wording changes; docs/ now builds with zero Sphinx warnings.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/chapters/naming_rules.rst             | 6 +++---
 docs/chapters/qualifiers.rst               | 8 ++++----
 docs/chapters/technical_specifications.rst | 2 +-
 docs/index.rst                             | 4 ++--
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/chapters/naming_rules.rst b/docs/chapters/naming_rules.rst
index c1ca6b5..c1ed45b 100644
--- a/docs/chapters/naming_rules.rst
+++ b/docs/chapters/naming_rules.rst
@@ -1,4 +1,4 @@
-.. _Rules
+.. _Rules:
 
 ESM Standard Name Rules
 ========================
@@ -213,12 +213,12 @@ Terminology
 #. For control-oriented variables, there are a few different prefixes that should be used depending on
    the use case for that specific variable:
 
-   +-------------------+-----------+-----------------------------------------------------------------------------------------------+
+   +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
    | **Prefix**        |  **Type** | **Use case**                    | **Example**                                                 |
    +===================+===========+=================================+=============================================================+
    | `is_`             | `logical` | A flag indicating some state or | `is_mpi_root` indicates whether or not the code is running  |
    |                   |           | condition is true or false      | on the MPI root process                                     |
-   +-------------------+-----------+-------------------------------- +-------------------------------------------------------------+
+   +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
    | `do_`             | `logical` | A flag whose value directs some | `do_chemical_tracer_diagnostics` indicates to a physics     |
    |                   |           | behavior                        | scheme that it should compute chemical tracer diagnostics   |
    +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
diff --git a/docs/chapters/qualifiers.rst b/docs/chapters/qualifiers.rst
index bc781cf..7bc1568 100644
--- a/docs/chapters/qualifiers.rst
+++ b/docs/chapters/qualifiers.rst
@@ -12,7 +12,7 @@ Prefixes
 ^^^^^^^^
 
 None. Note that this is a departure from the CF conventions, which in
-many cases - but not all - use surface_ as a prefix. This departure from
+many cases - but not all - use surface\_ as a prefix. This departure from
 the CF convention is to maintain consistency with all other level
 qualifiers that are used as _at_level-qualifier (i.e. as suffix), as well as
 reducing ambiguity between different uses of the word "surface" (see above).
@@ -165,9 +165,9 @@ Suffixes
 | on_radiation_timestep
 | on_previous_timestep
 | ``N`` _timesteps_back
-| since_ ``T``
-| over_ ``T``
-| reset_every_ ``T``
+| since\_ ``T``
+| over\_ ``T``
+| reset_every\_ ``T``
 
 Computational
 -------------
diff --git a/docs/chapters/technical_specifications.rst b/docs/chapters/technical_specifications.rst
index 7e09537..3d1e2d5 100644
--- a/docs/chapters/technical_specifications.rst
+++ b/docs/chapters/technical_specifications.rst
@@ -13,7 +13,7 @@ Technical specifications
    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 an attribute the
    physical units of that variable quantity (see the :ref:`section on Units <units_section>`). For example, the element
-   for the variable name ``exner_function`` may look similar to this:
+   for the variable name ``exner_function`` may look similar to this::
 
     <standard_name name="exner_function"
                    description="exner function, (p/p0)^(Rd/cp), where p0 is 1000 hPa">
diff --git a/docs/index.rst b/docs/index.rst
index 774e25a..7e21610 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,9 +3,9 @@
 
    <br />
 
-*******************
+*******************************************
 Earth System Modeling (ESM) Standard Names
-*******************
+*******************************************
 
 This document contains information about the rules used to create Standard Names
 for use with Earth System Models. It describes the

From f7f7c385d0d41cf3074e7acd1e7f522d86d8c9e6 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 15:31:27 -0600
Subject: [PATCH 17/21] Embed linked images as figures with captions and alt
 text

Replace the three plain hyperlinks to wiki-hosted PNGs in
naming_rules.rst with .. figure:: directives, so the images render
inline on the page instead of requiring a click-through. Each figure
gets descriptive alt text and a caption; the images continue to be
served from raw.githubusercontent.com rather than being vendored into
the repo.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/chapters/naming_rules.rst | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/docs/chapters/naming_rules.rst b/docs/chapters/naming_rules.rst
index c1ed45b..927d48b 100644
--- a/docs/chapters/naming_rules.rst
+++ b/docs/chapters/naming_rules.rst
@@ -35,14 +35,20 @@ Constructing names
    The following table provides a few concrete examples of standard names and how they are constructed
    with respect to the guideline template.
 
-   `image of table providing standard name construction examples <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_construction_examples.png>`_
+   .. figure:: https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_construction_examples.png
+      :alt: Table of example standard names showing how each is built from a base name plus qualifiers such as component, medium, level, and process, according to the naming guideline template.
+
+      Examples of standard names and how they are constructed with respect to the guideline template.
 
    Note that "transformations" are a special case, where multiple transformations may be applied,
    and multiple quantities may be compared, operated on, etc. For transformations involving
    multiple quantities (e.g. ``ratio_of_X_to_Y``; see the :ref:`section on Transformations <transformations>`
    for more information), the above formula may be extended around multiple base names.
 
-   `image of table providing standard name construction examples with multiple transformations <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_transformation_examples.png>`_
+   .. figure:: https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_transformation_examples.png
+      :alt: Table of example standard names showing how the construction template extends around multiple base names when more than one transformation or quantity is involved.
+
+      Examples of standard name construction for transformations involving multiple quantities.
 
    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``
@@ -121,7 +127,10 @@ Variable scope
 Terminology
 -----------
 
-   `annotated image detailing some of the terminology in this section <https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_terms.png>`_
+   .. figure:: https://raw.githubusercontent.com/wiki/ESCOMP/ESMStandardNames/images/standard_name_terms.png
+      :alt: Annotated diagram illustrating standard-name terminology such as layer, interface, and surface as used throughout this section.
+
+      Annotated diagram detailing some of the terminology used in this section.
 
 #. A "layer" is a vertical level of a model. A variable for a given layer is either at the vertical
    centerpoint of a level, or the vertical average of a level, as defined by the host (see above).

From 9a994147a8fb441a526f73f09fa2fb9c0af6cc40 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 16:15:37 -0600
Subject: [PATCH 18/21] Change formatting of qualifiers/suffixes/prefixes for
 better visual flow

---
 docs/chapters/qualifiers.rst | 340 +++++++++++++++++------------------
 1 file changed, 170 insertions(+), 170 deletions(-)

diff --git a/docs/chapters/qualifiers.rst b/docs/chapters/qualifiers.rst
index 7bc1568..22f54df 100644
--- a/docs/chapters/qualifiers.rst
+++ b/docs/chapters/qualifiers.rst
@@ -3,7 +3,8 @@
 Qualifiers
 ========================
 
-``this font`` = words or phrases to be substituted
+ * ``X``, ``Y``, ``Z``, etc. = words or phrases to be substituted
+ * ``something[_optional]`` = "_optional" is an optional portion of the qualifier to include as needed
 
 XY-surface
 ----------
@@ -20,31 +21,31 @@ reducing ambiguity between different uses of the word "surface" (see above).
 Suffixes
 ^^^^^^^^
 
-| at_adiabatic_condensation_level
-| at_cloud_top
-| at_convective_cloud_top
-| at_cloud_base
-| at_convective_cloud_base
-| at_freezing_level
-| at_ground_level
-| at_maximum_wind_speed_level
-| at_sea_ice_base
-| at_sea_level
-| at_top_of_atmosphere_boundary_layer
-| at_top_of_atmosphere_model
-| at_top_of_dry_convection
-| at_interfaces
-| at_toa
-| at_tropopause
-| at_surface
-| at_surface_adjacent_layer
-| at_2m
-| at_10m
-| at_bottom_interface
-| at_pressure_levels
-| at_top_of_viscous_sublayer
-| at_various_atmosphere_layers
-| extended_up_by_1
+| ``_at_adiabatic_condensation_level``
+| ``_at_cloud_top``
+| ``_at_convective_cloud_top``
+| ``_at_cloud_base``
+| ``_at_convective_cloud_base``
+| ``_at_freezing_level``
+| ``_at_ground_level``
+| ``_at_maximum_wind_speed_level``
+| ``_at_sea_ice_base``
+| ``_at_sea_level``
+| ``_at_top_of_atmosphere_boundary_layer``
+| ``_at_top_of_atmosphere_model``
+| ``_at_top_of_dry_convection``
+| ``_at_interfaces``
+| ``_at_toa``
+| ``_at_tropopause``
+| ``_at_surface``
+| ``_at_surface_adjacent_layer``
+| ``_at_2m``
+| ``_at_10m``
+| ``_at_bottom_interface``
+| ``_at_pressure_levels``
+| ``_at_top_of_viscous_sublayer``
+| ``_at_various_atmosphere_layers``
+| ``_extended_up_by_1``
 
 
 Component
@@ -53,14 +54,14 @@ Component
 Prefixes
 ^^^^^^^^
 
-| upward
-| downward
-| northward
-| southward
-| eastward
-| westward
-| x
-| y
+| ``upward``
+| ``downward``
+| ``northward``
+| ``southward``
+| ``eastward``
+| ``westward``
+| ``x``
+| ``y``
 
 Special Radiation Component
 ---------------------------
@@ -68,11 +69,11 @@ Special Radiation Component
 Prefixes
 ^^^^^^^^
 
-| net
-| upwelling
-| downwelling
-| incoming
-| outgoing
+| ``net_``
+| ``upwelling_``
+| ``downwelling_``
+| ``incoming_``
+| ``outgoing_``
 
 Medium
 ------
@@ -80,25 +81,25 @@ Medium
 Suffixes
 ^^^^^^^^
 
-| in_air
-| in_atmosphere_boundary_layer
-| in_mesosphere
-| in_sea_ice
-| in_sea_water
-| in_soil
-| in_soil_water
-| in_stratosphere
-| in_thermosphere
-| in_troposphere
-| in_atmosphere
-| in_surface_snow
-| in_diurnal_thermocline
-| in_canopy
-| in_lake
-| in_aquifer
-| in_aquifer_and_saturated_soil
-| in_convective_tower
-| between_soil_bottom_and_water_table
+| ``_in_air``
+| ``_in_atmosphere_boundary_layer``
+| ``_in_mesosphere``
+| ``_in_sea_ice``
+| ``_in_sea_water``
+| ``_in_soil``
+| ``_in_soil_water``
+| ``_in_stratosphere``
+| ``_in_thermosphere``
+| ``_in_troposphere``
+| ``_in_atmosphere``
+| ``_in_surface_snow``
+| ``_in_diurnal_thermocline``
+| ``_in_canopy``
+| ``_in_lake``
+| ``_in_aquifer``
+| ``_in_aquifer_and_saturated_soil``
+| ``_in_convective_tower``
+| ``_between_soil_bottom_and_water_table``
 
 Process
 -------
@@ -106,32 +107,32 @@ Process
 Suffixes
 ^^^^^^^^
 
-| due_to_advection
-| due_to_convection
-| due_to_deep_convection
-| due_to_diabatic_processes
-| due_to_diffusion
-| due_to_dry_convection
-| due_to_gwd
-| due_to_convective_gwd
-| due_to_convective_whole_atmosphere_gwd
-| due_to_orographic_gwd
-| due_to_gyre
-| due_to_isostatic_adjustment
-| due_to_large_scale_precipitation
-| due_to_longwave_heating
-| due_to_moist_convection
-| due_to_overturning
-| due_to_shallow_convection
-| due_to_pbl_processes
-| due_to_shortwave_heating
-| due_to_thermodynamics
-| due_to_background
-| due_to_subgrid_scale_vertical_mixing
-| due_to_convective_microphysics
-| due_to_model_physics
-| due_to_shoc
-| due_to_dynamics
+| ``_due_to_advection``
+| ``_due_to_convection``
+| ``_due_to_deep_convection``
+| ``_due_to_diabatic_processes``
+| ``_due_to_diffusion``
+| ``_due_to_dry_convection``
+| ``_due_to_gwd``
+| ``_due_to_convective_gwd``
+| ``_due_to_convective_whole_atmosphere_gwd``
+| ``_due_to_orographic_gwd``
+| ``_due_to_gyre``
+| ``_due_to_isostatic_adjustment``
+| ``_due_to_large_scale_precipitation``
+| ``_due_to_longwave_heating``
+| ``_due_to_moist_convection``
+| ``_due_to_overturning``
+| ``_due_to_shallow_convection``
+| ``_due_to_pbl_processes``
+| ``_due_to_shortwave_heating``
+| ``_due_to_thermodynamics``
+| ``_due_to_background``
+| ``_due_to_subgrid_scale_vertical_mixing``
+| ``_due_to_convective_microphysics``
+| ``_due_to_model_physics``
+| ``_due_to_shoc``
+| ``_due_to_dynamics``
 
 Condition
 ---------
@@ -139,18 +140,18 @@ Condition
 Suffixes
 ^^^^^^^^
 
-| assuming_clear_sky
-| assuming_deep_snow
-| assuming_no_snow
-| over_land
-| over_ocean
-| over_ice
-| for_momentum
-| for_heat
-| for_moisture
-| for_heat_and_moisture
-| assuming_shallow
-| assuming_deep
+| ``_assuming_clear_sky``
+| ``_assuming_deep_snow``
+| ``_assuming_no_snow``
+| ``_over_land``
+| ``_over_ocean``
+| ``_over_ice``
+| ``_for_momentum``
+| ``_for_heat``
+| ``_for_moisture``
+| ``_for_heat_and_moisture``
+| ``_assuming_shallow``
+| ``_assuming_deep``
 
 Time
 ----
@@ -158,16 +159,15 @@ Time
 Suffixes
 ^^^^^^^^
 
-| of_new_state
-| on_physics_timestep
-| on_dynamics_timestep
-
-| on_radiation_timestep
-| on_previous_timestep
-| ``N`` _timesteps_back
-| since\_ ``T``
-| over\_ ``T``
-| reset_every\_ ``T``
+| ``_of_new_state``
+| ``_on_physics_timestep``
+| ``_on_dynamics_timestep``
+| ``_on_radiation_timestep``
+| ``_on_previous_timestep``
+| ``_N_timesteps_back``
+| ``_since_T``
+| ``_over_T``
+| ``_reset_every_T``
 
 Computational
 -------------
@@ -175,52 +175,52 @@ Computational
 Prefixes
 ^^^^^^^^
 
-| lower_bound_of
-| upper_bound_of
-| unfiltered
-| nonnegative
-| is
-| do
-| identifier_for
-| control_for
-| number_of
-| index_of
-| vertical_index_at
-| vertical_dimension_of
-| cumulative
-| iounit_of
-| filename_of
-| frequency_of
-| period_of
-| XYZ_dimensioned
-| tendency_of ``X``
-| generic_tendency
-| one_way_coupling_of ``_X`` _to ``_Y``
-| tunable_parameter[s]_for ``_X``
-| map_of
+| ``lower_bound_of_``
+| ``upper_bound_of_``
+| ``unfiltered_``
+| ``nonnegative_``
+| ``is_``
+| ``do_``
+| ``identifier_for_``
+| ``control_for_``
+| ``number_of_``
+| ``index_of_``
+| ``vertical_index_at_``
+| ``vertical_dimension_of_``
+| ``cumulative_``
+| ``iounit_of_``
+| ``filename_of_``
+| ``frequency_of_``
+| ``period_of_``
+| ``xyz_dimensioned_``
+| ``tendency_of_X``
+| ``generic_tendency_``
+| ``one_way_coupling_of_X_to_Y``
+| ``tunable_parameter[s]_for_X``
+| ``map_of_``
 
 
 Infixes
 ^^^^^^^
 
-| directory_for ``_X`` _source_code
+| ``directory_for_X_source_code``
 
 Suffixes
 ^^^^^^^^
 
-| for_coupling
-| for_chemistry_coupling
-| from_coupled_process
-| from_wave_model
-| collection_array
-| multiplied_by_timestep
-| for_current_mpi_rank
-| for_current_cubed_sphere_tile
-| plus_one
-| minus_one
-| for_radiation
-| for_deep_convection
-| for_microphysics
+| ``_for_coupling``
+| ``_for_chemistry_coupling``
+| ``_from_coupled_process``
+| ``_from_wave_model``
+| ``_collection_array``
+| ``_multiplied_by_timestep``
+| ``_for_current_mpi_rank``
+| ``_for_current_cubed_sphere_tile``
+| ``_plus_one``
+| ``_minus_one``
+| ``_for_radiation``
+| ``_for_deep_convection``
+| ``_for_microphysics``
 
 .. _transformations:
 
@@ -229,33 +229,33 @@ Transformations
 
 Prefixes
 ^^^^^^^^
-| change_over_time_in ``_X``
-| convergence_of ``_X`` or horizontal_convergence_of ``_X``
-| correlation_of ``_X`` _and ``_Y`` [_over ``_Z``]
-| cosine_of ``_X``
-| covariance_of ``_X`` _and ``_Y`` [_over ``_Z``]
-| component_derivative_of ``_X``
-| derivative_of ``_X`` _wrt ``_Y``
-| direction_of ``_X``
-| divergence_of ``_X`` or horizontal_divergence_of ``_X``
-| histogram_of ``_X`` [_over ``_Z``]
-| integral_of ``_Y`` _wrt ``_X``
-| ln ``_X``
-| log10 ``_X``
-| lwe_thickness_of ``_X``
-| magnitude_of ``_X``
-| probability_distribution_of ``_X`` [_over ``_Z``]
-| probability_density_function_of ``_X`` [_over ``_Z``]
-| product_of ``_X`` _and ``_Y``
-| ratio_of ``_X`` _to ``_Y``
-| reciprocal_of ``_X``
-| sine_of ``_X``
-| square_of ``_X``
-| standard_deviation_of ``_X``
-| tendency_of ``_X``
-| variance_of ``_X``
-| volume_mixing_ratio_of ``_X``
+| ``change_over_time_in_X``
+| ``convergence_of_X`` or ``horizontal_convergence_of_X``
+| ``correlation_of_X_and_Y[_over_Z]``
+| ``cosine_of_X``
+| ``covariance_of_X_and_Y[_over_Z]``
+| ``component_derivative_of_X``
+| ``derivative_of_X_wrt_Y``
+| ``direction_of_X``
+| ``divergence_of_X`` or ``horizontal_divergence_of_X``
+| ``histogram_of_X[_over _Z]``
+| ``integral_of_Y_wrt_X``
+| ``ln_X``
+| ``log10_X``
+| ``lwe_thickness_of_X``
+| ``magnitude_of_X``
+| ``probability_distribution_of_X[_over_Z]``
+| ``probability_density_function_of_X[_over_Z]``
+| ``product_of_X_and_Y``
+| ``ratio_of_X_to_Y``
+| ``reciprocal_of_X``
+| ``sine_of_X``
+| ``square_of_X``
+| ``standard_deviation_of_X``
+| ``tendency_of_X``
+| ``variance_of_X``
+| ``volume_mixing_ratio_of_X``
 
 Suffixes
 ^^^^^^^^
-| ``X_`` mixing_ratio_wrt ``_Y``
+| ``X_mixing_ratio_wrt_Y``

From 93625a32fd56a4a6c9df01e8458b0b9a7bb01b6c Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 16:16:21 -0600
Subject: [PATCH 19/21] Better location to build docs locally

---
 README.md              | 2 +-
 StandardNamesRules.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 2f7f352..35fb967 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ The Earth System Modeling Standard Names Repository contains community-accepted
 Rules governing the designation and format of standard names are published as a chaptered
 Sphinx/Read the Docs site built from the [docs/](docs/) directory; see
 [docs/index.rst](https://github.com/ESCOMP/ESMStandardNames/blob/main/docs/index.rst) for the
-table of contents, or build it locally with `sphinx-build -b html docs docs/_build/html`.
+table of contents, or build it locally with `sphinx-build -b html docs docs/html`.
 
 A [Markdown file describing the standard names is included](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.md), as well as a [YAML version of the XML file](https://github.com/ESCOMP/ESMStandardNames/blob/main/Metadata-standard-names.yaml).
 
diff --git a/StandardNamesRules.rst b/StandardNamesRules.rst
index a5bc6a5..521e134 100644
--- a/StandardNamesRules.rst
+++ b/StandardNamesRules.rst
@@ -17,4 +17,4 @@ The source for the rules now lives under `docs/chapters/ <docs/chapters/>`_ in t
 See `docs/index.rst <docs/index.rst>`_ for the table of contents, or build the docs locally with::
 
     python -m pip install -r docs/requirements.txt
-    sphinx-build -b html docs docs/_build/html
+    sphinx-build -b html docs docs/html

From eeedf628f5a162377e894fdfc2c60922ca52c9d0 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Tue, 22 Sep 2026 17:08:59 -0600
Subject: [PATCH 20/21] Better formatting for "naming rules" chapter

---
 docs/chapters/naming_rules.rst | 112 +++++++++++++++++++--------------
 1 file changed, 64 insertions(+), 48 deletions(-)

diff --git a/docs/chapters/naming_rules.rst b/docs/chapters/naming_rules.rst
index 927d48b..3bb144d 100644
--- a/docs/chapters/naming_rules.rst
+++ b/docs/chapters/naming_rules.rst
@@ -17,7 +17,7 @@ Constructing names
    while the words in ``this font`` indicate other words or phrases to be substituted.
    The new standard name is constructed by joining the base standard name to the qualifiers using underscores.
 
-   [``transformation``] [``component``] [``non-instant time``] base_name [*in*/*of* ``medium``] [*at* ``level``] [*due_to* ``process``] [``non-current time``] [*assuming* ``condition``]
+   [``transformation``] [``component``] [``non-instant time``] base_name [*in* or *of* ``medium``] [*at* ``level``] [*due_to* ``process``] [``non-current time``] [*assuming* ``condition``]
 
    This construction was originally based on rules set forth in the
    `CF guidelines <http://cfconventions.org/Data/cf-standard-names/docs/guidelines.html>`_,
@@ -70,7 +70,7 @@ Variable scope
      since the start of the simulation
    * ``since_[date/time]`` indicates an accumulation or other change since a given date/time.
 
-   Dates, times, and durations should follow the `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`
+   Dates, times, and durations should follow the `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_
    international standard, modified only to use lowercase rather than uppercase letters. Note that
    the standard is slightly different for dates and times vs durations. For example:
 
@@ -113,9 +113,9 @@ Variable scope
    narrowly-defined context or a variable without the scope-narrowing qualifiers
    already exists and cannot be reused.
 
-   **Discouraged:** upward_virtual_potential_temperature_flux_for_mellor_yamada_janjic_surface_layer_scheme
+   **Discouraged:** ``upward_virtual_potential_temperature_flux_for_mellor_yamada_janjic_surface_layer_scheme``
 
-   **Preferred:** upward_virtual_potential_temperature_flux
+   **Preferred:** ``upward_virtual_potential_temperature_flux``
 
 #. If there are two identical quantities from different schemes/processes that
    need to be kept apart, suitable qualifiers are added to the names of the processes.
@@ -155,57 +155,61 @@ Terminology
 #. By default, `water` refers to all types of water in any phase (e.g. solid, liquid, gas,
    fresh water, salt water, etc.). The terms `sea` and `ocean` are synonymous, though new names
    should default to using `ocean` unless part of one of the following phrases:
-   * sea_water
-   * sea_ice
-   * sea_level
-   * sea_salt
-   * sea_surface
-   * sea_floor
-   * sea_binary_mask
-   * sea_area 
+
+   * ``sea_water``
+   * ``sea_ice``
+   * ``sea_level``
+   * ``sea_salt``
+   * ``sea_surface``
+   * ``sea_floor``
+   * ``sea_binary_mask``
+   * ``sea_area``
+
+.. _mixing_ratio:
 
 #. 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*,
-   *wrt_moist_air*, or *wrt_moist_air_and_condensed_water*, where *moist_air*
-   refers to dry air plus vapor and *moist_air_and_condensed_water* refers
+   with respect to what quantity they are defined, and options are ``wrt_dry_air``,
+   ``wrt_moist_air``, or ``wrt_moist_air_and_condensed_water``, where ``moist_air``
+   refers to dry air plus vapor and ``moist_air_and_condensed_water`` refers
    to dry air plus vapor and hydrometeors.
 
-   Use of the term *specific_humidity* should be avoided, as there is no consensus on
-   whether it refers to *water_vapor_mixing_ratio_wrt_moist_air* or
-   *water_vapor_mixing_ratio_wrt_moist_air_and_condensed_water*.
-   *total_water* can be used to designate water in every form, i.e. water
+   **Use of the term** ***specific_humidity*** **should be avoided**, as there are differing
+   conventions as to whether it refers to ``water_vapor_mixing_ratio_wrt_moist_air`` or
+   ``water_vapor_mixing_ratio_wrt_moist_air_and_condensed_water``.
+
+   ``total_water`` can be used to designate water in every form, i.e. water
    vapor plus condensed water.
 
-   Volume mixing ratios should be qualified as *volume_mixing_ratio*.
+   Volume mixing ratios should be qualified as ``volume_mixing_ratio``.
 
-#. By default, *mole_fraction_of_X_in_Y* refers to the total amount of *Y*. So, for example,
-   *mole_fraction_of_ozone_in_air* refers to the total amount of (moist) air. (In the case of air,
-   the default meaning is moist air, as described in the *mixing ratio* rule.) When this is not
-   the case, a qualifier should be used to denote this. *e.g.*, *mole_fraction_of_ozone_in_dry_air*.
+#. By default, ``mole_fraction_of_X_in_Y`` refers to the total amount of *Y*. So, for example,
+   ``mole_fraction_of_ozone_in_air`` refers to the total amount of (moist) air. (In the case of air,
+   the default meaning is moist air, as described in the :ref:`*mixing ratio* rule <mixing_ratio>`.) When this is not
+   the case, a qualifier should be used to denote this. *e.g.*, ``mole_fraction_of_ozone_in_dry_air``.
 
 #. When referring to soil quantities,
    *volume_fraction* should be used to express the volumetric soil moisture.
 
-#. Number concentration should appear as a prefix, that is, *number_concentration_of*. By default,
+#. Number concentration should appear as a prefix, that is, ``number_concentration_of_X``. By default,
    number concentrations are specified per unit of volume. When they are specified per
-   unit of mass, they should be written as *mass_number_concentration_of*.
+   unit of mass, they should be written as ``mass_number_concentration_of_X``.
 
-#. By default, *precipitation* refers to the sum of all phases of precipitating hydrometeors,
-   for example rain plus graupel plus hail.  The term *frozen_precipitation* refers to the
-   sum of all frozen precipitating hydrometers, for example graupel plus hail (but not rain).
+#. By default, ``precipitation`` refers to the sum of all phases of precipitating hydrometeors,
+   for example "rain plus graupel plus hail".  The term ``frozen_precipitation`` refers to the
+   sum of all frozen precipitating hydrometers, for example "graupel plus hail" (but not rain).
    Otherwise the standard name should explicitly state the type of hydrometeor(s) the
-   named quantity represents (e.g. *graupel*).
+   named quantity represents (e.g. ``graupel``).
 
-#. By default, the term *cloud* refers to all cloud phases and cloud types. Otherwise
+#. By default, the term ``cloud`` refers to all cloud phases and cloud types. Otherwise
    an additional prefix or suffix should be added to the standard name specifying what kind(s)
-   of clouds the variable represents (e.g. *ice_cloud* if only including glaciated clouds, or
-   *cloud_at_500hPa* if only including clouds that exist at 500 hPa).
+   of clouds the variable represents (e.g. ``ice_cloud`` if only including glaciated clouds, or
+   ``cloud_at_500hPa`` if only including clouds that exist at 500 hPa).
 
-#. Spell out acronyms unless they are defined in the list of "Acronyms, Abbreviations, and Aliases"
-   below. Whenever such an alias exist, use the alias in the
-   standard name and the full term in the description.
+#. Spell out acronyms unless they are defined in the
+   :ref"`list of "Acronyms, Abbreviations, and Aliases" <Aliases>`. Whenever such an alias exists,
+   use the alias in the standard name and the full term in the description.
 
 #. Chemical species in standard names should be denoted by chemical formulae (e.g. ``co2``,
    ``ch4``, ``c5h8``) or commonly accepted designations (e.g. ``cfc12``); generally when there are
@@ -225,30 +229,42 @@ Terminology
    +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
    | **Prefix**        |  **Type** | **Use case**                    | **Example**                                                 |
    +===================+===========+=================================+=============================================================+
-   | `is_`             | `logical` | A flag indicating some state or | `is_mpi_root` indicates whether or not the code is running  |
+   | ``is_``           |``logical``| A flag indicating some state or | ``is_mpi_root`` indicates whether or not the code is running|
    |                   |           | condition is true or false      | on the MPI root process                                     |
    +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
-   | `do_`             | `logical` | A flag whose value directs some | `do_chemical_tracer_diagnostics` indicates to a physics     |
+   | ``do_``           |``logical``| A flag whose value directs some | ``do_chemical_tracer_diagnostics`` indicates to a physics   |
    |                   |           | behavior                        | scheme that it should compute chemical tracer diagnostics   |
    +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
-   | `identifier_for_` | `integer` | A parameter indicating some     | `identifier_for_noah_land_surface_scheme` is an integer     |
+   |``identifier_for_``|``integer``| A parameter indicating some     | ``identifier_for_noah_land_surface_scheme`` is an integer   |
    |                   |           | state or condition              | identifying the Noah land surface model                     |
    +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
-   | `control_for_`    | `integer` | A control whose value directs   | `control_for_land_surface_scheme` is an integer identifying |
-   |                   |           | some behavior                   | the land surface scheme type                                |
+   | ``control_for_``  |``integer``| A control whose value directs   | ``control_for_land_surface_scheme`` is an integer           |
+   |                   |           | some behavior                   | identifying the land surface scheme type                    |
    +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
-   | `index_of_`       | `integer` | An index entry for an array     | `index_of_ice_vegetation_category` is an index describing   |
+   | ``index_of_``     |``integer``| An index entry for an array     | ``index_of_ice_vegetation_category`` is an index describing |
    |                   |           |                                 | the location of the ice vegetation category in the array of |
    |                   |           |                                 | vegetation categories                                       |
    +-------------------+-----------+---------------------------------+-------------------------------------------------------------+
 
 #. The ``direction`` of a vector, unless noted otherwise, is the geographical bearing measured in the positive clockwise direction from due north. For example, ``wind_to_direction = 90`` is the same as ``wind_from_direction = 270``, meaning wind blowing towards the east.
 
-#. **Disallowed terms:** A few terms are disallowed as standard name components for various reasons; mostly due to
-   ambiguity.
+Disallowed terms
+----------------
+
+A few terms are disallowed as standard name components for various reasons; mostly due to ambiguity:
+
+   - ``specific_humidity``
+
+     Disallowed due to ambiguity and different definitions between different fields. See above section describing ``mixing_ratio`` for more information.
+   - ``amount``
+
+     In most contexts this word is superfluous, and in all contexts it is non-descriptive. Consider a more specific term such as ``mass_content``
+
+Reserved names
+--------------
 
-   - ``specific_humidity`` Disallowed due to ambiguity and different definitions between different fields. See above section describing ``mixing_ratio`` for more information.
-   - ``amount`` In most contexts this word is superfluous, and in all contexts it is non-descriptive. Consider a more specific term such as ``mass_content``
+Currently there is only one "reserved" phrase that should only be used by a specific modeling
+system component. Others may be added here in the future as needed.
 
-#. **Reserved names:** The prefix ``ccpp_`` is reserved for CCPP framework-provided variables.
-   All other standard names should avoid the use of ``ccpp`` in their name.
+#. The prefix ``ccpp_`` is reserved for CCPP framework-provided variables. All other standard names
+   should avoid the use of ``ccpp`` in their name.

From 93dcc95b580d7e34487b7fb3c438ecde196e3889 Mon Sep 17 00:00:00 2001
From: "Michael Kavulich, Jr" <kavulich@ucar.edu>
Date: Wed, 23 Sep 2026 08:36:40 -0600
Subject: [PATCH 21/21] Simplify code to pass pylint branches check

---
 tools/write_standard_name_table.py | 14 +++-----------
 1 file changed, 3 insertions(+), 11 deletions(-)

diff --git a/tools/write_standard_name_table.py b/tools/write_standard_name_table.py
index 526c936..bca9de3 100755
--- a/tools/write_standard_name_table.py
+++ b/tools/write_standard_name_table.py
@@ -118,17 +118,9 @@ def parse_section(snl, sec, level='##'):
     snl.write(f'{level} {sec_name}\n')
     if sec_comment is not None:
         # First, squeeze out the spacing
-        while sec_comment.find('  ') >= 0:
-            sec_comment = sec_comment.replace('  ', ' ')
-        while sec_comment:
-            sec_comment = sec_comment.lstrip()
-            cind = sec_comment.find('\\n')
-            if cind > 0:
-                snl.write(f'{sec_comment[0:cind]}\n')
-                sec_comment = sec_comment[cind + 2:]
-            else:
-                snl.write(f'{sec_comment}\n')
-                sec_comment = ''
+        sec_comment = re.sub(' +', ' ', sec_comment)
+        for line in sec_comment.split('\\n'):
+            snl.write(f'{line.strip()}\n')
     for std_name in sec:
         if std_name.tag == 'section':
             parse_section(snl, std_name, level + '#')