2000-09-26 Joel Sherrill <joel@OARcorp.com>

	* started/binaries.t, started/buildc.t, started/buildrt.t,
	started/intro.t, started/nextstep.t, started/nt.t, started/require.t,
	started/sample.t:  Incorporate comments from Jeff Mayes.

8 files changed, 224 insertions, 135 deletions

diff --git a/doc/started/binaries.t b/doc/started/binaries.t
index fcf1830004..e3cc756c97 100644
--- a/doc/started/binaries.t
+++ b/doc/started/binaries.t
@@ -60,10 +60,10 @@ of a C/C++ toolset targeting the SPARC architecture.
 @example
 rpm -i rtems-base-binutils-2.9.5.0.24-1.i386.rpm
 rpm -i sparc-rtems-binutils-2.9.5.0.24-1.i386.rpm
-rpm -i rtems-base-gcc-gcc2.95.2newlib1.8.2-4.i386.rpm
-rpm -i sparc-rtems-gcc-gcc2.95.2newlib1.8.2-4.i386.rpm
-rpm -i rtems-base-gdb-4.18-2.i386.rpm
-rpm -i sparc-rtems-gdb-4.18-2.i386.rpm
+rpm -i rtems-base-gcc-gcc2.95.2newlib1.8.2-7.i386.rpm
+rpm -i sparc-rtems-gcc-gcc2.95.2newlib1.8.2-7.i386.rpm
+rpm -i rtems-base-gdb-4.18-4.i386.rpm
+rpm -i sparc-rtems-gdb-4.18-4.i386.rpm
 @end example
 
 Upon successful completion of the above command sequence, a 
@@ -72,6 +72,9 @@ installed in @code{/opt/rtems}.  In order to use this toolset,
 the directory @code{/opt/rtems/bin} must be included in your
 PATH.
 
+Once you have successfully installed the RPMs for BINUTILS, GCC,
+NEWLIB, and GDB, then you may proceed directly to @ref{Building RTEMS}.  
+
 @subsection Removing RPMs
 
 The following is a sample session illustrating the removal
@@ -86,6 +89,9 @@ rpm -e sparc-rtems-binutils-2.9.5.0.24-1.i386.rpm
 rpm -e rtems-base-binutils-2.9.5.0.24-1.i386.rpm
 @end example
 
+NOTE:  If you have installed any RTEMS BSPs, then it is likely that
+RPM will complain about not being able to remove everything.
+
 @section Zipped Tar Files
 
 This section provides information on installing and removing
diff --git a/doc/started/buildc.t b/doc/started/buildc.t
index b6a8af37af..111b7bf988 100644
--- a/doc/started/buildc.t
+++ b/doc/started/buildc.t
@@ -8,6 +8,14 @@
 
 @chapter Building the GNU C/C++ Cross Compiler Toolset
 
+NOTE:  This chapter does @b{NOT} apply if you installed
+prebuilt toolset executables for BINUTILS, GCC, NEWLIB,
+and GDB.  If you installed prebuilt executables for all
+of those, proceed to @ref{Building RTEMS}.  If you require
+a GDB with a special configuration to connect to your
+target board, then proceed to @code{Building the GNU Debugger GDB}
+for some advice.
+
 This chapter describes the steps required to acquire the
 source code for a GNU cross compiler toolset, apply 
 any required RTEMS specific patches, compile that 
@@ -18,36 +26,6 @@ your particular host, that they be used.  Prebuilt binaries
 are much easier to install.
 
 @c
-@c  Reading the Documentation
-@c
-
-@section Reading the Tools Documentation
-
-Each of the tools in the GNU development suite comes with documentation.
-It is in the reader's and tool maintainers' interest that one read the
-documentation before posting a problem to a mailing list or news group.
-The RTEMS Project provides formatted documentation for the primary
-tools in the cross development toolset including BINUTILS, GCC, 
-NEWLIB, and GDB at the following URL:
-
-@example
-http://www.oarcorp.com/rtems/releases/4.5.0/toolsdoc/html/index.html
-@end example
-
-Much of the documentation is available at other sites on the Internet.
-The following is a list of URLs where one can find HTML versions of
-the GNU manuals:
-
-@table @b
-@item Free Software Foundation 
-http://www.gnu.org/manual/manual.html
-
-@item Delorie Software
-http://www.delorie.com/gnu/docs
-
-@end table
-
-@c
 @c  Building BINUTILS GCC and NEWLIB
 @c
 @section Building BINUTILS GCC and NEWLIB
@@ -227,7 +205,8 @@ Apply the patch using the following command sequence:
 
 @example
 cd tools/@value{GCC-UNTAR}
-zcat ../../archive/@value{GCC-RTEMSPATCH} | patch -p1
+zcat ../../archive/@value{GCC-RTEMSPATCH} | \
+    patch -p1
 @end example
 
 Check to see if any of these patches have been rejected using the following
@@ -259,7 +238,8 @@ Apply the patch using the following command sequence:
 
 @example
 cd tools/@value{BINUTILS-UNTAR}
-zcat ../../archive/@value{BINUTILS-RTEMSPATCH} | patch -p1
+zcat ../../archive/@value{BINUTILS-RTEMSPATCH} | \
+    patch -p1
 @end example
 
 Check to see if any of these patches have been rejected using the following
@@ -292,7 +272,8 @@ Apply the patch using the following command sequence:
 
 @example
 cd tools/@value{NEWLIB-UNTAR}
-zcat ../../archive/@value{NEWLIB-RTEMSPATCH} | patch -p1
+zcat ../../archive/@value{NEWLIB-RTEMSPATCH} | \
+    patch -p1
 @end example
 
 Check to see if any of these patches have been rejected using the following
@@ -351,7 +332,7 @@ source code used to produce those binary files.  Before
 attempting to build any RPM from source, it is necessary to
 ensure that all required source and patches are in the @code{SOURCES}
 directory under the RPM root (probably @code{/usr/src/redhat} or
-@code{/usr/local/src/redhat} on your machine.  This procedure
+@code{/usr/local/src/redhat}) on your machine.  This procedure
 starts by installing the source RPMs as shown in the following 
 example:
 
@@ -567,7 +548,7 @@ After the compressed tar file @value{BUILDTOOLS-TAR} has been unpacked, there
 will be a set of scripts in the tools directory along with
 any source code you have previously unarchived.
 These scripts are intended to aid in building the tools and RTEMS.
-These scripts may be used to automate tool building process and hide
+These scripts may be used to automate the tool building process and hide
 the invocation of @code{configure} and @code{make} from you.  They are:
 
 @itemize @bullet
@@ -709,7 +690,7 @@ and not necessarily be correct for your CPU model.
 
 @end table
 
-The other items are RTEMS specific and are not technically required
+The other variables are RTEMS specific and are not technically required
 to be set unless you build RTEMS using the @code{bit_rtems} script
 as described in @ref{Using the bit_rtems Script}.  They are described
 in detail in that section.
@@ -874,7 +855,8 @@ Apply the patch using the following command sequence:
 
 @example
 cd tools/@value{GDB-UNTAR}
-zcat archive/@value{GDB-RTEMSPATCH} | patch -p1
+zcat archive/@value{GDB-RTEMSPATCH} | \
+    patch -p1
 @end example
 
 Check to see if any of these patches have been rejected using the following
@@ -896,7 +878,7 @@ This should not happen with a good patch file.
 
 @subsection Compiling and Installing the GNU Debugger GDB
 
-There are three methods of build the GNU Debugger:
+There are three methods of building the GNU Debugger:
 
 @itemize @bullet
 @item RPM
@@ -920,7 +902,7 @@ source code used to produce those binary files.  Before
 attempting to build any RPM from source, it is necessary to
 ensure that all required source and patches are in the @code{SOURCES}
 directory under the RPM root (probably @code{/usr/src/redhat} or
-@code{/usr/local/src/redhat} on your machine.  This procedure
+@code{/usr/local/src/redhat}) on your machine.  This procedure
 starts by installing the source RPMs as shown in the following
 example:
 
@@ -986,13 +968,9 @@ NOTE: It may be necessary to remove the build tree in the
 @subsubsection Using the GDB configure Script Directly
 
 This section describes how to configure the GNU debugger for
-standard RTEMS configurations as well as some alternative
-configurations that have been used in the past.
-
-@subheading Standard RTEMS GDB Configuration
-
-The following example illustrates the invocation of configure
-and make to build and install @value{GDB-UNTAR} for the
+RTEMS targets using @code{configure} and @code{make} directly.
+The following example illustrates the invocation of @code{configure}
+and @code{make} to build and install @value{GDB-UNTAR} for the
 m68k-rtems target:
 
 @example
@@ -1086,7 +1064,7 @@ This can occur for one of the following reasons:
 
 @end itemize
 
-If you are using binutils 2.9.1 or newer with certain versions of
+If you are using binutils 2.9.1 or newer with certain older versions of
 gcc, they do not agree on what the name of the newly 
 generated cross assembler is.  Older binutils called it @code{as.new}
 which became @code{as.new.exe} under Windows.  This is not a valid
@@ -1105,7 +1083,7 @@ in your PATH.  As a general rule, including "." in your PATH
 is a security risk and should be avoided.  Remove "." from
 your PATH.
 
-NOTE:  In some environments, it may be difficult remove "."
+NOTE:  In some environments, it may be difficult to remove "."
 completely from your PATH.  In this case, make sure that "."
 is after the system directories containing "as" and "ld".
 
@@ -1153,4 +1131,4 @@ build directory.
 
 This situation can be avoided entirely by never using 
 the source tree as the build directory -- even for
-native builds.
+
diff --git a/doc/started/buildrt.t b/doc/started/buildrt.t
index 256fb1f16b..f3e2451cd5 100644
--- a/doc/started/buildrt.t
+++ b/doc/started/buildrt.t
@@ -37,7 +37,11 @@ placed in your @code{archive} directory.
 @end ifset
 @end example
 
-@section Unpack the RTEMS Source
+@c
+@c  Unarchive the RTEMS Source
+@c
+
+@section Unarchive the RTEMS Source
 
 Use the following command sequence to unpack the RTEMS source into the
 tools directory: 
@@ -47,30 +51,11 @@ cd tools
 tar xzf ../archive/@value{RTEMS-TAR}
 @end example
 
-If you did not build and install the tools from source, then you
-will need to unarchive the build scripts at this point.  In this
-case, you will have to execute the following additional command
-since you did not do it as part of building the tools.
-
-@example
-tar xzf ../archive/@value{BUILDTOOLS-TAR}
-@end example
-
-At this point, the following files and directories should
-exist in the current directory in order to build RTEMS:
-
-@itemize @bullet
-@item bit
-@item bit_rtems
-@item common.sh
-@item @value{RTEMS-UNTAR}
-@item user.cfg
-@end itemize
 
 @section Add <INSTALL_POINT>/bin to Executable PATH
 
 In order to compile RTEMS, you must have the cross compilation toolset
-in your search patch.  The following command appends the directory
+in your search path.  The following command appends the directory
 where the tools were installed prior to this point:
 
 @example
@@ -86,9 +71,9 @@ derivatives of the C Shell.
 
 In order to insure that the cross-compiler is invoking the correct
 subprograms (like @code{as} and @code{ld}), one can test assemble
-a small program.  When in verbose more, @code{gcc} prints out information 
-showing where it found the subprograms it invokes.  Place the following
-function in a file named @code{f.c}:
+a small program.  When in verbose mode, @code{gcc} prints out information 
+showing where it found the subprograms it invokes.  In a temporary
+working directory, place the following function in a file named @code{f.c}:
 
 @example
 int f( int x )
@@ -109,9 +94,23 @@ a sequence of output showing where the cross-compiler searched for
 and found its subcomponents.  Verify that these paths correspond
 to your <INSTALL_POINT>.
 
-@b{NOTE:} One of the most common installation errors is for the
-cross-compiler not to be able to find the cross assembler and default
-to using the native @code{as}.  This can result in very confusing
+Look at the created file @code{f.s} and verify that it is in fact
+for your target processor.
+
+Then try to compile the file @code{f.c} directly to object code
+using a command like the following:
+
+@example
+m68k-rtems-gcc -v -c f.c
+@end example
+
+If this produces messages that indicate the assembly code is
+not valid, then it is likely that you have fallen victim to 
+one of the problems described in
+@ref{Error Message Indicates Invalid Option to Assembler}
+Don't feel bad about this, one of the most common installation errors
+is for the cross-compiler not to be able to find the cross assembler
+and default to using the native @code{as}.  This can result in very confusing
 error messages.
 
 @section Generate RTEMS for a Specific Target and BSP
@@ -124,13 +123,14 @@ Make a build directory under tools and build the RTEMS product in this
 directory. The ../@value{RTEMS-UNTAR}/configure
 command has numerous command line
 arguments. These arguments are discussed in detail in documentation that
-comes with the RTEMS distribution. In the installation described in the
-section "Unpack the RTEMS source", these configuration options can be found
-in the file tools/@value{RTEMS-UNTAR}/README.configure.
+comes with the RTEMS distribution. If you followed the procedure
+described in the section @code{Unpack the RTEMS source}, these
+configuration options can be found in the file
+tools/@value{RTEMS-UNTAR}/README.configure.
 
-The GNAT/RTEMS run-time implementation is based on the POSIX API.  Thus
-the RTEMS configuration for a GNAT/RTEMS environment MUST include the
-@code{--enable-posix} flag.
+@b{NOTE}: The GNAT/RTEMS run-time implementation is based on the POSIX
+API.  Thus the RTEMS configuration for a GNAT/RTEMS environment MUST
+include the @code{--enable-posix} flag.
 
 The following shows the command sequence required to configure,
 compile, and install RTEMS with the POSIX API, FreeBSD TCP/IP,
@@ -147,12 +147,12 @@ cd build-rtems
 make all install
 @end example
 
-Where the list of currently supported of <TARGET_CONFIGURATION>'s and
+Where the list of currently supported <TARGET_CONFIGURATION>'s and
 <BOARD_SUPPORT_PACKAGE>'s can be found in
 tools/@value{RTEMS-UNTAR}/README.configure.
 
-<INSTALL_POINT> is the installation point from the previous step
-"Modify the bit script" in the build of the tools. 
+<INSTALL_POINT> is typically the installation point for the 
+tools and is @code{/opt/rtems} when using prebuilt toolset executables.
 
 NOTE: The @code{make} utility used should be GNU make.
 
@@ -162,7 +162,17 @@ NOTE: The @code{make} utility used should be GNU make.
 
 @subsection Using the bit_rtems Script
 
-The simplest way to build RTEMS is to use the @code{bit_rtems} script.
+If you have not previously unarchived the build tools, then you
+will need to unarchive the build scripts at this point if you
+plan to use @code{bit_rtems} to build RTEMS.  If this is the
+case, you will have to execute the following additional command
+since you did not do it as part of building the tools.
+
+@example
+cd tools
+tar xzf ../archive/@value{BUILDTOOLS-TAR}
+@end example
+
 This script interprets the settings in the @code{user.cfg} file to
 enable or disable the various RTEMS options.  The RTEMS
 specific entries described below must be set to
diff --git a/doc/started/intro.t b/doc/started/intro.t
index a50da6ab06..de81001056 100644
--- a/doc/started/intro.t
+++ b/doc/started/intro.t
@@ -34,7 +34,7 @@ process used when developing RTEMS applications.
 Real-time embedded systems are found in practically every facet of our
 everyday lives.  Today's systems range from the common telephone, automobile
 control systems, and kitchen appliances to complex air traffic control
-systems, military weapon systems, an d production line control including
+systems, military weapon systems, and production line control including
 robotics and automation. However, in the current climate of rapidly changing
 technology, it is difficult to reach a consensus on the definition of a
 real-time embedded system. Hardware costs are continuing to rapidly decline 
@@ -94,7 +94,7 @@ code, device drivers, and error handling code.
 The build-host computer is optimized to support the code development cycle with
 support for code editors, compilers, and linkers requiring large disk drives,
 user development windows, and multiple developer connections.  Thus the build-host
-computer is typically a traditional UNIX workstation such as are available
+computer is typically a traditional UNIX workstation such as that available
 from SUN or Silicon Graphics, or a PC running either a version of MS-Windows
 or UNIX.  The build-host system may also be required to execute office productivity
 applications to allow the software developer to write  documentation, make
@@ -114,8 +114,8 @@ is typically a critical concern.  No hardware component is included without
 being cost justified.  As a result, the processor of the target system is
 often from a different processor family than that of the build-host system and
 usually has lower performance.  In addition to the processor families
-targeted only for use in embedded systems, there are versions of nearly every
-general-purpose process or specifically tailored for real-time embedded
+designed only for use in embedded systems, there are versions of nearly every
+general-purpose processor specifically tailored for real-time embedded
 systems.  For example, many of the processors targeting the embedded market
 do not include hardware floating point units, but do include peripherals such
 as timers, serial controllers, or network interfaces. 
@@ -125,6 +125,37 @@ as timers, serial controllers, or network interfaces.
 This section describes various resources on the Internet which are of
 use to RTEMS users.
 
+@c
+@c  Online Tool Documentation
+@c
+
+@subsection Online Tool Documentation
+
+Each of the tools in the GNU development suite comes with documentation.
+It is in the reader's and tool maintainers' interest that one read the
+documentation before posting a problem to a mailing list or news group.
+The RTEMS Project provides formatted documentation for the primary
+tools in the cross development toolset including BINUTILS, GCC,
+NEWLIB, and GDB at the following URL:
+
+@example
+http://www.oarcorp.com/rtems/releases/4.5.0/toolsdoc/html/index.html
+@end example
+
+Much of the documentation is available at other sites on the Internet.
+The following is a list of URLs where one can find HTML versions of
+the GNU manuals:
+
+@table @b
+@item Free Software Foundation
+http://www.gnu.org/manual/manual.html
+
+@item Delorie Software
+http://www.delorie.com/gnu/docs
+
+@end table
+
+
 @subsection RTEMS Mailing List
 
 @uref{mailto:rtems-users@@OARcorp.com,rtems-users@@OARcorp.com}
@@ -132,8 +163,7 @@ use to RTEMS users.
 This mailing list is dedicated to the discussion of issues related
 to RTEMS, including GNAT/RTEMS.  If you have questions about RTEMS,
 wish to make suggestions, or just want to pick up hints, this is a 
-good list to subscribe to.  Subscribe by sending an empty mail 
-message to 
+good list to monitor.  Subscribe by sending an empty mail message to 
 @uref{mailto:rtems-users-subscribe@@OARcorp.com,rtems-users-subscribe@@OARcorp.com}.  Messages sent 
 to @uref{mailto:rtems-users@@OARcorp.com,rtems-users@@OARcorp.com}
 are posted to the list.
@@ -148,7 +178,7 @@ focus on embedded issues.  Information on subscribing
 to this mailing list is included in the 
 @uref{http://www.objsw.com/CrossGCC/,CrossGCC FAQ}.
 
-The crossgcc FAQ as well as a number of patches and utilities
+The CrossGCC FAQ as well as a number of patches and utilities
 of interest to cross development system users are available
 at @uref{ftp://ftp.cygnus.com/pub/embedded/crossgcc}.
 
diff --git a/doc/started/nextstep.t b/doc/started/nextstep.t
index 391fcbe584..8c9c7e5b2b 100644
--- a/doc/started/nextstep.t
+++ b/doc/started/nextstep.t
@@ -74,7 +74,10 @@ that is not clear or missing, bring it to our attention.
 
 Also, some of the RTEMS documentation is still under
 construction.  If you would like to contribute to this
-effort, please contact the RTEMS Team.
+effort, please contact the RTEMS Team at @url{rtems-users@@OARcorp.com}.
+If you are interested in sponsoring the development of a new
+feature, BSP, device driver, port of an existing library, etc.,
+please contact @url{sales@@OARcorp.com}.
 
 @section Writing an Application
 
@@ -114,7 +117,7 @@ most of the examples, the initialization task completes by
 deleting itself.
 
 As you begin to write RTEMS application code, you may be confused
-by the plethora of alternatives.  Supporting multiple tasking
+by the range of alternatives.  Supporting multiple tasking
 APIs can make the choices confusing.  Many application groups
 writing new code choose one of the APIs as their primary API
 and only use services from the others if nothing comparable
diff --git a/doc/started/nt.t b/doc/started/nt.t
index 7df2be5d8a..1113799e27 100644
--- a/doc/started/nt.t
+++ b/doc/started/nt.t
@@ -63,12 +63,9 @@ Using Windows 95 or 98 is not recommended although it
 should be possible with version 3.77 of GNU make and an updated
 cygwinb19.dll.
 
-This procedure should also work with newer version of 
+This procedure should also work with newer versions of 
 the tool versions listed in this chapter, but this has
-not been verified.  If you have success with a particular
-version of the toolset or notice problems in this chapter,
-please let the RTEMS maintainers know so they can be
-addressed in future revisions of this document.
+not been verified.  
 
 @subsection MS-Windows Host Specific Requirements
 
@@ -111,7 +108,7 @@ at @b{http://www.gnu.org/software/emacs/windows/ntemacs.html}.
 from @b{http://www.simtel.net/pub/simtelnet/win95/editor/pfe101i.zip,http://www.simtel.net/pub/simtelnet/win95/editor/pfe101i.zip}.  Note this
 editor is no longer actively supported.
 
-@c @uref{http://www.simtel.net/pub/simtelnet/win95/editor/pfe101i.zip,http://www.simtel.net/pub/simtelnet/win95/editor/pfe101i.zip}
+@c @uref{http://www.simtel.net/pub/simtelnet/win95/editor/pfe101i.zip}
 
 @end itemize
 
@@ -131,7 +128,7 @@ Dos2Unix: Cleaning file XYZ ...
 The dos2unix utility may be downloaded from:
 
 @c @uref{ftp://ftp.micros.hensa.ac.uk/platforms/ibm-pc/ms-dos/simtelnet/txtutl/dos2unix.zip,ftp://ftp.micros.hensa.ac.uk/platforms/ibm-pc/ms-dos/simtelnet/txtutl/dos2unix.zip}
-@b{ftp://ftp.micros.hensa.ac.uk/platforms/ibm-pc/ms-dos/simtelnet/txtutl/dos2unix.zip,ftp://ftp.micros.hensa.ac.uk/platforms/ibm-pc/ms-dos/simtelnet/txtutl/dos2unix.zip}
+@b{ftp://ftp.micros.hensa.ac.uk/platforms/ibm-pc/ms-dos/simtelnet/txtutl/dos2unix.zip}
 
 You @b{must} change the format of every patched file 
 for the toolset build to work correctly.
@@ -151,11 +148,11 @@ was released and URLs may no longer be correct.]
 
 @item cdk.exe
 @c @uref{http://www.cygnus.com/misc/gnu-win32/,http://www.cygnus.com/misc/gnu-win32/}
-@b{http://www.cygnus.com/misc/gnu-win32/,http://www.cygnus.com/misc/gnu-win32/}
+@b{http://www.cygnus.com/misc/gnu-win32/}
 
 @item coolview.tar.gz
 @c @uref{http://www.lexa.ru/sos/,http://www.lexa.ru/sos/}
-@b{http://www.lexa.ru/sos/,http://www.lexa.ru/sos/}
+@b{http://www.lexa.ru/sos/}
 
 @end table
 
@@ -251,7 +248,7 @@ and change the following line:
 to:
 
 @example
--lcygwin %@{mwindows:-luser32 -lgdi32 -lcomdlg32@} -lkernel32 -ladvapi32
+-lcygwin %@{mwindows:-luser32 -lgdi32 -lcomdlg32@} k-lkernel32 -ladvapi32
 @end example
 
 @end enumerate
@@ -276,7 +273,8 @@ Apply the appropriate RTEMS specific patch as detailed in
 command to configure @value{BINUTILS-VERSION}:
 
 @example
-/source/@value{BINUTILS-UNTAR}/configure --verbose --target=m68k-rtems \
+/source/@value{BINUTILS-UNTAR}/configure \
+    --verbose --target=m68k-rtems \
     --prefix=/gcc-m68k-rtems --with-gnu-as --with-gnu-ld 
 @end example
 
@@ -297,7 +295,7 @@ make -k install
 @end example
 
 There is a problem with the gnu info package which will cause an 
-error during installation. Telling make to keep going with -k allows 
+error during installation. Telling make to keep going with @code{-k} allows 
 the install to complete.
 
 @item In the @code{cygnus.bat} file, add the directory
@@ -352,7 +350,8 @@ or Objective-C as Cygwin32 cross-compilers):
 @item Change to the /build/gcc directory to configure the compiler:
 
 @example
-/source/@value{GCC-UNTAR}/configure --verbose --target=m68k-rtems \
+/source/@value{GCC-UNTAR}/configure \
+    --verbose --target=m68k-rtems \
     --prefix=/gcc-m68k --with-gnu-as --with-gnu-ld \
     --with-newlib
 @end example
@@ -382,10 +381,6 @@ make -k install
 info package not building correctly requires that you use -k to 
 keep going.
 
-@example
-make -k install
-@end example
-
 @end enumerate
 
 With any luck, at this point you having a working cross-compiler.  So
diff --git a/doc/started/require.t b/doc/started/require.t
index cc3edf00a7..0f83a5f002 100644
--- a/doc/started/require.t
+++ b/doc/started/require.t
@@ -44,14 +44,14 @@ installed, then the additional size of each install directory
 will tend to be in the 40-60 Mbyte range.
 
 There are a number of factors which must be taken into
-account in oreder to estimate the amount of disk space required
+account in order to estimate the amount of disk space required
 to build RTEMS itself.  Attempting to build multiple BSPs in
 a single step increases the disk space requirements.  Similarly
 enabling optional features increases the build and install
 space requirements.  In particular, enabling and building
 the RTEMS tests results in a significant increase in build
-space requirements but since the test are not installed has
-no impact on installation requirements.
+space requirements but since the tests are not installed has,
+enabling them has no impact on installation requirements.
 
 @section General Host Software Requirements
 
@@ -79,11 +79,11 @@ compiler.
 
 @subsection GNU Make
 
-Both newlib nor RTEMS use GNU make specific features and can only be built
+Both NEWLIB and RTEMS use GNU make specific features and can only be built
 using GNU make.  Many systems include a make utility that is not GNU make.
 The safest way to meet this requirement is to ensure that when you invoke
 the command @code{make}, it is GNU make.  This can be verified by 
-attempting printing the GNU make version information:
+attempting to print the GNU make version information:
 
 @example
 make --version
@@ -114,19 +114,31 @@ makeinfo --version
 
 @subsection Solaris 2.x
 
-The build scripts are written in "shell".  The program @code{/bin/sh}
+The following problems have been reported by Solaris 2.x users:
+
+@itemize @bullet
+
+@item The build scripts are written in "shell".  The program @code{/bin/sh}
 on Solaris 2.x is not robust enough to execute these scripts.  If you
 are on a Solaris 2.x host, then change the first line of the files
 @code{bit}, @code{bit_gdb}, and @code{bit_rtems} to use the
 @code{/bin/ksh} shell instead.
 
+@item The native @code{patch} program is broken.  Install the GNU version.
+
+@item The native @code{m4} program is deficient.  Install the GNU version.
+
+@end itemize
+
 @subsection Linux
 
-@subsubsection Broken install Program
+The following problems have been reported by Linux users:
+
+@itemize @bullet
 
-Certain versions of GNU fileutils include a version of @code{install} which
-does not work properly.  Please perform the following test to see if you
-need to upgrade:
+@item Certain versions of GNU fileutils include a version of
+@code{install} which does not work properly.  Please perform
+the following test to see if you need to upgrade:
 
 @example
 install -c -d /tmp/foo/bar
@@ -136,6 +148,8 @@ If this does not create the specified directories your install
 program will not install RTEMS properly.   You will need to upgrade
 to at least GNU fileutils version 3.16 to resolve this problem.
 
+@end itemize
+
 @section Archive and Build Directories
 
 If you are using RPM or another packaging format that supports
diff --git a/doc/started/sample.t b/doc/started/sample.t
index 3c58509cfb..7921431cb5 100644
--- a/doc/started/sample.t
+++ b/doc/started/sample.t
@@ -19,11 +19,11 @@ tar xzf ../archive/hello_world_c.tgz
 
 @section Set the Environment Variable RTEMS_MAKEFILE_PATH 
 
-It must point to the appropriate directory containing RTEMS build for our
-target and board support package combination. 
+RTEMS_MAKEFILE_PATH must point to the appropriate directory containing
+RTEMS build for our target and board support package combination. 
 
 @example
-export RTEMS_MAKEFILE_PATH = <INSTALLATION_POINT>/<BOARD_SUPPORT_PACKAGE>
+export RTEMS_MAKEFILE_PATH=<INSTALLATION_POINT>/<BOARD_SUPPORT_PACKAGE>
 @end example
 
 Where <INSTALLATION_POINT> and <BOARD_SUPPORT_PACKAGE> are those used when
@@ -35,10 +35,11 @@ was changed to be more in compliance with GNU standards.
 
 @section Build the Sample Application
 
-Use the following command to start the build of the sample application: 
+Use the following command to start the build of the sample hello 
+world application: 
 
 @example
-cd tools/hello_world_c
+cd hello_world_c
 make
 @end example
 
@@ -56,17 +57,69 @@ If the sample application has successfully been build, then the application
 executable is placed in the following directory: 
 
 @example
-tools/hello_world_c/o-optimize/<filename>.exe
+hello_world_c/o-optimize/<filename>.exe
 @end example
 
 How this executable is downloaded to the target board is very dependent
-on the BOARD_SUPPORT_PACKAGE selected.
+on the BOARD_SUPPORT_PACKAGE selected.  The following is a list of
+commonly used BSPs classified by their RTEMS CPU family and pointers
+to instructions on how to use them.  [NOTE: All file names should be
+prepended with @value{RTEMS-UNTAR}/c/src/lib/libbsp.]
+
+@table @b
+@item i386/pc386
+@code{i386/pc386/HOWTO}
+
+@item i386/pc486
+The i386/pc386 specially compiler for an i486-class CPU.
+
+@item i386/pc586
+The i386/pc386 specially compiler for a Pentium-class CPU.
+
+@item i386/pc686
+The i386/pc386 specially compiler for a Pentium II.
+
+@item i386/pck6
+The i386/pc386 specially compiler for an AMD K6.
+
+@item m68k/mvme162
+@code{m68k/mvme162/README}.
+
+@item m68k/mvme167
+@code{m68k/mvme167/README}.
+
+@item powerpc/mcp750
+@code{powerpc/motorola_shared/README.MVME2300}.
+
+@item powerpc/mvme230x
+@code{powerpc/motorola_shared/README.MVME2300}.
+
+@item powerpc/psim
+This is a BSP for the PowerPC simulator included with @code{powerpc-rtems-gcc}.
+It is a bit complicated to initialize by hand.  The user is referred
+to the script @code{powerpc/psim/tools/psim}.
+
+@item sparc/erc32
+This can be used with the simulator included with @code{sparc-rtems-gcc}.
+An application can be run by executing the following commands
+upon entering gdb: 
+
+@example
+target sim
+load
+run
+@end example
+
+@end table
+
+RTEMS has many more BSPs and new BSPs for commercial boards and CPUs
+with on-CPU peripherals are generally welcomed.
 
 @section More Information on RTEMS Application Makefiles
 
 The hello world sample application is a simple example of an
-RTEMS application the uses the RTEMS Application Makefile 
-system.  This Makefile system gives simplifies building
+RTEMS application that uses the RTEMS Application Makefile 
+system.  This Makefile system simplifies building
 RTEMS applications by providing Makefile templates and
 capturing the configuration information used to build
 RTEMS specific to your BSP.  Building an RTEMS application