a08ccd7dd4930bff5bcf0a32bd35ec22db71215f
markd
  Sat Aug 22 06:14:41 2026 -0700
Fix the browser.theme drop down, which has never applied a theme, and retire browser.background and browser.bgcolor from the example configs. refs #38158

themeDropDown built the menu label from the hg.conf key and posted that label
back, while setThemeFromCart looks a theme up by key, so no entry carrying a sort
prefix or an underscore could ever resolve.  Broken since af6898753ba (2023)
introduced that key format and changed the menu side without the lookup side.
themeDropDown now passes the key suffix as the option value and the prettified
label as the display text, using cgiMakeDropListWithVals.

setThemeFromCart compared the generated link against "<>" instead of the config
value, so the "no theme file" marker never fired.  It also let an empty link from
a missing CSS file overwrite browser.style with nothing.  Both now test the right
string and leave browser.style alone when there is no theme to apply.

browser.background has not been read by any CGI since hBackgroundImage() and its
callers were removed in 2012 (8e6fcda9f58), and browser.bgcolor has never been
read at all, yet ex.hg.conf presented browser.background as a working setting.
Commented both out with a note, in ex.hg.conf and the three browserbox configs.

ex.hg.conf also documented two conflicting browser.theme formats in two places.
The comma form stopped working in 2023.  Consolidated to a single block that
describes what the code actually does.

diff --git src/product/ex.hg.conf src/product/ex.hg.conf
index a1ccc03b511..6815f10bc78 100644
--- src/product/ex.hg.conf
+++ src/product/ex.hg.conf
@@ -355,47 +355,55 @@
 #	distinct from UCSC hguid cookie.  If you have *multiple* central
 #	databases for multiple hosts, set a distinct cookie name per
 #	central database.
 # central.cookie=hguid.mylab
 
 # Configuratuion database containing cart tables.  Normally thest in in the
 # 	same database as central.db, however can be overriden with these
 # 	variables if needed.  If any of these are set, all must be set.
 # cart.db=
 # cart.host=
 # cart.user=
 # cart.password=
 
 
 
-#	personalize the background of the browser with a specified jpg
-#	floret.jpg is the standard UCSC default
-browser.background=../images/floret.jpg
+#	browser.background is dead.  It set a BACKGROUND attribute on the BODY tag via
+#	hBackgroundImage(), which commit 8e6fcda9f58 removed in 2012 along with its four
+#	callers.  No CGI has read this key since.  Set a background image in CSS instead,
+#	with browser.style below.  refs #38158
+#browser.background=../images/floret.jpg
 
 
 # Change this default documentRoot if different in your installation,
 #	to allow some of the browser cgi binaries to find help text files
 browser.documentRoot=/usr/local/apache/htdocs
 
 # Options to personalize the visual style of the browser
-#   Personalize the background of CGIs that don't use images
+#   browser.bgcolor is dead, no CGI has ever read it.  Set colors in the CSS file
+#   named by browser.style.  refs #38158
 #browser.bgcolor=FFF9D2
-#   Add a custom CSS file
-#browser.style=gbib.css
-#   Give the user a choice between different background images and CSS files
-#browser.theme.modern=background.png,HGStyle
-#browser.theme.classic=floret.png,HGStyle-old
+#   Add a custom CSS file.  The value is emitted verbatim as a stylesheet href, so it
+#   can be any path the web server serves, inside the kent tree or not.  It is loaded
+#   after HGStyle.css.
+#   The file must qualify its body rules as body.cgi or body.hgTracks; HGStyle.css has
+#   class-qualified body rules that outrank a bare "body" selector.  Set a background
+#   with the "background" shorthand rather than "background-image": body.hgTracks sets
+#   repeat-x / left bottom / fixed, and those longhands survive a background-image
+#   rule, leaving the image as a band across the bottom instead of tiled.
+#browser.style=/style/gbib.css
+#   To offer the user a choice of styles, see browser.theme further down this file.
 
 # optional location of grepIndex files
 grepIndex.genbank=/data/tmp/grepIndex
 grepIndex.default=/gbdb
 
 #  new option for track reording functions, August 2006
 hgTracks.trackReordering=on
 #	in case of failure of the above central.host machine,
 #	the following settings will be used to access a secondary
 #	mirror of the database
 backupcentral.db=hgcentral
 backupcentral.host=localhost
 backupcentral.user=readwrite
 backupcentral.password=update
 #	archivecentral settings are used for archived assemblies
@@ -743,38 +751,45 @@
 #wuhCor1_TopLink=http://genome.ucsc.edu/goldenPath/help/covidBrowserIntro.html
 #wuhCor1_TopLinkLabel=Quick start guide
 
 # Similar to a survey link, but you can add a piece of html and configure everything yourself
 #hgTracksNoteHtml=<span style="color:yellow">Some text</span>
 
 # Configure a program to resolve cloud URLs to HTTP URLs.  See mirrorManual.txt for details.
 # need to specify either resolvProts or resolvPrefix. resolvPrefix exists for cases where the 
 # URL rewriting system does not use a protocol, but uses a fixed https://xxx domain instead.
 # resolvCmd gets run in both cases and must return the final URL to stdout on a single line.
 #resolvProts=fs,drs
 #resolvPrefix=https://myapp.okta.com
 #resolvCmd=/var/www/tools/urlResolver /var/www/tools/config
 
 # user-specific CSS files that can be activated via the configuration menu.
-# Not active on our main site and still under development
-# The format is browser.theme.<numberForSorting>.<labelUnderscoresAreSpaces>=<filenameInStyleDirectory>
-# A filename of "<>" means "no file", just the default CSS settings.
+# Not active on our main site and still under development.
+# The format is browser.theme.<name>=<filenameInStyleDirectory>, one CSS file per entry.
+# The selected theme replaces browser.style, it does not add to it.
+#
+# <name> may carry a leading number to order the menu, <sortNumber>.<label>, and any
+# underscore in the label shows as a space.  Entries sort by <name>, so number them if
+# you care about the order.  A value of "<>" means "no theme file", which leaves
+# whatever browser.style set, so it makes a good first entry.
+#
+# The value is one filename, not a list.  The old comma form, background.png,HGStyle,
+# has not worked since 2023 and is silently ignored.  refs #38158
 #browser.theme.1.Default=<>
 #browser.theme.2.Classic=theme-classic.css
 #browser.theme.3.Sans_Serif=theme-modern.css
-#browser.theme.4.Light_Blue=theme-lightBlue.css
-#browser.theme.5.Dark=theme-dark.css
+#browser.theme.4.Dark=theme-dark.css
 
 # print the javascript includes to the following external javascript libraries that allow
 # the interactive tutorial to work:
 # https://cdn.jsdelivr.net/npm/shepherd.js@11.0.1/dist/css/shepherd.css
 # https://cdn.jsdelivr.net/npm/shepherd.js@11.0.1/dist/js/shepherd.min.js
 # Having this variable off will cause the files to not be included and so the tutorial link
 # in the help menu won't work
 #showTutorial=on
 #
 # Enable the right-click "Color this item" menu, which lets a user recolor a single
 # track item's glyph or draw a background highlight behind it. Off by default.
 #canColorItems=on
 #
 # For more details on the three settings below, see #33812 (UCSC internal reference)
 # maxItemsPossible=100000 # Sets the maximum possible value in hg.conf that users can set in