the Linux man-pages as an educational tool

[Alejandro Colomar]

Hi Collin,

> Date: 2026-08-03 19:39:43-0700
> From: Collin Funk <collin.funk1@gmail.com>
>
> Sam James <sam@gentoo.org> writes:
> 
> > Alejandro Colomar <alx@kernel.org> writes:
> >
> >> Hi Collin,
> >>
> >>> Date: 2026-08-02 16:27:21-0700
> >>> From: Collin Funk <collin.funk1@gmail.com>
> >>>
> >> [...]
> >>> 
> >>> I can't help but wonder of what happens in WG 14 rejects this
> >>> controversial, as obvious by this thread, change. Will the man-pages
> >>> changes be reverted? Or will we slowly watch them document personal
> >>> preferences instead of existing standards?
> >>
> >> This patch set is quite independent of the standard.  It documents a
> >> header file that has been provided since forever in glibc and most other
> >> POSIX-ish systems, so changes to the standard are unlikely to have any
> >> effects.  I've clarified this extensively.  If you want to discourage me
> >> from applying the change, you should rather bring up technical reasons.
> >>
> >> This passive-aggressive message is not something that will have the
> >> desired effects you could possibly reach with technical arguments.
> >
> > I didn't read it as passive-aggressive, but I will say that I think
> > you've gone a bit hard in the responses to Collin in this subthread, and
> > I think the fact you sent several followup emails to yourself indicates
> > perhaps things got heated in the moment.
> 
> The last sentence was probably a bit rude, sorry about that.

No problem; thanks!

> However, I
> think a reasonable third party can understand my frustration.

I hope you can understand mine too.

[...]


> I am happy enough to fix the SYNOPSIS of my
> man pages locally like this:
> 
>     $ git grep -lF '<memory.h>' \
>         | xargs -n 1 sed -i 's|<memory.h>.*|<string.h>|g'
> 
> Hopefully distributions consider doing the same.

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?


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://sourceware.org/pipermail/libc-alpha/attachments/20260804/9c0acb43/attachment.sig>