Re: the Linux man-pages as an educational tool

--5sektlshxedjgsgn
Content-Type: text/plain; protected-headers=v1; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
From: Alejandro Colomar <[email protected]>
To: Collin Funk <[email protected]>
Cc: Sam James <[email protected]>, 
	"G. Branden Robinson" <[email protected]>, Arsen =?utf-8?Q?Arsenovi=C4=87?= <[email protected]>, 
	"Maciej W. Rozycki" <[email protected]>, Paul Eggert <[email protected]>, [email protected], 
	[email protected], [email protected]
Subject: Re: the Linux man-pages as an educational tool
Message-ID: <anHVx-xWLmL7SPyM@devuan>
References: <[email protected]>
 <am6X32HkGdm2xTd7@devuan>
 <[email protected]>
 <am-2d02e1qq78Asv@devuan>
 <[email protected]>
 <20260802231058.o7gud4bd7co2nbhv@illithid>
 <[email protected]>
 <am_TTjDLlAI68zkp@devuan>
 <[email protected]>
 <[email protected]>
MIME-Version: 1.0
In-Reply-To: <[email protected]>

Hi Collin,

> Date: 2026-08-03 19:39:43-0700
> From: Collin Funk <[email protected]>
>
> Sam James <[email protected]> writes:
>=20
> > Alejandro Colomar <[email protected]> writes:
> >
> >> Hi Collin,
> >>
> >>> Date: 2026-08-02 16:27:21-0700
> >>> From: Collin Funk <[email protected]>
> >>>
> >> [...]
> >>>=20
> >>> I can't help but wonder of what happens in WG 14 rejects this
> >>> controversial, as obvious by this thread, change. Will the man-pages
> >>> changes be reverted? Or will we slowly watch them document personal
> >>> preferences instead of existing standards?
> >>
> >> This patch set is quite independent of the standard.  It documents a
> >> header file that has been provided since forever in glibc and most oth=
er
> >> POSIX-ish systems, so changes to the standard are unlikely to have any
> >> effects.  I've clarified this extensively.  If you want to discourage =
me
> >> from applying the change, you should rather bring up technical reasons.
> >>
> >> This passive-aggressive message is not something that will have the
> >> desired effects you could possibly reach with technical arguments.
> >
> > I didn't read it as passive-aggressive, but I will say that I think
> > you've gone a bit hard in the responses to Collin in this subthread, and
> > I think the fact you sent several followup emails to yourself indicates
> > perhaps things got heated in the moment.
>=20
> The last sentence was probably a bit rude, sorry about that.

No problem; thanks!

> However, I
> think a reasonable third party can understand my frustration.

I hope you can understand mine too.

[...]


> I am happy enough to fix the SYNOPSIS of my
> man pages locally like this:
>=20
>     $ git grep -lF '<memory.h>' \
>         | xargs -n 1 sed -i 's|<memory.h>.*|<string.h>|g'
>=20
> Hopefully distributions consider doing the same.

I've thought a bit more about it, and had an idea that might be
a reasonable compromise.

Here's a sample:

	 SYNOPSIS
	-     #include <memory.h>  // See STANDARDS
	+     #include <string.h>  // or <memory.h>; see memory.h(3head)
	=20
	      void *memccpy(size_t n;
			    void dest[restrict n], const void src[restrict n],
	@@ -34,8 +34,6 @@ ATTRIBUTES
	 STANDARDS
	      POSIX.1=E2=80=902008.
	=20
	-     ISO C and POSIX declare this function in <string.h>; see memory.h(3h=
ead).
	-

Here's the commit message, which explains why I believe this is
a reasonable compromise:

    man/man3/: Put first <string.h> in SYNOPSIS, then comment about <memory=
=2Eh>
   =20
    This is a compromise between the fact that <string.h> is the standard
    header and (only slightly) most portable header file for these
    functions, while hinting at the fact that it might be more appropriate
    to use <memory.h> where possible.
   =20
    Remove the STANDARDS and NOTES about this, since now the SYNOPSIS
    contains all the necessary information.  The extra info is in
    memory.h(3head), which is linked to in the SYNOPSIS.

What do you think?


Have a lovely day!
Alex

--=20
<https://www.alejandro-colomar.es>

--5sektlshxedjgsgn
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCgAdFiEES7Jt9u9GbmlWADAi64mZXMKQwqkFAmpx1zoACgkQ64mZXMKQ
wqmeeA/9FuzXkgsexYVWoAKBOqTTrrDKEE6qhsvESqRkTOZv24jynbQJllB3xA5v
/2m+pZ/INktkch4Tfo3SVFWE1wyK2NjMyQ+zh7l+E8Q+m7WvpuDmOQ6Ws9sPTPrM
XsWI2HFfOQ+lFIg/WERDzTZY4TJ0lW+ymnol66Kcd49JSAFm5D/ZMvmR96Y3Uqys
0asQH42X6A4oluG2RwgG8zP4TrPnQV5gSnzI+QPz03iffL+VHzZ4se4VHuf9UVI8
Z6XKV+qnpAsNHL3Y9ALZPZ5t77mO+m4UzCM6c2YIO3/nf186oTo8fiPr7Mw9w556
JAgIlfVC1/ntOQ6ZE81WH18y6ydp+20GyDcSSmrsjits9ViSOz8fedLN9B8mvRnU
iXVcz1yXEsE8KK7MsaSqxo1rsE0AR+vhaYoAEAw3iWIAdD9yvPJn7GtXS03ZtHQE
aSmxkrcUx9HJ/7DAoPGzMcwl0HITfdtIdQSf4isYhKsF1LaQ0f/zK0ob9yfsJIAc
ovLh7FR39lRUds9Coq1X3gVHZrB21vvtunzfMuuJqmFLl7MlmUT71X3f0cBa7vnb
LZm15tjPRx4tMANPx6LSRseg7k+ahiQWAVBE1FcOhH4SsaFkzhIFziJnrW2bvaWl
ghKAGvcfqH/iENwjcg+XUrGBt0OA3P1sGYF5EaMJILhLRb6oLdQ=
=83fK
-----END PGP SIGNATURE-----

--5sektlshxedjgsgn--