* [f2fs-dev] [PATCH] Documentation: f2fs: wrap tables in literal code blocks to fix LaTeX build
@ 2025-10-11 17:24 Masaharu Noguchi
2025-10-12 4:39 ` Akira Yokosawa
0 siblings, 1 reply; 3+ messages in thread
From: Masaharu Noguchi @ 2025-10-11 17:24 UTC (permalink / raw)
To: Jaegeuk Kim, Chao Yu, Jonathan Corbet, open list:F2FS FILE SYSTEM,
open list:DOCUMENTATION, open list
Cc: Masaharu Noguchi
Sphinx LaTeX builder fails with the following error:
Markup is unsupported in LaTeX:
filesystems/f2fs:: longtable does not support nesting a table.
Wrap the ASCII tables in literal code blocks so that they are rendered
as code instead of interpreted as tables. This fixes pdfdocs build
failure.
Signed-off-by: Masaharu Noguchi <nogunix@gmail.com>
---
Documentation/filesystems/f2fs.rst | 106 ++++++++++++++++-------------
1 file changed, 57 insertions(+), 49 deletions(-)
diff --git a/Documentation/filesystems/f2fs.rst b/Documentation/filesystems/f2fs.rst
index a8d02fe5be83..80f94f309cea 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.
@@ -298,12 +300,14 @@ compress_algorithm=%s Control compress algorithm, currently f2fs supports "lzo"
compress_algorithm=%s:%d Control compress algorithm and its compress level, now, only
"lz4" and "zstd" support compress level config.
- ========= ===========
+ .. code-block:: none
+
+ ========= ===========
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 +372,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
--
2.51.0
_______________________________________________
Linux-f2fs-devel mailing list
Linux-f2fs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/linux-f2fs-devel
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [f2fs-dev] [PATCH] Documentation: f2fs: wrap tables in literal code blocks to fix LaTeX build
2025-10-11 17:24 [f2fs-dev] [PATCH] Documentation: f2fs: wrap tables in literal code blocks to fix LaTeX build Masaharu Noguchi
@ 2025-10-12 4:39 ` Akira Yokosawa
2025-10-12 5:31 ` Masaharu Noguchi
0 siblings, 1 reply; 3+ messages in thread
From: Akira Yokosawa @ 2025-10-12 4:39 UTC (permalink / raw)
To: nogunix
Cc: corbet, Akira Yokosawa, linux-doc, linux-kernel, linux-f2fs-devel,
jaegeuk
Hello,
On Sun, 12 Oct 2025 02:24:15 +0900, Masaharu Noguchi wrote:
> Sphinx LaTeX builder fails with the following error:
>
> Markup is unsupported in LaTeX:
> filesystems/f2fs:: longtable does not support nesting a table.
>
> Wrap the ASCII tables in literal code blocks so that they are rendered
> as code instead of interpreted as tables. This fixes pdfdocs build
> failure.
>
> Signed-off-by: Masaharu Noguchi <nogunix@gmail.com>
With this patch applied,
"make SPHINXDIRS=filesystems htmldocs" emits following new warnings (Sphinx 8.2.3):
-------- -------- -------- -------- -------- -------- -------- --------
<srctree>/Documentation/filesystems/f2fs.rst:307: WARNING: Explicit markup ends without a blank line; unexpected unindent. [docutils]
<srctree>/Documentation/filesystems/f2fs.rst:308: ERROR: Malformed table.
No bottom table border found.
========= =========== [docutils]
<srctree>/Documentation/filesystems/f2fs.rst:309: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
<srctree>/Documentation/filesystems/f2fs.rst:310: ERROR: Unexpected indentation. [docutils]
<srctree>/Documentation/filesystems/f2fs.rst:311: ERROR: Malformed table.
No bottom table border found.
========= =========== [docutils]
-------- -------- -------- -------- -------- -------- -------- --------
That said, for your info, in-development Sphinx 8.3.0 (not yet released)
has a lot of improvements in its latex builder including support of these
nested tables [1].
So, I think one option for you might be to wait Sphinx 8.3.0 without
these changes.
One caveat is that docutils 0.22.x is not fully compatible with the latex
builder at the moment. If you'd like to test Sphinx 8.3.0, you need to
say "docutils<0.22" in pip install.
[1]: https://www.sphinx-doc.org/en/master/changes/index.html#release-8-3-0-in-development
Hope this helps,
Akira
_______________________________________________
Linux-f2fs-devel mailing list
Linux-f2fs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/linux-f2fs-devel
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [f2fs-dev] [PATCH] Documentation: f2fs: wrap tables in literal code blocks to fix LaTeX build
2025-10-12 4:39 ` Akira Yokosawa
@ 2025-10-12 5:31 ` Masaharu Noguchi
0 siblings, 0 replies; 3+ messages in thread
From: Masaharu Noguchi @ 2025-10-12 5:31 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: corbet, linux-doc, linux-kernel, linux-f2fs-devel, jaegeuk
Hello,
Thank you for your detailed feedback regarding the f2fs.rst issue.
I have tested the current mainline (without my patch) using
Sphinx 8.3.0+ (commit ab8303f4bb13) and Docutils 0.21.2
on Python 3.13.7.
The pdfdocs build now completes successfully, and the nested
tables in f2fs.rst no longer cause any LaTeX errors.
It seems that the problem has been resolved in the upcoming
Sphinx 8.3 release, as you mentioned.
Thanks again for your kind guidance.
Best regards,
Masaharu Noguchi
_______________________________________________
Linux-f2fs-devel mailing list
Linux-f2fs-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/linux-f2fs-devel
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2025-10-12 5:31 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-10-11 17:24 [f2fs-dev] [PATCH] Documentation: f2fs: wrap tables in literal code blocks to fix LaTeX build Masaharu Noguchi
2025-10-12 4:39 ` Akira Yokosawa
2025-10-12 5:31 ` Masaharu Noguchi
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).