git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v2] gitglossary: fix indentation of sub-lists

From
Jeff King <peff@peff.net>
Date
Apr 11, 2026, 21:55 UTC
Message-ID
<20260411215518.GA1651019@coredump.intra.peff.net>
In-Reply-To
<20260411214213.GA1563438@coredump.intra.peff.net>
On Sat, Apr 11, 2026 at 05:42:13PM -0400, Jeff King wrote:
Show 8 quoted lines
> > I think the first thing is caused by the context already being in an
> > open block?
> 
> Yes. Looks like asciidoc learned to handle nested entries better, but
> perhaps asciidoctor didn't.
> 
> I think I've found a workaround, which I'll post in a moment. Thanks for
> reporting.
Here it is.
-- >8 --
Subject: [PATCH] gitglossary: fix indentation of sub-lists

The glossary entry is a list of terms and their definitions, so multi-paragraph definitions need "+" continuation lines to indicate that they are part of a single entry.

When an entry contains a sub-list (say, a bulleted list), the final "+" may become ambiguous: is it connecting the next paragraph to the final entry of the sub-list, or to the original list of definition paragraphs?

Asciidoc generally connects it to the former, even when we mean the latter, and you end up with the next paragraph indented incorrectly, like this:

  glob
    ...defines glob...
    Two consecutive asterisks ("**") in patterns matched
    against full pathname may have special meaning:
    - ...some special meaning of **...
    - ...another special meaning of **...
    - Other consecutive asterisks are considered invalid.
      Glob magic is incompatible with literal magic.

That final "Glob magic is incompatible" paragraph is in the wrong spot. It should be at the same level as "Two consecutive asterisks", as it is not part of the final "Other consecutive asterisks" bullet point.

The same problem appears in several other spots in the glossary.

Usually we'd fix this by using "--" markers, which put the sub-list into its own block. But there's a catch: in some of these spots we are already in an open block, and nesting open blocks is a problem. It seems to work for me using Asciidoc 10.2.1, but Asciidoctor 2.0.26 makes a mess of it (our intent to open a new block seems to close the old one).

Fortunately there's a work-around: when using a "+" list-continuation, the number of empty lines above the continuation indicates which level of parent list to continue. So by adding an empty line after our unordered list (before the "+"), we should be able to continue the definition list item.

But asciidoc being asciidoc, of course that is not the end of the story. That technique works fine for the "glob" and "attr" lists in this patch, but under the "refs" item it works for only 1 of the 2 lists! I can't figure out why, and this may be an asciidoctor bug. But we can work around it by using "--" open-block markers here, since we're not already in an open block.

So using the extra blank line for the first two instances, and "--" markers for the second two, this patch produces identical output from "doc-diff HEAD^ HEAD" for both --asciidoctor and --ascii modes.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/glossary-content.adoc | 6 ++++++
 1 file changed, 6 insertions(+)
diff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc
index 20ba121314..8c4e9dd3be 100644
--- a/Documentation/glossary-content.adoc
+++ b/Documentation/glossary-content.adoc
@@ -430,6 +430,7 @@ full pathname may have special meaning:
    matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on.
 
  - Other consecutive asterisks are considered invalid.
+
 +
 Glob magic is incompatible with literal magic.
 
@@ -452,6 +453,7 @@ these forms:
 
 - "`!ATTR`" requires that the attribute `ATTR` be
   unspecified.
+
 +
 Note that when matching against a tree object, attributes are still
 obtained from working tree, not from the given tree object.
@@ -560,14 +562,17 @@ The ref namespace is hierarchical.
 Ref names must either start with `refs/` or be located in the root of
 the hierarchy. For the latter, their name must follow these rules:
 +
+--
  - The name consists of only upper-case characters or underscores.
 
  - The name ends with "`_HEAD`" or is equal to "`HEAD`".
+--
 +
 There are some irregular refs in the root of the hierarchy that do not
 match these rules. The following list is exhaustive and shall not be
 extended in the future:
 +
+--
  - `AUTO_MERGE`
 
  - `BISECT_EXPECTED_REV`
@@ -577,6 +582,7 @@ extended in the future:
  - `NOTES_MERGE_REF`
 
  - `MERGE_AUTOSTASH`
+--
 +
 Different subhierarchies are used for different purposes. For example,
 the `refs/heads/` hierarchy is used to represent local branches whereas
-- 
2.54.0.rc1.336.g4588871dc4
Previous: Jeff KingNext: Kristoffer Haugsbakk
Message 5 of 7 in “gitglossary: fix indentation of sub-lists”
  1. gitglossary: fix indentation of sub-listsJeff King, Apr 11, 2026
  2. Kristoffer HaugsbakkApr 11, 2026
  3. Kristoffer HaugsbakkApr 11, 2026
  4. Jeff KingApr 11, 2026
  5. gitglossary: fix indentation of sub-listsJeff King, Apr 11, 2026
  6. Kristoffer HaugsbakkApr 12, 2026
  7. Jeff KingApr 12, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.