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

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

Jean-Noël AVILA <jn.avila@free.fr> 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.