Problems in hgrc.5

[Eric S. Raymond]

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
like this:

SYNOPSIS
    $home/lib/hgrc              (Plan 9)
    $HOME/.hgrc                 (Unix)
    %USERPROFILE%\.hgrc         (Windows)
    %USERPROFILE%\Mercurial.ini (Windows)
    %HOME%\.hgrc                (Windows)
    %HOME%\Mercurial.ini        (Windows)

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

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

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>