From: Akira Yokosawa <akiyks@gmail.com>
To: Masaharu Noguchi <nogunix@gmail.com>,
jaegeuk@kernel.org, chao@kernel.org
Cc: corbet@lwn.net, linux-f2fs-devel@lists.sourceforge.net,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2] Documentation: f2fs: wrap tables in literal code blocks
Date: Tue, 11 Nov 2025 12:28:24 +0900 [thread overview]
Message-ID: <1c742563-5408-4fe1-b122-8a7a14cf737f@gmail.com> (raw)
In-Reply-To: <20251109095416.2428351-1-nogunix@gmail.com>
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/20251011172415.114599-1-nogunix@gmail.com/
> 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 <nogunix@gmail.com>
> ---
> 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.
================== ========================================
======================== ============================================================
prev parent reply other threads:[~2025-11-11 3:28 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-11-09 9:54 [PATCH v2] Documentation: f2fs: wrap tables in literal code blocks Masaharu Noguchi
2025-11-10 9:36 ` Bagas Sanjaya
2025-11-10 11:05 ` Akira Yokosawa
2025-11-11 3:28 ` Akira Yokosawa [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1c742563-5408-4fe1-b122-8a7a14cf737f@gmail.com \
--to=akiyks@gmail.com \
--cc=chao@kernel.org \
--cc=corbet@lwn.net \
--cc=jaegeuk@kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-f2fs-devel@lists.sourceforge.net \
--cc=linux-kernel@vger.kernel.org \
--cc=nogunix@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).