c7c977ef035c3ea2a45e3394f5d0fe9c1ed0739b
mspeir
  Wed Dec 24 10:56:26 2025 -0800
adding bulleted list of ra stanza specification, refs #35619

diff --git src/hg/htdocs/goldenPath/help/trackDb/trackDbHub.v3.html src/hg/htdocs/goldenPath/help/trackDb/trackDbHub.v3.html
index 5e05d855d80..cc56ea73716 100755
--- src/hg/htdocs/goldenPath/help/trackDb/trackDbHub.v3.html
+++ src/hg/htdocs/goldenPath/help/trackDb/trackDbHub.v3.html
@@ -49,41 +49,53 @@
 <div class="lightBlueBar">
     <div class="lightBlueBarTitle">&nbsp;&nbsp;Track Database Definition</div>
 </div>
 
 <!-- Finally to the content -->
 <div class="borderGuard">
 
 <DIV class="trackDbHub_intro">
 <H1>Hub Track Database Definition (<SPAN id="trackDbHub_version">v3</SPAN>)</H1>
 <H2>How to declare Dataset Display Settings in Genome Browser Hubs</H2>
 
     <p>For returning readers: We keep a <a href="changes.html">list of
         changes</a> to the trackDb specification below.</p>
 
     <P>This document describes how to set dataset display characteristics
-    using "track database" or "trackDb" settings through key-value pair
+    using "track database" or "trackDb" settings through name-value pair
     associations used in a Track Hub's trackDb.txt file.
 
     <P>The text file format for trackDb settings starts by creating a
-    text block, or "stanza", for each track dataset following
-    "ra" rules to establish a "record" of related settings. The first
-    line establishes the <code>track</code> "key", with additional lines
-    containing further "setting" keys, and one or more words or numbers
-    that follow, which are the "values" for each setting.  All trackDb
-    stanzas are keyed by <code>track</code> and delimited by blank lines.
-    Here is an example:</P>
+    text block, or "stanza", for each track dataset. These stanzas should be structured
+    according to the following format specification:
+    <ul>
+      <li>Lines consist of name-value pairs. The first line of the stanza
+          establishes the the <code>track</code> name. Additional
+          lines will contain further "setting" names followed
+          by "values" of one or more words of numbers.
+      <li>All trackDb stanzas must begin with a <code>track</code> line and a stanza ends
+          with a blank line.
+      <li>Periods should be avoided in <code>track</code> names, although there are some
+          settings that include periods in the name, e.g. filter.fieldName.
+      <li>The format supports '\' continuation characters. If the setting
+          is long or complex, break it into several lines using terminating
+          '\' characters to make it more readable.
+      <li>Text should be ASCII characters, but a limited set of Unicode characters are
+          <a href="/FAQ/FAQcustom.html#custom13">supported for longLabel and
+          shortLabel settings</a>.
+    </ul>
+    <p>Here is an example:</p>
 
     <pre>
         track myFirstTrack
         type bigBed 3
         bigDataUrl myFirstTrack.bb
         shortLabel Example Data
         longLabel The data in this track is format "bigBed 3".    </pre>
 
     <P>Every track stanza should have these five settings
     (<code>track type bigDataUrl shortLabel longLabel</code>).
     The first line's <code>track</code> key value (<code>myFirstTrack</code>) is the
     identifier for the dataset given to the Browser and it must be
     unique for each track within your data hub.  After the <code>track</code> key,
     the most important setting is the <code>type</code> key. This value
     (<code>bigBed 3</code>) tells the Browser the type of format the