Debian Codegraph @

texmf-dist/doc/man/man1/dvipdfmx.1

raw
1 .de EX
2 .sp
3 .in +5
4 .nf
5 .ft CW
6 ..
7 .de EE
8 .in -5
9 .ft R
10 .sp
11 .fi
12 ..
13 .TH "DVIPDFMX" "1" "1 June 2021"
14 .SH NAME
15 dvipdfmx, xdvipdfmx, dvipdfm \- produce PDF files directly from DVI files
16 .SH SYNOPSIS
17 .B dvipdfmx
18 or
19 .B dvipdfm
20 .RI [ options ]
21 .I file\c
22 .RB [ .dvi ]
23 .SH DESCRIPTION
24 The program
25 .B dvipdfmx
26 generates a PDF file from a DVI file. DVI files are the output produced
27 by TeX.
28 .B groff
29 can also generate DVI files using
30 .BR grodvi (-Tdvi).
31
32 In TeX Live,
33 .B dvipdfm
34 is another incarnation of
35 .B dvipdfmx
36 rather than a separate program. Compatibility is attempted as best as
37 possible.
38
39 .B xdvipdfmx
40 is another incarnation. It is used as the back end for
41 .BR xetex (1)
42 and is not intended to be invoked directly.
43
44 .B dvipdfmx
45 recognizes several commonly used
46 .BR \especial
47 commands, which are extensions to the DVI format. Specifically, it
48 understands color specials, papersize specials, tpic specials (which
49 allow it to be used with
50 .BR pic ),
51 hypertex specials, and some PostScript specials. These extensions allow
52 documents to contain color, figures, and hyperlinks. The program tries
53 to mimic the behavior of
54 .B dvips
55 where possible, so that many macro packages produced for use with
56 .B dvips
57 will also work with
58 .BR dvipdfmx .
59 In addition,
60 .B dvipdfmx
61 understands its own specific
62 .B \especial
63 commands to allow access to PDF features such as annotations and
64 bookmarks.
65
66 As of December 2018, one such special specific to
67 .B dvipdfmx
68 is
69 .IR pdf:trailerid ,
70 which specifies the /ID in the PDF trailer.
71 It is used like this (from the TeX level):
72 .br
73 \especial{pdf:trailerid [ (0123456789abcdef) (01234567890abcdef) ]}
74 .br
75 That is, the special takes an array (the square brackets) of two 16-byte
76 PDF strings (the parentheses). This is the same syntax as LuaTeX's
77 .IR "\epdfvariable trailerid" ,
78 while different from pdfTeX's
79 .IR \epdftrailerid .
80 It must appear on the first output page, otherwise it is ignored.
81
82 Unrecognized specials will generate warning messages. Packages that may need a
83 .B dvipdfm
84 or
85 .B dvipdfmx
86 driver option include
87 .IR geometry ,
88 .IR hyperref ,
89 .IR bookmark ,
90 .IR graphicx ,
91 and
92 .IR xcolor .
93
94 For issues related to bounding boxes (and hence image sizes), see
95 .BR extractbb (1).
96 .SH OPTIONS
97 Unlike with many other programs, argument values must be separated from
98 option names by a space, not an = sign; option names cannot be
99 abbreviated; and \- and \-\- cannot be used interchangeably.
100 .TP 5
101 .B \-\^c
102 Ignore (or accept) color
103 .BR \especials .
104 By default, color
105 .BR \especial "s"
106 are interpreted normally (changeable in the configuration file). The
107 .B \-\^c
108 option may be used to produce a black and white document
109 from a document containing color TeX
110 .B \especial
111 commands.
112 .TP 5
113 .B \-\-\^dvipdfm
114 Enable
115 .B dvipdfm
116 emulation mode. This is the default if the executable name is `dvipdfm'.
117 .TP 5
118 .B \-\^d number
119 Specify the number of decimal digits in the PDF output; must be between
120 0 and 5, default is 2.
121 .TP 5
122 .B \-\^e
123 Ignored, for (semi-)compatibility with
124 .BR dvipdfm .
125 .TP 5
126 .B \-\^f map_file
127 Read the font map file given by
128 .IR map_file .
129 The default map file in TeX Live is
130 .IR pdftex.map ,
131 as defined in the configuration file.
132 .TP 5
133 .B \-\-\^help
134 Show a help message and exit successfully.
135 .TP 5
136 .B \-\^i " cfgfile"
137 Read
138 .I cfgfile
139 as another include file, after reading the default
140 .IR dvipdfmx.cfg .
141 .TP 5
142 .B \-\-\^kpathsea-debug number
143 Have Kpathsea output debugging information; `-1' for everything (voluminous).
144 .TP 5
145 .B \-\^l
146 Select landscape mode. In other words, exchange the
147 .I x
148 and
149 .I y
150 dimensions of the paper.
151 .TP 5
152 .B \-\^m " mag"
153 Magnify the input document by
154 .IR mag .
155 .TP 5
156 .B \-\^o " filename"
157 Set the PDF output file name; use `-' for stdout.
158 By default, the name of the output
159 file is derived from the input, that is,
160 .IR file .pdf.
161 .TP 5
162 .B \-\^p " paper"
163 Select the papersize by name (e.g.,
164 .BR letter ", " legal ", " ledger ", " tabloid ", " a3 ", " a4 ", or " a5
165 )
166 .TP 5
167 .B \-\-\^pdfm-str-utf8
168 Assume PDFMark strings in
169 .B \especial
170 commands are encoded in UTF-8.
171 .TP 5
172 .B \-\^q
173 Quiet mode.
174 .TP 5
175 .B \-\^r " size"
176 Set resolution of bitmapped fonts to
177 .B size
178 dots per inch. Bitmapped fonts are generated
179 by the Kpathsea library, which uses Metafont. Bitmapped
180 fonts are included as Type 3 fonts in the PDF output file. Default is 600.
181 .TP 5
182 .B \-\^s " page_specifications"
183 Select the pages of the DVI file to be processed; default is `-',
184 meaning all pages. The
185 .I page_specifications
186 consists of a comma separated list of
187 .IR page_ranges :
188 .EX
189 .IR "page_specifications := page_specification" "[," page_specifications "]"
190 .EE
191 where
192 .EX
193 .IR "page_specification := single_page" | page_range
194 .IR "page_range := " [ first_page ]\^\-\^[ last_page ]
195 .EE
196 An empty
197 .I first_page
198 is treated as the first page of the DVI file, and
199 an empty
200 .I last_page
201 is treated as the last page of the DVI file.
202
203 Examples:
204 .RS
205 .TP 5
206 .B "\-\^s 1,3,5"
207 includes pages 1, 3, and 5;
208 .TP 5
209 .B "\-\^s \-"
210 includes all pages;
211 .TP 5
212 .B "\-\^s \-,\-"
213 includes two copies of all pages in the DVI file;
214 and
215 .TP 5
216 .B "\-\^s 1\-10"
217 includes the first ten pages of the DVI
218 file.
219 .RE
220 .TP 5
221 .B \-\^t
222 Search for thumbnail images of each page
223 in the directory named by the
224 .B TMPDIR
225 environment variable. The thumbnail images must be named in a specific
226 format: the same base name as the DVI file and the page number as the
227 extension to the file name.
228 .B dvipdfmx
229 does not generate such thumbnails itself, but it is distributed with a
230 wrapper program named
231 .B dvipdft
232 that does so.
233 .TP 5
234 .B \-\-\^version
235 Show a help message and exit successfully.
236 .TP 5
237 .B \-\^v
238 Increase verbosity.
239 Results of the
240 .B \-\^v
241 option are cumulative (e.g.,
242 .B \-\^vv
243 increases the verbosity by two increments). Maximum verbosity is four.
244 .TP 5
245 .B \-\^x x_offset
246 Set the left margin to
247 .IR x_offset .
248 The default left margin is
249 .BR 1.0in .
250 The dimension may be specified in any units understood by TeX (e.g.,
251 .BR bp ", " pt ", " in ", " cm ).
252 .TP 5
253 .B \-\^y y_offset
254 Set the top margin to
255 .IR y_offset .
256 The default top margin is
257 .BR 1.0in .
258 The dimension may be specified in any units understood by TeX (e.g.,
259 .BR bpt ", " pt ", " in ", " cm ).
260 .TP 5
261 .B \-\^z number
262 Set the compression level to
263 .IR compression_level .
264 Compression levels range from 0 (no compression) to
265 9 (maximum compression) and correspond to the values understood by zlib;
266 default is 9.
267 .TP 5
268 .B \-\^C number
269 Miscellaneous option flags; see the --help output for details.
270 .TP 5
271 .B \-\^D template
272 PostScript to PDF conversion command line template; the default is taken
273 from the configuration file, which also gives all the details and
274 mentions several possibilities.
275 .TP 5
276 .B \-\^E
277 Always try to embed fonts, ignoring licensing flags, etc.
278 .TP 5
279 .B \-\^I number
280 Image cache life in hours; default is -2, meaning to not cache images at
281 all. A value of -1 means to erase all old images and also new images; 0
282 means to erase all old images but leave new images.
283 .TP 5
284 .B \-\^K number
285 Encryption key length; default 40.
286 .TP 5
287 .B \-\^M
288 Process MetaPost PostScript output.
289 .TP 5
290 .B \-\^O number
291 Set maximum depth of open bookmark items; default 0.
292 .TP 5
293 .B \-\^P number
294 Set permission flags for PDF encryption; default 0x003C.
295 .TP 5
296 .B \-\^S
297 Enable PDF encryption.
298 .TP 5
299 .B \-\^V number
300 Set PDF minor version; default 5 (from the configuration file).
301 .SH "IMAGE BOUNDING BOXES"
302 When including images with
303 .BR dvipdfmx ,
304 their bounding boxes should be generated by running
305 .BR extractbb .
306 The result will be in an
307 .B .xbb
308 file; the xbb information is the same as for the PDF format.
309 .SH ENVIRONMENT
310 .B dvipdfmx
311 uses the
312 .B kpathsea
313 library for locating the files that it opens. Hence, the environment
314 variables documented in the
315 .I Kpathsea library
316 documentation influence
317 .BR dvipdfmx .
318 It also uses the value of the environment variable TMPDIR as the
319 directory to search for thumbnail images of each page.
320 .SH FILES
321 The precise location of the following files is determined by the
322 .I Kpathsea library
323 configuration. The location may be determined by using kpsewhich, e.g.,
324 .nf
325 .B kpsewhich \-progname=dvipdfmx \-format='other text files' dvipdfmx.cfg
326 .fi
327 .TP 5
328 .I dvipdfmx.cfg
329 Default configuration file
330 .TP 5
331 .I dvipdfmx-unsafe.cfg
332 Configuration file that runs Ghostscript without safety checks; use only
333 for trusted source files. It is currently required to use PSTricks with
334 XeTeX:
335 .B xetex \-output-driver="xdvipdfmx \-i dvipdfmx-unsafe.cfg -q -E" ...
336 .TP 5
337 .I pdftex.map
338 The default font map file (this may be changed in the config file).
339 .TP 5
340 .I *.tfm
341 TeX font metrics
342 .TP 5
343 .I *.vf
344 TeX virtual font files
345 .TP 5
346 .I *.pfb
347 PostScript Type 1 font files
348 .TP 5
349 .I
350 texmf.cnf
351 The Kpathsea library configuration file.
352 The location of this file may be found by typing
353 .nf
354 .B kpsewhich texmf.cnf
355 .fi
356 .SH "SEE ALSO"
357 dvipdft(1), extractbb(1),
358 .br
359 tex(1), luatex(1), xetex(1), dvips(1),
360 .br
361 groff(1), grodvi(1), pic(1),
362 the Kpathsea library Info documentation (https://tug.org/kpathsea),
363 and the Dvipdfmx User's Manual (in the distribution, and linked from
364 https://tug.org/dvipdfmx).
365 .SH AUTHOR
366 Primarily Mark A. Wicks; dvipdfmx extensions primarily by Jin-Hwan Cho,
367 Shunsaku Hirata, and Matthias Franz. For the version in TeX Live, please
368 send bugs and other reports to the maintainers at dvipdfmx (at) tug.org
369 (https://lists.tug.org/dvipdfmx).
370 .PP
371 This man page edited for TeX Live by Bob Tennent and others. This man
372 page is public domain.