Eric Sunshine <sunshine@xxxxxxxxxxxxxx> writes:
>> There's even an example of such usage in the README.
>>
>> Signed-off-by: Štěpán Němec <stepnem@xxxxxxxx>
>> ---
>> diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump
>> @@ -9,7 +9,7 @@ The <mode> parameter is one of:
>>
>> diff: elements are diff hunks. Arguments are given to diff.
>>
>> -merge: elements are merge conflicts. Arguments are ignored.
>> +merge: elements are merge conflicts. Arguments are given to ls-files -u.
>
> Should "ls-files -u" be formatted with backticks?
>
> Arguments are passed to `git ls-files -u`.
Probably not in this case, as this is end-user visible help message
that is not formatted but given to the terminal.
The whole preimage looks like this:
usage: git jump [--stdout] <mode> [<args>]
Jump to interesting elements in an editor.
The <mode> parameter is one of:
diff: elements are diff hunks. Arguments are given to diff.
merge: elements are merge conflicts. Arguments are ignored.
grep: elements are grep hits. Arguments are given to git grep or, if
configured, to the command in `jump.grepCmd`.
ws: elements are whitespace errors. Arguments are given to diff --check.
If the optional argument `--stdout` is given, print the quickfix
lines to standard output instead of feeding it to the editor.
and it is already a mixture. "given to `git grep`" is not quoted,
neither is "given to `diff --check`" or "given to `diff`"
I think rule for help/usage messages should be that
- anything that the end-user may want to cut&paste should be left
alone to make it easier to cut,
- but at the same time the message should make it clear which part
of a sentence is what,
Clicking on `--stdout` or `jump.grepCmd` does not include the
surrounding quotes, at least in my environment, so the use of
backquotes in these places satisfy the two goals, it seems.
Unlike `--stdout` and `jump.grepCmd`, all other things that are not
quoted, including the one that is added by this patch (i.e.,
"ls-files -u"), are something the end-user needs to cut and paste in
reaction to seeing this error message, so as long as they are
understandable in the sentences they appear in, I think they are
fine.
If we wanted to standardize, we may start to encourage consistent
use of quoting, but I do not think it should be part of this topic.
Thanks for being careful and thoughtful.
