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
