%
% 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}