From eb337df174159d963f556562cf8ccbe7a6f259ed Mon Sep 17 00:00:00 2001
From: Chris Bell <chrisbell@bellsworne.com>
Date: Fri, 4 Jul 2025 00:58:04 -0500
Subject: [PATCH] Update some incorrect info on the docs

---
 szf-docs.html | 131 ++++++++++++++++++++++++++++++++++----------------
 1 file changed, 89 insertions(+), 42 deletions(-)

diff --git a/szf-docs.html b/szf-docs.html
index 984bd62..0bdc08a 100644
--- a/szf-docs.html
+++ b/szf-docs.html
@@ -5,7 +5,6 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Session Zero Format (.szf) Documentation</title>
   <link href="https://fonts.googleapis.com/css2?family=PT+Serif:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel="stylesheet">
-  <link rel="icon" href="d20_no-bg_medium.png">
   <style>
     :root {
       --background-color: #1a202e;
@@ -82,26 +81,6 @@
       color: var(--heading-color);
     }
 
-    .nav-content {
-      max-width: 1200px;
-      margin: 0 auto;
-      width: 100%;
-    }
-
-    .logo-container {
-      display: flex;
-      align-items: center;
-      gap: 1rem;
-      text-decoration: none;
-      color: inherit;
-    }
-
-    .logo-text {
-      font-size: 1.5rem;
-      font-weight: bold;
-      color: var(--heading-color);
-    }
-
     .container {
       display: flex;
       flex: 1;
@@ -315,7 +294,6 @@
         <a href="index.html" class="logo-container">
           <img src="d20_no-bg_medium.png" alt="SessionZero Logo" class="logo-placeholder">
           <div class="logo-text">SessionZero</div>
-          <link rel="icon" href="d20_no-bg_medium.png">
         </a>
       </div>
     </nav>
@@ -486,27 +464,37 @@ FieldName (text) = Some Value</code></pre>
         <ul>
           <li><strong>[Metadata] Section</strong>: Contains information about the dataset.
             <ul>
-              <li>Name (text): The human-readable name of the dataset.</li>
-              <li>Type (text): The category of the dataset (e.g., items, spells, classes).</li>
-              <li>Guid (text): A globally unique identifier. <em>Optional</em>.</li>
-              <li>Version (text): The semantic version of the dataset.</li>
+              <li><strong>Name (text)</strong>: The human-readable name of the dataset.</li>
+              <li><strong>Type (text)</strong>: The category of the dataset (e.g., items, spells, classes, etc.). This is a completely arbitrary value, and user-definable, but should match the intended use of the dataset.</li>
+              <li><strong>Guid (text)</strong>: A globally unique identifier. <strong>Optional</strong>: If left blank, the system can generate one.</li>
+              <li><strong>Version (text)</strong>: The semantic version of the dataset.</li>
+            </ul>
+          </li>
+          <li><strong>[EntryName] Section</strong>: In datasets, sections are referred to as entries. Each entry represents a specific item, spell, or other game element.
+            <ul>
+              <li>EntryName is the unique key for the entry within the dataset.</li>
+              <li>Every entry must have a non-empty <code>Name (text)</code> field. This is the display name for the entry.</li>
             </ul>
           </li>
-          <li><strong>[EntryName] Section</strong>: Each entry represents a specific item, spell, or other game element.</li>
         </ul>
 
         <h4>Example: CoreItems.szf</h4>
         <pre><code>!type: dataset
 !schema: 1.1.0
 
+# Metadata for the entire item collection
 [Metadata]
+# Required metadata for datasets
 Name (text) = Core Fantasy Items
 Type (text) = items
 Guid (text) = c3d4e5f6-g7h8-9012-cdef-123456789012
 Version (text) = 1.0.0
+
+# Optional metadata
 Author (text) = Fantasy Creator
 Description (text-field) = A collection of basic items for any fantasy campaign.
 
+# Definition for a Longsword
 [Longsword]
 Name (text) = Longsword
 Description (text-field) = A standard sword with a long blade and crossguard.
@@ -524,9 +512,24 @@ IsMartial (bool) = true</code></pre>
         <h4>Structure:</h4>
         <ul>
           <li><strong>[Metadata] Section</strong>: Contains information about the template.</li>
-          <li><strong>[RequiredDatasets] Section</strong>: Lists all datasets required by this template.</li>
-          <li><strong>[SectionName]</strong>: Defines sections on the character sheet with fields, types, and default values.</li>
-          <li><strong>System Fields</strong>: Special fields that modify section behavior.</li>
+          <li><strong>[RequiredDatasets] Section</strong>: Lists all datasets required by this template.
+            <ul>
+              <li>The field name is a local alias for the dataset (e.g., CoreItems).</li>
+              <li>The value is a pipe-separated string: DatasetName|GUID|Version.</li>
+            </ul>
+          </li>
+          <li><strong>[SectionName]</strong>: Defines sections on the character sheet with fields, types, and default values.
+            <ul>
+              <li>Subsections can be defined using dot notation (e.g., <code>[AbilityScores.Modifiers]</code>).</li>
+            </ul>
+          </li>
+          <li><strong>System Fields</strong>: Special fields that modify section behavior:
+            <ul>
+              <li><code>DatasetType (system)</code>: Restricts a section to hold references from datasets of a specific type (e.g., <code>items</code>).</li>
+              <li><code>DatasetReference (system)</code>: Restricts a section to hold references from a specific dataset, identified by its alias from <code>[RequiredDatasets]</code>.</li>
+              <li><code>AllowQuantity (system)</code>: When set, allows entry-reference fields within that section to have an associated quantity field.</li>
+            </ul>
+          </li>
         </ul>
 
         <h4>Example: FantasyTemplate.szf</h4>
@@ -534,20 +537,27 @@ IsMartial (bool) = true</code></pre>
 !schema: 1.1.0
 
 [Metadata]
+# Required metadata for character templates
 Name (text) = Standard Fantasy Character
 Guid (text) = f9e8d7c6-b5a4-3210-9876-543210fedcba
 Version (text) = 2.1.0
+
+# Optional metadata
 Author (text) = Template Master
 
+# Datasets needed for this character sheet
 [RequiredDatasets]
 ClassData (text) = Core Classes|aaa-bbb-ccc|1.5.0
 ItemData (text) = Core Fantasy Items|c3d4e5f6-g7h8-9012-cdef-123456789012|1.0.0
 WeaponData (text) = Core Weapons|12345678-90ab-cdef-1234567890ab|1.0.0
 
+# Character information section
 [Info]
 CharacterName (text) =
+# This field expects a single entry from the 'ClassData' dataset.
 Class (entry-reference) = ClassData
 
+# Ability scores with default values
 [AbilityScores]
 Strength (number) = 10
 Dexterity (number) = 10
@@ -556,21 +566,45 @@ Dexterity (number) = 10
 StrengthMod (calculated) = (AbilityScores.Strength - 10) / 2
 DexterityMod (calculated) = (AbilityScores.Dexterity - 10) / 2
 
+# An equipment section linked to a specific dataset `WeaponData`
+# This section can only contain references to entries in the `WeaponData` dataset.
 [Equipment]
 DatasetReference (system) = WeaponData
 
+# An inventory section that can hold multiple items from the `ItemData` dataset.
 [Inventory]
 DatasetType (system) = items
 AllowQuantity (system) = true</code></pre>
 
         <h3 id="character">Character (!type: character)</h3>
+        <h4>Structure:</h4>
+        <ul>
+          <li><strong>[Metadata] Section</strong>: Contains information about the character.
+            <ul>
+              <li><strong>TemplateRef (text)</strong>: A mandatory reference to the source template: TemplateName|GUID|Version.</li>
+            </ul>
+          </li>
+          <li><strong>Content Sections</strong>: The sections defined in the template are populated with the character's specific values. Field types are not re-declared.</li>
+        </ul>
+
         <p>A character file is an instance of a character_template filled with specific data. It <strong>only contains values</strong>, as the structure and types are defined by the template.</p>
 
-        <h4>Example: Elara.szf</h4>
+        <h4>Structure:</h4>
+        <ul>
+          <li><strong>[Metadata] Section</strong>: Contains information about the character.
+            <ul>
+              <li><strong>TemplateRef (text)</strong>: A mandatory reference to the source template: TemplateName|GUID|Version.</li>
+            </ul>
+          </li>
+          <li><strong>Content Sections</strong>: The sections defined in the template are populated with the character's specific values. Field types are not re-declared.</li>
+        </ul>
+
+        <h4>Example: Aela.szf</h4>
         <pre><code>!type: character
 !schema: 1.1.0
 
 [Metadata]
+# Required metadata for character files
 Name = Aela the Huntress
 Guid = a1b2c3d4-e5f6-7890-abcd-ef1234567890
 Version = 1.0.0
@@ -578,17 +612,27 @@ TemplateRef = Standard Fantasy Character|f9e8d7c6-b5a4-3210-9876-543210fedcba|2.
 
 [Info]
 CharacterName = Aela the Huntress
+# The value 'Ranger' is an entry from the 'ClassData' dataset,
+# as specified by the 'Class' field in the template.
 Class = Ranger
 
 [AbilityScores]
 Strength = 16
 Dexterity = 14
 
+# Calculated values are not stored in the character file.
+
 [Equipment]
+# This section becomes an addable list of items with quantities restricted to the `WeaponData` dataset, as defined in the template.
+# 'PrimaryWeapon' is a user-defined field name for the item.
+# The value 'Longsword' refers to the 'Longsword' entry in the 'WeaponData' dataset.
 PrimaryWeapon = ItemData.Longsword
 PrimaryWeapon.Quantity = 1
 
 [Inventory]
+# This section becomes an addable list of items from any dataset of type 'items', and allows specifying quantities.
+# 'HealingPotion' and 'HempRope' are user-defined field names for the items,
+# collected from the 'ItemData' notated by the prefix.
 HealingPotion = ItemData.HealingPotion
 HealingPotion.Quantity = 5
 HempRope = ItemData.HempRope
@@ -601,9 +645,10 @@ HempRope.Quantity = 2</code></pre>
         <h3>System Properties</h3>
         <p>System properties are special fields within a character_template that modify the behavior of a section:</p>
         <ul>
-          <li><code>DatasetType (system) = type</code>: Restricts a section to holding references from datasets of a specific type.</li>
-          <li><code>DatasetReference (system) = alias</code>: Restricts a section to holding references from a specific dataset.</li>
-          <li><code>AllowQuantity (system) = true</code>: Allows entry-reference fields to have associated quantity fields.</li>
+          <li><code>DatasetType (system) = type</code>: Restricts a section to holding references from datasets of a specific type (e.g., items).</li>
+          <li><code>DatasetReference (system) = alias</code>: Restricts a section to holding references from a specific dataset, identified by its alias from <code>[RequiredDatasets]</code>.</li>
+          <li><strong>Note:</strong> A section can have DatasetType or DatasetReference, but not both.</li>
+          <li><code>AllowQuantity (system) = true</code>: When set, allows entry-reference fields within that section to have an associated quantity field.</li>
         </ul>
 
         <h3>Quantity Fields</h3>
@@ -611,17 +656,19 @@ HempRope.Quantity = 2</code></pre>
         <p><strong>Syntax:</strong> <code>ReferenceFieldName.Quantity = value</code></p>
 
         <h3>Calculated Fields</h3>
-        <p>Fields of type <code>calculated</code> contain formulas that are evaluated by the application. They support:</p>
+        <p>Fields of type <code>calculated</code> contain formulas that are evaluated by the application:</p>
         <ul>
-          <li>Basic arithmetic operations (+, -, *, /)</li>
-          <li>Parentheses for grouping</li>
-          <li>Dot notation to reference other fields</li>
+          <li>Formulas can reference other fields using dot notation to access other sections (e.g., AbilityScores.Strength).</li>
+          <li>Supported operations should include basic arithmetic (+, -, *, /), and parentheses for grouping.</li>
         </ul>
 
         <h3>Wildcard Calculations</h3>
-        <p>For sections with AllowQuantity enabled, use wildcard syntax for aggregate calculations:</p>
-        <p><code>SectionName.*.FieldName</code>: Refers to the FieldName property of all items in SectionName.</p>
+        <p>For sections where AllowQuantity is enabled, special wildcard syntax can be used in calculated fields to perform aggregate calculations:</p>
+        <ul>
+          <li><code>SectionName.*.FieldName</code>: Refers to the FieldName property of <em>all</em> items referenced in SectionName.</li>
+        </ul>
 
+        <h4>Example (in a template):</h4>
         <pre><code>[Inventory]
 DatasetType (system) = items
 AllowQuantity (system) = true
@@ -631,10 +678,10 @@ TotalWeight (calculated) = Inventory.*.Weight * Inventory.*.Quantity</code></pre
       <div class="section">
         <h2 id="best-practices">Best Practices</h2>
         <ol>
-          <li><strong>GUIDs:</strong> Leave this blank, and the system will generate a GUID for you. This ensures uniqueness across datasets and templates.</li>
+          <li><strong>GUIDs:</strong> Leave this blank, and the system will generate a GUID for you. This ensures uniqueness across datasets and templates. If you need to specify one, use a valid GUID format.</li>
           <li><strong>Versioning:</strong> Use semantic versioning for your files to manage updates and breaking changes.</li>
           <li><strong>Naming Convention:</strong> Strictly use <strong>PascalCase</strong> for all SectionNames and FieldNames.</li>
-          <li><strong>Nested sections:</strong> Use dot notation to create logical hierarchies but avoid excessive nesting.</li>
+          <li><strong>Nested sections/Sub-sections:</strong> Use dot notation to create logical hierarchies but avoid excessive nesting to maintain readability.</li>
           <li><strong>Dependencies:</strong> Explicitly list all required datasets in templates.</li>
           <li><strong>Validation:</strong> Before use, validate that a file's structure is correct and all references are valid.</li>
         </ol>