Re: [PATCH 1/2] man/man3/{mem,strn}*(): SYNOPSIS, STANDARDS: Document these as provided by <memory.h>

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

Alejandro Colomar <[email protected]> writes:

> Hi Sam,
>
>> Date: 2026-07-31 22:54:27+0100
>> From: Sam James <[email protected]>
>>
>> Alejandro Colomar <[email protected]> writes:
>>=20
>> > Hi Joseph,
>> >
>> >> Date: 2026-07-31 21:23:35+0000
>> >> From: Joseph Myers <[email protected]>
>> >>
>> >> I think it's irresponsible to use the man-pages project to promote=20
>> >> personal idiosyncratic ideas like this in preference to what's been t=
he=20
>> >> standard location of functions since 1989.
>> >>=20
>> >> I'd rather we add a mandatory deprecation warning to memory.h in glib=
c.
>> >
>> > I hope you don't; it'd be a gratuitous breaking change.
>> >
>>=20
>> Yet this change has the same effect, just people will see it themselves
>> rather than the compiler telling them, and go around sending patches to
>> change it.
>
> IME, people don't go changing includes unless they need something it's
> not available in the already-included header files.
>
> Analysis of includes is quite complex, and there are tools for that
> --iwyu(1)--.  As long as those tools don't start complaining --and they
> won't-- [1], I find it quite unlikely that people will start changing
> includes in existing code.
>

OK, that's useful behaviour. I wasn't aware it accepted a list of
headers that would provide it.

> This is rather something that will affect new code (new source files).
>
> [1]	iwyu(1) works in a way that it allows a number of headers to
> 	provide a symbol.  If no header provides the symbol, then it
> 	will recommend the best header for it; but if a header that
> 	provides the symbol is already there, it won't complain.
>
>> The man pages should reflect what the standard currently says, not what
>> you'd like it to say.
>
> Not exactly; the standard is a good guideline, but sometimes it's off.
> We have vendor extensions, which are well documented, and when the
> standard is bogus, the extensions take over the page.

I think we have different views on the purpose of man-pages and users'
expectations of them.

>
> FWIW, the information from the standard is still there.
>
> 	$ MANWIDTH=3D64 mansectf STANDARDS man3/memcpy.3 | cat
> 	memcpy(3)           Library Functions Manual          memcpy(3)
>
> 	STANDARDS
> 	     C11, POSIX.1=E2=80=902008.
>
> 	     ISO C and POSIX declare this function in <string.h>.
>
> 	Linux man=E2=80=90pages (unreleased) (date)                   memcpy(3)
>
> I've just removed it from the front of the page (SYNOPSIS), but it's
> still there, because of course, we must document the standard alongside
> the extension.
>
>> We had the same problem with e.g. stripping "C89"
>> everywhere.
>
> Sorry for that one; it was a useful change, though.  Now we have better
> manual pages than we had back then, regarding standards.  I hope you
> realize about that.  It triggered discussion, and a careful review of
> the text, which resulted in a good change after all.

Yes, we got there in the end, but it was very disruptive, and caused a
lot of pain. I am not sure the right lessons have been learned from it.

>
>> People want it to reflect what the standard says.
>
> And it still does.
>
>
> Have a lovely night!
> Alex

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

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

iQEBBAEWCgCpFiEEJaa7iN2bdkxrVUHCc4QJ9SDfkZAFAmpuBfcbFIAAAAAABAAO
bWFudTIsMi41KzEuMTIsMiwyXxSAAAAAAC4AKGlzc3Vlci1mcHJAbm90YXRpb25z
Lm9wZW5wZ3AuZmlmdGhob3JzZW1hbi5uZXQyNUE2QkI4OEREOUI3NjRDNkI1NTQx
QzI3Mzg0MDlGNTIwREY5MTkwDxxzYW1AZ2VudG9vLm9yZwAKCRBzhAn1IN+RkHOB
AP9KwAIyv2vYEGxBoN+FMx2NW3faGH9/efNQ+rhbiqiU0wD+Mjrr8Y9FVzx/Njk2
KAfEIkUGDhDAjH216OExoR1Z0gQ=
=J7bc
-----END PGP SIGNATURE-----
--=-=-=--