xdvipsk(1) General Commands Manual xdvipsk(1)
NAME
xdvipsk - convert a TeX DVI file to PostScript (dvips extexsion)
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 Make each section be a separate file; a "section" is a part of
the document processed independently, most often created to
avoid memory overflow. The filenames are created replacing the
suffix of the supplied output file name by a three-digit
sequence number. This option is most often used in conjunction
with the -S option which sets the maximum section length in
pages; if -i is specified and -S is not, each page is output as
a separate file. For instance, some phototypesetters cannot
print more than ten or so consecutive pages before running out
of steam; these options can be used to automatically split a
book into ten-page sections, each to its own file. On the other
hand, if your document uses very large fonts or very large
included figures, Dvips might take it upon itself to split the
output into unwanted sections, to try to avoid overflowing
printer memory.
[+]-I p
Resize mode for emTeX graphics
-j Download only needed characters 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
should be specified, 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. It
is 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. This is sometimes
necessary 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 the 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. Thus, 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 printer, if supported by the output
device.
-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',
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.
-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 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.
[+]-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
This sets the paper type to papertype. The papertype should be
defined in one of the configuration files, along with the
appropriate code to select it. (Currently known types include
letter, legal, ledger, a4, a3). You can also specify a
papertype of landscape, which rotates a document by 90 degrees.
To rotate a document whose paper type is not the default, you
can use the -t option twice, once for the paper type, and once
for landscape. In general, you should not use any -t option
when using a papersize special, which some LaTeX packages (e.g.,
'hyperref') insert. One exception is when using a nonstandard
paper size that is not already defined in config.ps; in this
case, you need to specify -tunknown. Another exception is when
producing multi-page files for further processing; use -t
nopaper to omit any paper size information in the output. (If
you just have a single page document, you can use -E to get pure
EPSF output.)
-T papersize
Set the paper size to papersize, a comma-separated pair of
dimensions such as '.1in,-.3cm' (*note papersize special::). It
overrides any paper size special in the DVI file. Be careful, as
the paper size will stick to a predefined size if there is one
close enough. To disable this behavior, use -tunknown.
title s
Use s as the title in the generated PostScript ('%%Title'). If
not specified, the default is the basename of the input file;
for example, running 'dvips /foo/bar.dvi' will have a '%%Title'
of 'bar.dvi'.
-u psmapfile
Set psmapfile to be the file that dvips uses for looking up
PostScript font aliases. If psmapfile begins with a + character,
then the rest of the name is used as the name of the map file,
and the map file is appended to the list of map files (instead
of replacing the list). In either case, if psmapfile has no
extension, then .map is added at the end.
-U Disable a PostScript virtual memory saving optimization that
stores the character metric information in the same string that
is used to store the bitmap information. This is only necessary
when driving the Xerox 4045 PostScript interpreter. It is
caused by a bug in that interpreter that results in `garbage' on
the bottom of each character. Not recommended unless you must
drive this printer.
-v Print the dvips version number and exit.
-V Download non-resident PostScript fonts as bitmaps. This requires
use of 'mtpk' or 'gsftopk' or 'pstopk' or some combination
thereof to generate the required bitmap fonts; these programs
are supplied with Dvips. The bitmap must be put into
'psfonts.map' as the downloadable file for that font. This is
useful only for those fonts for which you do not have real
outlines, being downloaded to printers that have no resident
fonts, i.e., very rarely.
[+]-W Extended search for emTeX graphics.
-x num Set the magnification ratio to num/1000. Overrides the
magnification specified in the DVI file. Must be between 10 and
100000. It is recommended that 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. num may be a
real number, not an integer, for increased precision.
-X num Set the horizontal resolution in dots per inch to num.
-y num Set the magnification ratio to num/1000 times the magnification
specified in the .dvi file. See -x above.
-Y num Set the vertical resolution in dots per inch to num.
-z Pass html hyperdvi specials through to the output for eventual
distillation into PDF. This is not enabled by default to avoid
including the header files unnecessarily, and use of temporary
files in creating the output.
-Z Compress bitmap fonts in the output file, thereby reducing the
size of 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 recommend 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. See the documentation for the
Kpathsea library for details. (Repeating it here is too cumbersome.)
KPATHSEA_DEBUG: Trace Kpathsea lookups; set 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 Arunas Povilaitis; fonts management by Mindaugas
Piesina; lua callbacks, configuration, and maintenance by Sigitas
Tolusis.
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)
06 February 2026 xdvipsk(1)
texlive-bin-extra 78219 - Generated Fri Mar 6 07:32:12 CST 2026