From 59dd711fefe88fc9bfc69826f7fc78ef0e6e3ab4 Mon Sep 17 00:00:00 2001
From: Paul Madden <paul.madden@noaa.gov>
Date: Wed, 27 Nov 2024 15:41:06 +0000
Subject: [PATCH] Update docs

---
 docs/sections/user_guide/yaml/tags.rst | 75 +++++++++++++++++---------
 1 file changed, 51 insertions(+), 24 deletions(-)

diff --git a/docs/sections/user_guide/yaml/tags.rst b/docs/sections/user_guide/yaml/tags.rst
index 8acd99caa..c622e85f2 100644
--- a/docs/sections/user_guide/yaml/tags.rst
+++ b/docs/sections/user_guide/yaml/tags.rst
@@ -35,7 +35,7 @@ Converts the tagged node to a Python ``boolean`` object. For example, given ``in
 
 .. code-block:: text
 
-   % uw config realize -i ../input.yaml --output-format yaml
+   $ uw config realize -i ../input.yaml --output-format yaml
    flag1: True
    flag2: True
 
@@ -52,7 +52,7 @@ Converts the tagged node to a Python ``datetime`` object. For example, given ``i
 
 .. code-block:: text
 
-   % uw config realize -i ../input.yaml --output-format yaml
+   $ uw config realize -i ../input.yaml --output-format yaml
    date1: 2024-09-01
    date2: 2024-09-01 00:00:00
 
@@ -69,49 +69,76 @@ Converts the tagged node to a Python ``float`` value. For example, given ``input
 
 .. code-block:: text
 
-   % uw config realize --input-file input.yaml --output-format yaml
+   $ uw config realize --input-file input.yaml --output-format yaml
    f2: 5.859
 
-``!int``
-^^^^^^^^
+``!include``
+^^^^^^^^^^^^
 
-Converts the tagged node to a Python ``int`` value. For example, given ``input.yaml``:
+Load and parse the files specified in the tagged sequence value and insert their contents here. For example, given ``numbers.yaml``:
 
 .. code-block:: yaml
 
-   f1: 3
-   f2: 11
-   f3: !int "{{ (f1 + f2) * 10 }}"
+   values: !include [constants.yaml]
+
+and ``constants.yaml``:
+
+.. code-block:: yaml
+
+   e: 2.718
+   pi: 3.141
 
 .. code-block:: text
 
-   % uw config realize --input-file input.yaml --output-format yaml
-   f1: 3
-   f2: 11
-   f2: 140
+   $ uw config realize --input-file numbers.yaml --output-format yaml
+   values:
+     e: 2.718
+     pi: 3.141
 
-``!include``
-^^^^^^^^^^^^
+Values from files later in the sequence overwrite their predecessors, and full-value replacement, not structural merging, is performed. For example, giben ``numbers.yaml``:
+
+.. code-block:: yaml
+
+   values: !include [e.yaml, pi.yaml]
 
-Parse the tagged file and include its tags. For example, given ``input.yaml``:
+``e.yaml``:
 
 .. code-block:: yaml
 
-   values: !include [./supplemental.yaml]
+   constants:
+     e: 2.718
 
-and ``supplemental.yaml``:
+and ``pi.yaml``:
 
 .. code-block:: yaml
 
-   e: 2.718
-   pi: 3.141
+   constants:
+     pi: 3.141
 
 .. code-block:: text
 
-   % uw config realize --input-file input.yaml --output-format yaml
+   $ uw config realize --input-file numbers.yaml --output-format yaml
    values:
-      e: 2.718
-      pi: 3.141
+     constants:
+       pi: 3.141
+
+``!int``
+^^^^^^^^
+
+Converts the tagged node to a Python ``int`` value. For example, given ``input.yaml``:
+
+.. code-block:: yaml
+
+   f1: 3
+   f2: 11
+   f3: !int "{{ (f1 + f2) * 10 }}"
+
+.. code-block:: text
+
+   $ uw config realize --input-file input.yaml --output-format yaml
+   f1: 3
+   f2: 11
+   f2: 140
 
 ``!remove``
 ^^^^^^^^^^^
@@ -131,5 +158,5 @@ and ``update.yaml``:
 
 .. code-block:: text
 
-   % uw config realize --input-file input.yaml --update-file update.yaml --output-format yaml
+   $ uw config realize --input-file input.yaml --update-file update.yaml --output-format yaml
    pi: 3.141