# To unbundle, sh this file echo README 1>&2 sed 's/.//' >README <<'//GO.SYSIN DD README' - - anim -- Algorithm Animation - - Jon Bentley (jlb@research.bell-labs.com) - Brian Kernighan (bwk@research.bell-labs.com) - - -EXECUTIVE SUMMARY - -Create a description of an animation in the language -described in script.def, using whatever tools you like -(e.g., awk programs, C programs). -Show the movie on an X11 system with movie. -Print selected frames through pic and troff with stills. - - Suntools support withdrawn 12/87; - Teletype 5620 and 630 support withdrawn 8/90. - This version assumes X11R5. - Plan 9 emulation library updated 6/93 to include unicode. - -An animation is normally produced by adding print statements -to a program. Each statement requests the drawing or erasing -of some piece of the animation. Objects may be lines, boxes, -circles, or text, positioned arbitrarily. Anim scales -coordinates so that the display always fits the screen. The -display may contain multiple independent views that depict -different aspects of interest; these views are completely -independent of each other and are scaled separately. - -When anim is used interactively, the viewer can control the -speed of display, proceed forward or backward through time, -and change the screen layout to emphasize certain views. It -is also possible to mark interesting points in time and step -from event to event interactively. - -When anim is used to produce stills, a simple language -permits the selection and positioning of arbitrary -collections of interesting frames and views. - - -LANGUAGE - -The language is defined but not explained much in script.def. -The awk program isort.gen can be run to give an example of -data in the script language, then processed subsequently -to make a movie or a set of stills. For more information, -see our papers: - - "A System for Algorithm Animation -- Tutorial and User Manual" - Computing Science Tech Report 132, January, 1987. - Available in PostScript: - echo send research/cstr/132 | mail netlib@research.bell-labs.com - - "A System for Algorithm Animation." - Computing Systems, Vol 4, #1, pp 5-30, Winter 1991. - - -PRIMARY PROGRAMS - -movie - shell script - "movie file.s" develops file.s if necessary to make file.i, - then displays it on an X-window terminal using anim. - -stills - shell script, invoking giant awk program stills.awk. - A troff preprocessor that creates pic pictures of - selected frames. Input language defined in stills.def - -develop - shell script, called by movie and stills. - Input language defined in script.def, output language - ("intermediate") defined in int.def. - Uses fdevelop (C program) to do the work. - -anim - Under X11, creates a new window for the movie. - - Try - isort.gen >dev.s (an example in this directory) - movie dev.s - (equivalent to fdevelop dev.s >dev.i; anim dev.i) - - The files test.s and test.i can be used for experimenting - with the host and terminal programs before worrying about - develop. qsort.[is] is a bigger and more interesting example. - - -SUPPORT PROGRAMS - -show.clicks make a new view to count clicks -view.clicks print summary of views and clicks -newer.c tests file ages; install if needed (used in develop) - - -INSTALLATION - - You may have to change some directory names and other parameters in - movie - stills - develop - Makefile - - BIN = directory where movie and stills are (e.g., /usr/bin) - LIB = directory where develop, fdevelop, stills.awk, anim - are (e.g., /usr/lib). - - Then - mkdir libXg - cd libXg - sh ../libXg.bundle - make - cd .. - make all - - anim uses a graphics library called libXg that is - included here. The makefile isn't very clever about - making this, nor about noticing if it has changed. - Pay attention! - - -PROBLEMS - - The locations of compilers, libraries, and similar things - vary wildly from system to system. Although we have tried - to parameterize these in the makefiles, you will surely - have to fiddle with file names and perhaps defined constants - in the makefiles. Even then, you may be stymied by incompatible - header files that you didn't even know you needed. Sorry. - - This package assumes X11 Release 5 and uses the Xt toolkit. - - This code also assumes an ANSI C compiler. If you don't - have one, you will have to edit, or, better, get one. - - -UPDATES - - New menu items Zoom in and Zoom out let you do just that. - If a null rectangle is selected on zooming in, the previous - zoomed-in rectangle is used. - - If the aspect ratio of the screen or a zoom rectangle is - between .75 and 1.25, the picture aspect ratio is forced to 1. - The -a option controls this; e.g., -a.9 sets it to 0.9. - - The run/1-step menu has been augmented with a third state, - "cycle", which plays the movie repeatedly until interrupted. - - A rudimentary color capability has been added, but the job - isn't complete. It does filled circles and boxes and lines - of various colors for now. - - It is possible to provide .i-format input in your own - coordinate system instead of the default [0,9999],[0,9999]. - The command - d s v x y x y - causes input in view v to be scaled under the assumption - that inputs for that view are in the range [x,y],[x,y]. - - We are, as always, in the middle of adding new features, - so things may well be shakier than normal. Complaints welcome. - - -HEARTFELT ACKNOWLEDGEMENT - - The code for the animation system owes an enormous debt to - Howard Trickey, who first figured out how to deal with - the egregious Suntools and X window systems, and then wrote - and continued to upgrade the X11 graphics library included here. - None of this would work without Howard's code, which is included - with his permission. - - -COPYRIGHT INFORMATION - -Copyright (C) AT&T 1992 -All Rights Reserved - -Permission to use, copy, modify, and distribute this software and -its documentation for any purpose and without fee is hereby -granted, provided that the above copyright notice appear in all -copies and that both that the copyright notice and this -permission notice and warranty disclaimer appear in supporting -documentation, and that the name of AT&T or any of its entities -not be used in advertising or publicity pertaining to -distribution of the software without specific, written prior -permission. - -AT&T DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, -INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. -IN NO EVENT SHALL AT&T OR ANY OF ITS ENTITIES BE LIABLE FOR ANY -SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER -IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, -ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF -THIS SOFTWARE. //GO.SYSIN DD README echo movie.1 1>&2 sed 's/.//' >movie.1 <<'//GO.SYSIN DD movie.1' -.TH MOVIE 1 -.CT 1 files prog_other -.SH NAME -movie, stills \- algorithm animation -.SH SYNOPSIS -.B movie -[ -.I file -] -.br -.B stills -[ -.I files ... -] -.SH DESCRIPTION -.PP -.I Movie -converts a script in a movie language -into an internal representation, then displays it in a window on an X11 system. -If the filename is of the form -\f2file\f(CW.s\f1, -.I movie -creates the intermediate form in -\f2file\f(CW.i\f1, -which will be used in subsequent calls if it is more recent than -\f2file\f(CW.s\f1. -.PP -In the terminal, button 1 stops and starts the movie; -button 2 adjusts view sizes and selects clicks; -button 3 sets various parameters. -.PP -.SS Movie language -.br -.B text -.I options x y string. -Text is centered and medium size by default; options: one of -.B "center -.B ljust -.B rjust -.B above -.BR below , -and one of -.BR "small -.B medium -.B big -.BR bigbig . -A leading quote is stripped from -.IR string , -as is a trailing quote if a leading one is present. -.br -.BI line -.I "options x1 y1 x2 y2. -Lines are solid by default; options: one of -.B "fat -.B fatfat -.B dotted -.B dashed -and one of -.B "-> -.B <- -.BR <-> . -.br -.BI box -.I "options xmin ymin xmax ymax. -A box may -.BR fill ed. -.br -.BI circle -.I "options x1 y1 radius. -Radius is measured in the -.I x -dimension. -A circle may be -.BR fill ed. -.br -Any text or geometrical object may be labeled with a name and colon. -A subsequent appearance of a label in the same view erases the previous -object with that label. -.BI erase -.I label -erases the object explicitly. -.B clear -erases all objects currently in the current view. -.br -.BI click -.I "optional name -leaves a mark in the intermediate with this name; -clicks are used to control stepping in a movie or to define frames -for a set of stills. -.br -A movie may consist of multiple independent views, -each presented as a rectangular sub-window. -.BI view -.I name -associates -subsequent objects with this view, -until changed again. -Labels and coordinates are local to views. -If no view statements appear, there is a single implicit view -.BR def.view . -.br -Comments follow #; blank lines are ignored. -.PP -.I Stills -converts selected frames of a movie into -commands for -.IR pic (1). -Commands for -.I stills -begin with -.B .begin stills -and end with -.B .end -.BR stills . -.SH FILES -All files are in -.BR /usr/lib/movie . -.TF stills.awk -.TP -.F develop -Shell script to control conversion from script language to internal form. -.TP -.F fdevelop -C program that does the work. -.TP -.F stills.awk -Awk program to process stills language into -.IR pic (1). -.TP -.F anim -Animation program itself. -This supports a -.B \-m -option for changing the default amount of memory -allocated to the movie. -.TP -.F newer -Test whether one file is newer than another. -.SH "SEE ALSO" -J. L. Bentley and B. W. Kernighan, -.IR "A System for Algorithm Animation" , -AT&T Bell Laboratories CSTR 132, January, 1987. -For a copy in PostScript, -.br -.B " echo send research/cstr/132 | mail netlib@research.bell-labs.com -.SH BUGS -There are several compiled-in limits that ought to be dynamic. -.br -The "slower" menu selection doesn't work under X11. //GO.SYSIN DD movie.1 echo script.def 1>&2 sed 's/.//' >script.def <<'//GO.SYSIN DD script.def' - Definition of Script Language - -OBJECTS -Text -% text - Quote rules for string: - If no leading quote, string starts at first character not - space or tab and goes for rest of line - If leading quote, later leading white space is kept and - trailing quote at end of line is stripped (if present); - intermediate quotes are kept - Some strings may be recognized by some processors: - bullet, dot, circle, times - Options -- [default] in brackets - [center] ljust rjust above below - small [medium] big bigbig - Option format (for text and geometry): - list of option names (possibly null) terminated by first number -Geometry -% line - Options - [solid] fat fatfat dotted dashed - [-] -> <- <-> -% box - Options - [nofill] fill -% circle - Radius measured in x dimension - Options - [nofill] fill - -HOUSEKEEPING -Erasing -% (label:) - At most one label per line -% erase