Re: [PATCH] Documentation/diff-options: explain different diff algorithms

Stefan Beller [off-list ref] writes:

On Mon, Jul 23, 2018 at 9:41 PM Jonathan Nieder [off-list ref] wrote:

quoted

Hi,

Stefan Beller wrote:

quoted

As a user I wondered what the diff algorithms are about. Offer at least
a basic explanation on the differences of the diff algorithms.

Interesting.  Let's see.

[...]

quoted

--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt

@@ -94,16 +94,34 @@ diff" algorithm internally.
      Choose a diff algorithm. The variants are as follows:
 +
 --
-`default`, `myers`;;
-     The basic greedy diff algorithm. Currently, this is the default.
 `minimal`;;
+     A diff as produced by the basic greedy algorithm described in

Why this reordering?

because Myers (below) is constructed from minimal + heuristic.
...
So the "minimal" algorithm is the basic myers algorithm,
and the "myers" algorithm is the extended version (extended
with a heuristic to be fast in corner cases, still producing good
enough diffs).

I am not sure that is a good reason for the target readers of this
document to move the default from the beginning to somewhere in the
middle.  For a textbook that explains different algorithms and gives
overview of how they work, that order may be appropriate, though.

quoted

quoted

-     Spend extra time to make sure the smallest possible diff is
-     produced.
+`default`, `myers`;;
+     The same algorithm as `minimal`, extended with a heuristic to
+     reduce extensive searches. Currently, this is the default.

Amusing --- this means that the Myers diff is spelled as "minimal"
instead of "myers".

Yeah, I had the same thought---for an end-user documentation update,
this change and the reordering does not feel like an improvement.

quoted

I wonder if these details (about all the algorithms) should go in a
separate Diff Algorithms section and this section could focus on
what use cases warrant using each, referring to that section for
details.  What do you think?

Good suggestion.