Hi again,
On Sun, 9 Nov 2025 18:54:16 +0900, Masaharu Noguchi wrote:
> Sphinx LaTeX builder fails with the following error when it tries to
> turn the ASCII tables in f2fs.rst into nested longtables:
>
> Markup is unsupported in LaTeX:
> filesystems/f2fs:: longtable does not support nesting a table.
>
> Wrap the tables in literal code blocks so that Sphinx renders them as
> verbatim text instead. This prevents the LaTeX builder from attempting
> unsupported table nesting and fixes the pdfdocs build.
>
> Akira Yokosawa pointed out that the in-development Sphinx 8.3 latex
> builder already handles these nested tables. I still want to fix the
> current documentation because Sphinx 8.3 is not released yet, and the
> LaTeX build on the stable 8.2.x series (which also requires
> "docutils<0.22" for now) remains broken without this change.
>
> Link: https://lore.kernel.org/lkml/[email protected]/
> Changes in v2:
> - wrap the compression level table in a literal block and add the
> missing blank lines so docutils no longer warns about malformed
> tables
> - consistently use ``.. code-block:: none`` for the other ASCII tables
> that previously triggered the LaTeX error
>
> Signed-off-by: Masaharu Noguchi <[email protected]>
> ---
> Documentation/filesystems/f2fs.rst | 115 +++++++++++++++--------------
> 1 file changed, 61 insertions(+), 54 deletions(-)
>
> diff --git a/Documentation/filesystems/f2fs.rst
> b/Documentation/filesystems/f2fs.rst
> index a8d02fe5be83..07b8e752476d 100644
> --- a/Documentation/filesystems/f2fs.rst
> +++ b/Documentation/filesystems/f2fs.rst
> @@ -188,34 +188,36 @@ fault_type=%d Support configuring fault
> injection type, should be
> enabled with fault_injection option, fault type value
> is shown below, it supports single or combined type.
>
> - =========================== ==========
> - Type_Name Type_Value
> - =========================== ==========
> - FAULT_KMALLOC 0x00000001
> - FAULT_KVMALLOC 0x00000002
> - FAULT_PAGE_ALLOC 0x00000004
> - FAULT_PAGE_GET 0x00000008
> - FAULT_ALLOC_BIO 0x00000010 (obsolete)
> - FAULT_ALLOC_NID 0x00000020
> - FAULT_ORPHAN 0x00000040
> - FAULT_BLOCK 0x00000080
> - FAULT_DIR_DEPTH 0x00000100
> - FAULT_EVICT_INODE 0x00000200
> - FAULT_TRUNCATE 0x00000400
> - FAULT_READ_IO 0x00000800
> - FAULT_CHECKPOINT 0x00001000
> - FAULT_DISCARD 0x00002000
> - FAULT_WRITE_IO 0x00004000
> - FAULT_SLAB_ALLOC 0x00008000
> - FAULT_DQUOT_INIT 0x00010000
> - FAULT_LOCK_OP 0x00020000
> - FAULT_BLKADDR_VALIDITY 0x00040000
> - FAULT_BLKADDR_CONSISTENCE 0x00080000
> - FAULT_NO_SEGMENT 0x00100000
> - FAULT_INCONSISTENT_FOOTER 0x00200000
> - FAULT_TIMEOUT 0x00400000 (1000ms)
> - FAULT_VMALLOC 0x00800000
> - =========================== ==========
> + .. code-block:: none
> +
> + =========================== ==========
> + Type_Name Type_Value
> + =========================== ==========
> + FAULT_KMALLOC 0x00000001
> + FAULT_KVMALLOC 0x00000002
> + FAULT_PAGE_ALLOC 0x00000004
> + FAULT_PAGE_GET 0x00000008
> + FAULT_ALLOC_BIO 0x00000010
> (obsolete)
> + FAULT_ALLOC_NID 0x00000020
> + FAULT_ORPHAN 0x00000040
> + FAULT_BLOCK 0x00000080
> + FAULT_DIR_DEPTH 0x00000100
> + FAULT_EVICT_INODE 0x00000200
> + FAULT_TRUNCATE 0x00000400
> + FAULT_READ_IO 0x00000800
> + FAULT_CHECKPOINT 0x00001000
> + FAULT_DISCARD 0x00002000
> + FAULT_WRITE_IO 0x00004000
> + FAULT_SLAB_ALLOC 0x00008000
> + FAULT_DQUOT_INIT 0x00010000
> + FAULT_LOCK_OP 0x00020000
> + FAULT_BLKADDR_VALIDITY 0x00040000
> + FAULT_BLKADDR_CONSISTENCE 0x00080000
> + FAULT_NO_SEGMENT 0x00100000
> + FAULT_INCONSISTENT_FOOTER 0x00200000
> + FAULT_TIMEOUT 0x00400000
> (1000ms)
> + FAULT_VMALLOC 0x00800000
> + =========================== ==========
> mode=%s Control block allocation mode which supports
> "adaptive"
> and "lfs". In "lfs" mode, there should be no random
> writes towards main area.
> @@ -296,14 +298,15 @@ nocheckpoint_merge Disable checkpoint merge
> feature.
> compress_algorithm=%s Control compress algorithm, currently f2fs
> supports "lzo",
> "lz4", "zstd" and "lzo-rle" algorithm.
> compress_algorithm=%s:%d Control compress algorithm and its compress level,
> now, only
> - "lz4" and "zstd" support compress level config.
> -
> - ========= ===========
> - algorithm level range
> - ========= ===========
> - lz4 3 - 16
> - zstd 1 - 22
> - ========= ===========
> + "lz4" and "zstd" support compress level config::
> +
> + ========= ===========
> + algorithm level range
> + ========= ===========
> + lz4 3 - 16
> + zstd 1 - 22
> + ========= ===========
> +
> compress_log_size=%u Support configuring compress cluster size. The size
> will
> be 4KB * (1 << %u). The default and minimum sizes are
> 16KB.
> compress_extension=%s Support adding specified extension, so that
> f2fs can enable
> @@ -368,38 +371,42 @@ errors=%s Specify f2fs behavior on
> critical errors. This supports modes:
> the partition in read-only mode. By default it uses
> "continue"
> mode.
>
> - ====================== =============== ===============
> ========
> - mode continue remount-ro
> panic
> - ====================== =============== ===============
> ========
> - access ops normal normal
> N/A
> - syscall errors -EIO -EROFS
> N/A
> - mount option rw ro
> N/A
> - pending dir write keep keep
> N/A
> - pending non-dir write drop keep
> N/A
> - pending node write drop keep
> N/A
> - pending meta write keep keep
> N/A
> - ====================== =============== ===============
> ========
> + .. code-block:: none
> +
> + ====================== ===============
> =============== ========
> + mode continue
> remount-ro panic
> + ====================== ===============
> =============== ========
> + access ops normal normal
> N/A
> + syscall errors -EIO -EROFS
> N/A
> + mount option rw ro
> N/A
> + pending dir write keep keep
> N/A
> + pending non-dir write drop keep
> N/A
> + pending node write drop keep
> N/A
> + pending meta write keep keep
> N/A
> + ====================== ===============
> =============== ========
> nat_bits Enable nat_bits feature to enhance full/empty nat
> blocks access,
> by default it's disabled.
> lookup_mode=%s Control the directory lookup behavior for
> casefolded
> directories. This option has no effect on directories
> that do not have the casefold feature enabled.
>
> - ==================
> ========================================
> - Value Description
> - ==================
> ========================================
> - perf (Default) Enforces a hash-only
> lookup.
> + .. code-block:: none
> +
> + ==================
> ========================================
> + Value Description
> + ==================
> ========================================
> + perf (Default) Enforces a
> hash-only lookup.
> The linear search fallback is always
> disabled, ignoring the on-disk flag.
> - compat Enables the linear search fallback
> for
> + compat Enables the linear search
> fallback for
> compatibility with directory entries
> created by older kernel that used a
> different case-folding algorithm.
> This mode ignores the on-disk flag.
> - auto F2FS determines the mode based on
> the
> + auto F2FS determines the mode
> based on the
> on-disk
> `SB_ENC_NO_COMPAT_FALLBACK_FL`
> flag.
> - ==================
> ========================================
> + ==================
> ========================================
> ========================
> ============================================================
>
> Debugfs Entries
My R-b tag was sent without inspecting the source .rst after the change.
Using TABs inside ASCII tables degrades their readability.
Masaharu, can you consider applying follow-up change below, which replaces
TABs with white spaces except for the leading ones, and submit a v3?
Thanks, Akira
---------8<---------8<---------8<---------8<---------8<---------8<---------8<-------
diff --git a/Documentation/filesystems/f2fs.rst
b/Documentation/filesystems/f2fs.rst
index 07b8e752476d..fbe9f8d35366 100644
--- a/Documentation/filesystems/f2fs.rst
+++ b/Documentation/filesystems/f2fs.rst
@@ -374,15 +374,15 @@ errors=%s Specify f2fs behavior on critical
errors. This supports modes:
.. code-block:: none
====================== ===============
=============== ========
- mode continue
remount-ro panic
+ mode continue remount-ro
panic
====================== ===============
=============== ========
- access ops normal normal
N/A
- syscall errors -EIO -EROFS
N/A
- mount option rw ro
N/A
- pending dir write keep keep
N/A
- pending non-dir write drop keep
N/A
- pending node write drop keep
N/A
- pending meta write keep keep
N/A
+ access ops normal normal
N/A
+ syscall errors -EIO -EROFS
N/A
+ mount option rw ro
N/A
+ pending dir write keep keep
N/A
+ pending non-dir write drop keep
N/A
+ pending node write drop keep
N/A
+ pending meta write keep keep
N/A
====================== ===============
=============== ========
nat_bits Enable nat_bits feature to enhance full/empty nat
blocks access,
by default it's disabled.
@@ -393,19 +393,19 @@ lookup_mode=%s Control the directory lookup
behavior for casefolded
.. code-block:: none
==================
========================================
- Value Description
+ Value Description
==================
========================================
- perf (Default) Enforces a
hash-only lookup.
- The linear search fallback is always
- disabled, ignoring the on-disk flag.
- compat Enables the linear search
fallback for
- compatibility with directory entries
- created by older kernel that used a
- different case-folding algorithm.
- This mode ignores the on-disk flag.
- auto F2FS determines the mode
based on the
- on-disk
`SB_ENC_NO_COMPAT_FALLBACK_FL`
- flag.
+ perf (Default) Enforces a hash-only
lookup.
+ The linear search fallback is
always
+ disabled, ignoring the on-disk
flag.
+ compat Enables the linear search
fallback for
+ compatibility with directory
entries
+ created by older kernel that
used a
+ different case-folding
algorithm.
+ This mode ignores the on-disk
flag.
+ auto F2FS determines the mode based
on the
+ on-disk
`SB_ENC_NO_COMPAT_FALLBACK_FL`
+ flag.
==================
========================================
========================
============================================================
_______________________________________________
Linux-f2fs-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/linux-f2fs-devel
