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

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

Jean-Noël AVILA <jn.avila@free.fr> writes:

> ... 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?

Thanks for thinking these things through.  The fact that such a
"magic" processing will hide the gory details from those whose
primary interest is to describe the commands and their options cuts
both ways.  It is a very welcome thing for developers around here, I
would assume.  At the same time, I can understand that purists would
find it unacceptably ugly, as `backticks` is now much more than a
mark-up that means "this text is typeset in monospace".  Inside it,
<text inside angle brackets>, [optional text], and (choices), all
signal that they have special meaning by being typeset differently.

I do not personally mind that, and I would even dream about a future
in which other projects notice what you did to AsciiDoctor, love it,
adopt it, and eventually it feeds back to improve AsciiDoctor proper.

It is very likely that is because I haven't seen any "side effects"
yet ;-)

Thanks.