Re: The goal of the Linux man-pages project

[Alejandro Colomar <alx@kernel.org>]

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

Hi DJ,

Thanks a lot for this feedback!  I appreciate the constructive tone!  :)

> Date: 2026-08-05 10:50:30-0400
> From: DJ Delorie <dj@redhat.com>
>
> Alejandro Colomar <alx@kernel.org> writes:
> > 	SYNOPSIS
> > 	     #include <string.h>  // see memory.h(3head)
> 
> This belongs in either SEE ALSO or FILES.

It's _also_ in SEE ALSO.

	$ MANWIDTH=64 man memcpy | grep -C1 memory.h
	SYNOPSIS
	     #include <string.h>  // see memory.h(3head)

	--
	SEE ALSO
	     memory.h(3head), bcopy(3),  memccpy(3),  memmove(3),  mem‐
	     pcpy(3), strcpy(3), strncpy(3), wmemcpy(3)

FILES is rarely used in man3; when used, it's more about configuration
files, and not includes.  SYNOPSIS is the main place where we currently
specify files.

Actually, this reminds me again of the documentation of types, which are
often provided in several header files.  I used NOTES in those, because
I couldn't think of a good section for that.  See for example the NOTES
section of size_t(3type):

	NOTES
	     size_t
		    The following headers also provide size_t: <aio.h>,
		    <glob.h>,   <grp.h>,    <iconv.h>,    <monetary.h>,
		    <mqueue.h>,     <ndbm.h>,    <pwd.h>,    <regex.h>,
		    <search.h>,  <signal.h>,   <stdio.h>,   <stdlib.h>,
		    <string.h>, <strings.h>, <sys/mman.h>, <sys/msg.h>,
		    <sys/sem.h>,      <sys/shm.h>,      <sys/socket.h>,
		    <sys/types.h>, <sys/uio.h>,  <time.h>,  <unistd.h>,
		    <wchar.h>, and <wordexp.h>.

	     ssize_t
		    The   following   headers   also  provide  ssize_t:
		    <aio.h>,   <monetary.h>,   <mqueue.h>,   <stdio.h>,
		    <sys/msg.h>,   <sys/socket.h>,   <sys/uio.h>,   and
		    <unistd.h>.

I think it could make sense to move that to a FILES section.

About being in SYNOPSIS, I think I want it there, because it's not there
as documenting a header file that provides this function, but mainly as
documenting that while it's provided by <string.h> it's not a string
function.

> > 	STANDARDS
> > 	     BSD.
> >
> > 	     These functions are also provided in <string.h>, as speci‐
> > 	     fied by ISO C.
> 
> Ok so far
> 
> >	     This is a historic mistake maintained  for
> > 	     compatibility  reasons.   Don’t  let  that fool you; these
> > 	     functions don’t necessarily operate on strings.
> 
> This just doesn't fit, it's far too opinionated and personal.  It needs
> to be more neutral and standards-respecting.
> 
>   "Historically, this file contained memory-related functions, while
>   string.h contained string-related functions, but currently these
>   functions are all in string.h, despite these not being string
>   functions, and typically memory.h just includes string.h for
>   compatibility across all the historic standards."
> 
> I'm not arguing against the message here, just the tone.

I believe your suggestion removes the idea that the message intended to
give, but I concede that the tone was too harsh.

	Author: Alejandro Colomar <alx@kernel.org>
	Date:   2026-08-05 17:11:04 +0200

	    man/man3head/memory.h.3head: STANDARDS: Neutralize the tone
	    
	    Reported-by: DJ Delorie <dj@redhat.com>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man3head/memory.h.3head b/man/man3head/memory.h.3head
	index 6c04722c4cf3..59f91e2ed023 100644
	--- a/man/man3head/memory.h.3head
	+++ b/man/man3head/memory.h.3head
	@@ -65,8 +65,7 @@ .SH STANDARDS
	 These functions are also provided in
	 .IR <string.h> ,
	 as specified by ISO C.
	-This is a historic mistake maintained for compatibility reasons.
	-Don't let that fool you;
	+This is a historic mistake maintained for compatibility reasons;
	 these functions don't necessarily operate on strings.
	 .SH HISTORY
	 SVr1, 4.3BSD.

Removing the "don't let that fool you" should neutralize the tone.
I prefer keeping the "historic mistake maintained for compatibility
reasons", because it really was a mistake, and I believe it is good to
acknowledge mistakes.  Documenting a mistake doesn't mean we're
disrespecting the authors; just that with the information we have today,
we wish it was different.

> As for the message...
> 
> I think the only way we could be more persuasive is if we convinced the
> standards committees to actually segregate string and memory functions
> in the specifications, and tell you to ("shall") include string.h or
> memory.h accordingly, but that would break a lot of programs if it was
> actually required ("must").

Agreed.

> As an interim step, we could get the standards to specify string.h for
> string functions and memory.h for memory functions ("should"), knowing
> that either include gives you both,

That is more or less what my draft of the standards proposal says.

My proposal doesn't provide the str[^n]*() functions in <memory.h>,
though.  I think it's much better if that remains a vendor extension.

> and at a later date (after all the
> software is migrated) change to "shall" and start encouraging providers
> to actually segregate them.  Or offer a #define that strictly separates
> them to aid in migration, such as we do with other api-breaking
> standards changes.


Have a lovely day!
Alex

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

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