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

"Jean-Noël Avila via GitGitGadget" [off-list ref] writes:

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <redacted>

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.

Le dimanche 21 juillet 2024, 01:16:02 CEST Junio C Hamano a écrit :

"Jean-Noël Avila via GitGitGadget" [off-list ref] writes:

quoted

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <redacted>

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.

Sorry for not being clear. Indeed I was wrong, Asciidoc.py also has this role 
management  behavior for any other inline markup (++, _, *, ^,  ~) except for 
back-quoted text.
 

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.

OK, but let's get rid of the "generalized role" stuff, then. 

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 can only agree. The fact that this "feature" is too easily triggered almost 
voids all the "painless technical doc editing for the rest of us" argument 
that is the main selling point of Asciidoc, Markdown and other lightweight 
markup systems.

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.

While doing the styling of synopsis, I tried to be smarter than that. There 
are basically 3 semantic entities in the grammar:

 * the _<placeholders>_ in italic
 * the `keywords`, in monospace
 * the grammar signs: [, ], |, ..., (, ), etc. These signs are not typeset.

Setting everything in monospace would mix keywords and grammar.

With this schema in mind, I don't find difficult to understand how the synopsis 
is written (putting aside the  {empty} hack). Fair enough, this is more 
difficult than just plain text, but the aim is still to get decent output.