Standartize the vocabulary to "the function returns" and "set! mutates"

(cherry picked from commit c31d352f2b)

collects/2htdp/batch-io.rkt

@@ -41,7 +41,7 @@
  
  write-file ;; String String -> String 
  ;; (write-file filename str) writes str to filename; 
- ;; produces the file name as a confirmation that the write succeeded 
+ ;; returns the file name as a confirmation that the write succeeded 
  )      
 
 ;; -----------------------------------------------------------------------------

collects/2htdp/private/clauses-spec-and-process.rkt

@@ -91,7 +91,7 @@
          (if r ((third s) r) (fourth s)))
        Spec))
 
-;; check whether rec? occurs, produce list of keyword x clause pairs 
+;; check whether rec? occurs, returns list of keyword x clause pairs 
 (define (clauses-use-kwd stx:list ->rec? tag kwds)
   (define kwd-in? (->kwds-in kwds))
   (map (lambda (stx)

collects/2htdp/private/launch-many-worlds.rkt

@@ -6,7 +6,7 @@
   launch-many-worlds
   ;; (launch-many-worlds e1 ... e2)
   ;; run expressions e1 through e2 in parallel,
-  ;; produce all values
+  ;; return all values
   )
 
 (define-syntax-rule 

collects/2htdp/private/world.rkt

@@ -129,7 +129,7 @@
        (height (if (pair? to-draw) (third to-draw) #f)))
       
       ;; the visible world 
-      (field [enable-images-button void] ;; used if stop-when call produces #t
+      (field [enable-images-button void] ;; used if stop-when call returns #t
              [disable-images-button void]
              [visible (new pasteboard%)])
       
@@ -334,7 +334,7 @@
         (show (ppdraw)))
       
       ;; -> Scene
-      ;; produce the scene for the this state
+      ;; return the scene for the this state
       (define/public (ppdraw)
         (check-scene-result (name-of draw 'your-draw) (draw (send world get))))
       

collects/2htdp/tests/test-image.rkt

@@ -1380,7 +1380,7 @@
       =>
       128)
 
-;; Rotation by 0 should produce an equivalent object
+;; Rotation by 0 should return an equivalent object
 (test (rotate 0 (make-object image-snip% green-blue-20x10-bitmap))
       =>
       (to-img (make-object image-snip% green-blue-20x10-bitmap)))

collects/2htdp/universe.rkt

@@ -35,7 +35,7 @@
 (provide
  launch-many-worlds
  ;; (launch-many-worlds e1 ... e2)
- ;; run expressions e1 through e2 in parallel, produce all values in same order
+ ;; run expressions e1 through e2 in parallel, return all values in same order
  )
 
 (provide-primitive
@@ -123,7 +123,7 @@
    ;; ******************************************************************
    DEFAULT #'(lambda (u w) (make-bundle u '() '()))
    ;; this is the wrong default function 
-   ;; instead of K there should be a function that produces a bundle 
+   ;; instead of K there should be a function that returns a bundle 
    (function-with-arity 2)
    ;; ******************************************************************
    ]

collects/htdp/convert.rkt

@@ -91,7 +91,7 @@
 
 ;; ------------------------------------------------------------------------
 (define OUT-ERROR
-  "The conversion function must produce a number; result: ~e")
+  "The conversion function must return a number, but it returned ~e")
 
 ;; ============================================================================
 ;; MODEL

collects/htdp/error-composition.scrbl

@@ -2,10 +2,9 @@
 
 @(require scribble/manual 
           (for-label [only-in lang/htdp-advanced set!]
-          [only-in lang/htdp-intermediate let]  
-          [only-in lang/htdp-beginner define]
-          [only-in racket/base syntax-local-expand-expression]
-          ))
+                     [only-in lang/htdp-intermediate let]  
+                     [only-in lang/htdp-beginner define]
+                     [only-in racket/base syntax-local-expand-expression]))
 
 @(require scribble/decode)
 
@@ -51,7 +50,7 @@ from other teachpacks.
     nor antagonistic.}
 
   @item{If an expression contains multiple errors, report the leftmost
-    error first.  E.g., the error in @racket{(define 1 2 3)} is
+    error first.  E.g., the error in @racket[(define 1 2 3)] is
     @samp{expected the variable name, but found a number}, not
     @samp{expected 2 parts after define, but found 3}.  Before raising
     an error about a sub-part of a macro, call
@@ -71,7 +70,7 @@ Use only the following vocabulary words to describe code:
       @list[@para{structure name} @para{type name} @para{field name} @para{binding}]]]
 
 @itemize[
-  @item{Use binding for the square-braced pair in a @racket{let}
+  @item{Use binding for the square-braced pair in a @racket[let]
     and similar binding forms.}
 
   @item{Use @word{argument} for actual arguments and @word{variable} for
@@ -86,6 +85,8 @@ Use only the following vocabulary words to describe code:
 
 @section{Words For Describing Runtime Behavior}
 
+Use the following vocabulary words to describe how code runs:
+
 @itemize[
   @item{When specifying a function's behavior, say @samp{the function
     takes ... and returns ...}}
@@ -94,12 +95,18 @@ Use only the following vocabulary words to describe code:
     expects ... but received ...}}
 
   @item{As much as possible, identify expressions and the value they evaluate
-    to, e.g. @samp{the value of @racket{(f x)} is 5}.  If it is necessary to
+    to, e.g. @samp{the value of @racket[(f x)] is 5}.  If it is necessary to
     mention evaluation order, such as when the context discusses mutable state,
     say that the expression @samp{evaluates to} a value.  Function calls
     are a special case of expression.  Prefer @samp{the function call returns ...}
     to @samp{the function call evaluates to ...}, except when trying to draw attention to
-    the evaluation of the arguments.}]
+    the evaluation of the arguments.}
+
+  @item{@racket[set!] and
+    @racketidfont{set-}@racket[_structure-name]@racketidfont{-}@racket[_field-name]@racketidfont{!}
+    @word{mutate} variables and structure instances, respectively. Avoid using
+    the verb @word{sets} when discussing mutation, and reserve the verbs
+    @word{changes} and @word{updates} for functional updates.}]
 
 
 @section{Prohibited Words}
@@ -157,7 +164,7 @@ not appreciate anyway).
     [Rationale: Students learn this distinction when they learn about
     lambda.  The first is the lambda implicit in the definition, the
     second is the variable introduced by the definition that can appear
-    as the first argument to @racket{set!}, the third is the particular
+    as the first argument to @racket[set!], the third is the particular
     sequence of letters.  But BSL should avoid this complexity, and
     ASL’s error messages should maintain consistency with BSL.]}
 

collects/htdp/hangman.rkt

@@ -114,7 +114,7 @@
 (define message-panel #f)
 
 ;; setup-gui : str ->* message% panel%
-;; to produce a status message and a panel where winning/losing can be announced
+;; to return a status message and a panel where winning/losing can be announced
 ;; effect: set up a new frame, arrange the GUI, and display (blank) status word 
 (define (setup-gui status)
   (local (#| --------------------------------------------------------------

collects/htdp/htdp-lib.scrbl

@@ -154,12 +154,12 @@ they can be syntactically restricted to application positions.
   @racket[id] is exported as the primitive operator named
   @racket[id]. An alternative to @racket[define-higher-order-primitive].}
 
-@defform[(first-order->higher-order expr)]{
+@defform[(first-order->higher-order expression)]{
 
-If @racket[expr] is an identifier for a first-order function (either a
-primitive or a function defined within Beginner Student), produces the
+If @racket[expression] is the name of a first-order function (either a
+primitive or a function defined within Beginner Student), returns the
 function as a value; otherwise, the form is equivalent to
-@racket[expr].
+@racket[expression].
 
 This form is mainly useful for implementing syntactic forms that, like
 the application of a higher-order primitive, allow first-order bindings

collects/htdp/tests/convert.rkt

@@ -35,11 +35,11 @@
 (convert-file IN f2c OUT)
 (with-input-from-file OUT check-convert-out)
 
-(check-error (convert-file IN list OUT) "convert: The conversion function must produce a number; result: (212)")
+(check-error (convert-file IN list OUT) "convert: The conversion function must return a number; but it returned (212)")
 
 (check-error (convert-file IN first OUT) "first: expected argument of type <non-empty list>; given 212")
 
-(check-error (convert-file IN fx OUT) "convert: The conversion function must produce a number; result: xyz")
+(check-error (convert-file IN fx OUT) "convert: The conversion function must return a number; but it returned xyz")
 
 (check-error (convert-file IN f2c 10) "convert-file: expected <string> as third argument, given: 10")
 

collects/lang/private/advanced-funs.rkt

@@ -31,7 +31,7 @@
     (with-input-from-string (string (-> any) -> any)
       "Turns the given string into input for read* operations.")
     (with-output-to-string (string (-> any) -> any)
-      "Produces a string from all write/display/print operations.")
+      "Returns a string from all write/display/print operations.")
     
     
     (print (any -> void)
@@ -63,7 +63,7 @@
     
     (assoc 
      (any (listof any) -> (listof any) or false)
-     "Produces the first element on the list whose first is equal? to v; otherwise it produces false."))
+     "Returns the first element on the list whose first is equal? to v; otherwise it returns false."))
    
    ("Misc"
     (gensym (-> symbol?)
@@ -75,7 +75,7 @@
     
     (force (delay -> any) "Finds the delayed value; see also delay.")
     (promise? (any -> boolean) "Determines if a value is delayed.")
-    (void (-> void) "Produces a void value.")
+    (void (-> void) "Returns a void value.")
     (void? (any -> boolean) "Determines if a value is void."))
    
    ("Posns"

collects/lang/private/beginner-funs.rkt

@@ -290,13 +290,13 @@
 	"Evaluates the number of items on a list.")
       (memq (any (listof any) -> (union false list))
 	"Determines whether some value is on some list"
-	" if so, it produces the suffix of the list that starts with x"
-	" if not, it produces false."
+	" if so, it returns the suffix of the list that starts with x"
+	" if not, it returns false."
 	" (It compares values with the eq? predicate.)")
       (memv (any (listof any) -> (union false list))
 	"Determines whether some value is on the list"
-	" if so, it produces the suffix of the list that starts with x"
-	" if not, it produces false."
+	" if so, it returns the suffix of the list that starts with x"
+	" if not, it returns false."
 	" (It compares values with the eqv? predicate.)")
       ((beginner-member? member?) (any (listof any) -> boolean)
 	"Determines whether some value is on the list"
@@ -405,7 +405,7 @@
       (string (char ... -> string)
 	"Builds a string of the given characters.")
       (make-string (nat char -> string)
-	"Produces a string of given length"
+	"Returns a string of given length"
 	" from a single given character.")
       (string-ref (string nat -> char)
 	"Extracts the i-the character from a string.")
@@ -455,7 +455,7 @@
 	"Converts a string into a symbol.")
       (string->number (string -> (union number false))
 	"Converts a string into a number,"
-	" produce false if impossible.")
+	" return false if impossible.")
       (string->list (string -> (listof char))
 	"Converts a string into a list of characters.")
       (list->string ((listof char) -> string)

collects/lang/private/intermediate-funs.rkt

@@ -52,7 +52,7 @@
             "Finds the (first) element of the list that maximizes the output of the function.")
     
     (memf ((X -> any) (listof X) -> (union false (listof X)))
-	  "Determines whether the first argument produces a non-false value for any item in the second argument.")
+	  "Determines whether the function fiven as the first argument returns a non-false value for any item in the second argument.")
     (apply ((X-1 ... X-N -> Y) X-1 ... X-i (list X-i+1 ... X-N) -> Y)
 	      "Applies a function using items from a list as the arguments.")
     (compose ((Y-1 -> Z) ... (Y-N -> Y-N-1) (X-1 ... X-N -> Y-N) -> (X-1 ... X-N -> Z))

collects/lang/private/teachprims.rkt

@@ -352,8 +352,8 @@ namespace.
                       (define r (f i))
                       (unless (char? r)
                         (hocheck 'build-string
-                                 "the second argument must be a function that produces a character, ~
-                                  given ~e, which produced ~e for ~e" f r i))
+                                 "the second argument must be a function that returns a character, ~
+                                  given ~e, which returned ~e when given ~e" f r i))
                       r))))
 
 

collects/scribblings/htdp-langs/advanced.scrbl

@@ -91,7 +91,8 @@
 @; ----------------------------------------------------------------------
 @section[#:tag "advanced-syntax"]{Syntax for Advanced}
 
-In Advanced, @racket[set!] can be used to change variables. @racket[define] and
+In Advanced, @racket[set!] can be used to mutate variables, and
+@racket[define-struct]'s structures are mutatable. @racket[define] and
 @racket[lambda] can define functions of zero arguments, and function calls can
 invoke functions of zero arguments.
 
@@ -155,17 +156,17 @@ the @racket[begin] expression is the value of the first @racket[expression].}
 
 @defform[(set! variable expression)]{
 
-Evaluates @racket[expression], and then changes the definition @racket[variable]
+Evaluates @racket[expression], and then mutates the @racket[variable]
 to have @racket[expression]'s value. The @racket[variable] must be defined 
 by @racket[define], @racket[letrec], @racket[let*], or @racket[let].}
 
 
 @defform[(delay expression)]{
 
-Produces a ``promise'' to evaluate @racket[expression]. The @racket[expression]
+Returns a ``promise'' to evaluate @racket[expression]. The @racket[expression]
 is not evaluated until the promise is forced with @racket[force]; when
 the promise is forced, the result is recorded, so that any further
-@racket[force] of the promise immediately produces the remembered value.}
+@racket[force] of the promise immediately returns the remembered value.}
 
 
 
@@ -262,7 +263,7 @@ error.}
 @defform[(unless test-expression body-expression)]{
 
 Like @racket[when], but the @racket[body-expression] is evaluated when the
-@racket[test-expression] produces @racket[false] instead of @racket[true].}
+@racket[test-expression] evaluates to @racket[false] instead of @racket[true].}
 
 
 @section[#:tag "advanced-common-syntax"]{Common Syntaxes}
@@ -291,7 +292,7 @@ level as they did in the @secref["intermediate-lam"] level.
               @itemize[
                @item{@racketidfont{set-}@racket[_structure-name]@racketidfont{-}@racket[_field-name]@racketidfont{!}
                 : takes an instance of the structure and a value, and
-                changes the instance's field to the given value.}]}
+                mutates the instance's field to the given value.}]}
              define-wish
              cond
              else

collects/scribblings/htdp-langs/prim-ops.rkt

@@ -312,22 +312,22 @@
              (#,check-error-elem expression)]]{
 
    Checks that the @racket[expression] reports an error,
-   where the error messages matches the string produced by the
-   @racket[matchexpression], if it is present.}
+   where the error messages matches the
+   value of @racket[matchexpression], if it is present.}
 
 
   @defform*[#:id [check-member-of check-member-of-id]
             [(check-member-of expression expression expression ...)]]{
 
-   Checks that the first @racket[expression] produces the same value
-   as one of the following @racket[expression]s.}
+   Checks that the value of the first @racket[expression] as that of
+   one of the following @racket[expression]s.}
 
 
   @defform*[#:id [check-range check-range-id]
             [(check-range expression low-expression high-expression)]]{
 
-   Checks that the first @racket[expression] produces a number in
-   between the numbers produced by @racket[low-expression] and
+   Checks that the value of the first @racket[expression] is a number in
+   between the value of the @racket[low-expression] and the
    @racket[high-expression], inclusive.}
 
   @; ----------------------------------------------------------------------

collects/tests/htdp-lang/intm-adv.rktl

@@ -106,7 +106,7 @@
   "foldl : first argument must be a function that expects two arguments, given #<procedure:car>")
 
 (htdp-err/rt-test (build-string 2 add1)
-  "build-string : the second argument must be a function that produces a character, given #<procedure:add1>, which produced 1 for 0")
+  "build-string : the second argument must be a function that returns a character, given #<procedure:add1>, which returned 1 when given 0")
 
 (htdp-test 0 '+ (+))
 (htdp-test 1 '+ (+ 1))