From ec185e60720d43687fe7c673c5fa13765af4f00d Mon Sep 17 00:00:00 2001
From: Guillaume Marceau <gmarceau@gmail.com>
Date: Fri, 8 Jul 2011 18:36:24 -0400
Subject: [PATCH] Adding files missing in the previous commit. (cherry picked
 from commit 9d465ed2987c4fa70aa2be96ff82a09467b5bc3f)

---
 collects/htdp/error-composition.scrbl | 199 ++++++++++++++++++++++++++
 collects/htdp/error-reporting.scrbl   |  47 ++++++
 collects/htdp/htdp-lib.scrbl          | 165 +++++++++++++++++++++
 collects/htdp/testing.scrbl           |  34 +++++
 4 files changed, 445 insertions(+)
 create mode 100755 collects/htdp/error-composition.scrbl
 create mode 100755 collects/htdp/error-reporting.scrbl
 create mode 100755 collects/htdp/htdp-lib.scrbl
 create mode 100755 collects/htdp/testing.scrbl

diff --git a/collects/htdp/error-composition.scrbl b/collects/htdp/error-composition.scrbl
new file mode 100755
index 0000000000..1d3107a898
--- /dev/null
+++ b/collects/htdp/error-composition.scrbl
@@ -0,0 +1,199 @@
+#lang scribble/doc
+
+@(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]
+          ))
+
+@(require scribble/decode)
+
+@(require [only-in scribble/core table style])
+
+
+@title[#:tag "error-guidelines"]{Error Message Composition Guidelines}
+
+This section lists some guidelines for writing good error messages for
+novices, as informed by @seclink["research"]{our research}.  Please
+follow these guidelines when you write code that is intended for
+beginners, including libraries and teachpacks.  It ensures that error
+messages from your code fits messages from the student languages and
+from other teachpacks.
+
+@(define (samp . text) @splice[@list{@emph{``@splice[text]''}}])
+@(define (word . text) @splice[@list{‘@splice[text]’}])
+
+@section{General Guidelines}
+
+@itemize[
+  @item{Frustrated students will peer at the error message for clues on
+    how to proceed.  Avoid offering hints, and avoid proposing any
+    specific modification. Students will follow well-meaning-but-wrong
+    advice uncritically, if only because they have no reason to doubt
+    the authoritative voice of the tool.}
+
+  @item{Be concise and clear.  Students give up reading error messages
+    if the text is too long, uses obscure words, or employs difficult
+    grammar.}]
+
+@section{Message Structure and Form}
+
+@itemize[
+  @item{Start the message with the name of the construct whose
+    constraint is being violated, followed by a colon.}
+
+  @item{State the constraint that was violated (@samp{expected a...}),
+    then contrast with what was found.  For example, @samp{this function
+    expects two arguments, but found only one}.  If needed, explain how
+    what was found fails to satisfy the constraint.  Write somewhat
+    anthropomorphically with an objective voice that is neither friendly
+    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
+    @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
+    @racket[syntax-local-expand-expression] on sub-expressions to its
+    left, so that such errors are shown first.}
+
+  @item{State the number of parts instead of saying @samp{found too many
+    parts}.  Write the code necessary to make plurals agree.}]
+
+@section{Words For Describing Code}
+
+Use only the following vocabulary words to describe code:
+
+@table[(style 'boxed '())
+@list[@list[@para{function} @para{variable} @para{argument} @para{function body}]
+      @list[@para{expression} @para{part} @para{clause} @para{top level}]
+      @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}
+    and similar binding forms.}
+
+  @item{Use @word{argument} for actual arguments and @word{variable} for
+    formal arguments in the header and body of a definition.}
+
+  @item{Use @word{part} when speaking about an s-expression that is not
+    an expression, either because it is malformed, because it occurs in
+    a non-expression position, or because it is a valid piece of syntax
+    for a macro invocation.  A well-formed and well-placed call to a
+    function, primitive, or macro is not a @word{part}, it is an
+    @word{expression}.}]
+
+@section{Words For Describing Runtime Behavior}
+
+@itemize[
+  @item{When specifying a function's behavior, say @samp{the function
+    takes ... and returns ...}}
+
+  @item{When describing a contract violation, say @samp{the function
+    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
+    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.}]
+
+
+@section{Prohibited Words}
+
+These guidelines use few terms intentionally, emphasizing commonality
+among concepts rather than technical precision (which most students do
+not appreciate anyway).
+
+@table[(style 'boxed '())
+@list[
+  @list[@para{@bold{Instead of}}
+        @para{@bold{Use}}]
+  @list[@para{procedure, primitive name, primitive operator, predicate,
+          selector, constructor}
+        @para{@samp{function}''}]
+  @list[@para{s-expression}
+        @para{@samp{expression}}]
+  @list[@para{identifier}
+        @para{@samp{argument} or @samp{variable}, depending on the use
+          in the program}]
+  @list[@para{defined name}
+        @para{@samp{function} or @samp{variable}}]
+  @list[@para{sequence}
+        @para{@samp{at least one (in parentheses)}}]
+  @list[@para{function header}
+        @para{@samp{after define}, @samp{after the name},
+          @samp{after the first argument}, ...}]
+  @list[@para{keyword}
+        @para{mention the construct directly by name, such as
+          @samp{expected a variable but found a cond}}]
+  @list[@para{built-in}  @para{Nothing --- avoid this term}]
+  @list[@para{macro} @para{Nothing --- avoid this term}]]]
+
+@section{General Vocabulary Guidelines}
+
+@itemize[
+  @item{Avoid modifiers that are not necessary to disambiguate. Write
+    @word{variable} instead of @word{local variable}, @word{defined
+    variable}, or @word{input variable}.  Write @word{clause} instead of
+    @word{question-answer clause}.  If they appear necessary for
+    disambiguation, try to find some other way to achieve this (and drop
+    the modifier).}
+
+  @item{When introducing macros with sub-parts, reuse existing
+    vocabulary words, such as @word{clause} or @word{binding} (if
+    appropriate), or just @word{part}, instead of defining new terms.}
+
+  @item{Use @word{name} only when describing the syntax of a definition
+    form.  For example, the define form in BSL should say @samp{expected
+    at least one variable after the function name}.  Outside of the
+    definition form, simply use the word @word{function} rather than
+    distinguish between (1) a function, (2) the variable that binds the
+    function, and (3) the name of that variable.
+
+    [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
+    sequence of letters.  But BSL should avoid this complexity, and
+    ASL’s error messages should maintain consistency with BSL.]}
+
+  @item{Avoid introducing technical vocabulary, even if well-known to a
+    mathematician.}]
+
+@section{Punctuation}
+
+@itemize[
+  @item{Do not use any punctuation beyond those of the normal English
+    language.  Do not write @litchar{<>} around type names, and do not
+    write quotes around keywords.}]
+
+@section[#:tag "research"]{Supporting Research}
+
+These guidelines arose from a collections of research studies held at
+the Worcester Polytechnic Institute, Brown University, and Northeastern
+University.  Further experiment details and results are described in:
+@itemize[
+  @item{@hyperlink["http://www.cs.brown.edu/~sk/Publications/Papers/Published/mfk-mind-lang-novice-inter-error-msg/"]{
+          Mind Your Language: On Novices' Interactions with Error
+          Messages}
+
+    This paper reports on a series of studies that explore beginning
+    students' interactions with the vocabulary and source-expression
+    highlighting in DrRacket.  Our findings demonstrate that the error
+    message DrRacket's old error messages significantly failed to convey
+    information accurately to students.}
+
+  @item{@hyperlink["http://www.cs.brown.edu/~sk/Publications/Papers/Published/mfk-measur-effect-error-msg-novice-sigcse/"]{
+          Measuring the Effectiveness of Error Messages Designed for
+          Novice Programmers}
+
+    This paper presents a fine-grained grading rubric for evaluating the
+    performance of individual error messages.  We applied the rubric to
+    a course worth of student work, which allowed us to characterize
+    some ways error messages fail.}]
+
+@; -----------------------------------------------------------------------------
diff --git a/collects/htdp/error-reporting.scrbl b/collects/htdp/error-reporting.scrbl
new file mode 100755
index 0000000000..4d46e46f47
--- /dev/null
+++ b/collects/htdp/error-reporting.scrbl
@@ -0,0 +1,47 @@
+#lang scribble/doc
+
+@(require scribble/manual)
+
+@title[#:tag "error-reporting"]{Error Reporting Functions} 
+
+@defmodule[htdp/error]
+
+To provide uniform error messages from the TeachPacks, this module
+provides several functions: 
+
+@defproc[(check-arg) void?]{
+ }
+
+@defproc[(check-arity) void?]{
+ }
+
+@defproc[(check-proc) void?]{
+ }
+
+@defproc[(check-result) void?]{
+ }
+
+@defproc[(check-list-list) void?]{
+ }
+
+@defproc[(check-color) void?]{
+ }
+
+@defproc[(check-fun-res) void?]{
+ }
+
+@defproc[(check-dependencies) void?]{
+ }
+
+@defproc[(natural?) void?]{
+ }
+
+@defproc[(find-non) void?]{
+ }
+ 
+@defproc[(tp-exn?) void?]{
+ }
+
+@defproc[(number->ord) void?]{
+ }
+
diff --git a/collects/htdp/htdp-lib.scrbl b/collects/htdp/htdp-lib.scrbl
new file mode 100755
index 0000000000..7d84f4abf4
--- /dev/null
+++ b/collects/htdp/htdp-lib.scrbl
@@ -0,0 +1,165 @@
+#lang scribble/doc
+
+@(require scribble/manual scribble/eval)
+@(define (htdp-ref s) @secref[#:doc '(lib "scribblings/htdp-langs/htdp-langs.scrbl") s])
+
+@title{HtDP Languages as Libraries}
+
+@; ------------------------------------------------------------
+@section{@italic{HtDP} Beginning Student}
+
+@defmodule[lang/htdp-beginner]
+
+The @racketmodname[lang/htdp-beginner] module provides the Beginning
+Student Language; see @htdp-ref["beginner"].
+
+@; ------------------------------------------------------------
+@section{@italic{HtDP} Beginning Student with Abbreviations}
+
+@defmodule[lang/htdp-beginner-abbr]
+
+The @racketmodname[lang/htdp-beginner-abbr] module provides the
+Beginning Student with Abbreviations language; see
+@htdp-ref["beginner-abbr"].
+
+@; ------------------------------------------------------------
+@section{@italic{HtDP} Intermediate Student}
+
+@defmodule[lang/htdp-intermediate]
+
+The @racketmodname[lang/htdp-intermediate] module provides the
+Intermediate Student language; see
+@htdp-ref["intermediate"].
+
+@; ------------------------------------------------------------
+@section{@italic{HtDP} Intermediate Student with Lambda}
+
+@defmodule[lang/htdp-intermediate-lambda]
+
+The @racketmodname[lang/htdp-intermediate-lambda] module provides the
+Intermediate Student with Lambda language; see
+@htdp-ref["intermediate-lam"].
+
+@; ------------------------------------------------------------
+@section{@italic{HtDP} Advanced Student}
+
+@defmodule[lang/htdp-advanced]
+
+The @racketmodname[lang/htdp-advanced] module provides the Advanced
+Student language; see @htdp-ref["advanced"].
+
+@; ------------------------------------------------------------
+@section{Pretty Big Text (Legacy Language)}
+
+@defmodule[lang/plt-pretty-big-text]
+
+The @racketmodname[lang/plt-pretty-big-text] module is similar to the
+@italic{HtDP} Advanced Student language, but with more of Racket's
+libraries in legacy form. It provides the bindings of 
+@racketmodname[mzscheme],
+@racketmodname[mzlib/etc], @racketmodname[mzlib/file],
+@racketmodname[mzlib/list], @racketmodname[mzlib/class],
+@racketmodname[mzlib/unit], @racketmodname[mzlib/include],
+@racketmodname[mzlib/defmacro], @racketmodname[mzlib/pretty],
+@racketmodname[mzlib/string], @racketmodname[mzlib/thread],
+@racketmodname[mzlib/math], @racketmodname[mzlib/match],
+@racketmodname[mzlib/shared], and @racketmodname[lang/posn].
+
+@; ------------------------------------------------------------
+
+@section{Pretty Big (Legacy Language)}
+
+@defmodule[lang/plt-pretty-big]
+
+The @racketmodname[lang/plt-pretty-big] module extends
+@racket[lang/plt-pretty-big-text] with @racketmodname[scheme/gui/base]
+and @racketmodname[lang/imageeq].  This language corresponds to the
+@onscreen{Pretty Big} legacy language in DrRacket.
+
+@; ----------------------------------------------------------------------
+
+@section{@racket[posn]s in @italic{HtDP} Languages}
+
+@defmodule[lang/posn]
+
+@defstruct[posn ([x any/c] [y any/c])]{
+
+The @racket[posn] structure type that is also provided by
+@racket[lang/htdp-beginner].}
+
+
+@; ----------------------------------------------------------------------
+
+@section{Image Equality in @italic{HtDP} Languages}
+
+@defmodule[lang/imageeq]
+
+@defproc[(image=? [i1 (is-a?/c image-snip%)]
+                  [i2 (is-a?/c image-snip%)])
+         boolean?]{
+
+The image-comparison operator that is also provided by
+@racket[lang/htdp-beginner].}
+
+@; ----------------------------------------------------------------------
+
+@section{Primitives in @italic{HtDP} Beginner}
+
+@defmodule[lang/prim]
+
+The @racketmodname[lang/prim] module several syntactic forms for
+use by the implementors of teachpacks, when the teachpack is to be
+used with the Beginner Student
+Language. In Beginner Student, primitive names (for built-in
+procedures) are distinguished from other types of expressions, so that
+they can be syntactically restricted to application positions.
+
+@defform[(define-primitive id proc-id)]{
+
+  Defines @racket[id] to be a primitive operator whose implementation
+  is @racket[proc-id], and that takes no procedures as
+  arguments. Normally, @racket[id] is exported from the teachpack and
+  @racket[proc-id] is not.}
+
+@defform[(provide-primitive id)]{
+
+  Like @racket[define-primitive], but the existing function @racket[id] is
+  exported as the primitive operator named @racket[id]. An alternative
+  to @racket[define-primitive].}
+
+@defform[(provide-primitives id ...)]{
+
+  Multiple-identifier version of @racket[provide-primitive].}
+
+@defform[(define-higher-order-primitive id proc-id (arg ...))]{
+
+  Defines @racket[id] to be a primitive operator whose implementation is
+  @racket[proc-id]. Normally, @racket[id] is exported from the teachpack and
+  @racket[proc-id] is not.
+
+  For each non-procedure argument, the corresponding @racket[arg] should be
+  an underscore. For each procedure argument, the corresponding @racket[arg]
+  should be the usual name of the procedure.
+
+  @as-examples[
+  @racketblock[
+   (define-higher-order-primitive convert-gui convert-gui/proc (f2c))
+  ]]
+}
+
+@defform[(provide-higher-order-primitive id (arg ...))]{
+
+  Like @racket[define-higher-order-primitive], but the existing function
+  @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)]{
+
+If @racket[expr] is an identifier for a first-order function (either a
+primitive or a function defined within Beginner Student), produces the
+function as a value; otherwise, the form is equivalent to
+@racket[expr].
+
+This form is mainly useful for implementing syntactic forms that, like
+the application of a higher-order primitive, allow first-order bindings
+to be used in an expression position.}
diff --git a/collects/htdp/testing.scrbl b/collects/htdp/testing.scrbl
new file mode 100755
index 0000000000..43caa5f74d
--- /dev/null
+++ b/collects/htdp/testing.scrbl
@@ -0,0 +1,34 @@
+#lang scribble/doc
+
+@(require scribble/manual)
+
+@title{Testing} 
+
+@; -----------------------------------------------------------------------------
+@defmodule[htdp/testing #:use-sources (test-engine/scheme-tests)]
+
+The library re-exports the following identifiers from test-engine/scheme-tests:
+
+ @racket[build-test-engine]
+ @racket[builder]
+ @racket[display-results]
+ @racket[error-handler]
+ @racket[exn:fail:wish]
+ @racket[generate-report]
+ @racket[get-test-engine]
+ @racket[reset-tests]
+ @racket[run-tests]
+ @racket[scheme-test-data]
+ @racket[signature-test-info%]
+
+
+@(require scribble/eval
+          (for-label racket/contract
+                     racket/class
+                     racket/gui/base
+                     lang/posn
+                     lang/imageeq
+                     lang/prim))
+
+@(define (htdp-ref s) @secref[#:doc '(lib "scribblings/htdp-langs/htdp-langs.scrbl") s])
+