Including Graphics Fails
========================

  The reasons why graphics inclusions fail are too numerous to mention.
The most common problem is an incorrect bounding box; read the section
on bounding boxes and check your PostScript file.  Complain very loudly
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
should 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, to strip the comments
from an included figure.  This might be necessary if the PostScript
spooling software does not read the structuring 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.

Unable to Generate Fonts
========================

  This happens a lot if either `MakeTeXPK' hasn't been properly edited
and installed, or if the local installation of METAFONT isn't correct.

  `MakeTeXPK' must echo the generated filename (and nothing else) to
standard output. See Font Generation.

  If METAFONT isn't found when `MakeTeXPK' is running, then you need to
install it. Retrieve it from, e.g., `ftp.cs.umb.edu' in
`pub/tex/web2c.tar.gz' and `pub/tex/web.tar.gz'.

  If METAFONT runs but generates fonts that are too large (and prints
out the name of each character as well as just a character number), then
your METAFONT base file probably hasn't been made properly.  To make a
proper `plain.base', assuming the local mode definitions are contained
in `modes.mf' type the following command (assuming UNIX):
     inimf "plain; input modes; dump"

Then copy the `plain.base' file from the current directory to where the
base files are stored on your system.

Using Color with dvips
**********************

  This new feature of `dvips' is somewhat experimental so your
experiences and comments are welcome.  Initially added by Jim Hafner,
IBM Research, `hafner@almaden.ibm.com', the color support has gone
through many changes by Tomas Rokicki.  Besides the changes to the
source code itself, there are additional TeX macro files:
`colordvi.tex' and `blackdvi.tex'.  There are also `.sty' versions of
these files that can be used with LaTeX and other similar macro
packages.  This feature adds one-pass multi-color printing of TeX
documents on any color PostScript device.

  In this section we describe the use of color from the document
preparer's point of view and then add some simple instructions on
installation for the system administrator.

Macro Files
===========

  All the color macro commands are defined in `colordvi.tex' (or
`colordvi.sty').  To access these macros simply add to the top of your
TeX file the command

     \input colordvi

or, if your document uses style files like LaTeX, add the `colordvi'
style option as in

     \documentstyle[12pt,colordvi]{article}

  There are basically two kinds of color macros, ones for local color
changes to, say, a few words or even one symbol and one for global color
changes.  Note that all the color names use a mixed case scheme.  There
are 68 predefined colors, with names taken primarily from the Crayola
crayon box of 64 colors, and one pair of macros for the user to set his
own color pattern.  More on this extra feature later. You can browse the
file `colordvi.tex' for a list of the predefined colors.  The comments
in this file also show a rough correspondence between the crayon names
and PANTONEs.

  A local color command is in the form

     \ColorName{this will print in color}

Here `ColorName' is the name of a predefined color. As this example
shows, this type of command takes one argument which is the text that is
to print in the selected color.  This can be used for nested color
changes since it restores the original color state when it completes.
For example, suppose you were writing in green and want to switch
temporarily to red, then blue, back to red and restore green.  Here is
one way that you can do this:

     This text is green but here we are \Red{switching to red,
     \Blue{nesting blue}, recovering the red} and back to
     original green.

In principle there is no limit to the nesting level, but it is not
advisable to nest too deep lest you loose track of the color history.

  The global color command has the form

     \textColorName

This macro takes no arguments and immediately changes the default color
from that point on to the specified color. This of course can be
overriden globally by another such command or locally by local color
commands. For example, expanding on the example above, we might have

     \textGreen
     This text is green but here we are \Red{switching to red,
     \Blue{nesting blue}, recovering the red} and back to
     original green.
     \textCyan
     The text from here on will be cyan unless
     \Yellow{locally changed to yellow}. Now we are back to cyan.

  The color commands will even work in math mode and across math mode
boundaries.  This means that if you have a color before going into math
mode, the mathematics will be set in that color as well.  More
importantly however, in alignment environments like `\halign',
`tabular' or `eqnarray', local color commands cannot extend beyond the
alignment characters.

  Because local color commands respect only some environment and
deliminator changes besides their own, care must be taken in setting
their scope.  It is best not to have then stretch too far.

  At the present time there are no macros for color environments in
LaTeX which might have a larger range.  This is primarily to keep the
TeX and LaTeX use compatible.

User Definable Colors
=====================

  There are two ways for the user to specify colors not already defined.
For local changes, there is the command `\Color' which takes two
arguments.  The first argument is a quadruple of numbers between zero
and one and specifies the intensity of cyan, magenta, yellow and black
(CMYK) in that order.  The second argument is the text that should
appear in the given color.  For example, suppose you want the words
"this color is pretty" to appear in a color which is 50% cyan, 85%
magenta, 40% yellow and 20% black.  You would use the command

     \Color{.5 .85 .4 .2}{this color is pretty}

  For global color changes, there is a command `\textColor' which takes
one argument, the CMYK quadruple of relative color intensities.  For
example, if you want the default color to be as above, then the command

     \textColor{.5 .85 .4 .2}
     The text from now on will be this pretty color

will do the trick.

  Making a global color change in the midst of a nested local colors is
highly discouraged.  Consequently, dvips will give you warning message
and do its best to recover by discarding the current color history.

Subtleties in Using Color
=========================

  These color macros are defined by use of specialized `\special'
keywords.  As such, they are put in the `.dvi' file only as explicit
message strings to the driver.  The (unpleasant) result is that certain
unprotected regions of the text can have unwanted color side effects.
For example, if a color region is split by TeX across a page boundary,
then the footers of the current page (e.g., the page number) and the
headers of the next page can inherit that color.  To avoid this effect
globally, users should make sure that these special regions of the text
are defined with their own local color commands.  For example in TeX,
to protect the header and footer, use

     \headline{\Black{My Header}}
     \footline{\Black{\hss\tenrm\folio\hss}}

  This warning also applies to figures and other insertions, so be
careful!

  Of course, in LaTeX, this is much more difficult to do because of the
complexity of the macros that control these regions.  This is
unfortunate, but is somehow inevitable because TeX and LaTeX were not
written with color in mind.

  Even when writing your own macros, much care must be taken.  The color
macros that `colorize' a portion of the text work by prefixing the text
with a special command to turn the color on and postfixing it with a
different special command to restore the original color.  It is often
useful to ensure that TeX is in horizontal mode before the first
special command is issued; this can be done by prefixing the color
command with `\leavevmode'.

Printing in Black/White, after Colorizing
=========================================

  If you have a TeX or LaTeX document written with color macros and you
want to print it in black and white there are two options.  On all
(good) PostScript devices, printing a color file will print in
corresponding grey-levels.  This is useful since in this way you can get
a rough idea of where the colors are changing without using expensive
color printing devices.  The second option is to replace the call to
input `colordvi.tex' with `blackdvi.tex' (and similarly for the `.sty'
files).  So in the above example, replacing the word `colordvi' with
`blackdvi' suffices.  This file defines the color macros as no-ops, and
so will produce normal black/white printing.  By this simple mechanism,
the user can switch to all black/white printing without having to
ferret out the color commands.  Also, some device drivers, particularly
non-PostScript ones like screen previewers, will simply ignore the
color commands and so print in normal black/white.  Hopefully, in the
future screen previewers for color displays will be compatible with
some form of color support.

Configuring dvips for Color Devices
===================================

  To configure dvips for a particular color device you need to fine tune
the color parameters to match your devices color rendition.  To do this,
you will need a PANTONE chart for your device.  The header file
`color.lpro' shows a (rough) correspondence between the Crayola crayon
names and the PANTONE numbers and also defines default CMYK values for
each of the colors.  Note that these colors must be defined in CMYK
terms and not RGB as dvips outputs PostScript color commands in CMYK.
This header file also defines (if they are not known to the
interpreter) the PostScript commands `setcmykcolor' and
`currentcmykcolor' in terms of a RGB equivalent so if your device only
understands RGB, there should be no problem.

  The parameters set in this file were determined by comparing the
PANTONE chart of a Tektronics PHASER printer with the actual Crayola
Crayons.  Because these were defined for a particular device, the
actual color rendition on your device may be very different.  There are
two ways to adjust this.  One is to use the PANTONE chart for your
device to rewrite `color.lpro' prior to compilation and installation.
A better alternative, which supports multiple devices, is to add a
header file option in the configuration file for each device that
defines, in `userdict', the color parameters for those colors that need
redefining.

  For example, if you need to change the parameters defining
`Goldenrod' (approximately PANTONE 109) for your device `mycolordev',
do the following.  In the PANTONE chart for your device, find the CMYK
values for PANTONE 109.  Let's say they are `{\ 0 0.10 0.75 0.03 }'.
Then create a header file named `mycolordev.pro' with the commands

     userdict begin
     /Goldenrod { 0 0.10 0.75 0.03 setcmykcolor} bind def

Finally, in `config.mycolordev' add the line

     h mycolordev.pro

This will then define `Goldenrod' in your device's CMYK values in
`userdict' which is checked before defining it in `TeXdict' by
`color.pro'.

  This mechanism, together with additions to `colordvi.tex' and
`blackdvi.tex' (and the `.sty' files), can also be used to predefine
other colors for your users.

Color Support Details
=====================

  To support color, dvips recognizes a certain set of specials.  These
specials all start with the keyword `color' or the keyword `background'.

  We will describe `background' first, since it is the simplest.  The
`background' keyword must be followed by a color specification.  That
color specification is used as a fill color for the background.  The
last `background' special on a page is the one that gets issued, and it
gets issued at the very beginning of the page, before any text or
specials are sent.  (This is possible because the prescan phase of
dvips notices all of the color specials so that the appropriate
information can be written out during the second phase.)

  Ahh, but what is a color specification?  It is one of three things.
First, it might be a PostScript procedure as defined in a PostScript
header file.  The `color.pro' file defines 64 of these, including
`Maroon'.  This PostScript procedure must set the current color to be
some value; in this case, `Maroon' is defined as `0 0.87 0.68 0.32
setcmykcolor'.

  The second possibility is the name of a color model (initially, one of
`rgb', `hsb', `cmyk', or `gray') followed by the appropriate number of
parameters.  When dvips encounters such a macro, it sends out the
parameters first, followed by the string created by prefixing
`TeXcolor' to the color model.  Thus, the color specification `rgb 0.3
0.4 0.5' would generate the PostScript code `0.3 0.4 0.5 TeXrgbcolor'.
Note that the case of zero arguments is disallowed, as that is handled
by the single keyword case above (where no changes to the name are made
before it is sent to the PostScript file.)

  The third and final type of color specification is a double quote
followed by any sequence of PostScript.  The double quote is stripped
from the output.  For instance, the color specification `"AggiePattern
setpattern' will set the `color' to the Aggie logo pattern (assuming
such exists.)

  So those are the three types of color specifications.  The same type
of specifications are used by both the `background' special and the
`color' special.  The `color' special itself has three forms.  The
first is just `color' followed by a color specification.  In this case,
the current global color is set to that color; the color stack must be
empty when such a command is executed.

  The second form is `color push' followed by a color specification.
This saves the current color on the color stack and sets the color to be
that given by the color specification.  This is the most common way to
set a color.

  The final version of the `color' special is just `color pop', with no
color specification; this says to pop the color last pushed on the
color stack from the color stack and set the current color to be that
color.

  The `dvips' program correctly handles these color specials across
pages, even when the pages are repeated or reversed.

  These color specials can be used for things such as patterns or
screens as well as simple colors.  However, note that in the
PostScript, only one `color specification' can be active at a time.
For instance, at the beginning of a page, only the bottommost entry on
the color stack is sent; also, when a color is `popped', all that is
done is that the color specification from the previous stack entry is
sent.  No `gsave' or `grestore' is used.  This means that you cannot
easily mix usage of the `color' specials for screens and colors, just
one or the other.  This may be addressed in the future by adding
support for different `categories' of color-like state.