Re: [PATCH v2 1/1] reset: support the --stdin option

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 28, 2017, 00:20 UTC
Message-ID: <xmqqa8acxcfj.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20170127221221.d53icsq7mdkbqm23@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 5 quoted lines

> I think a lot of the documentation uses <paths> to refer to pathspecs
> (e.g., git-log(1), git-diff(1), etc).  As long as we're consistent with
> that convention, I don't think it's that big a deal.
>
> This spot needs a specific mention because it violates the convention.

Yup, I think we are in agreement.

> I don't know if the are other spots where it might be unclear, but I
> think we're probably better to tighten those as they come up, rather
> than switch to saying "<pathspecs>" everywhere.

Oh, I do not think I would disagree. As I think this change is an instancethat makes the resulting text unclear, it would set a good example to tighten existing one as part of its clean-up.

It can be done as a follow-up bugfix patch (i.e. "previous one made the resulting document uncleasr and here is to fix it"), but that would not serve as good ra ole model to mentor newer contributor as doing the other way around.