linux-kernel - Re: [PATCH v2] Documentation: filesystems: convert fuse to RST

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20191219095356.4a3ad965@lwn.net>
Date:   Thu, 19 Dec 2019 09:53:56 -0700
From:   Jonathan Corbet <corbet@....net>
To:     "Daniel W. S. Almeida" <dwlsalmeida@...il.com>
Cc:     miklos@...redi.hu, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, skhan@...uxfoundation.org,
        linux-kernel-mentees@...ts.linuxfoundation.org,
        linux-fsdevel@...r.kernel.org
Subject: Re: [PATCH v2] Documentation: filesystems: convert fuse to RST

On Wed, 20 Nov 2019 16:26:55 -0300
"Daniel W. S. Almeida" <dwlsalmeida@...il.com> wrote:

> From: "Daniel W. S. Almeida" <dwlsalmeida@...il.com>
> 
> 
> Converts fuse.txt to reStructuredText format, improving the presentation
> without changing much of the underlying content.
> 
> Signed-off-by: Daniel W. S. Almeida <dwlsalmeida@...il.com>
> -----------------------------------------------------------
> Changes in v2:
> -Copied FUSE maintainer (Miklos Szeredi)
> -Fixed the reference in the MAINTAINERS file
> -Removed some of the excessive markup in fuse.rst
> -Moved fuse.rst into admin-guide
> -Updated index.rst

So I have to confess that I've lost track of where we stand with this.
Holidays and moving house will do that...apologies.  In any case, I have a
couple of additional comments.

[...]

> -There's a control filesystem for FUSE, which can be mounted by:
> +There's a control filesystem for FUSE, which can be mounted by: ::
>  
>    mount -t fusectl none /sys/fs/fuse/connections

Please just do "...can be mounted by::"; it will do what you want.

> -Mounting it under the '/sys/fs/fuse/connections' directory makes it
> +Mounting it under the ``'/sys/fs/fuse/connections'`` directory makes it

There's still a lot of extra markup, and this seems like *way* too many
quotes... 

> -INTERRUPT requests take precedence over other requests, so the
> +*INTERRUPT* requests take precedence over other requests, so the
>  userspace filesystem will receive queued INTERRUPTs before any others.

Not sure you need to add that markup either, but beyond that...

> -The userspace filesystem may ignore the INTERRUPT requests entirely,
> -or may honor them by sending a reply to the _original_ request, with
> -the error set to EINTR.
> +The userspace filesystem may ignore the *INTERRUPT* requests entirely,
> +or may honor them by sending a reply to the *original* request, with
> +the error set to ``EINTR``.
>  
>  It is also possible that there's a race between processing the
>  original request and its INTERRUPT request.  There are two possibilities:
>  
> -  1) The INTERRUPT request is processed before the original request is
> +  #. The *INTERRUPT* request is processed before the original request is
>       processed
>  
> -  2) The INTERRUPT request is processed after the original request has
> +  #. The *INTERRUPT* request is processed after the original request has
>       been answered
>  
>  If the filesystem cannot find the original request, it should wait for
>  some timeout and/or a number of new requests to arrive, after which it
> -should reply to the INTERRUPT request with an EAGAIN error.  In case
> -1) the INTERRUPT request will be requeued.  In case 2) the INTERRUPT
> +should reply to the INTERRUPT request with an ``EAGAIN`` error.  In case
> +1) the ``INTERRUPT`` request will be requeued.  In case 2) the ``INTERRUPT``
>  reply will be ignored.

Here you are marking up the same term in a different way.  That can only
create confusion, which is generally not the goal for the docs.

Please make another pass and try to get the markup down to a minimum;
remember that the plain-text reading experience matters too.

Thanks,

jon