Update System Principles

Language cleaned up by the technical writers xsipewe and tmanevik
from Combitech. Proofreading and corrections by Hans Bolinder.

5 files changed, 482 insertions, 495 deletions

diff --git a/system/doc/system_principles/create_target.xmlsrc b/system/doc/system_principles/create_target.xmlsrc
index a8ee2d1245..7c566229ac 100644
--- a/system/doc/system_principles/create_target.xmlsrc
+++ b/system/doc/system_principles/create_target.xmlsrc
@@ -31,55 +31,54 @@
     <rev>A</rev>
     <file>create_target.xml</file>
   </header>
+  <marker id="creating upgrading target system"></marker>
 
-  <section>
-    <title>Introduction</title>
-    <p>When creating a system using Erlang/OTP, the most simple way is
-      to install Erlang/OTP somewhere, install the application specific
+    <p>When creating a system using Erlang/OTP, the simplest way is
+      to install Erlang/OTP somewhere, install the application-specific
       code somewhere else, and then start the Erlang runtime system,
-      making sure the code path includes the application specific code.</p>
-    <p>Often it is not desirable to use an Erlang/OTP system as is. A
-      developer may create new Erlang/OTP compliant applications for a
+      making sure the code path includes the application-specific code.</p>
+    <p>It is often not desirable to use an Erlang/OTP system as is. A
+      developer can create new Erlang/OTP-compliant applications for a
       particular purpose, and several original Erlang/OTP applications
-      may be irrelevant for the purpose in question. Thus, there is a
+      can be irrelevant for the purpose in question. Thus, there is a
       need to be able to create a new system based on a given
-      Erlang/OTP system, where dispensable applications are removed,
-      and a set of new applications are included. Documentation and
+      Erlang/OTP system, where dispensable applications are removed
+      and new applications are included. Documentation and
       source code is irrelevant and is therefore not included in the
       new system.</p>
-    <p>This chapter is about creating such a system, which we call a
+    <p>This chapter is about creating such a system, which is called a
       <em>target system</em>.</p>
-    <p>In the following sections we consider creating target systems with
-      different requirements of functionality:</p>
+    <p>The following sections deal with target systems
+      with different requirements of functionality:</p>
     <list type="bulleted">
-      <item>a <em>basic target system</em> that can be started by
-       calling the ordinary <c>erl</c> script, </item>
-      <item>a <em>simple target system</em> where also code
-       replacement in run-time can be performed, and</item>
-      <item>an <em>embedded target system</em> where there is also
+      <item>A <em>basic target system</em> that can be started by
+       calling the ordinary <c>erl</c> script.</item>
+      <item>A <em>simple target system</em> where also code
+       replacement in runtime can be performed.</item>
+      <item>An <em>embedded target system</em> where there is also
        support for logging output from the system to file for later
        inspection, and where the system can be started automatically
-       at boot time. </item>
+       at boot time.</item>
     </list>
-    <p>We only consider the case when Erlang/OTP is running on a UNIX
-      system.</p>
-    <p>In the <c>sasl</c> application there is an example Erlang
-      module <c>target_system.erl</c> that contains functions for
-      creating and installing a target system.  This module is used in
-      the examples below, and the source code of the module is listed
-      at the end of this chapter.</p>
-  </section>
+    <p>Here is only considered the case when Erlang/OTP is running on a
+      UNIX system.</p>
+    <p>The <c>sasl</c> application includes the example Erlang
+      module <c>target_system.erl</c>, which contains functions for
+      creating and installing a target system. This module is used in
+      the following examples. The source code of the module is listed
+      in <seealso marker="#listing of target system">
+      Listing of target_system.erl</seealso></p>
 
   <section>
     <marker id="create"/>
     <title>Creating a Target System</title>
     <p>It is assumed that you have a working Erlang/OTP system structured
-      according to the OTP Design Principles.</p>
-    <p><em>Step 1.</em> First create a <c>.rel</c> file (see <seealso
-      marker="sasl:rel">rel(4)</seealso>) that specifies the <c>erts</c>
-      version and lists all applications that should be included in the
-      new basic target system. An example is the following
-      <c>mysystem.rel</c> file:</p>
+      according to the OTP design principles.</p>
+    <p><em>Step 1.</em> Create a <c>.rel</c> file (see the
+      <seealso marker="sasl:rel">rel(4)</seealso> manual page in
+      SASL), which specifies the ERTS version and lists
+      all applications that are to be included in the new basic target
+      system. An example is the following <c>mysystem.rel</c> file:</p>
     <code type="none">
 %% mysystem.rel
 {release,
@@ -91,23 +90,23 @@
   {pea, "1.0"}]}.</code>
     <p>The listed applications are not only original Erlang/OTP
       applications but possibly also new applications that you have
-      written yourself (here exemplified by the application
-      <c>pea</c>). </p>
-    <p><em>Step 2.</em> From the directory where the <c>mysystem.rel</c>
-      file reside, start the Erlang/OTP system:</p>
+      written (here exemplified by the application Pea (<c>pea</c>)).</p>
+    <p><em>Step 2.</em> Start Erlang/OTP from the directory where
+      the <c>mysystem.rel</c> file resides:</p>
     <pre>
 os> <input>erl -pa /home/user/target_system/myapps/pea-1.0/ebin</input></pre>
-    <p>where also the path to the <c>pea-1.0</c> ebin directory is
-      provided. </p>
-    <p><em>Step 3.</em> Now create the target system: </p>
+    <p>Here also the path to the <c>pea-1.0</c> ebin directory is
+      provided.</p>
+    <p><em>Step 3.</em> Create the target system:</p>
     <pre>
 1> <input>target_system:create("mysystem").</input></pre>
-    <p>The <c>target_system:create/1</c> function does the following:</p>
+    <p>The function <c>target_system:create/1</c> performs the
+      following:</p>
     <list type="ordered">
-      <item>Reads the <c>mysystem.rel</c> file, and creates a new file
-      <c>plain.rel</c> which is identical to former, except that it
-       only lists the <c>kernel</c> and <c>stdlib</c> applications. </item>
-      <item>From the <c>mysystem.rel</c> and <c>plain.rel</c> files
+      <item>Reads the file <c>mysystem.rel</c> and creates a new file
+      <c>plain.rel</c> that is identical to the former, except that it
+       only lists the Kernel and STDLIB applications.</item>
+      <item>From the files <c>mysystem.rel</c> and <c>plain.rel</c>
        creates the files <c>mysystem.script</c>,
       <c>mysystem.boot</c>, <c>plain.script</c>, and
       <c>plain.boot</c> through a call to
@@ -124,26 +123,26 @@ releases/mysystem.rel
 lib/kernel-2.16.4/
 lib/stdlib-1.19.4/
 lib/sasl-2.3.4/
-lib/pea-1.0/        </code>
+lib/pea-1.0/</code>
         <p>The file <c>releases/FIRST/start.boot</c> is a copy of our
           <c>mysystem.boot</c></p>
 	<p>The release resource file <c>mysystem.rel</c> is duplicated
           in the tar file. Originally, this file was only stored in
-          the <c>releases</c> directory in order to make it possible
+          the <c>releases</c> directory to make it possible
           for the <c>release_handler</c> to extract this file
           separately. After unpacking the tar
           file, <c>release_handler</c> would automatically copy the
           file to <c>releases/FIRST</c>. However, sometimes the tar
           file is unpacked without involving
-          the <c>release_handler</c> (e.g. when unpacking the first
-          target system) and therefore the file is now instead
+          the <c>release_handler</c> (for example, when unpacking the
+          first target system). The file is therefore now instead
           duplicated in the tar file so no manual copying is
-          necessary.</p>
+          needed.</p>
       </item>
-      <item>Creates the temporary directory <c>tmp</c> and extracts the tar file
-      <c>mysystem.tar.gz</c> into that directory. </item>
-      <item>Deletes the <c>erl</c> and <c>start</c> files from
-      <c>tmp/erts-5.10.4/bin</c>. These files will be created again from
+      <item>Creates the temporary directory <c>tmp</c> and extracts
+      the tar file <c>mysystem.tar.gz</c> into that directory.</item>
+      <item>Deletes the files <c>erl</c> and <c>start</c> from
+      <c>tmp/erts-5.10.4/bin</c>. These files are created again from
       source when installing the release.</item>
       <item>Creates the directory <c>tmp/bin</c>.</item>
       <item>Copies the previously created file <c>plain.boot</c> to
@@ -151,31 +150,31 @@ lib/pea-1.0/        </code>
       <item>Copies the files <c>epmd</c>, <c>run_erl</c>, and
       <c>to_erl</c> from the directory <c>tmp/erts-5.10.4/bin</c> to
        the directory <c>tmp/bin</c>.</item>
-      <item>Creates the directory <c>tmp/log</c>, which will be used
+      <item>Creates the directory <c>tmp/log</c>, which is used
        if the system is started as embedded with the <c>bin/start</c>
        script.</item>
       <item>Creates the file <c>tmp/releases/start_erl.data</c> with
        the contents "5.10.4 FIRST". This file is to be passed as data
-       file to the <c>start_erl</c> script.
-      </item>
+       file to the <c>start_erl</c> script.</item>
       <item>Recreates the file <c>mysystem.tar.gz</c> from the directories
-       in the directory <c>tmp</c>, and removes <c>tmp</c>.</item>
+       in the directory <c>tmp</c> and removes <c>tmp</c>.</item>
     </list>
   </section>
 
   <section>
     <title>Installing a Target System</title>
     <p><em>Step 4.</em> Install the created target system in a
-      suitable directory. </p>
+      suitable directory.</p>
     <pre>
 2> <input>target_system:install("mysystem", "/usr/local/erl-target").</input></pre>
-    <p>The function <c>target_system:install/2</c> does the following:
+    <p>The function <c>target_system:install/2</c> performs the following:
       </p>
     <list type="ordered">
       <item>Extracts the tar file <c>mysystem.tar.gz</c> into the target
        directory <c>/usr/local/erl-target</c>.</item>
-      <item>In the target directory reads the file <c>releases/start_erl.data</c>
-       in order to find the Erlang runtime system version ("5.10.4").</item>
+      <item>In the target directory reads the file
+      <c>releases/start_erl.data</c> to find the Erlang runtime system
+       version ("5.10.4").</item>
       <item>Substitutes <c>%FINAL_ROOTDIR%</c> and <c>%EMU%</c> for
       <c>/usr/local/erl-target</c> and <c>beam</c>, respectively, in
        the files <c>erl.src</c>, <c>start.src</c>, and
@@ -184,97 +183,102 @@ lib/pea-1.0/        </code>
       <c>start</c>, and <c>run_erl</c> in the target <c>bin</c>
        directory.</item>
       <item>Finally the target <c>releases/RELEASES</c> file is created
-       from data in the <c>releases/mysystem.rel</c> file.</item>
+       from data in the file <c>releases/mysystem.rel</c>.</item>
     </list>
   </section>
 
   <section>
     <marker id="start"/>
     <title>Starting a Target System</title>
-    <p>Now we have a target system that can be started in various ways.</p>
-    <p>We start it as a <em>basic target system</em> by invoking</p>
+    <p>Now we have a target system that can be started in various ways.
+      We start it as a <em>basic target system</em> by invoking:</p>
     <pre>
 os> <input>/usr/local/erl-target/bin/erl</input></pre>
-    <p>where only the <c>kernel</c> and <c>stdlib</c> applications are
-      started, i.e. the system is started as an ordinary development
-      system. There are only two files needed for all this to work:
-      <c>bin/erl</c> file (obtained from <c>erts-5.10.4/bin/erl.src</c>)
-      and the <c>bin/start.boot</c> file (a copy of <c>plain.boot</c>).</p>
+    <p>Here only the Kernel and STDLIB applications are
+      started, that is, the system is started as an ordinary development
+      system. Only two files are needed for all this to work:</p>
+      <list type="ordered">
+	<item><c>bin/erl</c> (obtained from
+	<c>erts-5.10.4/bin/erl.src</c>)</item>
+	<item><c>bin/start.boot</c> (a copy of
+	<c>plain.boot</c>)</item>
+      </list>
     <p>We can also start a distributed system (requires <c>bin/epmd</c>).</p>
     <p>To start all applications specified in the original
-      <c>mysystem.rel</c> file, use the <c>-boot</c> flag as follows:</p>
+      <c>mysystem.rel</c> file, use flag <c>-boot</c> as follows:</p>
     <pre>
 os> <input>/usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FIRST/start</input></pre>
-    <p>We start a <em>simple target system</em> as above. The only difference
-      is that also the file <c>releases/RELEASES</c> is present for
-      code replacement in run-time to work.</p>
-    <p>To start an <em>embedded target system</em> the shell script
-      <c>bin/start</c> is used. That shell script calls
+    <p>We start a <em>simple target system</em> as above. The only
+      difference is that also the file <c>releases/RELEASES</c> is
+      present for code replacement in runtime to work.</p>
+    <p>To start an <em>embedded target system</em>, the shell script
+      <c>bin/start</c> is used. The script calls
       <c>bin/run_erl</c>, which in turn calls <c>bin/start_erl</c>
       (roughly, <c>start_erl</c> is an embedded variant of
-      <c>erl</c>). </p>
+      <c>erl</c>).</p>
     <p>The shell script <c>start</c>, which is generated from
       erts-5.10.4/bin/start.src during installation, is only an
-      example. You should edit it to suite your needs. Typically it is
+      example. Edit it to suite your needs. Typically it is
       executed when the UNIX system boots.</p>
     <p><c>run_erl</c> is a wrapper that provides logging of output from
-      the run-time system to file. It also provides a simple mechanism
+      the runtime system to file. It also provides a simple mechanism
       for attaching to the Erlang shell (<c>to_erl</c>).</p>
-    <p><c>start_erl</c> requires the root directory
-      (<c>"/usr/local/erl-target"</c>), the releases directory
-      (<c>"/usr/local/erl-target/releases"</c>), and the location of
-      the <c>start_erl.data</c> file. It reads the run-time system
-      version (<c>"5.10.4"</c>) and release version (<c>"FIRST"</c>) from
-      the <c>start_erl.data</c> file, starts the run-time system of the
-      version found, and provides <c>-boot</c> flag specifying the boot
-      file of the release version found
-      (<c>"releases/FIRST/start.boot"</c>).</p>
-    <p><c>start_erl</c> also assumes that there is <c>sys.config</c> in
-      release version directory (<c>"releases/FIRST/sys.config"</c>). That
-      is the topic of the next section (see below).</p>
-    <p>The <c>start_erl</c> shell script should normally not be
+    <p><c>start_erl</c> requires:</p>
+     <list type="ordered">
+	<item>The root directory (<c>"/usr/local/erl-target"</c>)</item>
+	<item>The releases directory
+	(<c>"/usr/local/erl-target/releases"</c></item>
+	<item>The location of the file <c>start_erl.data</c></item>
+     </list>
+     <p>It performs the following:</p>
+     <list type="ordered">
+	<item>Reads the runtime system version (<c>"5.10.4"</c>) and
+	release version (<c>"FIRST"</c>) from the file
+	<c>start_erl.data</c>.</item>
+	<item>Starts the runtime system of the version found.</item>
+	<item>Provides the flag <c>-boot</c> specifying the boot
+	file of the release version found
+	(<c>"releases/FIRST/start.boot"</c>).</item>
+     </list>
+    <p><c>start_erl</c> also assumes that there is <c>sys.config</c>
+      in the release version directory (<c>"releases/FIRST/sys.config"</c>).
+      That is the topic of the next section.</p>
+    <p>The <c>start_erl</c> shell script is normally not to be
       altered by the user.</p>
   </section>
 
   <section>
     <title>System Configuration Parameters</title>
-    <p>As was pointed out above <c>start_erl</c> requires a
-      <c>sys.config</c> in the release version directory
-      (<c>"releases/FIRST/sys.config"</c>). If there is no such a
-      file, the system start will fail. Hence such a file has to
-      be added as well.</p>
-    <p></p>
-    <p>If you have system configuration data that are neither file
-      location dependent nor site dependent, it may be convenient to
-      create the <c>sys.config</c> early, so that it becomes a part of
+    <p>As was mentioned in the previous section, <c>start_erl</c>
+      requires a <c>sys.config</c> in the release version directory
+      (<c>"releases/FIRST/sys.config"</c>). If there is no such
+      file, the system start fails. Such a file must therefore
+      also be added.</p>
+    <p>If you have system configuration data that is neither
+      file-location-dependent nor site-dependent, it can be convenient
+      to create <c>sys.config</c> early, so it becomes part of
       the target system tar file created by
-      <c>target_system:create/1</c>. In fact, if you create, in the
-      current directory, not only the <c>mysystem.rel</c> file, but
-      also a <c>sys.config</c> file, that latter file will be tacitly
+      <c>target_system:create/1</c>. In fact, if you in the
+      current directory create not only the file <c>mysystem.rel</c>,
+      but also file <c>sys.config</c>, the latter file is tacitly
       put in the appropriate directory.</p>
   </section>
 
   <section>
-    <title>Differences from the Install Script</title>
-    <p>The above <c>install/2</c> procedure differs somewhat from that
+    <title>Differences From the Install Script</title>
+    <p>The previous <c>install/2</c> procedure differs somewhat from that
       of the ordinary <c>Install</c> shell script. In fact, <c>create/1</c>
       makes the release package as complete as possible, and leave to the
-      <c>install/2</c> procedure to finish by only considering location
-      dependent files.</p>
+      <c>install/2</c> procedure to finish by only considering
+      location-dependent files.</p>
   </section>
 
   <section>
     <title>Creating the Next Version</title>
-
-    <p>
-      In this example the <c>pea</c> application has been changed, and
-      so are <c>erts</c>, <c>kernel</c>, <c>stdlib</c> and
-      <c>sasl</c>.
-    </p>
-
-    <p>
-      <em>Step 1.</em> Create the <c>.rel</c> file:
-    </p>
+    <p>In this example the Pea application has been changed, and
+      so are the applications ERTS, Kernel, STDLIB
+      and SASL.</p>
+    <p><em>Step 1.</em> Create the file <c>.rel</c>:</p>
     <code type="none">
 %% mysystem2.rel
 {release,
@@ -284,65 +288,49 @@ os> <input>/usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FI
   {stdlib, "2.0"},
   {sasl, "2.4"},
   {pea, "2.0"}]}.</code>
-    <p>
-      <em>Step 2.</em> Create the application upgrade file (see
-      <seealso marker="sasl:appup">appup(4)</seealso>) for <c>pea</c>,
-      for example:
-    </p>
+    <p><em>Step 2.</em> Create the application upgrade file (see the
+      <seealso marker="sasl:appup">appup(4)</seealso> manual page in
+      SASL) for Pea, for example:</p>
     <code type="none">
 %% pea.appup
 {"2.0",
  [{"1.0",[{load_module,pea_lib}]}],
  [{"1.0",[{load_module,pea_lib}]}]}.</code>
-    <p>
-      <em>Step 3.</em> From the directory where the
-      <c>mysystem2.rel</c> file reside, start the Erlang/OTP system:
-    </p>
+    <p><em>Step 3.</em> From the directory where the file
+      <c>mysystem2.rel</c> resides, start the Erlang/OTP system,
+      giving the path to the new version of Pea:</p>
     <pre>
 os> <input>erl -pa /home/user/target_system/myapps/pea-2.0/ebin</input></pre>
-    <p>giving the path to the new version of <c>pea</c>. </p>
-
-    <p>
-      <em>Step 4.</em> Create the release upgrade file (see <seealso
-      marker="sasl:relup">relup(4)</seealso>):
-    </p>
+    <p><em>Step 4.</em> Create the release upgrade file (see the
+      <seealso marker="sasl:relup">relup(4)</seealso> manual page in
+      SASL):</p>
     <pre>
-1> <input>systools:make_relup("mysystem2",["mysystem"],["mysystem"],[{path,["/home/user/target_system/myapps/pea-1.0/ebin","/my/old/erlang/lib/*/ebin"]}]).</input></pre>
-    <p>
-      where <c>"mysystem"</c> is the base release and
-      <c>"mysystem2"</c> is the release to upgrade to.
-    </p>
-    <p>
-      Note that the <c>path</c> option is used for pointing out the
+1> <input>systools:make_relup("mysystem2",["mysystem"],["mysystem"],
+    [{path,["/home/user/target_system/myapps/pea-1.0/ebin",
+    "/my/old/erlang/lib/*/ebin"]}]).</input></pre>
+    <p>Here <c>"mysystem"</c> is the base release and
+      <c>"mysystem2"</c> is the release to upgrade to.</p>
+    <p>The <c>path</c> option is used for pointing out the
       old version of all applications. (The new versions are already
-      in the code path - assuming of course that the erlang node on
+      in the code path - assuming of course that the Erlang node on
       which this is executed is running the correct version of
-      Erlang/OTP.)
-    </p>
-    <p>
-      <em>Step 5.</em> Create the new release:
-    </p>
+      Erlang/OTP.)</p>
+    <p><em>Step 5.</em> Create the new release:</p>
     <pre>
 2> <input>target_system:create("mysystem2").</input></pre>
-    <p>
-      Given that the <c>relup</c> file generated in step 4 above is
-      now located in the current directory, it will automatically be
-      included in the release package.
-    </p>
+    <p>Given that the file <c>relup</c> generated in Step 4 is
+      now located in the current directory, it is automatically
+      included in the release package.</p>
   </section>
 
   <section>
     <title>Upgrading the Target System</title>
-    <p>
-      This part is done on the target node, and for this example we
+    <p>This part is done on the target node, and for this example we
       want the node to be running as an embedded system with the
-      <c>-heart</c> option, allowing automatic restart of the
-      node. See <seealso marker="#start">Starting a Target
-      System</seealso> above for more information.
-    </p>
-    <p>
-      We add <c>-heart</c> to <c>bin/start</c>:
-    </p>
+      <c>-heart</c> option, allowing automatic restart of the node.
+      For more information, see  <seealso marker="#start">
+      Starting a Target System</seealso>.</p>
+    <p>We add <c>-heart</c> to <c>bin/start</c>:</p>
     <code type="none">
 #!/bin/sh
 ROOTDIR=/usr/local/erl-target/
@@ -354,36 +342,27 @@ fi
 
 START_ERL_DATA=${1:-$RELDIR/start_erl.data}
 
-$ROOTDIR/bin/run_erl -daemon /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl $ROOTDIR $RELDIR $START_ERL_DATA -heart</code>
-    <p>
-      And we use the simplest possible <c>sys.config</c>, which we
-      store in <c>releases/FIRST</c>:
-    </p>
+$ROOTDIR/bin/run_erl -daemon /tmp/ $ROOTDIR/log "exec $ROOTDIR/bin/start_erl $ROOTDIR\
+$RELDIR $START_ERL_DATA -heart</code>
+    <p>We use the simplest possible <c>sys.config</c>, which we
+      store in <c>releases/FIRST</c>:</p>
     <code type="none">
 %% sys.config
 [].</code>
-    <p>
-      Finally, in order to prepare the upgrade, we need to put the new
+    <p>Finally, to prepare the upgrade, we must put the new
       release package in the <c>releases</c> directory of the first
-      target system:
-    </p>
+      target system:</p>
     <pre>
 os> <input>cp mysystem2.tar.gz /usr/local/erl-target/releases</input></pre>
-    <p>
-      And assuming that the node has been started like this:
-    </p>
+    <p>Assuming that the node has been started as follows:</p>
     <pre>
 os> <input>/usr/local/erl-target/bin/start</input></pre>
-    <p>
-      it can be accessed like this:
-    </p>
+    <p>It can be accessed as follows:</p>
     <pre>
 os> <input>/usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.1</input></pre>
-    <p>
-      Also note that logs can be found in
+    <p>Logs can be found in
       <c>/usr/local/erl-target/log</c>. This directory is specified as
-      an argument to <c>run_erl</c>in the start script listed above.
-    </p>
+      an argument to <c>run_erl</c>in the start script listed above.</p>
     <p>
       <em>Step 1.</em> Unpack the release:
     </p>
@@ -402,18 +381,19 @@ heart: Tue Apr  1 12:15:11 2014: Executed "/usr/local/erl-target/bin/start /usr/
       The above return value and output after the call to
       <c>release_handler:install_release/1</c> means that the
       <c>release_handler</c> has restarted the node by using
-      <c>heart</c>. This will always be done when the upgrade involves
-      a change of <c>erts</c>, <c>kernel</c>, <c>stdlib</c> or
-      <c>sasl</c>. See <seealso marker="upgrade">Upgrade when
-      Erlang/OTP has Changed</seealso> for more infomation about this.
+      <c>heart</c>. This is always done when the upgrade involves
+      a change of the applications ERTS, Kernel,
+      STDLIB, or SASL. For more information, see
+      <seealso marker="upgrade">
+      Upgrade when Erlang/OTP has Changed</seealso>.
     </p>
     <p>
-      The node will be accessible via a new pipe:
+      The node is accessible through a new pipe:
     </p>
     <pre>
 os> <input>/usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2</input></pre>
     <p>
-      Let's see which releases we have in our system:
+      Check which releases there are in the system:
     </p>
     <pre>
 1> <input>release_handler:which_releases().</input>
@@ -426,7 +406,7 @@ os> <input>/usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2</input></pre>
     <p>
       Our new release, "SECOND", is now the current release, but we
       can also see that our "FIRST" release is still permanent. This
-      means that if the node would be restarted at this point, it
+      means that if the node would be restarted now, it
       would come up running the "FIRST" release again.
     </p>
     <p>
@@ -434,11 +414,9 @@ os> <input>/usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2</input></pre>
     </p>
     <pre>
 2> <input>release_handler:make_permanent("SECOND").</input></pre>
-
     <p>
-      Now look at the releases again:
+      Check the releases again:
     </p>
-
     <pre>
 3> <input>release_handler:which_releases().</input>
 <output>[{"MYSYSTEM","SECOND",
@@ -447,19 +425,16 @@ os> <input>/usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2</input></pre>
  {"MYSYSTEM","FIRST",
   ["kernel-2.16.4","stdlib-1.19.4","sasl-2.3.4","pea-1.0"],
   old}]</output></pre>
-
   <p>
-    Here we see that the new release version is <c>permanent</c>, so
-    it would be safe to restart the node.
-  </p>
-
+    We see that the new release version is <c>permanent</c>, so
+    it would be safe to restart the node.</p>
   </section>
 
   <section>
+    <marker id="listing of target system"/>
     <title>Listing of target_system.erl</title>
     <p>This module can also be found in the <c>examples</c> directory
-      of the <c>sasl</c> application.</p>
+      of the SASL application.</p>
     <codeinclude file="../../../lib/sasl/examples/src/target_system.erl" tag="%module" type="erl"></codeinclude>
-
   </section>
 </chapter>
diff --git a/system/doc/system_principles/error_logging.xml b/system/doc/system_principles/error_logging.xml
index 80d5211323..3a82f4e0e0 100644
--- a/system/doc/system_principles/error_logging.xml
+++ b/system/doc/system_principles/error_logging.xml
@@ -28,41 +28,43 @@
     <rev></rev>
     <file>error_logging.xml</file>
   </header>
+  <marker id="error logging"></marker>
 
   <section>
     <title>Error Information From the Runtime System</title>
     <p>Error information from the runtime system, that is, information
-      about a process terminating due to an uncaught error exception,
+      about a process terminating because of an uncaught error exception,
       is by default written to terminal (tty):</p>
     <code type="none"><![CDATA[
 =ERROR REPORT==== 9-Dec-2003::13:25:02 ===
 Error in process <0.27.0> with exit value: {{badmatch,[1,2,3]},[{m,f,1},{shell,eval_loop,2}]}]]></code>
     <p>The error information is handled by the <em>error logger</em>, a
       system process registered as <c>error_logger</c>. This process
-      receives all error messages from the Erlang runtime system and
-      also from the standard behaviours and different Erlang/OTP
+      receives all error messages from the Erlang runtime system as
+      well as from the standard behaviours and different Erlang/OTP
       applications.</p>
-    <p>The exit reasons (such as <c>badarg</c> above) used by
+    <p>The exit reasons (such as <c>badarg</c>) used by
       the runtime system are described in
-      <seealso marker="doc/reference_manual:errors#exit_reasons">Errors and Error Handling</seealso>
-      in the Erlang Reference Manual.</p>
-    <p>The process <c>error_logger</c> and its user interface (with
-      the same name) are described in
-      <seealso marker="kernel:error_logger">error_logger(3)</seealso>.
-      It is possible to configure the system so that error information
-      is written to file instead/as well as tty. Also, it is possible
-      for user defined applications to send and format error
-      information using <c>error_logger</c>.</p>
+      <seealso marker="doc/reference_manual:errors#exit_reasons">
+      Errors and Error Handling</seealso>.</p>
+    <p>For information about the process <c>error_logger</c> and its user
+      interface (with the same name), see the
+      <seealso marker="kernel:error_logger">error_logger(3)</seealso>
+      manual page in Kernel. The system can be configured so that
+      error information
+      is written to file or to tty, or both. In addition, user-defined
+      applications can send and format error information using
+      <c>error_logger</c>.</p>
   </section>
 
   <section>
     <title>SASL Error Logging</title>
-    <p>The standard behaviors (<c>supervisor</c>, <c>gen_server</c>,
-      etc.) sends progress and error information to <c>error_logger</c>.
-      If the SASL application is started, this information is written
-      to tty as well. See
+    <p>The standard behaviours (<c>supervisor</c>, <c>gen_server</c>,
+      and so on) send progress and error information to <c>error_logger</c>.
+      If the SASL application is started, this information is
+      written to tty as well. For more information, see
       <seealso marker="sasl:error_logging">SASL Error Logging</seealso>
-      in the SASL User's Guide for further information.</p>
+      in the SASL User's Guide.</p>
     <pre>
 % <input>erl -boot start_sasl</input>
 Erlang (BEAM) emulator version 5.4.13 [hipe] [threads:0] [kernel-poll]
diff --git a/system/doc/system_principles/system_principles.xml b/system/doc/system_principles/system_principles.xml
index 79ed86cd9f..5718e8a3f6 100644
--- a/system/doc/system_principles/system_principles.xml
+++ b/system/doc/system_principles/system_principles.xml
@@ -28,35 +28,41 @@
     <rev></rev>
     <file>system_principles.xml</file>
   </header>
+  <marker id="system principles"></marker>
 
   <section>
     <title>Starting the System</title>
-    <p>An Erlang runtime system is started with the command <c>erl</c>:</p>
+    <p>An Erlang runtime system is started with command <c>erl</c>:</p>
     <pre>
 % <input>erl</input>
 Erlang/OTP 17 [erts-6.0] [hipe] [smp:8:8]
 
 Eshell V6.0  (abort with ^G)
 1> </pre>
-    <p><c>erl</c> understands a number of command line arguments, see
-      <c>erl(1)</c>. A number of them are also described in this chapter.</p>
-    <p>Application programs can access the values of the command line
-      arguments by calling one of the functions
-      <c>init:get_argument(Key)</c>, or <c>init:get_arguments()</c>.
-      See <c>init(3)</c>.</p>
+    <p><c>erl</c> understands a number of command-line arguments, see
+      the <seealso marker="erts:erl">erl(1)</seealso>  manual page in
+      ERTS. Some of them are also described in this chapter.</p>
+    <p>Application programs can access the values of the command-line
+      arguments by calling the function <c>init:get_argument(Key)</c>
+      or <c>init:get_arguments()</c>. See the
+      <seealso marker="erts:init">init(3)</seealso> manual page in
+      ERTS.</p>
   </section>
 
   <section>
     <title>Restarting and Stopping the System</title>
-    <p>The runtime system can be halted by calling <c>halt/0,1</c>.
-      See <c>erlang(3)</c>.</p>
-    <p>The module <c>init</c> contains function for restarting,
-      rebooting and stopping the runtime system. See <c>init(3)</c>.</p>
+    <p>The runtime system is halted by calling <c>halt/0,1</c>. For
+      details, see the <seealso marker="erts:erlang">erlang(3)</seealso>
+      manual page in ERTS.</p>
+    <p>The module <c>init</c> contains functions for restarting,
+      rebooting, and stopping the runtime system:</p>
     <pre>
 init:restart()
 init:reboot()
 init:stop()</pre>
-    <p>Also, the runtime system will terminate if the Erlang shell is
+    <p>For details, see the <seealso marker="erts:init">init(3)</seealso>
+      manual page in ERTS.</p>
+    <p>The runtime system terminates if the Erlang shell is
       terminated.</p>
   </section>
 
@@ -69,14 +75,15 @@ init:stop()</pre>
     <p>A boot script file has the extension <c>.script</c>.
       The runtime system uses a binary version of the script. This
       <em>binary boot script</em> file has the extension <c>.boot</c>.</p>
-    <p>Which boot script to use is specified by the command line flag
-      <c>-boot</c>. The extension <c>.boot</c> should be omitted.
-      Example, using the boot script <c>start_all.boot</c>:</p>
+    <p>Which boot script to use is specified by the command-line flag
+      <c>-boot</c>. The extension <c>.boot</c> is to be omitted.
+      For example, using the boot script <c>start_all.boot</c>:</p>
     <pre>
 % <input>erl -boot start_all</input></pre>
     <p>If no boot script is specified, it defaults to
-      <c>ROOT/bin/start</c>, see Default Boot Scripts below.</p>
-    <p>The command line flag <c>-init_debug</c> makes the <c>init</c>
+      <c>ROOT/bin/start</c>, see <seealso marker="#default_boot_scripts">
+      Default Boot Scripts</seealso>.</p>
+    <p>The command-line flag <c>-init_debug</c> makes the <c>init</c>
       process write some debug information while interpreting the boot
       script:</p>
     <pre>
@@ -87,59 +94,55 @@ init:stop()</pre>
 {start,heart}
 {start,error_logger}
 ...</pre>
-    <p>See <c>script(4)</c> for a detailed description of the syntax
-      and contents of the boot script.</p>
+    <p>For a detailed description of the syntax and contents of the
+    boot script, see the <c>script(4)</c> manual page in SASL.</p>
 
     <section>
+      <marker id="default_boot_scripts"></marker>
       <title>Default Boot Scripts</title>
-      <p>Erlang/OTP comes with two boot scripts:</p>
-      <taglist>
-        <tag><c>start_clean.boot</c></tag>
-        <item>
-          <p>Loads the code for and starts the applications Kernel and
-            STDLIB.</p>
-        </item>
-        <tag><c>start_sasl.boot</c></tag>
-        <item>
-          <p>Loads the code for and starts the applications Kernel,
-            STDLIB and SASL.</p>
-        </item>
-        <tag><c>no_dot_erlang.boot</c></tag>
-        <item>
-          <p>Loads the code for and starts the applications Kernel and
-          STDLIB, skips loading the <c>.erlang</c> file.
-	  Useful for scripts and other tools that should be behave the
-	  same regardless of user preferences.
-	  </p>
-        </item>
-      </taglist>
+      <p>Erlang/OTP comes with these boot scripts:</p>
+      <list type="bulleted">
+	<item><c>start_clean.boot</c> - Loads the code for and starts
+	the applications Kernel and STDLIB.</item>
+	<item><c>start_sasl.boot</c> - Loads the code for and starts
+	the applications Kernel, STDLIB, and
+	SASL).</item>
+	<item><c>no_dot_erlang.boot</c> - Loads the code for and
+	starts the applications Kernel and STDLIB.
+	Skips loading the file <c>.erlang</c>. Useful for scripts and
+	other tools that are to behave the same irrespective of user
+	preferences.</item>
+      </list>
       <p>Which of <c>start_clean</c> and <c>start_sasl</c> to use as
         default is decided by the user when installing Erlang/OTP using
         <c>Install</c>. The user is asked "Do you want to use a minimal
         system startup instead of the SASL startup". If the answer is
         yes, then <c>start_clean</c> is used, otherwise
-        <c>start_sasl</c> is used. A copy of the selected boot script
-        is made, named <c>start.boot</c> and placed in
-        the <c>ROOT/bin</c> directory.</p>
+        <c>start_sasl</c> is used. A copy of the selected boot script is
+	made, named <c>start.boot</c> and placed in directory
+        <c>ROOT/bin</c>.</p>
     </section>
 
     <section>
       <title>User-Defined Boot Scripts</title>
       <p>It is sometimes useful or necessary to create a user-defined
         boot script. This is true especially when running Erlang in
-        embedded mode, see <seealso marker="#code_loading">Code Loading Strategy</seealso>.</p>
-      <p>It is possible to write a boot script manually.
-        The recommended way to create a boot script, however, is to
-        generate the boot script from a release resource file
-        <c>Name.rel</c>, using the function
+        embedded mode, see <seealso marker="#code_loading">
+        Code Loading Strategy</seealso>.</p>
+      <p>A boot script can be written manually. However, it is
+        recommended to create a boot script by generating it from a
+        release resource file <c>Name.rel</c>, using the function
         <c>systools:make_script/1,2</c>. This requires that the source
         code is structured as applications according to the OTP design
         principles. (The program does not have to be started in terms of
-        OTP applications but can be plain Erlang).</p>
-      <p>Read more about <c>.rel</c> files in OTP Design Principles and
-        <c>rel(4)</c>.</p>
+        OTP applications, but can be plain Erlang).</p>
+      <p>For more information about <c>.rel</c> files, see
+        <seealso marker="otp design principles">
+        OTP Design Principles</seealso> and the
+        <seealso marker="sasl:rel">rel(4)</seealso> manual page in
+	SASL.</p>
       <p>The binary boot script file <c>Name.boot</c> is generated from
-        the boot script file <c>Name.script</c> using the function
+        the boot script file <c>Name.script</c>, using the function
         <c>systools:script2boot(File)</c>.</p>
     </section>
   </section>
@@ -148,16 +151,17 @@ init:stop()</pre>
     <marker id="code_loading"></marker>
     <title>Code Loading Strategy</title>
     <p>The runtime system can be started in either <em>embedded</em> or
-      <em>interactive</em> mode. Which one is decided by the command
-      line flag <c>-mode</c>.</p>
+      <em>interactive</em> mode. Which one is decided by the
+      command-line flag <c>-mode</c>.</p>
     <pre>
 % <input>erl -mode embedded</input></pre>
     <p>Default mode is <c>interactive</c>.</p>
+    <p>The mode properties are as follows:</p>
     <list type="bulleted">
-      <item>In embedded mode, all code is loaded during system start-up
+      <item>In embedded mode, all code is loaded during system startup
        according to the boot script. (Code can also be loaded later
-       by explicitly ordering the code server to do so).</item>
-      <item>In interactive mode, code is dynamically loaded when first
+       by explicitly ordering the code server to do so.)</item>
+      <item>In interactive mode, the code is dynamically loaded when first
        referenced. When a call to a function in a module is made, and
        the module is not loaded, the code server searches the code path
        and loads the module into the system.</item>
@@ -165,21 +169,21 @@ init:stop()</pre>
     <p>Initially, the code path consists of the current
       working directory and all object code directories under
       <c>ROOT/lib</c>, where <c>ROOT</c> is the installation directory
-      of Erlang/OTP. Directories can be named <c>Name[-Vsn]</c> and
-      the code server, by default, chooses the directory with
+      of Erlang/OTP. Directories can be named <c>Name[-Vsn]</c>. The
+      code server, by default, chooses the directory with
       the highest version number among those which have the same
       <c>Name</c>. The <c>-Vsn</c> suffix is optional. If an
       <c>ebin</c> directory exists under the <c>Name[-Vsn]</c>
-      directory, it is this directory which is added to the code path.</p>
-    <p>The code path can be extended by using the command line flags
-      <c>-pa Directories</c> and <c>-pz Directories</c>. These will add
-      <c>Directories</c> to the head or end of the code path,
-      respectively. Example</p>
+      directory, this directory is added to the code path.</p>
+    <p>The code path can be extended by using the command-line flags
+      <c>-pa Directories</c> and <c>-pz Directories</c>. These add
+      <c>Directories</c> to the head or the end of the code path,
+      respectively. Example:</p>
     <pre>
 % <input>erl -pa /home/arne/mycode</input></pre>
     <p>The code server module <c>code</c> contains a number of
-      functions for modifying and checking the search path, see
-      <c>code(3)</c>.</p>
+      functions for modifying and checking the search path, see the
+      <c>code(3)</c> manual page in Kernel.</p>
   </section>
 
   <section>
@@ -192,49 +196,65 @@ init:stop()</pre>
         <cell align="left" valign="middle"><em>Documented in</em></cell>
       </row>
       <row>
-        <cell align="left" valign="middle">module</cell>
+        <cell align="left" valign="middle">Module</cell>
         <cell align="left" valign="middle"><c>.erl</c></cell>
-        <cell align="left" valign="middle">Erlang Reference Manual</cell>
+        <cell align="left" valign="middle">
+          <seealso marker="erlang ref manual">
+          Erlang Reference Manual</seealso></cell>
       </row>
       <row>
-        <cell align="left" valign="middle">include file</cell>
+        <cell align="left" valign="middle">Include file</cell>
         <cell align="left" valign="middle"><c>.hrl</c></cell>
-        <cell align="left" valign="middle">Erlang Reference Manual</cell>
+        <cell align="left" valign="middle">
+          <seealso marker="erlang ref manual">
+          Erlang Reference Manual</seealso></cell>
       </row>
       <row>
-        <cell align="left" valign="middle">release resource file</cell>
+        <cell align="left" valign="middle">Release resource file</cell>
         <cell align="left" valign="middle"><c>.rel</c></cell>
-        <cell align="left" valign="middle"><c>rel(4)</c></cell>
+        <cell align="left" valign="middle">
+          <seealso marker="sasl:rel">rel(4)</seealso>
+          manual page in SASL</cell>
       </row>
       <row>
-        <cell align="left" valign="middle">application resource file</cell>
+        <cell align="left" valign="middle">Application resource file</cell>
         <cell align="left" valign="middle"><c>.app</c></cell>
-        <cell align="left" valign="middle"><c>app(4)</c></cell>
+        <cell align="left" valign="middle">
+          <seealso marker="kernel:app">app(4)</seealso>
+          manual page in Kernel</cell>
       </row>
       <row>
-        <cell align="left" valign="middle">boot script</cell>
+        <cell align="left" valign="middle">Boot script</cell>
         <cell align="left" valign="middle"><c>.script</c></cell>
-        <cell align="left" valign="middle"><c>script(4)</c></cell>
+        <cell align="left" valign="middle">
+          <seealso marker="sasl:script">script(4)</seealso>
+          manual page in SASL</cell>
       </row>
       <row>
-        <cell align="left" valign="middle">binary boot script</cell>
+        <cell align="left" valign="middle">Binary boot script</cell>
         <cell align="left" valign="middle"><c>.boot</c></cell>
         <cell align="left" valign="middle">-</cell>
       </row>
       <row>
-        <cell align="left" valign="middle">configuration file</cell>
+        <cell align="left" valign="middle">Configuration file</cell>
         <cell align="left" valign="middle"><c>.config</c></cell>
-        <cell align="left" valign="middle"><c>config(4)</c></cell>
+        <cell align="left" valign="middle">
+          <seealso marker="kernel:config">config(4)</seealso>
+          manual page in Kernel</cell>
       </row>
       <row>
-        <cell align="left" valign="middle">application upgrade file</cell>
+        <cell align="left" valign="middle">Application upgrade file</cell>
         <cell align="left" valign="middle"><c>.appup</c></cell>
-        <cell align="left" valign="middle"><c>appup(4)</c></cell>
+        <cell align="left" valign="middle">
+          <seealso marker="sasl:appup">appup(4)</seealso>
+          manual page in SASL</cell>
       </row>
       <row>
-        <cell align="left" valign="middle">release upgrade file</cell>
+        <cell align="left" valign="middle">Release upgrade file</cell>
         <cell align="left" valign="middle"><c>relup</c></cell>
-        <cell align="left" valign="middle"><c>relup(4)</c></cell>
+        <cell align="left" valign="middle">
+          <seealso marker="sasl:relup">relup(4)</seealso>
+          manual page in SASL</cell>
       </row>
       <tcaption>File Types</tcaption>
     </table>
diff --git a/system/doc/system_principles/upgrade.xml b/system/doc/system_principles/upgrade.xml
index 68e48da0b8..83e8128f94 100644
--- a/system/doc/system_principles/upgrade.xml
+++ b/system/doc/system_principles/upgrade.xml
@@ -31,88 +31,72 @@
     <rev></rev>
     <file>upgrade.xml</file>
   </header>
+  <marker id="upgrade section"></marker>
 
   <section>
     <title>Introduction</title>
-    <p>
-      As of Erlang/OTP 17, most applications deliver a valid
-      application upgrade (<c>appup</c>) file. In earlier releases, a
+    <marker id="upgrade"></marker>
+    <p>As of Erlang/OTP 17, most applications deliver a valid
+      application upgrade file (<c>appup</c>). In earlier releases, a
       majority of the applications in Erlang/OTP did not support
-      upgrade at all. Many of the applications use the
+      upgrade. Many of the applications use the
       <c>restart_application</c> instruction. These are applications
       for which it is not crucial to support real soft upgrade, for
-      instance tools and library applications. The
+      example, tools and library applications. The
       <c>restart_application</c> instruction
       ensures that all modules in the application are reloaded and
-      thereby running the new code.
-    </p>
+      thereby running the new code.</p>
   </section>
 
   <section>
-    <title>Upgrade of core applications</title>
-    <p>
-      The core applications ERTS, Kernel, STDLIB
+    <title>Upgrade of Core Applications</title>
+    <p>The core applications ERTS, Kernel, STDLIB,
       and SASL never allow real soft upgrade, but require the
       Erlang emulator to be restarted. This is indicated to the
       <c>release_handler</c> by the upgrade instruction
-      <c>restart_new_emulator</c>. This instruction will always be the
-      very first instruction executed, and it will restart the
+      <c>restart_new_emulator</c>. This instruction is always the
+      very first instruction executed, and it restarts the
       emulator with the new versions of the above mentioned core
-      applications and the old versions of all other
-      applications. When the node is back up all other upgrade instructions are
+      applications and the old versions of all other applications.
+      When the node is back up, all other upgrade instructions are
       executed, making sure each application is finally running its
-      new version.
-    </p>
-
-    <p>
-      It might seem strange to do a two-step upgrade instead of
+      new version.</p>
+    <p>It might seem strange to do a two-step upgrade instead of
       just restarting the emulator with the new version of all
       applications. The reason for this design decision is to allow
-      <c>code_change</c> functions to have side effects, for example changing
-      data on disk. It also makes sure that the upgrade mechanism for
-      non-core applications does not differ depending on whether or not
-      core applications are changed at the same time.
-    </p>
-
-    <p>
-      If, however, the more brutal variant is preferred, it is
-      possible to handwrite the release upgrade file using only the
+      <c>code_change</c> functions to have side effects, for example,
+      changing data on disk. It also guarantees that the upgrade
+      mechanism for non-core applications does not differ depending
+      on whether or not core applications are changed at the same time.</p>
+    <p>If, however, the more brutal variant is preferred, the
+      the release upgrade file can be handwritten using only the
       single upgrade instruction <c>restart_emulator</c>. This
-      instruction, in contrast to <c>restart_new_emulator</c>, will
-      cause the emulator to restart with the new versions of
-      <em>all</em> applications.
-    </p>
-
-    <p>
-      <em>Note</em> that if other instructions are included before
+      instruction, in contrast to <c>restart_new_emulator</c>,
+      causes the emulator to restart with the new versions of
+      <em>all</em> applications.</p>
+    <p><em>Note:</em> If other instructions are included before
       <c>restart_emulator</c> in the handwritten <c>relup</c> file,
-      they will be executed in the old emulator. This is a big risk
+      they are executed in the old emulator. This is a big risk
       since there is no guarantee that new beam code can be loaded
       into the old emulator. Adding instructions after
       <c>restart_emulator</c> has no effect as the
-      <c>release_handler</c> will not do any attempt at executing
-      them.
-    </p>
-
-    <p>
-      See <seealso marker="sasl:relup">relup(4)</seealso> for
-      information about the release upgrade file, and <seealso
-      marker="sasl:appup">appup(4)</seealso> for further information
-      about upgrade instructions.
-    </p>
+      <c>release_handler</c> will not execute them.</p>
+    <p>For information about the release upgrade file, see the
+      <seealso marker="sasl:relup">relup(4)</seealso> manual page
+      in SASL.
+      For more information about upgrade instructions, see the
+      <seealso marker="sasl:appup">appup(4)</seealso> manual page
+      in SASL.</p>
   </section>
 
   <section>
-    <title>Applications that still do not allow code upgrade</title>
-    <p>
-      A few applications, for instance HiPE do not support
-      upgrade at all. This is indicated by an application upgrade file
-      containing only <c>{Vsn,[],[]}</c>. Any attempt at creating a release
-      upgrade file with such input will fail.
-      The only way to force an upgrade involving applications like this is to
-      handwrite the <c>relup</c> file, preferably as described above
-      with only the <c>restart_emulator</c> instruction.
-    </p>
-
+    <title>Applications that Still do Not Allow Code Upgrade</title>
+    <p>A few applications, such as HiPE, do not support upgrade.
+      This is indicated by an application upgrade file containing only
+      <c>{Vsn,[],[]}</c>. Any attempt at creating a release upgrade file
+      with such input fails. The only way to force an upgrade involving
+      applications like this is to
+      handwrite the file <c>relup</c>, preferably as described above
+      with only the <c>restart_emulator</c> instruction.</p>
   </section>
 </chapter>
diff --git a/system/doc/system_principles/versions.xml b/system/doc/system_principles/versions.xml
index ff042f4a3b..25eb90f626 100644
--- a/system/doc/system_principles/versions.xml
+++ b/system/doc/system_principles/versions.xml
@@ -31,93 +31,99 @@
     <rev></rev>
     <file>versions.xml</file>
   </header>
-    <section><title>OTP Version</title>
+  <marker id="versions section"></marker>
+
+  <section>
+    <title>OTP Version</title>
     <p>As of OTP release 17, the OTP release number corresponds to
     the major part of the OTP version. The OTP version as a concept was
-    introduced in OTP 17. The <seealso marker="#version_scheme">version
-    scheme</seealso> used is described in more detail below.</p>
-
+    introduced in OTP 17. The version scheme used is described in detail in
+    <seealso marker="#version_scheme">Version Scheme</seealso>.</p>
     <p>OTP of a specific version is a set of applications of specific
     versions. The application versions identified by an OTP version
     corresponds to application versions that have been tested together
-    by the Erlang/OTP team at Ericsson AB. An OTP system can however be
+    by the Erlang/OTP team at Ericsson AB. An OTP system can, however, be
     put together with applications from different OTP versions. Such a
     combination of application versions has not been tested by the
     Erlang/OTP team. It is therefore <em>always preferred to use OTP
     applications from one single OTP version</em>.</p>
-
     <p>Release candidates have an <c>-rc&lt;N&gt;</c>
-    suffix. The suffix <c>-rc0</c> will be used during development up to
+    suffix. The suffix <c>-rc0</c> is used during development up to
     the first release candidate.</p>
 
-    <section><title>Retrieving Current OTP Version</title>
-    <p>In an OTP source code tree, the OTP version can be read from
-    the text file <c>&lt;OTP source root&gt;/OTP_VERSION</c>. The
-    absolute path to the file can be constructed by calling
-    <c>filename:join([<seealso marker="kernel:code#root_dir/0">code:root_dir()</seealso>, "OTP_VERSION"])</c>.</p>
-    <p>In an installed OTP development system, the OTP version can be read
-    from the text file <c>&lt;OTP installation root&gt;/releases/&lt;OTP release number&gt;/OTP_VERSION</c>.
-    The absolute path to the file can by constructed by calling
-    <c>filename:join([<seealso marker="kernel:code#root_dir/0">code:root_dir()</seealso>, "releases", <seealso marker="erts:erlang#system_info_otp_release">erlang:system_info(otp_release)</seealso>, "OTP_VERSION"]).</c></p>
-    <p>If the version read from the <c>OTP_VERSION</c> file in a
-    development system has a <c>**</c> suffix, the system has been
-    patched using the <c>otp_patch_apply</c> tool available to
-    licensed customers. In this case, the system consists of application
-    versions from multiple OTP versions. The version preceding the <c>**</c>
-    suffix corresponds to the OTP version of the base system that
-    has been patched. Note that if a development system is updated by
-    other means than <c>otp_patch_apply</c>, the <c>OTP_VERSION</c> file
-    may identify an incorrect OTP version.</p>
-
-    <p>No <c>OTP_VERSION</c> file will be placed in a
-    <seealso marker="create_target">target system</seealso> created
-    by OTP tools. This since one easily can create a target system
-    where it is hard to even determine the base OTP version. You may,
-    however, place such a file there yourself if you know the OTP
-    version.</p>
+    <section>
+      <title>Retrieving Current OTP Version</title>
+      <p>In an OTP source code tree, the OTP version can be read from
+      the text file <c>&lt;OTP source root&gt;/OTP_VERSION</c>. The
+      absolute path to the file can be constructed by calling
+      <c>filename:join([<seealso marker="kernel:code#root_dir/0">code:root_dir()</seealso>, "OTP_VERSION"])</c>.</p>
+      <p>In an installed OTP development system, the OTP version can be read
+      from the text file <c>&lt;OTP installation root&gt;/releases/&lt;OTP release number&gt;/OTP_VERSION</c>.
+      The absolute path to the file can by constructed by calling
+      <c>filename:join([<seealso marker="kernel:code#root_dir/0">code:root_dir()</seealso>, "releases", <seealso marker="erts:erlang#system_info_otp_release"> erlang:system_info(otp_release)</seealso>, "OTP_VERSION"]).</c></p>
+      <p>If the version read from the <c>OTP_VERSION</c> file in a
+      development system has a <c>**</c> suffix, the system has been
+      patched using the <c>otp_patch_apply</c> tool available to
+      licensed customers. In this case, the system consists of application
+      versions from multiple OTP versions. The version preceding the <c>**</c>
+      suffix corresponds to the OTP version of the base system that
+      has been patched. Notice that if a development system is updated by
+      other means than <c>otp_patch_apply</c>, the file <c>OTP_VERSION</c>
+      can identify an incorrect OTP version.</p>
+      <p>No <c>OTP_VERSION</c> file is placed in a
+      <seealso marker="create_target">target system</seealso> created
+      by OTP tools. This since one easily can create a target system
+      where it is hard to even determine the base OTP version. You can,
+      however, place such a file there if you know the OTP version.</p>
     </section>
 
-    <section><title>OTP Versions Table</title>
-    <p>The text file <c>&lt;OTP source root&gt;/otp_versions.table</c> that
-    is part of the source code contains information about all OTP versions
-    from OTP 17.0 up to current OTP version. Each line contains information
-    about application versions that are part of a specific OTP version, and
-    is on the format:</p>
-<pre>
-&lt;OtpVersion&gt; : &lt;ChangedAppVersions&gt; # &lt;UnchangedAppVersions&gt; :
-</pre>
-    <p><c>&lt;OtpVersion&gt;</c> is on the format <c>OTP-&lt;VSN&gt;</c>, i.e.,
-    the same as the git tag used to identify the source.
-    <c>&lt;ChangedAppVersions&gt;</c> and <c>&lt;UnchangedAppVersions&gt;</c>
-    are space separated lists of application versions on the
-    format <c>&lt;application&gt;-&lt;vsn&gt;</c>. 
-    <c>&lt;ChangedAppVersions&gt;</c> corresponds to changed applications
-    with new version numbers in this OTP version, and
-    <c>&lt;UnchangedAppVersions&gt;</c> corresponds to unchanged application
-    versions in this OTP version. Both of them might be empty, although
-    not at the same time. If &lt;ChangedAppVersions&gt; is empty, no changes
-    has been made that change the build result of any application. This could
-    for example be a pure bug fix of the build system. The order of lines
-    is undefined. All white space characters in this file are either space
-    (character 32) or line-break (character 10).</p>
-    <p>Using ordinary UNIX tools like <c>sed</c> and <c>grep</c> one
-    can easily find answers to various questions like:</p>
-    <taglist>
-      <tag>Which OTP versions are <c>kernel-3.0</c> part of?</tag>
-      <item><p><c> $ grep ' kernel-3\.0 ' otp_versions.table</c></p></item>
-      <tag>In which OTP version was <c>kernel-3.0</c> introduced?</tag>
-      <item><p><c> $ sed 's/#.*//;/ kernel-3\.0 /!d' otp_versions.table</c></p></item>
-    </taglist>
-    <p>The above commands give a bit more information than the exact answers,
-    but adequate information when manually searching for answers to these
-    questions.</p>
-    <warning><p>The format of the <c>otp_versions.table</c> might be subject
-    to changes during the OTP 17 release.</p></warning>
-    </section>
+    <section>
+      <title>OTP Versions Table</title>
+      <p>The text file <c>&lt;OTP source root&gt;/otp_versions.table</c>,
+      which is part of the source code, contains information about all
+      OTP versions from OTP 17.0 up to the current OTP version. Each line
+      contains information about application versions that are part of a
+      specific OTP version, and has the following format:</p>
+      <pre>
+&lt;OtpVersion&gt; : &lt;ChangedAppVersions&gt; # &lt;UnchangedAppVersions&gt; :</pre>
+      <p><c>&lt;OtpVersion&gt;</c> has the format <c>OTP-&lt;VSN&gt;</c>,
+      that is, the same as the git tag used to identify the source.</p>
+      <p><c>&lt;ChangedAppVersions&gt;</c> and
+      <c>&lt;UnchangedAppVersions&gt;</c> are space-separated lists of
+      application versions and has the format
+      <c>&lt;application&gt;-&lt;vsn&gt;</c>.</p>
+      <list type="bulleted">
+	<item><c>&lt;ChangedAppVersions&gt;</c> corresponds to changed
+	applications with new version numbers in this OTP version.</item>
+	<item><c>&lt;UnchangedAppVersions&gt;</c> corresponds to unchanged
+	application versions in this OTP version.</item>
+      </list>
+      <p>Both of them can be empty, but not at the same time.
+      If <c>&lt;ChangedAppVersions&gt;</c> is empty, no changes have
+      been made that change the build result of any application. This could,
+      for example, be a pure bug fix of the build system. The order of lines
+      is undefined. All white-space characters in this file are either space
+      (character 32) or line-break (character 10).</p>
+      <p>By using ordinary UNIX tools like <c>sed</c> and <c>grep</c> one
+      can easily find answers to various questions like:</p>
+      <list type="bulleted">
+	<item><p>Which OTP versions are <c>kernel-3.0</c> part of?</p>
+	<p><c>$ grep ' kernel-3\.0 ' otp_versions.table</c> </p></item>
+	<item><p>In which OTP version was <c>kernel-3.0</c> introduced?</p>
+	<p><c>$ sed 's/#.*//;/ kernel-3\.0 /!d' otp_versions.table</c>
+	</p></item>
+      </list>
+      <p>The above commands give a bit more information than the exact
+      answers, but adequate information when manually searching for answers
+      to these questions.</p>
+      <warning><p>The format of the <c>otp_versions.table</c> might be
+      subject to changes during the OTP 17 release.</p></warning>
     </section>
+  </section>
 
-    <section><title>Application Version</title>
-    <p>As of OTP 17.0 application versions will use the same
+  <section>
+    <title>Application Version</title>
+    <p>As of OTP 17.0 application versions use the same
     <seealso marker="#version_scheme">version scheme</seealso> as the
     OTP version. Application versions part of a release candidate will
     however not have an <c>-rc&lt;N&gt;</c> suffix as the OTP version.
@@ -125,88 +131,88 @@
     necessarily imply a major increment of the OTP version. This depends
     on whether the major change in the application is considered as a
     major change for OTP as a whole or not.</p>
-    </section>
+  </section>
 
+  <section>
+    <title>Version Scheme</title>
     <marker id="version_scheme"/>
-    <section><title>Version Scheme</title>
-    <note>Note that the version scheme was changed as of OTP 17.0. This implies
+    <note><p>The version scheme was changed as of OTP 17.0. This implies
     that application versions used prior to OTP 17.0 do not adhere to this
     version scheme. <seealso marker="#otp_17_0_app_versions">A list of
-    application versions used in OTP 17.0</seealso> can be found
-    at the end of this document.</note>
-
-    <p>In the normal case, a version will be constructed as
-    <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c> where <c>&lt;Major&gt;</c>
-    is the most significant part. However, more dot separated parts than
-    this may exist. The dot separated parts consists of non-negative integers.
-    If all parts less significant than <c>&lt;Minor&gt;</c> equals <c>0</c>,
-    they are omitted. The three normal parts
-    <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c> will be changed as
+    application versions used in OTP 17.0</seealso> is included at the
+    end of this section</p></note>
+    <p>In the normal case, a version is constructed as
+    <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c>,
+    where <c>&lt;Major&gt;</c> is the most significant part.</p>
+    <p>However, more dot-separated parts than this can exist.
+    The dot-separated parts consist of non-negative integers. If
+    all parts less significant than <c>&lt;Minor&gt;</c> equals
+    <c>0</c>, they are omitted. The three normal parts
+    <c>&lt;Major&gt;.&lt;Minor&gt;.&lt;Patch&gt;</c> are changed as
     follows:</p>
-    <taglist>
-      <tag><c>&lt;Major&gt;</c></tag><item>Increased when major changes,
-      including incompatibilities, have been made.</item>
-      <tag><c>&lt;Minor&gt;</c></tag><item>Increased when new functionality
-      has been added.</item>
-      <tag><c>&lt;Patch&gt;</c></tag><item>Increased when pure bug fixes
-      have been made.</item>
-    </taglist>
-    <p>When a part in the version number is increased, all less significant
+    <list type="bulleted">
+      <item><c>&lt;Major&gt;</c> - Increases when major changes,
+      including incompatibilities, are made.</item>
+      <item><c>&lt;Minor&gt;</c> - Increases when new
+      functionality is added.</item>
+      <item><c>&lt;Patch&gt;</c> - Increases when pure bug fixes
+      are made.</item>
+    </list>
+    <p>When a part in the version number increases, all less significant
     parts are set to <c>0</c>.</p>
-
     <p>An application version or an OTP version identifies source code
-    versions. That is, it does not imply anything about how the application
+    versions. That is, it implies nothing about how the application
     or OTP has been built.</p>
 
-    <section><title>Order of Versions</title>
-    <p>Version numbers in general are only partially ordered. However,
-    normal version numbers (with three parts) as of OTP 17.0 have a total
-    or linear order. This applies both to normal OTP versions and
-    normal application versions.</p>
-
-    <p>When comparing two version numbers that have an order, one
-    compare each part as ordinary integers from the most
-    significant part towards less significant parts. The order is
-    defined by the first parts of the same significance that
-    differ. An OTP version with a larger version include all
-    changes that that are part of a smaller OTP version. The same
-    goes for application versions.</p>
-
-    <p>In the general case, versions may have more than three parts. In
-    this case the versions are only partially ordered. Note that such
-    versions are only used in exceptional cases. When an extra
-    part (out of the normal three parts) is added to a version number,
-    a new branch of versions is made. The new branch has a linear
-    order against the base version. However, versions on different
-    branches have no order. Since they have no order, we
-    only know that they all include what is included in their
-    closest common ancestor. When branching multiple times from the
-    same base version, <c>0</c> parts are added between the base
-    version and the least significant <c>1</c> part until a unique
-    version is found. Versions that have an order can be compared
-    as described in the paragraph above.</p>
-
-    <p>An example of branched versions: The version <c>6.0.2.1</c>
-    is a branched version from the base version <c>6.0.2</c>.
-    Versions on the form <c>6.0.2.&lt;X&gt;</c> can be compared
-    with normal versions smaller than or equal to <c>6.0.2</c>,
-    and other versions on the form <c>6.0.2.&lt;X&gt;</c>. The
-    version <c>6.0.2.1</c> will include all changes in
-    <c>6.0.2</c>. However, <c>6.0.3</c> will most likely
-    <em>not</em> include all changes in <c>6.0.2.1</c> (note that
-    these versions have no order). A second branched version from the base
-    version <c>6.0.2</c> will be version <c>6.0.2.0.1</c>, and a
-    third branched version will be <c>6.0.2.0.0.1</c>.</p>
-    </section>
+    <section>
+      <title>Order of Versions</title>
+      <p>Version numbers in general are only partially ordered. However,
+      normal version numbers (with three parts) as of OTP 17.0 have a total
+      or linear order. This applies both to normal OTP versions and
+      normal application versions.</p>
+      <p>When comparing two version numbers that have an order, one
+      compare each part as ordinary integers from the most
+      significant part to less significant parts. The order is
+      defined by the first parts of the same significance that
+      differ. An OTP version with a larger version includes all
+      changes that are part of a smaller OTP version. The same
+      goes for application versions.</p>
+      <p>In general, versions can have more than three parts.
+      The versions are then only partially ordered. Such
+      versions are only used in exceptional cases. When an extra
+      part (out of the normal three parts) is added to a version number,
+      a new branch of versions is made. The new branch has a linear
+      order against the base version. However, versions on different
+      branches have no order, and therefore one can only conclude
+      that they all include what is included in their
+      closest common ancestor. When branching multiple times from the
+      same base version, <c>0</c> parts are added between the base
+      version and the least significant <c>1</c> part until a unique
+      version is found. Versions that have an order can be compared
+      as described in the previous paragraph.</p>
+      <p>An example of branched versions: The version <c>6.0.2.1</c>
+      is a branched version from the base version <c>6.0.2</c>.
+      Versions on the form <c>6.0.2.&lt;X&gt;</c> can be compared
+      with normal versions smaller than or equal to <c>6.0.2</c>,
+      and other versions on the form <c>6.0.2.&lt;X&gt;</c>. The
+      version <c>6.0.2.1</c> will include all changes in
+      <c>6.0.2</c>. However, <c>6.0.3</c> will most likely
+      <em>not</em> include all changes in <c>6.0.2.1</c> (note that
+      these versions have no order). A second branched version from the base
+      version <c>6.0.2</c> will be version <c>6.0.2.0.1</c>, and a
+      third branched version will be <c>6.0.2.0.0.1</c>.</p>
     </section>
+  </section>
 
+  <section>
+    <title>OTP 17.0 Application Versions</title>
     <marker id="otp_17_0_app_versions"/>
-    <section><title>OTP 17.0 Application Versions</title>
-    <p>The following application versions were part of OTP 17.0. If
-    the normal part of an applications version number compares
-    as smaller than the corresponding application version in this list,
+    <p>The following list details the application versions that
+    were part of OTP 17.0. If
+    the normal part of an application version number compares
+    as smaller than the corresponding application version in the list,
     the version number does not adhere to the version scheme introduced
-    in OTP 17.0 and should be considered as not having an order against
+    in OTP 17.0 and is to be considered as not having an order against
     versions used as of OTP 17.0.</p>
     <list>
       <item><c>asn1-3.0</c></item>
@@ -262,6 +268,6 @@
       <item><c>wx-1.2</c></item>
       <item><c>xmerl-1.3.7</c></item>
     </list>
-    </section>
+  </section>
 </chapter>