Le 22/07/2024 à 18:39, Junio C Hamano a écrit :
> Jean-Noël AVILA <jn.avila@xxxxxxx> writes:
>
>> 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.
>
> I agree it is not relevant what the feature is called, as that is
> something we did not want to trigger and take advantage of.
>
> It still is necessary to mention the fact that [strings] are eaten
> by us unknowingly triggering the feature.
>
>> 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.
>
> Thanks.
>
> It appears that asciidoctor considers `monospaced` that results in
> <code>...</code> is a bad match in the SYNOPSIS section
>
> cf. https://lore.kernel.org/git/xmqqsew3hdmv.fsf@gitster.g/
>
> but we should be able to sort it out.
>
Please hold on this patch. Cranking on your reflections about the ugly
markup and upon advice from Dan Allen (of asciidoctor) [1], I'd like to
push another way of managing the files, which would be to define a
custom 'synopsis' paragraph style which would allow to process
automatically the grammar.
Thanks
[1]
https://asciidoctor.zulipchat.com/#narrow/stream/279642-users/topic/Is.20there.20a.20way.20to.20disable.20role.20attributes.3F
