user: Rework Prefixes section

Rename it to "Choose an Installation Prefix".

Update #3675.

user/hosts/posix.rst

@@ -35,7 +35,7 @@ machine. If the machine is a centralised build server the prefix may be used to
 separate production versions from the test versions and the prefix paths may
 have restricted access rights to only those who manage and have configuration
 control of the machine. We call this project sandboxing and
-:ref:`project-sandboxing` explains this in more detail.
+:ref:`ProjectSandboxing` explains this in more detail.
 
 Linux
 -----

user/installation/project-sandboxing.rst

@@ -2,7 +2,7 @@
 
 .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
 
-.. _project-sandboxing:
+.. _ProjectSandboxing:
 
 Project Sandboxing
 ------------------

user/start/index.rst

@@ -57,7 +57,7 @@ place you have suitable storage. Another is permissions.  There is no
 need to become root or the administrator and we recommend you avoid
 doing this. You can build and install the tools anywhere on the host's
 file system you, as a standard user, have read and write access too.
-:ref:`Prefixes` and :ref:`project-sandboxing` provide detailed examples
+:ref:`Prefixes` and :ref:`ProjectSandboxing` provide detailed examples
 of possible locations and set ups.
 
 Simple Example

user/start/prefixes.rst

@@ -1,48 +1,46 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
+.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 Sebastian Huber
 .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
 
 .. _QuickStartPrefixes:
 
-Prefixes
+Choose an Installation Prefix
-========
+=============================
 
 .. index:: prefix
 
-You will see the term :ref:term:`prefix` referred to thoughout this
+You will see the term :ref:term:`prefix` referred to throughout this
 documentation and in a wide number of software packages you can download from
-the internet. A **prefix** is the path on your computer a software package is
+the internet.  It is also used in the
-built and installed under. Packages that have a **prefix** will place all parts
+`GNU Coding Standard <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>`_.
-under the **prefix** path. On a host computer like Linux the packages you
+A *prefix* is the path on your host computer a software package is installed
-install from your distribution typically use a platform specific standard
+under.  Packages that have a prefix will place all parts under the prefix
-**prefix**. For example on Linux it is :file:`/usr` and on FreeBSD it is
+path.  Packages for your host computer typically use a default prefix of
-:file:`/usr/local`.
+:file:`/usr/local` on FreeBSD and Linux.
 
-We recommend you *DO NOT* use the standard **prefix** when installing the RTEMS
+You have to select a prefix for your RTEMS tool suite installation.  The RTEMS
-Tools. The standard **prefix** is the default **prefix** each package built by
+tool suite consists of a cross tool chain (Binutils, GCC, GDB, Newlib, etc.)
-the RSB contains. If you are building the tools when logged in as a *Standard
+for your target architecture and :ref:`other tools <HostTools>` provided by the
-User* and not as the *Super User* (``root``) or *Administrator* the RTEMS
+RTEMS Project.  You build and install the tool suite with the
-Source Builder (RSB) *will* fail and report an error if the default **prefix**
+:ref:`RTEMS Source Builder (RSB) <RSB>`.  By default, the RSB will start the
-is not writable. We recommend you leave the standand **prefix** for the
+prefix path with a host operating system specific path plus :file:`rtems` plus
-packages your operating system installs or software you manually install such
+the RTEMS version, e.g.  :file:`/opt/rtems/5` on Linux and
-as applications.
+:file:`/usr/local/rtems/5` on FreeBSD and macOS.
 
-A further reason not to use the standard **prefix** is to allow more than one
+It is strongly recommended to run the RSB as a *normal user* and not with
-version of RTEMS to exist on your host machine at a time. The ``autoconf`` and
+*root* privileges (also known as *super user* or *Administrator*).  You have to
-``automake`` tools required by RTEMS are not versioned and vary between the
+make sure that your normal user has sufficient privileges to create files and
-various versions of RTEMS. If you use a single **prefix** such as the standard
+directories under the prefix.  For example, you can create a directory
-**prefix** there is a chance parts from a package of different versions may
+:file:`/opt/rtems` and give it to a developer group with read, write and
-interact. This should not happen but it can.
+execute permissions.  Alternatively, you can choose a prefix in your home
+directory, e.g. :file:`$HOME/rtems/5` or with a project-specific component
+:file:`$HOME/project-x/rtems/5`.  For more ideas, see the
+:ref:`project sandboxing <ProjectSandboxing>` section.  In this quick start
+chapter, we will choose :file:`$HOME/quick-start/rtems/5` for the RTEMS tool
+suite prefix.
 
-For POSIX or Unix hosts, the RTEMS Project uses :file:`/opt/rtems` as it's
+.. warning::
-standard **prefix**. We view this **prefix** as a production level path, and we
-prefer to place development versions under a different **prefix** away from the
-production versions. Under this top level **prefix** we place the various
-versions we need for development. For example the version 4.11.0 **prefix**
-would be :file:`/opt/rtems/4.11.0`. If an update called 4.11.1 is released the
-**prefix** would be :file:`/opt/rtems/4.11.1`. These are recommendations and
-the choice of what you use is entirely yours. You may decide to have a single
-path for all RTEMS 4.11 releases of :file:`/opt/rtems/4.11`.
 
-For Windows a typical **prefix** is :file:`C:\\opt\\rtems` and as an MSYS2 path
+    The prefix must not contain space characters.
-this is :file:`/c/opt/rtems`.

user/tools/index.rst

@@ -2,6 +2,8 @@
 
 .. Copyright (C) 2017 Chris Johns <chrisj@rtems.org>
 
+.. _HostTools:
+
 Host Tools
 **********