From 8c3845a768fcd2155c40a1e2167b778075f36911 Mon Sep 17 00:00:00 2001 From: Matthias Felleisen Date: Fri, 26 Oct 2007 21:58:57 +0000 Subject: [PATCH] some first scribblings for teachpacks svn: r7575 --- collects/teachpack/htdc/Docs/colors.thtml | 4 +- collects/teachpack/htdc/Docs/draw.thtml | 8 +- collects/teachpack/htdc/Docs/idraw.thtml | 8 +- collects/teachpack/htdp/Docs/image.scrbl | 103 +++++++++++++++++++ collects/teachpack/htdp/Docs/questions.scrbl | 60 +++++++++++ collects/teachpack/htdp/Docs/testing.scrbl | 60 +++++++++++ collects/teachpack/htdp/Docs/world.scrbl | 47 +++++++++ collects/teachpack/info.ss | 5 + collects/teachpack/teachpacks.scrbl | 28 +++++ 9 files changed, 313 insertions(+), 10 deletions(-) create mode 100644 collects/teachpack/htdp/Docs/image.scrbl create mode 100644 collects/teachpack/htdp/Docs/questions.scrbl create mode 100644 collects/teachpack/htdp/Docs/testing.scrbl create mode 100644 collects/teachpack/htdp/Docs/world.scrbl create mode 100644 collects/teachpack/info.ss create mode 100644 collects/teachpack/teachpacks.scrbl diff --git a/collects/teachpack/htdc/Docs/colors.thtml b/collects/teachpack/htdc/Docs/colors.thtml index 362622bafe..48dc8a31e8 100644 --- a/collects/teachpack/htdc/Docs/colors.thtml +++ b/collects/teachpack/htdc/Docs/colors.thtml @@ -13,7 +13,7 @@ at the top of your Definitions Window to import this library. 
 
                               +--------+
-                              | AColor |
+                              | IColor |
                               +--------+
                                   |
                                  / \
@@ -28,7 +28,7 @@ at the top of your Definitions Window to import this library.

-

The AColor class is abstract. Its variants (subclasses) are +

The IColor class is abstract. Its variants (subclasses) are created with no arguments.

diff --git a/collects/teachpack/htdc/Docs/draw.thtml b/collects/teachpack/htdc/Docs/draw.thtml index 636388e850..ee5bbd3053 100644 --- a/collects/teachpack/htdc/Docs/draw.thtml +++ b/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) | +-----------------------------------+ +---------------------------------------+ diff --git a/collects/teachpack/htdc/Docs/idraw.thtml b/collects/teachpack/htdc/Docs/idraw.thtml index f9d05f4a2d..a9fd55f926 100644 --- a/collects/teachpack/htdc/Docs/idraw.thtml +++ b/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) | +------------------------------------+ diff --git a/collects/teachpack/htdp/Docs/image.scrbl b/collects/teachpack/htdp/Docs/image.scrbl new file mode 100644 index 0000000000..cda4f751b7 --- /dev/null +++ b/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). +} diff --git a/collects/teachpack/htdp/Docs/questions.scrbl b/collects/teachpack/htdp/Docs/questions.scrbl new file mode 100644 index 0000000000..8b31479544 --- /dev/null +++ b/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. + +} + +} diff --git a/collects/teachpack/htdp/Docs/testing.scrbl b/collects/teachpack/htdp/Docs/testing.scrbl new file mode 100644 index 0000000000..68198f3939 --- /dev/null +++ b/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. diff --git a/collects/teachpack/htdp/Docs/world.scrbl b/collects/teachpack/htdp/Docs/world.scrbl new file mode 100644 index 0000000000..1707e94d8a --- /dev/null +++ b/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) +] diff --git a/collects/teachpack/info.ss b/collects/teachpack/info.ss new file mode 100644 index 0000000000..623d8adbc6 --- /dev/null +++ b/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 '()) + ) diff --git a/collects/teachpack/teachpacks.scrbl b/collects/teachpack/teachpacks.scrbl new file mode 100644 index 0000000000..fbc001b42e --- /dev/null +++ b/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"]