groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [groff] 02/03: refer.1.man: Put sections in conventional order.


From: Ingo Schwarze
Subject: Re: [groff] 02/03: refer.1.man: Put sections in conventional order.
Date: Sat, 29 Jun 2019 22:55:41 +0200
User-agent: Mutt/1.8.0 (2017-02-23)

Hi Branden,

G. Branden Robinson wrote on Sun, Jun 30, 2019 at 05:05:26AM +1000:
> At 2019-06-29T20:34:35+0200, Ingo Schwarze wrote:

>> Thanks for putting ENVIRONMENT before FILES.
>> 
>> But BUGS is always the very last section, certainly after SEE ALSO.
>> Groff itself documents that, see groff_mdoc(7), A MANUAL PAGE TEMPLATE.

> That may be true for mdoc-world, but it makes no sense to me.

It does make sense to me.

The sections following after SEE ALSO can be regarded as appendices
and/or auxiliary information: STANDARDS, HISTORY, AUTHORS, CAVEATS,
BUGS.

> "See Also" should come last, because it's the go-to place for the
> frustrated reader to who realizes they're reading the wrong man page,
> but are somewhere in the right neighborhood, and are seeking
> cross-references to get them where they need to go.

Exactly: so it comes after all the sections that describe the
intended syntax and semantics of the topic, and also after EXAMPLES
because examples often help to see at a glance what something is
all about.

But really, you don't need to study HISTORY, AUTHORS, and BUGS
to realize that some other page might help you more.

Either way, our personal opinions on how much sense it makes
matter little.  It was Ken and Dennis who made that decision to
put BUGS after SEE ALSO in Unix, and people no doubt got used to
it during those 45 years.

> But beyond my own opinion on the subject, Michael Kerrisk's man-pages
> project disagrees with you.  See man-pages(7):
> 
>            CONFORMING TO
>            NOTES
>            BUGS
>            EXAMPLE
>            SEE ALSO
> 
> (Now, in the spirit of full disclosure, on his website Michael Kerrisk
> deviates from his own style norm by grafting a site-generated "COLOPHON"
> section on to the end of all pages.  I can excuse this, since its
> purpose is to direct problem reports regarding man pages to the
> projectj that actually maintains them; and even with this information,
> the man-pages mailing list frequently gets bug reports about pages it
> doesn't maintain.  This practice makes the Web-hosted man pages a less
> salutary model for man page writers, but that is admittedly an
> endangered species.)

COLOPHON is ugly and unimportant, but we have no need to discuss it here.

What matters is that section conventions should not be changed
arbitrarily.  The whole point is that people can get used to them
and they always work the same way.

They have been formalized at least since AT&T Unix Version 3 in Feb. 1973,
even though Version 1 and Version 2 in 1971 and 1972 already informally
followed them.  Here is the what the file man/man0/xx in v3 says:

  NAME
  SYNOPSIS
  DESCRIPTION
  FILES
  SEE ALSO
  DIAGNOSTICS
  BUGS

  https://minnie.tuhs.org/cgi-bin/utree.pl?file=V3/man/man0/xx

That file remained unchanged until Version 7, and from there onward
to 4.1BSD.  The file was then renamed to the more intuitive
name man/man.template for 4.3BSD-Tahoe.  Sytem III renamed the
file to man/man0/skeleton and inserted EXAMPLES before FILES
and WARNINGS before BUGS.  That remained unchanged in System V.

Major progress in unification of manual pages was made by Cynthia
Livingston in 1989-91 for the 4.4BSD release.  

  NAME                                       unchanged
  SYNOPSIS                                   unchanged
  DESCRIPTION                                unchanged
  RETURN VALUES   (section 2 and 4)          new
  ENVIRONMENT     (sections 1, 6, 7 and 8)   new
  FILES                                      unchanged
  EXAMPLES                                   new
  DIAGNOSTICS     (sections 1, 6, 7 and 8)   moved up
  ERRORS          (sections 2 and 3)         new
  SEE ALSO                                   unchanged
  STANDARDS                                  new
  HISTORY                                    new
  AUTHORS                                    new
  BUGS                                       unchanged

Note that with the exception of moving DIAGNOSTICS before
SEE ALSO - which it appears you would actually agree with -
the existing order wasn't changed here.  Since at least 1991,
this order has always been documented in the groff project.

The commit history of the man-pages(7) manual page from the Linux
man pages project only goes back to 2007.  It substantially diverges
from Unix tradition right from the start, and i don't see any reason
for that.  Maybe it was invented from scratch for Linux kernel
development?  Not sure.  In any case, i can't see how anyone could
consider it authoritative in respects where it blatantly contradicts
practice that has been followed unbroken in Unix and roff from 1973
until today, like BUGS being the last section.

I don't think the program that has been the free de-facto standard
implementation of the original Unix text processing and documentation
system for almost three decades now should disrupt established
Unix practices that it has itself continuously documented merely
because someone offered a conflicting opinion in 2007, more than
thirty years after the fact, that was never adopted by the largest
existing manual page corpuses.

Yours,
  Ingo



reply via email to

[Prev in Thread] Current Thread [Next in Thread]