Re: [PATCH 1/2] ext4: docs: switch away from list-table

[Jani Nikula <jani.nikula@linux.intel.com>]

On Thu, 02 Sep 2021, Jonathan Corbet <corbet@lwn.net> wrote:
> 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