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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 30, 2024, 17:48 UTC
Message-ID: <xmqqa5gtsxz5.fsf@gitster.g>
In-Reply-To: <1986021.PYKUYFuaPT@cayenne>

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

Show 18 quoted lines

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