path: root/static/unix-v10/man1/ideal.1

.TH IDEAL 1
.CT 1 writing_troff graphics
.SH NAME
ideal \(mi troff preprocessor for drawing pictures
.SH SYNOPSIS
.B ideal
[
.I option ...
]
[
.I file ...
]
.SH DESCRIPTION
.I Ideal
is a constraint-based
.IR troff (1)
preprocessor for typesetting figures in the complex plane.
A line beginning 
.L .IS
marks the start of an
.I ideal
program,
.B .IE
or
.BR .IF 
marks the end.
.B .IE
leaves the typesetting baseline below the bottom of the picture;
.B .IF
(flyback) leaves it at the top.
The options are
.TP
.BI -T dev
Produce instructions for
.IR troff (1)
device
.I dev.
.B -a
is a synonym for
.BR -Taps ;
.B -t
for
.BR -T202 .
.TP
.B -tex
Produce output for
.IR tex (1).
.TP
.B -p
Produce
.IR plot (1)
instructions.
Erases come unbidden at every
.BR .IS .
.TP
.B -4
Produce instructions for a Tektronix
4014 and wait at each
.B .IE
for an input character
before erasing and starting the next picture.
.TP
.B -n
Produce raw
.IR ideal
output, which passes unharmed through
.I nroff.
.TP
.B -v
Print calculated values of variables on standard error.
.PP
.I Ideal
programs are built of
`boxes';
boxes look like C functions,
in that they are named and delimited by braces.
They may include the following kinds of statements,
each terminated by a semicolon:
.TF spline
.TP
.B 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 following
keywords as variable names:
.LR at ,
.LR bdlist ,
.LR boundary ,
.LR box ,
.LR conn ,
.LR construct ,
.LR draw ,
.LR exterior ,
.LR interior ,
.LR left ,
.LR opaque ,
.LR put ,
.LR right ,
.LR spline ,
.LR text ,
.LR to ,
.LR using ,
.L var
.TP
.I equation
declares relative positions of significant points of the box
.TP
.B conn
asks for a straight-line path through named points
.TP
.B pen
asks for a box to be replicated along a line between two points
.TP
.B left
left-justifies text with respect to a point
.TP
.B text
centers text with respect to a point
.TP
.B right
right-justifies text with respect to a point
.TP
.B spline
draws a spline guided by the named points
.TP
.B put
asks for an instance of a box to be drawn
.TP
.B opaque
asks for a box to erase lines already in the picture that
are covered by its bounding polygon
.TP
.B boundary
specifies the bounding polygon for an opaque box
.TP
.B construct
builds a partial picture on a separate `sheet of paper'
.TP
.B draw
adds the contents of the named constructed box to the current picture
.PD
.PP
.I Ideal
expects all components of a picture to be specified as boxes;
instructions to draw the entire picture should comprise a box called
.LR main .
Boxes are remembered across
.BR .IS / .IE
boundaries;
if you won't need a box again, you can reclaim the
space it requires by including the command
.BI ...forget " boxname"
on a line between any
.BR .IS / .IE
pair after the last use of
.I boxname.
Box
.L main
is an exception to this rule:
it is always forgotten at
.BR .IE .
.PP
During its first pass,
.I ideal
solves all the equations to determine the locations of all points
it needs to know.
These equations must be linear equations in complex variables,
although they may include non-linear operators:
.I 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.
.I Ideal
knows about the following functions:
.TF f[z,w]
.TP
.IB f [ z , w ]
.I == z+(w-z)f,
fraction
.I f
of the way from
.I z
to 
.I w
.TP
.BI re( z )
real part of complex number
.TP
.BI im( z )
imaginary part of complex number
.TP
.BI conj( z )
complex conjugate of complex number
.TP
.BI abs( z )
absolute value (modulus) of complex number
.TP
.BI cis( z )
the unit vector 
.if n .ig
$cos^x~+~i^sin^x$,
..
.if t .ig
cos(x) + i*sin(x)
..
where
.IR x " = re(" z )
and
.I x
is measured in degrees
(radians if the line
.B ...radians
appeared more
recently in the file than the line
.BR ...degrees )
.TP
.BI E( x )
.RI "== cis(360 x )
if
.I x
is measured in degrees
.TP
.BI angle( z )
angle of complex number,
.RI arctan(im( z )/re( z ))
.PD
.PP
During the second pass,
.I ideal
draws the picture.
.PP
To draw a circle,
include the line
.B ...libfile circle
between the
.B .IS
and
.B .IE
lines,
and
.B put
the box named
.LR 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
.LR center ,
radius
.LR radius ,
and passes through
.BR z1 ,
.BR z2 ,
and
.B z3.
.PP
To draw an arc,
include the line
.B ...libfile arc
between the
.B .IS
and
.B .IE
lines,
and
.B put
the box named
.LR arc ,
again giving 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
.LR center ,
radius
.LR radius ,
starts at point
.LR start ,
passes through point
.L midway
at angle
.LR midang ,
and
ends at point
.L end
at angle
.LR endang .
If no
.L midway
is specified, the arc is drawn counterclockwise from
.L start
to
.LR end .
.PP
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
.B ...width
command,
which includes a number in inches.
The default column width can be changed by a
.B ...colwid
command.
To defeat
.I ideal's
notion of the size of the picture, you can include lines of
the form
.BR ...minx ,
.BR ...miny ,
.BR ...maxx ,
or
.BR ...maxy ;
these give the various coordinates of the bounding box of the
picture in the coordinate system used by the picture.
.PP
.I Ideal
supports both C-style comments (between
.L /*
and
.L */
brackets \(em which nest),
and shell-style comments (between
.L #
and newline).
.SH EXAMPLES
.EX
.mk
\&...libfile circle
triangle {
	var z1, z2, z3;
	conn z1 to z2 to z3 to z1;
}
main {
	put T: triangle { 
		z1 = 0; z2 = 1; z3 = (2,2);
	}
	put circle {
		z1 = T.z1; z2 = T.z2; z3 = T.z3;
	}
}
.EE
.de xx
..
.if n .ig xx
.rt
.IS
...width 6
...libfile circle
...minx -8
triangle {
	var z1, z2, z3;
	conn z1 to z2 to z3 to z1;
}
main {
	put T: triangle { 
		z1 = 0; z2 = 1; z3 = (2,2);
	}
	put circle {
		z1 = T.z1; z2 = T.z2; z3 = T.z3;
	}
}
.IE
.xx
.SH "SEE ALSO"
.IR troff (1),
.IR pic (1), 
.IR ped (9.1), 
.IR doctype (1)
.br
C. J. Van Wyk,
`IDEAL User's Manual',
this manual, Volume 2
.SH BUGS
.I Ideal
is relatively unforgiving about syntax errors.
.br
Bounding box computation is naive for arcs and text strings.