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

From: SZEDER Gábor <szeder.dev@gmail.com>
Date: Nov 8, 2022, 21:27 UTC
Message-ID: <20221108212741.GC1731@szeder.dev>
In-Reply-To: <221108.86mt91qmkq.gmgdl@evledraar.gmail.com>

On Tue, Nov 08, 2022 at 08:16:49PM +0100, Ævar Arnfjörð Bjarmason wrote:

Show 20 quoted lines

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

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