Re: [RFC] formatting macro

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Monday, 12 August 2024 08:35:39 CEST Johannes Sixt wrote:
> Am 07.08.24 um 22:43 schrieb Jean-Noël AVILA:
> 
> 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.

The purpose of this series is to clarify the formatting rules for keywords and 
placeholders, and to uniformly apply them, so that the readers can relate the 
meaning of what they are reading with the visual cues in the text.  The more 
uniform the typesetting, the less surprised the reader, the smaller the 
communication impedance.

This requirement makes the documentation *less* easy to write, for sure.
It is no question of forcing authors to use the formatting macro everywhere. 
As explained in the Guildelines V3 of the series, the macro is introduced in 
order to remove the most hairy forms where manually doing the formatting would 
lead to difficult to read/write sequences. I bet most writers will remember and 
use the s macro when they want to typeset something like 
--ignore-submodules[=<when>]

As an added benefit, we can also simplify some existing parts, for instance see 
the ones in urls.txt.

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

I do not understand how the renderer could solve the issue of typesetting the 
"good part" in the place of the writers. The macro is there to mechanize the 
typesetting of selected parts, but it is up to the writers to define what is a 
keyword and what is a placeholder in their prose. Please note also that using 
proper placeholder differentiating and typesetting should have the side-effect 
of making the prose lighter, by removing the need to express which placeholder 
we are talking about.

To me, Asciidoc strikes a good balance for a tool that makes it easy to write 
simple things and not too complicated to write more complex ones. It is also 
customizable for specific needs, which is handy for our use case.  I am not 
aware of an existing renderer that would do the job really best. What do you 
have in mind?

JN