[racket-dev] [plt] Push #23038: master branch updated
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))
![[logo]](/logo.png){kind=logo}