4.3BSD-UWisc/man/catl/ideal.l
IDEAL(1) UNIX Programmer's Manual IDEAL(1)
NAME
ideal - ditroff preprocessor for drawing pictures
SYNOPSIS
ideal [ -P_d_e_v ] [ -n ] [ files ]
DESCRIPTION
_I_d_e_a_l is yet another troff preprocessor for drawing figures
on a typesetter. The -P option tells ideal to prepare out-
put for printer _d_e_v (default is varian/versatec). The -n
option produces raw _i_d_e_a_l output, which passes unharmed
through either _n_r_o_f_f(1) or _d_i_t_r_o_f_f(1). A line beginning
`.IS' marks the start of an _i_d_e_a_l program. An _i_d_e_a_l 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'.
The building block for _i_d_e_a_l 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:
_v_a_r 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
_e_q_u_a_t_i_o_n
declares relative positions of significant points of
the box
_c_o_n_n asks for a straight-line path through named points
_p_e_n asks for a box to be replicated along a line between
two points
_l_e_f_t left-justifies text with respect to a point
_t_e_x_t centers text with respect to a point
_r_i_g_h_t
right-justifies text with respect to a point
_s_p_l_i_n_e
draws a spline guided by the named points
_p_u_t asks for an instance of a box to be drawn
_o_p_a_q_u_e
asks for a box to erase lines already in the picture
Printed 1/10/87 1
IDEAL(1) UNIX Programmer's Manual IDEAL(1)
that are covered by its bounding polygon
_b_o_u_n_d_a_r_y
specifies the bounding polygon for an opaque box
_c_o_n_s_t_r_u_c_t
builds a partial picture on a separate ``sheet of
paper''
_d_r_a_w adds the contents of the named constructed box to the
current picture
_I_d_e_a_l expects all components of a picture to be specified as
boxes; instructions to draw the entire picture should
comprise 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 _m_a_i_n is an exception to this
rule: it is always forgotten when the .IE is processed.
During its first pass, _i_d_e_a_l 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: _i_d_e_a_l
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. _I_d_e_a_l
knows about the following functions:
_A[_z,_w]
=__z+_A(_w-_z), _A of the way from _z to _w
_r_e (_z)
real part of complex number _z
_i_m (_z)
imaginary part of complex number _z
_c_o_n_j (_z)
complex conjugate of complex number _z
_a_b_s (_z)
absolute value (modulus) of complex number _z
_c_i_s (_x)
a unit vector in the direction of the real part of its
argument _x, which is an angle in degrees (radians if
the line `...radians' appeared more recently in the
file than the line `...degrees')
Printed 1/10/87 2
IDEAL(1) UNIX Programmer's Manual IDEAL(1)
_E (_x)
=__c_i_s(360_x) if _x is measured in degrees
_i_n_t (_x)
integer part of the real part of its argument _x
_a_n_g_l_e (_z)
arctangent of _i_m(_z)/_r_e(_z)
During the second pass, _i_d_e_a_l draws the picture.
To draw a circle, include the line `...libfile circle'
between the .IS and .IE lines, and _p_u_t the box named _c_i_r_c_l_e,
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 _c_e_n_t_e_r,
radius _r_a_d_i_u_s, and passes through _z1, _z2, and _z3.
To draw an arc, include the line `...libfile arc' between
the .IS and .IE lines, and _p_u_t the box named _a_r_c, 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 _c_e_n_t_e_r, radius
_r_a_d_i_u_s, starts at point _s_t_a_r_t at angle _s_t_a_r_t_a_n_g, passes
through point _m_i_d_w_a_y at angle _m_i_d_a_n_g, and ends at point _e_n_d
at angle _e_n_d_a_n_g. If no _m_i_d_w_a_y is specified, the arc is
drawn counterclockwise from _s_t_a_r_t to _e_n_d.
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 _i_d_e_a_l'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.
_I_d_e_a_l supports both C-style comments (between /* and */
brackets, and they nest), and shell-style comments (between
# and newline).
SEE ALSO
ditroff(1), grn(1), pic(1)
_I_D_E_A_L _U_s_e_r'_s _M_a_n_u_a_l , C. J. Van Wyk.
BUGS
_I_d_e_a_l is relatively unforgiving about syntax errors. Bound-
ing box computation is naive for arcs and text strings.
Printed 1/10/87 3