Date: Wed, 20 Apr 2022 10:17:04 +0200 From: =?UTF-8?Q?Fernando_Apestegu=C3=ADa?= <fernando.apesteguia@gmail.com> To: Graham Perrin <grahamperrin@gmail.com> Cc: FreeBSD questions <freebsd-questions@freebsd.org>, FreeBSD documentation project <freebsd-doc@freebsd.org> Subject: Re: Conventions for FreeBSD manual pages Message-ID: <CAGwOe2aMq2aEBh3wJSCpdjLJf_GLUQo-qcNc1Df=TO0Frm9wSQ@mail.gmail.com> In-Reply-To: <3755196b-8803-ff72-364e-6b3b067f9702@gmail.com> References: <3755196b-8803-ff72-364e-6b3b067f9702@gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Apr 20, 2022 at 8:47 AM Graham Perrin <grahamperrin@gmail.com> wrot= e: > > 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 > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > For years, I assumed that SEE ALSO sections were disorderly. > > For example: > > * expecting a=E2=80=93z (alphabetical order) > > * finding ne, sy, se, at et cetera (disorderly) under > <https://www.freebsd.org/cgi/man.cgi?query=3Dtuning&sektion=3D7&manpath= =3DFreeBSD#SEE_ALSO> > > Today I discovered that there is, at least for Linux, a convention to sor= t: > > * first, by the section number (secondary) > > * second, by the name of the page, which appears first. > > I do see some logic to this, however =E2=80=93 without first knowing the > convention =E2=80=93 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. > >
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAGwOe2aMq2aEBh3wJSCpdjLJf_GLUQo-qcNc1Df=TO0Frm9wSQ>