[PATCH v2 11/13] docs: filesystems: vfs: Clean up lists

[Tobin C. Harding]

During conversion of txt file to rst format we added a bunch of lists.
To ease the review of that patch the list contents were not changed.  We
do that now as a separate patch.

This patch does not change the contents of the document in any real way,
does whitespace fixes and adds missing periods to list items.

Clean up lists by:

 - Adding missing periods.
 - Correcting the column width.
 - Correcting the indentation.

Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Signed-off-by: Tobin C. Harding <tobin@xxxxxxxxxx>
---
 Documentation/filesystems/vfs.rst | 1114 ++++++++++++++---------------
 1 file changed, 557 insertions(+), 557 deletions(-)

diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index 7ab885de9085..bd8f7891f44b 100644
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -127,34 +127,34 @@ members are defined:
    };
 
 - ``name``: the name of the filesystem type, such as "ext2", "iso9660",
-	"msdos" and so on
+  "msdos" and so on.
 
-- ``fs_flags``: various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.)
+- ``fs_flags``: various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.).
 
-- ``mount``: the method to call when a new instance of this
-	filesystem should be mounted
+- ``mount``: the method to call when a new instance of this filesystem
+  should be mounted.
 
 - ``kill_sb``: the method to call when an instance of this filesystem
-	should be shut down
+  should be shut down.
 
-- ``owner``: for internal VFS use: you should initialize this to THIS_MODULE in
-	most cases.
+- ``owner``: for internal VFS use: you should initialize this to
+  THIS_MODULE in most cases.
 
-- ``next``: for internal VFS use: you should initialize this to NULL
+- ``next``: for internal VFS use: you should initialize this to NULL.
 
-- ``s_lock_key``, ``s_umount_key``: lockdep-specific
+- ``s_lock_key``, ``s_umount_key``: lockdep-specific.
 
 The mount() method has the following arguments:
 
-- ``struct file_system_type *fs_type``: describes the filesystem, partly initialized
-	by the specific filesystem code
+- ``struct file_system_type *fs_type``: describes the filesystem, partly
+  initialized by the specific filesystem code.
 
-- ``int flags``: mount flags
+- ``int flags``: mount flags.
 
 - ``const char *dev_name``: the device name we are mounting.
 
 - ``void *data``: arbitrary mount options, usually comes as an ASCII
-	string (see "Mount Options" section)
+  string (see "Mount Options" section)
 
 The mount() method must return the root dentry of the tree requested by
 caller.  An active reference to its superblock must be grabbed and the
@@ -179,22 +179,22 @@ implementation.
 Usually, a filesystem uses one of the generic mount() implementations
 and provides a fill_super() callback instead.  The generic variants are:
 
-- ``mount_bdev``: mount a filesystem residing on a block device
+- ``mount_bdev``: mount a filesystem residing on a block device.
 
-- ``mount_nodev``: mount a filesystem that is not backed by a device
+- ``mount_nodev``: mount a filesystem that is not backed by a device.
 
 - ``mount_single``: mount a filesystem which shares the instance between
-	all mounts
+  all mounts.
 
 A fill_super() callback implementation has the following arguments:
 
 - ``struct super_block *sb``: the superblock structure.  The callback
-	must initialize this properly.
+  must initialize this properly.
 
 - ``void *data``: arbitrary mount options, usually comes as an ASCII
-	string (see "Mount Options" section)
+  string (see "Mount Options" section).
 
-- ``int silent``: whether or not to be silent on error
+- ``int silent``: whether or not to be silent on error.
 
 
 The Superblock Object
@@ -240,87 +240,87 @@ noted.  This means that most methods can block safely.  All methods are
 only called from a process context (i.e. not from an interrupt handler
 or bottom half).
 
-- ``alloc_inode``: this method is called by alloc_inode() to allocate memory
-	for struct inode and initialize it.  If this function is not
-	defined, a simple 'struct inode' is allocated.  Normally
-	alloc_inode will be used to allocate a larger structure which
-	contains a 'struct inode' embedded within it.
+- ``alloc_inode``: this method is called by alloc_inode() to allocate
+  memory for struct inode and initialize it.  If this function is not
+  defined, a simple 'struct inode' is allocated.  Normally alloc_inode
+  will be used to allocate a larger structure which contains a 'struct
+  inode' embedded within it.
 
 - ``destroy_inode``: this method is called by destroy_inode() to release
-	resources allocated for struct inode.  It is only required if
-	->alloc_inode was defined and simply undoes anything done by
-	->alloc_inode.
+  resources allocated for struct inode.  It is only required if
+  ->alloc_inode was defined and simply undoes anything done by
+  ->alloc_inode.
 
-- ``dirty_inode``: this method is called by the VFS to mark an inode dirty.
+- ``dirty_inode``: this method is called by the VFS to mark an inode
+  dirty.
 
 - ``write_inode``: this method is called when the VFS needs to write an
-	inode to disc.  The second parameter indicates whether the write
-	should be synchronous or not, not all filesystems check this flag.
+  inode to disc.  The second parameter indicates whether the write
+  should be synchronous or not, not all filesystems check this flag.
 
 - ``drop_inode``: called when the last access to the inode is dropped,
-	with the inode->i_lock spinlock held.
+  with the inode->i_lock spinlock held.
 
-	This method should be either NULL (normal UNIX filesystem
-	semantics) or "generic_delete_inode" (for filesystems that do not
-	want to cache inodes - causing "delete_inode" to always be
-	called regardless of the value of i_nlink)
+  This method should be either NULL (normal UNIX filesystem semantics)
+  or "generic_delete_inode" (for filesystems that do not want to cache
+  inodes - causing "delete_inode" to always be called regardless of the
+  value of i_nlink).
 
-	The "generic_delete_inode()" behavior is equivalent to the
-	old practice of using "force_delete" in the put_inode() case,
-	but does not have the races that the "force_delete()" approach
-	had. 
+  The "generic_delete_inode()" behavior is equivalent to the old
+  practice of using "force_delete" in the put_inode() case, but does not
+  have the races that the "force_delete()" approach had.
 
-- ``delete_inode``: called when the VFS wants to delete an inode
+- ``delete_inode``: called when the VFS wants to delete an inode.
 
 - ``put_super``: called when the VFS wishes to free the superblock
-	(i.e. unmount).  This is called with the superblock lock held
+  (i.e. unmount).  This is called with the superblock lock held.
 
-- ``sync_fs``: called when VFS is writing out all dirty data associated with
-	a superblock.  The second parameter indicates whether the method
-	should wait until the write out has been completed.  Optional.
+- ``sync_fs``: called when VFS is writing out all dirty data associated
+  with a superblock.  The second parameter indicates whether the method
+  should wait until the write out has been completed.  Optional.
 
-- ``freeze_fs``: called when VFS is locking a filesystem and
-	forcing it into a consistent state.  This method is currently
-	used by the Logical Volume Manager (LVM).
+- ``freeze_fs``: called when VFS is locking a filesystem and forcing it
+  into a consistent state.  This method is currently used by the Logical
+  Volume Manager (LVM).
 
-- ``unfreeze_fs``: called when VFS is unlocking a filesystem and making it writable
-	again.
+- ``unfreeze_fs``: called when VFS is unlocking a filesystem and making
+  it writable again.
 
 - ``statfs``: called when the VFS needs to get filesystem statistics.
 
-- ``remount_fs``: called when the filesystem is remounted.  This is called
-	with the kernel lock held
+- ``remount_fs``: called when the filesystem is remounted.  This is
+  called with the kernel lock held.
 
-- ``clear_inode``: called then the VFS clears the inode.  Optional
+- ``clear_inode``: called then the VFS clears the inode.  Optional.
 
 - ``umount_begin``: called when the VFS is unmounting a filesystem.
 
 - ``show_options``: called by the VFS to show mount options for
-	/proc/<pid>/mounts.  (see "Mount Options" section)
+  /proc/<pid>/mounts (see "Mount Options" section).
 
 - ``quota_read``: called by the VFS to read from filesystem quota file.
 
 - ``quota_write``: called by the VFS to write to filesystem quota file.
 
-- ``nr_cached_objects``: called by the sb cache shrinking function for the
-	filesystem to return the number of freeable cached objects it contains.
-	Optional.
+- ``nr_cached_objects``: called by the sb cache shrinking function for
+  the filesystem to return the number of freeable cached objects it
+  contains.  Optional.
 
-- ``free_cache_objects``: called by the sb cache shrinking function for the
-	filesystem to scan the number of objects indicated to try to free them.
-	Optional, but any filesystem implementing this method needs to also
-	implement ->nr_cached_objects for it to be called correctly.
+- ``free_cache_objects``: called by the sb cache shrinking function for
+  the filesystem to scan the number of objects indicated to try to free
+  them.  Optional, but any filesystem implementing this method needs to
+  also implement ->nr_cached_objects for it to be called correctly.
 
-	We can't do anything with any errors that the filesystem might
-	encountered, hence the void return type.  This will never be called if
-	the VM is trying to reclaim under GFP_NOFS conditions, hence this
-	method does not need to handle that situation itself.
+  We can't do anything with any errors that the filesystem might
+  encountered, hence the void return type.  This will never be called if
+  the VM is trying to reclaim under GFP_NOFS conditions, hence this
+  method does not need to handle that situation itself.
 
-	Implementations must include conditional reschedule calls inside any
-	scanning loop that is done.  This allows the VFS to determine
-	appropriate scan batch sizes without having to worry about whether
-	implementations will cause holdoff problems due to large scan batch
-	sizes.
+  Implementations must include conditional reschedule calls inside any
+  scanning loop that is done.  This allows the VFS to determine
+  appropriate scan batch sizes without having to worry about whether
+  implementations will cause holdoff problems due to large scan batch
+  sizes.
 
 Whoever sets up the inode is responsible for filling in the "i_op"
 field.  This is a pointer to a "struct inode_operations" which describes
@@ -334,23 +334,24 @@ On filesystems that support extended attributes (xattrs), the s_xattr
 superblock field points to a NULL-terminated array of xattr handlers.
 Extended attributes are name:value pairs.
 
-- ``name``: Indicates that the handler matches attributes with the specified name
-	(such as "system.posix_acl_access"); the prefix field must be NULL.
+- ``name``: Indicates that the handler matches attributes with the
+  specified name (such as "system.posix_acl_access"); the prefix field
+  must be NULL.
 
-- ``prefix``: Indicates that the handler matches all attributes with the specified
-	name prefix (such as "user."); the name field must be NULL.
+- ``prefix``: Indicates that the handler matches all attributes with the
+  specified name prefix (such as "user."); the name field must be NULL.
 
-- ``list``: Determine if attributes matching this xattr handler should be listed
-	for a particular dentry.  Used by some listxattr implementations like
-	generic_listxattr.
+- ``list``: Determine if attributes matching this xattr handler should
+  be listed for a particular dentry.  Used by some listxattr
+  implementations like generic_listxattr.
 
-- ``get``: Called by the VFS to get the value of a particular extended attribute.
-	This method is called by the getxattr(2) system call.
+- ``get``: Called by the VFS to get the value of a particular extended
+  attribute.  This method is called by the getxattr(2) system call.
 
-- ``set``: Called by the VFS to set the value of a particular extended attribute.
-	When the new value is NULL, called to remove a particular extended
-	attribute.  This method is called by the the setxattr(2) and
-	removexattr(2) system calls.
+- ``set``: Called by the VFS to set the value of a particular extended
+  attribute.  When the new value is NULL, called to remove a particular
+  extended attribute.  This method is called by the the setxattr(2) and
+  removexattr(2) system calls.
 
 When none of the xattr handlers of a filesystem match the specified
 attribute name or when a filesystem doesn't support extended attributes,
@@ -400,120 +401,118 @@ Again, all methods are called without any locks being held, unless
 otherwise noted.
 
 - ``create``: called by the open(2) and creat(2) system calls.  Only
-	required if you want to support regular files.  The dentry you
-	get should not have an inode (i.e. it should be a negative
-	dentry).  Here you will probably call d_instantiate() with the
-	dentry and the newly created inode
+  required if you want to support regular files.  The dentry you get
+  should not have an inode (i.e. it should be a negative dentry).  Here
+  you will probably call d_instantiate() with the dentry and the newly
+  created inode.
 
 - ``lookup``: called when the VFS needs to look up an inode in a parent
-	directory.  The name to look for is found in the dentry.  This
-	method must call d_add() to insert the found inode into the
-	dentry.  The "i_count" field in the inode structure should be
-	incremented.  If the named inode does not exist a NULL inode
-	should be inserted into the dentry (this is called a negative
-	dentry).  Returning an error code from this routine must only
-	be done on a real error, otherwise creating inodes with system
-	calls like create(2), mknod(2), mkdir(2) and so on will fail.
-	If you wish to overload the dentry methods then you should
-	initialise the "d_dop" field in the dentry; this is a pointer
-	to a struct "dentry_operations".
-	This method is called with the directory inode semaphore held
-
-- ``link``: called by the link(2) system call.  Only required if you want
-	to support hard links.  You will probably need to call
-	d_instantiate() just as you would in the create() method
+  directory.  The name to look for is found in the dentry.  This method
+  must call d_add() to insert the found inode into the dentry.  The
+  "i_count" field in the inode structure should be incremented.  If the
+  named inode does not exist a NULL inode should be inserted into the
+  dentry (this is called a negative dentry).  Returning an error code
+  from this routine must only be done on a real error, otherwise
+  creating inodes with system calls like create(2), mknod(2), mkdir(2)
+  and so on will fail.  If you wish to overload the dentry methods then
+  you should initialise the "d_dop" field in the dentry; this is a
+  pointer to a struct "dentry_operations".  This method is called with
+  the directory inode semaphore held.
+
+- ``link``: called by the link(2) system call.  Only required if you
+  want to support hard links.  You will probably need to call
+  d_instantiate() just as you would in the create() method.
 
 - ``unlink``: called by the unlink(2) system call.  Only required if you
-	want to support deleting inodes
-
-- ``symlink``: called by the symlink(2) system call.  Only required if you
-	want to support symlinks.  You will probably need to call
-	d_instantiate() just as you would in the create() method
-
-- ``mkdir``: called by the mkdir(2) system call.  Only required if you want
-	to support creating subdirectories.  You will probably need to
-	call d_instantiate() just as you would in the create() method
-
-- ``rmdir``: called by the rmdir(2) system call.  Only required if you want
-	to support deleting subdirectories
-
-- ``mknod``: called by the mknod(2) system call to create a device (char,
-	block) inode or a named pipe (FIFO) or socket.  Only required
-	if you want to support creating these types of inodes.  You
-	will probably need to call d_instantiate() just as you would
-	in the create() method
-
-- ``rename``: called by the rename(2) system call to rename the object to
-	have the parent and name given by the second inode and dentry.
-
-	The filesystem must return -EINVAL for any unsupported or
-	unknown	flags.  Currently the following flags are implemented:
-	(1) RENAME_NOREPLACE: this flag indicates that if the target
-	of the rename exists the rename should fail with -EEXIST
-	instead of replacing the target.  The VFS already checks for
-	existence, so for local filesystems the RENAME_NOREPLACE
-	implementation is equivalent to plain rename.
-	(2) RENAME_EXCHANGE: exchange source and target.  Both must
-	exist; this is checked by the VFS.  Unlike plain rename,
-	source and target may be of different type.
-
-- ``get_link``: called by the VFS to follow a symbolic link to the
-	inode it points to.  Only required if you want to support
-	symbolic links.  This method returns the symlink body
-	to traverse (and possibly resets the current position with
-	nd_jump_link()).  If the body won't go away until the inode
-	is gone, nothing else is needed; if it needs to be otherwise
-	pinned, arrange for its release by having get_link(..., ..., done)
-	do set_delayed_call(done, destructor, argument).
-	In that case destructor(argument) will be called once VFS is
-	done with the body you've returned.
-	May be called in RCU mode; that is indicated by NULL dentry
-	argument.  If request can't be handled without leaving RCU mode,
-	have it return ERR_PTR(-ECHILD).
-
-- ``readlink``: this is now just an override for use by readlink(2) for the
-	cases when ->get_link uses nd_jump_link() or object is not in
-	fact a symlink.  Normally filesystems should only implement
-	->get_link for symlinks and readlink(2) will automatically use
-	that.
-
-- ``permission``: called by the VFS to check for access rights on a POSIX-like
-	filesystem.
-
-	May be called in rcu-walk mode (mask & MAY_NOT_BLOCK).  If in rcu-walk
-        mode, the filesystem must check the permission without blocking or
-	storing to the inode.
-
-	If a situation is encountered that rcu-walk cannot handle, return
-	-ECHILD and it will be called again in ref-walk mode.
-
-- ``setattr``: called by the VFS to set attributes for a file.  This method
-	is called by chmod(2) and related system calls.
-
-- ``getattr``: called by the VFS to get attributes of a file.  This method
-	is called by stat(2) and related system calls.
+  want to support deleting inodes.
+
+- ``symlink``: called by the symlink(2) system call.  Only required if
+  you want to support symlinks.  You will probably need to call
+  d_instantiate() just as you would in the create() method.
+
+- ``mkdir``: called by the mkdir(2) system call.  Only required if you
+  want to support creating subdirectories.  You will probably need to
+  call d_instantiate() just as you would in the create() method.
+
+- ``rmdir``: called by the rmdir(2) system call.  Only required if you
+  want to support deleting subdirectories.
+
+- ``mknod``: called by the mknod(2) system call to create a device
+  (char, block) inode or a named pipe (FIFO) or socket.  Only required
+  if you want to support creating these types of inodes.  You will
+  probably need to call d_instantiate() just as you would in the
+  create() method.
+
+- ``rename``: called by the rename(2) system call to rename the object
+  to have the parent and name given by the second inode and dentry.
+
+  The filesystem must return -EINVAL for any unsupported or unknown
+  flags.  Currently the following flags are implemented:
+
+  1. ``RENAME_NOREPLACE``: this flag indicates that if the target of the
+     rename exists the rename should fail with -EEXIST instead of
+     replacing the target.  The VFS already checks for existence, so for
+     local filesystems the RENAME_NOREPLACE implementation is equivalent
+     to plain rename.
+  2. ``RENAME_EXCHANGE``: exchange source and target.  Both must exist;
+     this is checked by the VFS.  Unlike plain rename, source and target
+     may be of different type.
+
+- ``get_link``: called by the VFS to follow a symbolic link to the inode
+  it points to.  Only required if you want to support symbolic links.
+  This method returns the symlink body to traverse (and possibly resets
+  the current position with nd_jump_link()).  If the body won't go away
+  until the inode is gone, nothing else is needed; if it needs to be
+  otherwise pinned, arrange for its release by having get_link(..., ...,
+  done) do set_delayed_call(done, destructor, argument).  In that case
+  destructor(argument) will be called once VFS is done with the body
+  you've returned.  May be called in RCU mode; that is indicated by NULL
+  dentry argument.  If request can't be handled without leaving RCU
+  mode, have it return ERR_PTR(-ECHILD).
+
+- ``readlink``: this is now just an override for use by readlink(2) for
+  the cases when ->get_link uses nd_jump_link() or object is not in fact
+  a symlink.  Normally filesystems should only implement ->get_link for
+  symlinks and readlink(2) will automatically use that.
+
+- ``permission``: called by the VFS to check for access rights on a
+  POSIX-like filesystem.
+
+  May be called in rcu-walk mode (mask & MAY_NOT_BLOCK).  If in rcu-walk
+  mode, the filesystem must check the permission without blocking or
+  storing to the inode.
+
+  If a situation is encountered that rcu-walk cannot handle, return
+  -ECHILD and it will be called again in ref-walk mode.
+
+- ``setattr``: called by the VFS to set attributes for a file.  This
+  method is called by chmod(2) and related system calls.
+
+- ``getattr``: called by the VFS to get attributes of a file.  This
+  method is called by stat(2) and related system calls.
 
 - ``listxattr``: called by the VFS to list all extended attributes for a
-	given file.  This method is called by the listxattr(2) system call.
+  given file.  This method is called by the listxattr(2) system call.
 
-- ``update_time``: called by the VFS to update a specific time or the i_version of
-	an inode.  If this is not defined the VFS will update the inode itself
-	and call mark_inode_dirty_sync.
+- ``update_time``: called by the VFS to update a specific time or the
+  i_version of an inode.  If this is not defined the VFS will update the
+  inode itself and call mark_inode_dirty_sync.
 
-- ``atomic_open``: called on the last component of an open.  Using this optional
-	method the filesystem can look up, possibly create and open the file in
-	one atomic operation.  If it wants to leave actual opening to the
-	caller (e.g. if the file turned out to be a symlink, device, or just
-	something filesystem won't do atomic open for), it may signal this by
-	returning finish_no_open(file, dentry).  This method is only called if
-	the last component is negative or needs lookup.  Cached positive dentries
-	are still handled by f_op->open().  If the file was created,
-	FMODE_CREATED flag should be set in file->f_mode.  In case of O_EXCL
-	the method must only succeed if the file didn't exist and hence FMODE_CREATED
-	shall always be set on success.
+- ``atomic_open``: called on the last component of an open.  Using this
+  optional method the filesystem can look up, possibly create and open
+  the file in one atomic operation.  If it wants to leave actual opening
+  to the caller (e.g. if the file turned out to be a symlink, device, or
+  just something filesystem won't do atomic open for), it may signal
+  this by returning finish_no_open(file, dentry).  This method is only
+  called if the last component is negative or needs lookup.  Cached
+  positive dentries are still handled by f_op->open().  If the file was
+  created, FMODE_CREATED flag should be set in file->f_mode.  In case of
+  O_EXCL the method must only succeed if the file didn't exist and hence
+  FMODE_CREATED shall always be set on success.
 
-- ``tmpfile``: called in the end of O_TMPFILE open().  Optional, equivalent to
-	atomically creating, opening and unlinking a file in given directory.
+- ``tmpfile``: called in the end of O_TMPFILE open().  Optional,
+  equivalent to atomically creating, opening and unlinking a file in
+  given directory.
 
 
 The Address Space Object
@@ -666,185 +665,180 @@ cache in your filesystem.  The following members are defined:
 	   int (*swap_deactivate)(struct file *);
    };
 
-- ``writepage``: called by the VM to write a dirty page to backing store.
-      This may happen for data integrity reasons (i.e. 'sync'), or
-      to free up memory (flush).  The difference can be seen in
-      wbc->sync_mode.
-      The PG_Dirty flag has been cleared and PageLocked is true.
-      writepage should start writeout, should set PG_Writeback,
-      and should make sure the page is unlocked, either synchronously
-      or asynchronously when the write operation completes.
-
-      If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to
-      try too hard if there are problems, and may choose to write out
-      other pages from the mapping if that is easier (e.g. due to
-      internal dependencies).  If it chooses not to start writeout, it
-      should return AOP_WRITEPAGE_ACTIVATE so that the VM will not keep
-      calling ->writepage on that page.
-
-      See the file "Locking" for more details.
-
-- ``readpage``: called by the VM to read a page from backing store.
-       The page will be Locked when readpage is called, and should be
-       unlocked and marked uptodate once the read completes.
-       If ->readpage discovers that it needs to unlock the page for
-       some reason, it can do so, and then return AOP_TRUNCATED_PAGE.
-       In this case, the page will be relocated, relocked and if
-       that all succeeds, ->readpage will be called again.
-
-- ``writepages``: called by the VM to write out pages associated with the
-	address_space object.  If wbc->sync_mode is WBC_SYNC_ALL, then
-	the writeback_control will specify a range of pages that must be
-	written out.  If it is WBC_SYNC_NONE, then a nr_to_write is given
-	and that many pages should be written if possible.
-	If no ->writepages is given, then mpage_writepages is used
-	instead.  This will choose pages from the address space that are
-	tagged as DIRTY and will pass them to ->writepage.
-
-- ``set_page_dirty``: called by the VM to set a page dirty.
-        This is particularly needed if an address space attaches
-        private data to a page, and that data needs to be updated when
-        a page is dirtied.  This is called, for example, when a memory
-	mapped page gets modified.
-	If defined, it should set the PageDirty flag, and the
-        PAGECACHE_TAG_DIRTY tag in the radix tree.
-
-- ``readpages``: called by the VM to read pages associated with the address_space
-	object.  This is essentially just a vector version of
-	readpage.  Instead of just one page, several pages are
-	requested.
-	readpages is only used for read-ahead, so read errors are
-	ignored.  If anything goes wrong, feel free to give up.
-
-- ``write_begin``:
-	Called by the generic buffered write code to ask the filesystem to
-	prepare to write len bytes at the given offset in the file.  The
-	address_space should check that the write will be able to complete,
-	by allocating space if necessary and doing any other internal
-	housekeeping.  If the write will update parts of any basic-blocks on
-	storage, then those blocks should be pre-read (if they haven't been
-	read already) so that the updated blocks can be written out properly.
-
-        The filesystem must return the locked pagecache page for the specified
-	offset, in *pagep, for the caller to write into.
-
-	It must be able to cope with short writes (where the length passed to
-	write_begin is greater than the number of bytes copied into the page).
-
-	flags is a field for AOP_FLAG_xxx flags, described in
-	include/linux/fs.h.
-
-        A void * may be returned in fsdata, which then gets passed into
-        write_end.
-
-        Returns 0 on success; < 0 on failure (which is the error code), in
-	which case write_end is not called.
-
-- ``write_end``: After a successful write_begin, and data copy, write_end must
-        be called.  len is the original len passed to write_begin, and copied
-        is the amount that was able to be copied.
-
-        The filesystem must take care of unlocking the page and releasing it
-        refcount, and updating i_size.
-
-        Returns < 0 on failure, otherwise the number of bytes (<= 'copied')
-        that were able to be copied into pagecache.
-
-- ``bmap``: called by the VFS to map a logical block offset within object to
-	physical block number.  This method is used by the FIBMAP
-	ioctl and for working with swap-files.  To be able to swap to
-	a file, the file must have a stable mapping to a block
-	device.  The swap system does not go through the filesystem
-	but instead uses bmap to find out where the blocks in the file
-	are and uses those addresses directly.
+- ``writepage``: called by the VM to write a dirty page to backing
+  store.  This may happen for data integrity reasons (i.e. 'sync'), or
+  to free up memory (flush).  The difference can be seen in
+  wbc->sync_mode.  The PG_Dirty flag has been cleared and PageLocked is
+  true.  writepage should start writeout, should set PG_Writeback, and
+  should make sure the page is unlocked, either synchronously or
+  asynchronously when the write operation completes.
+
+  If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to try too
+  hard if there are problems, and may choose to write out other pages
+  from the mapping if that is easier (e.g. due to internal
+  dependencies).  If it chooses not to start writeout, it should return
+  AOP_WRITEPAGE_ACTIVATE so that the VM will not keep calling
+  ->writepage on that page.
+
+  See the file "Locking" for more details.
+
+- ``readpage``: called by the VM to read a page from backing store.  The
+  page will be Locked when readpage is called, and should be unlocked
+  and marked uptodate once the read completes.  If ->readpage discovers
+  that it needs to unlock the page for some reason, it can do so, and
+  then return AOP_TRUNCATED_PAGE.  In this case, the page will be
+  relocated, relocked and if that all succeeds, ->readpage will be
+  called again.
+
+- ``writepages``: called by the VM to write out pages associated with
+  the address_space object.  If wbc->sync_mode is WBC_SYNC_ALL, then the
+  writeback_control will specify a range of pages that must be written
+  out.  If it is WBC_SYNC_NONE, then a nr_to_write is given and that
+  many pages should be written if possible.  If no ->writepages is
+  given, then mpage_writepages is used instead.  This will choose pages
+  from the address space that are tagged as DIRTY and will pass them to
+  ->writepage.
+
+- ``set_page_dirty``: called by the VM to set a page dirty.  This is
+  particularly needed if an address space attaches private data to a
+  page, and that data needs to be updated when a page is dirtied.  This
+  is called, for example, when a memory mapped page gets modified.  If
+  defined, it should set the PageDirty flag, and the PAGECACHE_TAG_DIRTY
+  tag in the radix tree.
+
+- ``readpages``: called by the VM to read pages associated with the
+  address_space object.  This is essentially just a vector version of
+  readpage.  Instead of just one page, several pages are requested.
+  readpages is only used for read-ahead, so read errors are ignored.  If
+  anything goes wrong, feel free to give up.
+
+- ``write_begin``: Called by the generic buffered write code to ask the
+  filesystem to prepare to write len bytes at the given offset in the
+  file.  The address_space should check that the write will be able to
+  complete, by allocating space if necessary and doing any other
+  internal housekeeping.  If the write will update parts of any
+  basic-blocks on storage, then those blocks should be pre-read (if they
+  haven't been read already) so that the updated blocks can be written
+  out properly.
+
+  The filesystem must return the locked pagecache page for the specified
+  offset, in *pagep, for the caller to write into.
+
+  It must be able to cope with short writes (where the length passed to
+  write_begin is greater than the number of bytes copied into the page).
+
+  flags is a field for AOP_FLAG_xxx flags, described in
+  include/linux/fs.h.
+
+  A void * may be returned in fsdata, which then gets passed into
+  write_end.
+
+  Returns 0 on success; < 0 on failure (which is the error code), in
+  which case write_end is not called.
+
+- ``write_end``: After a successful write_begin, and data copy,
+  write_end must be called.  len is the original len passed to
+  write_begin, and copied is the amount that was able to be copied.
+
+  The filesystem must take care of unlocking the page and releasing it
+  refcount, and updating i_size.
+
+  Returns < 0 on failure, otherwise the number of bytes (<= 'copied')
+  that were able to be copied into pagecache.
+
+- ``bmap``: called by the VFS to map a logical block offset within
+  object to physical block number.  This method is used by the FIBMAP
+  ioctl and for working with swap-files.  To be able to swap to a file,
+  the file must have a stable mapping to a block device.  The swap
+  system does not go through the filesystem but instead uses bmap to
+  find out where the blocks in the file are and uses those addresses
+  directly.
 
 - ``invalidatepage``: If a page has PagePrivate set, then invalidatepage
-        will be called when part or all of the page is to be removed
-	from the address space.  This generally corresponds to either a
-	truncation, punch hole  or a complete invalidation of the address
-	space (in the latter case 'offset' will always be 0 and 'length'
-	will be PAGE_SIZE).  Any private data associated with the page
-	should be updated to reflect this truncation.  If offset is 0 and
-	length is PAGE_SIZE, then the private data should be released,
-	because the page must be able to be completely discarded.  This may
-	be done by calling the ->releasepage function, but in this case the
-	release MUST succeed.
-
-- ``releasepage``: releasepage is called on PagePrivate pages to indicate
-        that the page should be freed if possible.  ->releasepage
-        should remove any private data from the page and clear the
-        PagePrivate flag.  If releasepage() fails for some reason, it must
-	indicate failure with a 0 return value.
-	releasepage() is used in two distinct though related cases.  The
-	first is when the VM finds a clean page with no active users and
-        wants to make it a free page.  If ->releasepage succeeds, the
-        page will be removed from the address_space and become free.
-
-	The second case is when a request has been made to invalidate
-        some or all pages in an address_space.  This can happen
-        through the fadvise(POSIX_FADV_DONTNEED) system call or by the
-        filesystem explicitly requesting it as nfs and 9fs do (when
-        they believe the cache may be out of date with storage) by
-        calling invalidate_inode_pages2().
-	If the filesystem makes such a call, and needs to be certain
-        that all pages are invalidated, then its releasepage will
-        need to ensure this.  Possibly it can clear the PageUptodate
-        bit if it cannot free private data yet.
+  will be called when part or all of the page is to be removed from the
+  address space.  This generally corresponds to either a truncation,
+  punch hole or a complete invalidation of the address space (in the
+  latter case 'offset' will always be 0 and 'length' will be PAGE_SIZE).
+  Any private data associated with the page should be updated to reflect
+  this truncation.  If offset is 0 and length is PAGE_SIZE, then the
+  private data should be released, because the page must be able to be
+  completely discarded.  This may be done by calling the ->releasepage
+  function, but in this case the release MUST succeed.
+
+- ``releasepage``: releasepage is called on PagePrivate pages to
+  indicate that the page should be freed if possible.  ->releasepage
+  should remove any private data from the page and clear the PagePrivate
+  flag.  If releasepage() fails for some reason, it must indicate
+  failure with a 0 return value.  releasepage() is used in two distinct
+  though related cases.  The first is when the VM finds a clean page
+  with no active users and wants to make it a free page.  If
+  ->releasepage succeeds, the page will be removed from the
+  address_space and become free.
+
+  The second case is when a request has been made to invalidate some or
+  all pages in an address_space.  This can happen through the
+  fadvise(POSIX_FADV_DONTNEED) system call or by the filesystem
+  explicitly requesting it as nfs and 9fs do (when they believe the
+  cache may be out of date with storage) by calling
+  invalidate_inode_pages2().  If the filesystem makes such a call, and
+  needs to be certain that all pages are invalidated, then its
+  releasepage will need to ensure this.  Possibly it can clear the
+  PageUptodate bit if it cannot free private data yet.
 
 - ``freepage``: freepage is called once the page is no longer visible in
-        the page cache in order to allow the cleanup of any private
-	data.  Since it may be called by the memory reclaimer, it
-	should not assume that the original address_space mapping still
-	exists, and it should not block.
+  the page cache in order to allow the cleanup of any private data.
+  Since it may be called by the memory reclaimer, it should not assume
+  that the original address_space mapping still exists, and it should
+  not block.
 
 - ``direct_IO``: called by the generic read/write routines to perform
-        direct_IO - that is IO requests which bypass the page cache
-        and transfer data directly between the storage and the
-        application's address space.
-
-- ``isolate_page``: Called by the VM when isolating a movable non-lru page.
-	If page is successfully isolated, VM marks the page as PG_isolated
-	via __SetPageIsolated.
-
-- ``migrate_page``:  This is used to compact the physical memory usage.
-        If the VM wants to relocate a page (maybe off a memory card
-        that is signalling imminent failure) it will pass a new page
-	and an old page to this function.  migrate_page should
-	transfer any private data across and update any references
-        that it has to the page.
-
-- ``putback_page``: Called by the VM when isolated page's migration fails.
-
-- ``launder_page``: Called before freeing a page - it writes back the dirty page.  To
-	prevent redirtying the page, it is kept locked during the whole
-	operation.
-
-- ``is_partially_uptodate``: Called by the VM when reading a file through the
-	pagecache when the underlying blocksize != pagesize.  If the required
-	block is up to date then the read can complete without needing the IO
-	to bring the whole page up to date.
-
-- ``is_dirty_writeback``: Called by the VM when attempting to reclaim a page.
-	The VM uses dirty and writeback information to determine if it needs
-	to stall to allow flushers a chance to complete some IO.  Ordinarily
-	it can use PageDirty and PageWriteback but some filesystems have
-	more complex state (unstable pages in NFS prevent reclaim) or
-	do not set those flags due to locking problems.  This callback
-	allows a filesystem to indicate to the VM if a page should be
-	treated as dirty or writeback for the purposes of stalling.
-
-- ``error_remove_page``: normally set to generic_error_remove_page if truncation
-	is ok for this address space.  Used for memory failure handling.
-	Setting this implies you deal with pages going away under you,
-	unless you have them locked or reference counts increased.
+  direct_IO - that is IO requests which bypass the page cache and
+  transfer data directly between the storage and the application's
+  address space.
+
+- ``isolate_page``: Called by the VM when isolating a movable non-lru
+  page.  If page is successfully isolated, VM marks the page as
+  PG_isolated via __SetPageIsolated.
+
+- ``migrate_page``: This is used to compact the physical memory usage.
+  If the VM wants to relocate a page (maybe off a memory card that is
+  signalling imminent failure) it will pass a new page and an old page
+  to this function.  migrate_page should transfer any private data
+  across and update any references that it has to the page.
+
+- ``putback_page``: Called by the VM when isolated page's migration
+  fails.
+
+- ``launder_page``: Called before freeing a page - it writes back the
+  dirty page.  To prevent redirtying the page, it is kept locked during
+  the whole operation.
+
+- ``is_partially_uptodate``: Called by the VM when reading a file
+  through the pagecache when the underlying blocksize != pagesize.  If
+  the required block is up to date then the read can complete without
+  needing the IO to bring the whole page up to date.
+
+- ``is_dirty_writeback``: Called by the VM when attempting to reclaim a
+  page.  The VM uses dirty and writeback information to determine if it
+  needs to stall to allow flushers a chance to complete some IO.
+  Ordinarily it can use PageDirty and PageWriteback but some filesystems
+  have more complex state (unstable pages in NFS prevent reclaim) or do
+  not set those flags due to locking problems.  This callback allows a
+  filesystem to indicate to the VM if a page should be treated as dirty
+  or writeback for the purposes of stalling.
+
+- ``error_remove_page``: normally set to generic_error_remove_page if
+  truncation is ok for this address space.  Used for memory failure
+  handling.  Setting this implies you deal with pages going away under
+  you, unless you have them locked or reference counts increased.
 
 - ``swap_activate``: Called when swapon is used on a file to allocate
-	space if necessary and pin the block lookup information in
-	memory.  A return value of zero indicates success,
-	in which case this file can be used to back swapspace.
+  space if necessary and pin the block lookup information in memory.  A
+  return value of zero indicates success, in which case this file can be
+  used to back swapspace.
 
-- ``swap_deactivate``: Called during swapoff on files where swap_activate
-	was successful.
+- ``swap_deactivate``: Called during swapoff on files where
+  swap_activate was successful.
 
 
 The File Object
@@ -908,87 +902,93 @@ This describes how the VFS can manipulate an open file.  As of kernel
 Again, all methods are called without any locks being held, unless
 otherwise noted.
 
-- ``llseek``: called when the VFS needs to move the file position index
+- ``llseek``: called when the VFS needs to move the file position index.
 
-- ``read``: called by read(2) and related system calls
+- ``read``: called by read(2) and related system calls.
 
-- ``read_iter``: possibly asynchronous read with iov_iter as destination
+- ``read_iter``: possibly asynchronous read with iov_iter as
+  destination.
 
-- ``write``: called by write(2) and related system calls
+- ``write``: called by write(2) and related system calls.
 
-- ``write_iter``: possibly asynchronous write with iov_iter as source
+- ``write_iter``: possibly asynchronous write with iov_iter as source.
 
--  ``iopoll``: called when aio wants to poll for completions on HIPRI iocbs
+-  ``iopoll``: called when aio wants to poll for completions on HIPRI
+   iocbs.
 
-- ``iterate_shared``: called when the VFS needs to read the directory contents
-	when filesystem supports concurrent dir iterators
+- ``iterate``: called when the VFS needs to read the directory contents.
+
+- ``iterate_shared``: called when the VFS needs to read the directory
+  contents when filesystem supports concurrent dir iterators.
 
 - ``poll``: called by the VFS when a process wants to check if there is
-	activity on this file and (optionally) go to sleep until there
-	is activity.  Called by the select(2) and poll(2) system calls
+  activity on this file and (optionally) go to sleep until there is
+  activity.  Called by the select(2) and poll(2) system calls.
 
 - ``unlocked_ioctl``: called by the ioctl(2) system call.
 
-- ``compat_ioctl``: called by the ioctl(2) system call when 32 bit system calls
-	 are used on 64 bit kernels.
+- ``compat_ioctl``: called by the ioctl(2) system call when 32 bit
+  system calls are used on 64 bit kernels.
 
-- ``mmap``: called by the mmap(2) system call
+- ``mmap``: called by the mmap(2) system call.
 
-- ``open``: called by the VFS when an inode should be opened.  When the VFS
-	opens a file, it creates a new "struct file".  It then calls the
-	open method for the newly allocated file structure.  You might
-	think that the open method really belongs in
-	"struct inode_operations", and you may be right.  I think it's
-	done the way it is because it makes filesystems simpler to
-	implement.  The open() method is a good place to initialize the
-	"private_data" member in the file structure if you want to point
-	to a device structure
+- ``open``: called by the VFS when an inode should be opened.  When the
+  VFS opens a file, it creates a new "struct file".  It then calls the
+  open method for the newly allocated file structure.  You might think
+  that the open method really belongs in "struct inode_operations", and
+  you may be right.  I think it's done the way it is because it makes
+  filesystems simpler to implement.  The open() method is a good place
+  to initialize the "private_data" member in the file structure if you
+  want to point to a device structure.
 
-- ``flush``: called by the close(2) system call to flush a file
+- ``flush``: called by the close(2) system call to flush a file.
 
-- ``release``: called when the last reference to an open file is closed
+- ``release``: called when the last reference to an open file is closed.
 
-- ``fsync``: called by the fsync(2) system call.  Also see the section above
-	 entitled "Handling errors during writeback".
+- ``fsync``: called by the fsync(2) system call.  Also see the section
+  above entitled "Handling errors during writeback".
 
 - ``fasync``: called by the fcntl(2) system call when asynchronous
-	(non-blocking) mode is enabled for a file
+  (non-blocking) mode is enabled for a file.
 
-- ``lock``: called by the fcntl(2) system call for F_GETLK, F_SETLK, and F_SETLKW
-	commands
+- ``lock``: called by the fcntl(2) system call for F_GETLK, F_SETLK, and
+  F_SETLKW commands.
 
-- ``get_unmapped_area``: called by the mmap(2) system call
+- ``get_unmapped_area``: called by the mmap(2) system call.
 
-- ``check_flags``: called by the fcntl(2) system call for F_SETFL command
+- ``check_flags``: called by the fcntl(2) system call for F_SETFL
+  command.
 
-- ``flock``: called by the flock(2) system call
+- ``flock``: called by the flock(2) system call.
 
-- ``splice_write``: called by the VFS to splice data from a pipe to a file.  This
-		method is used by the splice(2) system call
+- ``splice_write``: called by the VFS to splice data from a pipe to a
+  file.  This method is used by the splice(2) system call.
 
-- ``splice_read``: called by the VFS to splice data from file to a pipe.  This
-	       method is used by the splice(2) system call
+- ``splice_read``: called by the VFS to splice data from file to a pipe.
+  This method is used by the splice(2) system call
 
-- ``setlease``: called by the VFS to set or release a file lock lease.  setlease
-	    implementations should call generic_setlease to record or remove
-	    the lease in the inode after setting it.
+- ``setlease``: called by the VFS to set or release a file lock lease.
+  setlease implementations should call generic_setlease to record or
+  remove the lease in the inode after setting it.
 
-- ``fallocate``: called by the VFS to preallocate blocks or punch a hole.
+- ``fallocate``: called by the VFS to preallocate blocks or punch a
+  hole.
 
 - ``copy_file_range``: called by the copy_file_range(2) system call.
 
-- ``remap_file_range``: called by the ioctl(2) system call for FICLONERANGE and
-	FICLONE and FIDEDUPERANGE commands to remap file ranges.  An
-	implementation should remap len bytes at pos_in of the source file into
-	the dest file at pos_out.  Implementations must handle callers passing
-	in len == 0; this means "remap to the end of the source file".  The
-	return value should the number of bytes remapped, or the usual
-	negative error code if errors occurred before any bytes were remapped.
-	The remap_flags parameter accepts REMAP_FILE_* flags.  If
-	REMAP_FILE_DEDUP is set then the implementation must only remap if the
-	requested file ranges have identical contents.  If REMAP_CAN_SHORTEN is
-	set, the caller is ok with the implementation shortening the request
-	length to satisfy alignment or EOF requirements (or any other reason).
+- ``remap_file_range``: called by the ioctl(2) system call for
+  FICLONERANGE and FICLONE and FIDEDUPERANGE commands to remap file
+  ranges.  An implementation should remap len bytes at pos_in of the
+  source file into the dest file at pos_out.  Implementations must
+  handle callers passing in len == 0; this means "remap to the end of
+  the source file".  The return value should the number of bytes
+  remapped, or the usual negative error code if errors occurred before
+  any bytes were remapped.  The remap_flags parameter accepts
+  REMAP_FILE_* flags.  If REMAP_FILE_DEDUP is set then the
+  implementation must only remap if the requested file ranges have
+  identical contents.  If REMAP_CAN_SHORTEN is set, the caller is ok
+  with the implementation shortening the request length to satisfy
+  alignment or EOF requirements (or any other reason).
 
 - ``fadvise``: possibly called by the fadvise64() system call.
 
@@ -1035,146 +1035,147 @@ defined:
 	   struct dentry *(*d_real)(struct dentry *, const struct inode *);
    };
 
-- ``d_revalidate``: called when the VFS needs to revalidate a dentry.  This
-	is called whenever a name look-up finds a dentry in the
-	dcache.  Most local filesystems leave this as NULL, because all their
-	dentries in the dcache are valid.  Network filesystems are different
-	since things can change on the server without the client necessarily
-	being aware of it.
+- ``d_revalidate``: called when the VFS needs to revalidate a dentry.
+  This is called whenever a name look-up finds a dentry in the dcache.
+  Most local filesystems leave this as NULL, because all their dentries
+  in the dcache are valid.  Network filesystems are different since
+  things can change on the server without the client necessarily being
+  aware of it.
 
-	This function should return a positive value if the dentry is still
-	valid, and zero or a negative error code if it isn't.
+  This function should return a positive value if the dentry is still
+  valid, and zero or a negative error code if it isn't.
 
-	d_revalidate may be called in rcu-walk mode (flags & LOOKUP_RCU).
-	If in rcu-walk mode, the filesystem must revalidate the dentry without
-	blocking or storing to the dentry, d_parent and d_inode should not be
-	used without care (because they can change and, in d_inode case, even
-	become NULL under us).
+  d_revalidate may be called in rcu-walk mode (flags & LOOKUP_RCU).  If
+  in rcu-walk mode, the filesystem must revalidate the dentry without
+  blocking or storing to the dentry, d_parent and d_inode should not be
+  used without care (because they can change and, in d_inode case, even
+  become NULL under us).
 
-	If a situation is encountered that rcu-walk cannot handle, return
-	-ECHILD and it will be called again in ref-walk mode.
+  If a situation is encountered that rcu-walk cannot handle, return
+  -ECHILD and it will be called again in ref-walk mode.
 
-- ``d_weak_revalidate``: called when the VFS needs to revalidate a "jumped" dentry.
-	This is called when a path-walk ends at dentry that was not acquired by
-	doing a lookup in the parent directory.  This includes "/", "." and "..",
-	as well as procfs-style symlinks and mountpoint traversal.
+- ``d_weak_revalidate``: called when the VFS needs to revalidate a
+  "jumped" dentry.  This is called when a path-walk ends at dentry that
+  was not acquired by doing a lookup in the parent directory.  This
+  includes "/", "." and "..", as well as procfs-style symlinks and
+  mountpoint traversal.
 
-	In this case, we are less concerned with whether the dentry is still
-	fully correct, but rather that the inode is still valid.  As with
-	d_revalidate, most local filesystems will set this to NULL since their
-	dcache entries are always valid.
+  In this case, we are less concerned with whether the dentry is still
+  fully correct, but rather that the inode is still valid.  As with
+  d_revalidate, most local filesystems will set this to NULL since their
+  dcache entries are always valid.
 
-	This function has the same return code semantics as d_revalidate.
+  This function has the same return code semantics as d_revalidate.
 
-	d_weak_revalidate is only called after leaving rcu-walk mode.
+  d_weak_revalidate is only called after leaving rcu-walk mode.
 
-- ``d_hash``: called when the VFS adds a dentry to the hash table.  The first
-	dentry passed to d_hash is the parent directory that the name is
-	to be hashed into.
+- ``d_hash``: called when the VFS adds a dentry to the hash table.  The
+  first dentry passed to d_hash is the parent directory that the name is
+  to be hashed into.
 
-	Same locking and synchronisation rules as d_compare regarding
-	what is safe to dereference etc.
+  Same locking and synchronisation rules as d_compare regarding what is
+  safe to dereference etc.
 
-- ``d_compare``: called to compare a dentry name with a given name.  The first
-	dentry is the parent of the dentry to be compared, the second is
-	the child dentry.  len and name string are properties of the dentry
-	to be compared.  qstr is the name to compare it with.
+- ``d_compare``: called to compare a dentry name with a given name.  The
+  first dentry is the parent of the dentry to be compared, the second is
+  the child dentry.  len and name string are properties of the dentry to
+  be compared.  qstr is the name to compare it with.
 
-	Must be constant and idempotent, and should not take locks if
-	possible, and should not or store into the dentry.
-	Should not dereference pointers outside the dentry without
-	lots of care (eg.  d_parent, d_inode, d_name should not be used).
+  Must be constant and idempotent, and should not take locks if
+  possible, and should not or store into the dentry.  Should not
+  dereference pointers outside the dentry without lots of care (eg.
+  d_parent, d_inode, d_name should not be used).
 
-	However, our vfsmount is pinned, and RCU held, so the dentries and
-	inodes won't disappear, neither will our sb or filesystem module.
-	->d_sb may be used.
+  However, our vfsmount is pinned, and RCU held, so the dentries and
+  inodes won't disappear, neither will our sb or filesystem module.
+  ->d_sb may be used.
 
-	It is a tricky calling convention because it needs to be called under
-	"rcu-walk", ie. without any locks or references on things.
+  It is a tricky calling convention because it needs to be called under
+  "rcu-walk", ie. without any locks or references on things.
 
-- ``d_delete``: called when the last reference to a dentry is dropped and the
-	dcache is deciding whether or not to cache it.  Return 1 to delete
-	immediately, or 0 to cache the dentry.  Default is NULL which means to
-	always cache a reachable dentry.  d_delete must be constant and
-	idempotent.
+- ``d_delete``: called when the last reference to a dentry is dropped
+  and the dcache is deciding whether or not to cache it.  Return 1 to
+  delete immediately, or 0 to cache the dentry.  Default is NULL which
+  means to always cache a reachable dentry.  d_delete must be constant
+  and idempotent.
 
-- ``d_init``: called when a dentry is allocated
+- ``d_init``: called when a dentry is allocated.
 
-- ``d_release``: called when a dentry is really deallocated
+- ``d_release``: called when a dentry is really deallocated.
 
 - ``d_iput``: called when a dentry loses its inode (just prior to its
-	being deallocated).  The default when this is NULL is that the
-	VFS calls iput().  If you define this method, you must call
-	iput() yourself
+  being deallocated).  The default when this is NULL is that the VFS
+  calls iput().  If you define this method, you must call iput()
+  yourself.
 
 - ``d_dname``: called when the pathname of a dentry should be generated.
-	Useful for some pseudo filesystems (sockfs, pipefs, ...) to delay
-	pathname generation.  (Instead of doing it when dentry is created,
-	it's done only when the path is needed.).  Real filesystems probably
-	dont want to use it, because their dentries are present in global
-	dcache hash, so their hash should be an invariant.  As no lock is
-	held, d_dname() should not try to modify the dentry itself, unless
-	appropriate SMP safety is used.  CAUTION : d_path() logic is quite
-	tricky.  The correct way to return for example "Hello" is to put it
-	at the end of the buffer, and returns a pointer to the first char.
-	dynamic_dname() helper function is provided to take care of this.
-
-	.. code-block:: c
-
-	   static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen)
-	   {
-		   return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]",
-					dentry->d_inode->i_ino);
-	   }
-
-- ``d_automount``: called when an automount dentry is to be traversed (optional).
-	This should create a new VFS mount record and return the record to the
-	caller.  The caller is supplied with a path parameter giving the
-	automount directory to describe the automount target and the parent
-	VFS mount record to provide inheritable mount parameters.  NULL should
-	be returned if someone else managed to make the automount first.  If
-	the vfsmount creation failed, then an error code should be returned.
-	If -EISDIR is returned, then the directory will be treated as an
-	ordinary directory and returned to pathwalk to continue walking.
-
-	If a vfsmount is returned, the caller will attempt to mount it on the
-	mountpoint and will remove the vfsmount from its expiration list in
-	the case of failure.  The vfsmount should be returned with 2 refs on
-	it to prevent automatic expiration - the caller will clean up the
-	additional ref.
-
-	This function is only used if DCACHE_NEED_AUTOMOUNT is set on the
-	dentry.  This is set by __d_instantiate() if S_AUTOMOUNT is set on the
-	inode being added.
-
-- ``d_manage``: called to allow the filesystem to manage the transition from a
-	dentry (optional).  This allows autofs, for example, to hold up clients
-	waiting to explore behind a 'mountpoint' while letting the daemon go
-	past and construct the subtree there.  0 should be returned to let the
-	calling process continue.  -EISDIR can be returned to tell pathwalk to
-	use this directory as an ordinary directory and to ignore anything
-	mounted on it and not to check the automount flag.  Any other error
-	code will abort pathwalk completely.
-
-	If the 'rcu_walk' parameter is true, then the caller is doing a
-	pathwalk in RCU-walk mode.  Sleeping is not permitted in this mode,
-	and the caller can be asked to leave it and call again by returning
-	-ECHILD.  -EISDIR may also be returned to tell pathwalk to
-	ignore d_automount or any mounts.
-
-	This function is only used if DCACHE_MANAGE_TRANSIT is set on the
-	dentry being transited from.
-
-- ``d_real``: overlay/union type filesystems implement this method to return one of
-	the underlying dentries hidden by the overlay.  It is used in two
-	different modes:
-
-	Called from file_dentry() it returns the real dentry matching the inode
-	argument.  The real dentry may be from a lower layer already copied up,
-	but still referenced from the file.  This mode is selected with a
-	non-NULL inode argument.
-
-	With NULL inode the topmost real underlying dentry is returned.
+  Useful for some pseudo filesystems (sockfs, pipefs, ...) to delay
+  pathname generation.  (Instead of doing it when dentry is created,
+  it's done only when the path is needed.).  Real filesystems probably
+  dont want to use it, because their dentries are present in global
+  dcache hash, so their hash should be an invariant.  As no lock is
+  held, d_dname() should not try to modify the dentry itself, unless
+  appropriate SMP safety is used.  CAUTION : d_path() logic is quite
+  tricky.  The correct way to return for example "Hello" is to put it at
+  the end of the buffer, and returns a pointer to the first char.
+  dynamic_dname() helper function is provided to take care of this.
+
+  .. code-block:: c
+
+     static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen)
+     {
+	     return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]",
+				  dentry->d_inode->i_ino);
+     }
+
+- ``d_automount``: called when an automount dentry is to be traversed
+  (optional).  This should create a new VFS mount record and return the
+  record to the caller.  The caller is supplied with a path parameter
+  giving the automount directory to describe the automount target and
+  the parent VFS mount record to provide inheritable mount parameters.
+  NULL should be returned if someone else managed to make the automount
+  first.  If the vfsmount creation failed, then an error code should be
+  returned.  If -EISDIR is returned, then the directory will be treated
+  as an ordinary directory and returned to pathwalk to continue walking.
+
+  If a vfsmount is returned, the caller will attempt to mount it on the
+  mountpoint and will remove the vfsmount from its expiration list in
+  the case of failure.  The vfsmount should be returned with 2 refs on
+  it to prevent automatic expiration - the caller will clean up the
+  additional ref.
+
+  This function is only used if DCACHE_NEED_AUTOMOUNT is set on the
+  dentry.  This is set by __d_instantiate() if S_AUTOMOUNT is set on the
+  inode being added.
+
+- ``d_manage``: called to allow the filesystem to manage the transition
+  from a dentry (optional).  This allows autofs, for example, to hold up
+  clients waiting to explore behind a 'mountpoint' while letting the
+  daemon go past and construct the subtree there.  0 should be returned
+  to let the calling process continue.  -EISDIR can be returned to tell
+  pathwalk to use this directory as an ordinary directory and to ignore
+  anything mounted on it and not to check the automount flag.  Any other
+  error code will abort pathwalk completely.
+
+  If the 'rcu_walk' parameter is true, then the caller is doing a
+  pathwalk in RCU-walk mode.  Sleeping is not permitted in this mode,
+  and the caller can be asked to leave it and call again by returning
+  -ECHILD.  -EISDIR may also be returned to tell pathwalk to ignore
+  d_automount or any mounts.
+
+  This function is only used if DCACHE_MANAGE_TRANSIT is set on the
+  dentry being transited from.
+
+- ``d_real``: overlay/union type filesystems implement this method to
+  return one of the underlying dentries hidden by the overlay.  It is
+  used in two different modes:
+
+  Called from file_dentry() it returns the real dentry matching the
+  inode argument.  The real dentry may be from a lower layer already
+  copied up, but still referenced from the file.  This mode is selected
+  with a non-NULL inode argument.
+
+  With NULL inode the topmost real underlying dentry is returned.
 
 Each dentry has a pointer to its parent dentry, as well as a hash list
 of child dentries.  Child dentries are basically like files in a
@@ -1188,39 +1189,38 @@ There are a number of functions defined which permit a filesystem to
 manipulate dentries:
 
 - ``dget``: open a new handle for an existing dentry (this just increments
-	the usage count)
+  the usage count).
 
 - ``dput``: close a handle for a dentry (decrements the usage count).  If
-	the usage count drops to 0, and the dentry is still in its
-	parent's hash, the "d_delete" method is called to check whether
-	it should be cached.  If it should not be cached, or if the dentry
-	is not hashed, it is deleted.  Otherwise cached dentries are put
-	into an LRU list to be reclaimed on memory shortage.
+  the usage count drops to 0, and the dentry is still in its parent's hash,
+  the "d_delete" method is called to check whether it should be cached.  If
+  it should not be cached, or if the dentry is not hashed, it is deleted.
+  Otherwise cached dentries are put into an LRU list to be reclaimed on
+  memory shortage.
 
 - ``d_drop``: this unhashes a dentry from its parents hash list.  A
-	subsequent call to dput() will deallocate the dentry if its
-	usage count drops to 0
+  subsequent call to dput() will deallocate the dentry if its usage count
+  drops to 0.
 
 - ``d_delete``: delete a dentry.  If there are no other open references to
-	the dentry then the dentry is turned into a negative dentry
-	(the d_iput() method is called).  If there are other
-	references, then d_drop() is called instead
+  the dentry then the dentry is turned into a negative dentry (the d_iput()
+  method is called).  If there are other references, then d_drop() is
+  called instead.
 
 - ``d_add``: add a dentry to its parents hash list and then calls
-	d_instantiate()
+  d_instantiate().
 
 - ``d_instantiate``: add a dentry to the alias hash list for the inode and
-	updates the "d_inode" member.  The "i_count" member in the
-	inode structure should be set/incremented.  If the inode
-	pointer is NULL, the dentry is called a "negative
-	dentry".  This function is commonly called when an inode is
-	created for an existing negative dentry
+  updates the "d_inode" member.  The "i_count" member in the inode
+  structure should be set/incremented.  If the inode pointer is NULL, the
+  dentry is called a "negative dentry".  This function is commonly called
+  when an inode is created for an existing negative dentry.
 
-- ``d_lookup``: look up a dentry given its parent and path name component
-	It looks up the child of that given name from the dcache
-	hash table.  If it is found, the reference count is incremented
-	and the dentry is returned.  The caller must use dput()
-	to free the dentry when it finishes using it.
+- ``d_lookup``: look up a dentry given its parent and path name component.
+  It looks up the child of that given name from the dcache hash table.  If
+  it is found, the reference count is incremented and the dentry is
+  returned.  The caller must use dput() to free the dentry when it finishes
+  using it.
 
 
 Mount Options
@@ -1234,8 +1234,8 @@ On mount and remount the filesystem is passed a string containing a
 comma separated list of mount options.  The options can have either of
 these forms:
 
-  option
-  option=value
+- option
+- option=value
 
 The <linux/parser.h> header defines an API that helps parse these
 options.  There are plenty of examples on how to use it in existing
@@ -1248,11 +1248,11 @@ Showing options
 If a filesystem accepts mount options, it must define show_options() to
 show all the currently active options.  The rules are:
 
-  - options MUST be shown which are not default or their values differ
-    from the default
+- options MUST be shown which are not default or their values differ from
+  the default.
 
-  - options MAY be shown which are enabled by default or have their
-    default value
+- options MAY be shown which are enabled by default or have their default
+  value.
 
 Options used only internally between a mount helper and the kernel (such
 as file descriptors), or which only have an effect during the mounting
-- 
2.21.0