%---------------cut here: beginning of psbsamp.tex file----------------
% psbsamp.tex V-1.1: a sample use of the psbox macros from Plain TeX.
% TeX & print this file.
% Requested in the same directory:
%    psbox.tex: a TeX file containing the macros
%    box.ps: an Illustrator EPSF file containing a sample dull drawing.
%2345678 1 345678 2 345678 3 345678 4 345678 5 345678 6 345678 7 3456789
%
\input psbox.tex   % 'told you it was necessary!
%
% Uncomment the line corresponding to your TeX system:
%\psfortextures%     For TeXtures on the Macintosh
%\psfordvitops %     For the DVItoPS converter for TeX on IBM mainframes
 \psfordvips   %     For DVIPS converter on VAX and UNIX
%\psforoztex   %     For OzTeX shareware on the Macintosh
%
% These are just to get a mini verbatim:
  \def\\{\hbox{$\backslash$}}
  \edef\{{\hbox{$\{$}}
  \edef\}{\hbox{$\}$}}
\def\section#1{\nobreak\medskip\centerline{\frameit{1pt}{3pt}{\hbox{#1}}}
  \medskip}
\def\LaTeX{{\rm L\kern-.36em\raise.3ex\hbox{a}\kern-.15em
    T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}
%
%
\line{\hfil
\frameit{1pt}{2pt}{\frameit{0.5pt}{3pt}{\hbox{PS}}}
\frameit{1pt}{2pt}{\frameit{0.5pt}{3pt}{\hbox{BOX}}}
\hfil \llap{by Jean Orloff (e-mail:}}
\line{\hfil ORLOFF @ SURYA11.CERN.CH)}
\bigbreak
This sample file demonstrates the use of a set of macros for including
Encapsulated PostScript (EPSF) graphics into any \TeX\ document (Plain
\TeX, Plain-based macros like Harvmac, Phyzzx,... or \LaTeX). The aim of
using the combination \TeX+PostScript is for crossing oceans along
e-mail cables (since both use pure text format for saving files) and
yet get a machine independent result when printed from any
computer on any PostScript printer\footnote{*}{You might think of
sending directly the PostScript description of the whole document, but
this would mean sending 15 times more caracters and moreover
forbidding your correspondant to make any correction to the
manuscript.}.

To get this to work, you first need to produce an EPSF file. This
is different from an usual postscript file. (For instance, with CERN's
package PAW/HIGZ, the output device specified in the metafile is -111
for simple postscript and -113 for EPSF). You can always check if you
succeeded by looking at your EPSF file: it should start with {\tt\%!}
and somewhere contain a line like:
$$
\hbox{\tt\%\%BoundingBox: llx lly urx ury\hfil}
$$
where llx \& lly (urx \& ury) are positive integer coordinates of the
lower-left (upper-right) corners of the smallest rectangle enclosing
your graphics. If all else fails, you still have the opportunity of
adding such a line by hand: you might then want to know that
coordinates are given in ``Big Points'' (1in=72bp)\footnote{**}{
Not to be confused with ``Points'' (1in=72.27pt): inventing units
related by such crazy factors as 72.27/72 definitely is a perverse and
deeply immoral sport!} from the bottom left
corner of the printed page. You can always visualize the corresponding
{\tt\%\%BoundingBox} using {\tt\\frameit} (see below). Once you have a
good EPSF file, you should save it in the same directory as the \TeX{}
file in which you want to insert your graphics.

Now you're ready for inserting. Here is how to do. In the
beginning of your \TeX{} file,
\item{1)} type {\tt\\input psbox.tex}
  in order to load the relevant \TeX{} macros;
\item{2)} type one of the following:
$$
\vbox{\halign{\tt\\psfor#\hfil&\qquad#\hfil\cr
textures& for TeXtures on the Macintosh\cr
dvitops&  for IBM mainframes dvi to postscript converter DVITOPS\cr
dvips&    for Unix, PC and VAX dvi to postscript converter DVIPS\cr
oztex&    for OzTeX shareware soft on the Macintosh.\cr}}
$$
The default is TeXtures which has the advantage showing you a screen
preview if you managed to save it along with your EPSF file (this is
possible on the Mac from Adobe Illustrator, Mathematica, ...). If you
get the wrong postscript converter, you will just get extremely
white(!) figures but the formatting of your text will be exactly the
same.

\noindent You can then get your graphics where you want in the text by
just typing:
$$
\hbox{\tt\$\$\\psbox\{box.ps\}\$\$}
$$
And this is what you get:
$$
\psbox{box.ps}
$$
The {\tt\\psbox\{EPSFilename\}} macro makes a \TeX{} \\vbox
having the right size to contain the graphics and issues a \\special
command for the postscript printer to put the EPSF graphics at the
right place.

\section{Scalings}
You can moreover use Postscript to resize your graphics. This can be
done via the {\tt\\psboxto} macro: here you
specify the dimensions and \TeX{} uniformly scales the graphics to fit
entirely in the given box. For instance
$$\eqalign{\hbox{\tt\$\$}
&\hbox{\tt\\boxit\{\\psboxto(3cm;7cm)\{box.ps\}\}}\cr
&\hbox{\tt\\boxit\{\\psboxto(7cm;3cm)\{box.ps\}\}\$\$}\cr}
$$
gives
$$
\boxit{\psboxto(3cm;7cm){box.ps}}
\boxit{\psboxto(7cm;3cm){box.ps}}
$$
(we have here materialized the \TeX boxes by the
{\tt\\boxit\{anybox\}} command which can be useful for
boxing not only psboxes, but any kind of text boxes. To
control the thickness of the line and to have some white space
between your box and it's framing, you can use
{\tt\\frameit\{LineThickness\} \{WhiteSpaceThickness\} \{\\anybox\}}).

If you specify one zero dimension in {\tt\\psboxto}, you get a box
proportional to the natural one for your drawing, but with the scale
specified by the non zero dimension:
$$\eqalign{\hbox{\tt\$\$}
&\hbox{\tt\\boxit\{\\psboxto(3cm;7cm)\{box.ps\}\}}\cr
&\hbox{\tt\\boxit\{\\psboxto(7cm;3cm)\{box.ps\}\}\$\$}\cr}
$$
yields
$$
\boxit{\psboxto(3cm;0cm){box.ps}}
\boxit{\psboxto(0cm;3cm){box.ps}}
$$
Altenatively, you can specify a scale factor%
\footnote{**}{This way you are sure to get exactly the same size for
the \TeX{} and EPSF box: with {\tt\\psboxto}, you can have the \TeX
box 1/1000 too large because of rounding errors unavoidable for
compatibility reasons}
($\times1000$ in the usual \TeX{} way):
$$
\hbox{\tt\\psboxscaled\{250\}\{box.ps\}:}\psboxscaled{250}{box.ps}
$$
On certain occasions, you may want to offset the graphics from what
would naturally come out. All you have to do is type something like
$$\hbox{\tt\\psxoffset=0.3cm\\psyoffset=12pt}
$$
which will {\bf raise} the figure by 12pt and shift it to the right
by 0.3cm. These dimensions get reset after each use of
{\tt\\psbox...} so you should type this just before the one you want
to offset. These dimensions also get scaled together with the figure if
you use {\tt\\psboxto or \\psboxscaled}:
$$\psxoffset=0.3cm\psyoffset=12pt\boxit{\psboxto(3cm;0cm){box.ps}}
\kern2 cm
\psxoffset=0.3cm\psyoffset=12pt\boxit{\psboxto(1cm;0cm){box.ps}}
$$
Since a {\tt\\psbox} is a true \TeX box, nothing prevents you to
have \psboxto(0cm;1em){box.ps} it in the middle of a line..(?) More
seriously, if you want your graphics to be as large as possible, you
can type
$$\hbox{\tt\$\$\\psboxto(\\hsize;0cm)\{box.ps\}\$\$}
$$
which gives
$$\psboxto(\hsize;0cm){box.ps}
$$
\section{Annotations}
For certain figures, you might want to add something on top of the
graphics (eg. a greek letter to name an axis, or other math symbols you
use in the text). This is what
{\tt\\psannotate\{\\psbox...\}\{annotation\}} was made for. For
instance if you type
$$\hbox{\tt\$\$
\\psannotate\{\\psbox\{box.ps\}\}\{\\fillinggrid\\at(3\\pscm;1\\pscm)\{A
sample at.\}\}\$\$}
$$
you get
$$\psannotate{\psboxto(10cm;3cm){box.ps}}
{\fillinggrid   \at(3\pscm;1\pscm){A sample at.}}
$$
This example displays the 2 possible annotations:
{\tt\\at((xdim;ydim)\{annotation text\}} will place {\tt annotation
text} xdim to the right of, and ydim higher than the current point
without actually moving  it (this may prove useful in other
circumstances). The dimensions may be expressed in any valid \TeX{}
unit, but here we used {\tt\\pscm} meaning scaled centimeters in order
for the annotation to keep the same relative position inside the
figure, whatever rescaling you later on might do. In order to help you
in the tedious task of determining the position of your annotations, you
can use {\tt\\fillinggrid} as one particular annotation. This will
produce a 1\\pscm by 1\\pscm grid that roughly fills your figure. You
will of course have to delete these in your final document\footnote{*}
{To suppress all these grids at once in your final document, you may
type {\tt\\let\\fillinggrid=\\relax} just after the line where you
{\tt\\input psbox.tex}.}.

\section{Figure environment for Plain\TeX}
If you have many large figures, the probability that \TeX{}
barks at you about ``overfull or underfull vbox...'' becomes
significant, because you give it a hard time trying to cut pages
into a document that has many large unbreakable units. To
overcome this problem, La\TeX{} users simply have to type:\hfil\break
{\tt\\begin\{figure\}[hbt]\hfil\break
\\begin\{center\}\\mbox\{\\psbox...\}\\end\{center\}\hfil\break
\\caption\{Some caption\}\hfil\break \\end\{figure\}\hfil\break}
In Plain\TeX{} you should use
{\tt\\centinsert\{\\psbox...\}} instead of {\tt\$\$\\psbox...\$\$}.
This will get your graphics precisely where you typed it except if
there is not enough room in the current page, in which case you'll get
it on top of the next one.

However, you will then probably want to have a caption, in case your
graphics and explanatory text get separated. You should then
use {\tt\\pscaption\{\\psbox...\}\{caption\}}, for instance
$$\hbox{\tt
\\centinsert\{\\pscaption\{\\psboxto(6cm;0cm)\{box.ps\}\}%
\{Figure 1: this is... purposes.\}\}
}$$

\noindent in order to get:
\centinsert{\pscaption{\psboxto(6cm;0cm){box.ps}}
{Figure 1: this is probably
the most stupid caption I can think of but it can still be useful for
illustrative purposes.}}
%
If your caption is short, it will automatically get centered:
$$\pscaption{\psbox{box.ps}}{\bf Figure 327.}
$$
\section{Errors}
\message{The following error messages should not frighten you, they
are intentional tests. Just continue and see what comes out!}
If \TeX{} cannot find the file you specified, you will
get the following output: $${\psbox{NotToBeFound.ps}}$$
On the other hand, an existing file which is not EPSF will produce:
$${\psbox{psbsamp.tex}}$$
\bye
