From d158302f1cd426a79c32e2fdc0f3c1f37ba9dc69 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Tue, 11 Mar 2008 13:32:39 +0000
Subject: [PATCH] req-trans and flatten doc clarifications

svn: r8946
---
 collects/scribblings/reference/pairs.scrbl    | 34 ++++++++++++-------
 .../scribblings/reference/stx-trans.scrbl     | 11 ++++--
 2 files changed, 29 insertions(+), 16 deletions(-)

diff --git a/collects/scribblings/reference/pairs.scrbl b/collects/scribblings/reference/pairs.scrbl
index 2596b1d9ac..fcab74070e 100644
--- a/collects/scribblings/reference/pairs.scrbl
+++ b/collects/scribblings/reference/pairs.scrbl
@@ -41,6 +41,11 @@
             #'(defproc (name [v contract]) any/c
                 "Returns " (to-element 'equiv)))))]))
 
+
+@(define list-eval (make-base-eval))
+@interaction-eval[#:eval list-eval (require scheme/list)]
+
+
 @title[#:tag "pairs"]{Pairs and Lists}
 
 A @deftech{pair} combines exactly two values. The first value is
@@ -269,18 +274,6 @@ Like @scheme[foldl], but the lists are traversed from right to left.
 (foldr (lambda (v l) (cons (add1 v) l)) '() '(1 2 3 4))
 ]}
 
-@defproc[(flatten [x any/c])
-         list?]{
-
-Flattens an arbitrary S-expression structure of pairs to a list.  Note
-that this function never raises an error, since all values are valid
-S-expressions.
-
-@examples[
-(flatten '((x) x (x (x) x) ()))
-(flatten 'x)
-]}
-
 @; ----------------------------------------
 @section{List Filtering}
 
@@ -447,7 +440,7 @@ Like @scheme[assoc], but finds an element using the predicate
 @defc_r[d d d d]
 
 @; ----------------------------------------
-@section{List Synonyms}
+@section{List Synonyms and More}
 
 @note-lib[scheme/list]
 
@@ -481,6 +474,21 @@ Like @scheme[assoc], but finds an element using the predicate
 
 @defproc[(last [lst list?]) any]{Returns the last element of the list.}
 
+@defproc[(flatten [v any/c])
+         list?]{
+
+Flattens an arbitrary S-expression structure of pairs into a
+list. More precisely, @scheme[v] is treated as a binary tree where
+pairs are interior nodes, and the resulting list contains all of the
+non-@scheme[null] leaves of the tree in the same order as an inorder
+traversal.
+
+@examples[
+#:eval list-eval
+(flatten '((a) b (c (d) . e) ()))
+(flatten 'a)
+]}
+
 @; ----------------------------------------
 @section{Immutable Cyclic Data}
 
diff --git a/collects/scribblings/reference/stx-trans.scrbl b/collects/scribblings/reference/stx-trans.scrbl
index 725e59ef1c..95ff58f429 100644
--- a/collects/scribblings/reference/stx-trans.scrbl
+++ b/collects/scribblings/reference/stx-trans.scrbl
@@ -532,8 +532,12 @@ See also @scheme[define-require-syntax], which supports macro-style
                  (listof import-source?))]{
 
 Expands the given @scheme[_require-spec] to lists of imports and
-import sources.  Note that the import sources specify modules to be
-visited, so this list is independent of the imports list.}
+import sources.  The latter specifies modules to be
+@tech{instantiate}d or @tech{visit}ed, so the modules that it
+represents should be a superset of the modules represented in the
+former list (so that a module will be @tech{instantiate}d or
+@tech{visit}ed even if all of imports are eventually filtered from the
+former list).}
 
 
 @defproc[(make-require-transformer [proc ((syntax?) . ->* . ((listof import?)
@@ -600,7 +604,8 @@ A structure representing a single imported identifier:
                           [mode (or/c exact-integer? false/c)])]{
 
 A structure representing an imported module, which must be
-instantiated or visited even if no binding is imported into a module.
+@tech{instantiate}d or @tech{visit}ed even if no binding is imported
+into a module.
 
 @itemize{