Re: [PATCH 2 0/1] Allowing localized substitution hints in parse-options

From: Junio C Hamano <gitster@pobox.com>
Date: May 27, 2024, 18:14 UTC
Message-ID: <xmqqzfsb86le.fsf@gitster.g>
In-Reply-To: <20240525122514.2608-1-ash@kambanaria.org>

Alexander Shopov <ash@kambanaria.org> writes:

Show 12 quoted lines

> 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.