On 10/24/2018 10:39 AM, David Malcolm wrote:
On Tue, 2018-10-23 at 18:49 -0600, Martin Sebor wrote:
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!
What I wanted to confirm is:
Martin: are you wiki user "MartinSebor", and are you happy to have
any/all of your gcc wiki edits copied into gcc itself, covered under
the usual FSF copyright assignment?
Yep, that would be me :) And yes, please feel free to copy or
move anything I added to the Wiki wherever you think it fits
best.
Manu: are you wiki user "ManuelLopezIbanez", and are you happy to have
any/all of your gcc wiki edits copied into gcc itself, covered under
the usual FSF copyright assignment?
Or is this generally true for *all* material on the gcc wiki?
I wouldn't have thought otherwise.
(I may be being overly pedantic here but I don't know if this is
already implicitly true, and I didn't want to start directly moving
stuff from the wiki to the source tree without knowing the provenance
and copyright-assignability of the material).
That might be a question for the overseers. Personally, I don't
think we should have to go to such lengths when copying material
within our own project.
Martin
FWIW, the wiki edit in question that I'm copying was:
https://gcc.gnu.org/wiki/DiagnosticsGuidelines?action=diff&rev1=7&rev2=8
(Editor: MartinSebor)
later modified by:
https://gcc.gnu.org/wiki/DiagnosticsGuidelines?action=diff&rev1=8&rev2=9
(Editor: ManuelLopezIbanez).
Thanks
Dave
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
