Subject: Re: [PATCH] docs: de-indent first paragraph of gitformat-* to flow the text

From: Junio C Hamano <[email-masked]>
Date: Tue, 22 Nov 2022 09:36:17 +0900

Ævar Arnfjörð Bjarmason  <[email-masked]> writes:

> Fix formatting issues with the documentation added to the new
> gitformat-* namespace in c0f6dd49f19 (Merge branch
> 'ab/tech-docs-to-help', 2022-08-14).

I think I saw you do this before, but please refrain from blaming a
merge UNLESS there is a regression between the tip of the topic
getting merged c0f6dd49f19^2 and the result of the merge c0f6dd49f19
as it is confusing.

>  === 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]

This makes the result awkward to read for those of us who consume
the text in the source form.  I do not think a one-time cost of
reindenting the whole paragraph (and reviewing the patch to do so)
outweighs the cost of burdening the readers with the awkwardness.