Subject: Re: [PATCH] gitglossary: fix indentation of sub-lists

From: "Kristoffer Haugsbakk" <[email-masked]>
Date: Sat, 11 Apr 2026 22:34:27 +0200

On Sat, Apr 11, 2026, at 21:06, Jeff King wrote:
> 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.

`Documentation/doc-diff` confirms that this is the effect of this change.

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

And that it is the effect for all the other spots at as well: pull a
paragraph out of a bullet list back to the previous block (or level).

> We can fix this by using "--" markers, which put the sub-list into its
> own block. This should catch all of the unordered lists in the glossary,
> which I found by grepping for " -" list markers.

Yes, for what it’s worth I think open blocks (`--`) are a great cure for
this when you are lucky enough to not already be in an open block.

AsciiDoc is certainly a format.

>
> Signed-off-by: Jeff King <[email-masked]>
> ---
> Just happened to notice this while looking at the "ref" entry.
>
>  Documentation/glossary-content.adoc | 12 ++++++++++--
>  1 file changed, 10 insertions(+), 2 deletions(-)
>[snip]