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

[G. Branden Robinson]

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