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

Bug #1173426 reported by Doug Smythies on 2013-04-26
This bug affects 2 people
Affects Status Importance Assigned to Milestone
Ubuntu Server Guide
Doug Smythies
ubuntu-docs (Ubuntu)
Doug Smythies

Bug Description

With the old theme (the one with the brown background) the use of the <keycap></keycap> pair in the source .xml file, resulted in significant text differentiation in the resulting html document.

With the new theme (the one with the red background) the use of the pair results in no differentiation in the resulting html document.

The PDF is O.K.

Example segment of source code:

then press the <keycap>+</keycap> key.

Two screen shots will be attached of the same area, one from the old theme and one from the new theme.

Doug Smythies (dsmythies) wrote :
Doug Smythies (dsmythies) wrote :
Doug Smythies (dsmythies) wrote :

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?

Doug Smythies (dsmythies) wrote :

The master file in question here is:


at and about line 1160:

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

If I change it to:

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

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

Doug Smythies (dsmythies) wrote :

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.

Changed in serverguide:
status: New → Confirmed
affects: serverguide → yelp-xsl (Ubuntu)
Doug Smythies (dsmythies) wrote :

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.

Doug Smythies (dsmythies) wrote :

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?

Doug Smythies (dsmythies) wrote :

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.

Doug Smythies (dsmythies) wrote :

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.

Doug Smythies (dsmythies) wrote :
Doug Smythies (dsmythies) wrote :
Doug Smythies (dsmythies) wrote :

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.

affects: yelp-xsl (Ubuntu) → ubuntu-docs (Ubuntu)
Changed in ubuntu-docs (Ubuntu):
assignee: nobody → Doug Smythies (dsmythies)
Changed in serverguide:
status: New → Confirmed
assignee: nobody → Doug Smythies (dsmythies)
Doug Smythies (dsmythies) wrote :

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.

John Kim (kotux) wrote :

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

Doug Smythies (dsmythies) wrote :

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

Changed in ubuntu-docs (Ubuntu):
status: Confirmed → Fix Committed
Launchpad Janitor (janitor) wrote :

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
    - Fix Various Bugs
    - 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 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

Changed in ubuntu-docs (Ubuntu):
status: Fix Committed → Fix Released
Doug Smythies (dsmythies) wrote :

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.

no longer affects: serverguide/quantal
no longer affects: serverguide/raring
no longer affects: serverguide/saucy
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.