@matheusbsbs / matheus-bagliano / commits / 66f5f6dca9

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>

Ævar Arnfjörð Bjarmason committed May 11, 2017 at 21:20 UTC 66f5f6dca95eda46bf02c8d06de8cb265995fd6e
9 files changed +46 -26
Documentation/CodingGuidelines
+5 -5
@@ -256,12 +256,12 @@ For C programs:
256
257 Note however that a comment that explains a translatable string to
258 translators uses a convention of starting with a magic token
259 - "TRANSLATORS: " immediately after the opening delimiter, even when
260 - it spans multiple lines. We do not add an asterisk at the beginning
261 - of each line, either. E.g.
259 + "TRANSLATORS: ", e.g.
260
263 - /* TRANSLATORS: here is a comment that explains the string
264 - to be translated, that follows immediately after it */
261 + /*
262 + * TRANSLATORS: here is a comment that explains the string to
263 + * be translated, that follows immediately after it.
264 + */
265 _("Here is a translatable string explained by the above.");
266
267 - Double negation is often harder to understand than no negation
bisect.c
+4 -2
@@ -995,8 +995,10 @@ int bisect_next_all(const char *prefix, int no_checkout)
995
996 steps_msg = xstrfmt(Q_("(roughly %d step)", "(roughly %d steps)",
997 steps), steps);
998 - /* TRANSLATORS: the last %s will be replaced with
999 - "(roughly %d steps)" translation */
998 + /*
999 + * TRANSLATORS: the last %s will be replaced with "(roughly %d
1000 + * steps)" translation.
1001 + */
1002 printf(Q_("Bisecting: %d revision left to test after this %s\n",
1003 "Bisecting: %d revisions left to test after this %s\n",
1004 nr), nr, steps_msg);
builtin/blame.c
+9 -6
@@ -2688,12 +2688,15 @@ parse_done:
2688 blame_date_width = sizeof("2006-10-19");
2689 break;
2690 case DATE_RELATIVE:
2691 - /* TRANSLATORS: This string is used to tell us the maximum
2692 - display width for a relative timestamp in "git blame"
2693 - output. For C locale, "4 years, 11 months ago", which
2694 - takes 22 places, is the longest among various forms of
2695 - relative timestamps, but your language may need more or
2696 - fewer display columns. */
2691 + /*
2692 + * TRANSLATORS: This string is used to tell us the
2693 + * maximum display width for a relative timestamp in
2694 + * "git blame" output. For C locale, "4 years, 11
2695 + * months ago", which takes 22 places, is the longest
2696 + * among various forms of relative timestamps, but
2697 + * your language may need more or fewer display
2698 + * columns.
2699 + */
2700 blame_date_width = utf8_strwidth(_("4 years, 11 months ago")) + 1; /* add the null */
2701 break;
2702 case DATE_NORMAL:
builtin/notes.c
+4 -2
@@ -340,8 +340,10 @@ static struct notes_tree *init_notes_check(const char *subcommand,
340
341 ref = (flags & NOTES_INIT_WRITABLE) ? t->update_ref : t->ref;
342 if (!starts_with(ref, "refs/notes/"))
343 - /* TRANSLATORS: the first %s will be replaced by a
344 - git notes command: 'add', 'merge', 'remove', etc.*/
343 + /*
344 + * TRANSLATORS: the first %s will be replaced by a git
345 + * notes command: 'add', 'merge', 'remove', etc.
346 + */
347 die(_("refusing to %s notes in %s (outside of refs/notes/)"),
348 subcommand, ref);
349 return t;
builtin/remote.c
+5 -2
@@ -1151,8 +1151,11 @@ static int show(int argc, const char **argv)
1151 url_nr = states.remote->url_nr;
1152 }
1153 for (i = 0; i < url_nr; i++)
1154 - /* TRANSLATORS: the colon ':' should align with
1155 - the one in " Fetch URL: %s" translation */
1154 + /*
1155 + * TRANSLATORS: the colon ':' should align
1156 + * with the one in " Fetch URL: %s"
1157 + * translation.
1158 + */
1159 printf_ln(_(" Push URL: %s"), url[i]);
1160 if (!i)
1161 printf_ln(_(" Push URL: %s"), _("(no URL)"));
notes-utils.c
+5 -2
@@ -132,8 +132,11 @@ struct notes_rewrite_cfg *init_copy_notes_for_rewrite(const char *cmd)
132 c->mode_from_env = 1;
133 c->combine = parse_combine_notes_fn(rewrite_mode_env);
134 if (!c->combine)
135 - /* TRANSLATORS: The first %s is the name of the
136 - environment variable, the second %s is its value */
135 + /*
136 + * TRANSLATORS: The first %s is the name of
137 + * the environment variable, the second %s is
138 + * its value.
139 + */
140 error(_("Bad %s value: '%s'"), GIT_NOTES_REWRITE_MODE_ENVIRONMENT,
141 rewrite_mode_env);
142 }
parse-options.c
+4 -2
@@ -589,8 +589,10 @@ static int usage_with_options_internal(struct parse_opt_ctx_t *ctx,
589
590 fprintf_ln(outfile, _("usage: %s"), _(*usagestr++));
591 while (*usagestr && **usagestr)
592 - /* TRANSLATORS: the colon here should align with the
593 - one in "usage: %s" translation */
592 + /*
593 + * TRANSLATORS: the colon here should align with the
594 + * one in "usage: %s" translation.
595 + */
596 fprintf_ln(outfile, _(" or: %s"), _(*usagestr++));
597 while (*usagestr) {
598 if (**usagestr)
ref-filter.c
+8 -4
@@ -1251,13 +1251,17 @@ char *get_head_description(void)
1251 state.branch);
1252 else if (state.detached_from) {
1253 if (state.detached_at)
1254 - /* TRANSLATORS: make sure this matches
1255 - "HEAD detached at " in wt-status.c */
1254 + /*
1255 + * TRANSLATORS: make sure this matches "HEAD
1256 + * detached at " in wt-status.c
1257 + */
1258 strbuf_addf(&desc, _("(HEAD detached at %s)"),
1259 state.detached_from);
1260 else
1259 - /* TRANSLATORS: make sure this matches
1260 - "HEAD detached from " in wt-status.c */
1261 + /*
1262 + * TRANSLATORS: make sure this matches "HEAD
1263 + * detached from " in wt-status.c
1264 + */
1265 strbuf_addf(&desc, _("(HEAD detached from %s)"),
1266 state.detached_from);
1267 }
sequencer.c
+2 -1
@@ -464,7 +464,8 @@ static int do_recursive_merge(struct commit *base, struct commit *next,
464
465 if (active_cache_changed &&
466 write_locked_index(&the_index, &index_lock, COMMIT_LOCK))
467 - /* TRANSLATORS: %s will be "revert", "cherry-pick" or
467 + /*
468 + * TRANSLATORS: %s will be "revert", "cherry-pick" or
469 * "rebase -i".
470 */
471 return error(_("%s: Unable to write new index file"),