inconsistent order of --diff-algorithm variants in man pages

inconsistent order of --diff-algorithm variants in man pages

[Vincent Lefevre]

In Documentation/diff-algorithm-option.adoc, which is used by the
git-blame(1) and git-diff(1) man pages:

`--diff-algorithm=(patience|minimal|histogram|myers)`::
        Choose a diff algorithm. The variants are as follows:
+
--
   `default`;;
   `myers`;;
        The basic greedy diff algorithm. Currently, this is the default.
   `minimal`;;
        Spend extra time to make sure the smallest possible diff is
        produced.
   `patience`;;
        Use "patience diff" algorithm when generating patches.
   `histogram`;;
        This algorithm extends the patience algorithm to "support
        low-occurrence common elements".
--

I think that using the same order in the --diff-algorithm line and
in the description that follows would be better, i.e.

  --diff-algorithm=(myers|minimal|patience|histogram)

FYI, the text was added in 07924d4d50e5304fb53eb60aaba8aef31d4c4e5e
in 2013, but without any explanation on this difference.

-- 
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / Pascaline project (LIP, ENS-Lyon)

Re: inconsistent order of --diff-algorithm variants in man pages

[Junio C Hamano]

Vincent Lefevre <vincent@vinc17.net> writes:

> In Documentation/diff-algorithm-option.adoc, which is used by the
> git-blame(1) and git-diff(1) man pages:
>
> `--diff-algorithm=(patience|minimal|histogram|myers)`::
>         Choose a diff algorithm. The variants are as follows:
> +
> --
>    `default`;;
>    `myers`;;
>         The basic greedy diff algorithm. Currently, this is the default.
>    `minimal`;;
>         Spend extra time to make sure the smallest possible diff is
>         produced.
>    `patience`;;
>         Use "patience diff" algorithm when generating patches.
>    `histogram`;;
>         This algorithm extends the patience algorithm to "support
>         low-occurrence common elements".
> --
>
> I think that using the same order in the --diff-algorithm line and
> in the description that follows would be better, i.e.
>
>   --diff-algorithm=(myers|minimal|patience|histogram)
>
> FYI, the text was added in 07924d4d50e5304fb53eb60aaba8aef31d4c4e5e
> in 2013, but without any explanation on this difference.

I think this is meant to list them as equals without any precedence
or preference order, so it is understandable that nobody paid much
attention.  Until now, that is.

I agree that being consistent between these two places makes tons of
sense.  I just do not know what the right ordering should be.  When
listing a set of equals without any precedence or preference order,
the most easy to see to new readers is alphabetical, except that the
built-in default (myers) is a head above among other equals, so it
does make sense to present it first.