Re: [PATCH 1/2] Documentation: replace sha1 by SHA-1

[Junio C Hamano <gitster@pobox.com>]

Jeff King <peff@peff.net> writes:

> On Fri, Apr 24, 2009 at 04:49:34PM +0200, Michael J Gruber wrote:
>
>> --- a/Documentation/git-cat-file.txt
>> +++ b/Documentation/git-cat-file.txt
>> @@ -76,7 +76,7 @@ If '--batch' is specified, output of the following form is printed for each
>>  object specified on stdin:
>>  
>>  ------------
>> -<sha1> SP <type> SP <size> LF
>> +<SHA-1> SP <type> SP <size> LF
>>  <contents> LF
>>  ------------
>
> Maybe it is just me, but I find the original for this one easier to
> read. Perhaps because <sha1> is really a variable name here (but for a
> human reader to interpret instead of a compiler), so I find the
> punctuation and capitalization distracting.
>
> I wonder if all <sha1> should simply be left as-is.

Or spell them using their official terminology "object name".

In all places in the documentation these two patches touch, that is what
matters.  They are computed by taking a hash over a defined format, and
the hash function we use happens to be SHA-1, but that is not important to
somebody who wants to use "cat-file" nor even to somebody who wants to
reimplement it.  I think hash-object should mention what the actual hash
function is, but even that should not stress the SHA-1-ness of the hash.
That's just too much implementation detail.

And sha1 and SHA1 are both accepted colloquial forms of "object name" in
the git world.  I think it is Ok to leave it in the IRC transcript "pack
heuristics" documentation (and I'd prefer that particular one left
untouched).  If we want to go formal in the documentation, I think
rewriting them to SHA-1 misses the point.