All of lore.kernel.org
 help / color / mirror / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Kevin Daudt <me@ikke.info>
Cc: git@vger.kernel.org
Subject: Re: [PATCH] doc/for-each-ref: explicitly specify option names
Date: Sat, 02 Sep 2017 11:03:19 +0900	[thread overview]
Message-ID: <xmqqk21hj1qw.fsf@gitster.mtv.corp.google.com> (raw)
In-Reply-To: 20170901144931.26114-1-me@ikke.info

Kevin Daudt <me@ikke.info> writes:

> 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.

  parent reply	other threads:[~2017-09-02  2:03 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-09-01 14:49 [PATCH] doc/for-each-ref: explicitly specify option names Kevin Daudt
2017-09-01 22:03 ` Jeff King
2017-09-01 23:03 ` Johannes Schindelin
2017-09-01 23:19 ` Jonathan Nieder
2017-09-02  2:03 ` Junio C Hamano [this message]
2017-09-11 19:33 ` [PATCH v2 1/2] doc/for-each-ref: consistently use '=' to between argument names and values Kevin Daudt
2017-09-11 19:33   ` [PATCH v2 2/2] doc/for-each-ref: explicitly specify option names Kevin Daudt
2017-09-12  2:28   ` [PATCH v2 1/2] doc/for-each-ref: consistently use '=' to between argument names and values Junio C Hamano
2017-09-12  4:38     ` Kevin Daudt

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqqk21hj1qw.fsf@gitster.mtv.corp.google.com \
    --to=gitster@pobox.com \
    --cc=git@vger.kernel.org \
    --cc=me@ikke.info \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.