Re: [RFC] formatting macro

From: Johannes Sixt <j6t@kdbg.org>
Date: Aug 12, 2024, 06:35 UTC
Message-ID: <f44c253d-9b37-451d-902d-486adb8e3d72@kdbg.org>
In-Reply-To: <4617471.LvFx2qVVIh@cayenne>

Am 07.08.24 um 22:43 schrieb Jean-Noël AVILA:

Show 40 quoted lines

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

You argued elsewhere in this thread:

>  * The fact that the source of the pages should be "perfectly readable" is a 
> moot argument. Fair enough, it is not the objective to make it impossible to 
> understand, but in the end, this is not what is consumed: these pages are 
> compiled into other formats where the markup has been translated into styling.

I buy this argument, in particular, since not even I read the plain text files, but use the rendered version.

I would like tone down my harsh opposition to mild opposition. IMO, it should still be easy to *write* the documentation. It should not be necessary that authors remember to use macros all over the place.

And I still think that we should not introduce macros just to please all renderers. Let's just pick the one renderer that can do the job best. If it means that some distribution cannot render the documentation perfectly themselves (Debian? I don't know), they can always use the pre-rendered version that Junio kindly produces.

-- Hannes