new guide section on parameterize and other doc tweaks

svn: r12953

collects/scribblings/guide/case.scrbl

@@ -4,7 +4,7 @@
           "guide-utils.ss"
           (for-label scheme/match))
 
-@title{Simple Dispatch: @scheme[case]}
+@title[#:tag "case"]{Simple Dispatch: @scheme[case]}
 
 The @scheme[case] form dispatches to a clause by matching the result
 of an expression to the values for the clause:

collects/scribblings/guide/forms.scrbl

@@ -90,3 +90,4 @@ form, a @scheme[_thing] is either an identifier or a keyword.
 @include-section["quote.scrbl"]
 @include-section["qq.scrbl"]
 @include-section["case.scrbl"]
+@include-section["parameterize.scrbl"]

collects/scribblings/guide/parameterize.scrbl

@@ -0,0 +1,67 @@
+#lang scribble/doc
+@(require scribble/manual
+          scribble/eval
+          "guide-utils.ss")
+
+@title[#:tag "parameterize"]{Dynamic Binding: @scheme[parameterize]}
+
+The @scheme[parameterize] form supports a kind of dynamic binding that
+is useful for adjusting defaults or passing extra arguments through
+layers of function calls. The settings that are adjusted by a
+@scheme[parameterize] form are called @deftech{parameters}.
+
+@margin-note{The term ``parameter'' is sometimes used to refer to the
+             arguments of a function, but ``parameter'' in PLT Scheme
+             has the more specific meaning described here.}
+
+@specform[(parameterize ([parameter-expr value-expr] ...)
+            body ...+)]
+
+The result of a @scheme[parameterize] form is the result of the last
+@scheme[_body] expression. While the @scheme[_body] expressions are
+evaluated, the parameter produced by each @scheme[_parameter-expr] is
+set to the result of the corresponding @scheme[_value-expr].
+
+Many parameters are built in. For example, the
+@scheme[error-print-width] parameter controls how many characters of a
+value are printed in an error message (in case the printed form of the
+value is very large):
+
+@interaction[
+(parameterize ([error-print-width 10]) 
+  (car (expt 10 1024)))
+(parameterize ([error-print-width 5])
+  (car (expt 10 1024)))
+]
+
+The @scheme[error-print-width] parameter acts like a kind of default
+argument to the function that formats error messages. This
+parameter-based argument can be configured far from the actual call to
+the error-formatting function, which in this case is called deep
+within the implementation of @scheme[car].
+
+The @scheme[parameterize] form adjusts the value of a parameter only
+while evaluating its body expressions. After the body produces a
+value, the parameter reverts to its previous value. If control escapes
+from the body due to an exception, as in the above example, then the
+parameter value is restored in that case, too. Finally, parameter
+values are thread-specific, so that multiple threads do not interfere
+with each others' settings.
+
+Use @scheme[make-parameter] to create a new parameter that works with
+@scheme[parameterize]. The argument to @scheme[make-parameter] is the
+value of the parameter when it is not otherwise set by
+@scheme[parameterize]. To access the current value of the parameter,
+call it like a function.
+
+@interaction[
+(define favorite-flavor (make-parameter 'chocolate))
+(favorite-flavor)
+(define (scoop)
+  `(scoop of ,(favorite-flavor)))
+(define (ice-cream n)
+  (list (scoop) (scoop) (scoop)))
+(parameterize ([favorite-flavor 'strawberry])
+  (ice-cream 3))
+(ice-cream 3)
+]

collects/scribblings/more/more.scrbl

@@ -4,6 +4,7 @@
           scribble/eval
           "../quick/keep.ss"
           (for-label scheme
+                     scheme/enter
                      readline
                      net/url
                      xml
@@ -422,7 +423,7 @@ To parse the incoming URL and to more easily format HTML output, we'll
 require two extra libraries:
 
 @schemeblock[
-(require net/url xml)
+(require xml net/url)
 ]
 
 The @schememodname[xml] library gives us @scheme[xexpr->string], which
@@ -582,15 +583,12 @@ connection. Inside @scheme[accept-and-handle], after the definition of
 
 @whole-prog["7"]
 
-We're assuming that 50MB should be plenty for any servlet. Due to the
-way that memory accounting is defined, @scheme[cust] might also be
-charged for the core server implementation and all of the libraries
-loaded on start-up, so the limit cannot be too small. Also,
-garbage-collector overhead means that the actual memory use of the
-system can be some small multiple of 50 MB. An important guarantee,
-however, is that different connections will not be charged for each
-other's memory use, so one misbehaving connection will not interfere
-with a different one.
+We're assuming that 50MB should be plenty for any
+servlet. Garbage-collector overhead means that the actual memory use
+of the system can be some small multiple of 50 MB. An important
+guarantee, however, is that different connections will not be charged
+for each other's memory use, so one misbehaving connection will not
+interfere with a different one.
 
 So, with the new line above, and assuming that you have a couple of
 hundred megabytes available for the @exec{mzscheme} process to use,

collects/scribblings/reference/class.scrbl

@@ -75,6 +75,8 @@
 
 @title[#:tag "mzlib:class" #:style 'toc]{Classes and Objects}
 
+@guideintro["classes"]{classes and objects}
+
 @note-lib[scheme/class #:use-sources (scheme/private/class-internal)]
 
 A @deftech{class} specifies

collects/scribblings/reference/match.scrbl

@@ -8,6 +8,8 @@
 
 @title[#:tag "match"]{Pattern Matching}
 
+@guideintro["match"]{pattern matching}
+
 The @scheme[match] form and related forms support general pattern
 matching on Scheme values. See also @secref["regexp"] for information
 on regular-expression matching on strings, bytes, and streams.

collects/scribblings/reference/parameters.scrbl

@@ -3,6 +3,8 @@
 
 @title[#:tag "parameters"]{Parameters}
 
+@guideintro["parameterize"]{parameters}
+
 See @secref["parameter-model"] for basic information on the
 parameter model. Parameters correspond to @defterm{preserved thread
 fluids} in Scsh @cite["Gasbichler02"].
@@ -45,6 +47,8 @@ applied to the initial @scheme[v].}
 @defform[(parameterize ((parameter-expr value-expr) ...)
            body ...+)]{
 
+@guideintro["parameterize"]{@scheme[parameterize]}
+
 The result of a @scheme[parameterize] expression is the result of the
 last @scheme[body]. The @scheme[parameter-expr]s determine the
 parameters to set, and the @scheme[value-expr]s determine the