html - new theme - <keycap> in .xml does not display with differentiation

When compiled, the issue is in the css file under span.key and there are two issues: First, bold is not specified (and this comes from higher up stuff); Second, there is some weird "span.key a" thing so it doesn't get hit anyway.
If I manually edit en.css and make it:

span.key {
  font-weight: bold;
  border-bottom: none;
}

Then things work as expected. So the question becomes how to change things such that the css file(s) will be correct.
For reference the default en.css area:

span.key a {
  border-bottom: none;
}

And note, for "key" there are only <span class="key keycap"> in the entire document. So what is the "a" for?

The master file in question here is:

/usr/share/yelp-xsl/xslt/common/html.xsl

at and about line 1160:

1158- <xsl:value-of select="$color.blue_border"/><xsl:text>;
1159-}
1160:span.key a {
1161- border-bottom: none;
1162-}

If I change it to:

1157- color: </xsl:text>
1158- <xsl:value-of select="$color.blue_border"/><xsl:text>;
1159-}
1160:span.key {
1161- font-weight: bold;
1162- border-bottom: none;
1163-}
1164:span.key a {
1165- border-bottom: none;
1166-}
1167-a > kbd {
1168- color: </xsl:text><xsl:value-of select="$color.link"/><xsl:text>;

Then things work as expected, but I do not know if I also break the weird "span.key a" thing.

I have been doing my work on a 12.04 server. It has yelp-xsl 3.4.1-1
The package doesn't seem to exist yet for saucy.
The raring version is 3.6.1-1, and the file and area of concern for this bug report is the same.

I will be un-assigning myself from this bug and changing "Affects" from serverguide to the package yelp-xsl. and status to confirmed.

There is version 3.8.1-1 for Saucy, it just isn't available in the package repository yet.
I looked at the source code on Launchpad, and the file and area in question is the same, however it is now in and around line 1251.

The issue of this bug report affects all official Ubuntu documentation.

Serverguide: DocBook source code, as described in previous entries, tag pairs of <kaycap>...</keycap> compile into html code of <span class="key keycap">...</span>

Ubuntu-docs (Desktop): Mallard code, tag pairs of <key>...</key> compile into html code of <span class=" key"><kbd>...</kbd></span>

Both also end up with a .css file based on the previously mentioned file, and they want to find a "span.key" entry to know what to do. It is not there, so they do nothing.

The file yelp-xsl/xslt/common/html.xsl requires an addition of these lines (slightly different than what I wrote in a previous post):

span.key {
  font-weight: bold;
}

This issue begs the question: How many more expected .css entries are missing?

Kevin Godby pointed out that in the Ubuntu-docs case, the <kbd></kdb> tag pair, which is inside most, but not all, <span class" key">...<.span> pairs does actually make a box around the key. For whatever reason "$color.gray_background" compiles into #f7f6f5, which is imperceptibly different than white, and also is not as declared in the color.xslt file ("'#f3f3f0'") (which probably is not grey enough anyhow). Once I took a screen shot and pasted it into photoshop and zoomed in (attached), I could finally see what Kevin referred to. This posting is for completeness only, and doesn't change the need to define "span.key" as per my previous posting.

This bug should be expanded to include all tags pairs where display differentiation would be desirable but it not present or not pronounced enough.

Another example, from the desktop docs, is within the <gui>...</gui> tags pair See also bug 1189282. I'll attach two screen shots, one from the old theme and one from the new theme.

I'm going to put this bug back to "serverguide" and add "ubuntu-docs", as I think the issues might be fixable via the two projects ubuntu.xsl files. I have actually already showed that it can be done, however doing so breaks other stuff. There is some very weird stuff going on, and things are somewhat overly intertwined. If the colors are set so that button backgrounds are actually visible, then the new theme header background becomes too dark. If the light text color is actually set to be lighter, it effects many other text elements as well (headers and such). If the yellow_border and yellow_background is actually set to be yellow, then yellow shows in places that we would not want to be yellow.

For whatever reason, the yelp-xsl file html.xsl file uses text_light for a great many things that should be at least normal text weight. So the ubuntu.xsl files for both serverguide and ubuntu-docs have merely redefined text_light as actually the same as text. (well, it defines it as '333' instead of '333333', but it renders as the same thing. (how is a color defined as only 3 digits anyhow? It takes 6 to define the 3 bytes.)) There are many other redefinitions of colors in the ubuntu.xsl files, seemingly done to force the resulting html to mimic the light-moin-theme, but at the same time breaking some other things.

So the way I am proposing to solve this bug report is: Add the missing span.key stuff to the ubuntu.xsl files; Add back meaningful color definitions; Add override definitions to the ubuntu.xsl files to use those colors as required.

For example:

<xsl:param name="color.text_light" select="'#333333'"/>
<xsl:param name="color.text_light_actually" select="'#aaaaaa'"/>

/* overide the yelp html.xsl here. Why? Because the defination of text_light is wrong above, but fixing it breaks a multitude of other things. */
span.gui, span.guiseq { color: </xsl:text>
  <xsl:value-of select="$color.text_light_actually"/><xsl:text>; }

It is a bit of a kludge on top of a kludge, but I don't know what else to do. It also makes for a bit of a messy css file as things end up defined and then overridden later.

Though it sounds trivial, hopefully you haven't spelled "definition" as "defination" as in the comment for the change. :-)

Oh ya, I did. Nothing is officially filed yet, so I'll fix it.

This bug was fixed in the package ubuntu-docs - 13.10

---------------
ubuntu-docs (13.10) saucy; urgency=low

  [Kevin Godby]
  * Improved wording of 'report a bug' footer text.
  * Added missing word (LP: #1170491)
  * Updated 'Google Docs' to 'Google Drive (LP: #1059554)
  * Various String Fixes and Validation Error Fixes
  * collect-screenshots.sh:
    - Fix Various Bugs
  * configure.in:
    - Bump version to 13.10
  * Update Add Accounts Instructions (LP: #1220968)
  * Merge updates from GNOME Upstream

  [John Kim]
  * String Fix (LP: #1189280)

  [Doug Smythies]
  * Add Colors (LP: #1173426)
  * fix-urls.sed:
  - Update Gnome Link
  * Update Screenshots
  * Update Time Instructions (LP: #1225251)
  * Replace Gwibber Page with Friends Page
  * Change references to Saucy (LP: #1225247)

  [Stephen Webb]
  * Update What's New for 13.10

  [Little Girl]
  * Improve Page Verbiage (LP: #1225829, LP: 1221452, LP: 1221456, LP: 1225842, LP: 1225842)
  * Added check_releases.sh to check for release versions in .page files

  [Benjamin Kerensa]
  * debian/control: Update Vcs-Bzr Field
  * debian/copyright: Update Copyright Year
 -- Benjamin Kerensa <email address hidden> Tue, 17 Sep 2013 01:04:05 -0700

Upstream reference:
https://bugzilla.gnome.org/show_bug.cgi?id=709943

While the root issue has been fixed in the upstream yelp-xsl, I intend to leave the ubuntu.xsl override in place. Why? Because the default differentiation remains, in my opinion, imperceptible.