[PATCH v4 2/4] doc: replay: improve config description

From: Kristoffer Haugsbakk <[email protected]>

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

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 <[email protected]>
---

Notes (series):
    v4:
    • Avoid two “for” in the same sentence; makes the sentence
      flow better
    
      Suggested by Toon: https://lore.kernel.org/git/[email protected]/#t
    
    ---
    
    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..a7dd5288553 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` 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