Re: [PATCH] pkeys.7: ffix

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hi!

On 1/10/22 19:49, наб wrote:
> Hi!
> 
> On Mon, Jan 10, 2022 at 07:13:48PM +0100, Alejandro Colomar (man-pages) wrote:
>> On 1/9/22 17:21, наб wrote:
>>> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
>>> ---
>>>    man7/pkeys.7 | 4 +---
>>>    1 file changed, 1 insertion(+), 3 deletions(-)
>>>
>>> diff --git a/man7/pkeys.7 b/man7/pkeys.7
>>> index 73ddcdc43..0fff6493f 100644
>>> --- a/man7/pkeys.7
>>> +++ b/man7/pkeys.7
>>> @@ -42,9 +42,7 @@ to change the contents of a register in order to remove write
>>>    access, or all access to a tagged page.
>>>    .PP
>>>    Protection keys work in conjunction with the existing
>>> -.BR PROT_READ /
>>> -.BR PROT_WRITE /
>>> -.BR PROT_EXEC
>>> +.BR PROT_READ / PROT_WRITE / PROT_EXEC

Ahh, sorry, EPARSE!

The existing code was wrong.  I read it as:
.BR PROT_READ " /"

>>
>> It's not that your formatting seems worse to me in this case.
>>
>> However, since we already have some kind of norm of writing each identifier
>> on its own line, I'll keep it like that for consistency.
>> That consistency also helps write scripts to find some patterns.
> The problem with that is, of course, that it looks, uh, Not Good
> (and that's already quite generous).
> Hardly a good use of a typesetting language.
> 
> There's two ways to go about this, both keeping one symbol per line
> (which, I do agree, is quite nice; the scriptability concern is somewhat
>   misplaced, IMO, given man(7)-imposed limitations, but.).
> 
> 1. Keeping the current /-based flow:
>       Protection keys work in conjunction with the existing
>       .BR PROT_READ / \
>       PROT_WRITE / \
>       PROT_EXEC
>       permissions passed to system calls such as
>     (This sets as my original patch: "isting [P_R]/[P_W]/[P_E] permiss".)
> 
> 2. Reorienting as a list:
>       Protection keys work in conjunction with the existing
>       .BR PROT_READ ,
>       .BR PROT_WRITE ", and"
>       .BR PROT_EXEC
>       permissions passed to system calls such as
>     (Which sets as "existing [P_R], [P_W], and [P_E] permissions".)

So, yes, either your 2nd option or fixing it to use " /" would be ok. 
Text tends to be more readable, I think.

For your second option, I'd avoid using ", and", and put and on its own 
line:

.BR AAA ,
.BR BBB ,
and
.BR CCC

rationale:

$ grep -rn '", and"' man? | wc -l
2
$ grep -rn "^and$" man? | wc -l
2447


Thanks!

Alex

> 
> IMO, 2 reads better. Thoughts? >
> наб

-- 
Alejandro Colomar
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/