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, 187 insertions, 186 deletions

diff --git a/lib/stdlib/doc/src/erl_parse.xml b/lib/stdlib/doc/src/erl_parse.xml
index 771ccc2dc6..647f36883c 100644
--- a/lib/stdlib/doc/src/erl_parse.xml
+++ b/lib/stdlib/doc/src/erl_parse.xml
@@ -28,20 +28,22 @@
     <docno>1</docno>
     <approved>Bjarne D&auml;cker</approved>
     <checked></checked>
-    <date>97-01-24</date>
+    <date>1997-01-24</date>
     <rev>B</rev>
-    <file>erl_parse.sgml</file>
+    <file>erl_parse.xml</file>
   </header>
   <module>erl_parse</module>
-  <modulesummary>The Erlang Parser</modulesummary>
+  <modulesummary>The Erlang parser.</modulesummary>
   <description>
-    <p>This module is the basic Erlang parser which converts tokens into
-      the abstract form of either forms (i.e., top-level constructs),
+    <p>This module is the basic Erlang parser that converts tokens into
+      the abstract form of either forms (that is, top-level constructs),
       expressions, or terms. The Abstract Format is described in the
       <seealso marker="erts:absform">ERTS User's Guide</seealso>.
-      Note that a token list must end with the <em>dot</em> token in order
-      to be acceptable to the parse functions (see <seealso marker="erl_scan">erl_scan(3)</seealso>).</p>
+      Notice that a token list must end with the <em>dot</em> token to be
+      acceptable to the parse functions (see the <seealso marker="erl_scan">
+      <c>erl_scan(3)</c></seealso>) module.</p>
   </description>
+
   <datatypes>
     <datatype>
       <name>abstract_clause()</name>
@@ -84,258 +86,257 @@
       <name name="token"></name>
     </datatype>
   </datatypes>
+
   <funcs>
     <func>
-      <name name="parse_form" arity="1"/>
-      <fsummary>Parse an Erlang form</fsummary>
-      <desc>
-        <p>This function parses <c><anno>Tokens</anno></c> as if it were
-          a form. It returns:</p>
-        <taglist>
-          <tag><c>{ok, <anno>AbsForm</anno>}</c></tag>
-          <item>
-            <p>The parsing was successful. <c><anno>AbsForm</anno></c> is the
-              abstract form of the parsed form.</p>
-          </item>
-          <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag>
-          <item>
-            <p>An error occurred.</p>
-          </item>
-        </taglist>
-      </desc>
-    </func>
-    <func>
-      <name name="parse_exprs" arity="1"/>
-      <fsummary>Parse Erlang expressions</fsummary>
-      <desc>
-        <p>This function parses <c><anno>Tokens</anno></c> as if it were
-          a list of expressions. It returns:</p>
-        <taglist>
-          <tag><c>{ok, <anno>ExprList</anno>}</c></tag>
-          <item>
-            <p>The parsing was successful. <c><anno>ExprList</anno></c> is a
-              list of the abstract forms of the parsed expressions.</p>
-          </item>
-          <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag>
-          <item>
-            <p>An error occurred.</p>
-          </item>
-        </taglist>
-      </desc>
-    </func>
-    <func>
-      <name name="parse_term" arity="1"/>
-      <fsummary>Parse an Erlang term</fsummary>
-      <desc>
-        <p>This function parses <c><anno>Tokens</anno></c> as if it were
-          a term. It returns:</p>
-        <taglist>
-          <tag><c>{ok, <anno>Term</anno>}</c></tag>
-          <item>
-            <p>The parsing was successful. <c><anno>Term</anno></c> is
-              the Erlang term corresponding to the token list.</p>
-          </item>
-          <tag><c>{error, ErrorInfo}</c></tag>
-          <item>
-            <p>An error occurred.</p>
-          </item>
-        </taglist>
-      </desc>
-    </func>
-    <func>
-      <name>format_error(ErrorDescriptor) -> Chars</name>
-      <fsummary>Format an error descriptor</fsummary>
-      <type>
-        <v>ErrorDescriptor = <seealso
-          marker="#type-error_info">error_description()</seealso></v>
-        <v>Chars = [char() | Chars]</v>
-      </type>
-      <desc>
-        <p>Uses an <c>ErrorDescriptor</c> and returns a string
-          which describes the error. This function is usually called
-          implicitly when an <c>ErrorInfo</c> structure is processed
-          (see below).</p>
-      </desc>
-    </func>
-    <func>
-      <name name="tokens" arity="1"/>
-      <name name="tokens" arity="2"/>
-      <fsummary>Generate a list of tokens for an expression</fsummary>
-      <desc>
-        <p>This function generates a list of tokens representing the abstract
-          form <c><anno>AbsTerm</anno></c> of an expression. Optionally, it
-          appends <c><anno>MoreTokens</anno></c>.</p>
-      </desc>
-    </func>
-    <func>
-      <name name="normalise" arity="1"/>
-      <fsummary>Convert abstract form to an Erlang term</fsummary>
-      <desc>
-        <p>Converts the abstract form <c><anno>AbsTerm</anno></c> of a
-          term into a
-          conventional Erlang data structure (i.e., the term itself).
-          This is the inverse of <c>abstract/1</c>.</p>
-      </desc>
-    </func>
-    <func>
       <name name="abstract" arity="1"/>
-      <fsummary>Convert an Erlang term into an abstract form</fsummary>
+      <fsummary>Convert an Erlang term into an abstract form.</fsummary>
       <desc>
         <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an
           abstract form of type <c><anno>AbsTerm</anno></c>.
-          This is the inverse of <c>normalise/1</c>.</p>
+          This function is the inverse of
+          <seealso marker="#normalise/1"><c>normalise/1</c></seealso>.</p>
         <p><c>erl_parse:abstract(T)</c> is equivalent to
           <c>erl_parse:abstract(T, 0)</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="abstract" arity="2"/>
-      <fsummary>Convert an Erlang term into an abstract form</fsummary>
+      <fsummary>Convert an Erlang term into an abstract form.</fsummary>
       <type name="encoding_func"/>
       <desc>
         <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an
           abstract form of type <c><anno>AbsTerm</anno></c>.</p>
-        <p>The <c><anno>Line</anno></c> option is the line that will
-          be assigned to each node of <c><anno>AbsTerm</anno></c>.</p>
-        <p>The <c><anno>Encoding</anno></c> option is used for
-          selecting which integer lists will be considered
+        <p>Option <c><anno>Line</anno></c> is the line to be
+          assigned to each node of <c><anno>AbsTerm</anno></c>.</p>
+        <p>Option <c><anno>Encoding</anno></c> is used for
+          selecting which integer lists to be considered
           as strings. The default is to use the encoding returned by
-          <seealso marker="epp#default_encoding/0">
+          function <seealso marker="epp#default_encoding/0">
           <c>epp:default_encoding/0</c></seealso>.
-          The value <c>none</c> means that no integer lists will be
-          considered as strings. The <c>encoding_func()</c> will be
-          called with one integer of a list at a time, and if it
-          returns <c>true</c> for every integer the list will be
+          Value <c>none</c> means that no integer lists are
+          considered as strings. <c>encoding_func()</c> is
+          called with one integer of a list at a time; if it
+          returns <c>true</c> for every integer, the list is
           considered a string.</p>
       </desc>
     </func>
+
     <func>
-      <name name="map_anno" arity="2"/>
-      <fsummary>
-        Map a function over the annotations of a <c>erl_parse</c> tree
-      </fsummary>
+      <name name="anno_from_term" arity="1"/>
+      <fsummary>Return annotations as terms.</fsummary>
       <desc>
-        <p>Modifies the <c>erl_parse</c> tree <c><anno>Abstr</anno></c>
-	  by applying <c><anno>Fun</anno></c> on each collection of
-	  annotations of the nodes of the <c>erl_parse</c> tree. The
-	  <c>erl_parse</c> tree is traversed in a depth-first,
-	  left-to-right, fashion.
-        </p>
+        <p>Assumes that <c><anno>Term</anno></c> is a term with the same
+          structure as a <c>erl_parse</c> tree, but with terms,
+          say <c>T</c>, where a <c>erl_parse</c> tree has collections
+          of annotations. Returns a <c>erl_parse</c> tree where each
+          term <c>T</c> is replaced by the value returned by
+          <seealso marker="erl_anno#from_term/1">
+          <c>erl_anno:from_term(T)</c></seealso>. The term
+          <c><anno>Term</anno></c> is traversed in a depth-first,
+          left-to-right fashion.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="anno_to_term" arity="1"/>
+      <fsummary>Return the representation of annotations.</fsummary>
+      <desc>
+        <p>Returns a term where each collection of annotations
+          <c>Anno</c> of the nodes of the <c>erl_parse</c> tree
+          <c><anno>Abstr</anno></c> is replaced by the term
+          returned by <seealso marker="erl_anno#to_term/1">
+          <c>erl_anno:to_term(Anno)</c></seealso>. The
+          <c>erl_parse</c> tree is traversed in a depth-first,
+          left-to-right fashion.</p>
       </desc>
     </func>
+
     <func>
       <name name="fold_anno" arity="3"/>
-      <fsummary>
-        Fold a function over the annotations of a <c>erl_parse</c> tree
+      <fsummary>Fold a function over the annotations of an <c>erl_parse</c> tree.
       </fsummary>
       <desc>
         <p>Updates an accumulator by applying <c><anno>Fun</anno></c> on
           each collection of annotations of the <c>erl_parse</c> tree
           <c><anno>Abstr</anno></c>. The first call to
           <c><anno>Fun</anno></c> has <c><anno>AccIn</anno></c> as
-          argument, and the returned accumulator
+          argument, the returned accumulator
           <c><anno>AccOut</anno></c> is passed to the next call, and
           so on. The final value of the accumulator is returned. The
-          <c>erl_parse</c> tree is traversed in a depth-first, left-to-right,
-          fashion.
-        </p>
+          <c>erl_parse</c> tree is traversed in a depth-first, left-to-right
+          fashion.</p>
       </desc>
     </func>
+
     <func>
-      <name name="mapfold_anno" arity="3"/>
-      <fsummary>
-        Map and fold a function over the annotations of a
-        <c>erl_parse</c> tree
+      <name>format_error(ErrorDescriptor) -> Chars</name>
+      <fsummary>Format an error descriptor.</fsummary>
+      <type>
+        <v>ErrorDescriptor = <seealso
+          marker="#type-error_info">error_description()</seealso></v>
+        <v>Chars = [char() | Chars]</v>
+      </type>
+      <desc>
+        <p>Uses an <c>ErrorDescriptor</c> and returns a string
+          that describes the error. This function is usually called
+          implicitly when an <c>ErrorInfo</c> structure is processed
+          (see section <seealso marker="#errorinfo">
+          Error Information</seealso>).</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="map_anno" arity="2"/>
+      <fsummary>Map a function over the annotations of an <c>erl_parse</c> tree.
       </fsummary>
       <desc>
         <p>Modifies the <c>erl_parse</c> tree <c><anno>Abstr</anno></c>
-	  by applying <c><anno>Fun</anno></c> on each collection of
-	  annotations of the nodes of the <c>erl_parse</c> tree, while
-	  at the same time updating an accumulator. The first call to
-	  <c><anno>Fun</anno></c> has <c><anno>AccIn</anno></c> as
-	  second argument, and the returned accumulator
-	  <c><anno>AccOut</anno></c> is passed to the next call, and
-	  so on. The modified <c>erl_parse</c> tree as well as the the
-	  final value of the accumulator are returned. The
-	  <c>erl_parse</c> tree is traversed in a depth-first,
-	  left-to-right, fashion.
-        </p>
+          by applying <c><anno>Fun</anno></c> on each collection of
+          annotations of the nodes of the <c>erl_parse</c> tree. The
+          <c>erl_parse</c> tree is traversed in a depth-first,
+          left-to-right fashion.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="mapfold_anno" arity="3"/>
+      <fsummary>Map and fold a function over the annotations of an
+        <c>erl_parse</c> tree.</fsummary>
+      <desc>
+        <p>Modifies the <c>erl_parse</c> tree <c><anno>Abstr</anno></c>
+          by applying <c><anno>Fun</anno></c> on each collection of
+          annotations of the nodes of the <c>erl_parse</c> tree, while
+          at the same time updating an accumulator. The first call to
+          <c><anno>Fun</anno></c> has <c><anno>AccIn</anno></c> as
+          second argument, the returned accumulator
+          <c><anno>AccOut</anno></c> is passed to the next call, and
+          so on. The modified <c>erl_parse</c> tree and the
+          final value of the accumulator are returned. The
+          <c>erl_parse</c> tree is traversed in a depth-first,
+          left-to-right fashion.</p>
       </desc>
     </func>
+
     <func>
       <name name="new_anno" arity="1"/>
-      <fsummary>
-        Create new annotations
-      </fsummary>
+      <fsummary>Create new annotations.</fsummary>
       <desc>
         <p>Assumes that <c><anno>Term</anno></c> is a term with the same
           structure as a <c>erl_parse</c> tree, but with <seealso
           marker="erl_anno#type-location">locations</seealso> where a
           <c>erl_parse</c> tree has collections of annotations.
           Returns a <c>erl_parse</c> tree where each location <c>L</c>
-          has been replaced by the value returned by <seealso
+          is replaced by the value returned by <seealso
           marker="erl_anno#new/1"><c>erl_anno:new(L)</c></seealso>.
           The term <c><anno>Term</anno></c> is traversed in a
-          depth-first, left-to-right, fashion.
-        </p>
+          depth-first, left-to-right fashion.</p>
       </desc>
     </func>
+
     <func>
-      <name name="anno_from_term" arity="1"/>
-      <fsummary>
-        Return annotations as terms
-      </fsummary>
+      <name name="normalise" arity="1"/>
+      <fsummary>Convert abstract form to an Erlang term.</fsummary>
       <desc>
-        <p>Assumes that <c><anno>Term</anno></c> is a term with the same
-          structure as a <c>erl_parse</c> tree, but with terms,
-          <c>T</c> say, where a <c>erl_parse</c> tree has collections
-          of annotations. Returns a <c>erl_parse</c> tree where each
-          term <c>T</c> has been replaced by the value returned by
-          <seealso marker="erl_anno#from_term/1">
-          <c>erl_anno:from_term(T)</c></seealso>. The term
-          <c><anno>Term</anno></c> is traversed in a depth-first,
-          left-to-right, fashion.
-        </p>
+        <p>Converts the abstract form <c><anno>AbsTerm</anno></c> of a
+          term into a conventional Erlang data structure (that is, the
+          term itself). This function is the inverse of
+          <seealso marker="#abstract/1"><c>abstract/1</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="anno_to_term" arity="1"/>
-      <fsummary>
-        Return the representation of annotations
-      </fsummary>
+      <name name="parse_exprs" arity="1"/>
+      <fsummary>Parse Erlang expressions.</fsummary>
       <desc>
-        <p>Returns a term where each collection of annotations
-          <c>Anno</c> of the nodes of the <c>erl_parse</c> tree
-          <c><anno>Abstr</anno></c> has been replaced by the term
-          returned by <seealso marker="erl_anno#to_term/1">
-          <c>erl_anno:to_term(Anno)</c></seealso>. The
-          <c>erl_parse</c> tree is traversed in a depth-first,
-          left-to-right, fashion.
-        </p>
+        <p>Parses <c><anno>Tokens</anno></c> as if it was a list of expressions.
+          Returns one of the following:</p>
+        <taglist>
+          <tag><c>{ok, <anno>ExprList</anno>}</c></tag>
+          <item>
+            <p>The parsing was successful. <c><anno>ExprList</anno></c> is a
+              list of the abstract forms of the parsed expressions.</p>
+          </item>
+          <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag>
+          <item>
+            <p>An error occurred.</p>
+          </item>
+        </taglist>
+      </desc>
+    </func>
+
+    <func>
+      <name name="parse_form" arity="1"/>
+      <fsummary>Parse an Erlang form.</fsummary>
+      <desc>
+        <p>Parses <c><anno>Tokens</anno></c> as if it was a form. Returns one
+          of the following:</p>
+        <taglist>
+          <tag><c>{ok, <anno>AbsForm</anno>}</c></tag>
+          <item>
+            <p>The parsing was successful. <c><anno>AbsForm</anno></c> is the
+              abstract form of the parsed form.</p>
+          </item>
+          <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag>
+          <item>
+            <p>An error occurred.</p>
+          </item>
+        </taglist>
+      </desc>
+    </func>
+
+    <func>
+      <name name="parse_term" arity="1"/>
+      <fsummary>Parse an Erlang term.</fsummary>
+      <desc>
+        <p>Parses <c><anno>Tokens</anno></c> as if it was a term. Returns
+          one of the following:</p>
+        <taglist>
+          <tag><c>{ok, <anno>Term</anno>}</c></tag>
+          <item>
+            <p>The parsing was successful. <c><anno>Term</anno></c> is
+              the Erlang term corresponding to the token list.</p>
+          </item>
+          <tag><c>{error, <anno>ErrorInfo</anno>}</c></tag>
+          <item>
+            <p>An error occurred.</p>
+          </item>
+        </taglist>
+      </desc>
+    </func>
+
+    <func>
+      <name name="tokens" arity="1"/>
+      <name name="tokens" arity="2"/>
+      <fsummary>Generate a list of tokens for an expression.</fsummary>
+      <desc>
+        <p>Generates a list of tokens representing the abstract
+          form <c><anno>AbsTerm</anno></c> of an expression. Optionally,
+          <c><anno>MoreTokens</anno></c> is appended.</p>
       </desc>
     </func>
   </funcs>
 
   <section>
+    <marker id="errorinfo"/>
     <title>Error Information</title>
-    <p>The <c>ErrorInfo</c> mentioned above is the standard
-      <c>ErrorInfo</c> structure which is returned from all IO
-      modules. It has the format:
-      </p>
+    <p><c>ErrorInfo</c> is the standard <c>ErrorInfo</c> structure that is
+      returned from all I/O modules. The format is as follows:</p>
     <code type="none">
-    {ErrorLine, Module, ErrorDescriptor}    </code>
-    <p>A string which describes the error is obtained with the following call:
-      </p>
+{ErrorLine, Module, ErrorDescriptor}</code>
+    <p>A string describing the error is obtained with the following call:</p>
     <code type="none">
-    Module:format_error(ErrorDescriptor)    </code>
+Module:format_error(ErrorDescriptor)</code>
   </section>
 
   <section>
     <title>See Also</title>
-    <p><seealso marker="io">io(3)</seealso>,
-       <seealso marker="erl_anno">erl_anno(3)</seealso>,
-       <seealso marker="erl_scan">erl_scan(3)</seealso>,
-       <seealso marker="erts:absform">ERTS User's Guide</seealso></p>
+    <p><seealso marker="erl_anno"><c>erl_anno(3)</c></seealso>,
+       <seealso marker="erl_scan"><c>erl_scan(3)</c></seealso>,
+       <seealso marker="io"><c>io(3)</c></seealso>,
+        section <seealso marker="erts:absform">The Abstract Format</seealso>
+        in the ERTS User's Guide</p>
   </section>
 </erlref>