Re: [PATCH v3 2/5] advice: make all entries stylistically consistent

["Kristoffer Haugsbakk" <code@khaugsbakk.name>]

On Tue, Mar 5, 2024, at 00:52, Junio C Hamano wrote:
>>  	detachedHead::
>> -		Advice shown when you used
>> +		Shown when the user uses
>>  		linkgit:git-switch[1] or linkgit:git-checkout[1]
>> -		to move to the detached HEAD state, to instruct how to
>> +		to move to the detached HEAD state; instruct how to
>>  		create a local branch after the fact.
>
> I agree "Advice shown when" -> "Shown when" is a good change for
> brevity, but I do not think the other change is an improvement.
>
> This advice message is shown when the user does X, in order to
> instruct the user how to do Y after that.  And "to instruct" is a
> common way to say the same thing as "in order to instruct".

Well argued. I’ll go back to the comma.

>>  	implicitIdentity::
>> -		Advice on how to set your identity configuration when
>> -		your information is guessed from the system username and
>> -		domain name.
>> +		Shown when the user's information is guessed from the
>> +		system username and domain name: tell the user how to
>> +		set their identity configuration.
>
> Should that be a colon?  Stopping a half-sentence and connecting to
> another half-sentence is usually done with a semicolon (like you did
> in the new version of detachedHEAD above).
>
> 	Shown when ... and domain name, to tell the user how to set
> 	their identity configuration.
>
> perhaps?  There may be other similar entries whose updated text uses
> colon followed by an imperative sentence, but I didn't look very
> carefully.

I’ll spoil it for you: there are a lot of colons. ;)

Good point. I’ll go over it again and probably use more semicolons
instead.

>>  	statusUoption::
>> -		Advise to consider using the `-u` option to linkgit:git-status[1]
>> -		when the command takes more than 2 seconds to enumerate untracked
>> -		files.
>> +		Shown when linkgit:git-status[1] takes more than 2
>> +		seconds to enumerate untracked files: consider using the
>> +		`-u` option.
>
> Earlier ones after a colon (or semicolon in detachedHEAD case), you
> gave an order to the advice message (e.g. "hey detachedHead advice,
> tell the user how to create a local branch"), but this one is giving
> an order to the end user, which feels inconsistent.
>
> I do not have a strong objection against giving an order to the
> advice message, as long as it is done consistently.  If we did so,
> the part after the colon would start with "instruct the user ..." or
> "tell the user ..." and the like, and the gist of what this one
> would say would be "shown when it is taking too long: suggest the
> user to consider `-u`".

Yeah, I paused for a minute when writing that. I’ll change to “tell” or
something similar.

> FWIW, my earlier "in order to" took an approach that is different
> from either of the two "giving an order" approaches.  I was trying
> to make the description explain what the message tries to do and/or
> why the message is given (e.g., "shown if it takes too long in order
> to suggest users to consider the -u option").
>
> Thanks.

-- 
Kristoffer Haugsbakk