[PATCH 0/5] Assorted filesystem docs formatting

[PATCH 0/5] Assorted filesystem docs formatting

[Bagas Sanjaya]

Hi,

Here are assorted docs formatting cleanup on filesystems (the shortlog
should be self-explanatory):

  * Patch [1/5] on AFS
  * Patch [2-3/5] on DAX
  * Patch [4-5/5] on zonefs

Enjoy!

Bagas Sanjaya (5):
  Documentation: afs: Use proper bullet for bullet lists
  Documentation: dax: Coalesce "See also" filesystem pointers into list
  Documentation: dax: Demote "Enabling DAX on xfs and ext4" subsections
  Documentation: zonefs: Separate mount options list
  Documentation: zonefs: Format error processing table

 Documentation/filesystems/afs.rst    | 21 +++++------
 Documentation/filesystems/dax.rst    | 18 +++-------
 Documentation/filesystems/zonefs.rst | 54 +++++++++++++++++-----------
 3 files changed, 47 insertions(+), 46 deletions(-)


base-commit: d879c2e0195bd5fd4c48467b95b77e494099c96c
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 1/5] Documentation: afs: Use proper bullet for bullet lists

[Bagas Sanjaya]

The lists use an asterisk in parentheses (``(*)``) as the bullet marker,
which isn't recognized by Sphinx as the proper bullet. Replace with just
an asterisk.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/afs.rst | 21 +++++++++------------
 1 file changed, 9 insertions(+), 12 deletions(-)

diff --git a/Documentation/filesystems/afs.rst b/Documentation/filesystems/afs.rst
index f15ba388bbde79..6135d64ada6372 100644
--- a/Documentation/filesystems/afs.rst
+++ b/Documentation/filesystems/afs.rst
@@ -23,17 +23,14 @@ This filesystem provides a fairly simple secure AFS filesystem driver. It is
 under development and does not yet provide the full feature set.  The features
 it does support include:
 
- (*) Security (currently only AFS kaserver and KerberosIV tickets).
-
- (*) File reading and writing.
-
- (*) Automounting.
-
- (*) Local caching (via fscache).
+ * Security (currently only AFS kaserver and KerberosIV tickets).
+ * File reading and writing.
+ * Automounting.
+ * Local caching (via fscache).
 
 It does not yet support the following AFS features:
 
- (*) pioctl() system call.
+ * pioctl() system call.
 
 
 Compilation
@@ -146,15 +143,15 @@ Proc Filesystem
 
 The AFS module creates a "/proc/fs/afs/" directory and populates it:
 
-  (*) A "cells" file that lists cells currently known to the afs module and
-      their usage counts::
+  * A "cells" file that lists cells currently known to the afs module and
+    their usage counts::
 
 	[root@andromeda ~]# cat /proc/fs/afs/cells
 	USE NAME
 	  3 cambridge.redhat.com
 
-  (*) A directory per cell that contains files that list volume location
-      servers, volumes, and active servers known within that cell::
+  * A directory per cell that contains files that list volume location
+    servers, volumes, and active servers known within that cell::
 
 	[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
 	USE ADDR            STATE
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 1/5] Documentation: afs: Use proper bullet for bullet lists

[Randy Dunlap]

On 11/25/25 6:55 PM, Bagas Sanjaya wrote:
> The lists use an asterisk in parentheses (``(*)``) as the bullet marker,
> which isn't recognized by Sphinx as the proper bullet. Replace with just
> an asterisk.
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  Documentation/filesystems/afs.rst | 21 +++++++++------------
>  1 file changed, 9 insertions(+), 12 deletions(-)
> 
> diff --git a/Documentation/filesystems/afs.rst b/Documentation/filesystems/afs.rst
> index f15ba388bbde79..6135d64ada6372 100644
> --- a/Documentation/filesystems/afs.rst
> +++ b/Documentation/filesystems/afs.rst
> @@ -23,17 +23,14 @@ This filesystem provides a fairly simple secure AFS filesystem driver. It is
>  under development and does not yet provide the full feature set.  The features
>  it does support include:
>  
> - (*) Security (currently only AFS kaserver and KerberosIV tickets).
> -
> - (*) File reading and writing.
> -
> - (*) Automounting.
> -
> - (*) Local caching (via fscache).
> + * Security (currently only AFS kaserver and KerberosIV tickets).
> + * File reading and writing.
> + * Automounting.
> + * Local caching (via fscache).
>  
>  It does not yet support the following AFS features:
>  
> - (*) pioctl() system call.
> + * pioctl() system call.
>  
>  
>  Compilation
> @@ -146,15 +143,15 @@ Proc Filesystem
>  
>  The AFS module creates a "/proc/fs/afs/" directory and populates it:
>  
> -  (*) A "cells" file that lists cells currently known to the afs module and
> -      their usage counts::
> +  * A "cells" file that lists cells currently known to the afs module and
> +    their usage counts::
>  
>  	[root@andromeda ~]# cat /proc/fs/afs/cells
>  	USE NAME
>  	  3 cambridge.redhat.com
>  
> -  (*) A directory per cell that contains files that list volume location
> -      servers, volumes, and active servers known within that cell::
> +  * A directory per cell that contains files that list volume location
> +    servers, volumes, and active servers known within that cell::
>  
>  	[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
>  	USE ADDR            STATE

-- 
~Randy

[PATCH 2/5] Documentation: dax: Coalesce "See also" filesystem pointers into list

[Bagas Sanjaya]

Filesystems for DAX implementation inspiration is listed in "See also"
admonitions, one for each filesystem (ext2, ext4, and xfs). Coalesce
them into a bullet list.

While at it, also link to XFS developer documentation in
Documentation/filesystems/xfs/ instead of user-facing counterpart in
Docmentation/admin-guide/xfs.rst.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/dax.rst | 14 +++-----------
 1 file changed, 3 insertions(+), 11 deletions(-)

diff --git a/Documentation/filesystems/dax.rst b/Documentation/filesystems/dax.rst
index 5b283f3d1eb113..e0631d5f6251d4 100644
--- a/Documentation/filesystems/dax.rst
+++ b/Documentation/filesystems/dax.rst
@@ -234,17 +234,9 @@ exposure of uninitialized data through mmap.
 
 These filesystems may be used for inspiration:
 
-.. seealso::
-
-  ext2: see Documentation/filesystems/ext2.rst
-
-.. seealso::
-
-  xfs:  see Documentation/admin-guide/xfs.rst
-
-.. seealso::
-
-  ext4: see Documentation/filesystems/ext4/
+  * :doc:`ext2 <ext2>`
+  * :doc:`ext4 <ext4/index>`
+  * :doc:`xfs <xfs/index>`
 
 
 Handling Media Errors
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 2/5] Documentation: dax: Coalesce "See also" filesystem pointers into list

[Randy Dunlap]

On 11/25/25 6:55 PM, Bagas Sanjaya wrote:
> Filesystems for DAX implementation inspiration is listed in "See also"
> admonitions, one for each filesystem (ext2, ext4, and xfs). Coalesce
> them into a bullet list.
> 
> While at it, also link to XFS developer documentation in
> Documentation/filesystems/xfs/ instead of user-facing counterpart in
> Docmentation/admin-guide/xfs.rst.
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  Documentation/filesystems/dax.rst | 14 +++-----------
>  1 file changed, 3 insertions(+), 11 deletions(-)
> 

-- 
~Randy

[PATCH 3/5] Documentation: dax: Demote "Enabling DAX on xfs and ext4" subsections

[Bagas Sanjaya]

Subsections of "Enabling DAX on xfs and ext4" section (both "Summary"
and "Details") are marked up as section heading instead, which makes
their way to filesystems toctree entry. Demote them.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/dax.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/filesystems/dax.rst b/Documentation/filesystems/dax.rst
index e0631d5f6251d4..f9243d45ce1280 100644
--- a/Documentation/filesystems/dax.rst
+++ b/Documentation/filesystems/dax.rst
@@ -38,7 +38,7 @@ Enabling DAX on xfs and ext4
 ----------------------------
 
 Summary
--------
+~~~~~~~
 
  1. There exists an in-kernel file access mode flag `S_DAX` that corresponds to
     the statx flag `STATX_ATTR_DAX`.  See the manpage for statx(2) for details
@@ -95,7 +95,7 @@ Summary
 
 
 Details
--------
+~~~~~~~
 
 There are 2 per-file dax flags.  One is a persistent inode setting (`FS_XFLAG_DAX`)
 and the other is a volatile flag indicating the active state of the feature
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 3/5] Documentation: dax: Demote "Enabling DAX on xfs and ext4" subsections

[Randy Dunlap]

On 11/25/25 6:55 PM, Bagas Sanjaya wrote:
> Subsections of "Enabling DAX on xfs and ext4" section (both "Summary"
> and "Details") are marked up as section heading instead, which makes
> their way to filesystems toctree entry. Demote them.
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  Documentation/filesystems/dax.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 

-- 
~Randy

[PATCH 4/5] Documentation: zonefs: Separate mount options list

[Bagas Sanjaya]

Mount options list is rendered in htmldocs output as combined with
preceding paragraph due to missing separator between them. Add it.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/zonefs.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/filesystems/zonefs.rst b/Documentation/filesystems/zonefs.rst
index c22124c2213d5d..58cfb1183589dd 100644
--- a/Documentation/filesystems/zonefs.rst
+++ b/Documentation/filesystems/zonefs.rst
@@ -307,6 +307,7 @@ Mount options
 -------------
 
 zonefs defines several mount options:
+
 * errors=<behavior>
 * explicit-open
 
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 4/5] Documentation: zonefs: Separate mount options list

[Damien Le Moal]

On 11/26/25 11:55 AM, Bagas Sanjaya wrote:
> Mount options list is rendered in htmldocs output as combined with
> preceding paragraph due to missing separator between them. Add it.
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Thank you for fixing this.

Acked-by: Damien Le Moal <dlemoal@kernel.org>


-- 
Damien Le Moal
Western Digital Research

Re: [PATCH 4/5] Documentation: zonefs: Separate mount options list

[Randy Dunlap]

On 11/25/25 6:55 PM, Bagas Sanjaya wrote:
> Mount options list is rendered in htmldocs output as combined with
> preceding paragraph due to missing separator between them. Add it.
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  Documentation/filesystems/zonefs.rst | 1 +
>  1 file changed, 1 insertion(+)
> 

-- 
~Randy

[PATCH 5/5] Documentation: zonefs: Format error processing table

[Bagas Sanjaya]

Format zonefs I/O error processing table as reST grid table.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/filesystems/zonefs.rst | 53 +++++++++++++++++-----------
 1 file changed, 32 insertions(+), 21 deletions(-)

diff --git a/Documentation/filesystems/zonefs.rst b/Documentation/filesystems/zonefs.rst
index 58cfb1183589dd..a2e97bd69b6347 100644
--- a/Documentation/filesystems/zonefs.rst
+++ b/Documentation/filesystems/zonefs.rst
@@ -255,30 +255,41 @@ permissions.
 Further action taken by zonefs I/O error recovery can be controlled by the user
 with the "errors=xxx" mount option. The table below summarizes the result of
 zonefs I/O error processing depending on the mount option and on the zone
-conditions::
+conditions:
 
     +--------------+-----------+-----------------------------------------+
     |              |           |            Post error state             |
-    | "errors=xxx" |  device   |                 access permissions      |
-    |    mount     |   zone    | file         file          device zone  |
-    |    option    | condition | size     read    write    read    write |
-    +--------------+-----------+-----------------------------------------+
-    |              | good      | fixed    yes     no       yes     yes   |
-    | remount-ro   | read-only | as is    yes     no       yes     no    |
-    | (default)    | offline   |   0      no      no       no      no    |
-    +--------------+-----------+-----------------------------------------+
-    |              | good      | fixed    yes     no       yes     yes   |
-    | zone-ro      | read-only | as is    yes     no       yes     no    |
-    |              | offline   |   0      no      no       no      no    |
-    +--------------+-----------+-----------------------------------------+
-    |              | good      |   0      no      no       yes     yes   |
-    | zone-offline | read-only |   0      no      no       yes     no    |
-    |              | offline   |   0      no      no       no      no    |
-    +--------------+-----------+-----------------------------------------+
-    |              | good      | fixed    yes     yes      yes     yes   |
-    | repair       | read-only | as is    yes     no       yes     no    |
-    |              | offline   |   0      no      no       no      no    |
-    +--------------+-----------+-----------------------------------------+
+    |              |           +--------+---------------+----------------+
+    |              |           |        |        access permissions      |
+    | "errors=xxx" | device    | file   +---------------+----------------+
+    | mount        | zone      | size   |     file      |   device zone  |
+    | option       | condition |        +-------+-------+--------+-------+
+    |              |           |        | read  | write |  read  | write |
+    +==============+===========+========+=======+=======+========+=======+
+    |              | good      | fixed  | yes   | no    |  yes   | yes   |
+    |              +-----------+--------+-------+-------+--------+-------+
+    | remount-ro   | read-only | as is  | yes   | no    |  yes   | no    |
+    | (default)    +-----------+--------+-------+-------+--------+-------+
+    |              | offline   |   0    | no    | no    |  no    | no    |
+    +--------------+-----------+--------+-------+-------+--------+-------+
+    |              | good      | fixed  | yes   | no    |  yes   | yes   |
+    |              +-----------+--------+-------+-------+--------+-------+
+    | zone-ro      | read-only | as is  | yes   | no    |  yes   | no    |
+    |              +-----------+--------+-------+-------+--------+-------+
+    |              | offline   |   0    | no    | no    |  no    | no    |
+    +--------------+-----------+--------+-------+-------+--------+-------+
+    |              | good      |   0    | no    | no    |  yes   | yes   |
+    |              +-----------+--------+-------+-------+--------+-------+
+    | zone-offline | read-only |   0    | no    | no    |  yes   | no    |
+    |              +-----------+--------+-------+-------+--------+-------+
+    |              | offline   |   0    | no    | no    |  no    | no    |
+    +--------------+-----------+--------+-------+-------+--------+-------+
+    |              | good      | fixed  | yes   | yes   |  yes   | yes   |
+    |              +-----------+--------+-------+-------+--------+-------+
+    | repair       | read-only | as is  | yes   | no    |  yes   | no    |
+    |              +-----------+--------+-------+-------+--------+-------+
+    |              | offline   |   0    | no    | no    |  no    | no    |
+    +--------------+-----------+--------+-------+-------+--------+-------+
 
 Further notes:
 
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 5/5] Documentation: zonefs: Format error processing table

[Damien Le Moal]

On 11/26/25 11:55 AM, Bagas Sanjaya wrote:
> Format zonefs I/O error processing table as reST grid table.
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Thank you for fixing this.

Acked-by: Damien Le Moal <dlemoal@kernel.org>

-- 
Damien Le Moal
Western Digital Research

Re: [PATCH 5/5] Documentation: zonefs: Format error processing table

[Randy Dunlap]

On 11/25/25 6:55 PM, Bagas Sanjaya wrote:
> Format zonefs I/O error processing table as reST grid table.
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  Documentation/filesystems/zonefs.rst | 53 +++++++++++++++++-----------
>  1 file changed, 32 insertions(+), 21 deletions(-)
> 

-- 
~Randy

Re: [PATCH 1/5] Documentation: afs: Use proper bullet for bullet lists

[David Howells]

Bagas Sanjaya <bagasdotme@gmail.com> wrote:

> The lists use an asterisk in parentheses (``(*)``) as the bullet marker,
> which isn't recognized by Sphinx as the proper bullet. Replace with just
> an asterisk.
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>

Acked-by: David Howells <dhowells@redhat.com>