[openbeos] Haiku Book and Revision 19612

Hi guys,

Merry Christmas to you all. Especially for this Christmas I put
something special under (or better: in) the tree: some Haiku Book
goodies.

Jérôme Duvall and I have been playing around (somewhat uncoordinated)
in the haiku book source. We tried several things (independently) and
I think it's time to bring out this messing about on the next level:
actually writing some standards to create an uniform way to write the
Haiku Book.

Even though I'm not absolutely convinced that Docbook is the best way
to go, I figured that every minute I (and we) spend on debating the
issue is a minute that is not invested in actually writing a Haiku
Book. And with correct procedures and some tools I figure we can make
the docbook Haiku Book a manageable solution.

So what's currently in the tree? It can be categorized into three
parts. First of all, there is a rough skeleton in place that divides
the book up in kits and that defines how the individual kits and
classes tie into the system. Secondly, the support kit documentation
contains some classes that show what the structure of an individual
class description is, and what syntactic elements it has to contain.
Finally, the midi2 kit contains a conversion of the doxygen
documentation Matthijs Hollemans did for his code. Please note that
the syntax of  the classes and the structure of that section might not
confirm to the rules I have set when experimenting in the support kit.

Furthermore, there is a document in the haiku_book subdir (located at
trunk/src/documentation/haiku_book) named howto.xml that is going to
be a howto for writing documentation. Currently it only deals with the
skeletal structure of classes (as you will find in the support kit
docs), but eventually it should be a complete guide for formatting and
content.

So what should we do to proceed? First of all, the current structure
resembles the BeBook. That's not without reason, the BeBook is
actually quite good and since most of us are used to it, it would be a
waste of time letting people getting used to another structure. The
structure is the division in kits and classes, and how classes are
actually described. The first thing to do is accept the BeBook as a
guide for the structure. Any inconsistencies and  usuability issues
will come out at a certain point in time and can be fixed accordingly.

So now we've accepted the rough structure, we need two tools to aid in
keeping the documentation consistent. The first thing is a tool that
checks a docbook file and checks whether the methodsynopsis (the
grammar of how methods are described in docbook) is correct and
consistent with the header. Jérôme already included and altered an
existing tool which can be found under
trunk/src/tools/docbook/headersampler/ . It basically needs to be made
a bit more conforming to the standards we are going to set.

The second tool is probably going to be a custom made tool. I thought
of a linking system to link between classes. In order to do this in a
less errorprone way I need to autogenerate a set of entities to link
between classes. Entities are aliases for longer pieces of docbook.
For example, I need to create an entity &BString_Length; that expands
to <link linkend="bstring_length"><function>Length()</function></link>.
Creating this manually is quite tedious (check midi2api.xml) so this
needs to be automated. I'm not very good at perl or python or any
other quick tool that can be used to write such a script, but I would
be able to explain very briefly to someone who can, what it should do
exactly.

With those tools handy, we could start defining some guidelines as to
how to write the actual content of the documentation. And after that,
writing the documentation is the final (and most labour-intensive)
step.

So, wrapping up, the current HOWTO is available at the location since
revision 19612. Do a jam in that subdirectory to generate both the
Haiku Book and the Howto(look under trunk/generated/documentation).
Then check what you think about the structure (look especially at the
Support kit, since that is the example of the eventual structure).
Check if you agree with them, and make suggestions for improvements.
Meanwhile, if you are able to write the autolinktool for me, e-mail
this list or me in particular and I'll tell you what it should do.
Finally if you are a beginner in Haiku (or BeOS) or if you are
studying C++ and you'd like to contribute, we can start by converting
all the headers to docbook. That way the developers can spend less
time on tedious manual labour and more on writing the content of the
Haiku book. Respond if you have some time to spare!

Again, merry Christmas, and I promise to teach myself to be less
verbal in e-mails for a new year's resolution.

Niels

Other related posts: