Update STDLIB documentation

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

1 files changed, 505 insertions, 326 deletions

diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
index 2255395f46..1120b926d5 100644
--- a/lib/stdlib/doc/src/sys.xml
+++ b/lib/stdlib/doc/src/sys.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2016</year>
+      <year>1996</year><year>2014</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -30,62 +30,67 @@
     <checked></checked>
     <date>1996-06-06</date>
     <rev></rev>
-    <file>sys.sgml</file>
+    <file>sys.xml</file>
   </header>
   <module>sys</module>
-  <modulesummary>A Functional Interface to System Messages</modulesummary>
+  <modulesummary>A functional interface to system messages.</modulesummary>
   <description>
-    <p>This module contains functions for sending system messages used by programs, and messages used for debugging purposes.
-      </p>
-    <p>Functions used for implementation of processes 
-      should also understand system messages such as debugging
-      messages and code change. These functions must be used to implement the use of system messages for a process; either directly, or through standard behaviours, such as <c>gen_server</c>.</p>
-    <p>The default timeout is 5000 ms, unless otherwise specified. The
-      <c>timeout</c> defines the time period to wait for the process to
+    <p>This module contains functions for sending system messages used by
+      programs, and messages used for debugging purposes.</p>
+    <p>Functions used for implementation of processes are also expected to
+      understand system messages, such as debug messages and code change. These
+      functions must be used to implement the use of system messages for a
+      process; either directly, or through standard behaviors, such as
+      <seealso marker="gen_server"><c>gen_server</c></seealso>.</p>
+    <p>The default time-out is 5000 ms, unless otherwise specified.
+      <c>timeout</c> defines the time to wait for the process to
       respond to a request. If the process does not respond, the
       function evaluates <c>exit({timeout, {M, F, A}})</c>.
       </p>
-    <p><marker id="dbg_opt"/>The functions make reference to a debug structure.
-      The debug structure is a list of <c>dbg_opt()</c>.
-      <c>dbg_opt()</c> is an internal data type used by the
-      <c>handle_system_msg/6</c> function. No debugging is performed if it is an empty list.
-      </p>
+    <marker id="dbg_opt"/>
+    <p>The functions make references to a debug structure.
+      The debug structure is a list of <c>dbg_opt()</c>, which is an internal
+      data type used by function <seealso marker="#handle_system_msg/6">
+      <c>handle_system_msg/6</c></seealso>. No debugging is performed if it is 
+      an empty list.</p>
   </description>
 
   <section>
     <title>System Messages</title>
-    <p>Processes which are not implemented as one of the standard
-      behaviours must still understand system
-      messages. There are three different messages which must be
-      understood:
-      </p>
+    <p>Processes that are not implemented as one of the standard
+      behaviors must still understand system messages. The following 
+      three messages must be understood:</p>
     <list type="bulleted">
       <item>
         <p>Plain system messages. These are received as
           <c>{system, From, Msg}</c>. The content and meaning of
           this message are not interpreted by the
-          receiving process module. When a system message has been
-          received, the function <c>sys:handle_system_msg/6</c>
-          is called in order to handle the request.
-          </p>
+          receiving process module. When a system message is received, function 
+	  <seealso marker="#handle_system_msg/6">
+          <c>handle_system_msg/6</c></seealso>
+          is called to handle the request.</p>
       </item>
       <item>
         <p>Shutdown messages. If the process traps exits, it must
-          be able to handle an shut-down request from its parent, the
+          be able to handle a shutdown request from its parent, the
           supervisor. The message <c>{'EXIT', Parent, Reason}</c>
-          from the parent is an order to terminate.  The process must terminate when this message is received, normally with the
+          from the parent is an order to terminate. The process must 
+	  terminate when this message is received, normally with the
           same <c>Reason</c> as <c>Parent</c>.
           </p>
       </item>
       <item>
-        <p>There is one more message which the process must understand if the modules used to implement the process change dynamically during runtime. An example of such a process is the <c>gen_event</c> processes. This message is <c>{get_modules, From}</c>. The reply to this message is <c>From ! {modules, Modules}</c>,
-          where <c>Modules</c> is a list of the currently active modules in the process.
-          </p>
+        <p>If the modules used to implement the process change dynamically
+          during runtime, the process must understand one more message. An
+          example is the <seealso marker="gen_event"><c>gen_event</c></seealso>
+          processes. The message is <c>{get_modules, From}</c>.
+          The reply to this message is <c>From ! {modules, Modules}</c>, where
+          <c>Modules</c> is a list of the currently active modules in the
+          process.</p>
         <p>This message is used by the release handler to find which
-          processes execute a certain module. The process may at a
-          later time be suspended and ordered to perform a code change
-          for one of its modules.
-          </p>
+          processes that execute a certain module. The process can later be
+          suspended and ordered to perform a code change for one of its
+          modules.</p>
       </item>
     </list>
   </section>
@@ -93,15 +98,16 @@
   <section>
     <title>System Events</title>
     <p>When debugging a process with the functions of this
-      module, the process generates <em>system_events</em> which are
+      module, the process generates <em>system_events</em>, which are
       then treated in the debug function. For example, <c>trace</c>
-      formats the system events to the tty.
+      formats the system events to the terminal.
       </p>
-    <p>There are three predefined system events which are used when a
+    <p>Three predefined system events are used when a
       process receives or sends a message. The process can also define its
       own system events. It is always up to the process itself
       to format these events.</p>
   </section>
+
   <datatypes>
     <datatype>
       <name name="name"/>
@@ -111,7 +117,7 @@
     </datatype>
     <datatype>
       <name name="dbg_opt"/>
-      <desc><p>See <seealso marker="#dbg_opt">above</seealso>.</p></desc>
+      <desc><p>See the introduction of this manual page.</p></desc>
     </datatype>
     <datatype>
       <name name="dbg_fun"/>
@@ -120,421 +126,594 @@
       <name name="format_fun"/>
     </datatype>
   </datatypes>
+
   <funcs>
     <func>
-      <name name="log" arity="2"/>
-      <name name="log" arity="3"/>
-      <fsummary>Log system events in memory</fsummary>
-      <desc>
-        <p>Turns the logging of system events On or Off. If On, a
-          maximum of <c><anno>N</anno></c>  events are kept in the
-          debug structure (the default is 10). If <c><anno>Flag</anno></c> is <c>get</c>, a list of all
-          logged events is returned. If <c><anno>Flag</anno></c> is <c>print</c>, the
-          logged events are printed to <c>standard_io</c>. The events are
-          formatted with a function that is defined by the process that
-          generated the event (with a call to
-          <c>sys:handle_debug/4</c>).</p>
-      </desc>
-    </func>
-    <func>
-      <name name="log_to_file" arity="2"/>
-      <name name="log_to_file" arity="3"/>
-      <fsummary>Log system events to the specified file</fsummary>
-      <desc>
-        <p>Enables or disables the logging of all system events in textual
-          format to the file. The events are formatted with a function that is 
-          defined by the process that generated the event (with a call
-          to <c>sys:handle_debug/4</c>).</p>
-      </desc>
-    </func>
-    <func>
-      <name name="statistics" arity="2"/>
-      <name name="statistics" arity="3"/>
-      <fsummary>Enable or disable the collections of statistics</fsummary>
+      <name name="change_code" arity="4"/>
+      <name name="change_code" arity="5"/>
+      <fsummary>Send the code change system message to the process.</fsummary>
       <desc>
-        <p>Enables or disables the collection of statistics. If <c><anno>Flag</anno></c> is
-          <c>get</c>, the statistical collection is returned.</p>
+        <p>Tells the process to change code. The process must be
+          suspended to handle this message. Argument <c><anno>Extra</anno></c>
+          is reserved for each process to use as its own. Function
+          <c><anno>Module</anno>:system_code_change/4</c> is called.
+	  <c><anno>OldVsn</anno></c> is the old version of the
+          <c><anno>Module</anno></c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="trace" arity="2"/>
-      <name name="trace" arity="3"/>
-      <fsummary>Print all system events on <c>standard_io</c></fsummary>
+      <name name="get_state" arity="1"/>
+      <name name="get_state" arity="2"/>
+      <fsummary>Get the state of the process.</fsummary>
       <desc>
-        <p>Prints all system events on <c>standard_io</c>. The events are
-          formatted with a function that is defined by the process that
-          generated the event (with a call to
-          <c>sys:handle_debug/4</c>).</p>
+        <p>Gets the state of the process.</p>
+        <note>
+          <p>These functions are intended only to help with debugging. They are
+            provided for convenience, allowing developers to avoid having to
+            create their own state extraction functions and also avoid having
+            to interactively extract the state from the return values of
+            <seealso marker="#get_status-1"><c>get_status/1</c></seealso> or
+            <seealso marker="#get_status-2"><c>get_status/2</c></seealso>
+            while debugging.</p>
+        </note>
+        <p>The value of <c><anno>State</anno></c> varies for different types of
+          processes, as follows:</p>
+        <list type="bulleted">
+          <item>
+            <p>For a
+              <seealso marker="gen_server"><c>gen_server</c></seealso>
+              process, the returned <c><anno>State</anno></c>
+              is the state of the callback module.</p>
+          </item>
+          <item>
+            <p>For a
+              <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>
+              process, <c><anno>State</anno></c> is the tuple
+              <c>{CurrentStateName, CurrentStateData}</c>.</p>
+          </item>
+          <item>
+            <p>For a
+              <seealso marker="gen_statem"><c>gen_statem</c></seealso>
+              process, <c><anno>State</anno></c> is the tuple
+              <c>{CurrentState,CurrentData}</c>.</p>
+          </item>
+          <item>
+            <p>For a
+              <seealso marker="gen_event"><c>gen_event</c></seealso>
+              process, <c><anno>State</anno></c> is a list of tuples,
+              where each tuple corresponds to an event handler registered
+              in the process and contains <c>{Module, Id, HandlerState}</c>,
+              as follows:</p>
+            <taglist>
+              <tag><c>Module</c></tag>
+              <item>
+                <p>The module name of the event handler.</p>
+              </item>
+              <tag><c>Id</c></tag>
+              <item>
+                <p>The ID of the handler (which is <c>false</c> if it was 
+                  registered without an ID).</p>
+              </item>
+              <tag><c>HandlerState</c></tag>
+              <item>
+                <p>The state of the handler.</p>
+              </item>
+            </taglist>
+          </item>
+        </list>
+        <p>If the callback module exports a function <c>system_get_state/1</c>,
+          it is called in the target process to get its state. Its argument is
+          the same as the <c>Misc</c> value returned by
+          <seealso marker="#get_status-1"><c>get_status/1,2</c></seealso>, and
+          function <seealso marker="#Module:system_get_state/1">
+          <c>Module:system_get_state/1</c></seealso> is expected to extract the
+          state of the callback module from it. Function
+          <c>system_get_state/1</c> must return <c>{ok, State}</c>, where
+          <c>State</c> is the state of the callback module.</p>
+        <p>If the callback module does not export a <c>system_get_state/1</c>
+          function, <c>get_state/1,2</c> assumes that the <c>Misc</c> value is
+          the state of the callback module and returns it directly instead.</p>
+        <p>If the callback module's <c>system_get_state/1</c> function crashes
+          or throws an exception, the caller exits with error 
+          <c>{callback_failed, {Module, system_get_state}, {Class, Reason}}</c>,
+          where <c>Module</c> is the name of the callback module and
+          <c>Class</c> and <c>Reason</c> indicate details of the exception.</p>
+        <p>Function <c>system_get_state/1</c> is primarily useful for
+          user-defined behaviors and modules that implement OTP
+          <seealso marker="#special_process">special processes</seealso>. 
+          The <c>gen_server</c>, <c>gen_fsm</c>,
+	  <c>gen_statem</c>, and <c>gen_event</c> OTP
+          behavior modules export this function, so callback modules for those
+          behaviors need not to supply their own.</p>
+        <p>For more information about a process, including its state, see
+          <seealso marker="#get_status-1"><c>get_status/1</c></seealso> and
+          <seealso marker="#get_status-2"><c>get_status/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="no_debug" arity="1"/>
-      <name name="no_debug" arity="2"/>
-      <fsummary>Turn off debugging</fsummary>
+      <name name="get_status" arity="1"/>
+      <name name="get_status" arity="2"/>
+      <fsummary>Get the status of the process.</fsummary>
       <desc>
-        <p>Turns off all debugging for the process. This includes
-          functions that have been installed explicitly with the
-          <c>install</c> function, for example triggers.</p>
+        <p>Gets the status of the process.</p>
+        <p>The value of <c><anno>Misc</anno></c> varies for different types of
+          processes, for example:</p>
+        <list type="bulleted">
+          <item>
+            <p>A <seealso marker="gen_server"><c>gen_server</c></seealso>
+              process returns the state of the callback module.</p>
+          </item>
+          <item>
+            <p>A <seealso marker="gen_fsm"><c>gen_fsm</c></seealso>
+              process returns information, such as its current 
+              state name and state data.</p>
+          </item>
+          <item>
+            <p>A <seealso marker="gen_statem"><c>gen_statem</c></seealso>
+              process returns information, such as its current
+              state name and state data.</p>
+          </item>
+          <item>
+            <p>A <seealso marker="gen_event"><c>gen_event</c></seealso>
+              process returns information about each of its
+              registered handlers.</p>
+          </item>
+        </list>
+        <p>Callback modules for <c>gen_server</c>,
+	  <c>gen_fsm</c>, <c>gen_statem</c>, and <c>gen_event</c>
+	  can also change the value of <c><anno>Misc</anno></c>
+          by exporting a function <c>format_status/2</c>, which contributes
+          module-specific information. For details, see
+          <seealso marker="gen_server#Module:format_status/2">
+          <c>gen_server:format_status/2</c></seealso>,
+          <seealso marker="gen_fsm#Module:format_status/2">
+          <c>gen_fsm:format_status/2</c></seealso>,
+          <seealso marker="gen_statem#Module:format_status/2">
+          <c>gen_statem:format_status/2</c></seealso>, and
+          <seealso marker="gen_event#Module:format_status/2">
+          <c>gen_event:format_status/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="suspend" arity="1"/>
-      <name name="suspend" arity="2"/>
-      <fsummary>Suspend the process</fsummary>
+      <name name="install" arity="2"/>
+      <name name="install" arity="3"/>
+      <fsummary>Install a debug function in the process.</fsummary>
       <desc>
-        <p>Suspends the process. When the process is suspended, it
-          will only respond to other system messages, but not other
-          messages.</p>
+        <p>Enables installation of alternative debug functions. An example of
+          such a function is a trigger, a function that waits for some
+          special event and performs some action when the event is
+          generated. For example, turning on low-level tracing.</p>
+        <p><c><anno>Func</anno></c> is called whenever a system event is
+          generated. This function is to return <c>done</c>, or a new
+          <c>Func</c> state. In the first case, the function is removed. It is 
+          also removed if the function fails.</p>
       </desc>
     </func>
+
     <func>
-      <name name="resume" arity="1"/>
-      <name name="resume" arity="2"/>
-      <fsummary>Resume a suspended process</fsummary>
+      <name name="log" arity="2"/>
+      <name name="log" arity="3"/>
+      <fsummary>Log system events in memory.</fsummary>
       <desc>
-        <p>Resumes a suspended process.</p>
+        <p>Turns the logging of system events on or off. If on, a
+          maximum of <c><anno>N</anno></c> events are kept in the
+          debug structure (default is 10).</p>
+        <p>If <c><anno>Flag</anno></c> is <c>get</c>, a list of all logged
+          events is returned.</p>
+        <p>If <c><anno>Flag</anno></c> is <c>print</c>, the logged events
+          are printed to <c>standard_io</c>.</p>
+        <p>The events are formatted with a function that is defined by the
+          process that generated the event (with a call to
+          <seealso marker="#handle_debug/4">
+          <c>handle_debug/4</c>)</seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="change_code" arity="4"/>
-      <name name="change_code" arity="5"/>
-      <fsummary>Send the code change system message to the process</fsummary>
+      <name name="log_to_file" arity="2"/>
+      <name name="log_to_file" arity="3"/>
+      <fsummary>Log system events to the specified file.</fsummary>
       <desc>
-        <p>Tells the process to change code. The process must be
-          suspended to handle this message. The <c><anno>Extra</anno></c> argument is
-          reserved for each process to use as its own. The function
-          <c><anno>Module</anno>:system_code_change/4</c> is called. <c><anno>OldVsn</anno></c> is
-          the old version of the <c><anno>Module</anno></c>.</p>
+        <p>Enables or disables the logging of all system events in text
+          format to the file. The events are formatted with a function that is 
+          defined by the process that generated the event (with a call to
+          <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>).
+        </p>
       </desc>
     </func>
+
     <func>
-      <name name="get_status" arity="1"/>
-      <name name="get_status" arity="2"/>
-      <fsummary>Get the status of the process</fsummary>
+      <name name="no_debug" arity="1"/>
+      <name name="no_debug" arity="2"/>
+      <fsummary>Turn off debugging.</fsummary>
       <desc>
-        <p>Gets the status of the process.</p>
-        <p>The value of <c><anno>Misc</anno></c> varies for different types of
-          processes. For example, a <c>gen_server</c> process returns
-          the callback module's state, a <c>gen_fsm</c> process
-          returns information such as its current state name and state data,
-	  a <c>gen_statem</c> process returns information about
-	  its current state and data, and a <c>gen_event</c> process
-	  returns information about each of its
-          registered handlers. Callback modules for <c>gen_server</c>,
-          <c>gen_fsm</c>, <c>gen_statem</c> and <c>gen_event</c>
-	  can also customise the value
-          of <c><anno>Misc</anno></c> by exporting a <c>format_status/2</c>
-          function that contributes module-specific information;
-          see <seealso marker="gen_server#Module:format_status/2">gen_server format_status/2</seealso>,
-          <seealso marker="gen_fsm#Module:format_status/2">gen_fsm format_status/2</seealso>,
-          <seealso marker="gen_statem#Module:format_status/2">gen_statem format_status/2</seealso>, and
-          <seealso marker="gen_event#Module:format_status/2">gen_event format_status/2</seealso>
-          for more details.</p>
+        <p>Turns off all debugging for the process. This includes
+          functions that are installed explicitly with function
+          <seealso marker="#install/2"><c>install/2,3</c></seealso>,
+          for example, triggers.</p>
       </desc>
     </func>
+
     <func>
-      <name name="get_state" arity="1"/>
-      <name name="get_state" arity="2"/>
-      <fsummary>Get the state of the process</fsummary>
+      <name name="remove" arity="2"/>
+      <name name="remove" arity="3"/>
+      <fsummary>Remove a debug function from the process.</fsummary>
       <desc>
-        <p>Gets the state of the process.</p>
-        <note>
-          <p>These functions are intended only to help with debugging. They are provided for
-            convenience, allowing developers to avoid having to create their own state extraction
-            functions and also avoid having to interactively extract state from the return values of
-            <seealso marker="#get_status-1"><c>get_status/1</c></seealso> or
-            <seealso marker="#get_status-2"><c>get_status/2</c></seealso> while debugging.</p>
-        </note>
-        <p>The value of <c><anno>State</anno></c> varies for different types of
-          processes. For a <c>gen_server</c> process, the returned <c><anno>State</anno></c>
-          is simply the callback module's state. For a <c>gen_fsm</c> process,
-          <c><anno>State</anno></c> is the tuple <c>{CurrentStateName, CurrentStateData}</c>.
-	  For a <c>gen_statem</c> process <c><anno>State</anno></c> is
-	  the tuple <c>{CurrentState,CurrentData}.</c>
-          For a <c>gen_event</c> process, <c><anno>State</anno></c> a list of tuples,
-          where each tuple corresponds to an event handler registered in the process and contains
-          <c>{Module, Id, HandlerState}</c>, where <c>Module</c> is the event handler's module name,
-          <c>Id</c> is the handler's ID (which is the value <c>false</c> if it was registered without
-          an ID), and <c>HandlerState</c> is the handler's state.</p>
-        <p>If the callback module exports a <c>system_get_state/1</c> function, it will be called in the
-          target process to get its state. Its argument is the same as the <c>Misc</c> value returned by
-          <seealso marker="#get_status-1">get_status/1,2</seealso>, and the <c>system_get_state/1</c>
-          function is expected to extract the callback module's state from it. The <c>system_get_state/1</c>
-          function must return <c>{ok, State}</c> where <c>State</c> is the callback module's state.</p>
-        <p>If the callback module does not export a <c>system_get_state/1</c> function, <c>get_state/1,2</c>
-          assumes the <c>Misc</c> value is the callback module's state and returns it directly instead.</p>
-        <p>If the callback module's <c>system_get_state/1</c> function crashes or throws an exception, the
-          caller exits with error <c>{callback_failed, {Module, system_get_state}, {Class, Reason}}</c> where
-          <c>Module</c> is the name of the callback module and <c>Class</c> and <c>Reason</c> indicate
-          details of the exception.</p>
-        <p>The <c>system_get_state/1</c> function is primarily useful for user-defined
-          behaviours and modules that implement OTP <seealso marker="#special_process">special
-          processes</seealso>. The <c>gen_server</c>, <c>gen_fsm</c>,
-	  <c>gen_statem</c> and <c>gen_event</c> OTP
-          behaviour modules export this function, so callback modules for those behaviours
-          need not supply their own.</p>
-        <p>To obtain more information about a process, including its state, see
-          <seealso marker="#get_status-1">get_status/1</seealso> and
-          <seealso marker="#get_status-2">get_status/2</seealso>.</p>
+        <p>Removes an installed debug function from the
+          process. <c><anno>Func</anno></c> must be the same as previously
+          installed.</p>
       </desc>
     </func>
+
     <func>
       <name name="replace_state" arity="2"/>
       <name name="replace_state" arity="3"/>
-      <fsummary>Replace the state of the process</fsummary>
+      <fsummary>Replace the state of the process.</fsummary>
       <desc>
         <p>Replaces the state of the process, and returns the new state.</p>
         <note>
-          <p>These functions are intended only to help with debugging, and they should not be
-            be called from normal code. They are provided for convenience, allowing developers
-            to avoid having to create their own custom state replacement functions.</p>
+          <p>These functions are intended only to help with debugging, and are
+            not to be called from normal code. They are provided for
+            convenience, allowing developers to avoid having to create their own
+            custom state replacement functions.</p>
         </note>
-        <p>The <c><anno>StateFun</anno></c> function provides a new state for the process.
-          The <c><anno>State</anno></c> argument and <c><anno>NewState</anno></c> return value
-          of <c><anno>StateFun</anno></c> vary for different types of processes. For a
-          <c>gen_server</c> process, <c><anno>State</anno></c> is simply the callback module's
-          state, and <c><anno>NewState</anno></c> is a new instance of that state. For a
-          <c>gen_fsm</c> process, <c><anno>State</anno></c> is the tuple
-          <c>{CurrentStateName, CurrentStateData}</c>, and <c><anno>NewState</anno></c>
-          is a similar tuple that may contain a new state name, new state data, or both.
-	  The same applies for a <c>gen_statem</c> process but
-	  it names the tuple fields <c>{CurrentState,CurrentData}</c>.
-          For a <c>gen_event</c> process, <c><anno>State</anno></c> is the tuple
-          <c>{Module, Id, HandlerState}</c> where <c>Module</c> is the event handler's module name,
-          <c>Id</c> is the handler's ID (which is the value <c>false</c> if it was registered without
-          an ID), and <c>HandlerState</c> is the handler's state. <c><anno>NewState</anno></c> is a
-          similar tuple where <c>Module</c> and <c>Id</c> shall have the same values as in
-          <c><anno>State</anno></c> but the value of <c>HandlerState</c> may be different. Returning
-          a <c><anno>NewState</anno></c> whose <c>Module</c> or <c>Id</c> values differ from those of
-          <c><anno>State</anno></c> will result in the event handler's state remaining unchanged. For a
-          <c>gen_event</c> process, <c><anno>StateFun</anno></c> is called once for each event handler
-          registered in the <c>gen_event</c> process.</p>
-        <p>If a <c><anno>StateFun</anno></c> function decides not to effect any change in process
-          state, then regardless of process type, it may simply return its <c><anno>State</anno></c>
-          argument.</p>
-        <p>If a <c><anno>StateFun</anno></c> function crashes or throws an exception, then
-          for <c>gen_server</c>, <c>gen_fsm</c> or <c>gen_statem</c> processes,
-	  the original state of the process is
-          unchanged. For <c>gen_event</c> processes, a crashing or failing <c><anno>StateFun</anno></c>
-          function means that only the state of the particular event handler it was working on when it
-          failed or crashed is unchanged; it can still succeed in changing the states of other event
+        <p>Function <c><anno>StateFun</anno></c> provides a new state for the
+          process. Argument <c><anno>State</anno></c> and the
+          <c><anno>NewState</anno></c> return value of
+          <c><anno>StateFun</anno></c> vary for different types of 
+          processes as follows:</p>
+        <list type="bulleted">
+          <item>
+            <p>For a <seealso marker="gen_server"><c>gen_server</c></seealso>
+              process, <c><anno>State</anno></c> is the state of the callback
+              module and <c><anno>NewState</anno></c> 
+              is a new instance of that state.</p>
+          </item>
+          <item>
+            <p>For a <seealso marker="gen_fsm"><c>gen_fsm</c></seealso> process,
+              <c><anno>State</anno></c> is the tuple <c>{CurrentStateName,
+              CurrentStateData}</c>, and <c><anno>NewState</anno></c> is a
+              similar tuple, which can contain 
+              a new state name, new state data, or both.</p>
+          </item>
+          <item>
+            <p>For a <seealso marker="gen_statem"><c>gen_statem</c></seealso>
+	      process, <c><anno>State</anno></c> is the
+	      tuple <c>{CurrentState,CurrentData}</c>,
+	      and <c><anno>NewState</anno></c> is a
+              similar tuple, which can contain
+              a new current state, new state data, or both.</p>
+          </item>
+          <item>
+            <p>For a <seealso marker="gen_event"><c>gen_event</c></seealso>
+              process, <c><anno>State</anno></c> is the
+              tuple <c>{Module, Id, HandlerState}</c> as follows:</p>
+            <taglist>
+              <tag><c>Module</c></tag>
+              <item>
+                <p>The module name of the event handler.</p>
+              </item>
+              <tag><c>Id</c></tag>
+              <item>
+                <p>The ID of the handler (which is <c>false</c> if it was
+                  registered without an ID).</p>
+              </item>
+              <tag><c>HandlerState</c></tag>
+              <item>
+                <p>The state of the handler.</p>
+              </item>
+            </taglist>
+            <p><c><anno>NewState</anno></c> is a similar tuple where
+              <c>Module</c> and <c>Id</c> are to have the same values as in
+              <c><anno>State</anno></c>, but the value of <c>HandlerState</c>
+              can be different. Returning a <c><anno>NewState</anno></c>, whose
+              <c>Module</c> or <c>Id</c> values differ from those of
+              <c><anno>State</anno></c>, leaves the state of the event handler
+              unchanged. For a <c>gen_event</c> process,
+              <c><anno>StateFun</anno></c> is called once for each event handler
+              registered in the <c>gen_event</c> process.</p>
+          </item>
+        </list>
+        <p>If a <c><anno>StateFun</anno></c> function decides not to effect any
+          change in process state, then regardless of process type, it can
+          return its <c><anno>State</anno></c> argument.</p>
+        <p>If a <c><anno>StateFun</anno></c> function crashes or throws an
+          exception, the original state of the process is unchanged for
+          <c>gen_server</c>, <c>gen_fsm</c>, and <c>gen_statem</c> processes.
+	  For <c>gen_event</c> processes, a crashing or
+	  failing <c><anno>StateFun</anno></c> function
+          means that only the state of the particular event handler it was
+          working on when it failed or crashed is unchanged; it can still
+          succeed in changing the states of other event
           handlers registered in the same <c>gen_event</c> process.</p>
-        <p>If the callback module exports a <c>system_replace_state/2</c> function, it will be called in the
-          target process to replace its state using <c>StateFun</c>. Its two arguments are <c>StateFun</c>
-          and <c>Misc</c>, where <c>Misc</c> is the same as the <c>Misc</c> value returned by
-          <seealso marker="#get_status-1">get_status/1,2</seealso>. A <c>system_replace_state/2</c> function
-          is expected to return <c>{ok, NewState, NewMisc}</c> where <c>NewState</c> is the callback module's
-          new state obtained by calling <c>StateFun</c>, and <c>NewMisc</c> is a possibly new value used to
-          replace the original <c>Misc</c> (required since <c>Misc</c> often contains the callback
-          module's state within it).</p>
-        <p>If the callback module does not export a <c>system_replace_state/2</c> function,
-          <c>replace_state/2,3</c> assumes the <c>Misc</c> value is the callback module's state, passes it
-          to <c>StateFun</c> and uses the return value as both the new state and as the new value of
-          <c>Misc</c>.</p>
-        <p>If the callback module's <c>system_replace_state/2</c> function crashes or throws an exception,
-          the caller exits with error <c>{callback_failed, {Module, system_replace_state}, {Class, Reason}}</c>
-          where <c>Module</c> is the name of the callback module and <c>Class</c> and <c>Reason</c> indicate details
-          of the exception. If the callback module does not provide a <c>system_replace_state/2</c> function and
-          <c>StateFun</c> crashes or throws an exception, the caller exits with error
+        <p>If the callback module exports a 
+          <seealso marker="#Module:system_replace_state/2">
+          <c>system_replace_state/2</c></seealso> function, it is called in the
+          target process to replace its state using <c>StateFun</c>. Its two
+          arguments are <c>StateFun</c> and <c>Misc</c>, where 
+          <c>Misc</c> is the same as the <c>Misc</c> value returned by
+          <seealso marker="#get_status-1"><c>get_status/1,2</c></seealso>.
+          A <c>system_replace_state/2</c> function is expected to return 
+          <c>{ok, NewState, NewMisc}</c>, where <c>NewState</c> is the new state
+          of the callback module, obtained by calling <c>StateFun</c>, and
+          <c>NewMisc</c> is
+          a possibly new value used to replace the original <c>Misc</c>
+          (required as <c>Misc</c> often contains the state of the callback
+          module within it).</p>
+        <p>If the callback module does not export a
+          <c>system_replace_state/2</c> function,
+          <seealso marker="#replace_state/2"><c>replace_state/2,3</c></seealso>
+          assumes that <c>Misc</c> is the state of the callback module,
+	  passes it to <c>StateFun</c> and uses the return value as
+	  both the new state and as the new value of <c>Misc</c>.</p>
+        <p>If the callback module's function <c>system_replace_state/2</c>
+          crashes or throws an exception, the caller exits with error
+          <c>{callback_failed, {Module, system_replace_state}, {Class,
+          Reason}}</c>, where <c>Module</c> is the name of the callback module
+          and <c>Class</c> and <c>Reason</c> indicate details of the exception.
+          If the callback module does not provide a
+          <c>system_replace_state/2</c> function and <c>StateFun</c> crashes or
+          throws an exception, the caller exits with error
           <c>{callback_failed, StateFun, {Class, Reason}}</c>.</p>
-        <p>The <c>system_replace_state/2</c> function is primarily useful for user-defined behaviours and
-          modules that implement OTP <seealso marker="#special_process">special processes</seealso>. The
-          <c>gen_server</c>, <c>gen_fsm</c>, <c>gen_statem</c> and
-	  <c>gen_event</c> OTP behaviour modules export this function,
-          and so callback modules for those behaviours need not supply their own.</p>
+        <p>Function <c>system_replace_state/2</c> is primarily useful for
+          user-defined behaviors and modules that implement OTP
+          <seealso marker="#special_process">special processes</seealso>. The
+          OTP behavior modules <c>gen_server</c>,
+	  <c>gen_fsm</c>, <c>gen_statem</c>, and <c>gen_event</c>
+	  export this function, so callback modules for those
+          behaviors need not to supply their own.</p>
       </desc>
     </func>
+
     <func>
-      <name name="install" arity="2"/>
-      <name name="install" arity="3"/>
-      <fsummary>Install a debug function in the process</fsummary>
+      <name name="resume" arity="1"/>
+      <name name="resume" arity="2"/>
+      <fsummary>Resume a suspended process.</fsummary>
       <desc>
-        <p>This function makes it possible to install other debug
-          functions than the ones defined above. An example of such a
-          function is a trigger, a function that waits for some
-          special event and performs some action when the event is
-          generated. This could, for example, be turning on low level tracing.
-          </p>
-        <p><c><anno>Func</anno></c> is called whenever a system event is
-          generated. This function should return <c>done</c>, or a new
-          func state. In the first case, the function is removed. It is removed 
-          if the function fails.</p>
+        <p>Resumes a suspended process.</p>
       </desc>
     </func>
+
     <func>
-      <name name="remove" arity="2"/>
-      <name name="remove" arity="3"/>
-      <fsummary>Remove a debug function from the process</fsummary>
+      <name name="statistics" arity="2"/>
+      <name name="statistics" arity="3"/>
+      <fsummary>Enable or disable the collections of statistics.</fsummary>
       <desc>
-        <p>Removes a previously installed debug function from the
-          process. <c><anno>Func</anno></c> must be the same as previously
-          installed.</p>
+        <p>Enables or disables the collection of statistics. If 
+          <c><anno>Flag</anno></c> is <c>get</c>, 
+          the statistical collection is returned.</p>
       </desc>
     </func>
+
+    <func>
+      <name name="suspend" arity="1"/>
+      <name name="suspend" arity="2"/>
+      <fsummary>Suspend the process.</fsummary>
+      <desc>
+        <p>Suspends the process. When the process is suspended, it
+          only responds to other system messages, but not other
+          messages.</p>
+      </desc>
+    </func>
+
     <func>
       <name name="terminate" arity="2"/>
       <name name="terminate" arity="3"/>
-      <fsummary>Terminate the process</fsummary>
+      <fsummary>Terminate the process.</fsummary>
       <desc>
-        <p>This function orders the process to terminate with the
-        given <c><anno>Reason</anno></c>. The termination is done
-        asynchronously, so there is no guarantee that the process is
-        actually terminated when the function returns.</p>
+        <p>Orders the process to terminate with the
+          specified <c><anno>Reason</anno></c>. The termination is done
+          asynchronously, so it is not guaranteed that the process is
+          terminated when the function returns.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="trace" arity="2"/>
+      <name name="trace" arity="3"/>
+      <fsummary>Print all system events on <c>standard_io</c>.</fsummary>
+      <desc>
+        <p>Prints all system events on <c>standard_io</c>. The events are
+          formatted with a function that is defined by the process that
+          generated the event (with a call to
+          <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>).
+        </p>
       </desc>
     </func>
   </funcs>
 
   <section>
     <title>Process Implementation Functions</title>
-    <p><marker id="special_process"/>The following functions are used when implementing a
-      special process. This is an ordinary process which does not use a
-      standard behaviour, but a process which understands the standard system messages.</p>
+    <marker id="special_process"/>
+    <p>The following functions are used when implementing a
+      special process. This is an ordinary process, which does not use a
+      standard behavior, but a process that understands the standard system
+     messages.</p>
   </section>
+
   <funcs>
     <func>
       <name name="debug_options" arity="1"/>
-      <fsummary>Convert a list of options to a debug structure</fsummary>
+      <fsummary>Convert a list of options to a debug structure.</fsummary>
       <desc>
-        <p>This function can be used by a process that initiates a debug
-          structure from a list of options. The values of the
-          <c><anno>Opt</anno></c> argument are the same as the corresponding
+        <p>Can be used by a process that initiates a debug
+          structure from a list of options. The values of argument
+          <c><anno>Opt</anno></c> are the same as for the corresponding
           functions.</p>
       </desc>
     </func>
+
     <func>
       <name name="get_debug" arity="3"/>
-      <fsummary>Get the data associated with a debug option</fsummary>
+      <fsummary>Get the data associated with a debug option.</fsummary>
       <desc>
-        <p>This function gets the data associated with a debug option. <c><anno>Default</anno></c> is returned if the
-          <c><anno>Item</anno></c> is not found.  Can be
-          used by the process to retrieve debug data for printing
-          before it terminates.</p>
+        <p>Gets the data associated with a debug option.
+          <c><anno>Default</anno></c>
+          is returned if <c><anno>Item</anno></c> is not found. Can be
+          used by the process to retrieve debug data for printing before it
+          terminates.</p>
       </desc>
     </func>
+
     <func>
       <name name="handle_debug" arity="4"/>
-      <fsummary>Generate a system event</fsummary>
+      <fsummary>Generate a system event.</fsummary>
       <desc>
         <p>This function is called by a process when it generates a
-           system event. <c><anno>FormFunc</anno></c> is a formatting
-           function which is called as <c><anno>FormFunc</anno>(Device,
-           <anno>Event</anno>, <anno>Extra</anno>)</c> in order to print
-           the events, which is necessary if tracing is activated.
-           <c><anno>Extra</anno></c> is any extra information which the
-           process needs in the format function, for example the name
-           of the process.</p>
+          system event. <c><anno>FormFunc</anno></c> is a formatting
+          function, called as <c><anno>FormFunc</anno>(Device,
+          <anno>Event</anno>, <anno>Extra</anno>)</c> to print the events, 
+          which is necessary if tracing is activated.
+          <c><anno>Extra</anno></c> is any extra information that the
+          process needs in the format function, for example, the process
+          name.</p>
       </desc>
     </func>
+
     <func>
       <name name="handle_system_msg" arity="6"/>
-      <fsummary>Take care of system messages</fsummary>
+      <fsummary>Take care of system messages.</fsummary>
       <desc>
-        <p>This function is used by a process module that wishes to take care of system
-          messages. The process receives a <c>{system, <anno>From</anno>, <anno>Msg</anno>}</c>
-          message and passes the <c><anno>Msg</anno></c> and <c><anno>From</anno></c> to this
-          function.
-          </p>
-        <p>This function <em>never</em> returns. It calls the function
-          <c><anno>Module</anno>:system_continue(<anno>Parent</anno>, NDebug, <anno>Misc</anno>)</c> where the
-          process continues the execution, or
-          <c><anno>Module</anno>:system_terminate(Reason, <anno>Parent</anno>, <anno>Debug</anno>, <anno>Misc</anno>)</c> if
-          the process should terminate. The <c><anno>Module</anno></c> must export
-          <c>system_continue/3</c>, <c>system_terminate/4</c>,
-          <c>system_code_change/4</c>, <c>system_get_state/1</c> and
-          <c>system_replace_state/2</c> (see below).
-          </p>
-        <p>The <c><anno>Misc</anno></c> argument can be used to save internal data
-          in a process, for example its state. It is sent to
+        <p>This function is used by a process module to take care of system
+          messages. The process receives a 
+          <c>{system, <anno>From</anno>, <anno>Msg</anno>}</c> message and
+          passes <c><anno>Msg</anno></c> and <c><anno>From</anno></c> to this
+          function.</p>
+        <p>This function <em>never</em> returns. It calls either of the
+          following functions:</p>
+        <list type="bulleted">
+          <item>
+            <p><c><anno>Module</anno>:system_continue(<anno>Parent</anno>,
+              NDebug, <anno>Misc</anno>)</c>,
+	      where the process continues the execution.</p>
+          </item>
+          <item>
+            <p><c><anno>Module</anno>:system_terminate(Reason,
+              <anno>Parent</anno>, <anno>Debug</anno>, <anno>Misc</anno>)</c>,
+              if the process is to terminate.</p>
+          </item>
+        </list>
+        <p><c><anno>Module</anno></c> must export the following:</p>
+        <list type="bulleted">
+          <item><c>system_continue/3</c></item>
+          <item><c>system_terminate/4</c></item>
+          <item><c>system_code_change/4</c></item>
+          <item><c>system_get_state/1</c></item>
+          <item><c>system_replace_state/2</c></item>
+        </list>
+        <p>Argument <c><anno>Misc</anno></c> can be used to save internal data
+          in a process, for example, its state. It is sent to
           <c><anno>Module</anno>:system_continue/3</c> or
-          <c><anno>Module</anno>:system_terminate/4</c></p>
+          <c><anno>Module</anno>:system_terminate/4</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="print_log" arity="1"/>
-      <fsummary>Print the logged events in the debug structure</fsummary>
+      <fsummary>Print the logged events in the debug structure.</fsummary>
       <desc>
-        <p>Prints the logged system events in the debug structure
+        <p>Prints the logged system events in the debug structure,
           using <c>FormFunc</c> as defined when the event was
-          generated by a call to <c>handle_debug/4</c>.</p>
+          generated by a call to
+          <seealso marker="#handle_debug/4"><c>handle_debug/4</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name>Mod:system_continue(Parent, Debug, Misc) -> none()</name>
-      <fsummary>Called when the process should continue its execution</fsummary>
+      <name>Module:system_code_change(Misc, Module, OldVsn, Extra) ->
+        {ok, NMisc}</name>
+      <fsummary>Called when the process is to perform a code change.</fsummary>
       <type>
-        <v>Parent = pid()</v>
-        <v>Debug = [<seealso marker="#type-dbg_opt">dbg_opt()</seealso>]</v>
         <v>Misc = term()</v>
+        <v>OldVsn = undefined | term()</v>
+        <v>Module = atom()</v>
+        <v>Extra = term()</v>
+        <v>NMisc = term()</v>
       </type>
       <desc>
-        <p>This function is called from <c>sys:handle_system_msg/6</c> when the process
-          should continue its execution (for example after it has been
-          suspended). This function never returns.</p>
+        <p>Called from <seealso marker="#handle_system_msg/6">
+          <c>handle_system_msg/6</c></seealso> when the process is to perform a
+          code change. The code change is used when the
+          internal data structure has changed. This function
+          converts argument <c>Misc</c> to the new data
+          structure. <c>OldVsn</c> is attribute <em>vsn</em> of the
+          old version of the <c>Module</c>. If no such attribute is
+          defined, the atom <c>undefined</c> is sent.</p>
       </desc>
     </func>
+
     <func>
-      <name>Mod:system_terminate(Reason, Parent, Debug, Misc) -> none()</name>
-      <fsummary>Called when the process should terminate</fsummary>
+      <name>Module:system_continue(Parent, Debug, Misc) -> none()</name>
+      <fsummary>Called when the process is to continue its execution.</fsummary>
       <type>
-        <v>Reason = term()</v>
         <v>Parent = pid()</v>
         <v>Debug = [<seealso marker="#type-dbg_opt">dbg_opt()</seealso>]</v>
         <v>Misc = term()</v>
       </type>
       <desc>
-        <p>This function is called from <c>sys:handle_system_msg/6</c> when the process
-          should terminate. For example, this function is called when
-          the process is suspended and its parent orders shut-down.
-          It  gives the process a chance to do a clean-up. This function never
-          returns.</p>
+        <p>Called from <seealso marker="#handle_system_msg/6">
+          <c>handle_system_msg/6</c></seealso> when the process is to continue
+          its execution (for example, after it has been
+          suspended). This function never returns.</p>
       </desc>
     </func>
+
     <func>
-      <name>Mod:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}</name>
-      <fsummary>Called when the process should perform a code change</fsummary>
+      <name>Module:system_get_state(Misc) -> {ok, State}</name>
+      <fsummary>Called when the process is to return its current state.
+      </fsummary>
       <type>
         <v>Misc = term()</v>
-        <v>OldVsn = undefined | term()</v>
-        <v>Module = atom()</v>
-        <v>Extra = term()</v>
-        <v>NMisc = term()</v>
+        <v>State = term()</v>
       </type>
       <desc>
-        <p>Called from <c>sys:handle_system_msg/6</c> when the process
-          should perform a code change. The code change is used when the
-          internal data structure has changed. This function
-          converts the <c>Misc</c> argument to the new data
-          structure. <c>OldVsn</c> is the <em>vsn</em> attribute of the
-          old version of the <c>Module</c>. If no such attribute was
-          defined, the atom <c>undefined</c> is sent.</p>
+        <p>Called from <seealso marker="#handle_system_msg/6">
+          <c>handle_system_msg/6</c></seealso>
+          when the process is to return a term that reflects its current state. 
+          <c>State</c> is the value returned by 
+          <seealso marker="#get_state/2"><c>get_state/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name>Mod:system_get_state(Misc) -> {ok, State}</name>
-      <fsummary>Called when the process should return its current state</fsummary>
+      <name>Module:system_replace_state(StateFun, Misc) ->
+        {ok, NState, NMisc}</name>
+      <fsummary>Called when the process is to replace its current state.
+      </fsummary>
       <type>
+        <v>StateFun = fun((State :: term()) -> NState)</v>
         <v>Misc = term()</v>
-        <v>State = term()</v>
-    </type>
+        <v>NState = term()</v>
+        <v>NMisc = term()</v>
+      </type>
       <desc>
-        <p>This function is called from <c>sys:handle_system_msg/6</c> when the process
-          should return a term that reflects its current state. <c>State</c> is the
-          value returned by <c>sys:get_state/2</c>.</p>
+        <p>Called from <seealso marker="#handle_system_msg/6">
+          <c>handle_system_msg/6</c></seealso> when the process is to replace
+          its current state. <c>NState</c> is the value returned by
+          <seealso marker="#replace_state/3"><c>replace_state/3</c></seealso>.
+          </p>
       </desc>
     </func>
+
     <func>
-      <name>Mod:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}</name>
-      <fsummary>Called when the process should replace its current state</fsummary>
+      <name>Module:system_terminate(Reason, Parent, Debug, Misc) -> none()</name>
+      <fsummary>Called when the process is to terminate.</fsummary>
       <type>
-        <v>StateFun = fun((State :: term()) -> NState)</v>
+        <v>Reason = term()</v>
+        <v>Parent = pid()</v>
+        <v>Debug = [<seealso marker="#type-dbg_opt">dbg_opt()</seealso>]</v>
         <v>Misc = term()</v>
-        <v>NState = term()</v>
-        <v>NMisc = term()</v>
-    </type>
+      </type>
       <desc>
-        <p>This function is called from <c>sys:handle_system_msg/6</c> when the process
-         should replace its current state. <c>NState</c> is the value returned by
-         <c>sys:replace_state/3</c>.</p>
+        <p>Called from <seealso marker="#handle_system_msg/6">
+          <c>handle_system_msg/6</c></seealso> when the process is to terminate.
+          For example, this function is called when
+          the process is suspended and its parent orders shutdown.
+          It gives the process a chance to do a cleanup. This function never
+          returns.</p>
       </desc>
     </func>
   </funcs>