| Message ID | 20240525122514.2608-1-ash@kambanaria.org (mailing list archive) |
|---|---|
| Headers | show |
| Series | Allowing localized substitution hints in parse-options | expand |
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. 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 <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. > >