Re: the Linux man-pages as an educational tool

--njol4fd35gtem72c
Content-Type: text/plain; protected-headers=v1; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
From: Alejandro Colomar <[email protected]>
To: Bruno Haible <[email protected]>
Cc: [email protected], [email protected], 
	Collin Funk <[email protected]>, "G. Branden Robinson" <[email protected]>, 
	Paul Eggert <[email protected]>, [email protected]
Subject: Re: the Linux man-pages as an educational tool
Message-ID: <anCO9tDqJH2PLD0w@devuan>
References: <[email protected]>
 <[email protected]>
 <am6X32HkGdm2xTd7@devuan>
 <4636165.RUnXabflUD@cagnes>
MIME-Version: 1.0
In-Reply-To: <4636165.RUnXabflUD@cagnes>

Hi Bruno,

> Date: 2026-08-03 14:35:06+0200
> From: Bruno Haible <[email protected]>
>
> Alejandro Colomar wrote:
> > 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
>=20
> The standard-compliant #include statement should be documented in the SYN=
OPSIS,
> not at the bottom of the man page.

That's an opinion, which I respect, but at the moment, and given the
thorough research I've carried out, I disagree with it it.

If you want to know what the standards say, you have available at your
disposition the STANDARDS section, and the standards themselves.

The Linux manual pages are not the ISO C manual pages.

> > 2) recommending to ignore it because it's bad.  When the standards are
> > bad, this is appropriate course.
>=20
> Which functions are "bad"?

I didn't say any functions are bad (other than gets(3)).  I did say the
standards are bad.  The standard specification of realloc(,0) is bad,
for example.  The standard #include's and organization of strn*()
functions is also bad.

Where did you get the idea that I've claimed that any functions are bad?

> It's not up to you (single person) to decide this.

I've done enough research and heard enough parties to conclude this.

> Rather, poll among the libc implementors, and if a majority says a functi=
on
> is "bad", then mark it as bad.

I've polled libc implementors for their technical reasons, I've heard
those arguments carefully, analyzed them, and concluded based on that.

I've also heard subjective opinions alongside those technical arguments,
and I've also carefully analyzed them, although they carry significantly
less weight than the technical arguments, and in some cases, they carry
negative weight, as they show that the person that emitted them is not
experienced enough about this topic.

With all that information, I've taken a decision.

I haven't marked any functions as bad (contrary to some opinions from
libc maintainers), FWIW.

> That's basically how it went with 'gets': The community realized it is a =
bad
> function, then the implementors started to withdraw it.

Here's an interesting story about gets(3), which I learnt recently:
The C Committee didn't remove it from ISO C.  It was the Austin Group
that triggered some unusual process within ISO for overriding the
C Committee, and removed it in a secret meeting.

The removal probably wouldn't have been accepted by the C Committee if
it had gone through the usual process.

> And even there, look at several implementors, not only at a single one. F=
or
> instance, NetBSD considers uselocale() to be "bad" and therefore does not
> implement it. That's a single-implementor opinion, not a majority.


Have a lovely day!
Alex

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

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

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

iQIzBAABCgAdFiEES7Jt9u9GbmlWADAi64mZXMKQwqkFAmpwkm0ACgkQ64mZXMKQ
wqkNEw/8DQu6XugmxlNmaDYTRPs2kMJa8VMaB2Ukt5SDpp9EZvll1B2AH59Olyup
HOb20WkFKIqlKNVTJ6GyR7RmvEu4LsXv/RjB4WDXSc+yPYKUej+8PWXZ+Z5PX8N6
aETS3kQ9LI/82imfX5tgessnlIC39YhmXDqAV09j7ebSukEZoaPAbNBxsU7owli9
Zgr/2iBcZBEwvBUsiEc/uUOa+bzUoXqAxlWRfkwnep9EwpjpJ1kZntAsTKcJ4pJA
c4PgK84gjhbUPJPf2MUZXKJjwRK9gf/uEuPynRHRUYuM5ACy1cIi1fMRlgifvWAq
Baa6MMN/TvzaTXtk6438PAiogF639xAY8rWLhz6o+KSxFcdNN7p5rd5umvqXovAL
szwrc9ZQ9pBroo1ErOXNTAJ4HAUKarnKRpqZMwZJAN66YqQIJbEJEgS4cX+Elkdn
ikzASsDkPkIvbXRNmD91LlG2b5wQTY442wFQjN/DvfXihSS3kkRuy+eHQSkuVIoe
5gKAtHeRGe6PQ0yVB/1Vnf0P6t3XU1j5E65cz1kJcthr+ecVbzby9B4H8qiirSEI
08i3n2sizNlRKKF+VqKYc9SRk01zRvwRoDR87SBaFL38f4Sp7a7AJCW/pySliXkq
Jcr0NKA98v+1U14iijYZeTFrnRnxkGdbdjuQPWlmKlK99DPlZXg=
=l2A0
-----END PGP SIGNATURE-----

--njol4fd35gtem72c--