From: Philip Oakley <philipoakley@iee.org>
Date: Tue, 16 Aug 2016 22:11:05 GMT
Subject: Re: [PATCH v1 1/3] doc: commit: --fixup/--squash can take a commit revision
Message-ID: <CAE3EC6B78644AA8BD07FED08AF44EAE@PhilipOakley>
In-Reply-To: <F18C2CCC29E5470CA1374D9718B2A3E6@PhilipOakley>

From: "Philip Oakley" <philipoakley@iee.org>
> From: "Junio C Hamano" <gitster@pobox.com>
>> "Philip Oakley" <philipoakley@iee.org> writes:
>>
>>>> I think the
>>>> use of "commit" in an angle-bracket-pair in the label for the
>>>> section, i.e. "--fixup=<commit>", has been considered to be clear
>>>> enough to tell that you can use usual extended SHA-1 syntax to
>>>> specify the commit you want to talk about,
>>>
>>> I certainly hadn't picked up on that ability to use the extended sha1
>>> syntax (specifying revisions...) here.
>>
>> By "has been considered", I meant that the documentation text is
>> still open for improvement.  I just didn't find rewording "commit"
>> with "commit revision" is that improvement we need there.
>>
>> Perhaps we need to have somewhere central a section that explains
>> various notations used in the documentation set.  I think it is safe
>> to say something like "unless otherwise qualified, <commit> (or any
>> object type in an angle-bracket-pair) is used as a placeholder to
>> take any acceptable way to spell object names (cf. gitrevisions for
>> details)" these days [*1*].
>
> True. I'm cautious that we may accidentally still hide it in another 
> document that the user doesn't see when reading "this" (or any other)  man 
> page.
>
> Your sentence is short enough to be added to those few key pages that 
> users refer to to get them started in the right direction.
>
>> *1* In ancient days I think some plumbing commands only took 40-hex
>> object names, but as far as I know they've all been updated.
>> --

I'll take the patch series away and have a rework over the coming week or 
so.

Philip