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

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Friday, 3 October 2025 05:41:34 CEST Jeff King wrote:
> On Thu, Oct 02, 2025 at 11:11:14PM -0400, Jeff King wrote:
> > 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


Thank you for cross-checking. This is indeed almost impossible to mechanize 
such testing at the moment.

JN