Re: [PATCH v3 1/2] name-rev: deprecate --stdin in favor of --annotate-text

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

Philip Oakley <philipoakley@iee.email> writes:

>>  --stdin::
>> +	This option is deprecated in favor of 'git name-rev --annotate-stdin'.
>> +	They are functionally equivalent.
>> +
>> +--annotate-stdin::
>>  	Transform stdin by substituting all the 40-character SHA-1
>>  	hexes (say $hex) with "$hex ($rev_name)".  When used with
>>  	--name-only, substitute with "$rev_name", omitting $hex
>> -	altogether.  Intended for the scripter's use.
>> +	altogether.
>
> Is there a preferred order for the old/new variant documentation?

If the surrounding list has a natural order of its own, e.g.  the
list is sorted alphabetically to help people locate an item by name,
it is OK to have old and new in that order and older one may appear
before the newer one.

But otherwise it may make sense to show the newer one first with the
mention of the older one as if it were a side note, especially when
they can appear next to each other like the one we are looking at, I
would think.

I do not think we have written preference.  It probably would help
to have a short paragraph in the coding guidelines document.

Thanks.