FreeLists / openbeos / [openbeos] Re: Documentation tools in the source tree

["Axel Dörfler" <axeld@xxxxxxxxxxxxxxxx>]

Hi Niels,

"Niels Reedijk" <niels.reedijk@xxxxxxxxx> wrote:
> Since there was a consensus on docbook, I thought it would be nice to
> have the docbook tools integrated into the tree to lower the barrier
> of entry for everyone that wants to contribute on some sort of doc.

I'm fine with that, but let's hear other voices first, as I'm not that 
experienced with DocBook and the spirit of our build system yet :-)

> The following changes are in my local tree:
> - trunk/src/libs/libxml2 -- contains libxml2 version 2.6.26
> - trunk/src/libs/libxslt -- contains libxslt version 1.1.16
> - trunk/headers/libs/libxml2 -- contains the headers of libxml2 as
> needed by libxslt
> - trunk/src/documentation/docbook-dtd -- contains the docbook dtd 
> version 4.2
> - trunk/src/documentation/docbook-xsl -- contains the docbook xslt
> sheets version 1.70.0
> 
> I also changed the documentation rules. What happens is this: if you
> want to build the documentation, jam will construct the target
> <build>xsltproc, which depends on <build>libxslt.a, which depends on
> <build>libxml2.a. This tool will, with the help of the dtd and xsl
> sheet, generate the actual documentation.

Where does xsltproc live?
Also, as this is used for building the tree, but could also have a use 
outside of that, aren't the buildtools a more appropriate home for it 
(same with libxml2 and libxslt)? This doesn't really fit to your target 
of lowering the barrier for doc writers, though, and I'm also not sure 
if that's a very good idea either, as only very few people will 
actually use docbook (far less than those who build the tree, at 
least), and I would think we want to have the documentation to be part
final image, too, at some point. Furthermore, while jam and GCC are 
clearly needed to bootstrap the build process (hmm, they could be 
downloaded by "configure", as well, though, if needed :-)), the docbook 
tools aren't.

But to get distracted a bit, I like the idea of having "configure" care 
about the correct Jam+GCC version; if there are updates to either of 
them, configure could be updated as well to know their updated version 
string and test those. It already does a similar job when running on 
Linux (building the cross compiler), so that would probably be a 
natural extension.
Anyone up for it?

> * If yes, how do I effectively integrate it into svn, taking into
> account the existence of vendor branches and stuff?

If I understand the process correctly (maybe I'd do it to complicated, 
but at least it seems to make sense 8-)), you would copy the verbatim 
files into the vendor branch (using current), and tag their versions. 
Then you'd copy those into the actual location and apply any Haiku 
specific changes. At least that would be a clean way to go about it.

Bye,
   Axel.