Re: Conventions for FreeBSD manual pages

On Wed, 20 Apr 2022 07:46:54 +0100, Graham Perrin wrote:
>I expect alphabetical order, by name.

Hi,

first a note related to sorting in general and than related to the man
pages "SEE ALSO".

You shouldn't expect alphabetical order when using software running on
any operating system. Computers tend to lexicographical order (this
more or less is the alphabetical order), but it comes with pitfalls.
Some pitfalls are relatively easy to resolve, such as caused by the
Icelandic or German alphabet, but for logographic writing systems it's
probably not that easy.

https://en.wikipedia.org/wiki/Alphabetical_order#Similar_orderings
https://en.wikipedia.org/wiki/Lexicographic_order
https://en.wikipedia.org/wiki/Logogram

I suspect anything listed by a man page's "SEE ALSO" section is equal
in all languages, even when using a logographic writing system, however,
sorting by manual sections isn't a bad idea. To separate commands from
e.g. devices and drivers can be helpful.

https://en.wikipedia.org/wiki/Man_page#Manual_sections

Taking a look at the FreeBSD and Linux man pages for "hier", I can't
see a difference for the rational behind the "SEE ALSO" sorting.

Manual section first, lexicographical order of the names second.

[rocketmouse@archlinux ~]$ man hier | grep SEE\ ALSO -A1
SEE ALSO
       find(1), ln(1), proc(5), file-hierarchy(7), mount(8)

https://www.freebsd.org/cgi/man.cgi?hier(7) :
SEE ALSO
     apropos(1), find(1), finger(1), grep(1), ls(1), whatis(1),	whereis(1),
     which(1), fd(4), devfs(5),	fsck(8)

It apparently a common standard, shared by FreeBSD and Linux, that
alone already makes it good.

Regards,
Ralf