Hi Alex! At 2022-06-08T17:12:19+0200, Alejandro Colomar wrote: > > +.SH SEE ALSO > > +.BR pipe (2), > > +.BR ioctl (2) > > | sort I'd like to suggest (gently), that advocating a lexicographic sort for this material is not the best approach. In principle, a man page renderer could recognize a "See also" section and perform a sort of man page references within it itself, because that is a mechanical process. (Recognizing man page cross references will be much easier with groff 1.23's [and plan9port troff's] `MR` macro.) In practice, I don't think any man(7) renderer does that because it's not worth the trouble, and doing so would lose sight of why the section is present. In the groff man pages, I try to order these cross references in a considered way, starting with the page that I consider most "important" or likely to fruitfully follow up the topic for the reader. That sort of judgment is subjective, of course, but with a well curated man page corpus, I think it's likely more useful than a mechanical sort. For example, in groff 1.23, the groff_man(7) and groff_man_style(7) pages refer first to each other; then to groff(7) (a reference for the groff language). And groff(7)'s "See also" section is more of an annotated bibliography; it was already largely that way when I started contributing to groff development. I think that's a good choice because a reader bewildered by a laconic yet lengthy (because the formatter has many features) reference page might strongly desire a more synoptic view, especially if they don't know where to go next. Steering people where they might value going next is the very point of a "See also" section, in my opinion. Their next best stop is not, in general, likely to fall in English lexicographic order. Regards, Branden
Attachment:
signature.asc
Description: PGP signature
