Merge branch 'bjorn/mnesia/doc'

* bjorn/mnesia/doc:
  Update asn1 documentation

1 files changed, 721 insertions, 736 deletions

diff --git a/lib/mnesia/doc/src/Mnesia_chap4.xmlsrc b/lib/mnesia/doc/src/Mnesia_chap4.xmlsrc
index a18f853662..1671faa9b6 100644
--- a/lib/mnesia/doc/src/Mnesia_chap4.xmlsrc
+++ b/lib/mnesia/doc/src/Mnesia_chap4.xmlsrc
@@ -31,163 +31,146 @@
     <rev></rev>
     <file>Mnesia_chap4.xml</file>
   </header>
-  <p>This chapter describes the Mnesia transaction system and the
-    transaction properties which make Mnesia a fault tolerant,
-    distributed database management system. 
-    </p>
-  <p>Also covered in this chapter are  the locking functions, 
+  <p>This section describes the <c>Mnesia</c> transaction system and
+    the transaction properties that make <c>Mnesia</c> a fault-tolerant,
+    distributed Database Management System (DBMS).</p>
+  <p>This section also describes the locking functions,
     including table locks and sticky locks, as well as alternative
-    functions which bypass the transaction system in favor of improved
-    speed and reduced overheads. These functions are called "dirty
-    operations". We also describe the usage of nested transactions. 
-    This chapter contains the following sections: 
-    </p>
+    functions that bypass the transaction system in favor of improved
+    speed and reduced overhead. These functions are called "dirty
+    operations". The use of nested transactions is also described.
+    The following topics are included:</p>
   <list type="bulleted">
-    <item>transaction properties, which include atomicity,
-     consistency, isolation, and durability
-    </item>
-    <item>Locking
-    </item>
-    <item>Dirty operations
-    </item>
-    <item>Record names vs table names
-    </item>
-    <item>Activity concept and various access contexts
-    </item>
-    <item>Nested transactions
-    </item>
-    <item>Pattern matching
-    </item>
-    <item>Iteration 
-    </item>
+    <item>Transaction properties, which include atomicity,
+      consistency, isolation, and durability</item>
+    <item>Locking</item>
+    <item>Dirty operations</item>
+    <item>Record names versus table names</item>
+    <item>Activity concept and various access contexts</item>
+    <item>Nested transactions</item>
+    <item>Pattern matching</item>
+    <item>Iteration</item>
   </list>
 
   <section>
     <marker id="trans_prop"></marker>
     <title>Transaction Properties</title>
-    <p>Transactions are an important tool when designing fault
-      tolerant, distributed systems. A Mnesia transaction is a mechanism
+    <p>Transactions are important when designing fault-tolerant,
+      distributed systems. A <c>Mnesia</c> transaction is a mechanism
       by which a series of database operations can be executed as one
-      functional block. The functional block which is run as a
+      functional block. The functional block that is run as a
       transaction is called a Functional Object (Fun), and this code can
-      read, write, or delete Mnesia records. The Fun is evaluated as a
-      transaction which either commits, or aborts. If a transaction 
-      succeeds in executing Fun it will replicate the action on all nodes
-      involved, or abort if an error occurs.  
-      </p>
-    <p>The following example shows a transaction which raises the
-      salary of certain employee numbers. 
-      </p>
+      read, write, and delete <c>Mnesia</c> records. The Fun is evaluated
+      as a transaction that either commits or terminates. If a transaction
+      succeeds in executing the Fun, it replicates the action on all nodes
+      involved, or terminates if an error occurs.</p>
+    <p>The following example shows a transaction that raises the
+      salary of certain employee numbers:</p>
     <codeinclude file="company.erl" tag="%5" type="erl"></codeinclude>
-    <p>The transaction <c>raise(Eno, Raise) - ></c> contains a Fun
-      made up of four lines of code. This Fun is called by the statement
-      <c>mnesia:transaction(F)</c> and returns a value. 
-      </p>
-    <p>The Mnesia transaction system facilitates the construction of
+    <p>The function <c>raise/2</c> contains a Fun
+      made up of four code lines. This Fun is called by the statement
+      <c>mnesia:transaction(F)</c> and returns a value.</p>
+    <p>The <c>Mnesia</c> transaction system facilitates the construction of
       reliable, distributed systems by providing the following important
-      properties:  
-      </p>
+      properties:</p>
     <list type="bulleted">
-      <item>The transaction handler ensures that a Fun which is placed
-       inside a transaction does not interfere with operations embedded
+      <item>The transaction handler ensures that a Fun, which is placed
+       inside a transaction, does not interfere with operations embedded
        in other transactions when it executes a series of operations on
        tables.  
       </item>
       <item>The transaction handler ensures that either all operations
        in the transaction are performed successfully on all nodes
        atomically, or the transaction fails without permanent effect on
-       any of the nodes. 
+       any node.
       </item>
-      <item>The Mnesia transactions have four important properties,
-       which we call <em>A</em>tomicity,
-      <em>C</em>onsistency,<em>I</em>solation, and
-      <em>D</em>urability, or ACID for short. These properties are
-       described in the following sub-sections.</item>
+      <item>The <c>Mnesia</c> transactions have four important properties,
+       called <em>A</em>tomicity,
+       <em>C</em>onsistency, <em>I</em>solation, and
+       <em>D</em>urability (ACID). These properties are
+       described in the following sections.</item>
     </list>
 
     <section>
       <title>Atomicity</title>
-      <p><em>Atomicity</em> means that database changes which are
+      <p>Atomicity means that database changes that are
         executed by a transaction take effect on all nodes involved, or
-        on none of the nodes. In other words, the transaction either
-        succeeds entirely, or it fails entirely. 
-        </p>
-      <p>Atomicity is particularly important when we want to
-        atomically write more than one record in the same
-        transaction. The <c>raise/2</c> function, shown as an example
-        above, writes one record only. The <c>insert_emp/3</c> function,
-        shown in the program listing in Chapter 2, writes the record
-        <c>employee</c> as well as employee relations such as
-        <c>at_dep</c> and <c>in_proj</c> into the database. If we run
-        this latter code inside a transaction, then the transaction
+        on none of the nodes. That is, the transaction either
+        succeeds entirely, or it fails entirely.</p>
+      <p>Atomicity is important when it is needed to write
+        atomically more than one record in the same
+        transaction. The function <c>raise/2</c>, shown in the previous
+        example, writes one record only. The function <c>insert_emp/3</c>,
+        shown in the program listing in
+        <seealso marker="Mnesia_chap2#getting_started">Getting Started</seealso>, writes the record
+        <c>employee</c> as well as employee relations, such as
+        <c>at_dep</c> and <c>in_proj</c>, into the database. If this
+        latter code is run inside a transaction, the transaction
         handler ensures that the transaction either succeeds completely,
-        or not at all. 
-        </p>
-      <p>Mnesia is a distributed DBMS where data can be replicated on
-        several nodes. In many such applications, it is important that a
+        or not at all.</p>
+      <p><c>Mnesia</c> is a distributed DBMS where data can be replicated
+        on several nodes. In many applications, it is important that a
         series of write operations are performed atomically inside a
         transaction. The atomicity property ensures that a transaction
-        take effect on all nodes, or none at all. </p>
+        takes effect on all nodes, or none.</p>
     </section>
 
     <section>
       <title>Consistency</title>
-      <p><em>Consistency</em>. This transaction property ensures that
+      <p>The consistency property ensures that
         a transaction always leaves the DBMS in a consistent state. For
-        example, Mnesia ensures that inconsistencies will not occur if
-        Erlang, Mnesia or the computer crashes while a write operation
-        is in progress.
-        </p>
+        example, <c>Mnesia</c> ensures that no inconsistencies occur if
+        Erlang, <c>Mnesia</c>, or the computer crashes while a write
+        operation is in progress.</p>
     </section>
 
     <section>
       <title>Isolation</title>
-      <p><em>Isolation</em>. This transaction property ensures that
-        transactions which execute on different nodes in a network, and
-        access and manipulate the same data records, will not interfere
-        with each other. 
-        </p>
-      <p>The isolation property makes it possible to concurrently execute 
-        the <c>raise/2</c> function. A classical problem in concurrency control
-        theory is the so called "lost update problem". 
-        </p>
-      <p>The isolation property is extremely useful if the following 
-        circumstances occurs where an employee (with an employee number
-        123) and two processes, (P1 and P2), are concurrently trying to 
-        raise the salary for the employee. The initial value of the
-        employees salary is, for example,  5. Process P1 then starts to execute,
-        it reads the employee record and adds 2 to the salary. At this
-        point in time, process P1 is for some reason preempted and
-        process P2 has the opportunity to run. P2 reads the record, adds 3
-        to the salary, and finally writes a new employee record with
-        the salary set to 8. Now, process P1 start to run again and
+      <p>The isolation property ensures that
+        transactions that execute on different nodes in a network, and
+        access and manipulate the same data records, do not interfere
+        with each other. The isolation property makes it possible to
+        execute the function <c>raise/2</c> concurrently. A classical
+        problem in concurrency control theory is the "lost update
+        problem".</p>
+      <p>The isolation property is in particular useful if the following
+        circumstances occur where an employee (with employee number
+        123) and two processes (P1 and P2) are concurrently trying to
+        raise the salary for the employee:</p>
+      <list type="bulleted">
+        <item><em>Step 1:</em> The initial value of the employees salary
+        is, for example, 5. Process P1 starts to execute, reads the
+        employee record, and adds 2 to the salary.</item>
+        <item><em>Step 2:</em> Process P1 is for some reason pre-empted
+        and process P2 has the opportunity to run.</item>
+        <item><em>Step 3:</em> Process P2 reads the record, adds 3 to
+        the salary, and finally writes a new employee record with
+        the salary set to 8.</item>
+        <item><em>Step 4:</em> Process P1 starts to run again and
         writes its employee record with salary set to 7, thus
         effectively overwriting and undoing the work performed by
-        process P2. The update performed by P2 is lost.   
-        </p>
-      <p>A transaction system makes it possible to concurrently
-        execute two or more processes which manipulate the same
-        record. The programmer does not need to check that  the
-        updates are synchronous, this is overseen by the
+        process P2. The update performed by P2 is lost.</item>
+      </list>
+      <p>A transaction system makes it possible to execute two or more
+        processes concurrently that manipulate the same record.
+        The programmer does not need to check that the
+        updates are synchronous; this is overseen by the
         transaction handler. All programs accessing the database through
-        the transaction system may be written as if they had sole access
-        to the data.
-        </p>
+        the transaction system can be written as if they had sole access
+        to the data.</p>
     </section>
 
     <section>
       <title>Durability</title>
-      <p><em>Durability</em>. This transaction property ensures that
+      <p>The durability property ensures that
         changes made to the DBMS by a transaction are permanent. Once a
-        transaction has been committed, all changes made to the database
-        are durable - i.e. they are written safely to disc and will not
-        be corrupted or disappear. 
-        </p>
+        transaction is committed, all changes made to the database are
+        durable, that is, they are written safely to disc and do not
+        become corrupted and do not disappear.</p>
       <note>
-        <p>The durability feature described does not entirely apply to
-          situations where Mnesia is configured as a "pure" primary memory
-          database. 
-          </p>
+        <p>The described durability feature does not entirely apply to
+          situations where <c>Mnesia</c> is configured as a "pure"
+          primary memory database.</p>
       </note>
     </section>
   </section>
@@ -195,397 +178,383 @@
   <section>
     <title>Locking</title>
     <p>Different transaction managers employ different strategies to
-      satisfy the isolation property. Mnesia uses the standard technique
-      of two-phase locking. This means that locks are set on records
-      before they are read or written. Mnesia uses five different kinds
-      of locks. 
-      </p>
+      satisfy the isolation property. <c>Mnesia</c> uses the standard
+      technique of two phase locking. That is, locks are set on records
+      before they are read or written. <c>Mnesia</c> uses the following
+      lock types:</p>
     <list type="bulleted">
       <item><em>Read locks</em>. A read lock is set on one replica of
        a record before it can be read.
       </item>
-      <item><em>Write locks</em>. Whenever a transaction writes to an
+      <item><em>Write locks</em>. Whenever a transaction writes to a
        record, write locks are first set on all replicas of that
-       particular record. 
+       particular record.
       </item>
       <item><em>Read table locks</em>. If a transaction traverses an
-       entire table in search for a record which satisfy some
+       entire table in search for a record that satisfies some
        particular property, it is most inefficient to set read locks on
-       the records, one by one. It is also very memory consuming, since
-       the read locks themselves may take up considerable space if the
-       table is very large. For this reason, Mnesia can set a read lock
-       on an entire table. 
+       the records one by one. It is also memory consuming, as
+       the read locks themselves can take up considerable space if the
+       table is large. Therefore, <c>Mnesia</c> can set a read lock
+       on an entire table.
       </item>
-      <item><em>Write table locks</em>. If a transaction writes a
-       large number of records to one table, it is possible to set a
-       write lock on the entire table. 
+      <item><em>Write table locks</em>. If a transaction writes many
+       records to one table, a write lock can be set on the entire table.
       </item>
       <item><em>Sticky locks</em>. These are write locks that stay in
-       place at a node after the transaction which initiated the lock
-       has terminated. </item>
+       place at a node after the transaction that initiated the lock
+       has terminated.</item>
     </list>
-    <p>Mnesia employs a strategy whereby functions such as
-      <c>mnesia:read/1</c> acquire the necessary locks dynamically as
-      the transactions execute. Mnesia automatically sets and releases
-      the locks and the  programmer does not have to code these
-      operations.  
-      </p>
+    <p><c>Mnesia</c> employs a strategy whereby functions, such as
+      <seealso marker="mnesia#read/1">mnesia:read/1</seealso>
+      acquire the necessary locks dynamically as
+      the transactions execute. <c>Mnesia</c> automatically sets and
+      releases the locks and the programmer does not need to code these
+      operations.</p>
     <p>Deadlocks can occur when concurrent processes set and release
-      locks on the same records. Mnesia employs a "wait-die" strategy to
-      resolve these situations. If Mnesia suspects that a deadlock can
+      locks on the same records. <c>Mnesia</c> employs a "wait-die"
+      strategy to resolve
+      these situations. If <c>Mnesia</c> suspects that a deadlock can
       occur when a transaction tries to set a lock, the transaction is
-      forced to release all its locks and sleep for a while. The
-      Fun in the transaction will be evaluated one more time. 
-      </p>
-    <p>For this reason, it is important that the code inside the Fun given to
-      <c>mnesia:transaction/1</c> is pure. Some strange results can
+      forced to release all its locks and sleep for a while. The Fun
+      in the transaction is evaluated once more.</p>
+    <p>It is therefore important that the code inside the Fun given to
+      <seealso marker="mnesia#transaction/2"><c>mnesia:transaction/1</c></seealso>
+      is pure. Some strange results can
       occur if, for example, messages are sent by the transaction
-      Fun. The following example illustrates this situation:  
-      </p>
+      Fun. The following example illustrates this situation:</p>
     <codeinclude file="company.erl" tag="%6" type="erl"></codeinclude>
-    <p>This transaction could write the text <c>"Trying to write ... "</c> a thousand times to the terminal. Mnesia does guarantee,
-      however, that each and every transaction will eventually run. As a
-      result, Mnesia is not only deadlock free, but also livelock
-      free.
-      </p>
-    <p>The Mnesia programmer cannot prioritize one particular
-      transaction to execute before other transactions which are waiting
-      to execute. As a result, the Mnesia DBMS transaction system is not
-      suitable for hard real time applications. However, Mnesia contains
-      other features that have real time properties.  
-      </p>
-    <p>Mnesia dynamically sets and releases locks as
-      transactions execute, therefore, it is very dangerous to execute code with
+    <p>This transaction can write the text <c>"Trying to write ... "</c>
+      1000 times to the terminal. However, <c>Mnesia</c> guarantees
+      that each transaction will eventually run. As a result,
+      <c>Mnesia</c> is not only deadlock free, but also livelock free.</p>
+    <p>The <c>Mnesia</c> programmer cannot prioritize one particular
+      transaction to execute before other transactions that are waiting
+      to execute. As a result, the <c>Mnesia</c> DBMS transaction system is
+      not suitable for hard real-time applications. However, <c>Mnesia</c>
+      contains other features that have real-time properties.</p>
+    <p><c>Mnesia</c> dynamically sets and releases locks as transactions
+      execute. It is therefore dangerous to execute code with
       transaction side-effects. In particular, a <c>receive</c>
       statement inside a transaction can lead to a situation where the
       transaction hangs and never returns, which in turn can cause locks
-      not to release. This situation could bring the whole system to a
-      standstill since other transactions which execute in other
+      not to release. This situation can bring the whole system to a
+      standstill, as other transactions that execute in other
       processes, or on other nodes, are forced to wait for the defective
-      transaction. 
-      </p>
-    <p>If a transaction terminates abnormally, Mnesia will
-      automatically release the locks held by the transaction. 
-      </p>
-    <p>We have shown examples of a number of functions that can be
-      used inside a transaction. The following list shows the
-      <em>simplest</em> Mnesia functions that work with transactions. It
-      is important to realize that these functions must be embedded in a
+      transaction.</p>
+    <p>If a transaction terminates abnormally, <c>Mnesia</c>
+      automatically releases the locks held by the transaction.</p>
+    <p>Up to now, examples of a number of functions that can be used
+      inside a transaction have been shown. The following list shows
+      the <em>simplest</em> <c>Mnesia</c> functions that work with
+      transactions. Notice that these functions must be embedded in a
       transaction. If no enclosing transaction (or other enclosing
-      Mnesia activity) exists, they will all fail.
-      </p>
+      <c>Mnesia</c> activity) exists, they all fail.</p>
     <list type="bulleted">
-      <item><c>mnesia:transaction(Fun) -> {aborted, Reason} |{atomic, Value}</c>. This function executes one transaction with the
-       functional object <c>Fun</c> as the single parameter. 
+      <item><seealso marker="mnesia#transaction/2">mnesia:transaction(Fun) -> {aborted, Reason} |{atomic, Value}</seealso>
+       executes one transaction with the
+       functional object <c>Fun</c> as the single parameter.
       </item>
-      <item><c>mnesia:read({Tab, Key}) -> transaction abort | RecordList</c>. This function reads all records with <c>Key</c>
-       as key from table <c>Tab</c>.  This function has the same semantics
+      <item><seealso marker="mnesia#read/1">mnesia:read({Tab, Key}) -> transaction abort | RecordList</seealso>
+       reads all records with <c>Key</c>
+       as key from table <c>Tab</c>. This function has the same semantics
        regardless of the location of <c>Table</c>. If the table is of
-       type <c>bag</c>, the <c>read({Tab, Key})</c> can return an arbitrarily
+       type <c>bag</c>, <c>read({Tab, Key})</c> can return an arbitrarily
        long list. If the table is of type <c>set</c>, the list is
-       either of length one, or <c>[]</c>.
+       either of length one or <c>[]</c>.
       </item>
-      <item><c>mnesia:wread({Tab, Key}) -> transaction abort | RecordList</c>. This function behaves the same way as the
-       previously listed <c>read/1</c> function, except that it
-       acquires a write lock instead of a read lock. If we execute a
-       transaction which reads a record, modifies the record, and then
+      <item><seealso marker="mnesia#wread/1">mnesia:wread({Tab, Key}) -> transaction abort | RecordList</seealso>
+       behaves the same way as the
+       previously listed function <c>read/1</c>, except that it
+       acquires a write lock instead of a read lock. To execute a
+       transaction that reads a record, modifies the record, and then
        writes the record, it is slightly more efficient to set the
-       write lock immediately.  In cases where we issue a
-      <c>mnesia:read/1</c>, followed by a <c>mnesia:write/1</c>, the
-       first read lock must be upgraded to a write lock when the write
-       operation is executed. 
+       write lock immediately. When a <seealso marker="mnesia#read/1">mnesia:read/1</seealso>
+       is issued, followed by a
+       <seealso marker="mnesia#write/1">mnesia:write/1</seealso>
+       the first read lock must be upgraded to a write lock when the
+       write operation is executed.
       </item>
-      <item><c>mnesia:write(Record) -> transaction abort | ok</c>. This function writes a record into the database. The
-      <c>Record</c> argument is an instance of a record. The function
-       returns <c>ok</c>, or aborts the transaction if an error should
-       occur. 
+      <item><seealso marker="mnesia#write/1">mnesia:write(Record) -> transaction abort | ok</seealso>
+       writes a record into the database. Argument
+       <c>Record</c> is an instance of a record. The function returns
+       <c>ok</c>, or terminates the transaction if an error occurs.
       </item>
-      <item><c>mnesia:delete({Tab, Key}) -> transaction abort | ok</c>. This
-       function deletes all records with the given key.
+      <item><seealso marker="mnesia#delete/1">mnesia:delete({Tab, Key}) -> transaction abort | ok</seealso>
+       deletes all records with the given key.
       </item>
-      <item><c>mnesia:delete_object(Record) -> transaction abort | ok</c>.  This function deletes records with object id
-      <c>Record</c>. This function is used when we want to delete only
-       some records in a table of type <c>bag</c>. </item>
+      <item><seealso marker="mnesia#delete_object/1">mnesia:delete_object(Record) -> transaction abort | ok</seealso>
+       deletes records with the OID <c>Record</c>. Use this function to
+       delete only some records in a table of type <c>bag</c>.</item>
     </list>
 
     <section>
       <title>Sticky Locks</title>
-      <p>As previously stated, the locking strategy used by Mnesia is
-        to lock one record when we read a record, and lock all replicas
-        of a record when we write a record. However, there are
-        applications which use Mnesia mainly for its fault-tolerant
-        qualities, and these applications may be configured with one
-        node doing all the heavy work, and a standby node which is ready
-        to take over in case the main node fails. Such applications may
+      <p>As previously stated, the locking strategy used by <c>Mnesia</c>
+        is to lock one record when reading a record, and lock all replicas
+        of a record when writing a record. However, some
+        applications use <c>Mnesia</c> mainly for its fault-tolerant
+        qualities. These applications can be configured with one
+        node doing all the heavy work, and a standby node that is ready
+        to take over if the main node fails. Such applications can
         benefit from using sticky locks instead of the normal locking
-        scheme. 
-        </p>
-      <p>A sticky lock is a lock which stays in place at a node after
-        the transaction which first acquired the lock has terminated. To
-        illustrate this, assume that we execute the following
-        transaction: 
-        </p>
+        scheme.</p>
+      <p>A sticky lock is a lock that stays in place at a node, after
+        the transaction that first acquired the lock has terminated. To
+        illustrate this, assume that the following transaction is
+        executed:</p>
       <code type="none">
         F = fun() ->
               mnesia:write(#foo{a = kalle})
             end,
-        mnesia:transaction(F).
-      </code>
+        mnesia:transaction(F).</code>
       <p>The <c>foo</c> table is replicated on the two nodes <c>N1</c>
-        and <c>N2</c>. 
-                <br></br>
-Normal locking requires: 
-        </p>
+        and <c>N2</c>.</p>
+      <p>Normal locking requires the following:</p>
       <list type="bulleted">
-        <item>one network rpc (2 messages) to acquire the write lock
+        <item>One network RPC (two messages) to acquire the write lock
         </item>
-        <item>three network messages to execute the two-phase commit protocol.
+        <item>Three network messages to execute the two-phase commit
+         protocol
         </item>
       </list>
-      <p>If we use sticky locks, we must first change the code as follows:
-        </p>
+      <p>If sticky locks are used, the code must first be changed as
+        follows:</p>
       <code type="none">
-
         F = fun() ->
               mnesia:s_write(#foo{a = kalle})
             end,
-        mnesia:transaction(F).
-      </code>
-      <p>This code uses the <c>s_write/1</c> function instead of the
-        <c>write/1</c> function. The <c>s_write/1</c> function sets a
+        mnesia:transaction(F).</code>
+      <p>This code uses the function
+        <seealso marker="mnesia#s_write/1">s_write/1</seealso>
+        instead of the function
+        <seealso marker="mnesia#write/1">write/1</seealso>
+        The function <c>s_write/1</c> sets a
         sticky lock instead of a normal lock. If the table is not
         replicated, sticky locks have no special effect. If the table is
-        replicated, and we set a sticky lock on node <c>N1</c>, this
-        lock will then stick to node <c>N1</c>. The next time we try to
-        set a sticky lock on the same record at node <c>N1</c>, Mnesia
-        will see that the lock is already set and will not do a network
-        operation in order to acquire the lock. 
-        </p>
-      <p>It is much more efficient to set a local lock than it is to set
-        a networked lock, and for this reason sticky locks can benefit 
-        application that use a replicated table and perform most of the
-        work on only one of the nodes. 
-        </p>
-      <p>If a record is stuck at node <c>N1</c> and we try to set a
+        replicated, and a sticky lock is set on node <c>N1</c>, this
+        lock then sticks to node <c>N1</c>. The next time you try to
+        set a sticky lock on the same record at node <c>N1</c>,
+        <c>Mnesia</c> detects that the lock is already set and do no
+        network operation to acquire the lock.</p>
+      <p>It is more efficient to set a local lock than it is to set
+        a networked lock. Sticky locks can therefore benefit an
+        application that uses a replicated table and perform most of the
+        work on only one of the nodes.</p>
+      <p>If a record is stuck at node <c>N1</c> and you try to set a
         sticky lock for the record on node <c>N2</c>, the record must be
-        unstuck. This operation is expensive and will reduce performance. The unsticking is
-        done automatically if we issue <c>s_write/1</c> requests at
-        <c>N2</c>.
-        </p>
+        unstuck. This operation is expensive and reduces performance.
+        The unsticking is done automatically if you issue <c>s_write/1</c>
+        requests at <c>N2</c>.</p>
     </section>
 
     <section>
       <title>Table Locks</title>
-      <p>Mnesia supports read and write locks on whole tables as a
+      <p><c>Mnesia</c> supports read and write locks on whole tables as a
         complement to the normal locks on single records. As previously
-        stated, Mnesia sets and releases locks automatically, and the
-        programmer does not have to code these operations. However,
-        transactions which read and write a large number of records in a
-        specific table will execute more efficiently if we start the
-        transaction by setting a table lock on this table. This will
-        block other concurrent transactions from the table. The
-        following two function are used to set explicit table locks for
-        read and write operations:
-        </p>
+        stated, <c>Mnesia</c> sets and releases locks automatically, and
+        the programmer does not need to code these operations. However,
+        transactions that read and write many records in a
+        specific table execute more efficiently if the
+        transaction is started by setting a table lock on this table. This
+        blocks other concurrent transactions from the table. The
+        following two functions are used to set explicit table locks for
+        read and write operations:</p>
       <list type="bulleted">
-        <item><c>mnesia:read_lock_table(Tab)</c> Sets a read lock on
-         the table <c>Tab</c></item>
-        <item><c>mnesia:write_lock_table(Tab)</c> Sets a write lock on
-         the table <c>Tab</c></item>
+        <item><seealso marker="mnesia#read_lock_table/1">mnesia:read_lock_table(Tab)</seealso>
+         sets a read lock on table <c>Tab</c>.</item>
+        <item><seealso marker="mnesia#write_lock_table/1">mnesia:write_lock_table(Tab)</seealso>
+         sets a write lock on table <c>Tab</c>.</item>
       </list>
-      <p>Alternate syntax for acquisition of table locks is as follows:
-        </p>
+      <p>Alternative syntax for acquisition of table locks is as
+        follows:</p>
       <code type="none">
         mnesia:lock({table, Tab}, read)
-        mnesia:lock({table, Tab}, write)
-      </code>
-      <p>The matching operations in Mnesia may either lock the entire
-        table or just a single record (when the key is bound in the
-        pattern).
-        </p>
+        mnesia:lock({table, Tab}, write)</code>
+      <p>The matching operations in <c>Mnesia</c> can either lock the
+        entire table or only a single record (when the key is bound in
+        the pattern).</p>
     </section>
 
     <section>
       <title>Global Locks</title>
       <p>Write locks are normally acquired on all nodes where a
         replica of the table resides (and is active). Read locks are
-        acquired on one node (the local one if  a local
-        replica exists).
-        </p>
-      <p>The function <c>mnesia:lock/2</c> is intended to support
-        table locks (as mentioned previously)
-        but also  for situations when locks need to be
-        acquired regardless of how tables have been replicated:
-        </p>
+        acquired on one node (the local one if a local
+        replica exists).</p>
+      <p>The function
+        <seealso marker="mnesia#lock/2">mnesia:lock/2</seealso>
+        is intended to support table locks (as mentioned previously)
+        but also for situations when locks need to be
+        acquired regardless of how tables have been replicated:</p>
       <code type="none">
         mnesia:lock({global, GlobalKey, Nodes}, LockKind)
 
-        LockKind ::= read | write | ...
-      </code>
-      <p>The lock is acquired on the LockItem on all Nodes in the
-        nodes list.</p>
+        LockKind ::= read | write | ...</code>
+      <p>The lock is acquired on <c>LockItem</c> on all nodes in the
+        node list.</p>
     </section>
   </section>
 
   <section>
     <title>Dirty Operations</title>
     <p>In many applications, the overhead of processing a transaction
-      may result in a loss of performance.  Dirty operation are short 
-      cuts which bypass much of the processing and increase the speed 
-      of the transaction.
-      </p>
-    <p>Dirty operation are useful in many situations, for example in a datagram routing
-      application where  Mnesia  stores the routing table, and it is time 
+      can result in a loss of performance. Dirty operation are short
+      cuts that bypass much of the processing and increase the speed
+      of the transaction.</p>
+    <p>Dirty operation are often useful, for example, in a
+      datagram routing application
+      where <c>Mnesia</c> stores the routing table, and it is time
       consuming to start a whole transaction every time a packet is
-      received.  For this reason, Mnesia has functions which manipulate
+      received. <c>Mnesia</c> has therefore functions that manipulate
       tables without using transactions. This alternative
-      to processing is known as a dirty operation. However, it is important to
-      realize the trade-off in avoiding the overhead of transaction
-      processing: 
-      </p>
+      to processing is known as a dirty operation. However, notice the
+      trade-off in avoiding the overhead of transaction processing:</p>
     <list type="bulleted">
-      <item>The atomicity and the isolation properties of Mnesia are lost.
+      <item>The atomicity and the isolation properties of <c>Mnesia</c>
+       are lost.
       </item>
       <item>The isolation property is compromised, because other
        Erlang processes, which use transaction to manipulate the data,
-       do not get the benefit of isolation if we simultaneously use
-       dirty operations to read and write records from the same table. 
+       do not get the benefit of isolation if dirty operations
+       simultaneously are used to read and write records from the same
+       table.
       </item>
     </list>
     <p>The major advantage of dirty operations is that they execute
-      much faster than equivalent operations that are processed as 
-      functional objects within a transaction. 
-      </p>
+      much faster than equivalent operations that are processed as
+      functional objects within a transaction.</p>
     <p>Dirty operations
       are written to disc if they are performed on a table of type
-      <c>disc_copies</c>, or type <c>disc_only_copies</c>. Mnesia also
-      ensures that all replicas of a table are updated if a
-      dirty write operation is performed on a table.
-      </p>
-    <p>A dirty operation will ensure a certain level of consistency. 
-      For example, it is not possible for dirty operations to return 
-      garbled records. Hence, each individual read or write operation 
-      is performed in an atomic manner. 
-      </p>
-    <p>All dirty functions execute a call to <c>exit({aborted, Reason})</c> on failure. Even if the following functions are
-      executed inside a transaction no locks will be acquired.  The
-      following functions are available:
-      </p>
+      <c>disc_copies</c> or type <c>disc_only_copies</c>. <c>Mnesia</c>
+      also ensures that all replicas of a table are updated if a
+      dirty write operation is performed on a table.</p>
+    <p>A dirty operation ensures a certain level of consistency.
+      For example, dirty operations cannot return
+      garbled records. Hence, each individual read or write operation
+      is performed in an atomic manner.</p>
+    <p>All dirty functions execute a call to <c>exit({aborted, Reason})</c>
+      on failure. Even if the following functions are
+      executed inside a transaction no locks are acquired. The
+      following functions are available:</p>
     <list type="bulleted">
-      <item><c>mnesia:dirty_read({Tab, Key})</c>. This function reads
-       record(s) from Mnesia.
+      <item><seealso marker="mnesia#dirty_read/1">mnesia:dirty_read({Tab, Key})</seealso>
+       reads one or more records from <c>Mnesia</c>.
+      </item>
+      <item><seealso marker="mnesia#dirty_write/1">mnesia:dirty_write(Record)</seealso>
+       writes the record <c>Record</c>.
       </item>
-      <item><c>mnesia:dirty_write(Record)</c>. This function writes
-       the record <c>Record</c></item>
-      <item><c>mnesia:dirty_delete({Tab, Key})</c>. This function deletes
-       record(s) with the key <c>Key</c>. 
+      <item><seealso marker="mnesia#dirty_delete/1">mnesia:dirty_delete({Tab, Key})</seealso>
+       deletes one or more records with key <c>Key</c>.
+      </item>
+      <item><seealso marker="mnesia#dirty_delete_object/1">mnesia:dirty_delete_object(Record)</seealso>
+       is the dirty operation alternative to the function
+       <seealso marker="mnesia#delete_object/1">delete_object/1</seealso>.
       </item>
-      <item><c>mnesia:dirty_delete_object(Record)</c> This function is
-       the dirty operation alternative to the function
-      <c>delete_object/1</c></item>
       <item>
-        <p><c>mnesia:dirty_first(Tab)</c>. This function returns the
-          "first" key in the table <c>Tab</c>.  </p>
-        <p>Records in <c>set</c> or <c>bag</c> tables are not sorted. 
-          However, there is
-          a record order which is not known to the user.
-          This means that it is possible to traverse a table by means of
-          this function in conjunction with the <c>dirty_next/2</c>
-          function.
-          </p>
-        <p>If there are no records at all in the table, this function
-          will return the atom <c>'$end_of_table'</c>. It is not
+        <p><seealso marker="mnesia#dirty_first/1">mnesia:dirty_first(Tab)</seealso>
+          returns the "first" key in table <c>Tab</c>.</p>
+        <p>Records in <c>set</c> or <c>bag</c> tables are not sorted.
+          However, there is a record order that is unknown to the user.
+          This means that a table can be traversed by this function
+          with the function
+          <seealso marker="mnesia#dirty_next/2">mnesia:dirty_next/2</seealso>.</p>
+        <p>If there are no records in the table, this function
+          returns the atom <c>'$end_of_table'</c>. It is not
           recommended to use this atom as the key for any user
-          records. 
-          </p>
+          records.</p>
       </item>
-      <item><c>mnesia:dirty_next(Tab, Key)</c>. This function returns
-       the "next" key in the table <c>Tab</c>. This function makes it
+      <item><p><seealso marker="mnesia#dirty_next/2">mnesia:dirty_next(Tab, Key)</seealso>
+       returns the "next" key in table <c>Tab</c>. This function makes it
        possible to traverse a table and perform some operation on all
-       records in the table. When the end of the table is reached the
+       records in the table. When the end of the table is reached, the
        special key <c>'$end_of_table'</c> is returned. Otherwise, the
-       function returns a key which can be used to read the actual
-       record. 
-            <br></br>
-The behavior is undefined if any process perform a write
-       operation on the table while we traverse the table with the
-      <c>dirty_next/2</c> function. This is because <c>write</c>
-       operations on a Mnesia table may lead to internal reorganizations
-       of the table itself. This is an implementation detail, but remember
-       the dirty functions are low level functions. 
+       function returns a key that can be used to read the actual
+       record.</p>
+       <p>The behavior is undefined if any process performs a write
+       operation on the table while traversing the table with the
+       function
+       <seealso marker="mnesia#dirty_next/2">dirty_next/2</seealso>
+       This is because <c>write</c>
+       operations on a <c>Mnesia</c> table can lead to internal
+       reorganizations of the table itself. This is an implementation
+       detail, but remember that the dirty functions are low-level
+       functions.</p>
       </item>
-      <item><c>mnesia:dirty_last(Tab)</c> This function works exactly like
-      <c>mnesia:dirty_first/1</c> but returns the last object in
-       Erlang  term  order for the <c>ordered_set</c> table type. For
+      <item><seealso marker="mnesia#dirty_last/1">mnesia:dirty_last(Tab)</seealso>
+       works exactly like
+       <seealso marker="mnesia#dirty_first/1">mnesia:dirty_first/1</seealso>
+       but returns the last object in
+       Erlang term order for the table type <c>ordered_set</c>. For
        all other table types, <c>mnesia:dirty_first/1</c> and 
-      <c>mnesia:dirty_last/1</c> are synonyms.
+       <c>mnesia:dirty_last/1</c> are synonyms.
       </item>
-      <item><c>mnesia:dirty_prev(Tab, Key)</c> This function works exactly like
-      <c>mnesia:dirty_next/2</c> but returns the previous object in
-       Erlang term  order for the ordered_set table type. For
-       all other table types, <c>mnesia:dirty_next/2</c> and 
-      <c>mnesia:dirty_prev/2</c> are synonyms.
+      <item><seealso marker="mnesia#dirty_prev/2">mnesia:dirty_prev(Tab, Key)</seealso>
+       works exactly like
+       <c>mnesia:dirty_next/2</c> but returns the previous object in
+       Erlang term order for the table type <c>ordered_set</c>. For
+       all other table types, <c>mnesia:dirty_next/2</c> and
+       <c>mnesia:dirty_prev/2</c> are synonyms.
       </item>
       <item>
-        <p><c>mnesia:dirty_slot(Tab, Slot)</c></p>
-        <p>Returns the list of records that are associated with Slot
+        <p><seealso marker="mnesia#dirty_slot/2">mnesia:dirty_slot(Tab, Slot)</seealso>
+          returns the list of records that are associated with <c>Slot</c>
           in a table. It can be used to traverse a table in a manner
-          similar to the <c>dirty_next/2</c> function. A table has a
+          similar to the function <c>dirty_next/2</c>. A table has a
           number of slots that range from zero to some unknown upper
           bound. The function <c>dirty_slot/2</c> returns the special
           atom <c>'$end_of_table'</c> when the end of the table is
-          reached.
-                    <br></br>
-The behavior of this function is undefined if the
+          reached.</p>
+        <p>The behavior of this function is undefined if the
           table is written on while being
-          traversed. <c>mnesia:read_lock_table(Tab)</c> may be used to
-          ensure that no transaction protected writes are performed
-          during the iteration. 
-          </p>
+          traversed. The function
+          <seealso marker="mnesia#read_lock_table/1">mnesia:read_lock_table(Tab)</seealso>
+          can be used to ensure that no transaction-protected writes
+          are performed during the iteration.</p>
       </item>
-      <item>
-        <p><c>mnesia:dirty_update_counter({Tab,Key}, Val)</c>. </p>
-        <p>Counters are positive integers with a value greater than or
-          equal to zero. Updating a counter will add the <c>Val</c> and
-          the counter where  <c>Val</c> is a positive or negative integer.
-                    <br></br>
- There exists no special counter records in
-          Mnesia. However, records on the form of <c>{TabName, Key, Integer}</c> can be used as counters, and can be
-          persistent.  
-          </p>
-        <p>It is not possible to have transaction protected updates of
-          counter records.
-          </p>
+      <item><p><seealso marker="mnesia#dirty_update_counter/2">mnesia:dirty_update_counter({Tab,Key}, Val)</seealso>.
+          Counters are positive integers with a value greater than or
+          equal to zero. Updating a counter adds <c>Val</c> and the
+          counter where <c>Val</c> is a positive or negative integer.</p>
+        <p><c>Mnesia</c> has no special counter records. However, records
+          of the form <c>{TabName, Key, Integer}</c> can be used as
+          counters, and can be persistent.</p>
+        <p>Transaction-protected updates of counter records are not
+          possible.</p>
         <p>There are two significant differences when using this
           function instead of reading the record, performing the
-          arithmetic, and writing the record:
-          </p>
+          arithmetic, and writing the record:</p>
         <list type="ordered">
-          <item>it is much more efficient
+          <item>It is much more efficient.
           </item>
-          <item>the <c>dirty_update_counter/2</c> function is
-           performed as an atomic operation although it is not protected by
-           a transaction. Accordingly, no table update is lost if two
-           processes simultaneously execute the
-          <c>dirty_update_counter/2</c> function.
+          <item>The funcion
+           <seealso marker="mnesia#dirty_update_counter/2">dirty_update_counter/2</seealso>
+           is performed as an atomic operation although it is not protected
+           by a transaction. Therfore no table update is lost if two
+           processes simultaneously execute the function
+          <c>dirty_update_counter/2</c>.
           </item>
         </list>
       </item>
-      <item><c>mnesia:dirty_match_object(Pat)</c>. This function is
-       the dirty equivalent of <c>mnesia:match_object/1</c>. 
+      <item><seealso marker="mnesia#dirty_match_object/2">mnesia:dirty_match_object(Pat)</seealso>
+       is the dirty equivalent of
+       <seealso marker="mnesia#match_object/1">mnesia:match_object/1</seealso>.
       </item>
-      <item><c>mnesia:dirty_select(Tab, Pat)</c>. This function is
-       the dirty equivalent of <c>mnesia:select/2</c>. 
+      <item><seealso marker="mnesia#dirty_select/2">mnesia:dirty_select(Tab, Pat)</seealso>
+       is the dirty equivalent of
+       <seealso marker="mnesia#select/2"> mnesia:select/2</seealso>.
       </item>
-      <item><c>mnesia:dirty_index_match_object(Pat, Pos)</c>. This
-       function is the dirty equivalent of
-      <c>mnesia:index_match_object/2</c>. 
+      <item><seealso marker="mnesia#dirty_index_match_object/2">mnesia:dirty_index_match_object(Pat, Pos)</seealso>
+       is the dirty equivalent of
+       <seealso marker="mnesia#index_match_object/2">mnesia:index_match_object/2</seealso>.
       </item>
-      <item><c>mnesia:dirty_index_read(Tab, SecondaryKey, Pos)</c>. This
-       function is the dirty equivalent of <c>mnesia:index_read/3</c>. 
+      <item><seealso marker="mnesia#dirty_index_read/3">mnesia:dirty_index_read(Tab, SecondaryKey, Pos)</seealso>
+       is the dirty equivalent of
+       <seealso marker="mnesia#index_read/3">mnesia:index_read/3</seealso>.
       </item>
-      <item><c>mnesia:dirty_all_keys(Tab)</c>. This function is the
-       dirty equivalent of <c>mnesia:all_keys/1</c>. 
+      <item><seealso marker="mnesia#dirty_all_keys/1">mnesia:dirty_all_keys(Tab)</seealso>
+       is the dirty equivalent of <seealso marker="mnesia#all_keys/1">
+mnesia:all_keys/1</seealso>.
       </item>
     </list>
   </section>
@@ -593,42 +562,38 @@ The behavior of this function is undefined if the
   <section>
     <marker id="recordnames_tablenames"></marker>
     <title>Record Names versus Table Names</title>
-    <p>In Mnesia, all records in a table must have the same name. All
-      the records must be instances of the same
-      record type. The record name does however not necessarily be
-      the same as the table name. Even though that it is the case in
-      the most of the examples in this document. If a table is created
-      without the <c>record_name</c> property the code below will 
-      ensure all records in the tables have the same name as the table:
-      </p>
+    <p>In <c>Mnesia</c>, all records in a table must have the same name.
+      All the records must be instances of the same
+      record type. The record name, however, does not necessarily have
+      to be the same as the table name, although this is the case in
+      most of the examples in this User's Guide. If a table is created
+      without property <c>record_name</c>, the following code ensures
+      that all records in the tables have the same name as the table:</p>
     <code type="none">
-      mnesia:create_table(subscriber, [])
-    </code>
-    <p>However, if the table is is created with an explicit record name 
-      as argument, as shown below, it is possible to store subscriber 
-      records in both of the tables regardless of the table names:
-      </p>
+      mnesia:create_table(subscriber, [])</code>
+    <p>However, if the table is created with an explicit record name
+      as argument, as shown in the following example, subscriber records
+      can be stored in both of the tables regardless of the table
+      names:</p>
     <code type="none">
       TabDef = [{record_name, subscriber}],
       mnesia:create_table(my_subscriber, TabDef),
-      mnesia:create_table(your_subscriber, TabDef).
-    </code>
-    <p>In order to access such
-      tables it is not possible to use the simplified access functions
-      as described earlier in the document. For example, 
-      writing a subscriber record into a table requires a
-      <c>mnesia:write/3</c>function instead of the simplified functions
-      <c>mnesia:write/1</c> and <c>mnesia:s_write/1</c>:
-      </p>
+      mnesia:create_table(your_subscriber, TabDef).</code>
+    <p>To access such tables, simplified access functions
+      (as described earlier) cannot be used. For example,
+      writing a subscriber record into a table requires the function
+      <seealso marker="mnesia#write/3">mnesia:write/3</seealso>
+      instead of the simplified functions
+      <seealso marker="mnesia#write/1">mnesia:write/1</seealso>
+      and
+      <seealso marker="mnesia#s_write/1">mnesia:s_write/1</seealso>:</p>
     <code type="none">
       mnesia:write(subscriber, #subscriber{}, write)
       mnesia:write(my_subscriber, #subscriber{}, sticky_write)
-      mnesia:write(your_subscriber, #subscriber{}, write)
-    </code>
-    <p>The following simplified piece of code illustrates the
+      mnesia:write(your_subscriber, #subscriber{}, write)</code>
+    <p>The following simple code illustrates the
       relationship between the simplified access functions used in
-      most examples and their more flexible counterparts:
-      </p>
+      most of the examples and their more flexible counterparts:</p>
     <code type="none">
       mnesia:dirty_write(Record) ->
         Tab = element(1, Record),
@@ -676,7 +641,7 @@ The behavior of this function is undefined if the
       
       mnesia:s_delete_object(Record) ->
         Tab = element(1, Record),
-        mnesia:delete_object(Tab, Record. sticky_write).
+        mnesia:delete_object(Tab, Record, sticky_write).
       
       mnesia:read({Tab, Key}) ->
         mnesia:read(Tab, Key, read).
@@ -690,217 +655,222 @@ The behavior of this function is undefined if the
       
       mnesia:index_match_object(Pattern, Attr) ->
         Tab = element(1, Pattern),
-        mnesia:index_match_object(Tab, Pattern, Attr, read).
-    </code>
+        mnesia:index_match_object(Tab, Pattern, Attr, read).</code>
   </section>
 
   <section>
     <title>Activity Concept and Various Access Contexts</title>
-    <p>As previously described, a functional object (Fun) performing
-      table access operations as listed below may be
-      passed on as arguments to the function
-      <c>mnesia:transaction/1,2,3</c>: 
-      </p>
+    <p>As previously described, a Functional Object (Fun) performing
+      table access operations, as listed here, can be passed
+      on as arguments to the function
+      <seealso marker="mnesia#transaction/2">mnesia:transaction/1,2,3</seealso>:
+    </p>
     <list type="bulleted">
       <item>
-        <p>mnesia:write/3 (write/1, s_write/1)</p>
+      <seealso marker="mnesia#write/3">mnesia:write/3 (write/1, s_write/1)</seealso>
       </item>
       <item>
-        <p>mnesia:delete/3 (delete/1, s_delete/1)</p>
+       <seealso marker="mnesia#delete/3">mnesia:delete/3</seealso>
+       (<seealso marker="mnesia#delete/1">mnesia:delete/1</seealso>,
+       <seealso marker="mnesia#s_delete/1">mnesia:s_delete/1</seealso>)
       </item>
       <item>
-        <p>mnesia:delete_object/3 (delete_object/1, s_delete_object/1)</p>
+       <seealso marker="mnesia#delete_object/3">mnesia:delete_object/3</seealso>
+       (<seealso marker="mnesia#delete_object/1">mnesia:delete_object/1</seealso>,
+       <seealso marker="mnesia#s_delete_object/1">mnesia:s_delete_object/1</seealso>)
       </item>
       <item>
-        <p>mnesia:read/3 (read/1, wread/1)</p>
+       <seealso marker="mnesia#read/3">mnesia:read/3</seealso>
+       (<seealso marker="mnesia#read/1">mnesia:read/1</seealso>,
+       <seealso marker="mnesia#wread/1">mnesia:wread/1</seealso>)
       </item>
       <item>
-        <p>mnesia:match_object/2 (match_object/1)</p>
+       <seealso marker="mnesia#match_object/3">mnesia:match_object/2</seealso>
+       (<seealso marker="mnesia#match_object/1">mnesia:match_object/1</seealso>)
       </item>
       <item>
-        <p>mnesia:select/3 (select/2)</p>
+       <seealso marker="mnesia#select/2">mnesia:select/3</seealso>
+       (<seealso marker="mnesia#select/2">mnesia:select/2</seealso>)
       </item>
       <item>
-        <p>mnesia:foldl/3 (foldl/4, foldr/3, foldr/4)</p>
+       <seealso marker="mnesia#foldl/3">mnesia:foldl/3</seealso>
+       (<c>mnesia:foldl/4</c>,
+       <seealso marker="mnesia#foldr/3">mnesia:foldr/3</seealso>,
+       <c>mnesia:foldr/4</c>)
       </item>
       <item>
-        <p>mnesia:all_keys/1</p>
+       <seealso marker="mnesia#all_keys/1">mnesia:all_keys/1</seealso>
       </item>
       <item>
-        <p>mnesia:index_match_object/4 (index_match_object/2)</p>
+       <seealso marker="mnesia#index_match_object/4">mnesia:index_match_object/4</seealso>
+       (<seealso marker="mnesia#index_match_object/2">mnesia:index_match_object/2</seealso>)
       </item>
       <item>
-        <p>mnesia:index_read/3</p>
+       <seealso marker="mnesia#index_read/3">mnesia:index_read/3</seealso>
       </item>
       <item>
-        <p>mnesia:lock/2 (read_lock_table/1, write_lock_table/1)</p>
+       <seealso marker="mnesia#lock/2">mnesia:lock/2</seealso>
+       (<seealso marker="mnesia#read_lock_table/1">mnesia:read_lock_table/1</seealso>,
+       <seealso marker="mnesia#write_lock_table/1">mnesia:write_lock_table/1</seealso>)
       </item>
       <item>
-        <p>mnesia:table_info/2</p>
+       <seealso marker="mnesia#table_info/2">mnesia:table_info/2</seealso>
       </item>
     </list>
-    <p>These functions will be performed in a
-      transaction context involving mechanisms like locking, logging,
-      replication, checkpoints, subscriptions, commit protocols
-      etc.However, the same function may also be
-      evaluated in other activity contexts. 
-            <br></br>
-The following activity access contexts are currently supported:
-      </p>
+    <p>These functions are performed in a
+      transaction context involving mechanisms, such as locking, logging,
+      replication, checkpoints, subscriptions, and commit protocols.
+      However, the same function can also be
+      evaluated in other activity contexts.</p>
+    <p>The following activity access contexts are currently supported:</p>
     <list type="bulleted">
-      <item>
-        <p>transaction      </p>
-      </item>
-      <item>
-        <p>sync_transaction</p>
-      </item>
-      <item>
-        <p>async_dirty</p>
-      </item>
-      <item>
-        <p>sync_dirty</p>
-      </item>
-      <item>
-        <p>ets</p>
-      </item>
+      <item><c>transaction</c></item>
+      <item><c>sync_transaction</c></item>
+      <item><c>async_dirty</c></item>
+      <item><c>sync_dirty</c></item>
+      <item><c>ets</c></item>
     </list>
     <p>By passing the same "fun" as argument to the function
-      <c>mnesia:sync_transaction(Fun [, Args])</c> it will be performed
-      in synced transaction context. Synced transactions waits until all
+       <seealso marker="mnesia#sync_transaction/3">mnesia:sync_transaction(Fun [, Args])</seealso>
+      it is performed
+      in synced transaction context. Synced transactions wait until all
       active replicas has committed the transaction (to disc) before
-      returning from the mnesia:sync_transaction call.  Using
-      sync_transaction is useful for applications that are executing on
-      several nodes and want to be sure that the update is performed on
-      the remote nodes before a remote process is spawned or a message
-      is sent to a remote process, and also when combining transaction
-      writes with dirty_reads. This is also useful in situations where
-      an application performs frequent or voluminous updates which may
-      overload Mnesia on other nodes.
-      </p>
+      returning from the <c>mnesia:sync_transaction</c> call. Using
+      <c>sync_transaction</c> is useful in the following cases:</p>
+    <list type="bulleted">
+      <item>When an application executes on several nodes and wants to
+       be sure that the update is performed on the remote nodes before
+       a remote process is spawned or a message is sent to a remote
+       process.</item>
+      <item>When a combining transaction writes with "dirty_reads", that
+        is, the functions <c>dirty_match_object</c>, <c>dirty_read</c>,
+        <c>dirty_index_read</c>, <c>dirty_select</c>, and so on.</item>
+      <item>When an application performs frequent or voluminous updates
+       that can overload <c>Mnesia</c> on other nodes.</item>
+    </list>
     <p>By passing the same "fun" as argument to the function
-      <c>mnesia:async_dirty(Fun [, Args])</c> it will be performed in
-      dirty context. The function calls will be mapped to the
-      corresponding dirty functions. This will still involve logging,
-      replication and subscriptions but there will be no locking,
-      local transaction storage or commit protocols involved.
-      Checkpoint retainers will be updated but  will be updated
-      "dirty". Thus, they will be updated asynchronously. The
-      functions will wait for the operation to be performed on one
-      node but not the others. If the table resides locally no waiting
-      will occur.
-      </p>
+       <seealso marker="mnesia#async_dirty/2">mnesia:async_dirty(Fun [, Args])</seealso>,
+      it is performed in dirty context. The function calls are mapped to
+      the corresponding dirty functions. This still involves logging,
+      replication, and subscriptions but no locking,
+      local transaction storage, or commit protocols are involved.
+      Checkpoint retainers are updated but updated
+      "dirty". Thus, they are updated asynchronously. The
+      functions wait for the operation to be performed on one
+      node but not the others. If the table resides locally, no waiting
+      occurs.</p>
     <p>By passing the same "fun" as an argument to the function
-      <c>mnesia:sync_dirty(Fun [, Args])</c> it will be performed in
-      almost the same context as <c>mnesia:async_dirty/1,2</c>. The
-      difference is that the operations are performed
-      synchronously. The caller will wait for the updates to be
-      performed on all active replicas. Using sync_dirty is useful for
-      applications that are executing on several nodes and want to be
-      sure that the update is performed on the remote nodes before a remote
-      process is spawned or a message is sent to a remote process. This
-      is also useful in situations where an application performs frequent or
-      voluminous updates which may overload Mnesia on other
-      nodes.
-      </p>
-    <p>You can check if your code is executed within a transaction with
-      <c>mnesia:is_transaction/0</c>, it returns <c>true</c> when called
-      inside a transaction context and false otherwise.</p>
-
-    <p>Mnesia tables with storage type RAM_copies and disc_copies
-      are implemented internally as "ets-tables" and 
-      it is possible for applications to access the these tables
-      directly. This is only recommended if all options have been weighed
-      and the possible outcomes are understood. By passing the earlier 
-      mentioned "fun" to the function
-      <c>mnesia:ets(Fun [, Args])</c> it will be performed but in a very raw
-      context. The operations will be performed directly on the
-      local ets tables assuming that the local storage type are
-      RAM_copies and that the table is not replicated on other
-      nodes. Subscriptions will not be  triggered nor
-      checkpoints updated, but this operation is blindingly fast. Disc resident
-      tables should not be updated with the ets-function since the
-      disc will not be updated.
-      </p>
-    <p>The Fun may also be passed as an argument to the function
-      <c>mnesia:activity/2,3,4</c> which enables usage of customized
+       <seealso marker="mnesia#sync_dirty/2">mnesia:sync_dirty(Fun [, Args])</seealso>,
+      it is performed in almost the same context as the function
+      <seealso marker="mnesia#async_dirty/2">mnesia:async_dirty/1,2</seealso>.
+      The difference is that the operations are performed
+      synchronously. The caller waits for the updates to be
+      performed on all active replicas. Using <c>mnesia:sync_dirty/1,2</c>
+      is useful in the following cases:</p>
+    <list type="bulleted">
+      <item>When an application executes on several nodes and wants to
+       be sure that the update is performed on the remote nodes before
+       a remote process is spawned or a message is sent to a remote
+       process.</item>
+      <item>When an application performs frequent or voluminous updates
+       that can overload <c>Mnesia</c> on the nodes.</item>
+      </list>
+    <p>To check if your code is executed within a transaction, use
+       the function
+       <seealso marker="mnesia#is_transaction/0">mnesia:is_transaction/0</seealso>.
+      It returns <c>true</c> when called
+      inside a transaction context, otherwise <c>false</c>.</p>
+    <p><c>Mnesia</c> tables with storage type <c>RAM_copies</c> and
+      <c>disc_copies</c> are implemented internally as
+      <c>ets</c> tables. Applications can access the these tables
+      directly. This is only
+      recommended if all options have been weighed and the possible
+      outcomes are understood. By passing the earlier mentioned "fun"
+      to the function
+      <seealso marker="mnesia#ets/2">mnesia:ets(Fun [, Args])</seealso>,
+      it is performed but in a raw
+      context. The operations are performed directly on the
+      local <c>ets</c> tables, assuming that the local storage type is
+      <c>RAM_copies</c> and that the table is not replicated on other
+      nodes.</p>
+    <p>Subscriptions are not triggered and no checkpoints are updated,
+      but this operation is blindingly fast. Disc resident
+      tables are not to be updated with the <c>ets</c> function, as the
+      disc is not updated.</p>
+    <p>The Fun can also be passed as an argument to the function
+      <seealso marker="mnesia#activity-4">mnesia:activity/2,3,4</seealso>,
+      which enables use of customized
       activity access callback modules. It can either be obtained
-      directly by stating the module name as argument or implicitly
-      by usage of the <c>access_module</c> configuration parameter.  A
-      customized callback module may be used for several purposes,
-      such as providing triggers, integrity constraints, run time
-      statistics, or virtual tables.
-            <br></br>
- The callback module does
-      not have to access real Mnesia tables, it is free to do whatever
-      it likes as long as the callback interface is fulfilled.
-            <br></br>
- In Appendix C "The Activity Access Call Back Interface" the source
-      code for one alternate implementation is provided
-      (mnesia_frag.erl). The context sensitive function
-      <c>mnesia:table_info/2</c> may be used to provide virtual
-      information about a table. One usage of this is to perform
+      directly by stating the module name as argument, or implicitly
+      by use of configuration parameter <c>access_module</c>. A
+      customized callback module can be used for several purposes,
+      such as providing triggers, integrity constraints, runtime
+      statistics, or virtual tables.</p>
+    <p>The callback module does not have
+      to access real <c>Mnesia</c> tables, it is free to do whatever
+      it wants as long as the callback interface is fulfilled.</p>
+    <p><seealso marker="Mnesia_App_B">Appendix B,
+      Activity Access Callback Interface</seealso> provides the
+      source code, <c>mnesia_frag.erl</c>, for one alternative
+      implementation. The context-sensitive function
+      <seealso marker="mnesia#table_info/2">mnesia:table_info/2</seealso>
+      can be used to provide virtual
+      information about a table. One use of this is to perform
       <c>QLC</c> queries within an activity context with a
       customized callback module. By providing table information about
-      table indices and other <c>QLC</c> requirements,
-      <c>QLC</c> may be used as a generic query language to
-      access virtual tables.
-      </p>
-    <p>QLC queries may be performed in all these activity
-      contexts (transaction, sync_transaction, async_dirty, sync_dirty
-      and ets). The ets activity will only work if the table has no
-      indices.
-      </p>
+      table indexes and other <c>QLC</c> requirements, <c>QLC</c> can
+      be used as a generic query language to access virtual tables.</p>
+    <p>QLC queries can be performed in all these activity
+      contexts (<c>transaction</c>, <c>sync_transaction</c>,
+      <c>async_dirty</c>, <c>sync_dirty</c>, and <c>ets</c>). The
+      <c>ets</c> activity only works if the table has no indexes.</p>
     <note>
-      <p>The mnesia:dirty_* function always executes with
-        async_dirty semantics regardless of which activity access contexts
-        are invoked. They may even invoke contexts without any
-        enclosing activity access context.</p>
+      <p>The function <c>mnesia:dirty_*</c> always executes with
+        <c>async_dirty</c> semantics regardless of which activity
+        access contexts that are started. It can even start contexts
+        without any enclosing activity access context.</p>
     </note>
   </section>
 
   <section>
-    <title>Nested transactions</title>
-    <p>Transactions may be nested in an arbitrary fashion. A child transaction
-      must run in the same process as its parent. When a child transaction
-      aborts, the caller of the child transaction will get the 
-      return value <c>{aborted, Reason}</c> and any work performed
-      by the child will be erased. If a child transaction commits, the
-      records written by the child will be propagated to the parent.
-      </p>
+    <title>Nested Transactions</title>
+    <p>Transactions can be nested in an arbitrary fashion. A child
+      transaction must run in the same process as its parent. When a
+      child transaction terminates, the caller of the child transaction
+      gets return value <c>{aborted, Reason}</c> and any work performed
+      by the child is erased. If a child transaction commits, the
+      records written by the child are propagated to the parent.</p>
     <p>No locks are released when child transactions terminate. Locks
-      created by a sequence of nested transactions are kept until 
-      the topmost transaction terminates. Furthermore, any updates 
-      performed by a nested transaction are only propagated 
+      created by a sequence of nested transactions are kept until
+      the topmost transaction terminates. Furthermore, any update
+      performed by a nested transaction is only propagated
       in such a manner so that the parent of the nested transaction
-      sees the updates. No final commitment will be done until
-      the top level transaction is terminated.
+      sees the updates. No final commitment is done until
+      the top-level transaction terminates.
       So, although a nested transaction returns <c>{atomic, Val}</c>,
-      if the enclosing parent transaction is aborted, the entire
-      nested operation is aborted.
-      </p>
+      if the enclosing parent transaction terminates, the entire
+      nested operation terminates.</p>
     <p>The ability to have nested transaction with identical semantics
-      as top level transaction makes it easier to write
-      library functions that manipulate mnesia tables.
-      </p>
-    <p>Say for example that we have a function that adds a
-      new subscriber to a telephony system:</p>
+      as top-level transaction makes it easier to write
+      library functions that manipulate <c>Mnesia</c> tables.</p>
+    <p>Consider a function that adds a subscriber to a telephony
+      system:</p>
     <pre>
       add_subscriber(S) ->
           mnesia:transaction(fun() ->
-              case mnesia:read( ..........
-    </pre>
+              case mnesia:read( ..........</pre>
     <p>This function needs to be called as a transaction.
-      Now assume that we wish to write a function that
-      both calls the <c>add_subscriber/1</c> function and
+      Assume that you wish to write a function that
+      both calls the function <c>add_subscriber/1</c> and
       is in itself protected by the context of a transaction.
-      By simply calling the <c>add_subscriber/1</c> from within
-      another transaction, a nested transaction is created.
-      </p>
-    <p>It is also possible to mix different activity access contexts while nesting, 
-      but the dirty ones (async_dirty,sync_dirty and ets) will inherit the transaction
-      semantics if they are called inside a transaction and thus it will grab locks and 
-      use two or three phase commit.
-      </p>
+      By calling <c>add_subscriber/1</c> from within
+      another transaction, a nested transaction is created.</p>
+    <p>Also, different activity access contexts can be mixed while
+      nesting. However, the dirty ones (<c>async_dirty</c>,
+      <c>sync_dirty</c>, and <c>ets</c>) inherit the transaction
+      semantics if they are called inside a transaction and thus
+      grab locks and use two or three phase commit.</p>
+    <p><em>Example:</em></p>
     <pre>
       add_subscriber(S) ->
           mnesia:transaction(fun() ->
@@ -915,17 +885,18 @@ The following activity access contexts are currently supported:
              mnesia:read({some_tab, some_data}),
              mnesia:transaction(fun() ->
                  %% In a transaction context.
-                 case mnesia:read( ..) ..end), end).
-    </pre>
+                 case mnesia:read( ..) ..end), end).</pre>
   </section>
 
   <section>
     <title>Pattern Matching</title>
     <marker id="matching"></marker>
-    <p>When it is not possible to use <c>mnesia:read/3</c> Mnesia
+    <p>When the function
+      <seealso marker="mnesia#read/3">mnesia:read/3</seealso>
+      cannot be used, <c>Mnesia</c>
       provides the programmer with several functions for matching
-      records against a pattern. The most useful functions of these are:
-      </p>
+      records against a pattern. The most useful ones
+      are the following:</p>
     <code type="none">
       mnesia:select(Tab, MatchSpecification, LockKind) ->
           transaction abort | [ObjectList]
@@ -934,170 +905,178 @@ The following activity access contexts are currently supported:
       mnesia:select(Cont) ->
           transaction abort | {[Object],Continuation} | '$end_of_table'
       mnesia:match_object(Tab, Pattern, LockKind) ->
-          transaction abort | RecordList
-    </code>
-    <p>These functions matches a <c>Pattern</c> against all records in
-      table <c>Tab</c>. In a <c>mnesia:select</c> call <c>Pattern</c> is
-      a part of <c>MatchSpecification</c> described below.  It is not
-      necessarily performed as an exhaustive search of the entire
-      table. By utilizing indices and bound values in the key of the
-      pattern, the actual work done by the function may be condensed
-      into a few hash lookups. Using <c>ordered_set</c> tables may reduce the
-      search space if the keys are partially bound.
-      </p>
+          transaction abort | RecordList</code>
+    <p>These functions match a <c>Pattern</c> against all records in
+      table <c>Tab</c>. In a
+      <seealso marker="mnesia#select/2">mnesia:select</seealso>
+      call, <c>Pattern</c> is
+      a part of <c>MatchSpecification</c> described in the following. It
+      is not necessarily performed as an exhaustive search of the entire
+      table. By using indexes and bound values in the key of the
+      pattern, the actual work done by the function can be condensed
+      into a few hash lookups. Using <c>ordered_set</c> tables can reduce
+      the search space if the keys are partially bound.</p>
     <p>The pattern provided to the functions must be a valid record,
       and the first element of the provided tuple must be the
       <c>record_name</c> of the table. The special element <c>'_'</c>
       matches any data structure in Erlang (also known as an Erlang
-      term). The special elements <c><![CDATA['$<number>']]></c> behaves as Erlang
-      variables i.e. matches anything and binds the first occurrence and
-      matches the coming occurrences of that variable against the bound value.
-      </p>
-    <p>Use the function <c>mnesia:table_info(Tab, wild_pattern)</c> 
-      to obtain a  basic pattern which matches all records in a table 
+      term). The special elements <c><![CDATA['$<number>']]></c>
+      behave as Erlang variables, that is, they match anything,
+      bind the first occurrence, and match the
+      coming occurrences of that variable against the bound value.</p>
+    <p>Use function
+      <seealso marker="mnesia#table_info/2">mnesia:table_info(Tab, wild_pattern)</seealso>
+      to obtain a basic pattern, which matches all records in a table,
       or use the default value in record creation.
-      Do not make the pattern hard coded since it will make your code more
-      vulnerable to future changes of the record definition.
-      </p>
+      Do not make the pattern hard-coded, as this makes the code more
+      vulnerable to future changes of the record definition.</p>
+    <p><em>Example:</em></p>
     <code type="none">
       Wildpattern = mnesia:table_info(employee, wild_pattern), 
       %% Or use
-      Wildpattern = #employee{_ = '_'},
-    </code>
-    <p>For the employee table the wild pattern will look like:</p>
+      Wildpattern = #employee{_ = '_'},</code>
+    <p>For the employee table, the wild pattern looks as follows:</p>
     <code type="none">
-      {employee, '_', '_', '_', '_', '_',' _'}.
-    </code>
-    <p>In order to constrain the match you must replace some
+      {employee, '_', '_', '_', '_', '_',' _'}.</code>
+    <p>To constrain the match, it is needed to replace some
       of the <c>'_'</c> elements. The code for matching out
-      all female employees, looks like:
-      </p>
+      all female employees looks as follows:</p>
     <code type="none">
       Pat = #employee{sex = female, _ = '_'},
       F = fun() -> mnesia:match_object(Pat) end,
-      Females = mnesia:transaction(F).
-    </code>
-    <p>It is also possible to use the match function if we want to
-      check the equality of different attributes. Assume that we want
-      to find all employees which happens to have a employee number
-      which is equal to their room number:
-      </p>
+      Females = mnesia:transaction(F).</code>
+    <p>The match function can also be used to check the equality of
+      different attributes. For example, to find all employees with
+      an employee number equal to their room number:</p>
     <code type="none">
       Pat = #employee{emp_no = '$1', room_no = '$1', _ = '_'},
       F = fun() -> mnesia:match_object(Pat) end,
-      Odd = mnesia:transaction(F).
-    </code>
-    <p>The function <c>mnesia:match_object/3</c> lacks some important
-      features that <c>mnesia:select/3</c> have. For example
+      Odd = mnesia:transaction(F).</code>
+    <p>The function
+      <seealso marker="mnesia#match_object/3">mnesia:match_object/3</seealso>
+      lacks some important features that
+      <seealso marker="mnesia#select/2">mnesia:select/3</seealso>
+      have. For example,
       <c>mnesia:match_object/3</c> can only return the matching records,
-      and it can not express constraints other then equality.
-      If we want to find the names of the male employees on the second floor
-      we could write:
-      </p>
+      and it cannot express constraints other than equality. To find
+      the names of the male employees on the second floor:</p>
     <codeinclude file="company.erl" tag="%21" type="erl"></codeinclude>
-    <p>Select can be used to add additional constraints and create
-      output which can not be done with <c>mnesia:match_object/3</c>.  </p>
-    <p>The second argument to select is a <c>MatchSpecification</c>.
-      A <c>MatchSpecification</c> is list of <c>MatchFunctions</c>, where
+    <p>The function <c>select</c> can be used to add more constraints
+      and create output that cannot be done with
+      <c>mnesia:match_object/3</c>.</p>
+    <p>The second argument to <c>select</c> is a <c>MatchSpecification</c>.
+      A <c>MatchSpecification</c> is a list of <c>MatchFunction</c>s, where
       each <c>MatchFunction</c> consists of a tuple containing
-      <c>{MatchHead, MatchCondition, MatchBody}</c>.  <c>MatchHead</c>
-      is the same pattern used in <c>mnesia:match_object/3</c> 
-      described above. <c>MatchCondition</c> is a list of additional
-      constraints applied to each record, and <c>MatchBody</c> is used 
-      to construct the return values.
-      </p>
-    <p>A detailed explanation of match specifications can be found in 
-      the <em>Erts users guide: Match specifications in Erlang </em>,
-      and the ets/dets documentations may provide some additional 
-      information.
-      </p>
-    <p>The functions <c>select/4</c> and <c>select/1</c> are used to
-      get a limited number of results, where the <c>Continuation</c>
-      are used to get the next chunk of results. Mnesia uses the
-      <c>NObjects</c> as an recommendation only, thus more or less
-      results then specified with <c>NObjects</c> may be returned in
-      the result list, even the empty list may be returned despite there
-      are more results to collect.
-      </p>
+      <c>{MatchHead, MatchCondition, MatchBody}</c>:</p>
+    <list type="bulleted">
+      <item><c>MatchHead</c> is the same pattern as used in
+       <c>mnesia:match_object/3</c> described earlier.</item>
+      <item><c>MatchCondition</c> is a list of extra constraints
+       applied to each record.</item>
+      <item><c>MatchBody</c> constructs the return values.</item>
+    </list>
+    <p>For details about the match specifications, see
+      "Match Specifications in Erlang" in
+      <seealso marker="erts:index">ERTS</seealso> User's Guide.
+      For more information, see the
+      <seealso marker="stdlib:ets">ets</seealso> and
+      <seealso marker="stdlib:dets">dets</seealso>
+      manual pages in <c>STDLIB</c>.</p>
+    <p>The functions
+      <seealso marker="mnesia#select/4">select/4</seealso> and
+      <seealso marker="mnesia#select/2">select/1</seealso>
+      are used to
+      get a limited number of results, where <c>Continuation</c>
+      gets the next chunk of results. <c>Mnesia</c> uses
+      <c>NObjects</c> as a recommendation only. Thus, more or less
+      results than specified with <c>NObjects</c> can be returned in
+      the result list, even the empty list can be returned even
+      if there are more results to collect.</p>
     <warning>
       <p>There is a severe performance penalty in using
-        <c>mnesia:select/[1|2|3|4]</c> after any modifying operations
-        are done on that table in the same transaction, i.e. avoid using
-        <c>mnesia:write/1</c> or <c>mnesia:delete/1</c> before a
-        <c>mnesia:select</c> in the same transaction.</p>
+        <c>mnesia:select/[1|2|3|4]</c> after any modifying operation
+        is done on that table in the same transaction. That is, avoid
+        using
+        <seealso marker="mnesia#write/1">mnesia:write/1</seealso> or
+        <seealso marker="mnesia#delete/1">mnesia:delete/1</seealso>
+        before <c>mnesia:select</c> in the same transaction.</p>
     </warning>
     <p>If the key attribute is bound in a pattern, the match operation
-      is very efficient. However, if the key attribute in a pattern is
-      given as <c>'_'</c>, or <c>'$1'</c>, the whole <c>employee</c>
+      is efficient. However, if the key attribute in a pattern is
+      given as <c>'_'</c> or <c>'$1'</c>, the whole <c>employee</c>
       table must be searched for records that match. Hence if the table is
-      large, this can become a time consuming operation, but it can be
-      remedied with indices (refer to Chapter 5: <seealso marker="Mnesia_chap5#indexing">Indexing</seealso>) if
-      <c>mnesia:match_object</c> is used.
-      </p>
-    <p>QLC queries can also be used to search Mnesia tables.  By
-      using <c>mnesia:table/[1|2]</c> as the generator inside a QLC
-      query you let the query operate on a mnesia table.  Mnesia
-      specific options to <c>mnesia:table/2</c> are {lock, Lock},
-      {n_objects,Integer} and {traverse, SelMethod}. The <c>lock</c>
-      option specifies whether mnesia should acquire a read or write
-      lock on the table, and <c>n_objects</c> specifies how many
-      results should be returned in each chunk to QLC. The last option is
-      <c>traverse</c> and it specifies which function mnesia should
-      use to traverse the table. Default <c>select</c> is used, but by using
-      <c>{traverse, {select, MatchSpecification}}</c> as an option to
-      <c>mnesia:table/2</c> the user can specify it's own view of the
-      table.
-      </p>
-    <p>If no options are specified a read lock will acquired and 100
-      results will be returned in each chunk, and select will be used
-      to traverse the table, i.e.:
-      </p>
+      large, this can become a time-consuming operation, but it can be
+      remedied with indexes (see
+      <seealso marker="Mnesia_chap5#indexing">Indexing</seealso>)
+      if the function
+      <seealso marker="mnesia#match_object/1">mnesia:match_object</seealso>
+      is used.</p>
+    <p>QLC queries can also be used to search <c>Mnesia</c> tables. By
+      using the function
+      <seealso marker="mnesia#table/1">mnesia:table/[1|2]</seealso>
+      as the generator inside a QLC
+      query, you let the query operate on a <c>Mnesia</c> table.
+      <c>Mnesia</c>-specific options to <c>mnesia:table/2</c> are
+      <c>{lock, Lock}</c>, <c>{n_objects,Integer}</c>, and
+      <c>{traverse, SelMethod}</c>:</p>
+    <list type="bulleted">
+      <item><c>lock</c> specifies whether <c>Mnesia</c> is to acquire a
+       read or write lock on the table.</item>
+      <item><c>n_objects</c> specifies how many results are to be
+       returned in each chunk to QLC.</item>
+      <item><c>traverse</c> specifies which function <c>Mnesia</c> is
+       to use to traverse the table. Default <c>select</c> is used, but
+       by using <c>{traverse, {select, MatchSpecification}}</c> as an
+       option to
+       <seealso marker="mnesia#table/1">mnesia:table/2</seealso>
+       the user can specify its own view of the table.</item>
+    </list>
+    <p>If no options are specified, a read lock is acquired, 100
+      results are returned in each chunk, and <c>select</c> is used
+      to traverse the table, that is:</p>
     <code type="none">
       mnesia:table(Tab) ->
-          mnesia:table(Tab, [{n_objects,100},{lock, read}, {traverse, select}]).
-    </code>
-    <p>The function <c>mnesia:all_keys(Tab)</c> returns all keys in a
-      table.</p>
+          mnesia:table(Tab, [{n_objects,100},{lock, read}, {traverse, select}]).</code>
+    <p>The function
+      <seealso marker="mnesia#all_keys/1">mnesia:all_keys(Tab)</seealso>
+      returns all keys in a table.</p>
   </section>
 
   <section>
     <title>Iteration</title>
     <marker id="iteration"></marker>
-    <p>Mnesia provides a couple of functions which iterates over all
-      the records in a table. 
-      </p>
+    <p><c>Mnesia</c> provides the following functions that iterate over all
+      the records in a table:</p>
     <code type="none">
       mnesia:foldl(Fun, Acc0, Tab) -> NewAcc | transaction abort
       mnesia:foldr(Fun, Acc0, Tab) -> NewAcc | transaction abort
       mnesia:foldl(Fun, Acc0, Tab, LockType) -> NewAcc | transaction abort
-      mnesia:foldr(Fun, Acc0, Tab, LockType) -> NewAcc | transaction abort
-    </code>
-    <p>These functions iterate over the mnesia table <c>Tab</c> and
-      apply the function <c>Fun</c> to each record. The <c>Fun</c>
-      takes two arguments, the first argument is a record from the
-      table and the second argument is the accumulator. The
-      <c>Fun</c> return a new accumulator. </p>
-    <p>The first time the <c>Fun</c> is applied <c>Acc0</c> will
-      be the second argument. The next time the <c>Fun</c> is called
-      the return value from the previous call, will be used as the 
-      second argument. The term the last call to the Fun returns
-      will be the return value of the <c>fold[lr]</c> function.
-      </p>
-    <p>The difference between <c>foldl</c> and <c>foldr</c> is the 
-      order the table is accessed for <c>ordered_set</c> tables,
-      for every other table type the functions are equivalent.
-      </p>
-    <p><c>LockType</c> specifies what type of lock that shall be 
+      mnesia:foldr(Fun, Acc0, Tab, LockType) -> NewAcc | transaction abort</code>
+    <p>These functions iterate over the <c>Mnesia</c> table <c>Tab</c>
+      and apply the function <c>Fun</c> to each record. <c>Fun</c>
+      takes two arguments, the first is a record from the
+      table, and the second is the accumulator.
+      <c>Fun</c> returns a new accumulator.</p>
+    <p>The first time <c>Fun</c> is applied, <c>Acc0</c> is
+      the second argument. The next time <c>Fun</c> is called,
+      the return value from the previous call is used as the
+      second argument. The term the last call to <c>Fun</c> returns
+      is the return value of the function
+       <seealso marker="mnesia#foldl/3">mnesia:foldl/3</seealso> or
+       <seealso marker="mnesia#foldr/3">mnesia:foldr/3</seealso>.</p>
+    <p>The difference between these functions is the
+      order the table is accessed for <c>ordered_set</c> tables.
+      For other table types the functions are equivalent.</p>
+    <p><c>LockType</c> specifies what type of lock that is to be
       acquired for the iteration, default is <c>read</c>. If
-      records are written or deleted during the iteration a write 
-      lock should be acquired. </p>
-    <p>These functions might be used to find records in a table
-      when it is impossible to write constraints for
-      <c>mnesia:match_object/3</c>, or when you want to perform 
-      some action on certain records.       
-      </p>
-    <p>For example finding all the employees who has a salary 
-      below 10 could look like:</p>
+      records are written or deleted during the iteration, a write
+      lock is to be acquired.</p>
+    <p>These functions can be used to find records in a table
+      when it is impossible to write constraints for the function
+       <seealso marker="mnesia#match_object/3">mnesia:match_object/3</seealso>,
+      or when you want to perform some action on certain records.</p>
+    <p>For example, finding all the employees who have a salary
+      less than 10 can look as follows:</p>
     <code type="none"><![CDATA[
       find_low_salaries() ->
         Constraint = 
@@ -1109,7 +1088,7 @@ The following activity access contexts are currently supported:
         Find = fun() -> mnesia:foldl(Constraint, [], employee) end,
         mnesia:transaction(Find).
     ]]></code>
-    <p>Raising the salary to 10 for everyone with a salary below 10
+    <p>To raise the salary to 10 for everyone with a salary less than 10
       and return the sum of all raises:</p>
     <code type="none"><![CDATA[
       increase_low_salaries() ->
@@ -1124,48 +1103,54 @@ The following activity access contexts are currently supported:
         IncLow = fun() -> mnesia:foldl(Increase, 0, employee, write) end,
         mnesia:transaction(IncLow).
     ]]></code>
-    <p>A lot of nice things can be done with the iterator functions
-      but  some caution should be taken about performance and memory
-      utilization for large tables. </p>
-    <p>Call these iteration functions on nodes that contain a replica of the
-      table. Each call to the function <c>Fun</c> access the table and if the table
-      resides on another node it will generate a lot of unnecessary
-      network traffic. </p>
-    <p>Mnesia also provides some functions that make it possible for
-      the user to iterate over the table. The order of the
-      iteration is unspecified if the table is not of the <c>ordered_set</c> 
-      type.      </p>
+    <p>Many nice things can be done with the iterator functions but take
+      some caution about performance and memory use for large tables.</p>
+    <p>Call these iteration functions on nodes that contain a replica of
+      the table. Each call to the function <c>Fun</c> access the table
+      and if the table resides on another node it generates much
+      unnecessary network traffic.</p>
+    <p><c>Mnesia</c> also provides some functions that make it possible
+      for the user to iterate over the table. The order of the iteration
+      is unspecified if the table is not of type <c>ordered_set</c>:</p>
     <code type="none">
       mnesia:first(Tab) ->  Key | transaction abort
       mnesia:last(Tab)  ->  Key | transaction abort
       mnesia:next(Tab,Key)  ->  Key | transaction abort
       mnesia:prev(Tab,Key)  ->  Key | transaction abort
-      mnesia:snmp_get_next_index(Tab,Index) -> {ok, NextIndex} | endOfTable
-    </code>
-    <p>The order of first/last and next/prev are only valid for
-      <c>ordered_set</c> tables, for all other tables, they are synonyms.
-      When the end of the table is reached the special key
+      mnesia:snmp_get_next_index(Tab,Index) -> {ok, NextIndex} | endOfTable</code>
+    <p>The order of <c>first</c>/<c>last</c> and <c>next</c>/<c>prev</c>
+      is only valid for
+      <c>ordered_set</c> tables, they are synonyms for other tables.
+      When the end of the table is reached, the special key
       <c>'$end_of_table'</c> is returned.</p>
     <p>If records are written and deleted during the traversal, use
-      <c>mnesia:fold[lr]/4</c> with a <c>write</c> lock. Or
-      <c>mnesia:write_lock_table/1</c> when using first and next.</p>
+      the function
+      <seealso marker="mnesia#foldl">mnesia:foldl/3</seealso> or
+      <seealso marker="mnesia#foldr">mnesia:foldr/3</seealso>
+      with a <c>write</c> lock. Or the function
+      <seealso marker="mnesia#write_lock_table/1">mnesia:write_lock_table/1</seealso>
+      when using <c>first</c> and <c>next</c>.</p>
     <p>Writing or deleting in transaction context creates a local copy
-      of each modified record, so modifying each record in a large
-      table uses a lot of memory. Mnesia will compensate for every
+      of each modified record. Thus, modifying each record in a large
+      table uses much memory. <c>Mnesia</c> compensates for every
       written or deleted record during the iteration in a transaction
-      context, which may reduce the performance. If possible avoid writing 
+      context, which can reduce the performance. If possible, avoid writing
       or deleting records in the same transaction before iterating over the
       table.</p>
-    <p>In dirty context, i.e. <c>sync_dirty</c> or <c>async_dirty</c>,
+    <p>In dirty context, that is, <c>sync_dirty</c> or <c>async_dirty</c>,
       the modified records are not stored in a local copy; instead,
-      each record is updated separately. This generates a lot of
+      each record is updated separately. This generates much
       network traffic if the table has a replica on another node and
       has all the other drawbacks that dirty operations
-      have. Especially for the <c>mnesia:first/1</c> and
-      <c>mnesia:next/2</c> commands, the same drawbacks as described
-      above for <c>dirty_first</c> and <c>dirty_next</c> applies, i.e. 
-      no writes to the table should be done during iteration.</p>
-    <p></p>
+      have. Especially for commands
+      <seealso marker="mnesia#first/1">mnesia:first/1</seealso> and
+      <seealso marker="mnesia#next/2">mnesia:next/2</seealso>,
+      the same drawbacks as described previously for
+      <seealso marker="mnesia#dirty_first/1">mnesia:dirty_first/1</seealso>
+      and
+      <seealso marker="mnesia#dirty_next/2">mnesia:dirty_next/2</seealso>
+      applies, that
+      is, no writing to the table is to be done during iteration.</p>
   </section>
 </chapter>