[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: |
G. Branden Robinson |
Subject: |
Re: [groff] 02/03: refer.1.man: Put sections in conventional order. |
Date: |
Sun, 30 Jun 2019 05:05:26 +1000 |
User-agent: |
NeoMutt/20180716 |
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. "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.
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.)
Regards,
Branden
signature.asc
Description: PGP signature
- Re: [groff] 02/03: refer.1.man: Put sections in conventional order.,
G. Branden Robinson <=