At 2024-04-13T13:22:01+0100, Keith Marshall wrote: > In the man-pages(7) document, as rendered at: > http://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf#man-pages.7 > > under the section heading "FORMATTING AND WORDING CONVENTIONS", and > subsection "Formatting conventions (general)", close to the bottom of > page 9, I see: > > > Any reference to another man page should be written with the name in > > bold, always followed by the section number, formatted in Roman > > (normal) font, without any separating spaces (e.g., intro(2)). The > > preferred way to write this in the source file is: > > > > .BR intro (2) > > I have noticed that, as of groff-1.23, both groff_man(7), and the > macro package which it documents, flagrantly ignore, and indeed > violate this convention. I further notice that man-pages(7) document, > from which I have quoted, above, appears to have been formatted using > that very version of groff_man(7), perhaps with the intro(2) > reference, within the quoted paragraph, having been formatted using: > > .MR intro 2 > > rather than the recommended: > > .BR intro (2) This is a deliberate change and was mooted on the groff mailing list for literally years before landing. For so long that plan9port's man(7) started doing it first, in fact. > This leads to a glaring anomaly, within the quoted paragraph; rather > than the topic name "intro" being set in bold, as the convention > demands, it is set in (non-bold) italics! > > In my personal opinion, FWIW, the use of italics in this context is > just plain ugly. Opinion aside, it does not conform to the > convention, as it is stated in man-pages(7) -- either the convention > needs to be changed, by common consent, or groff_man(7) needs to be > brought to heel. When Bell Labs promulgated man(7) in 1979, their convention was italic-on-roman, and they practiced it with high reliability, except in the "SEE ALSO" section itself, where they used roman-on-roman. Doug McIlroy (the person responsible for man(7), for those who don't know) characterized the latter as not a deliberate choice. There hasn't been a single reliable convention for the styling of man page cross references since at least 1988, with SunOS 4.0, when Sun transitioned from `IR` to `BR` to cases like the above. (I don't have records of what System V Unices were doing in this period, but Sun retained the change when converting their OS to a System V foundation for SunOS 5/Solaris 2.) This shift dovetailed with the limitations of PC video text mode, which did not have an attribute bit for underlining or italics, but did support bold and colors. When BSD adopted mdoc(7) to replace then-still-encumbered man(7)--at about the same time groff was developing a free one anyway[1]--they fragmented the convention further by adopting a practice of roman-on-roman.[2] So we had 3 choices of face for the topic part of the cross reference and all got used. Because proponents of any one convention are prone to leap into combat with the others to, uh, bring them to heel, I figured the best thing to do was let the distributor/user decide on the typeface. Besides which, marking a man page cross reference as such, semantically, makes it possible to automatically hyperlink them. That started to pay off in groff 1.23 and will do so even more in 1.24. Reading the groff_man(7) page might be helpful to you. Here is the relevant material from Git HEAD. groff 1.23.0's is similar. .MR topic [manual‐section [trailing‐text]] (since groff 1.23) Set a man page cross reference as “topic(manual‐section)”. If trailing‐text (typically punctuation) is specified, it follows the closing parenthesis without intervening space. Hyphenation is disabled while the cross reference is set. topic is set in the font specified by the MF string. If manual‐section is present, the cross reference hyperlinks to a URI of the form “man:topic(manual‐section)”. -dMF=man‐page‐topic‐font Select the font used for man page identifiers in .TH calls and topics named in .MR calls; the default is “I” (italic style of the default family). Any valid argument to groff’s “.ft” request may be used. If the MF string ends in “I”, it is assumed to be an oblique typeface, and italic corrections are applied before and after man page topics and identifiers. /etc/groff/man.local Put site‐local changes and customizations into this file. (The path in the last item is configured at build time and differs from place to place; the foregoing is Debian's practice.) Regards, Branden [1] Someone on the TUHS mailing list shared a recollection that some people in the Berkeley CSRG wanted to give up AT&T troff compatibility in favor of groff. Apparently, the kibosh was put on this by more senior figure(s). My inference is that this decision was made by those intending to incorporate BSDI; to implicitly condone copylefted software, let along to ship it, was intolerable to those who had visions of extracting fat economic rents from a captive market of Unix sites that had committed themselves to "Opposing Sun Forever".[3] [2] https://lists.gnu.org/archive/html/groff/2023-08/msg00005.html [3] https://en.wikipedia.org/wiki/Open_Software_Foundation
Attachment:
signature.asc
Description: PGP signature
