Re: [PATCH 08/11] doc: trailer.<token>.command: refer to existing example

From: Linus Arver <linusa@google.com>
Date: May 10, 2023, 07:08 UTC
Message-ID: <owlyh6skmznt.fsf@fine.c.googlers.com>
In-Reply-To: <xmqqwn1imwqk.fsf@gitster.g>

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

> "Linus Arver via GitGitGadget" <gitgitgadget@gmail.com> writes:

>> From: Linus Arver <linusa@google.com>

>> Signed-off-by: Linus Arver <linusa@google.com>
>> ---
>>   Documentation/git-interpret-trailers.txt | 9 +++++----
>>   1 file changed, 5 insertions(+), 4 deletions(-)

> This patch has more annoying "just rewrapping the text in a strange
> way without changing anything"

Noted. I will remove the whitespace churn in v2.

> than the real change which is to
> enclose <value> inside the angle brackets (which is good) and adding
> a new sentence.

I should probably move the angle bracket changes into 07.

> We are discouraging the use of .command and recommending folks to
> use .cmd instead, by the way.

I was motivated to add the reference to the example because I could not understand what

     Instead the first occurrence of substring $ARG is replaced by the
     value that would be passed as argument.

meant in the existing language. In hindsight maybe it's not worth adding the reference, because of the deprecation.

> At some point we may drop the
> example, and adding a reference to the example would mean somebody
> needs to remember removing this when it happens.

Wouldn't we also delete the entire `trailer.<token>.command::` section (and therefore the reference to the example) also at the same time?

Show 7 quoted lines

>> diff --git a/Documentation/git-interpret-trailers.txt  
>> b/Documentation/git-interpret-trailers.txt
>> index ac448fd732e..5ca758e363f 100644
>> --- a/Documentation/git-interpret-trailers.txt
>> +++ b/Documentation/git-interpret-trailers.txt
>> @@ -234,10 +234,11 @@ trailer.<token>.ifmissing::
>>   	that option for trailers with the specified <token>.

Show 15 quoted lines

>>   trailer.<token>.command::
>> -	This option behaves in the same way as 'trailer.<token>.cmd', except
>> -	that it doesn't pass anything as argument to the specified command.
>> -	Instead the first occurrence of substring $ARG is replaced by the
>> -	value that would be passed as argument.
>> +	This option behaves in the
>> +	same way as 'trailer.<token>.cmd', except that it doesn't pass  
>> anything as
>> +	argument to the specified command. Instead the first occurrence of  
>> substring
>> +	$ARG is replaced by the <value> from the trailer. See the
>> +	'trailer.see.command' trailer example in the "EXAMPLES" section below.
>>   +
>>   The 'trailer.<token>.command' option has been deprecated in favor of
>>   'trailer.<token>.cmd' due to the fact that $ARG in the user's command is