[patch] unshare.2: Add note about potential capabilities confusion

[patch] unshare.2: Add note about potential capabilities confusion

[Patrick Reader]

See https://bugzilla.kernel.org/show_bug.cgi?id=216215 for context.

I know nothing about groff formatting, so what I wrote here is based on 
my inference from reading the existing source. If it's wrong, I apologise.


Signed-off-by: Patrick Reader <_@pxeger.com>
---
  man/man2/unshare.2 | 10 ++++++++++
  1 file changed, 10 insertions(+)

diff --git a/man/man2/unshare.2 b/man/man2/unshare.2
index e72464950..851129022 100644
--- a/man/man2/unshare.2
+++ b/man/man2/unshare.2
@@ -461,6 +461,16 @@ Such functionality may be added in the future, if 
required.
  .\"be incrementally added to unshare without affecting legacy
  .\"applications using unshare.
  .\"
+.PP
+Creating all kinds of namespace, except user namespaces, requires the
+.B CAP_SYS_ADMIN
+capability. However, since creating a user namespace automatically 
confers a
+full set of capabilities, creating both a user namespace and any other type
+of namespace in the same
+.BR unshare ()
+call does not require the
+.B CAP_SYS_ADMIN
+capability in the original namespace.
  .SH EXAMPLES
  The program below provides a simple implementation of the
  .BR unshare (1)
-- 
2.37.3

Re: [patch] unshare.2: Add note about potential capabilities confusion

[Alejandro Colomar]

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

Hi Patrick,

On 9/6/22 11:01, Patrick Reader wrote:
> See https://bugzilla.kernel.org/show_bug.cgi?id=216215 for context.
> 
> I know nothing about groff formatting, so what I wrote here is based on 
> my inference from reading the existing source. If it's wrong, I apologise.

Well, you did quite well.  The man(7) source code you wrote is perfect, 
except for one minor detail: after the end-of-sentence period you should 
either write two spaces or a newline.

On top of that, we have a "rule" that helps the pages be more 
maintainable, and to me it also improves readability of the source code: 
that is semantic newlines.  But of course it's unlikely that you knew 
about them.

man-pages(7):
    Use semantic newlines
        In the source of a manual page, new sentences  should  be
        started on new lines, long sentences should be split into
        lines  at  clause breaks (commas, semicolons, colons, and
        so on), and long clauses should be split at phrase bound‐
        aries.  This convention,  sometimes  known  as  "semantic
        newlines",  makes it easier to see the effect of patches,
        which often operate at the level of individual sentences,
        clauses, or phrases.

There's a pointer to that manual page in the CONTRIBUTING file in the 
source of the repo, but I understand it's unlikely that one will follow 
all pointers from there just to write a very small patch, so don't worry.

> 
> 
> Signed-off-by: Patrick Reader <_@pxeger.com>

Would you mind fixing those small issues and send an v2?
I like the contents of the patch.

Cheers,

Alex

> ---
>   man/man2/unshare.2 | 10 ++++++++++
>   1 file changed, 10 insertions(+)
> 
> diff --git a/man/man2/unshare.2 b/man/man2/unshare.2
> index e72464950..851129022 100644
> --- a/man/man2/unshare.2
> +++ b/man/man2/unshare.2
> @@ -461,6 +461,16 @@ Such functionality may be added in the future, if 
> required.
>   .\"be incrementally added to unshare without affecting legacy
>   .\"applications using unshare.
>   .\"
> +.PP
> +Creating all kinds of namespace, except user namespaces, requires the
> +.B CAP_SYS_ADMIN
> +capability. However, since creating a user namespace automatically 
> confers a
> +full set of capabilities, creating both a user namespace and any other 
> type
> +of namespace in the same
> +.BR unshare ()
> +call does not require the
> +.B CAP_SYS_ADMIN
> +capability in the original namespace.
>   .SH EXAMPLES
>   The program below provides a simple implementation of the
>   .BR unshare (1)

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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

Re: [patch] unshare.2: Add note about potential capabilities confusion

[Patrick Reader]

On 06/09/2022 12:50, Alejandro Colomar wrote:
> Would you mind fixing those small issues and send an v2?

Voilà!

 From a63c099d31c8fd27af6428c4d9191df698b2c0e7 Mon Sep 17 00:00:00 2001
From: Patrick Reader <_@pxeger.com>
Date: Tue, 6 Sep 2022 12:56:12 +0100
Subject: [PATCH 2/2] fix formatting

---
  man/man2/unshare.2 | 7 ++++---
  1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/man/man2/unshare.2 b/man/man2/unshare.2
index 851129022..79a960728 100644
--- a/man/man2/unshare.2
+++ b/man/man2/unshare.2
@@ -464,9 +464,10 @@ Such functionality may be added in the future, if 
required.
  .PP
  Creating all kinds of namespace, except user namespaces, requires the
  .B CAP_SYS_ADMIN
-capability. However, since creating a user namespace automatically 
confers a
-full set of capabilities, creating both a user namespace and any other type
-of namespace in the same
+capability.
+However, since creating a user namespace automatically confers a full 
set of
+capabilities,
+creating both a user namespace and any other type of namespace in the same
  .BR unshare ()
  call does not require the
  .B CAP_SYS_ADMIN
-- 
2.37.3

Re: [patch] unshare.2: Add note about potential capabilities confusion

[Alejandro Colomar]

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

Hi Patrick,

On 9/6/22 13:58, Patrick Reader wrote:
> On 06/09/2022 12:50, Alejandro Colomar wrote:
>> Would you mind fixing those small issues and send an v2?
> 
> Voilà!
> 
>  From a63c099d31c8fd27af6428c4d9191df698b2c0e7 Mon Sep 17 00:00:00 2001
> From: Patrick Reader <_@pxeger.com>
> Date: Tue, 6 Sep 2022 12:56:12 +0100
> Subject: [PATCH 2/2] fix formatting

I was going to apply your patches, when I got a warning from git-am(1):

warning: Patch sent with format=flowed; space at the end of lines might 
be lost.
Applying: unshare.2: Add note about potential capabilities confusion
error: corrupt patch at line 10

I guess you copied the patches into your mailer, and it screwed it.  If 
you could re-send your patches with git-send-email(1) or some other tool 
that can send them pristine, that would be great.  Otherwise, I can try 
to apply your changes manually.

Cheers,

Alex

> 
> ---
>   man/man2/unshare.2 | 7 ++++---
>   1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/man/man2/unshare.2 b/man/man2/unshare.2
> index 851129022..79a960728 100644
> --- a/man/man2/unshare.2
> +++ b/man/man2/unshare.2
> @@ -464,9 +464,10 @@ Such functionality may be added in the future, if 
> required.
>   .PP
>   Creating all kinds of namespace, except user namespaces, requires the
>   .B CAP_SYS_ADMIN
> -capability. However, since creating a user namespace automatically 
> confers a
> -full set of capabilities, creating both a user namespace and any other 
> type
> -of namespace in the same
> +capability.
> +However, since creating a user namespace automatically confers a full 
> set of
> +capabilities,
> +creating both a user namespace and any other type of namespace in the same
>   .BR unshare ()
>   call does not require the
>   .B CAP_SYS_ADMIN

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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