lkml.org 
[lkml]   [2019]   [Dec]   [19]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH v2] Documentation: filesystems: convert fuse to RST
On Wed, 20 Nov 2019 16:26:55 -0300
"Daniel W. S. Almeida" <dwlsalmeida@gmail.com> wrote:

> From: "Daniel W. S. Almeida" <dwlsalmeida@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@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
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

\
 
 \ /
  Last update: 2019-12-19 17:54    [W:0.076 / U:4.276 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site