Re: [PATCH 1/6] doc: log, gitk: move '-L' description to 'line-range-options.txt'

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 31, 2020, 17:29 UTC
Message-ID: <xmqqmu02483u.fsf@gitster.c.googlers.com>
In-Reply-To: <C8539F4F-D51D-463B-825F-385AD743723E@gmail.com>

Philippe Blain <levraiphilippeblain@gmail.com> writes:

Show 10 quoted lines

>> Makes sense.  As to the conditional, I actually think the version
>> with SP after -L do not have to be listed and instead to show just
>> the "stuck" form as the standardised way.  If the option takes an
>> optional value, you must have to use the "stuck" form anyway, and
>> showing that you _could_ have SP there unnecessarily throws extra
>> bytes at the reader with no real gain.
>
> I'm not sure I understand here... The <range> argument is not optional
> here (`git log -L` by itself is meaningless)... I know gitcli(7) recommends the
> stuck form, ...

I do not think showing alternative ways distracts without adding much value. We should remember that most users are learning Git to only to do things they want to do and not necessarily learning Git to master all the slightly different ways to do the same thing. "You can write option and its argument separately most of the time but you must write option and its argument in the stuck form some other times---you must think if the argument is optional or not, whenyou want to write your argument separately" crams more things to learn than the simple "Write option and its arguments in the stuck form and it always works".