C style: use standard style for "TRANSLATORS" comments

Change all the "TRANSLATORS: [...]" comments in the C code to use the
regular Git coding style, and amend the style guide so that the
example there uses that style.

This custom style was necessary back in 2010 when the gettext support
was initially added, and was subsequently documented in commit
cbcfd4e3ea ("i18n: mention "TRANSLATORS:" marker in
Documentation/CodingGuidelines", 2014-04-18).

GNU xgettext hasn't had the parsing limitation that necessitated this
exception for almost 3 years. Since its 0.19 release on 2014-06-02
it's been able to recognize TRANSLATOR comments in the standard Git
comment syntax[1].

Usually we'd like to keep compatibility with software that's that
young, but in this case literally the only person who needs to be
using a gettext newer than 3 years old is Jiang Xin (the only person
who runs & commits "make pot" results), so I think in this case we can
make an exception.

This xgettext parsing feature was added after a thread on the Git
mailing list[2] which continued on the bug-gettext[3] list, but we
never subsequently changed our style & styleguide, do so.

There are already longstanding changes in git that use the standard
comment style & have their TRANSLATORS comments extracted properly
without getting the literal "*"'s mixed up in the text, as would
happen before xgettext 0.19.

Commit 7ff2683253 ("builtin-am: implement -i/--interactive",
2015-08-04) added one such comment, which in commit df0617bfa7 ("l10n:
git.pot: v2.6.0 round 1 (123 new, 41 removed)", 2015-09-05) got picked
up in the po/git.pot file with the right format, showing that Jiang
already runs a modern xgettext.

The xgettext parser does not handle the sort of non-standard comment
style that I'm amending here in sequencer.c, but that isn't standard
Git comment syntax anyway. With this change to sequencer.c & "make
pot" the comment in the pot file is now correct:

     #. TRANSLATORS: %s will be "revert", "cherry-pick" or
    -#. * "rebase -i".
    +#. "rebase -i".

1. http://git.savannah.gnu.org/cgit/gettext.git/commit/?id=10af7fe6bd
2. <2ce9ec406501d112e032c8208417f8100bed04c6.1397712142.git.worldhello.net@gmail.com>
   (https://public-inbox.org/git/2ce9ec406501d112e032c8208417f8100bed04c6.1397712142.git.worldhello.net@gmail.com/)
3. https://lists.gnu.org/archive/html/bug-gettext/2014-04/msg00016.html

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Acked-by: Jiang Xin <worldhello.net@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index a4191aa3889000ed844678331e5fd7f9fc628ba4..9fd7383819930c89632e57c2694c318a2efca9bb 100644 (file)
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -256,12 +256,12 @@ For C programs:
 
    Note however that a comment that explains a translatable string to
    translators uses a convention of starting with a magic token
-   "TRANSLATORS: " immediately after the opening delimiter, even when
-   it spans multiple lines.  We do not add an asterisk at the beginning
-   of each line, either.  E.g.
+   "TRANSLATORS: ", e.g.
 
-       /* TRANSLATORS: here is a comment that explains the string
-          to be translated, that follows immediately after it */
+       /*
+        * TRANSLATORS: here is a comment that explains the string to
+        * be translated, that follows immediately after it.
+        */
        _("Here is a translatable string explained by the above.");
 
  - Double negation is often harder to understand than no negation

diff --git a/bisect.c b/bisect.c
index 08c9fb7266c3b2ff8b970c21d350be4adfe7b0fc..c5d5a2b64befe41aed40f12e21deaae33adb9613 100644 (file)
--- a/bisect.c
+++ b/bisect.c
@@ -995,8 +995,10 @@ int bisect_next_all(const char *prefix, int no_checkout)
 
        steps_msg = xstrfmt(Q_("(roughly %d step)", "(roughly %d steps)",
                  steps), steps);
-       /* TRANSLATORS: the last %s will be replaced with
-          "(roughly %d steps)" translation */
+       /*
+        * TRANSLATORS: the last %s will be replaced with "(roughly %d
+        * steps)" translation.
+        */
        printf(Q_("Bisecting: %d revision left to test after this %s\n",
                  "Bisecting: %d revisions left to test after this %s\n",
                  nr), nr, steps_msg);

diff --git a/builtin/blame.c b/builtin/blame.c
index 07506a3e457d1540acb7700e4677d715d6842735..ca9ebe40e7d4dac16a7b325e18857e9f1bfb316c 100644 (file)
--- a/builtin/blame.c
+++ b/builtin/blame.c
@@ -2688,12 +2688,15 @@ int cmd_blame(int argc, const char **argv, const char *prefix)
                blame_date_width = sizeof("2006-10-19");
                break;
        case DATE_RELATIVE:
-               /* TRANSLATORS: This string is used to tell us the maximum
-                  display width for a relative timestamp in "git blame"
-                  output.  For C locale, "4 years, 11 months ago", which
-                  takes 22 places, is the longest among various forms of
-                  relative timestamps, but your language may need more or
-                  fewer display columns. */
+               /*
+                * TRANSLATORS: This string is used to tell us the
+                * maximum display width for a relative timestamp in
+                * "git blame" output.  For C locale, "4 years, 11
+                * months ago", which takes 22 places, is the longest
+                * among various forms of relative timestamps, but
+                * your language may need more or fewer display
+                * columns.
+                */
                blame_date_width = utf8_strwidth(_("4 years, 11 months ago")) + 1; /* add the null */
                break;
        case DATE_NORMAL:

diff --git a/builtin/notes.c b/builtin/notes.c
index 7b891471c461ddc3cd2b9d3186cc8b005f68ca2b..fb856e53b610087128094e3fc4deb7bab2106801 100644 (file)
--- a/builtin/notes.c
+++ b/builtin/notes.c
@@ -340,8 +340,10 @@ static struct notes_tree *init_notes_check(const char *subcommand,
 
        ref = (flags & NOTES_INIT_WRITABLE) ? t->update_ref : t->ref;
        if (!starts_with(ref, "refs/notes/"))
-               /* TRANSLATORS: the first %s will be replaced by a
-                  git notes command: 'add', 'merge', 'remove', etc.*/
+               /*
+                * TRANSLATORS: the first %s will be replaced by a git
+                * notes command: 'add', 'merge', 'remove', etc.
+                */
                die(_("refusing to %s notes in %s (outside of refs/notes/)"),
                    subcommand, ref);
        return t;

diff --git a/builtin/remote.c b/builtin/remote.c
index addf97ad29343b2328adce2c27ccea92aee6af7a..9054e2858e324aca5d6ce062331cf0ad9ccf0819 100644 (file)
--- a/builtin/remote.c
+++ b/builtin/remote.c
@@ -1151,8 +1151,11 @@ static int show(int argc, const char **argv)
                        url_nr = states.remote->url_nr;
                }
                for (i = 0; i < url_nr; i++)
-                       /* TRANSLATORS: the colon ':' should align with
-                          the one in "  Fetch URL: %s" translation */
+                       /*
+                        * TRANSLATORS: the colon ':' should align
+                        * with the one in " Fetch URL: %s"
+                        * translation.
+                        */
                        printf_ln(_("  Push  URL: %s"), url[i]);
                if (!i)
                        printf_ln(_("  Push  URL: %s"), _("(no URL)"));

diff --git a/notes-utils.c b/notes-utils.c
index 24a33616a47737e6ae8cf917080cbb314dcf2762..8f9ad7d1f85015cafc9175408d8264d08ea9581f 100644 (file)
--- a/notes-utils.c
+++ b/notes-utils.c
@@ -132,8 +132,11 @@ struct notes_rewrite_cfg *init_copy_notes_for_rewrite(const char *cmd)
                c->mode_from_env = 1;
                c->combine = parse_combine_notes_fn(rewrite_mode_env);
                if (!c->combine)
-                       /* TRANSLATORS: The first %s is the name of the
-                          environment variable, the second %s is its value */
+                       /*
+                        * TRANSLATORS: The first %s is the name of
+                        * the environment variable, the second %s is
+                        * its value.
+                        */
                        error(_("Bad %s value: '%s'"), GIT_NOTES_REWRITE_MODE_ENVIRONMENT,
                                        rewrite_mode_env);
        }

diff --git a/parse-options.c b/parse-options.c
index a23a1e67f04f8072bea357cbed34fdc1b39ab7ae..e5ad34a2c3f7c7d7fdb65171f8a142a2becc64bb 100644 (file)
--- a/parse-options.c
+++ b/parse-options.c
@@ -589,8 +589,10 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
 
        fprintf_ln(outfile, _("usage: %s"), _(*usagestr++));
        while (*usagestr && **usagestr)
-               /* TRANSLATORS: the colon here should align with the
-                  one in "usage: %s" translation */
+               /*
+                * TRANSLATORS: the colon here should align with the
+                * one in "usage: %s" translation.
+                */
                fprintf_ln(outfile, _("   or: %s"), _(*usagestr++));
        while (*usagestr) {
                if (**usagestr)

diff --git a/ref-filter.c b/ref-filter.c
index 3a640448fd83e6cf0bda8ddda081757d5941361e..563284175380cbd8cb3c503390b52781b16cf739 100644 (file)
--- a/ref-filter.c
+++ b/ref-filter.c
@@ -1251,13 +1251,17 @@ char *get_head_description(void)
                            state.branch);
        else if (state.detached_from) {
                if (state.detached_at)
-                       /* TRANSLATORS: make sure this matches
-                          "HEAD detached at " in wt-status.c */
+                       /*
+                        * TRANSLATORS: make sure this matches "HEAD
+                        * detached at " in wt-status.c
+                        */
                        strbuf_addf(&desc, _("(HEAD detached at %s)"),
                                state.detached_from);
                else
-                       /* TRANSLATORS: make sure this matches
-                          "HEAD detached from " in wt-status.c */
+                       /*
+                        * TRANSLATORS: make sure this matches "HEAD
+                        * detached from " in wt-status.c
+                        */
                        strbuf_addf(&desc, _("(HEAD detached from %s)"),
                                state.detached_from);
        }

diff --git a/sequencer.c b/sequencer.c
index 10c3b4ff81547891172319cee0e291c5160050e1..b77f359ca294aa5c5e929a14a1af46a874c3ae68 100644 (file)
--- a/sequencer.c
+++ b/sequencer.c
@@ -464,7 +464,8 @@ static int do_recursive_merge(struct commit *base, struct commit *next,
 
        if (active_cache_changed &&
            write_locked_index(&the_index, &index_lock, COMMIT_LOCK))
-               /* TRANSLATORS: %s will be "revert", "cherry-pick" or
+               /*
+                * TRANSLATORS: %s will be "revert", "cherry-pick" or
                 * "rebase -i".
                 */
                return error(_("%s: Unable to write new index file"),