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

[Alejandro Colomar <alx.manpages@gmail.com>]

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