Re: [Groff] ESR in manpages versus the WEB

[Eric S. Raymond]

Gunnar Ritter <address@hidden>:
> > I've described the two extensions I think would be merited.  The sort
> > of good-practice guidelines I nean are things like "don't use troff
> > requests outside the safe set" and "don't put running-text notes in a
> > synopsis section" and "don't write multiple description lines".
> 
> Multiple description lines?

I'm talking about name sections like this:

NAME
       bzip2, bunzip2 - a block-sorting file compressor, v1.0.3
       bzcat - decompresses files to stdout
       bzip2recover - recovers data from damaged bzip2 files

This is perfectly legitimate as troff, but the DocBook DTD only allows
one description line.  Multiple names are OK, so this passes muster:

NAME
       bzip2,  bunzip2,  bzcat,  bzip2recover  -  block-sorting  file compres-
       sion/uncompression, v1.0.3

This and the constraint on command synopses (no embedded text) are the
only places where DocBook enforces a structural regularity that man
markup doesn't have.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>