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:11 UTC
Message-ID: <20251003031113.GA6381@coredump.intra.peff.net>
In-Reply-To: <20250927195032.37223-1-jn.avila@free.fr>

On Sat, Sep 27, 2025 at 09:39:45PM +0200, Jean-Noël Avila wrote:

Show 6 quoted lines

> Asciidoctor and asciidoc.py have different behaviors when a paragraph
> follows a nested list item. Asciidoctor has a bug[1] that makes it keep a
> plus sign (+) used to attached paragraphs at the beginning of the paragraph.
> 
> This commit uses workarounds to avoid this problem by using second level
> definition lists and open blocks.

I think this is mostly making things better, but there is one curiosity.

Looking at:

  ./doc-diff HEAD^ HEAD

there are no changes with asciidoc, which is good.

Looking at:

  ./doc-diff --asciidoctor HEAD^ HEAD

most of the changes are like:

  @@ -3187,7 +3187,7 @@ CONFIGURATION FILE
                  specify the sparsity for each worktree independently. See git-
                  sparse-checkout(1) for more details.
  
  -               + For historical reasons, this extension is respected regardless
  +               For historical reasons, this extension is respected regardless
                  of the core.repositoryFormatVersion setting.

which is fixing up the bug. Good. But then there's also this hunk in git-config.1:

  @@ -3148,9 +3148,9 @@ CONFIGURATION FILE
                  •   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.
  +           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.
  
              relativeWorktrees
                  If enabled, indicates at least one worktree has been linked with

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!

Looking at the source, there is an extra blank line, which might be confusing things. This seems to help both asciidoc and asciidoctor do the right thing:

diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc
index 556eda5d12..110976ad60 100644
--- a/Documentation/config/extensions.adoc
+++ b/Documentation/config/extensions.adoc
@@ -60,7 +60,6 @@ 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

Not sure if we'd want to squash that in, or do it as a fix on top, or
even as a preparatory patch (since it does fix a real problem in the
asciidoc version, AFAICT).

-Peff