user: Rework Prefixes section

Rename it to "Choose an Installation Prefix".

Update #3675.

1 files changed, 36 insertions, 38 deletions

diff --git a/user/start/prefixes.rst b/user/start/prefixes.rst
index 87e76a1..2bd096f 100644
--- a/user/start/prefixes.rst
+++ b/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
-built and installed under. Packages that have a **prefix** will place all parts
-under the **prefix** path. On a host computer like Linux the packages you
-install from your distribution typically use a platform specific standard
-**prefix**. For example on Linux it is :file:`/usr` and on FreeBSD it is
-:file:`/usr/local`.
-
-We recommend you *DO NOT* use the standard **prefix** when installing the RTEMS
-Tools. The standard **prefix** is the default **prefix** each package built by
-the RSB contains. If you are building the tools when logged in as a *Standard
-User* and not as the *Super User* (``root``) or *Administrator* the RTEMS
-Source Builder (RSB) *will* fail and report an error if the default **prefix**
-is not writable. We recommend you leave the standand **prefix** for the
-packages your operating system installs or software you manually install such
-as applications.
-
-A further reason not to use the standard **prefix** is to allow more than one
-version of RTEMS to exist on your host machine at a time. The ``autoconf`` and
-``automake`` tools required by RTEMS are not versioned and vary between the
-various versions of RTEMS. If you use a single **prefix** such as the standard
-**prefix** there is a chance parts from a package of different versions may
-interact. This should not happen but it can.
-
-For POSIX or Unix hosts, the RTEMS Project uses :file:`/opt/rtems` as it's
-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
-this is :file:`/c/opt/rtems`.
+the internet.  It is also used in the
+`GNU Coding Standard <https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>`_.
+A *prefix* is the path on your host computer a software package is installed
+under.  Packages that have a prefix will place all parts under the prefix
+path.  Packages for your host computer typically use a default prefix of
+:file:`/usr/local` on FreeBSD and Linux.
+
+You have to select a prefix for your RTEMS tool suite installation.  The RTEMS
+tool suite consists of a cross tool chain (Binutils, GCC, GDB, Newlib, etc.)
+for your target architecture and :ref:`other tools <HostTools>` provided by the
+RTEMS Project.  You build and install the tool suite with the
+:ref:`RTEMS Source Builder (RSB) <RSB>`.  By default, the RSB will start the
+prefix path with a host operating system specific path plus :file:`rtems` plus
+the RTEMS version, e.g.  :file:`/opt/rtems/5` on Linux and
+:file:`/usr/local/rtems/5` on FreeBSD and macOS.
+
+It is strongly recommended to run the RSB as a *normal user* and not with
+*root* privileges (also known as *super user* or *Administrator*).  You have to
+make sure that your normal user has sufficient privileges to create files and
+directories under the prefix.  For example, you can create a directory
+:file:`/opt/rtems` and give it to a developer group with read, write and
+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.
+
+.. warning::
+
+    The prefix must not contain space characters.