Re: [PATCH] midx: fix a formatting issue in "multi-pack-index.txt"

From: Taylor Blau <me@ttaylorr.com>
Date: Nov 16, 2021, 21:49 UTC
Message-ID: <YZQngLFWlns9HyoW@nand.local>
In-Reply-To: <4ad06bc6-4f11-d6ef-ec95-ab0e9db9c2c7@gmail.com>

On Mon, Nov 15, 2021 at 11:25:56AM -0500, Derrick Stolee wrote:

Show 16 quoted lines

> On 11/15/2021 1:33 AM, Teng Long wrote:
> > Signed-off-by: Teng Long <dyroneteng@gmail.com>
>
> Hi Teng,
>
> Could you spend some time in your commit message explaining what
> is wrong about the characters used for bullet points here?
>
> > -  - A value j referring to the jth packfile.
> > -  - An offset within the jth packfile for the object.
> > +  * A value j referring to the jth packfile.
> > +  * An offset within the jth packfile for the object.
> >  - If large offsets are required, we use another list of large
> >    offsets similar to version 2 pack-indexes.
>
> Is it that the indentation isn't enough to show a sublist?

That's it. ASCIIDoc doesn't treat an indented dash character as the beginning of a sub-list. It will treat an indented asterisk as beginning a sub-list, but only if the rest of the list items begin with a "-".

It might just be worth converting this whole thing to use what ASCIIDoc would probably consider to be a more standard format, i.e.:

    * A list of packfile names.
    * A sorted list of object IDs.
    * A list of metadata for the ith object ID including:
    ** A value j referring to the jth packfile.
    ** An offset within the jth packfile for the object.
    * If large offsets are required, we use another list of large
      offsets similar to version 2 pack-indexes.

Show 5 quoted lines

> I see that the HTML rendering on git-scm.com [1] does fail to show
> this sublist, and I could believe that this change would fix it (but I
> am not sure).
>
> [1] https://www.git-scm.com/docs/multi-pack-index

Yeah, Teng's fix works just fine. So I'd be happy to see that picked up (with or without much additional explanation).

Thanks, Taylor