[PATCH v2] man/man3/mem*(): SYNOPSIS: Document non-standard mem*() functions as provided by <memory.h>

[Bruno Haible]

Hi Alejandro,

> > Your previous proposal "alx-0097r1 - <memory.h>, the legitimate header for
> > memcpy(3) et al." evaluates like this, IMO:
> >   * Benefit: Small.
> >   * Cost of adoption: Huge
> >     (there are more than 700000 references to memcpy() alone in Debian sources
> >     [1]).
> 
> There's literally no change.  The proposal includes this:
> 
>     7.28  String handling <string.h>
> 	@@ New subsection after title
> 	+7.28.<0+1>  General
> 	+1
> 	+	The header <string.h>
> 	+	includes the headers <memory.h> and <nonstring.h>.
> 
> Which means that <string.h> is still a valid provider of memcpy(3), and
> thus absolutely no existing code breaks.

Still, for the next 10 years, C programmers would debate whether they should
#include <string.h> or #include <memory.h>. Different C programmers in the
same team will have different personal opinions. Thus, programmer team leads
will have to establish coding styles/guidelines which say which header to
include in this case.

This is one of the challenges of language design: Each time the language
offers several nearly equivalent ways of doing the same thing, different
coding styles and the need for team guidelines are the consequence.
C++ is particularly affected by this; Go hardly. Pushing C to become
like C++, in this respect, would not be a good move.

The cost of adoption for this proposal is thus still big.

> > And, of course, for man page changes, consider the authoritative source.
> > For example, memfrob() exists only in glibc [2], therefore its authoritative
> > documentation is in the glibc manual [3], and it says "It is declared in
> > string.h." The man pages MUST say the same thing.
> 
> Yes, in v3 (which I'll send soon), they'll say the same thing.  That is,
> all the functions --standard or not-- will have text clarifying that the
> functions are also provided in <string.h>.  This covers what glibc says.
> What goes in the SYNOPSIS is something I'll diverge from glibc, but
> that's fair game.

I don't agree with you that it's "fair game". The SYNOPSIS is the first
eye-catcher, often the only part that a programmer reads. It would be a
disgrace if the man page, in the SYNOPSIS, mentions a different header than
the authoritative source.

Bruno