[CC += Doug] Hi Mark, Thanks for the feedback! See below for comments. On 2026-07-02T22:03:05-0700, Mark Harris wrote: > Alejandro Colomar wrote: > > > > Reported-by: "Serge E. Hallyn" > > Signed-off-by: Alejandro Colomar > > --- > > > > Hi Serge, > > > > I finally took some time to do this that you asked me to do some time > > ago. I've edited all the str*(3) manual pages so that the NAME section > > actually explains the name of the function. > > > > There's an exception: strpbrk(3). I refuse to explain that name. I've > > explained it as if it were called strchrs(), which is a name that Plan9 > > uses for that function, and which would have been a better name for it. > > (See patch 2/2). > > > > > > Have a lovely day! > > Alex > > > > man/man3/strcasecmp.3 | 2 +- > > man/man3/strchr.3 | 2 +- > > man/man3/strcmp.3 | 2 +- > > man/man3/strcoll.3 | 2 +- > > man/man3/strcpy.3 | 2 +- > > man/man3/strdup.3 | 2 +- > > man/man3/strerror.3 | 5 +++-- > > man/man3/strfmon.3 | 2 +- > > man/man3/strfromd.3 | 3 +-- > > man/man3/strfry.3 | 2 +- > > man/man3/strftime.3 | 2 +- > > man/man3/string.3 | 5 +---- > > man/man3/strlen.3 | 2 +- > > man/man3/strncat.3 | 5 +---- > > man/man3/strnlen.3 | 2 +- > > man/man3/strpbrk.3 | 2 +- > > man/man3/strptime.3 | 2 +- > > man/man3/strsep.3 | 2 +- > > man/man3/strsignal.3 | 2 +- > > man/man3/strspn.3 | 2 +- > > man/man3/strtod.3 | 2 +- > > man/man3/strtoimax.3 | 2 +- > > man/man3/strtok.3 | 2 +- > > man/man3/strtol.3 | 2 +- > > man/man3/strtoul.3 | 2 +- > > man/man3/strverscmp.3 | 2 +- > > man/man3/strxfrm.3 | 2 +- > > 27 files changed, 29 insertions(+), 35 deletions(-) > > > > diff --git a/man/man3/strcasecmp.3 b/man/man3/strcasecmp.3 > > index aa554341da4c..65941ddf6524 100644 > > --- a/man/man3/strcasecmp.3 > > +++ b/man/man3/strcasecmp.3 > > @@ -6,7 +6,7 @@ > > .\" > > .TH strcasecmp 3 (date) "Linux man-pages (unreleased)" > > .SH NAME > > -strcasecmp, strncasecmp \- compare two strings ignoring case > > +strcasecmp, strncasecmp \- strings case-insensitive compare > > .SH LIBRARY > > Standard C library > > .RI ( libc ,\~ \-lc ) [...] > > diff --git a/man/man3/strspn.3 b/man/man3/strspn.3 > > index fe4414317df6..7c85d209c59d 100644 > > --- a/man/man3/strspn.3 > > +++ b/man/man3/strspn.3 > > @@ -6,7 +6,7 @@ > > .\" > > .TH strspn 3 (date) "Linux man-pages (unreleased)" > > .SH NAME > > -strspn, strcspn \- get length of a prefix substring > > +strspn, strcspn \- string [complementary] span > > .SH LIBRARY > > Standard C library > > .RI ( libc ,\~ \-lc ) [...] > > diff --git a/man/man3/strxfrm.3 b/man/man3/strxfrm.3 > > index d4ac57006eb0..a892bf4c813b 100644 > > --- a/man/man3/strxfrm.3 > > +++ b/man/man3/strxfrm.3 > > @@ -6,7 +6,7 @@ > > .\" > > .TH strxfrm 3 (date) "Linux man-pages (unreleased)" > > .SH NAME > > -strxfrm \- string transformation > > +strxfrm \- string transform > > .SH LIBRARY > > Standard C library > > .RI ( libc ,\~ \-lc ) > > -- > > 2.53.0 > > > > The text after the \- is documented as a "summary-description", and > many users and tools (including man -k, apropos, and whatis) rely on > this. I thought precisely about whatis(1) when doing this. Here's what whatis(1) shows after this change (and a similar one for mem*(3)): $ find man/man3/ -type f \ | grep -e/mem -e/str \ | xargs basename -s.3 \ | xargs whatis \ | grep '(3)' \ | sort; memalign (3) - memory aligned allocate memccpy (3) - memory until-and-including-character copy memchr (3) - memory search character memcmp (3) - memory compare memcpy (3) - memory copy memeq (3) - memory equal memfrob (3) - memory frobnicate (obfuscate) memmem (3) - memory search submemory memmove (3) - memory move mempcpy (3) - memory return-offset-pointer copy memrchr (3) - memory rear-search character memset (3) - memory set strcasecmp (3) - strings case-insensitive compare strcasestr (3) - string case-insensitive search substring strcat (3) - string copy/catenate strchr (3) - string search character strchrnul (3) - string search character or NUL strcmp (3) - strings compare strcoll (3) - strings collate strcpy (3) - string copy/catenate strcspn (3) - string [complementary] span strdup (3) - string duplicate strdupa (3) - string duplicate using alloca streq (3) - strings equal strerror (3) - string error-string strerror_l (3) - string error-string strerror_r (3) - string error-string strerrordesc_np (3) - string error-string strerrorname_np (3) - string error-string strfmon (3) - string format monetary value strfmon_l (3) - string format monetary value strfromd (3) - string from float strfromf (3) - string from float strfroml (3) - string from float strfry (3) - string fry (obfuscate) strftime (3) - string format date and time strftime_l (3) - string format date and time string (3) - byte operations strlen (3) - string length strncasecmp (3) - strings case-insensitive compare strncat (3) - nonstring catenate strncmp (3) - strings compare strncpy (3) - fill a fixed-size buffer with non-null bytes from a st... strndup (3) - string duplicate strndupa (3) - string duplicate using alloca strnlen (3) - nonstring length strnul (3) - string search NUL strpbrk (3) - string search characters strptime (3) - string parse time strrchr (3) - string rear-search character strsep (3) - string separate strsignal (3) - string signal description strspn (3) - string [complementary] span strstr (3) - string search substring strtod (3) - string to float strtof (3) - string to float strtoimax (3) - string to [u]intmax_t strtok (3) - string tokenize strtok_r (3) - string tokenize reentrant strtol (3) - string to long int strtold (3) - string to float strtoll (3) - string to long int strtoq (3) - string to long int strtoul (3) - string to unsigned long int strtoull (3) - string to unsigned long int strtoumax (3) - string to [u]intmax_t strtouq (3) - string to unsigned long int strverscmp (3) - strings version compare strxfrm (3) - string transform As an example of how I think this is useful, I learnt the difference between strftime(3) and strptime(3) while doing this change. The ethymology of the name was the key to understanding it. strftime(3) is for _formatting_ a string, while strptime(3) is for _parsing_ from a string; I'll never forget that. Before, I knew one of them was for reading from a string, and the other for writing to a string, but never remembered which is which, so I had to consult the page every time. > Repeating the function name in a slightly more expanded form is > not only contrary to what users expect, but is much less useful than a > proper summary description. In most cases the new text does not > provide the summary that users expect from tools like man -k, is > inconsistent with other summaries that might be shown by man -k, and > is not even grammatically correct, making it needlessly difficult to > interpret as a summary or contrast with other summaries to determine > which of several matching functions is desired. I agree I wasn't entirely happy about it not being gramatically correct, but though that maybe it's not necessary to be so. > If an expanded form of the function name is useful, it could be added > to the NOTES section. I've CCd Doug McIlroy. I'm interested in his opinion before deciding what to do. Anyone else reading this, please give opinions too. I'm still undecided. Have a lovely day! Alex > > > > - Mark > --