Contents:

Installation
  `config.ps' installation
  PostScript font installation
  Ghostscript installation
  Diagnosing problems
    Debug options
    No output at all
    Output too small or inverted
    Error messages from printer
    Long documents fail to print
    Including graphics fails


Installation
************

  (A copy of this chapter is in the distribution file `dvipsk/INSTALL'.)

  Installing Dvips is mostly the same as installing any Kpathsea-using
program.  Therefore, for the basic steps involved, *note Installation:
(kpathsea)Installation..  (A copy is in the file `kpathsea/INSTALL'.)

  For solutions to common installation problems and information on how
to report a bug, see the file `kpathsea/BUGS' (*note Bugs:
(kpathsea)Bugs.).  For solutions to Dvips-specific problems, *note
Debug options::..  Also see the Dvips home page at
`http://www.radicaleye.com/dvips'.

  Dvips does require some additional installation, detailed in the
sections below.  Also, to configure color devices, *note Color device
configuration::..

`config.ps' installation
========================

  Dvips has its own configuration files: a file `config.ps' for
sitewide defaults, and a file `config.PRINTER' for each printer (output
device).  Since these are site-specific, `make install' does not create
them; you must create them yourself.

  (These Dvips configuration files are independent of the Kpathsea
onfiguration file `texmf.cnf' (*note Config files: (kpathsea)Config
files.).

  Dvips configuration files contents and searching are described fully
in *Note Config files::.  The simplest way to create a new
configuration file is to copy and modify the file
`dvipsk/contrib/config.proto', seasoning with options to your taste
from *Note Config files::.  Here is `config.proto' for your reading
pleasure:
     % Prototype Dvips configuration file.
     
     % How to print, maybe with lp instead lpr, etc.
     o |lpr
     
     % Default resolution of this device, in dots per inch.
     D 600
     
     % Metafont mode.  (This is completely different from the -M command-line
     % option, which controls whether mktexpk is invoked.)  Get
     % `ftp://ftp.tug.org/tex/modes.mf' for a list of mode names.  This mode
     % and the D number above must agree, or mktexpk will get confused.
     M ljfour
     
     % Memory available. Download the three-line PostScript file:
     %   %! Hey, we're PostScript
     %   /Times-Roman findfont 30 scalefont setfont 144 432 moveto
     %   vmstatus exch sub 40 string cvs show pop showpage
     % to determine this number. (It will be the only thing printed.)
     m 3500000
     
     % Correct printer offset. You can use testpage.tex from the LaTeX
     % distribution to find these numbers. Print testpage.dvi more than once.
     O 0pt,0pt
     
     % Partially download Type 1 fonts by default.  Only reason not to do
     % this is if you encounter bugs.  (Please report them to
     % <tex-k@mail.tug.org> if you do.)
     j
     
     % Also look for fonts at these resolutions.
     R 300 600
     
     % With a high resolution and a RISC cpu, better to compress the bitmaps.
     Z
     
     % Uncomment these if you have and want to use PostScript versions of the
     % fonts.
     %p +cmfonts.map
     %p +lafonts.map
     %p +cyrfonts.map
     %p +eufonts.map
     
     % You will also want definitions for alternative paper sizes -- A4,
     % legal, and such.  Examples in `contrib/papersize.level2' and
     % `contrib/papersize.simple'.

PostScript font installation
============================

  To use PostScript fonts with TeX and Dvips, you need both metric
files (`.tfm' and `.vf') and the outlines (`.pfa' or `.pfb').  *Note
Font concepts::.

  To support the basic PostScript font set, the recommended (and
simplest) approach is to retrieve
`ftp://ftp.tug.org/tex/psfonts.tar.gz' and unpack it in your
`$(fontdir)' directory (`/usr/local/share/texmf/fonts' by default).
This archive contains metrics, outlines, and bitmaps (for previewing)
for the 35 de facto standard fonts donated by URW and the additional
high-quality freely available PostScript fonts donated by Adobe,
Bitstream, and URW, including geometrically-created variants such as
oblique and small caps.

  `CTAN:/fonts/psfonts' contains support for many additional fonts for
which you must buy outlines (Adobe, Bigelow & Holmes, Monotype,
Softkey, Y&Y).  `psfonts.tar.gz' is a small extract from this
directory.  (For CTAN info, *note unixtex.ftp: (kpathsea)unixtex.ftp.;
a copy is in the top-level file `INSTALL'.)

  If you have additional PostScript fonts, you can make them available
to Dvips by (1) giving them with appropriate filenames; and (2) running
Afm2tfm (*note Making a font available::.) to make TFM and VF metrics
for TeX and Dvips to use.  Also add them to `psfonts.map' if necessary
(*note psfonts.map::.); it contains everything contained in
`psfonts.tar.gz' and most fonts that come with Unix systems.

  Following are locations for vendor-supplied fonts.  Please mail
<tex-k@mail.tug.org> if you find fonts elsewhere on your system.

DEC Ultrix
     /usr/lib/DPS/outline/decwin

DEC Digital Unix
     /usr/lib/X11/fonts/Type1Adobe

HP HP-UX 9, 10
     /usr/lib/X11/fonts/type1.st/typefaces

IBM AIX
     /usr/lpp/DPS/fonts/outlines
     /usr/lpp/X11/lib/X11/fonts/Type1
     /usr/lpp/X11/lib/X11/fonts/Type1/DPS

NeXT
     /NextLibrary/Fonts/outline

SGI IRIX
     /usr/lib/DPS/outline/base /usr/lib/X11/fonts/Type1

Sun SunOS 4.x
     (NeWSprint only)
     newsprint_2.5/SUNWsteNP/reloc/$BASEDIR/
     NeWSprint/small_openwin/lib/fonts
     /usr/openwin/lib/X11/fonts/Type1/outline

Sun Solaris 2
     /usr/openwin/lib/X11/fonts/Type1/outline

VMS
     SYS$COMMON:[SYSFONT.XDPS.OUTLINE]

The NeXT system supplies more fonts than any others, but there's a lot
of overlap.

  Finally, if you have an Hewlett-Packard printer, you should be able to
get Type 1 font files for the standard 35 fonts from HP, if the freely
available URW Type 1's do not satisfy for whatever reason.  The phone
number for HP Printer Drivers is (in the United States) 303-339-7009.
The driver set to ask for is Adobe Type Manager 2.51, and the disk set
number is `MP210en3'.  Mentioning anything other than Microsoft Windows
when you ask for the driver set will likely lead to great confusion on
the other end.

Ghostscript installation
========================

  Ghostscript is a PostScript interpreter freely available to end-users,
written by Peter Deutsch.  It can read the PostScript produced by Dvips
and render it on your monitor, or for another device (e.g., an Epson
printer) that does not support PostScript, or in PDF format.  The latest
version is available via `http://www.cs.wisc.edu/~ghost/index.html' and
`ftp://ftp.cs.wisc.edu/pub/ghost/aladdin/'.

  A somewhat older version of Ghostscript is available under the GNU
General Public License, free to everyone.  You can get that from
`ftp://prep.ai.mit.edu/pub/gnu/'.

  The program Ghostview, written by Tim Theisen, provides typical
previewing capabilities (next page/previous page, magnification, etc.).
It requires Ghostscript to run, and files in structured Postscript,
specifically with `%%Page' comments (no `N' in `config.ps').  You can
get Ghostview from the same places as Ghostscript.

Diagnosing problems
===================

  You've gone through all the trouble of installing Dvips, carefully
read all the instructions in this manual, and still can't get something
to work.  The following sections provide some helpful hints if you find
yourself in such a situation.

  For details on effective bug reporting, common installation problems,
and `mktexpk' problems, *note Bugs: (kpathsea)Bugs..

Debug options
-------------

  The `-d' flag to Dvips helps in tracking down certain errors.  The
parameter to this flag is an integer that tells what errors are
currently being tracked.  To track a certain class of debug messages,
simply provide the appropriate number given below; if you wish to track
multiple classes, sum the numbers of the classes you wish to track.  To
track all classes, you can use `-1'.  Another useful value is `3650',
which tracks everything having to do with file searching and opening.

  Some of these debugging options are actually provided by Kpathsea
(*note Debugging: (kpathsea)Debugging.).

  The classes are:
1
     specials

2
     paths

4
     fonts

8
     pages

16
     headers

32
     font compression

64
     files

128
     config files

256
     Partial Type 1 font encoding vectors

512
     Partial Type 1 subr calls

1024
     Kpathsea `stat' calls

2048
     Kpathsea hash table lookups

4096
     Kpathsea path element expansion

8192
     Kpathsea path searches

No output at all
----------------

  If you are not getting any output at all, even from the simplest
one-character file (for instance, `\ \bye'), then something is very
wrong.  Practically any file sent to a PostScript laser printer should
generate some output, at the very least a page detailing what error
occurred, if any.  Talk to your system administrator about downloading a
PostScript error handler.  (Adobe distributes a good one called
`ehandler.ps'.)

  It is possible, especially if you are using non-Adobe PostScript, that
your PostScript interpreter is broken.  Even then it should generate an
error message.  Dvips tries to work around as many bugs as possible in
common non-Adobe PostScript interpreters, but doubtless it misses a few.
PowerPage Revision 1, Interpreter Version 20001.001, on a Mitsubishi
Shinko CHC-S446i color thermal dye sublimation printer is known to be
unable to print with any but builtin fonts.

  If Dvips gives any strange error messages, or compilation on your
machine generated a lot of warnings, perhaps the Dvips program itself is
broken.  Try using the debug options to determine where the error
occurred (*note Debug options::.).

  It is possible your spooler is broken and is misinterpreting the
structured comments.  Try the `-N' flag to turn off structured comments
and see what happens.

Output too small or inverted
----------------------------

  If some documents come out inverted or too small, probably your
spooler is not supplying an end of job indicator at the end of each
file.  (This commonly happens on small machines that don't have
spoolers.)  You can force Dvips to do this with the `-F' flag (or `F'
config file option), but this generates files with a terminating binary
character (control-D).  You can also try using the `-s' flag (or `s'
config file option) to enclose the entire job in a save/restore pair.
*Note Command-line options::, and *Note Config files::.

Error messages from printer
---------------------------

  If your printer returns error messages, the error message gives very
good information on what might be going wrong.  One of the most common
error messages is `bop undefined'.  This is caused by old versions of
Transcript and other spoolers that do not properly parse the setup
section of the PostScript.  To fix this, turn off structured comments
with the `-N' option, but it'd be best to get your spooling software
updated.

  Another error message is `VM exhausted'.  Some printers indicate this
error by locking up, others quietly reset.  This is caused by Dvips
thinking that the printer has more memory than it actually does, and
then printing a complicated document.  To fix this, try lowering the
`m' parameter in the configuration file; use the debug option to make
sure you adjust the correct file.

  Other errors may indicate you are trying to include graphics that
don't nest properly in other PostScript documents, among other things.
Try the PostScript file on a QMS PS-810 or other Adobe PostScript
printer if you have one, or Ghostscript (*note Ghostscript
installation::.); it might be a problem with the printer itself.

Long documents fail to print
----------------------------

  This is usually caused by incorrectly specifying the amount of memory
the printer has in the configuration file; see the previous section.

Including graphics fails
------------------------

  The most common problem with including graphics is an incorrect
bounding box (*note Bounding box::.). Complain to whoever wrote the
software that generated the file if the bounding box is indeed
incorrect.

  Another possible problem is that the figure you are trying to include
does not nest properly; there are certain rules PostScript applications
must follow when generating files to be included.  The Dvips program
includes work-arounds for such errors in Adobe Illustrator and other
programs, but there are certainly applications that haven't been tested.

  One possible thing to try is the `-K' flag which strips the comments
from an included figure.  This might be necessary if the PostScript
spooling software does not read the structured comments correctly.  Use
of this flag will break graphics from some applications, though, since
some applications read the PostScript file from the input stream,
looking for a particular comment.

  Any application which generates graphics output containing raw binary
(not ASCII hex) will probably fail with Dvips.

