Merge tag 'OTP-19.0' into sverker/19/binary_to_atom-utf8-crash/ERL-474/OTP-14590

1 files changed, 251 insertions, 206 deletions

diff --git a/lib/sasl/doc/src/appup.xml b/lib/sasl/doc/src/appup.xml
index bacfaa76ef..6fbdcb9f5b 100644
--- a/lib/sasl/doc/src/appup.xml
+++ b/lib/sasl/doc/src/appup.xml
@@ -1,23 +1,24 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
 <!DOCTYPE fileref SYSTEM "fileref.dtd">
 
 <fileref>
   <header>
     <copyright>
-      <year>1997</year><year>2012</year>
+      <year>1997</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
-      The contents of this file are subject to the Erlang Public License,
-      Version 1.1, (the "License"); you may not use this file except in
-      compliance with the License. You should have received a copy of the
-      Erlang Public License along with this software. If not, it can be
-      retrieved online at http://www.erlang.org/.
-    
-      Software distributed under the License is distributed on an "AS IS"
-      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
-      the License for the specific language governing rights and limitations
-      under the License.
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+ 
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
     
     </legalnotice>
 
@@ -28,75 +29,85 @@
     <rev></rev>
   </header>
   <file>appup</file>
-  <filesummary>Application upgrade file.</filesummary>
+  <filesummary>Application upgrade file</filesummary>
   <description>
     <p>The <em>application upgrade file</em> defines how an application
       is upgraded or downgraded in a running system.</p>
-    <p>This file is used by the functions in <c>systools</c> when
-      generating a release upgrade file <c>relup</c>.</p>
+    <p>This file is used by the functions in 
+    <seealso marker="systools"><c>systools</c></seealso> 
+    when generating a release upgrade file <c>relup</c>.</p>
   </description>
 
   <section>
-    <title>FILE SYNTAX</title>
-    <p>The application upgrade file should be called
-      <c>Application.appup</c> where <c>Application</c> is the name of
-      the application.  The file should be located in the <c>ebin</c>
+    <title>File Syntax</title>
+    <p>The application upgrade file is to be called
+      <c>Application.appup</c>, where <c>Application</c> is the
+      application name. The file is to be located in the <c>ebin</c>
       directory for the application.</p>
     <p>The <c>.appup</c> file contains one single Erlang term, which
       defines the instructions used to upgrade or downgrade
-      the application.  The file has the following syntax:</p>
+      the application. The file has the following syntax:</p>
     <code type="none">
 {Vsn,
   [{UpFromVsn, Instructions}, ...],
-  [{DownToVsn, Instructions}, ...]}.
-    </code>
-    <list type="bulleted">
-      <item>
-        <p><c>Vsn = string()</c> is the current version of
-          the application.</p>
-      </item>
-      <item>
-        <p><c>UpFromVsn = string() | binary()</c> is an earlier
-          version of the application to upgrade from. If it is a
-          string, it will be interpreted as a specific version
-          number. If it is a binary, it will be interpreted as a
-          regular expression which can match multiple version
-          numbers.</p>
-      </item>
-      <item>
-        <p><c>DownToVsn = string() | binary()</c> is an earlier
-          version of the application to downgrade to. If it is a
-          string, it will be interpreted as a specific version
-          number. If it is a binary, it will be interpreted as a
-          regular expression which can match multiple version
-          numbers.</p>
-      </item>
-      <item>
-        <p><c>Instructions</c> is a list of <em>release upgrade instructions</em>, see below. It is recommended to use
+  [{DownToVsn, Instructions}, ...]}.</code>
+    <taglist>
+      <tag><c>Vsn = string()</c></tag>
+        <item><p>Current application version.</p></item>
+      <tag><c>UpFromVsn = string() | binary()</c></tag>
+        <item><p>An earlier
+          application version to upgrade from. If it is a
+          string, it is interpreted as a specific version
+          number. If it is a binary, it is interpreted as a
+          regular expression that can match multiple version
+          numbers.</p></item>
+      <tag><c>DownToVsn = string() | binary()</c></tag>
+        <item><p>An earlier
+          application version to downgrade to. If it is a
+          string, it is  interpreted as a specific version
+          number. If it is a binary, it is interpreted as a
+          regular expression that can match multiple version
+          numbers.</p></item>
+      <tag><c>Instructions</c></tag>
+        <item><p>A list of <em>release upgrade instructions</em>, see
+          <seealso marker="#Release Upgrade Instructions">Release
+          Upgrade Instructions</seealso>. It is recommended to use
           high-level instructions only. These are automatically
           translated to low-level instructions by <c>systools</c> when
-          creating the <c>relup</c> file.</p>
-      </item>
-    </list>
-    <p>In order to avoid duplication of upgrade instructions it is
-    allowed to use regular expressions to specify the <c>UpFromVsn</c>
-    and <c>DownToVsn</c>. To be considered a regular expression, the
-    version identifier must be specified as a binary, e.g.</p>
-    <code type="none">&lt;&lt;"2\\.1\\.[0-9]+">></code>
-    <p>will match all versions <c>2.1.x</c>, where x is any number.</p>
+          creating the <c>relup</c> file.</p></item>
+    </taglist>
+    <p>To avoid duplication of upgrade instructions, it is
+      allowed to use regular expressions to specify <c>UpFromVsn</c>
+      and <c>DownToVsn</c>. To be considered a regular expression, the
+      version identifier must be specified as a binary. For example,
+      the following match all versions <c>2.1.x</c>, where <c>x</c> is
+      any number:</p>
+    <code type="none">
+&lt;&lt;"2\\.1\\.[0-9]+">></code>
+    <p>Notice that the regular expression must match the complete
+      version string, so this example works for, for example,
+      <c>2.1.1</c>, but not for <c>2.1.1.1</c>.</p>
   </section>
 
   <section>
-    <title>RELEASE UPGRADE INSTRUCTIONS</title>
+    <marker id="Release Upgrade Instructions"></marker>
+    <title>Release Upgrade Instructions</title>
     <p>Release upgrade instructions are interpreted by the release
       handler when an upgrade or downgrade is made. For more
-      information about release handling, refer to <em>OTP Design Principles</em>.</p>
-    <p>A process is said to <em>use</em> a module <c>Mod</c>, if
+      information about release handling, see
+      <seealso marker="doc/design_principles:release_handling">OTP
+      Design Principles</seealso> in <em>System Documentation</em>.</p>
+    <p>A process is said to <em>use</em> a module <c>Mod</c> if
       <c>Mod</c> is listed in the <c>Modules</c> part of the child
-      specification used to start the process, see <c>supervisor(3)</c>.
-      In the case of gen_event, an event manager process is said to use
-      <c>Mod</c> if <c>Mod</c> is an installed event handler.</p>
-    <p><em>High-level instructions</em></p>
+      specification used to start the process, see
+      <seealso marker="stdlib:supervisor"><c>supervisor(3)</c></seealso>.
+      In the case of 
+      <seealso marker="stdlib:gen_event"><c>gen_event</c></seealso>, 
+      an event manager process is said to use <c>Mod</c> if <c>Mod</c> 
+      is an installed event handler.</p>
+
+    <section>
+    <title>High-Level Instructions</title>
     <pre>
 {update, Mod}
 {update, Mod, supervisor}
@@ -112,52 +123,69 @@
   Change = soft | {advanced,Extra}
     Extra = term()
   PrePurge = PostPurge = soft_purge | brutal_purge
-  DepMods = [Mod]
-    </pre>
-    <p>Synchronized code replacement of processes using the module
-      <c>Mod</c>. All those processes are suspended using
-      <c>sys:suspend</c>, the new version of the module is loaded and
-      then the processes are resumed using <c>sys:resume</c>.</p>
-    <p><c>Change</c> defaults to <c>soft</c> and defines the type of
-      code change. If it is set to <c>{advanced,Extra}</c>, processes
-      implemented using gen_server, gen_fsm or gen_event will transform
-      their internal state by calling the callback function
-      <c>code_change</c>. Special processes will call the callback
+  DepMods = [Mod]</pre>
+    <p>Synchronized code replacement of processes using module
+      <c>Mod</c>.</p>
+    <p>All those processes are suspended using 
+      <seealso marker="stdlib:sys#suspend/1"><c>sys:suspend</c></seealso>,
+      the new module version is loaded, and
+      then the processes are resumed using 
+      <seealso marker="stdlib:sys#resume/1"><c>sys:resume</c></seealso>.</p>
+    <taglist>
+    <tag><c>Change</c></tag>
+      <item><p>Defaults to <c>soft</c> and defines the type of
+      code change. If it is set to <c>{advanced,Extra}</c>, implemented
+      processes using 
+      <seealso marker="stdlib:gen_server"><c>gen_server</c></seealso>, 
+      <seealso marker="stdlib:gen_fsm"><c>gen_fsm</c></seealso>,
+      <seealso marker="stdlib:gen_statem"><c>gen_statem</c></seealso>, or
+      <seealso marker="stdlib:gen_event"><c>gen_event</c></seealso> 
+      transform their internal state by calling the callback function
+      <c>code_change</c>. Special processes call the callback
       function <c>system_code_change/4</c>. In both cases, the term
-      <c>Extra</c> is passed as an argument to the callback function.</p>
-    <p><c>PrePurge</c> defaults to <c>brutal_purge</c> and controls
-      what action to take with processes that are executing old code
-      before loading the new version of the module. If the value
+      <c>Extra</c> is passed as an argument to the callback
+      function.</p></item>
+    <tag><c>PrePurge</c></tag>
+      <item><p>Defaults to <c>brutal_purge</c>. It controls
+      what action to take with processes executing old code
+      before loading the new module version. If the value
       is <c>brutal_purge</c>, the processes are killed. If the value is
-      <c>soft_purge</c>, <c>release_handler:install_release/1</c>
-      returns <c>{error,{old_processes,Mod}}</c>.</p>
-    <p><c>PostPurge</c> defaults to <c>brutal_purge</c> and controls
+      <c>soft_purge</c>, 
+      <seealso marker="release_handler#install_release/1"><c>release_handler:install_release/1</c></seealso>
+      returns <c>{error,{old_processes,Mod}}</c>.</p></item>
+    <tag><c>PostPurge</c></tag>
+      <item><p>Defaults to <c>brutal_purge</c>. It controls
       what action to take with processes that are executing old code
-      when the new version of the module has been loaded. If the value
+      when the new module version has been loaded. If the value
       is <c>brutal_purge</c>, the code is purged when the release is
       made permanent and the processes are killed. If the value is
-      <c>soft_purge</c>, the release handler will purge the old code
-      when no remaining processes execute the code.</p>
-    <p><c>DepMods</c> defaults to [] and defines which other modules
-      <c>Mod</c> is dependent on. In <c>relup</c>, instructions for
-      suspending processes using <c>Mod</c> will come before
+      <c>soft_purge</c>, the release handler purges the old code
+      when no remaining processes execute the code.</p></item>
+    <tag><c>DepMods</c></tag>
+      <item><p>Defaults to <c>[]</c> and defines other modules that
+      <c>Mod</c> is dependent on. In the <c>relup</c> file, instructions 
+      for suspending processes using <c>Mod</c> come before
       instructions for suspending processes using modules in
-      <c>DepMods</c> when upgrading, and vice versa when downgrading.
+      <c>DepMods</c> when upgrading, and conversely when downgrading.
       In case of circular dependencies, the order of the instructions in
-      the <c>appup</c> script is kept.</p>
-    <p><c>Timeout</c> defines the timeout when suspending processes.
-      If no value or <c>default</c> is given, the default value for
-      <c>sys:suspend</c> is used.</p>
-    <p><c>ModType</c> defaults to <c>dynamic</c> and specifies if
-      the code is "dynamic", that is if a process using the module does
-      spontaneously switch to new code, or if it is "static".
-      When doing an advanced update and upgrading, the new version of a
+      the <c>appup</c> file is kept.</p></item>
+    <tag><c>Timeout</c></tag>
+      <item><p>Defines the time-out when suspending processes.
+      If no value or <c>default</c> is specified, the default value for
+      <seealso marker="stdlib:sys#suspend/1"><c>sys:suspend</c></seealso> 
+      is used.</p></item>
+    <tag><c>ModType</c></tag>
+      <item><p>Defaults to <c>dynamic</c>. It specifies if
+      the code is "dynamic", that is, if a process using the module
+      spontaneously switches to new code, or if it is "static".
+      When doing an advanced update and upgrade, the new version of a
       dynamic module is loaded before the process is asked to change
       code. When downgrading, the process is asked to change code before
       loading the new version. For static modules, the new version is
       loaded before the process is asked to change code, both in
       the case of upgrading and downgrading. Callback modules are
-      dynamic.</p>
+      dynamic.</p></item>
+    </taglist>
     <p><c>update</c> with argument <c>supervisor</c> is used when
       changing the start specification of a supervisor.</p>
     <pre>
@@ -166,212 +194,229 @@
 {load_module, Mod, PrePurge, PostPurge, DepMods}
   Mod = atom()
   PrePurge = PostPurge = soft_purge | brutal_purge
-  DepMods = [Mod]
-    </pre>
+  DepMods = [Mod]</pre>
     <p>Simple code replacement of the module <c>Mod</c>.</p>
-    <p>See <c>update</c> above for a description of <c>PrePurge</c> and
-      <c>PostPurge</c>.</p>
-    <p><c>DepMods</c> defaults to [] and defines which other modules
-      <c>Mod</c> is dependent on. In <c>relup</c>, instructions for
-      loading these modules will come before the instruction for loading
-      <c>Mod</c> when upgrading, and vice versa when downgrading.</p>
+    <p>For a description of <c>PrePurge</c> and <c>PostPurge</c>,
+      see <c>update</c> above.</p>
+    <p><c>DepMods</c> defaults to <c>[]</c> and defines which other modules
+      <c>Mod</c> is dependent on. In the <c>relup</c> file, instructions for
+      loading these modules come before the instruction for loading
+      <c>Mod</c> when upgrading, and conversely when downgrading.</p>
     <pre>
 {add_module, Mod}
+{add_module, Mod, DepMods}
   Mod = atom()
-    </pre>
+  DepMods = [Mod]</pre>
     <p>Loads a new module <c>Mod</c>.</p>
+    <p><c>DepMods</c> defaults to <c>[]</c> and defines which other modules
+      <c>Mod</c> is dependent on. In the <c>relup</c> file, instructions
+      related to these modules come before the instruction for
+      loading <c>Mod</c> when upgrading, and conversely when
+      downgrading.</p>
     <pre>
 {delete_module, Mod}
-  Mod = atom()
-    </pre>
+{delete_module, Mod, DepMods}
+  Mod = atom()</pre>
     <p>Deletes a module <c>Mod</c> using the low-level instructions
       <c>remove</c> and <c>purge</c>.</p>
+    <p><c>DepMods</c> defaults to <c>[]</c> and defines which other modules
+      <c>Mod</c> is dependent on. In the <c>relup</c> file, instructions
+      related to these modules come before the instruction for
+      removing <c>Mod</c> when upgrading, and conversely when
+      downgrading.</p>
     <pre>
 {add_application, Application}
 {add_application, Application, Type}
   Application = atom()
-  Type = permanent | transient | temporary | load | none
-    </pre>
+  Type = permanent | transient | temporary | load | none</pre>
     <p>Adding an application means that the modules defined by
       the <c>modules</c> key in the <c>.app</c> file are loaded using
       <c>add_module</c>.</p>
     <p><c>Type</c> defaults to <c>permanent</c> and specifies the start type
       of the application. If <c>Type = permanent | transient | temporary</c>,
-      the application will be loaded and started in the corresponding way,
-      see <c>application(3)</c>. If <c>Type = load</c>, the application will
-      only be loaded. If <c>Type = none</c>, the application will be neither
-      loaded nor started, although the code for its modules will be loaded.</p>
+      the application is loaded and started in the corresponding way, see
+      <seealso marker="kernel:application"><c>application(3)</c></seealso>.
+      If <c>Type = load</c>, the application is only loaded.
+      If <c>Type = none</c>, the application is not loaded and not
+      started, although the code for its modules is loaded.</p>
     <pre>
 {remove_application, Application}
-  Application = atom()
-    </pre>
+  Application = atom()</pre>
     <p>Removing an application means that the application is stopped,
-      the modules are unloaded using <c>delete_module</c> and then
+      the modules are unloaded using <c>delete_module</c>, and then
       the application specification is unloaded from the application
       controller.</p>
     <pre>
 {restart_application, Application}
-  Application = atom()
-    </pre>
+  Application = atom()</pre>
     <p>Restarting an application means that the application is
-      stopped and then started again similar to using the instructions
+      stopped and then started again, similar to using the instructions
       <c>remove_application</c> and <c>add_application</c> in sequence.</p>
-    <p><em>Low-level instructions</em></p>
+    </section>
+
+    <section>
+    <title>Low-Level Instructions</title>
     <pre>
 {load_object_code, {App, Vsn, [Mod]}}
   App = Mod = atom()
-  Vsn = string()
-    </pre>
-    <p>Reads each <c>Mod</c> from the directory <c>App-Vsn/ebin</c> as
-      a binary. It does not load the modules. The instruction should be
-      placed first in the script in order to read all new code from file
-      to make the suspend-load-resume cycle less time consuming. After
-      this instruction has been executed, the code server with the new
-      version of <c>App</c>.</p>
+  Vsn = string()</pre>
+    <p>Reads each <c>Mod</c> from directory <c>App-Vsn/ebin</c> as
+      a binary. It does not load the modules. The instruction is to be
+      placed first in the script to read all new code from the file
+      to make the suspend-load-resume cycle less time-consuming.</p>
     <pre>
-point_of_no_return
-    </pre>
+point_of_no_return</pre>
     <p>If a crash occurs after this instruction, the system cannot
-      recover and is restarted from the old version of the release.
-      The instruction must only occur once in a script. It should be
+      recover and is restarted from the old release version.
+      The instruction must only occur once in a script. It is to be
       placed after all <c>load_object_code</c> instructions.</p>
     <pre>
 {load, {Mod, PrePurge, PostPurge}}
   Mod = atom()
-  PrePurge = PostPurge = soft_purge | brutal_purge
-    </pre>
+  PrePurge = PostPurge = soft_purge | brutal_purge</pre>
     <p>Before this instruction occurs, <c>Mod</c> must have been loaded
       using <c>load_object_code</c>. This instruction loads the module.
-      <c>PrePurge</c> is ignored. See the high-level instruction
-      <c>update</c> for a description of <c>PostPurge</c>.</p>
+      <c>PrePurge</c> is ignored. For a description of <c>PostPurge</c>,
+      see the high-level instruction <c>update</c> earlier.</p>
     <pre>
 {remove, {Mod, PrePurge, PostPurge}}
   Mod = atom()
-  PrePurge = PostPurge = soft_purge | brutal_purge
-    </pre>
+  PrePurge = PostPurge = soft_purge | brutal_purge</pre>
     <p>Makes the current version of <c>Mod</c> old.
-      <c>PrePurge</c> is ignored. See the high-level instruction
-      <c>update</c> for a description of <c>PostPurge</c>.</p>
+      <c>PrePurge</c> is ignored. For a description of <c>PostPurge</c>,
+      see the high-level instruction <c>update</c> earlier.</p>
     <pre>
 {purge, [Mod]}
-  Mod = atom()
-    </pre>
-    <p>Purges each module <c>Mod</c>, that is removes the old code.
-      Note that any process executing purged code is killed.</p>
+  Mod = atom()</pre>
+    <p>Purges each module <c>Mod</c>, that is, removes the old code.
+      Notice that any process executing purged code is killed.</p>
     <pre>
 {suspend, [Mod | {Mod, Timeout}]}
   Mod = atom()
-  Timeout = int()>0 | default | infinity
-    </pre>
+  Timeout = int()>0 | default | infinity</pre>
     <p>Tries to suspend all processes using a module <c>Mod</c>. If a
-      process does not respond, it is ignored. This may cause
+      process does not respond, it is ignored. This can cause
       the process to die, either because it crashes when it
       spontaneously switches to new code, or as a result of a purge
       operation. If no <c>Timeout</c> is specified or <c>default</c> is
-      given, the default value for <c>sys:suspend</c> is used.</p>
+      specified, the default value for 
+      <seealso marker="stdlib:sys#suspend/1"><c>sys:suspend</c></seealso> 
+      is used.</p>
     <pre>
 {resume, [Mod]}
-  Mod = atom()
-    </pre>
+  Mod = atom()</pre>
     <p>Resumes all suspended processes using a module <c>Mod</c>.</p>
     <pre>
 {code_change, [{Mod, Extra}]}
 {code_change, Mode, [{Mod, Extra}]}
   Mod = atom()
   Mode = up | down
-  Extra = term()
-    </pre>
+  Extra = term()</pre>
     <p><c>Mode</c> defaults to <c>up</c> and specifies if it is an
-      upgrade or downgrade.</p>
-    <p>This instruction sends a <c>code_change</c> system message to
-      all processes using a module <c>Mod</c> by calling the function
-      <c>sys:change_code</c>, passing the term <c>Extra</c> as argument.</p>
+      upgrade or downgrade. This instruction sends a <c>code_change</c>
+      system message to all processes using a module <c>Mod</c> by
+      calling function 
+      <seealso marker="stdlib:sys#change_code/4"><c>sys:change_code</c></seealso>, 
+      passing term <c>Extra</c> as argument.</p>
     <pre>
 {stop, [Mod]}
-  Mod = atom()
-    </pre>
+  Mod = atom()</pre>
     <p>Stops all processes using a module <c>Mod</c> by calling
-      <c>supervisor:terminate_child/2</c>. The instruction is useful
+      <seealso marker="stdlib:supervisor#terminate_child/2"><c>supervisor:terminate_child/2</c></seealso>. 
+      This instruction is useful
       when the simplest way to change code is to stop and restart the
-      processes which run the code.</p>
+      processes that run the code.</p>
     <pre>
 {start, [Mod]}
-  Mod = atom()
-    </pre>
+  Mod = atom()</pre>
     <p>Starts all stopped processes using a module <c>Mod</c> by calling
-      <c>supervisor:restart_child/2</c>.</p>
+      <seealso marker="stdlib:supervisor#restart_child/2"><c>supervisor:restart_child/2</c></seealso>.</p>
     <pre>
 {sync_nodes, Id, [Node]}
 {sync_nodes, Id, {M, F, A}}
   Id = term()
   Node = node()
   M = F = atom()
-  A = [term()]
-    </pre>
+  A = [term()]</pre>
     <p><c>apply(M, F, A)</c> must return a list of nodes.</p>
-    <p>The instruction synchronizes the release installation with other
-      nodes. Each <c>Node</c> must evaluate this command, with the same
+    <p>This instruction synchronizes the release installation with other
+      nodes. Each <c>Node</c> must evaluate this command with the same
       <c>Id</c>. The local node waits for all other nodes to evaluate
-      the instruction before execution continues. In case a node goes
+      the instruction before execution continues. If a node goes
       down, it is considered to be an unrecoverable error, and
       the local node is restarted from the old release. There is no
-      timeout for this instruction, which means that it may hang
+      time-out for this instruction, which means that it can hang
       forever.</p>
     <pre>
 {apply, {M, F, A}}
   M = F = atom()
-  A = [term()]
-    </pre>
-    <p>Evaluates <c>apply(M, F, A)</c>. If the instruction appears
-      before the <c>point_of_no_return</c> instruction, a failure is
-      caught. <c>release_handler:install_release/1</c> then returns
-      <c>{error,{'EXIT',Reason}}</c>, unless <c>{error,Error}</c> is
-      thrown or returned. Then it returns <c>{error,Error}</c>.</p>
-    <p>If the instruction appears after the <c>point_of_no_return</c>
-      instruction, and the function call fails, the system is
-      restarted.</p>
+  A = [term()]</pre>
+    <p>Evaluates <c>apply(M, F, A)</c>.</p>
+    <p>If the instruction appears before instruction
+      <c>point_of_no_return</c>, a failure is caught.
+      <seealso marker="release_handler#install_release/1"><c>release_handler:install_release/1</c></seealso> 
+      then returns <c>{error,{'EXIT',Reason}}</c>, unless <c>{error,Error}</c> 
+      is thrown or returned. Then it returns <c>{error,Error}</c>.</p>
+    <p>If the instruction appears after instruction
+      <c>point_of_no_return</c> and the function call fails, the
+      system is restarted.</p>
     <pre>
-restart_new_emulator
-    </pre>
-    <p>This instruction is used when erts, kernel, stdlib or sasl is
+restart_new_emulator</pre>
+    <p>This instruction is used when the application <c>ERTS</c>,
+      <c>Kernel</c>, <c>STDLIB</c>, or <c>SASL</c> is
       upgraded. It shuts down the current emulator and starts a new
       one. All processes are terminated gracefully, and the new
-      version of erts, kernel, stdlib and sasl are used when the
-      emulator restarts. Only one <c>restart_new_emulator</c>
-      instruction is allowed in the relup, and it shall be placed
-      first. <seealso marker="systools#make_relup/3">systools:make_relup3,4</seealso>
-      will ensure this when the relup is generated. The rest of the
-      relup script is executed after the restart as a part of the boot
-      script.</p>
-    <p>An info report will be written when the upgrade is
-      completed. To programatically find out if the upgrade is
-      complete,
+      version of <c>ERTS</c>, <c>Kernel</c>, <c>STDLIB</c>, and
+      <c>SASL</c> are used when the emulator restarts.
+      Only one <c>restart_new_emulator</c> instruction is allowed
+      in the <c>relup</c> file, and it must be placed first.
+      <seealso marker="systools#make_relup/3"><c>systools:make_relup/3,4</c></seealso>
+      ensures this when the <c>relup</c> file is generated. The rest of the
+      instructions in the <c>relup</c> file is executed after the
+      restart as a part of the boot script.</p>
+    <p>An info report is written when the upgrade is completed.
+      To programmatically determine if the upgrade is complete,
       call <seealso marker="release_handler#which_releases/0">
-      release_handler:which_releases</seealso> and check if the
+      <c>release_handler:which_releases/0,1</c></seealso> and check if the
       expected release has status <c>current</c>.</p>
     <p>The new release must still be made permanent after the upgrade
-      is completed. Otherwise, the old emulator is started in case of
+      is completed, otherwise the old emulator is started if there is
       an emulator restart.</p>
+    <warning>
+      <p>As stated earlier, instruction <c>restart_new_emulator</c>
+        causes the emulator to be restarted with new versions of
+        <c>ERTS</c>, <c>Kernel</c>, <c>STDLIB</c>, and <c>SASL</c>.
+        However, all other applications do at startup run their old
+        versions in this new emulator. This is usually no problem,
+        but every now and then incompatible changes occur to the
+        core applications, which can cause
+        trouble in this setting. Such incompatible changes (when
+        functions are removed) are normally preceded by a deprecation
+        over two major releases. To ensure that your application is not
+        crashed by an incompatible change, always remove any call to
+        deprecated functions as soon as possible.</p>
+    </warning>
     <pre>
-restart_emulator
-    </pre>
+restart_emulator</pre>
     <p>This instruction is similar to <c>restart_new_emulator</c>,
-      except it shall be placed at the end of the relup script. It is
-      not related to an upgrade of the emulator or the core
+      except it must be placed at the end of the <c>relup</c> file.
+      It is not related to an upgrade of the emulator or the core
       applications, but can be used by any application when a complete
-      reboot of the system is reqiured.  When generating the
-      relup, <seealso marker="systools#make_relup/3">systools:make_relup/3,4</seealso>
+      reboot of the system is required.</p>
+    <p>When generating the <c>relup</c> file,
+      <seealso marker="systools#make_relup/3"><c>systools:make_relup/3,4</c></seealso>
       ensures that there is only one <c>restart_emulator</c>
-      instruction and that it is the last instruction of the
-      relup.</p>
+      instruction and that it is the last instruction in the
+      <c>relup</c> file.</p>
+    </section>
   </section>
 
   <section>
-    <title>SEE ALSO</title>
-    <p><seealso marker="relup">relup(4)</seealso>,
-      <seealso marker="release_handler">release_handler(3)</seealso>,
-      supervisor(3),
-      <seealso marker="systools">systools(3)</seealso></p>
+    <title>See Also</title>
+    <p><seealso marker="release_handler"><c>release_handler(3)</c></seealso>,
+      <seealso marker="relup"><c>relup(4)</c></seealso>,
+      <seealso marker="stdlib:supervisor"><c>supervisor(3)</c></seealso>,
+      <seealso marker="systools"><c>systools(3)</c></seealso></p>
   </section>
 </fileref>