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

From: Jeff King <peff@peff.net>
Date: Nov 21, 2022, 17:59 UTC
Message-ID: <Y3u8mzT6UN9DoOB7@coredump.intra.peff.net>
In-Reply-To: <patch-1.1-1c1434bba31-20221121T141411Z-avarab@gmail.com>

On Mon, Nov 21, 2022 at 03:15:50PM +0100, Ævar Arnfjörð Bjarmason wrote:

Show 6 quoted lines

> But the end result of having some paragraphs use "<p>" in the HTML
> output, and to have others wrapped in "<pre><code>" doesn't look
> nice. The most minimal way to fix this is to de-indent the opening
> line of paragraphs that don't start with another formatting
> element (e.g. "*" or "-" would already format them as text). Let's do
> that.

Is there any reason to just touch the opening line of the paragraphs, and not change the indent of the whole thing? I understand that doing the first line is sufficient to convince asciidoc to do what we want, and the diff is technically fewer lines, but the result is rather confusing for people who will work on the source in the future.

> There's a lot more to fix in these gitformat-* docs (as their
> formatting was funny before), but this is a minimal change to fix the
> most major issues.

I briefly looked at doc-diff output here. Most of them looked obviously correct (though since there isn't a lot of context in the doc-diff, it's sometimes hard to tell), but a few were questionable:

Show 8 quoted lines

> @@ -103,7 +103,7 @@ Git index format
>  
>    Object name for the represented object
>  
> -  A 16-bit 'flags' field split into (high to low bits)
> +A 16-bit 'flags' field split into (high to low bits)
>  
>      1-bit assume-valid flag

This puts "A 16-bit flags field" at a different indent than the paragraph before, but I think it is part of a list. It is less indented than the follow-on paragraph ("1-bit assume-valid flag"), but I think that is correct, as it is a sub-list of the 16-bit flags.

I know you said that formatting problems remain, and certainly this was not right before your patch either. But I think your patch makes it worse, because it pulls the touched line out of the list (and all of the adjacent parts are still rendered as code blocks, making the structure even less clear).

Show 9 quoted lines

> @@ -114,7 +114,7 @@ Git index format
>      12-bit name length if the length is less than 0xFFF; otherwise 0xFFF
>      is stored in this field.
>  
> -  (Version 3 or later) A 16-bit field, only applicable if the
> +(Version 3 or later) A 16-bit field, only applicable if the
>    "extended flag" above is 1, split into (high to low bits).
>  
>      1-bit reserved for future

This is the same (it's the same list).

Show 9 quoted lines

> @@ -125,16 +125,16 @@ Git index format
>  
>      13-bit unused, must be zero
>  
> -  Entry path name (variable length) relative to top level directory
> +Entry path name (variable length) relative to top level directory
>      (without leading slash). '/' is used as path separator. The special
>      path components ".", ".." and ".git" (without quotes) are disallowed.
>      Trailing slash is also disallowed.

And I think this is supposed to be part of that same list, too, but now is de-dented.

> -    The exact encoding is undefined, but the '.' and '/' characters
> +The exact encoding is undefined, but the '.' and '/' characters
>      are encoded in 7-bit ASCII and the encoding cannot contain a NUL
>      byte (iow, this is a UNIX pathname).

This is supposed to be a continuation of the earlier "Entry path name" item, but now is at the same top-level. Which is not right, but arguably is not worse than before your patch.

Show 6 quoted lines

>  
> -  (Version 4) In version 4, the entry path name is prefix-compressed
> +(Version 4) In version 4, the entry path name is prefix-compressed
>      relative to the path name for the previous entry (the very first
>      entry is encoded as if the path name for the previous entry is an
>      empty string).  At the beginning of an entry, an integer N in the

And this one is another top-level part of the list.

Show 12 quoted lines

> --- a/Documentation/gitformat-pack.txt
> +++ b/Documentation/gitformat-pack.txt
> @@ -294,10 +294,10 @@ Pack file entry: <+
>  
>    - The same trailer as a v1 pack file:
>  
> -    A copy of the pack checksum at the end of
> +A copy of the pack checksum at the end of
>      corresponding packfile.
>  
> -    Index checksum of all of the above.
> +Index checksum of all of the above.

These are supposed to be list items of "The same trailer as..." above. Now they're de-dented, which I think is worse than the state before your patch.

I don't want to say "we must fix all format problems at once", but I think in the cases I pointed out that trying to fix the code-block problem is a losing battle, because the list-like nature is being made worse. And they probably should remain untouched until somebody is willing to turn them into actual list elements and continuation markers.

-Peff