docbook and output files

[Matthew East]

Hi,

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hello,
>
> I have recently joined Xubuntu documentation team, and I have a few basic
> questions to ask.

Welcome aboard!

> As I was familiarizing myself with the way the documentation is structured
> I
> noticed that if I open, say, index.xml in yelp, the links to the chapters
> wouldn't work, pointing to .html files instead.

The reason for this is that the links in index.xml are hardcoded as links
to HTML files - this is because the ONLY use for index.xml is as an index
on the website (which is made up of all html files). We don't use
index.xml in the system documentation, or in yelp.

> I am aware that makefiles
> finally render .html files from the docbook trunk so my first question is:
> Should documentation in .xml be usable for an end-user as well? Or does
> the
> end user get just the compiled output in the form of .html files and
> docbook
> is just a smart way for us to manage and store the documentation?

Yelp can open xml files, and it does this by converting the xml into basic
html "on the fly". So yelp reads xml, and the user actually sees html. In
the makefiles, we do xml->html conversion at build time for the website
version of the documentation.

I hope that this answers your questions.

Matt