Re: [PATCH] recv.2: msg_iovec / MSG_ERRQUEUE / -v

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1.1: Type: text/plain, Size: 4093 bytes --]

[CC -= Rob, to not noise him too much]

Hi Branden,

On 2023-07-15 21:59, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-07-15T18:34:59+0200, Alejandro Colomar wrote:
>>> From 830a1b1233eb69bd8a4a64296581d094fb0edc46 Mon Sep 17 00:00:00 2001
>>> From: rokkbert <rokkbert@gmail.com>
>>
>> [...]
>>
>>> +.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.

But can that construct be anything other than a compound 
> 
> 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

[criticizing that link]

+ Examples:
+ an off-campus apartment
+ state-of-the-art design
+ 
+ When a compound adjective follows a noun, a hyphen is usually not necessary.
+ 
+ Example: The apartment is off campus.

What?  "is" is a verb.  The compound adjective follows a verb, not a noun.
Or does it mean after in the sense that anything can come in between, as
long as it's the noun which it modifies and it has come before the
adjective?  Is that a valid use of the word "follows"?  I'm not native,
but that sounds, ughh.


BTW, that's the only case where it says to not use hyphens, and since by
being alone it's necessarily not following a noun, I'd say it doesn't fall
in this rule, and so a hyphen would be deserved.

> http://www.mit.edu/course/21/21.guide/hyphen.htm
> https://grammarist.com/grammar/hyphens/

I don't see reasons to avoid it in the links above.

So, I'm tending to conclude that it's necessary, or at least useful or
tasteful.  Please quote the relevant parts if you disagree.

> 
> 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@gmail.com>
> Date:   Sat Jul 15 14:54:32 2023 -0500
> 
>     man-pages(7): Add attributive annotation advice.
> 
>     Prompted-by: Alejandro Colomar <alx@kernel.org>

We use Reported-by: (mostly for bug fixes), Suggested-by: (for features),
or when none fits, just Cc:.

>     Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>

LGTM.  Please send a patch.

Thanks!
Alex

> 
> 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

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]