Excessively complex, redundant markup in Ubuntu Server Documentation

[Lars Noodén]

The Ubuntu Server Manual has a lot of excessive and overly complex mark up. Simplifying the markup would facilitate maintenance by reducing the chance for errors. It would also, minimally, lower bandwidth requirements by allowing smaller file sizes.

Take for example this document on Kerberos authentication in Ubuntu:
    https://help.ubuntu.com/9.10/serverguide/C/kerberos.html

We see markup like these:

 <span class="emphasis"><em> ... </em></span>
 <span class="application"><strong> ... </strong></span>
 <span class="command"><strong> ... </strong></span>

Since CSS is used for the formatting and layout, the same effect could be had through much shorter, simpler markup:

 <em class="emphasis"> ... </em>
 <strong class="application"> ... </strong>
 <strong class="command"> ... </strong>

Bandwidth costs money.
Errors cost time, which is money.
K.I.S.S. is good engineering.

The conversion for the manual can be made accurately using a perl script.

[Eric Hickman (enhickman)]

changed source package to ubuntu-docs

[Matthew East (mdke)]

I think what you are referring to here is the HTML markup, rather than the original markup of the document, which is written in Docbook XML. The conversion of the document to HTML is performed by a parser called xsltproc and stylesheets supplied by the docbook-xsl package - the ubuntu-doc team doesn't have the time or the ability to modify the individual HTML markup used by these tools for specific commands. Ubuntu Server users will generally have enough bandwidth to download the few extra characters used by the markup. For that reason I'm closing the bug as "won't fix". If you want to pursue the principle upstream with docbook-xsl, you'll find information here: http://wiki.docbook.org/topic/DocBookXslStylesheets

[Lars Noodén (larsnooden)]

Let's wait on closing the bug until we actually *know* the source of the problem.

[Lars Noodén (larsnooden)]

If the document on the Ubuntu web site:

https://help.ubuntu.com/9.10/serverguide/C/

is not the original, please post the link to the Docbook, TEI-lite, or ISO 12083 version that is the original.

There isn't an obvious mention in the documentation of the existence of an original or the method that was used to generate the XHTML..

[Matthew East (mdke)]

Lars - I'm not sure why you say that we don't know the source of the problem, I'm pretty confident that I know which tools ubuntu-docs uses for building HTML, since I'm responsible for doing it.

Anyway, you can see the source code for the document in the bzr branch at lp:ubuntu-docs. You can browse it through a website here:

http://bazaar.launchpad.net/~ubuntu-core-doc/ubuntu-docs/lucid/files/head%3A/serverguide/C/

[Lars Noodén (larsnooden)]

Matthew - because the phrase 'I think' is, even on launchpad, usually followed by unsubstantiated claims usually easily proven wrong by checking with an authoritative source. In this case, since you are the one building the HTML documents out of the Docbook versions, you yourself are an authority on the topic.

Thanks for the bazaar link. It is what I was looking for but did not know about.

[Lars Noodén (larsnooden)]

In the eagerness to cancel the bug, it is overlooked that the error stems from the package 'docbook-xsl' which used to make the conversion to HTML.

[Daniel Leidert (dleidert-deactivatedaccount)]

There are plans to "clean" the (X)HTML output of docbook-xsl. So you can leave this open. However, this is not a short term goal. So it might stay open for a while.