From: David Malcolm <dmalcolm@redhat.com>
Date: Mon, 29 Oct 2018 22:25:29 +0000 (+0000)
Subject: ux.texi: move "Quoting" and "Fix-it hints" from DiagnosticsGuidelines wiki page
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=90938ef8823fcd69e1a1e045148e5b6a1909be13;p=gcc.git

ux.texi: move "Quoting" and "Fix-it hints" from DiagnosticsGuidelines wiki page

gcc/ChangeLog:
	* doc/ux.texi (Quoting): New subsection, adapted from material at
	https://gcc.gnu.org/wiki/DiagnosticsGuidelines written by
	MartinSebor and ManuelLopezIbanez.
	(Fix-it hints): Note that fix-it hints shouldn't be marked for
	translation.


Co-Authored-By: Manuel López-Ibáñez <manu@gcc.gnu.org>
Co-Authored-By: Martin Sebor <msebor@redhat.com>

From-SVN: r265606
---

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 35e5179762a..b649da16184 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,13 @@
+2018-10-29  David Malcolm  <dmalcolm@redhat.com>
+	    Martin Sebor  <msebor@redhat.com>
+	    Manuel Lopez-Ibanez  <manu@gcc.gnu.org>
+
+	* doc/ux.texi (Quoting): New subsection, adapted from material at
+	https://gcc.gnu.org/wiki/DiagnosticsGuidelines written by
+	MartinSebor and ManuelLopezIbanez.
+	(Fix-it hints): Note that fix-it hints shouldn't be marked for
+	translation.
+
 2018-10-29  Kugan Vivekanandarajah  <kuganv@linaro.org>
 
 	PR middle-end/87469
diff --git a/gcc/doc/ux.texi b/gcc/doc/ux.texi
index 63349252dce..adea7182caa 100644
--- a/gcc/doc/ux.texi
+++ b/gcc/doc/ux.texi
@@ -383,6 +383,38 @@ of the @code{auto_diagnostic_group} are related.  (Currently it doesn't
 do anything with this information, but we may implement that in the
 future).
 
+@subsection Quoting
+Text should be quoted by either using the @samp{q} modifier in a directive
+such as @samp{%qE}, or by enclosing the quoted text in a pair of @samp{%<}
+and @samp{%>} directives, and never by using explicit quote characters.
+The directives handle the appropriate quote characters for each language
+and apply the correct color or highlighting.
+
+The following elements should be quoted in GCC diagnostics:
+
+@itemize @bullet
+@item
+Language keywords.
+@item
+Tokens.
+@item
+Boolean, numerical, character, and string constants that appear in the
+source code.
+@item
+Identifiers, including function, macro, type, and variable names.
+@end itemize
+
+Other elements such as numbers that do not refer to numeric constants that
+appear in the source code should not be quoted. For example, in the message:
+
+@smallexample
+argument %d of %qE must be a pointer type
+@end smallexample
+
+@noindent
+since the argument number does not refer to a numerical constant in the
+source code it should not be quoted.
+
 @subsection Spelling and Terminology
 
 See the @uref{https://gcc.gnu.org/codingconventions.html#Spelling
@@ -400,6 +432,9 @@ can also be viewed via @option{-fdiagnostics-generate-patch} and
 @option{-fdiagnostics-parseable-fixits}.  With the latter, an IDE
 ought to be able to offer to automatically apply the suggested fix.
 
+Fix-it hints contain code fragments, and thus they should not be marked
+for translation.
+
 Fix-it hints can be added to a diagnostic by using a @code{rich_location}
 rather than a @code{location_t} - the fix-it hints are added to the
 @code{rich_location} using one of the various @code{add_fixit} member