Re: [PATCH v3 2/5] advice: make all entries stylistically consistent
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Mar 4, 2024, 23:52 UTC
- Message-ID
- <xmqq4jdlmu6q.fsf@gitster.g>
- In-Reply-To
- <d48b4719c275ef06da014b6d22983db9ae484db2.1709590037.git.code@khaugsbakk.name>
Kristoffer Haugsbakk <code@khaugsbakk.name> writes:
Show 14 quoted lines
> 1. Use “shown” instead of “advice shown” > • “advice” is implied and a bit repetitive > 2. Use “when” instead of “if” > 3. Lead with “Shown when” and end the entry with the effect it has, > where applicable > 4. Use “the user” instead of “a user” or “you” > 5. detachedHead: connect clause with a semicolon to make the sentence > flow better in this new context > 6. implicitIdentity: rewrite description in order to lead with *when* > the advice is shown (see point (3)) > 7. Prefer the present tense (with the exception of pushNonFFMatching) > 8. Use a colon to connect the last clause instead of a comma > 9. waitingForEditor: give example of relevance in this new context > 10. pushUpdateRejected: exception to the above principles
I'll let others comment on these as general principles. I do not immediately see anything objectionable, but I may change my mind after reading the updated text in the patch.
> Suggested-by: Junio C Hamano <gitster@pobox.com>
I am getting too much credit for this; I merely suggested to use "when" instead of "if" in the one you are newly adding.
Show 7 quoted lines
> 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".
Show 7 quoted lines
> 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.
Show 7 quoted lines
> 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`".
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.