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, 241 insertions, 175 deletions

diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml
index a9ecb60244..dddedf1132 100644
--- a/lib/stdlib/doc/src/string.xml
+++ b/lib/stdlib/doc/src/string.xml
@@ -24,306 +24,372 @@
 
     <title>string</title>
     <prepared>Robert Virding</prepared>
-    <responsible>Bjarne Dacker</responsible>
+    <responsible>Bjarne D&auml;cker</responsible>
     <docno>1</docno>
     <approved>Bjarne D&auml;cker</approved>
     <checked></checked>
-    <date>96-09-28</date>
+    <date>1996-09-28</date>
     <rev>A</rev>
-    <file>string.sgml</file>
+    <file>string.xml</file>
   </header>
   <module>string</module>
-  <modulesummary>String Processing Functions</modulesummary>
+  <modulesummary>String processing functions.</modulesummary>
   <description>
-    <p>This module contains functions for string processing.</p>
+    <p>This module provides functions for string processing.</p>
   </description>
+
   <funcs>
     <func>
-      <name name="len" arity="1"/>
-      <fsummary>Return the length of a string</fsummary>
+      <name name="centre" arity="2"/>
+      <name name="centre" arity="3"/>
+      <fsummary>Center a string.</fsummary>
       <desc>
-        <p>Returns the number of characters in the string.</p>
+        <p>Returns a string, where <c><anno>String</anno></c> is centered in the
+          string and surrounded by blanks or <c><anno>Character</anno></c>.
+	  The resulting string has length <c><anno>Number</anno></c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="equal" arity="2"/>
-      <fsummary>Test string equality</fsummary>
+      <name name="chars" arity="2"/>
+      <name name="chars" arity="3"/>
+      <fsummary>Returns a string consisting of numbers of characters.</fsummary>
       <desc>
-        <p>Tests whether two strings are equal. Returns <c>true</c> if
-          they are, otherwise <c>false</c>.</p>
+        <p>Returns a string consisting of <c><anno>Number</anno></c> characters
+          <c><anno>Character</anno></c>. Optionally, the string can end with
+          string <c><anno>Tail</anno></c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="concat" arity="2"/>
-      <fsummary>Concatenate two strings</fsummary>
+      <name name="chr" arity="2"/>
+      <fsummary>Return the index of the first occurrence of
+        a character in a string.</fsummary>
       <desc>
-        <p>Concatenates two strings to form a new string. Returns the
-          new string.</p>
+        <p>Returns the index of the first occurrence of
+          <c><anno>Character</anno></c> in <c><anno>String</anno></c>. Returns
+          <c>0</c> if <c><anno>Character</anno></c> does not occur.</p>
       </desc>
     </func>
+
     <func>
-      <name name="chr" arity="2"/>
-      <name name="rchr" arity="2"/>
-      <fsummary>Return the index of the first/last occurrence of<c>Character</c>in <c>String</c></fsummary>
+      <name name="concat" arity="2"/>
+      <fsummary>Concatenate two strings.</fsummary>
       <desc>
-        <p>Returns the index of the first/last occurrence of
-          <c><anno>Character</anno></c> in <c><anno>String</anno></c>. <c>0</c> is returned if <c><anno>Character</anno></c> does not
-          occur.</p>
+        <p>Concatenates <c><anno>String1</anno></c> and
+          <c><anno>String2</anno></c> to form a new string
+          <c><anno>String3</anno></c>, which is returned.</p>
       </desc>
     </func>
+
     <func>
-      <name name="str" arity="2"/>
-      <name name="rstr" arity="2"/>
-      <fsummary>Find the index of a substring</fsummary>
+      <name name="copies" arity="2"/>
+      <fsummary>Copy a string.</fsummary>
       <desc>
-        <p>Returns the position where the first/last occurrence of
-          <c><anno>SubString</anno></c> begins in <c><anno>String</anno></c>. <c>0</c> is returned if <c><anno>SubString</anno></c>
-          does not exist in <c><anno>String</anno></c>.
-          For example:</p>
-        <code type="none">
-> string:str(" Hello Hello World World ", "Hello World").
-8        </code>
+        <p>Returns a string containing <c><anno>String</anno></c> repeated
+          <c><anno>Number</anno></c> times.</p>
       </desc>
     </func>
+
     <func>
-      <name name="span" arity="2"/>
       <name name="cspan" arity="2"/>
-      <fsummary>Span characters at start of string</fsummary>
+      <fsummary>Span characters at start of a string.</fsummary>
       <desc>
         <p>Returns the length of the maximum initial segment of
-          <c><anno>String</anno></c>, which consists entirely of characters from (not
-          from) <c><anno>Chars</anno></c>.</p>
-        <p>For example:</p>
+          <c><anno>String</anno></c>, which consists entirely of characters
+          not from <c><anno>Chars</anno></c>.</p>
+        <p><em>Example:</em></p>
         <code type="none">
-> string:span("\t    abcdef", " \t").
-5
 > string:cspan("\t    abcdef", " \t").
-0        </code>
+0</code>
       </desc>
     </func>
+
     <func>
-      <name name="substr" arity="2"/>
-      <name name="substr" arity="3"/>
-      <fsummary>Return a substring of <c>String</c></fsummary>
+      <name name="equal" arity="2"/>
+      <fsummary>Test string equality.</fsummary>
+      <desc>
+        <p>Returns <c>true</c> if <c><anno>String1</anno></c> and
+          <c><anno>String2</anno></c> are equal, otherwise <c>false</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="join" arity="2"/>
+      <fsummary>Join a list of strings with separator.</fsummary>
       <desc>
-        <p>Returns a substring of <c><anno>String</anno></c>, starting at the
-          position <c><anno>Start</anno></c>, and ending at the end of the string or
-          at length <c><anno>Length</anno></c>.</p>
-        <p>For example:</p>
+        <p>Returns a string with the elements of <c><anno>StringList</anno></c>
+          separated by the string in <c><anno>Separator</anno></c>.</p>
+        <p><em>Example:</em></p>
         <code type="none">
-> substr("Hello World", 4, 5).
-"lo Wo"        </code>
+> join(["one", "two", "three"], ", ").
+"one, two, three"</code>
       </desc>
     </func>
+
     <func>
-      <name name="tokens" arity="2"/>
-      <fsummary>Split string into tokens</fsummary>
+      <name name="left" arity="2"/>
+      <name name="left" arity="3"/>
+      <fsummary>Adjust left end of a string.</fsummary>
       <desc>
-        <p>Returns a list of tokens in <c><anno>String</anno></c>, separated by the
-          characters in <c><anno>SeparatorList</anno></c>.</p>
-        <p>For example:</p>
+        <p>Returns <c><anno>String</anno></c> with the length adjusted in
+          accordance with <c><anno>Number</anno></c>. The left margin is
+          fixed. If <c>length(<anno>String</anno>)</c> &lt;
+          <c><anno>Number</anno></c>, then <c><anno>String</anno></c> is padded
+          with blanks or <c><anno>Character</anno></c>s.</p>
+        <p><em>Example:</em></p>
         <code type="none">
-> tokens("abc defxxghix jkl", "x ").
-["abc", "def", "ghi", "jkl"]        </code>
-	<p>Note that, as shown in the example above, two or more
-	adjacent separator characters in <c><anno>String</anno></c>
-	will be treated as one. That is, there will not be any empty
-	strings in the resulting list of tokens.</p>
+> string:left("Hello",10,$.).
+"Hello....."</code>
       </desc>
     </func>
+
     <func>
-      <name name="join" arity="2"/>
-      <fsummary>Join a list of strings with separator</fsummary>
+      <name name="len" arity="1"/>
+      <fsummary>Return the length of a string.</fsummary>
       <desc>
-	<p>Returns a string with the elements of <c><anno>StringList</anno></c>
-	  separated by the string in <c><anno>Separator</anno></c>.</p>
-	<p>For example:</p>
-	<code type="none">
-> join(["one", "two", "three"], ", ").
-"one, two, three"        </code>
+        <p>Returns the number of characters in <c><anno>String</anno></c>.</p>
       </desc>
     </func>
+
     <func>
-      <name name="chars" arity="2"/>
-      <name name="chars" arity="3"/>
-      <fsummary>Returns a string consisting of numbers of characters</fsummary>
+      <name name="rchr" arity="2"/>
+      <fsummary>Return the index of the last occurrence of
+        a character in a string.</fsummary>
       <desc>
-        <p>Returns a string consisting of <c><anno>Number</anno></c> of characters
-          <c><anno>Character</anno></c>. Optionally, the string can end with the
-          string <c><anno>Tail</anno></c>.</p>
+        <p>Returns the index of the last occurrence of
+          <c><anno>Character</anno></c> in <c><anno>String</anno></c>. Returns
+          <c>0</c> if <c><anno>Character</anno></c> does not occur.</p>
       </desc>
     </func>
+
     <func>
-      <name name="copies" arity="2"/>
-      <fsummary>Copy a string</fsummary>
+      <name name="right" arity="2"/>
+      <name name="right" arity="3"/>
+      <fsummary>Adjust right end of a string.</fsummary>
       <desc>
-        <p>Returns a string containing <c><anno>String</anno></c> repeated
-          <c><anno>Number</anno></c> times.</p>
+        <p>Returns <c><anno>String</anno></c> with the length adjusted in
+          accordance with <c><anno>Number</anno></c>. The right margin is
+          fixed. If the length of <c>(<anno>String</anno>)</c> &lt;
+          <c><anno>Number</anno></c>, then <c><anno>String</anno></c> is padded
+          with blanks or <c><anno>Character</anno></c>s.</p>
+        <p><em>Example:</em></p>
+        <code type="none">
+> string:right("Hello", 10, $.).
+".....Hello"</code>
       </desc>
     </func>
+
     <func>
-      <name name="words" arity="1"/>
-      <name name="words" arity="2"/>
-      <fsummary>Count blank separated words</fsummary>
+      <name name="rstr" arity="2"/>
+      <fsummary>Find the index of a substring.</fsummary>
       <desc>
-        <p>Returns the number of words in <c><anno>String</anno></c>, separated by
-          blanks or <c><anno>Character</anno></c>.</p>
-        <p>For example:</p>
+        <p>Returns the position where the last occurrence of
+          <c><anno>SubString</anno></c> begins in <c><anno>String</anno></c>.
+          Returns <c>0</c> if <c><anno>SubString</anno></c>
+          does not exist in <c><anno>String</anno></c>.</p>
+        <p><em>Example:</em></p>
         <code type="none">
-> words(" Hello old boy!", $o).
-4        </code>
+> string:rstr(" Hello Hello World World ", "Hello World").
+8</code>
       </desc>
     </func>
+
     <func>
-      <name name="sub_word" arity="2"/>
-      <name name="sub_word" arity="3"/>
-      <fsummary>Extract subword</fsummary>
+      <name name="span" arity="2"/>
+      <fsummary>Span characters at start of a string.</fsummary>
       <desc>
-        <p>Returns the word in position <c><anno>Number</anno></c> of <c><anno>String</anno></c>.
-          Words are separated by blanks or <c><anno>Character</anno></c>s.</p>
-        <p>For example:</p>
+        <p>Returns the length of the maximum initial segment of
+          <c><anno>String</anno></c>, which consists entirely of characters
+          from <c><anno>Chars</anno></c>.</p>
+        <p><em>Example:</em></p>
         <code type="none">
-> string:sub_word(" Hello old boy !",3,$o).
-"ld b"        </code>
+> string:span("\t    abcdef", " \t").
+5</code>
       </desc>
     </func>
+
+    <func>
+      <name name="str" arity="2"/>
+      <fsummary>Find the index of a substring.</fsummary>
+      <desc>
+        <p>Returns the position where the first occurrence of
+          <c><anno>SubString</anno></c> begins in <c><anno>String</anno></c>.
+          Returns <c>0</c> if <c><anno>SubString</anno></c>
+          does not exist in <c><anno>String</anno></c>.</p>
+        <p><em>Example:</em></p>
+        <code type="none">
+> string:str(" Hello Hello World World ", "Hello World").
+8</code>
+      </desc>
+    </func>
+
     <func>
       <name name="strip" arity="1"/>
       <name name="strip" arity="2"/>
       <name name="strip" arity="3"/>
-      <fsummary>Strip leading or trailing characters</fsummary>
+      <fsummary>Strip leading or trailing characters.</fsummary>
       <desc>
         <p>Returns a string, where leading and/or trailing blanks or a
           number of <c><anno>Character</anno></c> have been removed.
-          <c><anno>Direction</anno></c> can be <c>left</c>, <c>right</c>, or
-          <c>both</c> and indicates from which direction blanks are to be
-          removed. The function <c>strip/1</c> is equivalent to
+          <c><anno>Direction</anno></c>, which can be <c>left</c>, <c>right</c>,
+          or <c>both</c>, indicates from which direction blanks are to be
+          removed. <c>strip/1</c> is equivalent to
           <c>strip(String, both)</c>.</p>
-        <p>For example:</p>
+        <p><em>Example:</em></p>
         <code type="none">
 > string:strip("...Hello.....", both, $.).
-"Hello"        </code>
+"Hello"</code>
       </desc>
     </func>
+
     <func>
-      <name name="left" arity="2"/>
-      <name name="left" arity="3"/>
-      <fsummary>Adjust left end of string</fsummary>
+      <name name="sub_string" arity="2"/>
+      <name name="sub_string" arity="3"/>
+      <fsummary>Extract a substring.</fsummary>
       <desc>
-        <p>Returns the <c><anno>String</anno></c> with the length adjusted in
-          accordance with <c><anno>Number</anno></c>. The left margin is
-          fixed. If the <c>length(<anno>String</anno>)</c> &lt; <c><anno>Number</anno></c>,
-          <c><anno>String</anno></c> is padded with blanks or <c><anno>Character</anno></c>s.</p>
-        <p>For example:</p>
+        <p>Returns a substring of <c><anno>String</anno></c>, starting at
+          position <c><anno>Start</anno></c> to the end of the string, or to
+          and including position <c><anno>Stop</anno></c>.</p>
+        <p><em>Example:</em></p>
         <code type="none">
-> string:left("Hello",10,$.).
-"Hello....."        </code>
+sub_string("Hello World", 4, 8).
+"lo Wo"</code>
       </desc>
     </func>
+
     <func>
-      <name name="right" arity="2"/>
-      <name name="right" arity="3"/>
-      <fsummary>Adjust right end of string</fsummary>
+      <name name="substr" arity="2"/>
+      <name name="substr" arity="3"/>
+      <fsummary>Return a substring of a string.</fsummary>
       <desc>
-        <p>Returns the <c><anno>String</anno></c> with the length adjusted in
-          accordance with <c><anno>Number</anno></c>. The right margin is
-          fixed. If the length of <c>(<anno>String</anno>)</c> &lt; <c><anno>Number</anno></c>,
-          <c><anno>String</anno></c> is padded with blanks or <c><anno>Character</anno></c>s.</p>
-        <p>For example:</p>
+        <p>Returns a substring of <c><anno>String</anno></c>, starting at
+          position <c><anno>Start</anno></c>, and ending at the end of the
+          string or at length <c><anno>Length</anno></c>.</p>
+        <p><em>Example:</em></p>
         <code type="none">
-> string:right("Hello", 10, $.).
-".....Hello"        </code>
-      </desc>
-    </func>
-    <func>
-      <name name="centre" arity="2"/>
-      <name name="centre" arity="3"/>
-      <fsummary>Center a string</fsummary>
-      <desc>
-        <p>Returns a string, where <c><anno>String</anno></c> is centred in the
-          string and surrounded by blanks or characters. The resulting
-          string will have the length <c><anno>Number</anno></c>.</p>
+> substr("Hello World", 4, 5).
+"lo Wo"</code>
       </desc>
     </func>
+
     <func>
-      <name name="sub_string" arity="2"/>
-      <name name="sub_string" arity="3"/>
-      <fsummary>Extract a substring</fsummary>
+      <name name="sub_word" arity="2"/>
+      <name name="sub_word" arity="3"/>
+      <fsummary>Extract subword.</fsummary>
       <desc>
-        <p>Returns a substring of <c><anno>String</anno></c>, starting at the
-          position <c><anno>Start</anno></c> to the end of the string, or to and
-          including the <c><anno>Stop</anno></c> position.</p>
-        <p>For example:</p>
+        <p>Returns the word in position <c><anno>Number</anno></c> of
+          <c><anno>String</anno></c>. Words are separated by blanks or
+          <c><anno>Character</anno></c>s.</p>
+        <p><em>Example:</em></p>
         <code type="none">
-sub_string("Hello World", 4, 8).
-"lo Wo"        </code>
+> string:sub_word(" Hello old boy !",3,$o).
+"ld b"</code>
       </desc>
     </func>
+
     <func>
       <name name="to_float" arity="1"/>
-      <fsummary>Returns a float whose text representation is the integers (ASCII values) in String.</fsummary>
+      <fsummary>Returns a float whose text representation is the integers
+        (ASCII values) in a string.</fsummary>
       <desc>
-        <p>Argument <c><anno>String</anno></c> is expected to start with a valid text
-          represented float (the digits being ASCII values). Remaining characters 
-          in the string after the float are returned in <c><anno>Rest</anno></c>.</p>
-        <p>Example:</p>
+        <p>Argument <c><anno>String</anno></c> is expected to start with a
+          valid text represented float (the digits are ASCII values).
+          Remaining characters in the string after the float are returned in
+          <c><anno>Rest</anno></c>.</p>
+        <p><em>Example:</em></p>
         <code type="none">
-          > {F1,Fs} = string:to_float("1.0-1.0e-1"),
-          > {F2,[]} = string:to_float(Fs),
-          > F1+F2.
-          0.9
-          > string:to_float("3/2=1.5").
-          {error,no_float}
-          > string:to_float("-1.5eX").
-          {-1.5,"eX"}</code>
+> {F1,Fs} = string:to_float("1.0-1.0e-1"),
+> {F2,[]} = string:to_float(Fs),
+> F1+F2.
+0.9
+> string:to_float("3/2=1.5").
+{error,no_float}
+> string:to_float("-1.5eX").
+{-1.5,"eX"}</code>
       </desc>
     </func>
+
     <func>
       <name name="to_integer" arity="1"/>
-      <fsummary>Returns an integer whose text representation is the integers (ASCII values) in String.</fsummary>
+      <fsummary>Returns an integer whose text representation is the integers
+        (ASCII values) in a string.</fsummary>
       <desc>
-        <p>Argument <c><anno>String</anno></c> is expected to start with a valid text
-          represented integer (the digits being ASCII values). Remaining characters 
-          in the string after the integer are returned in <c><anno>Rest</anno></c>.</p>
-        <p>Example:</p>
+        <p>Argument <c><anno>String</anno></c> is expected to start with a
+          valid text represented integer (the digits are ASCII values).
+          Remaining characters in the string after the integer are returned in
+          <c><anno>Rest</anno></c>.</p>
+        <p><em>Example:</em></p>
         <code type="none">
-          > {I1,Is} = string:to_integer("33+22"),
-          > {I2,[]} = string:to_integer(Is),
-          > I1-I2.
-          11
-          > string:to_integer("0.5").
-          {0,".5"}
-          > string:to_integer("x=2").
-          {error,no_integer}</code>
+> {I1,Is} = string:to_integer("33+22"),
+> {I2,[]} = string:to_integer(Is),
+> I1-I2.
+11
+> string:to_integer("0.5").
+{0,".5"}
+> string:to_integer("x=2").
+{error,no_integer}</code>
       </desc>
     </func>
+
     <func>
       <name name="to_lower" arity="1" clause_i="1"/>
       <name name="to_lower" arity="1" clause_i="2"/>
       <name name="to_upper" arity="1" clause_i="1"/>
       <name name="to_upper" arity="1" clause_i="2"/>
-      <fsummary>Convert case of string (ISO/IEC 8859-1)</fsummary>
+      <fsummary>Convert case of string (ISO/IEC 8859-1).</fsummary>
       <type variable="String" name_i="1"/>
       <type variable="Result" name_i="1"/>
       <type variable="Char"/>
       <type variable="CharResult"/>
       <desc>
-        <p>The given string or character is case-converted. Note that
-          the supported character set is ISO/IEC 8859-1 (a.k.a. Latin 1),
-          all values outside this set is unchanged</p>
+        <p>The specified string or character is case-converted. Notice that
+          the supported character set is ISO/IEC 8859-1 (also called Latin 1);
+          all values outside this set are unchanged</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="tokens" arity="2"/>
+      <fsummary>Split string into tokens.</fsummary>
+      <desc>
+        <p>Returns a list of tokens in <c><anno>String</anno></c>, separated
+          by the characters in <c><anno>SeparatorList</anno></c>.</p>
+        <p><em>Example:</em></p>
+        <code type="none">
+> tokens("abc defxxghix jkl", "x ").
+["abc", "def", "ghi", "jkl"]</code>
+        <p>Notice that, as shown in this example, two or more
+          adjacent separator characters in <c><anno>String</anno></c>
+          are treated as one. That is, there are no empty
+          strings in the resulting list of tokens.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="words" arity="1"/>
+      <name name="words" arity="2"/>
+      <fsummary>Count blank separated words.</fsummary>
+      <desc>
+        <p>Returns the number of words in <c><anno>String</anno></c>, separated
+          by blanks or <c><anno>Character</anno></c>.</p>
+        <p><em>Example:</em></p>
+        <code type="none">
+> words(" Hello old boy!", $o).
+4</code>
       </desc>
     </func>
   </funcs>
 
   <section>
     <title>Notes</title>
-    <p>Some of the general string functions may seem to overlap each
-      other. The reason for this is that this string package is the
-      combination of two earlier packages and all the functions of
-      both packages have been retained.
-      </p>
+    <p>Some of the general string functions can seem to overlap each
+      other. The reason is that this string package is the
+      combination of two earlier packages and all functions of
+      both packages have been retained.</p>
+
     <note>
-      <p>Any undocumented functions in <c>string</c> should not be used.</p>
+      <p>Any undocumented functions in <c>string</c> are not to be used.</p>
     </note>
   </section>
 </erlref>