Document fixes reported by users.

1 files changed, 50 insertions, 34 deletions

diff --git a/doc/source-builder.txt b/doc/source-builder.txt
index 65fff59..d7e030a 100644
--- a/doc/source-builder.txt
+++ b/doc/source-builder.txt
@@ -124,7 +124,7 @@ RTEMS Source Builder environment is ok <3>
 The checking tool will output a list of executable files not found if problems
 are detected. Locate those executable files and install them. You may also be
 given a list of warnings about executable files not in the expected location
-how-ever the executable was located somewhere in your environment's path. You
+however the executable was located somewhere in your environment's path. You
 will need to check each tool to determine if this is an issue. An executable
 not in the standard location may indicate it is not the host operating system's
 standard tool. It maybe ok or it could be buggy, only you can determine this.
@@ -228,9 +228,9 @@ Examining: ../source-builder/config <2>
     set files.
 <6> Unstable tool sets are used by RTEMS developers to test new tool sets. You
     are welcome to try them but you must remember they are unstable, can change
-    at point in time and your application may not work. If you have an issue
-    with a production tool it may pay to try the unstable tool to see if it has
-    been resolved.
+    at any point in time and your application may not work. If you have an
+    issue with a production tool it may pay to try the unstable tool to see if
+    it has been resolved.
 
 Building
 ~~~~~~~~
@@ -347,6 +347,12 @@ gcc version 4.7.2 20120920 <4>
     recorded in the version string. The hash allows you to track from a GCC
     executable back to the original source used to build it.
 
+NOTE: The RTEMS thread model enables specific hooks in GCC so applications
+built with RTEMS tools need the RTEMS runtime to operate correctly. You can use
+RTEMS tools to build bare metal component but it is more difficult than with a
+bare metal tool chain and you need to know what you are doing at a low
+level. The RTEMS Source Builder can build bare metal tool chains.
+
 Installing and Tar Files
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -355,14 +361,24 @@ it can create a build set tar file or a tar file per package built. The normal
 and default behaviour is to let the RTEMS Source Builder install the tools. The
 source will be downloaded, built, installed and cleaned up.
 
-The tar files are created with the full build prefix present. This can cause
+The tar files are created with the full build prefix present and if you follow
+the examples given in this documentation the path is absolute. This can cause
 problems if you are installing on a host you do not have super user or
-administrator rights on if the prefix path references part you do not have
-write access t0o. You can use the +--strip-components+ option in tar if your
-tar file supports it to remove the parts you do not have write access too or
-you may need to unpack the tar file somewhere and copy the file tree from the
-level you have write access from. Embedding the full prefix path in the tar
-files lets you know what the prefix is.
+administrator rights on because the prefix path may references part you do not
+have write access too and tar will not extract the files. You can use the
++--strip-components+ option in tar if your host tar application supports it to
+remove the parts you do not have write access too or you may need to unpack the
+tar file somewhere and copy the file tree from the level you have write access
+from. Embedding the full prefix path in the tar files lets you know what the
+prefix is and is recommended. For example if
+`/home/chris/development/rtems/4.11` is the prefix used you cannot
+change directory to the root (`/`) and install because the `/home` is root
+access only. To install you would:
+
+-------------------------------------------------------------
+$ cd
+$ tar --strip-components=3 -xjf rtems-4.11-sparc-rtems4.11-1.tar.bz2
+-------------------------------------------------------------
 
 A build set tar file is created by adding `--bset-tar-file` option to the
 `sb-set-builder` command.
@@ -494,7 +510,7 @@ changing world of the host development machines. If your tool set is binary and
 you have lost the ability to build it you have lost a degree of control and
 flexibility open source gives you. Fast moving host environments are
 fantastic. We have powerful multi-core computers with huge amounts of memory
-and state of the art operating systems to run on them how-ever the product or
+and state of the art operating systems to run on them however the product or
 project you are part of may need to be maintained well past the life time of
 these host. Being able to build from source an important and critical part of
 this process because you can move to a newer host and create an equivalent tool
@@ -508,7 +524,7 @@ GNU C compiler (gcc) currently uses a number of 3rd party libraries internally
 processor is dynamically linked against the host's version of these libraries
 any change in the host's configuration may effect you. The changes the host's
 package management system makes may be perfectly reasonable in relation to the
-distribution being managed how-ever this may not extend to you and your
+distribution being managed however this may not extend to you and your
 tools. Building your tools from source and controlling the specific version of
 these dependent parts means you are not exposing yourself to unexpected and
 often difficult to resolve problems. On the other side you need to make sure
@@ -532,7 +548,7 @@ Bugs, Crashes, and Build Failures
 ---------------------------------
 
 The RTEMS Source Builder is a Python program and every care is taken to test
-the code how-ever bugs, crashes, and build failure can and do happen. If you
+the code however bugs, crashes, and build failure can and do happen. If you
 find a bug please report it via the RTEMS Bug tracker tool Bugzilla:
 
 https://www.rtems.org/bugzilla/
@@ -831,7 +847,7 @@ Scripting
 
 Configuration files specify how to build a package. Configuration files are
 scripts and have a +.cfg+ file extension. The script format is based loosely on
-the RPM spec file format how-ever the use and purpose in this tool does not
+the RPM spec file format however the use and purpose in this tool does not
 compare with the functionality and therefore the important features of the spec
 format RPM needs and uses.
 
@@ -1163,9 +1179,9 @@ configuration building the package changes.
 
 The +%version% macro sets the version the package. If the package is a single
 component it tracks that component's version number. For example in the
-_libusb_ configuration the +%version+ is the same as +%libusb_version+,
-how-ever in a GCC with Newlib configuration there is no single version
-number. In this case the GCC version is used.
+_libusb_ configuration the +%version+ is the same as +%libusb_version+, however
+in a GCC with Newlib configuration there is no single version number. In this
+case the GCC version is used.
 
 -------------------------------------------------------------
 Version: %{gcc_version}
@@ -1481,10 +1497,10 @@ between them and this makes existing tool incompatible with RTEMS.
 RTEMS allows architectures to have different tool versions and patches. The
 large number of architectures RTEMS supports can make it difficult to get a
 common stable version of all the packages. An architecture may require a recent
-GCC because an existing bug has been fixed, how-ever the more recent version
-may have a bug in other architecture. Architecture specific patches should be
+GCC because an existing bug has been fixed, however the more recent version may
+have a bug in other architecture. Architecture specific patches should be
 limited to the architecture it relates to. The patch may fix a problem on the
-effect architecture how-ever it could introduce a problem in another
+effect architecture however it could introduce a problem in another
 architecture. Limit exposure limits any possible crosstalk between
 architectures.
 
@@ -1643,17 +1659,17 @@ Clean away the results of a build even if the build fails. This is normally
 used with `--keep-going` when regression testing to see which build sets
 fail to build. It keeps the disk usage down.
 +--jobs+;;
-Control the number of jobs make is given. The jobs can 'none' for only 1 job,
-'half' so the number of jobs is half the number of detected cores, a fraction
-such as '0.25' so the number of jobs is a quarter of the number of detected
-cores and a number such as '25' which forces the number of jobs to that
-number.
+Control the number of jobs make is given. The jobs can be 'none' for only 1
+job, 'half' so the number of jobs is half the number of detected cores, a
+fraction such as '0.25' so the number of jobs is a quarter of the number of
+detected cores and a number such as '25' which forces the number of jobs to
+that number.
 +--host+;;
-Set the host triplet value. Becareful with this option.
+Set the host triplet value. Be careful with this option.
 +--build+;;
-Set the build triplet. Becareful with this option.
+Set the build triplet. Be careful with this option.
 +--target+;;
-Set the target triplet. Becareful with this option. This is useful if you have
+Set the target triplet. Be careful with this option. This is useful if you have
 a generic configuration script that can work for a range of architectures.
 +--prefix path+;;
 Tools build prefix, ie where they are installed.
@@ -1844,7 +1860,7 @@ Windows tool sets are supported creating native Windows executable. Native
 Windows tools are built using a MinGW compiler and do not need any extra
 libraries or emulation layer to run once built. The tools understand and use
 standard Windows paths and integrate easly into Windows IDE environments. A
-shell maybe needed to build other parts of your system how-ever if your
+shell maybe needed to build other parts of your system however if your
 development tools are all native Windows tool you can easly integrate these
 tool sets.
 
@@ -1992,12 +2008,12 @@ way to build tools on hosts that did not support RPMs. At the time the RTEMS
 tools maintainer only used spec files to create various packages. This meant I
 had either spec files, RPM files or SRPM files. The RPM and SPRM files where
 useless because you needed an 'rpm' type tool to extract and manage them. There
-are versions of 'rpm' for a number of non-RPM hosts how-ever these proved to be
-in various broken states and random-ally maintained. The solution I settled on
-was to use spec files so I wrote a Python based tool that parsed the spec file
+are versions of 'rpm' for a number of non-RPM hosts however these proved to be
+in various broken states and randomly maintained. The solution I settled on was
+to use spec files so I wrote a Python based tool that parsed the spec file
 format and allowed me to create a shell script I could run to build the
 package. This approach proved successful and I was able to track the RPM
-version of the RTEMS tools on a non-RPM host over a number of years. How-ever
+version of the RTEMS tools on a non-RPM host over a number of years. however
 the SpecBuilder tool did not help me build tools or other packages not related
 to the RTEMS project where there was no spec file I could use so I needed
 another tool. Rather than start again I decided to take the parsing code for