[Serdev] Thoughts on Documentation -- Again

[Andrei Pelinescu-Onciul]

On Jun 05, 2008 at 21:36, Martin Hoffmann <hn at nvnc.de> wrote:
> 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.

It looks very good to me.

> 
> 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.

We already put READMEs for convenience, so we might put man pages too
(especially if generating them involves installing lots of stuff).

> 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.

Ok, we need to decide where they will be generated (for example by make
doc or make man) and where to install them ( .../man/man7 ?). 
After that I volunteer to take care of the makefiles (if you send me the
magic command).

> 
> 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).
> 

Andrei