| 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. |