Alexander Shopov <ash@xxxxxxxxxxxxxx> writes:
> Subject: Re: [PATCH 4 1/1] parse-options: localize mark-up of placeholder text in the short help
It is more common to see "[PATCH v4 1/1]" around here. In fact, I
suspect that you have to fight the tool to have them produce "[PATCH
4 1/1]".
Not that it matters to me personally (as "git am" on the receiving
end will strip it), but when looking for a specific version of your
patch from the mailing list archive, people may find it harder than
necessary because of the subtle difference.
> i18n: expose substitution hint chars in functions and macros to
> translators
> ...
> 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.
Very well written.
> diff --git a/parse-options.c b/parse-options.c
> index 33bfba0ed4..8904345c07 100644
> --- a/parse-options.c
> +++ b/parse-options.c
> @@ -1076,11 +1076,23 @@ 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>]";
> + s = literal ? "[=%s]" :
> + /* TRANSLATORS: %s is a command line argument name, `<>' prompt the user to supply a value for it.
> + Change only the `<>' characters to something else if you use another convention for this.
> + Most translations leave this message as is. */
> + _("[=<%s>]");
This is way too wide. Documentation/CodingGuidelines should have
something to say on this, but in case it does not, we try to allow
those with 80-column terminals to read our code comfortably, and it
is even better to allow us to do so after a patch is quoted a few
times (i.e. adding a few columns on the left edge), so a practical
limit may be around 70-columns.
Also, our multi-line comments have opening slash-asterisk and closing
asterisk-slash on their own line.
This part is giving a help for the option value argument for a long
option, i.e. for "git subcommand --option[=<value>]", we are talking about
the "[=<value>]" part. It is not clear "command line argument name"
conveys that. Something along this line, perhaps?
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>]");
> else
> - s = literal ? "[%s]" : "[<%s>]";
> + s = literal ? "[%s]" :
> + /* TRANSLATORS: %s is a command line argument name, `<>' prompt the user to supply a value for it.
> + Change only the `<>' characters to something else if you use another convention for this.
> + Most translations leave this message as is. */
> + _("[<%s>]");
Ditto, except that this is for "the short form".
> else
> - s = literal ? " %s" : " <%s>";
> + s = literal ? " %s" :
> + /* TRANSLATORS: %s is a command line argument name, `<>' prompt the user to supply a value for it.
> + Change only the `<>' characters to something else if you use another convention for this.
> + Most translations leave this message as is. */
> + _(" <%s>");
Ditto, except that this is for "a value given to a command line option",
not specific to either long or short form.
> return utf8_fprintf(outfile, s, opts->argh ? _(opts->argh) : _("..."));
> }
I'll queue with the following change on top.
Thanks.
parse-options.c | 55 ++++++++++++++++++++++++++++++++++++++++---------------
1 file changed, 40 insertions(+), 15 deletions(-)
diff --git c/parse-options.c w/parse-options.c
index 8904345c07..3ff6a5d1fa 100644
--- c/parse-options.c
+++ w/parse-options.c
@@ -1076,23 +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]" :
- /* TRANSLATORS: %s is a command line argument name, `<>' prompt the user to supply a value for it.
- Change only the `<>' characters to something else if you use another convention for this.
- Most translations leave this message as is. */
- _("[=<%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]" :
- /* TRANSLATORS: %s is a command line argument name, `<>' prompt the user to supply a value for it.
- Change only the `<>' characters to something else if you use another convention for this.
- Most translations leave this message as is. */
- _("[<%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" :
- /* TRANSLATORS: %s is a command line argument name, `<>' prompt the user to supply a value for it.
- Change only the `<>' characters to something else if you use another convention for this.
- Most translations leave this message as is. */
- _(" <%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) : _("..."));
}
