dvips - convert a TeX DVI file to PostScript


SYNOPSIS

       dvips [ options ] file[.dvi]


DESCRIPTION

       THIS  MAN PAGE IS OBSOLETE!  See the Texinfo documentation
       instead.  You can read it either  in  Emacs  or  with  the
       standalone  info  program which comes with the GNU texinfo
       distribution as prep.ai.mit.edu:pub/gnu/texinfo*.tar.gz.

       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.

              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.

              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

              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

              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

              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.

              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.


Man(1) output converted with man2html