Re: [PATCH v2] doc: change the markup of paragraphs following a nested list item

From: Jeff King <peff@peff.net>
Date: Oct 3, 2025, 03:41 UTC
Message-ID: <20251003034134.GA625140@coredump.intra.peff.net>
In-Reply-To: <20251003031113.GA6381@coredump.intra.peff.net>

On Thu, Oct 02, 2025 at 11:11:14PM -0400, Jeff King wrote:

Show 23 quoted lines

> which I think is wrong? Looking at the end result with more context, it
> is:
> 
>              refStorage
>                  Specify the ref storage format to use. The acceptable
>                  values are:
>   
>                  •   files for loose files with packed-refs. This is the
>                      default.
>   
>                  •   reftable for the reftable format. This format is
>                      experimental and its internals are subject to
>                      change.
>   
>              Note that this setting should only be set by git-init(1) or
>              git-clone(1). Trying to change it after initialization will
>              not work and will produce hard-to-diagnose issues.
> 
> So that "Note that..." paragraph is attached to the refStorage
> definition, and should be indented to the same level as "Specify...".
> 
> Even more interesting, I think asciidoc gets this wrong both before and
> after your patch!

Sorry, this is incorrect. Rendering with regular asciidoc does produce the right output already.

The patch I showed to drop the extra newline turns that final paragraph into a continuation of the second bullet point. So it is wrong for both asciidoc (which is already correct) and for asciidoctor (which indents too little, but after my proposed patch indents too much).

That's a little hard to parse, so here's my attempt at showing visually. The rendered output before that final paragraph looks something like this, with markers 1-3 showing possible indentation levels:

  refStorage
      Specify ...

      •   files ...

      •   reftable ...

  (1) a peer of "refStorage" in the definition list
      (2) a continuation paragraph in the "refStorage" definition
          (3) a continuation paragraph in the second bullet point

The paragraph "Note that..." should be at indentation level 2, and currently is for both asciidoc and asciidoctor. After your patch it is unchanged in asciidoc and at indentation level 1 in asciidoctor.

My proposed patch (which is garbage) moves it to indentation level 3 in both.

I think to appease both systems we need to put the inner bulleted list inside a block. I think that is OK in this case because there is no inner block marker to worry about. So:

diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc
index 49a7598ca5..aaea8c107f 100644
--- a/Documentation/config/extensions.adoc
+++ b/Documentation/config/extensions.adoc
@@ -55,8 +55,9 @@ For historical reasons, this extension is respected regardless of the
 refStorage:::
 	Specify the ref storage format to use. The acceptable values are:
 +
+--
 include::../ref-storage-format.adoc[]
-
+--
 +
 Note that this setting should only be set by linkgit:git-init[1] or
 linkgit:git-clone[1]. Trying to change it after initialization will not

on top of your patch seems to do the right thing (no change in asciidoc,
and eliminating the regression from your patch). It's a little gross
because we are reaching across the include to realize that
ref-storage-format.adoc contains a list that needs to go into its own
block. I wonder if asciidoc implicitly opens a new block for an include
but asciidoctor doesn't. But at any rate, this is the only way I could
come up with for both to render correctly.

-Peff