Re* [PATCH] builtin/*: update usage format

Commit Message

Junio C Hamano Jan. 6, 2021, 7:05 a.m. UTC

"阿德烈 via GitGitGadget"  <[e-mail]> writes:

> From: ZheNing Hu <[e-mail]>
>
> According to the "Error Messages" section of
> Documentation/CodingGuidelines, we should not end in a full
> stop or start with a capital letter.

Yup, error("message"), die("message") and warn("messages") lack the
final full stop and starts with lowercase.

>  		OPT_CMDMODE(0, "abort", &resume.mode,
> -			N_("restore the original branch and abort the patching operation."),
> +			N_("restore the original branch and abort the patching operation"),
>  			RESUME_ABORT),

But is this an error message?  I do not think so.

> ...
>  	struct option options[] = {
> -		OPT__QUIET(&quiet, N_("Suppress output for setting url of a submodule")),
> +		OPT__QUIET(&quiet, N_("suppress output for setting url of a submodule")),
>  		OPT_END()
>  	};

Having said that, I do not *mimd* standardising the usage help
strings in the same way.  I do not think the "Error Messages"
section is the one we want to use for the justification of this
patch.

Perhaps a preparatory patch like the attached would be a good way
forward?  I dunno.

---- >8 -------- >8 -------- >8 -------- >8 -------- >8 ----
Subject: parse-options: format argh like error messages

"Keep it homogeneous across the repository" is in general a
guideline that can be used to converge to a good practice, but
we can be a bit more prescriptive in this case.  Just like the
messages we give die(_("...")) are formatted without the final
full stop and without the initial capitalization, most of the
argument help text are already formatted that way, and we want
to encourage that as the house style.

Noticed-by: ZheNing Hu <[e-mail]>
Signed-off-by: Junio C Hamano <[e-mail]>
---
 parse-options.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

Comments

Derrick Stolee Jan. 6, 2021, 12:03 p.m. UTC | #1

On 1/6/2021 2:05 AM, Junio C Hamano wrote:
> Subject: parse-options: format argh like error messages
> 
> "Keep it homogeneous across the repository" is in general a
> guideline that can be used to converge to a good practice, but
> we can be a bit more prescriptive in this case.  Just like the
> messages we give die(_("...")) are formatted without the final
> full stop and without the initial capitalization, most of the
> argument help text are already formatted that way, and we want
> to encourage that as the house style.

It's tough to "keep it homogeneous" when the repository isn't
already in that state. Thanks, ZheNing, for working to improve
that situation.

>   * `argh`::
> - *   token to explain the kind of argument this option wants. Keep it
> - *   homogeneous across the repository. Should be wrapped by N_() for
> - *   translation.
> + *   token to explain the kind of argument this option wants. Does not
> + *   begin in capital letter, and does not end with a full stop.
> + *   Should be wrapped by N_() for translation.

I think this more-specific language is helpful.

Thanks,
-Stolee

Patch

diff --git c/parse-options.h w/parse-options.h
index 7030d8f3da..ff6506a504 100644
--- c/parse-options.h
+++ w/parse-options.h
@@ -82,9 +82,9 @@  typedef enum parse_opt_result parse_opt_ll_cb(struct parse_opt_ctx_t *ctx,
  *   stores pointers to the values to be filled.
  *
  * `argh`::
- *   token to explain the kind of argument this option wants. Keep it
- *   homogeneous across the repository. Should be wrapped by N_() for
- *   translation.
+ *   token to explain the kind of argument this option wants. Does not
+ *   begin in capital letter, and does not end with a full stop.
+ *   Should be wrapped by N_() for translation.
  *
  * `help`::
  *   the short help associated to what the option does.