Re: the Linux man-pages as an educational tool (was: [PATCH v2] man/man3/mem*(): SYNOPSIS: Document non-standard mem*() functions as provided by <memory.h>)

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 4072 bytes --]

Hi Branden,

> Date: 2026-08-01 19:08:33-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
> At 2026-08-02T01:36:28+0200, Alejandro Colomar wrote:
> > > Date: 2026-08-01 18:29:13-0500
> > > From: Paul Eggert <eggert@cs.ucla.edu>
> > >
> > > On 8/1/26 17:10, Alejandro Colomar wrote:
> > > > #include's aren't that important.
> > > 
> > > But this whole thread is about #includes, no?
> > > 
> > > I would focus energy on areas of the manual where effort provides
> > > the most bang for the buck. As your remark suggests, this particular
> > > area is low priority.
> > 
> > I wouldn't call it low priority or low bang for the buck.  What I mean
> > is that it's not a breaking change.
> > 
> > I believe education is important, and provides bang for the buck.
> > It's not all about features.  The features are already there, but
> > misused.
> 
> I'd like to underscore this point.  As I noted in my response to Doug,
> the flagship book on C, as we all know, is stuck in 1988.  The throne is
> vacant, with many pretenders, some with excellent cases for service as
> regent.

In fact, the throne might currently fall in the Linux man-pages project.
While not being a blood heir of the Unix standards, it has become a
de-facto standard.

After all, both POSIX and C89 in one way or the other derive from the
Unix and System V manual pages (you can see it in their structure and
formatting).  Unix and System V were the largest systems of their age,
and GNU+Linux is currently in that position.  It's natural that its
manual pages are the current de-facto standard (no, not the texinfo
docs).

> But no head wears the crown.
> 
> And at the same time many C programmers are shy of consulting the formal
> standard.  We can lament their lack of wisdom in doing so and in failing
> to spin themselves up in standardese sufficiently to grapple with it.
> 
> But we can also throw 'em a bone.  To where shall they turn?
> 
> Sure, if they're in Emacs, they might go to glibc's Info manual.
> 
> But some people dislike Info, and some people use a different libc.

Michael was wise to document different libc's, including the BSDs, in
the manual pages, which is why they've become a standard.  If he had
limited to just glibc and Linux, it might not have been the case.

> So what remains for the motley crew left behind?
> 
> The man pages.

Indeed.

> I think people come to the Linux man-pages in part to learn C.  When I
> was starting out, long ago, I wondered why there wasn't a man page for
> the language itself.  Years later, I learned that there once sort of had
> been, in the 1970s.  It was Ritchie's "C Reference Manual".[1]

Hmmm, indeed, I believe that is the place to have it.  It doesn't make
much sense to document only part of the language in the pages but not
all of it.  FWIW, I've been documenting attributes and operators in the
manual pages recently.  We're closing the gap.

> But it wasn't on any Unix machine I had access to.
>
> Why not?
> 
> Because Prentice-Hall didn't want it there.  And still don't, I guess.
> 
> https://www.tuhs.org/cgi-bin/utree.pl?file=V7/usr/doc/cman

Hmmm.  Is there any copy of that?

> Maybe education is not a job the Linux man-pages project _should_ have,

I don't see why.  In fact, I believe it's its ultimate job.

If documentation for a car was an aseptic piece of text describing
it mechanically but not saying how to use it, it wouldn't be much good.
It doesn't need to teach you how to drive (that's for driving schools),
but it certainly must educate the driver about the limitations of the
car, such as "this vehicle can lift from the ground if you drive at
300 mph, don't reach this speed".  Or "if you have a lateral hit, the
airbag won't protect you".

Same happens here.


Cheers,
Alex

> but it is one that has been thrust upon it.
> 
> Regards,
> Branden
> 
> [1] Not a man page, but you could render it intelligibly with nroff.



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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]