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

[Sam James <sam@gentoo.org>]

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

Alejandro Colomar <alx@kernel.org> writes:

> Hi Sam,
>
>> Date: 2026-07-31 22:54:27+0100
>> From: Sam James <sam@gentoo.org>
>>
>> Alejandro Colomar <alx@kernel.org> writes:
>> 
>> > Hi Joseph,
>> >
>> >> Date: 2026-07-31 21:23:35+0000
>> >> From: Joseph Myers <josmyers@redhat.com>
>> >>
>> >> I think it's irresponsible to use the man-pages project to promote 
>> >> personal idiosyncratic ideas like this in preference to what's been the 
>> >> standard location of functions since 1989.
>> >> 
>> >> I'd rather we add a mandatory deprecation warning to memory.h in glibc.
>> >
>> > I hope you don't; it'd be a gratuitous breaking change.
>> >
>> 
>> 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=64 mansectf STANDARDS man3/memcpy.3 | cat
> 	memcpy(3)           Library Functions Manual          memcpy(3)
>
> 	STANDARDS
> 	     C11, POSIX.1‐2008.
>
> 	     ISO C and POSIX declare this function in <string.h>.
>
> 	Linux man‐pages (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

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