Re: [PATCH v8 06/12] docs: move commit-graph format docs to man section 5

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Nov 9, 2022, 01:34 UTC
Message-ID: <221109.86bkpgriso.gmgdl@evledraar.gmail.com>
In-Reply-To: <20221108212741.GC1731@szeder.dev>

On Tue, Nov 08 2022, SZEDER Gábor wrote:

Show 43 quoted lines

> On Tue, Nov 08, 2022 at 08:16:49PM +0100, Ævar Arnfjörð Bjarmason wrote:
>> 
>> On Tue, Nov 08 2022, SZEDER Gábor wrote:
>> 
>> > On Thu, Aug 04, 2022 at 06:28:35PM +0200, Ævar Arnfjörð Bjarmason wrote:
>> >> Continue the move of existing Documentation/technical/* protocol and
>> >> file-format documentation into our main documentation space.
>> >> 
>> >> By moving the documentation for the commit-graph format into man
>> >> section 5 and the new "developerinterfaces" category. This change is
>> >> split from subsequent commits due to the relatively large amount of
>> >> ASCIIDOC formatting changes that are required.
>> >
>> > So after this series I got a couple of gitformat-* manpages, but,
>> > alas, most of them render improperly: a lot of paragraphs are for some
>> > reason fixed width even in a fullscreen terminal window, and their
>> > width is more than 80 chars, so they are rather awkward in a
>> > standard-width terminal.  This also affects the html version, where
>> > those paragraphs are rendered with a fixed-width font.
>> 
>> Do you have examples of that
>
> Here's the description of two chunks copy-pasted from 'man
> gitformat-commit-graph' in a full-screen terminal, the first being
> properly formatted (i.e. line length adjusted to the width of the
> terminal), the latter having fixed-width:
>
>        Generation Data Overflow (ID: {G, D, O, 2 }) [Optional]
>            •   This list of 8-byte values stores the corrected commit date offsets for commits with corrected commit date offsets that cannot be stored within 31 bits.
>
>            •   Generation Data Overflow chunk is present only when Generation Data chunk is present and atleast one corrected commit date offset cannot be stored within 31 bits.
>
>        Extra Edge List (ID: {E, D, G, E}) [Optional]
>                This list of 4-byte values store the second through nth parents for
>                all octopus merges. The second parent value in the commit data stores
>                an array position within this list along with the most-significant bit
>                on. Starting at that array position, iterate through this list of commit
>                positions for the parents until reaching a value with the most-significant
>                bit on. The other bits correspond to the position of the last parent.
>
> There are similar formating issues in 'gitformat-index' and
> 'gitformat-pack' as well.  I can see these both with AsciiDoc and
> Asciidoctor.

Yeah, they look pretty bad.

Show 8 quoted lines

>> and are these cases where the formatting
>> was different before the move from Documentation/technical/*
>> 
>> I'm aware of e.g. gitformat-commit-graph(5) being somewhat funny, and
>> may have missed some cases, but I think that was also the case before...
>
> I'm not sure about "before", because 'make man' never built and
> installed these gitformat-* manpages before this series.

In the case of "gitformat-commit-graph" there was never a "html" version
of it before c0f6dd49f19 (Merge branch 'ab/tech-docs-to-help',
2022-08-14). But if you check out c0f6dd49f19^1 and:
	
	diff --git a/Documentation/Makefile b/Documentation/Makefile
	index 4f801f4e4c9..d7a066a68d0 100644
	--- a/Documentation/Makefile
	+++ b/Documentation/Makefile
	@@ -96,6 +96,7 @@ TECH_DOCS += SubmittingPatches
	 TECH_DOCS += ToolsForGit
	 TECH_DOCS += technical/bitmap-format
	 TECH_DOCS += technical/bundle-format
	+TECH_DOCS += technical/commit-graph-format
	 TECH_DOCS += technical/cruft-packs
	 TECH_DOCS += technical/hash-function-transition
	 TECH_DOCS += technical/http-protoco

Then "make html" you'll see what the formatting was like before. Here's generated versions of those & git-scm.com's version for comparison:

	https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/commit-graph-format.html
	https://git-scm.com/docs/gitformat-commit-graph
        https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/index-format.html
	https://git-scm.com/docs/gitformat-index
        https://vm.nix.is/~avar/noindex/2022-11-09-gitdocs/pack-format.html
        https://git-scm.com/docs/gitformat-pack

They should obviously be fixed, but I left that out of scope of that series. If it was a fix-syntax-nits-while-at-it it would have been a lot longer, and some of it's in some pseudo-syntax that was never quite valid markdown. E.g. commit-graph-format.txt tried to use link:* syntax in block-quoted text.

What I found *mostly* worked was to use "==" for sections, which e.g. for gitformat-commit-graph ends up formatting it nicely as long as it's followed by a bullet-point list, but as you show with "This lits of 4-byte..." that doesn't do the trick when it's not a list, instead it uses the literal formatting (which almost the entire body of the text used before).

I think the most minimal way of fixing it is to de-indent the opening
line of those sections, e.g.:

diff --git a/Documentation/gitformat-commit-graph.txt b/Documentation/gitformat-commit-graph.txt
index 31cad585e23..84df4a3ed03 100644
--- a/Documentation/gitformat-commit-graph.txt
+++ b/Documentation/gitformat-commit-graph.txt
@@ -67,17 +67,17 @@ All multi-byte numbers are in network byte order.

=== CHUNK LOOKUP:

- (C + 1) * 12 bytes listing the table of contents for the chunks:
+(C + 1) * 12 bytes listing the table of contents for the chunks:
First 4 bytes describe the chunk id. Value 0 is a terminating label.
Other 8 bytes provide the byte-offset in current file for chunk to
start. (Chunks are ordered contiguously in the file, so you can infer
the length using the next chunk position if necessary.) Each chunk
ID appears at most once.

- The CHUNK LOOKUP matches the table of contents from
+The CHUNK LOOKUP matches the table of contents from
the chunk-based file format, see linkgit:gitformat-chunk[5]

- The remaining data in the body is described one chunk at a time, and
+The remaining data in the body is described one chunk at a time, and
these chunks may be given in any order. Chunks are required unless
otherwise specified.

@@ -126,7 +126,7 @@ All multi-byte numbers are in network byte order.
be stored within 31 bits.

==== Extra Edge List (ID: {'E', 'D', 'G', 'E'}) [Optional]
- This list of 4-byte values store the second through nth parents for
+This list of 4-byte values store the second through nth parents for
all octopus merges. The second parent value in the commit data stores
an array position within this list along with the most-significant bit
on. Starting at that array position, iterate through this list of commit

Seems to fix those "flow" issues for me, i.e. it's now a normal
paragraph, instead of a block-quoted fixed-width text.