Re: [PATCH v3 0/3] doc: introducing synopsis para

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

Le lundi 19 août 2024, 22:08:19 CEST Junio C Hamano a écrit :
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> > Jean-Noël Avila (3):
> >   doc: introduce a synopsis custom paragraph attribute
> >   doc: update the guidelines to reflect the current formatting rules
> >   doc: apply synopsis simplification on git-clone and git-init
> 
> This topic has become quiet.  I still find s:["someything you really
> want to say"] notation a bit annoying to my eyes, but its may be the
> best compromise we can come up with.
> 
> So unless we have a strong objection, or (even better) an objection
> with an alternative that is less yucky, perhaps it is time to
> declare that this is the variant of AsciiDoc/Asciidoctor that we'd
> adopt for our documentation.  Comments?
> 
> Thanks.
> 

I understand that you are reluctant to include a change that, as the 
maintainer, you do not feel comfortable  keeping alive. 

The whole discussion thread tells me that other developers are not ready to go 
down the "full markup" path. Understandably, this makes it more difficult for 
everyone to propose changes and review them, as there's no tool to track such 
formatting errors and we have to rely on careful manual cross-checking.

I would like to thank you for pushing so that the markup can be simplified as 
much as can be. It can be simplified further one step further: it is possible 
both in asciidoc/asciidoctor to override the formatting of inline verbatim 
texts, so that everything that is backquoted is processed as a synopsis 
string. 
This way, strings like

`<commit>`
`diff.statGraphWidth=<width>`
` --dirstat-by-file[=<param>,...]`

are automatically rendered with the expected styles.

However, contrary to the s macro, this is quite disruptive as it forces the 
new processing on all existing manpages. Another drawback is that it is no 
longer genuine asciidoc, but it seems more in line with the critics. I'm 
refining the regexp at the moment to check for side-effects.

Is this proposition more appropriate?