From nobody Wed Apr 20 08:17:04 2022 X-Original-To: freebsd-questions@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id DDEB711D44C2; Wed, 20 Apr 2022 08:19:10 +0000 (UTC) (envelope-from fernando.apesteguia@gmail.com) Received: from mail-lf1-x129.google.com (mail-lf1-x129.google.com [IPv6:2a00:1450:4864:20::129]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1D4" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4Kjtqf1vHMz3Nxx; Wed, 20 Apr 2022 08:19:10 +0000 (UTC) (envelope-from fernando.apesteguia@gmail.com) Received: by mail-lf1-x129.google.com with SMTP id h27so1227743lfj.13; Wed, 20 Apr 2022 01:19:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc:content-transfer-encoding; bh=mCORvbIvUuJ9FuHlGVE1tTrE1D3/QGgLlc7J5r7gU+I=; b=Ml/3EZZnthNZaUlyaT4L5mAcvVm0MCYVRm6M3fRZanklLIcDHBtTIuMSgU/we4Ro9P 2yzRbATSWUMhRm+0uF7im0viNzpg0HmtaN0YZN/Q79iI6s1/5ndb93GnCiNo6rM2JxyI ZB3bUYgDPas46O8feM7UnDWv0BFKHKWpCwFbm6/l9ppWSeME0xKOyKE3Kq9S/iFrGHU2 MCmPNxIYc1qyJwEaCztFBGnz33/sJsuOcHfWGL0mNC2+iOfixhkkmoBD1/Aeui2lfiP2 Gef9S7Ud/OZo0g6w/lcGqRaepi4rXlbz0Wbd/dNR5RwAMdBVHV/KhaQUH6w1Tp2GgGRc ra5w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc:content-transfer-encoding; bh=mCORvbIvUuJ9FuHlGVE1tTrE1D3/QGgLlc7J5r7gU+I=; b=NMHB33T6ghA2QUAib2NNmRoZ16XjU5ucnITt2Tc9ZLQJtgLrrP0UPyIWDgoOIUCll/ nTWyP+yK/lp4mxCQHUIGgAqfOKREGwFSWhfu7eIV4bss7qxXqVNp4p+VaLUbhtSC9t11 ZvJTNec8jlybByCs6SKw+VgqwJ/R1pG8D8KQgjMAXOEm3qt7AQkfdbxm4XayMeb6H0hB ttmjsFlLw+axT+zu1QFPd0PSM6u9ALzkgchUjq1v+CkIVxmvM50BVqdwYeGBpvB5A9mi D0qEcZtjrfU36iHtHpLeEoyKy5reNKfj6so7q/pW4BbmoPn4jFmbKzkLjGEilpJpUpQG 3Z0w== X-Gm-Message-State: AOAM5309mFn4HVHyQn/QhLUUJIPUKeXhEt5A5djCWDOzE/dBwocB4aR1 z0o90+qFxxtcxd6/neR91D0gvwoaLD3McGHayjI= X-Google-Smtp-Source: ABdhPJy8wsg83dibWjrF7qXC0RzdW9VvQFZ2HEbUIiuebne/5/dIgRyLvksC30RS12XcHeztm7A8J9/TURhWKo8TiKM= X-Received: by 2002:a05:6512:3f26:b0:46b:92c0:54da with SMTP id y38-20020a0565123f2600b0046b92c054damr14755750lfa.369.1650442748521; Wed, 20 Apr 2022 01:19:08 -0700 (PDT) List-Id: User questions List-Archive: https://lists.freebsd.org/archives/freebsd-questions List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-questions@freebsd.org X-BeenThere: freebsd-questions@freebsd.org MIME-Version: 1.0 References: <3755196b-8803-ff72-364e-6b3b067f9702@gmail.com> In-Reply-To: <3755196b-8803-ff72-364e-6b3b067f9702@gmail.com> From: =?UTF-8?Q?Fernando_Apestegu=C3=ADa?= Date: Wed, 20 Apr 2022 10:17:04 +0200 Message-ID: Subject: Re: Conventions for FreeBSD manual pages To: Graham Perrin Cc: FreeBSD questions , FreeBSD documentation project Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: 4Kjtqf1vHMz3Nxx X-Spamd-Bar: - Authentication-Results: mx1.freebsd.org; dkim=pass header.d=gmail.com header.s=20210112 header.b="Ml/3EZZn"; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (mx1.freebsd.org: domain of fernandoapesteguia@gmail.com designates 2a00:1450:4864:20::129 as permitted sender) smtp.mailfrom=fernandoapesteguia@gmail.com X-Spamd-Result: default: False [-1.55 / 15.00]; R_SPF_ALLOW(-0.20)[+ip6:2a00:1450:4000::/36:c]; FREEMAIL_FROM(0.00)[gmail.com]; MID_RHS_MATCH_FROMTLD(0.00)[]; TO_DN_ALL(0.00)[]; DKIM_TRACE(0.00)[gmail.com:+]; DMARC_POLICY_ALLOW(-0.50)[gmail.com,none]; FREEMAIL_TO(0.00)[gmail.com]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; FREEMAIL_ENVFROM(0.00)[gmail.com]; ASN(0.00)[asn:15169, ipnet:2a00:1450::/32, country:US]; TAGGED_FROM(0.00)[]; R_MIXED_CHARSET(0.62)[subject]; DWL_DNSWL_NONE(0.00)[gmail.com:dkim]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; R_DKIM_ALLOW(-0.20)[gmail.com:s=20210112]; FROM_HAS_DN(0.00)[]; RCPT_COUNT_THREE(0.00)[3]; NEURAL_SPAM_SHORT(0.83)[0.830]; NEURAL_HAM_LONG(-1.00)[-1.000]; MIME_GOOD(-0.10)[text/plain]; TO_MATCH_ENVRCPT_SOME(0.00)[]; RCVD_IN_DNSWL_NONE(0.00)[2a00:1450:4864:20::129:from]; MLMMJ_DEST(0.00)[freebsd-questions,freebsd-doc]; RCVD_COUNT_TWO(0.00)[2]; RCVD_TLS_ALL(0.00)[] X-ThisMailContainsUnwantedMimeParts: N On Wed, Apr 20, 2022 at 8:47 AM Graham Perrin wrot= e: > > Please: does FreeBSD have anything like the Linux manual page for > conventions? > > > > 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 > > > 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. > >