Documentation

[Gervase Markham]

David Miller wrote:
> Cons:
> 1) If someone checks in an XML change that doesn't validate, it'll likely
> take out the HTML version of the docs on the website if they don't fix it
> within 15 minutes.

I don't see this as a Con; people shouldn't be modifying the docs 
without rebuilding, just as they shouldn't modify code without building it.

> 2) People checking out of cvs who don't have docbook set up won't have the
> html and text versions of the docs to read.

I'm more concerned about this con. Can we mitigate it? We certainly 
don't want to require people to set up a docs build environment; it's  a 
real pain.

Suggestion: we could get the website build script to also build a 
documentation tarball (HTML, text and PDF), and checksetup.pl could 
offer to download and unpack it if there is no documentation present. 
This would only ever happen on CVS checkouts, as we'd be shipping docs 
in all the release tarballs anyway. So we wouldn't have problems 
worrying about version skew.

Gerv