XDVIPSK(1)

💖 xdvipsk(1) 💖

okay bestie, gather round, because this is the manual for xdvipsk and it's literally the moment ✨

🌸 NAME 🌸

xdvipsk — convert a TeX DVI file to PostScript (dvips extexsion) 💅

yes, "extexsion" is a typo, but we keep it exactly as it is, no cap. the vibes are immaculate.

---

✨ SYNOPSIS ✨

xdvipsk [OPTIONS] file[.dvi]

---

🦋 DESCRIPTION 🦋

xdvipsk has a few base extensions:

• bitmap images — allows flexible inclusion of bitmap images. xdvipsk accepts BMP, PCX, TIFF, JPEG, PNG formats and is able to perform the same actions as with EPS images: scaling, rotating, trim, viewport.

xdvispk.def (extended dvips.def) driver for graphics package does not yet implement the operations of clipping, trimming and viewport.

• OpenType fonts — adds OpenType font support. Map files with information about OpenType fonts used in .dvi files are produced by LaTeX package luafontmaps.

PostScript header file texcid.pro is used for inclusion of OpenType fonts in PostScript files. It is an analogue of texps.pro that is used in case of Type1 fonts.

• mapfile, mapline specials — accepts font map special commands with prefixes mapfile and mapline to supplement font mapping provided in psfonts.map tables. mapfile is used for reading a font map file consisting of one or more font map lines. The name of the map file is given together with an optional leading modifier character (+). There is a companion special type mapline that allows to scan single map lines; its map line argument has the same syntax as the map lines from a map file.

Both specials can be used concurrently. The operation mode is selected by an optional modifier character (+) in front. This modifier defines how the individual map lines are going to be handled, and how a collision between an already registered map entry and a newer one is resolved; either ignoring a later entry with a warning in case modifier charcter is given, or replacing an existing entry in case no modifier character is given.

• Lua callbacks — adds Lua callbacks for specials (prescan, scan), after prescan, drawchar, drawrule, stack, dvips exit.

xdvipsk reads Lua script file xdvipsk.lua if it is found by kpse and looks for these Lua functions:

prescan_specials_callback(special, table) special- original special data, table with keys: hh, vv, pagenum.

scan_specials_callback(special, table) special- original special data, table with keys: hh, vv, pagenum

after_prescan_callback(table) table with keys: hpapersize, vpapersize, hoff, voff, actualdpi, vactualdpi, num, den, mag, totalpages

after_drawchar_callback(table) table with keys: charcode, cid, pixelwidth, rhh, rvv, dir, lastfont, tounicode

after_drawrule_callback(table) table with keys: hh, vv, dir, rw, rh

process_stack_callback(table) table with keys: cmd, hh, vv, dir

dvips_exit_callback(table) table with keys: exitcode, log_records_count

Return values for specials defines processing behaviour:

• non empty string defines modified dvi special to be processed;
• true value means processing original dvi special in default way;
• empty string | false value means skipping dvi special.

Default Lua script file can be changed by command line argument -lua or command luascript in xdvipsk config files.

• ToUnicode CMaps — ToUnicode CMaps support through adding GlyphNames2Unicode dictionary to T1 and OpenType fonts.

GlyphNames2Unicode is an undocumented dictionary which Adobe PostScript printer driver uses to communicate with Adobe Distiller. In this dictionary the keys are glyph names, the values are Unicode UTF-16 codes of them. The dictionary is stored in the FontInfo dictionary under the key GlyphNames2Unicode. Ghostscript recognises it and uses to generate ToUnicode CMaps with pdfwrite.

A bit OBSOLETE info can be found at <https://tug.org/TUGboat/tb38-2/tb119tolusis.pdf>

Development sources: <https://github.com/vtex-soft/xdvipsk.git>

---

👑 OPTIONS 👑

Extra xdvipsk options are marked with [+].

• - — Read additional options from standard input after processing the command line.
• --help — Print a usage message and exit.
• --version — Print the version number and exit.
• -a — Conserve memory by making three passes over the .dvi file instead of two and only loading those characters actually used. Generally only useful on machines with a very limited amount of memory, like some PCs.
• -A — Print only the odd pages. This option uses TeX page numbers, not physical page numbers.
• -b num — Generate num copies of each page, but duplicating the page body rather than using the /#copies PostScript variable. This can be useful in conjunction with a header file setting bop-hook to do color separations or other neat tricks.
• -B — Print only the even pages. This option uses TeX page numbers, not physical page numbers.
• -bitmapfontenc [on,off,strict] — Turns bitmap font encoding to off, on (no warnings for missing bitmap font encodings), or strict (with warnings for missing bitmap font encodings).
• -c num — Generate num consecutive copies of every page, i.e., the output is uncollated. This merely sets the builtin PostScript variable /#copies Default is 1. (For collated copies, see the -C option below.)
• -C num — Create num copies, but collated (by replicating the data in the PostScript file). Slower than the -c option, but easier on the hands, and faster than resubmitting the same PostScript file multiple times.
• -d num — Set the debug flags, showing what dvips is doing. This will work unless Dvips has been compiled without the 'DEBUG' option (not recommended). *Note Debug options::, for the possible values of num. Use '-d -1' as the first option for maximum output.
• -D num — Set both the horizontal and vertical resolution to num, given in dpi (dots per inch). This affects the choice of bitmap fonts that are loaded and also the positioning of letters in resident PostScript fonts. Must be between 10 and 10000. This affects both the horizontal and vertical resolution. If a high resolution (something greater than 400 dpi, say) is selected, the -Z flag should probably also be used. If you are using fonts made with Metafont, such as Computer Modern, mktexpk needs to know about the value for num that you use or Metafont will fail. See the modes.mf file (<https://ctan.org/pkg/modes>) for a list of resolutions and mode names for most devices.
• -e num — Maximum drift in pixels of each character from its 'true' resolution-independent position on the page. The default value of this parameter is resolution dependent (it is the number of entries in the list [100, 200, 300, 400, 500, 600, 800, 1000, 1200, 1600, 2000, 2400, 2800, 3200, ...] that are less than or equal to the resolution in dots per inch). Allowing individual characters to 'drift' from their correctly rounded positions by a few pixels, while regaining the true position at the beginning of each new word, improves the spacing of letters in words.
• -E — Generate an EPSF file with a tight bounding box. This only looks at marks made by characters and rules, not by any included graphics. In addition, it gets the glyph metrics from the tfm file, so characters that print outside their enclosing tfm box may confuse it. In addition, the bounding box might be a bit too loose if the character glyph has significant left or right side bearings. Nonetheless, this option works well enough for creating small EPSF files for equations or tables or the like. (Of course, dvips output, especially when using bitmap fonts, is resolution-dependent and thus does not make very good EPSF files, especially if the images are to be scaled; use these EPSF files with care.) For multiple page input files, also specify '-i' to get each page as a separate EPSF file; otherwise, all the pages are overlaid in the single output file.
• -f — Run as a filter. Read the .dvi file from standard input and write the PostScript to standard output. The standard input must be seekable, so it cannot be a pipe. If you must use a pipe, write a shell script that copies the pipe output to a temporary file and then points dvips at this file. This option also disables the automatic reading of the PRINTER environment variable; use '-P$PRINTER' after the -f to read it anyway. It also turns off the automatic sending of control-D (ASCII code 4) if it was turned on with the -F option or in the configuration file; use -F after the -f to send it anyway.
• -F — Write control-D (ASCII code 4) as the very last character of the PostScript file. This is useful when dvips is driving the printer directly instead of working through a spooler, as is common on personal systems. On systems shared by more than one person, this is not recommended.
• -G — Shift non-printing characters (ASCII 0-32, 127) to higher-numbered positions. This was useful to work around bugs in old versions of Adobe's PDF reader. It's more likely to cause problems nowadays.
• -h name — Prepend name as an additional header file, or, if name is '-', suppress inclusion of default header files. If -h is given multiple times, the headers are included in the order given. Any definitions in the header file get added to the PostScript userdict.
• [+]-H — Turbo mode for PS graphics
• -i — makes each section its own separate file, bestie. A "section" is a chunk of the document processed all by itself, and the reason you'd ever do this is usually to dodge a memory overflow. The filenames get made by swapping the suffix of the output file name you gave for a three-digit sequence number. This one is most often run hand-in-hand with -S, which sets the max section length in pages; but if you say -i and don't say -S, then literally every single page becomes its own file. 🌸 Say you've got a phototypesetter that can't print more than ten-ish consecutive pages before running out of steam — these options let you auto-split a book into ten-page sections, each in its own file. On the other hand, if your document uses very large fonts or very large included figures, Dvips might just take it upon itself to split the output into sections you did not ask for, all to try to avoid overflowing printer memory. 😭
• [+]-I p — resize mode for emTeX graphics.
• -j — download only the characters you actually need from Type 1 fonts. This is the default in the current release. Some debugging flags trace this operation. You can also control partial downloading on a per-font basis, via the psfonts.map file.
• [+]-J — download OpenType fonts partially.
• -k — print crop marks. This option increases the paper size (which you should specify, either with a paper size special or with the -T option) by a half inch in each dimension. It translates each page by a quarter inch and draws cross-style crop marks. Mostly useful with typesetters that can set the page size automatically. This works by downloading crop.pro.
• -K — this option causes comments in included PostScript graphics, font files, and headers to be removed. Sometimes you need this to get around bugs in spoolers or PostScript post-processing programs. Specifically, the %%Page comments, when left in, often cause difficulties. ⚠️ Use of this flag can cause some included graphics to fail, since the PostScript header macros from some software packages read portions of the input stream line by line, searching for a particular comment. This option has been turned off by default because PostScript previewers and spoolers have been getting better.
• -l [=]num[.SEQ] — the last page printed will be the first one numbered num. Default is the last page in the document. If num is prefixed by an equals sign, then it (and any argument to the -p option) is treated as a sequence number, rather than a value to compare with \count0 values. So like, using -l =9 will end with the ninth page of the document, no matter what the pages are actually numbered. 💅

On the other hand, if num is suffixed by .SEQ, the SEQth occurrence of num is used; for example, -l 99.2 says to end processing with the second page numbered 99 in the document.

• -L — by default or with -L1, the last papersize special wins; with -L0, the first special wins.
• -landscaperotate — when looking for matching paper sizes, permit rotation of page content on the page to match the given size; the default, as of Dvips 2022.1, is not to do this. It should not be needed in modern systems with normal print spoolers, and can be harmful when converting to PDF (*note Config file paper sizes::). This option accepts an optional suffix of 0 (to explicitly disable) or 1 (to explicitly enable); if the option is specified without a suffix, it enables the behavior.
• [+]-lua name — Lua script file name.
• -m — specify manual feed for the printer, if the output device supports it.
• -mode mode — use mode as the Metafont device name for path searching and font generation. This overrides any value from configuration files. With the default paths, explicitly specifying the mode also makes the program assume the fonts are in a subdirectory named mode.
• -M — turns off automatic font generation (mktexpk). If mktexpk is off, the invocation is appended to a file missfont.log by default in the current directory. You can then execute the log file to create the missing files after fixing the problem. If the current directory is not writable and the environment variable or configuration file value TEXMFOUTPUT is set, its value is used. Otherwise, nothing is written. The name missfont.log is overridden by the MISSFONT_LOG environment variable or configuration file value.
• -n num — at most num pages will be printed. Default is 100000. (Iconic number, honestly. 🫶)
• -N — turns off structured comments such as %%Page; this might be necessary on some systems that try to interpret PostScript comments in weird ways, or on some PostScript printers. Old versions of TranScript in particular cannot handle modern Encapsulated PostScript. > Beware: this also disables page movement, etc., in PostScript viewers such as Ghostview. 💀
• -noomega — this will disable the use of Omega extensions when interpreting DVI files. By default, the additional opcodes 129 and 134 are recognized by dvips as Omega or pTeX extensions and interpreted as requests to set 2-byte characters.
• -noptex — this will disable the use of pTeX extensions when interpreting DVI files. By default, the additional opcodes 130 and 135 are recognized by dvips as pTeX extensions and interpreted as requests to set 3-byte characters, and 255 as a request to change the typesetting direction.

The only drawback is that the virtual font array will (at least temporarily) require 65536 or more positions instead of the default 256 positions, i.e., the memory requirements of dvips will be somewhat larger. If you find this unacceptable or encounter another problem with the Omega or pTeX extensions, you can switch off the pTeX extension by using -noptex, or both by using -noomega (but please do send a bug report if you find such problems — see the bug address in the AUTHORS section below). 🐛

• [+]-noluatex — disable LuaTeX extensions.
• [+]-noToUnicode — disable ToUnicode CMap file generation for OpenType fonts.
• -o name — send output to the file name. If -o is specified without name (i.e., it is the last thing on the command line), the default is FILE.ps where the input DVI file was FILE.dvi. If -o isn't given at all, the configuration file default is used.

If name is -, output goes to standard output. If the first character of name is ! or |, then the remainder will be used as an argument to popen; thus, specifying |lpr as the output file will automatically queue the file for printing as usual. (The MS-DOS version will print to the local printer device PRN when name is |lpr and a program by that name cannot be found.) ✨

-o disables the automatic reading of the PRINTER environment variable, and turns off the automatic sending of control-D. See the -f option for how to override this.

• -O offset — move the origin by X-OFFSET,Y-OFFSET, a comma-separated pair of dimensions such as .1in,-.3cm (*note papersize special::). The origin of the page is shifted from the default position (of one inch down, one inch to the right from the upper left corner of the paper) by this amount. This is usually best specified in the printer-specific configuration file.

This is useful for a printer that consistently offsets output pages by a certain amount. You can use the file testpage.tex to determine the correct value for your printer. Be sure to do several runs with the same O value — some printers vary widely from run to run. 🙈

If your printer offsets every other page consistently, instead of every page, your best recourse is to use bop-hook (*note PostScript hooks::).

• -p [=]num[.SEQ] — exactly analogous to -l (q.v.), but specifying the first page number to be printed (processed).
• -pp pagelist — print pages FIRST through LAST; equivalent to -pFIRST-lLAST, except that multiple -pp options accumulate, unlike -p and -l. The - separator can also be :.
• -P PRINTER — read the configuration file config.PRINTER (PRINTER.cfg on MS-DOS), which typically sets the output name (most likely o |lpr -PPRINTER), resolution, Metafont mode, and perhaps other printer-specific defaults. It works best to put sitewide defaults in the one master config.ps file and only things that vary from printer to printer in the config.PRINTER files; config.ps is read before config.PRINTER. 🎀

A configuration file for eventual creation of Adobe PDF files is provided in config.pdf and thus can be loaded with -Ppdf. It will try to include Type 1 outline fonts into the PostScript file (*note Hypertext caveats::).

If no -P or -o is given, the environment variable PRINTER is checked. If that variable exists, and a corresponding config.PRINTER (PRINTER.cfg on MS-DOS) file exists, it is read. *Note Configuration file searching::.

• -q — run in quiet mode. Don't chatter about pages converted, etc.; report nothing but errors to standard error. (Me when I'm trying to focus 😌)
• [+]-Q — skip VTeX private specials.
• -r — output pages in reverse order. By default, page 1 is output first.
• -R[0|1|2] — run securely. -R2 disables both shell command execution in \special{} (via `, *note Dynamic creation of graphics::) and config files (via the E option, *note Configuration file commands::) and opening of any absolute or ..-relative filenames. -R1, the default, forbids shell escapes but allows absolute filenames. -R0 allows both. 🔒
• -s — causes the entire global output to be enclosed in a save/restore pair. This causes the file to not be truly conformant, and is thus not recommended, but is useful if you are driving the printer directly and don't care too much about the portability of the output.
• -S num — set the maximum number of pages in each 'section'. This option is most commonly used with the -i option; see that documentation above for more information. 🦋
• -t papertype — sets the paper type to papertype, bestie. That papertype needs to be defined in one of the config files, along with the right code to select it. (The types we know about rn: letter, legal, ledger, a4, a3.) You can also throw a *papertype* of landscapeat it, which rotates the doc 90 degrees. Wanna rotate a doc whose paper type isn't the default? Use-t**twice** — once for the paper type, once forlandscape. But like, generally? Don't use any -toption when apapersizespecial is in play, which some LaTeX packages (hi,hyperref💅) insert. Two exceptions tho: (1) you're using a nonstandard paper size that isn't already defined inconfig.ps— then you need-tunknown; (2) you're producing multi-page files for further processing — use -t nopaperto omit any paper size info in the output. (Oh, and if it's just a single page doc,-E` gets you pure EPSF output. 🎀)
• -T papersize — sets the paper size to papersize, which is a comma-separated pair of dimensions like .1in,-.3cm (*note papersize special::). It overrides any paper size special sitting in the DVI file. ⚠️ Be careful tho: the paper size will stick to a predefined size if there's one close enough. To turn that behavior off, use -tunknown.
• title s — uses s as the title in the generated PostScript (%%Title). No title given? Default is the basename of the input file. So like, running dvips /foo/bar.dvi gives you a %%Title of bar.dvi. periodt.
• -u psmapfile — sets psmapfile as the file dvips uses to look up PostScript font aliases. If psmapfile starts with a + character, the rest of the name is used as the map file name, and that map file gets appended to the list of map files (instead of replacing the list). Either way, if psmapfile has no extension, .map gets tacked onto the end. 🦋
• -U — disables a PostScript virtual memory saving optimization that stores character metric info in the same string used to store the bitmap info. Only needed when you're driving the Xerox 4045 PostScript interpreter, and it exists because of a bug in that interpreter that results in garbage at the bottom of every character. 😭 Not recommended unless you literally have to drive this printer.
• -v — prints the dvips version number and dips. 👋
• -V — downloads non-resident PostScript fonts as bitmaps. This needs mtpk or gsftopk or pstopk or some combo of them to generate the required bitmap fonts — those programs ship with Dvips. The bitmap has to be put into psfonts.map as the downloadable file for that font. Only useful for fonts where you don't have real outlines, being downloaded to printers with no resident fonts, i.e., very rarely. 💀
• [+]-W — extended search for emTeX graphics.
• -x num — sets the magnification ratio to num/1000. Overrides the magnification specified in the DVI file. Must be between 10 and 100000. Highly recommend you use standard magstep values (1095, 1200, 1440, 1728, 2074, 2488, 2986, and so on) to help reduce the total number of PK files generated. And num can be a real number, not just an integer, for extra precision. ✨
• -X num — sets the horizontal resolution in dots per inch to num.
• -y num — sets the magnification ratio to num/1000 times the magnification specified in the .dvi file. See -x above. 👀
• -Y num — sets the vertical resolution in dots per inch to num.
• -z — passes html hyperdvi specials through to the output for eventual distillation into PDF. Not enabled by default, because that avoids including the header files unnecessarily and avoids using temporary files while creating the output.
• -Z — compresses bitmap fonts in the output file, which shrinks what gets downloaded. Especially useful at high resolutions or when very large fonts are used. May slow down printing, especially on early 68000-based PostScript printers. Generally recommended today, and can be enabled in the configuration file (*note Configuration file commands::).

---

🌈 SEE ALSO 🌈

afm2tfm(1), tex(1), mf(1), dvips(1), dvitype(1), lpr(1), dvips.texi, README.overview.md, https://tug.org/dvips, https://github.com/vtex-soft/xdvipsk.

---

🧚 ENVIRONMENT 🧚

Xvipsk uses the same environment variables and algorithms for finding font files as TeX and its friends do. Check the docs for the Kpathsea library for the deets. (Repeating all of it here is just too cumbersome, ngl.)

• KPATHSEA_DEBUG — traces Kpathsea lookups; set it to -1 for complete tracing. 🔍
• PRINTER — see above.

---

👑 NOTES 👑

PostScript is a registered trademark of Adobe Systems Incorporated.

---

💖 AUTHOR 💖

Dvips created by Tomas Rokicki; extended to virtual fonts by Don Knuth. Path searching and configuration modifications by Karl Berry.

Main extensions by Arūnas Povilaitis; fonts management by Mindaugas Piešina; lua callbacks, configuration, and maintenance by Sigitas Tolušis.

Maintained in TeX Live; please send bug reports or other correspondence related to dvips to tex-k@tug.org (https://lists.tug.org/tex-k) and related xdvipsk to tex-dev@vtex.lt (https://github.com/vtex-soft/xdvipsk).

---

and that's the whole page, bestie!! 🫶 this beauty is dated 06 February 2026 and it lives under the name XDVIPSK(1). go forth and slay your DVI files. 💅✨