{"thread":{"id":"65467","subject":"[PATCH] gitglossary: fix indentation of sub-lists","startedAt":"2026-04-11T19:06:27Z","lastAt":"2026-04-12T19:57:04Z","messageCount":7,"participants":["Jeff King","Kristoffer Haugsbakk"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"541426","messageId":"20260411190625.GA754966@coredump.intra.peff.net","threadId":"65467","inReplyTo":null,"subject":"[PATCH] gitglossary: fix indentation of sub-lists","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-04-11T19:06:25Z","receivedAt":"2026-04-11T19:06:27Z","isPatch":true,"body":"The glossary entry is a list of terms and their definitions, so\nmulti-paragraph definitions need \"+\" continuation lines to indicate\nthat they are part of a single entry.\n\nWhen an entry contains a sub-list (say, a bulleted list), the final \"+\"\nmay become ambiguous: is it connecting the next paragraph to the final\nentry of the sub-list, or to the original list of definition paragraphs?\n\nAsciidoc generally connects it to the former, even when we mean the\nlatter, and you end up with the next paragraph indented incorrectly,\nlike this:\n\n  glob\n    ...defines glob...\n\n    Two consecutive asterisks (\"**\") in patterns matched\n    against full pathname may have special meaning:\n\n    - ...some special meaning of **...\n\n    - ...another special meaning of **...\n\n    - Other consecutive asterisks are considered invalid.\n\n      Glob magic is incompatible with literal magic.\n\nThat final \"Glob magic is incompatible\" paragraph is in the wrong spot.\nIt should be at the same level as \"Two consecutive asterisks\", as it is\nnot part of the final \"Other consecutive asterisks\" bullet point.\n\nThe same problem appears in several other spots in the glossary.\n\nWe can fix this by using \"--\" markers, which put the sub-list into its\nown block. This should catch all of the unordered lists in the glossary,\nwhich I found by grepping for \" -\" list markers.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\nJust happened to notice this while looking at the \"ref\" entry.\n\n Documentation/glossary-content.adoc | 12 ++++++++++--\n 1 file changed, 10 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc\nindex 20ba121314..8967e89ece 100644\n--- a/Documentation/glossary-content.adoc\n+++ b/Documentation/glossary-content.adoc\n@@ -415,7 +415,8 @@ glob;;\n +\n Two consecutive asterisks (\"`**`\") in patterns matched against\n full pathname may have special meaning:\n-\n++\n+--\n  - A leading \"`**`\" followed by a slash means match in all\n    directories. For example, \"`**/foo`\" matches file or directory\n    \"`foo`\" anywhere. \"`**/foo/bar`\" matches file or directory \"`bar`\"\n@@ -430,6 +431,7 @@ full pathname may have special meaning:\n    matches \"`a/b`\", \"`a/x/b`\", \"`a/x/y/b`\" and so on.\n \n  - Other consecutive asterisks are considered invalid.\n+--\n +\n Glob magic is incompatible with literal magic.\n \n@@ -442,7 +444,8 @@ See linkgit:gitattributes[5].\n +\n Each of the attribute requirements for the path takes one of\n these forms:\n-\n++\n+--\n - \"`ATTR`\" requires that the attribute `ATTR` be set.\n \n - \"`-ATTR`\" requires that the attribute `ATTR` be unset.\n@@ -452,6 +455,7 @@ these forms:\n \n - \"`!ATTR`\" requires that the attribute `ATTR` be\n   unspecified.\n+--\n +\n Note that when matching against a tree object, attributes are still\n obtained from working tree, not from the given tree object.\n@@ -560,14 +564,17 @@ The ref namespace is hierarchical.\n Ref names must either start with `refs/` or be located in the root of\n the hierarchy. For the latter, their name must follow these rules:\n +\n+--\n  - The name consists of only upper-case characters or underscores.\n \n  - The name ends with \"`_HEAD`\" or is equal to \"`HEAD`\".\n+--\n +\n There are some irregular refs in the root of the hierarchy that do not\n match these rules. The following list is exhaustive and shall not be\n extended in the future:\n +\n+--\n  - `AUTO_MERGE`\n \n  - `BISECT_EXPECTED_REV`\n@@ -577,6 +584,7 @@ extended in the future:\n  - `NOTES_MERGE_REF`\n \n  - `MERGE_AUTOSTASH`\n+--\n +\n Different subhierarchies are used for different purposes. For example,\n the `refs/heads/` hierarchy is used to represent local branches whereas\n-- \n2.54.0.rc1.279.g55df28c202\n"},{"id":"541431","messageId":"fb4dff1b-d304-4f29-a96c-373b1a73989b@app.fastmail.com","threadId":"65467","inReplyTo":"20260411190625.GA754966@coredump.intra.peff.net","subject":"Re: [PATCH] gitglossary: fix indentation of sub-lists","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-11T20:34:27Z","receivedAt":"2026-04-11T20:34:49Z","isPatch":true,"body":"On Sat, Apr 11, 2026, at 21:06, Jeff King wrote:\n> The glossary entry is a list of terms and their definitions, so\n> multi-paragraph definitions need \"+\" continuation lines to indicate\n> that they are part of a single entry.\n>\n> When an entry contains a sub-list (say, a bulleted list), the final \"+\"\n> may become ambiguous: is it connecting the next paragraph to the final\n> entry of the sub-list, or to the original list of definition paragraphs?\n>\n> Asciidoc generally connects it to the former, even when we mean the\n> latter, and you end up with the next paragraph indented incorrectly,\n> like this:\n>\n>   glob\n>     ...defines glob...\n>\n>     Two consecutive asterisks (\"**\") in patterns matched\n>     against full pathname may have special meaning:\n>\n>     - ...some special meaning of **...\n>\n>     - ...another special meaning of **...\n>\n>     - Other consecutive asterisks are considered invalid.\n>\n>       Glob magic is incompatible with literal magic.\n>\n> That final \"Glob magic is incompatible\" paragraph is in the wrong spot.\n> It should be at the same level as \"Two consecutive asterisks\", as it is\n> not part of the final \"Other consecutive asterisks\" bullet point.\n\n`Documentation/doc-diff` confirms that this is the effect of this change.\n\n>\n> The same problem appears in several other spots in the glossary.\n\nAnd that it is the effect for all the other spots at as well: pull a\nparagraph out of a bullet list back to the previous block (or level).\n\n> We can fix this by using \"--\" markers, which put the sub-list into its\n> own block. This should catch all of the unordered lists in the glossary,\n> which I found by grepping for \" -\" list markers.\n\nYes, for what it’s worth I think open blocks (`--`) are a great cure for\nthis when you are lucky enough to not already be in an open block.\n\nAsciiDoc is certainly a format.\n\n>\n> Signed-off-by: Jeff King <peff@peff.net>\n> ---\n> Just happened to notice this while looking at the \"ref\" entry.\n>\n>  Documentation/glossary-content.adoc | 12 ++++++++++--\n>  1 file changed, 10 insertions(+), 2 deletions(-)\n>[snip]\n"},{"id":"541432","messageId":"236b32a3-a04b-4d20-8290-02a464037b1d@app.fastmail.com","threadId":"65467","inReplyTo":"fb4dff1b-d304-4f29-a96c-373b1a73989b@app.fastmail.com","subject":"Re: [PATCH] gitglossary: fix indentation of sub-lists","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-11T20:47:34Z","receivedAt":"2026-04-11T20:47:56Z","isPatch":true,"body":"On Sat, Apr 11, 2026, at 22:34, Kristoffer Haugsbakk wrote:\n> On Sat, Apr 11, 2026, at 21:06, Jeff King wrote:\n>>[snip]\n>\n> `Documentation/doc-diff` confirms that this is the effect of this change.\n>\n>>\n>> The same problem appears in several other spots in the glossary.\n>\n> And that it is the effect for all the other spots at as well: pull a\n> paragraph out of a bullet list back to the previous block (or level).\n>\n\nBut with `make html` there are some `+` artifacts:\n\n    + Glob magic is incompatible with literal magic.\n    [...]\n    + Note that when matching against a tree object, attributes are [...]\n\nThis is very off the cuff since I have to go now. So I might be missing\nsomething/made a mistake.\n\nI think the first thing is caused by the context already being in an\nopen block?\n\n>[snip]\n"},{"id":"541433","messageId":"20260411214213.GA1563438@coredump.intra.peff.net","threadId":"65467","inReplyTo":"236b32a3-a04b-4d20-8290-02a464037b1d@app.fastmail.com","subject":"Re: [PATCH] gitglossary: fix indentation of sub-lists","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-04-11T21:42:13Z","receivedAt":"2026-04-11T21:42:14Z","isPatch":true,"body":"On Sat, Apr 11, 2026 at 10:47:34PM +0200, Kristoffer Haugsbakk wrote:\n\n> But with `make html` there are some `+` artifacts:\n> \n>     + Glob magic is incompatible with literal magic.\n>     [...]\n>     + Note that when matching against a tree object, attributes are [...]\n> \n> This is very off the cuff since I have to go now. So I might be missing\n> something/made a mistake.\n\nHmm, I don't see that in the HTML when I build with asciidoc. But if I\nbuild with asciidoctor, I see it both in the HTML and in the doc-diff\noutput. Yuck.\n\n> I think the first thing is caused by the context already being in an\n> open block?\n\nYes. Looks like asciidoc learned to handle nested entries better, but\nperhaps asciidoctor didn't.\n\nI think I've found a workaround, which I'll post in a moment. Thanks for\nreporting.\n\n-Peff\n"},{"id":"541434","messageId":"20260411215518.GA1651019@coredump.intra.peff.net","threadId":"65467","inReplyTo":"20260411214213.GA1563438@coredump.intra.peff.net","subject":"[PATCH v2] gitglossary: fix indentation of sub-lists","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-04-11T21:55:18Z","receivedAt":"2026-04-11T21:55:20Z","isPatch":true,"body":"On Sat, Apr 11, 2026 at 05:42:13PM -0400, Jeff King wrote:\n\n> > I think the first thing is caused by the context already being in an\n> > open block?\n> \n> Yes. Looks like asciidoc learned to handle nested entries better, but\n> perhaps asciidoctor didn't.\n> \n> I think I've found a workaround, which I'll post in a moment. Thanks for\n> reporting.\n\nHere it is.\n\n-- >8 --\nSubject: [PATCH] gitglossary: fix indentation of sub-lists\n\nThe glossary entry is a list of terms and their definitions, so\nmulti-paragraph definitions need \"+\" continuation lines to indicate\nthat they are part of a single entry.\n\nWhen an entry contains a sub-list (say, a bulleted list), the final \"+\"\nmay become ambiguous: is it connecting the next paragraph to the final\nentry of the sub-list, or to the original list of definition paragraphs?\n\nAsciidoc generally connects it to the former, even when we mean the\nlatter, and you end up with the next paragraph indented incorrectly,\nlike this:\n\n  glob\n    ...defines glob...\n\n    Two consecutive asterisks (\"**\") in patterns matched\n    against full pathname may have special meaning:\n\n    - ...some special meaning of **...\n\n    - ...another special meaning of **...\n\n    - Other consecutive asterisks are considered invalid.\n\n      Glob magic is incompatible with literal magic.\n\nThat final \"Glob magic is incompatible\" paragraph is in the wrong spot.\nIt should be at the same level as \"Two consecutive asterisks\", as it is\nnot part of the final \"Other consecutive asterisks\" bullet point.\n\nThe same problem appears in several other spots in the glossary.\n\nUsually we'd fix this by using \"--\" markers, which put the sub-list into\nits own block. But there's a catch: in some of these spots we are\nalready in an open block, and nesting open blocks is a problem. It seems\nto work for me using Asciidoc 10.2.1, but Asciidoctor 2.0.26 makes a\nmess of it (our intent to open a new block seems to close the old one).\n\nFortunately there's a work-around: when using a \"+\" list-continuation,\nthe number of empty lines above the continuation indicates which level\nof parent list to continue. So by adding an empty line after our\nunordered list (before the \"+\"), we should be able to continue the\ndefinition list item.\n\nBut asciidoc being asciidoc, of course that is not the end of the story.\nThat technique works fine for the \"glob\" and \"attr\" lists in this patch,\nbut under the \"refs\" item it works for only 1 of the 2 lists! I can't\nfigure out why, and this may be an asciidoctor bug. But we can work\naround it by using \"--\" open-block markers here, since we're not\nalready in an open block.\n\nSo using the extra blank line for the first two instances, and \"--\"\nmarkers for the second two, this patch produces identical output from\n\"doc-diff HEAD^ HEAD\" for both --asciidoctor and --ascii modes.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Documentation/glossary-content.adoc | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc\nindex 20ba121314..8c4e9dd3be 100644\n--- a/Documentation/glossary-content.adoc\n+++ b/Documentation/glossary-content.adoc\n@@ -430,6 +430,7 @@ full pathname may have special meaning:\n    matches \"`a/b`\", \"`a/x/b`\", \"`a/x/y/b`\" and so on.\n \n  - Other consecutive asterisks are considered invalid.\n+\n +\n Glob magic is incompatible with literal magic.\n \n@@ -452,6 +453,7 @@ these forms:\n \n - \"`!ATTR`\" requires that the attribute `ATTR` be\n   unspecified.\n+\n +\n Note that when matching against a tree object, attributes are still\n obtained from working tree, not from the given tree object.\n@@ -560,14 +562,17 @@ The ref namespace is hierarchical.\n Ref names must either start with `refs/` or be located in the root of\n the hierarchy. For the latter, their name must follow these rules:\n +\n+--\n  - The name consists of only upper-case characters or underscores.\n \n  - The name ends with \"`_HEAD`\" or is equal to \"`HEAD`\".\n+--\n +\n There are some irregular refs in the root of the hierarchy that do not\n match these rules. The following list is exhaustive and shall not be\n extended in the future:\n +\n+--\n  - `AUTO_MERGE`\n \n  - `BISECT_EXPECTED_REV`\n@@ -577,6 +582,7 @@ extended in the future:\n  - `NOTES_MERGE_REF`\n \n  - `MERGE_AUTOSTASH`\n+--\n +\n Different subhierarchies are used for different purposes. For example,\n the `refs/heads/` hierarchy is used to represent local branches whereas\n-- \n2.54.0.rc1.336.g4588871dc4\n\n"},{"id":"541436","messageId":"ee8d43cc-c38b-4a55-8237-94f92034d62f@app.fastmail.com","threadId":"65467","inReplyTo":"20260411215518.GA1651019@coredump.intra.peff.net","subject":"Re: [PATCH v2] gitglossary: fix indentation of sub-lists","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2026-04-12T09:10:34Z","receivedAt":"2026-04-12T09:10:56Z","isPatch":true,"body":"On Sat, Apr 11, 2026, at 23:55, Jeff King wrote:\n> On Sat, Apr 11, 2026 at 05:42:13PM -0400, Jeff King wrote:\n>\n>> > I think the first thing is caused by the context already being in an\n>> > open block?\n>>\n>> Yes. Looks like asciidoc learned to handle nested entries better, but\n>> perhaps asciidoctor didn't.\n>>\n>> I think I've found a workaround, which I'll post in a moment. Thanks for\n>> reporting.\n>\n> Here it is.\n>\n> -- >8 --\n> Subject: [PATCH] gitglossary: fix indentation of sub-lists\n>\n>[snip]\n>\n> Usually we'd fix this by using \"--\" markers, which put the sub-list into\n> its own block. But there's a catch: in some of these spots we are\n> already in an open block, and nesting open blocks is a problem. It seems\n> to work for me using Asciidoc 10.2.1, but Asciidoctor 2.0.26 makes a\n> mess of it (our intent to open a new block seems to close the old one).\n>\n> Fortunately there's a work-around: when using a \"+\" list-continuation,\n> the number of empty lines above the continuation indicates which level\n> of parent list to continue. So by adding an empty line after our\n> unordered list (before the \"+\"), we should be able to continue the\n> definition list item.\n\nNice.\n\n>\n> But asciidoc being asciidoc, of course that is not the end of the story.\n\nOuch.\n\n> That technique works fine for the \"glob\" and \"attr\" lists in this patch,\n> but under the \"refs\" item it works for only 1 of the 2 lists! I can't\n> figure out why, and this may be an asciidoctor bug. But we can work\n\nYou mention “asciidoc being asciidoc” but here it seems to be\nabout Asciidoctor?\n\n> around it by using \"--\" open-block markers here, since we're not\n> already in an open block.\n>\n> So using the extra blank line for the first two instances, and \"--\"\n> markers for the second two, this patch produces identical output from\n> \"doc-diff HEAD^ HEAD\" for both --asciidoctor and --ascii modes.\n\nNit: s/--ascii/--asciidoc/\n\n>\n> Signed-off-by: Jeff King <peff@peff.net>\n> ---\n>[snip]\n"},{"id":"541446","messageId":"20260412195656.GA1691477@coredump.intra.peff.net","threadId":"65467","inReplyTo":"ee8d43cc-c38b-4a55-8237-94f92034d62f@app.fastmail.com","subject":"Re: [PATCH v2] gitglossary: fix indentation of sub-lists","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2026-04-12T19:56:56Z","receivedAt":"2026-04-12T19:57:04Z","isPatch":true,"body":"On Sun, Apr 12, 2026 at 11:10:34AM +0200, Kristoffer Haugsbakk wrote:\n\n> > But asciidoc being asciidoc, of course that is not the end of the story.\n> \n> Ouch.\n> \n> > That technique works fine for the \"glob\" and \"attr\" lists in this patch,\n> > but under the \"refs\" item it works for only 1 of the 2 lists! I can't\n> > figure out why, and this may be an asciidoctor bug. But we can work\n> \n> You mention “asciidoc being asciidoc” but here it seems to be\n> about Asciidoctor?\n\nIt is. I meant \"asciidoc the language\", not \"asciidoc the tool\". I\ndidn't want to be too harsh on asciidoctor specifically. I think in\naggregate the pain comes equally from both tools. ;)\n\n> > So using the extra blank line for the first two instances, and \"--\"\n> > markers for the second two, this patch produces identical output from\n> > \"doc-diff HEAD^ HEAD\" for both --asciidoctor and --ascii modes.\n> \n> Nit: s/--ascii/--asciidoc/\n\nOops, yes.\n\n-Peff\n"}]}