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

[Taylor Blau <me@ttaylorr.com>]

On Tue, Jun 07, 2022 at 05:43:33PM +0000, Abhradeep Chakraborty via GitGitGadget wrote:
> 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?

> 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