man(1) Manual page archive

     delim $$

     NAME
          ideal - troff preprocessor for drawing pictures

     SYNOPSIS
          ideal [ -p ] [ -4 ] [ -n ] [ files ]

     DESCRIPTION
          Ideal is yet another troff(1) preprocessor for drawing fig-
          ures on a typesetter.  A line beginning `.IS' marks the
          start of an ideal program.  An ideal program ends with `.IE'
          or `.IF'; `.IE' leaves you below the bottom of the picture,
          while `.IF' (flyback) leaves you at the same place you were
          when you said `.IS'.

          When invoked with the -p option, ideal produces plot(1)
          instructions.  The erases come at every `.IS', and they come
          fast and furious, so you might prefer using the -4 option,
          which produces instructions for a Tektronix 4014, and waits
          at each `.IE' for an input character before erasing and
          starting the next picture.  The -n option produces raw ideal
          output, which passes unharmed through nroff.

          The building block for ideal programs is a ``box''; boxes
          look like C functions, in that they are named, and delimited
          by braces.  They may include the following kinds of state-
          ments, each terminated by a semicolon:

          var  declares one or more complex variables local to the
               box.  Variable names are made up of letters and digits,
               and start with a letter; do not use any of the follow-
               ing keywords as variable names: at, bdlist, boundary,
               box, conn, construct, draw, exterior, interior, left,
               opaque, put, right, spline, text, to, using, var

          equation
               declares relative positions of significant points of
               the box

          conn asks for a straight-line path through named points

          pen  asks for a box to be replicated along a line between
               two points

          left left-justifies text with respect to a point

          text centers text with respect to a point

          right
               right-justifies text with respect to a point

          spline
               draws a spline guided by the named points

          put  asks for an instance of a box to be drawn

          opaque

     IDEAL(1)                                                 IDEAL(1)

               asks for a box to erase lines already in the picture
               that are covered by its bounding polygon

          boundary
               specifies the bounding polygon for an opaque box

          construct
               builds a partial picture on a separate ``sheet of
               paper''

          draw adds the contents of the named constructed box to the
               current picture

          Ideal expects all components of a picture to be specified as
          boxes; instructions to draw the entire picture should com-
          prise a box called ``main.''  Boxes are remembered across
          .IS-.IE boundaries; if you won't need a box again, you can
          reclaim the space it requires by including the command
          `...forget boxname' on a line between any .IS-.IE pair after
          the last use of boxname.  Box main is an exception to this
          rule: it is always forgotten when the .IE is processed.

          During its first pass, ideal solves all the equations to
          determine the locations of all points it needs to know.
          These equations must be linear equations in complex vari-
          ables, although they may include non-linear operators: ideal
          plugs in for as many variables, and does as much function
          evaluation, as it can before solving the linear equation.
          It waits until it has absolutely no hope of reducing an
          equation to a linear equation before complaining.  Ideal
          knows about the following functions:

          α[z,w]
               $==~z+ alpha (w-z)$, $alpha$ of the way from $z$ to $w$

               real part of complex number

          z)
               imaginary part of complex number

          z)
               complex conjugate of complex number

          z)
               absolute value (modulus) of complex number

          x)
               a unit vector in the direction of the real part of its
               argument, which is an angle in degrees (radians if the
               line `...radians' appeared more recently in the file
               than the line `...degrees')

     IDEAL(1)                                                 IDEAL(1)

          x) $==~cis (360x)$ if $x$ is measured in degrees

          z)
               angle of complex number, arctan $(im(z)/re(z))$

          During the second pass, ideal draws the picture.

          To draw a circle, include the line `...libfile circle'
          between the .IS and .IE lines, and put the box named circle,
          giving enough information that the circle can be determined;
          for instance, give the center and the radius, or give three
          points through which the circle passes, or give the center
          and a point on the circle.  The circle has center center,
          radius radius, and passes through z1, z2, and z3.

          To draw an arc, include the line `...libfile arc'  between
          the .IS and .IE lines, and put the box named arc, again giv-
          ing enough information to determine the arc; for instance,
          give the center, radius, and starting and ending angles, or
          give three points on the arc--where to start, where to end,
          and somewhere in between.  The arc has center center, radius
          radius, starts at point start, passes through point midway
          at angle midang, and ends at point end at angle endang. If
          no midway is specified, the arc is drawn counterclockwise
          from start to end.

          The picture will be scaled to a default width of four inches
          and centered in a column of six inches.  The default width
          can be changed by a `...width' command, which includes a
          number in inches.  The default column width can be changed
          by a `...colwid' command.  To defeat ideal's notion of the
          size of the picture, you can include lines of the form
          `...minx', `...miny', `...maxx', or `...maxy'; these give
          the various coordinates of the bounding box of the picture
          in the coordinate system used by the picture.

          Ideal supports both C-style comments (between /* and */
          brackets, and they nest), and shell-style comments (between
          # and newline).

     SEE ALSO
          C. J. Van Wyk, IDEAL User's Manual , C. J. Van Wyk.
          pic(1), ped(9.1), doctype(1)

     BUGS
          Ideal is relatively unforgiving about syntax errors.  Bound-
          ing box computation is naive for arcs and text strings.