some first scribblings for teachpacks

svn: r7575

collects/teachpack/htdc/Docs/colors.thtml

@@ -13,7 +13,7 @@ at the top of your Definitions Window to import this library.
 <pre>
 <code>
                               +--------+
-                              | AColor |
+                              | IColor |
                               +--------+
                                   |
                                  / \
@@ -28,7 +28,7 @@ at the top of your Definitions Window to import this library.
 </pre>
 </p>
 
-<p>The <code>AColor</code> class is abstract. Its variants (subclasses) are
+<p>The <code>IColor</code> class is abstract. Its variants (subclasses) are
 created with no arguments. 
 </p>
 

collects/teachpack/htdc/Docs/draw.thtml

@@ -24,10 +24,10 @@ import geometry.*;
  | boolean bigBang(int,int,double)   |       +---------------------------------------+
  | boolean endOfTime(String)         |       | boolean show()                        |
  | World endOfWorld(String)          |       | boolean close()                       |
- |                                   |       | boolean drawCircle(Posn,int,AColor)   |
- |                                   |       | boolean drawDisk(Posn,int,AColor)     |
- | abstract World onTick()           |       | boolean drawRect(Posn,int,int,AColor) |
- | abstract World onKeyEvent(String) |       | boolean drawLine(Posn,Posn,AColor)    |
+ |                                   |       | boolean drawCircle(Posn,int,IColor)   |
+ |                                   |       | boolean drawDisk(Posn,int,IColor)     |
+ | abstract World onTick()           |       | boolean drawRect(Posn,int,int,IColor) |
+ | abstract World onKeyEvent(String) |       | boolean drawLine(Posn,Posn,IColor)    |
  | abstract boolean draw()           |       | boolean drawString(Posn,String)       |
  +-----------------------------------+       +---------------------------------------+
 </code>

collects/teachpack/htdc/Docs/idraw.thtml

@@ -25,10 +25,10 @@ import geometry.*;
   | void bigBang(int,int,double)    |       +------------------------------------+
   | World endOfTime(String)         |       | void show()                        |
   | World endOfWorld(String)        |       | void close()                       |
-  | abstract void onTick()          |       | void drawCircle(Posn,int,AColor)   |
-  | abstract void onKeyEvent(String)|       | void drawDisk(Posn,int,AColor)     |
-  | abstract void draw()            |       | void drawRect(Posn,int,int,AColor) |
-  +---------------------------------+       | void drawLine(Posn,Posn,AColor)    |
+  | abstract void onTick()          |       | void drawCircle(Posn,int,IColor)   |
+  | abstract void onKeyEvent(String)|       | void drawDisk(Posn,int,IColor)     |
+  | abstract void draw()            |       | void drawRect(Posn,int,int,IColor) |
+  +---------------------------------+       | void drawLine(Posn,Posn,IColor)    |
                                             | void drawString(Posn,String)       |
                                             +------------------------------------+
 </code>

collects/teachpack/htdp/Docs/image.scrbl

@@ -0,0 +1,103 @@
+#lang scribble/doc
+
+@begin[(require
+	 (lib "manual.ss" "scribble"))
+       
+       (require-for-label 
+	 (lib "lang.ss" "big")
+	 "../image.ss")]
+
+@title[#:tag "image"]{Manipulating Images: image.ss}
+
+The  teachpack provides primitives for constructing and manipulating
+images. Basic images are created as outlines or solid shapes. Additional
+primitives allow for the composition of images.
+
+;; {Mode} is one of the following two symbols or strings: 
+
+;; -- @scheme['solid]
+
+;; -- @scheme['outline]
+
+;; -- @scheme["solid"]
+
+;; -- @scheme["outline"]
+
+Interpretation: @scheme['solid] is used for creating solid basic
+  shapes; @scheme['outline] is used for creating outlines of basic
+  shapes. Strings are used in an analogous manner. 
+
+@scheme[(define-struct color (red blue green))]
+
+;; A [CS] is a structure: @scheme[(make-color N N N)]
+
+;; where N is between 0 and 255. 
+
+;; [Color] is one of:
+
+;; -- a color symbol, e.g., @scheme['blue]
+
+;; -- a color string, e.g., @scheme["blue"]
+
+;; -- a CS, e.g., @scheme[(make-color 0 0 255)], which also denotes blue. 
+
+;; Interpretation: @scheme[Color] arguments are used to paint the shapes
+
+;; or their outlines. See below for more information about color structs.
+
+The following predicate specifies what a valid image color is: 
+
+@defproc[(image-color? [x any]) boolean?]{
+ Determines if the input is a valid image color.}
+
+@section[#:tag "creational"]{Creating Basic Shapes}
+
+@defproc[(rectangle [w number?] [h number?] [m Mode] [c Color]) image?]{
+ Creates a @scheme[w] by @scheme[h] rectangle, filled in according to
+ @scheme[m] and painted in color @scheme[c]}
+
+@defproc[(circle [r number?] [m Mode] [c Color]) image?]{
+ Creates a circle or disk of radius @scheme[r], filled in according to
+ @scheme[m] and painted in color @scheme[c]}
+
+@defproc[(ellipse [w number?] [h number?] [m Mode] [c Color]) image?]{
+ Creates a @scheme[w] by @scheme[h] ellipse, filled in according to
+ @scheme[m] and painted in color @scheme[c]}
+
+@defproc[(triangle [s number?] [m Mode] [c Color]) image?]{ 
+ Creates an upward pointing equilateral
+ triangle whose side is @scheme[s] pixels long, filled in according to
+ @scheme[m] and painted in color @scheme[c]}
+
+@defproc[(star [n (and/c number? (>=/c 2))]
+	       [outer (and/c number? (>=/c 1))]
+	       [inner (and/c number? (>=/c 1))]
+	       [m Mode]
+	       [c Color]) image?]{
+ Creates a multi-pointed star with @scheme[n] points, an @scheme[outer]
+ radius for the max distance of the points to the center, and
+ an @scheme[inner] radius for the min distance to the center. }
+
+@defproc[(line [x number?][y number?] [c Color]) image?]{
+ Creates a line colored @scheme[c] from (0,0) to @scheme[(x,y)].
+ See @scheme[add-line] below.
+}
+
+@defproc[(text [s string?] [f (and/c number? positive?)] [c Color]) Image]{
+ Creates an image of the text @scheme[s] at point size @scheme[f] 
+ and painted in color @scheme[c].}
+
+@section[#:tag "composition"]{Composing Shapes}
+
+@defproc[(add-line [i image?] 
+		   [x number?]
+		   [y number?]
+		   [z number?]
+		   [u number?]
+		   [c Color]) image?]{
+ Add a line from @scheme[(x,y)] to @scheme[(z,u)] to image @scheme[i] and
+		   paints it color @scheme[c].}
+
+@defproc[(overlay [img image?] [img2 image?] [img* image?] ...) image?]{
+ Overlays all images on their pinhole (see below).
+}

collects/teachpack/htdp/Docs/questions.scrbl

@@ -0,0 +1,60 @@
+#lang scribble/doc
+
+@begin[(require
+	 (lib "manual.ss" "scribble"))
+       
+       (require-for-label 
+	 (lib "lang.ss" "big"))]
+
+@title[#:tag "questions"]{Questions concerning scribble}
+
+Here are my questions. Feel free to point me to specific pieces of
+ documentations. As a matter of fact, I'd almost prefer that. 
+
+@itemize{
+
+@item{
+   world.ss imports image.ss and re-exports all the bindings.
+
+   So in world.scrbl, I have to require @scheme[(for-label "world.ss")] but
+   when I do so, I don't get bindings for functions from
+   @scheme[image.ss].
+
+   If I require @scheme[(for-label "image.ss")] in addition, I get an
+   import conflict. What is the proper solution? 
+}
+
+@item{
+   I'd like to make graphical examples. I looked at the "quick" guide to
+   see how you do this, but I can't figure out how to run all this under
+   mred's control.
+}
+
+@item{
+   For the teachpack definitions, I like to spell out data definitions like
+   in HowToDesign. For example, 
+
+
+;; {Mode} is one of the following two symbols or strings: 
+
+;; -- @scheme['solid]
+
+;; -- @scheme['outline]
+
+;; -- @scheme["solid"]
+
+;; -- @scheme["outline"]
+
+   I want the two semi-colons, I want the scheme mode for the constants,
+   and I want the first part to look like an ordinary test line. 
+   [slatex and thtml do this for me]
+
+   I would also like to use @scheme[Mode] as if it were some exported
+   variable so that I can jump to its definition from other places in the
+   documentation. But I also don't want to introduce a (fake) visible
+   definition. I don't think deftech and defterm are the right tools. But
+   perhaps that's all there is to it. 
+
+}
+
+}

collects/teachpack/htdp/Docs/testing.scrbl

@@ -0,0 +1,60 @@
+#lang scribble/doc
+
+@begin[(require
+	 (lib "manual.ss" "scribble"))
+       
+       (require-for-label 
+	 (lib "lang.ss" "big")
+	 "../testing.ss")]
+
+@title[#:tag "testing"]{Testing: testing.ss}
+
+The @scheme[testing.ss] teachpack provides forms for formulating test cases
+and a primitive for reporting on test cases. 
+
+@defform[(check-expect test-expression expected-value)]{
+          where @scheme[test-expression] and
+          @scheme[expected-value] are both expressions, though the latter
+          should ideally be just a value. 
+
+          The form evaluates @scheme[test-expression] and then
+          verifies that its value is the same as
+          @scheme[expected-value].}
+
+@defform[(check-within test-expression expected-value delta)]{
+          where @scheme[test-expression], @scheme[expected-value], and
+          @scheme[delta] are expressions. 
+
+The form evaluates @scheme[test-expression] and verifies that all numbers
+within the value are equal to numbers in analogous positions in
+@scheme[expected-value], plus or minus @scheme[delta].
+
+Thus,
+@schemeblock[(check-within (make-posn 10 .1) (make-posn 10 .109) .01)]
+succeeds while
+@schemeblock[(check-within (make-posn 10 .1) (make-posn 10 .19) .01)]
+fails. 
+}
+
+@defform[(check-error test-expression message-string)]{
+ where @scheme[test-expression] and @scheme[expected-message] are expressions. 
+
+The form evaluates @scheme[test-expression] and verifies that it signals an
+error with @scheme[message-string] as the error report. If
+@scheme[test-expression] doesn't signal an error, the test case fails. 
+}
+
+@defproc[(generate-report) true]{
+ Displays statistics of running tests created with  @scheme[check-expect],
+ @scheme[check-within], and @scheme[check-error].
+
+ Place it at the end of the program or run the expression from the
+ Interactions window after clicking RUN.
+}
+
+@section{Style}
+
+While you are developing functions, you should place test cases below the
+relevant function definitions in the Definitions Window of
+drscheme. Eventually though, you should collect all these tests at the bottom of
+the window.

collects/teachpack/htdp/Docs/world.scrbl

@@ -0,0 +1,47 @@
+#lang scribble/doc
+
+@begin[(require
+	 (lib "manual.ss" "scribble"))
+       (require-for-label
+	 (lib "lang.ss" "big")
+	 (only "../world.ss" run-simulation)
+	 "../image.ss"
+	 )]
+
+@title[#:tag "world"]{Simulations and Animations: world.ss}
+
+The teachpack provides two kinds of functions. The first five allow
+students to simulate a small world of animated drawings and games: 
+
+@defproc[(run-simulation
+	   [w natural-number/c]
+	   [h natural-number/c]
+	   [r number?]
+	   [create-image (-> natural-number/c scene)]
+	   [gifs? boolean? #f])
+	 true]{
+   creates and shows a canvas of width @scheme[w] and height @scheme[h] , 
+   starts a clock, making it tick every @scheme[r] (usually fractional)
+   seconds. Every time the clock ticks, drscheme applies @scheme[create-image] to
+   the number of ticks passed since this function call. The results of
+   these applications are displayed in the canvas.
+
+   The fifth (and last) argument is optional. Providing @scheme[true] as
+   the fifth argument causes drscheme to collect the scenes that the
+   animation generates and to create an animated GIF from the results. Both
+   the intermediate images as well as the final animated GIF are saved in a
+   user-specified directory. This is useful for writing documentation and
+   for describing students work.  
+}
+
+In addition, 
+@schemeblock[
+(define (create-UFO-scene height)
+  (place-image UFO 50 height (empty-scene 100 100)))
+
+(define UFO
+  (overlay (circle 10 'solid 'green)
+           (rectangle 40 4 'solid 'green)))
+
+(run-simulation 100 100 (/ 1 28) create-UFO-scene)
+]

collects/teachpack/info.ss

@@ -0,0 +1,5 @@
+(module info (lib "infotab.ss" "setup")
+  (define name "Teachpacks")
+  (define scribblings '(("teachpacks.scrbl" (multi-page))))
+  (define compile-omit-files '())
+  )

collects/teachpack/teachpacks.scrbl

@@ -0,0 +1,28 @@
+#lang scribble/doc
+
+@begin[(require (lib "manual.ss" "scribble"))
+       (require-for-label (lib "lang.ss" "big"))]
+
+@title{Teachpacks}
+
+Teaching languages are small subsets of a full programming language. While
+such restrictions simplify error diagnosis and the construction of tools,
+they also make it impossible (or at least difficult) to write some
+interesting programs. To circumvent this restriction, it is possible to
+import teachpacks into programs written in a teaching language. 
+
+In principle, a teachpack is just a library. Like any other Scheme library,
+it may export values, functions, and even new constructs. In contrast to an
+ordinary library, however, a teachpack must enforce the contracts of the
+"lowest" teaching language into which it is exported and signal errors in a
+way with which students are familiar. 
+
+All but the last section describe the teachpacks that are available for
+"How to Design Programs" and that will remain around for the second
+edition.  The last section describes how to create your own
+teachpacks.
+
+@include-section["htdp/Docs/testing.scrbl"]
+@include-section["htdp/Docs/image.scrbl"]
+@include-section["htdp/Docs/world.scrbl"]
+@include-section["htdp/Docs/questions.scrbl"]