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

["Jean-Noël Avila" <jn.avila@free.fr>]

Le 22/07/2024 à 18:39, Junio C Hamano a écrit :
> 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.
> 


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