| Message ID | 20211115063318.14426-1-dyroneteng@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | midx: fix a formatting issue in "multi-pack-index.txt" | expand |
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? 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 Thanks, -Stolee
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
On Mon, Tue, 16 Nov 2021 16:49:52 -0500, Taylor Blau wrote: > That's it. ASCIIDoc doesn't treat an indented dash character as the > beginning of a sub-list. That's right. > It will treat an indented asterisk as beginning > a sub-list, but only if the rest of the list items begin with a "-". There are some questions here. I think the indent is not needed for bulleted list in ASCIIDOC. If we want to write a nested bulleted list, we could just use asterisks without any dashes like: " * Level 1 list item ** Level 2 list item *** Level 3 list item ** Level 2 list item * Level 1 list item ** Level 2 list item * Level 1 list item " And the dashes are suggested only be used as the marker for the first level because the dash doesn’t work well or a best practice for nested lists, like (dash is as level 2): " * Level 1 list item - Level 2 list item * Level 1 list item " But, if you are writting a non-nested bulleted lists, use dashes works too, like: " - Level 1 list item - Level 1 list item - Level 1 list item " > 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 agree with you. The asterisks are recommanded to use I think, it displays intuitively when writting ASCIIDOC lists (marker length = nesting level). > Yeah, Teng's fix works just fine. So I'd be happy to see that picked up > (with or without much additional explanation). I found it because I'm learning about the implements about the multi-pack-index, reverse-index and multi-pack-bitmap, very nice feature. Patch v2 will add more descriptions (Derrick Stolee suggested) in commit message and will make the replacements from dashes to asterisks. Finally, thanks Derrick Stolee and Taylor Blau for the relies. References: [1] https://asciidoc-py.github.io/userguide.html#_bulleted_lists
diff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/technical/multi-pack-index.txt index fb688976c4..6b2b48f4ef 100644 --- a/Documentation/technical/multi-pack-index.txt +++ b/Documentation/technical/multi-pack-index.txt @@ -20,8 +20,8 @@ and their offsets into multiple packfiles. It contains: - 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. + * 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.
Signed-off-by: Teng Long <dyroneteng@gmail.com> --- Documentation/technical/multi-pack-index.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)