Re: the Linux man-pages as an educational tool

[Alejandro Colomar <alx@kernel.org>]

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

> Date: 2026-08-02 03:15:43+0200
> From: Alejandro Colomar <alx@kernel.org>
>
> > Date: 2026-08-01 18:04:05-0700
> > From: Collin Funk <collin.funk1@gmail.com>
> >
> > Alejandro Colomar <alx@kernel.org> writes:
> > 
[...]
> > 
> > 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.
> 
> 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.
> 
> 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.
> 
> The manual pages should certainly educate about reality, and standards
> are only secondary to that.
> 
> 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

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

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