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? 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 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). 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 > > > >
