From 30bb8ed26322e9ef75e71b93747ab89e991561f5 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 22 Apr 2009 00:42:47 +0000
Subject: [PATCH] some slightly less-boring examples

svn: r14582
---
 collects/scribblings/guide/simple-data.scrbl  | 13 ++-
 .../scribblings/guide/simple-syntax.scrbl     | 92 ++++++++++---------
 collects/scribblings/guide/welcome.scrbl      | 58 ++++++------
 3 files changed, 85 insertions(+), 78 deletions(-)

diff --git a/collects/scribblings/guide/simple-data.scrbl b/collects/scribblings/guide/simple-data.scrbl
index 1272860289..933debcfdf 100644
--- a/collects/scribblings/guide/simple-data.scrbl
+++ b/collects/scribblings/guide/simple-data.scrbl
@@ -15,10 +15,9 @@ and imaginary numbers:
 @moreguide["numbers"]{numbers}
 
 @schemeblock[
-1                        1.0
-1/2                      0.5
-9999999999999999999999   1e+22
-1+2i                     1.0+2.0i
+1       3.14
+1/2     6.02e+23
+1+2i    9999999999999999999999
 ]
 
 @defterm{Booleans} are @scheme[#t] for true and @scheme[#f] for
@@ -36,8 +35,8 @@ appear in a string constant.
 @moreguide["strings"]{strings}
 
 @schemeblock[
-"hello world"
-"A \"fancy\" string"
+"Hello, world!"
+"Benjamin \"Bugsy\" Siegel"
 "\u03BBx:(\u03BC\u03B1.\u03B1\u2192\u03B1).xx"
 ]
 
@@ -49,5 +48,5 @@ difference between an input expression and a printed result.
 
 @examples[
 (eval:alts (unsyntax (schemevalfont "1.0000")) 1.0000)
-(eval:alts (unsyntax (schemevalfont "\"A \\u0022fancy\\u0022 string\"")) "A \u0022fancy\u0022 string")
+(eval:alts (unsyntax (schemevalfont "\"Bugs \\u0022Figaro\\u0022 Bunny\"")) "Bugs \u0022Figaro\u0022 Bunny")
 ]
diff --git a/collects/scribblings/guide/simple-syntax.scrbl b/collects/scribblings/guide/simple-syntax.scrbl
index 924880fe0d..5d949d9b45 100644
--- a/collects/scribblings/guide/simple-syntax.scrbl
+++ b/collects/scribblings/guide/simple-syntax.scrbl
@@ -81,11 +81,11 @@ the last @nonterm{expr}.
 
 @defexamples[
 #:eval ex-eval
-(code:line (define five 5)            (code:comment #, @t{defines @scheme[five] to be @scheme[5]}))
+(code:line (define pie 3)             (code:comment #, @t{defines @scheme[pie] to be @scheme[3]}))
 (code:line (define (piece str)        (code:comment #, @t{defines @scheme[piece] as a function})
-             (substring str 0 five))  (code:comment #, @t{of one argument}))
-five
-(piece "hello world")
+             (substring str 0 pie))   (code:comment #, @t{ of one argument}))
+pie
+(piece "key lime")
 ]
 
 Under the hood, a function definition is really the same as a
@@ -100,8 +100,6 @@ piece
 substring
 ]
 
-@; FIXME: check that everything says "procedure" and not "primitive"
-
 A function definition can include multiple expressions for the
 function's body. In that case, only the value of the last expression
 is returned when the function is called. The other expressions are
@@ -109,30 +107,30 @@ evaluated only for some side-effect, such as printing.
 
 @defexamples[
 #:eval ex-eval
-(define (greet name)
-  (printf "returning a greeting for ~a...\n" name)
-  (string-append "hello " name))
-(greet "universe")
+(define (bake flavor)
+  (printf "pre-heating oven...\n")
+  (string-append flavor " pie"))
+(bake "apple")
 ]
 
-Scheme programmers prefer to avoid assignment statements. It's
+Scheme programmers prefer to avoid side-effects. It's
 important, though, to understand that multiple expressions are allowed
 in a definition body, because it explains why the following
-@scheme[nogreet] function simply returns its argument:
+@scheme[nobake] function simply returns its argument:
 
 @def+int[
 #:eval ex-eval
-(define (nogreet name)
-  string-append "hello " name)
-(nogreet "world")
+(define (nobake flavor)
+  string-append flavor "jello")
+(nobake "green")
 ]
 
-Within @scheme[nogreet], there are no parentheses around
-@scheme[string-append "hello " name], so they are three separate
+Within @scheme[nobake], there are no parentheses around
+@scheme[string-append flavor "jello"], so they are three separate
 expressions instead of one function-call expression. The expressions
-@scheme[string-append] and @scheme["hello "] are evaluated, but the
+@scheme[string-append] and @scheme[flavor] are evaluated, but the
 results are never used. Instead, the result of the function is just
-the result of the expression @scheme[name].
+the result of the final expression, @scheme["jello"].
 
 @; ----------------------------------------------------------------------
 @section[#:tag "indentation"]{An Aside on Indenting Code}
@@ -161,13 +159,14 @@ next line under the first argument, instead of under the
 @scheme[define] keyword:
 
 @schemeblock[
-(define (nogreet name
-                 (string-append "hello " name)))
+(define (halfbake flavor
+                  (string-append flavor " creme brulee")))
 ]
 
-Furthermore, when an open parenthesis has no matching close
-parenthesis in a program, both @exec{mzscheme} and DrScheme use the
-source's indentation to suggest where it might be missing.
+In this case, indentation helps highlight the mistake. In other cases,
+where the indentation may be normal while an open parenthesis has no
+matching close parenthesis; both @exec{mzscheme} and DrScheme use the
+source's indentation to suggest where a parenthesis might be missing.
 
 @;- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 @section{Identifiers}
@@ -193,11 +192,11 @@ more examples:
 
 @schemeblock[
 #, @schemeid[+]
-#, @schemeid[Apple]
+#, @schemeid[Hfuhruhurr]
 #, @schemeid[integer?]
-#, @schemeid[call/cc]
-#, @schemeid[call-with-composable-continuation]
-#, @schemeid[x-1+3i]
+#, @schemeid[pass/fail]
+#, @schemeid[john-jacob-jingleheimer-schmidt]
+#, @schemeid[a-b-c+1-2-3]
 ]
 
 @;- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -225,10 +224,10 @@ pre-defined names are hyperlinked to the reference manual. So, you can
 click on an identifier to get full details about its use.
 
 @interaction[
-(code:line (string-append "hello"  " "  "scheme") (code:comment #, @t{append strings}))
-(code:line (substring "hello scheme" 6 12)        (code:comment #, @t{extract a substring}))
-(code:line (string-length "scheme")               (code:comment #, @t{get a string's length}))
-(code:line (string? "hello scheme")               (code:comment #, @t{recognize strings}))
+(code:line (string-append "rope" "twine" "yarn")  (code:comment #, @t{append strings}))
+(code:line (substring "corduroys" 0 4)            (code:comment #, @t{extract a substring}))
+(code:line (string-length "shoelace")             (code:comment #, @t{get a string's length}))
+(code:line (string? "c'est ne pas une string")    (code:comment #, @t{recognize strings}))
 (string? 1)
 (code:line (sqrt 16)                              (code:comment #, @t{find a square root}))
 (sqrt -16)
@@ -236,10 +235,11 @@ click on an identifier to get full details about its use.
 (code:line (- 2 1)                                (code:comment #, @t{subtract numbers}))
 (code:line (< 2 1)                                (code:comment #, @t{compare numbers}))
 (>= 2 1)
-(code:line (number? "hello scheme")               (code:comment #, @t{recognize numbers}))
+(code:line (number? "c'est une number")           (code:comment #, @t{recognize numbers}))
 (number? 1)
-(code:line (equal? 1 "hello")                     (code:comment #, @t{compare anything}))
-(equal? 1 1)
+(code:line (equal? 6 "half dozen")                (code:comment #, @t{compare anything}))
+(equal? 6 6)
+(equal? "half dozen" "half dozen")
 ]
 
 @;- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -403,7 +403,7 @@ expression:
 @def+int[
 (define (double v)
   ((if (string? v) string-append +) v v))
-(double "hello")
+(double "mnah")
 (double 5)
 ]
 
@@ -581,9 +581,12 @@ each clause, the @nonterm{id} is bound to the result of the
 @nonterm{expr} for use in the body.
 
 @interaction[
-(let ([x 1]
-      [y 2])
-  (format "adding ~s and ~s produces ~s" x y (+ x y)))
+(let ([x (random 4)]
+      [o (random 4)])
+  (cond
+   [(> x o) "X wins"]
+   [(> o x) "O wins"]
+   [else "cat's game"]))
 ]
 
 The bindings of a @scheme[let] form are available only in the body of
@@ -592,10 +595,13 @@ other. The @scheme[let*] form, in contrast, allows later clauses to
 use earlier bindings:
 
 @interaction[
-(let* ([x 1]
-       [y 2]
-       [z (+ x y)])
-  (format "adding ~s and ~s produces ~s" x y z))
+(let* ([x (random 4)]
+       [o (random 4)]
+       [diff (number->string (abs (- x o)))])
+  (cond
+   [(> x o) (string-append "X wins by " diff)]
+   [(> o x) (string-append "O wins by " diff)]
+   [else "cat's game"]))
 ]
 
 @; ----------------------------------------------------------------------
diff --git a/collects/scribblings/guide/welcome.scrbl b/collects/scribblings/guide/welcome.scrbl
index ef3b7316ee..e924f9b841 100644
--- a/collects/scribblings/guide/welcome.scrbl
+++ b/collects/scribblings/guide/welcome.scrbl
@@ -2,7 +2,8 @@
 @(require scribble/manual
           scribble/eval
           scribble/bnf
-          "guide-utils.ss")
+          "guide-utils.ss"
+          (for-label scheme/enter))
 
 @(define piece-eval (make-base-eval))
 
@@ -85,16 +86,16 @@ number:
 A string is also an expression that evaluates to itself. A string is
 written with double quotes at the start and end of the string:
 
-@interaction["hello world"]
+@interaction["Hello, world!"]
 
 Scheme uses parentheses to wrap larger expressions---almost any kind
 of expression, other than simple constants. For example, a function
 call is written: open parenthesis, function name, argument
 expression, and closing parenthesis. The following expression calls
 the built-in function @scheme[substring] with the arguments
-@scheme["hello world"], @scheme[0], and @scheme[5]:
+@scheme["the boy out of the country"], @scheme[4], and @scheme[7]:
 
-@interaction[(substring "hello world" 0 5)]
+@interaction[(substring "the boy out of the country" 4 7)]
 
 @; ----------------------------------------------------------------------
 @section{Definitions and Interactions}
@@ -104,9 +105,10 @@ using the @scheme[define] form, like this:
 
 @def+int[
 #:eval piece-eval
-(define (piece str)
-  (substring str 0 5))
-(piece "howdy universe")
+(define (extract str)
+  (substring str 4 7))
+(extract "the boy out of the country")
+(extract "the country out of the boy")
 ]
 
 Although you can evaluate the @scheme[define] form in the @tech{REPL},
@@ -118,29 +120,29 @@ top text area---called the @deftech{definitions area}---along with the
 @schememod[
 scheme
 code:blank
-(define (piece str)
-  (substring str 0 5))
+(define (extract str)
+  (substring str 4 7))
 ]
 
-If calling @scheme[(piece "howdy universe")] is part of the main
-action of your program, that would go in the @tech{definitions area},
-too. But if it was just an example expression that you were using to
-explore @scheme[piece], then you'd more likely leave the
-@tech{definitions area} as above, click @onscreen{Run}, and then
-evaluate @scheme[(piece "howdy universe")] in the @tech{REPL}.
+If calling @scheme[(extract "the boy")] is part of the main action of
+your program, that would go in the @tech{definitions area}, too. But
+if it was just an example expression that you were using to explore
+@scheme[extract], then you'd more likely leave the @tech{definitions
+area} as above, click @onscreen{Run}, and then evaluate
+@scheme[(extract "the boy")] in the @tech{REPL}.
 
 With @exec{mzscheme}, you'd save the above text in a file using your
-favorite editor. If you save it as @filepath{piece.ss}, then after starting
+favorite editor. If you save it as @filepath{extract.ss}, then after starting
 @exec{mzscheme} in the same directory, you'd evaluate the following
 sequence:
 
 @interaction[
 #:eval piece-eval
-(eval:alts (enter! "piece.ss") (void))
-(piece "howdy universe")
+(eval:alts (enter! "extract.ss") (void))
+(extract "the gal out of the city")
 ]
 
-The @scheme[enter!] function both loads the code and switches the
+The @scheme[enter!] form both loads the code and switches the
 evaluation context to the inside of the module, just like DrScheme's
 @onscreen{Run} button.
 
@@ -152,13 +154,13 @@ If your file (or @tech{definitions area} in DrScheme) contains
 @schememod[
 scheme
 
-(define (piece str)
-  (substring str 0 5))
+(define (extract str)
+  (substring str 4 7))
 
-(piece "howdy universe")
+(extract "the cat out of the bag")
 ]
 
-then it is a complete program that prints ``howdy'' when run. To
+then it is a complete program that prints ``cat'' when run. To
 package this program as an executable, choose one of the following
 options:
 
@@ -200,16 +202,16 @@ If you already know something about Scheme or Lisp, you might be
 tempted to put just
 
 @schemeblock[
-(define (piece str)
-  (substring str 0 5))
+(define (extract str)
+  (substring str 4 7))
 ]
 
-into @filepath{piece.scm} and run @exec{mzscheme} with
+into @filepath{extract.scm} and run @exec{mzscheme} with
 
 @interaction[
 #:eval piece-eval
-(eval:alts (load "piece.scm") (void))
-(piece "howdy universe")
+(eval:alts (load "extract.scm") (void))
+(extract "the dog out")
 ]
 
 That will work, because @exec{mzscheme} is willing to imitate a