Le dimanche 21 juillet 2024, 01:16:02 CEST Junio C Hamano a écrit :
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@xxxxxxxxx> writes:
>
> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@xxxxxxx>
> >
> > 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.
