Splitting up the xml spec file

[David Zeuthen]

On Tue, 2006-05-09 at 09:01 +0100, Richard Hughes wrote:
> (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?

Sounds good to me with using xmlto in the build chain as Ross points
out. Feel free to commit your changes. 

Thanks a lot for looking into this.

Cheers,
David