On Jun 05, 2008 at 21:36, Martin Hoffmann <[EMAIL PROTECTED]> 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 _______________________________________________ Serdev mailing list [email protected] http://lists.iptel.org/mailman/listinfo/serdev
