Re: [PATCH 2 0/1] Allowing localized substitution hints in parse-options

[Jiang Xin <worldhello.net@gmail.com>]

On Tue, May 28, 2024 at 2:14 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Alexander Shopov <ash@kambanaria.org> writes:
>
> > I hope this time patch submit is better.
> > Requests for changes from previous review should be handled.
> >
> > parse-options.c contains functions and macros to print messages with
> > terms optionally enclosed in chars promting substitution to users such as:
> >
> >   blah-blah-blah <TERM>
> >
> > Since languages using different alphabets or writing systems can translate
> > the term in an obvious manner to prompt the user to substitute them, I expose
> > these character to the translators so the messages can use the same style as
> > elsewhere in git.
>
> Most of the above explanation, starting from "parse-options.c
> contains... " should replace the proposed log message of the main
> patch [1/1], I would think.  Very clearly written.

Typically for a topic with only one commit, it's not necessary to
provide a cover letter but provide details in the commit log instead.

>
> The explanation after "such as:" needs improvement, though.  Are you
> trying to highlight that an explanation is spelled with dashes
> between words format?  Are you trying to highlight that the used
> term is capitalized?  Are you trying to highlight that the term
> comes after explanation?  The answer is none of the above, but it is
> not easy for readers to guess.
>
> One way to make it easier to follow would be to use a more realistic
> example.  The whole proposed log message may become like so:
>
>     parse-options.c API can show help text for an option that takes
>     an argument.  For the "--author" option that takes a name, for
>     example, the program may define the option like so:
>
>         OPT_STRING(0, "author", &au, N_("author"), N_("override author")),
>
>     When the command is run with "-h" (short help) option, the above
>     definition is shown as:
>
>         --[no-]author <author>    override author
>
>     As the program does not accept translated option names, the
>     first part of the above, "--[no-]author", is given as-is, but
>     the string "author" in a pair of "<>", and the explanation
>     "override author" may be translated into user's language.
>
>     The user's language may use a convention to mark a replaceable
>     part of the command line (called a "placeholder string")
>     differently from enclosing it inside a pair of "<>", but the
>     implementation in parse-options.c hardcodes "<%s>".

I guess the reason some people don't like the markers of placeholders
(such as "<" and ">" characters) is that such characters have special
meanings (used as IO redirection) in shell programming and they can be
replaced with safer characters for languages other than English.

>
>     Allow translators to specify the presentation of a placeholder
>     string for their languages by overriding the "<%s>".
>
> > Comments to the translators are shorter than before but hopefully they are
> > not cryptic.
>
> What is cryptic here is what "than before" refers to---compared
> what?
>
>   ... goes and looks ...
>
> Ah, this is an updated patch for an earlier attempt
>
>   https://lore.kernel.org/git/20240421191458.5411-1-ash@kambanaria.org/
>
> Thanks for sticking with this topic.  Very much appreciated.
>
>