Hi Alex,
At 2023-07-15T18:34:59+0200, Alejandro Colomar wrote:
> > From 830a1b1233eb69bd8a4a64296581d094fb0edc46 Mon Sep 17 00:00:00 2001
> > From: rokkbert <rokkbert@xxxxxxxxx>
>
> [...]
>
> > +.BR MSG_ERRQUEUE " (" recvmsg "() only; since Linux 2.2)"
>
> I believe it should be recvmsg()-only, since it's a compound
> adjective. Branden, can you please confirm if I'm right?
It's a little difficult to answer this because this two-word phrase does
not exist within a sentence.
Online authorities suggest that the hyphen should be omitted in most
cases, and don't call out "only" as an exception (unlike "based").
https://www.grammarbook.com/punctuation/hyphens.asp
http://www.mit.edu/course/21/21.guide/hyphen.htm
https://grammarist.com/grammar/hyphens/
In the man page in question, what we have is a sort of heading
(typographically, a paragraph tag), with some annotations on it, not a
complete sentence. Adding the hyphen doesn't clarify anything in this
case, so I would omit it.
I did some web searches to try to find analogous examples but I kept
running into exhibits of use from sources that I don't consider to be of
generally high reliability in the practice of standard grammar, such as
commercial advertising and job postings at the retail level.
On the broader subject of marking up these annotations, and looking at
existing Linux man-pages practice, I perceive a possible need for
further guidance in man-pages(7). So here's a straw-man patch for your
consideration.
commit 43b89c2304552b18c9a9ea02bca05ffd94d6518c (HEAD -> master)
Author: G. Branden Robinson <g.branden.robinson@xxxxxxxxx>
Date: Sat Jul 15 14:54:32 2023 -0500
man-pages(7): Add attributive annotation advice.
Prompted-by: Alejandro Colomar <alx@xxxxxxxxxx>
Signed-off-by: G. Branden Robinson <g.branden.robinson@xxxxxxxxx>
diff --git a/man7/man-pages.7 b/man7/man-pages.7
index d63f2d8f2..aa39dbfd2 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -255,6 +255,13 @@ .SS Sections within a manual page
Including version information is especially useful to users
who are constrained to using older kernel or C library versions
(which is typical in embedded systems, for example).
+.IP
+When an aspect of an interface requires multiple annotations,
+such as an applicable architecture,
+data type,
+or indication of read-only status,
+include these before the version information and separate them
+with semicolons.
.TP
.B OPTIONS
A description of the command-line options accepted by a
Regards,
Branden
Attachment:
signature.asc
Description: PGP signature
