doc: minor cleanups for language differences and extensions (#1616)

documentation/source/library-reference/language-extensions/for-iteration.rst

@@ -1,8 +1,11 @@
-Extensions to the FOR iteration construct
------------------------------------------
+.. index:: pair: for; keyed-by
+.. index:: pair: for; using
+
+Extensions to the FOR iteration macro
+-------------------------------------
 
 We have also made two extensions to the ``for`` iteration construct: a
-``keyed-by`` clause and ``in … using`` clauses.
+``keyed-by`` clause and ``in ... using`` clauses.
 
 The ``keyed-by`` clause allows iteration over table elements:
 
@@ -12,7 +15,7 @@ The ``keyed-by`` clause allows iteration over table elements:
       ...
     end;
 
-The ``in … using`` clause allows you to specify a iteration protocol
+The ``in ... using`` clause allows you to specify a iteration protocol
 other than the default (:drm:`forward-iteration-protocol`):
 
 .. code-block:: dylan

documentation/source/library-reference/language-extensions/index.rst

@@ -2,21 +2,23 @@
 Dylan Language Extensions
 *************************
 
-The Dylan language is described in `The Dylan Reference Manual
-<https://opendylan.org/books/drm/>`_ by Andrew Shalit (Addison-Wesley,
-1996). We call this book "the DRM" hereafter.
+.. TODO: how do the ../dylan/ documents (finalization, primitives, threads) fit in?
 
-Open Dylan provides an implementation of the Dylan language
-described by the DRM, with a few exceptions that are documented in
-:doc:`language-differences`.
+.. current-library:: common-dylan
+.. current-module:: common-dylan
 
-Open Dylan provides the Dylan language in the ``dylan`` module of the
-``dylan`` library.
+The Dylan language is described in the :drm:`Dylan Reference Manual <Title>` by
+Andrew Shalit (Addison-Wesley, 1996), hereafter referred to as "the DRM".
 
-This document is an introduction to Open Dylan's extensions to the
-Dylan language.  These extensions are either built in to the ``dylan``
-library or are available in a separate library, :doc:`common-dylan
-<../common-dylan/index>`.
+The ways in which Open Dylan differs from the DRM are documented in
+:doc:`language-differences`. The rest of this document describes features added
+to the language while retaining compatibility with the DRM.  These extensions
+are either built in to the ``dylan`` library or are available in a separate
+library, :doc:`common-dylan <../common-dylan/index>`.
+
+The :doc:`common-dylan <../common-dylan/index>` library exports the
+:mod:`common-dylan:common-dylan` module and several other very frequently used
+modules.
 
 The majority of the extensions are in the :doc:`common-extensions
 <../common-dylan/common-extensions>` module

documentation/source/library-reference/language-extensions/language-differences.rst

@@ -4,6 +4,9 @@ Language Differences
 .. current-library:: dylan
 .. current-module:: dylan
 
+This document describes the ways in which Open Dylan differs from the
+specification in the :drm:`Dylan Reference Manual <Title>`.
+
 Note that in addition to the intentional differences documented below, there
 are several `known bugs
 <https://github.com/dylan-lang/opendylan/issues?q=is%3Aissue+is%3Aopen+label%3ADRM>`_
@@ -23,8 +26,7 @@ achieved by returning the argument *hash-state* unchanged as the result
 protocol.
 
 This section describes the items that have been changed. We also provide
-a Table-extensions module, which you can read about in
-:doc:`../collections/table-extensions`.
+a :doc:`table-extensions module <../collections/table-extensions>`.
 
 .. generic-function:: table-protocol
    :open:
@@ -42,15 +44,14 @@ a Table-extensions module, which you can read about in
      Returns the functions used to iterate over tables. These functions are
      in turn used to implement the other collection operations on :drm:`<table>`.
 
-     The *test-function* argument is for the table test function, which is
-     used to compare table keys. It returns true if, according to the table's
-     equivalence predicate, the keys are members of the same equivalence
-     class. Its signature must be::
+     The *test-function* is used to compare table keys. It returns true if,
+     according to the table's equivalence predicate, the keys are members of
+     the same equivalence class. Its signature must be::
 
        test-function *key1* *key2* => *boolean*
 
-     The *hash-function* argument is for the table hash function, which
-     computes the hash code of a key. Its signature must be::
+     The *hash-function* must compute the hash code of a key. Its signature
+     must be::
 
        hash-function *key* *initial-state* => *id* *result-state*
 
@@ -60,8 +61,8 @@ a Table-extensions module, which you can read about in
      hash code is returned as two values: an integer *id* and a hash-state
      *result-state*. This *result-state* is obtained by merging the
      *initial-state* with the hash-state that results from hashing *key*.
-     The *result-state* may or may not be == to *initial-state*. The
-     *initial-state* could be modified by this operation.
+     The *result-state* may or may not be :drm:`==` to *initial-state*. The
+     *initial-state* may be modified by this operation.
 
 .. function:: merge-hash-ids
 
@@ -81,20 +82,15 @@ a Table-extensions module, which you can read about in
      generate a hash ID for an object by combining hash IDs of some of
      its parts.
 
-     The *id1*, *id2* arguments and the return value *merged-id* are all
-     integers.
-
-     The *ordered* argument is a boolean, and determines whether the
-     algorithm used to the merge the IDs is permitted to be
-     order-dependent. If false (the default), the merged result must be
-     independent of the order in which the arguments are provided. If
-     true, the order of the arguments matters because the algorithm used
-     need not be either commutative or associative. It is best to
-     provide a true value for *ordered* when possible, as this may
-     result in a better distribution of hash IDs. However, *ordered*
-     must only be true if that will not cause the hash function to
-     violate the second constraint on hash functions, described on page
-     :drm:`123 of the DRM <Tables#XREF-1049>`.
+     The *ordered* argument determines whether the algorithm used to merge the
+     IDs is permitted to be order-dependent. If false (the default), the merged
+     result must be independent of the order in which the arguments are
+     provided. If true, the order of the arguments matters because the
+     algorithm used need not be either commutative or associative. It is best
+     to provide a true value for *ordered* when possible, as this may result in
+     a better distribution of hash IDs. However, *ordered* must only be true if
+     that will not cause the hash function to violate the second constraint on
+     hash functions, :drm:`described in the DRM <Tables#XREF-1049>`.
 
 .. function:: object-hash