From: Toon Claes Date: Wed, 08 Jul 2026 12:04:00 GMT Subject: Re: [PATCH v3 2/4] doc: replay: improve config description Message-ID: <87cxwxofgv.fsf@emacs.iotcl.com> In-Reply-To: kristofferhaugsbakk@fastmail.com writes: > From: Kristoffer Haugsbakk > > First of all, this unordered list for `replay.refAction` introduces > a term with a colon. This is exactly what a description list is, > structurally. Let’s be stylistically consistent and use the desc. > list markup construct. Let’s also drop the harmless but unneeded > indentation. > > We can reuse the `::` delimiter since we use an open block. > But for consistency use the typical nested description list > delimiter, namely `;;`. Yeah, looking at some other docs (for example Documenation/config/branch.adoc) it makes sense to do it like this. > Second, let’s replace the inline-verbatim `git replay` with a link > to git-replay(1), since we are naming the command. But make that > conditional so that we avoid a self-link inside git-replay(1).[1] > > † 1: See e.g. e7b3a768 (doc: git-init: rework config item > init.templateDir, 2024-03-10) for another example of > avoiding self-linking > > Signed-off-by: Kristoffer Haugsbakk > --- > > Notes (series): > v3: > • Msg:[1] typo, fix to “stylistically” > • Msg: Move the paragraph about delimiters (;;) from the *next* > patch over here instead. This is the first place we do it. In the > next patch we can just say that we are doing the same trans- > formation as here. > • Msg: Remove double-space to separate two sentences. That’s > inconsitent for me. I moved away from that because two-space > separation takes up too much space when linewrapping is set to 72. > • Msg: This isn’t the option, it is `replay.refAction` > • Copy–paste mistake? We don’t have to ask > • Msg: ... and it’s better to call it an unordered list rather than > bullet points > > † 1: Commit message > > --- > > v2: > • Keep the description list for `replay.refAction` (Junio) > • Now rewrite the description list like in patch 1/3 (it’s > technically an unordered list) > • Msg: mention a previous commit which also avoided self-linking. > This helps establish a bit more context for why we do this. > > Documentation/config/replay.adoc | 16 ++++++++++------ > Documentation/git-replay.adoc | 1 + > 2 files changed, 11 insertions(+), 6 deletions(-) > > diff --git a/Documentation/config/replay.adoc b/Documentation/config/replay.adoc > index 7d549d2f0e5..7328da9537d 100644 > --- a/Documentation/config/replay.adoc > +++ b/Documentation/config/replay.adoc > @@ -1,11 +1,15 @@ > replay.refAction:: > - Specifies the default mode for handling reference updates in > - `git replay`. The value can be: > + Specifies the default mode for handling reference updates. > + The value can be: > + > -- > - * `update`: Update refs directly using an atomic transaction (default behavior). > - * `print`: Output update-ref commands for pipeline use. > +`update`;; Update refs directly using an atomic transaction (default behavior). > +`print`;; Output update-ref commands for pipeline use. > -- > + > -This setting can be overridden with the `--ref-action` command-line option. > -When not configured, `git replay` defaults to `update` mode. > +ifdef::git-replay[] > +See `--ref-action`. > +endif::git-replay[] > +ifndef::git-replay[] > +See `--ref-action` for linkgit:git-replay[1] for details. I'm not sure about using "for" twice, how about: See `--ref-action` in linkgit:git-replay[1] for details. > +endif::git-replay[] > diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc > index f9ca2db2833..4de85088d6c 100644 > --- a/Documentation/git-replay.adoc > +++ b/Documentation/git-replay.adoc > @@ -211,6 +211,7 @@ to use bare commit IDs instead of branch names. > > CONFIGURATION > ------------- > +:git-replay: 1 > include::config/replay.adoc[] > > GIT > -- > 2.54.0.22.g9e26862b904 > > -- Cheers, Toon