Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor

[Junio C Hamano <gitster@pobox.com>]

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

> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> Asciidoc.py does not have the concept of generalized roles, whereas
> asciidoctor interprets [foo]`blah` as blah with role foo in the
> synopsis, making in effect foo disappear in the output. Note that
> square brackets not directly followed by an inline markup do not
> define a role, which is why we do not have the issue on other parts of
> the documentation.

This was utterly misleading, at least to me, and it took a few times
of reading for me to really understand what you wanted to say.

It does not matter that "generalized roles" is not known by
AsciiDoc.  What really causes the breakage is that a string inside
[square brackets] followed by string inside `a pair of back quotes`
is interpreted by Asciidoctor as "generalized roles" (whatever it
is), even though we do not care at all about such a feature here.

How about phrasing it more like so?

    Writing a string inside [square brackets], immediately followed
    by a string inside `a pair of back quotes`, causes asciidoctor
    to eliminate the string inside [square brackets], because it is
    a syntax to trigger a "generalized role" feature, which we do
    not care about in the context of the synopsis section here.

    Work it around by inserting an otherwise no-op {empty} string to
    forbid asciidoctor from triggering that feature here.  AsciiDoc
    is not affected negatively by this additional empty string.

The reondered result _might_ be easier to read than pre-2.45 version
of documentation, but I somehow find the updated SYNOPSIS section
almost impossible to work with in the source form.  And the need for
these otherwise no-op {empty} makes it even less pleasant to work
with.

I wonder if there is a magic incantation that says "everything
should be typeset in monospace in this block, unless ..." so that we
can lose all these `back quotes`?  And then the part that follows
"unless ..." would say how we mark up the <placeholder> part which
is the only thing exempt from "everything is in monospace" default.

Thanks for a quick response.

>  Documentation/git-clone.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index 5de18de2ab8..8e925db7e9c 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -13,9 +13,9 @@ SYNOPSIS
>  	  [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]
>  	  [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]
>  	  [`--dissociate`] [`--separate-git-dir` _<git-dir>_]
> -	  [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-tags`]
> -	  [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]
> -	  [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`]
> +	  [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]
> +	  [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]
> +	  [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]
>  	  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
>  	  [_<directory>_]
>  
>
> base-commit: a7dae3bdc8b516d36f630b12bb01e853a667e0d9