summaryrefslogtreecommitdiff
path: root/dviware/dvitops/dvitops.1
blob: bc55ac49e2f10c48c3260f4a97dfb6581374e12d (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
'\" e
.\" $Header: /usr/jjc/dvitops/RCS/dvitops.1,v 1.5 90/08/14 13:31:17 jjc Rel $
.TH DVITOPS L
.SH NAME
dvitops \- convert the output of TeX to PostScript
.SH SYNOPSIS
.B dvitops
[
.B \-qrs
] [
.BI \-c ncopies
] [
.BI \-f firstpage
] [
.BI \-n npages
]
.if n .ti +0.5i
[
.BI \-m magnification
] [
.BI \-y kmem
] [
.BI \-h hoffset
] 
.if n .ti +0.5i
.if t .ti +0.5i
[
.BI \-v voffset
] [
.BI \-p papersize
] [
.BI \-d dpi
] [
.I dvifile
]
.SH DESCRIPTION
.B dvitops
converts a dvi file produced by TeX into PostScript.
If the
.I dvifile
argument is not present,
.B dvitops
reads the standard input. In this case the standard input must be a file
rather than a pipe.
The extension
.B .dvi
may be omitted.
The output is written on the standard output, and is normally piped
into
.BR lpr .
Either bitmap fonts in pk format, or ordinary PostScript fonts
may be used. If PostScript fonts are used which are not
resident in the printer, the output of
.B dvitops
must be passed through a filter or spooler that can handle
font downloading.
.SH OPTIONS
.TP
.B \-q
Quiet mode. Don't print the numbers of pages as they are printed.
.TP
.B \-r
Output pages in reverse order.
.TP
.B \-s
Sort pages by their
.B \ecount0
values.
.TP
.BI \-c ncopies
Print
.I ncopies
of each page. The copies will not be collated. The default is 1.
.TP
.BI \-f firstpage
The first page to be output will be
.I firstpage.
This is specified in the same way as in
.BR dvitype :
a sequence of one to ten numbers or asterisks separated by periods.
For example,
.B \-1.*.3
will match the first page whose
.B \ecount0
value is \-1, and whose
.B \ecount2
value is 3. The default is
.BR * ,
which will match any page.
.TP
.BI \-n npages
Output at most
.I npages
pages. The default is a large number.
.TP
.BI \-m magnification
Replace the magnification in the input file by
.IR magnification .
A magnification of 1000 means no magnification; a magnification to 2000
means magnification by a factor of 2.
.TP
.BI \-y kmem
Use at most
.IR kmem k
bytes of printer memory for preloading bitmap fonts.
In order to improve performance,
.B dvitops
puts the bitmap fonts that are most used in the document at the
beginning of the output; other fonts have to be output for each page
on which they are used. The default value is 100, which is suitable for
the oldest PostScript printers. Newer printers with more memory will
give better performance with a higher value.
.TP
.BI \-h hoffset
Position the left hand edge of the output
.I hoffset
away from the left edge of the paper.
.I hoffset
is given as a number with an optional decimal point followed by one
of the units of measure recognised by TeX.
The default value is 1 inch, which is the value assumed by most macro
packages.
.TP
.BI \-v voffset
Position the top edge of the output
.I voffset
away from the top edge of the paper.
.I voffset
is given as a number with an optional decimal point followed by one
of the units of measure recognised by TeX.
The default value is 1 inch, which is the value assumed by most macro
packages.
.TP
.BI \-p papersize
Produce output suitable for
.I papersize
paper.
.I papersize
is one of the standard PostScript paper types: 
.BR a4 ,
.BR letter ,
.BR legal ,
.BR b5 ,
.BR b4 ,
.BR tabloid ,
.BR ledger ,
.BR statement ,
.BR executive ,
.BR a3 ,
.BR a5 ,
.BR folio ,
.B quarto
or
.BR 10x17 .
The default is
.BR letter .
.B dvitops
uses the paper dimensions to position the output correctly.
Non-standard paper sizes can be accommodated using the
.B \-h
or
.B \-v
options.
.TP
.BI \-d dpi
Choose bitmap fonts suitable for a printer with a resolution
of
.I dpi
dots per inch. The default is 300.
.SH USAGE
.B dvitops
supports the use of TeX's
.B \especial
primitive to take advantage of some of PostScript's advanced facilities.
.B dvitops
recognises only
.B \especial
commands whose arguments start with a
.B dvitops:\&
tag.
The following
.B \especial
commands are available:
.TP
\fB\especial{dvitops: landscape}\fP
Print the current page in landscape mode,
with its top along the long side of the paper.
.TP
\fB\especial{dvitops: import \fIfilename width height \
\fR[ \fIoption\fR\|.\|.\|. ] \fB}\fR
This is used to include a picture in the output.
.I filename
must contain PostScript code.
The picture will be positioned with its
lower left hand corner at the current position.
The
.I width
and
.I height
arguments
give the desired height and width of the illustration in the output;
these are given as numbers with an optional decimal point followed
by one of the units of measure recognised by TeX.
.B dvitops
will scale the picture to fit this space. 
Usually
.B dvitops
will scale the picture by the same amount vertically as horizontally,
so that the picture retains its original proportions, and
will center the picture in any surplus horizontal or vertical white space.
An option of
.BR top ,
.BR bottom ,
.B left
or
.B right
will cause the picture to be positioned at the top, bottom, left or
right of the specified space, rather than being centered.
An option of
.B fill
will cause the picture to be scaled to fit the specified space both
horizontally and vertically. The imported file must
comply with the Adobe Document Structuring Conventions. In particular
it must contain a
.B %%BoundingBox:
comment in an appropriate place. Additionally, the file should
comply with the guidelines given in the specification of EPSF
(Encapsulated PostScript Format). A file beginning with the line
.br
.B "%!PS-Adobe-2.0 EPSF-1.2"
.br
is likely to meet these requirements.
.TP
\fB\especial{dvitops: inline \fIanything\fB}\fR
Include the arbitrary PostScript code
.I anything
in the output.
When this code is executed, the coordinate system in effect will
be TeX's: units are scaled points (65536 in a point) with the origin
1 inch down from and 1 inch to the right of the top left corner of
the page; currentpoint will be set to the currrent position
in the dvi file. All
.B inline
commands occurring on a given page will be collected together and output
at the end of page in the order in which they appeared.
.TP
\fB\especial{dvitops: prolog \fIfilename\fB}\fR
Make the PostScript definitions contained in
.I filename
available at this point in the file.
An extension of
.B .ps
may be omitted from
.IR filename .
This command is intended for use with the
.B inline
command. The
.B inline
command should be used simply to invoke procedures defined in other files
and made available by the
.B prolog
command.
The
.B prolog
command must be given at each place that the definitions that it contains
are required. This ensures that the definitions will be available even
if not all pages are output. The file will be downloaded at most once,
however many times it appears.
.TP
\fB\especial{dvitops: begin \fIregion\fB}\fR
.PD 0
.TP
\fB\especial{dvitops: end}\fR
Delimit a region of the dvi file to which
some geometric transformation is to be applied; the
.I region
argument serves to identify the region.
Regions cannot be nested, nor can they extend over more than one
output page. There can be multiple
.B begin
and
.B end
commands for each region.
.PD
.TP
\fB\especial{dvitops: origin \fIregion\fB}\fR
Make the current position the origin for transformations to be applied to
.IR region .
By default the origin is TeX's origin, 1 inch down from and 1 inch to
the right of the top left hand corner of the page.
.TP
\fB\especial{dvitops: rotate \fIregion \(*h\fB}\fR
Rotate
.I region
clockwise about its origin by \(*h degrees.
.TP
\fB\especial{dvitops: transform \fIregion a b c d\fB}\fR
Apply the affine transformation represented by the matrix
.EQ
left [ matrix { 
ccol { a above c } 
ccol { b above d }
} right ].
.EN
to
.IR region .
Arbitrarily many transformations may be applied to each region.
They will be applied in the order in which they are given.
.TP
\fB\especial{dvitops: gray \fIregion shade\fB}\fR
Use the gray shade corresponding to
.IR shade ,
which must be a number between 0 and 1, for
.IR region .
0 corresponds to black and 1 corresponds to white.
.TP
\fB\especial{dvitops: rgbcolor \fIregion red green blue\fB}\fR
Use the color described by the parameters
.IR red ,
.IR green ,
and
.IR blue ,
each of which must be numbers between 0 and 1, for
.IR region .
.TP
\fB\especial{dvitops: hsbcolor \fIregion hue saturation brightness\fB}\fR
Use the color described by the parameters
.IR hue ,
.IR saturation ,
and
.IR brightness ,
each of which must be numbers between 0 and 1, for
.IR region .
.SH ENVIRONMENT
.B dvitops
uses various environment variables in order to find the files
it requires. They each contain lists separated by colons.
.TP 15
.B
.SM TEXINPUTS
A list of directories in which to search for text input files.
.TP
.B
.SM TEXFONTS
A list of directories in which to search for tfm files.
.TP
.B
.SM TEXPK
A list of prototypes of names of pk files.
When a particular font is being searched for, a
.B %d
in the prototype will be replaced by the magnification of
the font in dots per inch, and a
.B %f
will be replaced by the name of the font.
.TP
.B
.SM TEXMAGS
A list of all the magnifications for which there is some pk file.
The magnifications are expressed in dots per inch.
.B dvitops
will only look for pk files at these magnifications. If a font
is required at some other magnification, a scaled version of the
font at one of the listed magnifications will be used.
.TP
.B
.SM DVITOPS
The value of this variable will be interpreted as if it had been typed in
at the beginning of the command line. For example, if it is set to
.B \-r
all output from
.B dvitops
will appear in reverse order (unless overridden by a second occurrence of
.BR \-r ).
.SH FILES
.PD 0
.TP 30
.B /usr/local/tex/inputs/dvitops.pro
PostScript definitions used by dvitops
.TP
.B /usr/local/tex/input/dvitops.fnt
list of the TeX and PostScript names of PostScript fonts
.TP
.B /usr/local/tex/pk/*.*pk
pk files
.TP
.B /usr/local/tex/fonts/*.tfm
tfm files
.TP
.B /usr/local/tex/fonts/*.enc
encoding files
.PD
.SH "SEE ALSO"
.LP
.\" IR "DVITOPS User Manual" ,
.BR tex (L)
.SH AUTHOR
James Clark <jjc@jclark.uucp>