letter 8.5in 11in\\ @+ \%\%BeginPaperSize: Letter\\ @+ letter\\ @+ \%\%EndPaperSize\\ legal 8.5in 14in\\ @+ ! \%\%DocumentPaperSizes: Legal\\ @+ \%\%BeginPaperSize: Legal\\ @+ legal\\ @+ \%\%EndPaperSize \noindent Note that you can even include structured comments in the configuration file! When \.{dvips has a paper format name given on the command line, it looks for a match by the {\it name; when it has a \.{papersize special, it looks for a match by dimensions. The first match found (in the order the paper size information is found in the configuration file) is used. If nothing matches, a warning is printed and the first paper size given is used, so the first paper size should always be the default. The dimensions must match within a quarter of an inch. Landscape mode for all of the paper sizes are automatically supported. If your printer has a command to set a special paper size, then give dimensions of \.{0in 0in; the PostScript code that sets the paper size can refer to the dimensions the user requested as \.{\ttbackslash hsize and \.{\ttbackslash vsize; these will be macros defined in the PostScript that return the requested size in default PostScript units. Note that virtually all of the PostScript commands you use here are device dependent and degrade the portability of the file; that is why the default first paper size entry should not send any PostScript commands down (although a structured comment or two would be okay). Also, some printers want {\tt BeginPaperSize comments and paper size setting commands; others (such as the NeXT) want {\tt PaperSize comments and they will handle setting the paper size. There is no solution I could find that works for both (except maybe specifying both). See the supplied {\tt config.ps file for a more realistic example.
\O a: Conserve memory by making three passes over the \.{dvi file instead of two and only loading those characters actually used. Generally only useful on machines with a very limited amount of memory, like some PCs.
\o b num: Generate {\it num copies of each page, but duplicating the page body rather than using PostScript’s {\tt\#copies. This can be useful in conjunction with a header file setting {\tt\char92bop-hook to do color separations or other neat tricks.
\o e num: Set the maximum drift parameter to {\it num dots (pixels) as explained above. \^{maxdrift
\O f: Run as a filter by default. \^{filter
\o h name: Add {\it name as a PostScript header file to be downloaded at the beginning. \^{header
\o i num: Make each section be a separate file, and set the maximum number of pages in a given file to {\it num. Under certain circumstances, \.{dvips will split the document into ‘sections’ to be processed independently; this is most often done for memory reasons. Using this option tells \.{dvips to place each section into a separate file; the new file names are created by replacing the suffix of the supplied output file name with a three-digit sequence number. This is essentially a combination of the command line options \.{-i and \.{-S; see the documentation for these options for more information.
\o m num: The value {\it num is the virtual memory available for fonts and strings in the printer. \^{memory Default is 180000. This value must be accurate if memory conservation and document splitting is to work correctly. To determine this value, send the following file to the printer: {\parindent=40pt\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, in which case this file might return a ridiculously low number; the NeXT computer is such a machine. For these systems, a value of one million works well.
\o o name: \^{output The default output file is set to {\it name. As above, it can be a pipe. Useful in printer-specific configuration files to redirect the output to a particular printer queue.
\o p name: The file to examine for PostScript font aliases is {\it name. It defaults to {\tt psfonts.map. This option allows different printers to use different resident fonts. If the name starts with a ‘{\tt +’ character, then the rest of the name (after any leading spaces) is used as an additional map file; thus, it is possible to have local map files pointed to by local configuration files that append to the global map file.
\O q: Run in quiet mode by default. \^{quiet
\O r: Reverse the order of pages by default. \^{reverse
\O s: Enclose the entire document in a global save/restore pair by default. Not recommended, but useful in some environments; this breaks the conformance of the document to the Adobe PostScript structuring conventions.
\o D num: Set the vertical and horizontal resolution to {\it num \^{resolution dots per inch. Useful in printer-specific configuration files.
\o E command: Execute the system command listed, for example as a UNIX shell command. Execution takes place immediately, while the configuration file is being read. This option can be used to insert the current date into a header file, for instance, as explained at the end of section~13. Possibly dangerous; in many installations it may be disabled, in which case a warning message will be printed if the option is used.
\o H path: The (colon-separated) path to search for PostScript header \^{header files is {\it path.
\O I: Ignore the {\tt PRINTER environment variable.
\O K: Filter comments out of included PostScript files; see the description above for more information.
\o M mode: Set {\it mode as the \MF\ mode to be used when generating fonts. This is \^{{\tt MakeTeXPK \^{{\MF passed along to \.{MakeTeXPK and overrides mode derivation from the base resolution.
\O N: Disable PostScript comments by default.
\o O offset: Move the origin by a certain amount. The {\it offset is a comma-separated pair of dimensions, such as \.{.1in,-.3cm (in the same syntax as used in the \.{papersize special). The origin of the page is shifted from the default position (of one inch down, one inch to the right from the upper left corner of the paper) by this amount. This is useful for a printer that consistently offsets output pages by a certain amount. You can use the file {\tt testpage.tex to determine the correct value for your printer. Be sure to do several runs with the same {\tt O value—some printers vary widely from run to run.
\o P path: The (colon-separated) path to search for bitmap \.{pk font files is {\it path. The \.{TEXPKS environment variable will override this. \^{{\tt TEXPKS \^{{\tt pk If a \.{\% character is found in {\it path, the following substitutions will be made, and then a search will be made for the resulting filenames. A \.{\%f is replaced by the font name. A \.{\%b is replaced by the output device horizontal resolution dots per inch. A \.{\%d is replaced by the font size in dots per inch. A \.{\%p is replaced by the font family; this is always \.{pk. A \.{\%m is replaced by the font mode; this is the mode given in the \.{M option. Note that, for each path element, if it contains a percent sign, you must give the full file name, including path, rather than just the directory name; a path element such as {\tt /fonts/\%b will try to open {\tt /fonts/300 when looking for {\tt cmr10.329pk, for instance, and this may not be what is intended; {\tt /fonts/\%b/\%f.\%dpk is needed. If a path element does not contain a percent sign, there is no need to specify the entire file name (because you can’t, unless you list all possible specific font names!).
\o R num num $\ldots\,$: Sets up a list of default resolutions to search for \.{pk fonts, if the \^{{\tt pk requested size is not available. The output will then scale the font found using PostScript scaling to the requested size. Note that the resultant output will be ugly, and thus a warning is issued. To turn this off, use a line with just the \.{R and no numbers.
\o S path: The path to search for special illustrations (Encapsulated PostScript files or psfiles) is {\it path. \^{{\tt TEXINPUTS The \.{TEXINPUTS environment variable will override this.
\o T path: The path to search for the \.{tfm files is {\it path. The \.{TEXFONTS environment variable will override this. \^{{\tt TEXFONTS This path is used for resident fonts and fonts that can’t otherwise be found. It’s usually best to make it identical to the path used by \TeX.
\O U: Turns off a memory-saving optimization; this is necessary for the Xerox 4045 printer, but not recommended otherwise. See the description above for more information.
\o V path: The path to search for virtual font \.{vf files is \^{{\tt vf \^{virtual fonts {\it path. This may be device-dependent if you use virtual fonts to simulate actual fonts on different devices.
\o W string: Sends {\it string to stderr, if a parameter is given; otherwise it cancels another previous message. This is useful in the default configuration file if you want to require the user to specify a printer, for instance, or if you want to notify the user that the resultant output has special characteristics.
\o X num: \^{resolution Set the horizontal resolution to {\it num dots per inch.
\o Y num: \^{resolution Set the vertical resolution to {\it num dots per inch.
\O Z: Compress all downloaded fonts by default, as above.\par
\sec{Automatic Font Generation
One major problem with \TeX\ and the Computer Modern fonts is the huge amount of disk space a full set of high resolution fonts can take. The \.{dvips program solves this problem by creating fonts on demand, so only those fonts that are actually used are stored on disk. At a typical site, less than one-fifth of the full set of Computer Modern fonts are used over a long period, so this saves a great deal of disk space.
Furthermore, the addition of dynamic font generation allows fonts to be used at any size, including typesetter resolutions and extremely huge banner sizes. Nothing special needs to be done; the fonts will be automatically created and installed as needed.
The downside is that it does take a certain amount of time to create a new font if it has never been used before. But once a font is created, it will exist on disk, and the next time that document is printed it will print very quickly.
It is the \.{MakeTeXPK shell script that is responsible for making these \^{{\tt MakeTeXPK fonts. The \.{MakeTeXPK script supplied invokes \MF\ to create the font and then copies the resultant \.{pk file to a world-writable font cache area.
\.{MakeTeXPK can be customized to do other things to get the font. For instance, if you are installing \.{dvips to replace (or run alongside) an existing PostScript driver, and that driver demands \.{gf fonts, you can easily modify \.{MakeTeXPK to invoke \.{gftopk to convert the \.{gf files to \.{pk files for \.{dvips. This provides the same space savings listed above.
Because \.{dvips (and thus \.{MakeTeXPK) is run by a wide variety of users, there must be a system-wide place to put the cached font files. In order for everyone to be able to supply fonts, the directory must be world writable. If your system administrator considers this a security hole, \.{MakeTeXPK can write to \.{/tmp/pk or some such directory, and periodically the cached fonts can be moved to a more general system area. Note that the cache directory must exist on the \.{pk file search path in order for \.{MakeTeXPK to work.
\sec{Path Interpretation
The \.{dvips program needs to read a wide variety of files from a large set of directories. It uses a set of paths to do this. The actual paths are listed in the next section; this section describes how the paths are interpreted.
All path variables are names of directories (path elements), separated by colons. Each path element can be either the literal name of a directory or one of the \.{\tilde forms common under UNIX. If a path element is a single tilde, \^{UNIX it is replaced by the contents of the environment variable \.{HOME, which \^{{\tt HOME is normally set to the user’s home directory. If the path element is a tilde followed by anything, the part after the tilde is interpreted as a user name, and his home directory is fetched from the system password file and used as the real path element.
Where environment variables can override paths, an additional path element form is allowed. If a path element is the empty string, it is replaced with the system defaults. Thus, to search the user’s home directory, followed by the system default paths, assuming the current shell is \.{csh, the following command would be used: \cmd{setenv TEXINPUTS \tilde: \noindent This is a path of two elements. The first is the user’s home directory. The second path element is the empty string, indicating that the system defaults should be searched.
The ‘system defaults’ as defined here means the strings set in the \.{Makefile before compilation, rather than any defaults set in \.{config.ps or printer-specific configuration files. This is to prevent path blowup, where more and more directories are added to the path by each level of configuration file.
\sec{Environment Variables
The \.{dvips program reads a certain set of environment variables to configure its operation. The path variables are read after all configuration files are read, so they override values in the configuration files. (The \.{TEXCONFIG variable, of course, is read before the configuration files.) The rest are read as needed.
Note that all defaults supplied here are just as supplied in the provided {\tt Makefile; they will almost certainly have been changed during installation at your particular site.
\descenv HOME,{\rm no default This environment variable is automatically set by the shell and is used to replace any occurrences of \.{\tilde in a path.
\descenv MAKETEXPK,{MakeTeXPK \%n \%d \%b \%m This environment variable sets the command to be executed to create a missing font. A \%n is replaced by the base name of the font to be created (such as \.{cmr10); a \%d is replaced by the resultant horizontal resolution of the font; a \%b is replaced by the horizontal resolution at which \.{dvips is currently generating output, and any \%m is replaced by a string that \MF\ can use as the right hand side of an assignment to \.{mag to create the desired font at the proper resolution. If a mode for \MF\ is set in a configuration file, that is automatically appended to the command before execution. Note that these substitutions are different than the ones performed on PK paths.
\descenv DVIPSHEADERS,{.:/usr/lib/tex/ps This environment variable determines where to search for header files such as {\tt tex.pro, font files, arguments to the {\tt -h option, and such files.
\descenv PRINTER,{\rm no default This environment variable is read to determine which default printer configuration file to read in. Note that it is the responsibility of the configuration file to send output to the proper print queue, if such functionality is desired.
\descenv TEXFONTS,{/LocalLibrary/Fonts/TeXFonts/tfm:/usr/lib/tex/fonts/tfm This is where \.{tfm files are searched for. A \.{tfm file only \^{{\tt tfm needs to be loaded if the font is a resident (PostScript) font or if for some reason no \.{pk file could be found.
\descenv TEXPKS,{/LocalLibrary/Fonts/TeXFonts/pk:/usr/lib/tex/fonts/pk This environment variable is a path on which to search for \.{pk fonts. Certain substitutions are performed if a percent sign is found anywhere \^{{\tt pk in the path. See the description of the {\tt P configuration file option for more information.
\descenv TEXINPUTS,{.:..:/usr/lib/tex/inputs This environment variable is used to find PostScript figures when they are included.
\descenv TEXCONFIG,{.:/usr/lib/tex/ps This environment variable sets the directories to search for configuration files, including the system-wide one. Using this single environment variable and the appropriate configuration files, it is possible to set up the program for any environment. (The other path environment variables can thus be redundant.)
\descenv VFFONTS,{.:/usr/lib/tex/fonts/vf This environment variable sets where \.{dvips looks for virtual fonts. A correct virtual font path is essential if PostScript fonts are to be used.
\sec{Other Bells And Whistles
For special effects, if any of the macros \.{bop-hook, \.{eop-hook, \.{start-hook, or \.{end-hook \^{{\tt bop-hook \^{{\tt eop-hook \^{{\tt start-hook \^{{\tt end-hook are defined in the PostScript \.{userdict, they will be executed at the beginning of a page, end of a page, start of the document, and end of a document, respectively. When these macros are executed, the default PostScript coordinate system and origin is in effect. Such macros can be defined in headers added by the \.{-h option or the \.{header= special, and might be useful for writing, for instance, DRAFT across the entire page, or, with the aid of a shell script, dating the document. These macros are executed outside of the save/restore context of the individual pages, so it is possible for them to accumulate information, but if a document must be divided into sections because of memory constraints, such added information will be lost across section breaks.
The two arguments to {\tt bop-hook are the \TeX\ page number and the sequence number of the page in the file; the first page gets zero, the second one, etc. The arguments to {\tt start-hook are hsize, vsize, mag, hdpi, vdpi, and the name of the \.{dvi input file. The procedures must leave these parameters on the stack. The other hooks are not (currently) given parameters, although this may change in the future.
As an example of what can be done, the following special will write a light DRAFT across each page in the document: {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{‘\$ \special{!userdict begin /bop-hook{gsave 200 30 translate 65 rotate /Times-Roman findfont 216 scalefont setfont 0 0 moveto 0.7 setgray (DRAFT) show grestoredef end$endverb
Note that using \.{bop-hook or \.{eop-hook in any way that preserves information across pages will break compliance with the Adobe document structuring conventions, so if you use any such tricks, it is recommended that you also use the \.{-N option to turn off structured comments.
Several of the above tricks can be used nicely together, and it is not necessary that a ‘printer configuration file’ be used only to set printer defaults. For instance, you might have a file \.{config.dated that contains just the two lines {\vskip0pt\parskip=0pt\leftskip=20pt\begverb{‘\$ E echo /bop-hook \{save /Times-Roman findfont 7 scalefont setfont \ 72 756 moveto \(‘date‘\) show restore\ def >.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 and OS/2 The MS-DOS and OS/2 versions of \.{dvips differs from UNIX in the following ways. \^{MS-DOS \^{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 \.{{\it printername.cfg, not \.{config.{\it printername. \item{$\bullet$ Pipes to printers are not supported by MS-DOS. Output must go to a file. OS/2 supports pipes. \item{$\bullet$ \.{MakeTeXPk is a batch or command file. Since MS-DOS has insufficient memory to run both \.{dvips and \MF\ at the same time, this batch or command 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. OS/2 has more memory so the \.{maketexp.cmd supplied writes out an \.{mfjob file for em\TeX\ and calls \.{mfjob. \item{$\bullet$ \.{dvidrv from em\TeX\ can be used to automatically make fonts under MS-DOS 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{\char123em: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{\char123em: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 and OS/2). \par \fi
\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.
\bye
This document was generated on October 5, 2024 using texi2html 5.0.