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

[Taylor Blau <me@ttaylorr.com>]

On Mon, Nov 15, 2021 at 11:25:56AM -0500, Derrick Stolee wrote:
> 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.

> 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