From: Anders Melchiorsen <mail@cup.kalibalik.dk>
Date: Sun, 02 Nov 2008 17:08:56 GMT
Subject: Re: [PATCH 1/7] Documentation: do not use regexp in refspec descriptions
Message-ID: <877i7mnjh3.fsf@cup.kalibalik.dk>
In-Reply-To: <7v7i7pba2x.fsf@gitster.siamese.dyndns.org>

Junio C Hamano <gitster@pobox.com> writes:

> Anders Melchiorsen <mail@cup.kalibalik.dk> writes:
>
>> The syntax is now easier to read, though wrong: all parts of the
>> refspec are actually optional.
>
> It probably is easier to read, but strictly speaking it is not
> wrong. The two parts, <src> and <dst>, _always_ exist, even though
> either or both of them can be an empty string.

The colon is not required, though the format suggests that it is.


>>  <refspec>...::
>>  	The canonical format of a <refspec> parameter is
>> -	`+?<src>:<dst>`; that is, an optional plus `{plus}`, followed
>> +	`[+]<src>:<dst>`; that is, an optional plus `{plus}`, followed
>>  	by the source ref, followed by a colon `:`, followed by
>>  	the destination ref.
>
> I am wondering if it would be clearer and easier to understand if we just
> said:
>
>   	The canonical format of a <refspec> parameter is
> 	an optional plus `{plus}`, followed by the source ref,
>         followed by a colon `:`, followed by the destination ref.
> 	Find various forms of refspecs in examples section.

I think that is an improvement. Removing the word "canonical" would be
even better, IMHO.


Anders.