From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 07 Oct 2025 14:24:52 GMT
Subject: Re: What's cooking in git.git (Oct 2025, #02; Mon, 6)
Message-ID: <xmqqms62n617.fsf@gitster.g>
In-Reply-To: <20251007082223.GA3336685@coredump.intra.peff.net>

Jeff King <peff@peff.net> writes:

> Subject: [PATCH] doc: fix indentation of refStorage item in git-config(1)
>
> Commit 5a12fd2a8c (doc: change the markup of paragraphs following a
> nested list item, 2025-09-27) converted the list of items in
> config/extensions.adoc into a definition list. This caused a small
> regression in the indentation of one item, but only when built with
> AsciiDoctor. You can see the problem with:
>
>   $ ./doc-diff --asciidoctor 5a12fd2a8c^ 5a12fd2a8c
>   --- a/c44beea485f0f2feaf460e2ac87fdd5608d63cf0-asciidoctor/home/peff/share/man/man1/git-config.1
>   +++ b/5a12fd2a8c850df311aa149c9bad87b7cb002abb-asciidoctor/home/peff/share/man/man1/git-config.1
>   @@ -3128,9 +3128,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
>
> (along with many other changes which are correctly fixing what
> 5a12fd2a8c intended to fix). The "Note" paragraph should remain aligned
> with the bullet points, as they are left-aligned with the rest of the
> definition text.
>
> The confusion comes from a paragraph following a list item (ironically,
> the same case that 5a12fd2a8c was solving!). We can solve it by adding
> "--" block markers around the nested list. We couldn't have done that
> before 5a12fd2a8c because before then our list was nested inside another
> set of block markers, something that AsciiDoctor has trouble with. But
> now that we are a top-level definition list, it is OK to do so (and in
> fact, you can see that commit already made a similar adjustment for the
> worktreeConfig entry).
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
>  Documentation/config/extensions.adoc | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> 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

Thanks.  Will queue.