Hi Branden, G. Branden Robinson wrote on Mon, Nov 12, 2018 at 11:31:42AM -0500:
> If we ignore Michael Kerrisk et al., _no_ section of a man(7) page > is standard. >From about 1970 to about 1985, i consider the list of sections used in Bell Labs manual pages standard. From about 1995 onwards, the closest thing to a standard is what is documented in the groff distribution - specifically, in the file groff_mdoc(7) which Werner Lemberg diligently maintained over the years (initially called groff_mdoc.samples(7)). Admittedly, the groff_man(7) manual does not contain a copy of the "MANUAL PAGE TEMPLATE" - but why should it? There is no need for duplicate information in the groff distribution. While the work of Michael Kerrisk is to be highly commended - without the Linux man pages project, the state of manual pages in the GNU/Linux world would be even worse - only part of what man-pages(7) says is good advice. Other parts diverge from earlier, perfectly viable practice. If BSD pages and the Linux man pages project agree on a particular point, that's a strong hint that it should probably be followed. If they disagree, the point has to be considered for technical merit, and that is where OPTIONS falls short for the reasons discussed. [...] > I regard the Austin Group as worthy of consideration as the Bell > Labs CSRC. Why shouldn't I? Because design by Thompson, Kernighan, Richie, Ossanna, and McIlroy is invariably better than design by committee? In particular when it comes to clarity and conciseness, which are key to documentation? Besides, that statement is somewhat unfair with respect to the Austin Group. They are not even trying to write documentation, but a standard, and the quality criteria for a standard do not coincide with the quality criteria for documentation, not even technical reference documentation. A standard ought to value formal exactness above all else even though that can never be fully attained, even at the expense of simplicity, while documentation should avoid being pedantic, as Doug rightfully emphasized. > We can keep this discussion better focused if you will decide whether > you want to argue from standards or from common practice, taste, and > judgment. >From a healthy balance of all of them. Yes, balancing them cannot be formalized but requires judgement. The more the existing (informal, scattered) standards agree, and the more common practice agrees on a given point, the more caution should be employed changing it; the more they diverge, the more judgement matters to figure out which way best serves clarity, simplicity, and conciseness. > Rolling back to the state of the groff tree before I made any > commits at all, I find that 32 of the 61 man page sources have > "OPTIONS" sections. Of what precedential value is that? It shows that groff documentation wasn't consistent in this respect, nothing more, nothing less. Yours, Ingo
