Re: the Linux man-pages as an educational tool

[Bruno Haible <bruno@clisp.org>]

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

The standard-compliant #include statement should be documented in the SYNOPSIS,
not at the bottom of the man page.

> 2) recommending to ignore it because it's bad.  When the standards are
> bad, this is appropriate course.

Which functions are "bad"? It's not up to you (single person) to decide this.
Rather, poll among the libc implementors, and if a majority says a function
is "bad", then mark it as bad.

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

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

Bruno