# Color

Dvips supports one-pass multi-color printing of TeX documents on any color PostScript device. Initially added by Jim Hafner, IBM Research, @email{hafner@almaden.ibm.com}, the color support has gone through many changes by Tomas Rokicki. Besides the source code support itself, there are additional TeX macro files: colordvi.tex' and blackdvi.tex', and corresponding .sty' versions for use with LaTeX.

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

## Color 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 plain TeX file the command:

\input colordvi


For (the obsolete) LaTeX 2.09, add the colordvi' style option as in:

\documentstyle[12pt,colordvi]{article}


For LaTeX 2e, these examples are not applicable. Instead, please see the documentation for the graphics package, available from CTAN:doc/latex/graphics/'. See also CTAN:doc/epslatex.ps'.

These macros provide two basic kinds of color macros: ones for local color changes (a few words, a single symbol) and one for global color changes (the whole document). All the color names use a mixed case scheme to avoid conflicts with other macros. 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 (see section User-definable colors). 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 has the form

\ColorName{this is the color ColorName}


where ColorName is the name of a predefined color, e.g., Blue'. As shown, these macros take one argument, the text to print in the specified color. This can be used for nested color changes since it restores the original color state when it completes. For example:

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


The color nesting level has no hard limit, but it is not advisable to nest too deeply lest you and the reader lose track of the color history. The global color command has the form

\textColorName


These macros take no arguments and changes the default color from that point on to ColorName. This of course can be overridden 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 until
\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. 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 delimiter changes besides their own, care must be taken in setting their scope. It is best not to have them 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 four 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 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.

## Color subtleties

Color macros are defined via \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, to protect the header and footer in plain TeX, 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 inevitable, because TeX and LaTeX were not written with color in mind.

Even when writing your own macros, much care must be taken. The macros that colorize' a portion of the text work prefix the text work by outputting one \special command to turn the color on before the text, and outputting another \special command afterwards 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 gray levels. This is useful to get a rough idea of the colors 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. blackdvi.tex' 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 black/white. Hopefully, in the future screen previewers for color displays will be compatible with some form of color support.

## Color device configuration

To configure Dvips for a particular color device you need to fine tune the color parameters to match your device's 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 Tektronix 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 (see section Configuration file commands) 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 on the Phaser) 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'. (On MS-DOS, you will have to call this file mycolordev.cfg'.)

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 start with the keyword color' or the keyword background', followed by a color specification.

### Color specifications

What is a color specification? 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 (Maroon') 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.)

### Color specials

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

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.

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