On 10/23/2018 02:42 PM, David Malcolm wrote:
I want to move material from
https://gcc.gnu.org/wiki/DiagnosticsGuidelines
into the new User Experience Guidelines chapter of our internals
documentation. I've already update the link in that wiki page to point
to the pertinent HTML build of the docs:
https://gcc.gnu.org/onlinedocs/gccint/Guidelines-for-Diagnostics.html
This patch does it for the "Quoting" section, and adds a note about
fix-it hints that would make the wiki page's "Fix-it hints" section
redundant.
Martin and Manu: can you confirm you wrote this wiki material, and that
it's OK to add it to the GCC docs (I don't know what license the wiki
is under). Are all such changes OK from a licensing perspective, for
material you contributed to the GCC wiki?
I did add a some brief text about quoting to the Wiki. Now that
we have guidelines for these things in the manual I think it makes
perfect sense to move stuff we all agree with there. Go for it!
Martin
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.
---
gcc/doc/ux.texi | 35 +++++++++++++++++++++++++++++++++++
1 file changed, 35 insertions(+)
diff --git a/gcc/doc/ux.texi b/gcc/doc/ux.texi
index 9185f68..1061aa0 100644
--- a/gcc/doc/ux.texi
+++ b/gcc/doc/ux.texi
@@ -384,6 +384,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
@@ -401,6 +433,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
