[PATCH] ux.texi: move "Quoting" and "Fix-it hints" from DiagnosticsGuidelines wiki page
Martin Sebor
msebor@gmail.com
Wed Oct 24 07:56:00 GMT 2018
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
>
More information about the Gcc-patches
mailing list