sasl: Editorial changes

1 files changed, 396 insertions, 347 deletions

diff --git a/lib/sasl/doc/src/release_handler.xml b/lib/sasl/doc/src/release_handler.xml
index 692159d7bf..162707676c 100644
--- a/lib/sasl/doc/src/release_handler.xml
+++ b/lib/sasl/doc/src/release_handler.xml
@@ -31,109 +31,115 @@
   <module>release_handler</module>
   <modulesummary>Unpacking and Installation of Release Packages</modulesummary>
   <description>
-    <p>The <em>release handler</em> is a process belonging to the SASL
-      application which is responsible for <em>release handling</em>,
+    <p>The <em>release handler</em> process belongs to the <c>SASL</c>
+      application, which is responsible for <em>release handling</em>,
       that is, unpacking, installation, and removal of release packages.</p>
-    <p>An introduction to release handling and a usage example can be
-      found in
-      <seealso marker="doc/design_principles:release_handling">Design Principles</seealso>.
-      </p>
+    <p>An introduction to release handling and an example is provided in
+      <seealso marker="doc/design_principles:release_handling">OTP Design
+      Principles</seealso> in <em>System Documentation</em>.</p>
     <p>A <em>release package</em> is a compressed tar file containing
       code for a certain version of a release, created by calling
-      <seealso marker="systools#make_tar/1">systools:make_tar/1,2</seealso>.
-      The release package should be placed in the <c>$ROOT/releases</c>
-      directory of the previous version of the release where
+      <seealso marker="systools#make_tar/1"><c>systools:make_tar/1,2</c></seealso>.
+      The release package is to be located in the <c>$ROOT/releases</c>
+      directory of the previous version of the release, where
       <c>$ROOT</c> is the installation root directory,
-      <c>code:root_dir()</c>.
-      Another <c>releases</c> directory can be specified using the SASL
-      configuration parameter <c>releases_dir</c>, or the OS environment
+      <seealso marker="kernel:code#root_dir/0"><c>code:root_dir()</c></seealso>.
+      Another <c>releases</c> directory can be specified using the <c>SASL</c>
+      configuration parameter <c>releases_dir</c> or the OS environment
       variable <c>RELDIR</c>. The release handler must have write access
-      to this directory in order to install the new release.
+      to this directory to install the new release.
       The persistent state of the release handler is stored there in a
       file called <c>RELEASES</c>.</p>
-    <p>A release package should always contain the release resource file
-      <c>Name.rel</c> and a boot script <c>Name.boot</c>. It may contain
-      a release upgrade file <c>relup</c> and a system configuration
-      file <c>sys.config</c>. The <c>.rel</c> file contains information
-      about the release: its name, version, and which ERTS and
-      application versions it uses. The <c>relup</c> file contains
-      scripts for how to upgrade to, or downgrade from, this version of
-      the release.</p>
+    <p>A release package is always to contain:</p>
+    <list type="bulleted">
+      <item>A release resource file, <c>Name.rel</c></item>
+      <item>A boot script, <c>Name.boot</c></item>
+    </list>
+    <p>The <c>.rel</c> file contains information about the release: its name,
+      version, and which <c>ERTS</c> and application versions it uses.</p>
+    <p>A release package can also contain:</p>
+    <list type="bulleted">
+      <item>A release upgrade file, <c>relup</c></item>
+      <item>A system configuration file, <c>sys.config</c></item>
+    </list>
+    <p>The <c>relup</c> file contains instructions for how to upgrade
+      to, or downgrade from, this version of the release.</p>
     <p>The release package can be <em>unpacked</em>, which extracts
       the files. An unpacked release can be <em>installed</em>.
       The currently used version of the release is then upgraded or
       downgraded to the specified version by evaluating the instructions
-      in <c>relup</c>. An installed release can be made
-      <em>permanent</em>. There can only be one permanent release in
-      the system, and this is the release that is used if the system
+      in the <c>relup</c> file. An installed release can be made
+      <em>permanent</em>. Only one permanent release can exist in
+      the system, and this release is used if the system
       is restarted. An installed release, except the permanent one,
       can be <em>removed</em>. When a release is removed, all files
-      that belong to that release only are deleted.</p>
-    <p>Each version of the release has a status. The status can be
+      belonging to that release only are deleted.</p>
+    <p>Each release version has a status, which can be
       <c>unpacked</c>, <c>current</c>, <c>permanent</c>, or <c>old</c>.
-      There is always one latest release which either has status
-      <c>permanent</c> (normal case), or <c>current</c> (installed, but
-      not yet made permanent). The following table illustrates
-      the meaning of the status values:</p>
+      There is always one latest release, which either has status
+      <c>permanent</c> (normal case) or <c>current</c> (installed, but
+      not yet made permanent). The meaning of the status values are
+      illustrated in the following table:</p>
     <pre>
-Status     Action                NextStatus
--------------------------------------------
-  -        unpack                unpacked
-unpacked   install               current
-           remove                  -
-current    make_permanent        permanent
-           install other         old
-           remove                  -
-permanent  make other permanent  old
-           install               permanent
-old        reboot_old            permanent
-           install               current
-           remove                  -
-    </pre>
+        Status     Action                NextStatus
+        -------------------------------------------
+        -          unpack                unpacked
+        unpacked   install               current
+                   remove                -
+        current    make_permanent        permanent
+                   install other         old
+                   remove                -
+        permanent  make other permanent  old
+                   install               permanent
+        old        reboot_old            permanent
+                   install               current
+                   remove                -</pre>
     <p>The release handler process is a locally registered process on
       each node. When a release is installed in a distributed system,
       the release handler on each node must be called. The release
-      installation may be synchronized between nodes. From an operator
-      view, it may be unsatisfactory to specify each node.  The aim is
+      installation can be synchronized between nodes. From an operator
+      view, it can be unsatisfactory to specify each node. The aim is
       to install one release package in the system, no matter how many
-      nodes there are. If this is the case, it is recommended that
-      software management functions are written which take care of
-      this problem. Such a function may have knowledge of the system
+      nodes there are. It is recommended that
+      software management functions are written that take care of
+      this problem. Such a function can have knowledge of the system
       architecture, so it can contact each individual release handler
       to install the package.</p>
-    <p>For release handling to work properly, the runtime system needs
-      to have knowledge about which release it is currently running. It
-      must also be able to change (in run-time) which boot script and
-      system configuration file should be used if the system is
+    <p>For release handling to work properly, the runtime system must
+      know which release it is running. It
+      must also be able to change (in runtime) which boot script and
+      system configuration file are to be used if the system is
       restarted. This is taken care of automatically if Erlang is
-      started as an embedded system. Read about this in <em>Embedded System</em>. In this case, the system configuration file
-      <c>sys.config</c> is mandatory.</p>
-    <p>The installation of a new release may restart the system. Which
-      program to use is specified by the SASL configuration
-      parameter <c>start_prg</c> which defaults
+      started as an embedded system. Read about this in
+      <seealso marker="doc/embedded:users_guide">Embedded System</seealso> in
+      <em>System Documentation</em>. In this case, the system
+      configuration file <c>sys.config</c> is mandatory.</p>
+    <p>The installation of a new release can restart the system. Which
+      program to use is specified by the <c>SASL</c> configuration
+      parameter <c>start_prg</c>, which defaults
       to <c>$ROOT/bin/start</c>.</p>
     <p>The emulator restart on Windows NT expects that the system is
       started using the <c>erlsrv</c> program (as a service).
-      Furthermore the release handler expects that the service is named 
-      <em>NodeName</em>_<em>Release</em>, where <em>NodeName</em> is
-      the first part of the Erlang nodename (up to, but not including
-      the "@") and <em>Release</em> is the current version of
-      the release. The release handler furthermore expects that a
+      Furthermore, the release handler expects that the service is named
+      <c>NodeName</c>_<c>Release</c>, where <c>NodeName</c> is
+      the first part of the Erlang node name (up to, but not including
+      the "@") and <c>Release</c> is the current release version.
+      The release handler furthermore expects that a
       program like <c>start_erl.exe</c> is specified as "machine" to
-      <c>erlsrv</c>. During upgrading with restart, a new service will
-      be registered and started. The new service will be set to
-      automatic and the old service removed as soon as the new release
+      <c>erlsrv</c>. During upgrading with restart, a new service
+      is registered and started. The new service is set to
+      automatic and the old service is removed when the new release
       is made permanent.</p>
-    <p>The release handler at a node which runs on a diskless machine,
+    <p>The release handler at a node running on a diskless machine,
       or with a read-only file system, must be configured accordingly
-      using the following <c>sasl</c> configuration parameters (see
-      <seealso marker="sasl_app">sasl(6)</seealso> for details):</p>
+      using the following <c>SASL</c> configuration parameters (for
+      details, see <seealso marker="sasl_app">sasl(6)</seealso>):</p>
     <taglist>
       <tag><c>masters</c></tag>
       <item>
-        <p>This node uses a number of master nodes in order to store
-          and fetch release information. All master nodes must be up
-          and running whenever release information is written by this
+        <p>This node uses some master nodes to store
+          and fetch release information. All master nodes must be
+          operational whenever release information is written by this
           node.</p>
       </item>
       <tag><c>client_directory</c></tag>
@@ -145,24 +151,25 @@ old        reboot_old            permanent
       <item>
         <p>This parameter specifies if the Erlang emulator is
           statically installed at the client node. A node with a static
-          emulator cannot dynamically switch to a new emulator because
+          emulator cannot dynamically switch to a new emulator, as
           the executable files are statically written into memory.</p>
       </item>
     </taglist>
-    <p>It is also possible to use the release handler to unpack and
+    <p>The release handler can also be used to unpack and
       install release packages when not running Erlang as an embedded
-      system, but in this case the user must somehow make sure that
+      system. However, in this case the user must somehow ensure that
       correct boot scripts and configuration files are used if
-      the system needs to be restarted.</p>
-    <p>There are additional functions for using another file structure
+      the system must be restarted.</p>
+    <p>Functions are provided for using another file structure
       than the structure defined in OTP. These functions can be used
       to test a release upgrade locally.</p>
   </description>
+
   <funcs>
     <func>
       <name>check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
       <name>check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
-      <fsummary>Check installation of a release in the system.</fsummary>
+      <fsummary>Checks installation of a release in the system.</fsummary>
       <type>
         <v>Vsn = OtherVsn = string()</v>
 	<v>Opts = [Opt]</v>
@@ -173,27 +180,29 @@ old        reboot_old            permanent
       <desc>
         <p>Checks if the specified version <c>Vsn</c> of the release
           can be installed. The release must not have status
-          <c>current</c>. Issues warnings if <c>relup</c> or
-          <c>sys.config</c> are not present. If <c>relup</c> is present,
+          <c>current</c>. Issues warnings if <c>relup</c> file or
+          <c>sys.config</c> is not present. If <c>relup</c> file is present,
           its contents are checked and <c>{error,Reason}</c> is
           returned if an error is found. Also checks that all required
-          applications are present and that all new code can be loaded,
-          or <c>{error,Reason}</c> is returned.</p>
-        <p>This function evaluates all instructions that occur before
+          applications are present and that all new code can be loaded;
+          <c>{error,Reason}</c> is returned if an error is found.</p>
+        <p>Evaluates all instructions that occur before
           the <c>point_of_no_return</c> instruction in the release
           upgrade script.</p>
-        <p>Returns the same as <c>install_release/1</c>. <c>Descr</c>
-          defaults to "" if no <c>relup</c> file is found.</p>
-	<p>If the option <c>purge</c> is given, all old code that can
-          be soft purged will be purged after all other checks are
-          successfully completed. This can be useful in order to
+        <p>Returns the same as 
+	<seealso marker="#install_release/1"><c>install_release/1</c></seealso>.
+	<c>Descr</c> defaults to "" if no <c>relup</c> file is found.</p>
+        <p>If option <c>purge</c> is specified, all old code that can
+          be soft-purged is purged after all other checks are
+          successfully completed. This can be useful to
           reduce the time needed by <seealso
-          marker="#install_release/1">install_release</seealso>.</p>
+          marker="#install_release/1"><c>install_release/1</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
       <name>create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}</name>
-      <fsummary>Create an initial RELEASES file.</fsummary>
+      <fsummary>Creates an initial <c>RELEASES</c> file.</fsummary>
       <type>
         <v>Root = RelDir = RelFile = string()</v>
         <v>AppDirs = [{App, Vsn, Dir}]</v>
@@ -202,52 +211,55 @@ old        reboot_old            permanent
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Creates an initial RELEASES file to be used by the release
-          handler. This file must exist in order to install new
+        <p>Creates an initial <c>RELEASES</c> file to be used by the
+          release handler. This file must exist to install new
           releases.</p>
         <p><c>Root</c> is the root of the installation (<c>$ROOT</c>) as
-          described above. <c>RelDir</c> is the the directory where
-          the <c>RELEASES</c> file should be created (normally
+          described earlier. <c>RelDir</c> is the directory where
+          the <c>RELEASES</c> file is to be created (normally
           <c>$ROOT/releases</c>). <c>RelFile</c> is the name
           of the <c>.rel</c> file that describes the initial release,
           including the extension <c>.rel</c>.</p>
         <p><c>AppDirs</c> can be used to specify from where the modules
-          for the specified applications should be loaded. <c>App</c> is
+          for the specified applications are to be loaded. <c>App</c> is
           the name of an application, <c>Vsn</c> is the version, and
           <c>Dir</c> is the name of the directory where <c>App-Vsn</c>
-          is located. The corresponding modules should be located under
+          is located. The corresponding modules are to be located under
           <c>Dir/App-Vsn/ebin</c>. The directories for applications not
           specified in <c>AppDirs</c> are assumed to be located in
           <c>$ROOT/lib</c>.</p>
       </desc>
     </func>
+
     <func>
       <name>install_file(Vsn, File) -> ok | {error, Reason}</name>
-      <fsummary>Install a release file in the release structure.</fsummary>
+      <fsummary>Installs a release file in the release structure.</fsummary>
       <type>
         <v>Vsn = File = string()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Installs a release dependent file in the release structure.
-          A release dependent file is a file that must be in
+        <p>Installs a release-dependent file in the release structure.
+          The release-dependent file must be in
           the release structure when a new release is installed:
-          <c>start.boot</c>, <c>relup</c> and <c>sys.config</c>.</p>
+          <c>start.boot</c>, <c>relup</c>, and <c>sys.config</c>.</p>
         <p>The function can be called, for example, when these files
-          are generated at the target. It should be called after
-          <c>set_unpacked/2</c> has been called.</p>
+          are generated at the target. The function is to be called after
+          <seealso marker="#set_unpacked/2"><c>set_unpacked/2</c></seealso> 
+	has been called.</p>
       </desc>
     </func>
+
     <func>
       <name>install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
       <name>install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}</name>
-      <fsummary>Install a release in the system.</fsummary>
+      <fsummary>Installs a release in the system.</fsummary>
       <type>
         <v>Vsn = OtherVsn = string()</v>
         <v>Opt = {error_action, Action} | {code_change_timeout, Timeout}</v>
         <v>&nbsp;&nbsp;&nbsp;| {suspend_timeout, Timeout} | {update_paths, Bool}</v>
         <v>&nbsp;Action = restart | reboot</v>
-        <v>&nbsp;Timeout = default | infinity | int()>0</v>
+        <v>&nbsp;Timeout = default | infinity | pos_integer()</v>
         <v>&nbsp;Bool = boolean()</v>
         <v>Descr = term()</v>
         <v>Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term()</v>
@@ -262,7 +274,7 @@ old        reboot_old            permanent
           version and a script <c>{Vsn,Descr2,Instructions2}</c> in this
           file for downgrading to <c>Vsn</c>.</p>
         <p>If a script is found, the first thing that happens is that
-          the applications specifications are updated according to
+          the application specifications are updated according to
           the <c>.app</c> files and <c>sys.config</c> belonging to
           the release version <c>Vsn</c>.</p>
         <p>After the application specifications have been updated,
@@ -271,101 +283,120 @@ old        reboot_old            permanent
           <c>OtherVsn</c> and <c>Descr</c> are the version
           (<c>UpFromVsn</c> or <c>Vsn</c>) and description
           (<c>Descr1</c> or <c>Descr2</c>) as specified in the script.</p>
-	  <p>If <c>{continue_after_restart,OtherVsn,Descr}</c> is
-	  returned, it means that the emulator will be restarted
-	  before the upgrade instructions are executed. This will
-	  happen if the emulator or any of the applications kernel,
-	  stdlib or sasl are updated. The new version of the emulator
-	  and these core applications will execute after the restart,
-	  but for all other applications the old versions will be
-	  started and the upgrade will be performed as normal by
+	<p>If <c>{continue_after_restart,OtherVsn,Descr}</c> is
+	  returned, the emulator is restarted
+	  before the upgrade instructions are executed. This
+	  occurs if the emulator or any of the applications
+          <c>Kernel</c>, <c>STDLIB</c>, or <c>SASL</c>
+	  are updated. The new emulator version
+	  and these core applications execute after the restart.
+	  For all other applications the old versions are
+	  started and the upgrade is performed as normal by
 	  executing the upgrade instructions.</p>
         <p>If a recoverable error occurs, the function returns
           <c>{error,Reason}</c> and the original application
           specifications are restored. If a non-recoverable error
           occurs, the system is restarted.</p>
-        <p>The option <c>error_action</c> defines if the node should be
-          restarted (<c>init:restart()</c>) or rebooted
-          (<c>init:reboot()</c>) in case of an error during
-          the installation. Default is <c>restart</c>.</p>
-        <p>The option <c>code_change_timeout</c> defines the timeout
-          for all calls to <c>sys:change_code</c>. If no value is
-          specified or <c>default</c> is given, the default value
-          defined in <c>sys</c> is used.</p>
-        <p>The option <c>suspend_timeout</c> defines the timeout for 
-          all calls to <c>sys:suspend</c>. If no value is specified,
-          the values defined by the <c>Timeout</c> parameter of
-          the <c>upgrade</c> or <c>suspend</c> instructions are used.
-          If <c>default</c> is specified, the default value defined in
-          <c>sys</c> is used.</p>
-        <p>The option <c>{update_paths,Bool}</c> indicates if all
-          application code paths should be updated (<c>Bool==true</c>),
-          or if only code paths for modified applications should be
-          updated (<c>Bool==false</c>, default). This option only has
-          effect for other application directories than the default
-          <c>$ROOT/lib/App-Vsn</c>, that is, application directories
-          provided in the <c>AppDirs</c> argument in a call to
-          <c>create_RELEASES/4</c> or <c>set_unpacked/2</c>.</p>
-        <p>Example: In the current version <c>CurVsn</c> of a release,
-          the application directory of <c>myapp</c> is
-          <c>$ROOT/lib/myapp-1.0</c>. A new version <c>NewVsn</c> is
-          unpacked outside the release handler, and the release handler
-          is informed about this with a call to:</p>
-        <code type="none">
+        <p><em>Options</em>:</p>
+        <taglist>
+          <tag><c>error_action</c></tag>
+            <item><p>Defines if the node is to be
+            restarted 
+	    (<seealso marker="erts:init#restart/0"><c>init:restart()</c></seealso>) 
+	    or rebooted
+            (<seealso marker="erts:init#reboot/0"><c>init:reboot()</c></seealso>) 
+	    if there is an error during
+            the installation. Default is <c>restart</c>.</p></item>
+          <tag><c>code_change_timeout</c></tag>
+            <item><p>Defines the time-out
+            for all calls to 
+	    <seealso marker="stdlib:sys#change_code/4"><c>stdlib:sys:change_code</c></seealso>. 
+	    If no value is specified or <c>default</c> is specified, the 
+	    default value defined in <c>sys</c> is used.</p></item>
+          <tag><c>suspend_timeout</c></tag>
+            <item><p>Defines the time-out for 
+            all calls to 
+	    <seealso marker="stdlib:sys#suspend/1"><c>stdlib:sys:suspend</c></seealso>. 
+	    If no value is specified, the values defined by the <c>Timeout</c> 
+	    parameter of the <c>upgrade</c> or <c>suspend</c> instructions are used.
+            If <c>default</c> is specified, the default value defined in
+            <c>sys</c> is used.</p></item>
+          <tag><c>{update_paths,Bool}</c></tag>
+            <item><p>Indicates if all
+            application code paths are to be updated (<c>Bool==true</c>)
+            or if only code paths for modified applications are to be
+            updated (<c>Bool==false</c>, default). This option has only
+            effect for other application directories than the default
+            <c>$ROOT/lib/App-Vsn</c>, that is, application directories
+            specified in argument <c>AppDirs</c> in a call to
+            <seealso marker="#create_RELEASES/4"><c>create_RELEASES/4</c></seealso> or 
+	    <seealso marker="#set_unpacked/2"><c>set_unpacked/2</c></seealso>.</p>
+            <p><em>Example:</em></p>
+            <p>In the current version <c>CurVsn</c> of a release, the
+              application directory of <c>myapp</c> is
+              <c>$ROOT/lib/myapp-1.0</c>. A new version <c>NewVsn</c> is
+              unpacked outside the release handler and the release
+              handler is informed about this with a call as follows:</p>
+            <code type="none">
 release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
-=> {ok,NewVsn}
-        </code>
-        <p>If <c>NewVsn</c> is installed with the option
-          <c>{update_paths,true}</c>, afterwards
-          <c>code:lib_dir(myapp)</c> will return
-          <c>/home/user/myapp-1.0</c>.</p>
+=> {ok,NewVsn}</code>
+            <p>If <c>NewVsn</c> is installed with option
+              <c>{update_paths,true}</c>, then
+              <seealso marker="kernel:code#lib_dir/1"><c>kernel:code:lib_dir(myapp)</c></seealso> 
+	      returns <c>/home/user/myapp-1.0</c>.</p></item>
+        </taglist>
 	<note>
-	  <p>Installing a new release might be quite time consuming if
+	  <p>Installing a new release can be time consuming if
 	  there are many processes in the system. The reason is that
 	  each process must be checked for references to old code
-	  before a module can be purged. This check might lead to
+	  before a module can be purged. This check can lead to
 	  garbage collections and copying of data.</p>
-	  <p>If you wish to speed up the execution of
-	  <c>install_release</c>, then you may call <seealso
-	  marker="#check_install_release/1">check_install_release</seealso>
-	  first, using the option <c>purge</c>. This will do the same
-	  check for old code, and then purge all modules that can be
-	  soft purged. The purged modules will then no longer have any
-	  old code, and <c>install_release</c> will not need to do the
+	  <p>To speed up the execution of
+	  <seealso marker="#install_release/1"><c>install_release</c></seealso>, 
+	  first call <seealso
+	  marker="#check_install_release/1"><c>check_install_release</c></seealso>,
+	  using option <c>purge</c>. This does the same
+	  check for old code. Then purges all modules that can be
+	  soft-purged. The purged modules do then no longer have any
+	  old code, and 
+	  <seealso marker="#install_release/1"><c>install_release</c></seealso>
+	  does not need to do the
 	  checks.</p>
-	  <p>Obviously, this will not reduce the overall time for the
-	  upgrade, but it will allow checks and purge to be executed
+	  <p>This does not reduce the overall time for the
+	  upgrade, but it allows checks and purge to be executed
 	  in the background before the real upgrade is started.</p>
 	</note>
 	<note>
 	  <p>When upgrading the emulator from a version older than OTP
-	  R15, there will be an attempt to load new application beam
-	  code into the old emulator. In some cases, the new beam
-	  format can not be read by the old emulator, and so the code
-	  loading will fail and terminate the complete upgrade. To
-	  overcome this problem, the new application code should be
-	  compiled with the old emulator. See <seealso
-	  marker="doc/design_principles:appup_cookbook">Design
-	  Principles</seealso> for more information about emulator
-	  upgrade from pre OTP R15 versions.</p>
+	  R15, an attempt is made to load new application beam
+	  code into the old emulator. Sometimes the new beam
+	  format cannot be read by the old emulator, so the code
+	  loading fails and the complete upgrade is terminated. To
+	  overcome this problem, the new application code is to be
+	  compiled with the old emulator. For more information about
+          emulator upgrade from pre OTP R15 versions, see
+          <seealso marker="doc/design_principles:appup_cookbook">Design
+          Principles</seealso> in <em>System Documentation</em>.</p>
 	</note>
       </desc>
     </func>
+
     <func>
       <name>make_permanent(Vsn) -> ok | {error, Reason}</name>
-      <fsummary>Make the specified release version permanent.</fsummary>
+      <fsummary>Makes the specified release version permanent.</fsummary>
       <type>
         <v>Vsn = string()</v>
         <v>Reason = {bad_status, Status} | term()</v>
       </type>
       <desc>
-        <p>Makes the specified version <c>Vsn</c> of the release
+        <p>Makes the specified release version <c>Vsn</c>
           permanent.</p>
       </desc>
     </func>
+
     <func>
       <name>remove_release(Vsn) -> ok | {error, Reason}</name>
-      <fsummary>Remove a release from the system.</fsummary>
+      <fsummary>Removes a release from the system.</fsummary>
       <type>
         <v>Vsn = string()</v>
         <v>Reason = {permanent, Vsn} | client_node | term()</v>
@@ -375,23 +406,26 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
           The release must not be the permanent release. Removes only
           the files and directories not in use by another release.</p>
       </desc>
+
     </func>
     <func>
       <name>reboot_old_release(Vsn) -> ok | {error, Reason}</name>
-      <fsummary>Reboot the system from an old release.</fsummary>
+      <fsummary>Reboots the system from an old release.</fsummary>
       <type>
         <v>Vsn = string()</v>
         <v>Reason = {bad_status, Status} | term()</v>
       </type>
       <desc>
         <p>Reboots the system by making the old release permanent, and
-          calls <c>init:reboot()</c> directly. The release must have
-          status <c>old</c>.</p>
+          calls 
+	  <seealso marker="erts:init#reboot/0"><c>init:reboot()</c></seealso> 
+	  directly. The release must have status <c>old</c>.</p>
       </desc>
     </func>
+
     <func>
       <name>set_removed(Vsn) -> ok | {error, Reason}</name>
-      <fsummary>Mark a release as removed.</fsummary>
+      <fsummary>Marks a release as removed.</fsummary>
       <type>
         <v>Vsn = string()</v>
         <v>Reason = {permanent, Vsn} | term()</v>
@@ -403,9 +437,10 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
           not delete any files.</p>
       </desc>
     </func>
+
     <func>
       <name>set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}</name>
-      <fsummary>Mark a release as unpacked.</fsummary>
+      <fsummary>Marks a release as unpacked.</fsummary>
       <type>
         <v>RelFile = string()</v>
         <v>AppDirs = [{App, Vsn, Dir}]</v>
@@ -419,18 +454,19 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
           the release is unpacked. <c>Vsn</c> is extracted from
           the release resource file <c>RelFile</c>.</p>
         <p><c>AppDirs</c> can be used to specify from where the modules
-          for the specified applications should be loaded. <c>App</c> is
+          for the specified applications are to be loaded. <c>App</c> is
           the name of an application, <c>Vsn</c> is the version, and
           <c>Dir</c> is the name of the directory where <c>App-Vsn</c>
-          is located. The corresponding modules should be located under
+          is located. The corresponding modules are to be located under
           <c>Dir/App-Vsn/ebin</c>. The directories for applications not
           specified in <c>AppDirs</c> are assumed to be located in
           <c>$ROOT/lib</c>.</p>
       </desc>
     </func>
+
     <func>
       <name>unpack_release(Name) -> {ok, Vsn} | {error, Reason}</name>
-      <fsummary>Unpack a release package.</fsummary>
+      <fsummary>Unpacks a release package.</fsummary>
       <type>
         <v>Name = Vsn = string()</v>
         <v>Reason = client_node | term()</v>
@@ -438,14 +474,15 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
       <desc>
         <p>Unpacks a release package <c>Name.tar.gz</c> located in
           the <c>releases</c> directory.</p>
-        <p>Performs some checks on the package - for example checks
-          that all mandatory files are present - and extracts its
+        <p>Performs some checks on the package, for example, checks
+          that all mandatory files are present, and extracts its
           contents.</p>
       </desc>
     </func>
+
     <func>
       <name>which_releases() -> [{Name, Vsn, Apps, Status}]</name>
-      <fsummary>Return all known releases</fsummary>
+      <fsummary>Returns all known releases.</fsummary>
       <type>
         <v>Name = Vsn = string()</v>
         <v>Apps = ["App-Vsn"]</v>
@@ -455,16 +492,18 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
         <p>Returns all releases known to the release handler.</p>
       </desc>
     </func>
+
     <func>
       <name>which_releases(Status) -> [{Name, Vsn, Apps, Status}]</name>
-      <fsummary>Return all known releases of a specific status</fsummary>
+      <fsummary>Returns all known releases of a specific status.</fsummary>
       <type>
         <v>Name = Vsn = string()</v>
         <v>Apps = ["App-Vsn"]</v>
         <v>Status = unpacked | current | permanent | old</v>
       </type>
       <desc>
-        <p>Returns all releases known to the release handler of a specific status.</p>
+        <p>Returns all releases, known to the release handler, of a
+          specific status.</p>
       </desc>
     </func>
   </funcs>
@@ -473,7 +512,8 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
     <title>Application Upgrade/Downgrade</title>
     <p>The following functions can be used to test upgrade and downgrade
       of single applications (instead of upgrading/downgrading an entire
-      release). A script corresponding to <c>relup</c> is created
+      release). A script corresponding to the instructions in the
+      <c>relup</c> file is created
       on-the-fly, based on the <c>.appup</c> file for the application,
       and evaluated exactly in the same way as <c>release_handler</c>
       does.</p>
@@ -482,20 +522,22 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
         of <c>.appup</c> files. They are not run within the context of
         the <c>release_handler</c> process. They must therefore
         <em>not</em> be used together with calls to
-        <c>install_release/1,2</c>, as this will cause
+        <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>, 
+	as this causes the
         <c>release_handler</c> to end up in an inconsistent state.</p>
-      <p>No persistent information is updated, why these functions can
+      <p>No persistent information is updated, so these functions can
         be used on any Erlang node, embedded or not. Also, using these
-        functions does not affect which code will be loaded in case of
+        functions does not affect which code is loaded if there is
         a reboot.</p>
-      <p>If the upgrade or downgrade fails, the application may end up
+      <p>If the upgrade or downgrade fails, the application can end up
         in an inconsistent state.</p>
     </warning>
   </section>
+
   <funcs>
     <func>
       <name>upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name>
-      <fsummary>Upgrade to a new application version</fsummary>
+      <fsummary>Upgrades to a new application version.</fsummary>
       <type>
         <v>App = atom()</v>
         <v>Dir = string()</v>
@@ -506,39 +548,46 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
       <desc>
         <p>Upgrades an application <c>App</c> from the current
           version to a new version located in <c>Dir</c> according to
-          the <c>.appup</c> script.</p>
+          the <c>.appup</c> file.</p>
         <p><c>App</c> is the name of the application, which must be
           started. <c>Dir</c> is the new library directory of
-          <c>App</c>, the corresponding modules as well as
-          the <c>.app</c> and <c>.appup</c> files should be located
+          <c>App</c>. The corresponding modules as well as
+          the <c>.app</c> and <c>.appup</c> files are to be located
           under <c>Dir/ebin</c>.</p>
         <p>The function looks in the <c>.appup</c> file and tries to
           find an upgrade script from the current version of
           the application using
-          <seealso marker="#upgrade_script/2">upgrade_script/2</seealso>.
+          <seealso marker="#upgrade_script/2"><c>upgrade_script/2</c></seealso>.
           This script is evaluated using
-          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>,
+          <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>,
           exactly in the same way as
-          <seealso marker="#install_release/1">install_release/1,2</seealso>
+          <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>
           does.</p>
-        <p>Returns <c>{ok, Unpurged}</c> if evaluating the script is
-          successful, where <c>Unpurged</c> is a list of unpurged
-          modules, or <c>restart_emulator</c> if this instruction is
-          encountered in the script, or <c>{error, Reason}</c> if
-          an error occurred when finding or evaluating the script.</p>
+        <p>Returns one of the following:</p>
+        <list type="bulleted">
+          <item><c>{ok, Unpurged}</c> if evaluating the script is
+            successful, where <c>Unpurged</c> is a list of unpurged
+            modules</item>
+          <item><c>restart_emulator</c> if this instruction is
+            encountered in the script</item>
+          <item><c>{error, Reason}</c> if an error occurred when
+            finding or evaluating the script</item>
+        </list>
 	<p>If the <c>restart_new_emulator</c> instruction is found in
-	  the script, <c>upgrade_app/2</c> will return
-	  <c>{error,restart_new_emulator}</c>. The reason for this is
-	  that this instruction requires that a new version of the
-	  emulator is started before the rest of the upgrade
-	  instructions can be executed, and this can only be done by
-          <c>install_release/1,2</c>.</p>
+          the script, 
+	  <seealso marker="#upgrade_app/2"><c>upgrade_app/2</c></seealso> 
+	  returns <c>{error,restart_new_emulator}</c>. This because
+          <c>restart_new_emulator</c> requires a new version of the
+          emulator to be started before the rest of the upgrade
+          instructions can be executed, and this can only be done by
+          <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
       <name>downgrade_app(App, Dir) -></name>
       <name>downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name>
-      <fsummary>Downgrade to a previous application version</fsummary>
+      <fsummary>Downgrades to a previous application version.</fsummary>
       <type>
         <v>App = atom()</v>
         <v>Dir = OldVsn = string()</v>
@@ -549,110 +598,124 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
       <desc>
         <p>Downgrades an application <c>App</c> from the current
           version to a previous version <c>OldVsn</c> located in
-          <c>Dir</c> according to the <c>.appup</c> script.</p>
+          <c>Dir</c> according to the <c>.appup</c> file.</p>
         <p><c>App</c> is the name of the application, which must be
-          started. <c>OldVsn</c> is the previous version of
-          the application and can be omitted if <c>Dir</c> is of
+          started. <c>OldVsn</c> is the previous application version
+          and can be omitted if <c>Dir</c> is of
           the format <c>"App-OldVsn"</c>. <c>Dir</c> is the library
-          directory of this previous version of <c>App</c>,
-          the corresponding modules as well as the old <c>.app</c> file
-          should be located under <c>Dir/ebin</c>. The <c>.appup</c>
-          file should be located in the <c>ebin</c> directory of
+          directory of the previous version of <c>App</c>.
+          The corresponding modules and the old <c>.app</c> file
+          are to be located under <c>Dir/ebin</c>. The <c>.appup</c>
+          file is to be located in the <c>ebin</c> directory of
           the <em>current</em> library directory of the application
-          (<c>code:lib_dir(App)</c>).</p>
+          (<seealso marker="kernel:code#lib_dir/1"><c>code:lib_dir(App)</c></seealso>).</p>
         <p>The function looks in the <c>.appup</c> file and tries to
-          find an downgrade script to the previous version of
+          find a downgrade script to the previous version of
           the application using
-          <seealso marker="#downgrade_script/3">downgrade_script/3</seealso>.
+          <seealso marker="#downgrade_script/3"><c>downgrade_script/3</c></seealso>.
           This script is evaluated using
-          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>,
+          <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>,
           exactly in the same way as
-          <seealso marker="#install_release/1">install_release/1,2</seealso>
+          <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>
           does.</p>
-        <p>Returns <c>{ok, Unpurged}</c> if evaluating the script is
-          successful, where <c>Unpurged</c> is a list of unpurged
-          modules, or <c>restart_emulator</c> if this instruction is
-          encountered in the script, or <c>{error, Reason}</c> if
-          an error occurred when finding or evaluating the script.</p>
+        <p>Returns one of the following:</p>
+        <list type="bulleted">
+          <item><c>{ok, Unpurged}</c> if evaluating the script is
+            successful, where <c>Unpurged</c> is a list of unpurged
+            modules</item>
+          <item><c>restart_emulator</c> if this instruction is
+            encountered in the script</item>
+          <item><c>{error, Reason}</c> if an error occurred when
+            finding or evaluating the script</item>
+        </list>
       </desc>
     </func>
+
     <func>
       <name>upgrade_script(App, Dir) -> {ok, NewVsn, Script}</name>
-      <fsummary>Find an application upgrade script</fsummary>
+      <fsummary>Finds an application upgrade script.</fsummary>
       <type>
         <v>App = atom()</v>
         <v>Dir = string()</v>
         <v>NewVsn = string()</v>
-        <v>Script = Instructions -- see appup(4)</v>
+        <v>Script = Instructions</v>
       </type>
       <desc>
         <p>Tries to find an application upgrade script for <c>App</c>
           from the current version to a new version located in
           <c>Dir</c>.</p>
         <p>The upgrade script can then be evaluated using
-          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>.
+          <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>.
           It is recommended to use
-          <seealso marker="#upgrade_app/2">upgrade_app/2</seealso>
-          instead, but this function is useful in order to inspect
-          the contents of the script.</p>
+          <seealso marker="#upgrade_app/2"><c>upgrade_app/2</c></seealso>
+          instead, but this function (<c>upgrade_script</c>) is useful
+          to inspect the contents of the script.</p>
         <p><c>App</c> is the name of the application, which must be
           started. <c>Dir</c> is the new library directory of
-          <c>App</c>, the corresponding modules as well as
-          the <c>.app</c> and <c>.appup</c> files should be located
+          <c>App</c>. The corresponding modules as well as
+          the <c>.app</c> and <c>.appup</c> files are to be located
           under <c>Dir/ebin</c>.</p>
         <p>The function looks in the <c>.appup</c> file and tries to
-          find an upgrade script from the current version of
-          the application. High-level instructions are translated to
-          low-level instructions and the instructions are sorted in
-          the same manner as when generating a <c>relup</c> script.</p>
+          find an upgrade script from the current application version.
+          High-level instructions are translated to
+          low-level instructions. The instructions are sorted in
+          the same manner as when generating a <c>relup</c> file.</p>
         <p>Returns <c>{ok, NewVsn, Script}</c> if successful, where
-          <c>NewVsn</c> is the new application version.</p>
+          <c>NewVsn</c> is the new application version.
+	For details about <c>Script</c>, see 
+	<seealso marker="appup"><c>appup(4)</c></seealso>.</p>
         <p>Failure: If a script cannot be found, the function fails
           with an appropriate error reason.</p>
       </desc>
     </func>
+
     <func>
       <name>downgrade_script(App, OldVsn, Dir) -> {ok, Script}</name>
-      <fsummary>Find an application downgrade script</fsummary>
+      <fsummary>Finds an application downgrade script.</fsummary>
       <type>
         <v>App = atom()</v>
         <v>OldVsn = Dir = string()</v>
-        <v>Script = Instructions -- see appup(4)</v>
+        <v>Script = Instructions</v>
       </type>
       <desc>
         <p>Tries to find an application downgrade script for <c>App</c>
           from the current version to a previous version <c>OldVsn</c>
           located in <c>Dir</c>.</p>
         <p>The downgrade script can then be evaluated using
-          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>.
+          <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>.
           It is recommended to use
-          <seealso marker="#downgrade_app/2">downgrade_app/2,3</seealso>
-          instead, but this function is useful in order to inspect
-          the contents of the script.</p>
+          <seealso marker="#downgrade_app/2"><c>downgrade_app/2,3</c></seealso>
+          instead, but this function (<c>downgrade_script</c>) is useful
+          to inspect the contents of the script.</p>
         <p><c>App</c> is the name of the application, which must be
           started. <c>Dir</c> is the previous library directory of
-          <c>App</c>, the corresponding modules as well as
-          the old <c>.app</c> file should be located under
-          <c>Dir/ebin</c>. The <c>.appup</c> file should be located in
+          <c>App</c>. The corresponding modules and
+          the old <c>.app</c> file are to be located under
+          <c>Dir/ebin</c>. The <c>.appup</c> file is to be located in
           the <c>ebin</c> directory of the <em>current</em> library
-          directory of the application (<c>code:lib_dir(App)</c>).</p>
+          directory of the application 
+	(<seealso marker="kernel:code#lib_dir/1"><c>code:lib_dir(App)</c>)</seealso>.</p>
         <p>The function looks in the <c>.appup</c> file and tries to
-          find an downgrade script from the current version of
-          the application. High-level instructions are translated to
-          low-level instructions and the instructions are sorted in
-          the same manner as when generating a <c>relup</c> script.</p>
-        <p>Returns <c>{ok, Script}</c> if successful.</p>
+          find a downgrade script from the current application version.
+          High-level instructions are translated to
+          low-level instructions. The instructions are sorted in
+          the same manner as when generating a <c>relup</c> file.</p>
+        <p>Returns <c>{ok, Script}</c> if successful. 
+	For details about <c>Script</c>, see 
+	<seealso marker="appup"><c>appup(4)</c></seealso>.</p>
         <p>Failure: If a script cannot be found, the function fails
           with an appropriate error reason.</p>
       </desc>
     </func>
+
     <func>
       <name>eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name>
-      <fsummary>Evaluate an application upgrade or downgrade script</fsummary>
+      <fsummary>Evaluates an application upgrade or downgrade script.</fsummary>
       <type>
         <v>App = atom()</v>
         <v>ToVsn = ToDir = string()</v>
-        <v>Script -- see upgrade_script/2, downgrade_script/3</v>
+        <v>Script</v>
+	<d>See <seealso marker="#upgrade_script/2"><c>upgrade_script/2</c></seealso>, <seealso marker="#downgrade_script/3"><c>downgrade_script/3</c></seealso></d>
         <v>Unpurged = [Module]</v>
         <v>&nbsp;Module = atom()</v>
         <v>Reason = term()</v>
@@ -660,114 +723,100 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
       <desc>
         <p>Evaluates an application upgrade or downgrade script
           <c>Script</c>, the result from calling
-          <seealso marker="#upgrade_app/2">upgrade_script/2</seealso> or
-          <seealso marker="#downgrade_app/3">downgrade_script/3</seealso>,
+          <seealso marker="#upgrade_script/2"><c>upgrade_script/2</c></seealso> or
+          <seealso marker="#downgrade_script/3"><c>downgrade_script/3</c></seealso>,
           exactly in the same way as
-          <seealso marker="#install_release/1">install_release/1,2</seealso>
+          <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>
           does.</p>
         <p><c>App</c> is the name of the application, which must be
           started. <c>ToVsn</c> is the version to be upgraded/downgraded
           to, and <c>ToDir</c> is the library directory of this version.
           The corresponding modules as well as the <c>.app</c> and
-          <c>.appup</c> files should be located under <c>Dir/ebin</c>.</p>
-        <p>Returns <c>{ok, Unpurged}</c> if evaluating the script is
-          successful, where <c>Unpurged</c> is a list of unpurged
-          modules, or <c>restart_emulator</c> if this instruction is
-          encountered in the script, or <c>{error, Reason}</c> if
-          an error occurred when evaluating the script.</p>
-	<p>If the <c>restart_new_emulator</c> instruction is found in
-	  the script, <c>eval_appup_script/4</c> will return
-	  <c>{error,restart_new_emulator}</c>. The reason for this is
-	  that this instruction requires that a new version of the
-	  emulator is started before the rest of the upgrade
-	  instructions can be executed, and this can only be done by
-          <c>install_release/1,2</c>.</p>
+          <c>.appup</c> files are to be located under <c>Dir/ebin</c>.</p>
+        <p>Returns one of the following:</p>
+        <list type="bulleted">
+          <item><c>{ok, Unpurged}</c> if evaluating the script is
+            successful, where <c>Unpurged</c> is a list of unpurged
+            modules</item>
+          <item><c>restart_emulator</c> if this instruction is
+            encountered in the script</item>
+          <item><c>{error, Reason}</c> if an error occurred when
+            finding or evaluating the script</item>
+        </list>
+        <p>If the <c>restart_new_emulator</c> instruction is found in
+          the script, 
+	  <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>
+	  returns <c>{error,restart_new_emulator}</c>. This because
+          <c>restart_new_emulator</c> requires a new version of the
+          emulator to be started before the rest of the upgrade
+          instructions can be executed, and this can only be done by
+          <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>.</p>
       </desc>
     </func>
   </funcs>
 
   <section>
     <title>Typical Error Reasons</title>
-    <list type="bulleted">
-      <item>
-        <p><c>{bad_masters, Masters}</c> - The master nodes
-          <c>Masters</c> are not alive.</p>
-      </item>
-      <item>
-        <p><c>{bad_rel_file, File}</c> - Specified <c>.rel</c> file
-          <c>File</c> can not be read, or does not contain a single
-          term.</p>
-      </item>
-      <item>
-        <p><c>{bad_rel_data, Data}</c> - Specified <c>.rel</c> file
-          does not contain a recognized release specification, but
-          another term <c>Data</c>.</p>
-      </item>
-      <item>
-        <p><c>{bad_relup_file, File}</c> - Specified <c>relup</c> file
-          <c>Relup</c> contains bad data.</p>
-      </item>
-      <item>
-        <p><c>{cannot_extract_file, Name, Reason}</c> - Problems when
-          extracting from a tar file, <c>erl_tar:extract/2</c> returned
-          <c>{error, {Name, Reason}}</c>.</p>
-      </item>
-      <item>
-        <p><c>{existing_release, Vsn}</c> - Specified release version
-          <c>Vsn</c> is already in use.</p>
-      </item>
-      <item>
-        <p><c>{Master, Reason, When}</c> - Some operation, indicated by
-          the term <c>When</c>, failed on the master node <c>Master</c>
-          with the specified error reason <c>Reason</c>.</p>
-      </item>
-      <item>
-        <p><c>{no_matching_relup, Vsn, CurrentVsn}</c> - Cannot find a
-          script for up/downgrading between <c>CurrentVsn</c> and
-          <c>Vsn</c>.</p>
-      </item>
-      <item>
-        <p><c>{no_such_directory, Path}</c> - The directory <c>Path</c>
-          does not exist.</p>
-      </item>
-      <item>
-        <p><c>{no_such_file, Path}</c> - The path <c>Path</c> (file or
-          directory) does not exist.</p>
-      </item>
-      <item>
-        <p><c>{no_such_file, {Master, Path}}</c> - The path <c>Path</c>
-          (file or directory) does not exist at the master node
-          <c>Master</c>.</p>
-      </item>
-      <item>
-        <p><c>{no_such_release, Vsn}</c> - The specified version
-          <c>Vsn</c> of the release does not exist.</p>
-      </item>
-      <item>
-        <p><c>{not_a_directory, Path}</c> - <c>Path</c> exists, but is
-          not a directory.</p>
-      </item>
-      <item>
-        <p><c>{Posix, File}</c> - Some file operation failed for
-          <c>File</c>. <c>Posix</c> is an atom named from the Posix
-          error codes, such as <c>enoent</c>, <c>eacces</c> or
-          <c>eisdir</c>. See <c>file(3)</c>.</p>
-      </item>
-      <item>
-        <p><c>Posix</c> - Some file operation failed, as above.</p>
-      </item>
-    </list>
+    <taglist>
+      <tag><c>{bad_masters, Masters}</c></tag>
+        <item><p>The master nodes <c>Masters</c> are not alive.</p></item>
+      <tag><c>{bad_rel_file, File}</c></tag>
+        <item><p>Specified <c>.rel</c> file <c>File</c> cannot be read or
+          does not contain a single term.</p></item>
+      <tag><c>{bad_rel_data, Data}</c></tag>
+        <item><p>Specified <c>.rel</c> file does not contain a recognized
+          release specification, but another term <c>Data</c>.</p></item>
+      <tag><c>{bad_relup_file, File}</c></tag>
+        <item><p>Specified <c>relup</c> file <c>Relup</c> contains bad
+          data.</p></item>
+      <tag><c>{cannot_extract_file, Name, Reason}</c></tag>
+        <item><p>Problems when extracting from a tar file,
+          <seealso marker="stdlib:erl_tar#extract/2"><c>erl_tar:extract/2</c></seealso>
+	  returned <c>{error, {Name, Reason}}</c>.</p></item>
+      <tag><c>{existing_release, Vsn}</c></tag>
+        <item><p>Specified release version <c>Vsn</c> is already
+          in use.</p></item>
+      <tag><c>{Master, Reason, When}</c></tag>
+        <item><p>Some operation, indicated by the term <c>When</c>, failed
+          on the master node <c>Master</c> with the specified error
+          reason <c>Reason</c>.</p></item>
+      <tag><c>{no_matching_relup, Vsn, CurrentVsn}</c></tag>
+        <item><p>Cannot find a script for upgrading/downgrading between
+          <c>CurrentVsn</c> and <c>Vsn</c>.</p></item>
+      <tag><c>{no_such_directory, Path}</c></tag>
+        <item><p>The directory <c>Path</c>does not exist.</p></item>
+      <tag><c>{no_such_file, Path}</c></tag>
+        <item><p>The path <c>Path</c> (file or directory) does not
+          exist.</p></item>
+      <tag><c>{no_such_file, {Master, Path}}</c></tag>
+        <item><p>The path <c>Path</c> (file or directory) does not exist at
+          the master node <c>Master</c>.</p></item>
+      <tag><c>{no_such_release, Vsn}</c></tag>
+        <item><p>The specified release version <c>Vsn</c> does not
+          exist.</p></item>
+      <tag><c>{not_a_directory, Path}</c></tag>
+        <item><p><c>Path</c> exists but is not a directory.</p></item>
+      <tag><c>{Posix, File}</c></tag>
+        <item><p>Some file operation failed for <c>File</c>. <c>Posix</c>
+          is an atom named from the Posix error codes, such as
+          <c>enoent</c>, <c>eacces</c>, or <c>eisdir</c>. See
+          <seealso marker="kernel:file"><c>file(3)</c></seealso>
+          in <c>Kernel</c>.</p></item>
+      <tag><c>Posix</c></tag>
+        <item><p>Some file operation failed, as for the previous item in
+          the list.</p></item>
+    </taglist>
   </section>
 
   <section>
-    <title>SEE ALSO</title>
-    <p><seealso marker="doc/design_principles:release_handling">OTP Design Principles</seealso>,
-      <seealso marker="kernel:config">config(4)</seealso>,
-      <seealso marker="relup">relup(4)</seealso>,
-      <seealso marker="rel">rel(4)</seealso>,
-      <seealso marker="script">script(4)</seealso>,
-      <seealso marker="stdlib:sys">sys(3)</seealso>,
-      <seealso marker="systools">systools(3)</seealso></p>
+    <title>See Also</title>
+    <p><seealso marker="doc/design_principles:users_guide">OTP Design Principles</seealso>,
+      <seealso marker="kernel:config"><c>config(4)</c></seealso>,
+      <seealso marker="rel"><c>rel(4)</c></seealso>,
+      <seealso marker="relup"><c>relup(4)</c></seealso>,
+      <seealso marker="script"><c>script(4)</c></seealso>,
+      <seealso marker="stdlib:sys"><c>sys(3)</c></seealso>,
+      <seealso marker="systools"><c>systools(3)</c></seealso></p>
   </section>
 </erlref>