Re: Conventions for FreeBSD manual pages

On Wed, Apr 20, 2022 at 8:47 AM Graham Perrin <grahamperrin@gmail.com> wrote:
>
> Please: does FreeBSD have anything like the Linux manual page for
> conventions?
>
> <https://man7.org/linux/man-pages/man7/man-pages.7.html>
>
> I can't find one.
>
> Background
> ==========
>
> For years, I assumed that SEE ALSO sections were disorderly.
>
> For example:
>
> * expecting a–z (alphabetical order)
>
> * finding ne, sy, se, at et cetera (disorderly) under
> <https://www.freebsd.org/cgi/man.cgi?query=tuning&sektion=7&manpath=FreeBSD#SEE_ALSO>
>
> Today I discovered that there is, at least for Linux, a convention to sort:
>
> * first, by the section number (secondary)
>
> * second, by the name of the page, which appears first.
>
> I do see some logic to this, however – without first knowing the
> convention – I never found it helpful. The apparent disorder was unhelpful.

That seems the same convention we have, at least as reported by
mandoc(1). For example, disordering the manual pages for kqueue(2)
results in:

/src/lib/libc/sys$ mandoc -Tlint ./kqueue.2
mandoc: ./kqueue.2:827:2: WARNING: unusual Xr order: aio_return after read
mandoc: ./kqueue.2:831:2: WARNING: unusual Xr order: write(2) after
pthread_setcancelstate(3)

diff --git a/lib/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2
index b4531b6cd02b..0ea3b78ffb24 100644
--- a/lib/libc/sys/kqueue.2
+++ b/lib/libc/sys/kqueue.2
@@ -822,13 +822,13 @@ have been applied.
 .Sh SEE ALSO
 .Xr aio_error 2 ,
 .Xr aio_read 2 ,
-.Xr aio_return 2 ,
 .Xr poll 2 ,
 .Xr read 2 ,
+.Xr aio_return 2 ,
 .Xr select 2 ,
 .Xr sigaction 2 ,
-.Xr write 2 ,
 .Xr pthread_setcancelstate 3 ,
+.Xr write 2 ,
 .Xr signal 3
 .Rs
 .%A Jonathan Lemon

Cheers.
>
> Whenever I look for a named thing, in a long string of names, with the
> intention of clicking (a link): I expect alphabetical order, by name.
>
>