On Monday, 5 August 2024 18:08:07 CEST Junio C Hamano wrote: > Johannes Sixt <j6t@xxxxxxxx> 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
