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

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

On 11/15/2021 1:33 AM, Teng Long wrote:

quoted

Signed-off-by: Teng Long <redacted>

Hi Teng,

Could you spend some time in your commit message explaining what
is wrong about the characters used for bullet points here?

quoted

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