Update Kernel documentation

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

1 files changed, 111 insertions, 108 deletions

diff --git a/lib/kernel/doc/src/seq_trace.xml b/lib/kernel/doc/src/seq_trace.xml
index 857444e338..d29aceb564 100644
--- a/lib/kernel/doc/src/seq_trace.xml
+++ b/lib/kernel/doc/src/seq_trace.xml
@@ -29,24 +29,17 @@
     <rev>A</rev>
   </header>
   <module>seq_trace</module>
-  <modulesummary>Sequential Tracing of Messages</modulesummary>
+  <modulesummary>Sequential tracing of messages.</modulesummary>
   <description>
     <p>Sequential tracing makes it possible to trace all messages
       resulting from one initial message. Sequential tracing is
-      completely independent of the ordinary tracing in Erlang, which
-      is controlled by the <c>erlang:trace/3</c> BIF. See the chapter
-      <seealso marker="#whatis">What is Sequential Tracing</seealso>
-      below for more information about what sequential tracing is and
-      how it can be used.</p>
-    <p><c>seq_trace</c> provides functions which control all aspects of 
+      independent of the ordinary tracing in Erlang, which
+      is controlled by the <c>erlang:trace/3</c> BIF. For more information
+      about what sequential tracing is and how it can be used, see section
+      <seealso marker="#whatis">Sequential Tracing</seealso>.</p>
+    <p><c>seq_trace</c> provides functions that control all aspects of
       sequential tracing. There are functions for activation,
-      deactivation, inspection and for collection of the trace output.</p>
-    <note>
-      <p>The implementation of sequential tracing is in beta status.
-        This means that the programming interface still might undergo
-        minor adjustments (possibly incompatible) based on feedback
-        from users.</p>
-    </note>
+      deactivation, inspection, and for collection of the trace output.</p>
   </description>
   <datatypes>
     <datatype>
@@ -239,20 +232,21 @@ seq_trace:set_token(OldToken), % activate the trace token again
   </funcs>
 
   <section>
-    <title>Trace Messages Sent To the System Tracer</title>
-    <p>The format of the messages are:</p>
+    <title>Trace Messages Sent to the System Tracer</title>
+    <p>The format of the messages is one of the following, depending on if
+      flag <c>timestamp</c> of the trace token is set to <c>true</c> or
+      <c>false</c>:</p>
     <code type="none">
 {seq_trace, Label, SeqTraceInfo, TimeStamp}</code>
     <p>or</p>
     <code type="none">
 {seq_trace, Label, SeqTraceInfo}</code>
-    <p>depending on whether the <c>timestamp</c> flag of the trace
-      token is set to <c>true</c> or <c>false</c>. Where:</p>
+    <p>Where:</p>
     <code type="none">
 Label = int()
 TimeStamp = {Seconds, Milliseconds, Microseconds}  
   Seconds = Milliseconds = Microseconds = int()</code>
-    <p>The <c>SeqTraceInfo</c> can have the following formats:</p>
+    <p><c>SeqTraceInfo</c> can have the following formats:</p>
     <taglist>
       <tag><c>{send, Serial, From, To, Message}</c></tag>
       <item>
@@ -262,141 +256,151 @@ TimeStamp = {Seconds, Milliseconds, Microseconds}
       <tag><c>{'receive', Serial, From, To, Message}</c></tag>
       <item>
         <p>Used when a process <c>To</c> receives a message with a
-          trace token that has the <c>'receive'</c> flag set to
-          <c>true</c>.</p>
+          trace token that has flag <c>'receive'</c> set to <c>true</c>.</p>
       </item>
       <tag><c>{print, Serial, From, _, Info}</c></tag>
       <item>
-        <p>Used when a process <c>From</c> has called 
+        <p>Used when a process <c>From</c> has called
           <c>seq_trace:print(Label, TraceInfo)</c> and has a trace
-          token with the <c>print</c> flag set to <c>true</c> and
+          token with flag <c>print</c> set to <c>true</c>, and
           <c>label</c> set to <c>Label</c>.</p>
       </item>
     </taglist>
     <p><c>Serial</c> is a tuple <c>{PreviousSerial, ThisSerial}</c>,
-      where the first integer <c>PreviousSerial</c> denotes the serial
-      counter passed in the last received message which carried a trace 
-      token. If the process is the first one in a new sequential trace,
-      <c>PreviousSerial</c> is set to the value of the process internal 
-      "trace clock". The second integer <c>ThisSerial</c> is the serial
-      counter that a process sets on outgoing messages and it is based
-      on the process internal "trace clock" which is incremented by one
-      before it is attached to the trace token in the message.</p>
+      where:</p>
+    <list type="bulleted">
+      <item><p>Integer <c>PreviousSerial</c> denotes the serial
+        counter passed in the last received message that carried a trace
+        token. If the process is the first in a new sequential trace,
+        <c>PreviousSerial</c> is set to the value of the process internal
+        "trace clock".</p></item>
+      <item><p>Integer <c>ThisSerial</c> is the serial
+        counter that a process sets on outgoing messages. It is based
+        on the process internal "trace clock", which is incremented by one
+        before it is attached to the trace token in the message.</p></item>
+    </list>
   </section>
 
   <section>
     <marker id="whatis"></marker>
-    <title>What is Sequential Tracing</title>
+    <title>Sequential Tracing</title>
     <p>Sequential tracing is a way to trace a sequence of messages sent
       between different local or remote processes, where the sequence
-      is initiated by one single message. In short it works like this:</p>
+      is initiated by a single message. In short, it works as follows:</p>
     <p>Each process has a <em>trace token</em>, which can be empty or
-      not empty. When not empty the trace token can be seen as
+      not empty. When not empty, the trace token can be seen as
       the tuple <c>{Label, Flags, Serial, From}</c>. The trace token is
       passed invisibly with each message.</p>
-    <p>In order to start a sequential trace the user must explicitly set
+    <p>To start a sequential trace, the user must explicitly set
       the trace token in the process that will send the first message
       in a sequence.</p>
     <p>The trace token of a process is set each time the process
       matches a message in a receive statement, according to the trace
       token carried by the received message, empty or not.</p>
-    <p>On each Erlang node a process can be set as the <em>system tracer</em>. This process will receive trace messages each time
+    <p>On each Erlang node, a process can be set as the <em>system tracer</em>.
+      This process receives trace messages each time
       a message with a trace token is sent or received (if the trace
       token flag <c>send</c> or <c>'receive'</c> is set). The system
-      tracer can then print each trace event, write it to a file or
+      tracer can then print each trace event, write it to a file, or
       whatever suitable.</p>
     <note>
-      <p>The system tracer will only receive those trace events that
+      <p>The system tracer only receives those trace events that
         occur locally within the Erlang node. To get the whole picture
-        of a sequential trace that involves processes on several Erlang
+        of a sequential trace, involving processes on many Erlang
         nodes, the output from the system tracer on each involved node
-        must be merged (off line).</p>
+        must be merged (offline).</p>
     </note>
-    <p>In the following sections Sequential Tracing and its most
-      fundamental concepts are described.</p>
+    <p>The following sections describe sequential tracing and its most
+      fundamental concepts.</p>
   </section>
 
   <section>
     <title>Trace Token</title>
-    <p>Each process has a current trace token. Initially the token is
+    <p>Each process has a current trace token. Initially, the token is
       empty. When the process sends a message to another process, a
-      copy of the current token will be sent "invisibly" along with
+      copy of the current token is sent "invisibly" along with
       the message.</p>
-    <p>The current token of a process is set in two ways, either</p>
-    <list type="ordered">
+    <p>The current token of a process is set in one of the following two
+      ways:</p>
+    <list type="bulleted">
       <item>
-        <p>explicitly by the process itself, through a call to
-          <c>seq_trace:set_token</c>, or</p>
+        <p>Explicitly by the process itself, through a call to
+          <c>seq_trace:set_token/1,2</c></p>
       </item>
       <item>
-        <p>when a message is received.</p>
+        <p>When a message is received</p>
       </item>
     </list>
-    <p>In both cases the current token will be set. In particular, if
-      the token of a message received is empty, the current token of
+    <p>In both cases, the current token is set. In particular, if
+      the token of a received message is empty, the current token of
       the process is set to empty.</p>
-    <p>A trace token contains a label, and a set of flags. Both
-      the label and the flags are set in 1 and 2 above.</p>
+    <p>A trace token contains a label and a set of flags. Both
+      the label and the flags are set in both alternatives above.</p>
   </section>
 
   <section>
     <title>Serial</title>
-    <p>The trace token contains a component which is called
-      <c>serial</c>. It consists of two integers <c>Previous</c> and
+    <p>The trace token contains a component called
+      <c>serial</c>. It consists of two integers, <c>Previous</c> and
       <c>Current</c>. The purpose is to uniquely identify each traced
-      event within a trace sequence and to order the messages
-      chronologically and in the different branches if any.</p>
+      event within a trace sequence, as well as to order the messages
+      chronologically and in the different branches, if any.</p>
     <p>The algorithm for updating <c>Serial</c> can be described as
       follows:</p>
-    <p>Let each process have two counters <c>prev_cnt</c> and
-      <c>curr_cnt</c> which both are set to 0 when a process is created.
+    <p>Let each process have two counters, <c>prev_cnt</c> and
+      <c>curr_cnt</c>, both are set to <c>0</c> when a process is created.
       The counters are updated at the following occasions:</p>
     <list type="bulleted">
       <item>
-        <p><em>When the process is about to send a message and the trace token is not empty.</em></p>
+        <p><em>When the process is about to send a message and the trace token
+          is not empty.</em></p>
         <p>Let the serial of the trace token be <c>tprev</c> and
-          <c>tcurr</c>.          <br></br>
-<c>curr_cnt := curr_cnt + 1</c>          <br></br>
-<c>tprev := prev_cnt</c>          <br></br>
-<c>tcurr := curr_cnt</c></p>
+          <c>tcurr</c>.</p>
+        <pre>
+curr_cnt := curr_cnt + 1
+tprev := prev_cnt
+tcurr := curr_cnt</pre>
         <p>The trace token with <c>tprev</c> and <c>tcurr</c> is then
           passed along with the message.</p>
       </item>
       <item>
-        <p><em>When the process calls</em><c>seq_trace:print(Label, Info)</c>, <em>Label matches the label part of the trace token and the trace token print flag is true.</em></p>
-        <p>The same algorithm as for send above.</p>
+        <p><em>When the process calls</em> <c>seq_trace:print(Label, Info)</c>,
+          <c>Label</c> <em>matches the label part of the trace token and the
+          trace token print flag is <c>true</c>.</em></p>
+        <p>The algorithm is the same as for send above.</p>
       </item>
       <item>
-        <p><em>When a message is received and contains a nonempty trace token.</em></p>
+        <p><em>When a message is received and contains a non-empty trace
+          token.</em></p>
         <p>The process trace token is set to the trace token from
           the message.</p>
         <p>Let the serial of the trace token be <c>tprev</c> and
-          <c>tcurr</c>.          <br></br>
-<c><![CDATA[if (curr_cnt < tcurr )]]></c>          <br></br>
-
-          &nbsp; &nbsp; &nbsp; &nbsp;<c>curr_cnt := tcurr</c>          <br></br>
-<c>prev_cnt := tcurr</c></p>
+          <c>tcurr</c>.</p>
+        <code>
+<![CDATA[if (curr_cnt < tcurr )]]>
+   curr_cnt := tcurr
+prev_cnt := tcurr</code>
       </item>
     </list>
-    <p>The <c>curr_cnt</c> of a process is incremented each time
+    <p><c>curr_cnt</c> of a process is incremented each time
       the process is involved in a sequential trace. The counter can
       reach its limit (27 bits) if a process is very long-lived and is
-      involved in much sequential tracing. If the counter overflows it
-      will not be possible to use the serial for ordering of the trace
-      events. To prevent the counter from overflowing in the middle of
-      a sequential trace the function <c>seq_trace:reset_trace/0</c>
-      can be called to reset the <c>prev_cnt</c> and <c>curr_cnt</c> of
-      all processes in the Erlang node. This function will also set all
-      trace tokens in processes and their message queues to empty and
-      will thus stop all ongoing sequential tracing.</p>
+      involved in much sequential tracing. If the counter overflows, the
+      serial for ordering of the trace events cannot be used. To prevent
+      the counter from overflowing in the middle of
+      a sequential trace, function <c>seq_trace:reset_trace/0</c>
+      can be called to reset <c>prev_cnt</c> and <c>curr_cnt</c> of
+      all processes in the Erlang node. This function also sets all
+      trace tokens in processes and their message queues to empty, and
+      thus stops all ongoing sequential tracing.</p>
   </section>
 
   <section>
-    <title>Performance considerations</title>
-    <p>The performance degradation for a system which is enabled for
-      Sequential Tracing is negligible as long as no tracing is
-      activated. When tracing is activated there will of course be an
-      extra cost for each traced message but all other messages will be
+    <title>Performance Considerations</title>
+    <p>The performance degradation for a system that is enabled for
+      sequential tracing is negligible as long as no tracing is
+      activated. When tracing is activated, there is an
+      extra cost for each traced message, but all other messages are
       unaffected.</p>
   </section>
 
@@ -404,13 +408,13 @@ TimeStamp = {Seconds, Milliseconds, Microseconds}
     <title>Ports</title>
     <p>Sequential tracing is not performed across ports.</p>
     <p>If the user for some reason wants to pass the trace token to a
-      port this has to be done manually in the code of the port
+      port, this must be done manually in the code of the port
       controlling process. The port controlling processes have to check
       the appropriate sequential trace settings (as obtained from
-      <c>seq_trace:get_token/1</c> and include trace information in
+      <c>seq_trace:get_token/1</c>) and include trace information in
       the message data sent to their respective ports.</p>
     <p>Similarly, for messages received from a port, a port controller
-      has to retrieve trace specific information, and set appropriate
+      has to retrieve trace-specific information, and set appropriate
       sequential trace flags through calls to
       <c>seq_trace:set_token/2</c>.</p>
   </section>
@@ -418,23 +422,23 @@ TimeStamp = {Seconds, Milliseconds, Microseconds}
   <section>
     <title>Distribution</title>
     <p>Sequential tracing between nodes is performed transparently.
-      This applies to C-nodes built with Erl_Interface too. A C-node
-      built with Erl_Interface only maintains one trace token, which
-      means that the C-node will appear as one process from
+      This applies to C-nodes built with <c>Erl_Interface</c> too. A C-node
+      built with <c>Erl_Interface</c> only maintains one trace token, which
+      means that the C-node appears as one process from
       the sequential tracing point of view.</p>
-    <p>In order to be able to perform sequential tracing between
+    <p>To be able to perform sequential tracing between
       distributed Erlang nodes, the distribution protocol has been
-      extended (in a backward compatible way). An Erlang node which
-      supports sequential tracing can communicate with an older
-      (OTP R3B) node but messages passed within that node can of course
+      extended (in a backward compatible way). An Erlang node
+      supporting sequential tracing can communicate with an older
+      (Erlang/OTP R3B) node but messages passed within that node can
       not be traced.</p>
   </section>
 
   <section>
-    <title>Example of Usage</title>
-    <p>The example shown here will give rough idea of how the new
-      primitives can be used and what kind of output it will produce.</p>
-    <p>Assume that we have an initiating process with
+    <title>Example of Use</title>
+    <p>This example gives a rough idea of how the new
+      primitives can be used and what kind of output it produces.</p>
+    <p>Assume that you have an initiating process with
       <c><![CDATA[Pid == <0.30.0>]]></c> like this:</p>
     <code type="none">
 -module(seqex).
@@ -463,8 +467,8 @@ loop() ->
             PortController ! {ack,Ack}
     end,
     loop().</code>
-    <p>A possible output from the system's sequential_tracer (inspired
-      by AXE-10 and MD-110) could look like:</p>
+    <p>A possible output from the system's <c>sequential_tracer</c> can be
+      like this:</p>
     <pre>
 17:&lt;0.30.0> Info {0,1} WITH
 "**** Trace Started ****"
@@ -475,7 +479,7 @@ loop() ->
 17:&lt;0.30.0> Received {2,4} FROM &lt;0.31.0> WITH
 {ack,{received,the_message}}</pre>
     <p>The implementation of a system tracer process that produces
-      the printout above could look like this:</p>
+      this printout can look like this:</p>
     <code type="none">
 tracer() ->
     receive
@@ -502,16 +506,15 @@ print_trace({'receive',Serial,From,To,Message}) ->
 print_trace({send,Serial,From,To,Message}) ->
     io:format("~p Sent ~p TO ~p WITH~n~p~n", 
               [From,Serial,To,Message]).</code>
-    <p>The code that creates a process that runs the tracer function
-      above and sets that process as the system tracer could look like
-      this:</p>
+    <p>The code that creates a process that runs this tracer function
+      and sets that process as the system tracer can look like this:</p>
     <code type="none">
 start() ->
     Pid = spawn(?MODULE,tracer,[]),
     seq_trace:set_system_tracer(Pid), % set Pid as the system tracer 
     ok.</code>
-    <p>With a function like <c>test/0</c> below the whole example can be
-      started.</p>
+    <p>With a function like <c>test/0</c>, the whole example can be
+      started:</p>
     <code type="none">
 test() ->
     P = spawn(?MODULE, loop, [port]),