Merge branch 'siri/sasl/improve-doc/OTP-9294'

* siri/sasl/improve-doc/OTP-9294:
  Add all valid report types in documentation of rb:list
  Fix minor faults in documentation of release handling
  Rename create_target.xml to create_target.xmlsrc to prepare for codeinclude

2 files changed, 40 insertions, 24 deletions

diff --git a/system/doc/design_principles/release_handling.xml b/system/doc/design_principles/release_handling.xml
index 8ed36f3c56..4378b6599c 100644
--- a/system/doc/design_principles/release_handling.xml
+++ b/system/doc/design_principles/release_handling.xml
@@ -178,13 +178,13 @@
     <marker id="instr"></marker>
     <title>Release Handling Instructions</title>
     <p>OTP supports a set of <em>release handling instructions</em>
-      that is used when creating <c>.appup</c> files. The release
+      that are used when creating <c>.appup</c> files. The release
       handler understands a subset of these, the <em>low-level</em>
       instructions. To make it easier for the user, there are also a
       number of <em>high-level</em> instructions, which are translated
       to low-level instructions by <c>systools:make_relup</c>.</p>
     <p>Here, some of the most frequently used instructions are
-      described. The complete list of instructions is found in
+      described. The complete list of instructions can be found in
       <c>appup(4)</c>.</p>
     <p>First, some definitions:</p>
     <taglist>
@@ -239,9 +239,10 @@
       <p><c>update</c> with argument <c>supervisor</c> is used when
         changing the start specification of a supervisor. See
         <seealso marker="appup_cookbook#sup">Appup Cookbook</seealso>.</p>
-      <p>The release handler finds the processes <em>using</em> a module
-        to update by traversing the supervision tree of each running
-        application and checking all the child specifications:</p>
+      <p>When a module is to be updated, the release handler finds
+        which processes that are <em>using</em> the module by
+        traversing the supervision tree of each running application
+        and checking all the child specifications:</p>
       <code type="none">
 {Id, StartFunc, Restart, Shutdown, Type, Modules}</code>
       <p>A process is using a module if the name is listed in
@@ -265,8 +266,8 @@
       <p>The instruction loads the module and is absolutely necessary
         when running Erlang in embedded mode. It is not strictly
         required when running Erlang in interactive (default) mode,
-        since the code server automatically searches for and loads
-        unloaded modules.</p>
+        since the code server then automatically searches for and
+        loads unloaded modules.</p>
       <p>The opposite of <c>add_module</c> is <c>delete_module</c> which
         unloads a module:</p>
       <code type="none">
@@ -294,7 +295,7 @@
         the modules are unloaded using a number of <c>delete_module</c>
         instructions and then the application specification is unloaded
         from the application controller.</p>
-      <p>Instruction for removing an application:</p>
+      <p>Instruction for restarting an application:</p>
       <code type="none">
 {restart_application, Application}</code>
       <p>Restarting an application means that the application is stopped
@@ -331,17 +332,17 @@
         of the emulator and the core applications. Then it shuts down
         the current emulator by calling <c>init:reboot()</c>, see
         <c>init(3)</c>. All processes are terminated gracefully and
-        the system can then be rebooted by the heart program, using
-        the temporary boot file. After the reboot, the rest of the
-        relup instructions are executed. This is done as a part of the
-        boot script.</p>
+        the system is rebooted by the heart program, using the
+        temporary boot file. After the reboot, the rest of the relup
+        instructions are executed. This is done as a part of the
+        temporary boot script.</p>
       <p>An info report is written when the upgrade is completed. To
         programatically find out if the upgrade is complete,
-        call <c>release_handler:which_releases/0</c> and check if the
-        expected release has status <c>current</c>.</p>
-      <p>The new version must be made permanent when the new emulator
-        is up and running. Otherwise, the old version will be used in
-        case of a new system reboot.</p>
+        call <c>release_handler:which_releases(current)</c> and check
+        if it returns the expected (i.e. the new) release.</p>
+      <p>The new release version must be made permanent when the new
+        emulator is up and running. Otherwise, the old version will be
+        used in case of a new system reboot.</p>
       <p>On UNIX, the release handler tells the heart program which
         command to use to reboot the system. Note that the environment
         variable <c>HEART_COMMAND</c>, normally used by the heart
@@ -362,8 +363,8 @@
 	a relup script, and it shall always be placed at the end. If
 	the relup is generated by <c>systools:make_relup/3,4</c> this
 	is automatically ensured.</p>
-      <p>When the release handler encounters the instruction, it shuts down
-        the emulator by calling <c>init:reboot()</c>, see
+      <p>When the release handler encounters the instruction, it shuts
+        down the emulator by calling <c>init:reboot()</c>, see
         <c>init(3)</c>. All processes are terminated gracefully and
         the system can then be rebooted by the heart program using the
         new release version. No more upgrade instruction will be
@@ -581,8 +582,8 @@ release_handler:remove_release(Vsn) => ok</code>
 [].</code>
     <p>2) Start the system as a simple target system. Note that in
       reality, it should be started as an embedded system. However,
-      using <c>erl</c> with the correct boot script and <c>.config</c>
-      file is enough for illustration purposes:</p>
+      using <c>erl</c> with the correct boot script and config file is
+      enough for illustration purposes:</p>
     <pre>
 % <input>cd $ROOT</input>
 % <input>bin/erl -boot $ROOT/releases/A/start -config $ROOT/releases/A/sys</input>
@@ -617,6 +618,7 @@ lib/ch_app-2/ebin/ch3.beam
 releases/B/start.boot
 releases/B/relup
 releases/B/sys.config
+releases/B/ch_rel-2.rel
 releases/ch_rel-2.rel</code>
     <p>4) Copy the release package <c>ch_rel-2.tar.gz</c> to
       the <c>$ROOT/releases</c> directory.</p>
diff --git a/system/doc/design_principles/release_structure.xml b/system/doc/design_principles/release_structure.xml
index 2e1daa611a..8aea0e1a10 100644
--- a/system/doc/design_principles/release_structure.xml
+++ b/system/doc/design_principles/release_structure.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2003</year><year>2009</year>
+      <year>2003</year><year>2011</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -61,12 +61,14 @@
   {ApplicationN, AppVsnN}]}.</code>
     <p>The file must be named <c>Rel.rel</c>, where <c>Rel</c> is a
       unique name.</p>
-    <p><c>Name</c>, <c>Vsn</c> and <c>Evsn</c> are strings.</p>
+    <p><c>Name</c>, <c>Vsn</c> and <c>EVsn</c> are strings.</p>
     <p>Each <c>Application</c> (atom) and <c>AppVsn</c> (string) is
       the name and version of an application included in the release.
-      Note the the minimal release based on Erlang/OTP consists of
+      Note that the minimal release based on Erlang/OTP consists of
       the <c>kernel</c> and <c>stdlib</c> applications, so these
       applications must be included in the list.</p>
+    <p>If the release is to be upgraded, it must also include
+      the <c>sasl</c> application.</p>
     <marker id="ch_rel"></marker>
     <p>Example: We want to make a release of <c>ch_app</c> from
       the <seealso marker="applications#ch_app">Applications</seealso>
@@ -173,6 +175,7 @@ lib/ch_app-1/ebin/ch_app.beam
 lib/ch_app-1/ebin/ch_sup.beam
 lib/ch_app-1/ebin/ch3.beam
 releases/A/start.boot
+releases/A/ch_rel-1.rel
 releases/ch_rel-1.rel</pre>
     <p>Note that a new boot script was generated, without
       the <c>local</c> option set, before the release package was made.
@@ -180,6 +183,17 @@ releases/ch_rel-1.rel</pre>
       under <c>lib</c>. Also, we do not know where the release package
       will be installed, so we do not want any hardcoded absolute paths
       in the boot script here.</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 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 duplicated in the tar file so no manual copying is
+      necessary.</p>
     <p>If a <c>relup</c> file and/or a system configuration file called
       <c>sys.config</c> is found, these files are included in
       the release package as well. See