
     >>>>>> THIS IS UNSUPPORTED SOFTWARE <<<<<<<

_texpict_ is a MzScheme utility for creating _LaTeX_ picture
expressions.

LaTeX pictures are created as `pict' structures. Procedures in the
texpict library create new simple picts (e.g., `tex') or create new
picts that include other 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 `tex' line, d is descent below the baseline and
a + d = h. For multiple tex lines (created with vX-append), a is 
ascent of top line above baseline and d is descent of bottom line,
so a + d < h. Other boxes have d = 0 and a = h.

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.

All positions and sizes must be specified as exact integers.

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
------------------------------------------------------------

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

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

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

   ;; 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


   ;; 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
   
   ;; 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

   ;; 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

   ;; 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

>  clip-descent   ; pict -> pict
>  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 (does not apply to
   ;; slanted lines)
>  thick       ; pict -> pict
>  thin        ; pict -> pict

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

>  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
>  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

   ;; Desribe 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 ; pict command-list -> pict

   ;; Create a self-rendering picture (for dc output only)
>  prog-picture ; (dc dx dy -> void) w a d -> pict


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

   ;; Parameter to use the old implementation of `connect'.
>  use-old-connect

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

pict-path:

   pict
   non-empty-pict-path-list

commands:

   `(place ,x ,y ,pict)
   `(put ,x ,y ,putable)
   `(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;
                                            ;  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
