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 <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 <ash@kambanaria.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/parse-options.c b/parse-options.c
index 33bfba0ed4a0eaad1bb3ce61876d6c01b6d2c6aa..3ff6a5d1fac125091808e7a907227026fe7d45df 100644 (file)
--- 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) : _("..."));
 }