[Linux-kernel-mentees] [PATCH v2] Documentation: filesystems: convert fuse to RST
corbet at lwn.net
Thu Dec 19 16:53:56 UTC 2019
On Wed, 20 Nov 2019 16:26:55 -0300
"Daniel W. S. Almeida" <dwlsalmeida at gmail.com> wrote:
> From: "Daniel W. S. Almeida" <dwlsalmeida at gmail.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 at gmail.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
> -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
> - 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.
More information about the Linux-kernel-mentees