Re: the Linux man-pages as an educational tool

--buhtcezjdrknhxqs
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: "G. Branden Robinson" <[email protected]>, 
	Paul Eggert <[email protected]>, [email protected], [email protected], 
	[email protected]
Subject: Re: the Linux man-pages as an educational tool
Message-ID: <am8wtqKpytXE6iBr@devuan>
References: <3556566.BddDVKsqQX@cagnes>
 <am50AM0bdufHa9W3@devuan>
 <15288158.RDIVbhacDa@cagnes>
 <am56ZBzNM5J07AUa@devuan>
 <[email protected]>
 <am6CnOddgaM10pry@devuan>
 <20260802000833.zpu27l7ibvrbouna@illithid>
 <am6PkypxYg-Fq4Iz@devuan>
 <[email protected]>
 <am6X32HkGdm2xTd7@devuan>
MIME-Version: 1.0
In-Reply-To: <am6X32HkGdm2xTd7@devuan>

> Date: 2026-08-02 03:15:43+0200
> From: Alejandro Colomar <[email protected]>
>
> > Date: 2026-08-01 18:04:05-0700
> > From: Collin Funk <[email protected]>
> >
> > Alejandro Colomar <[email protected]> writes:
> >=20
[...]
> >=20
> > I don't think anyone is arguing whether or not man-pages is an
> > educational tool. The argument is whether it should educate based on
> > current standards, or the maintainers preferences.
>=20
> I'm not innovating if I say that the standards are mostly ignored.
> Actually, I am more in the side of following the standards as much as
> possible and appropriate (but not more) on average.
>=20
> This is just a case where educating on the current standards is done by
> 1) documenting at the bottom of the manual what the standard says, and
> 2) recommending to ignore it because it's bad.  When the standards are
> bad, this is appropriate course.
>=20
> The manual pages should certainly educate about reality, and standards
> are only secondary to that.
>=20
> This reminds me of realloc(3).  That's a perfect example of educating
> based on current (and withdrawn) standards.  And the education might
> very well consist of saying "don't listen to the standards in this case;
> they're bad for you".

And let me expand on this.  realloc(p,0) is not just example and
precedent of how documentation *must* go against the standards when
appropriate.  It's also an example of how the manual pages must and will
go against the partial specification of glibc's official manual.

We would do programmers a disservice if the manual pages limited to
mirror what glibc's manual says.

Where the glibc documentation doesn't document its own perils, we must
deviate from that, and document them clearly.


Cheers,
Alex

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

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

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

iQIzBAABCgAdFiEES7Jt9u9GbmlWADAi64mZXMKQwqkFAmpvMj8ACgkQ64mZXMKQ
wqmXeQ//TKDvwJieYgWstabZ+yGmM93UNKTzdpkK4hGirz+EASwcH+1Y1F37N/QG
Viwu2XnmWnpKICqen+11Yu4Id1tyWA8i6JkHXb0PCIIL8ofwRN2FamgODqBZrFGt
IisH0QVFRz1mCF3MylEFSFRV/N9/XWiO22JBXGi9J5CqswVkrVo0KJWUy1lBoVh/
hd4S1rI3HBiFMxd49z3t66WVAgDuaTdOeo8K6VJgTz0vwAKQ6ZRzhyX1ByCygS63
vVZoUuXSQLFXbbsuXQ59K8qfK3OLVsSSTOxpVCzWnMTrgJHN84M6//JxGR4tVOG6
+ab5GsLa46TwPxPr8/SEXEajkpE1sIhSw+UvMyo/Kzj2de5vvgsgI7+DGj6hwHFj
Dy6p4isuOrf+vvERazsgxwhC/YvfcetO1L2GgM8jX2Nmq+PGR5VpmkGb1k7eDOIy
rEmB8Eb6cyOUNElMvfxuOXB6vJv43OJ8TTqGPHMidf977MEV0N3x3M366v4YZOMR
T1BybW7l1j+rkJW2OPaCLDfN03xqGOUvrEjcrwDe2SPuQxrR/f7xlGMWiypAo2XX
FGNZeJT1V3cVyaOhKbXvF+7F2PIAeWHzRSAWz9rbohEIMGSf1EA0Dqw1CzYkQGl3
35ZPwA+v21O/G0DBMxdoiCiOU/6zrsL/K60WUuLUwCt3zytkoBs=
=cCbA
-----END PGP SIGNATURE-----

--buhtcezjdrknhxqs--