Patchwork Problems in hgrc.5

login
register
mail settings
Submitter esr@thyrsus.com
Date June 18, 2013, 5:13 a.m.
Message ID <20130618051352.EA03B41783@snark.thyrsus.com>
Download mbox | patch
Permalink /patch/1733/
State RFC, archived
Headers show

Comments

esr@thyrsus.com - June 18, 2013, 5:13 a.m.
This is automatically generated email about markup problems in a man
page for which you appear to be responsible.  If you are not the right
person or list, please tell me so I can correct my database.

See http://catb.org/~esr/doclifter/bugs.html for details on how and
why these patches were generated.  Feel free to email me with any
questions.  Note: These patches do not change the modification date of
any manual page.  You may wish to do that by hand.

I apologize if this message seems spammy or impersonal. The volume of
markup bugs I am tracking is over five hundred - there is no real
alternative to generating bugmail from a database and template.

--
                             Eric S. Raymond
Problems with hgrc.5:

Renaming SYNOPSIS because either (a) third-party viewers and
translators will try to interpret it as a command synopsis and become
confused, or (b) it actually needs to be named "SYNOPSIS" with no
modifier for function protoypes to be properly recognized.
Jordi Gutiérrez Hermoso - June 19, 2013, 1:45 p.m.
Sup, Eric.

On 18 June 2013 01:13,  <esr@thyrsus.com> wrote:
> Problems with hgrc.5:
>
> Renaming SYNOPSIS because either (a) third-party viewers and
> translators will try to interpret it as a command synopsis and become
> confused, or (b) it actually needs to be named "SYNOPSIS" with no
> modifier for function protoypes to be properly recognized.
>
> --- hgrc.5-unpatched    2012-07-28 09:23:15.949459835 -0400
> +++ hgrc.5      2012-07-28 09:23:31.317459443 -0400
> @@ -30,7 +30,7 @@
>  .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
>  .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
>  ..
> -.SH SYNOPSIS
> +.SH DESCRIPTION
>  .sp
>  The Mercurial system uses a set of configuration files to control
>  aspects of its behavior.

The problem is that this manpage has a SYNOPSIS but no DESCRIPTION at
all. Is this truly a problem?

- Jordi G. H.
Nikolaj Sjujskij - June 19, 2013, 4:10 p.m.
Den 2013-06-19 17:45:40 skrev Jordi Gutiérrez Hermoso <jordigh@octave.org>:

> Sup, Eric.
>
> On 18 June 2013 01:13,  <esr@thyrsus.com> wrote:
>> Problems with hgrc.5:
>>
>> Renaming SYNOPSIS because either (a) third-party viewers and
>> translators will try to interpret it as a command synopsis and become
>> confused, or (b) it actually needs to be named "SYNOPSIS" with no
>> modifier for function protoypes to be properly recognized.
>>
>> --- hgrc.5-unpatched    2012-07-28 09:23:15.949459835 -0400
>> +++ hgrc.5      2012-07-28 09:23:31.317459443 -0400
>> @@ -30,7 +30,7 @@
>>  .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
>>  .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
>>  ..
>> -.SH SYNOPSIS
>> +.SH DESCRIPTION
>>  .sp
>>  The Mercurial system uses a set of configuration files to control
>>  aspects of its behavior.
>
> The problem is that this manpage has a SYNOPSIS but no DESCRIPTION at
> all. Is this truly a problem?
  Well, if this section isn't really a SYNOPSIS, why not rename it to  
DESCRIPTION?
esr@thyrsus.com - June 19, 2013, 4:48 p.m.
Jordi Gutiérrez Hermoso <jordigh@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.
esr@thyrsus.com - June 19, 2013, 5:11 p.m.
Nikolaj Sjujskij <sterkrig@myopera.com>:
>  Well, if this section isn't really a SYNOPSIS, why not rename it to
> DESCRIPTION?

That's what my patch does.
Matt Mackall - June 20, 2013, 7:08 p.m.
On Tue, 2013-06-18 at 01:13 -0400, esr@thyrsus.com wrote:
> This is automatically generated email about markup problems in a man
> page for which you appear to be responsible.  If you are not the right
> person or list, please tell me so I can correct my database.
> 
> See http://catb.org/~esr/doclifter/bugs.html for details on how and
> why these patches were generated.  Feel free to email me with any
> questions.  Note: These patches do not change the modification date of
> any manual page.  You may wish to do that by hand.
> 
> I apologize if this message seems spammy or impersonal. The volume of
> markup bugs I am tracking is over five hundred - there is no real
> alternative to generating bugmail from a database and template.
> 
> --
>                              Eric S. Raymond
> Problems with hgrc.5:
> 
> Renaming SYNOPSIS because either (a) third-party viewers and
> translators will try to interpret it as a command synopsis and become
> confused, or (b) it actually needs to be named "SYNOPSIS" with no
> modifier for function protoypes to be properly recognized.
> 
> --- hgrc.5-unpatched	2012-07-28 09:23:15.949459835 -0400
> +++ hgrc.5	2012-07-28 09:23:31.317459443 -0400
> @@ -30,7 +30,7 @@
>  .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
>  .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
>  ..
> -.SH SYNOPSIS
> +.SH DESCRIPTION

We build our manpages from RST files and source-level comments. I've
applied a patch that fixes the underlying text, thanks.
esr@thyrsus.com - June 20, 2013, 7:33 p.m.
Matt Mackall <mpm@selenic.com>:
> We build our manpages from RST files and source-level comments. I've
> applied a patch that fixes the underlying text, thanks.

Thanks.  There's another issue with generated section headers in hg.1
that I haven't figured out a fix for yet.  I'll look at the RST next time.

Patch

--- hgrc.5-unpatched	2012-07-28 09:23:15.949459835 -0400
+++ hgrc.5	2012-07-28 09:23:31.317459443 -0400
@@ -30,7 +30,7 @@ 
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.SH SYNOPSIS
+.SH DESCRIPTION
 .sp
 The Mercurial system uses a set of configuration files to control
 aspects of its behavior.