Re: <OK> Re: [Groff] ESR in manpages versus the WEB

[M Bianchi]

> On Mon, Jan 01, 2007 at 11:32:11AM -0500, Eric S. Raymond wrote:
> > Gunnar Ritter <address@hidden>:
> > > Eric S. Raymond wrote:
> > > ... 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.  ...

But that form is _so_ much easier to read and understand, especially for the
novice!  That, to my mind, is the overriding goal of the exercise.

This would seem be argue for structural macros.  E.g.

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

Here, particularly, is a case where a few man page templates would go a long
way towards encouraging good practice, even for us "experienced" groffers, but
especially for the new-comers.

Surely  doclifter  could deal with macros of that model and create DocBook stub
pages to point to the full-blown page; or am I missing something?

--
 Mike Bianchi