[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Groff] Multiple description lines in DocBook [was: ESR in manpages vers
From: |
Michael(tm) Smith |
Subject: |
[Groff] Multiple description lines in DocBook [was: ESR in manpages versus the WEB] |
Date: |
Wed, 3 Jan 2007 21:50:07 +0900 |
User-agent: |
Mutt/1.5.13 (2006-08-11) |
"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/