From 90938ef8823fcd69e1a1e045148e5b6a1909be13 Mon Sep 17 00:00:00 2001 From: David Malcolm Date: Mon, 29 Oct 2018 22:25:29 +0000 Subject: [PATCH] ux.texi: move "Quoting" and "Fix-it hints" from DiagnosticsGuidelines wiki page MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 Co-Authored-By: Martin Sebor From-SVN: r265606 --- gcc/ChangeLog | 10 ++++++++++ gcc/doc/ux.texi | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) 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 + Martin Sebor + Manuel Lopez-Ibanez + + * 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 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 -- 2.11.4.GIT