Hi Branden!
On 7/30/21 12:01 AM, G. Branden Robinson wrote:
Hi, Alex!
[regrets for the huge CC--those not interested in English/linux-man
style issues can skip this]
At 2021-07-29T16:56:37+0200, Alejandro Colomar (man-pages) wrote:
On 7/12/21 5:57 PM, Mickaël Salaün wrote:
+For instance, one process's thread may apply Landlock rules to itself,
s/process's/process'/
Many English language authorities would disagree with you, but I'll skip
digging up citations to them because the Linux man-pages project's
practice is already firmly in the other direction.
$ git grep "s's\>" | wc -l
322
Moreover, "process's" is extensively attested as most of those...
$ git grep "process's" | wc -l
320
My bad. It was correct. I was wrong.
I learnt today that the omission of "s" after the apostrophe is only in
the case of plural nouns (I don't remember having learnt that at school :/).
I suspect I probably wrote that before learning that.
...and a global change in the opposite direction from your
recommendation is credited to mtk in the Changes.old file.
$ grep -B2 "process' " Changes.old |head -n 3
A few files
mtk
s/process' /process's/
Finding examples of the opposite practice is complicated by the use of
apostrophes as single quotes (these usually _aren't_ confounded by code
examples, however, since it would be incorrect C language syntax to
quote a string literal with them). There are many such occurrences in
Changes.old; I'll skip them. The remainder are few enough that I'll
quote them here.
$ git grep -E "s'(\s|$)" man*
man2/adjtimex.2:Linux uses David L.\& Mills' clock adjustment algorithm (see RFC\ 5905).
man2/move_pages.2:.\" FIXME Describe the result if pointers in the 'pages' array are
man2/utimensat.2:.\" given a 'times' array in which both tv_nsec fields are UTIME_NOW, which
man2/utimensat.2:.\" provides equivalent functionality to specifying 'times' as NULL, the
man3/getaddrinfo.3:.\" 2008-02-26, mtk; clarify discussion of NULL 'hints' argument; other
man3/printf.3:thousands' grouping character is used.
man3/printf.3:the output is to be grouped with thousands' grouping characters
man3/printf.3:.\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$".
man3/scanf.3:This specifies that the input number may include thousands'
man3/xdr.3:the array elements' C form, and their external
man3/xdr.3:the array elements' C form, and their external
man5/elf.5:The array element is unused and the other members' values are undefined.
man5/proc.5:under the default overcommit 'guess' mode (i.e., 0 in
man5/proc.5:because other nodes' memory may be free,
man7/bootparam.7:The Linux kernel accepts certain 'command-line options' or 'boot time
man7/bootparam.7:parameters' at the moment it is started.
man7/bootparam.7:The option 'reboot=bios' will
man7/bootparam.7:A SCSI device can have a number of 'subdevices' contained within
man7/hier.7:Users' mailboxes.
man7/mount_namespaces.7:the root directory under several users' home directories.
man7/uri.7:schemes; see those tools' documentation for information on those schemes.
man7/uri.7:detects the users' environment (e.g., text or graphics,
man8/ld.so.8:and do not apply to those objects' children,
Of the above,
1. most are correct uses of the English plural possessive ("nodes'");
2. a few occur in comments, where they're fine if present as
commentary--if they're "commented out" chunks of man page source,
they should follow man page formatting rules in the event they
require "resurrection";
3. we see some uses of apostrophes as quotation marks; and
4. David L. Mills's name is marked as a plural possessive. The
application of apostrophe+s to singular proper names ending in "s" is
a debated issue, and there is probably some room for personal
preference on the part of the bearer of the name.
Two side issues:
A. Regarding point 3, I'd say this illustrates advantages of using
special character escape sequences like \[lq] and \[rq] for quotation.
First, you will get paired quotation marks in UTF-8, PDF, and HTML
output. Second, you won't encounter false positives in searches like
the above. Third, you semantically enrich the content. On the
downside, adopting special character escapes would likely mean having to
choose between U.S. and U.K. quotation styles[1].
I don't know what to do about this. For searches, if you come up with a
complex enough regex, you can get rid of quotations. If we use
different characters, then it will be really difficult to search for
actual quotations (I don't have them on my keyboard ;).
But having nicer PDF/HTML pages would be an advantage. However, I think
most usage of man-pages is in the terminal, so I'd focus on the terminal.
What do you think about this?
B. Regarding another active thread we're in, I observe
man2/adjtimex.2:Linux uses David L.\& Mills' clock adjustment algorithm (see RFC\ 5905).
as another case where \~ recommends itself over "\ "; this isn't even a
code example, and it illustrates the desirability of decoupling
non-breaking from participation in space adjustment.
Agreed.
Popping the stack, have I persuaded you on the plural possessive front?
:)
Yup :)
Best regards,
Branden
[1] https://man7.org/linux/man-pages/man7/groff_char.7.html (search for
"the apostrophe")
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
