doc: git diff reformatting

[jnavila]

This is the continuation of the editing of the manpages to reflect the new formatting rules.

Note that this patch makes use of the synopsis paragraph styling and needs to be applied above ja/doc-synopsis-markup. As the dots can be primarily interpreted as a grammar sign for repetition, here the dots which are part of the synopsis are manually forced to verbatim.

cc: Johannes Sixt [email protected]
cc: Patrick Steinhardt [email protected]

[jnavila]

/submit

[gitgitgadget]

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1769/jnavila/git_diff_new-v1

To fetch this version to local tag pr-1769/jnavila/git_diff_new-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1769/jnavila/git_diff_new-v1

[gitgitgadget]

On the Git mailing list, Johannes Sixt wrote (reply to this):

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

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Johannes Sixt <[email protected]> writes:

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

Thanks for placing this into words a lot better than how I could
have done.  I share the same feeling.

[gitgitgadget]

On the Git mailing list, Jean-Noël AVILA wrote (reply to this):

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

[gitgitgadget]

On the Git mailing list, Jean-Noël AVILA wrote (reply to this):

On Monday, 5 August 2024 18:08:07 CEST Junio C Hamano wrote:
> Johannes Sixt <[email protected]> writes:
> 
> > 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.
> 
> Thanks for placing this into words a lot better than how I could
> have done.  I share the same feeling.
> 

I'm working on a form of macro that would work almost the same way as the 
synopsis paragraph. You would have some markup, but it would be surrounding 
the text to typeset: 

s:["--ignore-matching-lines=<regex>"]

In this snippet the macro part (which is recognized by a regex) is  s:[ ]
The inside part is managed the same. If you need additional markup, it is 
possible:

s:["<commit1>`...`<commit2>"] to have the three dots rendered as <code>, 
because they are part of the tokens.

Square brackets are possible inside the double-quotes:
s:["--ignore-submodules[=<when>]"]

Is this something that wouldn't repel you?

Best regards,

JN

[gitgitgadget]

On the Git mailing list, Johannes Sixt wrote (reply to this):

Am 07.08.24 um 22:43 schrieb Jean-Noël AVILA:
> On Monday, 5 August 2024 18:08:07 CEST Junio C Hamano wrote:
>> Johannes Sixt <[email protected]> writes:
>>
>>> 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.
>>
>> Thanks for placing this into words a lot better than how I could
>> have done.  I share the same feeling.
>>
> 
> I'm working on a form of macro that would work almost the same way as the 
> synopsis paragraph. You would have some markup, but it would be surrounding 
> the text to typeset: 
> 
> s:["--ignore-matching-lines=<regex>"]
> 
> In this snippet the macro part (which is recognized by a regex) is  s:[ ]
> The inside part is managed the same. If you need additional markup, it is 
> possible:
> 
> s:["<commit1>`...`<commit2>"] to have the three dots rendered as <code>, 
> because they are part of the tokens.
> 
> 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.

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.

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.

-- Hannes

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

Johannes Sixt <[email protected]> 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 ;-)?

[gitgitgadget]

On the Git mailing list, Jean-Noël AVILA wrote (reply to this):

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

[gitgitgadget]

User Johannes Sixt <[email protected]> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Patrick Steinhardt wrote (reply to this):

On Sun, Aug 04, 2024 at 08:05:32PM +0000, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
> 

Nit: please provide a summary of what adaptations you made. It would
certainly help the reviewer to learn about the recently-introduced
`[synopsis]` style and why/since when we use backticks and underscores
for formatting.

The same also applies to subsequent commits, providing some pointers
would certainly help an unknowing reviewer such as myself.

> @@ -225,11 +225,12 @@ CONFIGURATION
>  
>  include::includes/cmd-config-section-all.txt[]
>  
> +:git-diff: 1
>  include::config/diff.txt[]
>  
>  SEE ALSO
>  --------
> -diff(1),
> +`diff`(1),

This one looks curious to me. Why is this item formatted differently
than the next three? I would have expected it to be formatted as
something like linkgit:git-diff[1] instead of `diff`(1)`.

Patrick

>  linkgit:git-difftool[1],
>  linkgit:git-log[1],
>  linkgit:gitdiffcore[7],
> -- 
> gitgitgadget
> 
> 

[gitgitgadget]

On the Git mailing list, Jean-Noël AVILA wrote (reply to this):

On Monday, 5 August 2024 11:11:07 CEST Patrick Steinhardt wrote:
> On Sun, Aug 04, 2024 at 08:05:32PM +0000, Jean-Noël Avila via GitGitGadget 
wrote:
> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
> > 
> 
> Nit: please provide a summary of what adaptations you made. It would
> certainly help the reviewer to learn about the recently-introduced
> `[synopsis]` style and why/since when we use backticks and underscores
> for formatting.
> 
> The same also applies to subsequent commits, providing some pointers
> would certainly help an unknowing reviewer such as myself.
> 

Thanks for the remark. The context is effectively missing, so I'll restate it.

> > @@ -225,11 +225,12 @@ CONFIGURATION
> >  
> >  include::includes/cmd-config-section-all.txt[]
> >  
> > +:git-diff: 1
> >  include::config/diff.txt[]
> >  
> >  SEE ALSO
> >  --------
> > -diff(1),
> > +`diff`(1),
> 
> This one looks curious to me. Why is this item formatted differently
> than the next three? I would have expected it to be formatted as
> something like linkgit:git-diff[1] instead of `diff`(1)`.
> 

Here we are referring to the 'diff' command, not git-diff. That is why we don't 
use the linkgit macro (which is used to generate cross links for html output).

Still, the general format of a reference to a man-page is to put the command 
name in bold, which our filters get by backquoting. 

> Patrick
> 
> >  linkgit:git-difftool[1],
> >  linkgit:git-log[1],
> >  linkgit:gitdiffcore[7],
> 

Thanks

[gitgitgadget]

On the Git mailing list, Patrick Steinhardt wrote (reply to this):

On Mon, Aug 05, 2024 at 08:51:21PM +0200, Jean-Noël AVILA wrote:
> On Monday, 5 August 2024 11:11:07 CEST Patrick Steinhardt wrote:
> > On Sun, Aug 04, 2024 at 08:05:32PM +0000, Jean-Noël Avila via GitGitGadget 
> wrote:
> > > @@ -225,11 +225,12 @@ CONFIGURATION
> > >  
> > >  include::includes/cmd-config-section-all.txt[]
> > >  
> > > +:git-diff: 1
> > >  include::config/diff.txt[]
> > >  
> > >  SEE ALSO
> > >  --------
> > > -diff(1),
> > > +`diff`(1),
> > 
> > This one looks curious to me. Why is this item formatted differently
> > than the next three? I would have expected it to be formatted as
> > something like linkgit:git-diff[1] instead of `diff`(1)`.
> > 
> 
> Here we are referring to the 'diff' command, not git-diff. That is why we don't 
> use the linkgit macro (which is used to generate cross links for html output).
> 
> Still, the general format of a reference to a man-page is to put the command 
> name in bold, which our filters get by backquoting. 

Oh, that makes sense of course. I totally forgot that there's a world
outside of Git. Thanks for the clarification!

Patrick

[gitgitgadget]

User Patrick Steinhardt <[email protected]> has been added to the cc: list.