From 5b34dd08d0ffc967b92abe187cc890d52ade5ac7 Mon Sep 17 00:00:00 2001 From: Alexander Shopov Date: Sat, 28 Dec 2024 12:42:18 +0100 Subject: parse-options: localize mark-up of placeholder text in the short help i18n: expose substitution hint chars in functions and macros to translators For example (based on builtin/commit.c and shortened): the "--author" option takes a name. In source this can be represented as: OPT_STRING(0, "author", &force_author, N_("author"), N_("override author")), When the command is run with "-h" (short help) option (git commit -h), the above definition is displayed as: --[no-]author override author Git does not use translated option names so the first part of the above, "--[no-]author", is given as-is (it is based on the 2nd argument of OPT_STRING). However the string "author" in the pair of "<>", and the explanation "override author for commit" 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>". In case the translator's writing system is sufficiently different than Latin the "<>" characters can be substituted by an empty string thus effectively skipping them in the output. For example languages with uppercase versions of characters can use that to deliniate replaceability. Alternatively a translator can decide to use characters that are visually close to "<>" but are not interpreted by the shell. Signed-off-by: Alexander Shopov Signed-off-by: Junio C Hamano --- parse-options.c | 43 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 3 deletions(-) (limited to 'parse-options.c') diff --git a/parse-options.c b/parse-options.c index 33bfba0ed4..3ff6a5d1fa 100644 --- a/parse-options.c +++ b/parse-options.c @@ -1076,11 +1076,48 @@ static int usage_argh(const struct option *opts, FILE *outfile) !opts->argh || !!strpbrk(opts->argh, "()<>[]|"); if (opts->flags & PARSE_OPT_OPTARG) if (opts->long_name) - s = literal ? "[=%s]" : "[=<%s>]"; + /* + * TRANSLATORS: The "<%s>" part of this string + * stands for an optional value given to a command + * line option in the long form, and "<>" is there + * as a convention to signal that it is a + * placeholder (i.e. the user should substitute it + * with the real value). If your language uses a + * different convention, you can change "<%s>" part + * to match yours, e.g. it might use "|%s|" instead, + * or if the alphabet is different enough it may use + * "%s" without any placeholder signal. Most + * translations leave this message as is. + */ + s = literal ? "[=%s]" : _("[=<%s>]"); else - s = literal ? "[%s]" : "[<%s>]"; + /* + * TRANSLATORS: The "<%s>" part of this string + * stands for an optional value given to a command + * line option in the short form, and "<>" is there + * as a convention to signal that it is a + * placeholder (i.e. the user should substitute it + * with the real value). If your language uses a + * different convention, you can change "<%s>" part + * to match yours, e.g. it might use "|%s|" instead, + * or if the alphabet is different enough it may use + * "%s" without any placeholder signal. Most + * translations leave this message as is. + */ + s = literal ? "[%s]" : _("[<%s>]"); else - s = literal ? " %s" : " <%s>"; + /* + * TRANSLATORS: The "<%s>" part of this string stands for a + * value given to a command line option, and "<>" is there + * as a convention to signal that it is a placeholder + * (i.e. the user should substitute it with the real value). + * If your language uses a different convention, you can + * change "<%s>" part to match yours, e.g. it might use + * "|%s|" instead, or if the alphabet is different enough it + * may use "%s" without any placeholder signal. Most + * translations leave this message as is. + */ + s = literal ? " %s" : _(" <%s>"); return utf8_fprintf(outfile, s, opts->argh ? _(opts->argh) : _("...")); } -- cgit v1.3 From 1782abd7734acffb8ebc37b74e120fd4c4b9c4cc Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 16 Jan 2025 13:35:49 -0800 Subject: parse-options: add show_usage_with_options_if_asked() Many commands call usage_with_options() when they are asked to give the help message, but it sends the help text to the standard error stream. When the user asked for it with "git cmd -h", the help message is the primary output from the command, hence we should send it to the standard output stream, instead. Introduce a helper function that captures the common pattern if (argc == 2 && !strcmp(argv[1], "-h")) usage_with_options(usage, options); and replaces it with show_usage_with_options_if_asked(argc, argv, usage, options); to help correct code paths. Note that this helper function still exits with status 129, and t0012 insists on it. After converting all the mistaken callers of usage_with_options() to call this new helper, we may want to address it---the end user is asking us to give the help text, and we are doing exactly as asked, so there is no reason to exit with non-zero status. Suggested-by: Jeff King Signed-off-by: Junio C Hamano --- parse-options.c | 10 ++++++++++ parse-options.h | 4 ++++ 2 files changed, 14 insertions(+) (limited to 'parse-options.c') diff --git a/parse-options.c b/parse-options.c index 33bfba0ed4..4051a8e1d1 100644 --- a/parse-options.c +++ b/parse-options.c @@ -1282,6 +1282,16 @@ void NORETURN usage_with_options(const char * const *usagestr, exit(129); } +void show_usage_with_options_if_asked(int ac, const char **av, + const char * const *usagestr, + const struct option *opts) +{ + if (ac == 2 && !strcmp(av[1], "-h")) { + usage_with_options_internal(NULL, usagestr, opts, 0, 0); + exit(129); + } +} + void NORETURN usage_msg_opt(const char *msg, const char * const *usagestr, const struct option *options) diff --git a/parse-options.h b/parse-options.h index d01361ca97..39f0886254 100644 --- a/parse-options.h +++ b/parse-options.h @@ -402,6 +402,10 @@ int parse_options(int argc, const char **argv, const char *prefix, NORETURN void usage_with_options(const char * const *usagestr, const struct option *options); +void show_usage_with_options_if_asked(int ac, const char **av, + const char * const *usage, + const struct option *options); + NORETURN void usage_msg_opt(const char *msg, const char * const *usagestr, const struct option *options); -- cgit v1.3