Re: [PATCH 1/2] ext4: docs: switch away from list-table
From: Jani Nikula <jani.nikula@linux.intel.com>
Date: 2021-10-08 01:07:06
Also in:
linux-doc
On Thu, 02 Sep 2021, Jonathan Corbet [off-list ref] wrote:
quoted hunk ↗ jump to hunk
Commit 3a6541e97c03 (Add documentation about the orphan file feature) added a new document on orphan files, which is great. But the use of "list-table" results in documents that are absolutely unreadable in their plain-text form. Switch this file to the regular RST table format instead; the rendered (HTML) output is identical. Signed-off-by: Jonathan Corbet <corbet@lwn.net> --- Documentation/filesystems/ext4/orphan.rst | 32 ++++++++--------------- 1 file changed, 11 insertions(+), 21 deletions(-)diff --git a/Documentation/filesystems/ext4/orphan.rst b/Documentation/filesystems/ext4/orphan.rst index bb19ecd1b626..d096fe0ba19e 100644 --- a/Documentation/filesystems/ext4/orphan.rst +++ b/Documentation/filesystems/ext4/orphan.rst@@ -21,27 +21,17 @@ in heavy creation of orphan inodes. When orphan file feature (referenced from the superblock through s\_orphan_file_inum) with several blocks. Each of these blocks has a structure: -.. list-table:: - :widths: 8 8 24 40 - :header-rows: 1 - - * - Offset - - Type - - Name - - Description - * - 0x0 - - Array of \_\_le32 entries - - Orphan inode entries - - Each \_\_le32 entry is either empty (0) or it contains inode number of - an orphan inode. - * - blocksize - 8 - - \_\_le32 - - ob\_magic - - Magic value stored in orphan block tail (0x0b10ca04) - * - blocksize - 4 - - \_\_le32 - - ob\_checksum - - Checksum of the orphan block. +============= ================ =============== =============================== +Offset Type Name Description +============= ================ =============== =============================== +0x0 Array of Orphan inode Each \_\_le32 entry is either + \_\_le32 entries entries empty (0) or it contains + inode number of an orphan + inode. +blocksize-8 \_\_le32 ob\_magic Magic value stored in orphan + block tail (0x0b10ca04) +blocksize-4 \_\_le32 ob\_checksum Checksum of the orphan block. +============= ================ =============== =============================== When a filesystem with orphan file feature is writeably mounted, we set RO\_COMPAT\_ORPHAN\_PRESENT feature in the superblock to indicate there may
As a third alternative, the csv-table directive [1] is sometimes a good choice. Picking | as the delim makes it look more like a table in the source, and you don't have to worry about aligning everything (the spaces before and after the delim are ignored by default). But it does require some boilerplate and you can't wrap the lines. The same table as an example: .. csv-table:: Block Structure :delim: | :header-rows: 1 :widths: auto Offset | Type | Name | Description 0x0 | Array of __le32 entries | Orphan inode entries | Each __le32 entry is either empty (0) or it contains inode number of an orphan inode. blocksize-8 | __le32 | ob_magic | Magic value stored in orphan block tail (0x0b10ca04) blocksize-4 | __le32 | ob_checksum | Checksum of the orphan block. Obviously not the best choice for this particular table, but just so you are aware of an alternative. BR, Jani. [1] https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table -- Jani Nikula, Intel Open Source Graphics Center