[PATCH] pkeys.7: ffix

[PATCH] pkeys.7: ffix

[наб]

[-- Attachment #1: Type: text/plain, Size: 632 bytes --]

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
 permissions passed to system calls such as
 .BR mprotect (2)
 and
-- 
2.30.2

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

Re: [PATCH] pkeys.7: ffix

[Alejandro Colomar (man-pages)]

Hi наб,

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

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.

But I'm open to discussion, if you want.

Thanks,

Alex

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

Re: [PATCH] pkeys.7: ffix

[наб]

[-- Attachment #1: Type: text/plain, Size: 1982 bytes --]

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
> 
> 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".)

IMO, 2 reads better. Thoughts?

наб

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

Re: [PATCH] pkeys.7: ffix

[Alejandro Colomar (man-pages)]

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/

[PATCH v2 1/2] pkeys.7: wfix

[наб]

[-- Attachment #1: Type: text/plain, Size: 632 bytes --]

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man7/pkeys.7 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/man7/pkeys.7 b/man7/pkeys.7
index 73ddcdc43..9c2356f65 100644
--- a/man7/pkeys.7
+++ b/man7/pkeys.7
@@ -42,8 +42,9 @@ 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_READ ,
+.BR PROT_WRITE ,
+and
 .BR PROT_EXEC
 permissions passed to system calls such as
 .BR mprotect (2)
-- 
2.30.2


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

[PATCH v2 2/2] glob.3: srcfix

[наб]

[-- Attachment #1: Type: text/plain, Size: 755 bytes --]

For consistency: this is the only non-false-positive for ", and",
which now reads:
  $ git grep '", and"'
  man2/ioctl_tty.2:.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man3/glob.3 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man3/glob.3 b/man3/glob.3
index 82fb16948..50516d600 100644
--- a/man3/glob.3
+++ b/man3/glob.3
@@ -147,7 +147,8 @@ Use alternative functions
 .IR pglob\->gl_closedir ,
 .IR pglob\->gl_readdir ,
 .IR pglob\->gl_opendir ,
-.IR pglob\->gl_lstat ", and"
+.IR pglob\->gl_lstat ,
+and
 .I pglob\->gl_stat
 for filesystem access instead of the normal library
 functions.
-- 
2.30.2

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

Re: [PATCH v2 1/2] pkeys.7: wfix

[Alejandro Colomar (man-pages)]

On 1/11/22 19:27, наб wrote:
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Patch applied.

Thanks!

Alex

> ---
>   man7/pkeys.7 | 5 +++--
>   1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/man7/pkeys.7 b/man7/pkeys.7
> index 73ddcdc43..9c2356f65 100644
> --- a/man7/pkeys.7
> +++ b/man7/pkeys.7
> @@ -42,8 +42,9 @@ 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_READ ,
> +.BR PROT_WRITE ,
> +and
>   .BR PROT_EXEC
>   permissions passed to system calls such as
>   .BR mprotect (2)

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

Re: [PATCH v2 2/2] glob.3: srcfix

[Alejandro Colomar (man-pages)]

Hi наб,

On 1/11/22 19:28, наб wrote:
> For consistency: this is the only non-false-positive for ", and",
> which now reads:
>    $ git grep '", and"'
>    man2/ioctl_tty.2:.BR "#include <termios.h>" "      /* Definition of " CLOCAL ", and"
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

:-)
Applied!

Cheers,

Alex

> ---
>   man3/glob.3 | 3 ++-
>   1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/glob.3 b/man3/glob.3
> index 82fb16948..50516d600 100644
> --- a/man3/glob.3
> +++ b/man3/glob.3
> @@ -147,7 +147,8 @@ Use alternative functions
>   .IR pglob\->gl_closedir ,
>   .IR pglob\->gl_readdir ,
>   .IR pglob\->gl_opendir ,
> -.IR pglob\->gl_lstat ", and"
> +.IR pglob\->gl_lstat ,
> +and
>   .I pglob\->gl_stat
>   for filesystem access instead of the normal library
>   functions.

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