linux-kernel - Re: [PATCH v4] 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: <20200110110923.31fc56e5@lwn.net>
Date:   Fri, 10 Jan 2020 11:09:23 -0700
From:   Jonathan Corbet <corbet@....net>
To:     "Daniel W. S. Almeida" <dwlsalmeida@...il.com>
Cc:     miklos@...redi.hu, markus.heiser@...marit.de,
        linux-fsdevel@...r.kernel.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, skhan@...uxfoundation.org,
        linux-kernel-mentees@...ts.linuxfoundation.org
Subject: Re: [PATCH v4] Documentation: filesystems: convert fuse to RST

On Tue, 31 Dec 2019 15:51:10 -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>

So I note that the last non-typo-fix change to this document happened in
2006, which leads me to suspect that it might be just a wee bit out of
date.  Miklos, what's the story here?  Should we put a warning at the top?

Otherwise I really only have one other comment on the conversion...


>  .../filesystems/{fuse.txt => fuse.rst}        | 174 ++++++++----------
>  Documentation/filesystems/index.rst           |   1 +
>  MAINTAINERS                                   |   2 +-
>  3 files changed, 80 insertions(+), 97 deletions(-)
>  rename Documentation/filesystems/{fuse.txt => fuse.rst} (79%)
> 
> diff --git a/Documentation/filesystems/fuse.txt b/Documentation/filesystems/fuse.rst
> similarity index 79%
> rename from Documentation/filesystems/fuse.txt
> rename to Documentation/filesystems/fuse.rst
> index 13af4a49e7db..aa7d6f506b8d 100644
> --- a/Documentation/filesystems/fuse.txt
> +++ b/Documentation/filesystems/fuse.rst
> @@ -1,41 +1,39 @@
> -Definitions
> -~~~~~~~~~~~
> +==============
> +FUSE
> +==============
>  
> -Userspace filesystem:
> +Definitions
> +===========
>  
> +``Userspace filesystem:``
>    A filesystem in which data and metadata are provided by an ordinary
>    userspace process.  The filesystem can be accessed normally through
>    the kernel interface.

I think that ``literal text`` should really only be used for literal text -
something that the user types, function names, etc.  Here you're defining a
term, which is different.  You could use **emphasis** as you have in other
places, but I also honestly think it doesn't need special markup at all.

Thanks,

jon