Re: [RFC] formatting macro

[Junio C Hamano <gitster@pobox.com>]

Johannes Sixt <j6t@kdbg.org> writes:

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

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