+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.
@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.
@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
@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.
-@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.
@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
@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.
@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.
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.
@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.
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.
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.
@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
@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.
@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}.
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
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)
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
@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
@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
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
@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:
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
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
@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
@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 *)
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
@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
@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++}
@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
@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
@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
@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
@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
@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
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
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
@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
@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
@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.
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
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.
@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.
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
@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
@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
projects / gcc.git / commitdiff