[Serdev] Thoughts on Documentation -- Again

[Martin Hoffmann]

Martin Hoffmann wrote:
> 
> as you may have noticed, I am playing around with documentation lately.
> In the process I have tried many things: TeX, Docbook, various Wikis.
> In the end, I am afraid that short of writing something new (which I
> did, too, but that is a different matter), Docbook turns out to be the
> best system. While editing XML is quite horrible, the advantage of the
> tool base around it makes up for a lot. As prove, I have taken bits from
> the existing docbook for the auth module and crafted a man page for
> it:[0]
> 
>    http://www.partim.de/pub/misc/auth.7
> 
> I for one find having a manual page the perfect documentation. But of
> course, you can turn this into HTML or PDF or whatever.

Since I think the reference is the most important bit (at least for me),
I continued playing with this approach. The result is that I did write
my very first XSLT transformation yesterday (followed by the very strong
urge to get really drunk) to get the output of docbook2man to where I
want it. The result is yet another man page:

   http://partim.de/pub/misc/auth_db.7

I changed the formatting a bit and, since auth_db has that, added a
section for the database schema. Everyone interested, please have a look
and come back with suggestions, especially on the sectioning and
formal bits of content, as they should be the same for all pages.

If there are no objections, I'd like to check in the sources (as
$(module_name).xml in the module directory [the normal one, not doc])
plus the aforementioned .xsl file somewhere in doc.  If I am not
mistaken, the man pages itself are not supposed to be put into the
repository since they are generated. Instead, some Makefile hackery is
necessary to get make tar to create the man pages as well. Since I am not
that good with Makefiles, I would appreciate some help there.

Once at it, I'd also like to "convert" ser(8) and ser.cfg(5) to docbook
and write a quick introduction to the config file format in ser.cfg(5).

Best regards,
Martin