Problems in hgrc.5
Eric S. Raymond
esr at thyrsus.com
Wed Jun 19 11:48:39 CDT 2013
Jordi Gutiérrez Hermoso <jordigh at octave.org>:
> The problem is that this manpage has a SYNOPSIS but no DESCRIPTION at
> all. Is this truly a problem?
It's two problems, actually - a cultural one and a technical one.
The cultural problem is that what you have under SYNOPSIS does not
obey the normal conventions for a manual-page synopsis. It is neither
a command synopsis nor a set of function prototypes nor a set of
profile names. It's running text giving an overview; it's exactly
like a DESCRIPTION section.
Conventionally, section 5 pages either don't have a synopsis at all
(see, for example, tzfile.5 or nanorc.5 or networks.5) or have a
synopsis considering of the unadorned name(s) of the config file (see,
for example, nfs.5 or deb_control.5). There are a handful of
exceptions that describe things like the command syntax of a
configuration loader (postmap.5) or a C include (utmp.5).
For hgrc.5 the right thing is probably no synopsis at all, because
the naming conventions for your files vary so much across platforms
and have to be explained in context. But there's a case for something
$home/lib/hgrc (Plan 9)
This would be unusual - I don't know of any other section 5 page with
platform qualifiers after the proffile names - but it would be in the
spirit of what is normally done.
Now to the technical problem:
That you've put running text in SYNOPSIS is not a technical problem at
all in troff-land, because troff doesn't enforce or rely on any of
these conventions. Very different story in XML-DocBook, which most
The XML-DocBook DTD thinks a SYNOPSIS section ought to match one of
the small set of alternatives I described above. It actually has
two elaborate sub-markups for describing command synopses and C function
There's an escape hatch - DocBook will let you put running text there -
but because the right thing is more structured, correct behavior for
a lifting tool is to try to parse one of those structures and complain
if it can't match any of them. Thus. doclifter complains.
<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>
More information about the Mercurial-devel