Update Programming Examples

Language cleaned up by the technical writers xsipewe and tmanevik
from Combitech. Proofreading and corrections by Björn Gustavsson.

1 files changed, 45 insertions, 41 deletions

diff --git a/system/doc/programming_examples/list_comprehensions.xml b/system/doc/programming_examples/list_comprehensions.xml
index d6c8a66e13..5b33b14dea 100644
--- a/system/doc/programming_examples/list_comprehensions.xml
+++ b/system/doc/programming_examples/list_comprehensions.xml
@@ -31,18 +31,15 @@
 
   <section>
     <title>Simple Examples</title>
-    <p>We start with a simple example:</p>
+    <p>This section starts with a simple example, showing a generator and a filter:</p>
     <pre>
 > <input>[X || X &lt;- [1,2,a,3,4,b,5,6], X > 3].</input>
 [a,4,b,5,6]</pre>
-    <p>This should be read as follows:</p>
-    <quote>
-      <p>The list of X such that X is taken from the list
+    <p>This is read as follows: The list of X such that X is taken from the list
         <c>[1,2,a,...]</c> and X is greater than 3.</p>
-    </quote>
     <p>The notation <c><![CDATA[X <- [1,2,a,...]]]></c> is a generator and
       the expression <c>X > 3</c> is a filter.</p>
-    <p>An additional filter can be added in order to restrict
+    <p>An additional filter, <c>integer(X)</c>, can be added to restrict
       the result to integers:</p>
     <pre>
 > <input>[X || X &lt;- [1,2,a,3,4,b,5,6], integer(X), X > 3].</input>
@@ -56,7 +53,7 @@
 
   <section>
     <title>Quick Sort</title>
-    <p>The well known quick sort routine can be written as follows:</p>
+    <p>The well-known quick sort routine can be written as follows:</p>
     <code type="none"><![CDATA[
 sort([Pivot|T]) ->
     sort([ X || X <- T, X < Pivot]) ++
@@ -64,15 +61,20 @@ sort([Pivot|T]) ->
     sort([ X || X <- T, X >= Pivot]);
 sort([]) -> [].]]></code>
     <p>The expression <c><![CDATA[[X || X <- T, X < Pivot]]]></c> is the list of
-      all elements in <c>T</c>, which are less than <c>Pivot</c>.</p>
+      all elements in <c>T</c> that are less than <c>Pivot</c>.</p>
     <p><c><![CDATA[[X || X <- T, X >= Pivot]]]></c> is the list of all elements in
-      <c>T</c>, which are greater or equal to <c>Pivot</c>.</p>
-    <p>To sort a list, we isolate the first element in the list and
-      split the list into two sub-lists. The first sub-list contains
-      all elements which are smaller than the first element in
-      the list, the second contains all elements which are greater
-      than or equal to the first element in the list. We then sort
-      the sub-lists and combine the results.</p>
+      <c>T</c> that are greater than or equal to <c>Pivot</c>.</p>
+      <p>A list sorted as follows:</p>
+      <list type="bulleted">
+       <item>The first element in the list is isolated
+       and the list is split into two sublists.</item>
+       <item>The first sublist contains
+      all elements that are smaller than the first element in
+      the list.</item>
+      <item>The second sublist contains all elements that are greater
+      than, or equal to, the first element in the list.</item>
+       <item>Then the sublists are sorted and the results are combined.</item>
+     </list>
   </section>
 
   <section>
@@ -82,10 +84,10 @@ sort([]) -> [].]]></code>
     <code type="none"><![CDATA[
 perms([]) -> [[]];
 perms(L)  -> [[H|T] || H <- L, T <- perms(L--[H])].]]></code>
-    <p>We take take <c>H</c> from <c>L</c> in all possible ways.
+    <p>This takes <c>H</c> from <c>L</c> in all possible ways.
       The result is the set of all lists <c>[H|T]</c>, where <c>T</c>
-      is the set of all possible permutations of <c>L</c> with
-      <c>H</c> removed.</p>
+      is the set of all possible permutations of <c>L</c>, with
+      <c>H</c> removed:</p>
     <pre>
 > <input>perms([b,u,g]).</input>
 [[b,u,g],[b,g,u],[u,b,g],[u,g,b],[g,b,u],[g,u,b]]</pre>
@@ -97,7 +99,7 @@ perms(L)  -> [[H|T] || H <- L, T <- perms(L--[H])].]]></code>
       that <c>A**2 + B**2 = C**2</c>.</p>
     <p>The function <c>pyth(N)</c> generates a list of all integers
       <c>{A,B,C}</c> such that <c>A**2 + B**2 = C**2</c> and where
-      the sum of the sides is equal to or less than <c>N</c>.</p>
+      the sum of the sides is equal to, or less than, <c>N</c>:</p>
     <code type="none"><![CDATA[
 pyth(N) ->
     [ {A,B,C} ||
@@ -140,7 +142,7 @@ pyth1(N) ->
   </section>
 
   <section>
-    <title>Simplifications with List Comprehensions</title>
+    <title>Simplifications With List Comprehensions</title>
     <p>As an example, list comprehensions can be used to simplify some
       of the functions in <c>lists.erl</c>:</p>
     <code type="none"><![CDATA[
@@ -151,45 +153,47 @@ filter(Pred, L) -> [X || X <- L, Pred(X)].]]></code>
 
   <section>
     <title>Variable Bindings in List Comprehensions</title>
-    <p>The scope rules for variables which occur in list
+    <p>The scope rules for variables that occur in list
       comprehensions are as follows:</p>
     <list type="bulleted">
-      <item>all variables which occur in a generator pattern are
-       assumed to be "fresh" variables</item>
-      <item>any variables which are defined before the list
-       comprehension and which are used in filters have the values
-       they had before the list comprehension</item>
-      <item>no variables may be exported from a list comprehension.</item>
+      <item>All variables that occur in a generator pattern are
+       assumed to be "fresh" variables.</item>
+      <item>Any variables that are defined before the list
+       comprehension, and that are used in filters, have the values
+       they had before the list comprehension.</item>
+      <item>Variables cannot be exported from a list comprehension.</item>
     </list>
-    <p>As an example of these rules, suppose we want to write
+    <p>As an example of these rules, suppose you want to write
       the function <c>select</c>, which selects certain elements from
-      a list of tuples. We might write
+      a list of tuples. Suppose you write
       <c><![CDATA[select(X, L) ->  [Y || {X, Y} <- L].]]></c> with the intention
-      of extracting all tuples from <c>L</c> where the first item is
+      of extracting all tuples from <c>L</c>, where the first item is
       <c>X</c>.</p>
-    <p>Compiling this yields the following diagnostic:</p>
+    <p>Compiling this gives the following diagnostic:</p>
     <code type="none">
 ./FileName.erl:Line: Warning: variable 'X' shadowed in generate</code>
-    <p>This diagnostic warns us that the variable <c>X</c> in
-      the pattern is not the same variable as the variable <c>X</c>
-      which occurs in the function head.</p>
-    <p>Evaluating <c>select</c> yields the following result:</p>
+    <p>This diagnostic warns that the variable <c>X</c> in
+      the pattern is not the same as the variable <c>X</c>
+      that occurs in the function head.</p>
+    <p>Evaluating <c>select</c> gives the following result:</p>
     <pre>
 > <input>select(b,[{a,1},{b,2},{c,3},{b,7}]).</input>
 [1,2,3,7]</pre>
-    <p>This result is not what we wanted. To achieve the desired
-      effect we must write <c>select</c> as follows:</p>
+    <p>This is not the wanted result. To achieve the desired
+      effect, <c>select</c> must be written as follows:</p>
     <code type="none"><![CDATA[
 select(X, L) ->  [Y || {X1, Y} <- L, X == X1].]]></code>
     <p>The generator now contains unbound variables and the test has
-      been moved into the filter. This now works as expected:</p>
+      been moved into the filter.</p>
+      <p>This now works as expected:</p>
     <pre>
 > <input>select(b,[{a,1},{b,2},{c,3},{b,7}]).</input>
 [2,7]</pre>
-    <p>One consequence of the rules for importing variables into a
+    <p>A consequence of the rules for importing variables into a
       list comprehensions is that certain pattern matching operations
-      have to be moved into the filters and cannot be written directly
-      in the generators. To illustrate this, do not write as follows:</p>
+      must be moved into the filters and cannot be written directly
+      in the generators.</p>
+      <p>To illustrate this, do <em>not</em> write as follows:</p>
     <code type="none"><![CDATA[
 f(...) ->
     Y = ...