Re: manpage tools

[Daniel Leidert <daniel.leidert.spam@gmx.net>]

Am Mittwoch, den 28.03.2007, 17:01 +0200 schrieb Magnus Holmgren:
> What tools do you prefer for writing manpages (e.g. for commands that lack one 
> from upstream)?

DocBook XML/XSL

> A DocBook XML file is modern, maintainable, can be converted to other formats 
> as well, and is suggested by dh-make. But I don't quite like the output of 
> the docbook-xsl template: for example, the spaces on either side of the 
> vertical bar between <arg>s in <group>s can't readily be omitted. Moreover, 
> you have to write a *lot* of tags due to, IMHO, unnecessary limitations as to 
> which elements can be contained in which, and the autogenerated Authors 
> section clashes with the common "This manual page was written ... for the 
> Debian ..." Authors section.

There is already a bug-report open about this issue, asking for an
updated template. The docbook-xsl package contains an example for a
manpage: /usr/share/doc/docbook-xsl/examples/foo.1.example_manpage.xml.gz

I'm currently working on better support for making manpages from
XML/SGML (and a small Makefile, that can be included in debian/rules is
already ready, but not uploaded yet).

Regards, Daniel