Hi Keith,

> Date: 2026-08-01 15:22:49-0700
> From: Keith Bostic <keith@bostic.com>
>
> On Sat, Aug 1, 2026 at 10:09 AM Alejandro Colomar <alx@kernel.org> wrote:
> 
> 
> Well, Keith Bostic wouldn't have suggested that I do this change, and
> Branden wouldn't be defending that it might make sense to make this
> change.
> 
> 
> Since my name came up: I did suggest man page changes, and I should have
> been clearer about what I meant.

Thanks!

> I generally think innovation should happen in releases, in response to the
> user base. That’s the model with the better track record. Somebody ships
> something, users adopt it or they don’t, and the standards codify existing
> practice once it reaches consensus. When the standards bodies invent
> instead of codify, results have been uneven.

Fully agreed.

> So if glibc added <nonstring.h> tomorrow, that’s the system working. Ship
> it, let people vote with their code, and let the standard adopt if it wants.
> 
> But as I understand it, the man-pages project doesn’t control the code it
> documents. It describes glibc and the kernel, it doesn’t ship them. A
> documentation project changing how coding should work in a release it
> doesn’t control feels different to me. So, my opinion is the man pages
> shouldn’t be changing the standard includes.

Actually, the documentation is for the system, not the standard.  The
system does provide <memory.h>, and thus it's fair game to document it,
I believe.

> Advocating for better usage in the documentation is a different thing, and
> a good thing. The man pages can even go pretty hard, that’s their job:
> “Notice the include file is string.h. That’s an historic accident
> maintained for compatibility reasons; don’t let that fool you, this
> function doesn’t operate on strings.”

Indeed.  That's in essence what I'll do, with different wording.

The SYNOPSIS is the way of saying "don't let other sources fool you,
this function doesn't work on strings, and you should include the
system's <memory.h> to get it, which is compatible with all versions of
libc".

The NOTES section is the way of documenting "but the standard says
something different; let's ignore it".

	--- HEAD^:man/man3/strdupa.3
	+++ HEAD:man/man3/strdupa.3
	@@ -11,6 +11,10 @@ SYNOPSIS
	      #include <string.h>
	 
	      char *strdupa(const char *s);
	+
	+     #define _GNU_SOURCE  /* See feature_test_macros(7) */
	+     #include <memory.h>
	+
	      char *strndupa(size_t n;
			    const char s[n], size_t n);
	 
	@@ -48,6 +52,9 @@ STANDARDS
	 HISTORY
	      GNU.
	 
	+NOTES
	+     The following header also provides strndupa(): <string.h>.
	+
	 SEE ALSO
	      alloca(3), strdup(3), strndup(3)
	 
> That teaches the reader what the function actually does without relabeling
> where it lives. I think it’s roughly what Joseph is suggesting as well,
> aiming the clarification at the reader’s understanding rather than at the
> SYNOPSIS line.

I should probably expand the NOTES a little bit, to be more clear about
why we ignore the standard in the SYNOPSIS.


Have a lovely night!
Alex

> 
> —keith
> keith@bostic.com

-- 
<https://www.alejandro-colomar.es>