Re: [RFC] formatting macro

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 12, 2024, 15:22 UTC
Message-ID: <xmqqwmkl7ol4.fsf@gitster.g>
In-Reply-To: <f44c253d-9b37-451d-902d-486adb8e3d72@kdbg.org>

Johannes Sixt <j6t@kdbg.org> writes:

Show 14 quoted lines

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

FWIW, I do read the plain text files, and rarely if ever use the HTML version, except when checking the effect of changes to the mark-up.

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

Yeah, s:[...] does repel me, but also I do not think it is sensible to claim that we confortably edit the "source" form that we find it hard to read.

Show 5 quoted lines

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

What Junio uses "Debian? I don't know" that cannot render the documentation ;-)?