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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 20, 2024, 23:16 UTC
Message-ID: <xmqq8qxvhcy5.fsf@gitster.g>
In-Reply-To: <pull.1765.git.1721496853517.gitgitgadget@gmail.com>

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

Show 8 quoted lines

> 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.

Show 22 quoted lines

>  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