{"thread":{"id":"56899","subject":"[PATCH] midx: fix a formatting issue in \"multi-pack-index.txt\"","startedAt":"2021-11-15T06:33:58Z","lastAt":"2021-11-18T23:51:14Z","messageCount":8,"participants":["Teng Long","Derrick Stolee","Taylor Blau","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"441112","messageId":"20211115063318.14426-1-dyroneteng@gmail.com","threadId":"56899","inReplyTo":null,"subject":"[PATCH] midx: fix a formatting issue in \"multi-pack-index.txt\"","fromName":"Teng Long","fromEmail":"dyroneteng@gmail.com","sentAt":"2021-11-15T06:33:18Z","receivedAt":"2021-11-15T06:33:58Z","isPatch":true,"sender":{"key":"dyroneteng@gmail.com","avatar":"https://avatars.githubusercontent.com/u/7803958?v=4"},"body":"Signed-off-by: Teng Long \n---\n Documentation/technical/multi-pack-index.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/technical/multi-pack-index.txt\nindex fb688976c4..6b2b48f4ef 100644\n--- a/Documentation/technical/multi-pack-index.txt\n+++ b/Documentation/technical/multi-pack-index.txt\n@@ -20,8 +20,8 @@ and their offsets into multiple packfiles. It contains:\n - A list of packfile names.\n - A sorted list of object IDs.\n - A list of metadata for the ith object ID including:\n- - A value j referring to the jth packfile.\n- - An offset within the jth packfile for the object.\n+ * A value j referring to the jth packfile.\n+ * An offset within the jth packfile for the object.\n - If large offsets are required, we use another list of large\n offsets similar to version 2 pack-indexes.\n \n-- \n2.33.1.dirty\n\n"},{"id":"441147","messageId":"4ad06bc6-4f11-d6ef-ec95-ab0e9db9c2c7@gmail.com","threadId":"56899","inReplyTo":"20211115063318.14426-1-dyroneteng@gmail.com","subject":"Re: [PATCH] midx: fix a formatting issue in \"multi-pack-index.txt\"","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2021-11-15T16:25:56Z","receivedAt":"2021-11-15T16:26:40Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 11/15/2021 1:33 AM, Teng Long wrote:\n> Signed-off-by: Teng Long \n\nHi Teng,\n\nCould you spend some time in your commit message explaining what\nis wrong about the characters used for bullet points here?\n\n> - - A value j referring to the jth packfile.\n> - - An offset within the jth packfile for the object.\n> + * A value j referring to the jth packfile.\n> + * An offset within the jth packfile for the object.\n> - If large offsets are required, we use another list of large\n> offsets similar to version 2 pack-indexes.\n\nIs it that the indentation isn't enough to show a sublist? I see\nthat the HTML rendering on git-scm.com [1] does fail to show this\nsublist, and I could believe that this change would fix it (but I\nam not sure).\n\n[1] https://www.git-scm.com/docs/multi-pack-index\n\nThanks,\n-Stolee\n"},{"id":"441368","messageId":"YZQngLFWlns9HyoW@nand.local","threadId":"56899","inReplyTo":"4ad06bc6-4f11-d6ef-ec95-ab0e9db9c2c7@gmail.com","subject":"Re: [PATCH] midx: fix a formatting issue in \"multi-pack-index.txt\"","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2021-11-16T21:49:52Z","receivedAt":"2021-11-16T21:49:56Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Mon, Nov 15, 2021 at 11:25:56AM -0500, Derrick Stolee wrote:\n> On 11/15/2021 1:33 AM, Teng Long wrote:\n> > Signed-off-by: Teng Long \n>\n> Hi Teng,\n>\n> Could you spend some time in your commit message explaining what\n> is wrong about the characters used for bullet points here?\n>\n> > - - A value j referring to the jth packfile.\n> > - - An offset within the jth packfile for the object.\n> > + * A value j referring to the jth packfile.\n> > + * An offset within the jth packfile for the object.\n> > - If large offsets are required, we use another list of large\n> > offsets similar to version 2 pack-indexes.\n>\n> Is it that the indentation isn't enough to show a sublist?\n\nThat's it. ASCIIDoc doesn't treat an indented dash character as the\nbeginning of a sub-list. It will treat an indented asterisk as beginning\na sub-list, but only if the rest of the list items begin with a \"-\".\n\nIt might just be worth converting this whole thing to use what ASCIIDoc\nwould probably consider to be a more standard format, i.e.:\n\n * A list of packfile names.\n * A sorted list of object IDs.\n * A list of metadata for the ith object ID including:\n ** A value j referring to the jth packfile.\n ** An offset within the jth packfile for the object.\n * If large offsets are required, we use another list of large\n offsets similar to version 2 pack-indexes.\n\n> I see that the HTML rendering on git-scm.com [1] does fail to show\n> this sublist, and I could believe that this change would fix it (but I\n> am not sure).\n>\n> [1] https://www.git-scm.com/docs/multi-pack-index\n\nYeah, Teng's fix works just fine. So I'd be happy to see that picked up\n(with or without much additional explanation).\n\nThanks,\nTaylor\n"},{"id":"441560","messageId":"20211118033959.59881-1-dyroneteng@gmail.com","threadId":"56899","inReplyTo":"YZQngLFWlns9HyoW@nand.local","subject":"Re: [PATCH] midx: fix a formatting issue in \"multi-pack-index.txt\"","fromName":"Teng Long","fromEmail":"dyroneteng@gmail.com","sentAt":"2021-11-18T03:39:59Z","receivedAt":"2021-11-18T03:40:40Z","isPatch":true,"sender":{"key":"dyroneteng@gmail.com","avatar":"https://avatars.githubusercontent.com/u/7803958?v=4"},"body":"\nOn Mon, Tue, 16 Nov 2021 16:49:52 -0500, Taylor Blau wrote:\n\n> That's it. ASCIIDoc doesn't treat an indented dash character as the\n> beginning of a sub-list.\n\nThat's right.\n\n> It will treat an indented asterisk as beginning\n> a sub-list, but only if the rest of the list items begin with a \"-\".\n\nThere are some questions here.\nI think the indent is not needed for bulleted list in ASCIIDOC. If we\nwant to write a nested bulleted list, we could just use asterisks\nwithout any dashes like:\n\n\"\n* Level 1 list item\n** Level 2 list item\n*** Level 3 list item\n** Level 2 list item\n* Level 1 list item\n** Level 2 list item\n* Level 1 list item\n\"\n\nAnd the dashes are suggested only be used as the marker for the first\nlevel because the dash doesn’t work well or a best practice for nested\nlists, like (dash is as level 2):\n\n\"\n* Level 1 list item\n- Level 2 list item\n* Level 1 list item\n\"\n\nBut, if you are writting a non-nested bulleted lists, use dashes works\ntoo, like:\n\n\"\n- Level 1 list item\n- Level 1 list item\n- Level 1 list item\n\"\n\n> It might just be worth converting this whole thing to use what ASCIIDoc\n> would probably consider to be a more standard format, i.e.:\n>\n> * A list of packfile names.\n> * A sorted list of object IDs.\n> * A list of metadata for the ith object ID including:\n> ** A value j referring to the jth packfile.\n> ** An offset within the jth packfile for the object.\n> * If large offsets are required, we use another list of large\n> offsets similar to version 2 pack-indexes.\n\nI agree with you.\n\nThe asterisks are recommanded to use I think, it displays intuitively\nwhen writting ASCIIDOC lists (marker length = nesting level).\n\n> Yeah, Teng's fix works just fine. So I'd be happy to see that picked up\n> (with or without much additional explanation).\n\nI found it because I'm learning about the implements about the\nmulti-pack-index, reverse-index and multi-pack-bitmap, very nice\nfeature.\n\nPatch v2 will add more descriptions (Derrick Stolee suggested) in\ncommit message and will make the replacements from dashes to asterisks.\n\nFinally, thanks Derrick Stolee and Taylor Blau for the relies.\n\nReferences:\n[1] https://asciidoc-py.github.io/userguide.html#_bulleted_lists\n"},{"id":"441575","messageId":"cover.1637218943.git.dyroneteng@gmail.com","threadId":"56899","inReplyTo":"20211115063318.14426-1-dyroneteng@gmail.com","subject":"[PATCH v2 0/1] [PATCH] midx: fix a formatting issue in docs","fromName":"Teng Long","fromEmail":"dyroneteng@gmail.com","sentAt":"2021-11-18T07:11:13Z","receivedAt":"2021-11-18T07:13:04Z","isPatch":true,"sender":{"key":"dyroneteng@gmail.com","avatar":"https://avatars.githubusercontent.com/u/7803958?v=4"},"body":"Patch 2 contains the changes from the advices from Derrick Stolee\nand Taylor Blau:\n\n 1. More introductions in commit message.\n 2. Use asterisks instead of dashes in \"multi-pack-index.txt\".\n\n\nTeng Long (1):\n midx: fix a formatting issue in \"multi-pack-index.txt\"\n\n Documentation/technical/multi-pack-index.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\nRange-diff against v1:\n1: a7dc1980a7 < -: ---------- midx: fix a formatting issue in \"multi-pack-index.txt\"\n-: ---------- > 1: 9b910a44f4 midx: fix a formatting issue in \"multi-pack-index.txt\"\n-- \n2.33.1.9.g5fbd2fc599.dirty\n\n"},{"id":"441576","messageId":"9b910a44f4143c94787110a688f2b17ba4eeb0fc.1637218943.git.dyroneteng@gmail.com","threadId":"56899","inReplyTo":"cover.1637218943.git.dyroneteng@gmail.com","subject":"[PATCH v2 1/1] midx: fix a formatting issue in \"multi-pack-index.txt\"","fromName":"Teng Long","fromEmail":"dyroneteng@gmail.com","sentAt":"2021-11-18T07:11:14Z","receivedAt":"2021-11-18T07:13:11Z","isPatch":true,"sender":{"key":"dyroneteng@gmail.com","avatar":"https://avatars.githubusercontent.com/u/7803958?v=4"},"body":"There is a formatting issue in \"multi-pack-index.html\", corresponding\nto the nesting bulleted list of a wrong usage in \"multi-pack-index.txt\"\nand this commit fix the problem.\n\nIn ASCIIDOC, it doesn't treat an indented character as the\nbeginning of a sub-list. If we want to write a nested bulleted list, we\ncould just use ASTERISK without any DASH like:\n\n \"\n * Level 1 list item\n ** Level 2 list item\n *** Level 3 list item\n ** Level 2 list item\n * Level 1 list item\n ** Level 2 list item\n * Level 1 list item\n \"\n\nThe DASH can be used for bulleted list too, But the DASH is suggested\nonly to be used as the marker for the first level because the DASH\ndoesn’t work well or a best practice for nested lists,\nlike (dash is as level 2 below):\n\n \"\n * Level 1 list item\n - Level 2 list item\n * Level 1 list item\n \"\n\nASTERISK is recommanded to use because it works intuitively and clearly\n(\"marker length = nesting level\") in nested lists, but the DASH can't.\nHowever, when you want to write a non-nested bulleted lists, DASH works\ntoo, like:\n\n \"\n - Level 1 list item\n - Level 1 list item\n - Level 1 list item\n \"\n\nReviewed-by: Taylor Blau \nReviewed-by: Derrick Stolee \nSigned-off-by: Teng Long \n---\n Documentation/technical/multi-pack-index.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/technical/multi-pack-index.txt b/Documentation/technical/multi-pack-index.txt\nindex fb688976c4..642e2517f3 100644\n--- a/Documentation/technical/multi-pack-index.txt\n+++ b/Documentation/technical/multi-pack-index.txt\n@@ -17,12 +17,12 @@ is not feasible due to storage space or excessive repack times.\n The multi-pack-index (MIDX for short) stores a list of objects\n and their offsets into multiple packfiles. It contains:\n \n-- A list of packfile names.\n-- A sorted list of object IDs.\n-- A list of metadata for the ith object ID including:\n- - A value j referring to the jth packfile.\n- - An offset within the jth packfile for the object.\n-- If large offsets are required, we use another list of large\n+* A list of packfile names.\n+* A sorted list of object IDs.\n+* A list of metadata for the ith object ID including:\n+** A value j referring to the jth packfile.\n+** An offset within the jth packfile for the object.\n+* If large offsets are required, we use another list of large\n offsets similar to version 2 pack-indexes.\n \n Thus, we can provide O(log N) lookup time for any number\n-- \n2.33.1.9.g5fbd2fc599.dirty\n\n"},{"id":"441601","messageId":"072baa38-9155-f417-12fb-4a97280daa6d@gmail.com","threadId":"56899","inReplyTo":"9b910a44f4143c94787110a688f2b17ba4eeb0fc.1637218943.git.dyroneteng@gmail.com","subject":"Re: [PATCH v2 1/1] midx: fix a formatting issue in \"multi-pack-index.txt\"","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2021-11-18T12:16:32Z","receivedAt":"2021-11-18T12:16:42Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 11/18/2021 2:11 AM, Teng Long wrote:\n> There is a formatting issue in \"multi-pack-index.html\", corresponding\n> to the nesting bulleted list of a wrong usage in \"multi-pack-index.txt\"\n> and this commit fix the problem.\n\nThank you for the detailed message!\n\n> -- A list of packfile names.\n> -- A sorted list of object IDs.\n> -- A list of metadata for the ith object ID including:\n> - - A value j referring to the jth packfile.\n> - - An offset within the jth packfile for the object.\n> -- If large offsets are required, we use another list of large\n> +* A list of packfile names.\n> +* A sorted list of object IDs.\n> +* A list of metadata for the ith object ID including:\n> +** A value j referring to the jth packfile.\n> +** An offset within the jth packfile for the object.\n> +* If large offsets are required, we use another list of large\n> offsets similar to version 2 pack-indexes.\n\nLGTM!\n\nThanks,\n-Stolee\n"},{"id":"441677","messageId":"xmqq4k89uiol.fsf@gitster.g","threadId":"56899","inReplyTo":"9b910a44f4143c94787110a688f2b17ba4eeb0fc.1637218943.git.dyroneteng@gmail.com","subject":"Re: [PATCH v2 1/1] midx: fix a formatting issue in \"multi-pack-index.txt\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-11-18T23:51:06Z","receivedAt":"2021-11-18T23:51:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Teng Long writes:\n\n> There is a formatting issue in \"multi-pack-index.html\", corresponding\n> to the nesting bulleted list of a wrong usage in \"multi-pack-index.txt\"\n> and this commit fix the problem.\n\nThanks, will apply.\n\n"}]}