summaryrefslogtreecommitdiff
path: root/dviware/psprint/vms/userguide.tex
blob: 492f7ba132b456cf9d615cf1eae5a5bfbbb96754 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
% LaTeX source for PSPRINT User Guide.
% System-dependent details are indicated by the string "SYSDEP".
% Cross references are indicated by the string "XREF".
% Feel free to make modifications applicable to your site.

\documentstyle[11pt]{article}

\nofiles                       % no auxiliary output

% make sure leading/trailing spaces work correctly in \verb
{\obeyspaces\gdef {\leavevmode\null\enskip\null}}

% 1 inch margins at left and right:
\oddsidemargin=0in
\evensidemargin=0in
\textwidth=6.25truein          % A4 paper is 8.25in wide

% 1 inch margins at top and bottom:
\headheight=0pt
\headsep=0pt
\topmargin=0in
\textheight=9.7in              % A4 paper is 11.7in high

\parindent=0pt
\parskip=\medskipamount
\renewcommand\labelitemii{ }   % don't use en-dash in nested itemize
\itemsep=0pt

\def\DVItoVDU{DVIto\kern-.15em VDU}
\def\aligneddots{\leaders\hbox to .75em{\hss.\hss}\hfill}

\begin{document}

\vspace*{\fill}

\begin{center}
\Huge\bf PSPRINT User Guide\\ [3mm]
\normalsize\bf Version 3.1 for VAX/VMS\\
\bf Andrew Trevorrow, October 1989
\end{center}

\bigskip
\bigskip

The PSPRINT command drives a variety of PostScript printers
and can be used to print a DVI file (produced by \TeX\ or \LaTeX),
a raw PostScript file, or an ordinary text file.
The currently supported printers include the Apple LaserWriter,
the Linotronic~300 and DEC's PrintServer~40.

\bigskip
\begin{center}
\bf Contents
\end{center}

                                       % XREF: check that page #s are up-to-date
Temporary Files              \aligneddots\ 1\\
\TeX\ Output                 \aligneddots\ 1\\
PostScript Output            \aligneddots\ 1\\
Text Output                  \aligneddots\ 1\\
Command Qualifiers           \aligneddots\ 2\\
Error Messages               \aligneddots\ 5\\
Including Global PostScript  \aligneddots\ 6\\
Using PostScript Fonts       \aligneddots\ 6\\
Using PostScript Graphics    \aligneddots\ 7

\vspace*{\fill}

\thispagestyle{empty}

\newpage
\setcounter{page}{1}

\subsection*{Temporary Files}

For each type of input file, PSPRINT will create a temporary file
in \verb|sys$scratch|.  % SYSDEP
This file has a \verb|.tmp| extension and
contains the PostScript commands required to print your job.
It is automatically deleted once printed;
you will only need to delete it if you decide to delete your job
from the print queue.

\subsection*{\TeX\ Output}

PSPRINT looks for a DVI file by default.  To print \verb|foo.dvi|, simply type:
\begin{center}
\verb|$ psprint foo|
\end{center}
PSPRINT will translate \verb|foo.dvi| into
a temporary PostScript file called \verb|foo.tmp|.
The DVI and \TeX\ page numbers are displayed as each page is translated.
(The order in which pages are translated depends on the PostScript
device being used.)
If no errors are found, the temporary file is automatically sent to the
appropriate queue where it is printed (and then deleted).

\subsection*{PostScript Output}

PostScript is a complete programming language with a powerful set of operators
for manipulating text and graphics.  A PostScript program is an ordinary text
file.  If you give it a name like \verb|foo.ps| then sending
it to the printer is simple:
\begin{center}
\verb|$ psprint foo.ps|
\end{center}
If you decide to use some other file extension you'll have to add the
\verb|/ps| qualifier.
The final section in this document   % XREF
describes how to merge a PostScript file with a \TeX\ source file.
People who want to write PostScript programs will need to get the
{\sl PostScript Language Reference Manual\/} and the
{\sl PostScript Language Tutorial and Cookbook}.  Both books are by
Adobe Systems Incorporated and published by Addison-Wesley.

\subsection*{Text Output}

To print a normal text file, just use any file extension except
\verb|.dvi| or \verb|.ps|:
\begin{center}
\verb|$ psprint foo.lis|~~~or~~~\verb|$ psprint foo.dat|~~~or~~~\dots
\end{center}
The output is {\em not\/} collated.
By default you get 66 lines per page, and any lines more than 80
characters long are truncated.  The \verb|/landscape| qualifier will
rotate the paper so that you can have lines up to 132 characters long
(but only 50 lines per page).
The \verb|/two| and \verb|/wide| qualifiers are variants of \verb|/text|
that use a smaller font to fit two logical pages on each sheet of
paper.

Type `\verb|psprint foo.ps /text|' if you want to print a PostScript file.

\newpage

\subsection*{Command Qualifiers}

The PSPRINT command can be followed by a variety of qualifiers:
\begin{itemize}
\item \verb|/device=printer_type| ---
tells PSPRINT which type of PostScript printer to use.
The currently supported \verb|printer_type| values are:
   \begin{itemize}
   \item
   \verb|LW  | --- for an Apple LaserWriter (the default)\\  % SYSDEP
   \verb|LINO| --- for a Linotronic~300\\
   \verb|PS40| --- for DEC's PrintServer~40
   \end{itemize}
If you have access to more than one type of printer, it may be a good idea
to define some symbols in your \verb|login.com| file:
   \begin{itemize}
   \item
   \verb|$lw*print   :== psprint/dev=LW     ! for LaserWriter|\\
   \verb|$lino*print :== psprint/dev=LINO   ! for Linotronic 300|\\
   \verb|$ps40*print :== psprint/dev=PS40   ! for PrintServer 40|
   \end{itemize}
\end{itemize}

Some qualifiers only apply to certain devices:
\begin{itemize}

\item \verb|/nobanner| (only if \verb|/device=LW| or \verb|LINO|) ---
prevents PSPRINT producing a banner page.

\item \verb|/manualfeed| (only if \verb|/device=LW|) ---
assumes you want to manually feed paper into the LaserWriter.
As soon as the printer sees your job it will wait for you to feed in each
sheet of paper (it will normally wait up to a minute).

\end{itemize}

These qualifiers only take effect if \verb|/device=LINO|:
\begin{itemize}

\item \verb|/lowres| ---
prints a DVI file at low resolution (635 dots per inch).
By default, \TeX\ output on the Linotronic is printed at 1270 dots per inch.
The temporary file created by PSPRINT will typically be very large.
Using \verb|/lowres| reduces both the size of the temporary file
(by roughly three quarters) and the likelihood of memory problems.
The print quality will of course be poorer but you'll
probably need a magnifying glass to see the difference.

\item \verb|/size=page_size| ---
sets the Linotronic page size and orientation.
Possible \verb|page_size| values are
\verb|A4P| (the default), \verb|A4L|, \verb|A5P|, \verb|A5L|,
\verb|B5P|, \verb|B5L| and \verb|A3L|.
The \verb|P| stands for portrait and the \verb|L| for landscape.
(Don't confuse the landscape orientation with \verb|/landscape| which rotates
the output within the page image, regardless of the \verb|/size| value.)
The portrait orientations are less wasteful of paper.

\item \verb|/cutmarks| ---
produces small cut marks at the corners of the page image
on Linotronic output.
\verb|/cutmarks| is the default; use \verb|/nocutmarks| to suppress them.

\end{itemize}

The following five qualifiers override PSPRINT's assumptions
about the format of the input file based on the given file specification:
\begin{itemize}
\item \verb|/dvi | --- for a DVI file.
\item \verb|/ps  | --- for a PostScript program.
\item \verb|/text| --- for an ordinary text file.
\item \verb|/two | ---
like \verb|/text| but the output is formatted so that two ``pages''
(both 60 lines by 80 columns) appear on each sheet of paper.
\item \verb|/wide| ---
like \verb|/text| but the output is formatted so that two wide ``pages''
(both 60 lines by 132 columns) appear on each sheet of paper.
\end{itemize}

\newpage

Some qualifiers can only be used with a DVI file:
\begin{itemize}

\item \verb|/pages=first:final| --- selects a subrange of pages for printing.
\verb|first| and \verb|final| can select either DVI page numbers
(positive integers) or \TeX\ page numbers.

A \TeX\ page specification is of the form \verb|[i0.i1...i9]| where
\verb|i0| to \verb|i9| are integers separated by periods and represent the
10 counter values that \TeX\ stores with each DVI page.
Any number of these integers may be absent and trailing periods may be omitted.
An absent integer will match any value in the corresponding counter.
Many DVI pages may match a particular \TeX\ page specification;
if \verb|first| is a \TeX\ page then the {\em lowest\/}
matching DVI page is selected, and if \verb|final| is a \TeX\ page then
the {\em highest\/} matching page is selected.

Assuming \TeX\ generated the 5 DVI pages `\verb|[0] [1] [2.1] [2.2] [3]|',
here are some examples of how you could use \verb|/pages|:
   \begin{itemize}
   \item
   \verb|$ psprint foo /pages=2     | --- prints the 2nd DVI page
                                          (\TeX\ page \verb|[1]|)\\
   \verb|$ psprint foo /pages=:4    | --- prints the first four pages\\
   \verb|$ psprint foo /pages=4:    | --- prints the last two pages\\
   \verb|$ psprint foo /pages=[2]   | --- prints \verb|[2.1]| and \verb|[2.2]|\\
   \verb|$ psprint foo /pages=1:[2] | --- prints the first four pages\\
   \verb|$ psprint foo /pages=[2.2]:| --- prints the last two pages
   \end{itemize}
Note that \verb|first| and \verb|final| are optional; they default to
the first and last DVI pages respectively.
Omitting `\verb|:final|' entirely sets \verb|final| equal to \verb|first|.

\item \verb|/increment=i| ---
prints pages $f,f+i,f+2i,f+3i,\ldots,f+ni$, where
$f$ is the first DVI page selected (either 1 or the start
of a \verb|/pages| subrange) and $f+ni$ is less than or equal to
the final DVI page selected.

The primary use of \verb|/increment| is to simplify the printing of a document
on both sides of the paper.  For example, if \verb|foo.dvi| has 8 pages then the
following steps will produce a double-sided document on a LaserWriter:
   \begin{enumerate}
   \item
   \verb|$ psprint foo /inc=2 /nobanner /rev| --- prints DVI pages 7, 5, 3, 1
   \item
   Remove the 4 pages from the output tray and carefully put them back
   into the input cassette so that page 1 remains face up and its
   top edge goes into the printer first.
   (If \verb|foo.dvi| had 7 pages then you would only need to remove the
   top 3 pages from the output tray.)
   \item
   \verb|$ psprint foo /inc=2 /pag=2: /norev| --- prints DVI pages 2, 4, 6, 8
   \end{enumerate}
Note that the use of \verb|/reverse| with \verb|/increment| has no effect on
{\em which\/} pages are printed; it simply changes the {\em order\/} in
which they are done.

If you intend doing a lot of two-sided printing then it is a good idea to
define some symbols in your \verb|login.com| file to avoid making mistakes:
   \begin{itemize}
   \item
   \verb|$ oddpages  :== psprint/pag=1:/inc=2/rev/nobanner|\\
   \verb|$ evenpages :== psprint/pag=2:/inc=2/norev|
   \end{itemize}

\item \verb|/reverse| or \verb|/noreverse| ---
forces PSPRINT to print pages in descending or ascending order respectively.
By default PSPRINT prints DVI pages in ascending order.

\item \verb|/magnification=n| ---
overrides the DVI magnification; \verb|n| is a positive integer 1000 times
the desired magnification and should match one of \TeX's \verb|\magstep|
values (see chapter 4 of {\sl The \TeX book\/}).

\item \verb|/stats| ---
shows statistics on the rules, fonts, characters and \verb|\special| commands
used on each page.

\item \verb|/conserve_vm| ---
forces PSPRINT to conserve the printer's virtual memory at the
expense of creating a larger output file (character bitmaps will be
downloaded more often).
If \verb|/device=LINO| then \verb|/conserve_vm| is the default;
if \verb|/device=LW| or \verb|PS40| then \verb|/noconserve_vm| is the default.

\item \verb|/units=xx| ---
sets the units of dimensions displayed in some PSPRINT messages
(e.g., if the page is off the paper).
\verb|xx| can be one of:
   \begin{itemize}
   \item
   \verb|in| --- for inches (the default)\\   % SYSDEP
   \verb|cm| --- for centimetres (2.54\,cm = 1\,in)\\
   \verb|mm| --- for millimetres (25.4\,mm = 1\,in)\\
   \verb|pt| --- for points (72.27\,pt = 1\,in)\\
   \verb|pc| --- for picas (1\,pc = 12\,pt)\\
   \verb|bp| --- for big points (PostScript's default units; 72\,bp = 1\,in)\\
   \verb|px| --- for pixels (depends on resolution of printer)
   \end{itemize}

\item \verb|/hoffset=dimen| and \verb|/voffset=dimen| ---
allow you to shift the printed location of each page.
For example, \verb|/hoffset=-0.5in| would
shift each page half an inch to the left.
A \verb|dimen| is any integer or real number, possibly negative, followed
by a two-letter unit (the same as for \verb|/units|).

\end{itemize}

The following qualifiers also apply to a DVI file, but are really for
system wizards.  Most users should never need to use them since their
default values are normally defined once at installation time and
are presumably correct:
\begin{itemize}

\item \verb|/resolution=n| ---
specifies the resolution of your printer in pixels per inch;
\verb|n| must be a positive integer.

\item \verb|/xsize=dimen| and \verb|/ysize=dimen| ---
specify the paper size.
PSPRINT will check that each DVI page fits within the given dimensions.
A \verb|dimen| is any positive integer or real number followed by a
two-letter unit (the same as for \verb|/units|).

\item \verb|/psprefix=string| ---
defines the TFM file name prefix that PSPRINT uses to recognize a
PostScript font.

\item \verb|/tfm_directory=directory| ---
specifies the location of TFM files for PostScript fonts.

\item \verb|/font_directory=directory| ---
specifies the default directory from which PSPRINT
gets all its character bitmap information.
This might come in handy if you are using Metafont
to create your own fonts or modify existing ones.
For example, the following commands
tell PSPRINT to first search for fonts in the current directory (\verb|[]|)
before looking in the default directory
(assumed to be \verb|tex_disk:[tex.pk]|):
   \begin{itemize}
   \item
   \verb|$ define dirlist [],tex_disk:[tex.pk]|\\
   \verb|$ psprint foo.dvi /font="dirlist:"|
   \end{itemize}
Use \verb|/stats| to see the default font directory at your site.

\item \verb|/dummy_font=file| ---
indicates the naming convention and format of all font files.
The given file must represent an unmagnified font.

\end{itemize}

\newpage

The \verb|/prep| qualifier only applies to a DVI or PS file:
\begin{itemize}

\item \verb|/prep=file| ---
specifies a file to be included at the end of the normal prologue.
This file will normally be a modified version of Apple's Laser Prep.
If no file is specified then a default file,
\verb|tex_ps:laserprep70.ps|, is included.
Such a file is needed to support PostScript files created by pressing Command-F
after clicking OK in the Print dialogue of most Macintosh applications.
The PostScript code generated by this method relies on the
procedures defined in Laser Prep, so if you want to include such code
(via a \verb|\special| command for instance) you need to use \verb|/prep| to
make sure the appropriate Laser Prep code is loaded first.

Command-F files contain comments at the top that indicate which version of
Laser Prep they require.  Try and choose the nearest matching Laser Prep file
provided with PSPRINT; see \verb|tex_ps:laserprep*.ps|.
These files contain comments describing how they were created, just in case
you need to generate a new version.

\end{itemize}

The remaining qualifiers apply to all types of input files:
\begin{itemize}

\item \verb|/landscape| --- specifies landscaped output
\begin{picture}(10,7)
\put(0,0){\framebox(10,7){}}
\end{picture}\,,
instead of the default portrait output
\begin{picture}(7,10)
\put(0,0){\framebox(7,10){}}
\end{picture}\,.
If~a DVI file, PSPRINT will check each page to make sure it fits
within the rotated paper.

\item \verb|/delete| --- deletes the input file after printing.

\item \verb|/notify| --- notifies you when the print job has finished.
On the PrintServer~40 you'll also see any PostScript messages,
a particularly useful feature when debugging a PostScript program.

\item \verb|/copies=n| --- specifies up to 100 copies.
Use of this facility is not encouraged.  Note in particular that
copies of a multiple-page document will {\em not\/} be collated.

\item \verb|/note=string| --- includes a note on your banner page.
For example, to get your output put in box 99, just type
`\verb|psprint/note="box 99" ...|'.

\item \verb|/queue=string| --- overrides the default queue used by PSPRINT\@.
(Some sites may have more than one printer of the same type).

\item \verb|/output=file| --- sends the PostScript code generated by PSPRINT
to a file rather than to a printer.  Since some of this code is device-specific
you should only send the file to a PostScript printer of the type that
PSPRINT intended to use.

\end{itemize}

\subsection*{Error Messages}

If PSPRINT detects one or more errors while translating a DVI file then
the temporary PostScript file is automatically deleted and nothing
is printed --- not even a banner page.
The sort of errors you are most likely to see include:
\begin{itemize}
\item
\verb|Page off paper (paper is ...| ---
the current page contains material beyond one or more paper edges.
Use \DVItoVDU\ to see where the problem lies.
\item
\verb|Couldn't open font file: ...| ---
your DVI file uses a font at a non-existent size.
Try a different font magnification in your source file.
\item
\verb|Couldn't open \special file: ...| ---
PSPRINT could not locate the given \verb|\special| file.
Check the file's spelling and/or directory location.
\end{itemize}
Error messages apply to the most recently displayed DVI/\TeX\ page.
Any message that does not make sense probably indicates some sort of bug.
Please save a copy of the input file and report the problem to your
local \TeX nician.

If your DVI file uses a large number of fonts or a few very large fonts then
you might get an error page with the message ``\verb|VMerror|''.
This indicates that PostScript's virtual memory has been exhausted,
and the rest of your job will be flushed.
This problem is unlikely to worry most people, particularly on the
PrintServer~40 which has much more VM than the LaserWriter or Linotronic.
If the problem does occur, there are a few things you can try:
\begin{enumerate}
\item
On a LaserWriter or PrintServer, use \verb|/conserve_vm|
or print a few pages at a time.
\item
On a Linotronic, use \verb|/lowres|.
(\verb|/conserve_vm| is the default for this device.)
\end{enumerate}
If you are sending your own PostScript program then an error should
produce some sort of message on the printed output.
If you are using a PrintServer~40 then specify \verb|/notify| to get all
PostScript messages sent back to your terminal.

\subsection*{Including Global PostScript}

When printing a DVI file, PSPRINT looks in your current directory for
a file called \verb|global.ps|.
If it exists then its contents will be included after the normal prologue.
The example \verb|global.ps| file supplied in \verb|tex_ps|
shows how to get the word ``DRAFT'' printed in the background on every page.

\subsection*{Using PostScript Fonts}

PSPRINT allows the use of PostScript fonts within a \TeX\ or \LaTeX\ document.
Such fonts can be used at any desired size and no character bitmaps need
to be downloaded since the shape information is resident in the printer.
The necessary typesetting information required by PSPRINT is extracted
from TFM files (\TeX\ Font Metric files).
A TFM file name beginning with ``\verb|ps-|'' is used to indicate a resident
PostScript font.   % SYSDEP; determined by /psprefix value in psdvi.cld

Each type of PostScript printer provides a different set of fonts.
To be able to use a particular PostScript font you need to know the
name of its corresponding TFM file and whether it actually exists in
the printer you want to use.  For each PostScript printer currently
supported there exists a file containing just such information ---
see \verb|tex_ps:*_fonts.ps|.

PSPRINT also uses these files, so you can be reasonably confident
about the validity of their contents.
To print a list of the PostScript fonts available in your printer you can type
the command `\verb|psprint tex_ps:fontlist.ps|'.

There are some important differences between PostScript fonts and
the Computer Modern fonts normally used with \TeX:
\begin{enumerate}
\item
PostScript fonts usually contain up to 256 characters, with many
empty locations.  Computer Modern fonts can also contain up to 256 characters
but typically use only the first 128 locations (with very few empty).
\item
When a PostScript font is scaled to the same design size as a CM font
it tends to look darker and larger.  You need to be a bit careful
when mixing the two font designs.
\item
The standard \TeX\ commands for accents and foreign letters need to be
redefined for a PostScript text font.  The file \verb|tex_ps:pstext.tex|
contains the required macro definitions; note that a few commands
(\verb|\j|, \verb|\aa|, \verb|\AA|, \verb|\t|) cannot be used at all.
Another file, \verb|tex_ps:psfonts.tex|, inputs these macros and illustrates
the use (and abuse) of PostScript fonts in a \TeX\ document.
\end{enumerate}

\subsection*{Using PostScript Graphics}

Creating figures and illustrations with \TeX\ is very difficult.
Although it is theoretically possible to place small dots
anywhere on a page and build up an arbitrarily complex picture,
time and memory limitations make such a scheme impractical.
(\LaTeX\ provides a \verb|picture| environment, but it is very inefficient
and only suitable for small, simple diagrams.)
PSPRINT allows you to merge PostScript graphics with \TeX\ or \LaTeX\@.

Let's assume you have a file called \verb|fig.ps| that contains
suitable PostScript commands for generating some sort of figure.
To include this figure in a \TeX\ or \LaTeX\ document, just type
`\verb|\special{fig.ps}|' after leaving sufficient space:
\begin{verbatim}
    % in a TeX source file                        % in a LaTeX source file
    \midinsert                                    \begin{figure}[ht]
       \vskip 3in                                    \vspace{3in}
       \special{fig.ps}                              \special{fig.ps}
       \centerline{Figure 1: Pie Sales}              \caption{Pie Sales}
    \endinsert                                    \end{figure}
\end{verbatim}
It may take a little practice to position the figure correctly.
When you print a raw PostScript file (e.g., `\verb|psprint fig.ps|')
the default origin is at the bottom left corner of the paper.
However, when you include this file in a \TeX\ document the origin is
automatically moved to the position of the \verb|\special| command.

\verb|\special| can appear almost anywhere in your source file.
It behaves like an invisible box of zero height and width.
\TeX\ simply stores the given argument in the DVI file along with the current
page position.  PSPRINT interprets the argument as a file name and then
includes this file in the information sent to the printer.
(The included file is bracketed by \verb|save| and \verb|restore| commands
to prevent any interference to the surrounding typesetting commands.)

You can move the figure about by shifting the \verb|\special| position,
or by including a \verb|translate| command in the PostScript file.
The latter option is faster because you don't have to run \TeX\ again.
For example, `\verb|72 36 translate|' at the start of \verb|fig.ps| would
move the figure 1\,in right and 0.5\,in up
(PostScript's default units are ``big points'' where 72\,bp = 1\,in).

Alternatively, you may prefer to place your figure at an absolute position
on the paper (i.e., at the same position produced by `\verb|psprint fig.ps|').
Simply include an \verb|initgraphics| command at the start of \verb|fig.ps|.
The position of the \verb|\special| command then becomes irrelevant;
just make sure it's on the right page!

The hardest part of the scheme is creating the PostScript file in the first
place.  You have a couple of choices:
\begin{enumerate}
\item
Learn enough PostScript to be able to draw your own figures.
You'll need to get the PostScript books mentioned on page~1.
\item
Use another program to create the graphic image
and then convert it into a corresponding PostScript file.
The Macintosh is a particularly nice machine for this purpose.
Many applications can either dump an EPS (Encapsulated PostScript) file,
or you can use the Command-F method mentioned earlier in the discussion
of PSPRINT's \verb|/prep| qualifier.
\end{enumerate}

\newpage

Let's look at a few examples.  The public directory \verb|tex_ps| contains
the \LaTeX\ source file for this User Guide, as well as a few PostScript
files used to produce the figures below.
These figures were created by calling
\begin{verbatim}
    \special{tex_ps:piechart.ps}
    \special{tex_ps:greybox.ps}
    \special{tex_ps:random.ps}
\end{verbatim}
at appropriate points in the source file.
The directory location is given with each PostScript file
so you can print a copy of the User Guide from any directory.
If the \verb|\special| command is only given a file name then
PSPRINT assumes the file is in your current directory.

\begin{figure}[h]   % produce figure here
    \vspace{2.1in}
    \special{tex_ps:piechart.ps}        % origin at left margin of text
    \caption{Pie Sales}
\end{figure}

\begin{figure}[h]   % produce figure here
    \begin{center}
       \begin{minipage}{4in}
          \special{tex_ps:greybox.ps}   % origin at top left of minipage box
          The text in this paragraph box was typeset by \LaTeX\@.
          The shaded rectangle was created by PostScript.
       \end{minipage}
    \end{center}
    \bigskip        % leave additional room for shaded box
    \caption{Shaded Text Box}
\end{figure}

\begin{figure}[h]   % produce figure here
    \begin{center}
       \setlength{\unitlength}{1in}
       \begin{picture}(1.3,1.3)   % dimensions match axis lengths in random.ps
          \put(0,0){\special{tex_ps:random.ps}}   % origin at bottom left corner
       \end{picture}
    \end{center}
    \caption{Random Dots}
\end{figure}

PSPRINT allows arbitrary PostScript text to appear after the file name in a
\verb|\special| command.  At least one space must be used to terminate the file
name; further characters are included as a new line at the {\em start\/} of
the given file.  There is a limit of about 200 characters.
For example, `\verb|\special{fig.ps 2 1 scale}|' could be used to double
the width of the figure in \verb|fig.ps|.
Note that it is possible to include the same PostScript file more than once,
but with a different starting line each time.

\end{document}