[openbeos] Re: The Haiku Book
- From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Mon, 11 Sep 2006 10:48:11 +0000
Hi,
2006/9/11, Jérôme Duval <korli@xxxxxxxxxxxxxxxx>:
Back then, Docbook had the advantage of being transformable with XSL to any
content we'd like. We thought to Doxygen in a way to generate API
documentation, but it didn't have something really better than Docbook in
its use, apart its ability to parse source files for doc tags. Now, the
generated XML from Doxygen could be used to generate API docbook files.
I would like to disagree to the point that doxygen hardly has
advantages. The advantage that you don't mention is the fact that
Doxygen knows C++. It knows it's structure. Therefore it requires a
lot less work when you want to structure your documentation, since
Doxygen does that for you. Docbook at the other hand is 'dumb' and
requires you to structure your documentation yourself.
About the Docbook syntax, I don't think it's hard
to learn and write, particularly if there
is already a load of samples to reuse.
Like I said in the initial post, the syntax isn't hard, it's the
semantics that might be a problem. Even though we can document
hundreds of examples on what the format of a section on a class should
be, how every member should be documented (method, return values,
parameters, brief descriptions), how everything should be linked
together, and any other convention that will unevitably pop up, the
fact remains that it will become a complicated exercise which will
cost a lot of time. Valuable time which Haiku developers - who are the
main documenters - can't invest in something else.
The Boost XSL sheets used to convert from Doxygen XML are already in our
repository. It's not easy to integrate them and structure the book.
I've tried using the Boost XSL sheets. From source to documentation
has the following steps:
1. Generate the doxygen xml
2. Merge the xml together into one file. With xsl magic.
3. Apply the boost xsl magic to turn the format into a boostbook
4. Apply another piece of magic to turn it into docbook
5. Yet more XSL magic to convert to output.
I'll be frank: this probably isn't a good way to go about it. I was
less than impressed by the output. The whole process just seems like a
silly exercise.
If docbook output is (still) desired, I can see two ways to go about it.
1. Write XSL magic that works doxygen's XML to the docbook output as we wish it.
2. Code docbook output directly into Doxygen.
So it's not impossible to unite the doxygen universe with the docbook
one. Perhaps it's time to decide how to write proper API documentation
using doxygen...
Niels
Other related posts:
