| Message ID | cb919513c14d426b51051ee5c16badec37538032.1654623814.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | bitmap-format.txt: fix some formatting issues and include checksum info | expand |
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
Taylor Blau <me@ttaylorr.com> 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.
Taylor Blau <me@ttaylorr.com> 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 :)
Junio C Hamano <gitster@pobox.com> 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 :)
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