[PATCH v4 2/4] doc: replay: improve config description
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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-linkingSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v4:
• Avoid two “for” in the same sentence; makes the sentence
flow better
Suggested by Toon: https://lore.kernel.org/git/87cxwxofgv.fsf@emacs.iotcl.com/#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(-)
Show changes to 2 files +11 −6
Documentation/config/replay.adoc, Documentation/git-replay.adoc
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