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

From: Derrick Stolee <stolee@gmail.com>
Date: Jan 6, 2021, 12:03 UTC
Message-ID: <b6c68abd-e6b7-acec-6b1f-f915fe20e2e1@gmail.com>
In-Reply-To: <xmqqwnwqtuj1.fsf@gitster.c.googlers.com>

On 1/6/2021 2:05 AM, Junio C Hamano wrote:

Show 9 quoted lines

> 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.

Show 7 quoted lines

>   * `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