Re: the Linux man-pages as an educational tool

--=-=-=
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Alejandro Colomar <[email protected]> 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)
>=20=09=20
> 	      void *memccpy(size_t n;
> 			    void dest[restrict n], const void src[restrict n],
> 	@@ -34,8 +34,6 @@ ATTRIBUTES
> 	 STANDARDS
> 	      POSIX.1=E2=80=902008.
>=20=09=20
> 	-     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 <memo=
ry.h>
>=20=20=20=20=20
>     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.
>=20=20=20=20=20
>     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
=2D-=20
Arsen Arsenovi=C4=87

--=-=-=
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQECBAEWCgCqFiEE/uKz0RP8AKMWLWBhUsKUMB6ixJMFAmpyChcbFIAAAAAABAAO
bWFudTIsMi41KzEuMTIsMiwyXxSAAAAAAC4AKGlzc3Vlci1mcHJAbm90YXRpb25z
Lm9wZW5wZ3AuZmlmdGhob3JzZW1hbi5uZXRGRUUyQjNEMTEzRkMwMEEzMTYyRDYw
NjE1MkMyOTQzMDFFQTJDNDkzEBxhcnNlbkBhYXJzZW4ubWUACgkQUsKUMB6ixJME
gQEA01D2PwmgvvI2f9uj57h42CNEzXxFD7a/B1L49MjpPVUA/2ZTeaYM0mPU0Lc2
pH7Oj/h23B32KzDuoEOrMsDs374E
=X27n
-----END PGP SIGNATURE-----
--=-=-=--