summaryrefslogtreecommitdiff
path: root/dviware/dvitops/dvitops.tex
blob: 524cda5b237fe700c7c5878362b24454fcb24023 (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
% $Header: /usr/jjc/dvitops/RCS/dvitops.tex,v 1.2 89/02/02 14:08:01 jjc Rel $
% this is the User Manual for DVITOPS in LaTeX format

% this macro was borrowed from the manual to Beebe's drivers
\newcommand{\namelistlabel}[1]{\mbox{#1}\hfil}
\newenvironment{namelist}[1]{%
\begin{list}{}
    {
      \let\makelabel\namelistlabel
      \settowidth{\labelwidth}{#1}
      \setlength{\leftmargin}{1.1\labelwidth}
    }
  }{%
\end{list}}
\documentstyle [11pt,a4,ps]{article}
\newcommand{\dvitops}{{\tt DVITOPS}}
\newcommand{\ps}{{\sc Post\-Script}}
\title{\dvitops\ User Manual}
\author{James Clark}
\newcommand{\error}[1]{\subsubsection{{\tt #1}}}

\begin{document}
\maketitle
\section{Introduction}
\dvitops\ translates a dvi file output of \TeX\ into \ps. It works with
both bitmap fonts and PostScript fonts. When used with the latter it
produces device-independent output.
\section{Usage}
The syntax for the \dvitops\ command is
\begin{flushleft}
{\tt dvitops} [{\it options}] {\it dvi\_file}
\end{flushleft}
You may omit the extension {\tt .dvi} from {\it dvi\_file}.
Options are delimited by the `{\tt -}' character. On MS-DOS,
they can also be delimited by `{\tt /}'. Options with no arguments
can be grouped behind a single delimiter. Option arguments that contain
white space must be enclosed in double-quotes. Option arguments
may, but need not be preceded by white space. 
The following options are currently supported:

\begin{namelist}{{\tt -h} {\it dimension}}
\item[{\tt -c} {\it ncopies}] 
Print {\it ncopies\/} copies of each page; 
note that the copies will not be collated.
\item[{\tt -h} {\it dimension}]
Horizontal offset. Position the origin {\it dimension} from the left edge
of the page; {\it dimension} must be a number followed by one of the units
of measure used by \TeX, for example {\tt1.5in}.
By default \dvitops\ positions the origin
of each page 1~inch down from and 1~inch to the right of
the upper left corner of the page.
This is the standard behaviour suggested by the Stanford \TeX\ project.
\item[{\tt -v} {\it dimension\/}]
Vertical offset. Position the origin {\it dimension} from the top of the page.
\item[{\tt -m} {\it number\/}]
This replaces the magnification in the
{\tt .dvi} file by {\it number}. This has the same effect as saying
 `\verb|\magnification=| {\it number}' in the \TeX\ file.
\item[{\tt -r}]
Reverse the order of the pages. This is useful if you have a printer
such as the Apple LaserWriter which stacks its output face up. If this
option occurs twice on the command line, pages will be in forward order.
This is useful if you include this option in the {\tt DVITOPS}
environment variable. See Section~\ref{ev}.
\item[{\tt -q}]
Work quietly; \dvitops\ will not print the numbers of pages as it
produces them.
\item[{\tt -f} {\it page}]
Select the first page to be processed;
{\it page} is specified by giving a sequence of 1 to 10 numbers or
asterisks separated by dots. For example, the specification `\verb|1.*.-5|'
can be used to refer to a page output by \TeX{} when \verb|\count0| is 1
and \verb|\count1| is $-5$.
An asterisk matches any number,
so the `\verb|*|' in `\verb|1.*.-5|' means that \verb|\count1| is ignored when
specifying the first page. If several pages match the given specification,
\dvitops\ will begin with the earliest such page in the file. The
default specification is `\verb|*|' which denotes
the page at the beginning of the file, since `\verb|*|' matches any page.
\item[{\tt -n} {\it number}]
Number of pages. Produce at most {\it number} pages.
\item[{\tt -s}]
Sort the pages by their \verb|\count0| value.
Negative numbers precede positive numbers. Negative numbers are sorted
in decreasing order, positive numbers in increasing order. Zero counts
as negative.
\item[{\tt -y} {\it kmem}]
Use at most {\it kmem\/} kbytes of printer memory for
preloading bitmap fonts.
\dvitops\ downloads the fonts that are most frequently used
in the document at the beginning. Other fonts have to be downloaded
on each page that they are used.
By default \dvitops\ will use at most 100k of the printer VM for this.
With this option it will use at most {\it kmem\/}k of VM.
\item[{\tt -p} {\it pagesize}]
This option informs \dvitops\ that {\it pagesize} paper will be used;
{\it pagesize} must be one of letter, legal, a4, b5, corresponding to the
page sizes used by standard \ps\ printers. This option does
not produce any \ps\ code to select this page size.
\dvitops\ needs to know the size of the page 
because the \ps\ origin is at the bottom of the page,
and the \TeX\ origin is at the top of the page. If you are using a
non-standard page size, you should choose the nearest standard page size
and adjust the position of the origin using the {\tt -h} and {\tt -v}
options.
\end{namelist}
See Section~\ref{ev} to find out how you can avoid having to
type in the options that you use frequently.

\section{\ps\ Fonts}
Ordinary \ps\ fonts not in pk format must have an entry in
the font directory file in order to be used with \dvitops.
This file is called {\tt dvitops.fnt}, and should be placed
in the same directory as the macro files used by \TeX.
Comments begin with a \verb|%|. They can start anywhere on the line
and continue to the end of the line.
Blank lines are ignored.
The syntax for each line is
\begin{flushleft}
{\it name} [{\it psname} [{\it encoding}]]
\end{flushleft}
{\it name} is the name of the font as it is known to \TeX, which is the same
as the name of the tfm file (with the extension {\tt .tfm} removed);
{\it psname} is the name of the font as it is known to \ps, for example
{\tt Times-Roman}. If {\it psname} is omitted it will be taken to be the same
as {\it name}.
The {\it encoding} field refers to an encoding file. An encoding file
describes an encoding vector for a font.
It should contain a list of the elements of the encoding vector
(without a preceding \verb|/|) separated by white space.
The file should have an extension of \verb|.enc|, which should be omitted
from {\it encoding}.
This field should be used in two situations:
if you created the tfm  file with the {\tt aftopl} utility,
and you specified an encoding file (with the \verb|-e| option),
or if you wish to use \dvitops\ with tfm files intended for
use with some other driver that automatically reencodes fonts.

\section{Environment variables}
\label{ev}
\dvitops\ needs to be able to find a number of different files.
It uses environment variables to do this. 
The environment variables must be all uppercase.
These environment variables all contain
lists. Elements of the list are separated by \verb|:| under UNIX
and by \verb|;| under MS-DOS.
\begin{namelist}{{\tt TEXINPUTS}}
\item[{\tt TEXFONTS}]
If this is set, it should contain a list of directories in which
\dvitops\ should search for tfm files, and encoding files.
\item[{\tt TEXINPUTS}]
If this is set, it should contain a list of directories in which
\dvitops\ should search for its text input files:
{\tt dvitops.fnt}, {\tt dvitops.pro},
and all the files referenced by \verb|\special| commands.
\item[{\tt TEXPK}]
This should be a list of prototypes of names of pk files.
A \verb|%f| in the prototype will be replaced by the name of the font
being searched for,
and a \verb|%d| by the magnification of the font in dots per inch.
\item[{\tt TEXMAGS}]
This should be a list of all the magnifications in dots per inch for which
there is some pk file.
\end{namelist}
The {\tt DVITOPS} environment variable allows you to avoid having to
type in frequently used options each time you use them.
When \dvitops\ reads its command line arguments, it types in the
value of this variable before any of the other arguments that have been
given. Thus if {\tt DVITOPS} is set to
\begin{verbatim}
-y 200 -r -p a4
\end{verbatim}
and you type
\begin{verbatim}
dvitops -f 1 user
\end{verbatim}
the effect will be the same as if you had typed
\begin{verbatim}
dvitops -y 200 -r -p a4 -f 1 user
\end{verbatim}
with the environment variable {\tt DVITOPS} unset.


\section{{\tt \char'134special} commands}
\TeX\ has a primitive \verb|\special| which allows
arbitrary text to be included in the {\tt .dvi} file.
\dvitops\ uses this to offer a variety of extra facilities.
To be recognised  by \dvitops\ the \verb|\special| must begin
with the `tag' {\tt dvitops:}. This tag is followed by a keyword and
possibly some arguments. The tag and keyword are not case-sensitive,
but the arguments are. White space is optional between the tag and the
keyword, but the keyword and arguments must be separated by white space.
A warning will be given if a \verb|\special| command with an
unrecognised tag is encountered, but it is an error if the keyword
following the {\tt dvitops:} tag is unrecognised.
\subsection{Landscape mode}
The command
\begin{verbatim}
\special{dvitops: landscape}
\end{verbatim}
will cause the page on which it occurs to be printed in landscape mode,
i.e. with the top of the page running along the long edge of the paper.
You must specify the command for each page that you want
printed in landscape mode.
\subsection{Graphics}
\label{graph}
You can include graphics in you document with the {\tt import} command.
The syntax of this command is:
\begin{flushleft}
\verb|\special{dvitops: import |{\it filename width height
{\rm[{\it option}\ldots]}}\verb|}|
\end{flushleft}
This option permits you to include a graphic in \ps\ form into the
document. There are three arguments:
{\it filename} is the name of the file containing the graphic,
{\it width} is the desired width of the graphic.
and {\it height} is the desired height of the graphic,
The {\it width} and {\it height} arguments must be specified as dimensions,
that is as a number with an optional decimal point followed by one
of the units of measure recognised by \TeX. The bottom left hand corner
of the graphic will be located at the point where the \verb|\special|
command was issued.
The graphic will be scaled so that it fits into the desired space,
but it will be scaled by the same factor horizontally
and vertically. It will be centred in any surplus
white space. This means that you do not have to know anything about the
dimensions of the graphic to be imported. \dvitops\ gets this
information from the \ps\ file. For example, Figure~\ref{elephant}
\begin{figure}[hbt]
\vspace{2in}
\special{dvitops: import picture.ps \the\textwidth 2in}
\caption{An Elephant}
\label{elephant}
\end{figure}
was produced by the \LaTeX\ commands
\begin{verbatim}
\begin{figure}[hbt]
\vspace{2in}
\special{dvitops: import picture.ps \the\textwidth 2in}
\caption{An Elephant}
\end{figure}
\end{verbatim}
\TeX\ expands \verb|\the\textwidth| to \the\textwidth, which
is the width of the text on the page. Note that the
graphic has been scaled so as to be 2~inches high and has been
centered horizontally with respect to  the text.
The file {\tt picture.ps} is the unaltered output of the
Macintosh version of Adobe Illustrator.

The \ps\ file containing the graphic should comply
with the Encapsulated Postscript Format
(EPSF) standard. EPSF files come in three flavours. The simplest
is just a text file. The first line of such a file will be:
\begin{verbatim}
%!PS-Adobe-2.0 EPSF 1.2
\end{verbatim}
This is the type of file that \dvitops\ needs. The other two
flavours contain in addition to the \ps\ text a representation
of the image that the \ps\ code will produce; one is intended
for the Macintosh environment, one for the MS-DOS environment.
In order for \dvitops\ successfully to import such a file, the
\ps\ text must be extracted from the file. 
A Macintosh EPSF file contains the \ps\ text in its data fork,
and the graphical representation in its resource fork. If such a
file is transferred to another system as a straight
binary  (not MacBinary) file, only the contents of the data fork
will in fact be transferred. Thus in order to import a Macintosh
EPSF file into \dvitops\ on another computer, it is only
necessary to transfer the file as a binary file. It may also
be necessary to change the carriage-returns which the Macintosh
uses as its line separator to whatever is used as a line separator
on the computer on which \dvitops\ is running
(carriage-return followed by line feed in MS-DOS,
line-feed in UNIX).
This method has been used successfully to import pictures produced with
Adobe Illustrator, Cricket Draw and Aldus Freehand running on a
Macintosh into \dvitops\ running under MS-DOS.

\subsection{\ps\ code}
\label{prolog}
\dvitops\ allows you to include your own \ps\ code in a document.
The \ps\ file that is output by \dvitops\ contains two sections:
a prologue and a script. The prologue contains only procedure
definitions and produces no printed output. The script 
calls the procedures defined in the prologue to generate the printed
pages. The pages of the script are independent of each other
but dependent on the prologue. \ps\ code that is executed within
the script of the document can only affect the page in which it occurs.
The command
\begin{flushleft}
\verb|\special{dvitops: prolog| {\it filename}\verb|}|
\end{flushleft}
will include {\it filename} in the prologue of the output file;
{\it filename}  must contain {\em only} definitions. The command
\begin{flushleft}
\verb|\special{dvitops: inline| {\it anything}\verb|}|
\end{flushleft}
will include {\it anything} in the script of the output file;
{\it anything} should a short piece of \ps\ code
which calls procedures defined in a prologue file. 
All the pieces of code from the {\tt inline} commands on a particular
page are held in memory until the end of the page is encountered.
The pieces of code are then output together after all the other output on
the page. The coordinate system in effect is the same as that used by
\TeX: units are scaled points (there are 65536 scaled points in a point);
y coordinates increase down the page; the origin is 1~inch down from
and 1~inch to the right of the upper left hand corner of the page.
Each \verb|\special| command in the {\tt .dvi} file
has an associated position, namely the reference point that would
have been present if a box of height, depth and width zero had appeared
in place of the \verb|\special| command.
\dvitops\ inserts code to move to that position before it outputs
the code from each {\tt inline} command. 
(This is what makes the {\tt inline} command useful.)
Note that any definitions
that you make in the code using  {\tt inline} commands will only
last until the end of the current page.

\subsection{Regions}
\dvitops\ allows you to select regions of a page and perform
various operations on them. Regions of the page are selected
using the following specials
\begin{flushleft}
\verb|\special{dvitops: begin |{\it region}\verb|}|\\
\verb|\special{dvitops: end}|
\end{flushleft}
Anything bracketed between these two commands will be part of the region
called {\it region}; {\it region} can be any alphanumeric string.
Regions cannot be nested; a {\tt begin}
command automatically terminates any previous {\tt begin} command
not already terminated with an {\tt end} command. All regions
are terminated automatically at the end of a page. The same
region can be the subject of more than one {\tt begin} command.
An {\tt end} command must have a preceding {\tt begin} command
on the same page.
Regions can include inline \ps\ and graphics.

\subsubsection{Transformations}
Once you have selected a region, you can apply a geometrical
transformation to it.
Each transformation is relative to an origin. By default
the origin is \TeX's origin, 1~inch down from and 1~inch to the
right of the upper right hand corner of the page
(unless changed by the {\tt -h} and {\tt -v} options).
This origin can be changed. The command
\begin{flushleft}
\verb|\special{dvitops: origin |{\it region}\verb|}|
\end{flushleft}
makes the current point the origin for {\it region}.
A region can have only one origin. Giving a region an origin
does not alter the position of the region on the page;
it just alters the effect of  transformations on that region.
The {\tt origin} command can be given anywhere on the page.

There are two \verb|\special| commands that perform
transformations:
\begin{flushleft}
\verb|\special{dvitops: rotate |{\it region $\theta$}\verb|}|\\
\verb|\special{dvitops: transform |{\it region a b c d}\verb|}|
\end{flushleft}
The {\tt transform} command performs the affine transformation
represented by the matrix
\[ \left( \begin{array}{cc}
a	&b\\
c	&d\\
\end{array} \right). \]
The {\tt rotate} command rotates the region about the origin of that
region by $\theta$ degrees in a clockwise direction. It is equivalent
to a {\tt transform} command; it is included because it is inconvenient
to calculate the appropriate transformation matrix for a rotation in \TeX.
Any number of transformations can be applied to a region. They will be
applied in the order in which they are given. 
Regions are only affected by transformation commands that appear on the 
same page. Apart from this transformation commands can appear at
any point in the document. For example, the following code
\begin{verbatim}
A \special{dvitops: begin example}%
\special{dvitops: origin example}sloping%
\special{dvitops: end} 
word.
\special{dvitops: rotate example -30}
\end{verbatim}
will produce
\begin{flushleft}
A \special{dvitops: begin example}%
\special{dvitops: origin example}sloping\special{dvitops: end} word.
\special{dvitops: rotate example -30}
\end{flushleft}
\subsubsection{Color}
You can also choose what color a region should be painted with.
\begin{flushleft}
\verb|\special{dvitops: gray| {\it whiteness}\verb|}|\\
\verb|\special{dvitops: hsbcolor| {\it hue saturation brightness}\verb|}|\\
\verb|\special{dvitops: rgbcolor| {\it red green blue}\verb|}|
\end{flushleft}
You should use at most one of these for each region. The arguments must
all be numbers between 0 and 1. A value of 0 for {\it whiteness}
will give black, and a value of 1 white.
You can get interesting effects using the \verb|gray| special.
For example, a macro \verb|\rbox| can be defined like this
\def\rbox#1{%
\leavevmode\setbox0\hbox{\strut#1}\special{dvitops: gray reverse 1}%
\vrule width \wd0 height \ht0 depth \dp0
\llap{\special{dvitops: begin reverse}\box0\special{dvitops: end}}}
\begin{verbatim}
\def\rbox#1{%
  \leavevmode\setbox0\hbox{\strut#1}%
  \special{dvitops: gray reverse 1}%
  \vrule width \wd0 height \ht0 depth \dp0
  \llap{\special{dvitops: begin reverse}%
    \box0
    \special{dvitops: end}}}
\end{verbatim}
Then \verb|\rbox{reverse out}| will produce \rbox{reverse out}.  Note
that objects on a page are not necessarily output in the order in
which they occur in the dvi file; in particular, all the text on a page
is output after everything else on the page.

\section{Errors}
\dvitops\ produces three types of error messages---fatal errors, errors
and warnings. The program will terminate immediately on a fatal error.
Each error message is prefixed by the full pathname of the 
\dvitops\ program, followed by a colon and one of 
``fatal error'', ``error'' and ``warning.'' 
\dvitops\ operates in two passes. On the second pass
\dvitops\ prints an opening bracket followed by the number of a page
just as it is about to start outputting the \ps\ code for that page;
it prints a closing bracket when it's done with a page.
The page number displayed is the values of \verb|\count0| through
\verb|\count9| separated by dots with trailing `.0's suppressed.
\TeX\ does the same.
This enables you to tell on the second pass where \dvitops\ has
encountered the error.

\end{document}