Re: The goal of the Linux man-pages project

[DJ Delorie <dj@redhat.com>]

Alejandro Colomar <alx@kernel.org> writes:
> 	SYNOPSIS
> 	     #include <string.h>  // see memory.h(3head)

This belongs in either SEE ALSO or FILES.

> 	STANDARDS
> 	     BSD.
>
> 	     These functions are also provided in <string.h>, as speci‐
> 	     fied by ISO C.

Ok so far

>	     This is a historic mistake maintained  for
> 	     compatibility  reasons.   Don’t  let  that fool you; these
> 	     functions don’t necessarily operate on strings.

This just doesn't fit, it's far too opinionated and personal.  It needs
to be more neutral and standards-respecting.

  "Historically, this file contained memory-related functions, while
  string.h contained string-related functions, but currently these
  functions are all in string.h, despite these not being string
  functions, and typically memory.h just includes string.h for
  compatibility across all the historic standards."

I'm not arguing against the message here, just the tone.

As for the message...

I think the only way we could be more persuasive is if we convinced the
standards committees to actually segregate string and memory functions
in the specifications, and tell you to ("shall") include string.h or
memory.h accordingly, but that would break a lot of programs if it was
actually required ("must").

As an interim step, we could get the standards to specify string.h for
string functions and memory.h for memory functions ("should"), knowing
that either include gives you both, and at a later date (after all the
software is migrated) change to "shall" and start encouraging providers
to actually segregate them.  Or offer a #define that strictly separates
them to aid in migration, such as we do with other api-breaking
standards changes.