Finished icons docs, renamed racket-icon-style to default-icon-style

collects/icons/main.rkt

@@ -10,7 +10,7 @@
           icon-styles
           icon-style/c
           toolbar-icon-height
-          racket-icon-style
+          default-icon-style
           icon->pict
           pict->icon
           load-icon-pict

collects/icons/private/svg.rkt

@@ -19,7 +19,7 @@
     (or (= dow 6) (= dow 0))))
 
 (defparam toolbar-icon-height (>/c 0) 16)
-(defparam racket-icon-style (or/c 'diffuse 'shiny) (if weekend? 'shiny 'diffuse))
+(defparam default-icon-style (or/c 'diffuse 'shiny) (if weekend? 'shiny 'diffuse))
 
 (defproc (icon->pict [icon (is-a?/c bitmap%)]) pict?
   (bitmap icon))
@@ -49,7 +49,7 @@
   (pict->icon (load-icon-pict category name height)))
 
 (defproc (format-icon-name [name string?] [color icon-color/c]
-                           [style (or/c icon-style/c #f) (racket-icon-style)]) string?
+                           [style (or/c icon-style/c #f) (default-icon-style)]) string?
   (cond [(and color style)  (format "~a/~a-~a" color name style)]
         [color  (format "~a/~a" color name)]
         [style  (format "~a-~a" name style)]
@@ -82,99 +82,99 @@
 ;; Common icon pict contructors
 
 (defproc (go-icon-pict [color icon-color/c] [height (>=/c 0)]
-                       [style icon-style/c (racket-icon-style)]) pict?
+                       [style icon-style/c (default-icon-style)]) pict?
   (load-icon-pict "run" (format-icon-name "go" color style) height))
 
 (defproc (bar-icon-pict [color icon-color/c] [height (>=/c 0)]
-                        [style icon-style/c (racket-icon-style)]) pict?
+                        [style icon-style/c (default-icon-style)]) pict?
   (load-icon-pict "run" (format-icon-name "bar" color style) height))
 
 (defproc (back-icon-pict [color icon-color/c] [height (>=/c 0)]
-                         [style icon-style/c (racket-icon-style)]) pict?
+                         [style icon-style/c (default-icon-style)]) pict?
   (load-icon-pict "run" (format-icon-name "back" color style) height))
 
 (defproc (stop-icon-pict [color icon-color/c] [height (>=/c 0)]
-                         [style icon-style/c (racket-icon-style)]) pict?
+                         [style icon-style/c (default-icon-style)]) pict?
   (load-icon-pict "run" (format-icon-name "stop" color style) height))
 
 (defproc (step-icon-pict [color icon-color/c] [height (>=/c 0)]
-                         [style icon-style/c (racket-icon-style)]) pict?
+                         [style icon-style/c (default-icon-style)]) pict?
   (hc-append (go-icon-pict color height style)
              (bar-icon-pict color height style)))
 
 (defproc (step-back-icon-pict [color icon-color/c] [height (>=/c 0)]
-                              [style icon-style/c (racket-icon-style)]) pict?
+                              [style icon-style/c (default-icon-style)]) pict?
   (hc-append (bar-icon-pict color height style)
              (back-icon-pict color height style)))
 
 (defproc (continue-icon-pict [color icon-color/c] [height (>=/c 0)]
-                             [style icon-style/c (racket-icon-style)]) pict?
+                             [style icon-style/c (default-icon-style)]) pict?
   (hc-append (bar-icon-pict color height style)
              (go-icon-pict color height style)))
 
 (defproc (continue-back-icon-pict [color icon-color/c] [height (>=/c 0)]
-                                  [style icon-style/c (racket-icon-style)]) pict?
+                                  [style icon-style/c (default-icon-style)]) pict?
   (hc-append (back-icon-pict color height style)
              (bar-icon-pict color height style)))
 
 (defproc (fast-forward-icon-pict [color icon-color/c] [height (>=/c 0)]
-                                 [style icon-style/c (racket-icon-style)]) pict?
+                                 [style icon-style/c (default-icon-style)]) pict?
   (define go (go-icon-pict color height style))
   (scale (hc-append go go) 3/4 1))
 
 (defproc (rewind-icon-pict [color icon-color/c] [height (>=/c 0)]
-                           [style icon-style/c (racket-icon-style)]) pict?
+                           [style icon-style/c (default-icon-style)]) pict?
   (define back (back-icon-pict color height style))
   (scale (hc-append back back) 3/4 1))
 
 (defproc (pause-icon-pict [color icon-color/c] [height (>=/c 0)]
-                          [style icon-style/c (racket-icon-style)]) pict?
+                          [style icon-style/c (default-icon-style)]) pict?
   (define gap (blank (* 1/16 height)))
   (define bar (bar-icon-pict color height style))
   (hc-append gap bar gap bar gap))
 
 (defproc (stop-sign-icon-pict [color icon-color/c] [height (>=/c 0)]
-                              [style icon-style/c (racket-icon-style)]) pict?
+                              [style icon-style/c (default-icon-style)]) pict?
   (load-icon-pict "sign" (format-icon-name "stop-sign" color style) height))
 
 (defproc (check-icon-pict [color icon-color/c] [height (>=/c 0)]
-                          [style icon-style/c (racket-icon-style)]) pict?
+                          [style icon-style/c (default-icon-style)]) pict?
   (load-icon-pict "check" (format-icon-name "check" color style) height))
 
 (defproc (magnifying-glass-icon-pict [color icon-color/c] [height (>=/c 0)]
-                                     [style icon-style/c (racket-icon-style)]) pict?
+                                     [style icon-style/c (default-icon-style)]) pict?
   (load-icon-pict "misc" (format-icon-name "magnifying-glass" color style) height))
 
 (defproc (magnifying-glass-left-icon-pict [color icon-color/c] [height (>=/c 0)]
-                                          [style icon-style/c (racket-icon-style)]) pict?
+                                          [style icon-style/c (default-icon-style)]) pict?
   (load-icon-pict "misc" (format-icon-name "magnifying-glass-left" color style) height))
 
 ;; Icons for tools and other special uses
 
-(defproc (stop-signs-icon-pict [height (>=/c 0)] [style icon-style/c (racket-icon-style)]) pict?
+(defproc (stop-signs-icon-pict [height (>=/c 0)] [style icon-style/c (default-icon-style)]) pict?
   (define h (* 2/3 height))
   (define s1 (inset (stop-sign-icon-pict 'red h style) (* 1/4 h) (* 1/2 h) 0 0))
   (define s2 (inset (stop-sign-icon-pict 'orange h style) (* 1/8 h) (* 1/4 h) 0 0))
   (define s3 (stop-sign-icon-pict 'cyan h style))
   (inset (lt-superimpose s3 s2 s1) (* 1/8 h) 0 (* 1/8 h) 0))
 
-(defproc (macro-stepper-icon-pict [height (>=/c 0)] [style icon-style/c (racket-icon-style)]) pict?
+(defproc (macro-stepper-icon-pict [height (>=/c 0)] [style icon-style/c (default-icon-style)]) pict?
   (ht-append (load-icon-pict "misc" (format-icon-name "hash-quote" #f style) height)
              (step-icon-pict 'blue height style)))
 
-(defproc (check-syntax-icon-pict [height (>=/c 0)] [style icon-style/c (racket-icon-style)]) pict?
+(defproc (check-syntax-icon-pict [height (>=/c 0)] [style icon-style/c (default-icon-style)]) pict?
   (hb-append
    (magnifying-glass-left-icon-pict #f (* 7/8 height) style)
    (check-icon-pict 'green height style)))
 
-(defproc (check-syntax-small-icon-pict [height (>=/c 0)] [style icon-style/c (racket-icon-style)]
+(defproc (check-syntax-small-icon-pict [height (>=/c 0)] [style icon-style/c (default-icon-style)]
                                        ) pict?
   (rb-superimpose
    (hc-append (check-icon-pict 'green height style)
               (blank (* 1/4 height)))
    (magnifying-glass-icon-pict #f (* 3/4 height) style)))
 
-(defproc (plt-logo-pict [height (>=/c 0)] [style icon-style/c (racket-icon-style)]) pict?
+(defproc (plt-logo-pict [height (>=/c 0)] [style icon-style/c (default-icon-style)]) pict?
   (load-icon-pict "logo" (format-icon-name "plt-logo" #f style) height))
 
 ;; ===================================================================================================
@@ -187,7 +187,7 @@
                                        (syntax->list #'(f ...)))])
        (syntax/loc stx
          (begin (defproc (f [color icon-color/c] [height (>=/c 0)]
-                            [style icon-style/c (racket-icon-style)]) (is-a?/c bitmap%)
+                            [style icon-style/c (default-icon-style)]) (is-a?/c bitmap%)
                   (pict->icon (f-pict color height style)))
                 ...)))]))
 
@@ -198,7 +198,7 @@
                                        (syntax->list #'(f ...)))])
        (syntax/loc stx
          (begin (defproc (f [height (>=/c 0)]
-                            [style icon-style/c (racket-icon-style)]) (is-a?/c bitmap%)
+                            [style icon-style/c (default-icon-style)]) (is-a?/c bitmap%)
                   (pict->icon (f-pict height style)))
                 ...)))]))
 

collects/icons/scribblings/icons.scrbl

@@ -5,7 +5,9 @@
           (for-label icons
                      slideshow/pict
                      mrlib/switchable-button
-                     racket)
+                     racket
+                     plot
+                     racket/draw)
           icons/private/doc
           icons
           slideshow/pict)
@@ -18,13 +20,13 @@
 @defmodule[icons]
 
 @(define icon-eval (make-base-eval))
-@interaction-eval[#:eval icon-eval (require icons)]
+@interaction-eval[#:eval icon-eval (require icons racket/math racket/list)]
 
 
 @section{Introduction (What is an icon, really?)}
 @margin-note*{This introduction describes an ideal, not necessarily the current state of things.}
 
-An icon is just a bitmap with an alpha channel, but most icons are not simply loaded from disk.
+As a first approximation, an icon is just a small bitmap with an alpha channel. But most icons are not simply loaded from disk.
 Icons can also be rendered from colorized SVG sources, resized, generated programmatically by drawing on a @racket[dc<%>], or composed using @racket[pict] functions.
 
 The @racketmodname[icons] module is intended to make it possible to do all of these things, and to make it easy to get common icons in different colors, heights and styles.
@@ -44,18 +46,18 @@ The author of this collection is available to adapt or create SVG icons for DrRa
 @section{Icon Parameters}
 
 @doc-apply[toolbar-icon-height]{
-The height of Racket toolbar icons.
+The height of DrRacket toolbar icons.
 
-As much as possible, please use @racket[(toolbar-icon-height)] as the @racket[height] argument when loading common icons that will be used in DrRacket toolbars and buttons, or in the toolbars and buttons of DrRacket tools.
+Use @racket[(toolbar-icon-height)] as the @racket[height] argument when loading common icons that will be used in DrRacket toolbars and buttons, or in the toolbars and buttons of DrRacket tools.
 
-(When making an icon for DrRacket's main toolbar, please try to keep it nearly square so that it will not take up too much horizontal space when the toolbar is docked vertically.
+(When making an icon for DrRacket's main toolbar, try to keep it nearly square so that it will not take up too much horizontal space when the toolbar is docked vertically.
 If you cannot, as with the Macro Stepper, send a thinner icon as the @racket[alternate-bitmap] argument to a @racket[switchable-button%].)
 }
 
-@doc-apply[racket-icon-style]{
+@doc-apply[default-icon-style]{
-The style of Racket icons. Its value is the default style argument for the functions in @secref["common-icons"].
+The style of DrRacket icons. Its value is the default style argument for the functions in @secref["common-icons"].
 
-If you use @racket[load-icon] to load icons in a DrRacket tool, to keep the tool's icons visually consistent with DrRacket's, please format the file name using @racket[format-icon-name], passing @racket[(racket-icon-style)] as the style.
+If you use @racket[load-icon] to load icons in a DrRacket tool, to keep the tool's icons visually consistent with DrRacket's, format the file name using @racket[format-icon-name] without supplying a @racket[style] argument.
 }
 
 @section{Loading Icons}
@@ -72,8 +74,7 @@ Icon sizes are given as heights to make it easier to append them horizontally.
 In the following example, applying @racket[load-icon] is equivalent to @racket[(plt-logo 100 'diffuse)]:
 @interaction[#:eval icon-eval (load-icon "logo" "plt-logo-diffuse" 100)]
 
-(In the interactions window, you would have to send the result of applying @racket[load-icon] to @racket[icon->pict] to see it.
+(In the interactions window, you would have to send the result of applying @racket[load-icon] to @racket[icon->pict] to see it.)
-The rules for printing images are different in documentation.)
 
 @doc-apply[icon-categories]{
 Returns a list of all the icon categories.
@@ -82,7 +83,7 @@ Returns a list of all the icon categories.
 }
 
 @doc-apply[icon-names]{
-Returns a list of all the names of icons in a given @racket[category].
+Returns a list of all the names of icons in the given @racket[category].
 
 @examples[#:eval icon-eval (icon-names "logo")]
 }
@@ -139,15 +140,15 @@ The remaining icon @(bar-icon 'red 14 'diffuse), returned by @racket[bar-icon],
 
 @doc-apply[magnifying-glass-icon]{
 @examples[#:eval icon-eval
-                 (list (magnifying-glass-icon #f 32 'shiny)
+                 (map (λ (color) (magnifying-glass-icon color 31 'diffuse))
-                       (magnifying-glass-icon 'orange 32 'diffuse)
+                      icon-colors)]
-                       (magnifying-glass-icon 'green 32 'diffuse))]
+Note that the uncolorized magnifying glass has a brown handle.
 }
 
 @doc-apply[magnifying-glass-left-icon]{
 @examples[#:eval icon-eval
-                 (list (magnifying-glass-left-icon #f 32 'shiny)
+                 (map (λ (color) (magnifying-glass-left-icon color 31 'shiny))
-                       (magnifying-glass-left-icon 'red 32 'diffuse))]
+                      icon-colors)]
 }
 
 @subsection{Tool Icons and Other Special Icons}
@@ -173,11 +174,47 @@ The remaining icon @(bar-icon 'red 14 'diffuse), returned by @racket[bar-icon],
 
 @section{Icon Constants and Contracts}
 
-@doc-apply[icon-colors]
+@doc-apply[icon-colors]{
-@doc-apply[icon-color/c]
+A list containing the names of allowed icon colors.
 
-@doc-apply[icon-styles]
+When an SVG icon source file is rendered, it is rendered once directly. Then, for each color corresponding to a symbol in @racket[icon-colors], it is colorized by replacing gradients, and then rendered.
-@doc-apply[icon-style/c]
+
+When loading an icon, a @racket[#f] color name loads an uncolorized rendering.
+Every icon can be loaded with a @racket[#f] color name.
+An icon can be loaded using any name in @racket[icon-colors] only if its SVG source has gradients that can be colorized.
+See @secref["new-icons"] for details.
+
+The actual hues associated with the color names are the hues of the first seven @racketmodname[plot] color numbers.
+The following example illustrates the correspondence:
+@interaction[#:eval icon-eval
+                    (require plot)
+                    (for/list ([color  (rest icon-colors)])
+                      (stop-icon-pict color 48))
+                    (parameterize ([plot-width 48]
+                                   [plot-height 48]
+                                   [plot-decorations? #f]
+                                   [plot-background-alpha 0])
+                      (for/list ([n  (in-range 7)])
+                        (plot3d-pict (surface3d (λ (x y) (- (sqr x) (sqr y))) -1 1 -1 1
+                                                #:color n #:line-color n
+                                                #:samples 11 #:line-width 1))))]
+This example also shows how to use @racketmodname[plot] to create icon @racket[pict]s from mathematical functions.
+}
+
+@doc-apply[icon-color/c]{
+A contract that identifies color names.
+}
+
+@doc-apply[icon-styles]{
+Typical icon styles.
+
+It is not necessary to have a version of each icon in each style.
+But if an icon has different styles, it should have these.
+}
+
+@doc-apply[icon-style/c]{
+A contract that identifies icon styles.
+}
 
 
 @section{Icon @racket[pict]s}
@@ -199,12 +236,21 @@ Corresponds to @racket[load-icon]. In fact, @racket[load-icon] uses @racket[load
 @doc-apply[pict->icon]{
 Convert from an icon to a @racket[pict], and back.
 
-The conversion from @racket[pict]s to icons can be lossy:
+The conversion from @racket[pict]s to icons can be lossy because it renders vector graphics as a bitmap. For example, converting text can look especially horrible:
 @interaction[#:eval icon-eval
                     (scale (text "Hello" null 10) 5)
                     (scale (icon->pict (pict->icon (text "Hello" null 10))) 5)]
 
 Therefore, when composing icons from parts, work only with @racket[pict]s, and convert to an icon as the last step.
+
+On the other hand, @racket[(compose pict->icon icon->pict)] always returns an equivalent icon:
+@interaction[#:eval icon-eval
+                    (define not-blurry (magnifying-glass-icon 'green 64 'shiny))
+                    not-blurry
+                    (define still-not-blurry
+                      (for/fold ([icon not-blurry]) ([i  (in-range 30)])
+                        (pict->icon (icon->pict icon))))
+                    still-not-blurry]
 }
 
 @doc-apply[go-icon-pict]
@@ -242,8 +288,77 @@ These return typical ``playback control'' icons, as @racket[pict]s.
 @doc-apply[plt-logo-pict]{ Corresponds to @racket[plt-logo]. }
 
 
-@section{Making New SVG Icons}
+@section[#:tag "new-icons"]{Making New SVG Icons}
 
-This section is intended for Racket developers.
+This section is intended for Racket developers, who have permission to add SVG icon sources to the repository.
 
-In the future, this section will tell where to install SVG sources and how to render them so they can be used as icons.
+Take the following steps to add an SVG icon to Racket's repository.
+
+@bold{1. Create an SVG file.}
+The author of this module uses @link["http://inkscape.org"]{Inkscape}, a free software vector graphics program.
+Another option is of course @link["http://www.adobe.com/illustrator"]{Adobe Illustrator}.
+
+If the icon (or part of it) can be generated by a mathematical function, use Racket's @racketmodname[plot] library.
+Specifically, use @racket[plot] or @racket[plot3d], passing an @racket[#:out-file] argument with a @racket[".svg"] file name extension.
+Use @racket[plot-file] or @racket[plot3d-file] in scripts.
+Set @racket[plot-decorations?] to @racket[#f] and @racket[plot-background-alpha] to @racket[0].
+
+If the icon (or part of it) can be otherwise generated programmatically, use Racket to draw on an @racket[svg-dc%], or use @link["http://www.imagemagick.org"]{ImageMagick} and its MVG or MagickWand languages.
+
+Use @tt{collects/icons/private/svg/run/stop-diffuse.svg} and @tt{collects/icons/private/svg/run/stop-shiny.svg} as simple examples of icons in diffuse and shiny styles.
+Note that the light source is apparently above and slightly to the left.
+
+@bold{2. Make SVG gradients colorizable.}
+Do this by editing the SVG file to change the names of gradients.
+It cannot currently be done in Inkscape, but a text editor's find-and-replace-all works perfectly.
+
+If part of the icon should be colorizable, find the gradient for that part and change its name to @tt{diffuseColorGradient}.
+Make sure the first stop is a dark version of the default color and the second stop is the default color.
+For specular highlights, do not use @tt{diffuseColorGradient}, but overlay the image with partially transparent gradients.
+
+For shiny icons, change undershine gradients (the bright spots opposite the light source that make icons look like candy or transparent plastic) to have the name @tt{undershineGradient}.
+Make sure the first stop is fully opaque with a hue close to the default color's, and the second stop is fully transparent.
+
+@bold{3. Place the SVG file in the @racketmodname[icons] collection.}
+Put it in the directory @tt{collects/icons/private/svg/<category>} where @tt{<category>} is a category appropriate for the icon.
+
+Feel free to make new category directories or even subcategories (by making subdirectories).
+For example, to make a subcategory of @racket["run"] called @racket["silly"], create a subdirectory @tt{silly} in the @tt{run} directory.
+The icon can then be loaded from category @racket["run/silly"].
+
+If the icon has diffuse and shiny versions, name them @tt{<name>-diffuse.svg} and @tt{<name>-shiny.svg}.
+
+@bold{4. Re-render PNGs.}
+Install Inkscape, then run the program @tt{collects/icons/private/svg/render-png.rkt}.
+This will delete every PNG rendering, and re-render every SVG source file in @tt{collects/icons/private/svg}.
+
+Renderings are done at specific power-of-two heights.
+For non-logo icons, the heights are currently 16, 32 and 64.
+Logos are rendered at 16, 32, 64, 128, 256 and 512.
+
+Uncolorized renders are put in a subdirectory named after their size.
+For example, a render of @tt{run/silly/walks-diffuse.svg} at height 64 will have the name @tt{run/silly/64/walks-diffuse.png}.
+
+Colorized renders are put in a further subdirectory named after their color.
+For example, a red render of @tt{run/silly/walks-diffuse.svg} at height 64 will have the name @tt{run/silly/64/red/walks-diffuse.png}.
+
+@bold{5. Load the icon.}
+For example, to load a red render of @tt{walks-diffuse.svg} at height 50, do
+
+@racketblock[(load-icon-pict "run/silly"
+                             (format-icon-name "walks" 'red 'diffuse)
+                             50)]
+
+For this, @racket[format-icon-name] returns @racket["red/walks-diffuse"].
+Then @racket[load-icon-pict] finds the first rendered height not less than @racket[50], which is @racket[64], loads a bitmap from @racket["run/silly/64/red/walks-diffuse.png"], converts it to a @racket[pict], and scales it by @racket[(/ 50 64)].
+
+For convenience, write functions to load the icon; for example,
+@racketblock[
+(define (silly-walk-icon-pict color height [style (default-icon-style)])
+  (load-icon-pict "run/silly"
+                  (format-icon-name "walk" color style)
+                  height))
+                                                                            
+(define (silly-walk-icon color height [style (default-icon-style)])
+  (pict->icon (silly-walk-icon-pict color height style)))
+]

collects/icons/tests/icon-tests.rkt

@@ -71,7 +71,7 @@
 
 (rb-superimpose (check-icon-pict 'green (toolbar-icon-height) 'diffuse)
                 (scale (magnifying-glass-icon-pict
-                        #f (toolbar-icon-height) (racket-icon-style))
+                        #f (toolbar-icon-height) (default-icon-style))
                        3/4))
 
 (define not-blurry

collects/plot/scribblings/params.scrbl

@@ -62,6 +62,10 @@ See @(racket ->pen-color) and @(racket ->brush-color) for details on how PLoT in
 When @(racket #t), certain renderers draw simplified plots to speed up drawing. PLoT sets it to @(racket #t), for example, when a user is clicking and dragging a 3D plot to rotate it.
 }
 
+@doc-apply[plot-decorations?]{
+When @(racket #f), axes, axis labels, ticks, tick labels, and the title are not drawn.
+}
+
 @section{Lines}
 
 @doc-apply[line-samples]