From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Wed, 07 Aug 2024 20:43:28 GMT
Subject: Re: [RFC] formatting macro
Message-ID: <4617471.LvFx2qVVIh@cayenne>
In-Reply-To: <xmqqcymn3qc8.fsf@gitster.g>

On Monday, 5 August 2024 18:08:07 CEST Junio C Hamano wrote:
> Johannes Sixt <j6t@kdbg.org> writes:
> 
> > I've a strong aversion to the formatting that this series applies,
> > because it introduces many (IMHO) unnecessary punctuation that
> > vandalizes the perfectly readable plain text. And this hunk now shows
> > where it goes too far. These lines under the new [synopsis] header just
> > aren't syopsis; they are comamnd output. The updated version abuses a
> > semantic token to achieve syntactic highlighting.
> >
> > To me this series looks too much like "we must adapt to the tool" when
> > the correct stance should be "the tool must adapt to us". If the tool
> > (one of asciidoc and asciidoctor, I presume) does not cooperate well
> > with out documents, then it is the tool that must be changed, not our
> > documents.
> >
> > I understand that some compromises are needed, but with this extent of
> > changes we give in to a sub-par tool too far.
> 
> Thanks for placing this into words a lot better than how I could
> have done.  I share the same feeling.
> 

I'm working on a form of macro that would work almost the same way as the 
synopsis paragraph. You would have some markup, but it would be surrounding 
the text to typeset: 

s:["--ignore-matching-lines=<regex>"]

In this snippet the macro part (which is recognized by a regex) is  s:[ ]
The inside part is managed the same. If you need additional markup, it is 
possible:

s:["<commit1>`...`<commit2>"] to have the three dots rendered as <code>, 
because they are part of the tokens.

Square brackets are possible inside the double-quotes:
s:["--ignore-submodules[=<when>]"]

Is this something that wouldn't repel you?

Best regards,

JN