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, 134 insertions, 111 deletions

diff --git a/lib/stdlib/doc/src/erl_eval.xml b/lib/stdlib/doc/src/erl_eval.xml
index d60b04b510..1c0f7f062f 100644
--- a/lib/stdlib/doc/src/erl_eval.xml
+++ b/lib/stdlib/doc/src/erl_eval.xml
@@ -28,19 +28,19 @@
     <docno>1</docno>
     <approved>Bjarne D&auml;cker</approved>
     <checked></checked>
-    <date>97-01-21</date>
+    <date>1997-01-21</date>
     <rev>B</rev>
-    <file>erl_eval.sgml</file>
+    <file>erl_eval.xml</file>
   </header>
   <module>erl_eval</module>
-  <modulesummary>The Erlang Meta Interpreter</modulesummary>
+  <modulesummary>The Erlang meta interpreter.</modulesummary>
   <description>
     <p>This module provides an interpreter for Erlang expressions. The
       expressions are in the abstract syntax as returned by
       <seealso marker="erl_parse"><c>erl_parse</c></seealso>,
-      the Erlang parser, or <seealso marker="io">
-      <c>io</c></seealso>.</p>
+      the Erlang parser, or <seealso marker="io"><c>io</c></seealso>.</p>
   </description>
+
   <datatypes>
     <datatype>
       <name name="bindings"/>
@@ -73,9 +73,9 @@
     </datatype>
     <datatype>
       <name name="local_function_handler"/>
-      <desc><p>Further described
-        <seealso marker="#local_function_handler">below.</seealso></p>
-      </desc>
+      <desc><p>Further described in section
+        <seealso marker="#local_function_handler">
+        Local Function Handler</seealso> in this module</p></desc>
     </datatype>
     <datatype>
       <name name="name"/>
@@ -85,152 +85,164 @@
     </datatype>
     <datatype>
       <name name="non_local_function_handler"/>
-      <desc><p>Further described
-        <seealso marker="#non_local_function_handler">below.</seealso></p>
-      </desc>
+      <desc><p>Further described in section
+        <seealso marker="#non_local_function_handler">
+        Non-Local Function Handler</seealso> in this module.</p></desc>
     </datatype>
     <datatype>
       <name name="value"/>
     </datatype>
   </datatypes>
+
   <funcs>
     <func>
-      <name name="exprs" arity="2"/>
-      <name name="exprs" arity="3"/>
-      <name name="exprs" arity="4"/>
-      <fsummary>Evaluate expressions</fsummary>
+      <name name="add_binding" arity="3"/>
+      <fsummary>Add a binding.</fsummary>
       <desc>
-        <p>Evaluates <c><anno>Expressions</anno></c> with the set of bindings
-          <c><anno>Bindings</anno></c>, where <c><anno>Expressions</anno></c>
-          is a sequence of
-          expressions (in abstract syntax) of a type which may be
-          returned by <seealso marker="io#parse_erl_exprs/2">
-        <c>io:parse_erl_exprs/2</c></seealso>. See below for an
-          explanation of how and when to use the arguments
-          <c><anno>LocalFunctionHandler</anno></c> and
-          <c><anno>NonLocalFunctionHandler</anno></c>.
-          </p>
-        <p>Returns <c>{value, <anno>Value</anno>, <anno>NewBindings</anno>}</c>
-        </p>
+        <p>Adds binding <c><anno>Name</anno>=<anno>Value</anno></c>
+          to <c><anno>BindingStruct</anno></c>.
+          Returns an updated binding structure.</p>
       </desc>
     </func>
+
+    <func>
+      <name name="binding" arity="2"/>
+      <fsummary>Return bindings.</fsummary>
+      <desc>
+        <p>Returns the binding of <c><anno>Name</anno></c>
+          in <c><anno>BindingStruct</anno></c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="bindings" arity="1"/>
+      <fsummary>Return bindings.</fsummary>
+      <desc>
+        <p>Returns the list of bindings contained in the binding
+          structure.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="del_binding" arity="2"/>
+      <fsummary>Delete a binding.</fsummary>
+      <desc>
+        <p>Removes the binding of <c><anno>Name</anno></c>
+          in <c><anno>BindingStruct</anno></c>.
+          Returns an updated binding structure.</p>
+      </desc>
+    </func>
+
     <func>
       <name name="expr" arity="2"/>
       <name name="expr" arity="3"/>
       <name name="expr" arity="4"/>
       <name name="expr" arity="5"/>
-      <fsummary>Evaluate expression</fsummary>
+      <fsummary>Evaluate expression.</fsummary>
       <desc>
         <p>Evaluates <c><anno>Expression</anno></c> with the set of bindings
-          <c><anno>Bindings</anno></c>. <c><anno>Expression</anno></c>
-          is an expression in
-          abstract syntax. See below for an explanation of
-          how and when to use the arguments
+          <c><anno>Bindings</anno></c>. <c><anno>Expression</anno></c> is an
+          expression in abstract syntax.
+          For an explanation of when and how to use arguments
           <c><anno>LocalFunctionHandler</anno></c> and
-          <c><anno>NonLocalFunctionHandler</anno></c>.
-          </p>
-        <p>Returns <c>{value, <anno>Value</anno>,
-        <anno>NewBindings</anno>}</c> by default. But if the
-        <c><anno>ReturnFormat</anno></c> is <c>value</c> only
-        the <c><anno>Value</anno></c> is returned.</p>
+          <c><anno>NonLocalFunctionHandler</anno></c>, see sections
+          <seealso marker="#local_function_handler">
+          Local Function Handler</seealso> and
+          <seealso marker="#non_local_function_handler">
+          Non-Local Function Handler</seealso> in this module.</p>
+        <p>Returns <c>{value, <anno>Value</anno>, <anno>NewBindings</anno>}</c>
+          by default. If <c><anno>ReturnFormat</anno></c> is <c>value</c>,
+          only <c><anno>Value</anno></c> is returned.</p>
       </desc>
     </func>
+
     <func>
       <name name="expr_list" arity="2"/>
       <name name="expr_list" arity="3"/>
       <name name="expr_list" arity="4"/>
-      <fsummary>Evaluate a list of expressions</fsummary>
+      <fsummary>Evaluate a list of expressions.</fsummary>
       <desc>
         <p>Evaluates a list of expressions in parallel, using the same
           initial bindings for each expression. Attempts are made to
-          merge the bindings returned from each evaluation.  This
-          function is useful in the <c>LocalFunctionHandler</c>. See below.
-          </p>
+          merge the bindings returned from each evaluation. This
+          function is useful in <c>LocalFunctionHandler</c>, see section
+          <seealso marker="#local_function_handler">
+          Local Function Handler</seealso> in this module.</p>
         <p>Returns <c>{<anno>ValueList</anno>, <anno>NewBindings</anno>}</c>.
         </p>
       </desc>
     </func>
+
     <func>
-      <name name="new_bindings" arity="0"/>
-      <fsummary>Return a bindings structure</fsummary>
-      <desc>
-        <p>Returns an empty binding structure.</p>
-      </desc>
-    </func>
-    <func>
-      <name name="bindings" arity="1"/>
-      <fsummary>Return bindings</fsummary>
-      <desc>
-        <p>Returns the list of bindings contained in the binding
-          structure.</p>
-      </desc>
-    </func>
-    <func>
-      <name name="binding" arity="2"/>
-      <fsummary>Return bindings</fsummary>
-      <desc>
-        <p>Returns the binding of <c><anno>Name</anno></c>
-          in <c><anno>BindingStruct</anno></c>.</p>
-      </desc>
-    </func>
-    <func>
-      <name name="add_binding" arity="3"/>
-      <fsummary>Add a binding</fsummary>
+      <name name="exprs" arity="2"/>
+      <name name="exprs" arity="3"/>
+      <name name="exprs" arity="4"/>
+      <fsummary>Evaluate expressions.</fsummary>
       <desc>
-        <p>Adds the binding <c><anno>Name</anno> = <anno>Value</anno></c>
-          to <c><anno>BindingStruct</anno></c>.
-          Returns an updated binding structure.</p>
+        <p>Evaluates <c><anno>Expressions</anno></c> with the set of bindings
+          <c><anno>Bindings</anno></c>, where <c><anno>Expressions</anno></c>
+          is a sequence of expressions (in abstract syntax) of a type that can
+          be returned by <seealso marker="io#parse_erl_exprs/2">
+          <c>io:parse_erl_exprs/2</c></seealso>.
+          For an explanation of when and how to use arguments
+          <c><anno>LocalFunctionHandler</anno></c> and
+          <c><anno>NonLocalFunctionHandler</anno></c>, see sections
+          <seealso marker="#local_function_handler">
+          Local Function Handler</seealso> and
+          <seealso marker="#non_local_function_handler">
+          Non-Local Function Handler</seealso> in this module.</p>
+        <p>Returns <c>{value, <anno>Value</anno>, <anno>NewBindings</anno>}</c>
+        </p>
       </desc>
     </func>
+
     <func>
-      <name name="del_binding" arity="2"/>
-      <fsummary>Delete a binding</fsummary>
+      <name name="new_bindings" arity="0"/>
+      <fsummary>Return a bindings structure.</fsummary>
       <desc>
-        <p>Removes the binding of <c><anno>Name</anno></c>
-          in <c><anno>BindingStruct</anno></c>.
-          Returns an updated binding structure.</p>
+        <p>Returns an empty binding structure.</p>
       </desc>
     </func>
   </funcs>
 
   <section>
+    <marker id="local_function_handler"></marker>
     <title>Local Function Handler</title>
-    <p><marker id="local_function_handler"></marker>
-      During evaluation of a function, no calls can be made to local
+    <p>During evaluation of a function, no calls can be made to local
       functions. An undefined function error would be
       generated. However, the optional argument
-      <c>LocalFunctionHandler</c> may be used to define a function
-      which is called when there is a call to a local function. The
+      <c>LocalFunctionHandler</c> can be used to define a function
+      that is called when there is a call to a local function. The
       argument can have the following formats:</p>
     <taglist>
       <tag><c>{value,Func}</c></tag>
       <item>
-        <p>This defines a local function handler which is called with:</p>
+        <p>This defines a local function handler that is called with:</p>
         <code type="none">
-Func(Name, Arguments)        </code>
+Func(Name, Arguments)</code>
         <p><c>Name</c> is the name of the local function (an atom) and
           <c>Arguments</c> is a list of the <em>evaluated</em>
           arguments. The function handler returns the value of the
-          local function. In this case, it is not possible to access
-          the current bindings. To signal an error, the function
-          handler just calls <c>exit/1</c> with a suitable exit value.</p>
+          local function. In this case, the current bindings cannot be
+          accessed. To signal an error, the function
+          handler calls <c>exit/1</c> with a suitable exit value.</p>
       </item>
       <tag><c>{eval,Func}</c></tag>
       <item>
-        <p>This defines a local function handler which is called with:</p>
+        <p>This defines a local function handler that is called with:</p>
         <code type="none">
-Func(Name, Arguments, Bindings)        </code>
+Func(Name, Arguments, Bindings)</code>
         <p><c>Name</c> is the name of the local function (an atom),
           <c>Arguments</c> is a list of the <em>unevaluated</em>
           arguments, and <c>Bindings</c> are the current variable
           bindings. The function handler returns:</p>
         <code type="none">
-{value,Value,NewBindings}        </code>
+{value,Value,NewBindings}</code>
         <p><c>Value</c> is the value of the local function and
           <c>NewBindings</c> are the updated variable bindings. In
           this case, the function handler must itself evaluate all the
           function arguments and manage the bindings. To signal an
-          error, the function handler just calls <c>exit/1</c> with a
+          error, the function handler calls <c>exit/1</c> with a
           suitable exit value.</p>
       </item>
       <tag><c>none</c></tag>
@@ -241,55 +253,66 @@ Func(Name, Arguments, Bindings)        </code>
   </section>
 
   <section>
-    <title>Non-local Function Handler</title>
-    <p><marker id="non_local_function_handler"></marker>
-      The optional argument <c>NonlocalFunctionHandler</c> may be
-      used to define a function which is called in the following
-      cases: a functional object (fun) is called; a built-in function
-      is called; a function is called using the M:F syntax, where M
-      and F are atoms or expressions; an operator Op/A is called
-      (this is handled as a call to the function <c>erlang:Op/A</c>).
-      Exceptions are calls to <c>erlang:apply/2,3</c>; neither of the
-      function handlers will be called for such calls. 
+    <marker id="non_local_function_handler"></marker>
+    <title>Non-Local Function Handler</title>
+    <p>The optional argument <c>NonLocalFunctionHandler</c> can be
+      used to define a function that is called in the following
+      cases:</p>
+    <list type="bulleted">
+      <item><p>A functional object (fun) is called.</p></item>
+      <item><p>A built-in function is called.</p></item>
+      <item><p>A function is called using the <c>M:F</c> syntax, where <c>M</c>
+        and <c>F</c> are atoms or expressions.</p></item>
+      <item><p>An operator <c>Op/A</c> is called (this is handled as a call to
+        function <c>erlang:Op/A</c>).</p></item>
+    </list>
+    <p>Exceptions are calls to <c>erlang:apply/2,3</c>; neither of the
+      function handlers are called for such calls.
       The argument can have the following formats:</p>
     <taglist>
       <tag><c>{value,Func}</c></tag>
       <item>
-        <p>This defines an nonlocal function handler which is called with:</p>
+        <p>This defines a non-local function handler that is called with:</p>
         <code type="none">
-Func(FuncSpec, Arguments)        </code>
+Func(FuncSpec, Arguments)</code>
         <p><c>FuncSpec</c> is the name of the function on the form
           <c>{Module,Function}</c> or a fun, and <c>Arguments</c> is a
           list of the <em>evaluated</em> arguments. The function
           handler returns the value of the function. To
-          signal an error, the function handler just calls
+          signal an error, the function handler calls
           <c>exit/1</c> with a suitable exit value.</p>
       </item>
       <tag><c>none</c></tag>
       <item>
-        <p>There is no nonlocal function handler.</p>
+        <p>There is no non-local function handler.</p>
       </item>
     </taglist>
     <note>
       <p>For calls such as <c>erlang:apply(Fun, Args)</c> or
-        <c>erlang:apply(Module, Function, Args)</c> the call of the
+        <c>erlang:apply(Module, Function, Args)</c>, the call of the
         non-local function handler corresponding to the call to
-        <c>erlang:apply/2,3</c> itself--<c>Func({erlang, apply}, [Fun, Args])</c> or <c>Func({erlang, apply}, [Module, Function, Args])</c>--will never take place. The non-local function
-        handler <em>will</em> however be called with the evaluated
-        arguments of the call to <c>erlang:apply/2,3</c>: <c>Func(Fun, Args)</c> or <c>Func({Module, Function}, Args)</c> (assuming
+        <c>erlang:apply/2,3</c> itself
+        (<c>Func({erlang, apply}, [Fun, Args])</c> or
+        <c>Func({erlang, apply}, [Module, Function, Args])</c>)
+        never takes place.</p>
+      <p>The non-local function handler <em>is</em> however called with the
+        evaluated arguments of the call to
+        <c>erlang:apply/2,3</c>: <c>Func(Fun, Args)</c> or
+        <c>Func({Module, Function}, Args)</c> (assuming
         that <c>{Module, Function}</c> is not <c>{erlang, apply}</c>).</p>
-      <p>Calls to functions defined by evaluating fun expressions
+     <p>Calls to functions defined by evaluating fun expressions
         <c>"fun ... end"</c> are also hidden from non-local function
-        handlers.</p> </note>
-    <p>The nonlocal function handler argument is probably not used as
+        handlers.</p>
+   </note>
+    <p>The non-local function handler argument is probably not used as
       frequently as the local function handler argument. A possible
       use is to call <c>exit/1</c> on calls to functions that for some
       reason are not allowed to be called.</p>
   </section>
 
   <section>
-    <title>Bugs</title>
-    <p>Undocumented functions in <c>erl_eval</c> should not be used.</p>
+    <title>Known Limitation</title>
+    <p>Undocumented functions in this module are not to be used.</p>
   </section>
 </erlref>