38fc33c4bbf6c8b960af709cb17a2467d6b6cac2
lrnassar
Tue Sep 29 15:40:59 2026 -0700
The description page variables section claimed shell and awk examples were safe from substitution, which is wrong twice over: parseVarNameMaybe accepts a bare $db as readily as ${db}, so an example using $db or $track as its own shell variable gets the value put in, and $$ still collapses to a single $. Say that instead, and document $$ as the way to write a literal dollar. The section also renders on trackDbDoc.html, which is the native trackDb doc, where "other trackDb settings are not available" is false, so it is now scoped to a hub's description page. Caught in code review of 8d05f42. refs #38283
diff --git src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml
index ddf0a6cc56b..4b6a72bb9f8 100644
--- src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml
+++ src/hg/htdocs/goldenPath/help/trackDb/trackDbLibrary.shtml
@@ -405,64 +405,69 @@
<P class="indent1">If the track has colors, or unusual display properties,
explain them in this section, or how to configure special settings.</p>
<p><b>Methods</b></p>
<p class="indent1">This section can explain data-handling algorithms,
or the significance of scores if generated in a special fashion.</p>
<p><b>Credits</b></p>
<P class="indent1">This section helps people find the contacts
for questions about the data. Please include an email or laboratory web page.</p>
<p><b>References</b></p>
<P class="indent1">Relevant publications regarding the data.</p>
</div>
<p><b>Example:</b></p>
<pre> html docs/myFirstTrack.html</pre>
Or with full path:
<pre> html https://path/to/location/docs/explainMyData.html</pre>
- <p><b>Variables in the description page</b></p>
- <p>The description page may use the variables below, written in the form
+ <p><b>Variables in a hub's description page</b></p>
+ <p>A hub's description page may use the variables below, written in the form
<code>${name}</code>. They are replaced when the page is shown, both on the track
settings page and on the item details page.</p>
<table class='bedExtraTbl'>
<tr><td><code>${db}</code></td><td>the assembly the track is being viewed on, for
example <code>hg38</code></td></tr>
<tr><td><code>${organism}</code></td><td>the organism in lower case, for example
<code>human</code></td></tr>
<tr><td><code>${Organism}</code></td><td>the organism with an initial capital, for
example <code>Human</code></td></tr>
<tr><td><code>${ORGANISM}</code></td><td>the organism in upper case, for example
<code>HUMAN</code></td></tr>
<tr><td><code>${date}</code></td><td>the release description of the assembly, for
example <code>Dec. 2013 (GRCh38/hg38)</code></td></tr>
<tr><td><code>${track}</code></td><td>the name of this track</td></tr>
<tr><td><code>${parentTrack}</code></td><td>the name of the container this track sits
in, either a <a href="#compositeTrack">compositeTrack</a> or a
<a href="#superTrack">superTrack</a>. A <a href="#view">view</a> is skipped, since
a view has no description page of its own. For a track that is not inside a
container, this is the same as <code>${track}</code>.</td></tr>
<tr><td><code>${downloadsServer}</code></td><td><code>hgdownload.soe.ucsc.edu</code>
</td></tr>
</table>
<p><code>${track}</code> and <code>${parentTrack}</code> come out with the prefix the
Genome Browser gives a hub track's name, so they can be used to build a link back into
the Browser. This is how the page of a track inside a container links to the container's
own page:</p>
<p><code><a href="hgTrackUi?db=${db}&amp;g=${parentTrack}">Back to the
container</a></code></p>
- <p>Nothing else is replaced. A dollar sign followed by anything other than the names
- listed above is left alone, so shell, awk and JavaScript examples elsewhere on the page
- are safe. Other trackDb settings are not available as variables, and neither is the
- session id.</p>
+ <p>These are the only names a hub's description page can use. Other trackDb settings
+ are not available as variables, and neither is the session id. UCSC's own description
+ pages are substituted when trackDb is loaded and follow different rules.</p>
+ <p>Take care with a dollar sign that is not meant as a variable. The bare form
+ <code>$db</code> is recognised as well as <code>${db}</code>, so a shell or awk example
+ that happens to use <code>$db</code> or <code>$track</code> as its own variable will come
+ out with the value substituted in. Write <code>$$</code> for a literal dollar sign:
+ <code>$$db</code> is shown as <code>$db</code>, and <code>$$</code> on its own is shown
+ as <code>$</code>.</p>
</DIV>
<DIV class="lessCommon_intro">
<H3>Common, though less frequently used settings</H3>
The following settings are available for many or all track types but are less frequently used.
Most are optional, but some may be required for specific track
types or in specific situations.<BR><BR>
<div class="hintBox">
<I><B>Inside hint:</B></I><I> The ra file
format supports '<code>\</code>' continuation characters. If the
setting is long or complex, break it into several lines using
terminating '<code>\</code>' characters to make it more readable.
</I>
</div>
<BR>