DVIPDFMX(1)

💖 DVIPDFMX(1) 💖

General Commands Manual ✨ okay so this is the manual page for dvipdfmx, and bestie, it's literally the tool that turns your DVI files into PDFs 🦋

✨ NAME ✨

dvipdfmx, xdvipdfmx, dvipdfm — produce PDF files directly from DVI files 📄💅

🎀 SYNOPSIS 🎀

dvipdfmx or dvipdfm [options] file[.dvi]

🌸 DESCRIPTION 🌸

okay so dvipdfmx generates a PDF file from a DVI file 💖 DVI files are the output that TeX makes, and groff can make them too using grodvi(-Tdvi) ✨

In TeX Live, dvipdfm is just another incarnation of dvipdfmx, not a separate program 🧚 Compatibility is attempted as best as possible, so it's giving close enough vibes 🫶

xdvipdfmx is another incarnation too 💜 It's used as the back end for xetex(1) and isn't meant to be invoked directly, so don't go poking it yourself 🙈

dvipdfmx recognizes several commonly used \special commands, which are extensions to the DVI format 🌈 Specifically, it understands color specials, papersize specials, tpic specials (which let it work with pic), hypertex specials, and some PostScript specials ✨ These extensions let documents have color, figures, and hyperlinks, and it's main character energy 👑 The program tries to mimic the behavior of dvips wherever possible, so a bunch of macro packages made for dvips will also work with dvipdfmx 🍓 On top of that, dvipdfmx understands its own special \special commands for PDF features like annotations and bookmarks 🔥

As of December 2018, one special that's specific to dvipdfmx is pdf:trailerid, which sets the /ID in the PDF trailer 🎀 You use it like this, from the TeX level:

\special{pdf:trailerid [ (0123456789abcdef) (01234567890abcdef) ]}

So the special takes an array (the square brackets) of two 16-byte PDF strings (the parentheses) 💅 This is the same syntax as LuaTeX's \pdfvariable trailerid, but different from pdfTeX's \pdftrailerid 😭 It must appear on the first output page, otherwise it gets ignored 💀

Heads up bestie: unrecognized specials will generate warning messages 🙈

Packages that may need a dvipdfm or dvipdfmx driver option include geometry, hyperref, bookmark, graphicx, and xcolor 🦋

For issues related to bounding boxes (and hence image sizes), check out extractbb(1) 💜

👑 OPTIONS 👑

ngl this part is lowkey long, but every single flag is here 🫶 Also, unlike with many other programs, argument values must be separated from option names by a space, not an = sign ✨ Option names can't be abbreviated either, and - and -- can't be used interchangeably 🙅‍♀️

• -c — Ignore (or accept) color \specials 🎨 By default, color specials are interpreted normally, and you can change that in the configuration file. Use -c to get a black and white document out of a document that has color TeX \special commands 🖤
• --dvipdfm — Turns on dvipdfm emulation mode 🧚 This is the default if the executable name is dvipdfm.
• -d number — Sets the number of decimal digits in the PDF output 🔢 It has to be between 0 and 5, and the default is 2.
• -e — Ignored, just there for (semi-)compatibility with dvipdfm 🫶
• -f map_file — Reads the font map file given by map_file 🗺️ The default map file in TeX Live is pdftex.map, as defined in the configuration file.
• --help — Shows a help message and exits successfully 💖
• -i cfgfile — Reads cfgfile as another include file, after reading the default dvipdfmx.cfg 📚
• --kpathsea-debug number — Has Kpathsea output debugging info 🐛 Use -1 for everything, which is voluminous, so brace yourself 😭
• -l — Selects landscape mode 🌅 In other words, it swaps the x and y dimensions of the paper.
• -m mag — Magnifies the input document by mag 🔍
• -o filename — Sets the PDF output file name 📁 Use - for stdout. By default, the output name is derived from the input, so file.pdf ✨
• -p paper — Selects the papersize by name 📄 Examples are letter, legal, ledger, tabloid, a3, a4, or a5 💅
• --pdfm-str-utf8 — Assumes PDFMark strings in \special commands are encoded in UTF-8 🌏
• -q — Quiet mode 🤫
• -r size — Sets the resolution of bitmapped fonts to size dots per inch 🖨️ The bitmapped fonts are generated by the Kpathsea library, which uses Metafont, and they get included as Type 3 fonts in the PDF output file 🦋 The default is 600.
• -s page_specifications — Selects which pages of the DVI file get processed ✂️ The default is -, which means all pages. The page_specifications is a comma separated list of page_ranges, and it looks like this:

page_specifications := page_specification[,page_specifications]
where
page_specification := single_page|page_range
page_range := [first_page]-[last_page]

An empty first_page counts as the first page of the DVI file, and an empty last_page counts as the last page of the DVI file 🌸 Here are some examples, bestie:

-s 1,3,5

includes pages 1, 3, and 5 ✨

-s -

includes all pages 💖

-s -,-

includes two copies of all pages in the DVI file 👯‍♀️

-s 1-10

includes the first ten pages of the DVI file 📖

• -t — Searches for thumbnail images of each page in the directory named by the TMPDIR environment variable 🖼️ The thumbnail images have to be named in a specific format: the same base name as the DVI file, with the page number as the extension to the file name. dvipdfmx doesn't generate those thumbnails itself, but it's distributed with a wrapper program called dvipdft that does 🧁
• --version — Shows a help message and exits successfully 💅 (yes, the manual says help message here, so that's what it does)
• -v — Increases verbosity 📢 The results are cumulative, so -vv increases the verbosity by two increments. Maximum verbosity is four 🔊
• -x x_offset — Sets the left margin to x_offset 📏 The default left margin is 1.0in. You can use any units TeX understands, like bp, pt, in, or cm ✨
• -y y_offset — Sets the top margin to y_offset 📏 The default top margin is 1.0in. Again, any units TeX understands work, like bpt, pt, in, or cm 🌷
• -z number — Sets the compression level to compression_level 🗜️ Levels range from 0 (no compression) to 9 (maximum compression) and match the values zlib understands. The default is 9 💜
• -C number — Miscellaneous option flags 🧩 See the --help output for details.
• -D template — PostScript to PDF conversion command line template 🛠️ The default comes from the configuration file, which also has all the details and mentions several possibilities.
• -E — Always tries to embed fonts, ignoring licensing flags and whatnot 🔤
• -I number — Image cache life in hours ⏳ The default is -2, which means don't cache images at all. A value of -1 erases all old images and also new images 💀 A value of 0 erases all old images but leaves the new ones alone.
• -K number — Encryption key length 🔐 The default is 40.
• -M — Processes MetaPost PostScript output 🌟
• -O number — Sets the maximum depth of open bookmark items 🔖 The default is 0.
• -P number — Sets permission flags for PDF encryption 🛡️ The default is 0x003C.
• -S — Enables PDF encryption 🔒
• -V number — Sets the PDF minor version 📘 The default is 5, which comes from the configuration file.

🦋 IMAGE BOUNDING BOXES 🦋

When you include images with dvipdfmx, their bounding boxes should be generated by running extractbb 🖼️ The result ends up in an .xbb file, and the xbb information is the same as for the PDF format ✨

🌈 ENVIRONMENT 🌈

dvipdfmx uses the kpathsea library to locate the files it opens 🗂️ So the environment variables documented in the Kpathsea library documentation influence dvipdfmx too 💜 It also uses the value of the environment variable TMPDIR as the directory to search for thumbnail images of each page 🧚

📁 FILES 📁

The precise location of the following files is determined by the Kpathsea library configuration 🗺️ You can find the location with kpsewhich, e.g.,

kpsewhich -progname=dvipdfmx -format='other text files' dvipdfmx.cfg

dvipdfmx.cfg : Default configuration file 🎀

dvipdfmx-unsafe.cfg : Configuration file that runs Ghostscript without safety checks 😬 Only use this for trusted source files! It's currently required to use PSTricks with XeTeX, like this: xetex -output-driver="xdvipdfmx -i dvipdfmx-unsafe.cfg -q -E" ...

pdftex.map : The default font map file (this may be changed in the config file) 🗺️

*.tfm : TeX font metrics 📏

*.vf : TeX virtual font files 🧩

*.pfb : PostScript Type 1 font files 🔤

texmf.cnf : The Kpathsea library configuration file 💖 You can find where this file lives by typing kpsewhich texmf.cnf.

🔗 SEE ALSO 🔗

dvipdft(1), extractbb(1), tex(1), luatex(1), xetex(1), dvips(1), groff(1), grodvi(1), pic(1), the Kpathsea library Info documentation (https://tug.org/kpathsea), and the Dvipdfmx User's Manual (in the distribution, and linked from https://tug.org/dvipdfmx) 📚✨

💜 AUTHOR 💜

Primarily Mark A. Wicks 👩‍💻 dvipdfmx extensions were primarily by Jin-Hwan Cho, Shunsaku Hirata, and Matthias Franz 🫶 For the version in TeX Live, please send bugs and other reports to the maintainers at dvipdfmx (at) tug.org (https://lists.tug.org/dvipdfmx) 🐛

This man page was edited for TeX Live by Bob Tennent and others 🌸 This man page is public domain 🎉

---

bestie, that's the whole thing!! 💖 Dated 1 June 2021, and it's giving DVIPDFMX(1) forever 🦋✨