Re: [PATCH] doc/for-each-ref: explicitly specify option names

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 2, 2017, 02:03 UTC
Message-ID: <xmqqk21hj1qw.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20170901144931.26114-1-me@ikke.info>

Kevin Daudt <me@ikke.info> writes:

Show 9 quoted lines

> For count, sort and format, only the argument names were listed under
> OPTIONS, not the option names.
>
> Add the option names to make it clear the options exist
>
> Signed-off-by: Kevin Daudt <me@ikke.info>
> ---
>  Documentation/git-for-each-ref.txt | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)

Sounds sensible. First I thought this was done deliberately because these placeholder can apply to more than one option and we wanted to explain each thing only once (e.g. "<object>" appears in 5 places, and having to repeat something like "you can spell <object> by the unique prefix of the object name, or the name of a ref that points at it, or ..." in each option would be awkward), but that is not the case here.

While we are at it, I just noticed that the SYNOPSIS section makes it look as if <pattern>... must come before points-at, merged, and their friends, but I do not think that should be the case. I also notice that unlike --sort/--format/... the last four/five options are spelled with "--option <value>" syntax; we should consistently use "--option=<value>" instead there.

But these two are separate issues that can be fixed in a patch separate from this one I am responding to.

p.s. I am still mostly offline and won't be doing any reviews or queuing that requires me to look at anything beyond the patch context. Please do not get disappointed if you do not see your patch in my tree until later next week.