
_texpict_ is a MzScheme/MrEd library for creating pictures using a
MrEd dc<%> (including post-script-dc% for _PostScript_ output) or
_LaTeX_ as the back-end. The library was originally designed for LaTeX
output, hence the name.

Pictures are created as `pict' structures. Some procedures in the
texpict library create new simple picts (e.g., `hline'). Others build
new picts out of existing picts (e.g., `ht-append'). In the latter
case, the embedded picts retain their identity, so that offset-finding
functions (e.g., `find-lt') can find the offset of an embedded pict in
a larger pict.

A pict has the following structure:
                w
        ------------------
       |                  | a  \
       |------------------|    |
       |                  |    | h
       |------------------|    |
       |                  | d  /
        ------------------     

For a single text line, d is descent below the baseline and
a + d = h. For multiple text lines (created with vX-append), a is 
ascent of top line above baseline and d is descent of bottom line,
so a + d < h. Most other boxes have d = 0 and a = h.

The size information for a pict is computed when the pict is
created. This strategy supports programs that create new picts though
arbitrarily complex computations on the size and shape of existing
picts. However, it also means that a pict cannot be generated before
its target device is known.

A slightly different set of picture-making function are available for
MrEd and LaTeX output. For example, the LaTeX set includes `tex',
which accepts a string of arbitrary LaTeX code, and the MrEd set
includes `dc', which accepts an arbitrary Scheme procedure for drawing
to a dc<%>.

When creating pictures with `picture' or `cons-picture', or when
finding relative picture locations with `find-lt', etc., the coordiate
system is upside-down: (0, 0) is in the lower left.

Slideshow output
----------------

Slideshow (see the "slideshow" collection) takes care of configuring
texpict and rendering them to the screen or printer. In particular,
the `slide' function takes any number of picts and assembles them into
a slide.

If you are using Slidshow, skip the following two sections. In the
reference below, functions are "MrEd only" are available, and
functions marked "LaTeX only" are not available.

MrEd (or PostScript) output
---------------------------

The MrEd texpict function set is loaded by the _mrpict.ss_ library.
The library is available in unit form via _mrpictr.ss_, which produces
a unit importing mred^. The _mrpicts.ss_ library file defines the
unit's signature.

When creating a picture for a MrEd dc<%> that contains text, texpict
needs a drawing context for measuring the text. Provide a dc<%> before
constructing pictures via the `dc-for-text-size' parameter. The dc<%>
should have the same text-measuring results as the destination dc<%>;
in particular, use a post-script-dc% for preparing PostScript output,
and a bitmap-dc% will work fine for bitmap-dc% or canvas% output.

The `draw-pict' function takes a picture, a device context

 ;; Example of prodcuing PostScript output
 (require (lib "mrpict.ss" "texpict"))

 ;; Create PS context
 (define ps-dc (make-object post-script-dc%))
 (send ps-dc start-doc "Pict output")
 (send ps-dc start-page)

 ;; Install context for sizing
 (dc-for-text-size ps-dc)

 ;; Create the pict
 (define p ...)

 ;; Output pict
 (draw-pict p ps-dc 0 0)
 (send ps-dc end-page)
 (send ps-dc end-doc)

If the output dc<%> has a "user scale", it is not reflected in the
size information reported for pictures. This is consistent with MrEd's
usual policy for reporting size information.

LaTeX output
------------

The LaTeX texpict function set is loaded by the _texpict.ss_ library.
The library is available in unit form via _texpictr.ss_, which
produces a unit with no imports. The _texpicts.ss_ library file
defines the unit's signature.

To create a LaTeX picture, assemble a pict and then
call `pict->string'. This string can be `display'ed to obtain the
LaTeX code, which is usually of the form:
   \begin{picture} ... \end{picture}
When using colors, the output may be of the form:
   \special{color push ...} ... \special{color pop ...}
so consider putting the output in an \hbox{} when using color.

The `tex' function creates a pict given an arbitrary LaTeX
expression as a string. Initially, `tex' guess at the size of the
resulting pict. (It always guesses 10 x 10.) The LaTeX expression
generated for a `tex' pict causes information to be written to an
auxilliary file when LaTeX evaluates the expression. If you use
`tex' boxes, then:

   * Use the package "mztp.sty" at the start of your LaTeX
     document "X.tex".
   * In the MzScheme code creating `tex' picts, call
     (read-in-sizes "X.mztp") before calling `tex'.
   * Run the texpict-LaTeX cycle twice to get properly
     draw pictures.

texpict keys `tex' size information on the exact LaTeX expression
provided to `tex'. If you use a single `tex' pict in two different
contexts where the provided expression produces differently sized
output, texpict will not distinguish the uses (and the size of the
first instance of the pict will be used) by default. The
`serialize-tex-picts' parameter can solve this problem, but
serialization requires that the output is built in exactly the same
order every time, and generally requires more texpict-tex cycles to
reach a fixed point after a small change to the output. The
`tex-series-prefix' parameter may be used to explicitly tag `tex'
sequences in different contexts.

For LaTeX output, all positions and sizes must be specified as exact
integers, but texpict does not check that exact integers are supplied.

------------------------------------------------------------
Structures
------------------------------------------------------------

A pict is an instance of the `pict' structure type:

> struct:pict :: (struct pict (draw width height ascent descent children))

The `children' field is a list of `child' structures:

> struct:child :: (struct child (pict dx dy))

------------------------------------------------------------
Procedures
------------------------------------------------------------

   ;; -- MrEd only --
   ;; Parameter specifying the dc<%> to use for measuring text.
   ;; Default: #f
>  dc-for-text-size

   ;; -- LaTeX only --
   ;; Load `tex' pict size information generated by a LaTeX run.
>  read-in-sizes  ; string -> void

   ;; -- LaTeX only --
   ;; Parameter specifying whether to produce LaTeX commands to
   ;; produce size information for a future run.
   ;; Default: #t
>  output-measure-commands

   ;; -- LaTeX only --
   ;; Parameter specifying whether the `pict2e' package is active.
   ;; Default: #f
>  using-pict2e-package

   ;; -- LaTeX only --
   ;; Parameter specifying whether to draw precise lines for `connect'
   ;; with bezier curves. The value is a Boolean or a procedure that
   ;; takes a length and returns the number of points to use.
   ;; Default: #f
>  draw-bezier-lines

   ;; -- LaTeX only --
   ;; Parameter to use the old implementation of `connect'.
   ;; Default: #f
>  use-old-connect

   ;; -- LaTeX only --
   ;; Parameter specifying a string to embed in the sizing key for a
   ;; pict created with `tex'. The prefix is applied when the `tex'
   ;; pict is created. Turning on the `serialize-tex-picts' parameter
   ;; effectively generates a new series prefix for every `tex' pict.
   ;; Default: #f
>  tex-series-prefix
   
   ;; -- LaTeX only --
   ;; Parameter specifying whether to assign serial numbers to
   ;; `tex'-generated strings for sizing purposes. Serial numbers
   ;; allow the same tex string to be used in multiple contexts, but
   ;; the output must be built in the same order every time.
   ;; Default: #f
>  serialize-tex-picts

   ;; Parameter specifying whether to draw in B&W or color (when
   ;; `colorize' is used).
   ;; Default: #f
>  black-and-white

   ;; Find an embedded picture; see bottom for the definition of pict-path
>  find-lt  ; (left & top)  ; pict pict-path -> dx dy
>  find-lc  ; (left & vertical center)
>  find-lb  ; (left & bottom)
>  find-ltl ; (left and top baseline)
>  find-lbl ; (left and bottom baseline)
>  find-ct  ; (horizontal center & top)
>  find-cc
>  find-cb
>  find-ctl
>  find-cbl
>  find-rt
>  find-rc
>  find-rb
>  find-rtl
>  find-rbl

   ;; Create a new pict that hides the given pict from find-XX
>  launder  ; pict -> pict

   ;; Create an empty pict
>  blank        ; -> pict
                ; s -> pict ; s is side length of square
                ; w h -> pict
                ; w h d -> pict

   ;; -- LaTeX only --
   ;; Create picts from LaTeX code
>  tex               ; string -> pict
>  text-line         ; string -> pict
>  text-line/phantom ; string string -> pict
>  tex-paragraph     ; w string ['top|'bottom] -> pict

   ;; -- MrEd only --
   ;; Create a pict from a string, style, size, and rotation.
   ;;  A style is one of
   ;;    null (the default, same a 'default),
   ;;    a font% object,
   ;;    a font family symbol (e.g., 'roman),
   ;;    a font face string (e.g., "-adobe-symbol"),
   ;;    `(bold . ,style),
   ;;    `(italic . ,style), 
   ;;    `(subscript . ,style), or
   ;;    `(supersript . ,style).
   ;;  A size is an exact number in [1, 255] in pixels; the
   ;;   default size is 12, but the size is ignored if
   ;;   a font% object is provided in the style.
   ;;  The default rotation is 0; for a non-zero rotation,
   ;;   the pict covers the rotated text, and the descent
   ;;   and ascent are zero.
>  text      ; string [style [size [angle]]] -> pict
   ;; Same, but use small caps:
>  caps-text ; string [style [size]] -> pict
   ;; A parameter used to refine text measurements to better
   ;; match an expected scaling of the image:
>  current-expected-text-scale ; -> (list num num)
                               ; (list num num) -> void

   ;; -- MrEd only --
   ;; Create an arbitrary self-rendering pict.  The arguments to the
   ;; rendering procedure will be a device context and top-left
   ;; location for drawing.
   ;;
   ;; When the rendering procedure is called, the current pen and
   ;; brush will be solid and in the pict's color (and linewidth), and
   ;; the scale and offset of the dc will be set. The text mode will
   ;; be transparent, but the font and colors are not guaranteed to be
   ;; anything in particular.
>  dc      ; (dc<%> dx dy -> void) w h a d -> pict

   ;; -- LaTeX only --
   ;; Delimitters to go around height h (result is taller than h;
   ;;  try h/2)
>  left-brace     ; h -> pict
>  right-brace    ; h -> pict
>  left-delimit   ; str h -> pict
>  right-delimit  ; str h -> pict
>  middle-delimit ; str h -> pict
   ;; Delimitter to go around width w (result is w wide)
>  top-brace      ; w -> pict
>  bottom-brace   ; w -> pict

   ;; Truncates picture, removing descent part
>  clip-descent   ; pict -> pict

   ;; Lifts picture relative to its baseline, extending
   ;;  the height if necessary
>  lift           ; pict n -> pict

   ;; Drops picture below its ascent line, extending
   ;;  the height if necessary
>  drop           ; pict n -> pict

   ;; Extends picture size; ascent and descent are
   ;;  extended, too
>  inset          ; pict i -> pict
                  ; pict hi vi -> pict
                  ; pict l t r b -> pict

>  hline        ; w h -> pict
>  dash-hline   ; w h seg-length -> pict ; default seg-length is 5
>  vline        ; w h -> pict
>  dash-vline   ; w h seg-length -> pict ; default seg-length is 5
   ;; To draw other kinds of lines, use `picture' or `cons-picture'

>  frame        ; pict -> pict
>  dash-frame   ; pict seg-length -> pict ; default seg-length is 5
>  oval         ; pict -> pict
>  oval/radius  ; pict r -> pict ; r is radius of corners

   ;; Creates a fairly round circle using four splines:
>  big-circle   ; diameter -> pict

   ;; Set the line thickness for a picture. For MrEd output,
   ;; selects between a pen width of 0 or 1.
>  thick       ; pict -> pict
>  thin        ; pict -> pict

   ;; -- MrEd only --
   ;; Set a specific pen width for drawing.
>  linewidth   ; w pict -> pict

   ;; Make a container picture that doesn't draw the child picture,
   ;; but uses the child's size
>  ghost        ; pict -> pict

   ;; Make a UML-like record picture, where the
   ;; first argument is the title and the rest are fields.
>  record       ; pict pict ... -> pict

   ;; Make a new picture as a column (vX-append) or row (hX-append)
   ;; of other pictures. Different procedures align pictures in the
   ;; orthogonal direction in different ways; e.g, vl-append left-aligns
   ;; all of the pitures. A specified amount of space is inserted
   ;; between each pair of pictures in making the column or row.
>  vl-append    ; [d] pict ... -> pict ; d units between each picture
>  vc-append                           ;  default=0
>  vr-append
>  ht-append
>  hc-append
>  hb-append
>  htl-append       ; align bottoms of ascents
>  hbl-append       ; align tops of descents (normal text alignment)

   ;; Make a new picture by superimposing a set of pictures. The
   ;; alignment indicators are essentially as above: horizontal
   ;; alignment then vertical alignment.
>  lt-superimpose ; pict ... -> pict
>  lb-superimpose
>  lc-superimpose
>  ltl-superimpose
>  lbl-superimpose
>  rt-superimpose
>  rb-superimpose
>  rc-superimpose
>  rtl-superimpose
>  rbl-superimpose
>  ct-superimpose
>  cb-superimpose
>  cc-superimpose
>  ctl-superimpose
>  cbl-superimpose

   ;; Make a table given a list of picts. The list is a
   ;; concatentation of rows (which means that a Scheme `list' call
   ;; can be formatted to reflect the shape of the output table).
   ;;
   ;; The col-aligns, row-aligns, col-seps, and row-seps arguments are
   ;; `lists' specifying the row and columns alignments separation
   ;; between rows and columns.  For C columns and R rows, the first
   ;; two should have C and R superimpose procedures, and the last two
   ;; should have C - 1 and R - 1 numbers, respectively. The lists can
   ;; be improper (e.g. just a number), in which case the non-pair cdr
   ;; is used as the value for all remaining list items that were
   ;; expected. The alignment procedures are used to superimpose all
   ;; of the cells in a column or row; this superimposition determines
   ;; the total width oir height of the column or row, and also
   ;; determines the horizontal or vertical placement of each cell in
   ;; the column or row.
>  table ; ncols pict-list col-aligns row-aligns col-seps row-seps -> pict

   ;; Apply a color to a picture. If the given picture has a colorized
   ;; sub-picture, the color of the sub-picture is not affected.
   ;; Be sure to use the LaTeX package `colordvi'.
>  colorize ; pict color-string -> pict

   ;; -- MrEd only --
   ;; same as above, except uses the color% object instead of a string
   ;; to indicate the color of the pict.
>  colorize ; pict color% -> pict

   ;; Describe a picture with low-level commands; see below.
>  picture      ; w h command-list -> pict

   ;; Create a new picture by `cons'ing drawing commands onto
   ;; an existing picture. `cons-picture*' maintains the pict's
   ;; descent and ascent.
>  cons-picture ; pict command-list -> pict
>  cons-picture* ; pict command-list -> pict

   ;; Creates a pict with the same bounding box, ascent, and descent
   ;; as the initial argument, but with the second pict placed on top.
   ;; The dx and dy argument specify how far left and down the second
   ;; pict's corner is frm the firts pict's corner.
   ;; Alternately, the sub-pict and procedure arguments find a point
   ;; in the intial pict for the second pict's corner. The procedure
   ;; should be like find-lt (i.e., the result dy is from the pict's
   ;; bottom instead of its top).
>  place-over ; pict dx dy pict -> pict
>  place-over ; pict sub-pict (pict pict -> dx dy) pict -> pict

   ;; Like place-over, but the second pict is drawn first, then the
   ;; initial pict.
>  place-under ; pict dx dy pict -> pict
>  place-under ; pict sub-pict (pict pict -> dx dy) pict -> pict

   ;; -- LaTeX only --
   ;; Generate the LaTeX code for a pict.
>  pict->string ; pict -> string

   ;; -- MrEd only --
   ;; Opens a frame that displays the pict.
   ;; The frame adds one method: 
   ;;   set-pict : pict -> void
   ;; that changes the visible pict.
   ;; the optional w and h arguments must
   ;; be either numbers of #f. If numbers,
   ;; the window is at least that size
   ;; and the pict is drawn in the middle of
   ;; the window.
>  show-pict ; pict [w h] -> void

   ;; -- MrEd only --
   ;; Draw a pict to a dc<%>
>  draw-pict ; pict dc x y -> void

   ;; -- MrEd only --
   ;; Generate a pict-drawer procedure for multiple renderings of a
   ;; pict (much faster than repeated calls to draw-pict)
>  make-pict-drawer ; pict -> (dc x y -> void)

------------------------------------------------------------
Picture Paths, Command, Putables, and Drawables
------------------------------------------------------------

pict-path:

   pict
   non-empty-pict-path-list

commands:

   ;; These commands use LaTeX-style coordinates: bottom-left
   ;; is (0, 0).

   `(place ,x ,y ,pict)
   `(put ,x ,y ,putable)
   
   ;; The varieties of `connect' commands are for LaTeX, where
   ;; lines are constrained to a small set of allowed angles.
   ;; For MrEd, all of the commands below act the same, and produce
   ;; liens with precisely the requested angle.

   `(connect ,x1 ,y1 ,x2 ,y2 ,bool)         ; line or vector; bool => vector;
                                            ;   from (x1,y1) to (~x2,~y2)
                                            ;   as close as possible
                                            ;   (synonym for connect~xy with 
                                            ;   an infinite tolerance when
                                            ;   draw-bezier-lines is #f, or
                                            ;   for curve when draw-bezier-lines
                                            ;   is #t)
   `(dconnect ,x ,y ,dx ,dy ,bool)          ; line or vector; bool => vector;
                                            ;   from (x,y) to (~(x+dx),~(y+dy))
                                            ;   as close as possible (uses
                                            ;   connect)
   `(connect~y ,tol ,x1 ,y2 ,x2 ,y2 ,bool)  ; sequence of lines from
                                            ;  (~x1,~y1) to (~x2,~y2) where
                                            ;  either: 
                                            ;    1) ~x2=x2 and |~y2-y2|<tol
                                            ;    2) ~y2=y2 and |~x2-x2|<tol and 
                                            ;       the final line is vertical
   `(connect~x ,tol ,x1 ,y2 ,x2 ,y2 ,bool)  ; like connect~y, but either:
                                            ;    1) ~x2=x2 and |~y2-y2|<tol
                                            ;       the final line is horizontal
                                            ;    2) ~y2=y2 and |~x2-x2|<tol
   `(connect~xy ,tol ,x1 ,y2 ,x2 ,y2 ,bool) ; like connect~y, but either:
                                            ;    1) ~x2=x2 and |~y2-y2|<tol
                                            ;       the final line is horizontal
                                            ;    2) ~y2=y2 and |~x2-x2|<tol
                                            ;       the final line is vertical
                                            ;    3) |(x2,y2)-(~x2,~y2)|<tol
   `(curve ,x1 ,y1 ,x2 ,y2 ,xc ,yc ,d)      ; bezier curve; d is optional density
                                            ;  for LaTeX; the default d is 1.0

  [Notes: curve can generate more precise lines than connect~, but it usually 
          requires more LaTeX memory.]

putables:

   draw
   `(line ,dh ,dv ,hlen)       ; LaTeX-style line - slope and size is limited
   `(vector ,dh ,dv ,hlen)     ; LaTeX-style vector - slope and size is limited
   `(circle ,d)                ; LaTeX-style circle - size is limited
   `(circle* ,d)
   `(frame ,draw)
   `(colorbox ,color-str ,draw)
   `(oval ,str ,w ,h)  ; str is portion a la LaTeX: e.g., "" or "[bl]";
                       ;  the oval is centered at the put position, instead of
                       ;  bl-aligned
   ; plus some more undocumented ones...

draws:

   string ; latex string
   `(picture ,w ,h ,@command-list)
   `(color ,color-string ,draw)
   `(thickness ,thickness ,draw) ; thickness is thicklines or thinlines

------------------------------------------------------------
Additional MrEd Utilities
------------------------------------------------------------

The _utils.ss_ library provides additional drawing procedures for MrEd
(not LaTeX) output.

  ;; Like `cons-picture', but the newly consed commands get a
  ;; color
> cons-colorized-picture  ; pict color-string command-list -> pict

  ;; Like `frame' and `dash-frame', but the frame gets a color and
  ;; optional line width
> color-frame             ; pict color-string -> pict
                          ; pict color-string line-w -> pict
> color-dash-frame        ; pict seg-length color-string -> pict
                          ; pict seg-length color-string line-w -> pict

  ;; Rounded frames
> round-frame             ; pict -> pict
> color-round-frame       ; pict color-string -> pict
                          ; pict color-string line-w -> pict

  ;; Unfilled and filled circles; works for all sizes.
> circle                  ; diameter -> pict
> disk                    ; diameter -> pict

  ;; Unfilled and filled ellipses; works for all sizes.
> ellipse                 ; width height -> pict
> filled-ellipse          ; width height -> pict

  ;; Unfilled and filled rectangle; works for all sizes.
> rectangle               ; width height -> pict
> filled-rectangle        ; width height -> pict

  ;; Creates an arrow or arrowhead in the specific direction
  ;;  within a size x size pict. (Points on the arrow may
  ;;  extend slightly beyond the box.)
> arrow                   ; size radians -> pict
> arrowhead               ; size radians -> pict

  ;; Creates a line with arrowhead(s) as a 0-sized picture (suitable
  ;; for use with `put'). The 0-sized picture contains the starting
  ;; point.
> arrow-line              ; dx dy size -> pict
> arrows-line             ; dx dy size -> pict
           
  ;; Conses a line or line-with-arrows onto a pict, using
  ;; one of the sub-pict-finding functions (e.g., `find-tc')
  ;; to extract the source and destination of the line.
> add-line                ; pict 
                          ; src-pict (pict -> x y)
                          ; dest-pict (pict -> x y)
                          ; [line-w [color-string [lines-under?]]]
                          ; -> pict
> add-arrow-line          ; arrow-size pict 
                          ; src-pict (pict -> x y)
                          ; dest-pict (pict -> x y)
                          ; [line-w [color-string [lines-under?]]]
                          ; -> pict
> add-arrows-line         ; arrow-size pict 
                          ; src-pict (pict -> x y)
                          ; dest-pict (pict -> x y)
                          ; [line-w [color-string [lines-under?]]] 
                          ; -> pict

  ;; Loads a bitmap into a pict; if the bitmap is not ok,
  ;;  the result is a box containing the words "bitmap failed"
> bitmap                  ; filename -> pict
> bitmap                  ; bitmap%-object -> pict

  ;; Scales a pict (by adjusting the destination dc<%>'s
  ;; scale while drawing the pict.
> scale                   ; pict factor -> pict
> scale                   ; pict x-factor y-factor -> pict

  ;; Syntax that is like `scale', but also sets
  ;; `current-expected-text-scale' while evaluating
  ;; `pict-expr':
> (scale/improve-new-text pict-expr s-expr)
> (scale/improve-new-text pict-expr sx-expr sy-expr)

  ;; Scales a color, making it brighter or darker. If the
  ;; factor is < 1, the color is darkened by multiplying
  ;; the RGB components by the factor. If the factor is > 1,
  ;; the color is lightened by dividing the gap between
  ;; the RGB components and 255 by the factor.
> scale-color             ; factor string-or-color% -> color%

  ;; Gets an immutable pen% from the-pen-list
> find-pen                ; string-or-color% [size [style]] -> pen%
                          ;   size defaults to 1
                          ;   style defaults to 'solid

  ;; Gets an immutable brush from the-brush-list
> find-brush              ; string-or-color% [style] -> brush%
                          ;   style defaults to 'solid


  ;; Calls a drawing function multiple times, gradually
  ;; changing the pen/brush color for each call. The
  ;; step count and step delta should be exact numbers;
  ;; the procedure is called with each number from 0 to 
  ;; the step count, using the step delta. For the first
  ;; call, the current pen and/or brush color matches the
  ;; starting color; for the last call, it matches the
  ;; ending color; and for intermediate calls, the color
  ;; is an intermediate color.
> color-series            ; dc<%> num-steps step-delta
                          ;  start-color-or-string%
                          ;  end-color-or-string%
                          ;  (num -> any)
                          ;  set-pen? set-brush?

  ;; Fluffy cloud; default color is "gray".
> cloud                   ; w h -> pict
                          ; w h color-string -> pict

  ;; Creates a MacOS-like file icon, optionally shaded
> file-icon               ; w h gray [fancy?] -> pict
                          ;   gray = #f -> white
                          ;   gray = #t -> default color
                          ;   gray = color/string -> uses color

  ;; Creates a jack-o-lantern; use the same pumkin-color and
  ;; face color to get a plain pumpkin. The size is the width.
> jack-o-lantern          ; size [pumpkin-color face-color] -> pict

  ;; Creates an angel wing, left or right, or any size.
  ;; The color and pen width for drawing the wing outline is the
  ;; current one.
> angel-wing              ; w h left? -> pict


  ;; Creates a fish, swimming either 'left or 'right.
  ;; If eye-color is #f, no eye is drawn. Defaults are
  ;; 'left, "blue", and "black".
> standard-fish           ; w h [direction color eye-color open-mouth?] -> pict


------------------------------------------------------------
_slideshow-run.ss_ and _slideshow.ss_
------------------------------------------------------------

The "slideshow-run.ss" and "slideshow.ss" modules simply re-export
`(lib "run.ss" "slideshow")' and `(lib "slideshow.ss" "slideshow")'
for backward compatibility.

See the "slideshow" collection for more details.

------------------------------------------------------------
_balloon.ss_
------------------------------------------------------------

The "balloon.ss" module produce functions for creating and placing
cartoon-speech ballons.

> (wrap-balloon pict spike-sym dx dy [color])

Superimposes `pict' on top of a balloon that wraps it.

The `spike-sym' indicates the corner from which a spike protrudes from
the balloon (i.e., the spike that points to whatever the balloon is
about). It's one of 'n, 's, 'e, 'w, 'ne, 'se, 'sw, or 'nw.

The `dx' and `dy' arguments specify how far the spike should protrude.
For a 'w spike, `dx' should be negative, etc.

The `color' argument is the background color for the balloon. It
defaults to `balloon-color'.

The result is a balloon, not a pict. The `balloon-pict' function
extracts a pict whose bounding box does not include the spike, but
includes the rest of the image. (The `balloon-point-x' and
`ballon-point-y' functions specify the location of the spike point.)

> (place-balloon balloon pict to-pict find-to-pos)
> (place-balloon balloon pict x y)

Superimposes the pict in `balloon' onto `pict' to produce a new
pict. The ballon is positioned so that its spike points to the
location specified by either `x' and `y' (numbers) or `to-pict' and
`find-to-pos'. In tghe latter case, `to-pict' is a sub-pict in `pict'
and `find-to-pos' is a function like `find-lt.

The resulting pict has the same bounding box, descent, and ascent as
`pict', even if the balloon extends beyond the bounding box.

> (balloon w h corner-radius spike-pos dx dy color)

Creates a balloon, much like `wrap-balloon' except that the balloon's
width is `w' and its height is `h'. The `corner-radius' argument
specifies the radius for the balloon's rounded corners; if the radius
is positive, the value is used as the radius of the rounded corner,
but if radius is negative, the absolute value is used as the the
proportion of the smallest dimension of the balloon.

> (make-balloon pict num num) -> balloon
> (balloon-pict balloon)      -> pict
> (balloon-point-x balloon)   -> num
> (balloon-point-y balloon)   -> num
> (balloon? v)                -> bool

A balloon value encapsulates a pict and the position of the basllon's
spike relative to the balloon's top-left corner.

> balloon-color

The default background color for a ballooon.

------------------------------------------------------------
_face.ss_
------------------------------------------------------------

The "face.ss" module provides functions for a kind of
Mr.-Potatohead-style face library. The _face-demo.ss_ module
implements an interactive browser for face configurations.

> default-face-color - orange

> (face mood-symbol [color]) - returns a pict a pre-comfigured face
  with the given base color. The built-in configurations, selected by
  mood-symbol, are as follows:

    'unhappy - (face* 'none 'plain #t default-face-color 6)
    'sortof-unhappy - (face* 'worried 'grimace #t default-face-color 6)
    'sortof-happy - (face* 'worried 'medium #f default-face-color 6)
    'happy - (face* 'none 'plain #f default-face-color 6)
    'happier - (face* 'none 'large #f default-face-color 3)
    'embarassed - (face* 'worried 'medium #f default-face-color 3)
    'badly-embarassed - (face* 'worried 'medium #t default-face-color 3)
    'unhappier - (face* 'normal 'large #t default-face-color 3)
    'happiest - (face* 'normal 'huge #f default-face-color 0 -3)
    'unhappiest - (face* 'normal 'huge #t default-face-color 0 -3)
    'mad - (face* 'angry 'grimace #t default-face-color 0)
    'mean - (face* 'angry 'narrow #f default-face-color 0)

> (face* eyebrow-kind mouth-kind frown? [color eye-inset eyebrow-dy pupil-dx pupil-dy])
  - returns a pict for a configured face:

      - eyebrow-kind is one of 'none, 'normal, 'worried, or 'angry
      - mouth-kind is one of 'plain, 'narrow, 'medium, 'large, 'huge, 
                             'grimace, or 'tongue
      - frown? determines whether the mouth is up or down
      - color is either a color string or a color% object
      - eye-inset adjusts the eye size; recommend values: between 0 and 10
      - eyebrow-dy adjusts the eyebrows; recommend values: between -5 and 5
      - pupil-dx adjusts the pupil; recommend values: between -10 and 10
      - pupil-dy adjusts the pupil; recommend values: between -15 and 15

------------------------------------------------------------
_code.ss_
------------------------------------------------------------

The "code.ss" module provides a unit for typesetting Scheme code a la
SlaTeX.

The _code@_ signed unit imports _code-params^_ and exports _code^_.
The _code-params^_ signature contains two elements:

   current-font-size - a thunk to obtain the font size to use for
                       text
   line-sep - an integer for the amount of space (in drawing units) to
              insert between lines of text

The _code^_ unit supplies the following

> (typeset-code stx) - produces a pict for code in the given syntax
  object. The source-location information of the syntax object
  determines the line breaks, line indenting, and space within a row.
  Empty rows are igmored.

  Normally, `typeset-code' is used through a macro (often called
  `code') that is generated by `define-code'. See below for more
  information.

  Embedded picts within `stx' are used directly. Row elements are
  combined using `htl-append', so use `code-align' (see below) as
  necessary to add an ascent to ascentless picts.

  Uses of certain keywords in `stx' typeset specially:

>    code:blank - produces a space
>    (code:comment s ...) - produces a comment block, with each `s'
                            on its own line; each `s' must be a string
                            or a pict
>    (code:line datum ...) - typesets the `datum' sequence, mostly useful
                             for the top-level sequence, since 
                             `typeset-code' takes only one argument
>    (code:contract datum ...) - like code:line, but every `datum' is
                                 colored as a comment, and a semi-colon
                                 is prefixed to every line
>    (code:template datum ...) - like code:line, but a semi-colon
                                 is prefixed to every line
>     $                        - typesets as a vertical bar (for no
                                 particularly good reason)

> current-code-tt - parameter for a one-argument function to turn a
  string into a pict, used to typeset text. The default is
    (lambda (s) (text s `(bold . modern) (current-font-size)))

> current-comment-color - parameter for a string or color% for comments
> current-keyword-color - parameter for a string or color% for keywords
> current-id-color - parameter for a string or color% for identifiers
> current-literal-color - parameter for a string or color% for literals
> current-base-color - parameter for a string or color% for everything else

For backward compatibility:
> comment-color - default string/color% for comments
> keyword-color - default string/color% for keywords
> id-color - default string/color% for ids
> literal-color - default string/color% for literals

> (code-align pict) - adjusts the ascent of `pict' so that its bottom
  aligns with the baseline for text; use this function when `pict'
  has no ascent.

> current-keyword-list - a list of identifiers to color as keywords; the
  default includes the MzScheme syntactic form names

> current-const-list - a list of identifiers to color ad literals; the
  default is 'empty

> code-colorize-enabled - a parameter to enable or disable all code
  coloring

In addition to the `code@' unit, the "code.ss" module exports a
`define-code' macro for defining other macros:

> (define-code code-id typeset-code-id) - defines `code-id' as a macro
  that uses `typeset-code-id', which is a function with the same input
  as `typeset-code'.

  The `code-id' syntactic form takes a sequence of `datum's:

    (code datum ...)

  It produces a pict that typesets the sequence. Source-location
  information for the `datum' determine the layout of code in the
  resulting pict.

  If a `datum' contains `(unsyntax expr)' (perhaps as #,expr), then
  the `expr' is evaluated and the result datum is spliced in place of
  the `unsyntax' form in `datum'. If the result is not a syntax object,
  it is given the source location of the `(unsyntax expr)'.

  The `code' syntactic form expands to a use of `typeset-code'. The
  `datum's are not merely syntax-quoted, because then the compiled
  form of the call would loose source information. Instead, `code'
  expands to an expression that preserves expansion-time
  source-location information.
