From f9b2e75a7517b1e290d3971678f862d2139011d8 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sat, 23 Jun 2007 02:33:00 +0000 Subject: [PATCH] more cross-referencing and icons to help explain margin notes svn: r6720 --- collects/scribble/latex-render.ss | 2 ++ collects/scribble/scribble.css | 5 +++ collects/scribblings/finger.png | Bin 0 -> 430 bytes collects/scribblings/guide/apply.scrbl | 2 +- collects/scribblings/guide/begin.scrbl | 6 ++++ collects/scribblings/guide/binding.scrbl | 4 +-- collects/scribblings/guide/booleans.scrbl | 2 +- collects/scribblings/guide/cond.scrbl | 15 +++++--- collects/scribblings/guide/define.scrbl | 2 +- collects/scribblings/guide/guide-utils.ss | 33 ++++++++++++++---- collects/scribblings/guide/hash-tables.scrbl | 2 +- collects/scribblings/guide/lambda.scrbl | 10 +++--- collects/scribblings/guide/let.scrbl | 10 +++++- collects/scribblings/guide/quote.scrbl | 4 +++ collects/scribblings/guide/set.scrbl | 4 +++ collects/scribblings/guide/simple-data.scrbl | 6 ++++ .../scribblings/guide/simple-syntax.scrbl | 20 +++++++++++ collects/scribblings/icons.ss | 15 ++++++++ collects/scribblings/magnify.png | Bin 0 -> 323 bytes .../scribblings/reference/define-struct.scrbl | 14 ++++---- collects/scribblings/reference/mz.ss | 13 +++---- collects/scribblings/reference/struct.scrbl | 18 +++++----- 22 files changed, 138 insertions(+), 49 deletions(-) create mode 100644 collects/scribblings/finger.png create mode 100644 collects/scribblings/icons.ss create mode 100644 collects/scribblings/magnify.png diff --git a/collects/scribble/latex-render.ss b/collects/scribble/latex-render.ss index af317dbd06..2814051c46 100644 --- a/collects/scribble/latex-render.ss +++ b/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{") diff --git a/collects/scribble/scribble.css b/collects/scribble/scribble.css index 1e841947e3..c383615a12 100644 --- a/collects/scribble/scribble.css +++ b/collects/scribble/scribble.css @@ -282,6 +282,11 @@ font-family: Courier; font-size: 80%; } + .imageleft { + float: left; + margin-right: 0.3em; + } + .nonavigation { color: #EEEEEE; } diff --git a/collects/scribblings/finger.png b/collects/scribblings/finger.png new file mode 100644 index 0000000000000000000000000000000000000000..af521e80ad42a9ae5407c620edc296e7c4bba598 GIT binary patch literal 430 zcmV;f0a5;mP)eTsH8vpRWL7c@7w$U2V zgi@`8IW*&B=1?m>V;Oz8ig#GY1&kt(uaRJL+|!8fSVRHkJ&~^XDC0gRu!4Eqz@dty zF5_O6gc~p!Nf9Mxd4uOT6++))|5)r5@Cfa=i3Q1`CbZ!=hVh`9z`8RzWV-*AXPoi+C>$z!PbFr~XFZC^~RnYUHzs60YM8UZEf3*hQz`yocb^Zf> Y0+i!VsAM9jdH?_b07*qoM6N<$g28abDF6Tf literal 0 HcmV?d00001 diff --git a/collects/scribblings/guide/apply.scrbl b/collects/scribblings/guide/apply.scrbl index 3365a53c2d..b13e7500ce 100644 --- a/collects/scribblings/guide/apply.scrbl +++ b/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 ...) diff --git a/collects/scribblings/guide/begin.scrbl b/collects/scribblings/guide/begin.scrbl index 7120d9e925..a3a6087c5c 100644 --- a/collects/scribblings/guide/begin.scrbl +++ b/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: diff --git a/collects/scribblings/guide/binding.scrbl b/collects/scribblings/guide/binding.scrbl index c3595331fb..8289bcb448 100644 --- a/collects/scribblings/guide/binding.scrbl +++ b/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 diff --git a/collects/scribblings/guide/booleans.scrbl b/collects/scribblings/guide/booleans.scrbl index f4fd1e7531..29ab4682f3 100644 --- a/collects/scribblings/guide/booleans.scrbl +++ b/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 diff --git a/collects/scribblings/guide/cond.scrbl b/collects/scribblings/guide/cond.scrbl index b320c9d6b4..e4285b5a65 100644 --- a/collects/scribblings/guide/cond.scrbl +++ b/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 ...+] ...)] diff --git a/collects/scribblings/guide/define.scrbl b/collects/scribblings/guide/define.scrbl index fe8e47df44..15719d0fc8 100644 --- a/collects/scribblings/guide/define.scrbl +++ b/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 diff --git a/collects/scribblings/guide/guide-utils.ss b/collects/scribblings/guide/guide-utils.ss index eeb64b2a66..f1123ec180 100644 --- a/collects/scribblings/guide/guide-utils.ss +++ b/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)))) diff --git a/collects/scribblings/guide/hash-tables.scrbl b/collects/scribblings/guide/hash-tables.scrbl index 2f8b6514e8..4d4abc4576 100644 --- a/collects/scribblings/guide/hash-tables.scrbl +++ b/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[ diff --git a/collects/scribblings/guide/lambda.scrbl b/collects/scribblings/guide/lambda.scrbl index 0773e471e9..6d9697ca75 100644 --- a/collects/scribblings/guide/lambda.scrbl +++ b/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) diff --git a/collects/scribblings/guide/let.scrbl b/collects/scribblings/guide/let.scrbl index 14c9a11970..491353b18f 100644 --- a/collects/scribblings/guide/let.scrbl +++ b/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 diff --git a/collects/scribblings/guide/quote.scrbl b/collects/scribblings/guide/quote.scrbl index e63722f1e7..09d4cd8698 100644 --- a/collects/scribblings/guide/quote.scrbl +++ b/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" diff --git a/collects/scribblings/guide/set.scrbl b/collects/scribblings/guide/set.scrbl index a58a211691..0522f29d45 100644 --- a/collects/scribblings/guide/set.scrbl +++ b/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: diff --git a/collects/scribblings/guide/simple-data.scrbl b/collects/scribblings/guide/simple-data.scrbl index b39d067532..41dc43f129 100644 --- a/collects/scribblings/guide/simple-data.scrbl +++ b/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" diff --git a/collects/scribblings/guide/simple-syntax.scrbl b/collects/scribblings/guide/simple-syntax.scrbl index 356ca930cf..3057da06b5 100644 --- a/collects/scribblings/guide/simple-syntax.scrbl +++ b/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 ] diff --git a/collects/scribblings/icons.ss b/collects/scribblings/icons.ss new file mode 100644 index 0000000000..a087670dfc --- /dev/null +++ b/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"))) diff --git a/collects/scribblings/magnify.png b/collects/scribblings/magnify.png new file mode 100644 index 0000000000000000000000000000000000000000..8556e407323719a5099dd6518622cfeb86a2bf4f GIT binary patch literal 323 zcmV-J0lfZ+P)*&n3&CLE8Ne1^0)+#CL^Wwri-Lq8NEXq%q-k0@ zJAi1yKN&H1&zy6UxwEW0jm&dx^iafpgj>AK3pX>&2e`ow-qFH7F0hTe49_plQKGZp zTL