Alexander Shopov [off-list ref] 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.
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>".
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.
On Tue, May 28, 2024 at 2:14 AM Junio C Hamano [off-list ref] wrote:
Alexander Shopov [off-list ref] writes:
quoted
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>".
quoted
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.