Re: [RFC] formatting macro
- From
Jean-Noël AVILA <jn.avila@free.fr>
- Date
- Aug 13, 2024, 20:42 UTC
- Message-ID
- <3596897.iIbC2pHGDl@cayenne>
- In-Reply-To
- <f44c253d-9b37-451d-902d-486adb8e3d72@kdbg.org>
On Monday, 12 August 2024 08:35:39 CEST Johannes Sixt wrote:
Show 5 quoted lines
> 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.
Show 6 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.
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