From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Thu, 09 Oct 2025 23:48:28 GMT
Subject: Re: [PATCH 1/3] doc: convert git-stash.adoc to synopis style
Message-ID: <02383db0-545a-4f4c-9fa9-30a819a30de2@app.fastmail.com>
In-Reply-To: <3f3e5a87e834a6cd1d5d7769bdd2c0dcfaa4b6ae.1759698702.git.gitgitgadget@gmail.com>

On Sun, Oct 5, 2025, at 23:11, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> - 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 <jn.avila@free.fr>
> ---
>  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]