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, 677 insertions, 585 deletions

diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml
index 835e252704..de06987d38 100644
--- a/lib/stdlib/doc/src/gen_fsm.xml
+++ b/lib/stdlib/doc/src/gen_fsm.xml
@@ -29,29 +29,30 @@
     <rev></rev>
   </header>
   <module>gen_fsm</module>
-  <modulesummary>Generic Finite State Machine Behaviour</modulesummary>
+  <modulesummary>Generic finite state machine behavior.</modulesummary>
   <description>
     <note>
       <p>
 	There is a new behaviour
 	<seealso marker="gen_statem"><c>gen_statem</c></seealso>
 	that is intended to replace <c>gen_fsm</c> for new code.
-	It has the same features and add some really useful.
-	This module will not be removed for the foreseeable future
+	<c>gen_fsm</c> will not be removed for the foreseeable future
 	to keep old state machine implementations running.
       </p>
     </note>
-    <p>A behaviour module for implementing a finite state machine.
-      A generic finite state machine process (gen_fsm) implemented
-      using this module will have a standard set of interface functions
-      and include functionality for tracing and error reporting. It will
-      also fit into an OTP supervision tree. Refer to
-      <seealso marker="doc/design_principles:fsm">OTP Design Principles</seealso> for more information.
+    <p>This behavior module provides a finite state machine.
+      A generic finite state machine process (<c>gen_fsm</c>) implemented
+      using this module has a standard set of interface functions
+      and includes functionality for tracing and error reporting. It
+      also fits into an OTP supervision tree. For more information, see
+      <seealso marker="doc/design_principles:fsm">OTP Design Principles</seealso>.
     </p>
-    <p>A gen_fsm assumes all specific parts to be located in a callback
-      module exporting a pre-defined set of functions. The relationship
-      between the behaviour functions and the callback functions can be
-      illustrated as follows:</p>
+
+    <p>A <c>gen_fsm</c> process assumes all specific parts to be located in a
+      callback module exporting a predefined set of functions. The relationship
+      between the behavior functions and the callback functions is as
+      follows:</p>
+
     <pre>
 gen_fsm module                    Callback module
 --------------                    ---------------
@@ -73,34 +74,261 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
 -                                 -----> Module:terminate/3
 
 -                                 -----> Module:code_change/4</pre>
-    <p>If a callback function fails or returns a bad value, the gen_fsm
-      will terminate.</p>
-    <p>A gen_fsm handles system messages as documented in
-       <seealso marker="sys">sys(3)</seealso>. The <c>sys</c> module
-       can be used for debugging a gen_fsm.</p>
-    <p>Note that a gen_fsm does not trap exit signals automatically,
-      this must be explicitly initiated in the callback module.</p>
+
+    <p>If a callback function fails or returns a bad value, the <c>gen_fsm</c>
+      process terminates.</p>
+
+    <p>A <c>gen_fsm</c> process handles system messages as described in
+      <seealso marker="sys"><c>sys(3)</c></seealso>. The <c>sys</c> module
+      can be used for debugging a <c>gen_fsm</c> process.</p>
+
+    <p>Notice that a <c>gen_fsm</c> process does not trap exit signals
+      automatically, this must be explicitly initiated in the callback
+      module.</p>
+
     <p>Unless otherwise stated, all functions in this module fail if
-      the specified gen_fsm does not exist or if bad arguments are
-      given.</p>
-    <p>The gen_fsm process can go into hibernation 
-    (see <seealso marker="erts:erlang#erlang:hibernate/3">erlang(3)</seealso>) if a callback
-    function specifies <c>'hibernate'</c> instead of a timeout value. This
-    might be useful if the server is expected to be idle for a long
-    time. However this feature should be used with care as hibernation
-    implies at least two garbage collections (when hibernating and
-    shortly after waking up) and is not something you'd want to do
-    between each call to a busy state machine.</p>
+      the specified <c>gen_fsm</c> process does not exist or if bad arguments
+      are specified.</p>
 
+    <p>The <c>gen_fsm</c> process can go into hibernation
+      (see <seealso marker="erts:erlang#hibernate/3">
+      <c>erlang:hibernate/3</c></seealso>) if a callback function
+      specifies <c>'hibernate'</c> instead of a time-out value. This
+      can be useful if the server is expected to be idle for a long
+      time. However, use this feature with care, as hibernation
+      implies at least two garbage collections (when hibernating and
+      shortly after waking up) and is not something you want to do
+      between each call to a busy state machine.</p>
   </description>
+
   <funcs>
     <func>
+      <name>cancel_timer(Ref) -> RemainingTime | false</name>
+      <fsummary>Cancel an internal timer in a generic FSM.</fsummary>
+      <type>
+        <v>Ref = reference()</v>
+        <v>RemainingTime = integer()</v>
+      </type>
+      <desc>
+        <p>Cancels an internal timer referred by <c>Ref</c> in the
+          <c>gen_fsm</c> process that calls this function.</p>
+        <p><c>Ref</c> is a reference returned from
+          <seealso marker="#send_event_after/2">
+          <c>send_event_after/2</c></seealso> or
+          <seealso marker="#start_timer/2"><c>start_timer/2</c></seealso>.</p>
+        <p>If the timer has already timed out, but the event not yet
+          been delivered, it is cancelled as if it had <em>not</em>
+          timed out, so there is no false timer event after
+          returning from this function.</p>
+        <p>Returns the remaining time in milliseconds until the timer would
+          have expired if <c>Ref</c> referred to an active timer, otherwise
+          <c>false</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>enter_loop(Module, Options, StateName, StateData)</name>
+      <name>enter_loop(Module, Options, StateName, StateData, FsmName)</name>
+      <name>enter_loop(Module, Options, StateName, StateData, Timeout)</name>
+      <name>enter_loop(Module, Options, StateName, StateData, FsmName, Timeout)</name>
+      <fsummary>Enter the <c>gen_fsm</c> receive loop.</fsummary>
+      <type>
+        <v>Module = atom()</v>
+        <v>Options = [Option]</v>
+        <v>&nbsp;Option = {debug,Dbgs}</v>
+        <v>&nbsp;&nbsp;Dbgs = [Dbg]</v>
+        <v>&nbsp;&nbsp;&nbsp;Dbg = trace | log | statistics</v>
+        <v>&nbsp;&nbsp;&nbsp;&nbsp;| {log_to_file,FileName} | {install,{Func,FuncState}}</v>
+        <v>StateName = atom()</v>
+        <v>StateData = term()</v>
+        <v>FsmName = {local,Name} | {global,GlobalName}</v>
+        <v>&nbsp;&nbsp;| {via,Module,ViaName}</v>
+        <v>&nbsp;Name = atom()</v>
+        <v>&nbsp;GlobalName = ViaName = term()</v>
+        <v>Timeout = int() | infinity</v>
+      </type>
+      <desc>
+        <p>Makes an existing process into a <c>gen_fsm</c> process.
+          Does not return,
+          instead the calling process enters the <c>gen_fsm</c> receive
+          loop and becomes a <c>gen_fsm</c> process. The process <em>must</em>
+          have been started using one of the start functions in
+          <seealso marker="proc_lib"><c>proc_lib(3)</c></seealso>. The user is
+          responsible for any initialization of the process, including
+          registering a name for it.</p>
+        <p>This function is useful when a more complex initialization
+          procedure is needed than the <c>gen_fsm</c> behavior provides.</p>
+        <p><c>Module</c>, <c>Options</c>, and <c>FsmName</c> have
+          the same meanings as when calling
+          <seealso marker="#start_link/3"><c>start[_link]/3,4</c></seealso>.
+          However, if <c>FsmName</c> is specified, the process must have
+          been registered accordingly <em>before</em> this function is
+          called.</p>
+        <p><c>StateName</c>, <c>StateData</c>, and <c>Timeout</c> have
+          the same meanings as in the return value of
+          <seealso marker="#Moduleinit"><c>Module:init/1</c></seealso>.
+          The callback module <c>Module</c> does not need to
+          export an <c>init/1</c> function.</p>
+        <p>The function fails if the calling process was not started by a
+          <c>proc_lib</c> start function, or if it is not registered
+          according to <c>FsmName</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>reply(Caller, Reply) -> Result</name>
+      <fsummary>Send a reply to a caller.</fsummary>
+      <type>
+        <v>Caller - see below</v>
+        <v>Reply = term()</v>
+        <v>Result = term()</v>
+      </type>
+      <desc>
+        <p>This function can be used by a <c>gen_fsm</c> process to
+          explicitly send a reply to a client process that called
+          <seealso marker="#sync_send_event/2">
+          <c>sync_send_event/2,3</c></seealso> or
+          <seealso marker="#sync_send_all_state_event/2">
+          <c>sync_send_all_state_event/2,3</c></seealso>
+          when the reply cannot be defined in the return value of
+          <seealso marker="#Module:StateName/3">
+          <c>Module:StateName/3</c></seealso> or
+          <seealso marker="#Module:handle_sync_event/4">
+          <c>Module:handle_sync_event/4</c></seealso>.</p>
+        <p><c>Caller</c> must be the <c>From</c> argument provided to
+          the callback function. <c>Reply</c> is any term
+          given back to the client as the return value of
+          <c>sync_send_event/2,3</c> or
+          <c>sync_send_all_state_event/2,3</c>.</p>
+        <p>Return value <c>Result</c> is not further defined, and
+          is always to be ignored.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>send_all_state_event(FsmRef, Event) -> ok</name>
+      <fsummary>Send an event asynchronously to a generic FSM.</fsummary>
+      <type>
+        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}</v>
+        <v>&nbsp;&nbsp;| {via,Module,ViaName} | pid()</v>
+        <v>&nbsp;Name = Node = atom()</v>
+        <v>&nbsp;GlobalName = ViaName = term()</v>
+        <v>Event = term()</v>
+      </type>
+      <desc>
+        <p>Sends an event asynchronously to the <c>FsmRef</c> of the
+          <c>gen_fsm</c> process and returns <c>ok</c> immediately.
+          The <c>gen_fsm</c> process calls
+          <seealso marker="#Module:handle_event/3">
+          <c>Module:handle_event/3</c></seealso> to handle the event.</p>
+        <p>For a description of the arguments, see
+          <seealso marker="#send_event/2"><c>send_event/2</c></seealso>.</p>
+        <p>The difference between <c>send_event/2</c> and
+          <c>send_all_state_event/2</c> is which callback function is
+          used to handle the event. This function is useful when
+          sending events that are handled the same way in every state,
+          as only one <c>handle_event</c> clause is needed to handle
+          the event instead of one clause in each state name function.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>send_event(FsmRef, Event) -> ok</name>
+      <fsummary>Send an event asynchronously to a generic FSM.</fsummary>
+      <type>
+        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}</v>
+        <v>&nbsp;&nbsp;| {via,Module,ViaName} | pid()</v>
+        <v>&nbsp;Name = Node = atom()</v>
+        <v>&nbsp;GlobalName = ViaName = term()</v>
+        <v>Event = term()</v>
+      </type>
+      <desc>
+        <p>Sends an event asynchronously to the <c>FsmRef</c> of the
+          <c>gen_fsm</c> process 
+          and returns <c>ok</c> immediately. The <c>gen_fsm</c> process calls
+          <seealso marker="#Module:StateName/2">
+          <c>Module:StateName/2</c></seealso> to handle the event, where
+          <c>StateName</c> is the name of the current state of
+          the <c>gen_fsm</c> process.</p>
+        <p><c>FsmRef</c> can be any of the following:</p>
+        <list type="bulleted">
+          <item>The pid</item>
+          <item><c>Name</c>, if the <c>gen_fsm</c> process is locally
+            registered</item>
+          <item><c>{Name,Node}</c>, if the <c>gen_fsm</c> process is locally
+            registered at another node</item>
+          <item><c>{global,GlobalName}</c>, if the <c>gen_fsm</c> process is
+            globally registered</item>
+          <item><c>{via,Module,ViaName}</c>, if the <c>gen_fsm</c> process is
+            registered through an alternative process registry</item>
+        </list>
+        <p><c>Event</c> is any term that is passed as one of
+          the arguments to <c>Module:StateName/2</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>send_event_after(Time, Event) -> Ref</name>
+      <fsummary>Send a delayed event internally in a generic FSM.</fsummary>
+      <type>
+        <v>Time = integer()</v>
+        <v>Event = term()</v>
+        <v>Ref = reference()</v>
+      </type>
+      <desc>
+        <p>Sends a delayed event internally in the <c>gen_fsm</c> process
+          that calls this function after <c>Time</c> milliseconds.
+          Returns immediately a
+          reference that can be used to cancel the delayed send using
+          <seealso marker="#cancel_timer/1"><c>cancel_timer/1</c></seealso>.</p>
+        <p>The <c>gen_fsm</c> process calls
+          <seealso marker="#Module:StateName/2">
+          <c>Module:StateName/2</c></seealso> to handle
+          the event, where <c>StateName</c> is the name of the current
+          state of the <c>gen_fsm</c> process at the time the delayed event is
+          delivered.</p>
+        <p><c>Event</c> is any term that is passed as one of
+          the arguments to <c>Module:StateName/2</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>start(Module, Args, Options) -> Result</name>
+      <name>start(FsmName, Module, Args, Options) -> Result</name>
+      <fsummary>Create a standalone <c>gen_fsm</c> process.</fsummary>
+      <type>
+        <v>FsmName = {local,Name} | {global,GlobalName}</v>
+        <v>&nbsp;&nbsp;| {via,Module,ViaName}</v>
+        <v>&nbsp;Name = atom()</v>
+        <v>&nbsp;GlobalName = ViaName = term()</v>
+        <v>Module = atom()</v>
+        <v>Args = term()</v>
+        <v>Options = [Option]</v>
+        <v>&nbsp;Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}</v>
+        <v>&nbsp;&nbsp;Dbgs = [Dbg]</v>
+        <v>&nbsp;&nbsp;&nbsp;Dbg = trace | log | statistics</v>
+        <v>&nbsp;&nbsp;&nbsp;&nbsp;| {log_to_file,FileName} | {install,{Func,FuncState}}</v>
+        <v>&nbsp;&nbsp;SOpts = [term()]</v>
+        <v>Result = {ok,Pid} | ignore | {error,Error}</v>
+        <v>&nbsp;Pid = pid()</v>
+        <v>&nbsp;Error = {already_started,Pid} | term()</v>
+      </type>
+      <desc>
+        <p>Creates a standalone <c>gen_fsm</c> process, that is, a process that
+          is not part of a supervision tree and thus has no supervisor.</p>
+        <p>For a description of arguments and return values, see
+          <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
       <name>start_link(Module, Args, Options) -> Result</name>
       <name>start_link(FsmName, Module, Args, Options) -> Result</name>
-      <fsummary>Create a gen_fsm process in a supervision tree.</fsummary>
+      <fsummary>Create a <c>gen_fsm</c> process in a supervision tree.
+      </fsummary>
       <type>
-        <v>FsmName = {local,Name} | {global,GlobalName}
-	| {via,Module,ViaName}</v>
+        <v>FsmName = {local,Name} | {global,GlobalName}</v>
+        <v>&nbsp;&nbsp;| {via,Module,ViaName}</v>
         <v>&nbsp;Name = atom()</v>
         <v>&nbsp;GlobalName = ViaName = term()</v>
         <v>Module = atom()</v>
@@ -117,54 +345,64 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
         <v>&nbsp;Error = {already_started,Pid} | term()</v>
       </type>
       <desc>
-        <p>Creates a gen_fsm process as part of a supervision tree.
-          The function should be called, directly or indirectly, by
-          the supervisor. It will, among other things, ensure that
-          the gen_fsm is linked to the supervisor.</p>
-        <p>The gen_fsm process calls <c>Module:init/1</c> to
-          initialize. To ensure a synchronized start-up procedure,
+        <p>Creates a <c>gen_fsm</c> process as part of a supervision tree.
+          The function is to be called, directly or indirectly, by
+          the supervisor. For example, it ensures that
+          the <c>gen_fsm</c> process is linked to the supervisor.</p>
+        <p>The <c>gen_fsm</c> process calls
+          <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso> to
+          initialize. To ensure a synchronized startup procedure,
           <c>start_link/3,4</c> does not return until
           <c>Module:init/1</c> has returned.</p>
-        <p>If <c>FsmName={local,Name}</c>, the gen_fsm is registered
-          locally as <c>Name</c> using <c>register/2</c>.
-          If <c>FsmName={global,GlobalName}</c>, the gen_fsm is
-          registered globally as <c>GlobalName</c> using
-          <c>global:register_name/2</c>.
-	  If <c>FsmName={via,Module,ViaName}</c>, the gen_fsm will
-	  register with the registry represented by <c>Module</c>.
-	  The <c>Module</c> callback should export the functions
-	  <c>register_name/2</c>, <c>unregister_name/1</c>,
-	  <c>whereis_name/1</c> and <c>send/2</c>, which should behave like the
-	  corresponding functions in <c>global</c>. Thus,
-	<c>{via,global,GlobalName}</c> is a valid reference.</p>
-	<p>If no name is provided,
-	the gen_fsm is not registered.</p>
+        <list type="bulleted">
+          <item>
+            <p>If <c>FsmName={local,Name}</c>, the <c>gen_fsm</c> process is
+              registered locally as <c>Name</c> using <c>register/2</c>.</p>
+          </item>
+          <item>
+            <p>If <c>FsmName={global,GlobalName}</c>, the <c>gen_fsm</c> process
+              is registered globally as <c>GlobalName</c> using
+              <seealso marker="kernel:global#register_name/2">
+              <c>global:register_name/2</c></seealso>.</p>
+          </item>
+          <item>
+            <p>If <c>FsmName={via,Module,ViaName}</c>, the <c>gen_fsm</c>
+              process registers with the registry represented by <c>Module</c>.
+              The <c>Module</c> callback is to export the functions
+              <c>register_name/2</c>, <c>unregister_name/1</c>,
+              <c>whereis_name/1</c>, and <c>send/2</c>, which are to behave
+              like the corresponding functions in
+              <seealso marker="kernel:global"><c>global</c></seealso>.
+              Thus, <c>{via,global,GlobalName}</c> is a valid reference.</p>
+          </item>
+        </list>
+        <p>If no name is provided, the <c>gen_fsm</c> process  is not
+          registered.</p>
         <p><c>Module</c> is the name of the callback module.</p>
-        <p><c>Args</c> is an arbitrary term which is passed as
+        <p><c>Args</c> is any term that is passed as
           the argument to <c>Module:init/1</c>.</p>
-        <p>If the option <c>{timeout,Time}</c> is present, the gen_fsm
-          is allowed to spend <c>Time</c> milliseconds initializing
-          or it will be terminated and the start function will return
+        <p>If option <c>{timeout,Time}</c> is present, the <c>gen_fsm</c>
+          process is allowed to spend <c>Time</c> milliseconds initializing
+          or it terminates and the start function returns
           <c>{error,timeout}</c>.</p>
-        <p>If the option <c>{debug,Dbgs}</c> is present,
-          the corresponding <c>sys</c> function will be called for each
-          item in <c>Dbgs</c>. See
-          <seealso marker="sys">sys(3)</seealso>.</p>
-        <p>If the option <c>{spawn_opt,SOpts}</c> is present,
-          <c>SOpts</c> will be passed as option list to
-          the <c>spawn_opt</c> BIF which is used to spawn the gen_fsm
-          process. See
-          <seealso marker="erts:erlang#spawn_opt/2">erlang(3)</seealso>.</p>
+        <p>If option <c>{debug,Dbgs}</c> is present, the corresponding
+          <c>sys</c> function is called for each item in <c>Dbgs</c>; see
+          <seealso marker="sys"><c>sys(3)</c></seealso>.</p>
+        <p>If option <c>{spawn_opt,SOpts}</c> is present, <c>SOpts</c> is
+          passed as option list to the <c>spawn_opt</c> BIF that is used to
+          spawn the <c>gen_fsm</c> process; see
+          <seealso marker="erts:erlang#spawn_opt/2">
+          <c>spawn_opt/2</c></seealso>.</p>
         <note>
-          <p>Using the spawn option <c>monitor</c> is currently not
-            allowed, but will cause the function to fail with reason
+          <p>Using spawn option <c>monitor</c> is not
+            allowed, it causes the function to fail with reason
             <c>badarg</c>.</p>
         </note>
-        <p>If the gen_fsm is successfully created and initialized
-          the function returns <c>{ok,Pid}</c>, where <c>Pid</c> is
-          the pid of the gen_fsm. If there already exists a process with
-          the specified <c>FsmName</c>, the function returns
-          <c>{error,{already_started,Pid}}</c> where <c>Pid</c> is
+        <p>If the <c>gen_fsm</c> process is successfully created and
+          initialized, the function returns <c>{ok,Pid}</c>, where <c>Pid</c>
+          is the pid of the <c>gen_fsm</c> process. If a process with the
+          specified <c>FsmName</c> exists already, the function returns
+          <c>{error,{already_started,Pid}}</c>, where <c>Pid</c> is
           the pid of that process.</p>
         <p>If <c>Module:init/1</c> fails with <c>Reason</c>,
           the function returns <c>{error,Reason}</c>. If
@@ -173,129 +411,106 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
           returns <c>{error,Reason}</c> or <c>ignore</c>, respectively.</p>
       </desc>
     </func>
+
     <func>
-      <name>start(Module, Args, Options) -> Result</name>
-      <name>start(FsmName, Module, Args, Options) -> Result</name>
-      <fsummary>Create a stand-alone gen_fsm process.</fsummary>
+      <name>start_timer(Time, Msg) -> Ref</name>
+      <fsummary>Send a time-out event internally in a generic FSM.</fsummary>
       <type>
-        <v>FsmName = {local,Name} | {global,GlobalName}
-	| {via,Module,ViaName}</v>
-        <v>&nbsp;Name = atom()</v>
-        <v>&nbsp;GlobalName = ViaName = term()</v>
-        <v>Module = atom()</v>
-        <v>Args = term()</v>
-        <v>Options = [Option]</v>
-        <v>&nbsp;Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}</v>
-        <v>&nbsp;&nbsp;Dbgs = [Dbg]</v>
-        <v>&nbsp;&nbsp;&nbsp;Dbg = trace | log | statistics</v>
-        <v>&nbsp;&nbsp;&nbsp;&nbsp;| {log_to_file,FileName} | {install,{Func,FuncState}}</v>
-        <v>&nbsp;&nbsp;SOpts = [term()]</v>
-        <v>Result = {ok,Pid} | ignore | {error,Error}</v>
-        <v>&nbsp;Pid = pid()</v>
-        <v>&nbsp;Error = {already_started,Pid} | term()</v>
+        <v>Time = integer()</v>
+        <v>Msg = term()</v>
+        <v>Ref = reference()</v>
       </type>
       <desc>
-        <p>Creates a stand-alone gen_fsm process, i.e. a gen_fsm which
-          is not part of a supervision tree and thus has no supervisor.</p>
-        <p>See <seealso marker="#start_link/3">start_link/3,4</seealso>
-          for a description of arguments and return values.</p>
+        <p>Sends a time-out event internally in the <c>gen_fsm</c>
+          process that calls this function after <c>Time</c> milliseconds.
+          Returns immediately a
+          reference that can be used to cancel the timer using
+          <seealso marker="#cancel_timer/1"><c>cancel_timer/1</c></seealso>.</p>
+        <p>The <c>gen_fsm</c> process calls
+          <seealso marker="#Module:StateName/2">
+          <c>Module:StateName/2</c></seealso> to handle
+          the event, where <c>StateName</c> is the name of the current
+          state of the <c>gen_fsm</c> process  at the time the time-out
+          message is delivered.</p>
+        <p><c>Msg</c> is any term that is passed in the
+          time-out message, <c>{timeout, Ref, Msg}</c>, as one of
+          the arguments to <c>Module:StateName/2</c>.</p>
       </desc>
     </func>
+
     <func>
       <name>stop(FsmRef) -> ok</name>
       <name>stop(FsmRef, Reason, Timeout) -> ok</name>
       <fsummary>Synchronously stop a generic FSM.</fsummary>
       <type>
-        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}
-	| {via,Module,ViaName} | pid()</v>
+        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}</v>
+        <v>&nbsp;&nbsp;| {via,Module,ViaName} | pid()</v>
         <v>&nbsp;Node = atom()</v>
         <v>&nbsp;GlobalName = ViaName = term()</v>
         <v>Reason = term()</v>
         <v>Timeout = int()>0 | infinity</v>
       </type>
       <desc>
-	<p>Orders a generic FSM to exit with the given <c>Reason</c>
-	  and waits for it to terminate. The gen_fsm will call
-          <seealso marker="#Module:terminate/3">Module:terminate/3</seealso>
-	  before exiting.</p>
-	<p>The function returns <c>ok</c> if the generic FSM terminates
-	  with the expected reason. Any other reason than <c>normal</c>,
-          <c>shutdown</c>, or <c>{shutdown,Term}</c> will cause an
+        <p>Orders a generic finite state machine to exit with the specified
+          <c>Reason</c> and waits for it to terminate. The <c>gen_fsm</c>
+          process calls <seealso marker="#Module:terminate/3">
+          <c>Module:terminate/3</c></seealso> before exiting.</p>
+        <p>The function returns <c>ok</c> if the generic finite state machine
+          terminates with the expected reason. Any other reason than
+          <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an
           error report to be issued using
-          <seealso marker="kernel:error_logger#format/2">error_logger:format/2</seealso>.
-	  The default <c>Reason</c> is <c>normal</c>.</p>
-	<p><c>Timeout</c> is an integer greater than zero which
+          <seealso marker="kernel:error_logger#format/2">
+          <c>error_logger:format/2</c></seealso>.
+          The default <c>Reason</c> is <c>normal</c>.</p>
+        <p><c>Timeout</c> is an integer greater than zero that
           specifies how many milliseconds to wait for the generic FSM
           to terminate, or the atom <c>infinity</c> to wait
           indefinitely. The default value is <c>infinity</c>. If the
-          generic FSM has not terminated within the specified time, a
-	  <c>timeout</c> exception is raised.</p>
-	<p>If the process does not exist, a <c>noproc</c> exception
-	  is raised.</p>
-      </desc>
-    </func>
-    <func>
-      <name>send_event(FsmRef, Event) -> ok</name>
-      <fsummary>Send an event asynchronously to a generic FSM.</fsummary>
-      <type>
-        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}
-	| {via,Module,ViaName} | pid()</v>
-        <v>&nbsp;Name = Node = atom()</v>
-        <v>&nbsp;GlobalName = ViaName = term()</v>
-        <v>Event = term()</v>
-      </type>
-      <desc>
-        <p>Sends an event asynchronously to the gen_fsm <c>FsmRef</c>
-          and returns <c>ok</c> immediately. The gen_fsm will call
-          <c>Module:StateName/2</c> to handle the event, where
-          <c>StateName</c> is the name of the current state of
-          the gen_fsm.</p>
-        <p><c>FsmRef</c> can be:</p>
-        <list type="bulleted">
-          <item>the pid,</item>
-          <item><c>Name</c>, if the gen_fsm is locally registered,</item>
-          <item><c>{Name,Node}</c>, if the gen_fsm is locally
-	  registered at another node, or</item>
-	  <item><c>{global,GlobalName}</c>, if the gen_fsm is globally
-	  registered.</item>
-	  <item><c>{via,Module,ViaName}</c>, if the gen_fsm is registered
-	  through an alternative process registry.</item>
-        </list>
-        <p><c>Event</c> is an arbitrary term which is passed as one of
-          the arguments to <c>Module:StateName/2</c>.</p>
+          generic finite state machine has not terminated within the specified
+          time, a <c>timeout</c> exception is raised.</p>
+        <p>If the process does not exist, a <c>noproc</c> exception
+          is raised.</p>
       </desc>
     </func>
+
     <func>
-      <name>send_all_state_event(FsmRef, Event) -> ok</name>
-      <fsummary>Send an event asynchronously to a generic FSM.</fsummary>
+      <name>sync_send_all_state_event(FsmRef, Event) -> Reply</name>
+      <name>sync_send_all_state_event(FsmRef, Event, Timeout) -> Reply</name>
+      <fsummary>Send an event synchronously to a generic FSM.</fsummary>
       <type>
-        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}
-	| {via,Module,ViaName} | pid()</v>
+        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}</v>
+        <v>&nbsp;&nbsp;| {via,Module,ViaName} | pid()</v>
         <v>&nbsp;Name = Node = atom()</v>
         <v>&nbsp;GlobalName = ViaName = term()</v>
         <v>Event = term()</v>
+        <v>Timeout = int()>0 | infinity</v>
+        <v>Reply = term()</v>
       </type>
       <desc>
-        <p>Sends an event asynchronously to the gen_fsm <c>FsmRef</c>
-          and returns <c>ok</c> immediately. The gen_fsm will call
-          <c>Module:handle_event/3</c> to handle the event.</p>
-        <p>See <seealso marker="#send_event/2">send_event/2</seealso>
-          for a description of the arguments.</p>
-        <p>The difference between <c>send_event</c> and
-          <c>send_all_state_event</c> is which callback function is
-          used to handle the event. This function is useful when
-          sending events that are handled the same way in every state,
-          as only one <c>handle_event</c> clause is needed to handle
-          the event instead of one clause in each state name function.</p>
+        <p>Sends an event to the <c>FsmRef</c> of the <c>gen_fsm</c>
+          process and waits until a reply arrives or a time-out occurs.
+          The <c>gen_fsm</c> process calls
+          <seealso marker="#Module:handle_sync_event/4">
+          <c>Module:handle_sync_event/4</c></seealso> to handle the event.</p>
+        <p>For a description of <c>FsmRef</c> and <c>Event</c>, see
+          <seealso marker="#send_event/2">send_event/2</seealso>.
+          For a description of <c>Timeout</c> and <c>Reply</c>, see
+          <seealso marker="#sync_send_event/3">
+          <c>sync_send_event/3</c></seealso>.</p>
+        <p>For a discussion about the difference between
+          <c>sync_send_event</c> and <c>sync_send_all_state_event</c>, see
+          <seealso marker="#send_all_state_event/2">
+          <c>send_all_state_event/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
       <name>sync_send_event(FsmRef, Event) -> Reply</name>
       <name>sync_send_event(FsmRef, Event, Timeout) -> Reply</name>
       <fsummary>Send an event synchronously to a generic FSM.</fsummary>
       <type>
-        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}
-	| {via,Module,ViaName} | pid()</v>
+        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}</v>
+        <v>&nbsp;&nbsp;| {via,Module,ViaName} | pid()</v>
         <v>&nbsp;Name = Node = atom()</v>
         <v>&nbsp;GlobalName = ViaName = term()</v>
         <v>Event = term()</v>
@@ -303,210 +518,231 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
         <v>Reply = term()</v>
       </type>
       <desc>
-        <p>Sends an event to the gen_fsm <c>FsmRef</c> and waits until a
-          reply arrives or a timeout occurs. The gen_fsm will call
-          <c>Module:StateName/3</c> to handle the event, where
+        <p>Sends an event to the <c>FsmRef</c> of the <c>gen_fsm</c>
+          process and waits until a reply arrives or a time-out occurs.
+          <c>The gen_fsm</c> process calls
+          <seealso marker="#Module:StateName/3">
+          <c>Module:StateName/3</c></seealso> to handle the event, where
           <c>StateName</c> is the name of the current state of
-          the gen_fsm.</p>
-        <p>See <seealso marker="#send_event/2">send_event/2</seealso>
-          for a description of <c>FsmRef</c> and <c>Event</c>.</p>
-        <p><c>Timeout</c> is an integer greater than zero which
+          the <c>gen_fsm</c> process.</p>
+        <p>For a description of <c>FsmRef</c> and <c>Event</c>, see
+          <seealso marker="#send_event/2"><c>send_event/2</c></seealso>.</p>
+        <p><c>Timeout</c> is an integer greater than zero that
           specifies how many milliseconds to wait for a reply, or
-          the atom <c>infinity</c> to wait indefinitely. Default value
-          is 5000. If no reply is received within the specified time,
+          the atom <c>infinity</c> to wait indefinitely. Defaults
+          to 5000. If no reply is received within the specified time,
           the function call fails.</p>
-        <p>The return value <c>Reply</c> is defined in the return value
+        <p>Return value <c>Reply</c> is defined in the return value
           of <c>Module:StateName/3</c>.</p>
-        <p>The ancient behaviour of sometimes consuming the server
+	<note>
+          <p>The ancient behavior of sometimes consuming the server
           exit message if the server died during the call while
-          linked to the client has been removed in OTP R12B/Erlang 5.6.</p>
+          linked to the client was removed in Erlang 5.6/OTP R12B.</p>
+	</note>
       </desc>
     </func>
+  </funcs>
+
+  <section>
+    <title>Callback Functions</title>
+    <p>The following functions are to be exported from a <c>gen_fsm</c>
+      callback module.</p>
+
+    <p><em>state name</em> denotes a state of the state machine.</p>
+
+    <p><em>state data</em> denotes the internal state of the Erlang process
+      that implements the state machine.</p>
+  </section>
+
+  <funcs>
     <func>
-      <name>sync_send_all_state_event(FsmRef, Event) -> Reply</name>
-      <name>sync_send_all_state_event(FsmRef, Event, Timeout) -> Reply</name>
-      <fsummary>Send an event synchronously to a generic FSM.</fsummary>
+      <name>Module:code_change(OldVsn, StateName, StateData, Extra) -> {ok, NextStateName, NewStateData}</name>
+      <fsummary>Update the internal state data during upgrade/downgrade.
+      </fsummary>
       <type>
-        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}
-	| {via,Module,ViaName} | pid()</v>
-        <v>&nbsp;Name = Node = atom()</v>
-        <v>&nbsp;GlobalName = ViaName = term()</v>
-        <v>Event = term()</v>
-        <v>Timeout = int()>0 | infinity</v>
-        <v>Reply = term()</v>
+        <v>OldVsn = Vsn | {down,  Vsn}</v>
+        <v>&nbsp;&nbsp;Vsn = term()</v>
+        <v>StateName = NextStateName = atom()</v>
+        <v>StateData = NewStateData = term()</v>
+        <v>Extra = term()</v>
       </type>
       <desc>
-        <p>Sends an event to the gen_fsm <c>FsmRef</c> and waits until a
-          reply arrives or a timeout occurs. The gen_fsm will call
-          <c>Module:handle_sync_event/4</c> to handle the event.</p>
-        <p>See <seealso marker="#send_event/2">send_event/2</seealso>
-          for a description of <c>FsmRef</c> and <c>Event</c>. See
-          <seealso marker="#sync_send_event/3">sync_send_event/3</seealso>
-          for a description of <c>Timeout</c> and <c>Reply</c>.</p>
-        <p>See
-          <seealso marker="#send_all_state_event/2">send_all_state_event/2</seealso>
-          for a discussion about the difference between
-          <c>sync_send_event</c> and <c>sync_send_all_state_event</c>.</p>
+        <p>This function is called by a <c>gen_fsm</c> process when it is to
+          update its internal state data during a release upgrade/downgrade,
+          that is, when instruction <c>{update,Module,Change,...}</c>,
+          where <c>Change={advanced,Extra}</c>, is given in
+          the <c>appup</c> file; see section
+          <seealso marker="doc/design_principles:release_handling#instr">
+          Release Handling Instructions</seealso> in OTP Design Principles.</p>
+        <p>For an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and for a downgrade,
+          <c>OldVsn</c> is <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the
+          <c>vsn</c> attribute(s) of the old version of the callback module
+          <c>Module</c>. If no such attribute is defined, the version is
+          the checksum of the Beam file.</p>
+        <p><c>StateName</c> is the current state name and <c>StateData</c> the
+          internal state data of the <c>gen_fsm</c> process.</p>
+        <p><c>Extra</c> is passed "as is" from the <c>{advanced,Extra}</c>
+          part of the update instruction.</p>
+        <p>The function is to return the new current state name and
+          updated internal data.</p>
       </desc>
     </func>
+
     <func>
-      <name>reply(Caller, Reply) -> Result</name>
-      <fsummary>Send a reply to a caller.</fsummary>
+      <name>Module:format_status(Opt, [PDict, StateData]) -> Status</name>
+      <fsummary>Optional function for providing a term describing the
+        current <c>gen_fsm</c> process status.</fsummary>
       <type>
-        <v>Caller - see below</v>
-        <v>Reply = term()</v>
-	<v>Result = term()</v>
+        <v>Opt = normal | terminate</v>
+        <v>PDict = [{Key, Value}]</v>
+        <v>StateData = term()</v>
+        <v>Status = term()</v>
       </type>
       <desc>
-        <p>This function can be used by a gen_fsm to explicitly send a
-          reply to a client process that called
-          <seealso marker="#sync_send_event/2">sync_send_event/2,3</seealso>
-          or
-          <seealso marker="#sync_send_all_state_event/2">sync_send_all_state_event/2,3</seealso>,
-          when the reply cannot be defined in the return value of
-          <c>Module:State/3</c> or <c>Module:handle_sync_event/4</c>.</p>
-        <p><c>Caller</c> must be the <c>From</c> argument provided to
-          the callback function. <c>Reply</c> is an arbitrary term,
-          which will be given back to the client as the return value of
-          <c>sync_send_event/2,3</c> or
-          <c>sync_send_all_state_event/2,3</c>.</p>
-        <p>The return value <c>Result</c> is not further defined, and
-	   should always be ignored.</p>
+        <note>
+          <p>This callback is optional, so callback modules need not
+            export it. The <c>gen_fsm</c> module provides a default
+            implementation of this function that returns the callback
+            module state data.</p>
+        </note>
+        <p>This function is called by a <c>gen_fsm</c> process in the
+          following situations:</p>
+        <list type="bulleted">
+          <item>One of <seealso marker="sys#get_status/1">
+            <c>sys:get_status/1,2</c></seealso>
+            is invoked to get the <c>gen_fsm</c> status. <c>Opt</c> is set to
+            the atom <c>normal</c> for this case.</item>
+          <item>The <c>gen_fsm</c> process terminates abnormally and logs an
+            error. <c>Opt</c> is set to the atom <c>terminate</c> for
+            this case.</item>
+        </list>
+        <p>This function is useful for changing the form and
+          appearance of the <c>gen_fsm</c> status for these cases. A callback
+          module wishing to change the <c>sys:get_status/1,2</c>
+          return value as well as how its status appears in
+          termination error logs, exports an instance
+          of <c>format_status/2</c> that returns a term describing the
+          current status of the <c>gen_fsm</c> process.</p>
+        <p><c>PDict</c> is the current value of the process dictionary of the
+          <c>gen_fsm</c> process.</p>
+        <p><c>StateData</c> is the internal state data of the
+          <c>gen_fsm</c> process.</p>
+        <p>The function is to return <c>Status</c>, a term that
+          change the details of the current state and status of
+          the <c>gen_fsm</c> process. There are no restrictions on the
+          form <c>Status</c> can take, but for
+          the <c>sys:get_status/1,2</c> case (when <c>Opt</c>
+          is <c>normal</c>), the recommended form for
+          the <c>Status</c> value is <c>[{data, [{"StateData",
+          Term}]}]</c>, where <c>Term</c> provides relevant details of
+          the <c>gen_fsm</c> state data. Following this recommendation is not
+          required, but it makes the callback module status
+          consistent with the rest of the <c>sys:get_status/1,2</c>
+          return value.</p>
+        <p>One use for this function is to return compact alternative
+          state data representations to avoid that large state terms
+          are printed in log files.</p>
       </desc>
     </func>
+
     <func>
-      <name>send_event_after(Time, Event) -> Ref</name>
-      <fsummary>Send a delayed event internally in a generic FSM.</fsummary>
+      <name>Module:handle_event(Event, StateName, StateData) -> Result</name>
+      <fsummary>Handle an asynchronous event.</fsummary>
       <type>
-        <v>Time = integer()</v>
         <v>Event = term()</v>
-        <v>Ref = reference()</v>
-      </type>
-      <desc>
-        <p>Sends a delayed event internally in the gen_fsm that calls
-          this function after <c>Time</c> ms. Returns immediately a
-          reference that can be used to cancel the delayed send using
-          <seealso marker="#cancel_timer/1">cancel_timer/1</seealso>.</p>
-        <p>The gen_fsm will call <c>Module:StateName/2</c> to handle
-          the event, where <c>StateName</c> is the name of the current
-          state of the gen_fsm at the time the delayed event is
-          delivered.</p>
-        <p><c>Event</c> is an arbitrary term which is passed as one of
-          the arguments to <c>Module:StateName/2</c>.</p>
-      </desc>
-    </func>
-    <func>
-      <name>start_timer(Time, Msg) -> Ref</name>
-      <fsummary>Send a timeout event internally in a generic FSM.</fsummary>
-      <type>
-        <v>Time = integer()</v>
-        <v>Msg = term()</v>
-        <v>Ref = reference()</v>
+        <v>StateName = atom()</v>
+        <v>StateData = term()</v>
+        <v>Result = {next_state,NextStateName,NewStateData}</v>
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,Timeout}</v>
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,hibernate}</v>
+        <v>&nbsp;&nbsp;| {stop,Reason,NewStateData}</v>
+        <v>&nbsp;NextStateName = atom()</v>
+        <v>&nbsp;NewStateData = term()</v>
+        <v>&nbsp;Timeout = int()>0 | infinity</v>
+        <v>&nbsp;Reason = term()</v>
       </type>
       <desc>
-        <p>Sends a timeout event internally in the gen_fsm that calls
-          this function after <c>Time</c> ms. Returns immediately a
-          reference that can be used to cancel the timer using
-          <seealso marker="#cancel_timer/1">cancel_timer/1</seealso>.</p>
-        <p>The gen_fsm will call <c>Module:StateName/2</c> to handle
-          the event, where <c>StateName</c> is the name of the current
-          state of the gen_fsm at the time the timeout message is
-          delivered.</p>
-        <p><c>Msg</c> is an arbitrary term which is passed in the
-          timeout message, <c>{timeout, Ref, Msg}</c>, as one of
-          the arguments to <c>Module:StateName/2</c>.</p>
+        <p>Whenever a <c>gen_fsm</c> process receives an event sent using
+          <seealso marker="#send_all_state_event/2">
+          <c>send_all_state_event/2</c></seealso>,
+          this function is called to handle the event.</p>
+        <p><c>StateName</c> is the current state name of the <c>gen_fsm</c>
+          process.</p>
+        <p>For a description of the other arguments and possible return values,
+          see <seealso marker="#Module:StateName/2">
+          <c>Module:StateName/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name>cancel_timer(Ref) -> RemainingTime | false</name>
-      <fsummary>Cancel an internal timer in a generic FSM.</fsummary>
+      <name>Module:handle_info(Info, StateName, StateData) -> Result</name>
+      <fsummary>Handle an incoming message.</fsummary>
       <type>
-        <v>Ref = reference()</v>
-        <v>RemainingTime = integer()</v>
+        <v>Info = term()</v>
+        <v>StateName = atom()</v>
+        <v>StateData = term()</v>
+        <v>Result = {next_state,NextStateName,NewStateData}</v> 
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,Timeout}</v>
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,hibernate}</v>
+        <v>&nbsp;&nbsp;| {stop,Reason,NewStateData}</v>
+        <v>&nbsp;NextStateName = atom()</v>
+        <v>&nbsp;NewStateData = term()</v>
+        <v>&nbsp;Timeout = int()>0 | infinity</v>
+        <v>&nbsp;Reason = normal | term()</v>
       </type>
       <desc>
-        <p>Cancels an internal timer referred by <c>Ref</c> in the
-          gen_fsm that calls this function.</p>
-        <p><c>Ref</c> is a reference returned from
-          <seealso marker="#send_event_after/2">send_event_after/2</seealso>
-          or
-          <seealso marker="#start_timer/2">start_timer/2</seealso>.</p>
-        <p>If the timer has already timed out, but the event not yet
-          been delivered, it is cancelled as if it had <em>not</em>
-          timed out, so there will be no false timer event after
-          returning from this function.</p>
-        <p>Returns the remaining time in ms until the timer would
-          have expired if <c>Ref</c> referred to an active timer,
-          <c>false</c> otherwise.</p>
+        <p>This function is called by a <c>gen_fsm</c> process when it receives
+          any other message than a synchronous or asynchronous event (or a
+          system message).</p>
+        <p><c>Info</c> is the received message.</p>
+        <p>For a description of the other arguments and possible return values,
+          see <seealso marker="#Module:StateName/2">
+          <c>Module:StateName/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name>enter_loop(Module, Options, StateName, StateData)</name>
-      <name>enter_loop(Module, Options, StateName, StateData, FsmName)</name>
-      <name>enter_loop(Module, Options, StateName, StateData, Timeout)</name>
-      <name>enter_loop(Module, Options, StateName, StateData, FsmName, Timeout)</name>
-      <fsummary>Enter the gen_fsm receive loop</fsummary>
+      <name>Module:handle_sync_event(Event, From, StateName, StateData) -> Result</name>
+      <fsummary>Handle a synchronous event.</fsummary>
       <type>
-        <v>Module = atom()</v>
-        <v>Options = [Option]</v>
-        <v>&nbsp;Option = {debug,Dbgs}</v>
-        <v>&nbsp;&nbsp;Dbgs = [Dbg]</v>
-        <v>&nbsp;&nbsp;&nbsp;Dbg = trace | log | statistics</v>
-        <v>&nbsp;&nbsp;&nbsp;&nbsp;| {log_to_file,FileName} | {install,{Func,FuncState}}</v>
+        <v>Event = term()</v>
+        <v>From = {pid(),Tag}</v>
         <v>StateName = atom()</v>
         <v>StateData = term()</v>
-        <v>FsmName = {local,Name} | {global,GlobalName}
-	| {via,Module,ViaName}</v>
-        <v>&nbsp;Name = atom()</v>
-        <v>&nbsp;GlobalName = ViaName = term()</v>
-        <v>Timeout = int() | infinity</v>
+        <v>Result = {reply,Reply,NextStateName,NewStateData}</v>
+        <v>&nbsp;&nbsp;| {reply,Reply,NextStateName,NewStateData,Timeout}</v> 
+        <v>&nbsp;&nbsp;| {reply,Reply,NextStateName,NewStateData,hibernate}</v>
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData}</v> 
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,Timeout}</v> 
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,hibernate}</v>
+        <v>&nbsp;&nbsp;| {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData}</v>
+        <v>&nbsp;Reply = term()</v>
+        <v>&nbsp;NextStateName = atom()</v>
+        <v>&nbsp;NewStateData = term()</v>
+        <v>&nbsp;Timeout = int()>0 | infinity</v>
+        <v>&nbsp;Reason = term()</v>
       </type>
       <desc>
-        <p>Makes an existing process into a gen_fsm. Does not return,
-          instead the calling process will enter the gen_fsm receive
-          loop and become a gen_fsm process. The process <em>must</em>
-          have been started using one of the start functions in
-          <c>proc_lib</c>, see
-          <seealso marker="proc_lib">proc_lib(3)</seealso>. The user is
-          responsible for any initialization of the process, including
-          registering a name for it.</p>
-        <p>This function is useful when a more complex initialization
-          procedure is needed than the gen_fsm behaviour provides.</p>
-        <p><c>Module</c>, <c>Options</c> and <c>FsmName</c> have
-          the same meanings as when calling
-          <seealso marker="#start_link/3">start[_link]/3,4</seealso>.
-          However, if <c>FsmName</c> is specified, the process must have
-          been registered accordingly <em>before</em> this function is
-          called.</p>
-        <p><c>StateName</c>, <c>StateData</c> and <c>Timeout</c> have
-          the same meanings as in the return value of
-          <seealso marker="#Moduleinit">Module:init/1</seealso>.
-          Also, the callback module <c>Module</c> does not need to
-          export an <c>init/1</c> function.</p>
-        <p>Failure: If the calling process was not started by a
-          <c>proc_lib</c> start function, or if it is not registered
-          according to <c>FsmName</c>.</p>
+        <p>Whenever a <c>gen_fsm</c> process receives an event sent using
+          <seealso marker="#sync_send_all_state_event/2">
+          <c>sync_send_all_state_event/2,3</c></seealso>,
+          this function is called to handle the event.</p>
+        <p><c>StateName</c> is the current state name of the <c>gen_fsm</c>
+          process.</p>
+        <p>For a description of the other arguments and possible return values,
+         see <seealso marker="#Module:StateName/3">
+         <c>Module:StateName/3</c></seealso>.</p>
       </desc>
     </func>
-  </funcs>
 
-  <section>
-    <title>CALLBACK FUNCTIONS</title>
-    <p>The following functions should be exported from a <c>gen_fsm</c>
-      callback module.</p>
-    <p>In the description, the expression <em>state name</em> is used to
-      denote a state of the state machine. <em>state data</em> is used
-      to denote the internal state of the Erlang process which
-      implements the state machine.</p>
-  </section>
-  <funcs>
     <func>
       <name>Module:init(Args) -> Result</name>
-      <fsummary>Initialize process and internal state name and state data.</fsummary>
+      <fsummary>Initialize process and internal state name and state data.
+      </fsummary>
       <type>
         <v>Args = term()</v>
         <v>Result = {ok,StateName,StateData} | {ok,StateName,StateData,Timeout}</v>
-	<v>&nbsp;&nbsp;| {ok,StateName,StateData,hibernate}</v>
+        <v>&nbsp;&nbsp;| {ok,StateName,StateData,hibernate}</v>
         <v>&nbsp;&nbsp;| {stop,Reason} | ignore</v>
         <v>&nbsp;StateName = atom()</v>
         <v>&nbsp;StateData = term()</v>
@@ -515,33 +751,36 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
       </type>
       <desc>
         <marker id="Moduleinit"></marker>
-        <p>Whenever a gen_fsm is started using
-          <seealso marker="#start/3">gen_fsm:start/3,4</seealso> or
-          <seealso marker="#start_link/3">gen_fsm:start_link/3,4</seealso>,
+        <p>Whenever a <c>gen_fsm</c> process  is started using
+          <seealso marker="#start/3"><c>start/3,4</c></seealso> or
+          <seealso marker="#start_link/3"><c>start_link/3,4</c></seealso>,
           this function is called by the new process to initialize.</p>
         <p><c>Args</c> is the <c>Args</c> argument provided to the start
           function.</p>
-        <p>If initialization is successful, the function should return
-          <c>{ok,StateName,StateData}</c>, 
-          <c>{ok,StateName,StateData,Timeout}</c> or <c>{ok,StateName,StateData,hibernate}</c>, 
-	  where <c>StateName</c>
+        <p>If initialization is successful, the function is to return
+          <c>{ok,StateName,StateData}</c>,
+          <c>{ok,StateName,StateData,Timeout}</c>, or
+          <c>{ok,StateName,StateData,hibernate}</c>, where <c>StateName</c>
           is the initial state name and <c>StateData</c> the initial
-          state data of the gen_fsm.</p>
-        <p>If an integer timeout value is provided, a timeout will occur
+          state data of the <c>gen_fsm</c> process.</p>
+        <p>If an integer time-out value is provided, a time-out occurs
           unless an event or a message is received within <c>Timeout</c>
-          milliseconds. A timeout is represented by the atom
-          <c>timeout</c> and should be handled by
-          the <c>Module:StateName/2</c> callback functions. The atom
+          milliseconds. A time-out is represented by the atom
+          <c>timeout</c> and is to be handled by the
+          <seealso marker="#Module:StateName/2">
+          <c>Module:StateName/2</c></seealso> callback functions. The atom
           <c>infinity</c> can be used to wait indefinitely, this is
           the default value.</p>
-	<p>If <c>hibernate</c> is specified instead of a timeout value, the process will go 
-	   into hibernation when waiting for the next message to arrive (by calling 
-	   <seealso marker="proc_lib#hibernate/3">proc_lib:hibernate/3</seealso>).</p>
-         <p>If something goes wrong during the initialization
-          the function should return <c>{stop,Reason}</c>, where
-          <c>Reason</c> is any term, or <c>ignore</c>.</p>
+        <p>If <c>hibernate</c> is specified instead of a time-out value, the
+          process goes into hibernation when waiting for the next message
+          to arrive (by calling <seealso marker="proc_lib#hibernate/3">
+          <c>proc_lib:hibernate/3</c></seealso>).</p>
+        <p>If the initialization fails, the function returns
+          <c>{stop,Reason}</c>, where <c>Reason</c> is any term,
+          or <c>ignore</c>.</p>
       </desc>
     </func>
+
     <func>
       <name>Module:StateName(Event, StateData) -> Result</name>
       <fsummary>Handle an asynchronous event.</fsummary>
@@ -549,8 +788,8 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
         <v>Event = timeout | term()</v>
         <v>StateData = term()</v>
         <v>Result = {next_state,NextStateName,NewStateData} </v>
-	<v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,Timeout}</v>
-	<v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,hibernate}</v>
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,Timeout}</v>
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,hibernate}</v>
         <v>&nbsp;&nbsp;| {stop,Reason,NewStateData}</v>
         <v>&nbsp;NextStateName = atom()</v>
         <v>&nbsp;NewStateData = term()</v>
@@ -558,56 +797,33 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
         <v>&nbsp;Reason = term()</v>
       </type>
       <desc>
-        <p>There should be one instance of this function for each
-          possible state name. Whenever a gen_fsm receives an event
-          sent using
-          <seealso marker="#send_event/2">gen_fsm:send_event/2</seealso>,
+        <p>There is to be one instance of this function for each
+          possible state name. Whenever a <c>gen_fsm</c> process  receives
+          an event sent using
+          <seealso marker="#send_event/2"><c>send_event/2</c></seealso>,
           the instance of this function with the same name as
           the current state name <c>StateName</c> is called to handle
-          the event. It is also called if a timeout occurs.</p>
-        <p><c>Event</c> is either the atom <c>timeout</c>, if a timeout
+          the event. It is also called if a time-out occurs.</p>
+        <p><c>Event</c> is either the atom <c>timeout</c>, if a time-out
           has occurred, or the <c>Event</c> argument provided to
           <c>send_event/2</c>.</p>
-        <p><c>StateData</c> is the state data of the gen_fsm.</p>
+        <p><c>StateData</c> is the state data of the <c>gen_fsm</c> process.</p>
         <p>If the function returns
           <c>{next_state,NextStateName,NewStateData}</c>, 
-          <c>{next_state,NextStateName,NewStateData,Timeout}</c> or
-	  <c>{next_state,NextStateName,NewStateData,hibernate}</c>,
-          the gen_fsm will continue executing with the current state
+          <c>{next_state,NextStateName,NewStateData,Timeout}</c>, or
+          <c>{next_state,NextStateName,NewStateData,hibernate}</c>, the
+          <c>gen_fsm</c> process continues executing with the current state
           name set to <c>NextStateName</c> and with the possibly
-          updated state data <c>NewStateData</c>. See
-          <c>Module:init/1</c> for a description of <c>Timeout</c> and <c>hibernate</c>.</p>
+          updated state data <c>NewStateData</c>. For a description of
+         <c>Timeout</c> and <c>hibernate</c>, see
+           <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>.</p>
         <p>If the function returns <c>{stop,Reason,NewStateData}</c>,
-          the gen_fsm will call
+          the <c>gen_fsm</c> process calls
           <c>Module:terminate(Reason,StateName,NewStateData)</c> and
-          terminate.</p>
-      </desc>
-    </func>
-    <func>
-      <name>Module:handle_event(Event, StateName, StateData) -> Result</name>
-      <fsummary>Handle an asynchronous event.</fsummary>
-      <type>
-        <v>Event = term()</v>
-        <v>StateName = atom()</v>
-        <v>StateData = term()</v>
-        <v>Result = {next_state,NextStateName,NewStateData} </v>
-	<v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,Timeout}</v>
-	<v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,hibernate}</v>
-        <v>&nbsp;&nbsp;| {stop,Reason,NewStateData}</v>
-        <v>&nbsp;NextStateName = atom()</v>
-        <v>&nbsp;NewStateData = term()</v>
-        <v>&nbsp;Timeout = int()>0 | infinity</v>
-        <v>&nbsp;Reason = term()</v>
-      </type>
-      <desc>
-        <p>Whenever a gen_fsm receives an event sent using
-          <seealso marker="#send_all_state_event/2">gen_fsm:send_all_state_event/2</seealso>,
-          this function is called to handle the event.</p>
-        <p><c>StateName</c> is the current state name of the gen_fsm.</p>
-        <p>See <c>Module:StateName/2</c> for a description of the other
-          arguments and possible return values.</p>
+          terminates.</p>
       </desc>
     </func>
+
     <func>
       <name>Module:StateName(Event, From, StateData) -> Result</name>
       <fsummary>Handle a synchronous event.</fsummary>
@@ -616,11 +832,11 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
         <v>From = {pid(),Tag}</v>
         <v>StateData = term()</v>
         <v>Result = {reply,Reply,NextStateName,NewStateData}</v> 
-	<v>&nbsp;&nbsp;| {reply,Reply,NextStateName,NewStateData,Timeout}</v> 
-	<v>&nbsp;&nbsp;| {reply,Reply,NextStateName,NewStateData,hibernate}</v>
+        <v>&nbsp;&nbsp;| {reply,Reply,NextStateName,NewStateData,Timeout}</v> 
+        <v>&nbsp;&nbsp;| {reply,Reply,NextStateName,NewStateData,hibernate}</v>
         <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData}</v> 
-	<v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,Timeout}</v> 
-	<v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,hibernate}</v>
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,Timeout}</v> 
+        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,hibernate}</v>
         <v>&nbsp;&nbsp;| {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData}</v>
         <v>&nbsp;Reply = term()</v>
         <v>&nbsp;NextStateName = atom()</v>
@@ -629,102 +845,56 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
         <v>&nbsp;Reason = normal | term()</v>
       </type>
       <desc>
-        <p>There should be one instance of this function for each
-          possible state name. Whenever a gen_fsm receives an event
-          sent using
-          <seealso marker="#sync_send_event/2">gen_fsm:sync_send_event/2,3</seealso>,
+        <p>There is to be one instance of this function for each
+          possible state name. Whenever a <c>gen_fsm</c> process receives an
+          event sent using <seealso marker="#sync_send_event/2">
+          <c>sync_send_event/2,3</c></seealso>,
           the instance of this function with the same name as
           the current state name <c>StateName</c> is called to handle
           the event.</p>
         <p><c>Event</c> is the <c>Event</c> argument provided to
-          <c>sync_send_event</c>.</p>
+          <c>sync_send_event/2,3</c>.</p>
         <p><c>From</c> is a tuple <c>{Pid,Tag}</c> where <c>Pid</c> is
-          the pid of the process which called <c>sync_send_event/2,3</c>
+          the pid of the process that called <c>sync_send_event/2,3</c>
           and <c>Tag</c> is a unique tag.</p>
-        <p><c>StateData</c> is the state data of the gen_fsm.</p>
-        <p>If the function returns
-          <c>{reply,Reply,NextStateName,NewStateData}</c>, 
-          <c>{reply,Reply,NextStateName,NewStateData,Timeout}</c> or 
-	  <c>{reply,Reply,NextStateName,NewStateData,hibernate}</c>,
-          <c>Reply</c> will be given back to <c>From</c> as the return
-          value of <c>sync_send_event/2,3</c>. The gen_fsm then
-          continues executing with the current state name set to
-          <c>NextStateName</c> and with the possibly updated state data
-          <c>NewStateData</c>. See <c>Module:init/1</c> for a
-          description of <c>Timeout</c> and <c>hibernate</c>.</p>
-        <p>If the function returns
-          <c>{next_state,NextStateName,NewStateData}</c>, 
-          <c>{next_state,NextStateName,NewStateData,Timeout}</c> or
-          <c>{next_state,NextStateName,NewStateData,hibernate}</c>,
-          the gen_fsm will continue executing in <c>NextStateName</c>
-          with <c>NewStateData</c>. Any reply to <c>From</c> must be
-          given explicitly using
-          <seealso marker="#reply/2">gen_fsm:reply/2</seealso>.</p>
-        <p>If the function returns
-          <c>{stop,Reason,Reply,NewStateData}</c>, <c>Reply</c> will be
-          given back to <c>From</c>. If the function returns
-          <c>{stop,Reason,NewStateData}</c>, any reply to <c>From</c>
-          must be given explicitly using <c>gen_fsm:reply/2</c>.
-          The gen_fsm will then call
-          <c>Module:terminate(Reason,StateName,NewStateData)</c> and
-          terminate.</p>
-      </desc>
-    </func>
-    <func>
-      <name>Module:handle_sync_event(Event, From, StateName, StateData) -> Result</name>
-      <fsummary>Handle a synchronous event.</fsummary>
-      <type>
-        <v>Event = term()</v>
-        <v>From = {pid(),Tag}</v>
-        <v>StateName = atom()</v>
-        <v>StateData = term()</v>
-        <v>Result = {reply,Reply,NextStateName,NewStateData}</v> 
-	<v>&nbsp;&nbsp;| {reply,Reply,NextStateName,NewStateData,Timeout}</v> 
-	<v>&nbsp;&nbsp;| {reply,Reply,NextStateName,NewStateData,hibernate}</v>
-        <v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData}</v> 
-	<v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,Timeout}</v> 
-	<v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,hibernate}</v>
-        <v>&nbsp;&nbsp;| {stop,Reason,Reply,NewStateData} | {stop,Reason,NewStateData}</v>
-        <v>&nbsp;Reply = term()</v>
-        <v>&nbsp;NextStateName = atom()</v>
-        <v>&nbsp;NewStateData = term()</v>
-        <v>&nbsp;Timeout = int()>0 | infinity</v>
-        <v>&nbsp;Reason = term()</v>
-      </type>
-      <desc>
-        <p>Whenever a gen_fsm receives an event sent using
-          <seealso marker="#sync_send_all_state_event/2">gen_fsm:sync_send_all_state_event/2,3</seealso>,
-          this function is called to handle the event.</p>
-        <p><c>StateName</c> is the current state name of the gen_fsm.</p>
-        <p>See <c>Module:StateName/3</c> for a description of the other
-          arguments and possible return values.</p>
-      </desc>
-    </func>
-    <func>
-      <name>Module:handle_info(Info, StateName, StateData) -> Result</name>
-      <fsummary>Handle an incoming message.</fsummary>
-      <type>
-        <v>Info = term()</v>
-        <v>StateName = atom()</v>
-        <v>StateData = term()</v>
-        <v>Result = {next_state,NextStateName,NewStateData}</v> 
-	<v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,Timeout}</v>
-	<v>&nbsp;&nbsp;| {next_state,NextStateName,NewStateData,hibernate}</v>
-        <v>&nbsp;&nbsp;| {stop,Reason,NewStateData}</v>
-        <v>&nbsp;NextStateName = atom()</v>
-        <v>&nbsp;NewStateData = term()</v>
-        <v>&nbsp;Timeout = int()>0 | infinity</v>
-        <v>&nbsp;Reason = normal | term()</v>
-      </type>
-      <desc>
-        <p>This function is called by a gen_fsm when it receives any
-          other message than a synchronous or asynchronous event (or a
-          system message).</p>
-        <p><c>Info</c> is the received message.</p>
-        <p>See <c>Module:StateName/2</c> for a description of the other
-          arguments and possible return values.</p>
+        <p><c>StateData</c> is the state data of the <c>gen_fsm</c> process.</p>
+        <list type="bulleted">
+          <item>
+            <p>If <c>{reply,Reply,NextStateName,NewStateData}</c>, 
+              <c>{reply,Reply,NextStateName,NewStateData,Timeout}</c>, or 
+              <c>{reply,Reply,NextStateName,NewStateData,hibernate}</c> is
+              returned, <c>Reply</c> is given back to <c>From</c> as the return
+              value of <c>sync_send_event/2,3</c>. The <c>gen_fsm</c> process
+              then continues executing with the current state name set to
+              <c>NextStateName</c> and with the possibly updated state data
+              <c>NewStateData</c>. For a description of <c>Timeout</c> and
+              <c>hibernate</c>, see
+              <seealso marker="#Module:init/1">
+              <c>Module:init/1</c></seealso>.</p>
+          </item>
+          <item>
+            <p>If <c>{next_state,NextStateName,NewStateData}</c>, 
+              <c>{next_state,NextStateName,NewStateData,Timeout}</c>, or
+              <c>{next_state,NextStateName,NewStateData,hibernate}</c> is
+              returned, the <c>gen_fsm</c> process continues executing in
+              <c>NextStateName</c> with <c>NewStateData</c>.
+              Any reply to <c>From</c> must be specified explicitly using
+              <seealso marker="#reply/2"><c>reply/2</c></seealso>.</p>
+          </item>
+          <item>
+            <p>If the function returns
+              <c>{stop,Reason,Reply,NewStateData}</c>, <c>Reply</c> is
+              given back to <c>From</c>. If the function returns
+              <c>{stop,Reason,NewStateData}</c>, any reply to <c>From</c>
+              must be specified explicitly using <c>reply/2</c>.
+              The <c>gen_fsm</c> process then calls
+              <c>Module:terminate(Reason,StateName,NewStateData)</c> and
+              terminates.</p>
+          </item>
+        </list>
       </desc>
     </func>
+
     <func>
       <name>Module:terminate(Reason, StateName, StateData)</name>
       <fsummary>Clean up before termination.</fsummary>
@@ -734,134 +904,56 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
         <v>StateData = term()</v>
       </type>
       <desc>
-        <p>This function is called by a gen_fsm when it is about to
-          terminate. It should be the opposite of <c>Module:init/1</c>
-          and do any necessary cleaning up. When it returns, the gen_fsm
-          terminates with <c>Reason</c>. The return value is ignored.</p>
+        <p>This function is called by a <c>gen_fsm</c> process when it is about
+          to terminate. It is to be the opposite of
+          <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
+          and do any necessary cleaning up. When it returns, the <c>gen_fsm</c>
+          process terminates with <c>Reason</c>. The return value is ignored.
+        </p>
         <p><c>Reason</c> is a term denoting the stop reason,
           <c>StateName</c> is the current state name, and
-          <c>StateData</c> is the state data of the gen_fsm.</p>
-        <p><c>Reason</c> depends on why the gen_fsm is terminating. If
+          <c>StateData</c> is the state data of the <c>gen_fsm</c> process.</p>
+        <p><c>Reason</c> depends on why the <c>gen_fsm</c> process is
+          terminating. If
           it is because another callback function has returned a stop
-          tuple <c>{stop,..}</c>, <c>Reason</c> will have the value
-          specified in that tuple. If it is due to a failure,
+          tuple <c>{stop,..}</c>, <c>Reason</c> has the value
+          specified in that tuple. If it is because of a failure,
           <c>Reason</c> is the error reason.</p>
-        <p>If the gen_fsm is part of a supervision tree and is ordered
-          by its supervisor to terminate, this function will be called
+        <p>If the <c>gen_fsm</c> process is part of a supervision tree and is
+          ordered by its supervisor to terminate, this function is called
           with <c>Reason=shutdown</c> if the following conditions apply:</p>
         <list type="bulleted">
-          <item>the gen_fsm has been set to trap exit signals, and</item>
-          <item>the shutdown strategy as defined in the supervisor's
-           child specification is an integer timeout value, not
-          <c>brutal_kill</c>.</item>
+          <item>
+            <p>The <c>gen_fsm</c> process has been set to trap exit signals.</p>
+          </item>
+          <item>
+            <p>The shutdown strategy as defined in the child specification of
+              the supervisor is an integer time-out value, not
+              <c>brutal_kill</c>.</p>
+          </item>
         </list>
-        <p>Even if the gen_fsm is <em>not</em> part of a supervision tree,
-	   this function will be called if it receives an <c>'EXIT'</c>
-	   message from its parent. <c>Reason</c> will be the same as in
-	   the <c>'EXIT'</c> message.</p>
-        <p>Otherwise, the gen_fsm will be immediately terminated.</p>
-        <p>Note that for any other reason than <c>normal</c>,
-          <c>shutdown</c>, or <c>{shutdown,Term}</c> the gen_fsm is
-	  assumed to terminate due to an error and
-	  an error report is issued using
-          <seealso marker="kernel:error_logger#format/2">error_logger:format/2</seealso>.</p>
-      </desc>
-    </func>
-    <func>
-      <name>Module:code_change(OldVsn, StateName, StateData, Extra) -> {ok, NextStateName, NewStateData}</name>
-      <fsummary>Update the internal state data during upgrade/downgrade.</fsummary>
-      <type>
-        <v>OldVsn = Vsn | {down,  Vsn}</v>
-        <v>&nbsp;&nbsp;Vsn = term()</v>
-        <v>StateName = NextStateName = atom()</v>
-        <v>StateData = NewStateData = term()</v>
-        <v>Extra = term()</v>
-      </type>
-      <desc>
-        <p>This function is called by a gen_fsm when it should update
-          its internal state data during a release upgrade/downgrade,
-          i.e. when the instruction <c>{update,Module,Change,...}</c>
-          where <c>Change={advanced,Extra}</c> is given in
-          the <c>appup</c> file. See
-          <seealso marker="doc/design_principles:release_handling#instr">OTP Design Principles</seealso>.</p>
-        <p>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and
-          in the case of a downgrade, <c>OldVsn</c> is
-          <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c>
-          attribute(s) of the old version of the callback module
-          <c>Module</c>. If no such attribute is defined, the version is
-          the checksum of the BEAM file.</p>
-        <p><c>StateName</c> is the current state name and
-          <c>StateData</c> the internal state data of the gen_fsm.</p>
-        <p><c>Extra</c> is passed as-is from the <c>{advanced,Extra}</c>
-          part of the update instruction.</p>
-        <p>The function should return the new current state name and
-          updated internal data.</p>
-      </desc>
-    </func>
-    <func>
-      <name>Module:format_status(Opt, [PDict, StateData]) -> Status</name>
-      <fsummary>Optional function for providing a term describing the
-        current gen_fsm status.</fsummary>
-      <type>
-        <v>Opt = normal | terminate</v>
-        <v>PDict = [{Key, Value}]</v>
-        <v>StateData = term()</v>
-        <v>Status = term()</v>
-      </type>
-      <desc>
-        <note>
-          <p>This callback is optional, so callback modules need not
-            export it. The gen_fsm module provides a default
-            implementation of this function that returns the callback
-            module state data.</p>
-        </note>
-        <p>This function is called by a gen_fsm process when:</p>
-        <list type="bulleted">
-          <item>One
-            of <seealso marker="sys#get_status/1">sys:get_status/1,2</seealso>
-            is invoked to get the gen_fsm status. <c>Opt</c> is set to
-            the atom <c>normal</c> for this case.</item>
-          <item>The gen_fsm terminates abnormally and logs an
-            error. <c>Opt</c> is set to the atom <c>terminate</c> for
-            this case.</item>
-        </list>
-        <p>This function is useful for customising the form and
-          appearance of the gen_fsm status for these cases. A callback
-          module wishing to customise the <c>sys:get_status/1,2</c>
-          return value as well as how its status appears in
-          termination error logs exports an instance
-          of <c>format_status/2</c> that returns a term describing the
-          current status of the gen_fsm.</p>
-        <p><c>PDict</c> is the current value of the gen_fsm's
-          process dictionary.</p>
-        <p><c>StateData</c> is the internal state data of the
-          gen_fsm.</p>
-        <p>The function should return <c>Status</c>, a term that
-          customises the details of the current state and status of
-          the gen_fsm. There are no restrictions on the
-          form <c>Status</c> can take, but for
-          the <c>sys:get_status/1,2</c> case (when <c>Opt</c>
-          is <c>normal</c>), the recommended form for
-          the <c>Status</c> value is <c>[{data, [{"StateData",
-          Term}]}]</c> where <c>Term</c> provides relevant details of
-          the gen_fsm state data. Following this recommendation isn't
-          required, but doing so will make the callback module status
-          consistent with the rest of the <c>sys:get_status/1,2</c>
-          return value.</p>
-        <p>One use for this function is to return compact alternative
-          state data representations to avoid having large state terms
-          printed in logfiles.</p>
+        <p>Even if the <c>gen_fsm</c> process is <em>not</em> part of a
+          supervision tree,
+          this function is called if it receives an <c>'EXIT'</c>
+          message from its parent. <c>Reason</c> is the same as in
+          the <c>'EXIT'</c> message.</p>
+        <p>Otherwise, the <c>gen_fsm</c> process terminates immediately.</p>
+        <p>Notice that for any other reason than <c>normal</c>,
+          <c>shutdown</c>, or <c>{shutdown,Term}</c> the <c>gen_fsm</c> process
+          is assumed to terminate because of an error and an error report is
+          issued using <seealso marker="kernel:error_logger#format/2">
+          <c>error_logger:format/2</c></seealso>.</p>
       </desc>
     </func>
   </funcs>
 
   <section>
-    <title>SEE ALSO</title>
-    <p><seealso marker="gen_event">gen_event(3)</seealso>,
-      <seealso marker="gen_server">gen_server(3)</seealso>,
-      <seealso marker="gen_statem">gen_statem(3)</seealso>,
-      <seealso marker="supervisor">supervisor(3)</seealso>,
-      <seealso marker="proc_lib">proc_lib(3)</seealso>,
-      <seealso marker="sys">sys(3)</seealso></p>
+    <title>See Also</title>
+    <p><seealso marker="gen_event"><c>gen_event(3)</c></seealso>,
+      <seealso marker="gen_server"><c>gen_server(3)</c></seealso>,
+      <seealso marker="gen_statem"><c>gen_statem(3)</c></seealso>,
+      <seealso marker="proc_lib"><c>proc_lib(3)</c></seealso>,
+      <seealso marker="supervisor"><c>supervisor(3)</c></seealso>,
+      <seealso marker="sys"><c>sys(3)</c></seealso></p>
   </section>
 </erlref>