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
