#set TITLE = "proc annotate"
#include top

.SH DESCRIPTION
\fBproc annotate\fR may be used to place arbitrary text at 
specific locations, in either absolute space or scaled space.
Annotation may include one or two arrows and a box if desired.

.SH FEATURES
Multiple lines of text supported.
Optional backing box for text.
Semi-intelligent placement of one or two arrows.
Control over text color, arrow color, and backing box color.

.SH EXAMPLES
See the Gallery Annotations examples
.ig >>
<a href="../gallery/gall.annot.html"><img src="../gallery/btn/here.gif"></a>
.>>

.SH PREREQUISITES
None.

.SH MANDATORY ATTRIBUTES
The \fCtext\fR and \fClocation\fR attributes MUST be specified.
If an arrow is desired, the \fCarrowhead\fR attribute must be specified.

.SH ATTRIBUTES
.LP
\fBtext\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\fImultiline text\fR
.ig >>
</a>
.>>
.IP
The text to be displayed.  Terminates with a blank line.
Text may also come from a file or command (see below).
.br
Example:
.nf
.ft C
text:	Value
	as of 1/15/99

.LP
\fBlocation\fR 
.ig >>
<a href="attributetypes.html#xy">
.>>
\fIx y\fR
.ig >>
</a>
.>>
.IP
The text will be placed at this location.
By default the text will be centered around X, and
the bottom of the first line will be at Y.
Absolute units are assumed;
append \fC(s)\fR to one or both values to indicate scaled units.  
.br
Example: \fClocation: 2.2(s) 3.0\fR


.LP
\fBarrowhead\fR 
.ig >>
<a href="attributetypes.html#xy">
.>>
\fIx y\fR
.ig >>
</a>
.>>
.IP
If specified, an arrow will be drawn pointing at this location.
The tail of the arrow will be placed automatically if \fCarrowtail\fR
is not specified.
Absolute units are assumed;
append \fC(s)\fR to one or both values to indicate scaled units.  
.br
Example: \fCarrowhead: 2012(s) 85(s)\fR

.LP
\fBarrowhead2\fR 
.ig >>
<a href="attributetypes.html#xy">
.>>
\fIx y\fR
.ig >>
</a>
.>>
.IP
Same as \fCarrowhead\fR above, for a second arrow.


.SH DETAIL ATTRIBUTES
.LP
\fBfromfile\fR \fIfilename\fR
.IP
If specified, the text will be read from this file.
This filename is expanded by a shell.

.LP
\fBfromcommand\fR \fIshell command\fR
.IP
If specified, this shell command will be executed to yield 
text on its standard output.

.LP
\fBtextdetails\fR 
.ig >>
<a href="textdetails.html">
.>>
\fItextdetails\fR
.ig >>
</a>
.>>
.IP
Allows control of details pertaining to the text, such as alignment, color, size, and font.
Example: \fCtextdetails: align=C size=9\fR

.LP
\fBbox\fR 
.ig >>
<a href="linedetails.html">
.>>
\fIlinedetails\fR
.ig >>
</a>
.>>
.IP
If specified, a box will be drawn around the text.
.br
Example: \fCbox: yes\fR  (do a default box)
.br
Example: \fCbox: color=yellow width=1.0\fR

.LP
\fBboxmargin\fR \fIn\fR
.IP
If specified, increase the size of the backing box by
\fIn\fR absolute units on all four sides.  
.br
Example: boxmargin: 0.15

.LP
\fBbackcolor\fR 
.ig >>
<a href="color.html">
.>>
\fIcolor\fR
.ig >>
</a>
.>>
.IP
Allows the box to be filled with \fIcolor\fR.
Has no effect if a box is not being done.

.LP
\fBarrowdetails\fR 
.ig >>
<a href="linedetails.html">
.>>
\fIlinedetails\fR
.ig >>
</a>
.>>
.IP
Allows control of details pertaining to the arrows, such as line thickness and color.

.LP
\fBarrowheadsize\fR \fIn\fR
.IP
Controls the size of the arrowhead.  
\fIn\fR is the length of the arrowhead in absolute units (default 0.1 inches).
This attribute may be set to 0 to suppress arrowhead and just draw line.

.LP
\fBarrowtail\fR 
.ig >>
<a href="attributetypes.html#xy">
.>>
\fIx y\fR
.ig >>
</a>
.>>
.IP
If specified, tail of 1st arrow will be at this point.  

.LP
\fBarrowtail2\fR 
.ig >>
<a href="attributetypes.html#xy">
.>>
\fIx y\fR
.ig >>
</a>
.>>
.IP
If specified, tail of 2nd arrow will be at this point.  

.LP
\fBverttext\fR  \fCyes\fR | \fCno\fR
.IP
If \fCyes\fR, text will be rendered vertically, from low to high.
This is a limited implementation;
backing box does not work with vertical text, nor does
automatic arrow tail placement (arrow tail must be specified).

#include bottom
