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

[Martin Sebor]

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
>>>
>>
>>