Re: the Linux man-pages as an educational tool

["Arsen Arsenović" <arsen@aarsen.me>]

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

Alejandro Colomar <alx@kernel.org> writes:

> I've thought a bit more about it, and had an idea that might be
> a reasonable compromise.
>
> Here's a sample:
>
> 	 SYNOPSIS
> 	-     #include <memory.h>  // See STANDARDS
> 	+     #include <string.h>  // or <memory.h>; see memory.h(3head)
> 	 
> 	      void *memccpy(size_t n;
> 			    void dest[restrict n], const void src[restrict n],
> 	@@ -34,8 +34,6 @@ ATTRIBUTES
> 	 STANDARDS
> 	      POSIX.1‐2008.
> 	 
> 	-     ISO C and POSIX declare this function in <string.h>; see memory.h(3head).
> 	-
>
> Here's the commit message, which explains why I believe this is
> a reasonable compromise:
>
>     man/man3/: Put first <string.h> in SYNOPSIS, then comment about <memory.h>
>     
>     This is a compromise between the fact that <string.h> is the standard
>     header and (only slightly) most portable header file for these
>     functions, while hinting at the fact that it might be more appropriate
>     to use <memory.h> where possible.
>     
>     Remove the STANDARDS and NOTES about this, since now the SYNOPSIS
>     contains all the necessary information.  The extra info is in
>     memory.h(3head), which is linked to in the SYNOPSIS.
>
> What do you think?

Why, though?

I think that, in the thread, it was already demonstrated (by Bionic
having an empty memory.h for a time) that nobody includes <memory.h> on
its own and expects to see these functions.  (not that Bionic is that
widely-used; a better test would be checking something like Debian
codesearch)

As I've noted before, what header provides what declaration is also
largely inconsequential.

So, the only effect of this can be to create new cases where <memory.h>
is included, for no gain.

It doesn't really matter that memory.h is only slightly less portable,
IMO.  It is unused, to the point where Autoconf recommends not using it,
and no longer bothers checking whether 'mem*' functions are also present
in string.h.

Is suddenly reviving a dead header to copy a few declarations of
functions well known to be part of string.h into it not just unneeded
churn?  Especially as program code would (nearly?) always need to do:

  #include <string.h>
  #ifdef HAVE_MEMORY_H
  # include <memory.h>
  #endif
-- 
Arsen Arsenović

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