\documentstyle[11pt,ifthen,guidemacros,twoside]{article}
\nonstopmode
%$Header: /afs/sipb/project/doc/iness-ps/RCS/post.tex,v 0.14 92/08/04 23:41:51 tlyu Exp Locker: tlyu $
\special{header=set-example.PS} 
\stdsizes
\setcounter{secnumdepth}{3}
\renewcommand{\thesection}{\arabic{section}}
\renewcommand{\thesubsection}{\thesection.\arabic{subsection}}
\renewcommand{\thefigure}{\arabic{figure}}
\renewcommand{\theequation}{\arabic{equation}}
\input /afs/sipb.mit.edu/user/tlyu/lib/tex/macros/nuke.tex
\def\RCS$#1${{#1}} %get RCS version without going into math mode
\def\PS{PostScript}
\def\GS{Ghostscript}

\title{\begin{center}
\vspace*{200bp}
\hspace*{1mm}\special{psfile=funky-owl.PS hoffset=-100}\hspace*{1mm}
\vspace{0.5cm}
\end{center}
{\Huge Inessential \PS\protect\footnote{Copyright \copyright\ 1992 Student
Information Processing Board, Massachussetts Institute of Technology}\\}
{\small ( \RCS$Revision: 0.14 $)}\\ {\Huge DRAFT COPY\\BLEED ON ME!}}

\author{The Student Information Processing Board\\ \small Kevin Iga\\
\small Tom Yu}

% Project begun {5/21/91}
% Revision 0 - K. Iga 5/21/91

% Trademarks and copyright symbols follow...

\def\SIPB{SIPB}
\def\LPS{Digital LPS40}
\def\LN{Digital LN03R}
\begin{document}
\maketitle
\vfill\newpage
\pagenumbering{roman}
\tableofcontents
\listoffigures
\pagenumbering{arabic}

\section{Introduction}

\subsection{What is \PS?}

\PS\ is a versatile page description language primarily used to
communicate with printers and other graphics output devices.  In
particular, it is the language understood by the public laser printers
on Athena, the \LN\ and the \LPS.  \PS\ was developed by Adobe Systems
Incorporated as a standardized device-independent page description
language.  As a result, a document written in \PS\ will look almost
exactly the same on any device capable of interpreting and creating
images from \PS.

Devices called {\it raster devices\/} are what are normally used to
display \PS.  Raster devices display images by forming them in a grid of
rectangular {\it pixels\/} (picture elements).  Some examples of raster
devices are a computer monitor, or a laser printer.  Raster devices form
the image of pixels by scanning horizontal lines of pixels, and
vertically covering an area with these horizonal lines to form a grid of
pixels.

\subsection{Programs that output \PS}

Many programs are available that will write \PS\ programs for you.  For
printing plain text, there is enscript.  For writing formatted text, you
can use \LaTeX\ together with {\tt dvips} or {\tt dvi2ps}, {\tt scribe},
{\tt ez}, {\tt troff}, and others.  For drawing diagrams, {\tt idraw}
and {\tt xfig} are available.  For drawing graphs, there are xmath and
matlab.  Although you may not have heard of these programs before, they
all can generate \PS\ programs which will then be printed out, thus
sparing you the chore of writing in raw \PS.

\subsection{Why program in raw \PS?}

So why would anyone want to program in \PS\ directly?  Often, you will
find that unnecessary, because all of the programs mentioned earlier
allow you to do most of the work that you will want to see on paper in
\PS.  They make it easy, and most of the time those things are what
you need to do.  But every once in a while, you will want to make a
fancy poster with shadowed letters.  Or you will want to make a map with
words in many different orientations.  Or you will want to draw
perspective line drawings according to some mathematical formula.  Or,
for some reason, the software out there just cannot get the effect you
want on paper.  Or maybe you just want to impress your friends.

There are several good ways to view \PS.  \PS\ is a powerful computer
programming language, just as genuine and powerful as C or Fortran.  It
is a tool for producing images, both on a video screen and of paper.  It
is an art form, allowing you to express yourself in ways that Leonardo
da Vinci would never have dreamed of.
\subsection{What this document does and does not offer}
This document will teach you a few of the basics of \PS, especially with
regard to Athena.  It does not promise to make you a wizard, although
after a short time some people may believe you are one.

If you have never used Athena before, you should probably read {\it
Getting Started on Athena}\footnote{This document is provided for no
charge.}, available from Graphic Arts (in the basement of Building 10),
and the {\it Inessential Guide to Athena}\footnote{This, and all other
SIPB documentation, is available at no charge}, available in the SIPB
office.  You should also have a little fun on Athena, just so you are
comfortable with the environment.  You might also try some of the
programs that format files in \PS\ to become familiar with printing on
Athena.

There is no way that this document can tell you everything about \PS.
There already exist many good books on \PS, and this document will make
no effort to replace any of them.  On the other hand, this document will
explain enough of \PS\ to enable you to do a number of simple, yet
visually impressive displays.
\section{Previewing \PS}
\subsection{\tt gs}
Available on Athena is a program called \GS, which is an interactive
\PS\ previewer.  To run it, enter the following commands in an xterm
window:
\begin{verbatim}
athena% add gnu
athena% gs
\end{verbatim}
\noindent A large blank white preview window will appear, and the
following message will appear {\it in your original xterm window}.
\begin{verbatim}
Initializing... done.
Ghostscript 2.3 Copyright (C) 1990, 1991 Aladdin Enterprises,
   Menlo Park, CA.  All rights reserved.
Distributed by Free Software Foundation, Inc.
Ghostscript comes with NO WARRANTY: see the file COPYING for details.
GS>
\end{verbatim}
The {\tt GS>} is the prompt for the \GS\ interpreter.  This interpreter
will behave just like the \PS\ interpreter in a typical \PS\ laser
printer in many ways, only at a much lower resolution (i.e. somewhat
``chunkier'').  You can type \PS\ commands at the {\tt GS>} prompt.  To
exit \GS, you type {\tt quit} at the {\tt GS>} prompt.  To run a file
that is on disk under \GS, you can type the following:
\begin{verbatim}
GS>(foo.PS) run
\end{verbatim}
\noindent to run the file {\tt foo.PS}.  You can also start up \GS\ with
a filename, as in {\tt gs foo.PS}.

One of the many good things about \GS\ is that it is interactive.  You
can type commands directly at it and it will behave almost exatcly like
a \PS\ printer will, executing the commands as it receives them.  This
way, you can experiment with \PS\ without depleting your print quota or
the Amazon rain forest.  There are a few subtle differences (besides the
resolution) between the output that you will see on the preview window
of \GS\ and the output that you will see if you actually send the
commands to the printer.  These will be explained as we come to them.

\subsection{\tt dxpsview}

A \PS\ previewer which is much superior to \GS, is {\tt dxpsview}.  This
program has two major disadvantages.  It is not interactive, and it only
runs on DECstations.  You can start it up simply by typing the command
{\tt dxpsview\&} in an xterm.  A window will appear, and you can use the
menus there to select a file to preview.  One of the major advantages is
that its rendering of fonts is much more accurate, since the actual font
rendering code is provided by Adobe.

\section{Printing out \PS}

On athena, the most common way to print files is by using the {\tt lpr}
command.  For example, to print out the file {\tt foo.PS} to the printer
{\tt bias}, you would use the following command:
\begin{verbatim}
athena% lpr -Pbias foo.PS
\end{verbatim}
Now you probably know that you can send plain text to the printer in
exactly the same way.  You may now wonder how the printer tells the
difference between plain text to be excuted and a \PS\ program to be
run.  Actually, it turns out that the program which actually talks to
the printer (called the {\it printer daemon}) checks the first two
characters of the file.  If the first two characters of the file are
{\tt \%!}, often pronounced ``percent bang'', then the daemon sends the
file off to the printer without changes.  If, on the other hand, the
file does not start with {\tt \%!}, the daemon runs the file through a
simple program which converts it into \PS\ that the printer can then
understand.  The characters {\tt \%!} will be ignored by the printer,
since any line that begins with the {\tt \%} character is a comment in
\PS.

As a result, any \PS\ that you write and expect to be printed properly
as a \PS\ page description must begin with the characters {\tt \%!}, or
the printer daemon will happily print out the text of the program
instead of sending it to the printer directly.

\section{Stacking the deck}

One very important concept in \PS\ is that it follows {\it
Reverse-Polish Notation\/} ({\it RPN\/}), which may be familiar to you
if you use a Hewlett-Packard calculator.  It is the notation that tells
you to add 2 and 3 by:

\begin{verbatim}
2 3 add
\end{verbatim}

This notation is also called {\it postfix notation}, and is used in
several other computer languages, notably FORTH.  If you have not seen
this before, you should learn it.  The basic concept to keep in mind
here is that of a stack.

Imagine a stack of plates.  Plates can be added to the top, and must be
removed only from the top of the stack.  Think now of the stack as an
abstract model, capable of holding many objects.  Each time you enter an
object, it gets ``pushed'' onto the top of the stack.  Removing objects
can only be done from the top of the stack, and is called (surprise!)
``popping''.

One useful thing to have when you are starting to play with the stack is
something to print out the current contents of the stack.  You can do
this in \GS\ by using the {\tt pstack} command.  Using the previous
example, this is what happens when you use \GS.
\begin{verbatim}
GS>2 3
GS<2>pstack
3
2
GS<2>add
GS<1>pstack
5
\end{verbatim}
\noindent Notice that the prompt for \GS\ changes when you have objects
on the stack, and that the contents of the stack are listed from top to
bottom.  The output from {\tt pstack} goes to the xterm, not to the
preview window.  There is no way to get {\tt pstack} to work over a
print spooler.

Operators will remove a certain number of operands in the stack and then
act upon them.  Some operators will also push some results on the stack.
For example, the {\tt add} operator would take the numbers 2 and 3, add
them together, and push the result, 5, onto the stack.

Other simple arithmetic operators that are handy to know include {\tt
sub}, {\tt mul}, and {\tt div}.  For example:
\begin{verbatim}
GS>10 5 div
GS>pstack
2
\end{verbatim}
There are a large number of calculations and operations that you can do
with the stack.  For example, to discard the top value from the stack,
you can use {\tt pop}.
\begin{verbatim}
GS>2
GS<1>pstack
2
GS<1>pop
GS>pstack
GS>
\end{verbatim}
There is another command that you can use to exchange the top two
objects on the stack, the {\tt exch} command.
\begin{verbatim}
GS>1 2
GS<2>pstack
2
1
GS<2>exch
GS<2>pstack
1
2
\end{verbatim}
You can also duplicate the top object on the stack, using the {\tt dup}
command.
\begin{verbatim}
GS>5
GS<1>pstack
5
GS<1>dup
GS<2>pstack
5
5
\end{verbatim}

On the more esoteric side, it is possible to {\tt roll} things about on
the stack using the syntax {\it x y\/} {\tt roll}, where $x$ is the
number of items to roll and $y$ is how much to roll it.  Positive $y$
rolls up on the stack, negative $y$ rolls down.
\begin{verbatim}
GS>1 2 3 4 5
GS<5>5 1 roll
GS<5>pstack
4
3
2
1
5
\end{verbatim}
\section{Get moving---graphics basics}

Now that you are familiar with some of the basic syntaax of \PS, you are
probably wondering how to get \PS\ to draw graphics.  There are a number
of key concepts that you must grasp before you can effectively program
using the graphics operators of \PS.

\subsection{The coordinate system}
\PS\ uses a cartesian coordinate system, with the default origin at the
lower-left hand corner of the paper.  The $x$ axis points to the right,
and the $y$ axis points to the top, by default.  There are 72 units in
an inch, known as {\it points\/} in printers' lingo.\footnote{Actually,
there are not exactly 72 points in an inch, but then again the
definition of a point is not that standard.  For more details, see
Chapter 10 of {\it The \TeX book}} You do not have to use the default
coordinate system if you do not want to.  In fact, it is possible to
use any rectangular coordinate system that you can derive from this one
using linear two-dimensional transformations.  The coordinate system
that you normally use when programming in \PS\ is called {\it user
space}.  At this point, in user space, no device-dependent
characteristics apply yet.  One way to visualize user space is as an
imaginary page upon which you can draw a path with a ``pen''.

\subsection{Path construction}
What \PS\ calls this ``pen'' is the {\it current point}.  At first, the
location of the current point is not defined.  To begin a path, you must
define the current point by using the {\tt moveto} operator.  You supply
the $x$ and $y$ coordinates for the current point to be moved to in user
space, like {\it x y\/} {\tt moveto}.  For example, {\tt 72 144 moveto}
will move the current point to a location 1 inch to the right and 2
inches up from the lower-left corner of the page.

After establishing the location of the current point, you can go on to
construct a {\it current path} in user space by using operators called
{\it path constructors}.  Almost all of the path constructors require
that a current point be defined, or they will produce an error.  You can
think of the current path as the path traced out by this imaginary pen
as it moves around in user space.

\subsection{Painting}

After you have a curent path in user space, you must render it onto the
{\it current page}, which is a virtual image of what will end up on the
physical page.  The current page uses a coordinate system called {\it
device space}, where each pixel is one unit on a side.  This coordinate
system is device dependent, and essentially, the current page is as
memory image of every pixel that winds up on the physical page.  You can
draw onto the current page by using {\it painting operators}.  Most of
the more useful painting operators take paths from user space and render
them onto the current page, although some of them will go directly to
the current page without using anything from user space.  These include
{\tt stroke} and {\tt fill}, which respectively draw a line along a path
and fill a path.  These will be described in more detail later on.  Most
commands that operate on the current path to render it onto the current
page will clear the path and reset the current point.

\subsection{The physical page}

Although you can draw images onto device space, they will not appear
until you copy device space to a physical page.  You use the {\tt
showpage} operator to do this.  Not all \PS\ previewers will wait until
you execute {\tt showpage} before they show what is being drawn.  {\tt
dxpsview} will show you the physical page, but there is a menu option to
get it to show you the current page as it is constructing it.  \GS\ will
show you what the image in device space is, rather than what the
physical page is.  \GS\ will display the following when it encounters a
{\tt showpage}.
\begin{verbatim}
GS>showpage
>>showpage, press <return> to continue<<
\end{verbatim}
\noindent and then clear the page after you press {\tt <return>}.

\nuke
Now that you are familiar with some of the basic syntax of \PS, you are
probably wondering how to actually do the graphics.  \PS\ has several
commands used to draw on the page.  One thing that is relatively
important to \PS's idea of graphics is the concept of a {\it current
point}.  When you first start drawing, there is no current point.  Many
of \PS's drawing primitives require there to be a current point, and
will be very unhappy if there isn't one.

One good way to think of the current point is to imagine it as a pen.
You start off not knowing where the pen is.  You use a {\tt moveto}
command to tell it where to go.  Other path constructors either move
this pen around, or cause it to draw things.  No matter what you do with
this pen, it always draws with opaque ink.  This means that if you draw
a white line through a black square, it will still show up.

The coordinate system that \PS\ uses is a rectangular one, with the $x$
axis on the short edge of the paper and the $y$ axis on the long edge of
the paper.  The location $(0,0)$ is at the lower-left hand corner of the
page, unlike in most graphics systems that you may have heard of, where
the origin is in the upper-right hand corner of a graphics screen.
There are 72 units in an inch.  These units are historically known as
{\it points} in printers' lingo.\footnote{Actually, there aren't exactly
72 points in an inch, but then again the definition of a point isn't
really that standard.  For more details, see Chapter 10 of {\it The \TeX
book}}
\endnuke
\subsection{\tt moveto}

To actually start drawing, you have to set the current point.  The {\tt
moveto} command will set the current point.  The syntax for this command
is {\it x y\/} {\tt moveto}.  This will move the current point to the
coordinates $(x,y)$.  You may be wondering what coordinate system these
are in.  It so happens that the default coordinate system is cartesian,
with the origin at the lower-left hand corner of the paper, the $x$ axis
along the short edge of the paper, and the $y$ axis along the long edge
of the paper.  For example, this command:

\begin{verbatim}
72 144 moveto
\end{verbatim}

\noindent will cause the current point to be set to a point one inch
right and two inches up from the lower-left hand corner of the page.

\subsection{\tt lineto}

Drawing line segments is almost as simple.  To do so, you can use the
{\tt lineto} command, whose syntax looks like this: {\it x y\/} {\tt
lineto}.  What this will do is draw a line segment from the current
point to the point $(x,y)$ and set the current point to $(x,y)$.

You will encounter an error if you attempt to use a path contruction
operator without first setting the current point.  For example, \GS\
will do something like the following if you execute a {\tt lineto}
without first doing a {\tt moveto}.

\begin{verbatim}
GS>100 100 lineto
Error: /nocurrentpoint in --lineto--
Operand stack:
    100 100
Execution stack:
    operator_403588 --nostringval-- --nostringval-- operator_409f10
--nostringval-- --nostringval-- false --nostringval-- --nostringval--
--nostringval--
Dictionary stack:
    337/401 3/200
\end{verbatim}

\subsection{\tt stroke}

If you tried doing stuff with {\tt moveto} and {\tt lineto} in \GS, you
probably noticed that nothing got drawn.  There is a good reason for
this.  The {\tt moveto} and {\tt lineto} commands do not actually do any
drawing.  Instead, they update something that \PS\ keeps track of that
is called the {\it current path}.  To actually put something on the page
you have to do something with the current path.  One of the things you
can do is to {\tt stroke} the path.  For example:

\begin{verbatim}
100 100 moveto 200 300 lineto stroke
\end{verbatim}

\noindent will end up drawing a diagonal line near the lower-left part
of the page.  The {\tt stroke} command also clears the current path,
which is usually what you want it to do.

\subsection{\tt showpage}

Of course, all that {\tt stroke} does is update the {\it current page},
which
\PS\ keeps around until you do something with it.  Usually what you want
to do with the current page is print it out, so you can use the {\tt
showpage} command to actually cause the current page to be output from
the printer, and also causes the current page to be erased, which is
usually what you want to do.

One thing worth noting is that the {\tt showpage} command under \GS\
does not actually do anything.  What \GS\ does instead is pause and wait
for you to press {\tt return} before continuing, displaying the
following message:

The reason for this is that \GS\ does not show the page when you do a
{\tt showpage}, rather, it displays the current page as it is being drawn
(each time you use {\tt stroke} or {\tt fill}, for exmple).

\subsection{\tt closepath}

You may notice something when you try to draw a closed path.  Even if
you finish the path with the same point that you start it off with, the
corner may look a bit strange.

\begin{figure}[htb]
\vspace*{2.2in}
\centerline{
\special{"
tlyuDict begin
0.2 0.2 0.5 in 0 [
(100 100 moveto)
(400 100 lineto)
(400 400 lineto)
(100 400 lineto)
(100 100 lineto)
(40 setlinewidth)
(stroke)
(showpage)
] 11 -2 in 2.2 in setarray
end 
}}
\caption{Drawing a box, not using {\tt closepath}\label{fig:nonclose}}
\end{figure}

If you look at Figure~\ref{fig:nonclose} carefully, you will notice that
the lower-left hand corner of the square does not close completely.  The
reason for this is that the ends of a path do not extend beyond their
endpoints.  Lines do have a real thickness, and the thickness of the
lines in Figure~\ref{fig:nonclose} have been increased to exaggerate the
problem.  To get around such a situation, you should use the {\tt
closepath} command to finish off your path, instead of using an explicit
{\tt lineto} to end it.

\begin{figure}[htb]
\vspace*{2.2in}
\centerline{
\special{"
tlyuDict begin
0.2 0.2 0.5 in 0 [
(100 100 moveto)
(400 100 lineto)
(400 400 lineto)
(100 400 lineto)
(closepath)
(40 setlinewidth)
(stroke)
(showpage)
] 11 -2 in 2.2 in setarray
end}}
\caption{Another box, using {\tt closepath}\label{fig:close}}
\end{figure}

The {\tt setlinewidth} command sets the line width to be used in the
next {\tt stroke} command.  You should be able to see what happens if
you try to close the path without using the {\tt closepath} command.
Compare this to Figure~\ref{fig:close}, which does use the {\tt
closepath} command.  The two major advantages of using {\tt closepath}
are that you do not get messy joins on closed shapes, and you do not have
to remember where the path started out.

\section{Less filling!  Tastes great! ({\tt fill} and other fun)}

\begin{figure}[htb]
\vspace*{1.1in}
\centerline{
\special{"
tlyuDict begin
0.1 0.1 0.5 in 0 [
(100 100 moveto)
(300 100 lineto)
(300 300 lineto)
(100 300 lineto)
(fill)
(showpage)
] 11 -2 in 1.1 in setarray
end
}}
\caption{Example of using {\tt fill}\label{fig:fill}}
\end{figure}

You can do other things with paths than just {\tt stroke} them.  It is
also possible to {\tt fill} them.  In this case, on a path where you
might want to use {\tt closepath} if you were using {\tt stroke}, the
use of {\tt closepath} is normally not necessary.  As a matter of fact,
you can leave out the closing segment of a path that you are going to
{\tt fill}, since it gets put in anyway.  The way you fill a path is
with the {\tt fill} command.  For an example, see Figure~\ref{fig:fill}

\begin{figure}[htb]
\vspace*{1.1in}
\centerline{
\special{"
tlyuDict begin
0.1 0.1 0.5 in 0 [
(100 100 moveto)
(300 100 lineto)
(300 300 lineto)
(100 300 lineto)
(0.75 setgray)
(fill)
(showpage)
] 11 -2 in 1.1 in setarray
end
}}
\caption{Example of using {\tt setgray}\label{fig:gfill}}
\end{figure}

Another useful thing is the ability to control the level of gray which
something gets filled with.  You can do this using the {\tt setgray}
command.  The syntax for this command is {\it x\/} {\tt setgray}, where
$x$ is a number between 0 and 1 specifying the amount of gray.  A value
of 0 signifies black, and a value of 1 signifies white.  For example, a
square filled at 0.75 can be seen at Figure~\ref{fig:gfill}.

Of course, it is also possible to use the {\tt setgray} command with
something like the {\tt stroke} command.  Incidentally, one thing you
should watch out for is that large areas of black are not good for the
printer.  At best, you end up wasting toner.  At worst, you can actually
damage the printer.  In addition, large areas of black do not get
printed very well, even if they do not happen to damage the printer.

\begin{figure}[htb]
\vspace*{90bp}
\special{psfile=path.ps}
\caption{The purpose of {\tt stroke} and {\tt showpage}\label{fig:path}}
\end{figure}

\begin{figure}[htb]
\vspace*{2.2in}
\centerline{
\special{"
tlyuDict begin
0.2 0.2 0.5 in 0 [
(0.75 setgray)
(100 100 moveto)
(300 100 lineto)
(300 300 lineto)
(100 300 lineto fill)
(1 setgray)
(200 100 moveto)
(300 200 lineto)
(200 300 lineto)
(100 200 lineto fill)
(showpage)
] 11 -2 in 2.2 in setarray end
}}
\caption{Example of the opaque nature of \PS\ graphics operators\label{fig:opaque}}
\end{figure}

Now that we have introduced most of the fundamental commands in \PS,
Figure~\ref{fig:path} is a quick summary of what \PS\ does with the
path, the current page, and the physical page.  Also, take a look a
Figure~\ref{fig:opaque} to see an example of how the \PS\ graphics
commands behave like they are using opaque ink.

\section{Running around in circles ({\tt arc} and {\tt arcn})}

There are several commands in \PS\ which are useful in drawing circles
or arcs.  These behave differently depending on whether or not the
current point is defined.  One of these is {\tt arc}.  The syntax for
this one is {\it xcenter ycenter radius start end\/} {\tt arc}.  For
example:

\begin{verbatim}
300 300 100 0 360 arc
\end{verbatim}

will draw a complete circle centered on the point (300,300), and having
a radius of 100 points.  The other arc-drawing command is {\tt arcn}.
The only difference between the two is the direction in which they draw
the arc.  The {\tt arc} command draws counter-clockwise, while the {\tt
arcn} command draws clockwise.  If, however, there is a current point
defined when you call {\tt arc} or {\tt arcn}, there will be a line
segment connecting the previous current point and the starting point of
the arc.

For an example of using {\tt arc} with a current point defined, see
Figure~\ref{fig:arccp}.  For an example of using {\tt arcn} without the
current point defined, see Figure~\ref{fig:arcn}.  Notice that the
$start$ and $end$ parameters specify the starting and ending angles,
specified counter-clockwise from the positive $x$ axis.

\begin{figure}[htb]
\vspace*{1.1in}
\centerline{
\special{"
tlyuDict begin
0.1 0.1 0.5 in 0 [
(300 300 moveto)
(300 300 200 0 90 arc)
(stroke)
(showpage)
] 11 -2 in 1.1 in setarray
end
}}
\caption{Using {\tt arc} with the current point defined\label{fig:arccp}}
\end{figure}

\begin{figure}[htb]
\vspace*{1.1in}
\centerline{
\special{"
tlyuDict begin
0.1 0.1 0.5 in 0 [
(300 300 200 0 90 arcn)
(stroke)
(showpage)
] 11 -2 in 1.1 in setarray
end
}}
\caption{Using {\tt arcn} without the current point defined\label{fig:arcn}}
\end{figure}

\section{A word is worth a thousand pictures---setting text}

At this point, you may be wondering how to do things like get text on
the page.  There are a number of things that you must do before you can
get started drawing text.  One of them is to select a font, ie.
typeface, in which to draw the text.  The next thing is to select a size
in which to draw the text.  For example, you would use the following to
select twelve-point Times-Roman:

\begin{verbatim}
/Times-Roman findfont 12 scalefont setfont
\end{verbatim}

The {\tt findfont} command actually goes and fetches the font from
wherever it lives, and returns it.  Most fonts start out scaled to one
point: not a very useful size.  The {\tt scalefont} command takes a font
and a point size, and proceeds to scale the font to that point size.
Finally, the {\tt setfont} command actually tells \PS\ to use that font
as its current font.

To actually put text on the page, you must first have a current point
defined.  The {\tt show} operator takes a string and displays it.  For
example:

\begin{verbatim}
100 100 moveto (This is a test) show
\end{verbatim}

Notice that strings are enclosed in parentheses.  You can include
balanced parentheses within strings, but if you want to include
unbalanced parentheses you should precede them with a backslash, like
this:

\begin{verbatim}
(some unbalanced \(parentheses\()
\end{verbatim}

Figure~\ref{fig:show} is an example of using the {\tt show} command to
display text.

\begin{figure}[htb]
\vspace*{2.2in}
\centerline{
\special{"
tlyuDict begin
0.2 0.2 0.5 in 0 [
(100 100 moveto)
(/Times-Roman findfont)
(144 scalefont setfont)
((testing) show)
(showpage)
] 11 -2 in 2.2 in setarray
end
}}
\caption{Example of using {\tt show} to display text\label{fig:show}}
\end{figure}

Not all fonts are available everywhere.  Typically a laser printer will
have the fonts Times-Roman, Times-Italic, Times-Bold, Times-BoldItalic,
Courier, Helvetica, Helvetica-Oblique, Helvetica-Bold,
Helvetica-BoldOblique, and Symbol.  There are a number of other fonts
out there, but these are the most widely available.

\section{Moving in with relatives ({\tt rmoveto} and {\tt rlineto})}

There are ways to construct path by specifying coordinates relative to
the current point.  One of the advantages of this is that you do not
have to constantly remember where the current point is, or if you want
to draw something that might get drawn in a variety of positions around
the page.  The commands to do this are {\tt rmoveto} and {\tt rlineto}.
You use these commands much as you would use {\tt moveto} and {\tt
lineto}.  For an example of how to use {\tt rlineto}, see
Figure~\ref{fig:rlineto}.

\begin{figure}[htb]
\vspace*{1.65in}
\centerline{
\special{"
tlyuDict begin
0.15 0.15 0.5 in 0 [
(100 100 moveto)
(100 0 rlineto)
(0 100 rlineto)
(-100 0 rlineto)
(closepath)
(stroke)
(showpage)
] 11 -2 in 1.65 in setarray
end
}}
\caption{Using {\tt rlineto}\label{fig:rlineto}}
\end{figure}

\section{{\tt def} awareness---defining stuff and why you should}

\PS\ has a command that lets you define things.  This can prove to be
very useful when you find yourself repeating command or numbers often.
The {\tt def} command is used to define a variable.  It turns out that
\PS\ variables and procedures are practially indistinguishable.  The way
that you use the {\tt def} command is {\it key value\/} {\tt def}.  For
$key$, you should specify something begining with the {\tt /} character.
$value$ can be just about anything.  For example:

\begin{verbatim}
/pi 3.1415926 def
\end{verbatim}

\noindent will define a variable that can be referenced by using {\tt
pi}.

On the other hand, you can also define procedures in \PS\ by using a
slightly different syntax.  One thing that people use rather often is
the following:

\begin{verbatim}
/inch {72 mul} def
\end{verbatim}

\noindent This is rather convenient, because instead of writing
something like {\tt 72 72 moveto}, you can use this: {\tt 1 inch 1 inch
moveto}.  Curly braces are special to \PS.  When the \PS\ interpreter
sees an open curly brace, it enters a {\it deferred execution mode},
where commands are not executed, but rather saved up to be assembled
into one object later.  When the interpreter reaches the close curly
brace, it takes everything between the two curly braces and treats it as
one {\it procedure object}.  Procedure objects are used for things other
than defining procedures, but we can get to that later.

You ``pass'' values to a procedure through the stack.  Procedures really
do not take parameters or arguments as you may be familiar with from
other programming languages.  If you are going to use a number of things
many times within a procedure, you can use something like:

\begin{verbatim}
/foo exch def
\end{verbatim}

\noindent to define the top thing on the stack to the key {\tt foo}.  At
this point, if you understand how stack operators work, you should be
able to understand why this works.

One thing to watch out for is that \PS\ {\it does not} have any form of
lexical scoping, as many languages do.  There is no way to make local
variables without making them on the stack in some
way.\footnote{Actually, this is not true.  It is possible to define
local variables by using dictionaries, but we won't talk about that
here.  Look in the Red Book if you want more details.}

\section{Front and center---how to center text}

\PS\ has a command that will let you find out how much the current point
will travel while displaying a string.  This is the {\tt stringwidth}
operator.  The syntax for it is {\it string\/} {\tt stringwidth}.  It
does take $string$ off of the stack, so you should have another copy
somewhere, either defined to something, or another copy on the stack.
It returns both the $x$ and the $y$ widths for the string.  Usually, the
$y$ width does not mean much to you, so you can safely discard it.
Unlike what you may think it is, it has nothing to do with how tall the
string is.

For example, the following procedure will take a string, an $x$ and $y$
coordinate, and center the string around it.  Note that it will not
center the string about the $y$ coordinate, but rather place its
baseline on the $y$ coordinate.

\begin{verbatim}
/center { moveto dup stringwidth pop neg 0 rmoveto show } def
\end{verbatim}

You can invoke this by using {\it string x y\/} {center}, once you have
defined it.  For an example of this, see Figure~\ref{fig:center}.

\begin{figure}[htb]
\vspace*{2.2in}
\centerline{
\special{"
tlyuDict begin
/center { moveto dup stringwidth pop 2 div neg 0 rmoveto
show } def
/inch {72 mul} def
0.2 0.2 0.5 in 0 [
(/Times-Roman findfont)
(144 scalefont setfont)
((centered) 4.25 inch 5.5 inch center)
(showpage)
] 11 -3 in 2.2 in setarray
end
}}
\caption{Example of centering text\label{fig:center}}
\end{figure}

\section{Transformers---you control the coordinate system}

You do not have to always use the coordinate system that \PS\ starts you
out with.  In fact, it is possible to apply any\footnote{This document
will not go over all possible linear transformations.  See the Red Book
for more.} linear transformation to the coordinate system that you have
at the moment and get a new one.  One thing to keep in mind is that the
only thing that changes when you alter the coordinate system is the
coordinates; the current path, the current point, as well as anything
that has already been set on the current page, remain unaltered by the
transformation.

\subsection{\tt scale}

One of the many things that you can do is to scale the coordinate system
by some arbitrary amount in both $x$ and $y$ directions.  You can also
use a negative scaling factor to cause something to be drawn in a mirror
image.  The syntax for this is {\it x y\/} {\tt scale}, where $x$ is the
amount to scale in the horizontal direction and $y$ is the amount to
scale in the vertical direction.  For example, the following:

\begin{verbatim}
2 2 scale
\end{verbatim}

\noindent scales the coordinate system uniformly in both directions.

\subsection{\tt translate}

The {\tt translate} command moves the origin of the coordinate system to
a new location.  The syntax is {\it x y\/} {\tt translate}, where $x$
and $y$ are the horizontal and vertical displacements to move the
origin.  For example, the following:

\begin{verbatim}
4.25 inch 5.5 inch translate
\end{verbatim}

\noindent will move the origin of the coordinate system to the center
of the page.

\subsection{\tt rotate}

\begin{figure}
\vspace*{2.2in}
\centerline{
\special{"
tlyuDict begin 0.2 0.2 0.5 in 0 [(100 100 moveto) (30 rotate)
(/Times-Roman findfont) (144 scalefont setfont) ((rotation!) show)
(showpage)] 11 -2 in 2.2 in setarray end }}
\caption{Example of rotating text\label{fig:rot}}
\end{figure}

You can also rotate the coordinate system about its origin.  The syntax
for this is {\it theta\/} {\tt rotate}, where $theta$ is the angle, in
degrees, to rotate the coordinate system counter-clockwise around the
origin.  For example, the following will rotate the coordinate system
$30^\circ$ counter-clockwise:

\begin{verbatim}
30 rotate
\end{verbatim}

For an example of rotating text, see Figure~\ref{fig:rot}.

\subsection{landscape mode}

A quick way to get a landscape mode (where the coordinate system is
oriented so that the long side of the paper is the $x$ axis) is to
combine {\tt translate} and {\tt rotate}, as follows:

\begin{verbatim}
90 rotate 0 -8.5 inch translate
\end{verbatim}

\section{Saving Massachusetts (or any graphics state)}

\PS\ has a concept of a {\it graphics state}, which consists of a number
of parameters that stay mostly the same as long as you are on the same
page.  Most of the graphics state gets reset when you execute a {\tt
showpage}.  The graphics state consists of things like the current path,
the current transformation, gray value, line width, font, and several
other things that we have not mentioned yet.\footnote{There is a
complete list of things in the graphics state in the Red Book.} Anyway,
it is possible to save and restore this graphics state.  One common
reason to do this is to reuse a path for more than one thing.  The
command to save a graphics state is {\tt gsave}, and the command to
restore a graphics state is {\tt grestore}.  These do not return any
values on the operand stack, but rather push and pop the graphics states
from a special stack called the {\it graphics state stack}.

\begin{figure}
\vspace*{2.2in}
\centerline{
\special{"
tlyuDict begin 0.2 0.2 0.5 in 0 [(100 100 moveto) (500 100 lineto) (500
500 lineto) (100 500 lineto) (closepath gsave) (0.75 setgray fill)
(grestore) (10 setlinewidth stroke) (showpage)] 11 -2 in 2.2 in setarray
end }}
\caption{Using {\tt gsave} to save the path\label{fig:gsave}}
\end{figure}

For an example of how to use {\tt gsave} and {\tt grestore} to reuse a
path, see Figure~\ref{fig:gsave}.

\section{Where to Get More Information}

If you want more information, you can look in the {\it \PS\ Language
Reference Manual} (second edition), by Adobe Systems.  This is often
called the ``Red Book'' by \PS\ hackers.  If you want more of a
beginner's guide, you should look at the {\it \PS\ Language Tutorial and
Cookbook}, also by Adobe Systems.  This is often called the ``Blue
Book'' by
\PS\ hackers.

You can also get help by coming by the SIPB office (in room W20-557,
just outside the student center Athena cluster), or by giving us a call
at x3-7788.  We suggest that you do this if you happen to have a
complicated problem.

\section{Acknowledgments}

Kevin Iga wrote the original version of this document.  That was later
cleaned up by Dave Cho, and then later rewritten by Tom Yu.  Many useful
comments have been provided by Richard Barbalace, Mark Eichin, Sybil
Shearin, and others.  Thanks to Kevin Iga for the amusing jokes.

\section{About this document}

This document was prepered with \LaTeX, using the font
NewCenturySchlbk-Roman as a text font, and Courier as a monospaced
display font for examples.  Almost all of the figures in this document
were prepared as \PS\ inserts into the \LaTeX document.  The same \PS\
code was used to set both the graphics output of the examples as well as
to typeset the commands used to generate them.

\end{document}