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

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 22, 2022, 00:36 UTC
Message-ID: <xmqqmt8ju8ou.fsf@gitster.g>
In-Reply-To: <patch-1.1-1c1434bba31-20221121T141411Z-avarab@gmail.com>

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> 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.

Show 13 quoted lines

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