Re: [PATCH v2 0/3] bitmap-format.txt: fix some formatting issues and include checksum info

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 7, 2022, 21:00 UTC
Message-ID: <xmqqo7z4ur2i.fsf@gitster.g>
In-Reply-To: <xmqqfskgwcou.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

Show 13 quoted lines

> "Abhradeep Chakraborty via GitGitGadget" <gitgitgadget@gmail.com>
> writes:
>
>> There are some issues in the bitmap-format html page.
>
> "First, it does not even exist!" before anything else ;-)
>
>> For example, some
>> nested lists are shown as top-level lists (e.g. [1]- Here
>> BITMAP_OPT_FULL_DAG (0x1) and BITMAP_OPT_HASH_CACHE (0x4) are shown as
>> top-level list). There is also a need of adding info about trailing checksum
>> in the docs.
> ...

No, this is not quite ready for production.

Almost all the "indented" material are shown in fixed-width typewriter format in the resulting HTML output.

Look how ugly the output from it is. Not your fault; it is mostly because when the original text was written, it was not even meant to be given to AsciiDoc.

  https://twitter.com/jch2355/status/1534276427607986178/photo/1
  https://pbs.twimg.com/media/FUrYP2nakAAnRaH?format=png

And as I already said, removal of the blank lines made it harder to see what is going on in the source, and because the output is pretty much straight copy of the source in the fixed-font, just like reading the source in the terminal, the output here is equally hard to read.

  https://twitter.com/jch2355/status/1534277664441511937/photo/1
  https://pbs.twimg.com/media/FUrZZXUUsAEmEeT?format=png

If we really want to give it to AsciiDoc, we'd need to reformat it more extensively, not just tweak it on the surface and making an equivalent of <pre>...</pre> slightly easier to read, which is what this patch does.

Thanks.