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