[openbeos] Re: Documentation tools in the source tree
- From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Fri, 1 Sep 2006 17:28:07 +0200
> 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?
It's part of libxslt.
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.
I thought about that too, but eventually I thought the situation was
comparable to rc. Because it is a tool that is only interesting for
our build process at the moment. Sure, it could be used to build other
docbooks as well, but let's face it, just like rdef files, outside our
repository there aren't many of those around (whereas gcc and jam have
a wider spread). Also, at the moment there is a small interest in
building the docs. Basically, people who want to build them are doc
writers. That's why there is no general interest to include it in the
buildtools anyway - and even so, they could be moved there if the time
was right.
Having said that, there are pobably good arguments on putting the libs
with the buildtools as well. It's just that libxml and libxslt leave a
lot of stuff around, there are several binaries, libraries and tools
attached. I just don't see the point in cluttering anyones
installation with that.
Plus, this way works pretty transparant.
> * 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.
Okay, thanks for these instructions.
Still open for other thoughts/opinions.
Niels
Other related posts:
