2015-10-19 23:17 GMT-06:00 Junio C Hamano <gitster@xxxxxxxxx>: > Alex Henrie <alexhenrie24@xxxxxxxxx> writes: > >> 2015-10-16 11:42 GMT-06:00 Junio C Hamano <gitster@xxxxxxxxx>: >>> >>> 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. I understand now, thanks. I really appreciate your commitment to being consistent. > [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. I pushed to change [options] to [<options>] because even if the angle brackets don't help new users or translators in this particular case, the angle brackets encourage Git authors to use angle brackets when writing commands that are not so easy to understand. If you think that [<option>...] is better because it is even more consistent, I would be happy to send a patch to make that change. Anyway, thanks again for your attention to detail. -Alex -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html