Re: the Linux man-pages as an educational tool

--flkxvvxrlbkhw4xh
Content-Type: text/plain; protected-headers=v1; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
Subject: Re: the Linux man-pages as an educational tool
MIME-Version: 1.0

At 2026-08-03T16:40:26+0200, Alejandro Colomar wrote:
> > From: Sam James <[email protected]>
> > Alejandro Colomar <[email protected]> writes:
> >=20
> [...]
> > > [Collin Funk] doesn't need to have read every word of the glibc
> > > manual, but this precise text he could have read it, because it
> > > was mentioned by Paul in this thread (different subthread) prior
> > > (19:28 UTC) to his message, and reviewed by me also prior (20:31
> > > UTC) to his message (23:27 UTC).
> >=20
> > I often reply as I go rather than reading all other emails around
> > that time. I don't think you should assume he read those emails and
> > deliberately neglected their contents.
>=20
> Me too.  But eventually I respond to those other emails, and rectify
> when that new information conflicts with something I said with
> incomplete information.  So far, Collin didn't rectify.

But does he _need_ to?  It's easy to have imperfect knowledge.  We all
swim in ignorance.

I advise against personalizing this conflict.  And even if you feel
insulted, there are hazards to injecting honor-based cultural patterns
into technical forums.

I'm deeply familiar with a region of my country that practices such
patterns, and I was still very young when I got heartily sick of it.

https://en.wikipedia.org/wiki/Culture_of_honor_(Southern_United_States)

> > > Also relevant is the fact that he accused me of "slowly"
> > > documenting "personal preferences".  His wording implies that it
> > > wasn't there before.  Maybe I misunderstood, though.  I'd be happy
> > > to rectify if I was wrong.
> >=20
> > I think he meant in general?
>=20
> I don't interpret that.  I guess he can defend himself and clarify.

Again, does Collin _need_ to?  Would it meaningfully advance your
objectives if he did?

Some things can be permitted to drop.  You can always pick them up again
later if someone tries to press your benign neglect to their advantage.

> I only see my style slightly different than Michael's, but not
> necessarily in the sense of involving a more opinionated approach.
> See the other messages where I've shown how Michael had done the exact
> same thing with strlcpy(3) a long time ago.
>=20
> On reconsideration, and after researching what Michael really did, I
> think I was wrong saying we have a different style at all.  I believe
> we've had the same style.  We just had different topics of expertise.
>=20
> Michael has had his own share of opinionated comments in manual pages.

You might be completely right about all of this.  Maybe people have
beatified Michael in the rosy glow of hindsight, and overlooked his less
temperate statements.  (Some day, they might do the same of you.  ;-) )

But I don't see how concern with this matter materially advances the
objectives of getting good advice to frustrated or curious programmers
into the Linux man-pages, and of making the C Standard Library more
comprehensible and less painful to use.

A suggestion I've been meaning to make but have struggled to find a good
place to inject is the following:

You've spoken multiple times of about 5 years of your work hammering as
hard as you could on the various memory buffer/string interfaces of
libc, and how much of the benefit of that work went into the
shadow-utils project.  And I believe you because I've caught fugitive
glimpses of that work over most of that period.

So I recommend, hypocritically, that you engage in a practice that I
struggle with:

Promote your work.

What I have in mind is an article, say of the length that a guest
columnist might write for LWN, working your way though a selection of
the most frustrating or fascinating issues you encountered.  To a first
approximation, every C programmer believes they know how to use these
functions, because hey, how hard could they be?  Illustrate the hazards.
Show how the na=EFve assumptions fail.  Point to how you solved them in
shadow-utils (or elsewhere).  Then, as your grand conclusion, show how
your proposed reforms to the C standard logically follow.

Circulate that piece, either to a few reviewers whose judgment you
trust, or on the linux-man list, possibly marked "[off-topic]" or
"[meta]".  Engage your reviewers and let them improve it, as Paul Eggert
did by pointing out the multiple evaluations of one of your macro
arguments.  (Even if it didn't matter in that case, it's not a great
pattern.)

Does this require more work of you before going to WG14?  Yes.  But at
the end of it you'll have an artifact you can point to.  It can be your
personal FAQ for this subject.  You can mine it for future N papers.

You're doing a lot of work arguing with people on these mailing lists,
too.  So think of it in terms of opportunity cost.  With a "Hard Lessons
Learned from string.h" paper, you have an artifact you can point to--
one that is almost certainly going to get read by more people than will
follow hyperlinks to mailing list disputes.

And like an N document, an article can be revised over time, whereas
with mailing list posts, your errors are burned into the ground to
embarrass a person for all eternity.

=2E..except for the fact that correct and incorrect claims alike are much
more often utterly forgotten.

Regards,
Branden

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

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

iQIzBAABCAAdFiEEh3PWHWjjDgcrENwa0Z6cfXEmbc4FAmpwtRkACgkQ0Z6cfXEm
bc693hAAsDHqCvKEcnBfydsJXua8rAcLUljVMNipthxDHnmRCHI3tc8MywpO1b87
4VfAbh/Gv1qJzv3pUShagA/Swaa1w0Rj67Sc8wB0li7Lo38G9tBQGBs9Ombn4AlE
VtHrDTFW+GE1riNEgV1NibkIZyFeyaDbNGodnttT/7W60Ft5KKstF5yU5ACv7Pxe
rJWCL8qeUKxDBNf/Eo91HKjDkyUAumaPHhvS4Z6U+LrMGtX78a7mZCB7Yu4tQXhT
+CHkvY4wlQexUT6FsQnKkoCDRIzRzXW5Hrsgx6xOMb+91TAEkHsYV8qA+2zNSkKe
wfyNerofn5uOmDMLYVUInaqCVo6iOZKc6VJfWSrOditJwOiu/QlcWv8cHLypxmGy
nk5FLomU0rnKsDtClmtSdCIKTpaS6NxQu74VLFLM8anLhNnKSZ+Hk9z2qdx08iJQ
SiIWiPZjtUF6IDW5YWsxgZKakBGfYh4hvp2XOzOsgEXlChl1hyDSPYOrl3LP51qU
YNSe+chCd1UMN9mO/jM4lunVWhcDZh7Zthhu3yXwApouHKX5AHqcJgfoUQyUxLuc
idue36/wXyT/sugHqnW7Q040uSvacp9+amZnnEeXTqaeKY9KfLhhhHZLgWWMAw3B
9M4+oTu/QPcSR5HIy2NPOwjs0F5UVc/PUVILIFGHuC44Z91+lE8=
=F1mx
-----END PGP SIGNATURE-----

--flkxvvxrlbkhw4xh--