* doc/bugreport.texi, doc/configterms.texi, doc/contrib.texi,

	doc/contribute.texi, doc/cpp.texi, doc/cppinternals.texi,
	doc/extend.texi, doc/install.texi, doc/invoke.texi, doc/md.texi,
	doc/portability.texi, doc/tree-ssa.texi, doc/trouble.texi: Avoid
	some first-person references and patronizing comments.  Based on
	printed manual.
	* doc/invoke.texi: Don't reference fortran@gnu.org.
	* doc/trouble.texi (Warning when a non-void function value is
	ignored): Rewrite.  From Russ Allbery and Chris Devers.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@84034 138bc75d-0d04-0410-961f-82ee72b054a4

14 files changed, 89 insertions, 71 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index fe15ad002bf..479cec5166e 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,15 @@
+2004-07-03  Joseph S. Myers  <jsm@polyomino.org.uk>
+
+	* doc/bugreport.texi, doc/configterms.texi, doc/contrib.texi,
+	doc/contribute.texi, doc/cpp.texi, doc/cppinternals.texi,
+	doc/extend.texi, doc/install.texi, doc/invoke.texi, doc/md.texi,
+	doc/portability.texi, doc/tree-ssa.texi, doc/trouble.texi: Avoid
+	some first-person references and patronizing comments.  Based on
+	printed manual.
+	* doc/invoke.texi: Don't reference fortran@gnu.org.
+	* doc/trouble.texi (Warning when a non-void function value is
+	ignored): Rewrite.  From Russ Allbery and Chris Devers.
+
 2004-07-02  Daniel Berlin  <dberlin@dberlin.org)
 
 	* tree-ssa-pre.c (bitmap_set_t): New.
diff --git a/gcc/doc/bugreport.texi b/gcc/doc/bugreport.texi
index d9613ef6d1c..9e10af910dc 100644
--- a/gcc/doc/bugreport.texi
+++ b/gcc/doc/bugreport.texi
@@ -1,5 +1,5 @@
 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-@c 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
+@c 1999, 2000, 2001, 2003, 2004 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
@@ -76,8 +76,8 @@ compiler bug.
 @item
 If the compiler does not produce an error message for invalid input,
 that is a compiler bug.  However, you should note that your idea of
-``invalid input'' might be my idea of ``an extension'' or ``support
-for traditional practice''.
+``invalid input'' might be someone else's idea of ``an extension'' or
+``support for traditional practice''.
 
 @item
 If you are an experienced user of one of the languages GCC supports, your
@@ -88,7 +88,7 @@ suggestions for improvement of GCC are welcome in any case.
 @section How and where to Report Bugs
 @cindex compiler bugs, reporting
 
-Bugs should be reported to our bug database.  Please refer to
+Bugs should be reported to the GCC bug database.  Please refer to
 @uref{http://gcc.gnu.org/bugs.html} for up-to-date instructions how to
 submit bug reports.  Copies of this file in HTML (@file{bugs.html}) and
 plain text (@file{BUGS}) are also part of GCC releases.
diff --git a/gcc/doc/configterms.texi b/gcc/doc/configterms.texi
index 39b3152d528..f97de5bd096 100644
--- a/gcc/doc/configterms.texi
+++ b/gcc/doc/configterms.texi
@@ -1,4 +1,4 @@
-@c Copyright (C) 2001, 2002 Free Software Foundation, Inc.
+@c Copyright (C) 2001, 2002, 2004 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
@@ -34,8 +34,8 @@ different system.  Some people call this a @dfn{host-x-host},
 @dfn{crossed native}, or @dfn{cross-built native}.  If build and target
 are the same, but host is different, you are using a cross compiler to
 build a cross compiler that produces code for the machine you're
-building on.  This is rare, so there is no common way of describing it
-(although I propose calling it a @dfn{crossback}).
+building on.  This is rare, so there is no common way of describing it.
+There is a proposal to call this a @dfn{crossback}.
 
 If build and host are the same, the GCC you are building will also be
 used to build the target libraries (like @code{libstdc++}).  If build and host
diff --git a/gcc/doc/contrib.texi b/gcc/doc/contrib.texi
index dfa80a48ccd..c43d6fbdfe3 100644
--- a/gcc/doc/contrib.texi
+++ b/gcc/doc/contrib.texi
@@ -59,7 +59,7 @@ Jon Beniston for his Microsoft Windows port of Java.
 
 @item
 Daniel Berlin for better DWARF2 support, faster/better optimizations,
-improved alias analysis, plus migrating us to Bugzilla.
+improved alias analysis, plus migrating GCC to Bugzilla.
 
 @item
 Geoff Berry for his Java object serialization work and various patches.
@@ -84,7 +84,7 @@ Eric Botcazou for fixing middle- and backend bugs left and right.
 
 @item
 Per Bothner for his direction via the steering committee and various
-improvements to our infrastructure for supporting new languages.  Chill
+improvements to the infrastructure for supporting new languages.  Chill
 front end implementation.  Initial implementations of
 cpplib, fix-header, config.guess, libio, and past C++ library (libg++)
 maintainer.  Dreaming up, designing and implementing much of GCJ.
@@ -289,7 +289,7 @@ via the steering committee.
 Anthony Green for his @option{-Os} contributions and Java front end work.
 
 @item
-Stu Grossman for gdb hacking, allowing GCJ developers to debug our code.
+Stu Grossman for gdb hacking, allowing GCJ developers to debug Java code.
 
 @item
 Michael K. Gschwind contributed the port to the PDP-11.
@@ -340,7 +340,7 @@ Kazu Hirata for caring and feeding the Renesas H8/300 port and various fixes.
 
 @item
 Manfred Hollstein for his ongoing work to keep the m88k alive, lots
-of testing and bug fixing, particularly of our configury code.
+of testing and bug fixing, particularly of GCC configury code.
 
 @item
 Steve Holmgren for MachTen patches.
@@ -630,7 +630,7 @@ Stefan Olsson for work on mt_alloc.
 Melissa O'Neill for various NeXT fixes.
 
 @item
-Rainer Orth for random MIPS work, including improvements to our o32
+Rainer Orth for random MIPS work, including improvements to GCC's o32
 ABI support, improvements to dejagnu's MIPS support, Java configuration
 clean-ups and porting work, etc.
 
@@ -701,7 +701,7 @@ documentation in texinfo format by contributing a first pass at a
 translation of the old @file{g77-0.5.16/f/DOC} file.
 
 @item
-Ken Rose for fixes to our delay slot filling code.
+Ken Rose for fixes to GCC's delay slot filling code.
 
 @item
 Paul Rubin wrote most of the preprocessor.
@@ -763,7 +763,7 @@ folding and help with the original VAX & m68k ports.
 
 @item
 Kenny Simpson for prompting libstdc++ fixes due to defect reports from
-the LWG (thereby keeping us in line with updates from the ISO).
+the LWG (thereby keeping GCC in line with updates from the ISO).
 
 @item
 Franz Sirl for his ongoing work with making the PPC port stable
diff --git a/gcc/doc/contribute.texi b/gcc/doc/contribute.texi
index 0aec26842b8..a90c048326d 100644
--- a/gcc/doc/contribute.texi
+++ b/gcc/doc/contribute.texi
@@ -1,5 +1,5 @@
 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-@c 1999, 2000, 2001 Free Software Foundation, Inc.
+@c 1999, 2000, 2001, 2004 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
@@ -7,7 +7,7 @@
 @chapter Contributing to GCC Development
 
 If you would like to help pretest GCC releases to assure they work well,
-our current development sources are available by CVS (see
+current development sources are available by CVS (see
 @uref{http://gcc.gnu.org/cvs.html}).  Source and binary snapshots are
 also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}.
 
diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi
index 399658256d6..62151645c68 100644
--- a/gcc/doc/cpp.texi
+++ b/gcc/doc/cpp.texi
@@ -1898,7 +1898,8 @@ or a C++ compiler.  This macro is similar to @code{__STDC_VERSION__}, in
 that it expands to a version number.  A fully conforming implementation
 of the 1998 C++ standard will define this macro to @code{199711L}.  The
 GNU C++ compiler is not yet fully conforming, so it uses @code{1}
-instead.  We hope to complete our implementation in the near future.
+instead.  It is hoped to complete the implementation of standard C++
+in the near future.
 
 @item __OBJC__
 This macro is defined, with value 1, when the Objective-C compiler is in
@@ -2542,7 +2543,7 @@ definition.  Recall that all macro definitions are rescanned for more
 macros to replace.  If the self-reference were considered a use of the
 macro, it would produce an infinitely large expansion.  To prevent this,
 the self-reference is not considered a macro call.  It is passed into
-the preprocessor output unchanged.  Let's consider an example:
+the preprocessor output unchanged.  Consider an example:
 
 @smallexample
 #define foo (4 + foo)
@@ -3836,10 +3837,10 @@ pragmas.
 
 CPP has a small number of internal limits.  This section lists the
 limits which the C standard requires to be no lower than some minimum,
-and all the others we are aware of.  We intend there to be as few limits
+and all the others known.  It is intended that there should be as few limits
 as possible.  If you encounter an undocumented or inconvenient limit,
-please report that to us as a bug.  (See the section on reporting bugs in
-the GCC manual.)
+please report that as a bug.  @xref{Bugs, , Reporting Bugs, gcc, Using
+the GNU Compiler Collection (GCC)}.
 
 Where we say something is limited @dfn{only by available memory}, that
 means that internal data structures impose no intrinsic limit, and space
diff --git a/gcc/doc/cppinternals.texi b/gcc/doc/cppinternals.texi
index 2b8c5086883..9f5863c3b70 100644
--- a/gcc/doc/cppinternals.texi
+++ b/gcc/doc/cppinternals.texi
@@ -16,7 +16,7 @@
 @ifinfo
 This file documents the internals of the GNU C Preprocessor.
 
-Copyright 2000, 2001, 2002 Free Software Foundation, Inc.
+Copyright 2000, 2001, 2002, 2004 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -47,7 +47,7 @@ into another language, under the above conditions for modified versions.
 @page
 @vskip 0pt plus 1filll
 @c man begin COPYRIGHT
-Copyright @copyright{} 2000, 2001, 2002
+Copyright @copyright{} 2000, 2001, 2002, 2004
 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
@@ -368,8 +368,8 @@ chaining a new token run on to the end of the existing one.
 
 The tokens forming a macro's replacement list are collected by the
 @code{#define} handler, and placed in storage that is only freed by
-@code{cpp_destroy}.  So if a macro is expanded in our line of tokens,
-the pointers to the tokens of its expansion that we return will always
+@code{cpp_destroy}.  So if a macro is expanded in the line of tokens,
+the pointers to the tokens of its expansion that are returned will always
 remain valid.  However, macros are a little trickier than that, since
 they give rise to three sources of fresh tokens.  They are the built-in
 macros like @code{__LINE__}, and the @samp{#} and @samp{##} operators
@@ -640,8 +640,8 @@ is safe.
 @cindex spacing
 @cindex token spacing
 
-First, let's look at an issue that only concerns the stand-alone
-preprocessor: we want to guarantee that re-reading its preprocessed
+First, consider an issue that only concerns the stand-alone
+preprocessor: there needs to be a guarantee that re-reading its preprocessed
 output results in an identical token stream.  Without taking special
 measures, this might not be the case because of macro substitution.
 For example:
@@ -670,7 +670,7 @@ expansion, but accidental pasting can occur in many places: both before
 and after each macro replacement, each argument replacement, and
 additionally each token created by the @samp{#} and @samp{##} operators.
 
-Let's look at how the preprocessor gets whitespace output correct
+Look at how the preprocessor gets whitespace output correct
 normally.  The @code{cpp_token} structure contains a flags byte, and one
 of those flags is @code{PREV_WHITE}.  This is flagged by the lexer, and
 indicates that the token was preceded by whitespace of some form other
@@ -719,11 +719,11 @@ a macro's first replacement token expands straight into another macro.
 
 Here, two padding tokens are generated with sources the @samp{foo} token
 between the brackets, and the @samp{bar} token from foo's replacement
-list, respectively.  Clearly the first padding token is the one we
-should use, so our output code should contain a rule that the first
+list, respectively.  Clearly the first padding token is the one to
+use, so the output code should contain a rule that the first
 padding token in a sequence is the one that matters.
 
-But what if we happen to leave a macro expansion?  Adjusting the above
+But what if a macro expansion is left?  Adjusting the above
 example slightly:
 
 @smallexample
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 251defa0645..0d2798f2a1e 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -524,7 +524,7 @@ follows:
 @cindex side effects, macro argument
 But this definition computes either @var{a} or @var{b} twice, with bad
 results if the operand has side effects.  In GNU C, if you know the
-type of the operands (here let's assume @code{int}), you can define
+type of the operands (here taken as @code{int}), you can define
 the macro safely as follows:
 
 @smallexample
@@ -1021,7 +1021,7 @@ char *y[4];
 @end smallexample
 
 To see the meaning of the declaration using @code{typeof}, and why it
-might be a useful way to write, let's rewrite it with these macros:
+might be a useful way to write, rewrite it with these macros:
 
 @smallexample
 #define pointer(T)  typeof(T *)
@@ -8063,7 +8063,7 @@ intelligence from the environment than one usually finds on a UNIX
 system.  Somehow the compiler and linker have to make sure that each
 template instance occurs exactly once in the executable if it is needed,
 and not at all otherwise.  There are two basic approaches to this
-problem, which I will refer to as the Borland model and the Cfront model.
+problem, which are referred to as the Borland model and the Cfront model.
 
 @table @asis
 @item Borland model
diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index 18f1b7b8a92..71070532e25 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -431,7 +431,7 @@ tarballs compressed with @command{gzip} or
 @command{bzip2}.  It is possible to download a full distribution or specific
 components.
 
-Please refer to our @uref{http://gcc.gnu.org/releases.html,,releases web page}
+Please refer to the @uref{http://gcc.gnu.org/releases.html,,releases web page}
 for information on how to obtain GCC@.
 
 The full distribution includes the C, C++, Objective-C, Fortran 77, Fortran
@@ -1688,7 +1688,7 @@ might emit some harmless messages resembling
 @samp{WARNING: Couldn't find the global config file.} or
 @samp{WARNING: Couldn't find tool init file} that can be ignored.
 
-@section How can I run the testsuite on selected tests?
+@section How can you run the testsuite on selected tests?
 
 In order to run sets of tests selectively, there are targets
 @samp{make check-gcc} and @samp{make check-g++}
@@ -1831,9 +1831,9 @@ WARNING: the testsuite detected a possible problem
 @end itemize
 
 It is normal for some tests to report unexpected failures.  At the
-current time our testing harness does not allow fine grained control
-over whether or not a test is expected to fail.  We expect to fix this
-problem in future releases.
+current time the testing harness does not allow fine grained control
+over whether or not a test is expected to fail.  This problem should
+be fixed in future releases.
 
 
 @section Submitting test results
@@ -1932,7 +1932,7 @@ Include the following information:
 
 @itemize @bullet
 @item
-Output from running @file{@var{srcdir}/config.guess}.  Do not send us
+Output from running @file{@var{srcdir}/config.guess}.  Do not send
 that file itself, just the one-line output from running it.
 
 @item
@@ -1981,9 +1981,9 @@ We'd also like to know if the
 @end ifhtml
 didn't include your host/target information or if that information is
 incomplete or out of date.  Send a note to
-@email{gcc@@gcc.gnu.org} telling us how the information should be changed.
+@email{gcc@@gcc.gnu.org} detailing how the information should be changed.
 
-If you find a bug, please report it following our
+If you find a bug, please report it following the
 @uref{../bugs.html,,bug reporting guidelines}.
 
 If you want to print the GCC manuals, do @samp{cd @var{objdir}; make
@@ -2529,7 +2529,7 @@ information about this platform is available at
 @end html
 @heading @anchor{dos}DOS
 
-Please have a look at our @uref{binaries.html,,binaries page}.
+Please have a look at the @uref{binaries.html,,binaries page}.
 
 You cannot install GCC by itself on MSDOS; it will not compile under
 any MSDOS compiler except itself.  You need to get the complete
@@ -2590,7 +2590,7 @@ Shared @file{libgcc_s.so} is now built and installed by default.
 @heading @anchor{h8300-hms}h8300-hms
 Renesas H8/300 series of processors.
 
-Please have a look at our @uref{binaries.html,,binaries page}.
+Please have a look at the @uref{binaries.html,,binaries page}.
 
 The calling convention and structure layout has changed in release 2.6.
 All code must be recompiled.  The calling convention now passes the
@@ -3392,7 +3392,7 @@ supported as cross-compilation target only.
 @heading @anchor{*-*-solaris2*}*-*-solaris2*
 
 Sun does not ship a C compiler with Solaris 2.  To bootstrap and install
-GCC you first have to install a pre-built compiler, see our
+GCC you first have to install a pre-built compiler, see the
 @uref{binaries.html,,binaries page} for details.
 
 The Solaris 2 @command{/bin/sh} will often fail to configure
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 4d05a98fd86..13f9c087356 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -2332,7 +2332,7 @@ future implementation may also work for C++ programs.
 The C standard is worded confusingly, therefore there is some debate
 over the precise meaning of the sequence point rules in subtle cases.
 Links to discussions of the problem, including proposed formal
-definitions, may be found on our readings page, at
+definitions, may be found on the GCC readings page, at
 @w{@uref{http://gcc.gnu.org/readings.html}}.
 
 @item -Wreturn-type
@@ -4473,11 +4473,10 @@ These two options are intended to be removed someday, once
 they have helped determine the efficacy of various
 approaches to improving loop optimizations.
 
-Please let us (@w{@email{gcc@@gcc.gnu.org}} and @w{@email{fortran@@gnu.org}})
-know how use of these options affects
-the performance of your production code.
-We're very interested in code that runs @emph{slower}
-when these options are @emph{enabled}.
+Please contact @w{@email{gcc@@gcc.gnu.org}}, and describe how use of
+these options affects the performance of your production code.
+Examples of code that runs @emph{slower} when these options are
+@emph{enabled} are very valuable.
 
 @item -fno-peephole
 @itemx -fno-peephole2
@@ -4690,7 +4689,7 @@ Enabled at levels @option{-O2}, @option{-O3}.
 @item -fweb
 @opindex fweb
 Constructs webs as commonly used for register allocation purposes and assign
-each web individual pseudo register.  This allows our register allocation pass
+each web individual pseudo register.  This allows the register allocation pass
 to operate on pseudos directly, but also strengthens several other optimization
 passes, such as CSE, loop optimizer and trivial dead code remover.  It can,
 however, make debugging impossible, since variables will no longer stay in a
diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index b7ccecef303..08c7d7ce2c2 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -5678,13 +5678,14 @@ single or double precision, but not both, the following could be specified:
 
 @strong{Note:} The scheduler attempts to avoid function unit conflicts
 and uses all the specifications in the @code{define_function_unit}
-expression.  It has recently come to our attention that these
+expression.  It has recently been discovered that these
 specifications may not allow modeling of some of the newer
 ``superscalar'' processors that have insns using multiple pipelined
 units.  These insns will cause a potential conflict for the second unit
 used during their execution and there is no way of representing that
-conflict.  We welcome any examples of how function unit conflicts work
-in such processors and suggestions for their representation.
+conflict.  Any examples of how function unit conflicts work
+in such processors and suggestions for their representation would be
+welcomed.
 
 @end ifset
 @ifset INTERNALS
diff --git a/gcc/doc/portability.texi b/gcc/doc/portability.texi
index b05698dcfa6..e65e979fcca 100644
--- a/gcc/doc/portability.texi
+++ b/gcc/doc/portability.texi
@@ -1,5 +1,5 @@
 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-@c 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
+@c 1999, 2000, 2001, 2002, 2004 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
@@ -18,9 +18,9 @@ GCC gets most of the information about the target machine from a machine
 description which gives an algebraic formula for each of the machine's
 instructions.  This is a very clean way to describe the target.  But when
 the compiler needs information that is difficult to express in this
-fashion, I have not hesitated to define an ad-hoc parameter to the machine
-description.  The purpose of portability is to reduce the total work needed
-on the compiler; it was not of interest for its own sake.
+fashion, ad-hoc parameters have been defined for machine descriptions.
+The purpose of portability is to reduce the total work needed on the
+compiler; it was not of interest for its own sake.
 
 @cindex endianness
 @cindex autoincrement addressing, availability
@@ -31,9 +31,10 @@ significant byte has the highest or lowest address of the bytes in a word)
 and the availability of autoincrement addressing.  In the RTL-generation
 pass, it is often necessary to have multiple strategies for generating code
 for a particular kind of syntax tree, strategies that are usable for different
-combinations of parameters.  Often I have not tried to address all possible
-cases, but only the common ones or only the ones that I have encountered.
-As a result, a new target may require additional strategies.  You will know
+combinations of parameters.  Often, not all possible cases have been
+addressed, but only the common ones or only the ones that have been
+encountered.  As a result, a new target may require additional
+strategies.  You will know
 if this happens because the compiler will call @code{abort}.  Fortunately,
 the new strategies can be added in a machine-independent fashion, and will
 affect only the target machines that need them.
diff --git a/gcc/doc/tree-ssa.texi b/gcc/doc/tree-ssa.texi
index 7981c283926..4b5e61684ac 100644
--- a/gcc/doc/tree-ssa.texi
+++ b/gcc/doc/tree-ssa.texi
@@ -408,7 +408,7 @@ block exits, the cleanup is run.
 
 @code{TRY_FINALLY_EXPR} complicates the flow graph, since the cleanup
 needs to appear on every edge out of the controlled block; this
-reduces our freedom to move code across these edges.  Therefore, the
+reduces the freedom to move code across these edges.  Therefore, the
 EH lowering pass which runs before most of the optimization passes
 eliminates these expressions by explicitly adding the cleanup to each
 edge.
diff --git a/gcc/doc/trouble.texi b/gcc/doc/trouble.texi
index c28f9a21f52..39273c33e02 100644
--- a/gcc/doc/trouble.texi
+++ b/gcc/doc/trouble.texi
@@ -129,7 +129,7 @@ Older GDB versions sometimes fail to read the output of GCC version
 DBX rejects some files produced by GCC, though it accepts similar
 constructs in output from PCC@.  Until someone can supply a coherent
 description of what is valid DBX input and what is not, there is
-nothing I can do about these problems.  You are on your own.
+nothing that can be done about these problems.
 
 @item
 The GNU assembler (GAS) does not support PIC@.  To generate PIC code, you
@@ -509,8 +509,7 @@ ISO C does not permit such a construct.
 
 @item
 K&R compilers allow comments to cross over an inclusion boundary
-(i.e.@: started in an include file and ended in the including file).  I think
-this would be quite ugly and can't imagine it could be needed.
+(i.e.@: started in an include file and ended in the including file).
 
 @cindex external declaration scope
 @cindex scope of external declarations
@@ -1242,11 +1241,16 @@ more annoyance than good.
 @item
 Warning when a non-void function value is ignored.
 
-Coming as I do from a Lisp background, I balk at the idea that there is
-something dangerous about discarding a value.  There are functions that
-return values which some callers may find useful; it makes no sense to
-clutter the program with a cast to @code{void} whenever the value isn't
-useful.
+C contains many standard functions that return a value that most
+programs choose to ignore.  One obvious example is @code{printf}.
+Warning about this practice only leads the defensive programmer to
+clutter programs with dozens of casts to @code{void}.  Such casts are
+required so frequently that they become visual noise.  Writing those
+casts becomes so automatic that they no longer convey useful
+information about the intentions of the programmer.  For functions
+where the return value should never be ignored, use the
+@code{warn_unused_result} function attribute (@pxref{Function
+Attributes}).
 
 @item
 @opindex fshort-enums