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. * 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. Disadvantages: * 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 -- [EMAIL PROTECTED] gnupg pub 1024D/0E6B06FF
signature.asc
Description: This is a digitally signed message part
-- ubuntu-desktop mailing list [EMAIL PROTECTED] http://lists.ubuntu.com/mailman/listinfo/ubuntu-desktop
