Merged changes from trunk. No conflicts.

svn: r17780

collects/2htdp/image.ss

@@ -101,11 +101,14 @@ and they all have good sample contracts. (It is amazing what we can do with kids
          angle?
          side-count?
          image-color?
+         pen-style? 
+         pen-cap?
+         pen-join?
          (rename-out [build-color make-color])
          color-red color-blue color-green color? color
          
          (rename-out [build-pen make-pen])
-         pen-color pen-width pen-style pen-cap pen-join
+         pen-color pen-width pen-style pen-cap pen-join pen
 
          image-width
          image-height

collects/2htdp/private/image-more.ss

@@ -59,12 +59,12 @@
 (define (save-image pre-image filename)
   (let* ([image (to-img pre-image)]
          [bm (make-object bitmap% 
-               (inexact->exact (ceiling (+ 2 (get-right image)))) 
-               (inexact->exact (ceiling (+ 2 (get-bottom image)))))]
+               (inexact->exact (ceiling (+ 1 (get-right image)))) 
+               (inexact->exact (ceiling (+ 1 (get-bottom image)))))]
          [bdc (make-object bitmap-dc% bm)])
     (send bdc set-smoothing 'aligned)
     (send bdc clear)
-    (render-image image bdc 1 1)
+    (render-image image bdc 0 0)
     (send bdc set-bitmap #f)
     (send bm save-file filename 'png)))
 

collects/2htdp/private/img-err.ss

@@ -8,6 +8,9 @@
          angle?
          side-count?
          image-color?
+         pen-style? 
+         pen-cap?
+         pen-join?
          image-snip->image
          bitmap->image
          check-mode/color-combination)

collects/2htdp/tests/robby-optimization-gone.ss

@@ -1,4 +1,4 @@
-#lang scheme
+#lang scheme/gui
 
 (require 2htdp/universe)
 (require 2htdp/image)
@@ -17,4 +17,4 @@
                        (set! s (string-append "-" s))
                        (rectangle 1 1 'solid 'green)))))
 
-(unless (string=? s "---") (error 'world-update-test "failed! ~s" s))
+(unless (string=? s "---") (error 'world-update-test "failed! ~s" s))

collects/2htdp/universe.ss

@@ -1,6 +1,11 @@
 #lang scheme/gui
 
 #| TODO: 
+   -- yield instead of sync
+   -- run callbacks in user eventspace
+   -- make timer fire just once; restart after on-tick callback finishes
+   -- take out counting; replace by 0.25 delay
+
    -- make window resizable :: why
    -- what if clauses are repeated in world and/or universe descriptions? 
    -- what if the initial world or universe state is omitted? the error message is bad then. 

collects/honu/main.ss

@@ -4,13 +4,18 @@
          "private/macro.ss")
 
 (provide (rename-out (#%dynamic-honu-module-begin #%module-begin)
-                     (honu-top #%top))
+                     (honu-top #%top)
+                     (semicolon \;)
+                     (honu-+ +)
+                     (honu-* *)
+                     (honu-/ /)
+                     (honu-- -)
+                     )
          #%datum
          true
          false
          display
          newline
-         \;
          else
          (rename-out
            (honu-if if)

collects/honu/private/honu-typed-scheme.ss

@@ -6,6 +6,7 @@
                      syntax/name
                      syntax/define
                      syntax/parse
+                     scheme/splicing
                      "contexts.ss"
                      "util.ss"
                      "ops.ss"
@@ -13,16 +14,25 @@
          ;; "typed-utils.ss"
          )
 
+(require (for-meta 2 scheme/base "util.ss"))
+(require (for-meta 3 scheme/base))
+
 (provide (all-defined-out))
 
 ;; macro for defining literal tokens that can be used in macros
-(define-syntax-rule (define-literal name)
-  (define-syntax name (lambda (stx)
+(define-syntax-rule (define-literal name ...)
+  (begin
+    (define-syntax name (lambda (stx)
                         (raise-syntax-error 'name
-                                            "this is a literal and cannot be used outside a macro"))))
+                                            "this is a literal and cannot be used outside a macro")))
+    ...))
 
 (define-literal honu-return)
-(define-literal \;)
+(define-literal semicolon)
+(define-literal honu-+ honu-* honu-/ honu-- honu-|| honu-%
+                honu-= honu-+= honu--= honu-*= honu-/= honu-%=
+                honu-&= honu-^= honu-\|= honu-<<= honu->>= honu->>>=
+                honu->> honu-<< honu->>> honu-< honu-> honu-<= honu->=)
 
 ;; (define-syntax (\; stx) (raise-syntax-error '\; "out of context" stx))
 
@@ -338,6 +348,13 @@
     [else (call-values parse-one (extract-until body (list #'\;
                                                            )))]))
 
+#|
+(define-honu-macro (e ... * e ... \;))
+
+(foo . bar ())
+x(2)
+|#
+
 (define (parse-block-one/2 stx context)
   (define (parse-one stx context)
     (define-syntax-class block
@@ -349,18 +366,106 @@
                                                     body.result)])
     (define-syntax-class expr
                          [pattern f])
+
     (define-splicing-syntax-class call
-                         [pattern (~seq e:expr (#%parens args ...))
-                                  #:with call #'(e args ...)])
-    (define-syntax-class expression
-                         #:literals (\;)
-                         [pattern (call:call \; . rest) #:with result #'call.call]
-                         [pattern (x:number \; . rest) #:with result #'x]
+                         [pattern (~seq e:expr (#%parens arg:expression-1))
+                                  #:with call #'(e arg.result)])
+    (define-splicing-syntax-class expression-last
+                         [pattern (~seq call:call) #:with result #'call.call]
+                         [pattern (~seq x:number) #:with result #'x]
                          )
+
+    (define-syntax-rule (define-infix-operator name next [operator reducer] ...)
+      (define-splicing-syntax-class name
+                                    #:literals (operator ...)
+                                    [pattern (~seq (~var left next) operator (~var right name))
+                                             #:with result (reducer #'left.result #'right.result)]
+                                    ...
+                                    [pattern (~seq (~var exp next))
+                                             #:with result #'exp.result]
+                                    ))
+
+    ;; TODO: maybe just have a precedence macro that creates all these constructs
+    ;;   (infix-operators ([honu-* ...]
+    ;;                     [honu-- ...])
+    ;;                    ([honu-+ ...]
+    ;;                     [honu-- ...]))
+    ;; Where operators defined higher in the table have higher precedence.
+    (define-syntax (infix-operators stx)
+      (define (create-stuff names operator-stuff)
+        (define make (syntax-lambda (expression next-expression operator-stuff)
+                                    #;
+                                    (printf "Make infix ~a ~a\n" (syntax->datum #'expression) (syntax->datum #'next-expression))
+                                    (with-syntax ([(ops ...) #'operator-stuff])
+                                      #'(define-infix-operator expression next-expression ops ...))))
+        (for/list ([name1 (drop-last names)]
+                   [name2 (cdr names)]
+                   [operator operator-stuff])
+                  (make name1 name2 operator)))
+      (syntax-case stx ()
+        [(_ first last operator-stuff ...)
+         (with-syntax ([(name ...) (generate-temporaries #'(operator-stuff ...))])
+           (with-syntax ([(result ...) (create-stuff (cons #'first
+                                                           (append
+                                                             (drop-last (syntax->list #'(name ...)))
+                                                             (list #'last)))
+
+                                                     (syntax->list #'(operator-stuff ...)))])
+             #'(begin
+                 result ...)))]))
+
+    #;
+    (infix-operators expression-1 expression-last
+                       ([honu-+ (syntax-lambda (left right)
+                                    #'(+ left right))]
+                        [honu-- (syntax-lambda (left right)
+                                               #'(- left right))])
+                       ([honu-* (syntax-lambda (left right)
+                                               #'(* left right))]
+                        [honu-/ (syntax-lambda (left right)
+                                               #'(/ left right))]))
+    
+
+    (define-syntax-class expression-top
+                         [pattern (e:expression-1 semicolon . rest)
+                                  #:with result #'e.result])
+
+
+    ;; infix operators in the appropriate precedence level
+    ;; things defined lower in the table have a higher precedence.
+    ;; the first set of operators is `expression-1'
+    (splicing-let-syntax ([sl (make-rename-transformer #'syntax-lambda)])
+      (infix-operators expression-1 expression-last
+        ([honu-= (sl (left right) #'(= left right))]
+         [honu-+= (sl (left right) #'(+ left right))]
+         [honu--= (sl (left right) #'(- left right))]
+         [honu-*= (sl (left right) #'(* left right))]
+         [honu-/= (sl (left right) #'(/ left right))]
+         [honu-%= (sl (left right) #'(modulo left right))]
+         [honu-&= (sl (left right) #'(+ left right))]
+         [honu-^= (sl (left right) #'(+ left right))]
+         [honu-\|= (sl (left right) #'(+ left right))]
+         [honu-<<= (sl (left right) #'(+ left right))]
+         [honu->>= (sl (left right) #'(+ left right))]
+         [honu->>>= (sl (left right) #'(+ left right))])
+        ([honu-|| (sl (left right) #'(+ left right))])
+        ([honu->> (sl (left right) #'(+ left right))]
+         [honu-<< (sl (left right) #'(+ left right))]
+         [honu->>> (sl (left right) #'(+ left right))]
+         [honu-< (sl (left right) #'(< left right))]
+         [honu-> (sl (left right) #'(> left right))]
+         [honu-<= (sl (left right) #'(<= left right))]
+         [honu->= (sl (left right) #'(>= left right))])
+        ([honu-+ (sl (left right) #'(+ left right))]
+         [honu-- (sl (left right) #'(- left right))])
+        ([honu-* (sl (left right) #'(* left right))]
+         [honu-% (sl (left right) #'(modulo left right))]
+         [honu-/ (sl (left right) #'(/ left right))])))
+
     ;; (printf "~a\n" (syntax-class-parse function stx))
     (syntax-parse stx
       [function:function (values #'function.result #'function.rest)]
-      [expr:expression (values #'expr.result #'expr.rest)]
+      [expr:expression-top (values #'expr.result #'expr.rest)]
       [(x:number . rest) (values #'x #'rest)]
       ))
   (cond

collects/honu/private/util.ss

@@ -1,11 +1,14 @@
 #lang scheme
 
+(provide (except-out (all-defined-out) test))
 
+#;
 (provide delim-identifier=?
          extract-until
          call-values)
 
-(require syntax/stx)
+(require syntax/stx
+         scheme/list)
 
 (define (delim-identifier=? a b)
   (eq? (syntax-e a) (syntax-e b)))
@@ -33,6 +36,19 @@
 (define-syntax-rule (call-values function values-producing)
   (call-with-values (lambda () values-producing) function))
 
+;; shortcut for treating arguments as syntax objects
+(define-syntax (syntax-lambda stx)
+  (syntax-case stx ()
+    [(_ (arg ...) body ...)
+     (with-syntax ([(temp ...) (generate-temporaries #'(arg ...))])
+       #'(lambda (temp ...)
+           (with-syntax ([arg temp] ...)
+             body ...)))]))
+
+;; removes the last element of a list
+(define (drop-last lst)
+  (take lst (sub1 (length lst))))
+
 (define (test)
   (let* ([original #'(a b c d e)]
          [delimiter #'c]

collects/meta/dist-specs.ss

@@ -91,6 +91,7 @@ i386-linux-fc6    :=tag unix
 i386-linux-f7     :=tag unix
 x86_64-linux-f7   :=tag unix
 i386-linux-f9     :=tag unix
+i386-linux-f12    :=tag unix
 i386-linux-debian :=tag unix
 i386-linux-debian-testing  :=tag unix
 i386-linux-debian-unstable :=tag unix

collects/mrlib/image-core.ss

@@ -908,7 +908,7 @@ the mask bitmap and the original bitmap are all together in a single bytes!
          curve-segment-start curve-segment-s-angle curve-segment-s-pull
          curve-segment-end curve-segment-e-angle curve-segment-e-pull 
          curve-segment-color
-         make-pen pen? pen-color pen-width pen-style pen-cap pen-join
+         make-pen pen? pen-color pen-width pen-style pen-cap pen-join pen
          
          make-bitmap bitmap? bitmap-raw-bitmap bitmap-raw-mask bitmap-angle bitmap-x-scale bitmap-y-scale 
          bitmap-rendered-bitmap bitmap-rendered-mask

collects/repos-time-stamp/stamp.ss

@@ -1 +1 @@
-#lang scheme/base (provide stamp) (define stamp "16jan2010")
+#lang scheme/base (provide stamp) (define stamp "23jan2010")

collects/syntax/private/stxparse/rep.ss

@@ -973,7 +973,7 @@
   (define (check-sc-expr x)
     (syntax-case x ()
       [sc (identifier? #'sc) (list #'sc null)]
-      [(sc arg ...) (identifier? #'sc) (list #'sc #'(arg ...))]
+      [(sc arg ...) (identifier? #'sc) (list #'sc (syntax->list #'(arg ...)))]
       [_ (raise-syntax-error #f "expected syntax class use" ctx x)]))
   (syntax-case stx ()
     [(rx sc)

collects/syntax/scribblings/parse-patterns.scrbl

@@ -104,6 +104,7 @@ means specifically @tech{@Spattern}.
                  (~not S-pattern)
                  #((unsyntax @svar[pattern-part]) ...)
                  #s(prefab-struct-key (unsyntax @svar[pattern-part]) ...)
+                 #&@#,svar[S-pattern]
                  (~rest S-pattern)
                  (@#,ref[~describe s] expr S-pattern)
                  A-pattern]
@@ -515,6 +516,17 @@ key and whose sequence of fields, when considered as a list, match the
 ]
 }
 
+@specsubform[#&@#,svar[S-pattern]]{ 
+
+Matches a term that is a box whose contents matches the inner
+@tech{@Spattern}.
+
+@myexamples[
+(syntax-parse #'#&5
+  [#&n:nat 'ok])
+]
+}
+
 @specsubform[(#, @defhere[~rest] S-pattern)]{
 
 Matches just like @scheme[S-pattern]. The @scheme[~rest] pattern form

collects/teachpack/2htdp/scribblings/image.scrbl

@@ -8,10 +8,18 @@
           lang/posn
           "shared.ss"
           "image-util.ss"
+          scribble/decode
           scribble/manual)
 
 @teachpack["image"]{Images}
 
+@(define mode/color-text
+   (make-splice
+    @list{If the @scheme[mode] is @scheme['outline] or @scheme["outline"], then the last
+     argument can be a @scheme[pen] struct or an @scheme[image-color?], but if the @scheme[mode]
+     is @scheme['solid] or @scheme["solid"], then the last argument must be an
+     @scheme[image-color?].}))
+
 @defmodule[#:require-form beginner-require 2htdp/image]
 
 The image teachpack provides a number of basic image construction functions, along with
@@ -27,70 +35,85 @@ Existing images can be rotated, scaled, and overlaid on top of each other.
                     [color image-color?])
             image?]
            [(circle [radius (and/c real? (not/c negative?))]
-                    [mode 'outline]
-                    [color pen?])
+                    [outline-mode (or/c 'outline "outline")]
+                    [pen-or-color (or/c pen? image-color?)])
             image?])]{
   Constructs a circle with the given radius, height, mode, and color.
   
-   If the @scheme[mode] is @scheme['outline], then the @scheme[color]
-  can be a @scheme[pen?] struct or an @scheme[image-color?], but if the @scheme[mode]
-  is @scheme['solid], then the @scheme[color] must be an
-  @scheme[image-color?].
-
-  @image-examples[(circle 30 "outline" "red")
-                  (circle 20 "solid" "blue")]
+  @mode/color-text
+  
+   @image-examples[(circle 30 "outline" "red")
+                   (circle 20 "solid" "blue")]
 
 }
 
-@defproc[(ellipse [width (and/c real? (not/c negative?))]
-                  [height (and/c real? (not/c negative?))]
-                  [mode mode?] 
-                  [color (or/c image-color? pen?)])
-         image?]{
+@defproc*[([(ellipse [width (and/c real? (not/c negative?))]
+                     [height (and/c real? (not/c negative?))]
+                     [mode mode?] 
+                     [color image-color?])
+            image?]
+           [(ellipse [width (and/c real? (not/c negative?))]
+                     [height (and/c real? (not/c negative?))]
+                     [mode (or/c 'outline "outline")] 
+                     [pen-or-color (or/c image-color? pen?)])
+            image?])]{
   Constructs an ellipsis with the given width, height, mode, and color.
 
-  If the @scheme[mode] is @scheme['outline], then the @scheme[color]
-  can be a @scheme[pen?] struct or an @scheme[image-color?], but if the @scheme[mode]
-  is @scheme['solid], then the @scheme[color] must be an
-  @scheme[image-color?].
+  @mode/color-text
   
   @image-examples[(ellipse 40 20 "outline" "black")
                   (ellipse 20 40 "solid" "blue")] 
 }
 
-@defproc[(triangle [side-length (and/c real? (not/c negative?))] 
-                   [mode mode?]
-                   [color (if (or (equal? mode 'outline)
-                                  (equal? mode "outline"))
-                              (or/c image-color? pen?)
-                              image-color?)])
-         image?]{
+@defproc*[([(triangle [side-length (and/c real? (not/c negative?))] 
+                      [mode mode?]
+                      [color image-color?])
+            image?]
+           [(triangle [side-length (and/c real? (not/c negative?))] 
+                      [outline-mode (or/c 'outline "outline")]
+                      [pen-or-color (or/c pen? image-color?)])
+            image?])]{
+
    Constructs a upward-pointing equilateral triangle. 
   The @scheme[side-length] argument 
   determines the 
   length of the side of the triangle.
 
-@image-examples[(triangle 40 "solid" "tan")]
+    @mode/color-text
+  
+    @image-examples[(triangle 40 "solid" "tan")]
 
 }
 
-@defproc[(right-triangle [side-length1 (and/c real? (not/c negative?))]
-                         [side-length2 (and/c real? (not/c negative?))]
-                         [mode mode?]
-                         [color image-color?])
-         image?]{
+@defproc*[([(right-triangle [side-length1 (and/c real? (not/c negative?))]
+                            [side-length2 (and/c real? (not/c negative?))]
+                            [mode mode?]
+                            [color image-color?])
+            image?]
+           [(right-triangle [side-length1 (and/c real? (not/c negative?))]
+                            [side-length2 (and/c real? (not/c negative?))]
+                            [outline-mode (or/c 'outline "outline")]
+                            [pen-or-color (or/c pen? image-color?)])
+            image?])]{
                  
   Constructs a triangle with a right angle where the two sides adjacent
   to the right angle have lengths @scheme[side-length1] and @scheme[side-length2].
 
+  @mode/color-text
+  
   @image-examples[(right-triangle 36 48 "solid" "black")]
 }
-                
-@defproc[(isosceles-triangle [side-length (and/c real? (not/c negative?))] 
-                             [angle angle?]
-                             [mode mode?]
-                             [color image-color?])
-         image?]{
+
+@defproc*[([(isosceles-triangle [side-length (and/c real? (not/c negative?))] 
+                                [angle angle?]
+                                [mode mode?]
+                                [color image-color?])
+            image?]
+           [(isosceles-triangle [side-length (and/c real? (not/c negative?))] 
+                                [angle angle?]
+                                [outline-mode (or/c 'outline "outline")]
+                                [pen-or-color (or/c pen? image-color?)])
+            image?])]{
 
  Creates a triangle with two equal-length sides, of length @scheme[side-length]
  where the angle between those sides is @scheme[angle]. The third
@@ -98,72 +121,118 @@ Existing images can be rotated, scaled, and overlaid on top of each other.
  @scheme[180], then the triangle will point up and if the @scheme[angle]
  is more, then the triangle will point down. 
  
+ @mode/color-text
+ 
  @image-examples[(isosceles-triangle 200 170 "solid" "seagreen")
                  (isosceles-triangle 60 30 "solid" "aquamarine")
                  (isosceles-triangle 60 330 "solid" "lightseagreen")]
 }
 
 
-@defproc[(square [side-length (and/c real? (not/c negative?))]
-                 [mode mode?]
-                 [color image-color?])
-         image?]{
+@defproc*[([(square [side-len (and/c real? (not/c negative?))]
+                    [mode mode?]
+                    [color image-color?])
+            image?]
+           [(square [side-len (and/c real? (not/c negative?))]
+                    [outline-mode (or/c 'outline "outline")]
+                    [pen-or-color (or/c pen? image-color?)])
+            image?])]{
 
  Constructs a square.
  
+ @mode/color-text
+ 
  @image-examples[(square 40 "solid" "slateblue")
                  (square 50 "outline" "darkmagenta")]
 
 }
 
-@defproc[(rectangle [width real?] [height real?] [mode mode?] [color image-color?]) image?]{
+@defproc*[([(rectangle [width real?]
+                       [height real?]
+                       [mode mode?]
+                       [color image-color?])
+            image?]
+           [(rectangle [width real?] 
+                       [height real?] 
+                       [outline-mode (or/c 'outline "outline")] 
+                       [pen-or-color (or/c pen? image-color?)])
+            image?])]{
   Constructs a rectangle with the given width, height, mode, and color.
+  
+  @mode/color-text
+  
   @image-examples[(rectangle 40 20 "outline" "black")
                   (rectangle 20 40 "solid" "blue")]
 }
 
-@defproc[(rhombus [side-length (and/c real? (not/c negative?))]
-                  [angle angle?]
-                  [mode mode?]
-                  [color image-color?])
-         image?]{
+@defproc*[([(rhombus [side-length (and/c real? (not/c negative?))]
+                     [angle angle?]
+                     [mode mode?]
+                     [color image-color?])
+            image?]
+           [(rhombus [side-length (and/c real? (not/c negative?))]
+                     [angle angle?]
+                     [outline-mode (or/c 'outline "outline")]
+                     [pen-or-color (or/c pen? image-color?)])
+            image?])]{
                  
 Constructs a four sided polygon with all equal sides and thus where opposite angles are equal to each
 other. The top and bottom pair of angles is @scheme[angle] and the left and right are @scheme[(- 180 angle)].
 
+@mode/color-text
+
 @image-examples[(rhombus 40 45 "solid" "magenta")
                 (rhombus 80 150 "solid" "mediumpurple")]
 }
 
-@defproc[(regular-polygon [side-length (and/c real? (not/c negative?))] 
-                          [side-count side-count?]
-                          [mode mode?]
-                          [color image-color?])
-         image?]{
+@defproc*[([(regular-polygon [side-length (and/c real? (not/c negative?))] 
+                             [side-count side-count?]
+                             [mode mode?]
+                             [color image-color?])
+            image?]
+           [(regular-polygon [side-length (and/c real? (not/c negative?))] 
+                             [side-count side-count?]
+                             [outline-mode (or/c 'outline "outline")]
+                             [pen-or-color (or/c pen? image-color?)])
+            image?])]{
   Constructs a regular polygon with @scheme[side-count] sides.
 
+  @mode/color-text
+
   @image-examples[(regular-polygon 50 3 "outline" "red")
                   (regular-polygon 40 4 "outline" "blue")
                   (regular-polygon 20 8 "solid" "red")]
 }
 
-@defproc[(star [side-length (and/c real? (not/c negative?))] 
-               [mode mode?]
-               [color image-color?])
-         image?]{
+@defproc*[([(star [side-length (and/c real? (not/c negative?))] 
+                  [mode mode?]
+                  [color image-color?])
+            image?]
+           [(star [side-length (and/c real? (not/c negative?))] 
+                  [outline-mode (or/c 'outline "outline")]
+                  [color (or/c pen? image-color?)])
+            image?])]{
   Constructs a star with five points. The @scheme[side-length] argument 
   determines the side length of the enclosing pentagon.
 
+  @mode/color-text
+
   @image-examples[(star 40 "solid" "gray")]
   
 }
 
-@defproc[(star-polygon [side-length (and/c real? (not/c negative?))]
-                       [side-count side-count?]
-                       [step-count step-count?]
-                       [mode mode?]
-                       [color image-color?])
-         image?]{
+@defproc*[([(star-polygon [side-length (and/c real? (not/c negative?))]
+                          [side-count side-count?]
+                          [step-count step-count?]
+                          [mode mode?]
+                          [color image-color?])
+            image?]
+           [(star-polygon [side-length (and/c real? (not/c negative?))]
+                          [side-count side-count?]
+                          [step-count step-count?]
+                          [outline-mode (or/c 'outline "outline")]
+                          [pen-or-color (or/c pen? image-color?)])
+            image?])]{
  
   Constructs an arbitrary regular star polygon (a generalization of the regular polygons). 
   The polygon is enclosed by a regular polygon with @scheme[side-count] sides each
@@ -173,18 +242,26 @@ other. The top and bottom pair of angles is @scheme[angle] and the left and righ
   For examples, if @scheme[side-count] is @scheme[5] and @scheme[step-count] is @scheme[2],
   then this function produces a shape just like @scheme[star].
   
+  @mode/color-text
+
   @image-examples[(star-polygon 40 5 2 "solid" "seagreen")
                   (star-polygon 40 7 3 "outline" "darkred")
                   (star-polygon 20 10 3 "solid" "cornflowerblue")]
  
 }
                 
-@defproc[(polygon [verticies (listof posn?)] 
-                  [mode mode?]
-                  [color image-color?])
-         image?]{
+@defproc*[([(polygon [verticies (listof posn?)] 
+                     [mode mode?]
+                     [color image-color?])
+            image?]
+           [(polygon [verticies (listof posn?)] 
+                     [outline-mode (or/c 'outline "outline")]
+                     [pen-or-color (or/c pen? image-color?)])
+            image?])]{
   Constructs a polygon connecting the given verticies.
   
+  @mode/color-text
+  
   @image-examples[(polygon (list (make-posn 0 0)
                                  (make-posn -10 20)
                                  (make-posn 60 0)
@@ -692,10 +769,20 @@ the parts that fit onto @scheme[scene].
 }
 
 @defproc[(scale [factor real?] [image image?]) image?]{
+
   Scales @scheme[image] by @scheme[factor]. 
+  
+  The pen sizes are also scaled and thus draw thicker (or thinner)
+  lines than the original image, unless the pen was size 
+  @scheme[0]. That pen size is treated specially to mean ``the
+  smallest available line'' and thus it always draws a one pixel
+  wide line; this is also the case for @scheme['outline] and @scheme["outline"]
+  shapes that are drawn with an @scheme[image-color?] instead of
+  a @scheme[pen].
+  
          
-         @image-examples[(scale 2 (ellipse 20 30 "solid" "blue"))
-                         (ellipse 40 60 "solid" "blue")]
+  @image-examples[(scale 2 (ellipse 20 30 "solid" "blue"))
+                   (ellipse 40 60 "solid" "blue")]
   
   
   
@@ -916,3 +1003,34 @@ The baseline of an image is the place where the bottoms any letters line up, not
 Two images are equal if they draw exactly the same way, at their current size
 (not neccessarily at all sizes).
 
+@section[#:tag "nitty-gritty"]{The nitty gritty of pixels, pens, and lines}
+
+The image library treats coordinates as if they are in the upper-left corner 
+of each pixel, and infinitesimally small.
+
+Thus, when drawing a solid @scheme[square] of whose side-length is 10, the image library
+colors in all of the pixels enclosed by the @scheme[square] starting at the upper
+left corner of (0,0) and going down to the upper left corner of (10,10),
+so the pixel whose upper left at (9,9) is colored in, but the pixel
+at (10,10) is not. All told, 100 pixels get colored in, just as expected for
+a @scheme[square] with a side length of 10.
+
+When drawing lines, however, things get a bit more complex. Specifically, 
+imagine drawing the outline of that rectangle. Since the border is
+between the pixels, there really isn't a natural pixel to draw to indicate
+the border. Accordingly, when drawing an outline @scheme[square] (without a 
+@scheme[pen] specification, but just a color as the last argument), 
+the image library uses a pen whose width is 1 pixel, but draws a line
+centered at the point (0.5,0.5) that goes down and around to the point (10.5,10.5).
+This means that the outline slightly exceeds the bounding box of the shape.
+Specifically, the upper and left-hand lines around the square are within
+the bounding box, but the lower and right-hand lines are just outside.
+
+The special case of adding 0.5 to each coordinate when drawing the square
+applies to all polygon-based shapes, but does not apply when a @scheme[pen]
+is passed as the last argument to create the shape.
+In that case, not adjustment of the pixels is performed and using a one
+pixel wide pen draws the pixels above and below the line, but each with
+a color that is half of the intensity of the given color. Using a
+@scheme[pen] with with two, colors the pixels above and below the line
+with the full intensity.