From: Jeff King <peff@peff•net>
To: "Jean-Noël Avila" <jn.avila@free•fr>
Cc: Junio C Hamano <gitster@pobox•com>,
git@vger•kernel.org, Kristoffer Haugsbakk <code@khaugsbakk•name>
Subject: Re: [PATCH v2] doc: change the markup of paragraphs following a nested list item
Date: Thu, 2 Oct 2025 23:11:13 -0400 [thread overview]
Message-ID: <20251003031113.GA6381@coredump.intra.peff.net> (raw)
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:
> 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
next prev parent reply other threads:[~2025-10-03 3:11 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-09-23 18:34 doc: config/extensions.adoc: line continuation syntax error Kristoffer Haugsbakk
2025-09-23 21:08 ` Jean-Noël AVILA
2025-09-24 0:54 ` Jeff King
2025-09-26 19:40 ` [PATCH] doc: change the markup of paragraphs following a nested list item Jean-Noël Avila
2025-09-26 20:54 ` Junio C Hamano
2025-09-27 19:39 ` [PATCH v2] " Jean-Noël Avila
2025-09-28 15:35 ` Junio C Hamano
2025-10-03 3:11 ` Jeff King [this message]
2025-10-03 3:41 ` Jeff King
2025-10-03 16:29 ` Junio C Hamano
2025-10-04 17:31 ` Jean-Noël AVILA
2025-10-10 16:11 ` Junio C Hamano
2025-10-10 22:23 ` Jeff King
2025-10-13 15:17 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20251003031113.GA6381@coredump.intra.peff.net \
--to=peff@peff$(echo .)net \
--cc=code@khaugsbakk$(echo .)name \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=jn.avila@free$(echo .)fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox