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

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Aug 21, 2024, 21:05 UTC
Message-ID: <1986021.PYKUYFuaPT@cayenne>
In-Reply-To: <xmqqzfp8cm30.fsf@gitster.g>

Le lundi 19 août 2024, 22:08:19 CEST Junio C Hamano a écrit :

Show 18 quoted lines

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