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

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?

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(+)

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
>

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

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

On Wed, 24 Oct 2018, 17:39 David Malcolm, <dmalcolm@redhat.com> wrote:

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

I'm wiki user "ManuelLopezIbanez". I believe nothing I have contributed to
the GCC wiki is an original work, since it is public domain information
about the workings of GCC collected from public discussions in the mailing
lists or derived from GCC itself. I contributed to the GCC wiki under the
assumption that all my contributions are in the public domain, except when
noted otherwise.

Best,

Manuel.