sorting "See also" cross-references? (was: [PATCH] ioctl_pipe.2: Add.)

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1832 bytes --]

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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]