Splitting up the xml spec file

[Richard Hughes]

(Okay, all files relative to doc/spec/)

At the moment we have one giant xml docbook file (hal-spec.xml.in) 
We need the .in suffix as we have stuff like version strings from
configure, and this is made into hal-spec.xml.
hal-spec.xml is then converted to hal-spec.html using docbook2html.

To split this up I think we need to do a few things:

* initially split it up into 4 chapters (we can further split it up if
required, but later...)
 - hal-spec-introduction.xml
 - hal-spec-properties.xml
 - hal-spec-fdi-files.xml
 - hal-spec-examples.xml      
* Use a master document where all the files are include'd from:
 - hal-spec-main.xml.in (we need the @VERSION@ here)

I'm proposing not running all the chapter files through configure (i.e.
they have .xml endings rather than .xml.in) as there's no need for any
constants to be used -- and cuts down on the configure requirement when
we change a file.

Now to include the xml documents, we need to use <xi:include../> which
makes the main file non-valid docbook, and hence cannot be used with
docbook2html (docbook2html is just a wrapper round openjade).

The best solution I've found if to use the following snippet:

xmllint --xinclude --postvalid --noent hal-spec-main.xml.in >
hal-spec.xml
docbook2html --nochunks hal-spec.xml -o .

Which takes all the included parts of the spec, and puts them in
hal-spec.xml (like we had before) and then we can run docbook2html (like
we did before).

We can easily add the xmllint line to Makefile.am, unless any xml gurus
know how to do this on one line.

I've also found lots of random spacing in the xml files, so I've been
repairing files as I've been going through them. I've also had to rip
references out to fdi files that did not exist anymore to make the
document validate.

Short term plan (if deemed okay): add the files, and get rid of the
large spec file we have now so we can easy work with the new files and
Joe can start committing the freebsd fixes :-)

Medium length plan (~week?): go through each included part of the spec
file, updating screenshots, correcting grammar and adding method names
and properties where applicable.

Long term plan (months?): Get the spec into serious shape so we can
point people at the spec with confidence.

How does that sound?

Richard.