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

Commit Message

Abhradeep Chakraborty June 7, 2022, 5:43 p.m. UTC

From: Abhradeep Chakraborty <[e-mail]>

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.

Signed-off-by: Abhradeep Chakraborty <[e-mail]>
---
 Documentation/technical/bitmap-format.txt | 20 +++++++-------------
 1 file changed, 7 insertions(+), 13 deletions(-)

Comments

Taylor Blau June 7, 2022, 8:51 p.m. UTC | #1

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

Junio C Hamano June 7, 2022, 10:02 p.m. UTC | #2

Taylor Blau <[e-mail]> writes:

> 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.

True.  Unless we are going to revamp the text in some major way so
that we produce "true" HTML, not just the text source enclosed in a
<pre></pre> pair, I would think we are better off keeping it not
passed to AsciiDoc and leaving it in text format.  After all, modern
browsers, which I presume those who want HTML output files would
read them with, can display plain text files just fine, don't they?

> 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.

There was some talk about asking those who are adept at website
engineering to work on git-scm.com; it may be a good starting point
to look at these text files that weren't originally written to be
given to AsciiDoc and convert them to be true AsciiDoc sources.

Thanks.

Abhradeep Chakraborty June 8, 2022, 3:40 p.m. UTC | #3

Taylor Blau <[e-mail]> wrote:

> 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.

Honestly I agree with you. I also felt the same but then I thought it
is still better than the currently broken page.

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

I have a limited knowledge on asciidoc. I removed those blank lines
only because it generates weird html output. I didn't find any other
way to fix that (with minimum source code changes).

> 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.

Yeah, quite sensible. I will surely look for better way.

> 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.

This is one of the main reason why I removed those blank lines and other
stuff. It is the minimum change to fix the html doc. But I will look more
into it.

Thanks :)

Abhradeep Chakraborty June 8, 2022, 4:06 p.m. UTC | #4

Junio C Hamano <[e-mail]> wrote:

> True.  Unless we are going to revamp the text in some major way so
> that we produce "true" HTML, not just the text source enclosed in a
> <pre></pre> pair, I would think we are better off keeping it not
> passed to AsciiDoc and leaving it in text format.  After all, modern
> browsers, which I presume those who want HTML output files would
> read them with, can display plain text files just fine, don't they?

I am not sure whether that's a good idea or not. As I come from web
dev background, I know that people get bored if they need to read
a plain-text long article. SEO optimisation also need some beautiful
designing of articles so that people can spend more time with visual
ease.

Of course, git doesn't need any SEO optimisation as it is very much
popular. But readers want some visual satisfaction while reading
Docs. That's why some people complain about GNU sites (git's site is
beautiful by the way).

Obviously, here I am using `people` to refer non git developers who are
curious about git internals.

Thanks :)

Patch

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'}
 
@@ -48,9 +48,7 @@  MIDXs, both the bit-cache and rev-cache extensions are required.
 			of the bitmap index (the same one as JGit).
 
 		2-byte flags (network byte order)
-
 			The following flags are supported:
-
 			- BITMAP_OPT_FULL_DAG (0x1) REQUIRED
 			This flag must always be present. It implies that the
 			bitmap index has been generated for a packfile or
@@ -60,7 +58,6 @@  MIDXs, both the bit-cache and rev-cache extensions are required.
 			requirement for the bitmap index format, also present in
 			JGit, that greatly reduces the complexity of the
 			implementation.
-
 			- BITMAP_OPT_HASH_CACHE (0x4)
 			If present, the end of the bitmap file contains
 			`N` 32-bit name-hash values, one per object in the
@@ -68,15 +65,13 @@  MIDXs, both the bit-cache and rev-cache extensions are required.
 			described below.
 
 		4-byte entry count (network byte order)
-
 			The total count of entries (bitmapped commits) in this bitmap index.
 
 		20-byte checksum
-
 			The SHA1 checksum of the pack/MIDX this bitmap index
 			belongs to.
 
-	- 4 EWAH bitmaps that act as type indexes
+	* 4 EWAH bitmaps that act as type indexes
 
 		Type indexes are serialized after the hash cache in the shape
 		of four EWAH bitmaps stored consecutively (see Appendix A for
@@ -84,7 +79,6 @@  MIDXs, both the bit-cache and rev-cache extensions are required.
 
 		There is a bitmap for each Git object type, stored in the following
 		order:
-
 			- Commits
 			- Trees
 			- Blobs
@@ -97,17 +91,17 @@  MIDXs, both the bit-cache and rev-cache extensions are required.
 		in a full set (all bits set), and the AND of all 4 bitmaps will
 		result in an empty bitmap (no bits set).
 
-	- N entries with compressed bitmaps, one for each indexed commit
+	* N entries with compressed bitmaps, one for each indexed commit
 
 		Where `N` is the total amount of entries in this bitmap index.
 		Each entry contains the following:
 
-		- 4-byte object position (network byte order)
+		** 4-byte object position (network byte order)
 			The position **in the index for the packfile or
 			multi-pack index** where the bitmap for this commit is
 			found.
 
-		- 1-byte XOR-offset
+		** 1-byte XOR-offset
 			The xor offset used to compress this bitmap. For an entry
 			in position `x`, a XOR offset of `y` means that the actual
 			bitmap representing this commit is composed by XORing the
@@ -124,12 +118,12 @@  MIDXs, both the bit-cache and rev-cache extensions are required.
 			with **previous** bitmaps, not bitmaps that will come afterwards
 			in the index.
 
-		- 1-byte flags for this bitmap
+		** 1-byte flags for this bitmap
 			At the moment the only available flag is `0x1`, which hints
 			that this bitmap can be re-used when rebuilding bitmap indexes
 			for the repository.
 
-		- The compressed bitmap itself, see Appendix A.
+		** The compressed bitmap itself, see Appendix A.
 
 == Appendix A: Serialization format for an EWAH bitmap