asciidoc makes ugly man pags (was: cogito_0.10-1 available)

[Lars Wirzenius <liw@liw.iki.fi>]

su, 2005-05-08 kello 22:15 -0600, Sebastian Kuzminsky kirjoitti:
> The only lintian/linda complaints are from missing manpages.  Some
> upstream folks are working on translating the existing docs from .txt
> to manpages (actually asciidoc), so it'll hopefully get cleaner soon
> without me lifting a finger.  :)

I had a brief look at asciidoc. If its own manual page is produced with
asciidoc, then I would suggest that its manual page formatting engine
needs some serious fixing. The output has unnecessary empty lines, which
look quite ugly, and is missing boldface and italics usage. See man(7)
for a summary of what the custom for Linux manual pages is.

The troff source for asciidoc(1) claims it was produced by db2man.xsl,
but no such file exists on my filesystem after asciidoc has been
installed.

So far, docbook2x-man seems to produce the best manual page formatting,
though it too isn't perfect. If asciidoc produces manual pages via an
intermediate DocBook step, I suggest switching to docbook2x-man as the
engine to take it from DB to troff.