Re: [RFC PATCH] docs: filesystems: convert autofs.txt to reST

From: Ian Kent <raven@themaw.net>
To: Jonathan Corbet <corbet@lwn.net>,
	Jaskaran Singh <jaskaransingh7654321@gmail.com>
Cc: akpm@linux-foundation.org, mchehab+samsung@kernel.org,
	christian@brauner.io, neilb@suse.com, mszeredi@redhat.com,
	willy@infradead.org, stefanha@redhat.com,
	linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
	skhan@linuxfoundation.org,
	linux-kernel-mentees@lists.linuxfoundation.org
Subject: Re: [RFC PATCH] docs: filesystems: convert autofs.txt to reST
Date: Fri, 15 Nov 2019 08:16:49 +0800	[thread overview]
Message-ID: <1b33820317e577e6b2329b3e37edb9a7bf3b3983.camel@themaw.net> (raw)
In-Reply-To: <20191114093831.2ab8a077@lwn.net>

On Thu, 2019-11-14 at 09:38 -0700, Jonathan Corbet wrote:
> On Wed, 13 Nov 2019 13:08:22 +0530
> Jaskaran Singh <jaskaransingh7654321@gmail.com> wrote:
> 
> Thanks for doing this.  Naturally I have some requests :)
> 
> > This patch converts autofs.txt to reST.
> 
> Some subsystem maintainers react strongly to changelogs that read
> "this
> patch"; it's best to express things in the imperative form described
> in
> Documentation/process/submitting-patches.rst.
> 
> >  - Most of the changes pertain to reST formatting.
> >  - Some of the code snippets are updated to reflect current source.
> >  - A definition of the autofs packet header has been added in the
> > chapter
> > 	"Communicating with autofs: the event pipe".
> >  - An indentation of an 8 space tab has been added wherever
> > suitable, so
> >    as to maintain consistency.
> >  - Removed indentation of the description of the ioctls which are
> > similar
> >    to the AUTOFS_IOC ioctls, as it does not come out quite right in
> > HTML.
> 
> These seems like good changes, but they are too much for a single
> patch.
> Please split this into multiple patches, separating the formatting
> and
> white-space changes from those that change the text.  That makes it
> much
> easier to review.
> 
> Some nits below.
> 
> > Signed-off-by: Jaskaran Singh <jaskaransingh7654321@gmail.com>
> > ---
> >  .../filesystems/{autofs.txt => autofs.rst}    | 258 ++++++++++--
> > ------
> >  Documentation/filesystems/index.rst           |   1 +
> >  2 files changed, 140 insertions(+), 119 deletions(-)
> >  rename Documentation/filesystems/{autofs.txt => autofs.rst} (77%)
> > 
> > diff --git a/Documentation/filesystems/autofs.txt
> > b/Documentation/filesystems/autofs.rst
> > similarity index 77%
> > rename from Documentation/filesystems/autofs.txt
> > rename to Documentation/filesystems/autofs.rst
> > index 3af38c7fd26d..a130cba76f07 100644
> > --- a/Documentation/filesystems/autofs.txt
> > +++ b/Documentation/filesystems/autofs.rst
> > @@ -1,12 +1,9 @@
> > -<head>
> > -<style> p { max-width:50em} ol, ul {max-width: 40em}</style>
> > -</head>
> 
> Heh, yeah, I'm not sure why that's there, it should definitely go.
> 
> > +=====================
> >  autofs - how it works
> >  =====================
> >  
> >  Purpose
> > --------
> > +=======
> >  
> >  The goal of autofs is to provide on-demand mounting and race free
> >  automatic unmounting of various other filesystems.  This provides
> > two
> > @@ -28,7 +25,7 @@ key advantages:
> >     first accessed a name.
> >  
> >  Context
> > --------
> > +=======
> >  
> >  The "autofs" filesystem module is only one part of an autofs
> > system.
> >  There also needs to be a user-space program which looks up names
> > @@ -43,7 +40,7 @@ filesystem type.  Several "autofs" filesystems
> > can be mounted and they
> >  can each be managed separately, or all managed by the same daemon.
> >  
> >  Content
> > --------
> > +=======
> >  
> >  An autofs filesystem can contain 3 sorts of objects: directories,
> >  symbolic links and mount traps.  Mount traps are directories with
> > @@ -52,7 +49,7 @@ extra properties as described in the next
> > section.
> >  Objects can only be created by the automount daemon: symlinks are
> >  created with a regular `symlink` system call, while directories
> > and
> >  mount traps are created with `mkdir`.  The determination of
> > whether a
> > -directory should be a mount trap or not is quite _ad hoc_, largely
> > for
> > +directory should be a mount trap or not is quite _ad hoc\_,
> > largely for
> 
> Remember that we want to preserve the readability of the plain-text
> document; sprinkling that sort of escape doesn't really
> help.  Recognize
> that what's there now is a sort of informal markup; I'd either fix it
> up or
> take it out.  So "*ad hoc*" or just "ad hoc".
> 
> (Or rephrase it, since this doesn't actually seem to be an
> appropriate use
> of "ad hoc" but that's a separate issue :)
> 
> >  historical reasons, and is determined in part by the
> >  *direct*/*indirect*/*offset* mount options, and the *maxproto*
> > mount option.

Yeah, this whole paragraph is not quite accurate.

For autofs user space the determination of whether these mounts are
trigger mounts (direct or offset mount option) or plain mount point
directories (indirect mount top level sub-directory) is done based
on the user supplied mount map syntax.

For other autofs users, such as systemd, the mount option (direct in
this case) is chosen based on what semantics the user wants.

Ian