doc: config/extensions.adoc: line continuation syntax error

doc: config/extensions.adoc: line continuation syntax error

[Kristoffer Haugsbakk]

Hi

See the HTML output on e.g. latest `master` (ca2559c1 (The tenth batch,
2025-09-18)) for `git-config.adoc`:

    + For historical reasons, this extension is respected regardless of the core.repositoryFormatVersion setting.

The context is a definition item `worktreeConfig` where this is the
second paragraph following a bullet list.  So I thought maybe you can
use:

    --
    <bullets>
    --

Here.  But we’re already inside a `--` block.  So apparently we can’t do
that.  I also tried a fair amount of permutations of using or not using
line continuation in this context.

This particular level of nesting seems tricky to resolve with Asciidoc.
Maybe someone can figure it out.  So before I forget...

Thanks

(The Cc is because he is one of the Asciidoc experts as a FYI only)

-- 
Kristoffer

Re: doc: config/extensions.adoc: line continuation syntax error

[Jean-Noël AVILA]

On Tuesday, 23 September 2025 20:34:00 CEST Kristoffer Haugsbakk wrote:
> Hi
> 
> See the HTML output on e.g. latest `master` (ca2559c1 (The tenth batch,
> 2025-09-18)) for `git-config.adoc`:
> 
>     + For historical reasons, this extension is respected regardless of the
> core.repositoryFormatVersion setting.
> 

At first, I could not see the same output. It seems to be again a discrepancy 
between asciidoc.py and asciidoctor. Only asciidoctor is producing this 
output, and for me, it looks like a bug in asciidoctor.


> The context is a definition item `worktreeConfig` where this is the
> second paragraph following a bullet list.  So I thought maybe you can
> use:
> 
>     --
>     <bullets>
>     --
> 
> Here.  But we’re already inside a `--` block.  So apparently we can’t do
> that.  I also tried a fair amount of permutations of using or not using
> line continuation in this context.
> 
> This particular level of nesting seems tricky to resolve with Asciidoc.
> Maybe someone can figure it out.  So before I forget...
> 
> Thanks
> 
> (The Cc is because he is one of the Asciidoc experts as a FYI only)

Indeed, open blocks cannot be nested [1]. But, the first open block is not 
necessary as it is a workaround for the missing knowledge of multi-level 
definition lists.

[1]: https://docs.asciidoctor.org/asciidoc/latest/blocks/open-blocks/
#:~:text=It%20allows%20you%20to%20apply,inside%20of%20another%20open%20block.

Something along the following lines seems to work with asciidoctor while 
preserving the original paragraph nesting:

diff --git a/Documentation/config/extensions.adoc b/Documentation/config/
extensions.adoc
index 829f2523fc..556eda5d12 100644
--- a/Documentation/config/extensions.adoc
+++ b/Documentation/config/extensions.adoc
@@ -3,8 +3,7 @@ extensions.*::
 	`core.repositoryFormatVersion` is not `1`. See
 	linkgit:gitrepository-layout[5].
 +
---
-compatObjectFormat::
+compatObjectFormat:::
 	Specify a compatibility hash algorithm to use.  The acceptable 
values
 	are `sha1` and `sha256`.  The value specified must be different from 
the
 	value of `extensions.objectFormat`.  This allows client level
@@ -19,18 +18,18 @@ Note that the functionality enabled by this extension is 
incomplete and subject
 to change.  It currently exists only to allow development and testing of
 the underlying feature and is not designed to be enabled by end users.
 
-noop::
+noop:::
 	This extension does not change git's behavior at all. It is useful 
only
 	for testing format-1 compatibility.
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-noop-v1::
+noop-v1:::
 	This extension does not change git's behavior at all. It is useful 
only
 	for testing format-1 compatibility.
 
-objectFormat::
+objectFormat:::
 	Specify the hash algorithm to use.  The acceptable values are 
`sha1` and
 	`sha256`.  If not specified, `sha1` is assumed.
 +
@@ -38,7 +37,7 @@ 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
 work and will produce hard-to-diagnose issues.
 
-partialClone::
+partialClone:::
 	When enabled, indicates that the repo was created with a partial 
clone
 	(or later performed a partial fetch) and that the remote may have
 	omitted sending certain unwanted objects.  Such a remote is called 
a
@@ -50,14 +49,14 @@ The value of this key is the name of the promisor remote.
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-preciousObjects::
+preciousObjects:::
 	If enabled, indicates that objects in the repository MUST NOT be 
deleted
 	(e.g., by `git-prune` or `git repack -d`).
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-refStorage::
+refStorage:::
 	Specify the ref storage format to use. The acceptable values are:
 +
 include::../ref-storage-format.adoc[]
@@ -67,13 +66,13 @@ 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
 work and will produce hard-to-diagnose issues.
 
-relativeWorktrees::
+relativeWorktrees:::
 	If enabled, indicates at least one worktree has been linked with
 	relative paths. Automatically set if a worktree has been created or
 	repaired with either the `--relative-paths` option or with the
 	`worktree.useRelativePaths` config set to `true`.
 
-worktreeConfig::
+worktreeConfig:::
 	If enabled, then worktrees will load config settings from the
 	`$GIT_DIR/config.worktree` file in addition to the
 	`$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
@@ -87,11 +86,12 @@ When enabling this extension, you must be careful to move
 certain values from the common config file to the main working tree's
 `config.worktree` file, if present:
 +
+--
 * `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to
   `$GIT_COMMON_DIR/config.worktree`.
 * If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config`
   to `$GIT_COMMON_DIR/config.worktree`.
-
+--
 +
 It may also be beneficial to adjust the locations of `core.sparseCheckout`
 and `core.sparseCheckoutCone` depending on your desire for customizable
@@ -104,4 +104,3 @@ details.
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
---

Re: doc: config/extensions.adoc: line continuation syntax error

[Jeff King]

On Tue, Sep 23, 2025 at 11:08:10PM +0200, Jean-Noël AVILA wrote:

> Indeed, open blocks cannot be nested [1]. But, the first open block is not 
> necessary as it is a workaround for the missing knowledge of multi-level 
> definition lists.

We've run in this before, but I don't think we ever came up with a
satisfactory general solution.

You can find one more case with:

  cd Documentation
  ./doc-diff --from-asciidoc --to-asciidoctor HEAD HEAD

and searching in the pager for:

  /^\+[ ]+\+

which shows added lines starting with "+". The other one is in the
pretty-formats %(decorate) description, which is included in a few
places.

There are some other hits for ASCII art, some of which I think are
mis-rendered. But that's a separate problem. :)

-Peff

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

[Jean-Noël Avila]

Asciidoctor and asciidoc.py have different behaviors when a paragraph
follows a nested list item. Asciidoctor has a bug[1] that makes it add a
straight plus sign (+) at the beginning of the paragraph.

[1]:https://github.com/asciidoctor/asciidoctor/issues/4704

This commit uses workarounds to avoid this problem by using second level
definition lists and open blocks.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/config/extensions.adoc | 23 +++++++++++------------
 Documentation/pretty-formats.adoc    |  6 ++++--
 2 files changed, 15 insertions(+), 14 deletions(-)

diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc
index 829f2523fc..556eda5d12 100644
--- a/Documentation/config/extensions.adoc
+++ b/Documentation/config/extensions.adoc
@@ -3,8 +3,7 @@ extensions.*::
 	`core.repositoryFormatVersion` is not `1`. See
 	linkgit:gitrepository-layout[5].
 +
---
-compatObjectFormat::
+compatObjectFormat:::
 	Specify a compatibility hash algorithm to use.  The acceptable values
 	are `sha1` and `sha256`.  The value specified must be different from the
 	value of `extensions.objectFormat`.  This allows client level
@@ -19,18 +18,18 @@ Note that the functionality enabled by this extension is incomplete and subject
 to change.  It currently exists only to allow development and testing of
 the underlying feature and is not designed to be enabled by end users.
 
-noop::
+noop:::
 	This extension does not change git's behavior at all. It is useful only
 	for testing format-1 compatibility.
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-noop-v1::
+noop-v1:::
 	This extension does not change git's behavior at all. It is useful only
 	for testing format-1 compatibility.
 
-objectFormat::
+objectFormat:::
 	Specify the hash algorithm to use.  The acceptable values are `sha1` and
 	`sha256`.  If not specified, `sha1` is assumed.
 +
@@ -38,7 +37,7 @@ 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
 work and will produce hard-to-diagnose issues.
 
-partialClone::
+partialClone:::
 	When enabled, indicates that the repo was created with a partial clone
 	(or later performed a partial fetch) and that the remote may have
 	omitted sending certain unwanted objects.  Such a remote is called a
@@ -50,14 +49,14 @@ The value of this key is the name of the promisor remote.
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-preciousObjects::
+preciousObjects:::
 	If enabled, indicates that objects in the repository MUST NOT be deleted
 	(e.g., by `git-prune` or `git repack -d`).
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-refStorage::
+refStorage:::
 	Specify the ref storage format to use. The acceptable values are:
 +
 include::../ref-storage-format.adoc[]
@@ -67,13 +66,13 @@ 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
 work and will produce hard-to-diagnose issues.
 
-relativeWorktrees::
+relativeWorktrees:::
 	If enabled, indicates at least one worktree has been linked with
 	relative paths. Automatically set if a worktree has been created or
 	repaired with either the `--relative-paths` option or with the
 	`worktree.useRelativePaths` config set to `true`.
 
-worktreeConfig::
+worktreeConfig:::
 	If enabled, then worktrees will load config settings from the
 	`$GIT_DIR/config.worktree` file in addition to the
 	`$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
@@ -87,11 +86,12 @@ When enabling this extension, you must be careful to move
 certain values from the common config file to the main working tree's
 `config.worktree` file, if present:
 +
+--
 * `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to
   `$GIT_COMMON_DIR/config.worktree`.
 * If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config`
   to `$GIT_COMMON_DIR/config.worktree`.
-
+--
 +
 It may also be beneficial to adjust the locations of `core.sparseCheckout`
 and `core.sparseCheckoutCone` depending on your desire for customizable
@@ -104,4 +104,3 @@ details.
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
---
diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc
index 618ddc4a0c..2121e8e1df 100644
--- a/Documentation/pretty-formats.adoc
+++ b/Documentation/pretty-formats.adoc
@@ -232,7 +232,7 @@ ref names with custom decorations. The `decorate` string may be followed by a
 colon and zero or more comma-separated options. Option values may contain
 literal formatting codes. These must be used for commas (`%x2C`) and closing
 parentheses (`%x29`), due to their role in the option syntax.
-+
+
 ** `prefix=<value>`: Shown before the list of ref names.  Defaults to "{nbsp}++(++".
 ** `suffix=<value>`: Shown after the list of ref names.  Defaults to "+)+".
 ** `separator=<value>`: Shown between ref names.  Defaults to "+,+{nbsp}".
@@ -241,10 +241,12 @@ parentheses (`%x29`), due to their role in the option syntax.
 ** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
 
 +
+--
 For example, to produce decorations with no wrapping
 or tag annotations, and spaces as separators:
-+
+
 ++%(decorate:prefix=,suffix=,tag=,separator= )++
+--
 
 ++%(describe++`[:<option>,...]`++)++::
 human-readable name, like linkgit:git-describe[1]; empty string for
-- 
2.51.0

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

[Junio C Hamano]

Jean-Noël Avila <jn.avila@free.fr> writes:

> Asciidoctor and asciidoc.py have different behaviors when a paragraph
> follows a nested list item. Asciidoctor has a bug[1] that makes it add a
> straight plus sign (+) at the beginning of the paragraph.
>
> [1]:https://github.com/asciidoctor/asciidoctor/issues/4704

I read both the above introductory paragraph and the Asciidoctor
issue, but couldn't figure out what a "straight plus sign" is.  Even
if it were a typo of "stray plus sign" (which I am guessing but with
very low confidence), I do not see it at

  https://git.github.io/htmldocs/git-config.html#:~:text=extensions.*,compatObjectFormat

which I think is rendered via Asciidoctor.

Could you rephrase to clarify?

Thanks.


> diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc
> index 829f2523fc..556eda5d12 100644
> --- a/Documentation/config/extensions.adoc
> +++ b/Documentation/config/extensions.adoc
> @@ -3,8 +3,7 @@ extensions.*::
>  	`core.repositoryFormatVersion` is not `1`. See
>  	linkgit:gitrepository-layout[5].
>  +
> ---
> -compatObjectFormat::
> +compatObjectFormat:::
>  	Specify a compatibility hash algorithm to use.  The acceptable values
>  	are `sha1` and `sha256`.  The value specified must be different from the
>  	value of `extensions.objectFormat`.  This allows client level
> @@ -19,18 +18,18 @@ Note that the functionality enabled by this extension is incomplete and subject
>  to change.  It currently exists only to allow development and testing of
>  the underlying feature and is not designed to be enabled by end users.
>  
> -noop::
> +noop:::
>  	This extension does not change git's behavior at all. It is useful only
>  	for testing format-1 compatibility.
>  +
>  For historical reasons, this extension is respected regardless of the
>  `core.repositoryFormatVersion` setting.
>  
> -noop-v1::
> +noop-v1:::
>  	This extension does not change git's behavior at all. It is useful only
>  	for testing format-1 compatibility.
>  
> -objectFormat::
> +objectFormat:::
>  	Specify the hash algorithm to use.  The acceptable values are `sha1` and
>  	`sha256`.  If not specified, `sha1` is assumed.
>  +
> @@ -38,7 +37,7 @@ 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
>  work and will produce hard-to-diagnose issues.
>  
> -partialClone::
> +partialClone:::
>  	When enabled, indicates that the repo was created with a partial clone
>  	(or later performed a partial fetch) and that the remote may have
>  	omitted sending certain unwanted objects.  Such a remote is called a
> @@ -50,14 +49,14 @@ The value of this key is the name of the promisor remote.
>  For historical reasons, this extension is respected regardless of the
>  `core.repositoryFormatVersion` setting.
>  
> -preciousObjects::
> +preciousObjects:::
>  	If enabled, indicates that objects in the repository MUST NOT be deleted
>  	(e.g., by `git-prune` or `git repack -d`).
>  +
>  For historical reasons, this extension is respected regardless of the
>  `core.repositoryFormatVersion` setting.
>  
> -refStorage::
> +refStorage:::
>  	Specify the ref storage format to use. The acceptable values are:
>  +
>  include::../ref-storage-format.adoc[]
> @@ -67,13 +66,13 @@ 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
>  work and will produce hard-to-diagnose issues.
>  
> -relativeWorktrees::
> +relativeWorktrees:::
>  	If enabled, indicates at least one worktree has been linked with
>  	relative paths. Automatically set if a worktree has been created or
>  	repaired with either the `--relative-paths` option or with the
>  	`worktree.useRelativePaths` config set to `true`.
>  
> -worktreeConfig::
> +worktreeConfig:::
>  	If enabled, then worktrees will load config settings from the
>  	`$GIT_DIR/config.worktree` file in addition to the
>  	`$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
> @@ -87,11 +86,12 @@ When enabling this extension, you must be careful to move
>  certain values from the common config file to the main working tree's
>  `config.worktree` file, if present:
>  +
> +--
>  * `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to
>    `$GIT_COMMON_DIR/config.worktree`.
>  * If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config`
>    to `$GIT_COMMON_DIR/config.worktree`.
> -
> +--
>  +
>  It may also be beneficial to adjust the locations of `core.sparseCheckout`
>  and `core.sparseCheckoutCone` depending on your desire for customizable
> @@ -104,4 +104,3 @@ details.
>  +
>  For historical reasons, this extension is respected regardless of the
>  `core.repositoryFormatVersion` setting.
> ---
> diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc
> index 618ddc4a0c..2121e8e1df 100644
> --- a/Documentation/pretty-formats.adoc
> +++ b/Documentation/pretty-formats.adoc
> @@ -232,7 +232,7 @@ ref names with custom decorations. The `decorate` string may be followed by a
>  colon and zero or more comma-separated options. Option values may contain
>  literal formatting codes. These must be used for commas (`%x2C`) and closing
>  parentheses (`%x29`), due to their role in the option syntax.
> -+
> +
>  ** `prefix=<value>`: Shown before the list of ref names.  Defaults to "{nbsp}++(++".
>  ** `suffix=<value>`: Shown after the list of ref names.  Defaults to "+)+".
>  ** `separator=<value>`: Shown between ref names.  Defaults to "+,+{nbsp}".
> @@ -241,10 +241,12 @@ parentheses (`%x29`), due to their role in the option syntax.
>  ** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
>  
>  +
> +--
>  For example, to produce decorations with no wrapping
>  or tag annotations, and spaces as separators:
> -+
> +
>  ++%(decorate:prefix=,suffix=,tag=,separator= )++
> +--
>  
>  ++%(describe++`[:<option>,...]`++)++::
>  human-readable name, like linkgit:git-describe[1]; empty string for

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

[Jean-Noël Avila]

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.

[1]:https://github.com/asciidoctor/asciidoctor/issues/4704

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---

Sorry for the straight/stray confusion. It is saner to remove it.

The first occurrence of the described issue is a few lines below where you
looked at:

https://git.github.io/htmldocs/git-config.html#:~:text=+%20For%20historical

also see the second one:

https://git.github.io/htmldocs/git-log.html#:~:text=%2B%20%25(decorate

And big thank you to peff for teaching doc-diff.

 Documentation/config/extensions.adoc | 23 +++++++++++------------
 Documentation/pretty-formats.adoc    |  6 ++++--
 2 files changed, 15 insertions(+), 14 deletions(-)

diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc
index 829f2523fc..556eda5d12 100644
--- a/Documentation/config/extensions.adoc
+++ b/Documentation/config/extensions.adoc
@@ -3,8 +3,7 @@ extensions.*::
 	`core.repositoryFormatVersion` is not `1`. See
 	linkgit:gitrepository-layout[5].
 +
---
-compatObjectFormat::
+compatObjectFormat:::
 	Specify a compatibility hash algorithm to use.  The acceptable values
 	are `sha1` and `sha256`.  The value specified must be different from the
 	value of `extensions.objectFormat`.  This allows client level
@@ -19,18 +18,18 @@ Note that the functionality enabled by this extension is incomplete and subject
 to change.  It currently exists only to allow development and testing of
 the underlying feature and is not designed to be enabled by end users.
 
-noop::
+noop:::
 	This extension does not change git's behavior at all. It is useful only
 	for testing format-1 compatibility.
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-noop-v1::
+noop-v1:::
 	This extension does not change git's behavior at all. It is useful only
 	for testing format-1 compatibility.
 
-objectFormat::
+objectFormat:::
 	Specify the hash algorithm to use.  The acceptable values are `sha1` and
 	`sha256`.  If not specified, `sha1` is assumed.
 +
@@ -38,7 +37,7 @@ 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
 work and will produce hard-to-diagnose issues.
 
-partialClone::
+partialClone:::
 	When enabled, indicates that the repo was created with a partial clone
 	(or later performed a partial fetch) and that the remote may have
 	omitted sending certain unwanted objects.  Such a remote is called a
@@ -50,14 +49,14 @@ The value of this key is the name of the promisor remote.
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-preciousObjects::
+preciousObjects:::
 	If enabled, indicates that objects in the repository MUST NOT be deleted
 	(e.g., by `git-prune` or `git repack -d`).
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
 
-refStorage::
+refStorage:::
 	Specify the ref storage format to use. The acceptable values are:
 +
 include::../ref-storage-format.adoc[]
@@ -67,13 +66,13 @@ 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
 work and will produce hard-to-diagnose issues.
 
-relativeWorktrees::
+relativeWorktrees:::
 	If enabled, indicates at least one worktree has been linked with
 	relative paths. Automatically set if a worktree has been created or
 	repaired with either the `--relative-paths` option or with the
 	`worktree.useRelativePaths` config set to `true`.
 
-worktreeConfig::
+worktreeConfig:::
 	If enabled, then worktrees will load config settings from the
 	`$GIT_DIR/config.worktree` file in addition to the
 	`$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and
@@ -87,11 +86,12 @@ When enabling this extension, you must be careful to move
 certain values from the common config file to the main working tree's
 `config.worktree` file, if present:
 +
+--
 * `core.worktree` must be moved from `$GIT_COMMON_DIR/config` to
   `$GIT_COMMON_DIR/config.worktree`.
 * If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config`
   to `$GIT_COMMON_DIR/config.worktree`.
-
+--
 +
 It may also be beneficial to adjust the locations of `core.sparseCheckout`
 and `core.sparseCheckoutCone` depending on your desire for customizable
@@ -104,4 +104,3 @@ details.
 +
 For historical reasons, this extension is respected regardless of the
 `core.repositoryFormatVersion` setting.
---
diff --git a/Documentation/pretty-formats.adoc b/Documentation/pretty-formats.adoc
index 618ddc4a0c..2121e8e1df 100644
--- a/Documentation/pretty-formats.adoc
+++ b/Documentation/pretty-formats.adoc
@@ -232,7 +232,7 @@ ref names with custom decorations. The `decorate` string may be followed by a
 colon and zero or more comma-separated options. Option values may contain
 literal formatting codes. These must be used for commas (`%x2C`) and closing
 parentheses (`%x29`), due to their role in the option syntax.
-+
+
 ** `prefix=<value>`: Shown before the list of ref names.  Defaults to "{nbsp}++(++".
 ** `suffix=<value>`: Shown after the list of ref names.  Defaults to "+)+".
 ** `separator=<value>`: Shown between ref names.  Defaults to "+,+{nbsp}".
@@ -241,10 +241,12 @@ parentheses (`%x29`), due to their role in the option syntax.
 ** `tag=<value>`: Shown before tag names. Defaults to "`tag:`{nbsp}".
 
 +
+--
 For example, to produce decorations with no wrapping
 or tag annotations, and spaces as separators:
-+
+
 ++%(decorate:prefix=,suffix=,tag=,separator= )++
+--
 
 ++%(describe++`[:<option>,...]`++)++::
 human-readable name, like linkgit:git-describe[1]; empty string for
-- 
2.51.0

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

[Junio C Hamano]

Jean-Noël Avila <jn.avila@free.fr> writes:

> 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.
>
> [1]:https://github.com/asciidoctor/asciidoctor/issues/4704
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>
> Sorry for the straight/stray confusion. It is saner to remove it.
>
> The first occurrence of the described issue is a few lines below where you
> looked at:
>
> https://git.github.io/htmldocs/git-config.html#:~:text=+%20For%20historical
>
> also see the second one:
>
> https://git.github.io/htmldocs/git-log.html#:~:text=%2B%20%25(decorate
>
> And big thank you to peff for teaching doc-diff.

Thanks!

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

[Jeff King]

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

> 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

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

[Jeff King]

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

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> 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.

Sounds good.  Thanks.

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

[Jean-Noël AVILA]

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

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

[Junio C Hamano]

Jean-Noël AVILA <jn.avila@free.fr> writes:

> 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:
>> ...
>> 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.
>
> Thank you for cross-checking. This is indeed almost impossible to mechanize 
> such testing at the moment.

Thanks, both.  

So we'd see an update to this (I think this is already in 'next')?

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

[Jeff King]

On Fri, Oct 10, 2025 at 09:11:16AM -0700, Junio C Hamano wrote:

> >> 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.
> >
> > Thank you for cross-checking. This is indeed almost impossible to mechanize 
> > such testing at the moment.
> 
> Thanks, both.  
> 
> So we'd see an update to this (I think this is already in 'next')?

I think we already did, in:

  https://lore.kernel.org/git/20251007082223.GA3336685@coredump.intra.peff.net/

and you queued that on the topic (and merged it to next already). Or am
I misunderstanding the question?

-Peff

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I think we already did, in:
>
>   https://lore.kernel.org/git/20251007082223.GA3336685@coredump.intra.peff.net/
>
> and you queued that on the topic (and merged it to next already).

Thanks, indeed we have 84a6bf79 (doc: fix indentation of refStorage
item in git-config(1), 2025-10-07) already on the topic.