kalle <[email protected]> writes:
> Am 06.03.2018 um 02:36 schrieb Junio C Hamano:
>> kalle <[email protected]> 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".
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 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". 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.
