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, 129 insertions, 102 deletions

diff --git a/lib/stdlib/doc/src/epp.xml b/lib/stdlib/doc/src/epp.xml
index ac87f9c2b6..1dc0161398 100644
--- a/lib/stdlib/doc/src/epp.xml
+++ b/lib/stdlib/doc/src/epp.xml
@@ -28,214 +28,241 @@
     <docno>1</docno>
     <approved>Kenneth Lundin</approved>
     <checked></checked>
-    <date>97-01-31</date>
+    <date>1997-01-31</date>
     <rev>B</rev>
-    <file>epp.sgml</file>
+    <file>epp.xml</file>
   </header>
   <module>epp</module>
-  <modulesummary>An Erlang Code Preprocessor</modulesummary>
+  <modulesummary>An Erlang code preprocessor.</modulesummary>
   <description>
-    <p>The Erlang code preprocessor includes functions which are used
-      by <c>compile</c> to preprocess macros and include files before
-      the actual parsing takes place.</p>
+    <p>The Erlang code preprocessor includes functions that are used by the
+      <seealso marker="compiler:compile"><c>compile</c></seealso>
+      module to preprocess macros and include files before
+      the parsing takes place.</p>
+
     <p>The Erlang source file <marker
       id="encoding"/><em>encoding</em> is selected by a
       comment in one of the first two lines of the source file. The
-      first string that matches the regular expression
+      first string matching the regular expression
       <c>coding\s*[:=]\s*([-a-zA-Z0-9])+</c> selects the encoding. If
-      the matching string is not a valid encoding it is ignored. The
-      valid encodings are <c>Latin-1</c> and <c>UTF-8</c> where the
-      case of the characters can be chosen freely. Examples:</p>
-      <pre>
+      the matching string is not a valid encoding, it is ignored. The
+      valid encodings are <c>Latin-1</c> and <c>UTF-8</c>, where the
+      case of the characters can be chosen freely.</p>
+
+    <p><em>Examples:</em></p>
+
+    <pre>
 %% coding: utf-8</pre>
-      <pre>
+
+    <pre>
 %% For this file we have chosen encoding = Latin-1</pre>
-      <pre>
+
+    <pre>
 %% -*- coding: latin-1 -*-</pre>
   </description>
+
   <datatypes>
     <datatype>
       <name name="macros"></name>
     </datatype>
     <datatype>
       <name name="epp_handle"></name>
-      <desc><p>Handle to the epp server.</p></desc>
+      <desc><p>Handle to the <c>epp</c> server.</p></desc>
     </datatype>
     <datatype>
       <name name="source_encoding"></name>
     </datatype>
   </datatypes>
+
   <funcs>
     <func>
-      <name name="open" arity="1"/>
-      <fsummary>Open a file for preprocessing</fsummary>
+      <name name="close" arity="1"/>
+      <fsummary>Close the preprocessing of the file associated with <c>Epp</c>.
+      </fsummary>
       <desc>
-        <p>Opens a file for preprocessing.</p>
-	<p>If <c>extra</c> is given in
-	<c><anno>Options</anno></c>, the return value will be
-	<c>{ok, <anno>Epp</anno>, <anno>Extra</anno>}</c> instead
-	of <c>{ok, <anno>Epp</anno>}</c>.</p>
+        <p>Closes the preprocessing of a file.</p>
       </desc>
     </func>
+
     <func>
-      <name name="open" arity="2"/>
-      <fsummary>Open a file for preprocessing</fsummary>
+      <name name="default_encoding" arity="0"/>
+      <fsummary>Return the default encoding of Erlang source files.</fsummary>
       <desc>
-        <p>Equivalent to <c>epp:open([{name, FileName}, {includes, IncludePath}])</c>.</p>
+        <p>Returns the default encoding of Erlang source files.</p>
       </desc>
     </func>
+
     <func>
-      <name name="open" arity="3"/>
-      <fsummary>Open a file for preprocessing</fsummary>
+      <name name="encoding_to_string" arity="1"/>
+      <fsummary>Return a string representation of an encoding.</fsummary>
       <desc>
-        <p>Equivalent to <c>epp:open([{name, FileName}, {includes, IncludePath},
-	{macros, PredefMacros}])</c>.</p>
+        <p>Returns a string representation of an encoding. The string
+          is recognized by
+          <seealso marker="#read_encoding/1"><c>read_encoding/1,2</c></seealso>,
+          <seealso marker="#read_encoding_from_binary/1">
+          <c>read_encoding_from_binary/1,2</c></seealso>, and
+          <seealso marker="#set_encoding/1"><c>set_encoding/1,2</c></seealso>
+          as a valid encoding.</p>
       </desc>
     </func>
+
     <func>
-      <name name="close" arity="1"/>
-      <fsummary>Close the preprocessing of the file associated with <c>Epp</c></fsummary>
+      <name name="format_error" arity="1"/>
+      <fsummary>Format an error descriptor.</fsummary>
       <desc>
-        <p>Closes the preprocessing of a file.</p>
+        <p>Takes an <c><anno>ErrorDescriptor</anno></c> and returns
+          a string that
+          describes the error or warning. This function is usually
+          called implicitly when processing an <c>ErrorInfo</c>
+          structure (see section
+          <seealso marker="#errorinfo">Error Information</seealso>).</p>
       </desc>
     </func>
+
     <func>
-      <name name="parse_erl_form" arity="1"/>
-      <fsummary>Return the next Erlang form from the opened Erlang source file</fsummary>
-      <type name="warning_info"/>
+      <name name="open" arity="1"/>
+      <fsummary>Open a file for preprocessing.</fsummary>
       <desc>
-        <p>Returns the next Erlang form from the opened Erlang source file.
-          The tuple <c>{eof, <anno>Line</anno>}</c> is returned at end-of-file. The first
-          form corresponds to an implicit attribute <c>-file(File,1).</c>, where
-          <c>File</c> is the name of the file.</p>
+        <p>Opens a file for preprocessing.</p>
+        <p>If <c>extra</c> is specified in
+          <c><anno>Options</anno></c>, the return value is
+          <c>{ok, <anno>Epp</anno>, <anno>Extra</anno>}</c> instead
+          of <c>{ok, <anno>Epp</anno>}</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="parse_file" arity="2"/>
-      <fsummary>Preprocess and parse an Erlang source file</fsummary>
+      <name name="open" arity="2"/>
+      <fsummary>Open a file for preprocessing.</fsummary>
       <desc>
-        <p>Preprocesses and parses an Erlang source file.
-	Note that the tuple <c>{eof, <anno>Line</anno>}</c> returned
-	at end-of-file is included as a "form".</p>
-	<p>If <c>extra</c> is given in
-	<c><anno>Options</anno></c>, the return value will be
-	<c>{ok, [<anno>Form</anno>], <anno>Extra</anno>}</c> instead
-	of <c>{ok, [<anno>Form</anno>]}</c>.</p>
+        <p>Equivalent to
+          <c>epp:open([{name, FileName}, {includes, IncludePath}])</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="parse_file" arity="3"/>
-      <fsummary>Preprocess and parse an Erlang source file</fsummary>
+      <name name="open" arity="3"/>
+      <fsummary>Open a file for preprocessing.</fsummary>
       <desc>
-        <p>Equivalent to <c>epp:parse_file(FileName, [{includes, IncludePath},
-	{macros, PredefMacros}])</c>.</p>
+        <p>Equivalent to <c>epp:open([{name, FileName}, {includes, IncludePath},
+          {macros, PredefMacros}])</c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="default_encoding" arity="0"/>
-      <fsummary>Return the default encoding of Erlang source files</fsummary>
+      <name name="parse_erl_form" arity="1"/>
+      <fsummary>Return the next Erlang form from the opened Erlang source file.
+      </fsummary>
+      <type name="warning_info"/>
       <desc>
-        <p>Returns the default encoding of Erlang source files.</p>
+        <p>Returns the next Erlang form from the opened Erlang source file.
+          Tuple <c>{eof, <anno>Line</anno>}</c> is returned at the end of the
+          file. The first form corresponds to an implicit attribute
+          <c>-file(File,1).</c>, where <c>File</c> is the file name.</p>
       </desc>
     </func>
+
     <func>
-      <name name="encoding_to_string" arity="1"/>
-      <fsummary>Return a string representation of an encoding</fsummary>
+      <name name="parse_file" arity="2"/>
+      <fsummary>Preprocess and parse an Erlang source file.</fsummary>
       <desc>
-        <p>Returns a string representation of an encoding. The string
-        is recognized by <c>read_encoding/1,2</c>,
-        <c>read_encoding_from_binary/1,2</c>, and
-        <c>set_encoding/1,2</c> as a valid encoding.</p>
+        <p>Preprocesses and parses an Erlang source file.
+          Notice that tuple <c>{eof, <anno>Line</anno>}</c> returned at the
+          end of the file is included as a "form".</p>
+        <p>If <c>extra</c> is specified in
+         <c><anno>Options</anno></c>, the return value is
+         <c>{ok, [<anno>Form</anno>], <anno>Extra</anno>}</c> instead
+         of <c>{ok, [<anno>Form</anno>]}</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="parse_file" arity="3"/>
+      <fsummary>Preprocess and parse an Erlang source file.</fsummary>
+      <desc>
+        <p>Equivalent to <c>epp:parse_file(FileName, [{includes, IncludePath},
+          {macros, PredefMacros}])</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="read_encoding" arity="1"/>
       <name name="read_encoding" arity="2"/>
-      <fsummary>Read the encoding from a file</fsummary>
+      <fsummary>Read the encoding from a file.</fsummary>
       <desc>
         <p>Read the <seealso marker="#encoding">encoding</seealso> from
           a file. Returns the read encoding, or <c>none</c> if no
-          valid encoding was found.</p>
-        <p>The option <c>in_comment_only</c> is <c>true</c> by
+          valid encoding is found.</p>
+        <p>Option <c>in_comment_only</c> is <c>true</c> by
           default, which is correct for Erlang source files. If set to
-          <c>false</c> the encoding string does not necessarily have to
+          <c>false</c>, the encoding string does not necessarily have to
           occur in a comment.</p>
       </desc>
     </func>
+
     <func>
       <name name="read_encoding_from_binary" arity="1"/>
       <name name="read_encoding_from_binary" arity="2"/>
-      <fsummary>Read the encoding from a binary</fsummary>
+      <fsummary>Read the encoding from a binary.</fsummary>
       <desc>
         <p>Read the <seealso marker="#encoding">encoding</seealso> from
           a binary. Returns the read encoding, or <c>none</c> if no
-          valid encoding was found.</p>
-        <p>The option <c>in_comment_only</c> is <c>true</c> by
+          valid encoding is found.</p>
+        <p>Option <c>in_comment_only</c> is <c>true</c> by
           default, which is correct for Erlang source files. If set to
-          <c>false</c> the encoding string does not necessarily have to
+          <c>false</c>, the encoding string does not necessarily have to
           occur in a comment.</p>
       </desc>
     </func>
+
     <func>
       <name name="set_encoding" arity="1"/>
-      <fsummary>Read and set the encoding of an IO device</fsummary>
+      <fsummary>Read and set the encoding of an I/O device.</fsummary>
       <desc>
         <p>Reads the <seealso marker="#encoding">encoding</seealso> from
-          an IO device and sets the encoding of the device
-          accordingly. The position of the IO device referenced by
+          an I/O device and sets the encoding of the device
+          accordingly. The position of the I/O device referenced by
           <c><anno>File</anno></c> is not affected. If no valid
-          encoding can be read from the IO device the encoding of the
-          IO device is set to the default encoding.</p>
+          encoding can be read from the I/O device, the encoding of the
+          I/O device is set to the default encoding.</p>
         <p>Returns the read encoding, or <c>none</c> if no valid
-          encoding was found.</p>
+          encoding is found.</p>
       </desc>
     </func>
+
     <func>
       <name name="set_encoding" arity="2"/>
-      <fsummary>Read and set the encoding of an IO device</fsummary>
+      <fsummary>Read and set the encoding of an I/O device.</fsummary>
       <desc>
         <p>Reads the <seealso marker="#encoding">encoding</seealso> from
-          an IO device and sets the encoding of the device
-          accordingly. The position of the IO device referenced by
+          an I/O device and sets the encoding of the device
+          accordingly. The position of the I/O device referenced by
           <c><anno>File</anno></c> is not affected. If no valid
-          encoding can be read from the IO device the encoding of the
-          IO device is set to the
-	  <seealso marker="#encoding">encoding</seealso> given by
-	  <c><anno>Default</anno></c>.</p>
+          encoding can be read from the I/O device, the encoding of the
+          I/O device is set to the
+          <seealso marker="#encoding">encoding</seealso> specified by
+          <c><anno>Default</anno></c>.</p>
         <p>Returns the read encoding, or <c>none</c> if no valid
-          encoding was found.</p>
-      </desc>
-    </func>
-    <func>
-      <name name="format_error" arity="1"/>
-      <fsummary>Format an error descriptor</fsummary>
-      <desc>
-        <p>Takes an <c><anno>ErrorDescriptor</anno></c> and returns
-          a string which
-          describes the error or warning. This function is usually
-          called implicitly when processing an <c>ErrorInfo</c>
-          structure (see below).</p>
+          encoding is found.</p>
       </desc>
     </func>
   </funcs>
 
   <section>
     <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 following format:
-      </p>
+    <marker id="errorinfo"/>
+    <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="erl_parse">erl_parse(3)</seealso></p>
+    <p><seealso marker="erl_parse"><c>erl_parse(3)</c></seealso></p>
   </section>
 </erlref>