c0e8fa6df3a0bd406c4188d49ee00f20aef203e5
max
  Mon Sep 7 12:07:18 2026 -0700
Substitute trackDb variables in hub track description pages

A hub's description page comes straight off the hub's web server and has
never been through variable substitution, so a $db or $parentTrack in it
reached the reader as literal text. Native trackDb pages are fine, since
hgTrackDb substitutes them when it loads trackDb, but there was no
equivalent step for a hub.

hgc's getTrackHtml and hgTrackUi's trackUi both call hVarSubstTrackDbHtml
on a hub track's html.  Only a short list of variables is recognized there and nothing is an
error, because a hub page written before this existed can easily contain
a dollar sign inside a shell example, and silently rewriting that would
be worse than not substituting at all.

Adds $parentTrack, the name of the container a track sits in, which is
what a subtrack description page needs to link back to its superTrack or
composite. Views are skipped, since a view has no page of its own, and
the hub_<id>_ prefix is kept so the name works as hgTrackUi's g=
parameter. Documents $track, $parentTrack and $hgsid in trackDb/README.

refs #37599

diff --git src/hg/makeDb/trackDb/README src/hg/makeDb/trackDb/README
index 7d7f8f1662e..8bbd24333bc 100644
--- src/hg/makeDb/trackDb/README
+++ src/hg/makeDb/trackDb/README
@@ -56,30 +56,41 @@
      $organism - all lower case organism, like 'mouse'
      $db - database (like mm3, hg15, etc.)
      $date - freeze date of underlying assembly
      $blurb - If there is a blurb field in the .ra file this echos it.
      $matrix - content of the matrix and optional matrixHeader trackDb setting
                which will be converted to an HTML table. If there is no matrix
                setting, an empty string is substituted.
      $chainMinScore -  value that gets substituted into this statement on the
                chain or chainNet html page: 'Chains scoring below a minimum
                score of "$chainMinScore" were discarded'.
      $chainLinearGap - value for the -linearGap matrix used with axtChain
                (e.g. loose, medium). Gets substituted into the chain or
                chainNet html page.
      $downloadsServer - the value of the hg.conf downloads.server variable, or
                          hgdownload.soe.ucsc.edu if not set.
+     $track - the track's own name, as hgTrackUi's g= parameter needs it. For a
+               hub track that includes the hub_<id>_ prefix.
+     $parentTrack - the name of the container the track sits in, a superTrack or
+               a composite, in the same form as $track. Views are skipped, since
+               a view has no description page of its own. For a track that is
+               not in a container this is the same as $track. Useful for linking
+               a subtrack's description page back to its container, e.g.
+               <a href="hgTrackUi?db=$db&amp;g=$parentTrack">.
+     $hgsid - the current session id. Substituted only where there is a cart,
+               that is by the CGIs; hgTrackDb leaves it empty, so it is of use
+               in hub description pages rather than in native trackDb.
 In addition, if there is an $otherDb field set in the .ra file, these
 variables are available:
      $o_ORGANISM - all upper case other organism, like 'MOUSE'
      $o_Organism - initial capped other organism, like 'Mouse'
      $o_organism - all lower case other organism, like 'mouse'
      $o_db - other database (like mm3, hg15, etc.)
      $o_date - freeze date of underlying other assembly
 
 Any other ra fields may be referenced as a variable.
 The reference can be in the form $name or ${name}.  Without
 the braces, name is terminated by a character other than
 [0-9A-Za-Z_].  A literal $ is represented as $$.
 
 Here are some details on how to load various track types into the database
 tables: