git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH 4 1/1] parse-options: localize mark-up of placeholder text in the short help

From
Junio C Hamano <gitster@pobox.com>
Date
Dec 28, 2024, 16:55 UTC
Message-ID
<xmqqy0zz3fxv.fsf@gitster.g>
In-Reply-To
<20241228114221.10351-4-ash@kambanaria.org>
Alexander Shopov <ash@kambanaria.org> 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.

Show 11 quoted lines
> 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.
Show 14 quoted lines
> 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.
Show 8 quoted lines
> +			  _("[=<%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".
Show 7 quoted lines
>  	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) : _("..."));
 }
Previous: Alexander ShopovNext: Jiang Xin
Message 15 of 16 in “[RESUBMIT 2nd] Consistency for substitution hints (i18n) 0/1]”
  1. [RESUBMIT 2nd] Consistency for substitution hints (i18n) 0/1]Alexander Shopov, Apr 21, 2024
  2. [RESUBMIT 2nd] Consistency for substitution hints (i18n) 1/1] parse-options: use localized substitution hintsAlexander Shopov, Apr 21, 2024
  3. Junio C HamanoApr 21, 2024
  4. 0/1 Allowing localized substitution hints in parse-optionsAlexander Shopov, May 25, 2024
  5. Junio C HamanoMay 27, 2024
  6. Jiang XinMay 28, 2024
  7. 1/1 parse-options: allow localized substitution hints in macrosAlexander Shopov, May 25, 2024
  8. Junio C HamanoMay 27, 2024
  9. 0/1 parse-options: localize mark-up of placeholder text in the short helpAlexander Shopov, Jul 7, 2024
  10. 1/1 parse-options: localize mark-up of placeholder text in the short helpAlexander Shopov, Jul 7, 2024
  11. Alexander ShopovJul 14, 2024
  12. Junio C HamanoJul 15, 2024
  13. 0/1 Localize mark-up of placeholder text in the short helpAlexander Shopov, Dec 28, 2024
  14. 1/1 parse-options: localize mark-up of placeholder text in the short helpAlexander Shopov, Dec 28, 2024
  15. Junio C HamanoDec 28, 2024
  16. Jiang XinDec 30, 2024

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.