Re: [PATCH 4/4] doc: convert git-request-pull synopsis and options to new style

On Monday, 20 July 2026 01:47:02 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <[email protected]> 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