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, [email protected] 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 <[email protected]> 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].} > > -@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 > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > --- 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 > +@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 > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > --- 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)) _________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
