This is Info file dvips.info, produced by Makeinfo-1.64 from the input file /ade-src/contrib/unixtex/dvipsk/dvips.texi. START-INFO-DIR-ENTRY * DVIps: (dvips). DVI-to-PostScript translator. END-INFO-DIR-ENTRY File: dvips.info, Node: Including Graphics Fails, Next: Unable to Generate Fonts, Prev: Long Documents Fail, Up: Problems 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. File: dvips.info, Node: Unable to Generate Fonts, Prev: Including Graphics Fails, Up: Problems 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. *Note 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. File: dvips.info, Node: Color, Next: Index, Prev: Problems, Up: Top 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. * Menu: * Macro Files:: * User Definable Colors:: User Definable Colors * Color Subtleties:: Subtleties in Using Color * Ted Turner:: Printing in Black/White, after Colorizing * Color Configuration :: Configuring dvips for Color Devices * Color Support Details:: Color Support Details File: dvips.info, Node: Macro Files, Next: User Definable Colors, Up: 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 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. File: dvips.info, Node: User Definable Colors, Next: Color Subtleties, Prev: Macro Files, Up: Color 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. File: dvips.info, Node: Color Subtleties, Next: Ted Turner, Prev: User Definable Colors, Up: Color 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'. File: dvips.info, Node: Ted Turner, Next: Color Configuration, Prev: Color Subtleties, Up: Color 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. File: dvips.info, Node: Color Configuration, Next: Color Support Details, Prev: Ted Turner, Up: Color 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. File: dvips.info, Node: Color Support Details, Prev: Color Configuration, Up: Color 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. File: dvips.info, Node: Index, Prev: Color, Up: Top Index ***** * Menu: * -mode: Invoking dvips. * -pp RANGE: Invoking dvips. * .dvipsrc: Config File. * .enc: Special Font Effects. * @VAR@ substitutions: Installation. * bop-hook <1>: Bells and Whistles. * bop-hook: EPSF Macros. * config.ps: Invoking dvips. * end-hook: Bells and Whistles. * eop-hook: Bells and Whistles. * MakeTeXPK: Config File Options. * PKFONTS: Config File Options. * start-hook: Bells and Whistles. * vf: Config File Options. * METAFONT: Config File Options. * \.: afm2tfm. * \AA: afm2tfm. * \dot: afm2tfm. * \epsffile: EPSF Macros. * \H: afm2tfm. * \leavevmode: EPSF Macros. * \rotninety: Graphics Support. * a3: Invoking dvips. * a4: Invoking dvips. * ac_include: Installation. * accents: afm2tfm. * accents, in wrong position: afm2tfm. * afm: PostScript fonts. * afm2tfm <1>: PostScript fonts. * afm2tfm: afm2tfm. * afm2tfm options: Invoking Afm2tfm. * automatic font generation: Font Generation. * bounding box: Bounding Box. * c-auto.h.in: Installation. * CFLAGS: Installation. * CODINGSCHEME: Invoking Afm2tfm. * color: Color. * color macros: Macro Files. * color subtleties: Color Subtleties. * colors, user-definable: User Definable Colors. * command-line options: Invoking dvips. * compilation: Installation. * compressed PostScript: Dynamic Creation of Graphics. * compression: Invoking dvips. * CONFIG: Installation. * config.ps: Config File. * config.ps, editing: Installation. * configdir: Installation. * configuration: Installation. * configuration file path: Environment Variables. * configuration file searching: Config File. * configuration files: Config File Options. * configure, running: Installation. * control-D: Invoking dvips. * copies: Invoking dvips. * debug options: Debug Options. * debugging <1>: Problems. * debugging: Invoking dvips. * default resolutions: Config File Options. * devices, supporting more than one: Installation. * DOS: MS-DOS. * dot accent: afm2tfm. * downloading fonts: Non-resident Fonts. * drift: Config File Options. * DVIPSFONTS: Environment Variables. * DVIPSHEADERS <1>: Config File Options. * DVIPSHEADERS: Environment Variables. * DVIPSMAKEPK: Environment Variables. * DVIPSSIZES: Environment Variables. * dynamic creation of graphics: Dynamic Creation of Graphics. * dynamic font generation: Font Generation. * efficient fonts: afm2tfm. * ehandler.ps: No Output. * encoding file format: Changing Encodings. * environment variables: Environment Variables. * EOF: Invoking dvips. * epsf macros: EPSF Macros. * epsf.tex: EPSF Macros. * epsfsize: EPSF Macros. * epsfxsize: EPSF Macros. * expanded fonts <1>: Invoking Afm2tfm. * expanded fonts: Special Font Effects. * ExtendFont: Special Font Effects. * fallback resolutions: Config File Options. * filter <1>: Invoking dvips. * filter: Config File Options. * font reencoding: Special Font Effects. * fonts, downloading: Non-resident Fonts. * fonts, expanded: Special Font Effects. * fonts, free PostScript: Installation. * fonts, outlined: Special Font Effects. * fonts, remapping: Changing Encodings. * fonts, slanted: Special Font Effects. * fonts, small caps: Special Font Effects. * fonts, system PostScript: Installation. * generating fonts: Font Generation. * graphics: Including PostScript. * graphics support: Graphics Support. * header <1>: Invoking dvips. * header: Config File Options. * header files: Header Files. * header path: Config File Options. * Hungarian umlaut: afm2tfm. * install-data Make target: Installation. * install-exec Make target: Installation. * install_fonts Make variable: Installation. * installation: Installation. * installation directories, changing: Installation. * invoking dvips: Invoking dvips. * kerning: afm2tfm. * Knuth, Donald E.: PostScript fonts. * kpathsea/CONFIG: Installation. * landscape: Invoking dvips. * landscape orientation: Paper Size and Landscape. * last-resort font sizes: Environment Variables. * ledger: Invoking dvips. * legal: Invoking dvips. * letter: Invoking dvips. * ligature: afm2tfm. * literal headers: Literal headers. * literal PostScript: Literal PS. * macros for color: Macro Files. * macros for epsf inclusion: EPSF Macros. * magnification <1>: EPSF Macros. * magnification: Invoking dvips. * magscale: EPSF Macros. * Makefile.in: Installation. * MakeTeXPK <1>: Font Generation. * MakeTeXPK: Environment Variables. * MakeTeXPK, editing: Installation. * manual feed: Invoking dvips. * maxdrift <1>: Config File Options. * maxdrift: Invoking dvips. * media: Invoking dvips. * memory <1>: Config File Options. * memory: afm2tfm. * missfont.log: Invoking dvips. * MS-DOS: MS-DOS. * mtpk: Invoking dvips. * multiple output devices, supporting: Installation. * non-resident fonts: Non-resident Fonts. * oblique fonts: Special Font Effects. * options to Afm2tfm: Invoking Afm2tfm. * options to dvips: Invoking dvips. * outline fonts: Special Font Effects. * output <1>: Config File Options. * output: Invoking dvips. * output encoding of fonts: Changing Encodings. * page range: Invoking dvips. * pages: Invoking dvips. * PaintType: Special Font Effects. * paper size: Paper Size and Landscape. * paper type: Invoking dvips. * paths, changing default: Installation. * paths.make, editing: Installation. * pfa font: Non-resident Fonts. * pfb font: Non-resident Fonts. * pk path: Config File Options. * PostScript encoding of fonts: Changing Encodings. * PostScript fonts: PostScript fonts. * PostScript fonts, freely available: Installation. * PostScript fonts, on your system: Installation. * PostScript graphics: Including PostScript. * PRINTER <1>: Config File. * PRINTER: Environment Variables. * printer configuration files: Config File Options. * problems: Problems. * psfile: Graphics Support. * psfonts.map <1>: Special Font Effects. * psfonts.map <2>: Non-resident Fonts. * psfonts.map: Installation. * pstopk: Invoking dvips. * quiet <1>: Invoking dvips. * quiet: Config File Options. * ReEncodeFont: Special Font Effects. * reencoding of fonts: Special Font Effects. * remapping fonts: Changing Encodings. * resolution <1>: Config File Options. * resolution <2>: Invoking dvips. * resolution <3>: Config File Options. * resolution: Invoking dvips. * reverse <1>: Config File Options. * reverse: Invoking dvips. * scaleunit: Graphics Support. * scaling small caps: Invoking Afm2tfm. * SDict <1>: Literal headers. * SDict: Graphics Support. * searching config files, order of: Config File. * security: Invoking dvips. * slanted fonts <1>: Invoking Afm2tfm. * slanted fonts: Special Font Effects. * SlantFont: Special Font Effects. * small caps fonts: Special Font Effects. * structured comments: Invoking dvips. * Swedish A ring: afm2tfm. * system dependencies: Installation. * testpage.tex: Config File Options. * TEXCONFIG: Environment Variables. * TEXFONTS: Config File Options. * TEXINPUTS: Config File Options. * TEXPICTS <1>: Environment Variables. * TEXPICTS: Config File Options. * tfm: PostScript fonts. * TranScript: Invoking dvips. * trouble: Problems. * uncompressing PostScript: Dynamic Creation of Graphics. * user-definable colors: User Definable Colors. * virtual fonts <1>: afm2tfm. * virtual fonts: Config File Options. * VMusage: Header Files. * vptovf: afm2tfm.