WIP -- cleanups for language differences and extensions

Author: cgay

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,24 @@
 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?
+.. TODO: what about simple-profiling, simple-timing, byte-vector, threads, ...?
 
-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,15 @@ 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
+     The *test-function* return value 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::
 
        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* return value must compute the hash code of a key. Its
+     signature must be::
 
        hash-function *key* *initial-state* => *id* *result-state*
 
@@ -60,8 +62,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 +83,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