On Tue, May 28, 2024 at 2:14 AM Junio C Hamano <gitster@xxxxxxxxx> wrote:
>
> Alexander Shopov <ash@xxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxx/
>
> Thanks for sticking with this topic. Very much appreciated.
>
>
