Re: [PATCH] pull: add angle brackets to usage string

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 20, 2015, 05:17 UTC
Message-ID: <xmqqbnbu9kzr.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <CAMMLpeTf93NnqPM+SaxfhsSdMg1HUiVyo5FFdiuGF9o-KQbGog@mail.gmail.com>

Alex Henrie <alexhenrie24@gmail.com> writes:

Show 15 quoted lines

> 2015-10-16 11:42 GMT-06:00 Junio C Hamano <gitster@pobox.com>:
>>
>> Yes, but that fixes historical "mistake", no?
>>
>> With this, you are breaking historical practice by changing only one
>> instance to deviate from the then-current practice of saying
>> 'options' without brackets.  It is based on the point of view that
>> considers anything inside <bracket> and a fixed string 'options' are
>> meant to be replaced by intelligent readers, which is as valid as
>> the more recent practice to consider only things inside <bracket>
>> are placeholders.
>
> OK, I see. You're saying that it's OK to fix typos and grammatical
> errors in contrib/examples, but it's not okay to modernize the
> scripts' designs.

Please read it again, look at contrib/examples and realize that that is not what I said at all.

This is not about modern vs old-school. The reason why the part of the patch to contrib/ under discussion is wrong is because of (in)consistency.

Look at the output from "git grep option contrib/examples/" and notice that in the old days, these scripted Porcelains consistently said "[options]" without "<bracket>".

It would have been a different matter if the patch _were_ to update all "[options]" to "[<options>]" in contrib/examples/ consistently, and such a patch might have even been an improvement, especially if the modern style were clearly superiour than the old-school style (which is not, by they way [*1*]).

But that is not what the patch did. It turned only one of them into "[<options>]", making the single instance inconsistent from all the others around it. That is why it was wrong.

[Footnote]

*1* The "modern" style is not necessarily an improvement, by the
    way.  The way we specify that a "thing" in the help text is a
    placeholder and that there may be more instances of the same
    "thing" is to say "[<thing>...]", but in your "modernized" form,
    unlike all the other usual "things", possibly multiple options
    are spelled "[<options>]" without having ellipses at the end,
    which is an oddball.  If we are to treat options specially like
    that anyway, intelligent readers can read an "old-school"
    description "[options]" and understand that that token stands
    for possibly multiple options just fine, and all we have gained
    by going to the "modernized" form is to waste two characters for
    <brackets>.

    I am not saying that we should not apply the other half of the
    patch that makes builtin/pull.c say "[<options>]".  These days,
    many other commands nearby (i.e. the "modern" ones) do use that
    form consistently, so it is an improvement.