[PATCH] install.texi changes for underfull/overfull hboxes

[Janis Johnson <janis187 at us dot ibm dot com>]

This patch changes the wording in several places in the installation
instructions to get rid of messages about overfull and underfull
hboxes from "make dvi".  In most cases the original wording was fine
and changing it would have been utterly silly except that it gets rid
of the annoying warnings.

I have patches to other files to get rid of _all_but_one_ of these
messages, but will see how this patch flies before submitting them.

Tested with "make dvi" and "make info".  OK for the mainline?

2002-09-03  Janis Johnson  <janis187@us.ibm.com>

	* doc/install.texi: Fix overfull and underfull hboxes.

Index: install.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/install.texi,v
retrieving revision 1.139
diff -u -r1.139 install.texi
--- install.texi	30 Aug 2002 20:48:14 -0000	1.139
+++ install.texi	3 Sep 2002 21:31:21 -0000
@@ -147,8 +147,9 @@
 We recommend you browse the entire generic installation instructions before
 you proceed.
 
-Lists of successful builds for released versions of GCC are
-available at @uref{http://gcc.gnu.org/buildstat.html}. 
+Lists of references to messages reporting successful builds for released
+versions of GCC are available at
+@uref{http://gcc.gnu.org/buildstat.html}. 
 These lists are updated as new information becomes available.
 
 The installation procedure itself is broken into five steps.
@@ -364,8 +365,9 @@
 @table @code
 
 @item --exec-prefix=@var{dirname}
-Specify the toplevel installation directory for architecture-dependent
-files.  The default is @file{@var{prefix}}.
+Specify the toplevel installation directory for files that are
+architecture-dependent.
+The default is @file{@var{prefix}}.
 
 @item --bindir=@var{dirname}
 Specify the installation directory for the executables called by users
@@ -433,16 +435,18 @@
 @var{suffix}) are prepended (appended) before further transformations
 can happen with a special transformation script @var{pattern}.
 
-As currently implemented, this options only take effect for native
+As currently implemented, these options only take effect for native
 builds; cross compiler binaries' names are not transformed even when a
-transformation is explicitly asked for by one of this options.
+transformation is explicitly asked for by one of these options.
 
 For native builds, some of the installed programs are also installed
-with the target alias in front of their name, as in
-@samp{i686-pc-linux-gnu-gcc}. All of the above transformations happen
-before the target alias is prepended to the name - so, specifying
-@option{--program-prefix=foo-} and @option{program-suffix=-3.1}, the
-resulting binary would be installed as
+with the target alias in front of their names, as in
+@samp{i686-pc-linux-gnu-gcc}.  All of the above transformations happen
+before the target alias is prepended to the name, so specifying
+both the option
+@option{--program-prefix=foo-} and the option
+@option{--program-suffix=-3.1} causes the
+resulting binary to be installed as
 @file{/usr/local/bin/i686-pc-linux-gnu-foo-gcc-3.1}.
 
 As a last shortcoming, none of the installed Ada programs are
@@ -538,6 +542,7 @@
 @samp{libiberty} do not support shared libraries at all.
 
 Use @option{--disable-shared} to build only static libraries.  Note that
+the option
 @option{--disable-shared} does not accept a list of package names as
 argument, only @option{--enable-shared} does.
 
@@ -551,15 +556,25 @@
 assembler installed on your system, you may want to use this option in
 connection with @option{--with-as=@var{pathname}}.
 
-The systems where it makes a difference whether you use the GNU assembler are
-@samp{hppa1.0-@var{any}-@var{any}}, @samp{hppa1.1-@var{any}-@var{any}},
-@samp{i386-@var{any}-sysv}, @samp{i386-@var{any}-isc},
-@samp{i860-@var{any}-bsd}, @samp{m68k-bull-sysv},
-@samp{m68k-hp-hpux}, @samp{m68k-sony-bsd},
-@samp{m68k-altos-sysv}, @samp{m68000-hp-hpux},
-@samp{m68000-att-sysv}, @samp{@var{any}-lynx-lynxos},
-and @samp{mips-@var{any}}.
-On any other system, @option{--with-gnu-as} has no effect.
+The following systems are the only ones where it makes a difference
+whether or not you use the GNU assembler.  On any other system,
+@option{--with-gnu-as} has no effect.
+
+@itemize
+@item @samp{hppa1.0-@var{any}-@var{any}}
+@item @samp{hppa1.1-@var{any}-@var{any}}
+@item @samp{i386-@var{any}-sysv}
+@item @samp{i386-@var{any}-isc}
+@item @samp{i860-@var{any}-bsd}
+@item @samp{m68k-bull-sysv}
+@item @samp{m68k-hp-hpux}
+@item @samp{m68k-sony-bsd}
+@item @samp{m68k-altos-sysv}
+@item @samp{m68000-hp-hpux}
+@item @samp{m68000-att-sysv}
+@item @samp{@var{any}-lynx-lynxos}
+@item @samp{mips-@var{any}}
+@end itemize
 
 On the systems listed above (except for the HP-PA, for ISC on the
 386, and for @samp{mips-sgi-irix5.*}), if you use the GNU assembler,
@@ -729,7 +744,7 @@
 Specify that a user visible @command{cpp} program should not be installed.
 
 @item --with-cpp-install-dir=@var{dirname}
-Specify that the user visible @command{cpp} program should be installed
+Specify that the user-visible @command{cpp} program be installed
 in @file{@var{prefix}/@var{dirname}/cpp}, in addition to @var{bindir}.
 
 @item --enable-maintainer-mode
@@ -1002,11 +1017,15 @@
 
 If you want to save additional space during the bootstrap and in
 the final installation as well, you can build the compiler binaries
-without debugging information with @samp{make CFLAGS='-O' LIBCFLAGS='-g
--O2' LIBCXXFLAGS='-g -O2 -fno-implicit-templates' bootstrap}.  This will save
+without debugging information as in the following example.  This will save
 roughly 40% of disk space both for the bootstrap and the final installation.
 (Libraries will still contain debugging information.)
 
+@example
+     make CFLAGS='-O' LIBCFLAGS='-g -O2' \
+       LIBCXXFLAGS='-g -O2 -fno-implicit-templates' bootstrap
+@end example
+
 If you wish to use non-default GCC flags when compiling the stage2 and
 stage3 compilers, set @code{BOOT_CFLAGS} on the command line when doing
 @samp{make bootstrap}.  Non-default optimization flags are less well
@@ -1332,7 +1351,7 @@
 info format in @file{@var{infodir}} (normally @file{@var{prefix}/info}).
 
 If you built a released version of GCC using @samp{make bootstrap} then please
-quickly review the build status page for your release, available from
+review the build status page for your release, available from
 @uref{http://gcc.gnu.org/buildstat.html}.
 If your system is not listed for the version of GCC that you built,
 send a note to
@@ -1802,8 +1821,10 @@
 simplest way to do so is by providing @option{--with-as} and
 @option{--with-ld} to @file{configure}, e.g.@:
 
-@samp{configure --with-as=/opt/ctl/bin/cam --with-ld=/opt/ctl/bin/cld
---enable-languages=c}
+@example
+     configure --with-as=/opt/ctl/bin/cam --with-ld=/opt/ctl/bin/cld \
+       --enable-languages=c
+@end example
 
 The comparison test during @samp{make bootstrap} fails on Unicos/Mk
 because the assembler inserts timestamps into object files.  You should
@@ -1949,9 +1970,9 @@
 For @code{cris-axis-aout} and @code{cris-axis-elf} you need binutils 2.11
 or newer.  For @code{cris-axis-linux-gnu} you need binutils 2.12 or newer.
 
-Pre-packaged tools can be obtained from
-@uref{ftp://ftp.axis.com/pub/axis/tools/cris/compiler-kit/}.  More
-information about this platform is available at
+See @uref{ftp://ftp.axis.com/pub/axis/tools/cris/compiler-kit/}
+for binaries.
+More information about this platform is available at
 @uref{http://developer.axis.com/}.
 
 @html
@@ -2006,15 +2027,17 @@
 
 In principle, @option{--enable-threads} is now compatible with
 @option{--enable-libgcj} on FreeBSD@.  However, it has only been built
-and tested on i386-*-freebsd4.5 and alpha-*-freebsd5.0.  The static
+and tested on @samp{i386-*-freebsd4.5} and @samp{alpha-*-freebsd5.0}.
+The static
 library may be incorrectly built (symbols are missing at link time).
-There is a rare timing-based startup hang (probably involves an
-assupmtion about the thread library).  Multi-threaded boehm-gc (required for
+There is a rare timing-based startup hang (which probably involves an
+assumption about the thread library).  Multi-threaded boehm-gc (required for
 libjava) exposes severe threaded signal-handling bugs on FreeBSD before
 4.5-RELEASE.  The alpha port may not fully bootstrap without some manual
-intervention: gcjh will crash with a floating-point exception while
+intervention: @command{gcjh} will crash with a floating-point exception while
 generating @file{java/lang/Double.h} (just copy the version built on
-i386-*-freebsd* and rerun the top-level gmake with no arguments and it
+@samp{i386-*-freebsd*} and rerun the top-level @command{gmake} with no
+arguments and it
 should properly complete the bootstrap).  Other CPU architectures
 supported by FreeBSD will require additional configuration tuning in, at
 the very least, both boehm-gc and libffi.
@@ -2136,9 +2159,15 @@
 must be used if both ports are to be installed on the same system.
 
 You must use GNU binutils 2.11 or above with the 32-bit port.  Thread
-support is not currently implemented, so @option{--enable-threads} does
-not work.  See @uref{http://gcc.gnu.org/ml/gcc-prs/2002-01/msg00551.html}
-and @uref{http://gcc.gnu.org/ml/gcc-bugs/2002-01/msg00663.html}.
+support is not currently implemented, so
+the configuration option @option{--enable-threads} does
+not work.  See:
+
+@itemize
+@item @uref{http://gcc.gnu.org/ml/gcc-prs/2002-01/msg00551.html}
+@item @uref{http://gcc.gnu.org/ml/gcc-bugs/2002-01/msg00663.html}
+@end itemize
+
 GCC 2.95.x is not supported under HP-UX 11 and cannot be used to
 compile GCC 3.0 and up.  Refer to @uref{binaries.html,,binaries} for
 information about obtaining precompiled GCC binaries for HP-UX.
@@ -2324,8 +2353,10 @@
 building a cross compiler.   The easiest way to do this is with a configure
 command like this:
 
-@samp{CC=/udk/usr/ccs/bin/cc @var{/your/path/to}/gcc/configure
---host=i686-pc-udk --target=i686-pc-udk --program-prefix=udk-}
+@example
+     CC=/udk/usr/ccs/bin/cc @var{/your/path/to}/gcc/configure \
+       --host=i686-pc-udk --target=i686-pc-udk --program-prefix=udk-
+@end example
 
 @emph{You should substitute @samp{i686} in the above command with the appropriate
 processor for your host.}
@@ -2467,7 +2498,8 @@
 
 The initial assembler shipped with AIX 4.3.0 generates incorrect object
 files.  A fix for APAR IX74254 (64BIT DISASSEMBLED OUTPUT FROM COMPILER FAILS
-TO ASSEMBLE/BIND) is available from IBM Customer Support and from its
+TO ASSEMBLE/BIND) is available from IBM Customer Support.
+It is also available from its
 @uref{http://techsupport.services.ibm.com/,,techsupport.services.ibm.com}
 website as PTF U453956.  This fix is incorporated in AIX 4.3.1 and above.
 
@@ -2597,7 +2629,8 @@
 ./xgcc: Internal compiler error: program as got fatal signal 11
 @end smallexample
 
-A patched version of the assembler is available as the file
+A patched version of the HP assembler that fixes this problem
+is available for download from
 @uref{ftp://altdorf.ai.mit.edu/archive/cph/hpux-8.0-assembler}.  If you
 have HP software support, the patch can also be obtained directly from
 HP, as described in the following note:
@@ -2855,10 +2888,10 @@
 registration required).
 
 Versions of the assembler prior to ``cctools-364'' cannot handle the
-4-argument form of rlwinm and related mask-using instructions.  Darwin
+4-argument form of @code{rlwinm} and related mask-using instructions.  Darwin
 1.3 (Mac OS X 10.0) uses cctools-353 for instance.  To get cctools-364,
 check out @file{cctools} with tag @samp{Apple-364}, build it, and
-install the assembler as @file{usr/bin/as}.  See
+install the assembler as @file{usr/bin/as}.  See information at
 @uref{http://www.opensource.apple.com/tools/cvs/docs.html} for details.
 
 Also, the default stack limit of 512K is too small, and a bootstrap will
@@ -3033,8 +3066,10 @@
 Sun @command{as} 4.x is broken in that it cannot cope with long symbol names.
 A typical error message might look similar to the following:
 
-@samp{/usr/ccs/bin/as: "/var/tmp/ccMsw135.s", line 11041:
-error: can't compute value of an expression involving an external symbol.}
+@smallexample
+/usr/ccs/bin/as: "/var/tmp/ccMsw135.s", line 11041: error:
+  can't compute value of an expression involving an external symbol.
+@end smallexample
 
 This is Sun bug 4237974.  This is fixed with patch 108908-02 for Solaris
 2.6 and has been fixed in later (5.x) versions of the assembler,
@@ -3262,7 +3297,8 @@
 working on a generic OS/2 port with pgcc.  The current code can be found
 at @uref{http://www.goof.com/pcg/os2/,,http://www.goof.com/pcg/os2/}.
 
-An older copy of GCC 2.8.1 is included with the EMX tools available at
+An older copy of GCC 2.8.1 is included with the EMX tools, which are
+available at
 @uref{ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/,,
 ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/}.