Merge branch 'bjorn/kernel/doc'

* bjorn/kernel/doc:
  code: Remove 'bad_path' error code from set_path/1
  Update Kernel documentation

1 files changed, 76 insertions, 90 deletions

diff --git a/lib/kernel/doc/src/heart.xml b/lib/kernel/doc/src/heart.xml
index 9da4773f2d..7c37c5ea00 100644
--- a/lib/kernel/doc/src/heart.xml
+++ b/lib/kernel/doc/src/heart.xml
@@ -29,93 +29,80 @@
     <rev>A</rev>
   </header>
   <module>heart</module>
-  <modulesummary>Heartbeat Monitoring of an Erlang Runtime System</modulesummary>
+  <modulesummary>Heartbeat monitoring of an Erlang runtime system.</modulesummary>
   <description>
     <p>This modules contains the interface to the <c>heart</c> process.
       <c>heart</c> sends periodic heartbeats to an external port
       program, which is also named <c>heart</c>. The purpose of
-      the heart port program is to check that the Erlang runtime system
+      the <c>heart</c> port program is to check that the Erlang runtime system
       it is supervising is still running. If the port program has not
       received any heartbeats within <c>HEART_BEAT_TIMEOUT</c> seconds
-      (default is 60 seconds), the system can be rebooted. Also, if
+      (defaults to 60 seconds), the system can be rebooted. Also, if
       the system is equipped with a hardware watchdog timer and is
       running Solaris, the watchdog can be used to supervise the entire
       system.</p>
-    <p>An Erlang runtime system to be monitored by a heart program,
-      should be started with the command line flag <c>-heart</c> (see
-      also <seealso marker="erts:erl">erl(1)</seealso>). The <c>heart</c>
-      process is then started automatically:</p>
+    <p>An Erlang runtime system to be monitored by a heart program
+      is to be started with command-line flag <c>-heart</c> (see
+      also <seealso marker="erts:erl"><c>erl(1)</c></seealso>).
+      The <c>heart</c> process is then started automatically:</p>
     <pre>
 % <input>erl -heart ...</input></pre>
-    <p>If the system should be rebooted because of missing heart-beats,
-      or a terminated Erlang runtime system, the environment variable
-      <c>HEART_COMMAND</c> has to be set before the system is started.
-      If this variable is not set, a warning text will be printed but
-      the system will not reboot. However, if the hardware watchdog is
-      used, it will trigger a reboot <c>HEART_BEAT_BOOT_DELAY</c>
-      seconds later nevertheless (default is 60).</p>
-    <p>To reboot on the WINDOWS platform <c>HEART_COMMAND</c> can be
+    <p>If the system is to be rebooted because of missing heartbeats,
+      or a terminated Erlang runtime system, environment variable
+      <c>HEART_COMMAND</c> must be set before the system is started.
+      If this variable is not set, a warning text is printed but
+      the system does not reboot. However, if the hardware watchdog is
+      used, it still triggers a reboot <c>HEART_BEAT_BOOT_DELAY</c>
+      seconds later (defaults to 60 seconds).</p>
+    <p>To reboot on Windows, <c>HEART_COMMAND</c> can be
       set to <c>heart -shutdown</c> (included in the Erlang delivery)
-      or of course to any other suitable program which can activate a
-      reboot.</p>
-    <p>The hardware watchdog will not be started under Solaris if
-      the environment variable <c>HW_WD_DISABLE</c> is set.</p>
-    <p>The <c>HEART_BEAT_TIMEOUT</c> and <c>HEART_BEAT_BOOT_DELAY</c>
-      environment variables can be used to configure the heart timeouts,
-      they can be set in the operating system shell before Erlang is
-      started or be specified at the command line:</p>
+      or to any other suitable program that can activate a reboot.</p>
+    <p>The hardware watchdog is not started under Solaris if
+      environment variable <c>HW_WD_DISABLE</c> is set.</p>
+    <p>The environment variables <c>HEART_BEAT_TIMEOUT</c> and
+      <c>HEART_BEAT_BOOT_DELAY</c> can be used to configure the heart
+      time-outs; they can be set in the operating system shell before Erlang
+      is started or be specified at the command line:</p>
     <pre>
 % <input>erl -heart -env HEART_BEAT_TIMEOUT 30 ...</input></pre>
     <p>The value (in seconds) must be in the range 10 &lt; X &lt;= 65535.</p>
-    <p>It should be noted that if the system clock is adjusted with
-      more than <c>HEART_BEAT_TIMEOUT</c> seconds, <c>heart</c> will
-      timeout and try to reboot the system. This can happen, for
-      example, if the system clock is adjusted automatically by use of
-      NTP (Network Time Protocol).</p>
-
-  <p> If a crash occurs, an <c><![CDATA[erl_crash.dump]]></c> will <em>not</em> be written
-	  unless the environment variable <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> is set.
-  </p>
-
+    <p>Notice that if the system clock is adjusted with
+      more than <c>HEART_BEAT_TIMEOUT</c> seconds, <c>heart</c>
+      times out and tries to reboot the system. This can occur, for
+      example, if the system clock is adjusted automatically by use of the
+      Network Time Protocol (NTP).</p>
+    <p>If a crash occurs, an <c><![CDATA[erl_crash.dump]]></c> is <em>not</em>
+      written unless environment variable
+        <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> is set:</p>
     <pre>
 % <input>erl -heart -env ERL_CRASH_DUMP_SECONDS 10 ...</input></pre>
-
-  <p> If a regular core dump is wanted, let heart know by setting the kill signal to abort
-      using the environment variable <c><![CDATA[HEART_KILL_SIGNAL=SIGABRT]]></c>.
-      If unset, or not set to <c><![CDATA[SIGABRT]]></c>, the default behaviour will be a kill
-      signal using <c><![CDATA[SIGKILL]]></c>.
-  </p>
-
+    <p>If a regular core dump is wanted, let <c>heart</c> know by setting
+      the kill signal to abort using environment variable
+      <c><![CDATA[HEART_KILL_SIGNAL=SIGABRT]]></c>. If unset, or not set to
+      <c><![CDATA[SIGABRT]]></c>, the default behavior is a kill signal using
+      <c><![CDATA[SIGKILL]]></c>:</p>
     <pre>
 % <input>erl -heart -env HEART_KILL_SIGNAL SIGABRT ...</input></pre>
-
-  <p>
-	  Furthermore, <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> has the following behaviour on
-	  <c>heart</c>:
-  </p>
-  <taglist>
-	  <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag>
-	  <item><p>
-			  Suppresses the writing a crash dump file entirely,
-			  thus rebooting the runtime system immediately.
-			  This is the same as not setting the environment variable.
-		  </p>
-	  </item>
-	  <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag>
-	  <item><p> Setting the environment variable to a negative value will not reboot
-			  the runtime system until the crash dump file has been completly written.
-		  </p>
-	  </item>
-	  <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag>
-	  <item><p>
-			  Heart will wait for <c>S</c> seconds to let the crash dump file be written.
-			  After <c>S</c> seconds <c>heart</c> will reboot the runtime system regardless of
-			  the crash dump file has been written or not.
-		  </p>
-	  </item>
-  </taglist>
-
-    <p>In the following descriptions, all function fails with reason
+    <p>Furthermore, <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> has the
+      following behavior on <c>heart</c>:</p>
+    <taglist>
+      <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag>
+      <item><p>Suppresses the writing of a crash dump file entirely,
+        thus rebooting the runtime system immediately.
+        This is the same as not setting the environment variable.</p>
+      </item>
+      <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag>
+      <item><p>Setting the environment variable to a negative value does not
+        reboot the runtime system until the crash dump file is completly
+        written.</p>
+      </item>
+      <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag>
+      <item><p><c>heart</c> waits for <c>S</c> seconds to let the crash dump
+        file be written. After <c>S</c> seconds, <c>heart</c> reboots the
+        runtime system, whether the crash dump file is written or not.</p>
+      </item>
+    </taglist>
+    <p>In the following descriptions, all functions fail with reason
       <c>badarg</c> if <c>heart</c> is not started.</p>
   </description>
 
@@ -128,37 +115,36 @@
   <funcs>
     <func>
       <name name="set_cmd" arity="1"/>
-      <fsummary>Set a temporary reboot command</fsummary>
+      <fsummary>Set a temporary reboot command.</fsummary>
       <desc>
-        <p>Sets a temporary reboot command. This command is used if 
+        <p>Sets a temporary reboot command. This command is used if
           a <c>HEART_COMMAND</c> other than the one specified with
-          the environment variable should be used in order to reboot
-          the system. The new Erlang runtime system will (if it
-          misbehaves) use the environment variable
-          <c>HEART_COMMAND</c> to reboot.</p>
-
-        <p>Limitations: The <c><anno>Cmd</anno></c> command string
-        will be sent to the heart program as a ISO-latin-1 or UTF-8
-        encoded binary depending on the file name encoding mode of the
-        emulator (see
-	<seealso marker="kernel:file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seealso>).
-	The size of the encoded binary must be less than 2047 bytes.</p>
+          the environment variable is to be used to reboot
+          the system. The new Erlang runtime system uses (if it misbehaves)
+          environment variable <c>HEART_COMMAND</c> to reboot.</p>
+        <p>Limitations: Command string <c><anno>Cmd</anno></c> is sent to the
+          <c>heart</c> program as an ISO Latin-1 or UTF-8 encoded binary,
+          depending on the filename encoding mode of the emulator (see
+          <seealso marker="kernel:file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seealso>).
+          The size of the encoded binary must be less than 2047 bytes.</p>
       </desc>
     </func>
+
     <func>
       <name name="clear_cmd" arity="0"/>
-      <fsummary>Clear the temporary boot command</fsummary>
+      <fsummary>Clear the temporary boot command.</fsummary>
       <desc>
         <p>Clears the temporary boot command. If the system terminates,
           the normal <c>HEART_COMMAND</c> is used to reboot.</p>
       </desc>
     </func>
+
     <func>
       <name name="get_cmd" arity="0"/>
-      <fsummary>Get the temporary reboot command</fsummary>
+      <fsummary>Get the temporary reboot command.</fsummary>
       <desc>
-        <p>Get the temporary reboot command. If the command is cleared,
-          the empty string will be returned.</p>
+        <p>Gets the temporary reboot command. If the command is cleared,
+          the empty string is returned.</p>
       </desc>
     </func>
 
@@ -166,12 +152,12 @@
       <name name="set_callback" arity="2"/>
       <fsummary>Set a validation callback</fsummary>
       <desc>
-          <p> This validation callback will be executed before any heartbeat sent
-              to the port program. For the validation to succeed it needs to return
-              with the value <c>ok</c>.
+          <p> This validation callback will be executed before any
+          heartbeat is sent to the port program. For the validation to
+          succeed it needs to return with the value <c>ok</c>.
         </p>
-        <p> An exception within the callback will be treated as a validation failure. </p>
-        <p> The callback will be removed if the system reboots. </p>
+        <p>An exception within the callback will be treated as a validation failure.</p>
+        <p>The callback will be removed if the system reboots.</p>
       </desc>
     </func>
     <func>