xml or html for Ubuntu Guides

Matthew East mdke at ubuntu.com
Fri Dec 2 17:14:50 GMT 2005

Hi all (sending to -doc and -desktop),

Some may remember that early in the Breezy release process the
documentation team spent a couple of meetings and a lot of mailing list
traffic about the classic question of what format to ship our docs in.

The options are:

xml, or html. Those who run dapper can see that for the purposes of
answering this question, we've uploaded both formats in the latest

The question affects ubuntu-docs. The decision for Breezy was to ship
them in html, but this decision was rapidly reversed shortly prior to
release when Seb and Jeff W pointed out that this broke the About Ubuntu
panel entry (there was no way of ensuring that the localised copy of the
document got opened from the panel).

For dapper, the About Ubuntu panel entry looks like it is going to be
opening a program [1] written especially for the purpose (like the About
Gnome dialogue), rather than yelp. So it looks like the problem
encountered in Breezy will not arise.

[1] https://wiki.ubuntu.com/AboutUbuntu

For this reason, the possibility of shipping the docs in html is now
again a valid one, and I thought I would therefore reopen debate on the
subject. I envisage that the debate will be less disorganised than the
last one, because (a) we have the benefit of experience from the Breezy
debacle, and (b) I'm mailing the desktop people so that we get a broad
range of technical opinion.

My personal opinion is in favour of html. Here are what I see the
advantages and disadvantages of html:


* We can customise the stylesheets for the documents more easily
(building on the css already in place) by simply working on the
ubuntu-book.css shipped with the package. This can be done without
affecting the non-ubuntu documentation.
* Greater loading speed (this is the killer for me) - Yelp renders in
html, and therefore converts xml to html using its own stylesheets when
you load a document. The time it takes to load pages from xml in yelp is
probably enough to put the user off the help entirely! If we ship html,
the xml->html conversion is undergone in the build process, which means
that the document opens instantly.
* minor advantages - same format as kubuntu docs, we can put the same
format on help.ubuntu.com as we put in the distribution.


* There is no side panel in the html. I don't think this is a
particularly serious disadv. because the html we build has quite good
navigation included.
* We need to ensure that translation will work: I am fairly confident
that it will - shipping localised omf files in
(e.g.) /usr/share/omf/desktopguide-html/ will work I believe.
* We may have to ship the xhtml transitional dtd because scrollkeeper
doesn't seem to have it already.

So all in all, the advantages are huge, and the disadvantages are not
really disadvantages, or where they are, they are outweighed :)

Ok, let discussion commence (please reply to both lists if you can). If
anyone spots any advantages or disadvantages I've missed, please tell
us, and let's have people's views as to what format to ship!

thanks, Matt
mdke at ubuntu.com
gnupg pub 1024D/0E6B06FF
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.ubuntu.com/archives/ubuntu-desktop/attachments/20051202/42c9b288/attachment.pgp

More information about the ubuntu-desktop mailing list