Go to the first, previous, next, last section, table of contents.


7. Configuration File Searching

The dvips program has a system of loading configuration files such that parameters can be set globally across the system, on a per-printer basis, or by the user.

When dvips starts up, first the global `config.ps' file is searched for and loaded. This file is looked for along the path for configuration files, which is set in the `Makefile' at compilation. After this master configuration file is loaded, a file by the name of `.dvipsrc' is loaded from the current user's home directory, if such a file exists. This file is loaded in exactly the same way as the global configuration file, and it can override any options set in the global file.

Then the command line is read and parsed. If the `-P' option is encountered, at that point in the command line a configuration file for that printer is read in. Thus, the printer configuration file can override anything in the global or user configuration file, and it can also override most options in the command line up to the point that the `-P' option was encountered.

After the command line has been completely scanned, if there was no `-P' option selected, and also the `-o' and `-f' command line options were not used, a `PRINTER' environment variable is searched for. If this variable exists, and a configuration file for the printer mentioned in it exists, this configuration file is loaded last of all.

Because the printer-specific configuration files are read after the user's configuration file, the user cannot override things in the printer configuration files. On the other hand, the configuration path usually includes the current directory, and can be set to include the user's home directory (or any other directory of the user), so the user can always provide his or her own printer-specific configuration files that will be found before the system global ones.

A few options are treated specially, in that they are not overridden by configuration files:

`-mode'
This overrides any mode setting (`M' line) in `config.*'. `-mode' does not affect the resolution, however.
`-o'
This overrides any output setting (`o' line) in `config.*'.
`-D'
As well as setting the current resolution, this unsets the mode if the mode was set from a configuration file. If `config.$PRINTER' is read, however, any `D' or `M' lines from it will take effect.

The purpose of these special cases is to (1) minimize the chance of having a mismatched mode and resolution (which `MakeTeXPK' cannot handle), and (2) to let command-line options override config files.

7.1 Configuration File Options

Most of the configuration file options are similar to the command line options, but there are a few new ones.

Again, many may be turned off by suffixing the letter with a zero (0). These options are `a', `f', `q', `r', `K', `N', `U', and `Z'.

Within a configuration file, any empty line or line starting with a space, asterisk, equal sign, or a pound sign is ignored.

`@ name hsize vsize'
This option is used to set the paper size defaults and options for the particular printer this configuration file describes. There are three formats for this option. If the option is specified on a line by itself, with no parameters, it instructs dvips to discard all other paper size information (possibly from another configuration file) and start fresh. If three parameters are given, as above, with the first parameter being a name and the second and third being a dimension (as in 8.5in or 3.2cc, just like in the `papersize' special), then the option is interpreted as starting a new paper size description, where name is the name and hsize and vsize describe the horizontal and vertical size of the sheet of paper, respectively. If both hsize and vsize are equal to zero (although you must still specify units!) then any page size will match it. If the `@' character is immediately followed by a `+' sign, then the remainder of the line (after skipping any leading blanks) is treated as PostScript code to send to the printer to select that particular paper size. After all that, if the first character of the line is an exclamation point, then the line is put in the initial comments section of the final output file; else, it is put in the setup section of the output file. For instance, a subset of the paper size information supplied in the default `config.ps' looks like
@ letterSize 8.5in 11in
@ letter 8.5in 11in
@+ %%BeginPaperSize: Letter
@+ letter
@+ %%EndPaperSize
@ legal 8.5in 14in
@+ ! %%DocumentPaperSizes: Legal
@+ %%BeginPaperSize: Legal
@+ legal
@+ %%EndPaperSize
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 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 `hsize' and `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 `BeginPaperSize' comments and paper size setting commands; others (such as the NeXT) want `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 `config.ps' file for a more realistic example.
`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.
`b num'
Generate num copies of each page, but duplicating the page body rather than using the `#numcopies' option. This can be useful in conjunction with a header file setting `\bop-hook' to do color separations or other neat tricks.
`e num'
Set the maximum drift parameter to num dots (pixels) as explained above.
`f'
Run as a filter by default.
`h name'
Add name as a PostScript header file to be downloaded at the beginning.
`i num'
Make each section be a separate file, and set the maximum number of pages in a given file to 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.
`m num'
The value num is the virtual memory available for fonts and strings in the printer. 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:
%! Hey, we're PostScript
/Times-Roman findfont 30 scalefont setfont 144 432 moveto
vmstatus exch sub 40 string cvs show pop showpage
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 name'
The default output file is set to name. As above, it can be a pipe. Useful in printer-specific configuration files to redirect the output to a particular printer queue.
`p name'
The file to examine for PostScript font aliases is name. It defaults to `psfonts.map'. This option allows different printers to use different resident fonts. If the name starts with a `+' 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.
`q'
Run quietly by default.
`r'
Reverse the order of pages by default.
`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.
`D num'
Set the vertical and horizontal resolution to num dots per inch. Useful in printer-specific configuration files.
`E command'
Executes the command listed; can be used to get the current date into a header file for inclusion, for instance. Possibly dangerous; in many installations this may be disabled, in which case a warning message will be printed if the option is used.
`H path'
The (colon-separated) path to search for PostScript header files is path. The environment variable `DVIPSHEADERS' overrides this.
`K'
Filter comments out of included PostScript files; see the description above for more information.
`M mode'
Set mode as the METAFONT mode to be used when generating fonts and for path searching. The `-mode' option overrides this. With the default paths, specifying a mode this way also makes the program assume the fonts are in a subdirectory named mode. See section `TeX directory structure' in Kpathsearch library.
`N'
Disable PostScript comments by default.
`O offset'
Move the origin by a certain amount. The 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 `testpage.tex' to determine the correct value for your printer. Be sure to do several runs with the same O value--some printers vary widely from run to run.
`P path'
The (colon-separated) path to search for bitmap `pk' font files is path. The `PKFONTS', `TEXPKS', `GLYPHFONTS', and `TEXFONTS' environment variables override this. See section `TeX environment variables' in Kpathsearch library.
`R num num ...'
Sets up a list of default resolutions to search for `pk' fonts, if the requested size is not available. The output will then scale the font found using PostScript scaling to the requested size. The resulting output may be ugly, and thus a warning is issued. To turn this off, use a line with just the `R' and no numbers.
`S path'
The path to search for special illustrations (Encapsulated PostScript files or psfiles) is path. The `TEXPICTS' and then `TEXINPUTS' environment variables override this.
`T path'
The path to search for the `tfm' files is path. The `TFMFONTS' and then `TEXFONTS' environment variables overrides this. This path is used for resident fonts and fonts that can't otherwise be found.
`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.
`V path'
The path to search for virtual font `vf' files is path. This may be device-dependent if you use virtual fonts to simulate actual fonts on different devices.
`W string'
Sends 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.
`X num'
Set the horizontal resolution to num dots per inch.
`Y num'
Set the vertical resolution to num dots per inch.
`Z'
Compress all downloaded fonts by default, as above.


Go to the first, previous, next, last section, table of contents.