Re: [PATCH 4/5] doc: git-diff: apply format changes to diff-generate-patch

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

On Monday, 5 August 2024 07:53:19 CEST Johannes Sixt wrote:
> Am 04.08.24 um 22:05 schrieb Jean-Noël Avila via GitGitGadget:
> > @@ -134,17 +135,18 @@ or like this (when the `--cc` option is used):
> >  
> >  2.   It is followed by one or more extended header lines
> >       (this example shows a merge with two parents):
> > -
> > -       index <hash>,<hash>..<hash>
> > -       mode <mode>,<mode>..<mode>
> > -       new file mode <mode>
> > -       deleted file mode <mode>,<mode>
> >  +
> > -The `mode <mode>,<mode>..<mode>` line appears only if at least one of
> > -the <mode> is different from the rest. Extended headers with
> > +[synopsis]
> > +index <hash>,<hash>`..`<hash>
> > +mode <mode>,<mode>`..`<mode>
> > +new file mode <mode>
> > +deleted file mode <mode>,<mode>
> > ++
> > +The `mode` __<mode>__++,++__<mode>__++..++__<mode>__ line appears only if 
at least one of
> > +the _<mode>_ is different from the rest. Extended headers with
> 
> 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.
> 
> Just my 2c.
> 
> -- Hannes
> 
> 

Hello,

I was half expecting this kind of reactions. First there are some remarks on 
your remarks.
 
 * You think the markup is unnecessary. To me, it is critical in order to make 
the documentation output a little more meaningful. My experience as a 
translator is that there's a great lack of consistency in the vocabulary, the 
grammar styles, the typesetting and the cross-references of the pages. On top 
of that, they are clearly not user-oriented. Overall, the joke about how 
cryptic the man-pages of Git are is not coming from nowhere. There's no one to 
blame: we are all developers doing our best, but we are not technical writers 
dedicated to this project.
 * 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 suspect some writers are not thinking when quoting text, that this is not a 
quotation but an inline formatting command. But this is markup, and sometimes, 
it cannot  be removed of the way.
 * I converted the lines to synopsis because there are placeholders in them. 
These lines are presented as an example but they are neither. This is another 
example of communication impedance,  where the presented text is not what it 
is described as, and requires from the reader to interpret what the writer was 
thinking and forgot to make clear to a newcomer.


As for the "need to adapt to the tool", for block formatting, I tried to get 
something bearable (the synopis style); I'd really like something similar for 
inline formatting but my asciidoc/asciidoctor Fu requires an upgrade in order 
to make it happen. As it seems to be too epidermic, I'll try to cook something 
anyway and keep being open to any proposition.

In the mean time, a proper editor setup (syntax highlighting and fontification 
, two panels with one showing the compiled output) can alleviate your pain. 

JN