Re: [Groff] man pages (tangential to Future Redux)

[Ingo Schwarze]

Hi,

Eric S. Raymond wrote on Fri, Feb 28, 2014 at 12:15:35PM -0500:

> most likely asciidoc.

To support my claim that this is a terrible idea, i just randonly
selected one of the 15 ports in the OpenBSD ports tree and formatted
its manuals with it.  Here is a list of issues with the generated
man(7) output:

 - The output uses HTML escape sequences, e.g. "Don’t daemonize".
   This is not only completely pointless, but obviously not going
   to work on any terminal, nor in any browser, either, given that
   the same document freely uses "<" and ">" and "&" characters.
   So this is an egregious case of inconsistent encoding.

 - The output misuses the .TH macro in two ways.
   It incorrectly sets the date to the empty string
   and the volume header to the page title.

 - The output uses wrong markup (\fI instead of \fB)
   for the program name everywhere, even in the SYNOPSIS.

 - The output incorrectly uses \fI instead of \fB for command
   line options.  Consequently, options are hard to distinguish
   from the placeholders for arguments.

 - Placeholders for arguments are placed inside angle brackets,
   i.e. "<...>", contrary to usual conventions.

 - The output includes lots of empty lines.
   This does not only violate roff and man(7) syntax,
   but also ruins vertical spacing, leading to really ugly
   final output from man(1), for example double blank lines
   between items of .TP lists.

 - The output incorrectly uses \- for dashes in the mittle
   of words in completely normal text, e.g. "... is a light\-weight
   HTTP proxy daemon designed to..." and "In addition to command\-line
   options, there are..."

 - The output incorrectly uses \&. for full stops at the of
   sentences in completely normal text.  That is likely to
   break inter-sentence spacing with some renderers.

 - The output fails to break the line after the end of sentences.
   That is likely to break inter-sentence spacing, yet again.

 - The output defines its own macros .Sh, .Sp, and .Ip,
   using low-level roff requests.  That's breaking the principle
   of separation of structure and content we just discussed
   and endangers portability.  Besides, it does so basically
   without any good reason.  The .Sp macro has little merit
   beyond .sp or .PP, in particular in view of the fact that
   it's doing a terrible job with verticle spacing elesewhere.
   The .Sh macro is a roll-your-own .SS, only with a less
   professional implementation, ignoring \n[PD] and failing
   to properly set the left margin, the font, and the font size,
   to provide some examples of its weakness.  It is included in
   the man(7) code even when it's not used.  Finally, .Ip is just
   a shallow wrapper around .IP needlessly fiddling with vertical
   spacing.

Note this is just from one randomly selected manual containing four
kilobytes, 600 words, including macros and prologue.  Taking any
substatial body of asciidoc-generated documentation, the list could
no doubt be continued.

This mess is typical for anything coming out of asciidoc and/or
DocBook.  In addition to that, DocBook is prone to outright formatting
bugs, in particular missing line endings, having several man(7)
macro lines end up on one single line, without the required line
break before each new macro line, of course completely garbling the
manual page.

Consequently, i counsel anybody who has the choice of formatting
tools to avoid asciidoc and DocBook at all cost.  If you must use
a preprocessor, the best format i'm aware of to start from is Perl
POD.  It's not pretty either, and pod2man(1) also generates an ugly
preamble, but at least what follows is decent man(7) code.

I didn't report this anywhere before because i simply didn't consider
asciidoc relevant in any sense, it is a niche product that is hardly
used anywhere.  But now that you say you want to push it, calling
it out for its utter weakness does make some sense, i think.

Yours,
  Ingo