Merge branch 'ab/c-translators-comment-style' into maint

Update the C style recommendation for notes for translators, as
recent versions of gettext tools can work with our style of
multi-line comments.

* ab/c-translators-comment-style:
  C style: use standard style for "TRANSLATORS" comments

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
+   "TRANSLATORS: ", e.g.
-   it spans multiple lines.  We do not add an asterisk at the beginning
-   of each line, either.  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

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);

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"
+		 * TRANSLATORS: This string is used to tell us the
-		   output.  For C locale, "4 years, 11 months ago", which
+		 * maximum display width for a relative timestamp in
-		   takes 22 places, is the longest among various forms of
+		 * "git blame" output.  For C locale, "4 years, 11
-		   relative timestamps, but your language may need more or
+		 * months ago", which takes 22 places, is the longest
-		   fewer display columns. */
+		 * 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:

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;

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)"));

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);
 	}

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)

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);
 	}

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"),