the Linux man-pages as an educational tool

[Alejandro Colomar]

Hi Branden, Sam,

> Date: 2026-08-03 10:34:56-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
> At 2026-08-03T16:40:26+0200, Alejandro Colomar wrote:
> > > From: Sam James <sam@gentoo.org>
> > > Alejandro Colomar <alx@kernel.org> writes:
> > > 
> > [...]
> > > > [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).
> > > 
> > > 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.
> > 
> > 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.
> > > 
> > > I think he meant in general?
> > 
> > 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.

No, he doesn't need to.  I was and still am willing to let him drop it
without any resentment, just as I've always done (or so I think, and try
to).  Love everyone, no matter what.

But Sam should probably have dropped it too; that's what I intended to
mean in my response to Sam.

So, please everyone drop it and calm down.  I'm willing to.

> > 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.
> > 
> > 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.
> > 
> > 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ïve 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.

I've been wanting to do that for a long time.  I just need to do more
work for that to be perfect, though.  One thing I don't like about
articles is that they're immutable, and thus aren't a good teaching
material; mistakes will happen that will make the resource problematic.

A benefit of manual pages is that they're a living document that
improves with time.  Once the pages become close to perfect, it could
make sense to write an article that could stand the pass of decades.

If I write such an article, I want it to be valid 50 years from now;
and not only valid, but the canonical resource for the topic.

> 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.)

Indeed; I regard Paul as an expert in this topic.  We might slightly
disagree, but I acknowledge he's mostly right.

> 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.

I don't think such an article should be the first step.  It should
probably be the last: once the documentation and the system provide the
tools, the article should summarize that, and be a tutorial for it.

I don't see that article happening before 2030 (possibly much later).

> 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.

I've made enough errors and have been embarrased for many times, that
I don't fear that.  :)

Also, I think it's easier to rectify mistakes in mailing list
discussions, than to rectify an article that thousands of people have
read.

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


Have a lovely day!  :-)
Alex

-- 
<https://www.alejandro-colomar.es>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://sourceware.org/pipermail/libc-alpha/attachments/20260803/2722c798/attachment-0001.sig>