% This document describes how to use dvips. Macros at top cut and % slashed from another document. \newif\ifgeneric\genericfalse \ifx\ntmanloaded Y\else\input dvipsmac \fi % uh oh, no macros, give our own. % Finally, the document itself. The \.{dvips} program converts a \TeX\ \.{dvi} file into a PostScript file for printing or distribution. Seldom has such a seemingly easy programming task required so much effort. % Why use dvips? \sec{Why Use dvips?} The \.{dvips} program has a number of features that set it apart from other PostScript drivers for \TeX. This rather long section describes the advantages \^{{\tt dvips}} \^{PostScript} of using \.{dvips}, and may be skipped if you are just interested in learning how to use the program. Installation is covered in section 14 near the end of this document. The \.{dvips} driver generates excellent, standard PostScript, that can be included in other documents as figures or printed through a variety of spoolers. The generated PostScript requires very little printer memory, so very complex documents with a lot of fonts can easily be printed even on PostScript printers without much memory, such as the original Apple LaserWriter. The PostScript output is also compact, requiring less disk space to store and making it feasible as a transfer format. Even those documents that are too complex to print in their entirety on a particular printer can be printed, since \.{dvips} will automatically split such documents \^{memory} into pieces, reclaiming the printer memory between each piece. The \.{dvips} program supports graphics in a natural way, allowing PostScript graphics to be included and automatically scaled and positioned in a variety of ways. Printers with resolutions other than 300 dpi are also supported, even if they have a different resolution in the horizontal and vertical directions. High resolution output is supported for typesetters, including an option that compresses the bitmapped fonts so that typesetter virtual memory is \^{resolution} not exhausted. This option also significantly reduces the size of the PostScript file and decoding in the printer is very fast. Missing fonts can be automatically generated if \MF\ exists on the system, or fonts can be converted from \.{gf} to \.{pk} format on demand. \^{automatic font generation} If a font cannot be generated, a scaled version of the same font at a different size can be used instead, although \.{dvips} will complain loudly about the poor \ae sthetics of the resulting output. Users will appreciate features such as collated copies and support for \.{tpic}, \.{psfig}, \.{emtex}, and \.{METAPOST}; \^{{\tt tpic}} \^{{\tt psfig}} \^{{\tt emtex}} \^{{\tt METAPOST}} system administrators will love the support for multiple printers, each with their own configuration file, and the ability to pipe the output directly to a program such as \.{lpr}. Support for MS-DOS and VMS in addition to UNIX is provided in the \^{MS-DOS} \^{UNIX} \^{VMS} standard distribution, and porting to other systems is easy. One of the most important features is the support of virtual fonts, which add an entirely new level of flexibility to \TeX. Virtual fonts are used to give \.{dvips} its excellent PostScript font support, handling all the font remapping in a natural, portable, elegant, and extensible way. The \.{dvips} \^{{\tt afm2tfm}} driver even comes with its own \.{afm2tfm} program that creates the necessary virtual fonts and \TeX\ font metric files automatically from the Adobe font metric files. Source is provided and freely distributable, so adding a site-specific feature is possible. Adding such features is made easier by the highly modular structure of the program. There is really no reason to use another driver, and the more people use \.{dvips}, the less time will be spent fighting with PostScript and the more time will be available to create beautiful documents. So if you don't use \.{dvips} on your system, get it today. \sec{Using dvips} To use \.{dvips}, simply type \cmd{localhost> dvips foo} \noindent where \.{foo.dvi} is the output of \TeX\ that you want to print. If \.{dvips} has been installed correctly, the document should come out of your default printer. If you use fonts that have not been used on your system before, they may be automatically generated; this process can take a few minutes. The next time that document is printed, these fonts will already exist, so printing will go much faster. Many options are available; they are described in a later section. For a brief summary of available options, just type \cmd{localhost> dvips} \sec{Paper Size and Landscape Mode} Most \TeX\ documents at a particular site are designed to use the standard paper size (for example, letter size in the United States or A4 in Europe.) The \.{dvips} program defaults to these paper sizes and can be customized for the defaults at each site or on each printer. But many documents are designed for other paper sizes. For instance, you may want to design a document that has the long edge of the \^{landscape} paper horizontal. This can be useful when typesetting booklets, brochures, complex tables, or many other documents. This type of paper orientation is called landscape orientation (the `normal' orientation is portrait). \^{portrait} Alternatively, a document might be designed for ledger or A3 paper. Since the intended paper size is a document design decision, and not a decision that is made at printing time, such information should be given in the \TeX\ file and not on the \.{dvips} command line. For this reason, \.{dvips} supports a \.{papersize} special. It is hoped that this special will become standard over time for \TeX\ previewers and other printer drivers. The format of the \.{papersize} special is \cmd{\ttbackslash special\char123papersize=8.5in,11in\char125} \noindent where the dimensions given above are for a standard letter sheet. The first dimension given is the horizontal size of the page, and the second is the vertical size. The dimensions supported are the same as for \TeX; namely, in (inches), cm (centimeters), mm (millimeters), pt (points), sp (scaled points), bp (big points, the same as the default PostScript unit), pc (picas), dd (didot points), and cc (ciceros). For a landscape document, the \.{papersize} comment would be given as \cmd{\ttbackslash special\char123papersize=11in,8.5in\char125} \noindent An alternate specification of \.{landscape} is to have a special of the form \cmd{\ttbackslash special\char123landscape\char125} \noindent This is supported for backward compatibility, but it is hoped that eventually the \.{papersize} comment will dominate. Of course, using such a command only informs \.{dvips} of the desired paper size; you must still adjust the \.{hsize} and \.{vsize} in your \TeX\ document to actually use the full page. The {\tt papersize} special must occur somewhere on the first page of the document. The {\tt dvips} default landscape configuration is presently as though the paper were rotated ninety degrees counterclockwise; this seems to be the convention adopted by previewers that the author is familiar with. If for some reason you need your landscape orientation to be rotated clockwise, simply include at the top of your \TeX\ file or in some included macro file \cmd{\ttbackslash special\char123! /landplus90 true store\char125} \noindent to set this orientation. Alternatively, you can change the default value of {\tt landplus90} in the {\tt tex.lpro} file before compilation, or include a header file that just includes the definition {\tt /landplus90 true store}. \sec{Including PostScript Graphics} Scaling and including PostScript graphics is a breeze---if the PostScript \^{graphics} \^{PostScript graphics} file is correctly formed. Even if it is not, however, the file can usually be accommodated with just a little more work. The most important feature of a good PostScript file---from the standpoint of including it in another document---is an accurate bounding box comment. \sub{The Bounding Box Comment} Every well-formed PostScript file has a comment describing where on the \^{bounding box} page the graphic is located, and how big that graphic is. This information is given in terms of the lower left and upper right corners of a box just enclosing the graphic, and is thus referred to as a bounding box. These coordinates are given in PostScript units (there are precisely 72 PostScript units to the inch) with respect to the lower left corner of the sheet of paper. To see if a PostScript file has a bounding box comment, just look at the first few lines of the file. (PostScript is standard ASCII, so you can use any text editor to do this.) If within the first few dozen lines there is a line of the form \cmd{\%\%BoundingBox:\ 0 1 2 3} \noindent (with any numbers), chances are very good that the file is Encapsulated PostScript and will work easily with \.{dvips}. If the file contains instead a line like \cmd{\%\%BoundingBox:\ (atend)} \noindent the file is still probably Encapsulated PostScript, but the bounding box (that \.{dvips} needs to position the graphic) is at the end of the file and should be moved to the position of the line above. This can be done with that same text editor, or with a simple Perl script. If the document lacks a bounding box altogether, one can easily be added. Simply print the file. Now, take a ruler, and make the following measurements. All measurements should be in PostScript units, so measure it in inches and multiply by 72. Alternatively, the {\tt bbfig} program distributed with {\tt dvips} in the {\tt contrib} directory can be used to automate this process. From the left edge of the paper to the leftmost mark on the paper is {\it llx}, the first number. From the bottom edge of the paper to the bottommost mark on the paper is {\it lly}, the second number. From the left edge of the paper to the rightmost mark on the paper is {\it urx}, the third number. The fourth and final number, {\it ury}, is the distance from the bottom of the page to the uppermost mark on the paper. Now, add a comment of the following form as the second line of the document. (The first line should already be a line starting with the two characters `{\tt \%!}'; if it is not, the file probably isn't PostScript.) \cmd{\%\%BoundingBox:\ {\it llx lly urx ury}} \noindent Or, if you don't want to modify the file, you can simply write these numbers down in a convenient place and use them when you import the graphic. If the document does not have such a bounding box, or if the bounding box is given at the end of the document, please complain to the authors of the software package that generated the file; without such a line, including PostScript graphics can be tedious. \sub{Using the EPSF Macros} Now you are ready to include the graphic into a \TeX\ file. Simply add to \^{{\tt epsf} macros} the top of your \TeX\ file a line like \cmd{\ttbackslash input epsf} \noindent (or, if your document is in La\TeX\ or Sli\TeX, add the \.{epsf} style option, as was done to the following line). \cmd{\ttbackslash documentstyle[12pt,epsf]\char123article\char125} \noindent This only needs to be done once, no matter how many figures you plan to include. Now, at the point you want to include the file, enter a line such as \cmd{\ttbackslash epsffile\char123foo.ps\char125} \noindent If you are using La\TeX\ or Sli\TeX, you may need to add a \.{\ttbackslash leavevmode} command immediately before the \^{{\tt leavevmode}} \.{\ttbackslash epsffile} command to get certain environments to work correctly. If your file did not (or does not currently) have a bounding box comment, you should supply those numbers you wrote down as in the following example: \cmd{\ttbackslash epsffile[100 100 500 500]\char123foo.ps\char125} \noindent (in the same order they would have been in a normal bounding box comment). Now, save your changes and run \TeX\ and \.{dvips}; the output should have your graphic positioned at precisely the point you indicated, with the proper amount of space reserved. The effect of the \.{\ttbackslash epsffile} macro is to typeset the figure as a \TeX\ \.{\ttbackslash vbox} at the point of the page that the command is executed. By default, the graphic will have its `natural' width (namely, the width of its bounding box). The \TeX\ box will have depth zero and a `natural' height. The graphic will be scaled by any \.{dvi} magnification in effect at the \^{magnification} time. Any PostScript graphics included by any method in this document (except \^{{\tt bop-hook}} \.{bop-hook} and its ilk) are scaled by the current \.{dvi} magnification. For graphics included with \.{\ttbackslash epsffile} where the size is given in \TeX\ dimensions, this scaling will produce the correct, or expected, results. For compatibility with old PostScript drivers, it is possible to turn \^{{\tt magscale}} this scaling off with the following \TeX\ command: \cmd{\ttbackslash special\char123! /magscale false def\char125} \noindent Use of this command is not recommended because it will make the \.{\ttbackslash epsffile} graphics the wrong size if global magnification is used in a \.{dvi} document, and it will cause any PostScript graphics to appear improperly scaled and out of position if a \.{dvi} to \.{dvi} program is used to scale or otherwise modify the document. You can enlarge or reduce the figure by putting \cmd{\ttbackslash epsfxsize=} \noindent right before the call to \.{\ttbackslash epsffile}. Then the width of the \TeX\ box will be \.{} and its height will be scaled proportionately. Alternatively you can force the \^{{\tt epsfxsize}} vertical size to a particular size with \cmd{\ttbackslash epsfysize=} \noindent in which case the height will be set and the width will be scaled proportionally. If you set both, the aspect ratio of the included graphic will be distorted but both size specifications will be honored. By default, clipping is disabled for included EPSF images. This is because clipping to the bounding box dimensions often cuts off a small portion of the figure, due to slightly inaccurate bounding box arguments. The problem might be subtle; lines around the boundary of the image might be half their intended width, or the tops or bottoms of some text annotations might be sliced off. If you want to turn clipping on, just use the command \cmd{\ttbackslash epsfclipon} \noindent and to turn clipping back off, use \cmd{\ttbackslash epsfclipoff} A more general facility for sizing is available by defining the \.{\ttbackslash epsfsize} macro. You can redefine this macro \^{{\tt epsfsize}} to do almost anything. This \TeX\ macro is passed two parameters by \.{\ttbackslash epsffile}. The first parameter is the natural horizontal size of the PostScript graphic, and the second parameter is the natural vertical size. This macro is responsible for returning the desired horizontal size of the graph (the same as assigning \.{\ttbackslash epsfxsize} above). In the definitions given below, only the body is given; it should be inserted \cmd{\ttbackslash def\ttbackslash epsfsize\#1\#2\char123{\it body}\/\char125} \noindent Some common definitions are: {\options \.{\ttbackslash epsfxsize} This definition (the default) enables the default features listed above, by setting \.{\ttbackslash epsfxsize} to the same value it had before the macro was called. \.{0pt} This definition forces natural sizes for all graphics by setting the width to zero, which turns on horizontal scaling. \.{\#1} This forces natural sizes too, by returning the first parameter only (the natural width) and setting the width to it. \.{\ttbackslash hsize} This forces all graphics to be scaled so they are as wide as the current horizontal size. (In La\TeX, use \.{\ttbackslash textwidth} instead of \.{\ttbackslash hsize}.) \.{0.5\#1} This scales all figures to half of their natural size. \.{\ttbackslash ifdim\#1>\ttbackslash hsize\ttbackslash hsize\ttbackslash else\#1\ttbackslash fi} This keeps graphics at their natural size, unless the width would be wider than the current \.{\ttbackslash hsize}, in which case the graphic is scaled down to \.{\ttbackslash hsize}.\par} If you want \TeX\ to report the size of the figure as a message on your terminal when it processes each figure, give the command \cmd{\ttbackslash epsfverbosetrue} \sub{Header Files} Often in order to get a particular graphic file to work, a certain header \^{header} file might need to be sent first. Sometimes this is even desirable, since the size of the header macros can dominate the size of certain PostScript graphics files. The \.{dvips} program provides support for this with the \.{header=} special command. For instance, to ensure that \.{foo.ps} gets downloaded as part of the header material, the following command should be added to the \TeX\ file: \cmd{\ttbackslash special\char123header=foo.ps\char125} \noindent The dictionary stack will be at the \.{userdict} level when these header files are included. For these and all other header files (including the headers required by \.{dvips} itself and any downloaded fonts), the printer VM budget is debited by some value. If the header file has, in its first 1024 bytes, a line of the form \cmd{\%\%VMusage: {\it min} {\it max}} \noindent then the maximum value is used. If it doesn't, then the total size of the header file in bytes is used as an approximation of the memory requirements. \sub{Literal PostScript} For simple graphics, or just for experimentation, literal PostScript \^{literal PostScript} graphics can be included. Simply use a special command that starts with a double quote ({\tt"}). For instance, the following (simple) graphic: \vskip\baselineskip \vbox to 100bp{\vss % a bp is the same as a PostScript unit \special{" newpath 0 0 moveto 100 100 lineto 394 0 lineto closepath gsave 0.8 setgray fill grestore stroke}} \noindent was created by typing: \cmd{\ttbackslash vbox to 100bp\char123\ttbackslash vss \% a bp is the same as a PostScript unit\\ \ttbackslash special\char123" newpath 0 0 moveto 100 100 lineto 394 0 lineto\\ closepath gsave 0.8 setgray fill grestore stroke\char125\char125} \noindent (Note that you are responsible for leaving space for such literal graphics.) Literal graphics are discouraged because of their nonportability. \sub{Literal Headers} Similarly, you can define your own macros for use in such literal graphics through the use of literal macros. Literal macros are defined just like literal graphics, only you begin the special with an exclamation point instead of a double quote. These literal macros are included as part of the header material in a special dictionary called \.{SDict}. This dictionary \^{{\tt SDict}} is the first one on the PostScript dictionary stack when any PostScript graphic is included, whether by literal inclusion or through the \.{\ttbackslash epsffile} macros. \sub{Other Graphics Support} There are other ways to include graphics with \.{dvips}. One is to use an \^{obsolete} existing package, such as \.{emtex}, \.{psfig}, \.{tpic}, or \.{METAPOST}, all supported by \.{dvips}. Other facilities are available for historical reasons, but their use is discouraged, in hope that some `sane' form of PostScript inclusion shall become standard. Note that the main advantage of the \.{\ttbackslash epsffile} macros is that they can be adapted for whatever form of special eventually becomes standard, and thus only minor modifications to that one file need to be made, rather than revising an entire library of \TeX\ documents. Most of these specials use a flexible key and value scheme: \cmd{\ttbackslash special\char123psfile=filename.ps[key=value]*\char125} \noindent This will download the PostScript file called \.{filename.ps} such that the current point will be the origin of the PostScript \^{{\tt psfile}} coordinate system. The optional key/value assignments allow you to specify transformations on the PostScript. The possible keys are:\vskip\baselineskip \centerline{\vbox{\halign{\tt#\hfil\quad&#\hfil\cr hoffset &The horizontal offset (default 0)\cr voffset &The vertical offset (default 0)\cr hsize &The horizontal clipping size (default 612)\cr vsize &The vertical clipping size (default 792)\cr hscale &The horizontal scaling factor (default 100)\cr vscale &The vertical scaling factor (default 100)\cr angle &The rotation (default 0)\cr clip &Enable clipping to the bounding box\cr}}} The dimension parameters are all given in PostScript units. The \.{hscale} and \.{vscale} are given in non-dimensioned percentage units, and the rotation value is specified in degrees. \cmd{\ttbackslash special\char123psfile=foo.ps hoffset=72 hscale=90 vscale=90\char125} \noindent will shift the graphics produced by file \.{foo.ps} right by one inch and will draw it at 0.9 times normal size. Offsets are given relative to the point of the special command, and are unaffected by scaling or rotation. Rotation is counterclockwise about the origin. The order of operations is to rotate the figure, scale it, then offset it. For compatibility with older PostScript drivers, it is possible to change the units that \.{hscale} and \.{vscale} are given in. This can be done by redefining \.{@scaleunit} \^{{\tt scaleunit}} in \.{SDict} \^{{\tt SDict}} by a \TeX\ command such as \cmd{\ttbackslash special\char123! /@scaleunit 1 def\char125} \noindent The \.{@scaleunit} variable, which is by default 100, is what \.{hscale} and \.{vscale} are divided by to yield an absolute scale factor. All of the methods for including graphics we have described so far enclose the graphic in a PostScript save/restore pair, guaranteeing that the figure will have no effect on the rest of the document. Another type of special command allows literal PostScript instructions to be inserted without enclosing them in this protective shield; users of this feature are supposed to understand what they are doing (and they shouldn't change the PostScript graphics state unless they are willing to take the consequences). This command can take many forms, because it has had a tortuous history; any of the following will work: \cmd{\ttbackslash special\char123ps:{\it text}\char125\\ \ttbackslash special\char123ps::{\it text}\char125\\ \ttbackslash special\char123ps::[begin]{\it text}\char125\\ \ttbackslash special\char123ps::[end]{\it text}\char125} \noindent (with longer forms taking precedence over shorter forms, when they are used). Note that {\tt ps::} and {\tt ps::[end]} do not do any positioning, so they can be used to continue PostScript literals started with {\tt ps:} or {\tt ps::[begin]}. There is also the command \cmd{\ttbackslash special\char123ps:\ plotfile filename\char125} \noindent which will copy the commands from \.{filename} verbatim into the output (but omitting lines that begin with \%). An example of the proper use of literal specials can be found in the file \.{rotate.tex} which makes it easy to typeset text turned 90 degrees. To finish off this section, the following examples are presented without explanation: {\vskip0pt\parskip=0pt\begverb{`\$} \def\rotninety{\special{ps:currentpoint currentpoint translate 90 rotate neg exch neg exch translate}}\font\huge=cmbx10 at 14.4truept \setbox0=\hbox to0pt{\huge A\hss}\vskip16truept\centerline{\copy0 \special{ps:gsave}\rotninety\copy0\rotninety\copy0\rotninety \box0\special{ps:grestore}}\vskip16truept$endverb} \smallskip {\def\rotninety{\special{ps:currentpoint currentpoint translate 90 rotate neg exch neg exch translate}}\font\huge=cmbx10 at 14.4truept \setbox0=\hbox to0pt{\huge A\hss}\vskip16truept\centerline{\copy0 \special{ps:gsave}\rotninety\copy0\rotninety\copy0\rotninety \box0\special{ps:grestore}}\vskip16truept} \smallskip {\vskip0pt\parskip=0pt\begverb{`\$} \vbox to 2truein{\special{ps:gsave 0.3 setgray}\hrule height 2in width\hsize\vskip-2in\special{ps:grestore}\font\big=cminch\big \vss\special{ps:gsave 1 setgray}\vbox to 0pt{\vskip2pt \line{\hss\hskip4pt NEAT\hss}\vss}\special{ps:0 setgray}% \hbox{\raise2pt\line{\hss NEAT\hss}\special{ps:grestore}}\vss}$endverb} \smallskip \vbox to 2truein{\special{ps:gsave 0.3 setgray}\hrule height 2in width\hsize\vskip-2in\special{ps:grestore}\font\big=cminch\big \vss\special{ps:gsave 1 setgray}\vbox to 0pt{\vskip2pt \line{\hss\hskip4pt NEAT\hss}\vss}\special{ps:0 setgray}% \hbox{\raise2pt\line{\hss NEAT\hss}\special{ps:grestore}}\vss} Some caveats are in order when using the above forms. Make sure that each \.{gsave} on a page is matched with a \.{grestore} on the same page. Do not use \.{save} or \.{restore}. Use of these macros can interact with the PostScript generated by \.{dvips} if care is not taken; try to understand what the above macros are doing before writing your own. The \.{\ttbackslash rotninety} macro especially has a useful trick that appears again and again. \sub{Dynamic Creation of PostScript Graphics Files} PostScript is an excellent page description language---but it does tend to be rather verbose. Compressing PostScript graphics files can often reduce them by more than a factor of five. For this reason, if the filename parameter to one of the graphics inclusion techniques starts with a backtick ({\tt`}), the filename is instead interpreted as a command to execute that will send the actual file to standard output. Thus, \cmd{\ttbackslash special\char123psfile="`zcat foo.ps.Z"\char125} \noindent will include the uncompressed version of \.{foo.ps}. Since such a command is not accessible to \TeX, if you use this facility with the \.{EPSF} macros, you need to supply the bounding box parameter yourself, as in \cmd{\ttbackslash epsffile[72 72 540 720]\char123 "`zcat screendump.ps.Z"\char125} \noindent to include \.{screendump.ps}. Of course, the commands to be executed can be anything, including using a file conversion utility such as \.{tek2ps} or whatever is appropriate. This extension is not portable to other \.{dvi2ps} programs. Yet. \sec{Using PostScript Fonts} Thanks to Donald~E.~Knuth, \^{Knuth, Donald E.} the \.{dvips} driver now supports PostScript fonts \^{PostScript fonts} through the virtual font capability. PostScript fonts are (or should be) accompanied by a font metric file such as \.{Times-Roman.afm}, which describes characteristics of a font called Times-Roman. \^{{\tt afm}} To use such fonts with \TeX, we need \.{tfm} files that contain similar \^{{\tt tfm}} information. These can be generated from \.{afm} files by running the program \.{afm2tfm}, supplied with \.{dvips}. \^{{\tt afm2tfm}} This program also creates virtual fonts with which you can use normal plain \TeX\ conventions. Note that non-resident downloaded PostScript fonts tend to use a great deal of printer virtual memory. PostScript printers typically have between 130,000 and 400,000 bytes of available virtual memory; each downloaded font will require approximately 30,000 bytes of that. For many applications, bitmapped fonts work much better, even at typesetter resolutions (with the \.{-Z} option.) Even resident PostScript fonts can take a fair amount of memory, but less with this release of \.{dvips} than previously. Also, bitmapped fonts tend to image faster than PostScript fonts. \sub{The afm2tfm Program} The \.{afm2tfm} program can convert an Adobe \.{afm} file into a `raw' \TeX\ \.{tfm} file with the command \cmd{localhost> afm2tfm Times-Roman rptmr} \noindent (You should run this from in a directory where \.{Times-Roman.afm} resides.) The output file \.{rptmr.tfm} is `raw' because it does no character remapping; it simply converts the character information on a one-to-one basis to \TeX\ characters {\it with the same code}. The name \.{rptmr} stands for Resident PostScript Times Roman; section~6 below explains more about a proposed scheme for font names. In the following examples, we will use the font Times-Roman to illustrate the conversion process. For the standard 35 LaserWriter fonts, however, it is highly recommended that you use the supplied \.{tfm} and \.{vf} files that come with \.{dvips} (usually in a file called \.{dvipslib.tar.Z}), as these files contain some additional changes that make them work better with \TeX\ than they otherwise would. PostScript fonts have a different encoding scheme from that of plain \TeX. Although both schemes are based on ASCII, special characters such as ligatures and accents are handled quite differently. Therefore we obtain \^{ligature} \^{accents} \^{virtual fonts} best results by using a `virtual font' interface, which makes \TeX\ act as if the PostScript font had a standard \TeX\ encoding. Such a virtual font can be obtained, for example, by the command \cmd{localhost> afm2tfm Times-Roman -v ptmr rptmr} \noindent This produces two outputs, namely the `virtual property list' file \.{ptmr.vpl}, and the \TeX\ font metric file \.{rptmr.tfm}. The latter file describes an `actual font' on which the virtual font is based. To use the font in \TeX, you should first run \cmd{localhost> vptovf ptmr.vpl ptmr.vf ptmr.tfm} \noindent and then install the virtual font file \.{ptmr.vf} in the virtual font directory (by default, \.{/usr/lib/tex/fonts/vf}) and install \.{ptmr.tfm} and \.{rptmr.tfm} in the directory for \TeX\ font metrics (by default, \.{/usr/lib/tex/fonts/tfm}). (This probably has already been done for you for the most common PostScript fonts.) You can also make more complex virtual fonts by editing \.{ptmr.vpl} before running \.{vptovf}; such editing might add the uppercase Greek characters in the standard \TeX\ positions, for instance. Once this has been done, you're all set. You can use code like this in \TeX\ henceforth: \cmd{\ttbackslash font\ttbackslash myfont=ptmr at 10pt\\ \ttbackslash myfont Hello, I am being typeset in Times-Roman.} Note that there are two fonts, one actual (`rptmr', which is analogous to a raw piece of hardware) and one virtual (`ptmr', which has typesetting know-how added). You could also say \cmd{\ttbackslash font\ttbackslash TR=rptmr at 10pt} \noindent and typeset directly with that, but then you would have no ligatures \^{ligature} or kerning, and you would have to use Adobe \^{kerning} character positions for special letters like \AE. The virtual font called \.{ptmr} not only has ligatures and kerning, and most of the standard accent conventions of \TeX, it also has a few additional features not present in the Computer Modern fonts. For example, it includes all the Adobe characters (such as the Polish ogonek and the French guillemots). The only things you lose from ordinary \TeX\ text fonts are the dotless j (which can be hacked into the VPL file with literal PostScript specials if you have the patience) and uppercase Greek letters (which just don't exist unless you buy them separately). Experts may refer to Donald E.~Knuth article in {\it TUGboat} v. 11, no. 1, Apr. 1990, pp. 13--23. ``Virtual Fonts: More Fun for Grand Wizards.'' When \.{dvips} goes to use a font, it first checks to see if it is one of the fonts listed in a file called \.{psfonts.map}. If it is mentioned in \^{{\tt psfonts.map}} that file, then it is assumed that the font is a resident PostScript font and can be found with the PostScript \.{findfont} operator. This file resides by default in {\tt /usr/lib/tex/ps}, and consists of a single font per line. Note that only the raw PostScript font names should be listed in this file; the \.{vf} fonts should not be, since they are automatically mapped to the raw PostScript fonts by the virtual font machinery. The supplied \.{psfonts.map} file defines the most common PostScript fonts. As much as possible, the PostScript fonts follow plain \TeX\ conventions for accents. The two exceptions to this are the Hungarian umlaut (which is at position {\tt 0x7D} in {\tt cmr10}, but position {\tt 0xCD} in {\tt ptmr}) and the dot accent (at positions {\tt 0x5F} and {\tt 0xC7}, respectively). In order to use these accents with PostScript fonts or in math mode when {\tt \char92 textfont0} is a PostScript font, you will need to use the following definitions. Note that these definitions will not work with normal \TeX\ fonts for the relevant accents; note also that these definitions are already part of the distributed \.{psfonts.sty}. In addition, the \.{\char92 AA} that is used to typeset the \AA\ character must be modified as shown. {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$} \def\H#1{{\accent"CD #1}}\def\.#1{{\accent"C7 #1}} \def\dot{\mathaccent"70C7 } \newdimen\aadimen \def\AA{\leavevmode\setbox0\hbox{h}\aadimen\ht0 \advance\aadimen-1ex\setbox0\hbox{A}\rlap{\raise.67\aadimen \hbox to \wd0{\hss\char'27\hss}}A}$endverb} These PostScript fonts can be scaled to any size. Go wild! Note, however, that using PostScript fonts does use up a great deal of the printer's virtual memory and it does take time. \^{memory} You may find downloading the Computer Modern bitmapped fonts to be faster than using the built-in PostScript fonts. \sub{Changing a Font's Encoding} The \.{afm2tfm} program also allows you to specify a different encoding for a PostScript font. This should only be done by wizards. This can be done at two levels. You can specify a different output encoding with \.{-o}. This only applies when you are building a virtual font, and it tells \.{afm2tfm} to attempt to remap the font to match the output encoding as closely as possible. In such an output encoding, you can also specify ligature pairs and kerning information that will be used in addition to the information in the \.{afm} file. This will be the most common re-encoding required, since the only thing that changes is the \.{vf} file (and its associated \.{tfm} file) and since most everything you would want to do can be done with this method. You can also specify a different PostScript encoding with \.{-p}. This option affects the generation of both the raw \.{tfm} file and the virtual \.{vf} and \.{tfm} files, and it also requires that the encoding file be available to be downloaded as part of every PostScript document produced that uses this font. But this is the only way to access characters in a PostScript font that are neither encoded in the \.{afm} file nor built from other characters (constructed characters.) For instance, \.{Times-Roman} contains the extra characters \.{registered} and \.{thorn} (among others) that can only be accessed through such a PostScript reencoding. Any ligature or kern information specified in the PostScript encoding is ignored by \.{afm2tfm}. The format of the encoding files is simple---it is precisely the same format that is used to define an encoding vector in PostScript! For this reason, the same file can be used as a PostScript or \TeX\ encoding file for \.{afm2tfm} as well as downloaded to the printer as part of a document that uses a reencoded font. The specific format that \.{afm2tfm} accepts is one of the following form: {\vskip0pt\parskip=0pt\begverb{`\\} % comments are mostly ignored; more on this later /MyEncoding [ /Alpha /Beta /Gamma /Delta ... /A /B ... /Z % exactly 256 entries, each with a / at the front /wfooaccent /xfooaccent /yfooaccent /zfooaccent ] def \endverb} Comments, which start with a percent sign and continue until the end of the current line, are mostly ignored. The first `word' of the file must start with a forward slash (a PostScript literal name) and is used as the name of the encoding. The next word must be an open bracket. Following that must be precisely 256 character names; use {\tt /.notdef} for any that you do not want to define. Finally, there must be a close bracket. The final token is usually {\tt def}, but this is not enforced. Note that all names are case sensitive. Any ligature or kern information is given in the comments. As each comment is encountered, it is examined. If the first word after the percent sign is {\tt LIGKERN}, exactly, then the entire rest of the line is parsed for ligature and kern information. This ligature and kern information is given in groups of words, each group of which must be terminated by a semicolon (with a space before and after it, unless it occurs on the end of a line.) In these {\tt LIGKERN} statements, three types of information may be specified. These three types are ligature pairs, kerns to remove or ignore, and the character value of this font's boundary character. Which of the types the particular set of words corresponds to is automatically determined by the allowable syntax. Throughout the {\tt LIGKERN} section, the boundary character is specified as {\tt ||}. To set the boundary character value, a command such as {\tt || = 39 ;} must be used. To indicate a kern to remove, give the names of the two characters (without the leading slash) separated by {\tt \char123\char125}, as in {\tt one \char123\char125\ one ;}. This is similar to the way you might use {\tt \char123\char125} in a \TeX\ file to turn off ligatures or kerns at a particular location. Either or both of the character names can be given as {\tt *}, which is a wild card matching any character; thus, all kerns can be removed with {\tt * \char123\char125\ * ;}. To specify a ligature, specify the names of the pair of characters, followed by the ligature `operation' (as in \MF), followed by the replacing character name. Either (but not both) of the first two characters can be {\tt ||} to indicate a word boundary. Normally the `operation' is {\tt =:} meaning that both characters are removed and replaced by the third character, but by adding {\tt |} characters on either side of the {\tt =:}, you can specify which of the two leading characters to retain. In addition, by suffixing the ligature operation with one or two {\tt >} signs, you can indicate that the ligature scanning operation should skip that many characters before proceeding. This works just like in \MF. A typical ligature might be specified with {\tt ff i =:{} ffi ;}. A more convoluted ligature is {\tt one one |=:|>> exclam ;} which indicates that every pair of adjacent {\tt 1}'s should be separated by an exclamation point, and then two of the resulting characters should be skipped over before continuing searching for ligatures and kerns. You cannot give more {\tt >}'s in an ligature operation as you did {\tt |}, so there are a total of eight possible ligature operations: \cmd{=: |=: |=:> =:| =:|> |=:| |=:|> |=:|>>} \noindent The default set of ligatures and kerns built in to \.{afm2tfm} can be specified with: {\vskip0pt\parskip=0pt\begverb{`\\} % LIGKERN space l =: lslash ; space L =: Lslash ; % LIGKERN question quoteleft =: questiondown ; % LIGKERN exclam quoteleft =: exclamdown ; % LIGKERN hyphen hyphen =: endash ; endash hyphen =: emdash ; % LIGKERN quoteleft quoteleft =: quotedblleft ; % LIGKERN quoteright quoteright =: quotedblright ; % LIGKERN space {} * ; * {} space ; zero {} * ; * {} zero ; % LIGKERN one {} * ; * {} one ; two {} * ; * {} two ; % LIGKERN three {} * ; * {} three ; four {} * ; * {} four ; % LIGKERN five {} * ; * {} five ; six {} * ; * {} six ; % LIGKERN seven {} * ; * {} seven ; eight {} * ; * {} eight ; % LIGKERN nine {} * ; * {} nine ; \endverb} \sub{Special Effects} Special effects are also obtainable, with commands such as \cmd{localhost> afm2tfm Times-Roman -s .167 -v ptmro rptmro} \noindent which create \.{ptmro.vpl} and \.{rptmro.tfm}. To use this, proceed as above but put the line \cmd{rptmro Times-Roman ".167 SlantFont"} \noindent into \.{psfonts.map}. Then \.{rptmro} (our name for an obliqued Times) will act as if it were a \^{{\tt psfonts.map}} resident font, although it is actually constructed from Times-Roman by PostScript hackery. (This oblique version of Times-Roman is obtained by slanting everything 1/6 to the right.) Similarly, you can get an expanded font by \cmd{localhost> afm2tfm Times-Roman -e 1.2 -v ptmrre rptmrre} \noindent and by recording the pseudo-resident font \cmd{rptmrre Times-Roman "1.2 ExtendFont"} \noindent in \.{psfonts.map}. You can also create a small caps font with a command such as \cmd{localhost> afm2tfm Times-Roman -V ptmrc rptmr} \noindent This is done strictly with a virtual font, however. In addition, the font on which the small caps font is based (in this case {\tt rptmr} may already be created and installed, in which case no additional {\tt psfonts.map} entry is needed. In any case, you must give the appropriate name of the font that is not small caps as the base name (last parameter) to {\tt afm2tfm}. For instance, if you create a slanted small caps font, you must give the base name of the raw slanted font as that last parameter, not the base name of the unslanted font. By default, the {\tt -V} option uses a font scaled to 80\% for lower case. If you specify the {\tt -c} option, you can change this scaling. If you change the PostScript encoding of a font, you must specify the input file as a header file, as well as give a reencoding command. For instance, let us say we are using Times-Roman reencoded according to the encoding {\tt MyEncoding} (stored in the file {\tt myenc.enc}) as {\tt rptmrx}. In this case, our {\tt psfonts.map} entry would look like \cmd{rptmrx Times-Roman "MyEncoding ReEncodeFont" .date h .date$endverb} \noindent(with no newline following \.{setfont}); then the command-line option \.{-Pdated} to \.{dvips} will print current date and time on the top of each page of output. Note that multiple \.{-P} options can be used. \ifgeneric\else \sec{MS-DOS} The MS-DOS version of \.{dvips} differs from UNIX in the following ways. \^{MS-DOS} \item{$\bullet$} Path separators are \.{;} not \.{:}. \item{$\bullet$} Directory separators are \.{\ttbackslash} not \.{/}. \item{$\bullet$} The user's initialization file is \.{dvips.ini} not \.{.dvipsrc}. \item{$\bullet$} Pipes to printers are not supported. Output must go to a file. \item{$\bullet$} \.{MakeTeXPk} is a batch file. Since MS-DOS has insufficient memory to run both \.{dvips} and \MF\ at the same time, this batch file will typically write out a set of commands for running \MF\ later. The \.{maketexp.bat} supplied writes out an \.{mfjob} file for em\TeX. \item{$\bullet$} \.{dvidrv} from em\TeX\ can be used to automatically make fonts as follows: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$} dvidrv dvips file.dvi $endverb} \.{dvidrv} sets an option \.{-pj=mfjobfile} for \.{dvips}, where \.{mfjobfile} is the name of a temporary \.{mfjob} file. If there are missing fonts, \.{dvips} will write this \.{mfjob} file and then ask: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$} Exit to make missing fonts now (y/n)? $endverb} If you answer yes, \.{dvips} exits with errorlevel 8 which tells \.{dvidrv} to call \.{mfjob} to make the fonts, and then to call \.{dvips} again. For this to work, \.{dvidrv}, \.{dvips}, \.{mfjob} and \.{mf} must be located in the \.{PATH}, and the environment variables for \.{mfjob} and \.{mf} set correctly. A font mode must be set with the '\.{M}' option in \.{config.ps}. If the \.{-pj} option is set, dvips will not call \.{MakeTeXPk.bat}. \item{$\bullet$} Limited em\TeX\ specials. The following ones are supported: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$} \special{em:message xxx} \special{em:point n} \special{em:line a[h|v|p],b[h|v|p] [,width]} \special{em:linewidth width} \special{em:moveto} \special{em:lineto} \special{em:graph xxx[,width[,height]]} $endverb} \item{} The line cut parameters \.{[h|v|p]} of the \.{\ttbackslash special{\char123}em:line ...{\char125}} command are ignored. Lines are ended with a rounded cap. A maximum of 1613 different point numbers are permitted on each page. The \.{\ttbackslash special{\char123}em:graph xxx{\char125}} supports \.{PCX}, \.{MSP1}, \.{MSP2} and \.{BMP} files. The graph file may be scaled by giving an optional width and height (expressed in the same way as \TeX\ dimensions). An example: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$} \special{em:graph scrdump.pcx,100mm,75mm} $endverb} The program \.{dvips} can use em\TeX\ font libraries created with the em\TeX\ \.{fontlib /2} option. If a \.{pxl} font is found within a font library, \.{dvips} will complain, and then ignore the \.{pxl} font. The font library names and directory names can be specified with this configuration file option. {\options \def\o#1 #2:{{\tt #1} {\it #2}:} \def\O#1:{{\tt #1}:} \o L path: The list of \.{fli} font libraries to search for bitmap \.{pk} font files is {\it path}. \^{{\tt fli}} Fonts are sought first in these libraries and then as single files. Font libraries can be created with em\TeX 's \.{fontlib}; the usual extension is \.{fli}. Directories as well as file names can be entered here, the files will be searched for in all these directories. A directory name must have trailing directory separator (\.{/} for UNIX, \.{\ttbackslash} for MS-DOS). \par } \sec{OS/2} The OS/2 version of \.{dvips} differs from UNIX in the following ways. \^{OS/2} \item{$\bullet$} Path separators are \.{;} not \.{:}. \item{$\bullet$} Directory separators are \.{\ttbackslash} not \.{/}. \item{$\bullet$} The user's initialization file is \.{dvips.ini} not \.{.dvipsrc}. \item{$\bullet$} Printer configuration files are called \.{.cfg}, not \.{config.}. \item{$\bullet$} The environment variable defining the search patch to tfm files is called \.{TEXTFM}, not \.{TEXFONTS}. \item{$\bullet$} \.{MakeTeXPk} is a \.{.cmd} file called \.{MakeTeXP.cmd}. It writes out an \.{mfjob} file for em\TeX\ and calles \.{mfjob}. \item{$\bullet$} \.{dvidrv} from em\TeX\ can be used to automatically make fonts as follows: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$} dvidrv dvips file.dvi $endverb} \.{dvidrv} sets an option \.{-pj=mfjobfile} for \.{dvips}, where \.{mfjobfile} is the name of a temporary \.{mfjob} file. If there are missing fonts, \.{dvips} will write this \.{mfjob} file and then ask: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$} Exit to make missing fonts now (y/n)? $endverb} If you answer yes, \.{dvips} exits with errorlevel 8 which tells \.{dvidrv} to call \.{mfjob} to make the fonts, and then to call \.{dvips} again. For this to work, \.{dvidrv}, \.{dvips}, \.{mfjob} and \.{mf} must be located in the \.{PATH}, and the environment variables for \.{mfjob} and \.{mf} set correctly. A font mode must be set with the '\.{M}' option in \.{config.ps}. If the \.{-pj} option is set, dvips will not call \.{MakeTeXPk.bat}. \item{$\bullet$} Limited em\TeX\ specials. The following ones are supported: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$} \special{em:message xxx} \special{em:point n} \special{em:line a[h|v|p],b[h|v|p] [,width]} \special{em:linewidth width} \special{em:moveto} \special{em:lineto} \special{em:graph xxx[,width[,height]]} $endverb} \item{} The line cut parameters \.{[h|v|p]} of the \.{\ttbackslash special{\char123}em:line ...{\char125}} command are ignored. Lines are ended with a rounded cap. A maximum of 1613 different point numbers are permitted on each page. The \.{\ttbackslash special{\char123}em:graph xxx{\char125}} supports \.{PCX}, \.{MSP1}, \.{MSP2} and \.{BMP} files. The graph file may be scaled by giving an optional width and height (expressed in the same way as \TeX\ dimensions). An example: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{`\$} \special{em:graph scrdump.pcx,100mm,75mm} $endverb} The program \.{dvips} can use em\TeX\ font libraries created with the em\TeX\ \.{fontlib /2} option. If a \.{pxl} font is found within a font library, \.{dvips} will complain, and then ignore the \.{pxl} font. The font library names and directory names can be specified with this configuration file option. {\options \def\o#1 #2:{{\tt #1} {\it #2}:} \def\O#1:{{\tt #1}:} \o L path: The list of \.{fli} font libraries to search for bitmap \.{pk} font files is {\it path}. \^{{\tt fli}} Fonts are sought first in these libraries and then as single files. Font libraries can be created with em\TeX 's \.{fontlib}; the usual extension is \.{fli}. Directories as well as file names can be entered here, the files will be searched for in all these directories. A directory name must have trailing directory separator (\.{/} for UNIX, \.{\ttbackslash} for OS/2). \par } \sec{Installation} If \.{dvips} has not already been installed on your system, the \^{installation} following steps are all that are needed. First update the \.{Makefile}---in particular, the paths. Everything concerning \.{dvips} can be adjusted in the \.{Makefile}. Make sure you set key parameters such as the default resolution, and make sure that the path given for packed pixel files is correct. Next, check the file name definitions in \.{MakeTeXPK}. If you don't \^{{\tt MakeTeXPK}} have \MF\ installed, you cannot use \.{MakeTeXPK} to automatically generate the fonts; you can, however, modify it to generate \.{pk} fonts from \.{gf} fonts if you don't have a full set of \.{pk} fonts but do have a set of \.{gf} fonts. If you don't have that, you should probably not install \.{MakeTeXPK} at all; this will disable automatic font generation. Now, check the configuration parameters in \.{config.ps}. You should also update the default resolution here. This file is the system-wide configuration file that will be automatically installed. If you are unsure how much memory your PostScript printer has, print the following file: \cmd{\%! Hey, we're PostScript\\ /Times-Roman findfont 30 scalefont setfont 144 432 moveto\\ vmstatus exch sub 40 string cvs show pop showpage} \noindent Note that the number returned by this file is the total memory free; it is often a good idea to tell \.{dvips} that the printer has somewhat less memory. This is because many programs download permanent macros that can reduce the memory in the printer. In general, a memory size of about \.{300000} is plenty, since \.{dvips} can automatically split a document if required. It is unfortunate that PostScript printers with much less virtual memory still exist. Some systems or printers can dynamically increase the memory available to a PostScript interpreter; for these systems, a value of one million works well. Next, run \.{make}. Everything should compile smoothly. You may need to adjust the compiler options in the \.{Makefile} if something goes amiss. Once everything is compiled, run \.{make} \.{install}. After this is done, you may want to create a configuration file for each PostScript printer at your site. If the font caching is considered a security hole, make the `cache' directory be something like \.{/tmp/pks}, and \.{cron} a job to move the good \.{pk} files into the real directory. Or simply disable this feature by not installing \.{MakeTeXPK}. Don't forget to install the new \.{vf} files and \.{tfm} files. Note that the \.{tfm} files distributed with earlier (pre-5.471) versions of \.{dvips}, and all versions of other PostScript drivers, are different. A test program called \.{test.tex} is provided, so you can easily check that the most important parts of \.{dvips} have been installed properly. \sec{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. This is all too common, and is usually caused by some broken PostScript application out there. The following sections provide some helpful hints if you find yourself in such a situation. In all cases, you should attempt to find the smallest file that causes the problem. This will not only make debugging easier, it will also reduce the number of possible interactions among different parts of the system. \sub{Debug Options} The \.{-d} flag to \.{dvips} is very useful for helping to track 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. The classes are: $$\vbox{\halign{\hfil #\quad&#\hfil\cr 1&specials\cr2&paths\cr4&fonts\cr8&pages\cr16&headers\cr 32&font compression\cr64&files\cr 128&memory\cr}}$$ \sub{No Output At All} If you are not getting any output at all, even from the simplest one-character file (for instance, \.{\char92~\char92 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. I've tried to work around as many bugs as possible in common non-Adobe PostScript interpreters, but I'm sure I've missed a few. If \.{dvips} gives any strange error messages, or compilation on your machine generated a lot of warnings, perhaps the \.{dvips} program itself is broken. Carefully check the types in \.{dvips.h} and the declarations in the \.{Makefile}, and try using the debug options to determine where the error occurred. 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. \sub{Output Too Small or Inverted} If some documents come out inverted or too small, your spooler is not supplying an end of job indicator at the end of each file. (This happens a lot on small machines that don't have spoolers.) You can force \.{dvips} to do this with the \.{-F} flag, but note that this generates files with a binary character (control-D) in them. You can also try using the \.{-s} flag to enclose the entire job in a save/restore pair. \sub{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 make sure you get your spooling software updated. You might also try turning off comments on included files with the \.{-K} option; many spoolers cannot deal with nested documents. Another error message is \.{VM exhausted}. (Some printers indicate this error by locking up; others quietly reset.) This is caused by telling \.{dvips} that the printer has more memory than it actually does, and then printing a complicated document. To fix this, try lowering the parameter to \.{m} in the configuration file; use the debug option to make sure you adjust the correct file. Other errors may indicate that the graphics you are trying to include don't nest properly in other PostScript documents, or any of a number of other possibilities. Try the output on a QMS PS-810 or other Adobe PostScript printer; it might be a problem with the printer itself. \sub{400 DPI Is Used Instead Of 300 DPI} This common error is caused by not editing the \.{config.ps} file to reflect the correct resolution for your site. You can use the debug flags (\.{-d64}) to see what files are actually being read. \sub{Long Documents Fail To Print} This is usually caused by incorrectly specifying the amount of memory the printer has in \.{config.ps}; see the description above. \sub{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 hex) will probably fail with \.{dvips}. \sub{Can't Find Font Files} If \.{dvips} complains that it cannot find certain font files, it is possible that the paths haven't been set up correctly for your system. Use the debug flags to determine precisely what fonts are being looked for and make sure these match where the fonts are located on your system. \sub{Can't Generate Fonts} This happens a lot if either \.{MakeTeXPK} hasn't been properly edited and installed, or if the local installation of \MF\ isn't correct. If \.{MakeTeXPK} isn't properly edited or isn't installed, an error such as \.{MakeTeXPK not found} will be printed on the console. The fix is to talk to the person who installed \.{dvips} and have them fix this. If \MF\ isn't found when \.{MakeTeXPK} is running, make sure it is installed on your system. The person who installed \TeX\ should be able to install \MF\ easily. If \MF\ 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 \MF\ base file probably hasn't been made properly. To make a proper \.{plain.base}, assuming the local mode definitions are contained in \.{local.mf} (on the NeXT, \.{next.mf}; on the Amiga, \.{amiga.mf}), type the following command (assuming \.{csh} under UNIX): \cmd{localhost> inimf "plain; input local; dump"} \noindent Now, copy the \.{plain.base} file from the current directory to where the base files are stored on your system. Note that a preloaded \.{cmbase.base} should never be used when creating fonts, and a program such as \.{cmmf} should never exist on the system. The macros defined in \.{cmbase} will break fonts that do not use \.{cmbase}; such fonts include the La\TeX\ fonts. Loading the \.{cmbase} macros when they are needed is done automatically and takes less than a second---an insignificant fraction of the total run time of \MF\ for a font, especially when the possibility of generating incorrect fonts is taken into account. If you create the La\TeX\ font {\tt circle10}, for instance, with the \.{cmbase} macros loaded, the characters will have incorrect widths. \sec{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, {\tt 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 La\TeX\ 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. \sub{The 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 \cmd{\ttbackslash input colordvi} \noindent or, if your document uses style files like La\TeX, add the \.{colordvi} style option as in \cmd{\ttbackslash documentstyle[12pt,colordvi]\char123article\char125} 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 \cmd{\ttbackslash ColorName\char123this will print in color\char125} \noindent 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: \cmd{This text is green but here we are \ttbackslash Red\char123switching to red, \\ \ttbackslash Blue\char123nesting blue\char125, recovering the red\char125\ and back to \\ original green.} \noindent In principle there is no limit to the nesting level, but it is not advisable to nest too deep lest you lose track of the color history. The global color command has the form \cmd{\ttbackslash textColorName} \noindent 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 \cmd{\ttbackslash textGreen \\ This text is green but here we are \ttbackslash Red\char123switching to red, \\ \ttbackslash Blue\char123nesting blue\char125, recovering the red\char125\ and back to \\ original green.\\ \ttbackslash textCyan \\ The text from here on will be cyan unless \\ \ttbackslash Yellow\char123locally changed to yellow\char125. 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 \.{\ttbackslash 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 then stretch too far. At the present time there are no macros for color environments in La\TeX\ which might have a larger range. This is primarily to keep the \TeX\ and La\TeX\ use compatible. \sub{User Definable Colors} There are two ways for the user to specify colors not already defined. For local changes, there is the command \.{\ttbackslash 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 \cmd{\ttbackslash Color\char123{.5 .85 .4 .2}\char125\char123 this color is pretty\char125} For global color changes, there is a command \.{\ttbackslash 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 \cmd{\ttbackslash textColor\char123{.5 .85 .4 .2}\char125 \\ The text from now on will be this pretty color} \noindent 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. \sub{Subtleties in Using Color} These color macros are defined by use of specialized \.{\ttbackslash 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 \cmd{\ttbackslash headline\char123\ttbackslash Black\char123 My Header\char125\char125 \\ \ttbackslash footline\char123\ttbackslash Black\char123 \ttbackslash hss\ttbackslash tenrm\ttbackslash folio\ttbackslash hss\char125\char125} This warning also applies to figures and other insertions, so be careful! Of course, in La\TeX, 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 La\TeX\ 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 insure that \TeX\ is in horizontal mode before the first special command is issued; this can be done by prefixing the color command with {\tt\char92 leavevmode}. \sub{Printing in Black/White, after Colorizing} If you have a \TeX\ or La\TeX\ 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. \sub{Configuring dvips for Color Devices} 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 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 \.{\char123\ 0 0.10 0.75 0.03 \char125}. Then create a header file named \.{mycolordev.pro} with the commands \cmd{userdict begin \\ /Goldenrod \char123\ 0 0.10 0.75 0.03 setcmykcolor\char125\ bind def} \noindent Finally, in \.{config.mycolordev} add the line \cmd{h mycolordev.pro} \noindent 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. \sub{Protecting Regions From Spurious Colors} Because color is defined via \TeX's {\tt\ttbackslash special} command, it cannot be sensitive to the output routine or certain regions of the page like the header and footer. Consequently, these regions need to be protected from spurious color changes (particularly when local colors spread across page breaks). Users need to be aware of the possibility of certain regions getting unwanted or unpredicted colors. Headers and footers are most worrisome so style designers who want to use color should keep this in mind. One particular region of text that gets spurious color effects is labels in list environments. For instance, because of the way list items are defined in standard La\TeX, the bullet for items that start with a different color also gets drawn in that color. To give the user a simple mechanism to solve this problem (and other unforeseen effects of this type) one other special macro is automatically defined. This macro is called {\tt\ttbackslash globalColor}. It is actually a {\it local\/} color macro and so takes a single argument. But the color effect it produces is always the same as that set by the {\it last\/} {\tt\ttbackslash textColor} or {\tt\ttbackslash textColorName} command. In effect, when a {\tt\ttbackslash textColorName} command is called, {\tt\ttbackslash globalColor} gets a new definition equivalent to the local {\tt\ttbackslash ColorName} macro. For example, when the default is black, {\tt\ttbackslash globalColor=\ttbackslash Black} and when {\tt\ttbackslash textGreen} appears, {\tt\ttbackslash globalColor=\ttbackslash Green}. This special macro can then be used to protect sensitive regions of the text. For example, in La\TeX\ files, one might make sure that the header and footers have {\tt\ttbackslash globalColor} wrapping their contents. In this way, they will inherit the current active root (unnested) color state. \sub{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 {\tt background} special and the {\tt color} special. The {\tt color} special itself has three forms. The first is just {\tt 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 {\tt 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 {\tt color} special is just {\tt 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 {\tt 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 {\tt 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.