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

[Toon Claes <toon@iotcl.com>]

kristofferhaugsbakk@fastmail.com writes:

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

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 <code@khaugsbakk.name>
> ---
>
> 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