Hi Szabolcs,

> Date: 2026-11-12 13:41:14+0100
> From: Szabolcs Nagy <nsz@port70.net>
>
> * Alejandro Colomar <alx+linux-man@kernel.org> [2026-11-12 13:27:13 +0100]:
> > How about something this (we can improve the wording)?
> > 
> > 	diff --git i/man/man3/crypt.3 w/man/man3/crypt.3
> > 	index 524781d3c2a0..d579bc5394fb 100644
> > 	--- i/man/man3/crypt.3
> > 	+++ w/man/man3/crypt.3
> > 	@@ -111,6 +111,9 @@ .SH ATTRIBUTES
> > 	 .BR crypt_r ()
> > 	 T}     Thread safety   MT-Safe
> > 	 .TE
> > 	+.SH VERSIONS
> > 	+POSIX specifies a quite useless API,
> > 	+and all systems extend it significantly.
> 
> please don't put nonsense into the official man pages.

I agree I could have used more precise wording.

I think you could have used more precise wording too, since you're
complaining about that.  What is nonsense in what I said?  Is it perhaps
too offensive?  Yes; I think I should have said s/useless/limited/.

Is it completely nonsense?  I think not.

> your job

Ironically, your job is *not* to judge or specify my job (if it's a job
at all).

I suggest that you limit yourself to comment on what *the manual pages*
should say, rather than on what *I* should do.

I'll continue as if you had said s/your job/the job of the manual pages/

> is to document the interface contract including
> implementation defined behaviour,

The contract is specified in the sections of the manual page that are
meant for that, such as DESCRIPTION, RETURN VALUE, etc.

VERSIONS is a section for discussing differences between
implementations, and between implementations and the spec (although this
might also go in STANDARDS; it's a blurry line).

> not to judge the spec

I do agree that we should not judge the spec unnecessarily.

But about what you said literally, I disagree.  The manual pages have
been full of opinions --where appropriate-- since the very early times
of manual pages.  Already in the early BSDs there were comments about
strncpy(3), for example.

Here's some of them:

	$ git show man-pages-5.00:man3/strcpy.3 \
	| MANWIDTH=64 lman /dev/stdin \
	| grep -A5 NOTES;
	NOTES
	     Some  programmers consider strncpy() to be inefficient and
	     error prone.  If the programmer knows (i.e., includes code
	     to test!)  that the size  of  dest  is  greater  than  the
	     length of src, then strcpy() can be used.

See <https://lore.kernel.org/linux-man/anJZza-qbi_y5r1N@devuan/> for
a (incomplete) list of historic counter-examples.

> and other systems.

I didn't judge other systems, I think.


Have a lovely day!
Alex

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