more cross-referencing and icons to help explain margin notes

svn: r6720

collects/scribble/latex-render.ss

@@ -63,6 +63,8 @@
         (printf "\\newcommand{\\schemeinput}[1]{\\colorbox{LightGray}{\\hspace{-0.5ex}\\schemeinputcol{#1}\\hspace{-0.5ex}}}\n")
         (printf "\\newcommand{\\highlighted}[1]{\\colorbox{PaleBlue}{\\hspace{-0.5ex}\\schemeinputcol{#1}\\hspace{-0.5ex}}}\n")
         (printf "\\newcommand{\\techlink}[1]{#1}\n")
+        (printf "\\newcommand{\\imageleft}[1]{#1}\n")
+        (printf "\\newcommand{\\imageright}[1]{#1}\n")
         (printf "\\begin{document}\n")
         (when (part-title-content d)
           (printf "\\title{")

collects/scribble/scribble.css

@@ -282,6 +282,11 @@
                font-family: Courier; font-size: 80%;
                }
 
+               .imageleft { 
+                 float: left;
+                 margin-right: 0.3em;
+               }
+
                .nonavigation {
                color: #EEEEEE;
                }

collects/scribblings/guide/apply.scrbl

@@ -46,7 +46,7 @@ by-position arguments. For that case, an @scheme[_arg] can be an
 @scheme[_arg-keyword _arg-expr] sequence instead of just a
 @scheme[_arg-expr]:
 
-@margin-note{For an introduction to keywords, see @secref["guide:keywords"].}
+@guideother{@secref["guide:keywords"] introduces keywords.}
 
 @specform/subs[
 (_proc-expr _arg ...)

collects/scribblings/guide/begin.scrbl

@@ -14,6 +14,8 @@ display, opening a graphical window, or manipulating a file on disk.
 @;------------------------------------------------------------------------
 @section{Effects Before: @scheme[begin]}
 
+@refalso["mz:begin"]{@scheme[begin]}
+
 A @scheme[begin] expression sequences expressions:
 
 @specform[(begin expr ...+)]{}
@@ -67,6 +69,8 @@ later in @secref["guide:macros"].
 @;------------------------------------------------------------------------
 @section{Effects After: @scheme[begin0]}
 
+@refalso["mz:begin"]{@scheme[begin0]}
+
 A @scheme[begin0] expression has the same syntax as a @scheme[begin]
 expression:
 
@@ -91,6 +95,8 @@ computation produces an unknown number of results.
 @;------------------------------------------------------------------------
 @section{Effects If...: @scheme[when] and @scheme[unless]}
 
+@refalso["mz:when+unless"]{@scheme[when] and @scheme[unless]}
+
 The @scheme[when] form combines an @scheme[if]-style conditional with
 sequencing for the ``then'' clause and no ``else'' clause:
 

collects/scribblings/guide/binding.scrbl

@@ -16,8 +16,8 @@ start with the meaning described here: @scheme[cons] refers to the
 function that creates a pair, @scheme[car] refers to the function
 that extracts the first element of a pair, and so on.
 
-@margin-note{For information on the syntax of identifiers, see
-@secref["guide:symbols"].}
+@guideother{@secref["guide:symbols"] introduces the syntax of
+identifiers.}
 
 Forms like @scheme[define], @scheme[lambda], and @scheme[let]
 associate a meaning with one or more identifiers; that is, they

collects/scribblings/guide/booleans.scrbl

@@ -3,7 +3,7 @@
 @require[(lib "eval.ss" "scribble")]
 @require["guide-utils.ss"]
 
-@title{Booleans}
+@title[#:tag "guide:booleans"]{Booleans}
 
 Scheme has two distinguished constants to represent boolean values:
 @scheme[#t] for true and @scheme[#f] for false. Uppercase

collects/scribblings/guide/cond.scrbl

@@ -3,7 +3,7 @@
 @require[(lib "eval.ss" "scribble")]
 @require["guide-utils.ss"]
 
-@title{Conditionals}
+@title[#:tag "guide:conditionals"]{Conditionals}
 
 Most functions used for branching, such as @scheme[<] and
 @scheme[string?], produce either @scheme[#t] or @scheme[#f]. Scheme's
@@ -35,6 +35,8 @@ list:
 @;------------------------------------------------------------------------
 @section{Simple Branching: @scheme[if]}
 
+@refalso["mz:if"]{@scheme[if]}
+
 In an @scheme[if] form,
 
 @specform[(if test-expr then-expr else-expr)]
@@ -49,7 +51,9 @@ side-effects based on a @scheme[_test-expr], use @scheme[when] or
 @scheme[unless], which we describe later in @secref["guide:begin"].
 
 @;------------------------------------------------------------------------
-@section{Combining Tests: @scheme[and] and @scheme[or]}
+@section[#:tag "guide:and+or"]{Combining Tests: @scheme[and] and @scheme[or]}
+
+@refalso["mz:and+or"]{@scheme[and] and @scheme[or]}
 
 Scheme's @scheme[and] and @scheme[or] are syntactic forms, rather than
 functions. Unlike a function, the @scheme[and] and @scheme[or] forms
@@ -86,16 +90,17 @@ the @scheme[and] or @scheme[or] result. Therefore, the last
 @scheme[expr] is in tail position, which means that the above
 @scheme[got-milk?] function runs in constant space.
 
-@margin-note{For an introduction to tail calls and tail positions, see
-@secref["guide:tail-recursion"].}
+@guideother{@secref["guide:tail-recursion"] introduces tail calls and tail positions.}
 
 @;------------------------------------------------------------------------
-@section{Chaining Tests: @scheme[cond]}
+@section[#:tag "guide:cond"]{Chaining Tests: @scheme[cond]}
 
 The @scheme[cond] form chains a series of tests to select a result
 expression. To a first approximation, the syntax of @scheme[cond] is
 as follows:
 
+@refalso["mz:cond"]{@scheme[cond]}
+
 @specform[(cond [test-expr expr ...+] 
                 ...)]
 

collects/scribblings/guide/define.scrbl

@@ -4,7 +4,7 @@
 @require["guide-utils.ss"]
 @require[(lib "string.ss")]
 
-@title{Definitions: @scheme[define]}
+@title[#:tag "guide:define"]{Definitions: @scheme[define]}
 
 A basic definition has the form
 

collects/scribblings/guide/guide-utils.ss

@@ -3,10 +3,14 @@
            (lib "struct.ss" "scribble")
            (lib "decode.ss" "scribble")
            (lib "kw.ss")
-           (lib "eval.ss" "scribble"))
+           (lib "eval.ss" "scribble")
+           "../icons.ss")
 
   (provide Quick MzScheme HtDP
            tool
+           moreguide
+           guideother
+           refalso
            refdetails
            refdetails/gory
            refsecref)
@@ -23,19 +27,34 @@
   (define (tool name . desc)
     (apply item (bold name) ", " desc))
 
+  (define (moreguide tag . s)
+    (apply margin-note
+           (decode-content (append
+                            (list
+                             finger (secref tag) " (later in this guide)"
+                             " explains more about ")
+                            s
+                            (list ".")))))
+
+  (define (guideother . s)
+    (apply margin-note
+           (cons magnify (decode-content s))))
+
   (define (refdetails* tag what . s)
     (apply margin-note
-           (decode-content (append (list "For " what " on ")
+           (decode-content (append (list magnify (refsecref tag))
+                                   (list what)
                                    s
-                                   (list ", see "
-                                         (refsecref tag)
-                                         ".")))))
+                                   (list ".")))))
 
   (define (refdetails tag . s)
-    (apply refdetails* tag "more" s))
+    (apply refdetails* tag " provides more on " s))
+
+  (define (refalso tag . s)
+    (apply refdetails* tag " also documents " s))
 
   (define (refdetails/gory tag . s)
-    (apply refdetails* tag "gory details" s))
+    (apply refdetails* tag " documents the fine points of " s))
 
   (define (refsecref s)
     (make-element #f (list (secref s) " in " MzScheme))))

collects/scribblings/guide/hash-tables.scrbl

@@ -49,7 +49,7 @@ Beware that even a weak hash table retains its values strongly, as
 long as the corresponding key is accessible. This creates a catch-22
 dependency when a value refers back to its key, so that the mapping is
 retained permanently. To break the cycle, map the key to an
-@seclink["guide:ephemerons"]{ephemeron} that pair the value with its key (in
+@seclink["guide:ephemerons"]{ephemeron} that pairs the value with its key (in
 addition to the implicit pairing of the hash table).
 
 @examples[

collects/scribblings/guide/lambda.scrbl

@@ -51,8 +51,7 @@ into a list bound to @scheme[_rest-id].
 Functions with a @scheme[_rest-id] often use @scheme[apply] to call
 another function that accepts any number of arguments.
 
-@margin-note{See @secref["guide:apply"] for more information on
-@scheme[apply].}
+@guideother{@secref["guide:apply"] describes @scheme[apply].}
 
 @defexamples[
 (define max-mag 
@@ -137,8 +136,8 @@ keyword, instead of position. Keyword arguments can be mixed with
 by-position arguments, and default-value expressions can be supplied
 for either kind of argument:
 
-@margin-note{For an introduction to applications with keywords,
-             see @secref["guide:keyword-args"].}
+@guideother{@secref["guide:keyword-args"] introduces function
+calls with keywords.}
 
 @specform/subs[
 (lambda gen-formals
@@ -187,8 +186,7 @@ through parallel lists in the first two (by-position) arguments,
 and then all by-position arguments from an application as the
 remaining by-position arguments.
 
-@margin-note{For an introduction to @scheme[keyword-apply], see
-@secref["guide:apply"].}
+@guideother{@secref["guide:apply"] inroduces @scheme[keyword-apply].}
 
 @defexamples[
 (define (trace-wrap f)

collects/scribblings/guide/let.scrbl

@@ -3,7 +3,7 @@
 @require[(lib "eval.ss" "scribble")]
 @require["guide-utils.ss"]
 
-@title{Local Binding}
+@title[#:tag "guide:let"]{Local Binding}
 
 Although internal @scheme[define]s can be used for local binding,
 Scheme provides three forms that give the programmer more
@@ -13,6 +13,8 @@ control over bindings: @scheme[let], @scheme[let*], and
 @;------------------------------------------------------------------------
 @section{Parallel Binding: @scheme[let]}
 
+@refalso["mz:let"]{@scheme[let]}
+
 A @scheme[let] form binds a set of identifiers, each to the result of
 some expression, for use in the @scheme[let] body:
 
@@ -67,6 +69,8 @@ evaluated in order, even though the bindings are delayed until all
 @;------------------------------------------------------------------------
 @section{Sequential Binding: @scheme[let*]}
 
+@refalso["mz:let"]{@scheme[let*]}
+
 The syntax of @scheme[let*] is the same as @scheme[let]:
 
 @specform[(let* ([id expr] ...) body ...+)]{}
@@ -100,6 +104,8 @@ In other words, a @scheme[let*] form is equivalent to nested
 @;------------------------------------------------------------------------
 @section{Recursive Binding: @scheme[letrec]}
 
+@refalso["mz:let"]{@scheme[letrec]}
+
 The syntax of @scheme[letrec] is also the same as @scheme[let]:
 
 @specform[(letrec ([id expr] ...) body ...+)]{}
@@ -157,6 +163,8 @@ an @scheme[_id] is referenced before its value is ready, the result is
 @; ----------------------------------------
 @section{Multiple Values: @scheme[let-values], @scheme[let*-values], @scheme[letrec-values]}
 
+@refalso["mz:let"]{multiple-value binding forms}
+
 In the same way that @scheme[define-values] binds multiple
 results in a definition (see @secref["guide:multiple-values"]),
 @scheme[let-values], @scheme[let*-values], and

collects/scribblings/guide/quote.scrbl

@@ -5,6 +5,8 @@
 
 @title{Quoting: @scheme[quote] and @schemevalfont{'}}
 
+@refalso["mz:quote"]{@scheme[quote]}
+
 The @scheme[quote] form produces a constant:
 
 @specform[(#,(schemekeywordfont "quote") datum)]
@@ -57,6 +59,8 @@ and this shorthand is almost always used instead of
 @scheme[quote]. The shorthand applies even within the @scheme[_datum],
 so it can produce a list containing @scheme[quote].
 
+@refdetails["mz:parse-quote"]{the @schemevalfont{'} shorthand}
+
 @examples[
 'apple
 '"hello"

collects/scribblings/guide/set.scrbl

@@ -7,6 +7,8 @@
 
 @title[#:tag "guide:set!"]{Assignment: @scheme[set!]}
 
+@refalso["mz:set!"]{@scheme[set!]}
+
 Assign to a variable using @scheme[set!]:
 
 @specform[(set! id expr)]
@@ -164,6 +166,8 @@ the program.
 @;------------------------------------------------------------------------
 @section{Multiple Values: @scheme[set!-values]}
 
+@refalso["mz:set!"]{@scheme[set!-values]}
+
 The @scheme[set!-values] form assigns to multiple variables at once,
 given an expression that produces an appropriate number of values:
 

collects/scribblings/guide/simple-data.scrbl

@@ -12,6 +12,8 @@ in color), value expression are shown in green.
 @defterm{Numbers} are written in the usual way, including fractions
 and imagnary numbers:
 
+@moreguide["guide:numbers"]{numbers}
+
 @schemeblock[
 1                        1.0
 1/2                      0.5
@@ -23,12 +25,16 @@ and imagnary numbers:
 false. In conditionals, however, all non-@scheme[#f] values are
 treated as true.
 
+@moreguide["guide:booleans"]{booleans}
+
 @defterm{Strings} are written between doublequotes. Within a string,
 backslash is an escaping character; for example, a backslash followed
 by a doublequote includes a little doublequote in the string. Except
 for an unescaped doublequote or backslash, any Unicode character can
 appear in a string constant.
 
+@moreguide["guide:strings"]{strings}
+
 @schemeblock[
 "hello world"
 "A \"fancy\" string"

collects/scribblings/guide/simple-syntax.scrbl

@@ -62,6 +62,8 @@ a sequence as an element for repetition.
 
 A definition of the form
 
+@moreguide["guide:define"]{definitions}
+
 @schemeblock[#, @val-defn-stx]
 
 binds @nonterm{id} to the result of @nonterm{expr}, while
@@ -164,6 +166,8 @@ source's indentation information to suggest where it might be missing.
 Scheme's syntax for identifiers is especially liberal. Excluding the
 special characters
 
+@moreguide["guide:binding"]{identifiers}
+
 @t{
   @hspace[2] @litchar{(} @litchar{)} @litchar{[} @litchar{]} 
   @litchar["{"] @litchar["}"]
@@ -194,6 +198,8 @@ We have already seen many function calls---or @defterm{procedure
 applications} in more traditional Scheme terminology. The syntax of a
 function call is
 
+@moreguide["guide:application"]{function calls}
+
 @schemeblock[
 #, app-expr-stx
 ]
@@ -236,6 +242,8 @@ The next simplest kind of expression is an @scheme[if] conditional:
 #, if-expr-stx
 ]
 
+@moreguide["guide:conditionals"]{conditionals}
+
 The first @nonterm{expr} is always evaluted. If it produces a
 non-@scheme[#f] value, then the second @nonterm{expr} is
 evaluted for the result of the whole @scheme[if] expression, otherwise
@@ -285,6 +293,8 @@ but these kinds of nested @scheme[if]s are difficult to read.  Scheme
 provides more readable shortcuts through the @scheme[and] and
 @scheme[or] forms, which work with any number of expressions:
 
+@moreguide["guide:and+or"]{@scheme[and] and @scheme[or]}
+
 @schemeblock[
 #, and-expr-stx
 #, or-expr-stx
@@ -322,6 +332,8 @@ tests, each with its own result:
 
 The shorthand for a sequence of tests is the @scheme[cond] form:
 
+@moreguide["guide:cond"]{@scheme[cond]}
+
 @schemeblock[
 #, cond-expr-stx
 ]
@@ -368,6 +380,8 @@ In our earlier grammar of function calls, we oversimplified.  The
 actual syntax of a function call allows an arbitrary
 expression for the function, instead of just an @nonterm{id}:
 
+@moreguide["guide:application"]{function calls}
+
 @schemeblock[
 #, app2-expr-stx
 ]
@@ -400,6 +414,8 @@ a procedure'' error like this one.
 Programming in Scheme would be tedious if you had to name all of your
 numbers. Instead of writing @scheme[(+ 1 2)], you'd have to write
 
+@moreguide["guide:lambda"]{@scheme[lambda]}
+
 @interaction[
 (define a 1)
 (define b 2)
@@ -506,6 +522,8 @@ It's time to retract another simplification in our grammar of
 Scheme. In the body of a function, definitions can appear before the
 body expressions:
 
+@moreguide["guide:intdefs"]{local (internal) definitions}
+
 @schemeblock[
 #, fun-defn2-stx
 #, lambda2-expr-stx
@@ -534,6 +552,8 @@ advantage of @scheme[let] is that it can be used in any expression
 position. Also, @scheme[let] binds many identifiers at once, instead
 of requiring a separate @scheme[define] for each identifier.
 
+@moreguide["guide:intdefs"]{@scheme[let] and @scheme[let*]}
+
 @schemeblock[
 #, let-expr-stx
 ]

collects/scribblings/icons.ss

@@ -0,0 +1,15 @@
+(module icons (lib "new-lambda.ss" "scribblings")
+  (require (lib "manual.ss" "scribble")
+           (lib "struct.ss" "scribble"))
+
+  (provide magnify
+           finger)
+
+  (define (mk name)
+    (make-element "imageleft"
+                  (list
+                   (make-element (make-image-file (build-path (collection-path "scribblings")
+                                                              name))
+                                 (list "+")))))
+  (define magnify (mk "magnify.png"))
+  (define finger (mk "finger.png")))

collects/scribblings/reference/define-struct.scrbl

@@ -69,7 +69,7 @@ of the same sort bound to @scheme[id] (see @secref["mz:structinfo"]),
 and it specifies a supertype for the new structure type. Alternately,
 the @scheme[#:super] option can be used to specify an expression that
 must produce a @tech{structure type descriptor}. See
-@scheme[make-struct-type] for more information on structure subtypes
+@secref["mz:structures"] for more information on structure subtypes
 and supertypes. If both @scheme[super-id] and @scheme[#:super] are
 provided, a syntax error is reported.
 
@@ -83,12 +83,12 @@ a syntax error is reported.
 
 The @scheme[#:inspector], @scheme[#:auto-value], and @scheme[#:guard]
 options specify an inspector, value for automatic fields, and guard
-procedure, respectively. See @scheme[make-struct-type] for more
-information on these properties of a structure type. The
-@scheme[#:property] option, which is the only one that can be
-specified multiple times, attaches a property value to the structure
-type; see @scheme[make-struct-type] for more information on
-properties.
+procedure, respectively. See @scheme[make-struct-type] (in
+@secref["mz:creatingmorestructs"]) for more information on these
+properties of a structure type. The @scheme[#:property] option, which
+is the only one that can be specified multiple times, attaches a
+property value to the structure type; see @secref["mz:structprops"]
+for more information on properties.
 
 If the @scheme[#:omit-define-syntaxes] option is supplied, then
 @scheme[id] is not bound as a transformer. If the

collects/scribblings/reference/mz.ss

@@ -3,7 +3,8 @@
            (lib "manual.ss" "scribble")
            (lib "eval.ss" "scribble")
            (lib "decode.ss" "scribble")
-           (lib "kw.ss"))
+           (lib "kw.ss")
+           "../icons.ss")
 
   (provide (all-from (lib "manual.ss" "scribble"))
            (all-from (lib "eval.ss" "scribble")))
@@ -25,10 +26,6 @@
 
   (define/kw (guideintro tag #:body s)
     (apply margin-note
-           (decode-content (append (list "For an introduction to ")
-                                   s
-                                   (list ", see "
-                                         (secref tag)
-                                         " in "
-                                         Guide
-                                         "."))))))
+           (decode-content (append (list finger (secref tag) " in " Guide " introduces ")
+                                   s)))))
+

collects/scribblings/reference/struct.scrbl

@@ -57,8 +57,8 @@ depends on the current inspector.)
 
 @defproc[(make-struct-type [name symbol?]
                            [super-type (or/c struct-type? false/c)]
-                           [init-field-k non-negative-exact-integer?]
-                           [auto-field-k non-negative-exact-integer?]
+                           [init-field-cnt non-negative-exact-integer?]
+                           [auto-field-cnt non-negative-exact-integer?]
                            [auto-v any/c #f]
                            [props (listof (cons/c struct-type-property?
                                                   any/c))
@@ -83,9 +83,9 @@ Creates a new structure type.  The @scheme[name] argument is used as
 the type name. If @scheme[super-type] is not @scheme[#f], the new type
 is a subtype of the corresponding structure type.
 
-The new structure type has @scheme[(+ init-field-k auto-field-k)]
+The new structure type has @scheme[(+ init-field-cnt auto-field-cnt)]
 fields (in addition to any fields from @scheme[super-type]), but only
-@scheme[init-field-k] constructor arguments (in addition to any
+@scheme[init-field-cnt] constructor arguments (in addition to any
 constructor arguments from @scheme[super-type]). The remaining
 fields are initialized with @scheme[auto-v].
  
@@ -109,12 +109,12 @@ further information.  Providing a non-@scheme[#f] value for
 The @scheme[immutables] argument provides a list of field
 positions. Each element in the list must be unique, otherwise
 @exnraise[exn:fail:contract]. Each element must also fall in the range
-@scheme[0] (inclusive) to @scheme[init-field-k] (exclusive), otherwise
+@scheme[0] (inclusive) to @scheme[init-field-cnt] (exclusive), otherwise
 @exnraise[exn:fail:contract].
 
 The @scheme[guard] argument is either a procedure of @math{n}
 arguments or @scheme[#f], where @math{n} is the number of arguments
-for the new structure type's constructor (i.e., @scheme[init-field-k]
+for the new structure type's constructor (i.e., @scheme[init-field-cnt]
 plus constructor arguments implied by @scheme[super-type], if any). If
 @scheme[guard] is a procedure, then the procedure is called
 whenever an instance of the type is constructed, or whenever an
@@ -142,7 +142,7 @@ The result of @scheme[make-struct-type] is five values:
 
  @item{an @tech{accessor} procedure, which consumes a structure and a field
  index between @math{0} (inclusive) and
- @math{@scheme[init-field-k]+@scheme[auto-field-k]} (exclusive),
+ @math{@scheme[init-field-cnt]+@scheme[auto-field-cnt]} (exclusive),
  and}
 
  @item{a @tech{mutator} procedure, which consumes a structure, a field
@@ -365,11 +365,11 @@ Returns eight values that provide information about the structure type
 
   @item{@scheme[name]: the structure type's name as a symbol;}
 
-  @item{@scheme[init-field-k]: the number of fields defined by the
+  @item{@scheme[init-field-cnt]: the number of fields defined by the
    structure type provided to the constructor procedure (not counting
    fields created by its ancestor types);}
 
-  @item{@scheme[auto-field-k]: the number of fields defined by the
+  @item{@scheme[auto-field-cnt]: the number of fields defined by the
    structure type without a counterpart in the constructor procedure
    (not counting fields created by its ancestor types);}