Re: [PATCH v2 2/3] bitmap-format.txt: fix some formatting issues

From: Taylor Blau <me@ttaylorr.com>
Date: Jun 7, 2022, 20:51 UTC
Message-ID: <Yp+6WU+k2OwHDB1b@nand.local>
In-Reply-To: <cb919513c14d426b51051ee5c16badec37538032.1654623814.git.gitgitgadget@gmail.com>

On Tue, Jun 07, 2022 at 05:43:33PM +0000, Abhradeep Chakraborty via GitGitGadget wrote:

Show 8 quoted lines

> From: Abhradeep Chakraborty <chakrabortyabhradeep79@gmail.com>
>
> The asciidoc generated html for `Documentation/technical/bitmap-
> format.txt` is broken. This is mainly because `-` is used for nested
> lists (which is not allowed in asciidoc) instead of `*`.
>
> Fix these and also reformat it (e.g. removing some blank lines) for
> better readability of the html page.

Hmm. When I render the HTML for this page and view it in my browser, the removed blank lines makes the contents of the section "2-byte flags (network byte order)" run together, and I think it hurts readability IMHO.

Is there a way to keep those line breaks without significantly reformatting the source of this file?

Show 17 quoted lines

> Signed-off-by: Abhradeep Chakraborty <chakrabortyabhradeep79@gmail.com>
> ---
>  Documentation/technical/bitmap-format.txt | 20 +++++++-------------
>  1 file changed, 7 insertions(+), 13 deletions(-)
>
> diff --git a/Documentation/technical/bitmap-format.txt b/Documentation/technical/bitmap-format.txt
> index 04b3ec21785..f22669b5916 100644
> --- a/Documentation/technical/bitmap-format.txt
> +++ b/Documentation/technical/bitmap-format.txt
> @@ -39,7 +39,7 @@ MIDXs, both the bit-cache and rev-cache extensions are required.
>
>  == On-disk format
>
> -	- A header appears at the beginning:
> +	* A header appears at the beginning:
>
>  		4-byte signature: {'B', 'I', 'T', 'M'}

Similarly, everything below the "A header appears at the beginning" list item appears in a <pre> element, so the rendered HTML looks more like plaintext to me.

This isn't new from your patch, but I wonder if now is a good opportunity to make some light use of the formatting options that ASCIIDoc gives us to make the page read a little bit more easily when rendered as HTML.

I don't want to compromise too much on the readability of the .txt file, though, so if there isn't a good way to strike this balance, then I trust you and think we should leave it as you have modified things here.

Thanks, Taylor