From: kalle <kalle@projektwerkstatt.de>
Date: Wed, 07 Mar 2018 23:34:14 GMT
Subject: Re: git help clone: questions
Message-ID: <725671ac-0a36-cd9e-c605-6ffdcb7e9a33@projektwerkstatt.de>
In-Reply-To: <xmqq4llrzer5.fsf@gitster-ct.c.googlers.com>



Am 07.03.2018 um 23:45 schrieb Junio C Hamano:
> kalle <kalle@projektwerkstatt.de> writes:
> 
>> Am 06.03.2018 um 02:36 schrieb Junio C Hamano:
>>> kalle <kalle@projektwerkstatt.de> 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