xml or html for Ubuntu Guides

[Matthew East]

On Sat, 2005-12-03 at 08:57 +0100, Vincent Untz wrote:
> Hi,
> 
> Le vendredi 02 décembre 2005 à 17:14 +0000, Matthew East a écrit :
> > Hi all (sending to -doc and -desktop),

{snip}
 
> > 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?

It is probably not that hard to change yelp's stylesheet: however I
imagine (I haven't looked into this) that it is non-trivial to get yelp
to use different stylesheets for different documents. If that is right,
then we've have the two problems:
* We might have to ensure that our stylesheets (and css) work for all
documents, rather than just Ubuntu-specific ones.
* We might have to use the same stylesheet for the ubuntu-specific
documents. This would be a problem because we're currently using at
least two types of stylesheet, one for articles [1] and one for books
[2].

[1] An example is http://doc.ubuntu.com/ubuntu/aboutubuntu/C/index.html
[2] An example is http://doc.ubuntu.com/ubuntu/desktopguide/C/index.html

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

I think it is: slow loading static help pages are a turn off for (at
least some) users, those users will go on irc or the forum. If
everything else is equal and the alternatives are (a) fast, or (b) slow,
then I would obviously go with (a) :)

> > * 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 :-)

Most web browsers that I know don't read xml. We currently convert them
to html [1], [2], and [3], that was my point.

[3] http://help.ubuntu.com

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

You didn't bring any reasons in favour of shipping in xml? Why do you
prefer that?

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/20051203/d8f68571/attachment.pgp