[racket-dev] [plt] Push #23038: master branch updated

From: Matthias Felleisen (matthias at ccs.neu.edu)
Date: Fri Jul 15 11:58:13 EDT 2011


Guillaume, I finally realize that you replace 'produce' with 'return'. WHY? The use of 'produce' for functions in HtDP is pervasive. Do you really want to use distinct vocabularies in teachpacks+langs and the book? 





On Jul 15, 2011, at 3:29 AM, gmarceau at racket-lang.org wrote:

> gmarceau has updated `master' from 00bb92816c to c31d352f2b.
>  http://git.racket-lang.org/plt/00bb92816c..c31d352f2b
> 
> =====[ 1 Commits ]======================================================
> 
> Directory summary:
>   4.5% collects/2htdp/private/
>   8.4% collects/2htdp/
>   3.1% collects/htdp/tests/
>  31.7% collects/htdp/
>  22.1% collects/lang/private/
>  25.7% collects/scribblings/htdp-langs/
>   4.2% collects/tests/htdp-lang/
> 
> ~~~~~~~~~~
> 
> c31d352 Guillaume Marceau <gmarceau at racket-lang.org> 2011-07-15 03:27
> :
> | Standartize the vocabulary to "the function returns" and "set! mutates"
> :
>  M collects/2htdp/batch-io.rkt                         |    2 +-
>  M collects/2htdp/private/clauses-spec-and-process.rkt |    2 +-
>  M collects/2htdp/private/launch-many-worlds.rkt       |    2 +-
>  M collects/2htdp/private/world.rkt                    |    4 +-
>  M collects/2htdp/tests/test-image.rkt                 |    2 +-
>  M collects/2htdp/universe.rkt                         |    4 +-
>  M collects/htdp/convert.rkt                           |    2 +-
>  M collects/htdp/error-composition.scrbl               |   25 ++++++++++------
>  M collects/htdp/hangman.rkt                           |    2 +-
>  M collects/htdp/htdp-lib.scrbl                        |    8 ++--
>  M collects/htdp/tests/convert.rkt                     |    4 +-
>  M collects/lang/private/advanced-funs.rkt             |    6 ++--
>  M collects/lang/private/beginner-funs.rkt             |   12 ++++----
>  M collects/lang/private/intermediate-funs.rkt         |    2 +-
>  M collects/lang/private/teachprims.rkt                |    4 +-
>  M collects/scribblings/htdp-langs/advanced.scrbl      |   13 ++++----
>  M collects/scribblings/htdp-langs/prim-ops.rkt        |   12 ++++----
>  M collects/tests/htdp-lang/intm-adv.rktl              |    2 +-
> 
> =====[ Overall Diff ]===================================================
> 
> collects/2htdp/batch-io.rkt
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/2htdp/batch-io.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/2htdp/private/clauses-spec-and-process.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/2htdp/private/launch-many-worlds.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/2htdp/private/world.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/2htdp/tests/test-image.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/2htdp/universe.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/htdp/convert.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/htdp/error-composition.scrbl
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/htdp/hangman.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/htdp/htdp-lib.scrbl
> +++ NEW/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].}
> 
> - at defform[(first-order->higher-order expr)]{
> + at 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
> - at racket[expr].
> + at 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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/htdp/tests/convert.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/lang/private/advanced-funs.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/lang/private/beginner-funs.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/lang/private/intermediate-funs.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/lang/private/teachprims.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/scribblings/htdp-langs/advanced.scrbl
> +++ NEW/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
> + at 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
> - at racket[force] of the promise immediately produces the remembered value.}
> + at 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
> - at racket[test-expression] produces @racket[false] instead of @racket[true].}
> + at 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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/scribblings/htdp-langs/prim-ops.rkt
> +++ NEW/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
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --- OLD/collects/tests/htdp-lang/intm-adv.rktl
> +++ NEW/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))




Posted on the dev mailing list.