[Groff] Multiple description lines in DocBook [was: ESR in manpages versus the WEB]

[Michael(tm) Smith]

"Eric S. Raymond" <address@hidden>, 2007-01-01 11:32 -0500:

> 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.

That was true prior to DocBook 4.3, but it's not true currently
(neither in DocBook 4 nor DocBook 5).

The current version of DocBook 4 is 4.5. And the version that should
be available as a package for most distros is 4.4 (which was
released 2 years ago) or at least 4.3 (released in 2004).

One of the changes that was made for DocBook 4.3 was to allow
multiples Refnamediv instances within a Refentry -- which enable
multiple description lines in output. See the content model here:

  http://www.docbook.org/tdg/en/html/refentry.html

So that means your example above would be valid DocBook if it were
marked up as follows:

  <refentry>
  <refnamediv>
    <refname>bzip2</refname>
    <refname>bunzip2</refname>
    <refpurpose>a block-sorting file compressor, v1.0.3</refpurpose>
  </refnamediv>
  <refnamediv>
    <refname>bzcat</refname>
    <refpurpose>decompresses files to stdout</refpurpose>
  </refnamediv>
  <refnamediv>
    <refname>bzip2recover</refname>
    <refpurpose>recovers data from damaged bzip2 files</refpurpose>
  </refnamediv>
  ...
  </refentry>

So there's currently no need for man-page authors to follow a
"don't write multiple description lines" best practice.

  --Mike

-- 
Michael(tm) Smith
http://www.w3.org/People/Smith/