Am 07.03.2018 um 23:45 schrieb Junio C Hamano: > kalle <kalle@xxxxxxxxxxxxxxxxxxx> writes: > >> Am 06.03.2018 um 02:36 schrieb Junio C Hamano: >>> kalle <kalle@xxxxxxxxxxxxxxxxxxx> writes: >>> >>>> -In the explanation of the option --reference: shouldn't there be >>>> written '<repository>' instead of 'reference repository'? >>> >>> "Shouldn't X be Y?" is not an effective way to communicate; it >>> solicits a "no, the current one is fine." without any explanation. >>> >>> If you think X should be Y for some reason, please say "I think X >>> should be Y BECAUSE Z" instead. Without stating why you think >>> differently from what those who wrote the current text, it is hard >>> for people to respond either with "Yeah, you're right---I agree >>> with Z" or with "No, Z does not hold because..." >>> >> I wrote this, because when it is written about 'reference repository', I >> consider it not totally clear, which repository is meant, as the option >> '--reference <repository>' only names one as <repository>. >> For reasons of clearness, I now propose writing "reference repository >> <repository>". > > I do not have particularly a strong opinion, but I think it is very > sensible to call the value given to the option "--reference" with a > phrase that is not just "repository". i agree and didn't state this. i proposed to add <repository>. <repository> could also be named <reference-repository>. > > As the command line of "clone" must name one repository (i.e. the > one which we clone from), and its "--reference" option must name > another repository as its value (i.e. the one that we borrow from in > order to reduce the object transfer), calling both <repository> > makes it easier to confuse readers you made my point unless the writer carefully makes > sure that <repository> in the desription is unambiguous and it is > clear which one of these two repositories is being discussed by the > context.> > I just re-read the existing Documentation/git-clone.txt and looked > for "reference". All uses of "reference repository" in the prose > made sense and I found it would not be an improvement if any of them > is replaced with just "repository". This was never my proposal, though. It may be helpful to add > something like: > > --reference[-if-able] <repository>:: > + Define a repository (reference repository) to borrow > + objects from. > If the reference repository is on the local machine, > ... > > to define which repository we mean by that term, though. > in all, it was just meant as a quite small proposal for me. i also don't have any strong opinion about it. greetings, kalle
