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

["SZEDER Gábor" <szeder.dev@gmail.com>]

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.

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