2004-10-28 Joseph S. Myers <jsm@polyomino.org.uk>
+ * doc/contrib.texi, doc/cpp.texi, doc/cppopts.texi,
+ doc/extend.texi, doc/gcov.texi, doc/install.texi, doc/invoke.texi,
+ doc/libgcc.texi, doc/md.texi, doc/passes.texi,
+ doc/sourcebuild.texi, doc/tm.texi: Improve Texinfo formatting.
+
+2004-10-28 Joseph S. Myers <jsm@polyomino.org.uk>
+
* doc/c-tree.texi, doc/cpp.texi, doc/implement-c.texi,
doc/invoke.texi, doc/md.texi, doc/passes.texi, doc/tm.texi: Put
punctuation outside quotes.
@item
Gabriel Dos Reis for contributions to G++, contributions and
maintenance of GCC diagnostics infrastructure, libstdc++-v3,
-including valarray<>, complex<>, maintaining the numerics library
-(including that pesky <limits> :-) and keeping up-to-date anything
+including @code{valarray<>}, @code{complex<>}, maintaining the numerics library
+(including that pesky @code{<limits>} :-) and keeping up-to-date anything
to do with numbers.
@item
Ulrich Drepper for his work on glibc, testing of GCC using glibc, ISO C99
support, CFG dumping support, etc., plus support of the C++ runtime
libraries including for all kinds of C interface issues, contributing and
-maintaining complex<>, sanity checking and disbursement, configuration
+maintaining @code{complex<>}, sanity checking and disbursement, configuration
architecture, libio maintenance, and early math work.
@item
Jason Molenda for major help in the care and feeding of all the services
on the gcc.gnu.org (formerly egcs.cygnus.com) machine---mail, web
services, ftp services, etc etc. Doing all this work on scrap paper and
-the backs of envelopes would have been... difficult.
+the backs of envelopes would have been@dots{} difficult.
@item
Catherine Moore for fixing various ugly problems we have sent her
GCC 2.95.3.
@item
-Peter Schmid for constant testing of libstdc++ -- especially application
+Peter Schmid for constant testing of libstdc++---especially application
testing, going above and beyond what was requested for the release
-criteria -- and libstdc++ header file tweaks.
+criteria---and libstdc++ header file tweaks.
@item
Jason Schroeder for jcf-dump patches.
quote marks. Directories after @option{-I-} are searched for all
headers. Second, the directory containing the current file is not
searched for anything, unless it happens to be one of the directories
-named by an @option{-I} switch. @option{-I-} is deprecated, -iquote
+named by an @option{-I} switch. @option{-I-} is deprecated, @option{-iquote}
should be used instead.
@option{-I. -I-} is not the same as no @option{-I} options at all, and does
compiler issues a warning, and the excess leading characters are
ignored.
-For example, 'ab' for a target with an 8-bit @code{char} would be
-interpreted as @w{(int) ((unsigned char) 'a' * 256 + (unsigned char)
-'b')}, and '\234a' as @w{(int) ((unsigned char) '\234' * 256 + (unsigned
-char) 'a')}.
+For example, @code{'ab'} for a target with an 8-bit @code{char} would be
+interpreted as @w{@samp{(int) ((unsigned char) 'a' * 256 + (unsigned char)
+'b')}}, and @code{'\234a'} as @w{@samp{(int) ((unsigned char) '\234' *
+256 + (unsigned char) 'a')}}.
@item Source file inclusion.
@item -MMD
@opindex MMD
Like @option{-MD} except mention only user header files, not system
--header files.
+header files.
@ifclear cppmanual
@item -fpch-deps
using thunks.
On the SH Symbian OS target the @code{dllimport} attribute also has
-another affect - it can cause the vtable and run-time type information
+another affect---it can cause the vtable and run-time type information
for a class to be exported. This happens when the class has a
dllimport'ed constructor or a non-inline, non-pure virtual function
and, for either of those two conditions, the class also has a inline
@opindex fno-common
The @code{common} attribute requests GCC to place a variable in
``common'' storage. The @code{nocommon} attribute requests the
-opposite -- to allocate space for it directly.
+opposite---to allocate space for it directly.
These attributes override the default chosen by the
@option{-fno-common} and @option{-fcommon} flags respectively.
In the following example @code{struct my_packed_struct}'s members are
packed closely together, but the internal layout of its @code{s} member
-is not packed -- to do that, @code{struct my_unpacked_struct} would need to
+is not packed---to do that, @code{struct my_unpacked_struct} would need to
be packed too.
@smallexample
@itemx --preserve-paths
Preserve complete path information in the names of generated
@file{.gcov} files. Without this option, just the filename component is
-used. With this option, all directories are used, with '/' characters
-translated to '#' characters, '.' directory components removed and '..'
-components renamed to '^'. This is useful if sourcefiles are in several
+used. With this option, all directories are used, with @samp{/} characters
+translated to @samp{#} characters, @file{.} directory components
+removed and @file{..}
+components renamed to @samp{^}. This is useful if sourcefiles are in several
different directories. It also affects the @samp{-l} option.
@item -f
be something more complicated if the @samp{-l} or @samp{-p} options are
given. Refer to those options for details.
-The @file{.gcov} files contain the ':' separated fields along with
+The @file{.gcov} files contain the @samp{:} separated fields along with
program source code. The format is
@smallexample
For native builds, some of the installed programs are also installed
with the target alias in front of their name, as in
@samp{i686-pc-linux-gnu-gcc}. All of the above transformations happen
-before the target alias is prepended to the name - so, specifying
+before the target alias is prepended to the name---so, specifying
@option{--program-prefix=foo-} and @option{program-suffix=-3.1}, the
resulting binary would be installed as
@file{/usr/local/bin/i686-pc-linux-gnu-foo-gcc-3.1}.
another directory which is based on the @option{--prefix} value.)
Both the local-prefix include directory and the GCC-prefix include
-directory are part of GCC's "system include" directories. Although these
+directory are part of GCC's ``system include'' directories. Although these
two directories are not fixed, they need to be searched in the proper
order for the correct processing of the include_next directive. The
local-prefix include directory is searched before the GCC-prefix
Supplement OSS631C or later. If you are using release 5.0.7 of
OpenServer, you must have at least the first maintenance pack installed
(this includes the relevant portions of OSS646). OSS646, also known as
-the "Execution Environment Update", provides updated link editors and
+the ``Execution Environment Update'', provides updated link editors and
assemblers, as well as updated standard C and math libraries. The C
startup modules are also updated to support the System V gABI draft, and
GCC relies on that behavior. OSS631 provides a collection of commonly
testing. In general, only the @option{--with-gnu-as} option is tested.
A modern bintuils (as well as a plethora of other development related
GNU utilities) can be found in Support Level Supplement OSS658A, the
-"GNU Development Tools" package. See the SCO web and ftp sites for details.
-That package also contains the currently "officially supported" version of
+``GNU Development Tools'' package. See the SCO web and ftp sites for details.
+That package also contains the currently ``officially supported'' version of
GCC, version 2.95.3. It is useful for bootstrapping this version.
@html
to pass all the source files to the compiler at once (for those
languages for which the compiler can handle this). This will allow
intermodule analysis (IMA) to be performed by the compiler. Currently the only
-language for which this is supported is C. If you pass source files for
+language for which this is supported is C@. If you pass source files for
multiple languages to the driver, using this option, the driver will invoke
the compiler(s) that support IMA once each, passing each compiler all the
source files appropriate for it. For those languages that do not support
IMA this option will be ignored, and the compiler will be invoked once for
each source file in that language. If you use this option in conjunction
-with -save-temps, the compiler will generate multiple pre-processed files
-(one for each source file), but only one (combined) .o or .s file.
+with @option{-save-temps}, the compiler will generate multiple
+pre-processed files
+(one for each source file), but only one (combined) @file{.o} or
+@file{.s} file.
@item --help
@opindex help
To resolve this you either need to put @file{cpp0} and the other compiler
components where @command{gcc} expects to find them, or you can set the environment
variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
-Don't forget the trailing '/'.
+Don't forget the trailing @samp{/}.
@xref{Environment Variables}.
@item -dumpmachine
With @option{-fbranch-probabilities}, it reads back the data gathered
and issues prefetch instructions according to them. In addition to the opportunities
noticed by @option{-fprefetch-loop-arrays}, it also notices more complicated
-memory access patterns -- for example accesses to the data stored in linked
+memory access patterns---for example accesses to the data stored in linked
list whose elements are usually allocated sequentially.
In order to prevent issuing double prefetches, usage of
@item -fvisibility=@var{default|internal|hidden|protected}
@opindex fvisibility
-Set the default ELF image symbol visibility to the specified option - all
+Set the default ELF image symbol visibility to the specified option---all
symbols will be marked with this unless overridden within the code.
Using this feature can very substantially improve linking and
load times of shared object libraries, produce more optimized
available to be linked against from outside the shared object.
@code{protected} and @code{internal} are pretty useless in real-world
usage so the only other commonly used option will be @code{hidden}.
-The default if -fvisibility isn't specified is @code{default} ie; make every
-symbol public - this causes the same behavior as previous versions of
+The default if @option{-fvisibility} isn't specified is
+@code{default}, i.e., make every
+symbol public---this causes the same behavior as previous versions of
GCC.
A good explanation of the benefits offered by ensuring ELF
symbols have the correct visibility is given by ``How To Write
Shared Libraries'' by Ulrich Drepper (which can be found at
-@w{@uref{http://people.redhat.com/~drepper/}}) - however a superior
+@w{@uref{http://people.redhat.com/~drepper/}})---however a superior
solution made possible by this option to marking things hidden when
the default is public is to make the default hidden and mark things
public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
part of the API interface contract} and thus all new code should
always specify visibility when it is not the default ie; declarations
only for use within the local DSO should @strong{always} be marked explicitly
-as hidden as so to avoid PLT indirection overheads - making this
+as hidden as so to avoid PLT indirection overheads---making this
abundantly clear also aids readability and self-documentation of the code.
Note that due to ISO C++ specification requirements, operator new and
operator delete must always be of default visibility.
@deftypefnx {Runtime Function} int __cmpdf2 (double @var{a}, double @var{b})
@deftypefnx {Runtime Function} int __cmptf2 (long double @var{a}, long double @var{b})
These functions calculate @math{a <=> b}. That is, if @var{a} is less
-than @var{b}, they return -1; if @var{a} is greater than @var{b}, they
+than @var{b}, they return @minus{}1; if @var{a} is greater than @var{b}, they
return 1; and if @var{a} and @var{b} are equal they return 0. If
either argument is NaN they return 1, but you should not rely on this;
if NaN is a possibility, use one of the higher-level comparison
The constant zero
@item P
-0 or -1 for @code{dep} instruction
+0 or @minus{}1 for @code{dep} instruction
@item Q
Non-volatile memory for floating-point loads and stores
Non-SP registers (everything except @samp{SP})
@item R
-Indirect through @samp{IP} - Avoid this except for @code{QImode}, since we
+Indirect through @samp{IP}---Avoid this except for @code{QImode}, since we
can't access extra bytes
@item S
@item Motorola 68HC11 & 68HC12 families---@file{m68hc11.h}
@table @code
@item a
-Register 'a'
+Register `a'
@item b
-Register 'b'
+Register `b'
@item d
-Register 'd'
+Register `d'
@item q
An 8-bit register
Stack pointer register
@item x
-Register 'x'
+Register `x'
@item y
-Register 'y'
+Register `y'
@item z
-Pseudo register 'z' (replaced by 'x' or 'y' at the end)
+Pseudo register `z' (replaced by `x' or `y' at the end)
@item A
An address register: x, y or z
@item D,S,H:
mode of the containing operand
@item 0,F:
- value of the other parts (F - all bits set)
+ value of the other parts (F---all bits set)
@end table
The constraint matches if the specified part of a constant
has a value different from it's other parts.
and take care of standard bookkeeping that applies to every pass.
The theory of operation is that each pass defines a structure that
-represents everything we need to know about that pass --- when it
+represents everything we need to know about that pass---when it
should be run, how it should be run, what intermediate language
form or on-the-side data structures it needs. We register the pass
to be run in some particular order, and the pass manager arranges
@item lang.opt
This file registers the set of switches that the front end accepts on
-the command line, and their --help text. The file format is
+the command line, and their @option{--help} text. The file format is
documented in the file @file{c.opt}. These files are processed by the
script @file{opts.sh}.
@item lang-specs.h
There is also an extra chapter called @file{gcc} containing a template for
creating new executable tests.
-The tests are run using two 'sh' scripts: run_acats and run_all.sh
-To run the tests using a simulator or a cross target, see the small
-customization section at the top of run_all.sh
+The tests are run using two @command{sh} scripts: @file{run_acats} and
+@file{run_all.sh}. To run the tests using a simulator or a cross
+target, see the small
+customization section at the top of @file{run_all.sh}.
These tests are run using the build tree: they can be run without doing
a @code{make install}.
being compiled. @var{n_named_args} is set to the number of named
arguments, including a structure return address if it is passed as a
parameter, when making a call. When processing incoming arguments,
-@var{n_named_args} is set to -1.
+@var{n_named_args} is set to @minus{}1.
When processing a call to a compiler support library function,
@var{libname} identifies which one. It is a @code{symbol_ref} rtx which
operand is smaller than the second, 1 to indicate that they are equal,
and 2 to indicate that the first operand is greater than the second.
If this macro evalutes to @code{false} the comparison functions return
--1, 0, and 1 instead of 0, 1, and 2. If the target uses the routines
+@minus{}1, 0, and 1 instead of 0, 1, and 2. If the target uses the routines
in @file{libgcc.a}, you do not need to define this macro.
@end defmac
delays, however: (b) there's a better chance to predict the actual grouping
that will be formed, and (c) correctly emulating the grouping can be very
important. In such targets one may want to allow issuing dependent insns
-closer to one another - i.e, closer than the dependence distance; however,
+closer to one another---i.e., closer than the dependence distance; however,
not in cases of "costly dependences", which this hooks allows to define.
@end deftypefn
initializer for an array of integers. Each initializer element
N refers to an entity that needs mode switching, and specifies the number
of different modes that might need to be set for this entity.
-The position of the initializer in the initializer - starting counting at
-zero - determines the integer that is used to refer to the mode-switched
+The position of the initializer in the initializer---starting counting at
+zero---determines the integer that is used to refer to the mode-switched
entity in question.
In macros that take mode arguments / yield a mode result, modes are
represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode
@deftypefn {Target Hook} int TARGET_CXX_IMPORT_EXPORT_CLASS (tree @var{type}, int @var{import_export})
If defined by a backend this hook allows the decision made to export
class @var{type} to be overruled. Upon entry @var{import_export}
-will contain 1 if the class is going to be exported, -1 if it is going
+will contain 1 if the class is going to be exported, @minus{}1 if it is going
to be imported and 0 otherwise. This function should return the
modified value and perform any other actions necessary to support the
backend's targeted operating system.
projects / platform / upstream / gcc.git / commitdiff