[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <avW2G8eKE5w0Xy9O@devuan>
Date: Thu, 12 Nov 2026 14:12:21 +0100
From: Alejandro Colomar <alx@...nel.org>
To: Alejandro Colomar <alx+linux-man@...nel.org>,
Rich Felker <dalias@...c.org>, Vincent Lefevre <vincent@...c17.net>, linux-man@...r.kernel.org,
libc-alpha@...rceware.org, Walter Harms <wharms@....de>, ~hallyn/shadow@...ts.sr.ht,
musl@...ts.openwall.com
Subject: Re: Re: [PATCH v1] man/man3/crypt.3: These functions accept
many algorithms, not only DES
Hi Szabolcs,
> Date: 2026-11-12 13:41:14+0100
> From: Szabolcs Nagy <nsz@...t70.net>
>
> * Alejandro Colomar <alx+linux-man@...nel.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>
Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)
Powered by blists - more mailing lists
Confused about mailing lists and their use?
Read about mailing lists on Wikipedia
and check out these
guidelines on proper formatting of your messages.
