DVIPS(1)                                                 DVIPS(1)

NAME
       dvips - convert a TeX DVI file to PostScript

SYNOPSIS
       dvips [ options ] file[.dvi]

DESCRIPTION
       The  program dvips takes a DVI file file[.dvi] produced by
       TeX (or by some other processor such as GFtoDVI) and  con-
       verts  it  to  PostScript,  normally  sending  the  result
       directly to the (laser)printer.  The DVI file may be spec-
       ified  without  the .dvi extension.  Fonts used may either
       be resident in the printer or defined  as  bitmaps  in  PK
       files, or a `virtual' combination of both.  If the mktexpk
       program is  installed,  dvips  will  automatically  invoke
       METAFONT to generate fonts that don't already exist.

       For  more  information, see the Texinfo manual dvips.texi,
       which should be installed somewhere on your system,  hope-
       fully accessible through the standard Info tree.

OPTIONS
       -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  odd  pages  (TeX  pages,  not sequence
              pages).

       -b num Generate num copies of each page,  but  duplicating
              the  page  body  rather  than  using the #numcopies
              option.  This can be useful in conjunction  with  a
              header  file  setting \bop-hook to do color separa-
              tions or other neat tricks.

       -B     Print only even  pages  (TeX  pages,  not  sequence
              pages).

       -c num Generate  num  copies of every page.  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.  This  is  intended  only  for
              emergencies  or  for  unusual  fact-finding expedi-
              tions; it will work only if dvips has been compiled
              with  the  DEBUG  option.  If nonzero, prints addi-
              tional information on standard output.  The  number
              is taken as a set of independent bits.  The meaning
              of each bit follows.  1=specials; 2=paths; 4=fonts;
              8=pages; 16=headers; 32=font compression; 64=files;
              128=memory; 256=Kpathsea stat(2) calls;  512=Kpath-
              sea  hash table lookups; 1024=Kpathsea path element
              expansion; 2048=Kpathsea searches.  To trace every-
              thing having to do with file searching and opening,
              use 3650 (2048 + 1024 + 512 + 64 + 2). To track all
              classes,  you  can  use  `-1'  (output is extremely
              voluminous).

       -D num Set the resolution in dpi (dots per inch)  to  num.
              This  affects  the  choice of bitmap fonts that are
              loaded and also the positioning of letters in resi-
              dent  PostScript  fonts.  Must  be  between  10 and
              10000.  This affects both the horizontal and verti-
              cal  resolution.   If  a high resolution (something
              greater than 400 dpi, say) is selected, the -Z flag
              should probably also be used.

       -e num Make  sure  that  each  character is placed at most
              this many pixels from its  `true'  resolution-inde-
              pendent  position on the page. The default value of
              this parameter is resolution  dependent.   Allowing
              individual  characters  to  `drift' from their cor-
              rectly 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     makes dvips attempt to generate an EPSF file with a
              tight bounding box.  This only  works  on  one-page
              files,  and  it only looks at marks made by charac-
              ters and rules, not by any included  graphics.   In
              addition,  it  gets  the glyph metrics from the tfm
              file, so characters that lie outside their  enclos-
              ing  tfm  box  may  confuse  it.   In addition, the
              bounding box might be a bit too loose if the  char-
              acter  glyph  has  significant  left  or right side
              bearings.  Nonetheless, this option works well  for
              creating  small  EPSF files for equations or tables
              or the like.  (Note, of course, that  dvips  output
              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 a great deal of
              care.)

       -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,  and  turns off the
              automatic sending of control D if it was turned  on
              with  the  -F  option or in the configuration file;
              use -F after this option if you want both.

       -F     Causes Control-D (ASCII code 4) to be  appended  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 extremely small systems.  NOTE! DO NOT
              USE THIS OPTION!

       -h name
              Prepend  file  name  as  an additional header file.
              (However, if the name is simply  `-'  suppress  all
              header  files  from  the output.)  This header file
              gets added to the PostScript userdict.

       -i     Make each section be a separate file.   Under  cer-
              tain  circumstances,  dvips will split the document
              up into `sections' to be  processed  independently;
              this  is most often done for memory reasons.  Using
              this option tells dvips to place each section  into
              a  separate  file;  the  new file names 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.  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.

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

       -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 pack-
              ages 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 get-
              ting better.

       -l num The last page printed will be the  first  one  num-
              bered 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.

       -m     Specify manual feed for printer.

       -M     Turns  off  the automatic font generation facility.
              If any fonts are missing, commands to generate  the
              fonts  are appended to the file missfont.log in the
              current directory; this file can then  be  executed
              and deleted to create the missing fonts.

       -n num At  most  num  pages  will  be  printed. Default is
              100000.

       -N     Turns off structured comments; this might be neces-
              sary   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.

       -o name
              The  output  will  be  sent to file name If no file
              name is given, the default name  is  file.ps  where
              the  .dvi  file was called file.dvi; if this option
              isn't given, any default in the configuration  file
              is  used.   If  the first character of the supplied
              output file name is an exclamation mark,  then  the
              remainder  will  be  used  as an argument to popen;
              thus, specifying !lpr as the output file will auto-
              matically queue the file for printing.  This option
              also disables the automatic reading of the  PRINTER
              environment  variable,  and turns off the automatic
              sending of control D if it was turned on  with  the
              -F  option  or  in  the  configuration file; use -F
              after this option if you want both.

       -O offset
              Move the origin by a certain amount.  The offset is
              a  comma-separated  pair  of  dimensions,  such  as
              .1in,-.3cm (in the same syntax used in  the  paper-
              size  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.

       -p num The first page printed will be the first  one  num-
              bered  num.  Default is the first page in the docu-
              ment.  If the num is prefixed by  an  equals  sign,
              then  it  (and  any  argument  to the -l option) is
              treated as a sequence number, rather than  a  value
              to  compare with \count0 values.  Thus, using -p =3
              will start with the third page of the document,  no
              matter what the pages are actually numbered.

       -pp pagelist
              A  comma-separated  list  of pages and ranges (a-b)
              may be given, which will be interpreted as  \count0
              values.   Pages  not specified will not be printed.
              Multiple -pp options may be specified or all  pages
              and  page  ranges  can  be  specified  with one -pp
              option.

       -P printername
              Sets up the output  for  the  appropriate  printer.
              This  is  implemented by reading in config.printer-
              name , which can then set the output pipe  (as  in,
              !lpr  -Pprintername  as  well as the font paths and
              any other config.ps defaults for that printer only.
              Note  that config.ps is read before config.printer-
              name In addition, another file called ~/.dvipsrc is
              searched for immediately after config.ps; this file
              is intended for user defaults.  If no -P command is
              given, the environment variable PRINTER is checked.
              If that variable exists, and a  corresponding  con-
              figuration  file exists, that configuration file is
              read in.

       -q     Run in quiet mode.  Don't chatter about pages  con-
              verted, etc.; report nothing but errors to standard
              error.

       -r     Stack pages in reverse  order.   Normally,  page  1
              will be printed first.

       -R     Run  in  secure  mode. This means that ``backtick''
              commands from a \special{} or \psffile{}  macro  in
              the   (La)TeX  source  like  \special{psfile="`zcat
              foo.ps.Z"}  or  \psffile[72  72   540   720]{"`zcat
              screendump.ps.gz"} are not executed.

       -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 paper-
              type 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 -t land-
              scape, which rotates a document by 90 degrees.   To
              rotate a document whose size is not letter, you can
              use the -t option twice, once for  the  page  size,
              and  once  for landscape.  The upper left corner of
              each page in the .dvi file is placed one inch  from
              the  left  and  one inch from the top.  Use of this
              option is highly  dependent  on  the  configuration
              file.   Note  that  executing  the  letter or a4 or
              other PostScript operators cause the document to be
              nonconforming and can cause it not to print on cer-
              tain printers, so the paper size should not execute
              such an operator if at all possible.

       -T offset
              Set the paper size to the given pair of dimensions.
              This option takes its arguments in the  same  style
              as  -O.  It overrides any paper size special in the
              dvi file.

       -U     Disable a PostScript virtual  memory  saving  opti-
              mization  that stores the character metric informa-
              tion 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     Download  non-resident PostScript fonts as bitmaps.
              This requires use of `gsftopk' or `pstopk' or  some
              other  such  program(s)  in  order  to generate the
              required bitmap fonts; these programs are  supplied
              with dvips.

       -x num Set the magnification ratio to num /1000. Overrides
              the magnification specified in the .dvi file.  Must
              be between 10 and 100000.

       -X num Set  the  horizontal resolution in dots per inch to
              num.

       -Y num Set the vertical resolution in  dots  per  inch  to
              num.

       -Z     Causes bitmapped fonts to be compressed before they
              are downloaded, thereby reducing the  size  of  the
              PostScript   font-downloading  information.   Espe-
              cially useful at  high  resolutions  or  when  very
              large  fonts  are  used.   Will  slow down printing
              somewhat,   especially   on    early    68000-based
              PostScript printers.

SEE ALSO
       mf(1), afm2tfm(1), tex(1), latex(1), lpr(1), dvips.texi.

ENVIRONMENT
       Dvipsk  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 com-
       plete tracing.

       PRINTER: see above.

NOTES
       PostScript  is  a  registered  trademark  of Adobe Systems
       Incorporated.

AUTHOR
       Tomas Rokicki <rokicki@cs.stanford.edu>; extended to  vir-
       tual fonts by Don Knuth.  Path searching and configuration
       modifications by kb@mail.tug.org.

                           1 June 1996                          1