Patchwork [doc] Minor layout improvements for the manual

login
register
mail settings
Submitter Ralf Wildenhues
Date Sept. 21, 2010, 5:50 a.m.
Message ID <20100921055039.GA31507@gmx.de>
Download mbox | patch
Permalink /patch/65271/
State New
Headers show

Comments

Ralf Wildenhues - Sept. 21, 2010, 5:50 a.m.
[ this has gcc/doc, gcc/fortran doc, and contrib parts ]

Went though the GCC manual and fixed a few formatting issues in the PDF,
man page, and info output.  I checked each of those, plus HTML output,
with 'make info html pdf' and visually, to ensure none of them degraded.

Issues fixed:

- formatting of code, commands, and keywords in @cindex entries,
a couple of code annotations inside text,

- a couple of @deftypefn had the wrong number of arguments, leading
to strings like '()' being indexed instead of the actual function name,

- line length in PDF output; I fixed most but not all instances.
Most prominently:

- allowed @uref/@url entries to line-wrap in the PDF output.
The strategy of wrapping these in @w{...} was added in r38863,
<http://gcc.gnu.org/ml/gcc-patches/2001-01/msg00601.html>,
presumably to avoid '@/' instances in man page output, or because
texinfo and/or PDF readers were less capable at the time.  IMVHO it is
better to fix the manpage creation to cope, and to allow wrapping of
URLs: common PDF readers still infer the wrapped URL correctly (tested
xpdf, acroread), the line length is much saner, and URLs are still
copy-pasteable in info output.

- fixed a couple of false conversions in texi2pod.pl:

       -print-multi-lib
           Print the mapping from multilib directory names to compiler switches that enable
           them.  The directory name is separated from the switches by ;, and each switch
           starts with an @} instead of the @samp{-, without spaces between multiple
           switches.  This is supposed to ease shell-processing.

- page length output in PDF: a couple of tables have long lists of
@itemx which makeinfo all renders on a single page.  Adding @need
every ten lines allows TeX to insert breaks at reasonable positions,
improving the text flow (and leaving other output formats unchanged).

OK for trunk?

Thanks,
Ralf

Improve formatting of manuals.

contrib/ChangeLog:
2010-08-19  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>

	* texi2pod.pl: Replace @@ before @{ and @}, for @samp{@@}.
	Also escape characters with grave accents, to be fixed ...
	(unmunge): ... here.
	(postprocess): Also handle @/ and @acronym{...}.

gcc/ChangeLog:
2010-08-19  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>

	* doc/contrib.texi (Contributors): Allow URL to wrap in PDF
	output.
	* doc/cppopts.texi: Fix markup of index entry.
	* doc/extend.texi (Constructing Calls): Fix markup of
	__builtin_va_arg_pack and __builtin_va_arg_pack_len definition.
	(Conditionals, C++ Comments, Pragmas, Unnamed Fields, Thread-Local)
	(Vague Linkage, C++ Attributes): Fix markup of index entries and
	keywords.
	* doc/invoke.texi (Option Summary): Fix spacing.  Rewrap to
	avoid long lines.
	(C Dialect Options, C++ Dialect Options, Warning Options)
	(Debugging Options, Spec Files, Darwin Options)
	(i386 and x86-64 Options, MIPS Options)
	(RS/6000 and PowerPC Options, Code Gen Options): Fix markup of
	index entries, avoid abbreviations, allow URLs to wrap, avoid
	long lines, avoid overlong pages from long @itemx lists.
	* doc/objc.texi (Garbage Collection): Allow URLs to wrap.
	* doc/standards.texi (Standards): Likewise.
	* doc/trouble.texi (Incompatibilities): Fix markup of index
	entry.

gcc/fortran/ChangeLog:
2010-08-19  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>

	* gfortran.texi (Argument list functions): Allow URL to wrap.
	* intrinsic.texi (GETGID, GETPID, GETUID, IMAGE_INDEX)
	(IS_IOSTAT_END, IS_IOSTAT_EOR, NUM_IMAGES, THIS_IMAGE)
	(ISO_FORTRAN_ENV): Fix markup in index entries, and a couple of
	code markups in the text.
	* invoke.texi (Fortran Dialect Options)
	(Error and Warning Options, Directory Options, Code Gen Options):
	Likewise.  Remove @code inside @smallexample.
Tobias Burnus - Sept. 21, 2010, 7:04 p.m.
Ralf Wildenhues wrote:
> Went though the GCC manual and fixed a few formatting issues in the PDF,
> man page, and info output.  I checked each of those, plus HTML output,
> with 'make info html pdf' and visually, to ensure none of them degraded.

> OK for trunk?

The Fortran bits are OK (actually, I regard them as obvious). Thanks for 
the janitorial fixes.

Tobias

> gcc/fortran/ChangeLog:
> 2010-08-19  Ralf Wildenhues<Ralf.Wildenhues@gmx.de>
>
> 	* gfortran.texi (Argument list functions): Allow URL to wrap.
> 	* intrinsic.texi (GETGID, GETPID, GETUID, IMAGE_INDEX)
> 	(IS_IOSTAT_END, IS_IOSTAT_EOR, NUM_IMAGES, THIS_IMAGE)
> 	(ISO_FORTRAN_ENV): Fix markup in index entries, and a couple of
> 	code markups in the text.
> 	* invoke.texi (Fortran Dialect Options)
> 	(Error and Warning Options, Directory Options, Code Gen Options):
> 	Likewise.  Remove @code inside @smallexample.
Joseph S. Myers - Sept. 22, 2010, 7:33 p.m.
This patch is OK.

Patch

diff --git a/contrib/texi2pod.pl b/contrib/texi2pod.pl
index fcdc145..5a4bbac 100755
--- a/contrib/texi2pod.pl
+++ b/contrib/texi2pod.pl
@@ -1,6 +1,6 @@ 
 #! /usr/bin/perl -w
 
-#   Copyright (C) 1999, 2000, 2001, 2003 Free Software Foundation, Inc.
+#   Copyright (C) 1999, 2000, 2001, 2003, 2010 Free Software Foundation, Inc.
 
 # This file is part of GCC.
 
@@ -213,10 +213,12 @@  while(<$inf>) {
 
     # Now the ones that have to be replaced by special escapes
     # (which will be turned back into text by unmunge())
+    # Replace @@ before @{ and @} in order to parse @samp{@@} correctly.
     s/&/&amp;/g;
+    s/\@\@/&at;/g;
     s/\@\{/&lbrace;/g;
     s/\@\}/&rbrace;/g;
-    s/\@\@/&at;/g;
+    s/\@`\{(.)\}/&$1grave;/g;
 
     # Inside a verbatim block, handle @var, @samp and @url specially.
     if ($shift ne "") {
@@ -391,9 +393,11 @@  sub postprocess
     s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g;
     s/\@(?:samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<$1>/g;
     s/\@sc\{([^\}]*)\}/\U$1/g;
+    s/\@acronym\{([^\}]*)\}/\U$1/g;
     s/\@file\{([^\}]*)\}/F<$1>/g;
     s/\@w\{([^\}]*)\}/S<$1>/g;
     s/\@(?:dmn|math)\{([^\}]*)\}/$1/g;
+    s/\@\///g;
 
     # keep references of the form @ref{...}, print them bold
     s/\@(?:ref)\{([^\}]*)\}/B<$1>/g;
@@ -462,6 +466,7 @@  sub unmunge
     # Replace escaped symbols with their equivalents.
     local $_ = $_[0];
 
+    s/&(.)grave;/E<$1grave>/g;
     s/&lt;/E<lt>/g;
     s/&gt;/E<gt>/g;
     s/&lbrace;/\{/g;
diff --git a/gcc/doc/contrib.texi b/gcc/doc/contrib.texi
index 7fe5aa4..53f113d 100644
--- a/gcc/doc/contrib.texi
+++ b/gcc/doc/contrib.texi
@@ -80,7 +80,7 @@  Janne Blomqvist for contributions to GNU Fortran.
 Segher Boessenkool for various fixes.
 
 @item
-Hans-J. Boehm for his @uref{http://www.hpl.hp.com/personal/Hans_Boehm/gc/,,
+Hans-J. Boehm for his @uref{http://www.hpl.hp.com/@/personal/@/Hans_Boehm/@/gc/,,
 garbage collector}, IA-64 libffi port, and other Java work.
 
 @item
diff --git a/gcc/doc/cppopts.texi b/gcc/doc/cppopts.texi
index 80a9df8..57624ed 100644
--- a/gcc/doc/cppopts.texi
+++ b/gcc/doc/cppopts.texi
@@ -188,8 +188,8 @@  without @samp{-pedantic} but treats as warnings.
 
 @item -M
 @opindex M
-@cindex make
-@cindex dependencies, make
+@cindex @command{make}
+@cindex dependencies, @command{make}
 Instead of outputting the result of preprocessing, output a rule
 suitable for @command{make} describing the dependencies of the main
 source file.  The preprocessor outputs one @command{make} rule containing
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 4f2cc07..d737617 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -568,7 +568,7 @@  the containing function.  You should specify, for @var{result}, a value
 returned by @code{__builtin_apply}.
 @end deftypefn
 
-@deftypefn {Built-in Function} __builtin_va_arg_pack ()
+@deftypefn {Built-in Function} {} __builtin_va_arg_pack ()
 This built-in function represents all anonymous arguments of an inline
 function.  It can be used only in inline functions which will be always
 inlined, never compiled as a separate function, such as those using
@@ -594,7 +594,7 @@  myprintf (FILE *f, const char *format, ...)
 @end smallexample
 @end deftypefn
 
-@deftypefn {Built-in Function} __builtin_va_arg_pack_len ()
+@deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len ()
 This built-in function returns the number of anonymous arguments of
 an inline function.  It can be used only in inline functions which
 will be always inlined, never compiled as a separate function, such
@@ -796,8 +796,8 @@  This example is perfectly equivalent to
 x ? x : y
 @end smallexample
 
-@cindex side effect in ?:
-@cindex ?: side effect
+@cindex side effect in @code{?:}
+@cindex @code{?:} side effect
 @noindent
 In this simple case, the ability to omit the middle operand is not
 especially useful.  When it becomes useful is when the first operand does,
@@ -3900,7 +3900,7 @@  extension is irrelevant.
 
 @node C++ Comments
 @section C++ Style Comments
-@cindex //
+@cindex @code{//}
 @cindex C++ comments
 @cindex comments, C++ style
 
@@ -12370,7 +12370,7 @@  bit-fields.  See the Solaris man page for @code{cmn_err} for more information.
 @node Pragmas
 @section Pragmas Accepted by GCC
 @cindex pragmas
-@cindex #pragma
+@cindex @code{#pragma}
 
 GCC supports several types of pragmas, primarily in order to compile
 code originally written for other compilers.  Note that in general
@@ -12936,8 +12936,8 @@  versions earlier than 4.4.
 
 @node Unnamed Fields
 @section Unnamed struct/union fields within structs/unions
-@cindex struct
-@cindex union
+@cindex @code{struct}
+@cindex @code{union}
 
 As permitted by ISO C1X and for compatibility with other compilers,
 GCC allows you to define
@@ -12989,7 +12989,7 @@  previously defined structure or union type with a tag.
 @section Thread-Local Storage
 @cindex Thread-Local Storage
 @cindex @acronym{TLS}
-@cindex __thread
+@cindex @code{__thread}
 
 Thread-local storage (@acronym{TLS}) is a mechanism by which variables
 are allocated such that there is one instance of the variable per extant
@@ -13442,15 +13442,15 @@  vtable will still be emitted in every translation unit which defines it.
 Make sure that any inline virtuals are declared inline in the class
 body, even if they are not defined there.
 
-@item type_info objects
-@cindex type_info
+@item @code{type_info} objects
+@cindex @code{type_info}
 @cindex RTTI
 C++ requires information about types to be written out in order to
 implement @samp{dynamic_cast}, @samp{typeid} and exception handling.
-For polymorphic classes (classes with virtual functions), the type_info
+For polymorphic classes (classes with virtual functions), the @samp{type_info}
 object is written out along with the vtable so that @samp{dynamic_cast}
 can determine the dynamic type of a class object at runtime.  For all
-other types, we write out the type_info object when it is used: when
+other types, we write out the @samp{type_info} object when it is used: when
 applying @samp{typeid} to an expression, throwing an object, or
 referring to a type in a catch clause or exception specification.
 
@@ -13770,7 +13770,7 @@  Some attributes only make sense for C++ programs.
 
 @table @code
 @item init_priority (@var{priority})
-@cindex init_priority attribute
+@cindex @code{init_priority} attribute
 
 
 In Standard C++, objects defined at namespace scope are guaranteed to be
@@ -13795,7 +13795,7 @@  Note that the particular values of @var{priority} do not matter; only their
 relative ordering.
 
 @item java_interface
-@cindex java_interface attribute
+@cindex @code{java_interface} attribute
 
 This type attribute informs C++ that the class is a Java interface.  It may
 only be applied to classes declared within an @code{extern "Java"} block.
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 4787a90..38233b7 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -164,7 +164,7 @@  in the following sections.
 @gccoptlist{-c  -S  -E  -o @var{file}  -no-canonical-prefixes  @gol
 -pipe  -pass-exit-codes  @gol
 -x @var{language}  -v  -###  --help@r{[}=@var{class}@r{[},@dots{}@r{]]}  --target-help  @gol
---version -wrapper@@@var{file} -fplugin=@var{file} -fplugin-arg-@var{name}=@var{arg}  @gol
+--version -wrapper @@@var{file} -fplugin=@var{file} -fplugin-arg-@var{name}=@var{arg}  @gol
 -fdump-ada-spec@r{[}-slim@r{]}}
 
 @item C Language Options
@@ -263,9 +263,9 @@  Objective-C and Objective-C++ Dialects}.
 -Wsystem-headers  -Wtrampolines  -Wtrigraphs  -Wtype-limits  -Wundef @gol
 -Wuninitialized  -Wunknown-pragmas  -Wno-pragmas @gol
 -Wunsuffixed-float-constants  -Wunused  -Wunused-function @gol
--Wunused-label  -Wunused-parameter -Wno-unused-result -Wunused-value  -Wunused-variable @gol
--Wunused-but-set-parameter -Wunused-but-set-variable -Wvariadic-macros -Wvla @gol
--Wvolatile-register-var  -Wwrite-strings}
+-Wunused-label  -Wunused-parameter -Wno-unused-result -Wunused-value @gol
+-Wunused-variable -Wunused-but-set-parameter -Wunused-but-set-variable @gol
+-Wvariadic-macros -Wvla -Wvolatile-register-var  -Wwrite-strings}
 
 @item C and Objective-C-only Warning Options
 @gccoptlist{-Wbad-function-cast  -Wmissing-declarations @gol
@@ -330,13 +330,13 @@  Objective-C and Objective-C++ Dialects}.
 
 @item Optimization Options
 @xref{Optimize Options,,Options that Control Optimization}.
-@gccoptlist{
--falign-functions[=@var{n}] -falign-jumps[=@var{n}] @gol
+@gccoptlist{-falign-functions[=@var{n}] -falign-jumps[=@var{n}] @gol
 -falign-labels[=@var{n}] -falign-loops[=@var{n}] -fassociative-math @gol
 -fauto-inc-dec -fbranch-probabilities -fbranch-target-load-optimize @gol
 -fbranch-target-load-optimize2 -fbtr-bb-exclusive -fcaller-saves @gol
 -fcheck-data-deps -fconserve-stack -fcprop-registers -fcrossjumping @gol
--fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules -fcx-limited-range @gol
+-fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules @gol
+-fcx-limited-range @gol
 -fdata-sections -fdce -fdce @gol
 -fdelayed-branch -fdelete-null-pointer-checks -fdse -fdse @gol
 -fearly-inlining -fipa-sra -fexpensive-optimizations -ffast-math @gol
@@ -345,24 +345,26 @@  Objective-C and Objective-C++ Dialects}.
 -fgcse -fgcse-after-reload -fgcse-las -fgcse-lm -fgraphite-identity @gol
 -fgcse-sm -fif-conversion -fif-conversion2 -findirect-inlining @gol
 -finline-functions -finline-functions-called-once -finline-limit=@var{n} @gol
--finline-small-functions -fipa-cp -fipa-cp-clone -fipa-matrix-reorg -fipa-pta @gol
--fipa-profile -fipa-pure-const -fipa-reference -fipa-struct-reorg @gol
--fira-algorithm=@var{algorithm} @gol
+-finline-small-functions -fipa-cp -fipa-cp-clone -fipa-matrix-reorg @gol
+-fipa-pta -fipa-profile -fipa-pure-const -fipa-reference @gol
+-fipa-struct-reorg -fira-algorithm=@var{algorithm} @gol
 -fira-region=@var{region} -fira-coalesce @gol
 -fira-loop-pressure -fno-ira-share-save-slots @gol
 -fno-ira-share-spill-slots -fira-verbose=@var{n} @gol
 -fivopts -fkeep-inline-functions -fkeep-static-consts @gol
 -floop-block -floop-interchange -floop-strip-mine @gol
--floop-parallelize-all -flto -flto-compression-level -flto-report -fltrans @gol
--fltrans-output-list -fmerge-all-constants -fmerge-constants -fmodulo-sched @gol
--fmodulo-sched-allow-regmoves -fmove-loop-invariants -fmudflap @gol
--fmudflapir -fmudflapth -fno-branch-count-reg -fno-default-inline @gol
+-floop-parallelize-all -flto -flto-compression-level -flto-report @gol
+-fltrans -fltrans-output-list -fmerge-all-constants -fmerge-constants @gol
+-fmodulo-sched -fmodulo-sched-allow-regmoves -fmove-loop-invariants @gol
+-fmudflap -fmudflapir -fmudflapth -fno-branch-count-reg @gol
+-fno-default-inline @gol
 -fno-defer-pop -fno-function-cse -fno-guess-branch-probability @gol
 -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
 -fno-sched-interblock -fno-sched-spec -fno-signed-zeros @gol
 -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
 -fomit-frame-pointer -foptimize-register-move -foptimize-sibling-calls @gol
--fpartial-inlining -fpeel-loops -fpredictive-commoning -fprefetch-loop-arrays @gol
+-fpartial-inlining -fpeel-loops -fpredictive-commoning @gol
+-fprefetch-loop-arrays @gol
 -fprofile-correction -fprofile-dir=@var{path} -fprofile-generate @gol
 -fprofile-generate=@var{path} @gol
 -fprofile-use -fprofile-use=@var{path} -fprofile-values @gol
@@ -380,7 +382,8 @@  Objective-C and Objective-C++ Dialects}.
 -fsel-sched-pipelining -fsel-sched-pipelining-outer-loops @gol
 -fsignaling-nans -fsingle-precision-constant -fsplit-ivs-in-unroller @gol
 -fsplit-wide-types -fstack-protector -fstack-protector-all @gol
--fstrict-aliasing -fstrict-overflow -fthread-jumps -ftracer -ftree-bit-ccp @gol
+-fstrict-aliasing -fstrict-overflow -fthread-jumps -ftracer @gol
+-ftree-bit-ccp @gol
 -ftree-builtin-call-dce -ftree-ccp -ftree-ch -ftree-copy-prop @gol
 -ftree-copyrename -ftree-dce -ftree-dominator-opts -ftree-dse @gol
 -ftree-forwprop -ftree-fre -ftree-loop-if-convert @gol
@@ -589,7 +592,7 @@  Objective-C and Objective-C++ Dialects}.
 -mno-fp-ret-in-387  -msoft-float @gol
 -mno-wide-multiply  -mrtd  -malign-double @gol
 -mpreferred-stack-boundary=@var{num}
--mincoming-stack-boundary=@var{num}
+-mincoming-stack-boundary=@var{num} @gol
 -mcld -mcx16 -msahf -mmovbe -mcrc32 -mrecip @gol
 -mmmx  -msse  -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -msse4 -mavx @gol
 -maes -mpclmul -mfsgsbase -mrdrnd -mf16c -mfused-madd @gol
@@ -736,7 +739,7 @@  Objective-C and Objective-C++ Dialects}.
 -msplit  -mno-split  -munix-asm  -mdec-asm}
 
 @emph{picoChip Options}
-@gccoptlist{-mae=@var{ae_type} -mvliw-lookahead=@var{N}
+@gccoptlist{-mae=@var{ae_type} -mvliw-lookahead=@var{N} @gol
 -msymbol-as-address -mno-inefficient-warnings}
 
 @emph{PowerPC Options}
@@ -889,8 +892,8 @@  See i386 and x86-64 Options.
 
 @emph{i386 and x86-64 Windows Options}
 @gccoptlist{-mconsole -mcygwin -mno-cygwin -mdll
--mnop-fun-dllimport -mthread -municode -mwin32 -mwindows
--fno-set-stack-executable}
+-mnop-fun-dllimport -mthread @gol
+-municode -mwin32 -mwindows -fno-set-stack-executable}
 
 @emph{Xstormy16 Options}
 @gccoptlist{-msim}
@@ -1659,7 +1662,7 @@  freestanding and hosted environments.
 
 @item -fopenmp
 @opindex fopenmp
-@cindex openmp parallel
+@cindex OpenMP parallel
 Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
 @code{!$omp} in Fortran.  When @option{-fopenmp} is specified, the
 compiler generates parallel code according to the OpenMP Application
@@ -2400,8 +2403,8 @@  less vulnerable to unintended effects and much easier to search for.
 @item -Woverloaded-virtual @r{(C++ and Objective-C++ only)}
 @opindex Woverloaded-virtual
 @opindex Wno-overloaded-virtual
-@cindex overloaded virtual fn, warning
-@cindex warning for overloaded virtual fn
+@cindex overloaded virtual function, warning
+@cindex warning for overloaded virtual function
 Warn when a function declaration hides virtual functions from a
 base class.  For example, in:
 
@@ -3348,7 +3351,7 @@  The 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 the GCC readings page, at
-@w{@uref{http://gcc.gnu.org/readings.html}}.
+@uref{http://gcc.gnu.org/@/readings.html}.
 
 This warning is enabled by @option{-Wall} for C and C++.
 
@@ -4759,7 +4762,7 @@  This option is a detailed version of
 @option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
 which will serve for most needs.
 
-A specification has the syntax
+A specification has the syntax@*
 [@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
 
 The optional first word limits the specification to
@@ -9316,17 +9319,17 @@  appear here are:
 
 @table @code
 @item %include <@var{file}>
-@cindex %include
+@cindex @code{%include}
 Search for @var{file} and insert its text at the current point in the
 specs file.
 
 @item %include_noerr <@var{file}>
-@cindex %include_noerr
+@cindex @code{%include_noerr}
 Just like @samp{%include}, but do not generate an error message if the include
 file cannot be found.
 
 @item %rename @var{old_name} @var{new_name}
-@cindex %rename
+@cindex @code{%rename}
 Rename the spec string @var{old_name} to @var{new_name}.
 
 @end table
@@ -10892,6 +10895,7 @@  one controlled by the @option{-mcpu} or @option{-march} option.
 @itemx -dynamic
 @itemx -exported_symbols_list
 @itemx -filelist
+@need 800
 @itemx -flat_namespace
 @itemx -force_flat_namespace
 @itemx -headerpad_max_install_names
@@ -10902,6 +10906,7 @@  one controlled by the @option{-mcpu} or @option{-march} option.
 @itemx -multi_module
 @itemx -multiply_defined
 @itemx -multiply_defined_unused
+@need 800
 @itemx -noall_load
 @itemx -no_dead_strip_inits_and_terms
 @itemx -nofixprebinding
@@ -10912,6 +10917,7 @@  one controlled by the @option{-mcpu} or @option{-march} option.
 @itemx -prebind
 @itemx -prebind_all_twolevel_modules
 @itemx -private_bundle
+@need 800
 @itemx -read_only_relocs
 @itemx -sectalign
 @itemx -sectobjectsymbols
@@ -10922,6 +10928,7 @@  one controlled by the @option{-mcpu} or @option{-march} option.
 @itemx -sectorder
 @itemx -segaddr
 @itemx -segs_read_only_addr
+@need 800
 @itemx -segs_read_write_addr
 @itemx -seg_addr_table
 @itemx -seg_addr_table_filename
@@ -10932,6 +10939,7 @@  one controlled by the @option{-mcpu} or @option{-march} option.
 @itemx -single_module
 @itemx -static
 @itemx -sub_library
+@need 800
 @itemx -sub_umbrella
 @itemx -twolevel_namespace
 @itemx -umbrella
@@ -12012,7 +12020,7 @@  for the ABI and the set of available instructions.  The choices for
 @var{cpu-type} are:
 @table @emph
 @item generic
-Produce code optimized for the most common IA32/AMD64/EM64T processors.
+Produce code optimized for the most common IA32/@/AMD64/@/EM64T processors.
 If you know the CPU on which your code will run, then you should use
 the corresponding @option{-mtune} option instead of
 @option{-mtune=generic}.  But, if you do not know exactly what CPU users
@@ -12390,6 +12398,7 @@  preferred alignment to @option{-mpreferred-stack-boundary=2}.
 @itemx -mssse3
 @itemx -mno-ssse3
 @itemx -msse4.1
+@need 800
 @itemx -mno-sse4.1
 @itemx -msse4.2
 @itemx -mno-sse4.2
@@ -12400,6 +12409,7 @@  preferred alignment to @option{-mpreferred-stack-boundary=2}.
 @itemx -maes
 @itemx -mno-aes
 @itemx -mpclmul
+@need 800
 @itemx -mno-pclmul
 @itemx -mfsgsbase
 @itemx -mno-fsgsbase
@@ -12410,6 +12420,7 @@  preferred alignment to @option{-mpreferred-stack-boundary=2}.
 @itemx -msse4a
 @itemx -mno-sse4a
 @itemx -mfma4
+@need 800
 @itemx -mno-fma4
 @itemx -mxop
 @itemx -mno-xop
@@ -14042,7 +14053,7 @@  generates 64-bit code when you select a 64-bit architecture, but you
 can use @option{-mgp32} to get 32-bit code instead.
 
 For information about the O64 ABI, see
-@w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
+@uref{http://gcc.gnu.org/@/projects/@/mipso64-abi.html}.
 
 GCC supports a variant of the o32 ABI in which floating-point registers
 are 64 rather than 32 bits wide.  You can select this combination with
@@ -15010,6 +15021,7 @@  These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
 @itemx -mno-powerpc-gpopt
 @itemx -mpowerpc-gfxopt
 @itemx -mno-powerpc-gfxopt
+@need 800
 @itemx -mpowerpc64
 @itemx -mno-powerpc64
 @itemx -mmfcrf
@@ -15020,6 +15032,7 @@  These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
 @itemx -mno-popcntd
 @itemx -mfprnd
 @itemx -mno-fprnd
+@need 800
 @itemx -mcmpb
 @itemx -mno-cmpb
 @itemx -mmfpgpr
@@ -17837,8 +17850,13 @@  that function is not instrumented.  The match is done on substrings:
 if the @var{file} parameter is a substring of the file name, it is
 considered to be a match.
 
-For example,
-@code{-finstrument-functions-exclude-file-list=/bits/stl,include/sys}
+For example:
+
+@smallexample
+-finstrument-functions-exclude-file-list=/bits/stl,include/sys
+@end smallexample
+
+@noindent
 will exclude any inline function defined in files whose pathnames
 contain @code{/bits/stl} or @code{include/sys}.
 
@@ -18002,7 +18020,7 @@  visibility so that the @samp{type_info} nodes will be unified between
 the DSOs.
 
 An overview of these techniques, their benefits and how to use them
-is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
+is at @uref{http://gcc.gnu.org/@/wiki/@/Visibility}.
 
 @item -fstrict-volatile-bitfields
 This option should be used if accesses to volatile bitfields (or other
diff --git a/gcc/doc/objc.texi b/gcc/doc/objc.texi
index c15c1ac..43da303 100644
--- a/gcc/doc/objc.texi
+++ b/gcc/doc/objc.texi
@@ -317,7 +317,7 @@  argument types.
 Support for a new memory management policy has been added by using a
 powerful conservative garbage collector, known as the
 Boehm-Demers-Weiser conservative garbage collector.  It is available from
-@w{@uref{http://www.hpl.hp.com/personal/Hans_Boehm/gc/}}.
+@uref{http://www.hpl.hp.com/@/personal/@/Hans_Boehm/@/gc/}.
 
 To enable the support for it you have to configure the compiler using an
 additional argument, @w{@option{--enable-objc-gc}}.  You need to have
diff --git a/gcc/doc/standards.texi b/gcc/doc/standards.texi
index 38072df..67753db 100644
--- a/gcc/doc/standards.texi
+++ b/gcc/doc/standards.texi
@@ -188,9 +188,9 @@  changes to the C++ language, some of which have been implemented in an
 experimental C++0x mode in GCC@. The C++0x mode in GCC tracks the draft
 working paper for the C++0x standard; the latest working paper is
 available on the ISO C++ committee's web site at
-@uref{http://www.open-std.org/jtc1/sc22/wg21/}. For information
+@uref{http://www.open-std.org/@/jtc1/@/sc22/@/wg21/}. For information
 regarding the C++0x features available in the experimental C++0x mode,
-see @uref{http://gcc.gnu.org/projects/cxx0x.html}. To select this
+see @uref{http://gcc.gnu.org/projects/@/cxx0x.html}. To select this
 standard in GCC, use the option @option{-std=c++0x}; to obtain all the
 diagnostics required by the standard, you should also specify
 @option{-pedantic} (or @option{-pedantic-errors} if you want them to be
@@ -214,7 +214,7 @@  Objective-C Language'', available at a number of web sites:
 
 @itemize
 @item
-@uref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/ObjectiveC/}
+@uref{http://developer.apple.com/@/mac/@/library/@/documentation/@/Cocoa/@/Conceptual/@/ObjectiveC/}
 is a recent (and periodically updated) version;
 @item
 @uref{http://objc.toodarkpark.net}
diff --git a/gcc/doc/trouble.texi b/gcc/doc/trouble.texi
index 703f2ed..03e3993 100644
--- a/gcc/doc/trouble.texi
+++ b/gcc/doc/trouble.texi
@@ -385,7 +385,7 @@  such as @samp{+=}.  GCC, following the ISO standard, does not
 allow this.
 
 @cindex apostrophes
-@cindex '
+@cindex @code{'}
 @item
 GCC complains about unterminated character constants inside of
 preprocessing conditionals that fail.  Some programs have English
diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi
index 10492f0..d7e656f 100644
--- a/gcc/fortran/gfortran.texi
+++ b/gcc/fortran/gfortran.texi
@@ -1685,7 +1685,7 @@  C
 @end smallexample
 
 For details refer to the g77 manual
-@uref{http://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/index.html#Top}.
+@uref{http://gcc.gnu.org/@/onlinedocs/@/gcc-3.4.6/@/g77/@/index.html#Top}.
 
 Also, @code{c_by_val.f} and its partner @code{c_by_val.c} of the
 GNU Fortran testsuite are worth a look.
diff --git a/gcc/fortran/intrinsic.texi b/gcc/fortran/intrinsic.texi
index d2b3b94..030ff63 100644
--- a/gcc/fortran/intrinsic.texi
+++ b/gcc/fortran/intrinsic.texi
@@ -5464,7 +5464,7 @@  END PROGRAM
 @node GETGID
 @section @code{GETGID} --- Group ID function
 @fnindex GETGID
-@cindex system, group id
+@cindex system, group ID
 
 @table @asis
 @item @emph{Description}:
@@ -5541,8 +5541,8 @@  END PROGRAM
 @node GETPID
 @section @code{GETPID} --- Process ID function
 @fnindex GETPID
-@cindex system, process id
-@cindex process id
+@cindex system, process ID
+@cindex process ID
 
 @table @asis
 @item @emph{Description}:
@@ -5580,7 +5580,7 @@  end program info
 @node GETUID
 @section @code{GETUID} --- User ID function
 @fnindex GETUID
-@cindex system, user id
+@cindex system, user ID
 @cindex user id
 
 @table @asis
@@ -6351,7 +6351,7 @@  kind.
 @node IMAGE_INDEX
 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
 @fnindex IMAGE_INDEX
-@cindex coarray, IMAGE_INDEX
+@cindex coarray, @code{IMAGE_INDEX}
 @cindex images, cosubscript to image index conversion
 
 @table @asis
@@ -6734,7 +6734,7 @@  end program test_irand
 @node IS_IOSTAT_END
 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
 @fnindex IS_IOSTAT_END
-@cindex IOSTAT, end of file
+@cindex @code{IOSTAT}, end of file
 
 @table @asis
 @item @emph{Description}:
@@ -6760,7 +6760,7 @@  Elemental function
 @item @emph{Return value}:
 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
 @var{I} has the value which indicates an end of file condition for
-IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
+@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
 
 @item @emph{Example}:
 @smallexample
@@ -6779,7 +6779,7 @@  END PROGRAM
 @node IS_IOSTAT_EOR
 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
 @fnindex IS_IOSTAT_EOR
-@cindex IOSTAT, end of record
+@cindex @code{IOSTAT}, end of record
 
 @table @asis
 @item @emph{Description}:
@@ -6805,7 +6805,7 @@  Elemental function
 @item @emph{Return value}:
 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
 @var{I} has the value which indicates an end of file condition for
-IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
+@code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
 
 @item @emph{Example}:
 @smallexample
@@ -9238,7 +9238,7 @@  REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
 @node NUM_IMAGES
 @section @code{NUM_IMAGES} --- Function that returns the number of images
 @fnindex NUM_IMAGES
-@cindex coarray, NUM_IMAGES
+@cindex coarray, @code{NUM_IMAGES}
 @cindex images, number of
 
 @table @asis
@@ -11868,7 +11868,7 @@  end program test_tanh
 @node THIS_IMAGE
 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
 @fnindex THIS_IMAGE
-@cindex coarray, THIS_IMAGE
+@cindex coarray, @code{THIS_IMAGE}
 @cindex images, index of this image
 
 @table @asis
@@ -12625,16 +12625,16 @@  size of 16, 32, and 64 bits. It is negative if a target platform
 does not support the particular kind. (Fortran 2008 or later.)
 
 @item @code{IOSTAT_END}:
-The value assigned to the variable passed to the IOSTAT= specifier of
+The value assigned to the variable passed to the @code{IOSTAT=} specifier of
 an input/output statement if an end-of-file condition occurred.
 
 @item @code{IOSTAT_EOR}:
-The value assigned to the variable passed to the IOSTAT= specifier of
+The value assigned to the variable passed to the @code{IOSTAT=} specifier of
 an input/output statement if an end-of-record condition occurred.
 
 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
 Scalar default-integer constant, used by @code{INQUIRE} for the
-IOSTAT= specifier to denote an that a unit number identifies an
+@code{IOSTAT=} specifier to denote an that a unit number identifies an
 internal unit. (Fortran 2008 or later.)
 
 @item @code{NUMERIC_STORAGE_SIZE}:
diff --git a/gcc/fortran/invoke.texi b/gcc/fortran/invoke.texi
index 1dfd3bd..9e2bc75 100644
--- a/gcc/fortran/invoke.texi
+++ b/gcc/fortran/invoke.texi
@@ -253,7 +253,7 @@  the default width of @code{DOUBLE PRECISION} to 16 bytes if possible, unless
 
 @item -fdollar-ok
 @opindex @code{fdollar-ok}
-@cindex $
+@cindex @code{$}
 @cindex symbol names
 @cindex character set
 Allow @samp{$} as a valid non-first character in a symbol name. Symbols 
@@ -717,7 +717,7 @@  The following example will trigger the warning.
 @item -Wampersand
 @opindex @code{Wampersand}
 @cindex warnings, ampersand
-@cindex &
+@cindex @code{&}
 Warn about missing ampersand in continued character constants. The warning is
 given with @option{-Wampersand}, @option{-pedantic}, @option{-std=f95},
 @option{-std=f2003} and @option{-std=f2008}. Note: With no ampersand
@@ -851,10 +851,10 @@  is not included in @option{-Wall} but is implied by @option{-Wall -Wextra}.
 
 @item -Walign-commons
 @opindex @code{Walign-commons}
-@cindex warnings, alignment of COMMON blocks
-@cindex alignment of COMMON blocks
+@cindex warnings, alignment of @code{COMMON} blocks
+@cindex alignment of @code{COMMON} blocks
 By default, @command{gfortran} warns about any occasion of variables being
-padded for proper alignment inside a COMMON block. This warning can be turned
+padded for proper alignment inside a @code{COMMON} block. This warning can be turned
 off via @option{-Wno-align-commons}. See also @option{-falign-commons}.
 
 @item -Werror
@@ -929,8 +929,8 @@  debugging options.
 @cindex directory, options
 @cindex options, directory search
 @cindex search path
-@cindex INCLUDE directive
-@cindex directive, INCLUDE
+@cindex @code{INCLUDE} directive
+@cindex directive, @code{INCLUDE}
 These options affect how GNU Fortran searches
 for files specified by the @code{INCLUDE} directive and where it searches
 for previously compiled modules.
@@ -1313,13 +1313,13 @@  array constructors.  The code below requires this option to expand
 the array at compile time.
 
 @smallexample
-@code{program test}
-@code{implicit none}
-@code{integer j}
-@code{integer, parameter :: n = 100000}
-@code{integer, parameter :: i(n) = (/ (2*j, j = 1, n) /)}
-@code{print '(10(I0,1X))', i}
-@code{end program test}
+program test
+implicit none
+integer j
+integer, parameter :: n = 100000
+integer, parameter :: i(n) = (/ (2*j, j = 1, n) /)
+print '(10(I0,1X))', i
+end program test
 @end smallexample
 
 @emph{Caution:  This option can lead to long compile times and excessively
@@ -1427,14 +1427,14 @@  needs to be enabled (e.g. via @option{-ffpe-trap}).
 
 @item -falign-commons
 @opindex @code{falign-commons}
-@cindex alignment of COMMON blocks
+@cindex alignment of @code{COMMON} blocks
 By default, @command{gfortran} enforces proper alignment of all variables in a
-COMMON block by padding them as needed. On certain platforms this is mandatory,
-on others it increases performance. If a COMMON block is not declared with
+@code{COMMON} block by padding them as needed. On certain platforms this is mandatory,
+on others it increases performance. If a @code{COMMON} block is not declared with
 consistent data types everywhere, this padding can cause trouble, and
-@option{-fno-align-commons } can be used to disable automatic alignment. The
-same form of this option should be used for all files that share a COMMON block.
-To avoid potential alignment issues in COMMON blocks, it is recommended to order
+@option{-fno-align-commons} can be used to disable automatic alignment. The
+same form of this option should be used for all files that share a @code{COMMON} block.
+To avoid potential alignment issues in @code{COMMON} blocks, it is recommended to order
 objects from largests to smallest.
 
 @item -fno-protect-parens
@@ -1442,8 +1442,8 @@  objects from largests to smallest.
 @cindex re-association of parenthesed expressions
 By default the parentheses in expression are honored for all optimization
 levels such that the compiler does not do any re-association. Using
-@option{-fno-protect-parens} allows the compiler to reorder REAL and
-COMPLEX expressions to produce faster code. Note that for the re-association
+@option{-fno-protect-parens} allows the compiler to reorder @code{REAL} and
+@code{COMPLEX} expressions to produce faster code. Note that for the re-association
 optimization @option{-fno-signed-zeros} and @option{-fno-trapping-math}
 need to be in effect.
 @end table