Subject: Re: [PATCH 1/3] doc: convert git-stash.adoc to synopis style

From: "Kristoffer Haugsbakk" <[email-masked]>
Date: Fri, 10 Oct 2025 01:48:28 +0200

On Sun, Oct 5, 2025, at 23:11, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email-masked]>
>
> - Switch the synopsis to a synopsis block which will automatically
>   format placeholders in italics and keywords in monospace
> - Use _<placeholder>_ instead of <placeholder> in the description
> - Use `backticks` for keywords and more complex option
> descriptions. The new rendering engine will apply synopsis rules to
> these spans.
>
> Also do not refer to the man page in the description of settings when this
> description is already in the man page.
>
> Signed-off-by: Jean-Noël Avila <[email-masked]>
> ---
>  Documentation/config/stash.adoc |  29 ++++---
>  Documentation/git-stash.adoc    | 134 ++++++++++++++++----------------
>  2 files changed, 85 insertions(+), 78 deletions(-)
>
> diff --git a/Documentation/config/stash.adoc b/Documentation/config/stash.adoc
> index e556105a15..7fc32027f7 100644
> --- a/Documentation/config/stash.adoc
> +++ b/Documentation/config/stash.adoc
> @@ -1,19 +1,28 @@
> -stash.index::
> +ifndef::git-stash[]
> +:see-show: See the description of the 'show' command in linkgit:git-stash[1].

Okay, here you use 'show' and not `show` because this conditional
attribute will pass on `show` and render it as such, not as
inline-verbatim “show”. Bare 'show' is indeed better than bare `show`.

> +endif::git-stash[]
> +
> +ifdef::git-stash[]
> +:see-show:
> +endif::git-stash[]
>[snip]