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

From: Philippe Blain <levraiphilippeblain@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com>,
	"Git mailing list" <git@vger.kernel.org>,
	"Thomas Rast" <tr@thomasrast.ch>,
	"Eric Sunshine" <sunshine@sunshineco.com>,
	"René Scharfe" <l.s.r@web.de>
Subject: Re: [PATCH 1/6] doc: log, gitk: move '-L' description to 'line-range-options.txt'
Date: Sat, 31 Oct 2020 13:18:01 -0400	[thread overview]
Message-ID: <C8539F4F-D51D-463B-825F-385AD743723E@gmail.com> (raw)
In-Reply-To: <xmqqft5w7poo.fsf@gitster.c.googlers.com>

Hi Junio,

> Le 29 oct. 2020 à 16:16, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> From: Philippe Blain <levraiphilippeblain@gmail.com>
>> 
>> The description of the '-L' option for `git log` and `gitk` is the
>> same, but is repeated in both 'git-log.txt' and 'gitk.txt'.
> 
> They are moral equivalents but differ slightly, both in
> an insignificant way (i.e. SP after -L and its parameters) and a
> significant way (i.e. Note about gitk usage), so "the same, but is
> repeated" is not sufficient to explain why the contents of the new
> file looks the way it is.

OK. I'll expand on that.

>> Remove the duplication by creating a new file, 'line-range-options.txt',
>> and include it in both files.
> 
> 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, but this option has been listed as `-L <range>` in the git-log
documentation ever since it appeared... So I did not think it wise to change it, 
that's why I introduce the conditional.

Thanks,

Philippe.