extend.texi, [...]: Improve formatting.

gcc:
	* doc/extend.texi, doc/gcc.texi, doc/invoke.texi, doc/md.texi,
	doc/rtl.texi, doc/tm.texi: Improve formatting.  Improve
	documentation of -std and -Wwrite-strings.

contrib:
	* texi2pod.pl: Handle @r inside @item.

From-SVN: r43718

9 files changed, 227 insertions, 195 deletions

diff --git a/contrib/ChangeLog b/contrib/ChangeLog
index bd0825e..7279ad9 100644
--- a/contrib/ChangeLog
+++ b/contrib/ChangeLog
@@ -1,3 +1,7 @@
+2001-07-03  Joseph S. Myers  <jsm28@cam.ac.uk>
+
+	* texi2pod.pl: Handle @r inside @item.
+
 2001-07-02  Zack Weinberg  <zackw@stanford.edu>
 
 	* gcc_update: Remove entries for gcc.1, cpp.1, gcov.1.
diff --git a/contrib/texi2pod.pl b/contrib/texi2pod.pl
index d70b448..7a930ee 100755
--- a/contrib/texi2pod.pl
+++ b/contrib/texi2pod.pl
@@ -279,9 +279,6 @@ sub postprocess
     s/\@w\{([^\}]*)\}/S<$1>/g;
     s/\@(?:dmn|math)\{([^\}]*)\}/$1/g;
 
-    # Handle @r inside bold.
-    1 while s/B<((?:[^<>]|I<[^<>]*>)*)R<([^>]*)>/B<$1>${2}B</g;
-
     # Cross references are thrown away, as are @noindent and @refill.
     # (@noindent is impossible in .pod, and @refill is unnecessary.)
     # @* is also impossible in .pod; we discard it and any newline that
@@ -303,9 +300,11 @@ sub postprocess
     s/\@uref\{([^\},]*),([^\},]*),([^\},]*)\}/$3/g;
 
     # Turn B<blah I<blah> blah> into B<blah> I<blah> B<blah> to
-    # match Texinfo semantics of @emph inside @samp.
+    # match Texinfo semantics of @emph inside @samp.  Also handle @r
+    # inside bold.
     s/&LT;/</g;
     s/&GT;/>/g;
+    1 while s/B<((?:[^<>]|I<[^<>]*>)*)R<([^>]*)>/B<$1>${2}B</g;
     1 while (s/B<([^<>]*)I<([^>]+)>/B<$1>I<$2>B</g);
     1 while (s/I<([^<>]*)B<([^>]+)>/I<$1>B<$2>I</g);
     s/[BI]<>//g;
diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 5b45aab..01d855a 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,9 @@
+2001-07-03  Joseph S. Myers  <jsm28@cam.ac.uk>
+
+	* doc/extend.texi, doc/gcc.texi, doc/invoke.texi, doc/md.texi,
+	doc/rtl.texi, doc/tm.texi: Improve formatting.  Improve
+	documentation of -std and -Wwrite-strings.
+
 2001-07-02  Geoffrey Keating  <geoffk@redhat.com>
 
 	* cse.c (canon_hash): Don't register registers in very small
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 28835fb..f08be3b 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -387,6 +387,7 @@ called @dfn{lexical scoping}.  For example, here we show a nested
 function which uses an inherited variable named @code{offset}:
 
 @example
+@group
 bar (int *array, int offset, int size)
 @{
   int access (int *array, int index)
@@ -396,6 +397,7 @@ bar (int *array, int offset, int size)
   for (i = 0; i < size; i++)
     @dots{} access (array, i) @dots{}
 @}
+@end group
 @end example
 
 Nested function definitions are permitted within functions in the places
@@ -886,7 +888,13 @@ conforming) and in C++.  In that format the
 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are
 mandatory.  The exponent is a decimal number that indicates the power of
 2 by which the significant part will be multiplied.  Thus @samp{0x1.f} is
-1 15/16, @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
+@tex
+$1 {15\over16}$,
+@end tex
+@ifnottex
+1 15/16,
+@end ifnottex
+@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3}
 is the same as @code{1.55e1}.
 
 Unlike for floating-point numbers in the decimal notation the exponent
@@ -1493,7 +1501,7 @@ double y;
 @end example
 
 @noindent
-both @code{x} and @code{y} can be cast to type @code{union} foo.
+both @code{x} and @code{y} can be cast to type @code{union foo}.
 
 Using the cast as the right-hand side of an assignment to a variable of
 union type is equivalent to storing in a member of the union:
@@ -1581,6 +1589,7 @@ their own functions that never return.  You can declare them
 @code{noreturn} to tell the compiler this fact.  For example,
 
 @smallexample
+@group
 void fatal () __attribute__ ((noreturn));
 
 void
@@ -1589,6 +1598,7 @@ fatal (@dots{})
   @dots{} /* @r{Print error message.} */ @dots{}
   exit (1);
 @}
+@end group
 @end smallexample
 
 The @code{noreturn} keyword tells the compiler to assume that
@@ -1973,7 +1983,8 @@ alternate stack.
 
 @smallexample
 void *alt_stack;
-void f () __attribute__ ((interrupt_handler, sp_switch ("alt_stack")));
+void f () __attribute__ ((interrupt_handler,
+                          sp_switch ("alt_stack")));
 @end smallexample
 
 @item trap_exit
@@ -3181,7 +3192,7 @@ asm volatile ("eieio" : : );
 @noindent
 Assume @code{addr} contains the address of a memory mapped device
 register.  The PowerPC @code{eieio} instruction (Enforce In-order
-Execution of I/O) tells the cpu to make sure that the store to that
+Execution of I/O) tells the CPU to make sure that the store to that
 device register happens before it issues any other I/O@.
 
 Note that even a volatile @code{asm} instruction can be moved in ways
@@ -4725,20 +4736,20 @@ and will be removed from g++ at some point.
 @cindex Backwards Compatibility
 @cindex ARM [Annotated C++ Reference Manual]
 
-Now that there is a definitive ISO standard C++, g++ has a specification
+Now that there is a definitive ISO standard C++, G++ has a specification
 to adhere to.  The C++ language evolved over time, and features that
 used to be acceptable in previous drafts of the standard, such as the ARM
 [Annotated C++ Reference Manual], are no longer accepted.  In order to allow
-compilation of C++ written to such drafts, g++ contains some backwards
+compilation of C++ written to such drafts, G++ contains some backwards
 compatibilities.  @emph{All such backwards compatibility features are
-liable to disappear in future versions of g++.} They should be considered
+liable to disappear in future versions of G++.} They should be considered
 deprecated @xref{Deprecated Features}.
 
 @table @code
 @item For scope
 If a variable is declared at for scope, it used to remain in scope until
 the end of the scope which contained the for statement (rather than just
-within the for scope).  g++ retains this, but issues a warning, if such a
+within the for scope).  G++ retains this, but issues a warning, if such a
 variable is accessed outside the for scope.
 
 @item implicit C language
diff --git a/gcc/doc/gcc.texi b/gcc/doc/gcc.texi
index d20e6b5..fb4eb6a 100644
--- a/gcc/doc/gcc.texi
+++ b/gcc/doc/gcc.texi
@@ -188,7 +188,7 @@ included in the section entitled ``GNU Free Documentation License''.
 @sp 1
 @c The version number appears five times more in this file.
 
-@center for gcc-3.1
+@center for GCC 3.1
 @page
 @vskip 0pt plus 1filll
 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
@@ -197,7 +197,7 @@ Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1998,
 For GCC Version 3.1@*
 @sp 1
 Published by the Free Software Foundation @*
-59 Temple Place - Suite 330@*
+59 Temple Place---Suite 330@*
 Boston, MA 02111-1307, USA@*
 Last printed April, 1998.@*
 Printed copies are available for $50 each.@*
@@ -1143,9 +1143,11 @@ arguments do not work with GCC@.  For example, a program like this
 will not work:
 
 @example
+@group
 foobar (
 #define luser
         hack)
+@end group
 @end example
 
 ISO C does not permit such a construct.  It would make sense to support
@@ -3214,12 +3216,12 @@ and some files shared with Objective-C and C++.
 
 The source files for parsing C++ are in @file{cp/}.
 They are @file{parse.y},
-@file{class.c},@*
+@file{class.c},
 @file{cvt.c}, @file{decl.c}, @file{decl2.c},
-@file{except.c},@*
+@file{except.c},
 @file{expr.c}, @file{init.c}, @file{lex.c},
-@file{method.c}, @file{ptree.c},@*
-@file{search.c}, @file{spew.c}, @*
+@file{method.c}, @file{ptree.c},
+@file{search.c}, @file{spew.c},
 @file{semantics.c}, @file{tree.c},
 @file{typeck2.c}, and
 @file{typeck.c}, along with header files @file{cp-tree.def},
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 251530a..4b01442 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -237,7 +237,8 @@ in the following sections.
 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
 @gccoptlist{
 -a  -ax  -d@var{letters}  -dumpspecs  -dumpmachine  -dumpversion @gol
--fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
+-fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
+-fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
 -fdump-ast-original@r{[}-@var{n}@r{]} -fdump-ast-optimized@r{[}-@var{n}@r{]} @gol
 -fdump-ast-inlined@r{[}-@var{n}@r{]} @gol
 -fmem-report  -fpretend-float @gol
@@ -288,12 +289,12 @@ in the following sections.
 -iprefix @var{file}  -iwithprefix @var{dir} @gol
 -iwithprefixbefore @var{dir}  -isystem @var{dir} @gol
 -M  -MM  -MF  -MG  -MP  -MQ  -MT  -nostdinc  -P  -remap @gol
--trigraphs  -undef  -U@var{macro}  -Wp\,@var{option}}
+-trigraphs  -undef  -U@var{macro}  -Wp,@var{option}}
 
 @item Assembler Option
 @xref{Assembler Options,,Passing Options to the Assembler}.
 @gccoptlist{
--Wa\,@var{option}}
+-Wa,@var{option}}
 
 @item Linker Options
 @xref{Link Options,,Options for Linking}.
@@ -301,7 +302,7 @@ in the following sections.
 @var{object-file-name}  -l@var{library} @gol
 -nostartfiles  -nodefaultlibs  -nostdlib @gol
 -s  -static  -static-libgcc  -shared  -shared-libgcc  -symbolic @gol
--Wl\,@var{option}  -Xlinker @var{option} @gol
+-Wl,@var{option}  -Xlinker @var{option} @gol
 -u @var{symbol}}
 
 @item Directory Options
@@ -526,7 +527,7 @@ in the following sections.
 
 @emph{System V Options}
 @gccoptlist{
--Qy  -Qn  -YP\,@var{paths}  -Ym\,@var{dir}}
+-Qy  -Qn  -YP,@var{paths}  -Ym,@var{dir}}
 
 @emph{ARC Options}
 @gccoptlist{
@@ -876,7 +877,7 @@ In C mode, support all ISO C89 programs.  In C++ mode,
 remove GNU extensions that conflict with ISO C++.
 
 This turns off certain features of GCC that are incompatible with ISO
-C (when compiling C code), or of standard C++ (when compiling C++ code),
+C89 (when compiling C code), or of standard C++ (when compiling C++ code),
 such as the @code{asm} and @code{typeof} keywords, and
 predefined macros such as @code{unix} and @code{vax} that identify the
 type of system you are using.  It also enables the undesirable and
@@ -910,40 +911,33 @@ affected.
 
 @item -std=
 @opindex std
-Determine the language standard.  A value for this option must be provided;
+Determine the language standard.  This option is currently only
+supported when compiling C@.  A value for this option must be provided;
 possible values are
 
 @table @samp
-@item iso9899:1990
-Same as @option{-ansi}
+@item c89
+@itemx iso9899:1990
+ISO C89 (same as @option{-ansi}).
 
 @item iso9899:199409
-ISO C as modified in amendment 1
-
-@item iso9899:1999
-ISO C99.  Note that this standard is not yet fully supported; see
-@w{@uref{http://gcc.gnu.org/c99status.html}} for more information.
-
-@item c89
-same as @option{-std=iso9899:1990}
+ISO C89 as modified in amendment 1.
 
 @item c99
-same as @option{-std=iso9899:1999}
+@itemx c9x
+@itemx iso9899:1999
+@itemx iso9899:199x
+ISO C99.  Note that this standard is not yet fully supported; see
+@w{@uref{http://gcc.gnu.org/c99status.html}} for more information.  The
+names @samp{c9x} and @samp{iso9899:199x} are deprecated.
 
 @item gnu89
-default, iso9899:1990 + gnu extensions
+Default, ISO C89 plus GNU extensions (including some C99 features).
 
 @item gnu99
-iso9899:1999 + gnu extensions
-
-@item iso9899:199x
-same as @option{-std=iso9899:1999}, deprecated
-
-@item c9x
-same as @option{-std=iso9899:1999}, deprecated
-
-@item gnu9x
-same as @option{-std=gnu99}, deprecated
+@itemx gnu9x
+ISO C99 plus GNU extensions.  When ISO C99 is fully implemented in GCC,
+this will become the default.  The name @samp{gnu9x} is deprecated.
 
 @end table
 
@@ -1268,7 +1262,7 @@ this check is normally unnecessary.
 
 An alternative to using this option is to specify that your
 @code{operator new} does not throw any exceptions; if you declare it
-@samp{throw()}, g++ will check the return value.  See also @samp{new
+@samp{throw()}, G++ will check the return value.  See also @samp{new
 (nothrow)}.
 
 @item -fconserve-space
@@ -1307,7 +1301,7 @@ identifiers.  However, ISO C and C++ forbid @samp{$} in identifiers.
 @opindex fno-elide-constructors
 The C++ standard allows an implementation to omit creating a temporary
 which is only used to initialize another object of the same type.
-Specifying this option disables that optimization, and forces g++ to
+Specifying this option disables that optimization, and forces G++ to
 call the copy constructor in all cases.
 
 @item -fno-enforce-eh-specs
@@ -1343,7 +1337,7 @@ a @i{for-init-statement} is limited to the @samp{for} loop itself,
 as specified by the C++ standard.
 If @option{-fno-for-scope} is specified, the scope of variables declared in
 a @i{for-init-statement} extends to the end of the enclosing scope,
-as was the case in old versions of gcc, and other (traditional)
+as was the case in old versions of G++, and other (traditional)
 implementations of C++.
 
 The default if neither flag is given to follow the standard,
@@ -1407,13 +1401,13 @@ synonyms as keywords.
 @item -fno-optional-diags
 @opindex fno-optional-diags
 Disable diagnostics that the standard says a compiler does not need to
-issue.  Currently, the only such diagnostic issued by g++ is the one for
+issue.  Currently, the only such diagnostic issued by G++ is the one for
 a name having multiple meanings within a class.
 
 @item -fpermissive
 @opindex fpermissive
 Downgrade messages about nonconformant code from errors to warnings.  By
-default, g++ effectively sets @option{-pedantic-errors} without
+default, G++ effectively sets @option{-pedantic-errors} without
 @option{-pedantic}; this option reverses that.  This behavior and this
 option are superseded by @option{-pedantic}, which works as it does for GNU C@.
 
@@ -1489,18 +1483,18 @@ Do not assume @samp{inline} for functions defined inside a class scope.
 functions will have linkage like inline functions; they just won't be
 inlined by default.
 
-@item -Wctor-dtor-privacy (C++ only)
+@item -Wctor-dtor-privacy @r{(C++ only)}
 @opindex Wctor-dtor-privacy
 Warn when a class seems unusable, because all the constructors or
 destructors in a class are private and the class has no friends or
 public static member functions.
 
-@item -Wnon-virtual-dtor (C++ only)
+@item -Wnon-virtual-dtor @r{(C++ only)}
 @opindex Wnon-virtual-dtor
 Warn when a class declares a non-virtual destructor that should probably
 be virtual, because it looks like the class will be used polymorphically.
 
-@item -Wreorder (C++ only)
+@item -Wreorder @r{(C++ only)}
 @opindex Wreorder
 @cindex reordering, warning
 @cindex warning for reordering of member initializers
@@ -1523,41 +1517,41 @@ members.
 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
 
 @table @gcctabopt
-@item -Weffc++ (C++ only)
+@item -Weffc++ @r{(C++ only)}
 @opindex Weffc++
 Warn about violations of various style guidelines from Scott Meyers'
 @cite{Effective C++} books.  If you use this option, you should be aware
 that the standard library headers do not obey all of these guidelines;
 you can use @samp{grep -v} to filter out those warnings.
 
-@item -Wno-deprecated (C++ only)
+@item -Wno-deprecated @r{(C++ only)}
 @opindex Wno-deprecated
 Do not warn about usage of deprecated features.  @xref{Deprecated Features}.
 
-@item -Wno-non-template-friend (C++ only)
+@item -Wno-non-template-friend @r{(C++ only)}
 @opindex Wno-non-template-friend
 Disable warnings when non-templatized friend functions are declared
 within a template.  With the advent of explicit template specification
-support in g++, if the name of the friend is an unqualified-id (i.e.,
+support in G++, if the name of the friend is an unqualified-id (i.e.,
 @samp{friend foo(int)}), the C++ language specification demands that the
 friend declare or define an ordinary, nontemplate function.  (Section
-14.5.3).  Before g++ implemented explicit specification, unqualified-ids
+14.5.3).  Before G++ implemented explicit specification, unqualified-ids
 could be interpreted as a particular specialization of a templatized
 function.  Because this non-conforming behavior is no longer the default
-behavior for g++, @option{-Wnon-template-friend} allows the compiler to
+behavior for G++, @option{-Wnon-template-friend} allows the compiler to
 check existing code for potential trouble spots, and is on by default.
 This new compiler behavior can be turned off with
 @option{-Wno-non-template-friend} which keeps the conformant compiler code
 but disables the helpful warning.
 
-@item -Wold-style-cast (C++ only)
+@item -Wold-style-cast @r{(C++ only)}
 @opindex Wold-style-cast
 Warn if an old-style (C-style) cast is used within a C++ program.  The
 new-style casts (@samp{static_cast}, @samp{reinterpret_cast}, and
 @samp{const_cast}) are less vulnerable to unintended effects, and much
 easier to grep for.
 
-@item -Woverloaded-virtual (C++ only)
+@item -Woverloaded-virtual @r{(C++ only)}
 @opindex Woverloaded-virtual
 @cindex overloaded virtual fn, warning
 @cindex warning for overloaded virtual fn
@@ -1584,23 +1578,23 @@ b->f();
 
 will fail to compile.
 
-@item -Wno-pmf-conversions (C++ only)
+@item -Wno-pmf-conversions @r{(C++ only)}
 @opindex Wno-pmf-conversions
 Disable the diagnostic for converting a bound pointer to member function
 to a plain pointer.
 
-@item -Wsign-promo (C++ only)
+@item -Wsign-promo @r{(C++ only)}
 @opindex Wsign-promo
 Warn when overload resolution chooses a promotion from unsigned or
 enumeral type to a signed type over a conversion to an unsigned type of
-the same size.  Previous versions of g++ would try to preserve
+the same size.  Previous versions of G++ would try to preserve
 unsignedness, but the standard mandates the current behavior.
 
-@item -Wsynth (C++ only)
+@item -Wsynth @r{(C++ only)}
 @opindex Wsynth
 @cindex warning for synthesized methods
 @cindex synthesized methods, warning
-Warn when g++'s synthesis behavior does not match that of cfront.  For
+Warn when G++'s synthesis behavior does not match that of cfront.  For
 instance:
 
 @smallexample
@@ -1616,7 +1610,7 @@ main ()
 @}
 @end smallexample
 
-In this example, g++ will synthesize a default @samp{A& operator =
+In this example, G++ will synthesize a default @samp{A& operator =
 (const A&);}, while cfront will use the user-defined @samp{operator =}.
 @end table
 
@@ -1697,7 +1691,7 @@ the remaining front ends would be able to digest them correctly.
 @item -fmessage-length=@var{n}
 @opindex fmessage-length
 Try to format error messages so that they fit on lines of about @var{n}
-characters.  The default is 72 characters for g++ and 0 for the rest of
+characters.  The default is 72 characters for @command{g++} and 0 for the rest of
 the front ends supported by GCC@.  If @var{n} is zero, then no
 line-wrapping will be done; each error message will appear on a single
 line.
@@ -1922,6 +1916,7 @@ Also warn about constructions where there may be confusion to which
 such a case:
 
 @smallexample
+@group
 @{
   if (a)
     if (b)
@@ -1929,6 +1924,7 @@ such a case:
   else
     bar ();
 @}
+@end group
 @end smallexample
 
 In C, every @code{else} branch belongs to the innermost possible @code{if}
@@ -1941,6 +1937,7 @@ To eliminate the warning, add explicit braces around the innermost
 the enclosing @code{if}.  The resulting code would look like this:
 
 @smallexample
+@group
 @{
   if (a)
     @{
@@ -1950,6 +1947,7 @@ the enclosing @code{if}.  The resulting code would look like this:
         bar ();
     @}
 @}
+@end group
 @end smallexample
 
 @item -Wsequence-point
@@ -2088,6 +2086,7 @@ despite appearing to have an error.  Here is one example of how
 this can happen:
 
 @smallexample
+@group
 @{
   int x;
   switch (y)
@@ -2100,6 +2099,7 @@ this can happen:
     @}
   foo (x);
 @}
+@end group
 @end smallexample
 
 @noindent
@@ -2134,7 +2134,7 @@ Some spurious warnings can be avoided if you declare all the functions
 you use that never return as @code{noreturn}.  @xref{Function
 Attributes}.
 
-@item -Wreorder (C++ only)
+@item -Wreorder @r{(C++ only)}
 @opindex Wreorder
 @cindex reordering, warning
 @cindex warning for reordering of member initializers
@@ -2273,7 +2273,7 @@ would check to see whether the two values have ranges that overlap; and
 this is done with the relational operators, so equality comparisons are
 probably mistaken.
 
-@item -Wtraditional (C only)
+@item -Wtraditional @r{(C only)}
 @opindex Wtraditional
 Warn about certain constructs that behave differently in traditional and
 ISO C@.  Also warn about ISO C constructs that have no traditional C
@@ -2372,7 +2372,7 @@ of @code{void}.  GNU C assigns these types a size of 1, for
 convenience in calculations with @code{void *} pointers and pointers
 to functions.
 
-@item -Wbad-function-cast (C only)
+@item -Wbad-function-cast @r{(C only)}
 @opindex Wbad-function-cast
 Warn whenever a function call is cast to a non-matching type.
 For example, warn if @code{int malloc()} is cast to @code{anything *}.
@@ -2392,9 +2392,12 @@ two- or four-byte boundaries.
 
 @item -Wwrite-strings
 @opindex Wwrite-strings
-Give string constants the type @code{const char[@var{length}]} so that
+When compiling C, give string constants the type @code{const
+char[@var{length}]} so that
 copying the address of one into a non-@code{const} @code{char *}
-pointer will get a warning.  These warnings will help you find at
+pointer will get a warning; when compiling C++, warn about the
+deprecated conversion from string constants to @code{char *}.
+These warnings will help you find at
 compile time code that can try to write into a string constant, but
 only if you have been very careful about using @code{const} in
 declarations and prototypes.  Otherwise, it will just be a nuisance;
@@ -2429,14 +2432,14 @@ Warn if any functions that return structures or unions are defined or
 called.  (In languages where you can return an array, this also elicits
 a warning.)
 
-@item -Wstrict-prototypes (C only)
+@item -Wstrict-prototypes @r{(C only)}
 @opindex Wstrict-prototypes
 Warn if a function is declared or defined without specifying the
 argument types.  (An old-style function definition is permitted without
 a warning if preceded by a declaration which specifies the argument
 types.)
 
-@item -Wmissing-prototypes (C only)
+@item -Wmissing-prototypes @r{(C only)}
 @opindex Wmissing-prototypes
 Warn if a global function is defined without a previous prototype
 declaration.  This warning is issued even if the definition itself
@@ -2505,7 +2508,7 @@ reduce the padding and so make the structure smaller.
 Warn if anything is declared more than once in the same scope, even in
 cases where multiple declaration is valid and changes nothing.
 
-@item -Wnested-externs (C only)
+@item -Wnested-externs @r{(C only)}
 @opindex Wnested-externs
 Warn if an @code{extern} declaration is encountered within a function.
 
@@ -2992,16 +2995,16 @@ numbers and line number note output.  This makes it more feasible to
 use diff on debugging dumps for compiler invocations with different
 options, in particular with and without @option{-g}.
 
-@item -fdump-translation-unit (C and C++ only)
-@item -fdump-translation-unit-@var{number} (C and C++ only)
+@item -fdump-translation-unit @r{(C and C++ only)}
+@itemx -fdump-translation-unit-@var{number} @r{(C and C++ only)}
 @opindex fdump-translation-unit
 Dump a representation of the tree structure for the entire translation
 unit to a file.  The file name is made by appending @file{.tu} to the
 source file name.  If the @samp{-@var{number}} form is used, @var{number}
 controls the details of the dump as described for the @option{-fdump-tree} options.
 
-@item -fdump-class-hierarchy (C++ only)
-@item -fdump-class-hierarchy-@var{number} (C++ only)
+@item -fdump-class-hierarchy @r{(C++ only)}
+@itemx -fdump-class-hierarchy-@var{number} @r{(C++ only)}
 @opindex fdump-class-hierarchy
 Dump a representation of each class's hierarchy and virtual function
 table layout to a file.  The file name is made by appending @file{.class}
@@ -3009,8 +3012,8 @@ to the source file name.  If the @samp{-@var{number}} form is used, @var{number}
 controls the details of the dump as described for the @option{-fdump-tree}
 options.
 
-@item -fdump-ast-@var{switch} (C++ only)
-@item -fdump-ast-@var{switch}-@var{number} (C++ only)
+@item -fdump-ast-@var{switch} @r{(C++ only)}
+@itemx -fdump-ast-@var{switch}-@var{number} @r{(C++ only)}
 @opindex fdump-ast
 Control the dumping at various stages of processing the abstract syntax
 tree to a file.  The file name is generated by appending a switch
@@ -3314,11 +3317,11 @@ allows the control of this limit for functions that are explicitly marked as
 inline (ie marked with the inline keyword or defined within the class
 definition in c++).  @var{n} is the size of functions that can be inlined in
 number of pseudo instructions (not counting parameter handling).  The default
-value of n is 10000.  Increasing this value can result in more inlined code at
+value of @var{n} is 10000.  Increasing this value can result in more inlined code at
 the cost of compilation time and memory consumption.  Decreasing usually makes
 the compilation faster and less code will be inlined (which presumably
 means slower programs).  This option is particularly useful for programs that
-use inlining heavily such as those based on recursive templates with c++.
+use inlining heavily such as those based on recursive templates with C++.
 
 @emph{Note:} pseudo instruction represents, in this particular context, an
 abstract measurement of function's size.  In no way, it represents a count
@@ -3482,7 +3485,7 @@ can be changed to a load before the loop and a store after the loop.
 Use global dataflow analysis to identify and eliminate useless null
 pointer checks.  Programs which rely on NULL pointer dereferences @emph{not}
 halting the program may not work properly with this option.  Use
--fno-delete-null-pointer-checks to disable this optimizing for programs
+@option{-fno-delete-null-pointer-checks} to disable this optimizing for programs
 which depend on that behavior.
 
 @item -fexpensive-optimizations
@@ -4093,31 +4096,31 @@ converts them.  See the @option{-std} and @option{-ansi} options.
 The nine trigraph sequences are
 @table @samp
 @item ??(
--> @samp{[}
+@expansion{} @samp{[}
 
 @item ??)
--> @samp{]}
+@expansion{} @samp{]}
 
 @item ??<
--> @samp{@{}
+@expansion{} @samp{@{}
 
 @item ??>
--> @samp{@}}
+@expansion{} @samp{@}}
 
 @item ??=
--> @samp{#}
+@expansion{} @samp{#}
 
 @item ??/
--> @samp{\}
+@expansion{} @samp{\}
 
 @item ??'
--> @samp{^}
+@expansion{} @samp{^}
 
 @item ??!
--> @samp{|}
+@expansion{} @samp{|}
 
 @item ??-
--> @samp{~}
+@expansion{} @samp{~}
 
 @end table
 
@@ -4125,7 +4128,7 @@ Trigraph support is not popular, so many compilers do not implement it
 properly.  Portable code should not rely on trigraphs being either
 converted or ignored.
 
-@item -Wp\,@var{option}
+@item -Wp,@var{option}
 @opindex Wp
 Pass @var{option} as an option to the preprocessor.  If @var{option}
 contains commas, it is split into multiple options at the commas.
@@ -4138,7 +4141,7 @@ contains commas, it is split into multiple options at the commas.
 You can pass options to the assembler.
 
 @table @gcctabopt
-@item -Wa\,@var{option}
+@item -Wa,@var{option}
 @opindex Wa
 Pass @var{option} as an option to the assembler.  If @var{option}
 contains commas, it is split into multiple options at the commas.
@@ -4327,7 +4330,7 @@ For example, to pass @option{-assert definitions}, you must write
 @option{-Xlinker "-assert definitions"}, because this passes the entire
 string as a single argument, which is not what the linker expects.
 
-@item -Wl\,@var{option}
+@item -Wl,@var{option}
 @opindex Wl
 Pass @var{option} as an option to the linker.  If @var{option} contains
 commas, it is split into multiple options at the commas.
@@ -4427,8 +4430,8 @@ the environment variable @env{GCC_EXEC_PREFIX}.  @xref{Environment
 Variables}.
 
 As a special kludge, if the path provided by @option{-B} is
-@samp{[foo/]stage<N>/} then it will be replaced by
-@samp{[foo/]include}.  This is to help with boot-strapping the compiler.
+@file{[foo/]stage@var{N}/} then it will be replaced by
+@file{[foo/]include}.  This is to help with boot-strapping the compiler.
 
 @item -specs=@var{file}
 @opindex specs
@@ -4638,7 +4641,7 @@ simply substituted with a file name chosen for the previous @samp{%u},
 without regard to any appended suffix.
 
 @item %j@var{SUFFIX}
-Substitutes the name of the HOST_BIT_BUCKET, if any, and if it is
+Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
 writable, and if save-temps is off; otherwise, substitute the name
 of a temporary file, just like @samp{%u}.  This temporary file is not
 meant for communication between processes, but rather as a junk
@@ -4683,7 +4686,7 @@ predefined macro, except for macros that start with @samp{__} or with
 C@.
 
 @item %I
-Substitute a @option{-iprefix} option made from GCC_EXEC_PREFIX@.
+Substitute a @option{-iprefix} option made from @env{GCC_EXEC_PREFIX}.
 
 @item %s
 Current argument is the name of a library or startup file of some sort.
@@ -5373,7 +5376,7 @@ With @option{-mflat}, the compiler does not generate save/restore instructions
 and will use a ``flat'' or single register window calling convention.
 This model uses %i7 as the frame pointer and is compatible with the normal
 register window model.  Code from either may be intermixed.
-The local registers and the input registers (0-5) are still treated as
+The local registers and the input registers (0--5) are still treated as
 ``call saved'' registers and will be saved on the stack as necessary.
 
 With @option{-mno-flat} (the default), the compiler emits save/restore
@@ -5936,12 +5939,16 @@ compiler is built for cross-compilation.
 @opindex mcpu
 This specifies the name of the target ARM processor.  GCC uses this name
 to determine what kind of instructions it can emit when generating
-assembly code.  Permissible names are: arm2, arm250, arm3, arm6, arm60,
-arm600, arm610, arm620, arm7, arm7m, arm7d, arm7dm, arm7di, arm7dmi,
-arm70, arm700, arm700i, arm710, arm710c, arm7100, arm7500, arm7500fe,
-arm7tdmi, arm8, strongarm, strongarm110, strongarm1100, arm8, arm810,
-arm9, arm9e, arm920, arm920t, arm940t, arm9tdmi, arm10tdmi, arm1020t,
-xscale.
+assembly code.  Permissible names are: @samp{arm2}, @samp{arm250},
+@samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
+@samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
+@samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
+@samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
+@samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm8},
+@samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
+@samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
+@samp{arm920t}, @samp{arm940t}, @samp{arm9tdmi}, @samp{arm10tdmi},
+@samp{arm1020t}, @samp{xscale}.
 
 @itemx -mtune=@var{name}
 @opindex mtune
@@ -5959,8 +5966,9 @@ this option.
 This specifies the name of the target ARM architecture.  GCC uses this
 name to determine what kind of instructions it can emit when generating
 assembly code.  This option can be used in conjunction with or instead
-of the @option{-mcpu=} option.  Permissible names are: armv2, armv2a,
-armv3, armv3m, armv4, armv4t, armv5, armv5t, armv5te.
+of the @option{-mcpu=} option.  Permissible names are: @samp{armv2},
+@samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
+@samp{armv5}, @samp{armv5t}, @samp{armv5te}.
 
 @item -mfpe=@var{number}
 @itemx -mfp=@var{number}
@@ -6018,7 +6026,7 @@ pointers.
 
 @item -mnop-fun-dllimport
 @opindex mnop-fun-dllimport
-Disable support for the @emph{dllimport} attribute.
+Disable support for the @code{dllimport} attribute.
 
 @item -msingle-pic-base
 @opindex msingle-pic-base
@@ -7119,7 +7127,7 @@ the default if the configure option @option{--with-gnu-as} is used.
 @opindex msplit-addresses
 @opindex mno-split-addresses
 Generate code to load the high and low parts of address constants separately.
-This allows @code{gcc} to optimize away redundant loads of the high order
+This allows GCC to optimize away redundant loads of the high order
 bits of addresses.  This optimization requires GNU as and GNU ld.
 This optimization is enabled by default for some embedded targets where
 GNU as and GNU ld are standard.
@@ -8236,12 +8244,12 @@ Identify the versions of each tool used by the compiler, in a
 Refrain from adding @code{.ident} directives to the output file (this is
 the default).
 
-@item -YP\,@var{dirs}
+@item -YP,@var{dirs}
 @opindex YP
 Search the directories @var{dirs}, and no others, for libraries
 specified with @option{-l}.
 
-@item -Ym\,@var{dir}
+@item -Ym,@var{dir}
 @opindex Ym
 Look in the directory @var{dir} to find the M4 preprocessor.
 The assembler uses this option.
@@ -8294,8 +8302,8 @@ count register BK@.
 Enable (disable) generation of code using decrement and branch,
 DBcond(D), instructions.  This is enabled by default for the C4x.  To be
 on the safe side, this is disabled for the C3x, since the maximum
-iteration count on the C3x is 2^23 + 1 (but who iterates loops more than
-2^23 times on the C3x?).  Note that GCC will try to reverse a loop so
+iteration count on the C3x is @math{2^23 + 1} (but who iterates loops more than
+@math{2^23} times on the C3x?).  Note that GCC will try to reverse a loop so
 that it can utilise the decrement and branch instruction, but will give
 up if there is more than one memory reference in the loop.  Thus a loop
 where the loop counter is decremented can generate slightly more
@@ -8363,9 +8371,9 @@ instruction, it is disabled by default.
 @opindex mloop-unsigned
 @opindex mno-loop-unsigned
 The maximum iteration count when using RPTS and RPTB (and DB on the C40)
-is 2^31 + 1 since these instructions test if the iteration count is
+is @math{2^31 + 1} since these instructions test if the iteration count is
 negative to terminate the loop.  If the iteration count is unsigned
-there is a possibility than the 2^31 + 1 maximum iteration count may be
+there is a possibility than the @math{2^31 + 1} maximum iteration count may be
 exceeded.  This switch allows an unsigned iteration count.
 
 @item -mti
@@ -8681,7 +8689,7 @@ Output instruction sizes to the asm file.
 @item -minit-stack=@var{N}
 @opindex minit-stack
 Specify the initial stack address, which may be a symbol or numeric value,
-__stack is the default.
+@samp{__stack} is the default.
 
 @item -mno-interrupts
 @opindex mno-interrupts
diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index 3d4d2b1..06c8e3f 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -79,7 +79,7 @@ If a @code{define_insn} is used, the template given is inserted into the
 insn list.  If a @code{define_expand} is used, one of three things
 happens, based on the condition logic.  The condition logic may manually
 create new insns for the insn list, say via @code{emit_insn()}, and
-invoke DONE@.  For certain named patterns, it may invoke FAIL to tell the
+invoke @code{DONE}.  For certain named patterns, it may invoke @code{FAIL} to tell the
 compiler to use an alternate way of performing that task.  If it invokes
 neither @code{DONE} nor @code{FAIL}, the template given in the pattern
 is inserted, as if the @code{define_expand} were a @code{define_insn}.
@@ -1632,7 +1632,7 @@ Constant in range 0 to 63 (for 64-bit shifts)
 Constant in range 0 to 255 (for @code{out} instruction)
 
 @item Z
-Constant in range 0 to 0xffffffff or symbolic reference known to fit specified range.
+Constant in range 0 to @code{0xffffffff} or symbolic reference known to fit specified range.
 (for using immediates in zero extending 32-bit to 64-bit x86-64 instructions)
 
 @item e
@@ -3827,7 +3827,7 @@ from i386.md:
 @end smallexample
 
 In this case, the actual split condition will be
-"TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed."
+@samp{TARGET_ZERO_EXTEND_WITH_AND && !optimize_size && reload_completed}.
 
 The @code{define_insn_and_split} construction provides exactly the same
 functionality as two separate @code{define_insn} and @code{define_split}
diff --git a/gcc/doc/rtl.texi b/gcc/doc/rtl.texi
index 618322a..922828f 100644
--- a/gcc/doc/rtl.texi
+++ b/gcc/doc/rtl.texi
@@ -1793,7 +1793,7 @@ are filled to an entire word with zeros instead of by sign-extension.
 @section Vector Operations
 @cindex vector operations
 
-All normal rtl expressions can be used with vector modes; they are
+All normal RTL expressions can be used with vector modes; they are
 interpreted as operating on each part of the vector independently.
 Additionally, there are a few new expressions to describe specific vector
 operations.
@@ -2360,7 +2360,8 @@ where @var{z} is an index register and @var{i} is a constant.
 Here is an example of its use:
 
 @example
-(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42) (reg:SI 48))))
+(mem:SF (post_modify:SI (reg:SI 42) (plus (reg:SI 42)
+                                          (reg:SI 48))))
 @end example
 
 This says to modify pseudo register 42 by adding the contents of pseudo
diff --git a/gcc/doc/tm.texi b/gcc/doc/tm.texi
index 81aa6b9..7a1d8bc 100644
--- a/gcc/doc/tm.texi
+++ b/gcc/doc/tm.texi
@@ -376,7 +376,7 @@ the effect you need.
 
 @findex LINK_ELIMINATE_DUPLICATE_LDIRECTORIES
 @item LINK_ELIMINATE_DUPLICATE_LDIRECTORIES
-A nonzero value causes collect2 to remove duplicate -L<directory> search
+A nonzero value causes collect2 to remove duplicate @option{-L@var{directory}} search
 directories from linking commands.  Do not give it a nonzero value if
 removing duplicate search directories changes the linker's semantics.
 
@@ -804,7 +804,7 @@ RTX to hold the register containing the function's return address.  This
 RTX can then be used to implement the @code{__builtin_return_address}
 function, for level 0.
 
-Note - earlier implementations of GCC used a single data area to hold
+Note---earlier implementations of GCC used a single data area to hold
 all of the per-function information.  Thus when processing of a nested
 function began the old per-function data had to be pushed onto a
 stack, and when the processing was finished, it had to be popped off the
@@ -886,9 +886,9 @@ macro need not be a constant.
 
 @findex LIBGCC2_WORDS_BIG_ENDIAN
 @item LIBGCC2_WORDS_BIG_ENDIAN
-Define this macro if WORDS_BIG_ENDIAN is not constant.  This must be a
-constant value with the same meaning as WORDS_BIG_ENDIAN, which will be
-used only when compiling libgcc2.c.  Typically the value will be set
+Define this macro if @code{WORDS_BIG_ENDIAN} is not constant.  This must be a
+constant value with the same meaning as @code{WORDS_BIG_ENDIAN}, which will be
+used only when compiling @file{libgcc2.c}.  Typically the value will be set
 based on preprocessor defines.
 
 @findex FLOAT_WORDS_BIG_ENDIAN
@@ -996,15 +996,15 @@ size of an integer.
 Define this macro if there is a guaranteed alignment for the stack
 pointer on this machine.  The definition is a C expression
 for the desired alignment (measured in bits).  This value is used as a
-default if PREFERRED_STACK_BOUNDARY is not defined.
+default if @code{PREFERRED_STACK_BOUNDARY} is not defined.
 
 @findex PREFERRED_STACK_BOUNDARY
 @item PREFERRED_STACK_BOUNDARY
 Define this macro if you wish to preserve a certain alignment for
 the stack pointer.  The definition is a C expression
-for the desired alignment (measured in bits).  If STACK_BOUNDARY is
+for the desired alignment (measured in bits).  If @code{STACK_BOUNDARY} is
 also defined, this macro must evaluate to a value equal to or larger
-than STACK_BOUNDARY@.
+than @code{STACK_BOUNDARY}.
 
 @cindex @code{PUSH_ROUNDING}, interaction with @code{PREFERRED_STACK_BOUNDARY}
 If @code{PUSH_ROUNDING} is not defined, the stack will always be aligned
@@ -1925,7 +1925,7 @@ The byte offset.
 @item YMODE
 The mode of a top level SUBREG (or what may become one).
 @end table
-The default function can be found in rtlanal.c, function
+The default function can be found in @file{rtlanal.c}, function
 @code{subreg_regno_offset}.  Normally this does not need to be defined.
 @end table
 
@@ -2628,7 +2628,7 @@ You only need to define this macro if you want to support call frame
 debugging information like that provided by DWARF 2.
 
 If this RTL is a @code{REG}, you should also define
-DWARF_FRAME_RETURN_COLUMN to @code{DWARF_FRAME_REGNUM (REGNO)}.
+@code{DWARF_FRAME_RETURN_COLUMN} to @code{DWARF_FRAME_REGNUM (REGNO)}.
 
 @findex INCOMING_FRAME_SP_OFFSET
 @item INCOMING_FRAME_SP_OFFSET
@@ -2708,14 +2708,14 @@ If you want to support call frame exception handling, you must
 define either this macro or the @code{eh_return} instruction pattern.
 
 @findex ASM_PREFERRED_EH_DATA_FORMAT
-@item ASM_PREFERRED_EH_DATA_FORMAT(@var{CODE}, @var{GLOBAL})
+@item ASM_PREFERRED_EH_DATA_FORMAT(@var{code}, @var{global})
 This macro chooses the encoding of pointers embedded in the exception
 handling sections.  If at all possible, this should be defined such
 that the exception handling section will not require dynamic relocations,
 and so may be read-only.
 
-@var{CODE} is 0 for data, 1 for code labels, 2 for function pointers.
-@var{GLOBAL} is true if the symbol may be affected by dynamic relocations.
+@var{code} is 0 for data, 1 for code labels, 2 for function pointers.
+@var{global} is true if the symbol may be affected by dynamic relocations.
 The macro should return a combination of the @code{DW_EH_PE_*} defines
 as found in @file{dwarf2.h}.
 
@@ -2723,15 +2723,15 @@ If this macro is not defined, pointers will not be encoded but
 represented directly.
 
 @findex ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX
-@item ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX(@var{FILE}, @var{ENCODING}, @var{SIZE}, @var{ADDR}, @var{DONE})
+@item ASM_MAYBE_OUTPUT_ENCODED_ADDR_RTX(@var{file}, @var{encoding}, @var{size}, @var{addr}, @var{done})
 This macro allows the target to emit whatever special magic is required
 to represent the encoding chosen by @code{ASM_PREFERRED_EH_DATA_FORMAT}.
 Generic code takes care of pc-relative and indirect encodings; this must
 be defined if the target uses text-relative or data-relative encodings.
 
-This is a C statement that branches to @var{DONE} if the format was
-handled.  @var{ENCODING} is the format chosen, @var{SIZE} is the number
-of bytes that the format occupies, @var{ADDR} is the @code{SYMBOL_REF}
+This is a C statement that branches to @var{done} if the format was
+handled.  @var{encoding} is the format chosen, @var{size} is the number
+of bytes that the format occupies, @var{addr} is the @code{SYMBOL_REF}
 to be emitted.
 
 @findex SMALL_STACK
@@ -3047,7 +3047,7 @@ outgoing arguments.
 If the target machine does not have a push instruction, set it to zero.
 That directs GCC to use an alternate strategy: to
 allocate the entire argument block and then store the arguments into
-it.  When PUSH_ARGS is nonzero, PUSH_ROUNDING must be defined too.
+it.  When @code{PUSH_ARGS} is nonzero, @code{PUSH_ROUNDING} must be defined too.
 On some machines, the definition
 
 @findex PUSH_ROUNDING
@@ -3157,7 +3157,7 @@ after the function returns.
 @var{fundecl} is a C variable whose value is a tree node that describes
 the function in question.  Normally it is a node of type
 @code{FUNCTION_DECL} that describes the declaration of the function.
-From this you can obtain the DECL_MACHINE_ATTRIBUTES of the function.
+From this you can obtain the @code{DECL_MACHINE_ATTRIBUTES} of the function.
 
 @var{funtype} is a C variable whose value is a tree node that
 describes the function in question.  Normally it is a node of type
@@ -3316,7 +3316,7 @@ definition of this macro might be
 If defined, a C expression that indicates when it is the called function's
 responsibility to make a copy of arguments passed by invisible reference.
 Normally, the caller makes a copy and passes the address of the copy to the
-routine being called.  When FUNCTION_ARG_CALLEE_COPIES is defined and is
+routine being called.  When @code{FUNCTION_ARG_CALLEE_COPIES} is defined and is
 nonzero, the caller does not make a copy.  Instead, it passes a pointer to the
 ``live'' value.  The called function must not modify this value.  If it can be
 determined that the value won't be modified, it need not make a copy;
@@ -3733,7 +3733,7 @@ arguments.  But usually, on such machines, nothing else has been pushed
 yet, because the function prologue itself does all the pushing.)  This
 region is used on machines where an argument may be passed partly in
 registers and partly in memory, and, in some cases to support the
-features in @file{varargs.h} and @file{stdarg.h}.
+features in @code{<varargs.h>} and @code{<stdarg.h>}.
 
 @item
 An area of memory used to save certain registers used by the function.
@@ -3963,7 +3963,7 @@ that you know will result.
 The first word of this block is a flag which will be nonzero if the
 object module has already been initialized.  So test this word first,
 and do not call @code{__bb_init_func} if the flag is
-nonzero.  BLOCK_OR_LABEL contains a unique number which may be used to
+nonzero.  @var{labelno} contains a unique number which may be used to
 generate a label as a branch destination when @code{__bb_init_func}
 will not be called.
 
@@ -3982,14 +3982,14 @@ local_label:
 Output code to call the subroutine @code{__bb_init_trace_func}
 and pass two parameters to it.  The first parameter is the same as
 for @code{__bb_init_func}.  The second parameter is the number of the
-first basic block of the function as given by BLOCK_OR_LABEL@.  Note
+first basic block of the function as given by @var{labelno}.  Note
 that @code{__bb_init_trace_func} has to be called, even if the object
 module has been initialized already.
 
 Described in assembler language, the code to be output looks like:
 @example
 parameter1 <- LPBX0
-parameter2 <- BLOCK_OR_LABEL
+parameter2 <- @var{labelno}
 call __bb_init_trace_func
 @end example
 @end table
@@ -4024,7 +4024,7 @@ that you know will result.
 Described in assembler language, the code to be output looks like:
 
 @smallexample
-inc (LPBX2+4*BLOCKNO)
+inc (LPBX2+4*@var{blockno})
 @end smallexample
 
 @vindex __bb
@@ -4035,7 +4035,7 @@ call the function @code{__bb_trace_func}, which will increment the
 counter.
 
 @code{__bb} consists of two words.  In the first word, the current
-basic block number, as given by BLOCKNO, has to be stored.  In
+basic block number, as given by @var{blockno}, has to be stored.  In
 the second word, the address of a block allocated in the object
 module has to be stored.  The address is given by the label created
 with this statement:
@@ -4046,7 +4046,7 @@ ASM_GENERATE_INTERNAL_LABEL (@var{buffer}, "LPBX", 0);
 
 Described in assembler language, the code to be output looks like:
 @example
-move BLOCKNO -> (__bb)
+move @var{blockno} -> (__bb)
 move LPBX0 -> (__bb+4)
 call __bb_trace_func
 @end example
@@ -4151,13 +4151,13 @@ as the @code{sibcall} md pattern can not fail, or fall over to a
 @section Implementing the Varargs Macros
 @cindex varargs implementation
 
-GCC comes with an implementation of @file{varargs.h} and
-@file{stdarg.h} that work without change on machines that pass arguments
+GCC comes with an implementation of @code{<varargs.h>} and
+@code{<stdarg.h>} that work without change on machines that pass arguments
 on the stack.  Other machines require their own implementations of
 varargs, and the two machine independent header files must have
 conditionals to include it.
 
-ISO @file{stdarg.h} differs from traditional @file{varargs.h} mainly in
+ISO @code{<stdarg.h>} differs from traditional @code{<varargs.h>} mainly in
 the calling convention for @code{va_start}.  The traditional
 implementation takes just one argument, which is the variable in which
 to store the argument pointer.  The ISO implementation of
@@ -4448,12 +4448,12 @@ the instruction cache directly, you can define the following macro.
 
 @table @code
 @findex CLEAR_INSN_CACHE
-@item CLEAR_INSN_CACHE (@var{BEG}, @var{END})
+@item CLEAR_INSN_CACHE (@var{beg}, @var{end})
 If defined, expands to a C expression clearing the @emph{instruction
 cache} in the specified interval.  If it is not defined, and the macro
-INSN_CACHE_SIZE is defined, some generic code is generated to clear the
+@code{INSN_CACHE_SIZE} is defined, some generic code is generated to clear the
 cache.  The definition of this macro would typically be a series of
-@code{asm} statements.  Both @var{BEG} and @var{END} are both pointer
+@code{asm} statements.  Both @var{beg} and @var{end} are both pointer
 expressions.
 @end table
 
@@ -4831,7 +4831,7 @@ reload register instead of two by reloading a sum of two pseudo
 registers into a register.  On the other hand, for number of RISC
 processors offsets are limited so that often an intermediate address
 needs to be generated in order to address a stack slot.  By defining
-LEGITIMIZE_RELOAD_ADDRESS appropriately, the intermediate addresses
+@code{LEGITIMIZE_RELOAD_ADDRESS} appropriately, the intermediate addresses
 generated for adjacent some stack slots can be made identical, and thus
 be shared.
 
@@ -5062,7 +5062,8 @@ reversed safely.  If no expansion is specified, this macro is defined as
 follows:
 
 @smallexample
-#define REVERSE_CONDEXEC_PREDICATES_P (x, y) ((x) == reverse_condition (y))
+#define REVERSE_CONDEXEC_PREDICATES_P (x, y) \
+   ((x) == reverse_condition (y))
 @end smallexample
 
 @end table
@@ -5544,7 +5545,7 @@ unique sections.
 @findex UNIQUE_SECTION
 @item UNIQUE_SECTION (@var{decl}, @var{reloc})
 A C statement to build up a unique section name, expressed as a
-STRING_CST node, and assign it to @samp{DECL_SECTION_NAME (@var{decl})}.
+@code{STRING_CST} node, and assign it to @samp{DECL_SECTION_NAME (@var{decl})}.
 @var{reloc} indicates whether the initial value of @var{exp} requires
 link-time relocations.  If you do not define this macro, GCC will use
 the symbol name prefixed by @samp{.} as the section name.  Note - this
@@ -6020,7 +6021,7 @@ the name, and a newline.
 
 This macro controls how the assembler definitions of uninitialized global
 variables are output.  This macro exists to properly support languages like
-@code{c++} which do not have @code{common} data.  However, this macro currently
+C++ which do not have @code{common} data.  However, this macro currently
 is not defined for all targets.  If this macro and
 @code{ASM_OUTPUT_ALIGNED_BSS} are not defined then @code{ASM_OUTPUT_COMMON}
 or @code{ASM_OUTPUT_ALIGNED_COMMON} or
@@ -6335,7 +6336,7 @@ A C statement to output to the stdio stream @var{stream} assembler code
 which defines (equates) the symbol @var{name} to have the value @var{value}.
 
 @findex SET_ASM_OP
-If SET_ASM_OP is defined, a default definition is provided which is
+If @code{SET_ASM_OP} is defined, a default definition is provided which is
 correct for most systems.
 
 @findex ASM_OUTPUT_DEF_FROM_DECLS
@@ -6356,7 +6357,7 @@ and @var{low} are already known by the assembler so that the difference
 resolves into a constant.
 
 @findex SET_ASM_OP
-If SET_ASM_OP is defined, a default definition is provided which is
+If @code{SET_ASM_OP} is defined, a default definition is provided which is
 correct for most systems.
 
 @findex ASM_OUTPUT_WEAK_ALIAS
@@ -6366,7 +6367,7 @@ which defines (equates) the weak symbol @var{name} to have the value
 @var{value}.
 
 Define this macro if the target only supports weak aliases; define
-ASM_OUTPUT_DEF instead if possible.
+@code{ASM_OUTPUT_DEF} instead if possible.
 
 @findex OBJC_GEN_METHOD_LABEL
 @item OBJC_GEN_METHOD_LABEL (@var{buf}, @var{is_inst}, @var{class_name}, @var{cat_name}, @var{sel_name})
@@ -6667,13 +6668,13 @@ Define this macro to a C string constant containing the name of the
 program which lists dynamic dependencies, like @code{"ldd"} under SunOS 4.
 
 @findex PARSE_LDD_OUTPUT
-@item PARSE_LDD_OUTPUT (@var{PTR})
+@item PARSE_LDD_OUTPUT (@var{ptr})
 Define this macro to be C code that extracts filenames from the output
-of the program denoted by @code{LDD_SUFFIX}.  @var{PTR} is a variable
+of the program denoted by @code{LDD_SUFFIX}.  @var{ptr} is a variable
 of type @code{char *} that points to the beginning of a line of output
 from @code{LDD_SUFFIX}.  If the line lists a dynamic dependency, the
-code must advance @var{PTR} to the beginning of the filename on that
-line.  Otherwise, it must set @var{PTR} to @code{NULL}.
+code must advance @var{ptr} to the beginning of the filename on that
+line.  Otherwise, it must set @var{ptr} to @code{NULL}.
 
 @end table
 
@@ -6912,7 +6913,7 @@ fprintf (@var{stream}, "\t.word L%d-L%d\n",
 You must provide this macro on machines where the addresses in a
 dispatch table are relative to the table's own address.  If defined, GCC
 will also use this macro on all machines when producing PIC@.
-@var{body} is the body of the ADDR_DIFF_VEC; it is provided so that the
+@var{body} is the body of the @code{ADDR_DIFF_VEC}; it is provided so that the
 mode and flags can be read.
 
 @findex ASM_OUTPUT_ADDR_VEC_ELT
@@ -7015,12 +7016,12 @@ This macro need not be defined on most platforms.
 @findex DOESNT_NEED_UNWINDER
 @item DOESNT_NEED_UNWINDER
 A C expression that decides whether or not the current function needs to
-have a function unwinder generated for it.  See the file @code{except.c}
+have a function unwinder generated for it.  See the file @file{except.c}
 for details on when to define this, and how.
 
 @findex MASK_RETURN_ADDR
 @item MASK_RETURN_ADDR
-An rtx used to mask the return address found via RETURN_ADDR_RTX, so
+An rtx used to mask the return address found via @code{RETURN_ADDR_RTX}, so
 that it does not contain any extraneous set bits in it.
 
 @findex DWARF2_UNWIND_INFO
@@ -7033,11 +7034,11 @@ or @samp{OBJECT_FORMAT_ELF}), GCC will provide a default definition of
 1.
 
 If this macro is defined to 1, the DWARF 2 unwinder will be the default
-exception handling mechanism; otherwise, setjmp/longjmp will be used by
+exception handling mechanism; otherwise, @code{setjmp}/@code{longjmp} will be used by
 default.
 
 If this macro is defined to anything, the DWARF 2 unwinder will be used
-instead of inline unwinders and __unwind_function in the non-setjmp case.
+instead of inline unwinders and @code{__unwind_function} in the non-@code{setjmp} case.
 
 @findex DWARF_CIE_DATA_ALIGNMENT
 @item DWARF_CIE_DATA_ALIGNMENT
@@ -7060,7 +7061,7 @@ This describes commands for alignment.
 @findex LABEL_ALIGN_AFTER_BARRIER
 @item LABEL_ALIGN_AFTER_BARRIER (@var{label})
 The alignment (log base 2) to put in front of @var{label}, which follows
-a BARRIER@.
+a @code{BARRIER}.
 
 This macro need not be defined if you don't want any special alignment
 to be done at such a time.  Most machine descriptions do not currently
@@ -7081,16 +7082,16 @@ The maximum number of bytes to skip when applying
 @findex LOOP_ALIGN
 @item LOOP_ALIGN (@var{label})
 The alignment (log base 2) to put in front of @var{label}, which follows
-a NOTE_INSN_LOOP_BEG note.
+a @code{NOTE_INSN_LOOP_BEG} note.
 
 This macro need not be defined if you don't want any special alignment
 to be done at such a time.  Most machine descriptions do not currently
 define the macro.
 
 Unless it's necessary to inspect the @var{label} parameter, it is better
-to set the variable @var{align_loops} in the target's
+to set the variable @code{align_loops} in the target's
 @code{OVERRIDE_OPTIONS}.  Otherwise, you should try to honour the user's
-selection in @var{align_loops} in a @code{LOOP_ALIGN} implementation.
+selection in @code{align_loops} in a @code{LOOP_ALIGN} implementation.
 
 @findex LOOP_ALIGN_MAX_SKIP
 @item LOOP_ALIGN_MAX_SKIP
@@ -7100,13 +7101,13 @@ This works only if @code{ASM_OUTPUT_MAX_SKIP_ALIGN} is defined.
 @findex LABEL_ALIGN
 @item LABEL_ALIGN (@var{label})
 The alignment (log base 2) to put in front of @var{label}.
-If LABEL_ALIGN_AFTER_BARRIER / LOOP_ALIGN specify a different alignment,
+If @code{LABEL_ALIGN_AFTER_BARRIER} / @code{LOOP_ALIGN} specify a different alignment,
 the maximum of the specified values is used.
 
 Unless it's necessary to inspect the @var{label} parameter, it is better
-to set the variable @var{align_labels} in the target's
+to set the variable @code{align_labels} in the target's
 @code{OVERRIDE_OPTIONS}.  Otherwise, you should try to honour the user's
-selection in @var{align_labels} in a @code{LABEL_ALIGN} implementation.
+selection in @code{align_labels} in a @code{LABEL_ALIGN} implementation.
 
 @findex LABEL_ALIGN_MAX_SKIP
 @item LABEL_ALIGN_MAX_SKIP
@@ -7800,7 +7801,7 @@ the FPSCR PR bit has to be cleared, while for a double precision
 operation, this bit has to be set.  Changing the PR bit requires a general
 purpose register as a scratch register, hence these FPSCR sets have to
 be inserted before reload, i.e.@: you can't put this into instruction emitting
-or MACHINE_DEPENDENT_REORG@.
+or @code{MACHINE_DEPENDENT_REORG}.
 
 You can have multiple entities that are mode-switched, and select at run time
 which entities actually need it.  @code{OPTIMIZE_MODE_SWITCHING} should
@@ -7828,8 +7829,8 @@ switch is needed / supplied.
 @var{entity} is an integer specifying a mode-switched entity.  If
 @code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro to
 return an integer value not larger than the corresponding element in
-NUM_MODES_FOR_MODE_SWITCHING, to denote the mode that @var{entity} must
-be switched into prior to the execution of INSN@.
+@code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} must
+be switched into prior to the execution of @var{insn}.
 
 @findex NORMAL_MODE
 @item NORMAL_MODE (@var{entity})
@@ -7839,12 +7840,12 @@ mode switching.  It should evaluate to an integer, which is a mode that
 
 @findex MODE_PRIORITY_TO_MODE
 @item MODE_PRIORITY_TO_MODE (@var{entity}, @var{n})
-This macro specifies the order in which modes for ENTITY are processed.
-0 is the highest priority, NUM_MODES_FOR_MODE_SWITCHING[ENTITY] - 1 the
+This macro specifies the order in which modes for @var{entity} are processed.
+0 is the highest priority, @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the
 lowest.  The value of the macro should be an integer designating a mode
-for ENTITY@.  For any fixed @var{entity}, @code{mode_priority_to_mode}
+for @var{entity}.  For any fixed @var{entity}, @code{mode_priority_to_mode}
 (@var{entity}, @var{n}) shall be a bijection in 0 @dots{}
-@code{num_modes_for_mode_switching}[@var{entity}] @minus{} 1 .
+@code{num_modes_for_mode_switching[@var{entity}] - 1}.
 
 @findex EMIT_MODE_SET
 @item EMIT_MODE_SET (@var{entity}, @var{mode}, @var{hard_regs_live})
@@ -7885,7 +7886,7 @@ thus speeding up the compiler.  The most important predicates to include
 in the list specified by this macro are those used in the most insn
 patterns.
 
-For each predicate function named in @var{PREDICATE_CODES}, a
+For each predicate function named in @code{PREDICATE_CODES}, a
 declaration will be generated in @file{insn-codes.h}.
 
 @item SPECIAL_MODE_PREDICATES
@@ -8260,7 +8261,7 @@ other language compilers for that matter.  Thus if @code{c_lex} is going
 to be called from target-specific code, it must only be done so when
 building the C and C++ compilers.  This can be done by defining the
 variables @code{c_target_objs} and @code{cxx_target_objs} in the
-target entry in the @code{config.gcc} file.  These variables should name
+target entry in the @file{config.gcc} file.  These variables should name
 the target-specific, language-specific object file which contains the
 code that uses @code{c_lex}.  Note it will also be necessary to add a
 rule to the makefile fragment pointed to by @code{tmake_file} that shows
@@ -8298,8 +8299,8 @@ of specifically named weak labels, optionally with a value.
 @findex pragma
 @item HANDLE_PRAGMA_PACK_PUSH_POP
 Define this macro (to a value of 1) if you want to support the Win32
-style pragmas @samp{#pragma pack(push,<n>)} and @samp{#pragma
-pack(pop)}.  The pack(push,<n>) pragma specifies the maximum alignment
+style pragmas @samp{#pragma pack(push,@var{n})} and @samp{#pragma
+pack(pop)}.  The @samp{pack(push,@var{n})} pragma specifies the maximum alignment
 (in bytes) of fields within a structure, in much the same way as the
 @samp{__aligned__} and @samp{__packed__} @code{__attribute__}s do.  A
 pack value of zero resets the behaviour to the default.  Successive
@@ -8473,8 +8474,8 @@ without user intervention.  For instance, under Microsoft Windows
 symbols must be explicitly imported from shared libraries (DLLs).
 
 @findex MD_ASM_CLOBBERS
-@item MD_ASM_CLOBBERS
-A C statement that adds to @var{CLOBBERS} @code{STRING_CST} trees for
+@item MD_ASM_CLOBBERS (@var{clobbers})
+A C statement that adds to @var{clobbers} @code{STRING_CST} trees for
 any hard regs the port wishes to automatically clobber for all asms.
 
 @findex ISSUE_RATE