doc: convert git-stash, git tag and git worktree to synopis style #1969
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- 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>
- 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 add the config section in the manual page and 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>
- 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 add the config section in the manual page and 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>
|
/submit |
|
Submitted as pull.1969.git.1759698702.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
This patch series was integrated into seen via git@788f2cc. |
|
This branch is now known as |
|
This patch series was integrated into seen via git@2db5a8b. |
|
This patch series was integrated into seen via git@7b2890d. |
|
This patch series was integrated into next via git@fd4f96f. |
|
There was a status update in the "Cooking" section about the branch Doc-mark-up modernization continues. Will merge to 'master'. source: <pull.1969.git.1759698702.gitgitgadget@gmail.com> |
| @@ -1,19 +1,28 @@ | |||
| stash.index:: | |||
| ifndef::git-stash[] | |||
There was a problem hiding this comment.
On the Git mailing list, "Kristoffer Haugsbakk" wrote (reply to this):
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]There was a problem hiding this comment.
On the Git mailing list, Jean-Noël Avila wrote (reply to this):
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]
There was a problem hiding this comment.
On the Git mailing list, Junio C Hamano wrote (reply to this):
Jean-Noël Avila <jn.avila@free.fr> writes:
>>> 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.
This is already in 'next', isn't it, though?There was a problem hiding this comment.
On the Git mailing list, Jean-Noël AVILA wrote (reply to this):
On Friday, 10 October 2025 17:52:59 CEST Junio C Hamano wrote:
> Jean-Noël Avila <jn.avila@free.fr> writes:
> >>> 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.
>
> This is already in 'next', isn't it, though?
That's fine. I couldn't come up with a substitution scheme that would work
correctly for both asciidoc.py and asciidoctor.
So let's just let this patch as it is and recall that attributes are not a
panacea.
There was a problem hiding this comment.
On the Git mailing list, Junio C Hamano wrote (reply to this):
Jean-Noël AVILA <jn.avila@free.fr> writes:
>> > Wil try and reroll.
>>
>> This is already in 'next', isn't it, though?
>
> That's fine. I couldn't come up with a substitution scheme that would work
> correctly for both asciidoc.py and asciidoctor.
>
> So let's just let this patch as it is and recall that attributes are not a
> panacea.
OK. Let me make sure that I did not mark the topic as "on hold".
Thanks.|
User |
|
This patch series was integrated into seen via git@6d49757. |
|
This patch series was integrated into seen via git@7dac520. |
|
There was a status update in the "Cooking" section about the branch Doc-mark-up modernization continues. Will merge to 'master'. source: <pull.1969.git.1759698702.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via git@a5ff2be. |
|
This patch series was integrated into seen via git@b48a32e. |
|
This patch series was integrated into seen via git@050bf81. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
backticksfor keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans.Also add the CONFIGURATION section when it is missing and do not refer to the man page in the description of settings when this list is included in the manual page.
cc: "Kristoffer Haugsbakk" kristofferhaugsbakk@fastmail.com