From b6391ebfdd0cd710b632714b61305edf401fa602 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Sun, 27 May 2007 00:00:11 +0000
Subject: [PATCH] guide edits

svn: r6342
---
 collects/scribble/html-render.ss             |  2 +-
 collects/scribble/scheme.ss                  | 12 +++
 collects/scribble/scribble.css               |  3 +-
 collects/scribblings/guide/booleans.scrbl    | 25 ++++++
 collects/scribblings/guide/data.scrbl        | 26 ++----
 collects/scribblings/guide/guide.scrbl       |  2 +
 collects/scribblings/guide/hash-tables.scrbl | 69 +++++++++++++++
 collects/scribblings/guide/pairs.scrbl       | 90 ++++++++++++++++++++
 collects/scribblings/guide/symbols.scrbl     | 86 +++++++++++++++++++
 collects/scribblings/guide/syntax.scrbl      |  2 +-
 collects/scribblings/reference/data.scrbl    |  2 +-
 11 files changed, 294 insertions(+), 25 deletions(-)
 create mode 100644 collects/scribblings/guide/booleans.scrbl
 create mode 100644 collects/scribblings/guide/hash-tables.scrbl
 create mode 100644 collects/scribblings/guide/pairs.scrbl
 create mode 100644 collects/scribblings/guide/symbols.scrbl

diff --git a/collects/scribble/html-render.ss b/collects/scribble/html-render.ss
index 06f4c5711a..b5e353992c 100644
--- a/collects/scribble/html-render.ss
+++ b/collects/scribble/html-render.ss
@@ -183,7 +183,7 @@
 
       (define/override (render-table t part ht)
         `((table ((cellspacing "0") ,@(case (table-style t)
-                                        [(boxed) '((width "100%") (bgcolor "lightgray"))]
+                                        [(boxed) '((width "100%") (bgcolor "#E8E8FF"))]
                                         [(centered) '((align "center"))]
                                         [(at-right) '((align "right"))]
                                         [(at-left) '((align "left"))]
diff --git a/collects/scribble/scheme.ss b/collects/scribble/scheme.ss
index afc858a47c..2d0f57d1c8 100644
--- a/collects/scribble/scheme.ss
+++ b/collects/scribble/scheme.ss
@@ -248,6 +248,18 @@
                    p-color)
               (set! src-col (+ src-col 1))
               (hash-table-put! col-map src-col dest-col))]
+           [(hash-table? (syntax-e c))
+            (advance c init-line!)
+            (let ([equal-table? (hash-table? (syntax-e c) 'equal)])
+              (out (if equal-table?
+                       "#hash"
+                       "#hasheq")
+                   value-color)
+              (set! src-col (+ src-col 5 (if equal-table? 2 0)))
+              (hash-table-put! col-map src-col dest-col)
+              ((loop init-line! +inf.0)
+               (syntax-ize (hash-table-map (syntax-e c) cons)
+                           (syntax-column c))))]
            [else
             (advance c init-line!)
             (let-values ([(s it? sub?)
diff --git a/collects/scribble/scribble.css b/collects/scribble/scribble.css
index 4641e4d937..273adc27d1 100644
--- a/collects/scribble/scribble.css
+++ b/collects/scribble/scribble.css
@@ -18,11 +18,12 @@
                }
 
                .refcontent { 
-                background-color: beige;
+                background-color: #F5F5DC;
                 display: block;
                 position: relative;
                 width: 10em;
                 font-size: 85%;
+                border: 0.5em solid #F5F5DC;
                }
 
                h1,h2,h3,h4,h5,h6 {
diff --git a/collects/scribblings/guide/booleans.scrbl b/collects/scribblings/guide/booleans.scrbl
new file mode 100644
index 0000000000..f4fd1e7531
--- /dev/null
+++ b/collects/scribblings/guide/booleans.scrbl
@@ -0,0 +1,25 @@
+#reader(lib "docreader.ss" "scribble")
+@require[(lib "manual.ss" "scribble")]
+@require[(lib "eval.ss" "scribble")]
+@require["guide-utils.ss"]
+
+@title{Booleans}
+
+Scheme has two distinguished constants to represent boolean values:
+@scheme[#t] for true and @scheme[#f] for false. Uppercase
+@schemevalfont{#T} and @schemevalfont{#F} are parsed as the same
+values, but the lowercase forms are preferred.
+
+The @scheme[boolean?] procedure recognizes the two boolean
+constants. In the result of a test expression for @scheme[if],
+@scheme[cond], @scheme[and], @scheme[or], etc., however, any value
+other than @scheme[#f] counts as true.
+
+@examples[
+(= 2 (+ 1 1))
+(boolean? #t)
+(boolean? #f)
+(boolean? "no")
+(if "no" 1 0)
+]
+
diff --git a/collects/scribblings/guide/data.scrbl b/collects/scribblings/guide/data.scrbl
index 44582a1c83..1da811ee30 100644
--- a/collects/scribblings/guide/data.scrbl
+++ b/collects/scribblings/guide/data.scrbl
@@ -3,7 +3,7 @@
 @require[(lib "eval.ss" "scribble")]
 @require["guide-utils.ss"]
 
-@title[#:tag "datatypes" #:style 'toc]{Built-In and Programmer-Defined Datatypes}
+@title[#:tag "datatypes" #:style 'toc]{Built-In Datatypes}
 
 The @seclink["to-scheme"]{little Scheme section} introduced some of
 Scheme's built-in datatype: numbers, booleans, strings, lists, and
@@ -14,28 +14,12 @@ class-based object system to @secref["classes"].
 
 @local-table-of-contents[]
 
-@section{Booleans}
-
-Scheme has two distinguished constants to represent boolean values:
-@scheme[#t] for true and @scheme[#f] for false. Uppercase
-@schemevalfont{#T} and @schemevalfont{#F} are parsed as the same
-values, but the lowercase forms are preferred.
-
-The @scheme[boolean?] procedure recognizes the two boolean
-constants. In the result of a test expression for @scheme[if],
-@scheme[cond], @scheme[and], @scheme[or], etc., however, any value
-other than @scheme[#f] counts as true.
-
-@examples[
-(= 2 (+ 1 1))
-(boolean? #t)
-(boolean? #f)
-(boolean? "no")
-(if "no" 1 0)
-]
-
+@include-section["booleans.scrbl"]
 @include-section["numbers.scrbl"]
 @include-section["chars.scrbl"]
 @include-section["char-strings.scrbl"]
 @include-section["byte-strings.scrbl"]
+@include-section["symbols.scrbl"]
+@include-section["pairs.scrbl"]
 @include-section["vectors.scrbl"]
+@include-section["hash-tables.scrbl"]
diff --git a/collects/scribblings/guide/guide.scrbl b/collects/scribblings/guide/guide.scrbl
index dc50443870..b5ede55f4e 100644
--- a/collects/scribblings/guide/guide.scrbl
+++ b/collects/scribblings/guide/guide.scrbl
@@ -24,6 +24,8 @@ precise details to @|MzScheme| and other reference manuals.
 
 @include-section["data.scrbl"]
 
+@section{Programmer-Defined Datatypes}
+
 @; ----------------------------------------------------------------------
 @section[#:tag "scheme-forms"]{Programs and Expressions}
 
diff --git a/collects/scribblings/guide/hash-tables.scrbl b/collects/scribblings/guide/hash-tables.scrbl
new file mode 100644
index 0000000000..cc82c3f1bc
--- /dev/null
+++ b/collects/scribblings/guide/hash-tables.scrbl
@@ -0,0 +1,69 @@
+#reader(lib "docreader.ss" "scribble")
+@require[(lib "manual.ss" "scribble")]
+@require[(lib "eval.ss" "scribble")]
+@require["guide-utils.ss"]
+
+@title[#:tag "hash-tables"]{Hash Tables}
+
+A @defterm{hash table} implements a maping from keys to values, where
+both keys can values can be arbitrary Scheme values, and access and
+update to the tabel are normally constant-time operations. Keys are
+compared using @scheme[equal?] or @scheme[eq?], depending on whether
+the hash table is created with @scheme['equal] or @scheme['eq].
+
+@examples[
+(define ht (make-hash-table 'equal))
+(hash-table-put! ht "apple" '(red round))
+(hash-table-put! ht "banana" '(yellow long))
+(hash-table-get ht "apple")
+(hash-table-get ht "coconut")
+(hash-table-get ht "coconut" "not there")
+]
+
+A literal hash table can be written as an expression by using
+@schemefont{#hash} (for an @scheme[equal?]-based table) or
+@schemefont{#hasheq} (for an @scheme[eq?]-based table). A parenthesized
+sequence must immediately follow @schemefont{#hash} or
+@schemefont{#hasheq}, where each element is a sequence is a dotted
+key--value pair. Literal hash tables are immutable.
+
+@examples[
+(define ht #hash(("apple" . (red round))
+                 ("banana" . (yellow long))))
+(hash-table-get ht "apple")
+]
+
+@refdetails["mz:parse-hashtable"]{the syntax of hash table literals}
+
+A hash table can optionally retain its keys @defterm{weakly}, so the
+mapping is retained only so long as the key is retained elsewhere.
+
+@examples[
+(define ht (make-hash-table 'weak))
+(hash-table-put! ht (gensym) "can you see me?")
+(collect-garbage)
+(eval:alts (hash-table-count ht) 0)
+]
+
+Beware that a weak hash table retains its values strongly, as long as
+the corresponding key is accessible. This creates a catch-22
+dependency in the case that a value refers back to its key, so that
+the mapping is retained permanently. To break the cycle, map the key
+to an @seclink["ephemerons"]{ephemeron} that pair the value with its
+key (in addition to the implicit pairing of the hash table).
+
+@examples[
+(define ht (make-hash-table 'weak))
+(let ([g (gensym)])
+  (hash-table-put! ht g (list g)))
+(collect-garbage)
+(eval:alts (hash-table-count ht) 1)
+]
+
+@interaction[
+(define ht (make-hash-table 'weak))
+(let ([g (gensym)])
+  (hash-table-put! ht g (make-ephemeron g (list g))))
+(collect-garbage)
+(eval:alts (hash-table-count ht) 0)
+]
diff --git a/collects/scribblings/guide/pairs.scrbl b/collects/scribblings/guide/pairs.scrbl
new file mode 100644
index 0000000000..0ed80d71aa
--- /dev/null
+++ b/collects/scribblings/guide/pairs.scrbl
@@ -0,0 +1,90 @@
+#reader(lib "docreader.ss" "scribble")
+@require[(lib "manual.ss" "scribble")]
+@require[(lib "eval.ss" "scribble")]
+@require["guide-utils.ss"]
+
+@interaction-eval[(require (lib "list.ss"))]
+@interaction-eval[(define mutable-cons cons)]
+
+@title{Pairs and Lists}
+
+A @defterm{pair} joins two arbitrary values. The @scheme[cons]
+procedure constructs pairs, and the @scheme[car] and @scheme[cdr]
+procedures extract the first and second elements of the pair,
+respectively. The @scheme[pair?] predicate recogizes pairs.
+
+Some pairs print by wrapping parentheses around the printed forms of
+the two pair elements, putting a @litchar{.} between them.
+
+@examples[
+(cons 1 2)
+(cons (cons 1 2) 3)
+(car (cons 1 2))
+(cdr (cons 1 2))
+(pair? (cons 1 2))
+]
+
+A @defterm{list} is a combination of pairs that creates a linked
+list. More precisely, a list is either the empty list @scheme[null],
+or it is a pair whose first element is a list element and whose second
+element is a list. The @scheme[list?] predicate recognizes lists. The
+@scheme[null?]  predicate recognizes the empty list.
+
+A list prints as a pair of parentheses wrapped around the list
+elements.
+
+@examples[
+null
+(cons 0 (cons 1 (cons 2 null)))
+(list? null)
+(list? (cons 1 (cons 2 null)))
+(list? (cons 1 2))
+]
+
+An expression with @litchar{'} followed by the printed form of a pair
+or list produces a pair or list constant.
+
+@examples[
+'()
+'(1 . 2)
+'(1 2 3)
+]
+
+A pair can be mutable or immutable. Most pairs are immutable (contrary
+to Lisp tradition), and @scheme[pair?] and @scheme[list?] recognize
+immutable pairs and lists, only. The @scheme[mutable-cons] procedure
+creates a mutable pair, which works with @scheme[set-car!] and
+@scheme[set-cdr!], as well as @scheme[car] and @scheme[cdr].
+
+@examples[
+(define p (mutable-cons 1 2))
+p
+(eval:alts (pair? p) #f)
+(set-car! p 0)
+p
+]
+
+Among the most important predefined proecdures on lists are those that
+iterate through the lists elements:
+
+@interaction[
+(map (lambda (i) (/ 1 i))
+     '(1 2 3))
+(andmap (lambda (i) (i . < . 3))
+       '(1 2 3))
+(ormap (lambda (i) (i . < . 3))
+       '(1 2 3))
+(filter (lambda (i) (i . < . 3))
+        '(1 2 3))
+(foldl (lambda (v i) (+ v i))
+       10
+       '(1 2 3))
+(for-each (lambda (i) (display i))
+          '(1 2 3))
+(member "Keys" 
+        '("Florida" "Keys" "U.S.A."))
+(assoc 'where 
+       '((when "3:30") (where "Florida") (who "Mickey")))
+]
+
+@refdetails["mz:pairs"]{pairs and lists}
diff --git a/collects/scribblings/guide/symbols.scrbl b/collects/scribblings/guide/symbols.scrbl
new file mode 100644
index 0000000000..85ef2e829b
--- /dev/null
+++ b/collects/scribblings/guide/symbols.scrbl
@@ -0,0 +1,86 @@
+#reader(lib "docreader.ss" "scribble")
+@require[(lib "manual.ss" "scribble")]
+@require[(lib "eval.ss" "scribble")]
+@require["guide-utils.ss"]
+
+@title{Symbols}
+
+A @defterm{symbol} is an atomic value that prints like an identifier.
+An expression that starts with @litchar{'} and continues with an
+identifier produces a symbol value.
+
+@examples[
+'a
+(symbol? 'a)
+]
+
+For any sequence of characters, exactly one corresponding symbol is
+@defterm{interned}; the @scheme[string->symbol] procedure or
+@scheme[read]ing a syntactic identifier produces an interned
+symbol. Since interned symbols can be cheaply compared with
+@scheme[eq?] (and thus @scheme[eqv?] or @scheme[equal?]), they serves
+as a convenient values to use for tags and enumerations.
+
+Symbols are case-sensitive. By using a @schemefont{#ci} suffix or in
+other ways, the reader can be made to case-fold character sequences to
+arrive at a symbol, but the reader preserves case by default.
+
+@examples[
+(eq? 'a 'a)
+(eq? 'a (string->symbol "a"))
+(eq? 'a 'b)
+(eq? 'a 'A)
+(eval:alts #, @elem{@schemefont{#ci}@schemevalfont{'A}} #ci'A)
+]
+
+Any string (i.e., any character sequence) can be supplied to
+@scheme[string->symbol] to obtain the corresponding symbol. For reader
+input, any character can appear directly in an identifier, except for
+whitespace and the following special characters:
+
+@t{
+  @hspace[2] @litchar{(} @litchar{)} @litchar{[} @litchar{]} 
+  @litchar["{"] @litchar["}"]
+  @litchar{"} @litchar{,} @litchar{'} @litchar{`}
+  @litchar{;} @litchar{#} @litchar["|"] @litchar["\\"]
+}
+
+Actually, @litchar{#} is disallowed only at the beginning of a symbol,
+and then only if not followed by @litchar{%}; otherwise, @litchar{#} is
+allowed, too. Also, @litchar{.} by itself is not a symbol.
+
+Whitespace or special characters can be included in an identifier by
+quoting them with @litchar["|"] or @litchar["\\"]. These quoting
+mechanisms are used in the printed form of identifiers that contain
+special characters or that might otherwise look like numbers.
+
+@examples[
+(string->symbol "one, two")
+(string->symbol "6")
+]
+
+@refdetails["mz:parse-symbol"]{the syntax of symbols}
+
+The @scheme[display] form of a symbol is the same as the corresponding
+string.
+
+@examples[
+(display 'Apple)
+(display '|6|)
+]
+
+The @scheme[gensym] and @scheme[string->uninterned-symbol] procedures
+generate fresh @defterm{uninterned} symbols that are not equal
+(according to @scheme[eq?]) to any previously interned or uninterned
+symbol. Uninterned symbols are useful as fresh tags that cannot be
+confused with any other value.
+
+@examples[
+(define s (gensym))
+(eval:alts s 'g42)
+(eval:alts (eq? s 'g42) #f)
+(eq? 'a (string->uninterned-symbol "a"))
+]
+
+
+@refdetails["mz:symbols"]{symbols}
diff --git a/collects/scribblings/guide/syntax.scrbl b/collects/scribblings/guide/syntax.scrbl
index ff6bc5a3d0..bc967298aa 100644
--- a/collects/scribblings/guide/syntax.scrbl
+++ b/collects/scribblings/guide/syntax.scrbl
@@ -168,7 +168,7 @@ special characters
   @hspace[2] @litchar{(} @litchar{)} @litchar{[} @litchar{]} 
   @litchar["{"] @litchar["}"]
   @litchar{"} @litchar{,} @litchar{'} @litchar{`}
-  @litchar{;} @litchar{#} 
+  @litchar{;} @litchar{#} @litchar["|"] @litchar["\\"]
 }
 
 and except for the sequences of characters that make number constants,
diff --git a/collects/scribblings/reference/data.scrbl b/collects/scribblings/reference/data.scrbl
index ab8825fe82..6f24fbf6c0 100644
--- a/collects/scribblings/reference/data.scrbl
+++ b/collects/scribblings/reference/data.scrbl
@@ -90,7 +90,7 @@ ephemeron key (see @secref["ephemeron"]).
 @section[#:tag "keywords"]{Keywords}
 
 @; ----------------------------------------------------------------------
-@section[#:tag "pairs"]{Pairs and Lists}
+@section[#:tag "mz:pairs"]{Pairs and Lists}
 
 @defproc[(cons [a any/c] [d any/c]) pair?]{Returns a pair whose first
 element is @scheme[a] and second element is @scheme[d].}