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

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Sep 23, 2025, 21:08 UTC
Message-ID: <6196161.lOV4Wx5bFT@cayenne>
In-Reply-To: <a6e4e995-fc19-465d-bd7a-c002bc0db31f@app.fastmail.com>

On Tuesday, 23 September 2025 20:34:00 CEST Kristoffer Haugsbakk wrote:

Show 8 quoted lines

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

Show 18 quoted lines

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