From: Jean-Noël Avila <jn.avila@free.fr>
Date: Fri, 10 Oct 2025 06:40:44 GMT
Subject: Re: [PATCH 1/3] doc: convert git-stash.adoc to synopis style
Message-ID: <bb0f530b-96f3-4655-8448-1d322413cd1f@free.fr>
In-Reply-To: <02383db0-545a-4f4c-9fa9-30a819a30de2@app.fastmail.com>

Le 10/10/2025 à 01:48, Kristoffer Haugsbakk a écrit :
> 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`.

TBH I did not spot the issue when I did this. I wasn't aware that
Asciidoc does not automatically handle inline formatting in attributes.
But it seems we can force it. This "show" keyword should definitely be
inline verbatim.

Wil try and reroll.

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