the Linux man-pages as an educational tool

[Collin Funk]

Alejandro Colomar <alx@kernel.org> writes:

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

But myself and likely many others who have commented on this thread do
not agree that strings.h is a bad name. Or that general memory related
functions, which are used on strings a large portion of the time, need a
separate header.

In one of your original messages you mentioned the following:

> The standard mixes functions for handling strings, functions for
> handling bytes, and other hybrids, all in a single header file:
> <string.h>.
>
> This has historically caused confusion, for example leading to believe
> that strncpy(3) is appropriate to handle strings.

Then, in another you said:

> I find that an acceptable result.  #include's aren't that important.
> When reading code, the section of #include's is unimportant as long as
> it works.

If I concede that "#include's aren't that important", then strncpy still
exists and still looks like a function that should be used on
strings. So, we have still have the same problem unaddressed, right?
People will still use the function and write bugs.

> The manual pages should certainly educate about reality, and standards
> are only secondary to that.

The current reality and standards are fully in alignment here. memcpy et
al. have been defined in string.h since before I was born. Anyone who
knows of memory.h knows that they can just do s/memory/string/ and make
their code look more recent. Anyone who doesn't know about memory.h will
be confused why the man-pages tell them to use a different header than
they have used for decades. New programmers will follow those
instructions and find their code breaks on illumos, when it really
shouldn't.

Collin