%
%	LaTeX file for  the TeXtyl Manual
%	Copyright (c) 1986, 1987  John S. Renner
%

\documentstyle[twoside,12pt]{report}
\makeindex
\pagestyle{plain}
\pagenumbering{roman}
\begin{document}
\bibliographystyle{plain}
\hfuzz 5pt 
\vfuzz 3pt
%\hoffset 1in
%\voffset 1in
\hyphenchar\tentt=-1
% big tt font
\font\btt=cmtt10 scaled \magstep2
\hyphenchar\btt=-1
% font for small caps
\font\smallrm=cmr10

% special comma
\def\Coma{$\raise 2.5pt\hbox{\btt ,}$}
% macro for specifying a parameter
\def\Prm#1{\leavevmode \hbox{$\>\langle${\it #1\/}$\rangle\,$}}
% macro for specifying an optional parameter
\def\Opt#1{\leavevmode \hbox{$\>\lbrack\langle${\it #1\/}$\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack\,$}}
% optional parameter without large comma
\def\sOpt#1{\leavevmode \hbox{$\>\lbrack\langle${\it #1\/}$\rangle\,
\rbrack\,$}}
% used for simple verbatim environment using | | delimiters
%  taken from TeXbook
\chardef\other=12
\def\ttverbatim{\begingroup \catcode`\\=\other \catcode`\{=\other
        \catcode`\}=\other \catcode`\$=\other \catcode`\&=\other
	\catcode`\~=\other \catcode`\%=\other \catcode`\#=\other
    \obeyspaces \obeylines \tt}
{\obeyspaces\gdef {\ }}
\outer\def\begintt{$$\let\par=\endgraf \ttverbatim \parskip=0pt
   catcode`\|=0 \rightskip=-5pc \ttfinish}
{\catcode`\|=0 |catcode`|\=\other
  |obeylines
  |gdef|ttfinish#1^^M#2\endtt{#1|vbox{#2}|endgroup$$}}
\catcode`\|=\active
{\obeylines\gdef|{\ttverbatim\spaceskip=.5em plus .25em minus .15em\let^^M=\  \let|=\endgroup}}
%
% macro for figures for Tyling
\input{textyl}

\newcommand{\TT}{{\it\TeX tyl\/} }
\newcommand{\TTN}{{\it\TeX tyl}}
\newcommand{\DVI}{{\smallrm DVI}}
\newcommand{\Makeodd}{{\ifodd\count0{\newpage\mbox{\  }\newpage}\fi}}

\title{\TeX tyl: a line-drawing interface for \TeX}
\author{John S. Renner}
\date{14 March 1987
\thanks{Copyright \copyright 1987~John~S.~Renner All rights reserved.}}
\maketitle
\clearpage %end page 0
\begin{verse}
\it Geometry can produce legible letters,\\
 but art alone makes them beautiful.\\
\end{verse}\par
\noindent\begintyl{260 pt}[1in]
\special{tyl beginfigure "zapf"}
\special{tyl line m 2 1,92; 45,92}
\special{tyl line m 2 1,92; 1,48}
\special{tyl line m 2 1,48; 111,48}
\special{tyl line m 2 45,92; 45,4}
\special{tyl line m 2 12,48; 12,92}
\special{tyl line m 2 23,48; 23,92}
\special{tyl line m 2 34,48;34,92}
\special{tyl line m 2 1,70;45,70}
\special{tyl line m 2 1,92; 23,48}
\special{tyl line m 2 1,92; 89,4}
\special{tyl line m 2 23,92;1,70}
\special{tyl line m 2 23,92;1,48}
\special{tyl line m 2 23,92; 45,48}
\special{tyl line m 2 45,92;1,48}
\special{tyl line m 2 45,92; 23,48}
\special{tyl line m 2 1,70,23,48}
\special{tyl arc m 2 11 @ 12,81 270,90}
\special{tyl arc m 2 11 @ 34,81 10 10}
\special{tyl arc m 2 11 @ 34,59 10 10}
\special{tyl arc m 2 11 @ 12,59 270 90}
\special{tyl arc m 2 22 @ 23,70 10 10}

\special{tyl line m 2 45,92; 111,26}
\special{tyl line m 2 1,48; 45,4}
\special{tyl line m 2 45,4;100,60}
\special{tyl arc m 2 32 @ 45,48 10 10}
\special{tyl line m 2 45,4; 89,4}
\special{tyl line m 2 89,4; 89,60}
\special{tyl line m 2 89,4 111 26}
\special{tyl arc m 2 22  @ 67,26 10 10}
\special{tyl line m 2 67 26; 111 26}
\special{tyl arc m 2 16 @ 89,26 10 10}
\special{tyl line m 2 89,26; 111,48}
\special{tyl arc m 2 11 @ 100,37 10 10}
\special{tyl line m 2 100,37;100,60}
\special{tyl line m 2 111,26;111,48}
\special{tyl line m 2 111,48; 100,60}
\special{tyl arc m 2 8 @ 100 48 10 10}
\special{tyl arc m 2 6 @ 94 54 10 10}
\special{tyl line m 2 89,60; 100 48}
\special{tyl line m 2 95,54; 83 54}
\special{tyl arc m 2 4 @ 89 54 10 10}
\special{tyl line m 2 89 54; 100 54}
\special{tyl line m 2 89,60;83,54}
\special{tyl line m 2 89, 60; 100 60}
\special{tyl line m 2 83,54; 83,48}
\special{tyl line m 2 84,48; 89,54}
\special{tyl arc m 2 3 @ 86 51 10 10}
\special{tyl endfigure "zapf"}
\endtyl
\par
\nobreak
\begin{verse}
\it Art begins where geometry ends,\\*
and imparts to letters a character\\*
transcending mere measurement.\\*
\hskip 2in\hbox{\smallrm Paul Standard}
\end{verse}\index{Zapf{,} Hermann}\index{Standard{,} Paul}
\newpage %end page 1
\mbox{   }
\newpage %clear page 2
\tableofcontents

\Makeodd
\chapter*{ Introduction} 
\label{introduction} 
\TT\index{{\TT}} is a prototype post-processing system to be used in
conjuction with {\TeX}\index{{\TeX}}\cite{knuth-tex82}, the typesetting program by Donald
Knuth.  The purpose of \TT is to ``draw'' lines and curves in a
device-independent manner. \TT is a post-processor that
interprets certain commands in a {\DVI}\index{DVI} 
({\underline d}e{\underline v}ice-{\underline i}ndependent)
file that is the
output of {\TeX} and contains the actual typesetting commands.
\TT will produce as its output another
{\DVI} file that contains the commands to typeset the lines and
curves on a printer or output device.\par

In the current version of \TT (version 1.2 of March 1987), the simple line drawing
capabilities\index{capabilities} include several general types of straight lines, arcs, and
spline curves. Advanced features of \TT are for {\it MusiCopy}\index{MusiCopy}, the
music-typesetting\index{music} project  at the Ohio State
University\cite{gourlay}, namely typesetting ties, slurs, and beams.\par

The name\index{{\TT}, name} for \TT comes from three ideas: (1) a proper computer graphics
term for rendering images is called ``tiling,'' (2) the
mis-pro\-noun\-ci\-ation of the name sounds like ``textile,'' which evokes an image
of lines and bargello effects from weaving, and (3) this process of ``tyl''-ing\index{tyling} comes after {\TeX}.\par

The main design goals\index{design goals} of \TT were (1) the minimization of data required
to typeset graphics on printers capable of setting only characters at
arbitrary positions on a page,
(2) the adherence to the  {\DVI} format of {\TeX} output for specifying the
way to typeset a document in a device-independent manner,  (3)
 a simple, portable interface that would not require a change to the
functionality or design of {\TeX}, and (4) a user interface that is easy to
use by people and programs alike.\par

\TT was not intended to mimic nor replace sexy programs like
{\it Ideal\/}\index{Ideal}\cite{vanwyk}, which know about constraints 
and alignment niceties.
Rather, \TT is designed to
take care of medium-level details for {\TeX} for use on printing devices not
capable of directly accessing and 
loading full bitmaps\index{bitmaps} produced by such systems as {\it
PostScript\/}\index{PostScript}\cite{adobe}. It is clear that {\DVI}-format is a subset of {\it
PostScript}, but a large community of users are not able to make use of such
a super-set, and \TT is intended to provide line-drawing
capabilities\index{capabilities} for them.\par

Probably the best way to read this manual\index{{\TT}, how to read manual}
 is to read the first four (4) 
chapters, and skip right to the chapter entitled {\it Future Extensions},
for a good introduction to \TTN. The other chapters deal with details of 
the innards of \TTN, and describe the design in successively finer
detail.\par

I would like to thank John Gourlay, and Clayton Elwell for their support,
comments, reminders, and good ideas during this three-year labor, and the 
{\smallrm CGRG} for not hassling me about this.\par

\Makeodd
\chapter{The Basics}
\pagenumbering{arabic}
\label{getting-started}So, let's draw.
I will assume that the reader  has a reasonably good working knowledge of how to
use {\TeX}\index{{\TeX}} and/or {\LaTeX}\index{{\LaTeX}}, and sort of understands
 Knuth's\index{Knuth{,} Donald} concept of ``boxes,''\index{boxes} and their
attributes of height, width, and current position\index{current position}. We need these concepts
because our direct interface is with {\TeX}, in the form of a {\tt .tex}
text-file\index{{\tt .tex} text file}. To typeset the line-drawings, we ask {\TeX} to place our drawing
at the current position on the page. Throughout this manual, I will provide
some examples of drawings to illustrate ideas. These figures are thumb-nail
size, but should be sufficient to get the idea across without using up lots
of space on a page.
 Let's look at a simple example: After typing |\input{textyl}| \index{{\tt
textyl.tex} file}\index{{\tt input}}
near the
beginning of your file, but after any required preamble\index{preamble}, we
can obtain a trivial drawing like:
\index{line example}\par
\noindent\hskip 2in\begintyl{2truecm}[1in]
\special{tyl line  4 20, 0; 80,30}
\endtyl\par
\noindent Simple, but we achieved this 
 line by typing
\begin{verbatim}
...a trivial drawing like:\par
\noindent\hskip 2in\begintyl{2cm}[1in]
\special{tyl line  4 20, 0; 80,30}
\endtyl\par
\end{verbatim}

The |\begintyl{2cm}[2in]| and |\endtyl| commands\index{macros}\index{space macros} were
\index{{\tt begintyl}}\index{{\tt endtyl}}\index{macros, {\it see} {\tt begintyl}}to give us some
space\index{space} to ``paste'' the picture in
(about 2 centimeters of vertical space, 1 inch of horizontal space, 
and offset from the left-most margin by 2 inches),\footnote{See also Appendix~\ref{secapp}} 
 and the |\special...|\index{{\tt special}} is our way of asking for the above drawn line.
 Here, we must use a ``|\special|'' to talk to {\TeX}
at this level. Later, \TT will actually do the work involved in
typesetting that line that {\TeX} recorded as being at this place on the
page. The |\special|\index{specials} is a way to make a kind of note or memo that {\TeX}
will write into the {\DVI} file for some other program like 
\TT to work with, or choose to ignore, like most {\DVI}
filters do. \par

Let's look at what |\special{tyl line 4 20, 0; 80,30}| is all about. First,
|tyl| is a name-string\index{{\tt tyl} name-string} asserting that this command
 should make sense to \TTN. 
Next, |line| is the name of the graphic
primitive\index{primitive}
 to typeset: a
line segment (we will get to the other primitives later). The rest of the ``special''
notes that the thickness\index{line thickness} of the line is $4$, and to draw the line from a
mark 20 printer's-points\index{printer's points, measurement} to the
 right of the current position to a mark 80
points over and 30 points higher from that current position. Mathematically,
we are using a {\bf first-quadrant} cartesian
 coordinate-space\index{cartesian-space}\index{coordinates}
 whose origin\index{origin}\index{coordinates, origin} is at the
current position\index{current position} on the page, and we are drawing a line from $(20,0)$ to 
$(80,30)$ in integer units\index{measurement, units} of printer's-points in that space. It looks like this (magnified):\par
\noindent\hskip 1in\begintyl{130 pt}
\special{tyl beginfigure}
\special{tyl line m 2 0,0 0,40}
\special{tyl label m 1  0 43 "+Y"}
\special{tyl line m 2 0 0 90 0}
\special{tyl label m 1 93 0 "+X"}
\special{tyl arc m 1 2 10 10}
\special{tyl line m 8 20,0;80,30}
\special{tyl line m 1 0 10, -2,10}
\special{tyl line m 1 0 20, -2 20}
\special{tyl line m 1 0 30 -2 30}
\special{tyl line m 1 0 40 -2,38}
\special{tyl line m 1 0 40 2 38}

\special{tyl line m 1 10 0 10 -2}
\special{tyl line m 1 20 0 20 -2}
\special{tyl line m 1 30 0 30 -2}
\special{tyl line m 1 40 0 40 -2}
\special{tyl line m 1 50 0 50 -2}
\special{tyl line m 1 60 0 60 -2}
\special{tyl line m 1 70 0 70 -2}
\special{tyl line m 1 80 0 80 -2}
\special{tyl line m 1 90 0 88 2}
\special{tyl line m 1 90 0 88 -2}
\special{tyl endfigure}
\endtyl
\par
\vskip 10pt
\noindent where we have emphasized the origin of the quadrant, and used
tick-marks for every ten printer's-points. In reality, someone preparing a
figure would sketch\index{figures, preparation}
\index{preparing a figure} something out on grid paper, and then use those
coordinates for use in the |\special|. If he were really in luck, he
could use a graphic editor that would take care of such numeric details, and
maybe even output the  |\special| strings for direct insertion into the
{\tt .tex} file. Maybe. For now, we will have to stick to the grid-paper
method. The only things that we have to remember are that the origin\index{grid-origin} of our
quadrant is placed at the position\index{current position} on the page where we invoke the
|\special| of {\TeX}, and that we may want to leave white space\index{space}\index{leaving white space} for our
graphic to be drawn in. This last constraint is because {\TeX} does not
really know about the size of our drawing, it thinks that the |\special| is
a ``box''\index{boxes} with zero height and width placed at the current position on the
page. It is up to us to decide how much {\it real\/} space to tell {\TeX} to
leave for our drawing to be put into later by \TTN.\par
In the example above,
and the following examples, we will put our |\special| strings within an
environment that makes it easy to specify where the origin of our quadrant
should be placed. For example, |\begintyl{4cm}[1in]| \index{{\tt begintyl}}
 tells {\TeX} to place
our origin 4 centimeters down from where it was just sitting.
A horizontal width is an optional second parameter to |\begintyl|,
and is enclosed in square braces immediately following the vertical 
displacement parameter (with no spaces in-between). So |\begintyl{5cm}|
would place our origin 5 centimeters below the current position, with no
relative horizontal width. Other spacing requirements have to be done by
hand (e.g., like typing |\hskip 1in| before the |\begintyl|), or by putting the whole
|\begintyl| \ldots |\endtyl| group within a containing environment (e.g.,
\LaTeX's |figure| environment).
 We could, if
we wanted,
leave no extra white-space\index{leaving no space} and have the drawing extend  into
 and over any text that {\TeX} may typeset
before {\it or\/} after we invoke a |\special{tyl ...}| command. We would,
of course, start that  tyling-environment with a 
 |\begintyl{0pt}| command, and finish with the |\endtyl| command, and it
might do something
 like \begintyl{0pt}\special{tyl arc m 3 5 @4 0;5 5}\endtyl this.
\par

\goodbreak Once we are satisfied with our {\tt .tex}\index{{\tt .tex} text file}
 file containing |\special| strings
requesting line-drawings, we run the {\tt .tex} file through
 {\TeX}\index{{\TeX}} or {\LaTeX}\index{{\LaTeX}}, and
(barring any fatal errors) end up with a {\tt .dvi} file\index{{\tt .dvi} file}. 
We now run\index{running {\TT}}
 this {\tt .dvi} file through \TT which goes through the file and converts our
|\special| strings left-over from {\TeX} into commands to actually typeset
the line-drawing. The whole process might look something like this:\par

\bgroup\small
{\it prompt:}\underbar{\tt tex}\par
{\tt This is TeX, Version mumble...}\par
{\tt **}\underbar{\tt myfile.tex}\par
\hspace*{6em}$\ldots$ {\it output from \TeX}\par
{\tt Output written on myfile.dvi ( n pages , m bytes).}\par
{\it prompt:}\underbar{\tt textyl}\par
{\tt This is TeXtyl, Version blah...}\par
{\tt DVI-input File Name:}\underbar{\tt myfile.dvi}\par
{\tt DVI-output File Name}\par
{\tt (different than input name)[default of myfile.tyl]:}
\underbar{\tt myfile2.dvi}\par
\hspace*{6em}$\ldots$ {\it output  from \TT}\par
{\tt Output written on myfile2.dvi}\par
{\tt Log written on myfile2.tlog}\par

\egroup
\noindent So there you have it. All we have to do is give this 
new {\tt .dvi} (or {\tt .tyl}) file to
a favorite {\DVI} filter\index{DVI-filters}, and look at the document with the
line-drawing results on that particular filter's output device\index{output
device}
(usually paper or a bitmapped screen). You should
contact your local maintainer\index{local maintainer} if \TT or the filter
 cannot find the right fonts, and try again.\par
By the way, the {\tt .tlog} file is useful for finding out about the
``tyling'' of the {\tt .dvi} file. Besides noting any errors, the log file
contains the approximate height and depth of each non-trivial figure. A
portion of the {\tt .tlog}\index{{\tt .tlog} file} file for this document 
might look like:
\vspace*{-20pt}

{\footnotesize\begin{verbatim}
17] [
Figure #1 on page 18 is approx. 33 pts high and 47 pts wide

Figure #2 on page 18 is approx. 32 pts high and 51 pts wide

Figure #3 on page 18 is approx. 27 pts high and 45 pts wide

Figure #4 on page 18 is approx. 31 pts high and 82 pts wide
18] [19] [20] [
\end{verbatim}

}
This information allows you to re-edit the parameters to |\begintyl| so that
\index{{\tt begintyl}} they can better approximate the actual sizes of the figures.\par
\medskip\filbreak
Let's try a slightly more complicated example: drawing a spline.\index{spline, example} 
\TT understands drawing smooth spline curves\index{spline curves}\index{curves} through 
in\-teger co\-ordinate points (both positive and negative)\index{spline, coordinates}
 on our grid. For example:
\vspace*{-10pt}
\begin{verbatim}
\begintyl{3cm}[1in]
\special{tyl spline m 4 K 7 5,10; 9,14; 15,7;22,13;
                               17,14;12,5;7,0;}
\endtyl\par
\end{verbatim}
yields\par
\noindent\hskip 1in\begintyl{2cm}[1in]
\special{tyl spline m 4 K 7 5,10; 9,14; 15,7; 22,13;17,14;12,5; 7,0; }
\endtyl
\par\filbreak
\noindent Here, we are using units of millimeters for measurement (denoted
by an |m| or |M|,\index{{\tt M}-marker}\index{millimeters, measurement} a line thickness of $4$, and we
 want to use a Catmull-Rom type spline\index{spline,
Catmull-Rom}\index{Catmull-Rom splines}
(denoted by |k| or |K|\index{{\tt K}-marker}---also the default type\index{spline, 
default}
 if none is specified). We 
 specify that there are $7$ control points\index{spline, control-points} 
to interpolate through, and then
list those $x, y$ pairs.  Some things are optional
\index{defaulting values}\index{optional values}
 for you (like the spline type, or the units of measure), but
some are {\it not\/} (notably the line-thickness and the number of control points).
As we go through these examples, I will point out the minimum that we
need to specify a graphic primitive, and note other options or features that
we might want to use. For a detailed look at the specifications of the
primitives, please refer to the \underbar{\it User-Level
Details} in chapter~\ref{user-level}.\par\filbreak

Let's try one more type of spline-primitive: the thick-n-thin
spline\index{ttspline}\index{Thick-n-thin spline}\index{spline, ttspline}. This
is a primitive that lets us specify a spline of varying line thickness along
the spline. An example\index{ttspline, example} invocation might be:
\begin{verbatim}
\special{TYL ttspline m 5 4,6; 14,25; 18,19; 21,15; 24,8;
                           10;    2;    6;     3;     8}
\end{verbatim}\par
\noindent\hskip 1in
\begintyl{4cm}[2in]
\special{tyl ttspline m 5 4,6; 14,25; 18,19; 21,15; 24,8;
			  10;	2;	6;	3;    8}
\endtyl\par
\noindent It looks similar to the |spline| primitive, but here we did not
specify a single line thickness right after the |m|\index{{\tt M}-marker}
 measure-marker. The |5|
refers to the number of control-points as before, then is followed by the
$(x,y)$ coordinate pairs, and then  the line-thicknesses\index{ttspline, thicknesses}. The first
number (here, |10|) refers to the line thickness at the first control-point
(here, $(4,6)$ ); the next for the second control-point, etc. We did not
need to align the thicknesses under the control-points, but  it
makes the correspondence more apparent.  We did not
specify the type of spline to use, so the Catmull-Rom interpolating spline
was used by default\index{ttspline, defaults}. We could have inserted a
 |b| marker\index{{\tt B}-marker}
 directly before the number of control-points,\label{thebases}
and gotten a spline using the B-spline basis\index{B-spline
basis}.\index{spline, B-spline}
 Using 
a |d| marker\index{{\tt D}-marker} yields a spline with the Cardinal
basis\index{Cardinal basis},\index{spline, Cardinal} and
an |i|\index{{\tt I}-marker} would indicate an
Interpolating B-spline\index{B-splines, interpolating-type}\index{spline,
Interpolating B-spline}
 (which is a little different)\index{interpolating B-spline}. We will
look closer at these spline-types on page~\pageref{diffsplines}.
\par\filbreak

If you've been very observant, you may have noticed that the way we type in
the |\special| strings\index{typing in special
strings}\index{specials, typing in}
 (the letters and numbers within the |{| -- |}| pair)
has been rather indiscriminant about upper vs. lower-case\index{specials, case insensitivity}.
 That's okay. \TT
 has only a few things to worry about, and so it will try to
figure things out for you. It is pretty lenient about how you
punctuate\index{specials, punctuation}
 and
separate (``delimit'')\index{delimiters} keywords\index{keywords}
 and markers\index{markers}.\goodbreak\filbreak  We only have to remember 
\begin{enumerate}
\item the relative ordering of the keywords and integers,
\item being careful to avoid
mis-using the word markers\footnote{See the index for a list of markers} in
the wrong places, and
\item supplying enough parameters that are expected.
\end{enumerate}
Other than its own macro-expansions, {\TeX} really
 doesn't care about the ``meaning'' of the final strings that
 goes inside the curly braces of the 
|\special{...}| command-strings, only \TT does.\par

We'll briefly look at an example of one more graphic primitive, and then get
on to more advanced topics. \TT has the ability to draw arcs and
circles like\index{arcs}\index{circles}:\par
\noindent\hskip 2in\begintyl{7truecm}[2in]
% 15-Mar-87 15:51:23
% TeXtyl figure written with width= 198 mm and height= 206 mm
%   you may have to scale it with Transform or Fit operators in beginfigure
\special{tyl beginfigure m W 198 206 F 50 50}
\special{tyl arc m 3 c 64 @(134 114) 357 54}
\special{tyl arc m (T 120 80 0 0 0) 3 c 31 @(36 31) 10 10}
\special{tyl arc m 3 c 53 @(129 77) 94 58}
\special{tyl arc m 3 c 66 @(85 140) 27 323}
\special{tyl arc m 1 c 57 @(57 100) 10 10}
\special{tyl endfigure}
\endtyl\par\filbreak
\noindent Arcs are drawn from an initial angle (measured
from the horizontal (positive x-axis) in integer degrees) counter-clockwise 
to a final angle with 
the arc centered about the origin.\index{arcs, angles}\index{arcs, center}
 If the
initial angle is the same as the final angle, we get a full circle\index{circles}\index{arcs, circles}.
A simple arc invocation might look like\index{arcs, example}:\par
|\special{tyl arc m 2 3, 48, 280}|\par
\noindent which would draw an arc of line thickness $2$, a radius\index{arcs, radius} of $3$
millimeters, from an initial angle of 48 degrees until the final angle of 280
degrees centered about the origin. We could specify that the arc is to be
centered\index{arcs, centering}
elsewhere by using a special |@|\index{{\tt @}-marker} marker. So,\par
|\special{tyl arc m 2 3, @ 7,7; 10 10  }|\par
\noindent would draw an arc of line-thickness $2$, radius of $3$ mm as before,
but centered at $(7,\, 7)$ from the origin. Also, since the initial and final
angles are the same in this example (|10|), we would get a full circle.
\par\vfill\pagebreak[4]
%\Makeodd
\chapter{Advanced Features}
\label{advanced-features}In the previous chapter, we saw basic examples of most of the graphic
primitives available in \TTN, how to invoke them\index{primitives, invoking}, and some of
the parameters\index{primitives, parameters} to the primitives. We also saw examples of how we interface
with {\TeX} using the |\special| command strings, and how the origin of our
drawing quadrant is placed at the reference point  of the ``box'' containing
the |\special| (usually the lower-left corner of the box created with the
|\begintyl| and |\endtyl| macros.\index{macros}\index{boxes}
 (see the {\TeX book}\cite{knuth-tex82}\index{\TeX book} for a better explaination of
``specials''). The rest of this chapter will look more at
the parameters available for the primitives, and how we can
combine\index{primitives, combining}\index{combining primitives}
primitives and manipulate them.\par

\section{Transforms}
\label{transforms}\index{transforms}
The most interesting additional parameter for the primitives is a transform
operation. It allows us to modify an already-exisiting definition of a
primitive without our having to totally re-edit the |\special|
string, nor having
to explicitly re-compute the  coordinates of the line/spline points.
Thus we can take a simple definition similar as before, like:\par
|\special{tyl line m 4 0,8; 39,44}|\par
\noindent and change its size, or rotate it, or translate (shift)
its position\index{scaling}\index{rotation}%
\index{translating}\index{primitives, scaling; rot\-ating; trans\-lating}
without completely changing the actual text of the
 specification of the control points (this is really useful
when dealing with splines having many control points).
\index{transforms, scaling}\index{transforms, rotating}
\index{transforms, translation}
\filbreak
 Let's look at an
example, and then go into more detail about the transform. For example, to
rotate the above definition about its center by 60 degrees
counter-clockwise, all we have to specify is
|\special{tyl line m T (100, 100, 0, 0, 60) 4 0,8; 39, 44}|
 which yields\index{transforms, example}\par
\noindent\hskip 1in\begintyl{1in}[2in]
% 15-Mar-87 15:47:50
% TeXtyl figure written with width= 196 mm and height= 71 mm
%   you may have to scale it with Transform or Fit operators in beginfigure
\special{tyl beginfigure m W 196 71 F 51 51}
\special{tyl line m 4 c 170 0 154 71}
\special{tyl line m 4 c 54 61 0 11}
\special{tyl line m 1 c 109 28 114 37}
\special{tyl line m 1 c 107 45 114 37}
\special{tyl line m 1 c 110 34 87 34}
\special{tyl line m 1 c 111 37 89 37}
\special{tyl line m 1 c 110 39 87 39}
\special{tyl endfigure}
\endtyl\par
\noindent as expected. We use the |T|\index{{\tt T}-marker} marker to note the need for a
transformation, and follow it by five numbers\index{transforms, parameters}.
 The first two are for
scaling, the next two for translation, and the last (here, |60|) is for our
rotation.  In general, the 
format for specifying some transformation on the currently-specified points
is:\par
\qquad{\btt T}\ \Prm{Sx}\Coma\Prm{Sy}\Coma\Prm{Tx}\Coma\Prm{Ty}\Coma\Prm{Rot}\Coma\par
\noindent where \Prm{Tx} and \Prm{Ty} are translations of the object in
 the $X$ or $Y$ direction, respectively, by some signed distance according to the 
current units of \Prm{measure} (|m|\index{{\tt M}-marker} still means millimeters in the above example).
 \Prm{Rot} is a signed integer angle (in degrees) \index{rotation} 
by which\index{rotation, using degrees measurement}
to rotate the primitive counter-clockwise about its center.
  \Prm{Sx} and \Prm{Sy} are\index{transforms, parameters}
integer scale parameters representing the real values of the 
transform multiplied by 100. For example, if you wanted to scale the drawing
in the $X$ direction (relative to the drawing's center)
 by an additional 50\% (i.e., scale by 1.5),
\Prm{Sx} would be 150. Negative values are usuable, too, so
mirroring\index{transforms, mirroring} about the $Y$ axis is achievable by
scaling in the negative $X$ direction, like $\Prm{Sx} = -100$.
To obtain any transform, {\it all\/} the transform parameters must be
specified. A no-op transform\index{transforms, no-op} would look kind of like
{\tt T~(100,~100,~\kern-1pt0,~\kern-1pt0,~\kern-1pt0)} in the middle of 
the |\special|. \par 

\section{Figures}
\label{figures}
The last major \TT concept is the idea of combining 
several primitives\index{primitives, combining} into what we call a
``figure.''\index{figures}\index{combining primitives}
This figure can be manipulated either as a single entity  or in parts
by
using the \Prm{transform} operations\index{figures, transforms} described 
in the previous section. 
These optional figure-level transformations
will transform all the figure's primitives (which may have local
transformations of their own). The result is a nested symbol definition
\index{nested symbols}\index{figures, nested symbols}
that has concatenatable transformations\index{transforms, concatenation}. 
This is useful for defining some
 symbol, created from various primitives, and dealing with it 
as a unit. For example,  a basic logotype can be defined, and then moved
about, scaled, or rotated as desired {\it without\/} having to change the
original definition of the logotype or its parts from scratch. 
These  commands are:\par
\medskip
{\btt\char'134 special\char'173 tyl beginfigure}
{\leavevmode \hbox{$\>\lbrack\langle${\it transform\/}$\rangle\,
\rbrack\,$}}{\btt\char'175}\par
\noindent which opens a level of definition\index{{\bf beginfigure}}\index{figures, defining},
and\par
\medskip
{\btt\char'134 special\char'173 tyl endfigure}{\btt\char'175}\par
\noindent which closes that level of definition\index{{\bf endfigure}}.
 Any calls to a
|\special{tyl ...| primitive within a |beginfigure| -- |endfigure| pair
become part of that figure's definition\index{figures, sub-figures}. 
Note the definition of |beginfigure| allows the ability to apply a
transformation at the outer level. A simple example might be:\index{figures,
examples}\vspace*{-10pt}
\begin{verbatim}
\begintyl{2in}
\special{tyl beginfigure}
	\special{tyl line m 2 5,10; 15,15 }
	\special{tyl line m 4 10,20; 16,1 }
	\special{tyl line m 8 15,10; 25,10 }
\special{tyl endfigure}
\endtyl
\end{verbatim}
giving a figure of three lines:\par
\noindent\hskip 2in\begintyl{1truein}[2in]
\special{tyl beginfigure "oflines"}
\special{tyl line m 2 5,10; 15,15 }
\special{tyl line m 4 10,20; 16,1 }
\special{tyl line m 8 15,10; 25,10 }
\special{tyl endfigure "oflines" }
\endtyl\par
\noindent We can also define sub-figures\index{sub-figures} within figures
and apply\label{sub-figures}
transformations\index{transforms, sub-figures} to those, too. The idea looks like:\par
|\begintyl{down-distance}[optional-width]|\par
|\special{tyl beginfigure}|\par
\qquad	$\ldots$\par
\qquad|\special{tyl beginfigure}|  {\it \% Some sub-figure }\par
\qquad	$\ldots$\hbox{\hskip 2in}   {\it \% of other primitives}\par
\qquad|\special{tyl endfigure}|\par
\qquad   $\ldots$\par
|\special{tyl endfigure}|\par
|\endtyl|\par
\noindent Where ``$\ldots$'' means possible other invocations of
primitives with |\special{tyl...}| strings.  We are
able to use spacing and tabbing to nicely indent our |\special| strings,
since {\TeX} considers all that white space to be non-existent within the 
|\begintyl| -- |\endtyl| environment.\index{{\tt begintyl}}\index{{\tt
endtyl}}
\par\filbreak

We'll look at a basic figure\index{figures, example}, and apply some
transforms to parts of it. 
 For the basic figure, we have:\par
\noindent\hskip 2in\begintyl{1in}[2in]
\special{tyl beginfigure "TeXtyl-logo-1"}
     \special{tyl beginfigure "tex-logo"}
	\special{tyl line m 3 2,13; 10,13}
	\special{tyl line m 3 6,13; 6,6}

	\special{tyl line m 3 8,11;8,4}
	\special{tyl line m 3 8,11;12,11}
	\special{tyl line m 3 8,8; 11,8}
	\special{tyl line m 3 8,4;12,4}

	\special{tyl line m 3 13,13;18,6}
	\special{tyl line m 3 13,6;18,13}
    \special{tyl endfigure}
    \special{tyl beginfigure  "tyl-logo"}
	\special{tyl line m 3 20,10;24,10}
	\special{tyl line m 3 22,12;22,6}

	\special{tyl line m 3 25,10;27,6}
	\special{tyl line m 3 29,10;26,2}

	\special{tyl line m 3 31,13;31,6}
    \special{tyl endfigure}
\special{tyl endfigure}\endtyl\par\filbreak
\noindent Now let's scale a sub-figure by using a |T|\index{{\tt T}-marker}
 transform at the 
|beginfigure| level; i.e., something like 
\verb+\special{tyl beginfigure T 60 60 0 0 0}+ :\par
\noindent\hskip 2in\begintyl{ 1in}[2in]
\special{tyl beginfigure "TeXtyl-logo-2"}
     \special{tyl beginfigure "tex-logo"}
	\special{tyl line m 3 2,13; 10,13}
	\special{tyl line m 3 6,13; 6,6}

	\special{tyl line m 3 8,11;8,4}
	\special{tyl line m 3 8,11;12,11}
	\special{tyl line m 3 8,8; 11,8}
	\special{tyl line m 3 8,4;12,4}

	\special{tyl line m 3 13,13;18,6}
	\special{tyl line m 3 13,6;18,13}
    \special{tyl endfigure}
    \special{tyl beginfigure T 60 60 0 0 0  "tyl-logo"}
	\special{tyl line m 3 20,10;24,10}
	\special{tyl line m 3 22,12;22,6}

	\special{tyl line m 3 25,10;27,6}
	\special{tyl line m 3 29,10;26,2}

	\special{tyl line m 3 31,13;31,6}
    \special{tyl endfigure}
\special{tyl endfigure}\endtyl\par\filbreak
\noindent We can rotate, and then also translate that same
sub-figure and achieve the next two examples. First, a rotation about 
the sub-figure's center:\par
\noindent\hskip 2in\begintyl{ 1in}[2in]
\special{tyl beginfigure "TeXtyl-logo-3"}
     \special{tyl beginfigure "tex-logo"}
	\special{tyl line m 3 2,13; 10,13}
	\special{tyl line m 3 6,13; 6,6}

	\special{tyl line m 3 8,11;8,4}
	\special{tyl line m 3 8,11;12,11}
	\special{tyl line m 3 8,8; 11,8}
	\special{tyl line m 3 8,4;12,4}

	\special{tyl line m 3 13,13;18,6}
	\special{tyl line m 3 13,6;18,13}
    \special{tyl endfigure}
    \special{tyl beginfigure T 60 60 0 0 -35 "tyl-logo"}
	\special{tyl line m 3 20,10;24,10}
	\special{tyl line m 3 22,12;22,6}

	\special{tyl line m 3 25,10;27,6}
	\special{tyl line m 3 29,10;26,2}

	\special{tyl line m 3 31,13;31,6}
    \special{tyl endfigure}
\special{tyl endfigure}\endtyl\par\filbreak
\noindent and now also translated {\it after\/} the rotation:\par
\noindent\hskip 2in\begintyl{1in}[2in]
\special{tyl beginfigure "TeXtyl-logo-4"}
     \special{tyl beginfigure "tex-logo"}
	\special{tyl line m 3 2,13; 10,13}
	\special{tyl line m 3 6,13; 6,6}

	\special{tyl line m 3 8,11;8,4}
	\special{tyl line m 3 8,11;12,11}
	\special{tyl line m 3 8,8; 11,8}
	\special{tyl line m 3 8,4;12,4}

	\special{tyl line m 3 13,13;18,6}
	\special{tyl line m 3 13,6;18,13}
    \special{tyl endfigure}
    \special{tyl beginfigure T 60 60 -8 -8 -35  "tyl-logo"}
	\special{tyl line m 3 20,10;24,10}
	\special{tyl line m 3 22,12;22,6}

	\special{tyl line m 3 25,10;27,6}
	\special{tyl line m 3 29,10;26,2}

	\special{tyl line m 3 31,13;31,6}
    \special{tyl endfigure}
\special{tyl endfigure}\endtyl\par\filbreak
\noindent Finally, we can take the whole figure, and perform a scale and a
then a rotation on it (we evaluate scaling first, then rotations and finally
translations):\par
\noindent\hskip 2in\begintyl{3cm}[2in]
\special{tyl beginfigure T 80 80 0 0 60  "TeXtyl-logo-5"}
     \special{tyl beginfigure "tex-logo"}
	\special{tyl line m 3 2,13; 10,13}
	\special{tyl line m 3 6,13; 6,6}

	\special{tyl line m 3 8,11;8,4}
	\special{tyl line m 3 8,11;12,11}
	\special{tyl line m 3 8,8; 11,8}
	\special{tyl line m 3 8,4;12,4}

	\special{tyl line m 3 13,13;18,6}
	\special{tyl line m 3 13,6;18,13}
    \special{tyl endfigure}
    \special{tyl beginfigure  "tyl-logo"}
	\special{tyl line m 3 20,10;24,10}
	\special{tyl line m 3 22,12;22,6}

	\special{tyl line m 3 25,10;27,6}
	\special{tyl line m 3 29,10;26,2}

	\special{tyl line m 3 31,13;31,6}
    \special{tyl endfigure}
\special{tyl endfigure}\endtyl
\par\filbreak

\section{Others}
We'll finish off this section with a couple more primitives: a simple spline
example, and the primitives for a music-typesetting project underway at Ohio
State University\cite{gourlay}\index{OSU}. The first example is not really that different from our
first spline example, except that in this case, we have a ``closed'' 
spline:\index{splines, closed}\index{closed splines} one whose
 first control-point will coincide with its last control-point.
We can type something that looks like:
\begin{verbatim}
\special{tyl spline m 3 b O 8 (10,9) (4,16) (8,23)
        (11,21) (13,17) (20,16) (22,13) (19,8)}
\end{verbatim}\par
\noindent  The |O| (letter ``Oh'')\index{{\tt O}-marker}
  marker denotes a closed spline\index{closed splines}. The default
option is an ``open'' spline\index{open spline}\index{splines, open},
 and can be marked with a |U|\index{{\tt U}-marker} instead of the
|O| if you wish to be explicit. 
The difference is in the way that \TT
manipulates the control points when doing the interpolation.
 In this example, we used a B-spline, as marked with a
|b|\index{{\tt B}-marker}, and  we listed {\it only\/} the unique 
coordinates to get this nice bean-shape:\par
\noindent\begintyl{3cm}[2in]
\special{tyl spline m 3 b O 8 10,9;4,16;8,23;11,21;13,17;20,16;22,13;19,8}
\endtyl\par

\label{diffsplines}\TT provides three types of spline interpolation which I alluded to on
page~\pageref{thebases}.  The Catmull-Rom basis is probably the most
intuitively useful spline for users. It produces a smooth curve that goes
\index{splines, Catmull-Rom, example}
through the control points (which we can mark with dots):\par
\noindent\hskip 1in\begintyl{1in}[1in]
\special{tyl spline m 2 K X 8 7 5,10; 9,14; 15,7; 22,13;17,14;12,5; 7,0;}
\endtyl\par
The Cardinal basis\index{splines, Cardinal, example} is of the same family
as the Catmull-Rom. It, too, interpolates through the control points, and is
included for convenience and as an alternative to the Catmull-Rom. For
example:\par
\noindent\hskip 1in\begintyl{1in}[1in]
\special{tyl spline m 2 D X 8 7 5,10; 9,14; 15,7; 22,13;17,14;12,5; 7,0;}
\endtyl\par
The B-spline\index{splines, B-spline, example} is a little different in that
the curve {\it approximates\/} the control points. Using the same control points as
the above example, but using the B-spline basis, we see:\par
\noindent\hskip 1in\begintyl{1in}[1in]
\special{tyl spline m 3 B X 8 7 5,10; 9,14; 15,7; 22,13;17,14;12,5; 7,0;}
\endtyl\par
For the most part, you will probably want to draw curves through the control
points that you specify, and so the Catmull-Rom basis is the 
convenient default. The B-spline type is provided for completeness for users
who might have data using that basis.\par

 There {\it are\/} times when the Catmull-Rom or Cardinal bases give flakey
curves and the B-spline basis is not appropriate either. \TT provides a
fourth type of spline for these situations: an interpolating B-spline
curve.\index{splines, Interpolating B-spline, example} It has the advantages
of Catmull-Rom's interpolation, and the special flexibilities of the
B-spline, but is computationally more expensive. See \cite{wu-abel} or \cite{barsky} for a
complete explanation. Here is an example using the same control points as
the above examples, but using the interpolating B-spline:\par
\noindent\hskip 1in\begintyl{1in}[1in]
\special{tyl spline m 3 I X 8 7 5,10; 9,14; 15,7; 22,13;17,14;12,5; 7,0;}
\endtyl\par

For the {\it MusiCopy\/}\index{MusiCopy} project, we have the ability to draw ties and slurs
\index{ties}\index{slurs}---the long arcs connecting groups of notes. For the most part, I assume
that there is a program that is going to take care of the details of knowing where these
graphic elements are to be placed, and will produce the correct |\special|
string for inclusion in the {\tt .tex} file, but I will give an example for
completeness.\filbreak This graceful arc is produced by specifying a minimum and
\index{ties, {\it see also} slurs}\index{slurs, {\it see also} ties}
\index{ties, example} maximum thickness, and the five control points for the shape.\par
\noindent\begintyl{4truecm}[2in]
\special{tyl tieslur m 2 8 5 5,10; 7,13;15,16;24,17; 28,15 }
\endtyl\par\filbreak

\noindent The call looked like\index{tieslur, example}:\par 
|\special{tyl tieslur m 2 8 5 (5,10)(7,13);[15,16];(24,17); 28,15 }| \par 
\noindent where |2| and |8| are the min and\index{tieslur, thicknesses}
max thicknesses at the endpoints and the middle, respectively. The following
|5| is for the number of control points, and the five pairs of integers
following that are the coordinates of the points. We use a special way of
producing a smooth and gradual thin to thick to thin line-thickness, 
but  will discuss it in a later chapter.\index{ties, and ttsplines}\par\filbreak

The last example is the most specialized for the music project: beams\index{beams}. We'll
just look at an example of how they are called and appear, and leave the
details for the next chapter.\par
\noindent\begintyl{3truecm}[2in]
\special{tyl beginfigure "beams" }
	\special{tyl beam m 0 3,20; 15,23 }
	\special{tyl beam m 0 g 3,10;11,7 }
\special{tyl endfigure }\endtyl\par
\noindent The basic order of the parameters looks something like:\par
|\special{tyl beam m 0 g 3,10;11,7 }|\par
\noindent where |0| (zero) is the ``staff-size,''\index{staff-size}
 |g|\index{{\tt G}-marker} indicates a beam size for
``grace'' notes\index{grace-notes} (|r|\index{{\tt R}-marker} 
is the default for ``regular'' sized notes), and the
last two pairs are the coordinates of the line-segment that the beam is to be
centered over.\par

\Makeodd
\chapter{User-Level Details}
\label{user-level}
From the user's point of view\index{user's view} using {\TeX}\index{{\TeX}},
 commands\index{{\TeX} commands}\index{specials} that \TT 
interprets will look like the word ``|tyl|'', followed by
 the name of the graphic to typeset, then a
list of parameters\index{parameters to {\TT}}\index{{\TT}, parameters} 
all enclosed within the curly 
braces of a \hbox{|\special{...}|} command.
This use of a |\special| could be produced
by some other program (a graphic editor, for example),
\index{graphic editors} and the text strings merely
inserted into the {\tt .tex} text-file. \par

As far as the user is concerned, he is pasting in a picture at the current
position\index{current position} on the page where he invokes the |\special|. The user should
think of this picture as being a box just big enough to contain all the
lines of his graphic image, and whose first-quadrant cartesian
 origin is the reference\index{origin of quadrant}\index{reference point}
point that will be placed at the current position on the page. Thus, he
might want to  make sure that there is enough blank space \index{blank space}around the current
position on the page to contain the
image before he tries to ``paste it in.'' Space can be created by using
\TeX's |\hskip| or |\vskip|, or \LaTeX's |\hspace| and |\vspace| commands,
\index{{\TeX}}\index{{\LaTeX}} or hoping for the best with \LaTeX's
|figure| environment \index{{\LaTeX}, {\tt figure } environment} surrounding
the box created by |\begintyl| and |\endtyl|.
\par

The kinds of graphic primitives\index{primitives}\index{capabilities} 
that \TT knows how to typeset are
uniform-thickness line segments, uniform-thickness splines,
uniform-thickness arcs, variable-thickness
splines, music beams, and music ties/slurs.  Line segments are
merely a subset of splines, and so variable-thickness lines are available by
specifying a spline of just two control points with a thickness at one end
point,\index{primitives, built-up}
 and another thickness at the other end point. The feature here is to have 
several primitives available, and allow for other graphic elements
 to be built using them.\par\filbreak

We'll look at the basic syntax for the primitives, and then discuss what
each parameter really means and how to specify what you want.
The parameters\index{primitives, parameters}\label{parameters} for each 
of the graphic types are as follows:  literals are
in a {\btt typewriter} face, any required parameters for the primitive are 
in \mbox{$\langle$ angle $\rangle$} brackets,
 and any {\it optional\/} parameters are within 
\mbox{$\lbrack$ square $\rbrack$}
brackets. Please note that the relative ordering of the parameters
 {\it is\/} important, even
if you do not use any or all optional parameters. Also, it is does not
matter if you use upper- or lower-case letters for the primitives or markers.
\par\filbreak
\medskip
{\btt\char'134 special\char'173 tyl line}
 \Opt{measure}
\Opt{transform} \Prm{thick}\Coma\par
\hfil \Opt{vector}{\leavevmode\hbox{$\>\lbrack${\btt L}$\>\langle style\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}} $ x_{\rm left}\,\Coma\>
y_{\rm bottom}\,\Coma\>
x_{\rm right}\, \Coma\> y_{\rm top}${\btt\char'175} \par

\noindent draws a line\index{{\bf line}} segment\index{line segments}
 from the point $\left( x_{\rm left}\, , \; y_{\rm
bottom}\right)$ to the point
$\left( x_{\rm right}\, ,\; y_{\rm top}\right)$ using a line of
thickness\index{line thickness}
\Prm{thick}.\par\filbreak

\medskip
{\btt\char'134 special\char'173 tyl spline}
 \Opt{measure}\Opt{transform}\Prm{thick}\Coma\par
\hfil \Opt{vector}
{\leavevmode\hbox{$\>\lbrack${\btt L}$\>\langle style\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}}
\Opt{s-type}\Opt{closure}\par
\hfil{\leavevmode\hbox{$\>\lbrack${\btt X}$\>\langle dotsize\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}}
\Prm{numpts}\Coma $x_1\, \Coma\> y_1\, \Coma\> \ldots\>\Coma\>
 x_{\rm numpts}\, \Coma\> y_{\rm numpts}$ {\btt \char'175} \par

\noindent draws a smooth spline\index{{\bf spline}} curve through the integer points
 $x_1\, , \; y_1 ,\; \ldots$ \linebreak[4]
 $\; x_{\rm numpts}\, ,\; y_{\rm numpts}$
using a line of thickness \Prm{thick}. If the optional {\btt X} marker
\index{{\tt X}-marker} is specified, dots of diameter \Prm{dotsize} are
placed to mark the positon of the control points specified. This 
may be useful for checking your data.\par\filbreak

\medskip
{\btt\char'134 special\char'173 tyl ttspline} \Opt{measure}
\Opt{transform}\par
\hfil \Opt{vector}\Opt{s-type}\Opt{closure}
{\leavevmode\hbox{$\>\lbrack${\btt L}$\>\langle style\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}} \par
\hfil{\leavevmode\hbox{$\>\lbrack${\btt X}$\>\langle dotsize\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}}
\Prm{numpts}\Coma
$x_1\, \Coma\> y_1\, \Coma\>\ldots\>\Coma\>
x_{\rm numpts}\,\Coma\> y_{\rm numpts}\,\Coma\>$\par
\hfil $thick_1\, \Coma\>\ldots\>
\Coma\> thick_{\rm numpts}$ {\btt \char'175} \par

\noindent draws a smooth spline through the integer points $x_1 , \; y_1 ,\;
\ldots$ using a\index{{\bf ttspline}}
line of varying thickness defined by $thick_i$ at each control point\index{ttspline, thicknesses} 
$\left( x_i,\; y_i\right)$ (ergo {\underbar t}hick-{\underbar t}hin 
splines). The {\btt X} marker is also available for marking the positions
of the specified control points. \par\filbreak

\medskip
{\btt\char'134 special\char'173 tyl arc} \Opt{measure}
\Opt{transform} \Prm{thick}\Coma\par
\hfil \Opt{vector}
{\leavevmode\hbox{$\>\lbrack${\btt L}$\>\langle style\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}}\Prm{radius}\Coma
{\leavevmode\hbox{$\>\lbrack${\btt @}$\>\langle cent_x\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\langle cent_y\rangle\, 
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}}\par
\hfil\Prm{$angle_1$}\Coma \Prm{$angle_2$}{\btt \char'175} \par

\noindent draws an arc\index{{\bf arc}} of radius \Prm{arc-radius} going counter-clockwise
starting from \Prm{$angle_1$} degrees from zero, and \index{arcs, angles}
finishing at \Prm{$angle_2$} degrees around from zero. If the center point is not specified with 
the {\btt @} marker\index{{\tt @}-marker}, the arc is assumed to be centered
at $(0,\, 0)$.\index{arcs, centering}
 Ellipses\index{ellipses} can be achieved by a simple scaling
 of a closed arc\index{oval, {\it see} ellipse}
since scaling and rotational transformations
 are about the {\it center\/} of the primitive.\par\filbreak

\medskip
{\btt\char'134 special\char'173 tyl label} \Opt{measure}
\Prm{face}\Coma $\;x\, \Coma\> y$\Coma {\btt "}\Prm{string}{\btt "}
{\btt\char'175}\par

\noindent places a simple label\index{{\bf label}} at $(x,\, y)$ using
 a font style\index{labels, font style}\index{labels, face} of 
\Prm{face} (currently selectable by an integer: e.g.,
 |1| is amtt10. See page~\pageref{labelfonts} for a better list).
\Prm{String} is a simple sequence of letters and spaces contained 
within matching double quotes ({\btt "}).\index{{\tt "}-marker}
Here, the case of the letters of \Prm{string} is taken  verbatim,
and it is {\it not}
interpreted;  {\TeX} macros or typesetting commands are not 
usable here.\index{labels, strings} If you want to typeset fancier
labels, \TT is too late in the game.\par\filbreak

The optional parameter 
\Prm{measure}\index{measurement}\index{units of measure} is any 
of {\btt S}\index{{\tt S}-measure},
 {\btt P}\index{{\tt P}-measure}, 
or {\btt M}\index{{\tt M}-measure} 
denoting that the integer
points, like $x_1,\; y_1,\;\ldots $ are measured in
scaled-points,\index{scaled points}
printer's-points\index{printer's points}, or millimeters\index{millimeters}
respectively. If none is specified, the measurement
of\index{measurement, default}
printer's-points is assumed. Just to refresh how big each of those units is:
\begin{itemize}
\item there are 72.27 printer's points {\it (pp)\/} per inch
\item and 65536 scaled-points {\it (sp)\/} per printer's point
\item and 25.4 millimeters {\it (mm)\/} per inch
\end{itemize}\par
  Also remember that the coordinates for the above
control points (like $x_{left}$ or $x_i$) are in {\it first quadrant} 
cartesian coordinate-space\index{coordinate space system}. It is useful not to have to remember some
other coordinate systems, and makes things easier for
the user and user programs to interact with \TTN, which takes care
of such details.\par\filbreak

\Prm{Thick} is the pixel-thickness\index{line thickness}
\index{pixel thickness} of the vector font\index{vector font} to use. Currently
the range is from about 1 to 12 pixels thick (we'll talk more about these 
sizes later). Here are some examples of lines having from 2 to 10 ``pixels''
 in even thicknesses.\index{line thickness, example}\par
\noindent\hskip 1in\begintyl{3truecm}[1in]
\special{tyl beg}
\special{tyl line m 2 2 4 11 26}
\special{tyl line m 4 12 23 15 10}
\special{tyl line m 6 15 20 25 13}
\special{tyl line m 8 26 9 31 23}
\special{tyl line m 10 33 2 33 16} 
\special{tyl end}\endtyl
\par\filbreak
 \Prm{Vector} refers to the {\it
type\/} of vector\index{vector-types}\index{pens} to use,
 namely {\btt C}\index{{\tt C}-marker} for vectors that look as if they are
 drawn with a {\it circular\/} ``pen,''\index{circular pen}
 {\btt H}\index{{\tt H}-marker} for a {\it horizontal\/}
pen,\index{horizontal pen}
 and {\btt V}\index{{\tt V}-marker} for 
{\it vertical\/} pen appearance\index{vertical pen}.
 A circular pen vector-type is the default\index{vector-types, default}. See also 
section~\ref{vect-pens} for examples and a better description.\par\filbreak

\Prm{Style} \index{line style}\index{{\tt L}-marker}is the
 line-style to use when drawing. Currently, \TT is able to 
provide solid (style |0|), dotted (style |1|), dashed (|2|), and dot-dashed (|3|)
line-styles.\index{line style, dotted}\index{line style, dashed}
\index{line style, solid}\index{line style, dot-dashed} The solid line-style is 
the default. Here are some simple examples of the styles:\index{line styles, examples}\par
\begintyl{3truecm}[1in]
\special{tyl beg}
\special{tyl line m 2 L 0 (2 4 11 26)}
\special{tyl line m 2 L 1 (12 23 15 10)}
\special{tyl line m 2 L 2 (15 20 25 13)}
\special{tyl line m 2 L 3 (26 9 31 23)}
\special{tyl end}\endtyl
\par\filbreak

\Prm{S-type} is the kind of spline-basis\index{splines, types}\index{splines, basis} 
to use when interpolating the spline
through the control points. Currently, {\btt B}\index{{\tt B}-marker}
 indicates the {\underbar b}-spline basis\index{B-spline basis}
(which interpolates a spline within the convex hull of the control points),
{\btt I}\index{{\tt I}-marker} indicates an
 {\underbar i}nterpolating B-spline\index{interpolating B-spline, basis} (goes through the points
specified), {\btt D}\index{{\tt D}-marker} for the Cardinal
basis,\index{Cardinal basis}
and {\btt K}\index{{\tt K}-marker} which 
indicates the Catmull-Rom basis\index{Catmull-Rom basis} (which also
 interpolates a spline {\it through\/} the control points). The
Catmull basis is the default\index{splines, default basis} spline type in the current 
implementation.\par\filbreak

\Prm{Closure}\index{closure}\index{splines, closure} is used to
indicate whether the spline is a closed \index{closed splines}
curve (the endpoints overlap), or an open curve\index{open spline} (the
default)\index{splines, default closure}. We use 
the iconography of {\btt O}\index{{\tt O}-marker} for a closed curve,
 and {\btt U}\index{{\tt U}-marker} for an 
open-ended curve.\par\filbreak

Now we come to describe what \Prm{transform} is all about. \TT
allows the user to modify the coordinates of the control points without
having to re-calculate their new positions by himself.
\index{design decisions}I tried to make the specification and modification
of {\it \TeX tyl's\/} primitives as painless and intuitive\index{user intuition} as possible. We
usually think more in terms of connecting dots and placing graphic elements,
 and not in terms of slopes, tangents and velocites which are messy at best,
and get more cumbersome from there.\par\filbreak

Geometric transforms\index{transformations, {\it see } transforms}
\index{geometric transforms} like scaling 
(independently in the $X$ and $Y$ directions), rotating about the ``center''
of the graphic object (a primitive or a figure), and translating in the $X$ and $Y$ directions are 
available for most of the primitives. The 
format\index{{\bf transform}} for specifying some transformation on 
the currently-specified points\index{transforms, parameters, format}
is:\par
\qquad{\btt T}\Coma\Prm{Sx}\Coma\Prm{Sy}\Coma\Prm{Tx}\Coma\Prm{Ty}\Coma\Prm{Rot}\Coma\par
\noindent where \Prm{Tx} and \Prm{Ty} are translations of the object in
 the $X$ and $Y$ direction by some signed distance according to the 
current units of \Prm{measure}. \Prm{Rot} is a signed integer angle (in
degrees) by which
to rotate the primitive or figure counter-clockwise about its center.
  \Prm{Sx} and \Prm{Sy} are\index{transforms, parameters}
{\it integer\/} scale parameters representing the {\it floating-point\/} values of the 
transform multiplied by 100 and truncated.
To obtain any transform, {\it all\/} the transform parameters must be
specified\index{transforms, parameters, requirement}.\par\filbreak

Two other special types of graphics capabilities are meant to be utilized 
 by a
knowledgeable program, such as the music-typesetting\index{music} system being written at 
the Ohio State University. These are:\par
\medskip
{\btt\char'134 special\char'173 tyl tieslur} \Opt{measure}
 \Prm{minthick}\Coma \Prm{maxthick}\Coma\par
\hfil \Prm{numpts}\Coma
$ x_1\, \Coma\> y_1\, \Coma\>\ldots\>\Coma\>
x_{\rm numpts}\,\Coma\> y_{\rm numpts}${\btt\char'175}\par
 
\noindent which draws a smooth spline curve through the
 points\index{{\bf tieslur}}\index{slurs}\index{ties}
$\left(x_i,\;y_i\right)$,
and uses a built-in algorithm to figure out the correct thicknesses of the
tie/slur between \Prm{minthick} and \Prm{maxthick}. These control points 
 are  also in first quadrant cartesian coordinates, and a circular-pen
vector-type is used to draw the 
spline.\index{tieslur, pen type}\index{tieslur, thicknesses}\index{tieslur,
vector type}\par\filbreak

\medskip
{\btt\char'134 special\char'173 tyl beam} \Opt{measure} \Prm{staffsize}\Coma
\Opt{beamtype}\par
\hfil $x_1\, \Coma\> y_1\, \Coma\> x_2\, \Coma\> y_2${\btt\char'175} \par

\noindent draws a music beam\index{{\bf beam}} from $\left(x_1,\;y_1\right)$ to
  $\left(x_2,\;y_2\right)$ (also in first quadrant space)
using a beam of \Prm{beamtype}\index{beam-types}
 {\btt G}\index{{\tt G}-marker} for a {\it grace\/}-note sized
beam,\index{beams, sizes}
 or {\btt R}\index{{\tt R}-marker}\index{beams, default size} (the default) for 
{\it regular} sized beams in the specified
staff-size\index{beams, staff size}.
 For a description of staff sizes, see \cite{ross}.\par\filbreak

Finally, there are two more |\special|s that \TT can
understand. These are used to group any of the above graphic primitives together
into a ``symbol.''\index{symbol, {\it see} figure}  The commands are:\par
\medskip
{\btt\char'134 special\char'173 tyl beginfigure} \Opt{measure} 
\Opt{transform}\par
\hfil{\leavevmode\hbox{$\>\lbrack${\btt W}$\>\langle width\/\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\langle height\rangle\,\rbrack\,$}}
{\leavevmode\hbox{$\>\lbrack${\btt F}$\>\langle width\/\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\langle height\rangle\,\rbrack\,$}}
{\btt\char'175}\par
\noindent which opens a level of definition\index{{\bf beginfigure}},
and\par
\medskip
{\btt\char'134 special\char'173 tyl endfigure}{\btt\char'175}\par
\noindent which closes that level of definition\index{{\bf endfigure}}. These are analagous to 
{\it push} and {\it pop} kinds of operations, with many levels of
recursive definition available. The optional {\btt F} 
marker\index{{\tt F}-marker} specifies the final optimal
 width and height of the figure,\index{figures, fitting to size}
in terms of units of \Prm{measure}. This is useful for fitting a figure to a
specific size, so that you do not have to compute the scaling parameters
by yourself. This ability is often desireable if the figure was created by
some program that output the figure at a different scaling factor than you
require on the page. The {\btt W} marker\index{{\tt W}-marker} indicates the
width and height of the figure at the size that it was originally written,
which we assume the figure-making program output along with the definition
of the figure elements.\index{programs making figures}\index{graphic editors}
 For most
 practical purposes, you can let \TT\ 
compute the size of the figure as it was originally created, and then let it
fit the figure to the sizes requested by the {\btt F} marker.\par

Besides the implicit transform parameters created by using the {\btt F}
and/or {\btt W} markers, an explicit figure-level 
tranformations\index{tranforms, figure-level}\index{figures, tranforms}
can be specified using the \Prm{transform} capability using units of
\Prm{measure} (or the default units of printer's
points).\index{measurement,default}
 Also, any transforms applied at a level of
definition are additive\index{transforms, additiveness}
over the lower-level definitions\index{figure definitions} and any
transformations that they may have 
locally\index{figures, transforms}.\par\filbreak
%\vskip 10pt
%If this were the {\TeX book}, this paragraph would have three ``dangerous
%bend'' signs in front. \TT currently has a temporary
% ability to alter certain internal global
%variables from the |\special| level. This is meant mostly for debugging,
%hacking, and generally limited use. You are on your own with these, and
% I would discourage much use of it (since it may disappear soon).
% The basic call is\par
%{\btt\char'134 special\char'173 tyl param} \Prm{param-num} \Prm{value}{\btt\char'175}\par
%\noindent where \Prm{param-num} is currently one of\index{{\bf param}}
%\begin{itemize}
%\item {\tt 1}: for changing the current minimum number of intervals per
%spline span
%\item {\tt 2}: for changing the minimum number of intervals per arc
%spline-span
%\item {\tt 3}: for debugging the tie/slur clamping mechanism (skip it or not).
%\end{itemize}
% and \Prm{value} is the new value. For example,
%\begin{verbatim}
%  \special{tyl param 1  4}
%  \special{tyl param 3 = -1}
%\end{verbatim}
%the first sets the minimum number of intervals per spline span to $4$, and the
%second call says to {\it not\/} skip the clamping mechanism (the |=| sign 
%is optional, of course). Once these
%variables are set, they are in effect for the rest of the document, or until
%changed with a matching |\special{tyl param...| invocation.
%See later chapters to understand these terms.\par

\Makeodd
\chapter{When Things Go Wrong}
Despite the best of examples and directions about careful typing of
\hbox{|\special|} strings, there are times when \TT will
get upset and complain about some situation or input. Fortunately, \TT can
continue from most of them (like missing or incorrect parameters), and 
just report them in the |.tlog| log-file\index{{\tt .tlog}
file}\index{{\TT}, {\tt .tlog} log-file}
for you.\index{{\TT}, error handling} An example run of \TT might look
like:\filbreak
\begin{verbatim}
  >textyl
  This is TeXtyl, version ...
   DVI-input File Name: myfile.dvi
   DVI-output File Name :
  (different than input name)[default of myfile.tyl]
   [1] [?2]
  Output written on myfile.tyl
  Log written on myfile.tlog
  Some error(s) occurred. Please check Logfile for details.
  Assume that the outputfile is incorrect
\end{verbatim}\filbreak
Rather than annoy you at the terminal with long error messages, \TT puts a 
|?|\index{{\tt ?} flag} mark to indicate that some error happened. Since it wrote the 
|.tyl|\index{{\tt .tyl} file} output file, \TT must have recovered\index{{\TT}, error recovering}
well enough to finish its job,
but the output probably does not look right. The |.tlog| file might look
like\filbreak
\begin{verbatim}
This is TeXtyl, Version blah...
Reading File: myfile.dvi
 [1] [
Error in fig# 1 on page 2
Arc Thickness not found. Setting to 1
2]
Output written on myfile.tyl
Log written on myfile.tlog
\end{verbatim}\filbreak
\noindent which was just a missing parameter to the |\special{tyl arc ...}| string.
You will  have to re-edit the file and insert the correct thickness.
\index{{\TT}, error messages}
All the error messages that are written to the |.tlog| file try to pin down
the error to the figure number on the error-containing page. These
references to the position of the error
come from the $n^{\rm th}$ figure on the page (the $n$ count is relative to
each page, and starts from 1), and the page number is from {\TeX}'s
|\count0| register that enumerates pages.
 Sometimes \TT
cannot always determine the exact figure on the page
(e.g., if we forget to close a figure definition with an
|endfigure|), and so estimates at least the bad page in question. For the most
part, the error is a just missing parameter,
 or a bad parameter to a |\special| string being read by \TTN.\par\filbreak

 However, there are a larger number of errors that \TT
found ``surprising'' \index{errors, internal}\index{surprise errors}
and so marks these errors on your screen as |?! |.\index{{\tt ?!} flag} Most
of these internal errors are based on the functionality of {\DVI}type 
concerning {\smallrm TFM} information, and the structure and commands
of the {\DVI} file being read. \TTN, like {\DVI}type, will complain, and 
possibly roll over and die gracefully.\par\filbreak

The other ``surprising''  errors that \TT might complain about are really
internal to \TTN, and constitute a bug,\index{{\TT}, simple problem} or just a
compile-time constant that is too small. These easily-fixed surprises are
\begin{itemize}
\item |too many dvistrings|. This page required more {\DVI} bytes than usual.
 Have your local maintainer\index{local
maintainer} increase the size of the internal buffer used for storing a
page's {\DVI} bytes.
\item |too many spline segments required|.  The spline you tried to set might
be too large/long for the space allocated for a spline's description.
That size is also a compile-time constant. \TT
will reduce the number of control points that it interpolates so that you
can at least get the output, and so that it does not die ungracefully.
\item |figure definition not closed at end of page|. You forgot a
|\special{tyl endfigure}| command in some figure definition on the page. \TT
will not typeset that figure, and will go on to the next page.
\end{itemize}\par\filbreak
There are also some down-deep errors that could potentially (although
doubtfully) show up. These
are probably some error in the vector fonts being referenced by
\TTN.\index{{\TT}, serious problems}
\begin{itemize}
\item |min radius of vector font is zero|. The referenced vector font's
{\smallrm TFM} information reported that the font's radius size
is smaller than it was designed to be.
 \TT will make a temporary fix so that it can
continue, but the output figure will be wrong. Have the local maintainer
re-check the vector fonts.
\item |bad dydx|. This is a rare problem. Somewhere, the code to typeset a
diagonal line segment referenced an impossible $dy/dx$ combination, and cannot find
any vector character to fit. \TT will continue, but you may see a
tiny glitch in your figure.
\item |dx is too big/small|, |dy is too big/small|. This is a problem. For
some reason, a distance was referenced that is out of the range of the 
32-bit representation of integers. This really should never happen.
\end{itemize}

For the most part, \TT can recover from errors that it encounters, and give
a brief summary in the |.tlog| file. Other errors have to do with {\smallrm
TFM} file information, and are outside the scope of \TT to handle
gracefully. The most serious ``surprise'' errors are bugs, and you should
report them directly to me with a copy of the |.tex| file, or at least a
detailed printout from {\DVI}type of the |.dvi| file processed by \TTN.\par

\Makeodd
\chapter{Design Details}
 The top-level of \TT is taken directly from the
 {\DVI}type\cite{dvitype}\index{DVItype}
 program, with a few
modifications. Most of the diagnostic functionality of {\DVI}type is
maintained, but without the user interface (\TT assumes it is supposed to 
process all the pages).
  A ``hook'' was inserted into
the program to handle the {\TeX}
|\special|s\index{handling specials}\index{specials, handling by {\TT}} 
that \TT understands
(hereafter, ``special'' will refer only to those commands that 
\TT  understands---other |\special|s are ignored, and simply output 
to the {\DVI} file without\index{specials}
modification).\index{DVI file}
  The {\DVI}type code was used  mostly for its keeping\index{DVI
position coordinates}
track of the current {\DVI}\  {\bf h} and {\bf v} position coordinates
on a page, and handling {\smallrm TFM} information\index{TFM information}.\par

Basically, as \TT slurps in a {\DVI} file, it processes 
``normal'' commands
in a normal way (i.e., just keeping track of positions and counters).
 When it reads a |\special| string, it tries to interpret the parameters
and expand the special, producing 
 commands to typeset the graphic using characters from special fonts.

The result is a transformed {\DVI} file that now contains
``normal'' (i.e., non-special, `put-that-character-there') dvi-commands
as far as \TT can tell, after taking care of new font definitions
and doing any bookkeeping of counters and internal references.\par

\section{Vectors}
\label{vectors}
Several design decisions\index{design decisions} were made to give \TT  the ability to
typeset the graphics of the complexity that we desire. This ability is
intrinsically bound to the fonts to be used, and the way that we use them.
For this project, I had to create a font of short, oriented line segments\index{vector font}.
This was to minimize the amount of information required to typeset a
curve. One could address each pixel of the virtual device to draw the graphic
(putting hundreds of periods from a font), but that is not
device-independent, and the
amount of data is huge in comparison to using line segments.
 These line
segments can be connected together rather smoothly to give the appearance of
a continuous line segment or curve.\par
 Using this scheme, described by Nelson
and Saxe\index{Nelson{,} Bruce}\index{Saxe{,} James}
 at Carnegie-Mellon University\cite{nelson-saxe}, I am able to typeset the correct
character corresponding to the desired length and angle. I modified their
font those
angles cover the first and fourth cartesian quadrant system,
\index{vector font, range of angles}
and whose vectors are from the origin to points clockwise along the perimeters
of semisquares of decreasing radii\label{semisquare}. They use this scheme in order to use the
longest vectors\index{vector font}\index{vectors, typesetting with}
 possible for a given distance (thus minimizing the number of
characters to typeset), and also have shorter vectors for use in tightly
curving lines. They use a semisquare (rather than a semicircle)
 for a quick line-tangent intersection test in their algorithm to decide the maximum
length vector to use that has a satisfactory variance from the tangent to the
line.
I really must give correct thanks to Dario Giuse\index{Giuse{,} Dario}
 at C-MU\cite{dario} for first
implementing the vector-font typesetting code that I subsequently modified
for \TTN.\par

 I modified the  vector font for use with
Metafont~79\cite{knuth-mf}, and was able to describe it 
in a device-independent manner. Because of the limitations
of\index{Metafont, limitations}
Metafont~79's\index{Metafont}\index{vector font, dimensions}
and {\TeX}'s representation of character heights and depths, I could not accurately
describe the character dimensions in such a way that I could leave the
low-level typesetting details to {\TeX} 
through its idea of {\smallrm TFM} information. Thus, \TT has to take
care of the details of calculating the correct dimensions for each character
of each vector font. This calculation is done,
 however, only as a particular font is first
required, and the dimensions\index{vector font, computing dimensions}
 are computed on-the-fly using the group of
parameters found in the {\smallrm TFM} file that we have defined for our own
use. After this initial parameter calculation, subsequent references to that
font's {\smallrm TFM} information is accessible via a caching scheme.
 The fonts contain such information as the measure of the maximum-length
vector of the font, and the height and width of the pen used to draw the
font ({\it all in scaled points}). \par

Current plans for the vector fonts are for sizes in the range from about 1
to 12 ``pixels'' for each of the three types of Metafont pens (circular,
flat horizontal, and flat vertical).\index{vector font, sizes}\index{vector
font, types} The fonts are
actually device-independent in size, as our ``pixel'' is measured in
absolute units of 16384 $(2^{14})$ 
scaled-points\index{vector font, pixelsize}. However, there is a step within
Metafont~79 that insures that the vector size is an odd-number of
physical pixels computed at the final output-resolution. This is to avoid
some discretization errors and the accompanying aliasing artifacts.
 I expect the vectors drawn \index{vector font, pen-types}
with circular pens (the ``cvec'' fonts)\index{vector font, cvec} to be the 
most utilized.  Their
endpoints are rounded and are positioned to coincide
 so that the segments overlap slightly and
meet up gracefully producing a smoother curve.  Here are some examples of
circular, horizontal, and vertical pens that can be used for 
different effects:\label{vect-pens}\index{vector font, pens, example}\par 
\noindent\hskip 1in\begintyl{35mm}[1in]
\special{tyl beginfigure} 
\special{tyl line m 10  c 5 5 10 30}
\special{tyl line m 10  h 15 5 27 30}
\special{tyl line m 10  v 30 15 45 23}
\special{tyl endfigure}
\endtyl\par 

\medskip
{\bf Beams}\par
A similar scheme is used for the beam characters found within the music
fonts\index{beam font}\index{music font}.  The beam characters are in two types
 (those for grace notes, and\index{beam font, types}
those for regular notes) for the staff sizes\index{staff sizes} of music (numbered 0
down to 8). See also \cite{ross}.\index{beam font, sizes}\label{beam-chars-sizes}
 The font is also a set of short line-segments that will be
connected to create a beam (some other program will have to know about the
details of describing how to attach stems from the beams down to the notes).
However, the beam characters are different\index{beam font, difference from vector font} from the vector fonts in that
each staff size of music has one particular size of beam
characters\index{beam font, relation to staff size}
associated with it.\par

 The beams are designed\index{beam font, design} to appear as if they are drawn
with a flat-edged pen held perpendicular to a ruler (at all orientations).
When a vertical pen is drawn along a path, the actual cross sectional
distance of the line segment decreases with the angle (i.e., it is thickest
when drawn along a line at zero degrees from the horizontal, and thinnest as
it is drawn along a line approaching $\pm 90$ degrees). The way to maintain
the appearance of consistent thickness of the line segments at all drawn
angles is to actually {\it increase\/} the ``height'' of the vertical pen as
a function of the angle from the horizontal. This function was geometrically
derived to be the {\it secant\/} of the angle, which yielded in a scaling
factor to apply to the original definition of the vertical pen's height.\par

Another difference from the vector fonts is that the beam characters do not
have to cover as large a angular range. The angles from the horizontal are
less than 45 degrees on the average,\index{beam font, range of angles}
 and the lengths of the beam characters\label{beamsizes}
are no smaller than the width of a quarter note for that staff size. The
current implementation defines the beam characters in four groups per staff
size: regular beams in lengths\index{beam font, lengths}
 of 1.0 and 1.5 quarter-note-lengths, and
grace-note beams in lengths of 0.5 and 0.66 grace-note-lengths.\par

 The scheme
of typesetting is similar to that of the vectors, but an added constraint is
resolved. Since the beam characters use a slightly smaller set of fixed angles from
the horizontal,\index{beam font, constraints}
we have to choose the best beam character to use such that we use
the maximum length beam character {\it and\/}  try to obtain the least
deviation from the angle requested to fit the beam font.
  The dimensions of these beam characters
are computed only as each music font is required, and a caching scheme
is maintained to avoid unnecessary re-loading of font information and
subsequent definition in the {\DVI} file.  \par

\section{Splines}
\label{splines}\index{splines, families}A second decision\index{design decisions} that I made
 for the current implementation of this system
was to use Catmull-Rom\cite{cagd} splines as the default instead of B-splines.\index{splines, default type} The
reasons for this are two-fold: (1) Catmull-Rom splines\index{Catmull-Rom splines} are of the same
family as B-splines, but are {\it guaranteed} to produce a smooth curve {\it
through} the control points, whereas B-splines only approximate within the
convex-hull described by the control points.  Therefore, Catmull-Rom splines
are a true interpolant; and (2) when dealing with the ties and slurs,\index{ties}\index{slurs} the
user wants the curve to go through the five points that he specifies (left,
middle and right points). With B-splines, he would have to {\it estimate}
the position of the middle control points in order to get the curve  to be
in the correct position.  Catmull-Rom  and Cardinal splines are just
as easy to calculate, and usually achieve the effects that we need.\par

I have also experimented with operations on the B-splines to achieve true
interpolation. This method was described by Barsky and Greenberg\cite{barsky}
 describing how to re-compute B-spline control-points
so\index{B-splines, recomputing points}
that the resulting spline would interpolate through desired points (inverse
interpolation)\index{splines, inversion}\index{splines, interpolation}.
 It actually does not require very hairy mathematics. 
Arcs and circles are implemented\index{arcs, representation}
 using this spline primitive. The arc\index{arcs, control points}
control-points are computed (or pre-computed in the case of circles,
\index{circles, control points} and\index{circles, representation}
ellipses\index{ellipses} which are just scaled circles) 
and then are used in the inversion
procedure so that the resulting B-spline passes smoothly {\it through\/}
those original points. We will later describe further this usefulness of
implementing various graphic objects using lower-level primitives.\par

I also use the Catmull-Rom interpolation when computing the different
thick\-nes\-ses\index{line thickness} along both the tie/slurs and the var\-iable-thick\-ness splines
(``ttsplines'')\index{ttspline}\index{ttspline, line thicknesses}.
 I need to interpolate from the current control-point's
thickness along the curve to the next control-point's thickness, and can do
this smoothly by using the interpolation methods available when computing
the splines anyway.\par

Since we have the ability to draw splines of varying thickness, we can
easily implement ties and slurs\index{slurs} (those long
 arcs connecting groups of notes\index{tieslur, implementation}
on a musical score), since they are splines of usually five control points,
having the specified {\it minthick\/} thickness at the left and right, and
{\it maxthick\/} thickness in the middle. \par

\Makeodd
\chapter{The Implementation}
\section{Overview}
\TT is currently nearly 9000 lines of Pascal code (not {\smallrm WEB}). It is
a prototype, and {\it not} a product.
Testing was simplified by the ability to pre-view\index{DVI file, previewing} the contents of the
{\DVI} file on Sun workstations using the {\smallrm DVISUN}
\index{DVISUN}\cite{dvisun} program. It was written using
Berkeley Unix\footnote{Unix is a trademark of Bell Laboratories}\index{Unix} 
 Pascal\index{Pascal}, but is not dependent on that operating system 
except for
differences in I/O. There are also differences in
efficiency/ease of reading from files---{\tt read}s versus {\tt get}s.  I/O
routines for both byte types (signed and unsigned)
 are written and available, and have been set up
for easy porting to other machines.\par

The idea for handling {\DVI} files is to read each byte
into a buffer until we read an {\tt eop} (end-of-page marker), when we will
write that buffer out into a file, and start a  fresh buffer with the next
page. If we encounter a |\special| in our reading, we treat it as a
\index{specials, handling}\index{macro-expansion}
macro-expansion---substituting {\it our} byte-string for the byte-string
that represented the invoked special, and put this ``tyled''\index{tyling} string into the
buffer for subsequent output.  A nice feature of this slurping is the parser
for the specials. It is simple and extensible enough to easily accommodate
new \TT primitives, and different or additional parameters.\par

Besides being careful about the expansion of the |\special| string, \TT
has to keep track of any newly-defined fonts for insertion into the
{\tt postamble} in the  {\DVI} file, and do some bookkeeping for
{\tt bop} backpointers, and file byte-length.\par

Most of this chapter discusses the
algorithms and data-structures of \TT at various levels. 
We'll start with the high-level and user concepts, and work our way down
into the details of outputting the actual bytes into the {\tt .dvi} file.\par

\section{Primitives}
The user's interface to \TT is through |.tex| text files.\index{{\tt .tex}
text file}
He types in the |\special| strings for {\TeX},\index{{\TeX}} 
and fills in the name of the primitive to typeset
and any parameters to modify the attributes of the
primitive. This |.tex| file is converted by {\TeX} into a |.dvi| file which
is then given to \TTN.
\index{primitives, modifying attributes}
For the most part, all of the graphic primitives\index{primitives}
 in \TT have common attributes
of\index{primitives, attributes}\label{prims-attribs}
\begin{itemize}
\item  bounding-box\index{bounding box},
\item line thickness,
\item pen-type (see section~\ref{vect-pens}),
\item line style\index{line style}
\end{itemize}
that describe basic appearances of an item. A ``bounding-box''
\index{bounding box} describes the
minimum and maximum $X$ and $Y$ values of a minimum-sized
orthogonal rectangle that encloses the primitive.
I'll describe the primitives and
point out their additional or modified attributes to those above. My plan
was to provide a number of primitives that were conceptually built upon
lower-level primitives, and share similar representations wherever possible.
For example, a |tieslur| is clearly built upon the representation\index{tieslur, representation} of a
spline primitive. With this concept, I was able to represent the following
primitives and effectively ``draw'' them by reducing to easier primitives,
\index{primitives, reduction of} down to the vector-font level.\par\filbreak
\medskip
\noindent{\bf Line}\par
The most basic primitive is the |line|, as all other non-figure 
primitives\index{line segments}\index{{\tt line}}
reduce to the same routines that produce line-segments. A line has
 attributes of bottom-left and upper-right endpoints,
and is drawn from left to right in {\DVI}-space, which is similar to
fourth-quadrant cartesian space, but $y$-values are positive-increasing going down the
y-axis\index{DVI-space}. In section~\ref{vect-setting} I will describe how the line is
``drawn'' on the virtual page using the vector-font characters.\par
\medskip
\noindent{\bf Spline}\par
The spline primitives (|spline| and |ttspline|) have the attributes of a
\index{splines, attributes}
line, and in addition:\index{{\tt spline}}\index{{\tt ttspline}}
\begin{itemize}
\item spline type (see section~\ref{splines}),
\item openness, 
\item a count, and a list of control-points.
\end{itemize}
The spline primitives all use the same basic algorithm for interpolation of
its control-points (``knots'') using one of three spline bases: the B-spline
basis, the Cardinal basis, and the Catmull-Rom basis. The difference is mainly
in the choice of basis matrix.\index{splines, basis}\index{splines, B-spline}
\index{splines, Catmull-Rom}\index{splines, Cardinal}\par

|Ttspline|s have an additional attribute that describes the thickness of the
spline at each control point. \TT uses the same method of
spline\index{{\tt ttspline}}
interpolation for computing the varying thicknesses over the length of the
spline as for computing the position of the line-segment positions over the
spline.\par
\medskip
\noindent{\bf Ties}\par
A |tieslur|\index{{\tt tieslur}} is just a subset of 
ttsplines\index{tieslur, relation to ttsplines}. It has exactly $5$
control-points,\index{tieslur, attributes}
which is sufficient to describe even the longest slur. It needs two
specified line thicknesses: (1) a minimum thickness value at the far end points,
and (2) a maximum thickness in the middle of the slur. \TT uses an internal
algorithm to figure the other thicknesses of the control points. This then
reduces to a ttspline of five control points for interpolation. The only
other difference from a |ttspline| is in the 
``clamping'' mechanism\index{splines, clamping}\index{clamping}\index{ttspline, clamping}\index{tieslur, clamping}.
 Let me explain: optimally, we would like the smoothest possible transitions
of line thicknesses along a varying thickness spline, but this is still
subject to the aliasing artifacts
(``stair-steps'',\ ``jaggies'')\index{jaggies} of the printing device's
resolution (you can't have 3.3 pixels in black and white).  We could have a
vector font for every possible pixel-size of the printer, and thus be able
to achieve as smooth a line as the printer is capable. This could easily
require the printer to use dozens of different fonts per page (imagine a
page of math, text, and a complex figure) which most printers' limited font
memories\index{output device, font memory} cannot handle\par
We are faced with either not being able to  print the page (sort of
defeating the whole purpose), or to reduce the number of fonts required to
set that particular figure. This reduction is called ``clamping.'' We make
sure that a requested vector size is in a pre-selected set of fonts, and
then modify that size if it is not in that set. Usually this involves just
adding/subtracting a vector-pixel unit and iterating again through the test-modify
loop until the size fits.\par

Ties and slurs use the same basic clamping mechanism as |ttspline|s
(described above), but also have a built-in way to select and compute the
thicknesses along the length of the spline. This means that \TT decides the
 thicknesses for the tie/slur using its own algorithm based on the user
specifying the maximum and minimum thicknesses.\par

\medskip
\noindent{\bf Arcs}\par
|Arc|s \index{{\tt arc}} are described\index{arcs, attributes} in terms of a radius, an initial and
final angle, and an optional  center coordinate. Internally, this is
transformed into a uniform-thickness spline.\index{arcs, representation}
  Closed circles are a special
case\index{circles} of arcs,\index{circles, relation to arcs}
\index{arcs, circles} and so we can pre-compute
the  control points of the closed spline\index{arcs, closed splines} to describe the
circle,\index{circles, control points} and then just scale to fit the desired
radius and translate its center to the required coordinate. Ellipses,
\index{arcs, ellipses} \index{ellipses} although not a named primitive, can
be simulated effectively by specifying a closed arc (a.k.a\   circle) and
\index{ellipses, relation to circles}
transform it by scaling as desired in either $X$ and/or $Y$, since circles are a
special case of ellipses.\par

Open arcs are represented by an open spline\index{arcs, open}\index{arcs, open spline} whose control
points were computed\index{arcs, control points} by sampling along the length
of the arc. We do this sampling in 16 places using the parametric
representation of the arc:
$$x = r \cos\theta \> {,}\>\> y = r \sin\theta \qquad 
{\rm\ for\ } \alpha_1 \le \theta \le \alpha_2  $$ and
$\theta$ is a multiple of ${1\over 16} (\alpha_2 - \alpha_1)$. After we obtain
these control points, we can interpolate over the knots and obtain the
spline segments.\par

In reality, we  have to treat arcs with a little more special care 
than simple splines. In computing open splines, we have to do some tricks
with the list of control points. We introduce ``phantom'' control
points
which help the endpoints look nicer. See \cite{wu-abel} for a better explanation
of phantoms\index{phantom control points}. The problem with arcs is that the
\index{arcs, phantoming}endpoints would look too ``flat'' if we used the normal phantom-ing method\index{phantoming}.
What I do is to create two extra control points (one before the start of the
actual arc, and one after) so that we preserve roundness by continuing
around the arc with the same parameters to the representation. Then I {\it
lie\/} to \TT 's innards, saying, ``these extra points are not really part
of the arc to typeset. They are the phantoms, so don't compute any for
us.''\index{lies} After that, everything else works pretty much the same as
regular open-splines in ``tyl''-ing\index{tyling}. It should be apparent that splines are
the largest class of primitive types that \TT deals with, since they are
capable of simulating/representing most graphical objects that we ususally
work with.\index{splines, use in simulating}\par
\medskip
\noindent{\bf Beams}\par
The last basic primitive that \TT offers is the |beam|. Beams\index{{\tt beam}} are
graphically equivalent to straight line-segments. The only difference
is\index{beams, difference from lines}
that they have a different font that they use. This font and the particular
characters from it are determined by the beam's two attributes:\index{beams, attributes} staffsize
and beam-type. Staff size refers to the spacing of the staff lines of
a\index{staff sizes}\index{staff lines}
music score, which also determines the size of the music symbols to use. It
is analagous to defining the point size of a character given the interline
spacing measure. See \cite{ross} for examples of each size, also the 
discussion of the beam characters on page~\pageref{beam-chars-sizes}. The
beam-type attribute refers to the size of notes that the beam connects:
regular or grace notes. More will be said about beams in
section~\ref{beam-setting}.\par
\medskip
\noindent{\bf Labels}\par
|Label|s\index{{\tt label}} are not really considered primitives, but are included 
here for convenience and completeness. They have no correspondence 
with any of the other graphic-primitives described above, but may be
included in figure definitions.
Labels have the attributes of starting position, font-style, and 
the string-body of the label. They are not transformable at the
local level (but are affected by figure-level transforms),
 and are basically pretty simple in nature. {\TeX} macros are not expanded
within the string-body by \TTN; you should use {\TeX} do to any
smarter label-typesetting.\par
Currently, the built-in list of fonts selectable for
 use\index{fonts, for labels}\index{labels, font face-styles} in placing
labels is:\label{labelfonts}
\begin{itemize}
\item amtt10 (selectable by specifying face |1|)
\item amb10 (face |2|)
\item amsl10 (|3|)
\item amtt8 (|4|)
\item and amsl8 (|5|) 
\end{itemize}
The characters from these fonts are simply set, as \TT does not 
worry about kerning or ligatures, and spacing is done with 
information found in the parameter section of the |.tfm| file.
 This font mapping list is only temporary, and 
can be changed  within the \TT source program.\par

\section{Procedural Handling}\label{proc-handling}
After \TT picks apart the |\special| strings\index{special} from the {\DVI} file,
and determines the parameters (both specified and defaulted) for the specified 
primitive, \TT makes a note about where in the file the start of the special
occurs, and passes the data to a {\it handler}.\index{handlers} A handler is
a procedure that is specific to each primitive (e.g., there is a
|linehandle|,\index{handlers, linehandle} and a |ttsplinehandle|
procedure\index{handlers, ttsplinehandle}) that knows about the internal
representation of each primitive, and how to ``handle'' the data passed to
it. We'll talk more about the internal representation in the next
section.\par

The handlers' primary responsibility is to take care of primitive-level
geometric transformations, and then to decide what to do with the data,
 depending on the context of\index{handlers, functionality}
the primitive being dealt with. This context is determined by whether the
primitive is contained in a figure, or is by itself. If the primitive is
{\it not}
contained in a figure (i.e., the |\special| string was not within a
|beginfigure| -- |endfigure| pair), the handler 
\begin{enumerate}
\item computes the bounding box for the primitive\index{bounding box},
\item transforms the
coordinates of the primitive into {\DVI}-space\index{DVI-space},
\item offsets them by the current position on the page,
\item outputs a {\DVI} |push| command,\index{{\tt push}}
\item calls an appropriate procedure to actually typeset the primitive,
\item and finishes with a |pop| command.\index{{\tt pop}}
\end{enumerate}
We need to transform coordinates from our first-quadrant cartesian space
into {\DVI}-space because the lower-level procedures that actually
typeset and output the vector characters assume that they are putting the
characters onto a page of the {\DVI} file.\index{transform to DVI space}\par

If the primitive's definition is part of an enclosing figure definition, we
delay output of this primitive until the figure is completely defined. The
handler does any simple geometric transformations required, and then
 simply packs the data into another structure, and sort of ``stacks'' this
new structure (let's call it an {\it item}\index{item}) onto a list of items
that are contained in this figure.  Our reference to ``figure''
here could also be a sub-figure within an enclosing figure, but for now
we'll just deal with primitives in terms of simple, one-level figures. When
the figure definition is complete, the |figurehandle|
procedure\index{handlers, figurehandle} is called. We will get into figures
more in the next section, but for now, we'll say that this handler
\begin{enumerate}
\item computes the bounding box of all the sub-items of this figure, 
taking care of necessary transformations,
\item outputs a |push| command,
\item unpacks each sub-item, and transforms its coordinates into {\smallrm
DVI}-space,
\item calls the item's particular primitive handler with a special flag
that says to simply call the appropriate procedure for immediate typesetting
without doing any further transforms,
\item and finishes with outputting a |pop| command to the {\DVI}
file.
\end{enumerate}
The design of these handlers was to maintain the idea
of\index{handlers, design idea}
``information-hiding'' such that each handler (primitive-  or figure-level)
would know only about one level of abstraction below it.\par

\section{Figures}
Let's look more closely at what we called ``items'' \index{item}in the previous section,
and how we really represent figures. Up to this point, I have been rather
ambiguous when referring to ``primitives.''\index{primitives, definition of} In some cases, it meant
{\it graphic-primitives\/} (like lines and splines); in other cases it meant
{\it the things that we can make pictures with\/} (like figures, sub-figures,
and graphic-primitives). Well, now the ambiguity gets worse. I'll try to be
careful about distinguishing ``graphic-primitives'' when I mean  primitives that
are reducible to vector characters, and use ``primitives'' when I mean
graphic-primitives {\it and\/} figures. The reason for
the difference is that since we have the ability to do recursive sub-figure
definitions, a ``figure'' (as denoted by a |beginfigure|--|endfigure| pair)
becomes a building block (just like graphic-primitives) for
that enclosing figure's definition.  It is analagous to the programming
language concept of \Prm{block}, where (in BNF notation)
\vspace*{-10pt}\begin{verbatim}
 <figure> ::= <primitive> / <primlist>
 <primlist> ::= <beginfigure> <primlist> <endfigure> /
                <primitive> <primlist> /   <empty>
\end{verbatim} 
where \Prm{primitive} is what we previously referred
 to as an ``item,''\Prm{beginfigure} is
 denoted by |\special{tyl beginfigure}|, and
\Prm{endfigure} is denoted by |\special{tyl endfigure}|.  Refer back
to page~\pageref{sub-figures} for an example of sub-figures.\par

\medskip
\noindent{\bf Items}\par
The ``item'' data structure contains the attributes for graphic-primitives,
as outlined in section~\ref{prims-attribs}, and also contains 
attributes for a figure like:
\begin{itemize}
\item any figure-level transformation parameters,
\item a ``name,''
\item and the list of items contained in this figure.
\end{itemize}
As you may surmise, this can yield a linked-list of linked-lists when built
to represent a complex nested figure. In our previous discussion of
handlers, one mode of their operation was to ``pack and stack'' the data
into an item. Packing\index{item, packing} is easy enough to understand, but putting this
structure in the correct place is tricky. When an item is created and filled
with the appropriate parameters in a graphic-primitive's handler, there is a
notion of ``context''\index{figures, context} which refers to the depth of recursion
of sub-figures. A depth of $0$ means that there is no higher-level figure, a
depth of $1$ means that any primitives encountered will belong to an
outermost level figure, etc. When \TT comes across a |beginfigure| special
string, it changes the recursive-definition context, and names that figure
with that depth number. After that, any graphic-primitives that are
encountered belong to that named figure in that context. An |endfigure|
special will decrement the depth of recursion, and thus will change context
back to the previous context. If this new context has a depth of $0$, then
we know we have closed the outermost level of figure definition, and thus
we are ready to typeset the entire figure.\par

Let's look at how items are inserted\index{item, inserting} onto our data structure so that context
is maintained. \TT uses a procedure called |pushItem| that takes an item and
puts it on the correct list (or sub-list) according to the current figure
context. Roughly, the algorithm is a simple insert, based on a key of
depth-name.
\begin{tabbing}
\hskip 1cm \= Start from the front of the list of this figure\\
  \> while \= the list is not empty\\
\>	\> Look \= at the item\\
\>	\>     \> if it is \= a figure of the current context\\
\>	\>	\>\> then we are done searching. do an insert\\
\>	\>	\> otherwise {\it there must be a sub-figure lower on the
list}\\
\>	\>	\> \> look for the next item on the list that is a figure\\
\>	\>	\> \> and start the next search from its list
\end{tabbing}
I really simplified the explanation of the
insertion scheme here, but the important idea is that of looking for the
correctly labelled figure-list and inserting the item there.\par

Once the structure is built, and \TT determines that it is ready to typeset
the entire figure, it traverses\index{item, traversing} the structure to compute and note the
bounding boxes of the sub-figures (and their bounding boxes, too).\index{bounding
box}
 We need to do this in case there are any\index{transforms, figure-level}
figure-level scaling or rotations of graphic-primitives which are performed relative
to the center of the bounding box of the primitives contained in the 
figure. As we traverse the sub-figures, we do any required sub-figure
transforms, record the dimensions of the bounding box, and pop up a level.
When our traversal has reached the top level, all the figure's primitives
have been transformed according to the recursive definition's specifications
(i.e., the transforms are additive as we descend in recursive 
depth).\index{transforms, additiveness}  If there are any top-level transforms
to be taken care of,\index{transforms, top-level} we revisit the lists of
primitives, performing the transforms.
Finally, at
this point we are ready to re-traverse the structure, grab each
graphic-primitive, unpack it, transform it into {\DVI}-space, 
and give control to its handler for immediate typesetting.\par

If you really want to get picky, the contents of a figure are not
typeset and output until the last balancing |endfigure|\index{{\tt endfigure}} is encountered. It
is at the current position on the page where this |endfigure| is set that
the origin of our figure is placed. We can get away with this condition
because specials are viewed by {\TeX} as ``boxes'' of zero width, and so a consecutive series of
|\special|s do not change the current position on the page relative to the
first invocation of the list. If, however, the user types in normal
{\TeX}-typesettable text in the middle of a list of |\special|s defining a 
figure, the current position will move, and our figure will be shifted down
to the position where the final |endfigure| is invoked. This might make him
unhappy. My advice is to think of the figure/picture as an atomic entity,
whose contents is strictly a list of |\special| strings defining that
figure.\par


\section{The Fonts}
The whole basis of this program lies in the ability to typeset graphics with
characters. Thus we have two families of fonts: the vector fonts (originally
designed at C-MU\cite{nelson-saxe} by Bruce Lucas\index{Lucas{,} Bruce}),
 and the beam fonts (part of the music
fonts for the {\it MusiCopy\/}\index{MusiCopy} project).\par

\TT converts the requests for line-drawings into commands to typeset these
characters of line segments. See Appendix~\ref{font-examples} 
for examples of these characters. Since Metafont~79\index{Metafont} limits the {\smallrm
TFM} information to 16 heights and depths, we have to do the computations of
the character dimensions ourselves.\index{fonts, computing dimensions of}
 This is easy to do as \TT has the
correct dimensions for each character described in Pascal code in such a way
that only a couple parameters from the {\tt .tfm} file need to be accessed
in order for the code to define the exact (internal) dimensions for a font.
In essence, the basic description of the vector and beam fonts are
hard-coded in \TTN , in a manner independent of the actual size of the 
pens used to draw them.
This ``on-the-fly'' font calculation is done only as needed, and then the
font information is cached and noted so that future requests for that font
will not require us to re-compute these dimensions.\par

Within the modified {\DVI} file,
\TT defines these new fonts and begins numbering from 300,\index{fonts,
numbering} as a sort of
``signature.''\index{{\TT}, signatures} So if you look at this new 
{\DVI} file with {\smallrm DVI}type, you can tell the parts that are typeset
figures by noting the places in the listing that reference a font numbered
above 300.\par

\subsection{Vector Setting}\label{vect-setting} The vector fonts themselves,
as described in section~\ref{vectors}, are typeset using the method
described by Nelson\cite{nelson-saxe}, and I'll describe how \TT does it. In
section~\ref{proc-handling}, we made mention that a graphic-primitive's
handler call an ``appropriate procedure to actually typeset the primitive.''
This typesetting procedure is actually the ``hook''\index{programmer's hook}
for a programmer to get right to the typesetting code. The procedures look
like |Tyl|$x$, where $x$ is a graphic primitive (e.g., |TylSpline|,
|TylArc|, etc.), and take as parameters the information equivalent to the
unpacked representation of an item.  The coordinates of any points
used are in {\DVI}-space, \index{DVI-space} and in units of
scaled-points. Refer to the code for the formal parameter
list of each |Tyl|$x$  procedure. These hooks call procedures to ``lay''
line-segments
on the page, after doing some work of clamping\index{clamping}, and opening
the correct font files for the requested
line-thickness\index{line thickness} (thickness{\underbar es} in the case
of |ttspline|s). These procedures, in turn, call |layline|,\index{{\tt
layline}} a procedure that determines the best way to typeset the
line-segment.  |Layline| checks to see if the line is strictly horizonal or
vertical so that it can reduce the line to typsetting a {\TeX} rule, and
then just add endpoints for smooth overlap. However, if the line is more
diagonal, we have to go through more work.\par

Diagonal lines, and certain cases where we think using {\TeX} rules 
inappropriate, require potentially using the full set of vector characters. 
The |diagonal| procedure intersects the line-segment with the origin of 
the semi-square 
of the vector font (see also page~\pageref{semisquare}). In essence, it
implements a greedy method by scaling down the radius of the semi-square to find
the longest possible radius of the vector characters such that the far point
of the line-segment lies just outside that radius.\par
\noindent
\begin{figure}[h]\hskip 4cm\begintyl{8cm}[1in]
\special{tyl beginfigure}
\special{tyl line m 2 0 70 32 70}
\special{tyl line m 2 32 70 32 6}
\special{tyl line m 2 0 6 32 6}
\special{tyl line m 2 0 55 16 55}
\special{tyl line m 2 16 55 16 22}
\special{tyl line m 2 16 22 0 22}
\special{tyl line m 2 0 46 8 46}
\special{tyl line m 2 8 46 8 30}
\special{tyl line m 2 0 30 8 30}
\special{tyl line m 2 0 42 4 42}
\special{tyl line m 2 4 42 4 34}
\special{tyl line m 2 0 34 4 34}
\special{tyl line m 2 0 40 2 40}
\special{tyl line m 2 2 40 2 36}
\special{tyl line m 2 0 36 2 36}
\special{tyl line m 2 0 38 32 38}
\special{tyl line m 8 0 38 25 54}
\special{tyl endfigure}\endtyl
\caption{Semi-squares of the Vector Fonts}
\end{figure}
\noindent Then |diagonal|
determines the $dy$ and $dx$ from the current position to that intersection
point on the line.\footnote{Thus $dx$ and $abs(dy)$ are integer powers of 2 
between 0 and 16 inclusive.}
  We use the mapping \index{vector font, mapping function}
function similar to \cite{nelson-saxe} to determine character code corresponding to these
$dy$ and $dx$ values:\goodbreak
\vspace*{-10pt}
$$ code = 160 + dy + dx - 9*{\rm max}\,(dx,\, -dy)\qquad {\rm\ for\ } dy < 0 \> {,
}\>\> dx \geq 0$$
$$ code = 160 + dy - dx - 7*{\rm max}\,(dx,\, dy)\qquad {\rm\ for\ } dy \geq 0 \> {,
}\>\> dx \geq 0$$
but this scheme assumes that our font has at least 160 characters (i.e.,
256), but most fonts have only 128 characters. We have to re-map this 
discontinuous set of codes to fit with a range of $0 \ldots 127$, and in doing so,
we have to lie\index{lies} about two of the characters by pretending that
the two longest vertical vectors do not exist, but each is
 to be replaced by {\it two\/} vectors of half that length.\par

Once we have determined the vector character, all we have to do is move to the
current-position, set the character, increment our position, 
and finish setting the rest of this line-segment.  The
thickness of the vector theoretically does not matter, as the path followed
by the vector character is invariant over the thickness (at least to the
resolution of the printer).\index{vector font, path invariance}\par

\subsection{Beam Setting}\label{beam-setting}
The way that \TT typesets beam is similar to typesetting
line-segments.\index{beams, typesetting}
 The
|TylBeam| procedure  takes care of determining the correct beam character to
use. Recall from section~\ref{beam-chars-sizes} that there are two lengths
for each type of quarternote (i.e., regular notes and grace notes). When \TT
tries to typeset the beam, it uses the beam character whose length is
longest {\it and\/} whose angle is closest to that required.\par

 Given a music font of beam characters with their lengths, heights, depths,
and angles from horizontal computed, we try to set the whole beam at once by
the following method:
\begin{enumerate}
\item Compute the $dy$ and $dx$ of the beam, as well as its length and
actual angle from horizontal
\item compute the fractional number of characters needed to typset the beam
for both sizes of beam characters (this is
${{\rm length}_{\rm beam}\over {{\rm length}_{\rm beamchar}}}$)
\item try to bracket a pair of beam characters whose angles are nearest the
actual angle of the beam
\item use the beam character that has the smallest angular deviation from
that of the actual beam
\item typeset the  characters along the line from the left
endpoint of the beam to as close to the right endpoint as possible. Then
typeset the last character such that the right-hand-side of the character
coincides with the right endpoint of the beam.
\end{enumerate}
 We only need to select one character to use for typesetting as the
slope of the beam is constant over its length, and the character used has a
``slope'' (angle from horizontal) that is as close as possible to the
beam.\par
This juggling of ``best-length'' versus ``best-slope'' is only necessary
because of the need to keep the set of characters to a reasonable size, and
also because the angles required for beams is not as broad as for the
requirements of the more-general vector line-segments.\par

\section{Buffering}
As \TT reads in  bytes from the {\DVI} file for subsequent interpretation, it
 copies them
into an internal buffer. At a simple level, this buffer is used to simply
copy the {\DVI} bytes used on a {\DVI} page (delimited by |bop| and |eop|
bytes). Thus, \TT would act simply as a mechanism that copies its input to
its output, verbatim. At the level that {\it we} are interested in, this
buffer will hold all the bytes up to, and including  a |tyl| special string. 
On page~\pageref{proc-handling}, we made mention of a ``note about where the
start of the special occurred'' in the {\DVI} file. When we read
a\index{specials}\index{tyling}
|special|, we mark the position of the beginning byte of the special, as
found in our buffer. If we find that the special is ``tyl''-able, we back up
the current place in the buffer to the start of the special, and proceed
with the tyling. \TT will output typesetting command bytes, and effectively
over-write the previous |special| string in the buffer, achieving a kind of
in-line macro-expansion of the special.\index{macro-expansion}\par

A tricky part of this macro-expansion approach is taking care of defining
new fonts that were used during tyling on a page. As \TT ``tyl''s a figure,
it records the used font names (here, only vector or beam fonts) in a list
of ``fonts-to-be-defined.''\index{fonts, to be defined}\index{fonts, defining}
 At the end of a page, we formally define these
as yet undefined fonts within the {\DVI} file, and then mark them as having
been {\DVI}-defined to avoid re-definition before the postamble. Even
this scheme needs cleverness since we do not know all the fonts used to
typeset any primitive until the end of the page, but we have to define the
font within the {\DVI} file before the first actual use of the font to typeset
those graphic primitives.\par

The way we get around this ``Catch-22''-ish situation is to have an internal
flag (a ``font-flag'')\index{fonts, font flag}  
inserted into the buffer before the first commands to typeset a graphic
primitive. Since the {\DVI} format\index{DVI format} allows us to
 define fonts\index{defining fonts} between any two
{\DVI} commands in a file, we can define them mid-stream.
As \TT parses a graphic primitive's
|special| string, it backs up in the buffer to the start of the special,
outputs the font-flag and then continues to insert the tyling commands into
the buffer until the next special, or the end of page. At the end of a page,
all the tyl-able |specials| have been expanded, we have buffer full of {\DVI}
commands and font-flags for this page, and a list of fonts ready for initial
definition in the {\DVI} file. We are now ready to write the buffer to the
actual file. As \TT writes each byte of the buffer to the disk file, it
first looks at the byte. If it is ``normal'' (i.e., $0\ldots 255$), it
converts the byte to the proper system-dependent format (if necessary) and
outputs it to the disk file. However, if the byte is our font-flag, it
treats this flag as a macro, too, and writes out to the file the formal {\DVI}
definitions of the new fonts. \TT does this expansion only once per page,
and ignores any other font-flags for the rest of the page (well, it actually
outputs them as |nop|s). After these new fonts have been defined, \TT
continues to output each byte of the page buffer, and when done, starts
processing on the next {\DVI} page for tyling.\par

\section{Odds 'n Sods}
This section contains down-deep information in \TT that really does not fit nicely
anywhere else.\par
As I discussed before, \TT is built on top of the {\DVI}type\index{DVItype}
program\cite{dvitype} and was modified in following ways:
\begin{itemize}
\item The |specialcases| and |skippages| procedures were modified to call
{\TTN}'s |mainhandlespecials| procedure to handle any |\special| strings,
instead of throwing those bytes out.
\item The |readpostamble| procedure was changed so that we can insert all
the font definitions of the new fonts that we used during any tyling. \TT
simply copies to the internal buffer any font definitons already in the
postamble\index{postamble}, until it reaches a |postpost|. Here \TT backs up one byte (over
the |postpost|), outputs all its new fonts, and then inserts the new
|postpost|.
\item The |main| loop was modified so that at each end-of-page, we write out
the internal buffer, clear it, and reset any internal counters for the page
(like figure-depth context, figure-number, and counts of
fonts-to-be-defined).
\end{itemize}\par
\medskip
\noindent{\bf Other Notes}\par
I have implemented an adaptive sub-division method for determining an
optimal number of vector characters with which to typeset a splines.
\index{splines, typesetting}
The method uses a simple quadrature\index{subdivision of splines}
 sub-division on each span of the spline until a linear-distance criterion
is met. If we let the number of sub-divisions be $N$,
we can determine the near-optimum number of
intervals with which  to actually sample the spline when we do the
interpolation as $2^N$.
 This is ``optimal'' in that we use the fewest vectors for long
spans, and do not under-sample shorter, tighter spans, and achieve a spline
that is very smooth.\par
The names of the primtives\index{primitives, names} within the |\special|
strings need be unique only to the first three letters. Thus 
|\special{tyl beg}| is equivalent to 
|\special{tyl beginfigure}|. This can make input easier and
shorter.\par

Also, we can be pretty lenient about how we delimit\index{delimiters} our
keywords\index{keywords} and makers. In most of the examples, commas or 
spaces were used to separate the markers and integers. In actuality, we can
use almost anything for keyword and marker delimiting {\it other} than:
\begin{itemize}
\item other alphabetic letters 
\item other marker characters (like |@| and |"|)\index{{\tt "}-marker}
\item {\tt\%}, |~|, |\| and  those other reserved characters
 which might upset {\TeX}, as it
tries to expand macros inside the body of the |special| string before
outputting it to the {\DVI} file.
\end{itemize}
For example,
\hbox{|\special{tyl line *()(]!::4... 3** 4&&12[5}|}
is lexically equivalent to the nicely typed
\hbox{|\special{tyl line m 4 (3,4)(12,5)}|} or the tersely typed
\hbox{|\special{tyl lin m 4 3 4 12 5}|}.\par

Another ``signature''\index{{\TT}, signatures} of \TT is whenever we output the
commands to typset a line-drawing, we preceed the |push| command with 
{\it two} |nop|s. This easily identifies the sections that have been
``tyl''-ed.\par

\Makeodd
\chapter{Future Extensions}
Given  a little time, one could extend\index{extensions} the current set of graphic
primitives in \TTN, such as:
\begin{itemize}
\item simpler-appearing macros,
\item  regular polygons (all
easily built upon currently-existing primitives),
\item oriented arrows 
\item line-pattern filled figures, 
\item a more general method of defining and instancing symbol definitions.
\end{itemize}
 I am still experimenting with two
methods of adequately computing the smoothest interpolation of thicknesses
along the length of the slur.  When the thickness for a particular segment
of the curve have been determined, we check to see if that thickness is in a
subset of vector-font sizes.  If so, we can use it as-is; otherwise, we have
to clamp\index{clamping} that thickness to fit in the subset.  The only problem is that
achieving a super-smooth interpolation along the curve's thicknesses might
require a large number of vector fonts to be loaded---sometimes stressing
the printing\index{output device} device's capabilities.  I still have to experiment to find a
reasonable subset of these sizes that can be used and still achieve adequate
results.\par

 I wrote this program with the intention of ease
of extensibility for additional ``primitives'' to be built on top of the
functionality provided by \TTN.
 I have also interfaced  \TT with
 Dario Giuse's\index{Giuse{,} Dario} graphic drawing program 
 {\it DP\/}  that he 
wrote at  C-MU\cite{dario}. It is smart enough to represent its graphics primitives 
in files as a list of text-strings, and is now able to output the |\special|
strings, specifying the width and height of the created figure.
 Converting the files of the MacDraw program to yield
{\smallrm ASCII} strings is potentially possible, too.
In either case, such strings are  be easily converted to
|\special| command strings for \TT to work on.\par
\Makeodd
\appendix
\chapter{{\TeX}tyl Summary}
Let's summarize the abilities and requirements of \TTN . First of all, we
have to put an |\input{textyl}| near the start of the document (at least
before our first invocation of a |\special{tyl ...| command). This loads the
macros that we need to create space for our figure, and to set up the right
environment for \TTN .\par

Once the macros have been loaded, when we want to set a figure (or even a
single \TT primitive), we must place the primitives within an environment
started  by
\hbox{|\begintyl{|\Prm{vertsize}|}[|\Prm{horizsize}|]|}
 and finished by |\endtyl|. Here,
the required parameter,\Prm{vertsize}, determines the vertical
size of the box that \TT will create for our figure to be placed in. If we
do not need extra space, we put in |0pt| or some similar zero-length
dimension. The optional parameter,\Prm{horizsize}, will add a non-zero width
to the box that |\begintyl| creates for us. It is {\it crucial\/} that there
is {\it no\/} space between the |}| and |[| characters of the |\begintyl|
invocation if we decide to use the optional horizontal width specification.
Otherwise, things may go awry for this figure. Also, we are responsible for
any offsets that we may need before the figure is placed. We can achieve
this through |\hskip| and |\vskip| calls in \TeX\ , or |\hspace| and
|\vspace| calls in \LaTeX.\index{space}
\index{{\TeX}}\index{{\LaTeX}}\index{{\TeX} commands}\par

The types of primitives that we may place within the |\begintyl| and
|\endtyl| pair are summarized here, without their surrounding
 |\special{tyl | -- |}|, nor any extra delimiting punctuation (like commas).
\begin{verse}
{\tt beginfigure} \sOpt{meas} \sOpt{xfm}\ 
{\leavevmode\hbox{$\>\lbrack${\tt W}$\>\langle wid\/\rangle\,
\langle ht\rangle\,\rbrack\,$}}
{\leavevmode\hbox{$\>\lbrack${\tt F}$\>\langle wid\/\rangle\,
\langle ht\rangle\,\rbrack\,$}} \mbox{\it which opens the environment}

{\tt endfigure}\mbox{\it \ \ which closes the environment}

{\tt line} \sOpt{meas}\sOpt{xfm} \Prm{thick}
\sOpt{vect}{\leavevmode\hbox{$\>\lbrack${\tt L}$\>\langle style\rangle\,\rbrack$}}
 $ x_{\rm l}\> y_{\rm b}\> x_{\rm r}\> y_{\rm t}$

{\tt spline} \sOpt{meas}\sOpt{xfm}\Prm{thick}
\sOpt{vect}{\leavevmode\hbox{$\>\lbrack${\tt L}$\>\langle style\rangle\,\rbrack$}}
\sOpt{spltype}\\
\hspace*{2em}\sOpt{closure}
{\leavevmode\hbox{$\>\lbrack${\tt X}$\>\langle thick\rangle\,\rbrack$}}
\Prm{numpts}\mbox{\it the x-y points}

{\tt ttspline} \sOpt{meas}\sOpt{xfm}
\sOpt{vect}{\leavevmode\hbox{$\>\lbrack${\tt L}$\>\langle style\rangle\,\rbrack$}}
\sOpt{spltype}\\
\hspace*{2em}\sOpt{closure}
{\leavevmode\hbox{$\>\lbrack${\tt X}$\>\langle thick\rangle\,\rbrack$}}
\Prm{numpts} \mbox{\it points} \mbox{\it thicknesses}

{\tt arc} \sOpt{meas}\sOpt{xfm} \Prm{thick}\sOpt{vect}
{\leavevmode\hbox{$\>\lbrack${\tt L}$\>\langle style\rangle\,\rbrack$}}\Prm{radius}\\
\hspace*{2em}{\leavevmode\hbox{$\>\lbrack${\tt @}$\>\langle cent_x\rangle\,
\langle cent_y\rangle\,\rbrack$}}\Prm{startAng} \Prm{stopAng}

{\tt label} \sOpt{meas}
\Prm{face}$\;x \> y$ \mbox{{\tt "}\Prm{string}{\tt "}}

{\tt tieslur} \sOpt{meas} \Prm{minthick}\Prm{maxthick}
\Prm{numpts}\mbox{\it points}

{\tt beam} \sOpt{meas} \Prm{staffsize}
\sOpt{beamtype} $x_1 \> y_1\> x_2\> y_2$

where:
\end{verse}
\begin{description}
\item[meas] specifies units of length for this primitive. One of |S|,|P|, or
|M| indicates scaled-points, printers-points, and millimeters, respectively.
Defaults to printers-points.

\item[xfm] specifies a transformation to be applied. It is of the form\\
\mbox{{\tt T}\Prm{sx}\Prm{sy}\Prm{tx}\Prm{ty}\Prm{rot}}, where {\it sx\/} and
{\it sy\/} are for scaling, {\it tx\/} and {\it ty\/} are for translation,
and {\it rot\/} is for counter-clockwise rotation (in degrees).

\item[thick] is the integer thickness of the line. Usually between 1 and 12.

\item[vect] is the type of vector font to use. One of |C|, |H|, or |V|
indicates circular, horizontal-flat, or vertical-flat pen type. Defaults to
circular pen.

\item[style] is the line-style to use. One of |0|, |1|, |2|, or |3| indicates
a solid, dotted, dashed, or dot-dashed line-style. Defaults to solid line.

\item[spltype] is the kind of spline to use through the control points. One of
|B|, |D|, |K|, or |I| indicates the B-spline, Cardinal, Catmull-Rom, or
Interpolating b-spline basis to use, respectively. Defaults to Catmull-Rom.

\item[closure] is one of |O| (``oh'') or |U| which indicates that the spline
is closed or open, respectively. Defaults to open.

\item[numpts] is the integer number of control points for this spline.

\item[radius] is the length of the radius in units specified by \Prm{meas}.

\item[centx] and {\bf centy} are the center-point coordinates
 of the arc/circle.

\item[startAng] and {\bf stopAng} are the initial and final angles,
respectively, for the arc as measured in degrees counter-clockwise from the
positive x-axis. If they are the same number, a closed circle is indicated.

\item[face] refers to the style of typeface for the label.
See page~\pageref{labelfonts} for the list.

\item[string] is the string-body of the label to typeset at the specified
position.

\item[staffsize] refers to the staff note-size for beams. It is between 0
and 8, inclusive.

\item[beamtype] is the type of beam to use. One of |G| or |R| indicates
grace-note size, or regular size beams, respectively. Defaults to regular.

\item[wid] and {\bf ht} refer to the width and height of a figure, in units
specified by \Prm{meas}. Mainly used in conjuction with |F| (``Fitting''
size operator) and |W| (``Written'' size marker).
\end{description}
\Makeodd
\chapter{Font Example}\label{font-examples}
% macros for font tables
\def\oct#1{\hbox{\rm\'{}\kern-.2em\it#1\/\kern.05em}} % octal constant
\def\hex#1{\hbox{\rm\H{}\tt#1}} % hexadecimal constant
\def\oddline#1{\cr
  \noalign{\nointerlineskip}
  \multispan{19}\hrulefill&
  \setbox0=\hbox{\lower 4pt\hbox{\hex{#1x}}}\smash{\box0}\cr%was 2.3pt
  \noalign{\nointerlineskip}}
\def\evenline{\cr\noalign{\hrule}}
\def\chartstrut{\lower4.5pt\vbox to20pt{}}%was 14pt
\def\beginchart#1{$$\postdisplaypenalty=-10000 \global\count222=0 #1
  \halign to\hsize\bgroup
    \chartstrut##\tabskip0pt plus10pt&
    &\hfil##\hfil&\vrule##\cr
    \lower6.5pt\null
    &&&\oct0&&\oct1&&\oct2&&\oct3&&\oct4&&\oct5&&\oct6&&\oct7&\evenline}
\def\endchart{\raise11.5pt\null&&&\hex 8&&\hex 9&&\hex A&&\hex B&
  &\hex C&&\hex D&&\hex E&&\hex F&\cr\egroup$$}
\def\:{\setbox0=\hbox{\char\count222}%
  \ifdim\ht0>7.5pt\reposition
  \else\ifdim\dp0>2.5pt\reposition\fi\fi
  \box0\global\advance\count222 by1 }
\def\reposition{\setbox0=\hbox{$\vcenter{\kern2pt\box0\kern2pt}$}}
\def\normalchart{%
  &\oct{00x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline0
  &\oct{01x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{02x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline1
  &\oct{03x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{04x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline2
  &\oct{05x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{06x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline3
  &\oct{07x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{10x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline4
  &\oct{11x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{12x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline5
  &\oct{13x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{14x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline6
  &\oct{15x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline
  &\oct{16x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\oddline7
  &\oct{17x}&&\:&&\:&&\:&&\:&&\:&&\:&&\:&&\:&\evenline}
\font\cv=cvec3
\vfill\eject
\centerline{Example of |cvec3|}\par
\beginchart{\cv}
\normalchart
\endchart
%\vfill\eject
%\Makeodd
\chapter{Macros and Extended Examples}\label{secapp}
All of the thumbnail figures in this manual were created using the 
|\special{tyl...| strings\index{specials} as described, and were placed within an
environment delimited by |\begintyl| and |\endtyl|.\index{{\tt
begintyl}}\index{{\tt endtyl}} This environment allows
the user to specify a vertical and optional horizontal offset from the
``current-position'' on the page. This determines where the origin of the
user's coordinate system is to be placed. Also, this environment sets
parameters so that the user can use tabbing and spacing to align the
\hbox{|\special|} strings as he desires (e.g., to better show the nesting of
figures and graphic-primitives). The macros\index{macros} used are defined 
below:
\vspace*{-20pt}

\bgroup\footnotesize
\begin{verbatim}
  %  This is textyl.tex
  %
  % macros for figures for Tyling
  % specify : 
  % \begintyl{vert_dimen}[optional_horiz_dimen]
  %	   (with NO intervening space between the } and the [ chars)
  % then the \special{tyl ...} strings
  %  then you must finish environment with  \endtyl 
  %
\def\begintyl#1{\begingroup\endlinechar=-1\catcode `\^^I=9
	\dimen120=#1
	\ifhmode\toks0={\futurelet\tyltempb\begHtyl}
	\let\endtyl=\endHtyl
	\else\toks0={\futurelet\tyltempb\begVtyl}
	\let\endtyl=\endVtyl\fi
	\the\toks0}
\def\begHtyl{\ifx [\tyltempb \let\tylh=\tylHspace
	\else\let\tylh=\tylHnospace\fi\tylh}
%
\def\tylHspace[#1]{\setbox0=\hbox to #1\bgroup
	\vbox to \dimen120\bgroup\vss}
\def\tylHnospace{\setbox0=\hbox\bgroup
	\vbox to \dimen120\bgroup\vss}
%
\def\begVtyl{\ifx [\tyltempb \let\tylv=\tylVspace
	\else\let\tylv=\tylVnospace\fi\tylv}
%
\def\tylVspace[#1]{\setbox0=\vbox to \dimen120\bgroup\vss 
	\hbox to #1\bgroup}
\def\tylVnospace{\setbox0=\vbox to \dimen120\bgroup\vss
	\hbox\bgroup}
%
\def\endHtyl{\egroup\hss\egroup\box0\endgroup}
\def\endVtyl{\hss\egroup\egroup\box0\endgroup}
\end{verbatim}

\egroup
\par
Let's look at a non-trivial example of frequently-used figures. The
original figure is from \cite{ahu}, page 325. I'll give the diagram, and then
the annotated |\special| commands.\par
\begintyl{9cm}
\special{tyl begin /AHU=fig=9.7/}
  \special{tyl arc m 2 6 @ 10 46 10 10 /state=s1/}
  \special{tyl label m 5 9 46 "s1"}
  \special{tyl arc m 2 6 @ 62 20 10 10 /state=s2/}
  \special{tyl lab m 5 61 20 "s2"}
  \special{tyl arc m 2 6 @ 62 60 10 10 /state=s3/}
  \special{tyl lab m 5 61 60 "s3"}
  \special{tyl arc m 2 6 @ 104 34 10 10 /finalstate=s4/}
  \special{tyl arc m 2 8 @ 104 34 10 10}
  \special{tyl lab m 5 103 34 "s4"}
%now draw the connectors  
  \special{tyl line m 3 16 48 56 59 /s1-s2/}
  \special{tyl lab m 1 30 53 "a"}
     \special{tyl line m 3 56 59 53 60}% and the arrow
     \special{tyl line m 3 56 59 54 57}
     \special{tyl line m 3 53 60 54 57}

  \special{tyl line m 3 15 43 56 23 /s1-s3/}
  \special{tyl lab m 1 32 30 "e"}
     \special{tyl line m 3 56 23 55 25}
     \special{tyl line m 3 56 23 53 23}
     \special{tyl line m 3 55 25 53 23}

  \special{tyl spline m 3 4 12 52; 62 76; 90,63;  105,44 /s1-s4/}     
  \special{tyl lab m 1 70 78 "b"}
     \special{tyl line m 3 105,42 106 44}
     \special{tyl line m 3 105 42 104 44}
     \special{tyl line m 3 104 44 106 44}

  \special{tyl line m 3 62 26 62 54 /s3-s2/}
  \special{tyl lab m 1 64 38 "b"}
     \special{tyl line m 3 62 54 64 52}
     \special{tyl line m 3 62 54 60 52}
     \special{tyl line m 3 60 52 64 52}

  \special{tyl spline m 3 3 67 55; 80 42; 96 36 /s3-s4/}
  \special{tyl lab m 1 76 40 "e"}
     \special{tyl line m 3 96 36 95 38}
     \special{tyl line m 3 96 36 95 35}
     \special{tyl line m 3 95 35 95 38}

  \special{tyl spline m 3 3 69 61; 86 52; 98 40 /s4-s3/}
  \special{tyl lab m 1 89 51 "a"}
     \special{tyl line m 3 69 61 71 62}
     \special{tyl line m 3 69 61 70 59}
     \special{tyl line m 3 70 59 71 62}

  \special{tyl line m 3 69 22 96 32 /s2-s4/}
  \special{tyl lab m 1 82 24 "e"}
     \special{tyl line m 3 96 32, 94 33}
     \special{tyl line m 3 96 32 95 30}
     \special{tyl line m 3 94 33 95 30}
\special{tyl endfigure}
\endtyl\par
And the text to produce this is:

\bgroup\footnotesize
\begin{verbatim}
\begintyl{9cm}
\special{tyl begin /AHU=fig=9.7/}
  \special{tyl arc m 2 6 @ 10 46 10 10 /state=s1/}
  \special{tyl label m 5 9 46 "s1"}
  \special{tyl arc m 2 6 @ 62 20 10 10 /state=s2/}
  \special{tyl lab m 5 61 20 "s2"}
  \special{tyl arc m 2 6 @ 62 60 10 10 /state=s3/}
  \special{tyl lab m 5 61 60 "s3"}
  \special{tyl arc m 2 6 @ 104 34 10 10 /finalstate=s4/}
  \special{tyl arc m 2 8 @ 104 34 10 10}
  \special{tyl lab m 5 103 34 "s4"}
%now draw the connectors  
  \special{tyl line m 3 16 48 56 59 /s1-s2/}
  \special{tyl lab m 1 30 53 "a"}
     \special{tyl line m 3 56 59 53 60}% and the arrow
     \special{tyl line m 3 56 59 54 57}
     \special{tyl line m 3 53 60 54 57}

  \special{tyl line m 3 15 43 56 23 /s1-s3/}
  \special{tyl lab m 1 32 30 "e"}
     \special{tyl line m 3 56 23 55 25}
     \special{tyl line m 3 56 23 53 23}
     \special{tyl line m 3 55 25 53 23}

  \special{tyl spline m 3 4 12 52; 62 76; 90,63;  105,44 /s1-s4/}     
  \special{tyl lab m 1 70 78 "b"}
     \special{tyl line m 3 105,42 106 44}
     \special{tyl line m 3 105 42 104 44}
     \special{tyl line m 3 104 44 106 44}

  \special{tyl line m 3 62 26 62 54 /s3-s2/}
  \special{tyl lab m 1 64 38 "b"}
     \special{tyl line m 3 62 54 64 52}
     \special{tyl line m 3 62 54 60 52}
     \special{tyl line m 3 60 52 64 52}

  \special{tyl spline m 3 3 67 55; 80 42; 96 36 /s3-s4/}
  \special{tyl lab m 1 76 40 "e"}
     \special{tyl line m 3 96 36 95 38}
     \special{tyl line m 3 96 36 95 35}
     \special{tyl line m 3 95 35 95 38}

  \special{tyl spline m 3 3 69 61; 86 52; 98 40 /s4-s3/}
  \special{tyl lab m 1 89 51 "a"}
     \special{tyl line m 3 69 61 71 62}
     \special{tyl line m 3 69 61 70 59}
     \special{tyl line m 3 70 59 71 62}

  \special{tyl line m 3 69 22 96 32 /s2-s4/}
  \special{tyl lab m 1 82 24 "e"}
     \special{tyl line m 3 96 32, 94 33}
     \special{tyl line m 3 96 32 95 30}
     \special{tyl line m 3 94 33 95 30}
\special{tyl endfigure}
\endtyl\par
\end{verbatim}

\egroup
\vfill
\Makeodd
\begin{thebibliography}{99}
\typeout{bib}
\bibitem{adobe}Adobe Systems Inc., {\it PostScript Language Reference Manual.}
Addison-Wesley, Reading, MA, 1985.

\bibitem{ahu}Alfred V. Aho, John E. Hopcroft, and Jeffrey D. Ullman, {\it
The Design and Analysis of Computer Algorithms.} Addison-Wesley, Reading,
Mass. 1974.

\bibitem{barsky}Brian A. Barsky, and Donald P. Greenberg, ``Determining a
Set of B-spline Control Vertices to Generate an Interpolating Surface.''
{\it Computer Graphics and Image Processing.} {\bf 14} 3, (Nov. 1980), pp.203--226.

\bibitem{cagd}Edwin E. Catmull, and Raphael J. Rom, ``A Class of Local
Interpolating Splines.'' {\it Computer Aided Geometric Design.}
Robert E. Barnhill and Richard F. Riesenfeld, eds.
 Academic Press, New York, NY, 1974, pp. 317--326.

\bibitem{dvitype}David R. Fuchs, Howard Trickey, {\it The DVI$\,$type processor.} Program
documentation, 1983--4.

\bibitem{dario}Dario Giuse, {\it DP---Format of the drawing files.}
Technical Report. Car\-negie -Mellon University Robotics Institute, 1983.

\bibitem{gourlay}John S. Gourlay, ``A Language for Music Printing.'' 
{\it Communications of the ACM\/} {\bf 29} 5, (May 1986), pp. 388--401.

\bibitem{dvisun}Norm Hutchinson, et al. {\smallrm DVISUN} Program. 1983.

\bibitem{knuth-tex82}Donald E. Knuth, {\it The \TeX book.} Addison-Wesley,
Reading, Mass. 1984.

\bibitem{knuth-mf}Donald E. Knuth, {\it \TeX\ and METAFONT: New Directions in
Typesetting.} Digital Press, Bedford, MA, 1979.

\bibitem{nelson-saxe}Bruce Nelson, and James Saxe, ``Drawing Splines with a 
Vector Font.''
Unpublished technical report. Carnegie-Mellon University, 1980.

\bibitem{ross}Ted Ross, {\it The Art of Music Engraving and Processing.}
Hansen Books, 1970.

\bibitem{updike}Daniel Berkeley Updike, {\it Printing Types: Their History,
Forms, and Use.} Harvard University Press, Cambridge, MA, 1937.

\bibitem{wu-abel}Sheng-Chuan Wu, John F. Abel, and Donald Greenberg,
  ``An Interactive Computer 
Graphics Approach to Surface Representation.'' 
 {\it Communications of the ACM\/} {\bf 20} 10, (Oct. 1977), pp. 703--712.

\bibitem{vanwyk}Christopher J. Van Wyk, {\it A Language for Typesetting
Graphics.} Ph.D. dissertation. Stanford University, 1980.

\bibitem{zapf}Hermann Zapf, {\it The Printing Salesman's Herald.} Book 39.
Champion Papers, New York, NY, 1978.
\end{thebibliography}
\Makeodd
\begin{theindex}
\newcommand{\largeletter}[1]{{\pagebreak[2]\Large\hspace{-.5in}\parbox[t]{.5in}{\makebox[.35in][r]{\uppercase{#1}}}\nopagebreak[4]\vspace{-1.5ex}}}
\item {\tt "}-marker 19, 48
\item {\tt .dvi} file 3
\item {\tt .tex} text file 1, 3, 34
\item {\tt .tlog} file 4, 23
\item {\tt .tyl} file 23
\item {\tt ?!} flag 24
\item {\tt ?} flag 23
\item {\tt @}-marker 8, 19
\indexspace
\largeletter{a}
\item {\tt arc} 36
\item {\bf arc} 19
\item arcs 7
  \subitem  angles 8, 19
  \subitem  attributes 36
  \subitem  center 8
  \subitem  centering 8, 19
  \subitem  circles 8, 36
  \subitem  closed splines 36
  \subitem  control points 31, 36
  \subitem  ellipses 36
  \subitem  example 8
  \subitem  open 36
  \subitem  open spline 36
  \subitem  phantoming 37
  \subitem  radius 8
  \subitem  representation 31, 36
\indexspace
\largeletter{b}
\item {\tt B}-marker 6, 14, 20
\item B-spline basis 6, 20
\item B-splines 
  \subitem  interpolating-type 6
  \subitem  recomputing points 30
\item {\bf beam} 22
\item {\tt beam} 37
\item beam-types 22
\item beam font 29
  \subitem  constraints 30
  \subitem  design 29
  \subitem  difference from vector font 29
  \subitem  lengths 30
  \subitem  range of angles 30
  \subitem  relation to staff size 29
  \subitem  sizes 29
  \subitem  types 29
\item beams 16
  \subitem  attributes 37
  \subitem  default size 22
  \subitem  difference from lines 37
  \subitem  sizes 22
  \subitem  staff size 22
  \subitem  typesetting 45
\item {\bf beginfigure} 11, 22
\item {\tt begintyl} 1, 3, 4, 12, 57
\item bitmaps {\it\romannumeral 6}
\item blank space 17
\item bounding box 34, 38, 41
\item boxes 1, 3, 9
\indexspace
\largeletter{c}
\item {\tt C}-marker 20
\item capabilities {\it\romannumeral 5}, {\it\romannumeral 6}, 17
\item Cardinal basis 6, 20
\item cartesian-space 2
\item Catmull-Rom basis 20
\item Catmull-Rom splines 5, 30
\item circles 7, 8, 36
  \subitem  control points 31, 36
  \subitem  relation to arcs 36
  \subitem  representation 31
\item circular pen 20
\item clamping 35, 43, 49
\item closed splines 14, 20
\item closure 20
\item combining primitives 9, 10
\item coordinates 2
  \subitem  origin 2
\item coordinate space system 19
\item current position 1, 2, 3, 17
\item curves 5
\indexspace
\largeletter{d}
\item {\tt D}-marker 6, 20
\item defaulting values 5
\item defining fonts 46
\item delimiters 6, 48
\item design decisions 21, 27, 30
\item design goals {\it\romannumeral 5}
\item DVI {\it\romannumeral 5}
\item DVI-filters 4
\item DVI-space 35, 38, 43
\item DVI file 27
  \subitem  previewing 33
\item DVI format 46
\item DVI position coordinates 27
\item DVISUN 33
\item DVItype 27, 47
\indexspace
\largeletter{e}
\item ellipses 19, 31, 36
  \subitem  relation to circles 36
\item {\tt endfigure} 42
\item {\bf endfigure} 11, 22
\item {\tt endtyl} 1, 12, 57
\item errors 
  \subitem  internal 24
\item extensions 49
\indexspace
\largeletter{f}
\item {\tt F}-marker 22
\item figure definitions 22
\item figures 10
  \subitem  context 41
  \subitem  defining 11
  \subitem  example 12
  \subitem  examples 11
  \subitem  fitting to size 22
  \subitem  nested symbols 11
  \subitem  preparation 2
  \subitem  sub-figures 11
  \subitem  tranforms 22
  \subitem  transforms 10, 22
\item fonts 
  \subitem  computing dimensions of 42
  \subitem  defining 46
  \subitem  font flag 46
  \subitem  for labels 38
  \subitem  numbering 43
  \subitem  to be defined 46
\indexspace
\largeletter{g}
\item {\tt G}-marker 16, 22
\item geometric transforms 21
\item Giuse{,} Dario 28, 49
\item grace-notes 16
\item graphic editors 17, 22
\item grid-origin 3
\indexspace
\largeletter{h}
\item {\tt H}-marker 20
\item handlers 38
  \subitem  design idea 39
  \subitem  figurehandle 39
  \subitem  functionality 38
  \subitem  linehandle 38
  \subitem  ttsplinehandle 38
\item handling specials 27
\item horizontal pen 20
\indexspace
\largeletter{i}
\item {\tt I}-marker 6, 20
\item Ideal {\it\romannumeral 5}
\item {\tt input} 1
\item interpolating B-spline 6
  \subitem  basis 20
\item item 39, 40
  \subitem  inserting 41
  \subitem  packing 40
  \subitem  traversing 41
\indexspace
\largeletter{j}
\item jaggies 36
\indexspace
\largeletter{k}
\item {\tt K}-marker 5, 20
\item keywords 6, 48
\item Knuth{,} Donald 1
\indexspace
\largeletter{l}
\item {\tt L}-marker 20
\item {\tt label} 37
\item {\bf label} 19
\item labels 
  \subitem  face 19
  \subitem  font face-styles 38
  \subitem  font style 19
  \subitem  strings 19
\item {\LaTeX} 1, 3, 17, 51
  \subitem  {\tt figure } environment 17
\item {\tt layline} 43
\item leaving no space 3
\item leaving white space 3
\item lies 37, 44
\item {\tt line} 35
\item {\bf line} 18
\item line example 1
\item line segments 18, 35
\item line style 20, 34
  \subitem  dashed 20
  \subitem  dot-dashed 20
  \subitem  dotted 20
  \subitem  solid 20
\item line styles 
  \subitem  examples 20
\item line thickness 2, 18, 20, 31, 43
  \subitem  example 20
\item local maintainer 4, 25
\item Lucas{,} Bruce 42
\indexspace
\largeletter{m}
\item {\tt M}-marker 5, 6, 10
\item {\tt M}-measure 19
\item macro-expansion 33, 46
\item macros 1, 9, 57
  \subitem  {\it see} {\tt begintyl} 1
\item markers 6
\item measurement 19
  \subitem  default 19
  \subitem default 22
  \subitem  units 2
\item Metafont 28, 42
  \subitem  limitations 28
\item millimeters 19
  \subitem  measurement 5
\item music {\it\romannumeral 5}, 21
\item music font 29
\item MusiCopy {\it\romannumeral 5}, 15, 42
\indexspace
\largeletter{n}
\item Nelson{,} Bruce 28
\item nested symbols 11
\indexspace
\largeletter{o}
\item {\tt O}-marker 14, 20
\item open spline 14, 20
\item optional values 5
\item origin 2
\item origin of quadrant 17
\item OSU 14
\item output device 4, 49
  \subitem  font memory 36
\item oval 
  \subitem  {\it see} ellipse 19
\indexspace
\largeletter{p}
\item {\tt P}-measure 19
\item parameters to {\TT} 17
\item Pascal 33
\item pens 20
\item phantom control points 37
\item phantoming 37
\item pixel thickness 20
\item {\tt pop} 39
\item postamble 47
\item PostScript {\it\romannumeral 6}
\item preamble 1
\item preparing a figure 2
\item primitive 2
\item primitives 17, 34
  \subitem  attributes 34
  \subitem  built-up 17
  \subitem  combining 9, 10
  \subitem  definition of 40
  \subitem  invoking 9
  \subitem  modifying attributes 34
  \subitem  names 48
  \subitem  parameters 9, 18
  \subitem  reduction of 34
  \subitem  scaling; rot\-ating; trans\-lating 9
\item printer's points 19
  \subitem  measurement 2
\item programmer's hook 43
\item programs making figures 22
\item {\tt push} 39
\indexspace
\largeletter{r}
\item {\tt R}-marker 16, 22
\item reference point 17
\item rotation 9, 10
  \subitem  using degrees measurement 10
\item running {\TT} 3
\indexspace
\largeletter{s}
\item {\tt S}-measure 19
\item Saxe{,} James 28
\item scaled points 19
\item scaling 9
\item slurs 15, 21, 30, 31
  \subitem  {\it see also} ties 16
\item space 1, 3, 51
\item space macros 1
\item special 38
\item {\tt special} 2
\item specials 2, 17, 27, 46, 57
  \subitem  case insensitivity 6
  \subitem  handling 33
  \subitem  handling by {\TT} 27
  \subitem  punctuation 6
  \subitem  typing in 6
\item {\tt spline} 35
\item {\bf spline} 18
\item spline 
  \subitem  B-spline 6
  \subitem  Cardinal 6
  \subitem  Catmull-Rom 5
  \subitem  control-points 5
  \subitem  coordinates 5
  \subitem  default 5
  \subitem  example 5
  \subitem  Interpolating B-spline 6
  \subitem  ttspline 6
\item spline curves 5
\item splines 
  \subitem  attributes 35
  \subitem  B-spline 35
    \subsubitem  example 15
  \subitem  basis 20, 35
  \subitem  Cardinal 35
    \subsubitem  example 14
  \subitem  Catmull-Rom 35
    \subsubitem  example 14
  \subitem  clamping 35
  \subitem  closed 14
  \subitem  closure 20
  \subitem  default basis 20
  \subitem  default closure 20
  \subitem  default type 30
  \subitem  families 30
  \subitem  Interpolating B-spline 
    \subsubitem  example 15
  \subitem  interpolation 30
  \subitem  inversion 30
  \subitem  open 14
  \subitem  types 20
  \subitem  typesetting 47
  \subitem  use in simulating 37
\item staff-size 16
\item staff lines 37
\item staff sizes 29, 37
\item Standard{,} Paul {\it\romannumeral 1}
\item sub-figures 11
\item subdivision of splines 47
\item surprise errors 24
\item symbol 
  \subitem  {\it see} figure 22
\indexspace
\largeletter{t}
\item {\tt T}-marker 10, 12
\item {\TeX} {\it\romannumeral 5}, 1, 3, 17, 34, 51
\item \TeX book 9
\item {\TeX} commands 17, 51
\item {\TT} {\it\romannumeral 5}
  \subitem  {\tt .tlog} log-file 23
  \subitem  error handling 23
  \subitem  error messages 24
  \subitem  error recovering 23
  \subitem  how to read manual {\it\romannumeral 6}
  \subitem  name {\it\romannumeral 5}
  \subitem  parameters 17
  \subitem  serious problems 26
  \subitem  signatures 43, 48
  \subitem  simple problem 25
\item {\tt textyl.tex} file 1
\item TFM information 27
\item Thick-n-thin spline 6
\item ties 15, 21, 30
  \subitem  and ttsplines 16
  \subitem  example 16
  \subitem  {\it see also} slurs 16
\item {\bf tieslur} 21
\item {\tt tieslur} 35
\item tieslur 
  \subitem  attributes 35
  \subitem  clamping 35
  \subitem  example 16
  \subitem  implementation 31
  \subitem  pen type 21
  \subitem  relation to ttsplines 35
  \subitem  representation 34
  \subitem  thicknesses 16, 21
  \subitem  vector type 21
\item tranforms 
  \subitem  figure-level 22
\item {\bf transform} 21
\item transformations 
  \subitem  {\it see } transforms 21
\item transforms 9
  \subitem  additiveness 22, 42
  \subitem  concatenation 11
  \subitem  example 10
  \subitem  figure-level 41
  \subitem  mirroring 10
  \subitem  no-op 10
  \subitem  parameters 10, 21
    \subsubitem  format 21
    \subsubitem  requirement 21
  \subitem  rotating 9
  \subitem  scaling 9
  \subitem  sub-figures 11
  \subitem  top-level 42
  \subitem  translation 9
\item transform to DVI space 39
\item translating 9
\item {\tt ttspline} 35
\item ttspline 6, 31
  \subitem  clamping 35
  \subitem  defaults 6
  \subitem  example 6
  \subitem  line thicknesses 31
  \subitem  thicknesses 6, 18
\item {\bf ttspline} 18
\item tyling {\it\romannumeral 5}, 33, 37, 46
\item {\tt tyl} name-string 2
\item typing in special strings 6
\indexspace
\largeletter{u}
\item {\tt U}-marker 14, 20
\item units of measure 19
\item Unix 33
\item user's view 17
\item user intuition 21
\indexspace
\largeletter{v}
\item {\tt V}-marker 20
\item vector-types 20
  \subitem  default 20
\item vector font 20, 28
  \subitem  computing dimensions 28
  \subitem  cvec 29
  \subitem  dimensions 28
  \subitem  mapping function 44
  \subitem  path invariance 45
  \subitem  pen-types 29
  \subitem  pens 
    \subsubitem  example 29
  \subitem  pixelsize 29
  \subitem  range of angles 28
  \subitem  sizes 29
  \subitem  types 29
\item vectors 
  \subitem  typesetting with 28
\item vertical pen 20
\indexspace
\largeletter{w}
\item {\tt W}-marker 22
\indexspace
\largeletter{x}
\item {\tt X}-marker 18
\indexspace
\largeletter{z}
\item Zapf{,} Hermann {\it\romannumeral 1}
\end{theindex}

\end{document}