From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.5 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,T_TVD_MIME_EPI autolearn=no autolearn_force=no version=3.4.4 Received: from mandoc.bsd.lv (bsd.lv [66.111.2.12]) by inbox.vuxu.org (Postfix) with ESMTP id 08D712F035 for ; Fri, 13 Sep 2024 23:04:02 +0200 (CEST) Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 1bc6c114 for ; Fri, 13 Sep 2024 21:04:02 +0000 (UTC) Received: from nyc.source.kernel.org (nyc.source.kernel.org [147.75.193.91]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 92c8518d for ; Fri, 13 Sep 2024 21:04:02 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by nyc.source.kernel.org (Postfix) with ESMTP id B186EA45916 for ; Fri, 13 Sep 2024 21:03:53 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 2CE84C4CEC0 for ; Fri, 13 Sep 2024 21:04:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1726261440; bh=TNuGDszXDmpH9Vt9ctwvG9sYHJ1aUpOL62M3pWjfAkE=; h=Date:From:To:Subject:References:In-Reply-To:From; b=sSo+aaPwDmg72Pv74Lg2cWg1fPW7W1YHlBSohz2f9yjZzo0G2ki80p2wPMtfpoQRv 7XOy217I5aQyDYMyGGEdzdu8aYOuvFQDUJZUEC6xXYiFSrnqSiC61erCH/9A03iwMs aX4/aR82gX0jZH9Ihwumr8l8DRu60Ix/hTL+omwtFV6trlD90KRr9xbcj/cJgX5DRJ mjfAz4b5tovBvC2Je3gl20+TKhhMInlxWc1beDw3Z1zbXXTjw227hDmqiSVt2JkdYV bYJXFjxnG20WOqJ+GGp6WC6l6cwqSytzCmJKUsgM2KOuL4sMQSpd+CSVEZL35mc4rH O3kVeeOhZmmJg== Date: Fri, 13 Sep 2024 23:03:58 +0200 From: Alejandro Colomar To: tech@mandoc.bsd.lv Subject: Re: Apropos NAME limitations (was: [Bug] Apropos - Xr Child of Nd Rendering) Message-ID: References: X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="6f5bgxfuig6kcee4" Content-Disposition: inline In-Reply-To: --6f5bgxfuig6kcee4 Content-Type: text/plain; protected-headers=v1; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable From: Alejandro Colomar To: tech@mandoc.bsd.lv Subject: Re: Apropos NAME limitations (was: [Bug] Apropos - Xr Child of Nd Rendering) References: MIME-Version: 1.0 In-Reply-To: On Fri, Sep 13, 2024 at 10:23:48PM GMT, Ingo Schwarze wrote: > Hello Alex, Hello Ingo, > Alejandro Colomar wrote on Fri, Sep 13, 2024 at 08:48:02PM +0200: > > On Fri, Sep 13, 2024 at 05:49:49PM GMT, Ingo Schwarze wrote: >=20 > >> .Sh NAME > >> .Nm name0 , > >> .Nm name1 , > >> .Nm name2 > >> .Nd a one line description >=20 > > Do you have similar limitations for the NAME section in man(7)? >=20 > Similar limitations? >=20 > The mdoc(7) and man(7) languages are rather dissimilar in this respect > in the first place because a man(7) NAME section typically does not > contain any macros at all, and also because the man(7) language does > not generally support nesting of macros, not even outside the NMAE > section. The exceptions where man(7) does support a very limited > amount of nesting are rare. >=20 > Consider this example to understand the typical case: >=20 > .TH getent 1 (date) "Linux man-pages (unreleased)" > .SH NAME > getent \- get entries from Name Service Switch libraries > .SH SYNOPSIS >=20 > > I'm wondering if some of the pages in the Linux man-pages would cause > > problems. >=20 > A very brief look into the linux-man-pages git repo gives me the > impression that what's in there is generally just fine. That includes > pages like ioctl_eventpoll(2) where the NAME section is spread out > across multiple short input lines. It's good to know that spreading into several lines is ok. That was one of the things I was worried about. > The command "makewhatis -p" (picky mode) form the mandoc toolbox > does find a few mismatches that look suspicious (not sure all of them > are really wrong), but nothing very alarming: >=20 > man2/getcwd.2: Section "3" manual in 2 directory Nah, that's fine. $ head man2/getcwd.2=20 =2Eso man3/getcwd.3 =2E\" Because getcwd(3) is layered on a system call of the same name > man2/mq_notify.2: Section "3" manual in 2 directory > man2/mq_open.2: Section "3" manual in 2 directory > man2/mq_unlink.2: Section "3" manual in 2 directory > man2const/PR_GET_SECCOMP.2const: Section "2" manual in 2const directory > man2const/PR_MPX_ENABLE_MANAGEMENT.2const: Section "2" manual in 2const d= irectory > man2const/PR_MPX_DISABLE_MANAGEMENT.2const: Section "2" manual in 2const = directory > man2const/PR_TASK_PERF_EVENTS_DISABLE.2const: Section "2" manual in 2cons= t directory > man2/riscv_flush_icache.2: Section "3" manual in 2 directory > man2/mq_timedreceive.2: Section "3" manual in 2 directory > man2/mq_timedsend.2: Section "3" manual in 2 directory > man3/sigstack.3: Section "2" manual in 3 directory > man3/vlimit.3: Section "2" manual in 3 directory > man3/vtimes.3: Section "2" manual in 3 directory > man3const/PA_WSTRING.3const: Section "3head" manual in 3const directory > man3const/PA_WCHAR.3const: Section "3head" manual in 3const directory > man3const/PA_STRING.3const: Section "3head" manual in 3const directory > man3const/PA_POINTER.3const: Section "3head" manual in 3const directory > man3const/PA_LAST.3const: Section "3head" manual in 3const directory > man3const/PA_INT.3const: Section "3head" manual in 3const directory > man3const/PA_FLOAT.3const: Section "3head" manual in 3const directory > man3const/PA_FLAG_SHORT.3const: Section "3head" manual in 3const directory > man3const/PA_FLAG_PTR.3const: Section "3head" manual in 3const directory > man3const/PA_FLAG_LONG_LONG.3const: Section "3head" manual in 3const dire= ctory > man3const/PA_FLAG_LONG_DOUBLE.3const: Section "3head" manual in 3const di= rectory > man3const/PA_FLAG_LONG.3const: Section "3head" manual in 3const directory > man3const/PA_DOUBLE.3const: Section "3head" manual in 3const directory > man3const/PA_CHAR.3const: Section "3head" manual in 3const directory > man3/register_printf_type.3: Section "3head" manual in 3 directory > man3/register_printf_specifier.3: Section "3head" manual in 3 directory > man3/register_printf_modifier.3: Section "3head" manual in 3 directory > man4/console_ioctl.4: Section "2" manual in 4 directory > man4/tty_ioctl.4: Section "2" manual in 4 directory > man3/S_ISSOCK.3: Section "7" manual in 3 directory > man3/S_ISREG.3: Section "7" manual in 3 directory > man3/S_ISLNK.3: Section "7" manual in 3 directory > man3/S_ISFIFO.3: Section "7" manual in 3 directory > man3/S_ISDIR.3: Section "7" manual in 3 directory > man3/S_ISCHR.3: Section "7" manual in 3 directory > man3/S_ISBLK.3: Section "7" manual in 3 directory > man7/man.7: No one-line description, using filename "man" > man3/queue.3: Section "7" manual in 3 directory > man3type/sigset_t.3type: Section "7" manual in 3type directory > man3type/siginfo_t.3type: Section "7" manual in 3type directory >=20 > These seem mostly caused by use of .so, which is fragile anyway, > so maybe this isn't such a big deal. >=20 > A very quick and dirty perl(1) script i just wrote to find macros > in the NAME sections in linux-man-pages came up with exactly > one instance, $ find -type f \ | xargs sed -n '/^\.SH NAME/,/^\.SH/p' \ | grep '^\.[A-RT-Z]' -C2; .SH NAME hosts.equiv \- list of hosts and users that are granted "trusted" .B r command access to your system .SH DESCRIPTION Yup, this is the kind of corner case I had in mind. > in hosts.equiv(5) - btw., is hosts.equiv(5) really > still supported in Linux? I don't know. I removed support for rlogind(8) in shadow utils recently: commit ca046af5d976e9eb835772997ffd594b9ee979aa Author: Alejandro Colomar Date: Sat May 18 01:57:40 2024 +0200 Remove support for rlogind in login(1), that is, remove the '-r' flag =20 The "quick hack" finally disappeared. Probably nobody noticed. ;) (See the changes in for the context of this pun.) =20 Probably everybody uses SSH these days for remote login. Let's remove this insecure method. =20 Closes: Reviewed-by: dkwo Reviewed-by: Iker Pedrosa Cc: "Serge E. Hallyn" Cc: Michael Vetter Cc: Sam James Cc: Benedikt Brinkmann Signed-off-by: Alejandro Colomar But that's the closest I've been to that. I don't know if it's in use by anyone. > It's so horribly insecure that the whole > mechanism was removed from OpenBSD many years ago. >=20 > .SH NAME > hosts.equiv \- list of hosts and users that are granted "trusted" > .B r > command access to your system >=20 > I wouldn't call that "great wording", but makewhatis(8) doesn't > choke on it: >=20 > $ makewhatis -DDt man/man5/hosts.equiv.5 > man/man5/hosts.equiv.5: Adding name hosts.equiv, bits=3D0x6 > man/man5/hosts.equiv.5: Adding name hosts.equiv, bits=3D0x8 > man/man5/hosts.equiv.5: Adding name hosts.equiv, bits=3D0x10 > hosts.equiv(5) - list of hosts and users that are granted "trusted" r c= ommand access to your system >=20 > $ man -k -M man hosts > hosts(5) - static table lookup for hostnames > hosts.equiv(5) - list of hosts and users that are granted "trusted" r c= ommand access to your system >=20 > Of course, the letter "r" will not be bold in apropos(1) output, but > that's not the worst downside of that particular one-line description. >=20 > So, i think your are almost completely fine in this respect, Alex. Yup, that's good. :) > Is the first sentence of >=20 > https://www.kernel.org/doc/man-pages/maintaining.html >=20 > outdated? It says: Very much. >=20 > The current man-pages maintainer is (since 2004) Michael Kerrisk > (mtk.manpages@gmail.com; blog); starting in 2020, Alejandro Colomar > (alx.manpages@gmail.com) has joined as comaintainer.=20 It was outdated 3 years ago. I moved most of the website to the git repository: <./CONTRIBUTING>, <./CONTRIBUTING.d/*>, <./README>, <./RELEASE>, <./INSTALL>, <./LICENSES/*>. But I didn't find time to move that one page, and it remains there. The README says: History Tarballs Tarballs of man-pages-1.* releases are available at: Maintainers Alejandro Colomar 2020 - present (5.09 - HEAD) Michael Kerrisk 2004 - 2021 (2.00 - 5.13) Andries Brouwer 1995 - 2004 (1.6 - 1.70) Rik Faith 1993 - 1995 (1.0 - 1.5) The rationale was that for 1 year I was the only maintainer of the project and still didn't have access to kernel.org, so the project lived in a small server at my home. I couldn't update the website for a year, and the only source of truth was my git repository. I've decommissioned most of the website when I've had access to it, since it didn't make sense to update it when everything was already in git. I just added some links to the files in the repo. > If that is outdated and there is currently a shortage of maintainers, > that's a pity. :-( There's shortage of maintainers, but because there's shortage of food in my table. If companies --cough, Red Hat, cough-- scratch their pockets, I'd be more than happy to come back (and if they scratch enough, maybe I get Michael to come back too). >=20 > All the best for you, Thanks! > Ingo Have a lovely night! Alex --=20 --6f5bgxfuig6kcee4 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEE6jqH8KTroDDkXfJAnowa+77/2zIFAmbkqLYACgkQnowa+77/ 2zKBfA/+OfIIqfw3AXy5CgkzqMpFccKcbcPBBN+oawFclQaSi5f5eoQECt8tREQK 69cU+Pdrqih95E8SrZmJhb72MbCRZSfg/gfYvf9EXMsIkixxwWKU6Fm1NY014d/V 2ARpICCw1Wzf7DMB/PqaIHsJ8iYL1vctWCj/DZwhfbvl5OWOJ22MkUAttIkxZrmq 9/fZHtMR2VHj6JBGreNLfSYAvUfete5UayzQgSAXpMNLohbmXCZQw/+2NgpDrrBe PR1AS4NQ9qEO5ePlkusm88vLjs5K5+5IOXtDwZIfHNb/sTRUHbRZ591domc1GevI rSH6t6r0IBJHrnsBqacsNifQHPfI3i2D6BHY8G5jjrz9SVXOHlqmaudxSVaxOTmM ayUEThJL6PRvfSA4S6bOuS5bMrQ7iPRfNzkBj2OAmDmKB/ccCYSYIfPN5sO1QKNC e4++yaLUsU6MMDDe8lvqhgItHBH2KAPNw9MKxCiKKoguMakR7jTsHa97nHlEI48m q69yqI5hjQZ2ti/O419n6DfO8ktlzskYBP1nPgGw0G4rfA+U90zBeRgaL3JDmLFX q7qxiMHMHKvdz7U77VO5PhRemhJI7Ovq/12n7YLJ6ggLNq2oXdc6ImboNhNhO/wx if10vnWl+KH/pyRc6Wyi6r/oGM8KbkS5e6vzqCAT0vrXCsQ4hCU= =NWVS -----END PGP SIGNATURE----- --6f5bgxfuig6kcee4-- -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv