Merge branch 'bjorn/stdlib/doc'

* bjorn/stdlib/doc:
  Update STDLIB documentation

1 files changed, 438 insertions, 296 deletions

diff --git a/lib/stdlib/doc/src/lists.xml b/lib/stdlib/doc/src/lists.xml
index 03d0063599..60dbae70c2 100644
--- a/lib/stdlib/doc/src/lists.xml
+++ b/lib/stdlib/doc/src/lists.xml
@@ -25,11 +25,11 @@
     <title>lists</title>
     <prepared>Robert Virding</prepared>
     <docno>1</docno>
-    <date>96-09-28</date>
+    <date>1996-09-28</date>
     <rev>A</rev>
   </header>
   <module>lists</module>
-  <modulesummary>List Processing Functions</modulesummary>
+  <modulesummary>List processing functions.</modulesummary>
   <description>
     <p>This module contains functions for list processing.</p>
 
@@ -44,132 +44,156 @@
     <p>Whenever an <marker
       id="ordering_function"></marker><em>ordering function</em>
       <c>F</c> is expected as argument, it is assumed that the
-      following properties hold of <c>F</c> for all x, y and z:</p>
+      following properties hold of <c>F</c> for all x, y, and z:</p>
+
     <list type="bulleted">
-      <item><p>if x <c>F</c> y and y <c>F</c> x then x = y (<c>F</c>
-        is antisymmetric);</p>
+      <item><p>If x <c>F</c> y and y <c>F</c> x, then x = y (<c>F</c>
+        is antisymmetric).</p>
       </item>
-      <item><p>if x <c>F</c> y and y <c>F</c> z then x <c>F</c> z
-        (<c>F</c> is transitive);</p>
+      <item><p>If x <c>F</c> y and y <c>F</c> z, then x <c>F</c> z
+        (<c>F</c> is transitive).</p>
       </item>
       <item><p>x <c>F</c> y or y <c>F</c> x (<c>F</c> is total).</p>
       </item>
     </list>
-    <p>An example of a typical ordering function is less than or equal
-      to, <c>=&lt;/2</c>.</p>
 
+    <p>An example of a typical ordering function is less than or equal
+      to: <c>=&lt;/2</c>.</p>
   </description>
+
   <funcs>
     <func>
       <name name="all" arity="2"/>
-      <fsummary>Return true if all elements in the list satisfy<c>Pred</c></fsummary>
+      <fsummary>Return <c>true</c> if all elements in a list satisfy
+        <c>Pred</c>.</fsummary>
       <desc>
-        <p>Returns <c>true</c> if <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns
-          <c>true</c> for all elements <c><anno>Elem</anno></c> in <c><anno>List</anno></c>,
-          otherwise <c>false</c>.</p>
+        <p>Returns <c>true</c> if <c><anno>Pred</anno>(<anno>Elem</anno>)</c>
+          returns <c>true</c> for all elements <c><anno>Elem</anno></c> in
+          <c><anno>List</anno></c>, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="any" arity="2"/>
-      <fsummary>Return true if any of the elements in the list satisfies<c>Pred</c></fsummary>
+      <fsummary>Return <c>true</c> if any of the elements in a list
+        satisfies <c>Pred</c>.</fsummary>
       <desc>
-        <p>Returns <c>true</c> if <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns
-          <c>true</c> for at least one element <c><anno>Elem</anno></c> in
-          <c><anno>List</anno></c>.</p>
+        <p>Returns <c>true</c> if <c><anno>Pred</anno>(<anno>Elem</anno>)</c>
+          returns <c>true</c> for at least one element <c><anno>Elem</anno></c>
+          in <c><anno>List</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="append" arity="1"/>
-      <fsummary>Append a list of lists</fsummary>
+      <fsummary>Append a list of lists.</fsummary>
       <desc>
-        <p>Returns a list in which all the sub-lists of
-          <c><anno>ListOfLists</anno></c> have been appended. For example:</p>
+        <p>Returns a list in which all the sublists of
+          <c><anno>ListOfLists</anno></c> have been appended.</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:append([[1, 2, 3], [a, b], [4, 5, 6]]).</input>
 [1,2,3,a,b,4,5,6]</pre>
       </desc>
     </func>
+
     <func>
       <name name="append" arity="2"/>
-      <fsummary>Append two lists</fsummary>
+      <fsummary>Append two lists.</fsummary>
       <desc>
-        <p>Returns a new list <c><anno>List3</anno></c> which is made from
+        <p>Returns a new list <c><anno>List3</anno></c>, which is made from
           the elements of <c><anno>List1</anno></c> followed by the elements of
-          <c><anno>List2</anno></c>. For example:</p>
+          <c><anno>List2</anno></c>.</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:append("abc", "def").</input>
 "abcdef"</pre>
         <p><c>lists:append(A, B)</c> is equivalent to <c>A ++ B</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="concat" arity="1"/>
-      <fsummary>Concatenate a list of atoms</fsummary>
+      <fsummary>Concatenate a list of atoms.</fsummary>
       <desc>
-        <p>Concatenates the text representation of the elements
-          of <c><anno>Things</anno></c>. The elements of <c><anno>Things</anno></c> can be atoms,
-          integers, floats or strings.</p>
+        <p>Concatenates the text representation of the elements of
+          <c><anno>Things</anno></c>. The elements of <c><anno>Things</anno></c>
+          can be atoms, integers, floats, or strings.</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:concat([doc, '/', file, '.', 3]).</input>
 "doc/file.3"</pre>
       </desc>
     </func>
+
     <func>
       <name name="delete" arity="2"/>
-      <fsummary>Delete an element from a list</fsummary>
+      <fsummary>Delete an element from a list.</fsummary>
       <desc>
         <p>Returns a copy of <c><anno>List1</anno></c> where the first element
           matching <c><anno>Elem</anno></c> is deleted, if there is such an
           element.</p>
       </desc>
     </func>
+
     <func>
       <name name="droplast" arity="1"/>
-      <fsummary>Drop the last element of a list</fsummary>
+      <fsummary>Drop the last element of a list.</fsummary>
       <desc>
-        <p>Drops the last element of a <c><anno>List</anno></c>. The list should
-           be non-empty, otherwise the function will crash with a <c>function_clause</c></p>
+        <p>Drops the last element of a <c><anno>List</anno></c>. The list is to
+           be non-empty, otherwise the function crashes with a
+           <c>function_clause</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="dropwhile" arity="2"/>
-      <fsummary>Drop elements from a list while a predicate is true</fsummary>
+      <fsummary>Drop elements from a list while a predicate is <c>true</c>.
+      </fsummary>
       <desc>
-        <p>Drops elements <c><anno>Elem</anno></c> from <c><anno>List1</anno></c> while
-          <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c> and returns
-          the remaining list.</p>
+        <p>Drops elements <c><anno>Elem</anno></c> from
+          <c><anno>List1</anno></c> while
+          <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c> and
+          returns the remaining list.</p>
       </desc>
     </func>
+
     <func>
       <name name="duplicate" arity="2"/>
-      <fsummary>Make N copies of element</fsummary>
+      <fsummary>Make <c>N</c> copies of element.</fsummary>
       <desc>
-        <p>Returns a list which contains <c><anno>N</anno></c> copies of the term
-          <c><anno>Elem</anno></c>. For example:</p>
+        <p>Returns a list containing <c><anno>N</anno></c> copies of term
+          <c><anno>Elem</anno></c>.</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:duplicate(5, xx).</input>
 [xx,xx,xx,xx,xx]</pre>
       </desc>
     </func>
+
     <func>
       <name name="filter" arity="2"/>
-      <fsummary>Choose elements which satisfy a predicate</fsummary>
+      <fsummary>Select elements that satisfy a predicate.</fsummary>
       <desc>
-        <p><c><anno>List2</anno></c> is a list of all elements <c><anno>Elem</anno></c> in
-          <c><anno>List1</anno></c> for which <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns
-          <c>true</c>.</p>
+        <p><c><anno>List2</anno></c> is a list of all elements
+          <c><anno>Elem</anno></c> in <c><anno>List1</anno></c> for which
+          <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="filtermap" arity="2"/>
-      <fsummary>Filter and map elements which satisfy a function</fsummary>
-      <desc>
-        <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> on successive elements <c>Elem</c>
-          of <c><anno>List1</anno></c>. <c><anno>Fun</anno>/2</c> must return either a boolean
-          or a tuple <c>{true, <anno>Value</anno>}</c>. The function returns the list of elements
-          for which <c><anno>Fun</anno></c> returns a new value, where a value of <c>true</c>
-          is synonymous with <c>{true, <anno>Elem</anno>}</c>.</p>
-        <p>That is, <c>filtermap</c> behaves as if it had been defined as follows:</p>
+      <fsummary>Filter and map elements that satisfy a function.</fsummary>
+      <desc>
+        <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> on successive
+          elements <c>Elem</c> of <c><anno>List1</anno></c>.
+          <c><anno>Fun</anno>/2</c> must return either a Boolean or a tuple
+          <c>{true, <anno>Value</anno>}</c>. The function returns the list of
+          elements for which <c><anno>Fun</anno></c> returns a new value, where
+          a value of <c>true</c> is synonymous with
+          <c>{true, <anno>Elem</anno>}</c>.</p>
+        <p>That is, <c>filtermap</c> behaves as if it had been defined as
+          follows:</p>
         <code type="none">
 filtermap(Fun, List1) ->
     lists:foldr(fun(Elem, Acc) ->
@@ -179,26 +203,29 @@ filtermap(Fun, List1) ->
                            {true,Value} -> [Value|Acc]
                        end
                 end, [], List1).</code>
-        <p>Example:</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:filtermap(fun(X) -> case X rem 2 of 0 -> {true, X div 2}; _ -> false end end, [1,2,3,4,5]).</input>
 [1,2]</pre>
       </desc>
     </func>
+
     <func>
       <name name="flatlength" arity="1"/>
-      <fsummary>Length of flattened deep list</fsummary>
+      <fsummary>Length of flattened deep list.</fsummary>
       <desc>
-        <p>Equivalent to <c>length(flatten(<anno>DeepList</anno>))</c>, but more
-          efficient.</p>
+        <p>Equivalent to <c>length(flatten(<anno>DeepList</anno>))</c>, but
+          more efficient.</p>
       </desc>
     </func>
+
     <func>
       <name name="flatmap" arity="2"/>
-      <fsummary>Map and flatten in one pass</fsummary>
+      <fsummary>Map and flatten in one pass.</fsummary>
       <desc>
-        <p>Takes a function from <c><anno>A</anno></c>s to lists of <c><anno>B</anno></c>s, and a
-          list of <c><anno>A</anno></c>s (<c><anno>List1</anno></c>) and produces a list of
+        <p>Takes a function from <c><anno>A</anno></c>s to lists of
+          <c><anno>B</anno></c>s, and a list of <c><anno>A</anno></c>s
+          (<c><anno>List1</anno></c>) and produces a list of
           <c><anno>B</anno></c>s by applying the function to every element in
           <c><anno>List1</anno></c> and appending the resulting lists.</p>
         <p>That is, <c>flatmap</c> behaves as if it had been defined as
@@ -206,37 +233,42 @@ filtermap(Fun, List1) ->
         <code type="none">
 flatmap(Fun, List1) ->
     append(map(Fun, List1)).</code>
-        <p>Example:</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:flatmap(fun(X)->[X,X] end, [a,b,c]).</input>
 [a,a,b,b,c,c]</pre>
       </desc>
     </func>
+
     <func>
       <name name="flatten" arity="1"/>
-      <fsummary>Flatten a deep list</fsummary>
+      <fsummary>Flatten a deep list.</fsummary>
       <desc>
         <p>Returns a flattened version of <c><anno>DeepList</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="flatten" arity="2"/>
-      <fsummary>Flatten a deep list</fsummary>
+      <fsummary>Flatten a deep list.</fsummary>
       <desc>
-        <p>Returns a flattened version of <c><anno>DeepList</anno></c> with the tail
+        <p>Returns a flattened version of <c><anno>DeepList</anno></c> with tail
           <c><anno>Tail</anno></c> appended.</p>
       </desc>
     </func>
+
     <func>
       <name name="foldl" arity="3"/>
-      <fsummary>Fold a function over a list</fsummary>
-      <desc>
-        <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>, <anno>AccIn</anno>)</c> on successive elements <c>A</c>
-          of <c><anno>List</anno></c>, starting with <c><anno>AccIn</anno> == <anno>Acc0</anno></c>.
-          <c><anno>Fun</anno>/2</c> must return a new accumulator which is passed to
-          the next call. The function returns the final value of
-          the accumulator. <c><anno>Acc0</anno></c> is returned if the list is empty.
-          For example:</p>
+      <fsummary>Fold a function over a list.</fsummary>
+      <desc>
+        <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>, <anno>AccIn</anno>)</c>
+          on successive elements <c>A</c> of <c><anno>List</anno></c>, starting
+          with <c><anno>AccIn</anno> == <anno>Acc0</anno></c>.
+          <c><anno>Fun</anno>/2</c> must return a new accumulator, which is
+          passed to the next call. The function returns the final value of
+          the accumulator. <c><anno>Acc0</anno></c> is returned if the list is
+          empty.</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:foldl(fun(X, Sum) -> X + Sum end, 0, [1,2,3,4,5]).</input>
 15
@@ -244,12 +276,14 @@ flatmap(Fun, List1) ->
 120</pre>
       </desc>
     </func>
+
     <func>
       <name name="foldr" arity="3"/>
-      <fsummary>Fold a function over a list</fsummary>
+      <fsummary>Fold a function over a list.</fsummary>
       <desc>
-        <p>Like <c>foldl/3</c>, but the list is traversed from right to
-          left. For example:</p>
+        <p>Like <seealso marker="#foldl/3"><c>foldl/3</c></seealso>, but the
+          list is traversed from right to left.</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>P = fun(A, AccIn) -> io:format("~p ", [A]), AccIn end.</input>
 #Fun&lt;erl_eval.12.2225172&gt;
@@ -257,10 +291,11 @@ flatmap(Fun, List1) ->
 1 2 3 void
 > <input>lists:foldr(P, void, [1,2,3]).</input>
 3 2 1 void</pre>
-        <p><c>foldl/3</c> is tail recursive and would usually be
-          preferred to <c>foldr/3</c>.</p>
+        <p><c>foldl/3</c> is tail recursive and is usually preferred to
+          <c>foldr/3</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="join" arity="2"/>
       <fsummary>Insert an element between elements in a list</fsummary>
@@ -278,45 +313,52 @@ flatmap(Fun, List1) ->
     </func>
     <func>
       <name name="foreach" arity="2"/>
-      <fsummary>Apply a function to each element of a list</fsummary>
+      <fsummary>Apply a function to each element of a list.</fsummary>
       <desc>
-        <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> for each element <c><anno>Elem</anno></c> in
-          <c><anno>List</anno></c>. This function is used for its side effects and
+        <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> for each element
+          <c><anno>Elem</anno></c> in <c><anno>List</anno></c>. This function
+          is used for its side effects and
           the evaluation order is defined to be the same as the order
           of the elements in the list.</p>
       </desc>
     </func>
+
     <func>
       <name name="keydelete" arity="3"/>
-      <fsummary>Delete an element from a list of tuples</fsummary>
+      <fsummary>Delete an element from a list of tuples.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
         <p>Returns a copy of <c><anno>TupleList1</anno></c> where the first
-          occurrence of a tuple whose <c><anno>N</anno></c>th element compares equal to
+          occurrence of a tuple whose <c><anno>N</anno></c>th element compares
+          equal to
           <c><anno>Key</anno></c> is deleted, if there is such a tuple.</p>
       </desc>
     </func>
+
     <func>
       <name name="keyfind" arity="3"/>
-      <fsummary>Search for an element in a list of tuples</fsummary>
+      <fsummary>Search for an element in a list of tuples.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
         <p>Searches the list of tuples <c><anno>TupleList</anno></c> for a
-          tuple whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>.
+          tuple whose <c><anno>N</anno></c>th element compares equal to
+          <c><anno>Key</anno></c>.
           Returns <c><anno>Tuple</anno></c> if such a tuple is found,
           otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="keymap" arity="3"/>
-      <fsummary>Map a function over a list of tuples</fsummary>
+      <fsummary>Map a function over a list of tuples.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
         <p>Returns a list of tuples where, for each tuple in
-          <c><anno>TupleList1</anno></c>, the <c><anno>N</anno></c>th element <c><anno>Term1</anno></c> of the tuple
+          <c><anno>TupleList1</anno></c>, the <c><anno>N</anno></c>th element
+          <c><anno>Term1</anno></c> of the tuple
           has been replaced with the result of calling
           <c><anno>Fun</anno>(<anno>Term1</anno>)</c>.</p>
-        <p>Examples:</p>
+        <p><em>Examples:</em></p>
         <pre>
 > <input>Fun = fun(Atom) -> atom_to_list(Atom) end.</input>
 #Fun&lt;erl_eval.6.10732646&gt;
@@ -324,33 +366,37 @@ flatmap(Fun, List1) ->
 [{name,"jane",22},{name,"lizzie",20},{name,"lydia",15}]</pre>
       </desc>
     </func>
+
     <func>
       <name name="keymember" arity="3"/>
-      <fsummary>Test for membership of a list of tuples</fsummary>
+      <fsummary>Test for membership of a list of tuples.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
-        <p>Returns <c>true</c> if there is a tuple in <c><anno>TupleList</anno></c>
-          whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>, otherwise
-          <c>false</c>.</p>
+        <p>Returns <c>true</c> if there is a tuple in
+          <c><anno>TupleList</anno></c> whose <c><anno>N</anno></c>th element
+          compares equal to <c><anno>Key</anno></c>, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="keymerge" arity="3"/>
-      <fsummary>Merge two key-sorted lists of tuples</fsummary>
+      <fsummary>Merge two key-sorted lists of tuples.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
-        <p>Returns the sorted list formed by merging <c><anno>TupleList1</anno></c>
-          and <c><anno>TupleList2</anno></c>. The merge is performed on
-          the <c><anno>N</anno></c>th element of each tuple. Both <c><anno>TupleList1</anno></c> and
-          <c><anno>TupleList2</anno></c> must be key-sorted prior to evaluating this
-          function. When two tuples compare equal, the tuple from
+        <p>Returns the sorted list formed by merging
+          <c><anno>TupleList1</anno></c> and <c><anno>TupleList2</anno></c>.
+          The merge is performed on the <c><anno>N</anno></c>th element of each
+          tuple. Both <c><anno>TupleList1</anno></c> and
+          <c><anno>TupleList2</anno></c> must be key-sorted before evaluating
+          this function. When two tuples compare equal, the tuple from
           <c><anno>TupleList1</anno></c> is picked before the tuple from
           <c><anno>TupleList2</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="keyreplace" arity="4"/>
-      <fsummary>Replace an element in a list of tuples</fsummary>
+      <fsummary>Replace an element in a list of tuples.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
         <p>Returns a copy of <c><anno>TupleList1</anno></c> where the first
@@ -359,193 +405,226 @@ flatmap(Fun, List1) ->
           <c><anno>NewTuple</anno></c>, if there is such a tuple <c>T</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="keysearch" arity="3"/>
-      <fsummary>Search for an element in a list of tuples</fsummary>
+      <fsummary>Search for an element in a list of tuples.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
         <p>Searches the list of tuples <c><anno>TupleList</anno></c> for a
-          tuple whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>.
+          tuple whose <c><anno>N</anno></c>th element compares equal to
+          <c><anno>Key</anno></c>.
           Returns <c>{value, <anno>Tuple</anno>}</c> if such a tuple is found,
           otherwise <c>false</c>.</p>
-      <note><p>This function is retained for backward compatibility.
-      The function <c>lists:keyfind/3</c> (introduced in R13A)
-      is in most cases more convenient.</p></note>
+      <note>
+        <p>This function is retained for backward compatibility. Function
+          <seealso marker="#keyfind/3"><c>keyfind/3</c></seealso>
+          is usually more convenient.</p>
+      </note>
       </desc>
     </func>
+
     <func>
       <name name="keysort" arity="2"/>
-      <fsummary>Sort a list of tuples</fsummary>
+      <fsummary>Sort a list of tuples.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
-        <p>Returns a list containing the sorted elements of the list
-          <c><anno>TupleList1</anno></c>. Sorting is performed on the <c><anno>N</anno></c>th
-          element of the tuples. The sort is stable.</p>
+        <p>Returns a list containing the sorted elements of list
+          <c><anno>TupleList1</anno></c>. Sorting is performed on the
+          <c><anno>N</anno></c>th element of the tuples. The sort is stable.</p>
       </desc>
     </func>
+
     <func>
       <name name="keystore" arity="4"/>
-      <fsummary>Store an element in a list of tuples</fsummary>
+      <fsummary>Store an element in a list of tuples.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
         <p>Returns a copy of <c><anno>TupleList1</anno></c> where the first
           occurrence of a tuple <c>T</c> whose <c><anno>N</anno></c>th element
           compares equal to <c><anno>Key</anno></c> is replaced with
-          <c><anno>NewTuple</anno></c>, if there is such a tuple <c>T</c>. If there
-          is no such tuple <c>T</c> a copy of <c><anno>TupleList1</anno></c> where
+          <c><anno>NewTuple</anno></c>, if there is such a tuple <c>T</c>.
+          If there is no such tuple <c>T</c>, a copy of
+          <c><anno>TupleList1</anno></c> where
           [<c><anno>NewTuple</anno></c>] has been appended to the end is
           returned.</p>
       </desc>
     </func>
+
     <func>
       <name name="keytake" arity="3"/>
-      <fsummary>Extract an element from a list of tuples</fsummary>
+      <fsummary>Extract an element from a list of tuples.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
-        <p>Searches the list of tuples <c><anno>TupleList1</anno></c> for a tuple
-          whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>.
-          Returns <c>{value, <anno>Tuple</anno>, <anno>TupleList2</anno>}</c> if such a tuple is
-          found, otherwise <c>false</c>. <c><anno>TupleList2</anno></c> is a copy
+        <p>Searches the list of tuples <c><anno>TupleList1</anno></c> for a
+          tuple whose <c><anno>N</anno></c>th element compares equal to
+          <c><anno>Key</anno></c>. Returns <c>{value, <anno>Tuple</anno>,
+          <anno>TupleList2</anno>}</c> if such a tuple is found, otherwise
+          <c>false</c>. <c><anno>TupleList2</anno></c> is a copy
           of <c><anno>TupleList1</anno></c> where the first occurrence of
           <c><anno>Tuple</anno></c> has been removed.</p>
       </desc>
     </func>
+
     <func>
       <name name="last" arity="1"/>
-      <fsummary>Return last element in a list</fsummary>
+      <fsummary>Return last element in a list.</fsummary>
       <desc>
         <p>Returns the last element in <c><anno>List</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="map" arity="2"/>
-      <fsummary>Map a function over a list</fsummary>
+      <fsummary>Map a function over a list.</fsummary>
       <desc>
-        <p>Takes a function from <c><anno>A</anno></c>s to <c><anno>B</anno></c>s, and a list of
-          <c><anno>A</anno></c>s and produces a list of <c><anno>B</anno></c>s by applying
+        <p>Takes a function from <c><anno>A</anno></c>s to
+          <c><anno>B</anno></c>s, and a list of <c><anno>A</anno></c>s and
+          produces a list of <c><anno>B</anno></c>s by applying
           the function to every element in the list. This function is
-          used to obtain the return values. The evaluation order is
-          implementation dependent.</p>
+          used to obtain the return values. The evaluation order depends on
+          the implementation.</p>
       </desc>
     </func>
+
     <func>
       <name name="mapfoldl" arity="3"/>
-      <fsummary>Map and fold in one pass</fsummary>
+      <fsummary>Map and fold in one pass.</fsummary>
       <desc>
-        <p><c>mapfoldl</c> combines the operations of <c>map/2</c> and
-          <c>foldl/3</c> into one pass. An example, summing
-          the elements in a list and double them at the same time:</p>
+        <p>Combines the operations of
+          <seealso marker="#map/2"><c>map/2</c></seealso> and 
+          <seealso marker="#foldl/3"><c>foldl/3</c></seealso> into one pass.</p>
+        <p><em>Example:</em></p>
+        <p>Summing the elements in a list and double them at the same time:</p>
         <pre>
 > <input>lists:mapfoldl(fun(X, Sum) -> {2*X, X+Sum} end,</input>
 <input>0, [1,2,3,4,5]).</input>
 {[2,4,6,8,10],15}</pre>
       </desc>
     </func>
+
     <func>
       <name name="mapfoldr" arity="3"/>
-      <fsummary>Map and fold in one pass</fsummary>
+      <fsummary>Map and fold in one pass.</fsummary>
       <desc>
-        <p><c>mapfoldr</c> combines the operations of <c>map/2</c> and
-          <c>foldr/3</c> into one pass.</p>
+        <p>Combines the operations of
+          <seealso marker="#map/2"><c>map/2</c></seealso> and 
+          <seealso marker="#foldr/3"><c>foldr/3</c></seealso> into one pass.</p>
       </desc>
     </func>
+
     <func>
       <name name="max" arity="1"/>
-      <fsummary>Return maximum element of a list</fsummary>
+      <fsummary>Return maximum element of a list.</fsummary>
       <desc>
         <p>Returns the first element of <c><anno>List</anno></c> that compares
           greater than or equal to all other elements of
           <c><anno>List</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="member" arity="2"/>
-      <fsummary>Test for membership of a list</fsummary>
+      <fsummary>Test for membership of a list.</fsummary>
       <desc>
-        <p>Returns <c>true</c> if <c><anno>Elem</anno></c> matches some element of
-          <c><anno>List</anno></c>, otherwise <c>false</c>.</p>
+        <p>Returns <c>true</c> if <c><anno>Elem</anno></c> matches some element
+          of <c><anno>List</anno></c>, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="merge" arity="1"/>
-      <fsummary>Merge a list of sorted lists</fsummary>
+      <fsummary>Merge a list of sorted lists.</fsummary>
       <desc>
-        <p>Returns the sorted list formed by merging all the sub-lists
-          of <c><anno>ListOfLists</anno></c>. All sub-lists must be sorted prior to
+        <p>Returns the sorted list formed by merging all the sublists of
+          <c><anno>ListOfLists</anno></c>. All sublists must be sorted before
           evaluating this function. When two elements compare equal,
-          the element from the sub-list with the lowest position in
-          <c><anno>ListOfLists</anno></c> is picked before the other element.</p>
+          the element from the sublist with the lowest position in
+          <c><anno>ListOfLists</anno></c> is picked before the other
+          element.</p>
       </desc>
     </func>
+
     <func>
       <name name="merge" arity="2"/>
-      <fsummary>Merge two sorted lists</fsummary>
+      <fsummary>Merge two sorted lists.</fsummary>
       <desc>
-        <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> and
-          <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and <c><anno>List2</anno></c> must be
-          sorted prior to evaluating this function. When two elements
+        <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>
+          and <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and
+          <c><anno>List2</anno></c> must be
+          sorted before evaluating this function. When two elements
           compare equal, the element from <c><anno>List1</anno></c> is picked
           before the element from <c><anno>List2</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="merge" arity="3"/>
-      <fsummary>Merge two sorted list</fsummary>
+      <fsummary>Merge two sorted list.</fsummary>
       <desc>
-        <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> and
-          <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and <c><anno>List2</anno></c> must be
-          sorted according to the <seealso
+        <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>
+          and <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and
+          <c><anno>List2</anno></c> must be sorted according to the <seealso
           marker="#ordering_function">ordering function</seealso>
-          <c><anno>Fun</anno></c> prior to evaluating this function. <c><anno>Fun</anno>(<anno>A</anno>,
-          <anno>B</anno>)</c> should return <c>true</c> if <c><anno>A</anno></c> compares less
-          than or equal to <c><anno>B</anno></c> in the ordering, <c>false</c>
-          otherwise. When two elements compare equal, the element from
+          <c><anno>Fun</anno></c> before evaluating this function.
+          <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> is to return
+          <c>true</c> if <c><anno>A</anno></c> compares less
+          than or equal to <c><anno>B</anno></c> in the ordering, otherwise
+          <c>false</c>. When two elements compare equal, the element from
           <c><anno>List1</anno></c> is picked before the element from
           <c><anno>List2</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="merge3" arity="3"/>
-      <fsummary>Merge three sorted lists</fsummary>
+      <fsummary>Merge three sorted lists.</fsummary>
       <desc>
         <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>,
-          <c><anno>List2</anno></c> and <c><anno>List3</anno></c>. All of <c><anno>List1</anno></c>,
-          <c><anno>List2</anno></c> and <c><anno>List3</anno></c> must be sorted prior to
-          evaluating this function. When two elements compare equal,
-          the element from <c><anno>List1</anno></c>, if there is such an element,
+          <c><anno>List2</anno></c>, and <c><anno>List3</anno></c>. All of
+          <c><anno>List1</anno></c>, <c><anno>List2</anno></c>, and
+          <c><anno>List3</anno></c> must be sorted before evaluating this
+          function. When two elements compare equal, the element from
+          <c><anno>List1</anno></c>, if there is such an element,
           is picked before the other element, otherwise the element
           from <c><anno>List2</anno></c> is picked before the element from
           <c><anno>List3</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="min" arity="1"/>
-      <fsummary>Return minimum element of a list</fsummary>
+      <fsummary>Return minimum element of a list.</fsummary>
       <desc>
         <p>Returns the first element of <c><anno>List</anno></c> that compares
           less than or equal to all other elements of
           <c><anno>List</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="nth" arity="2"/>
-      <fsummary>Return the Nth element of a list</fsummary>
+      <fsummary>Return the <c>N</c>th element of a list.</fsummary>
       <type_desc variable="N">1..length(<anno>List</anno>)</type_desc>
       <desc>
-        <p>Returns the <c><anno>N</anno></c>th element of <c><anno>List</anno></c>. For example:</p>
+        <p>Returns the <c><anno>N</anno></c>th element of
+          <c><anno>List</anno></c>.</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:nth(3, [a, b, c, d, e]).</input>
 c</pre>
       </desc>
     </func>
+
     <func>
       <name name="nthtail" arity="2"/>
-      <fsummary>Return the Nth tail of a list</fsummary>
+      <fsummary>Return the <c>N</c>th tail of a list.</fsummary>
       <type_desc variable="N">0..length(<anno>List</anno>)</type_desc>
       <desc>
-        <p>Returns the <c><anno>N</anno></c>th tail of <c><anno>List</anno></c>, that is, the sublist of
-          <c><anno>List</anno></c> starting at <c><anno>N</anno>+1</c> and continuing up to
-          the end of the list. For example:</p>
+        <p>Returns the <c><anno>N</anno></c>th tail of <c><anno>List</anno></c>,
+          that is, the sublist of <c><anno>List</anno></c> starting at
+          <c><anno>N</anno>+1</c> and continuing up to the end of the list.</p>
+        <p><em>Example</em></p>
         <pre>
 > <input>lists:nthtail(3, [a, b, c, d, e]).</input>
 [d,e]
@@ -557,70 +636,91 @@ c</pre>
 []</pre>
       </desc>
     </func>
+
     <func>
       <name name="partition" arity="2"/>
-      <fsummary>Partition a list into two lists based on a predicate</fsummary>
-      <desc>
-        <p>Partitions <c><anno>List</anno></c> into two lists, where the first list
-          contains all elements for which <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns
-          <c>true</c>, and the second list contains all elements for
-          which <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>false</c>.</p>
-        <p>Examples:</p>
+      <fsummary>Partition a list into two lists based on a predicate.</fsummary>
+      <desc>
+        <p>Partitions <c><anno>List</anno></c> into two lists, where the first
+          list contains all elements for which
+          <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c>,
+          and the second list contains all elements for which
+          <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>false</c>.</p>
+        <p><em>Examples:</em></p>
         <pre>
 > <input>lists:partition(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).</input>
 {[1,3,5,7],[2,4,6]}
 > <input>lists:partition(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).</input>
 {[a,b,c,d,e],[1,2,3,4]}</pre>
-        <p>See also <c>splitwith/2</c> for a different way to partition
-          a list.</p>
+        <p>For a different way to partition a list, see
+          <seealso marker="#splitwith/2"><c>splitwith/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
       <name name="prefix" arity="2"/>
-      <fsummary>Test for list prefix</fsummary>
+      <fsummary>Test for list prefix.</fsummary>
       <desc>
         <p>Returns <c>true</c> if <c><anno>List1</anno></c> is a prefix of
           <c><anno>List2</anno></c>, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="reverse" arity="1"/>
-      <fsummary>Reverse a list</fsummary>
+      <fsummary>Reverse a list.</fsummary>
       <desc>
         <p>Returns a list with the elements in <c><anno>List1</anno></c>
           in reverse order.</p>
       </desc>
     </func>
+
     <func>
       <name name="reverse" arity="2"/>
-      <fsummary>Reverse a list appending a tail</fsummary>
+      <fsummary>Reverse a list appending a tail.</fsummary>
       <desc>
         <p>Returns a list with the elements in <c><anno>List1</anno></c>
-          in reverse order, with the tail <c><anno>Tail</anno></c> appended. For
-          example:</p>
+          in reverse order, with tail <c><anno>Tail</anno></c> appended.</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:reverse([1, 2, 3, 4], [a, b, c]).</input>
 [4,3,2,1,a,b,c]</pre>
       </desc>
     </func>
+
     <func>
       <name name="seq" arity="2"/>
       <name name="seq" arity="3"/>
-      <fsummary>Generate a sequence of integers</fsummary>
+      <fsummary>Generate a sequence of integers.</fsummary>
       <desc>
-        <p>Returns a sequence of integers which starts with <c><anno>From</anno></c>
-          and contains the successive results of adding <c><anno>Incr</anno></c> to
-          the previous element, until <c><anno>To</anno></c> has been reached or
-          passed (in the latter case, <c><anno>To</anno></c> is not an element of
+        <p>Returns a sequence of integers that starts with
+          <c><anno>From</anno></c> and contains the successive results of
+          adding <c><anno>Incr</anno></c> to the previous element, until
+          <c><anno>To</anno></c> is reached or passed (in the latter case,
+          <c><anno>To</anno></c> is not an element of
           the sequence). <c><anno>Incr</anno></c> defaults to 1.</p>
-        <p>Failure: If <c><anno>To</anno>&lt;<anno>From</anno>-<anno>Incr</anno></c> and <c><anno>Incr</anno></c>
-          is positive, or if <c><anno>To</anno>><anno>From</anno>-<anno>Incr</anno></c> and <c><anno>Incr</anno></c> is
-          negative, or if <c><anno>Incr</anno>==0</c> and <c><anno>From</anno>/=<anno>To</anno></c>.</p>
+        <p>Failures:</p>
+        <list type="bulleted">
+          <item>
+            <p>If <c><anno>To</anno> &lt;
+	      <anno>From</anno> - <anno>Incr</anno></c>
+              and <c><anno>Incr</anno> &gt; 0</c>.</p>
+          </item>
+          <item>
+            <p>If <c><anno>To</anno> &gt;
+              <anno>From</anno> - <anno>Incr</anno></c> and
+              <c><anno>Incr</anno> &lt; 0</c>.</p>
+          </item>
+          <item>
+            <p>If <c><anno>Incr</anno> =:= 0</c> and
+              <c><anno>From</anno> =/= <anno>To</anno></c>.</p>
+          </item>
+        </list>
         <p>The following equalities hold for all sequences:</p>
         <code type="none">
-length(lists:seq(From, To)) == To-From+1
-length(lists:seq(From, To, Incr)) == (To-From+Incr) div Incr</code>
-        <p>Examples:</p>
+length(lists:seq(From, To)) =:= To - From + 1
+length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr</code>
+        <p><em>Examples:</em></p>
         <pre>
 > <input>lists:seq(1, 10).</input>
 [1,2,3,4,5,6,7,8,9,10]
@@ -634,74 +734,87 @@ length(lists:seq(From, To, Incr)) == (To-From+Incr) div Incr</code>
 [1]</pre>
       </desc>
     </func>
+
     <func>
       <name name="sort" arity="1"/>
-      <fsummary>Sort a list</fsummary>
+      <fsummary>Sort a list.</fsummary>
       <desc>
         <p>Returns a list containing the sorted elements of
           <c><anno>List1</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="sort" arity="2"/>
-      <fsummary>Sort a list</fsummary>
+      <fsummary>Sort a list.</fsummary>
       <desc>
         <p>Returns a list containing the sorted elements of
           <c><anno>List1</anno></c>, according to the <seealso
           marker="#ordering_function">ordering function</seealso>
-          <c><anno>Fun</anno></c>. <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> should return <c>true</c> if
-          <c><anno>A</anno></c> compares less than or equal to <c><anno>B</anno></c> in the
-          ordering, <c>false</c> otherwise.</p>
+          <c><anno>Fun</anno></c>. <c><anno>Fun</anno>(<anno>A</anno>,
+          <anno>B</anno>)</c> is to return <c>true</c> if <c><anno>A</anno></c>
+          compares less than or equal to <c><anno>B</anno></c> in the
+          ordering, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="split" arity="2"/>
-      <fsummary>Split a list into two lists</fsummary>
+      <fsummary>Split a list into two lists.</fsummary>
       <type_desc variable="N">0..length(<anno>List1</anno>)</type_desc>
       <desc>
-        <p>Splits <c><anno>List1</anno></c> into <c><anno>List2</anno></c> and <c><anno>List3</anno></c>.
-          <c><anno>List2</anno></c> contains the first <c><anno>N</anno></c> elements and
-          <c><anno>List3</anno></c> the rest of the elements (the <c><anno>N</anno></c>th tail).</p>
+        <p>Splits <c><anno>List1</anno></c> into <c><anno>List2</anno></c> and
+          <c><anno>List3</anno></c>. <c><anno>List2</anno></c> contains the
+          first <c><anno>N</anno></c> elements and <c><anno>List3</anno></c>
+          the remaining elements (the <c><anno>N</anno></c>th tail).</p>
       </desc>
     </func>
+
     <func>
       <name name="splitwith" arity="2"/>
-      <fsummary>Split a list into two lists based on a predicate</fsummary>
+      <fsummary>Split a list into two lists based on a predicate.</fsummary>
       <desc>
         <p>Partitions <c><anno>List</anno></c> into two lists according to
-          <c><anno>Pred</anno></c>. <c>splitwith/2</c> behaves as if it is defined
-          as follows:</p>
+          <c><anno>Pred</anno></c>. <c>splitwith/2</c> behaves as if it is
+          defined as follows:</p>
         <code type="none">
 splitwith(Pred, List) ->
     {takewhile(Pred, List), dropwhile(Pred, List)}.</code>
-        <p>Examples:</p>
+        <p><em>Examples:</em></p>
         <pre>
 > <input>lists:splitwith(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).</input>
 {[1],[2,3,4,5,6,7]}
 > <input>lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).</input>
 {[a,b],[1,c,d,2,3,4,e]}</pre>
-        <p>See also <c>partition/2</c> for a different way to partition
-          a list.</p>
+        <p>For a different way to partition a list, see 
+          <seealso marker="#partition/2"><c>partition/2</c></seealso>.</p>
       </desc>
     </func>
+
     <func>
       <name name="sublist" arity="2"/>
-      <fsummary>Return a sub-list of a certain length, starting at the first position</fsummary>
+      <fsummary>Return a sublist of a certain length, starting at the first
+        position.</fsummary>
       <desc>
-        <p>Returns the sub-list of <c><anno>List1</anno></c> starting at position 1
-          and with (max) <c><anno>Len</anno></c> elements. It is not an error for
-          <c><anno>Len</anno></c> to exceed the length of the list, in that case
-          the whole list is returned.</p>
+        <p>Returns the sublist of <c><anno>List1</anno></c> starting at
+          position 1 and with (maximum) <c><anno>Len</anno></c> elements. It is
+          not an error for <c><anno>Len</anno></c> to exceed the length of the
+          list, in that case the whole list is returned.</p>
       </desc>
     </func>
+
     <func>
       <name name="sublist" arity="3"/>
-      <fsummary>Return a sub-list starting at a given position and with a given number of elements</fsummary>
+      <fsummary>Return a sublist starting at a specified position and with a
+        specified number of elements.</fsummary>
       <type_desc variable="Start">1..(length(<anno>List1</anno>)+1)</type_desc>
       <desc>
-        <p>Returns the sub-list of <c><anno>List1</anno></c> starting at <c><anno>Start</anno></c>
-          and with (max) <c><anno>Len</anno></c> elements. It is not an error for
-          <c><anno>Start</anno>+<anno>Len</anno></c> to exceed the length of the list.</p>
+        <p>Returns the sublist of <c><anno>List1</anno></c> starting at
+          <c><anno>Start</anno></c> and with (maximum) <c><anno>Len</anno></c>
+          elements. It is not an error for
+          <c><anno>Start</anno>+<anno>Len</anno></c> to exceed the length of
+          the list.</p>
+        <p><em>Examples:</em></p>
         <pre>
 > <input>lists:sublist([1,2,3,4], 2, 2).</input>
 [2,3]
@@ -711,142 +824,163 @@ splitwith(Pred, List) ->
 []</pre>
       </desc>
     </func>
+
     <func>
       <name name="subtract" arity="2"/>
-      <fsummary>Subtract the element in one list from another list</fsummary>
+      <fsummary>Subtract the element in one list from another list.</fsummary>
       <desc>
-        <p>Returns a new list <c><anno>List3</anno></c> which is a copy of
-          <c><anno>List1</anno></c>, subjected to the following procedure: for each
-          element in <c><anno>List2</anno></c>, its first occurrence in <c><anno>List1</anno></c>
-          is deleted. For example:</p>
+        <p>Returns a new list <c><anno>List3</anno></c> that is a copy of
+          <c><anno>List1</anno></c>, subjected to the following procedure:
+          for each element in <c><anno>List2</anno></c>, its first occurrence
+          in <c><anno>List1</anno></c> is deleted.</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:subtract("123212", "212").</input>
 "312".</pre>
         <p><c>lists:subtract(A, B)</c> is equivalent to <c>A -- B</c>.</p>
-	<warning><p>The complexity of <c>lists:subtract(A, B)</c> is proportional
-	to <c>length(A)*length(B)</c>, meaning that it will be very slow if
-	both <c>A</c> and <c>B</c> are long lists.
-	(Using ordered lists and
-	<seealso marker="ordsets#subtract/2">ordsets:subtract/2</seealso>
-	is a much better choice if both lists are long.)</p></warning>
+        <warning>
+          <p>The complexity of <c>lists:subtract(A, B)</c> is proportional to
+            <c>length(A)*length(B)</c>, meaning that it is very slow if both
+            <c>A</c> and <c>B</c> are long lists. (If both lists are long, it
+            is a much better choice to use ordered lists and
+            <seealso marker="ordsets#subtract/2">
+            <c>ordsets:subtract/2</c></seealso>.</p>
+        </warning>
       </desc>
     </func>
+
     <func>
       <name name="suffix" arity="2"/>
-      <fsummary>Test for list suffix</fsummary>
+      <fsummary>Test for list suffix.</fsummary>
       <desc>
         <p>Returns <c>true</c> if <c><anno>List1</anno></c> is a suffix of
           <c><anno>List2</anno></c>, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="sum" arity="1"/>
-      <fsummary>Return sum of elements in a list</fsummary>
+      <fsummary>Return the sum of elements in a list.</fsummary>
       <desc>
         <p>Returns the sum of the elements in <c><anno>List</anno></c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="takewhile" arity="2"/>
-      <fsummary>Take elements from a list while a predicate is true</fsummary>
+      <fsummary>Take elements from a list while a predicate is <c>true</c>.
+      </fsummary>
       <desc>
-        <p>Takes elements <c><anno>Elem</anno></c> from <c><anno>List1</anno></c> while
-          <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c>, that is,
-          the function returns the longest prefix of the list for which
+        <p>Takes elements <c><anno>Elem</anno></c> from
+          <c><anno>List1</anno></c> while
+          <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c>, that
+          is, the function returns the longest prefix of the list for which
           all elements satisfy the predicate.</p>
       </desc>
     </func>
+
     <func>
       <name name="ukeymerge" arity="3"/>
-      <fsummary>Merge two key-sorted lists of tuples, removing duplicates</fsummary>
+      <fsummary>Merge two key-sorted lists of tuples, removing duplicates.
+      </fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
-        <p>Returns the sorted list formed by merging <c><anno>TupleList1</anno></c>
-          and <c><anno>TupleList2</anno></c>. The merge is performed on the
-          <c><anno>N</anno></c>th element of each tuple. Both <c><anno>TupleList1</anno></c> and
-          <c><anno>TupleList2</anno></c> must be key-sorted without duplicates
-          prior to evaluating this function. When two tuples compare
-          equal, the tuple from <c><anno>TupleList1</anno></c> is picked and the
-          one from <c><anno>TupleList2</anno></c> deleted.</p>
+        <p>Returns the sorted list formed by merging
+          <c><anno>TupleList1</anno></c> and
+          <c><anno>TupleList2</anno></c>. The merge is performed on the
+          <c><anno>N</anno></c>th element of each tuple. Both
+          <c><anno>TupleList1</anno></c> and <c><anno>TupleList2</anno></c>
+          must be key-sorted without duplicates before evaluating this function.
+          When two tuples compare equal, the tuple from
+          <c><anno>TupleList1</anno></c> is picked and the
+          one from <c><anno>TupleList2</anno></c> is deleted.</p>
       </desc>
     </func>
+
     <func>
       <name name="ukeysort" arity="2"/>
-      <fsummary>Sort a list of tuples, removing duplicates</fsummary>
+      <fsummary>Sort a list of tuples, removing duplicates.</fsummary>
       <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
       <desc>
-        <p>Returns a list containing the sorted elements of the list
-          <c><anno>TupleList1</anno></c> where all but the first tuple of the
-          tuples comparing equal have been deleted. Sorting is
+        <p>Returns a list containing the sorted elements of list
+          <c><anno>TupleList1</anno></c> where all except the first tuple of
+          the tuples comparing equal have been deleted. Sorting is
           performed on the <c><anno>N</anno></c>th element of the tuples.</p>
       </desc>
     </func>
+
     <func>
       <name name="umerge" arity="1"/>
-      <fsummary>Merge a list of sorted lists, removing duplicates</fsummary>
+      <fsummary>Merge a list of sorted lists, removing duplicates.</fsummary>
       <desc>
-        <p>Returns the sorted list formed by merging all the sub-lists
-          of <c><anno>ListOfLists</anno></c>. All sub-lists must be sorted and
-          contain no duplicates prior to evaluating this function.
-          When two elements compare equal, the element from the
-          sub-list with the lowest position in <c><anno>ListOfLists</anno></c> is
-          picked and the other one deleted.</p>
+        <p>Returns the sorted list formed by merging all the sublists
+          of <c><anno>ListOfLists</anno></c>. All sublists must be sorted and
+          contain no duplicates before evaluating this function.
+          When two elements compare equal, the element from the sublist
+          with the lowest position in <c><anno>ListOfLists</anno></c> is
+          picked and the other is deleted.</p>
       </desc>
     </func>
+
     <func>
       <name name="umerge" arity="2"/>
-      <fsummary>Merge two sorted lists, removing duplicates</fsummary>
+      <fsummary>Merge two sorted lists, removing duplicates.</fsummary>
       <desc>
-        <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> and
-          <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and <c><anno>List2</anno></c> must be
-          sorted and contain no duplicates prior to evaluating this
+        <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>
+          and <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and
+          <c><anno>List2</anno></c> must be
+          sorted and contain no duplicates before evaluating this
           function. When two elements compare equal, the element from
-          <c><anno>List1</anno></c> is picked and the one from <c><anno>List2</anno></c>
-          deleted.</p>
+          <c><anno>List1</anno></c> is picked and the one from
+          <c><anno>List2</anno></c> is deleted.</p>
       </desc>
     </func>
+
     <func>
       <name name="umerge" arity="3"/>
-      <fsummary>Merge two sorted lists, removing duplicates</fsummary>
+      <fsummary>Merge two sorted lists, removing duplicates.</fsummary>
       <desc>
-        <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> and
-          <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and <c><anno>List2</anno></c> must be
-          sorted according to the <seealso
+        <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>
+          and <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and
+          <c><anno>List2</anno></c> must be sorted according to the <seealso
           marker="#ordering_function">ordering function</seealso>
-          <c>Fun</c> and contain no duplicates prior to evaluating
-          this function. <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> should return <c>true</c> if
-          <c><anno>A</anno></c> compares less than or equal to <c><anno>B</anno></c> in the
-          ordering, <c>false</c> otherwise. When two elements compare
-          equal, the element from
-          <c><anno>List1</anno></c> is picked and the one from <c><anno>List2</anno></c>
-          deleted.</p>
+          <c>Fun</c> and contain no duplicates before evaluating this function.
+          <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> is to return
+          <c>true</c> if <c><anno>A</anno></c> compares less than or equal to
+          <c><anno>B</anno></c> in the ordering, otherwise <c>false</c>. When
+          two elements compare equal, the element from <c><anno>List1</anno></c>
+          is picked and the one from <c><anno>List2</anno></c> is deleted.</p>
       </desc>
     </func>
+
     <func>
       <name name="umerge3" arity="3"/>
-      <fsummary>Merge three sorted lists, removing duplicates</fsummary>
+      <fsummary>Merge three sorted lists, removing duplicates.</fsummary>
       <desc>
         <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>,
-          <c><anno>List2</anno></c> and <c><anno>List3</anno></c>. All of <c><anno>List1</anno></c>,
-          <c><anno>List2</anno></c> and <c><anno>List3</anno></c> must be sorted and contain no
-          duplicates prior to evaluating this function. When two
+          <c><anno>List2</anno></c>, and <c><anno>List3</anno></c>. All of
+          <c><anno>List1</anno></c>, <c><anno>List2</anno></c>, and
+          <c><anno>List3</anno></c> must be sorted and contain no
+          duplicates before evaluating this function. When two
           elements compare equal, the element from <c><anno>List1</anno></c> is
-          picked if there is such an element, otherwise the element
-          from <c><anno>List2</anno></c> is picked, and the other one deleted.</p>
+          picked if there is such an element, otherwise the element from
+          <c><anno>List2</anno></c> is picked, and the other is deleted.</p>
       </desc>
     </func>
+
     <func>
       <name name="unzip" arity="1"/>
-      <fsummary>Unzip a list of two-tuples into two lists</fsummary>
+      <fsummary>Unzip a list of two-tuples into two lists.</fsummary>
       <desc>
         <p>"Unzips" a list of two-tuples into two lists, where the first
           list contains the first element of each tuple, and the second
           list contains the second element of each tuple.</p>
       </desc>
     </func>
+
     <func>
       <name name="unzip3" arity="1"/>
-      <fsummary>Unzip a list of three-tuples into three lists</fsummary>
+      <fsummary>Unzip a list of three-tuples into three lists.</fsummary>
       <desc>
         <p>"Unzips" a list of three-tuples into three lists, where
           the first list contains the first element of each tuple,
@@ -854,76 +988,84 @@ splitwith(Pred, List) ->
           the third list contains the third element of each tuple.</p>
       </desc>
     </func>
+
     <func>
       <name name="usort" arity="1"/>
-      <fsummary>Sort a list, removing duplicates</fsummary>
+      <fsummary>Sort a list, removing duplicates.</fsummary>
       <desc>
         <p>Returns a list containing the sorted elements of
-          <c><anno>List1</anno></c> where all but the first element of the elements
-          comparing equal have been deleted.</p>
+          <c><anno>List1</anno></c> where all except the first element of the
+          elements comparing equal have been deleted.</p>
       </desc>
     </func>
+
     <func>
       <name name="usort" arity="2"/>
-      <fsummary>Sort a list, removing duplicates</fsummary>
+      <fsummary>Sort a list, removing duplicates.</fsummary>
       <desc>
-        <p>Returns a list which contains the sorted elements of
-          <c><anno>List1</anno></c> where all but the first element of the elements
-          comparing equal according to the <seealso
+        <p>Returns a list containing the sorted elements of
+          <c><anno>List1</anno></c> where all except the first element of the
+          elements comparing equal according to the <seealso
           marker="#ordering_function">ordering function</seealso>
-          <c><anno>Fun</anno></c> have been deleted. <c><anno>Fun</anno>(A, B)</c> should return
+          <c><anno>Fun</anno></c> have been deleted.
+          <c><anno>Fun</anno>(A, B)</c> is to return
           <c>true</c> if <c>A</c> compares less than or equal to
-          <c>B</c> in the ordering, <c>false</c> otherwise.</p>
+          <c>B</c> in the ordering, otherwise <c>false</c>.</p>
       </desc>
     </func>
+
     <func>
       <name name="zip" arity="2"/>
-      <fsummary>Zip two lists into a list of two-tuples</fsummary>
+      <fsummary>Zip two lists into a list of two-tuples.</fsummary>
       <desc>
         <p>"Zips" two lists of equal length into one list of two-tuples,
           where the first element of each tuple is taken from the first
-          list and the second element is taken from corresponding
+          list and the second element is taken from the corresponding
           element in the second list.</p>
       </desc>
     </func>
+
     <func>
       <name name="zip3" arity="3"/>
-      <fsummary>Zip three lists into a list of three-tuples</fsummary>
+      <fsummary>Zip three lists into a list of three-tuples.</fsummary>
       <desc>
         <p>"Zips" three lists of equal length into one list of
           three-tuples, where the first element of each tuple is taken
           from the first list, the second element is taken from
-          corresponding element in the second list, and the third
-          element is taken from the corresponding element in the third
-          list.</p>
+          the corresponding element in the second list, and the third
+          element is taken from the corresponding element in the third list.</p>
       </desc>
     </func>
+
     <func>
       <name name="zipwith" arity="3"/>
-      <fsummary>Zip two lists into one list according to a fun</fsummary>
+      <fsummary>Zip two lists into one list according to a fun.</fsummary>
       <desc>
-        <p>Combine the elements of two lists of equal length into one
-          list. For each pair <c><anno>X</anno>, <anno>Y</anno></c> of list elements from the two
-          lists, the element in the result list will be
+        <p>Combines the elements of two lists of equal length into one list.
+          For each pair <c><anno>X</anno>, <anno>Y</anno></c> of list elements
+          from the two lists, the element in the result list is
           <c><anno>Combine</anno>(<anno>X</anno>, <anno>Y</anno>)</c>.</p>
         <p><c>zipwith(fun(X, Y) -> {X,Y} end, List1, List2)</c> is
           equivalent to <c>zip(List1, List2)</c>.</p>
-        <p>Example:</p>
+        <p><em>Example:</em></p>
         <pre>
 > <input>lists:zipwith(fun(X, Y) -> X+Y end, [1,2,3], [4,5,6]).</input>
 [5,7,9]</pre>
       </desc>
     </func>
+
     <func>
       <name name="zipwith3" arity="4"/>
-      <fsummary>Zip three lists into one list according to a fun</fsummary>
-      <desc>
-        <p>Combine the elements of three lists of equal length into one
-          list. For each triple <c><anno>X</anno>, <anno>Y</anno>, <anno>Z</anno></c> of list elements from
-          the three lists, the element in the result list will be
-          <c><anno>Combine</anno>(<anno>X</anno>, <anno>Y</anno>, <anno>Z</anno>)</c>.</p>
-        <p><c>zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1, List2, List3)</c> is equivalent to <c>zip3(List1, List2, List3)</c>.</p>
-        <p>Examples:</p>
+      <fsummary>Zip three lists into one list according to a fun.</fsummary>
+      <desc>
+        <p>Combines the elements of three lists of equal length into one
+          list. For each triple <c><anno>X</anno>, <anno>Y</anno>,
+          <anno>Z</anno></c> of list elements from the three lists, the element
+          in the result list is <c><anno>Combine</anno>(<anno>X</anno>,
+          <anno>Y</anno>, <anno>Z</anno>)</c>.</p>
+        <p><c>zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1, List2, List3)</c> is
+          equivalent to <c>zip3(List1, List2, List3)</c>.</p>
+        <p><em>Examples:</em></p>
         <pre>
 > <input>lists:zipwith3(fun(X, Y, Z) -> X+Y+Z end, [1,2,3], [4,5,6], [7,8,9]).</input>
 [12,15,18]