A new batch of synopsis conversion

[jnavila]

The conversion to synopsis continues. Now the commands are less common, so I may propose larger PRs if it's ok.

[jnavila]

/submit

[gitgitgadget]

Submitted as pull.2185.git.1784490878.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2185/jnavila/convert_synopsis_202606-v1

To fetch this version to local tag pr-2185/jnavila/convert_synopsis_202606-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2185/jnavila/convert_synopsis_202606-v1

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Backtick-quote all option terms in the OPTIONS section, convert
> standalone placeholders to _<placeholder>_ form, and convert
> single-quoted commands and tools in prose to backtick form.

OK.

> @@ -708,15 +708,15 @@ BASE TREE INFORMATION
>  
>  The base tree information block is used for maintainers or third party
>  testers to know the exact state the patch series applies to. It consists
> +of the "base commit", which is a well-known commit that is part of the
>  stable part of the project history everybody else works off of, and zero
> +or more "prerequisite patches", which are well-known patches in flight
> +that is not yet part of the "base commit" that need to be applied on top
> +of "base commit" in topological order before the patches can be applied.

GIven that the last part of this hunk below uses backtick-quoting
for `prerequisite patch` and `patch id`, shouldn't the references to
`base commit`, and `prerequisite patch(es)` in the above also be
backtick quoted for consistency?

> +The "base commit" is shown as "base-commit: " followed by the 40-hex of
> +the commit object name.  A `prerequisite patch` is shown as
> +"prerequisite-patch-id: " followed by the 40-hex `patch id`, which can
>  be obtained by passing the patch through the `git patch-id --stable`
>  command.

[gitgitgadget]

Jean-Noël AVILA wrote on the Git mailing list (how to reply to this email):

On Monday, 20 July 2026 01:40:17 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> > Backtick-quote all option terms in the OPTIONS section, convert
> > standalone placeholders to _<placeholder>_ form, and convert
> > single-quoted commands and tools in prose to backtick form.
> 
> OK.
> 
> > @@ -708,15 +708,15 @@ BASE TREE INFORMATION
> > 
> >  The base tree information block is used for maintainers or third party
> >  testers to know the exact state the patch series applies to. It consists
> > 
> > +of the "base commit", which is a well-known commit that is part of the
> > 
> >  stable part of the project history everybody else works off of, and zero
> > 
> > +or more "prerequisite patches", which are well-known patches in flight
> > +that is not yet part of the "base commit" that need to be applied on top
> > +of "base commit" in topological order before the patches can be applied.
> 
> GIven that the last part of this hunk below uses backtick-quoting
> for `prerequisite patch` and `patch id`, shouldn't the references to
> `base commit`, and `prerequisite patch(es)` in the above also be
> backtick quoted for consistency?
> 

In fact, the formatting were swapped. For proper rendering and preservation of 
spaces, it should be:

The "base commit" is shown as "`base-commit:` " followed by the 40-hex of
the commit object name.  A "prerequisite patch" is shown as
"`prerequisite-patch-id:` " followed by the 40-hex "patch id", which can
be obtained by passing the patch through the `git patch-id --stable`
command.


Only the constant strings are back-ticked. The others are only quoted.

Will reroll.

> > +The "base commit" is shown as "base-commit: " followed by the 40-hex of
> > +the commit object name.  A `prerequisite patch` is shown as
> > +"prerequisite-patch-id: " followed by the 40-hex `patch id`, which can
> > 
> >  be obtained by passing the patch through the `git patch-id --stable`
> >  command.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> @@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into the project.
>  First you push that change to your public repository for others to
>  see:
>  
> -	git push https://git.ko.xz/project master
> +-----
> +git push https://git.ko.xz/project master
> +-----
>  
>  Then, you run this command:
>  
> -	git request-pull v1.0 https://git.ko.xz/project master
> +------
> +git request-pull v1.0 https://git.ko.xz/project master
> +------
>  
>  which will produce a request to the upstream, summarizing the
>  changes between the `v1.0` release and your `master`, to pull it
> @@ -67,11 +71,15 @@ from your public repository.
>  If you pushed your change to a branch whose name is different from
>  the one you have locally, e.g.
>  
> -	git push https://git.ko.xz/project master:for-linus
> +-----
> +git push https://git.ko.xz/project master:for-linus
> +-----
>  
>  then you can ask that to be pulled with
>  
> -	git request-pull v1.0 https://git.ko.xz/project master:for-linus
> +-----
> +git request-pull v1.0 https://git.ko.xz/project master:for-linus
> +-----

Is there a widely accepted guideline among AsciiDoc users governing
how many dashes should delimit these blocks, other than "at least
four, with the opening and closing counts matching"?  If so, what is
it?  We see five, six, five, and five dashes in the proposed changes
above, and in '[PATCH 1/4]' we saw nine.  Even if varying counts are
functionally equivalent, the inconsistency is a bit distracting.

Thanks.

[Footnote]

 * an excerpt from [PATCH 1/4]

diff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc
index 538b91afc0..dd1e0a3718 100644
--- a/Documentation/git-imap-send.adoc
+++ b/Documentation/git-imap-send.adoc
@@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism.
 
 Once the commits are ready to be sent, run the following command:
 
-  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+
+---------
+$ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+---------

[gitgitgadget]

Jean-Noël AVILA wrote on the Git mailing list (how to reply to this email):

On Monday, 20 July 2026 01:47:02 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> > @@ -54,11 +54,15 @@ the `v1.0` release, and want it to be integrated into 
the
> > project.> 
> >  First you push that change to your public repository for others to
> > 
> >  see:
> > -	git push https://git.ko.xz/project master
> > +-----
> > +git push https://git.ko.xz/project master
> > +-----
> > 
> >  Then, you run this command:
> > -	git request-pull v1.0 https://git.ko.xz/project master
> > +------
> > +git request-pull v1.0 https://git.ko.xz/project master
> > +------
> > 
> >  which will produce a request to the upstream, summarizing the
> >  changes between the `v1.0` release and your `master`, to pull it
> > 
> > @@ -67,11 +71,15 @@ from your public repository.
> > 
> >  If you pushed your change to a branch whose name is different from
> >  the one you have locally, e.g.
> > 
> > -	git push https://git.ko.xz/project master:for-linus
> > +-----
> > +git push https://git.ko.xz/project master:for-linus
> > +-----
> > 
> >  then you can ask that to be pulled with
> > 
> > -	git request-pull v1.0 https://git.ko.xz/project master:for-linus
> > +-----
> > +git request-pull v1.0 https://git.ko.xz/project master:for-linus
> > +-----
> 
> Is there a widely accepted guideline among AsciiDoc users governing
> how many dashes should delimit these blocks, other than "at least
> four, with the opening and closing counts matching"?  If so, what is
> it?  We see five, six, five, and five dashes in the proposed changes
> above, and in '[PATCH 1/4]' we saw nine.  Even if varying counts are
> functionally equivalent, the inconsistency is a bit distracting.
> 
> Thanks.
> 
> [Footnote]
> 
>  * an excerpt from [PATCH 1/4]
> 
> diff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-
send.adoc
> index 538b91afc0..dd1e0a3718 100644
> --- a/Documentation/git-imap-send.adoc
> +++ b/Documentation/git-imap-send.adoc
> @@ -192,7 +192,10 @@ supports only `XOAUTH2` as the mechanism.
> 
>  Once the commits are ready to be sent, run the following command:
> 
> -  $ git format-patch --cover-letter -M --stdout origin/master | git imap-
send
> +
> +---------
> +$ git format-patch --cover-letter -M --stdout origin/master | git imap-send
> +---------


"Widely accepted", I do not know. I would better frame it as "because at least 
four is needed and I'm lazy, then it's four". I'm not expert enough the 
asciidoc specification to have a definitive answer of mine, but the 
asciidoctor specification says exactly four [1]

We could indeed apply the rule of 4 dashes by default.

Note that this only applies because it is a listing block which does not 
accept nesting.

I will reroll.

[1]: https://docs.asciidoctor.org/asciidoc/latest/verbatim/listing-blocks/
#delimited-listing-block

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Jean-Noël AVILA <jn.avila@free.fr> writes:

> "Widely accepted", I do not know. I would better frame it as "because at least 
> four is needed and I'm lazy, then it's four". I'm not expert enough the 
> asciidoc specification to have a definitive answer of mine, but the 
> asciidoctor specification says exactly four [1]
>
> We could indeed apply the rule of 4 dashes by default.
>
> Note that this only applies because it is a listing block which does not 
> accept nesting.
>
> I will reroll.

Thanks.  Sounds like a good plan to me.

[gitgitgadget]

This patch series was integrated into seen via git@15b21a2.