xml or html for Ubuntu Guides

[Vincent Untz]

Hi,

Le vendredi 02 décembre 2005 à 17:14 +0000, Matthew East a écrit :
> 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
> package.
> 
> 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:
> 
> Advantages:
> 
> * 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.

Is it hard to change the stylesheet for xml?

> * 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.

Is the speed loading difference important?

> * minor advantages - same format as kubuntu docs, we can put the same
> format on help.ubuntu.com as we put in the distribution.

I think we can put the xml files on the website. Or we can simply
convert them in html, it's not that hard :-)

The best option to me would be to go with xml, but if it's too
difficult, switch to html 2 months before the release, eg.

Vincent

-- 
Les gens heureux ne sont pas pressés.