On Thu, May 17, 2018 at 9:00 PM, Simon Ruderich <simon@xxxxxxxxxxxx> wrote:
> On Thu, May 17, 2018 at 12:46:51PM -0700, Stefan Beller wrote:
>> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
>> index bb9f1b7cd82..7b2527b9a19 100644
>> --- a/Documentation/diff-options.txt
>> +++ b/Documentation/diff-options.txt
>> @@ -292,6 +292,19 @@ dimmed_zebra::
>> blocks are considered interesting, the rest is uninteresting.
>> --
>>
>> +--color-moved-[no-]ignore-space-at-eol::
>> + Ignore changes in whitespace at EOL when performing the move
>> + detection for --color-moved.
>> +--color-moved-[no-]ignore-space-change::
>> + Ignore changes in amount of whitespace when performing the move
>> + detection for --color-moved. This ignores whitespace
>> + at line end, and considers all other sequences of one or
>> + more whitespace characters to be equivalent.
>> +--color-moved-[no-]ignore-all-space::
>> + Ignore whitespace when comparing lines when performing the move
>> + detection for --color-moved. This ignores differences even if
>> + one line has whitespace where the other line has none.
>> +
>> --word-diff[=<mode>]::
>> Show a word diff, using the <mode> to delimit changed words.
>> By default, words are delimited by whitespace; see
>
> Hello,
>
> I think it would be better to specify the options unabbreviated.
> Not being able to search the man page for
> "--color-moved-ignore-space-at-eol" or
> "--color-moved-no-ignore-space-at-eol" can be a major pain when
> looking for documentation. So maybe something like this instead:
>
>> +--color-moved-ignore-space-at-eol::
>> +--color-moved-no-ignore-space-at-eol::
>> + Ignore changes in whitespace at EOL when performing the move
>> + detection for --color-moved.
That makes sense.
Stepping back a bit, looking for similar precedents, we have lots of
"[no-]" strings in our documentation. But that is ok, as we the prefix
is at the beginning of the option ("--[no-]foo-bar"), such that searching
for the whole option without the leading dashes ("foo-bar") will still find
the option.
So maybe another option would be rename the negative options
to "--no-color-moved-ignore-space-at-eol", such that the documentation
could fall back to the old pattern of "--[no-]long-name".
Initially I was tempted on not choosing such names, as I viewed all
this white space options specific to the color-move feature, such that
a prefix of "--color-moved" might be desirable. Turning off one sub-feature
in that feature would naturally be --feature-no-subfeature instead of
negating the whole feature.
I also cannot find a good existing example for subfeatures in features,
they would usually come as --feature=<option1, option2>
Undecided,
Stefan
