From ddb3f48847326f5ba813b913b14e7d2c73b53521 Mon Sep 17 00:00:00 2001 From: Carl Gay Date: Mon, 14 Sep 2020 02:52:21 +0000 Subject: [PATCH] doc: minor cleanups for language differences and extensions --- .../language-extensions/for-iteration.rst | 11 +++-- .../language-extensions/index.rst | 26 ++++++----- .../language-differences.rst | 44 +++++++++---------- 3 files changed, 41 insertions(+), 40 deletions(-) diff --git a/documentation/source/library-reference/language-extensions/for-iteration.rst b/documentation/source/library-reference/language-extensions/for-iteration.rst index e95b904f7e..d9b1e90493 100644 --- a/documentation/source/library-reference/language-extensions/for-iteration.rst +++ b/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 diff --git a/documentation/source/library-reference/language-extensions/index.rst b/documentation/source/library-reference/language-extensions/index.rst index 9f2833fcd9..c920983a64 100644 --- a/documentation/source/library-reference/language-extensions/index.rst +++ b/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 -`_ 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 ` 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 diff --git a/documentation/source/library-reference/language-extensions/language-differences.rst b/documentation/source/library-reference/language-extensions/language-differences.rst index 768af91086..71b15dcea8 100644 --- a/documentation/source/library-reference/language-extensions/language-differences.rst +++ b/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