diff options
Diffstat (limited to 'Build/source/texk/dvipsk/dvips.texi')
-rw-r--r-- | Build/source/texk/dvipsk/dvips.texi | 4738 |
1 files changed, 0 insertions, 4738 deletions
diff --git a/Build/source/texk/dvipsk/dvips.texi b/Build/source/texk/dvipsk/dvips.texi deleted file mode 100644 index 38f129ce99e..00000000000 --- a/Build/source/texk/dvipsk/dvips.texi +++ /dev/null @@ -1,4738 +0,0 @@ -\input texinfo -@setfilename dvips.info -@settitle Dvips: A DVI-to-PostScript translator - -@set version 2021.1 -@set month-year February 2021 - -@copying -This manual documents Dvips version @value{version} -(@value{month-year}), a program to translate a DVI file into -PostScript. You may freely use, modify and/or distribute this file. -@end copying - -@c Define a new index for filenames and options. -@defcodeindex fl -@defcodeindex op - -@c Put everything in one index (arbitrarily chosen to be the concept index). -@syncodeindex fl cp -@syncodeindex fn cp -@syncodeindex ky cp -@syncodeindex op cp -@syncodeindex pg cp -@syncodeindex vr cp - -@dircategory TeX -@direntry -* DVI-to-Postscript: (dvips). Translating TeX DVI files to PostScript. -* afm2tfm: (dvips)Invoking afm2tfm. Making Type 1 fonts available to TeX. -* dvips: (dvips)Invoking Dvips. DVI-to-PostScript translator. -@end direntry - -@titlepage -@title Dvips: A DVI-to-PostScript Translator -@subtitle for version @value{version} -@subtitle @value{month-year} -@author Tomas Rokicki -@author @url{https://tug.org/dvips} - -@page -@insertcopying -@vskip 0pt plus 1filll -@end titlepage - -@summarycontents -@contents - -@ifnottex -@node Top -@top Dvips - -@insertcopying - -@menu -* Why Dvips:: Why use Dvips? -* Installation:: How to compile and install Dvips. -* Invoking Dvips:: Command-line options, configuration files, etc. -* Paper size and landscape:: Changing the paper dimensions. -* Interaction with PostScript:: TeX meets Dvips meets PostScript. -* PostScript fonts:: Installing and using PostScript fonts. -* Color:: Using color with Dvips. -* Index:: General index. -@end menu -@end ifnottex - - -@node Why Dvips -@chapter 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 of using Dvips, and may be skipped if you are just -interested in learning how to use the program. @xref{Installation}, for -details of compilation and installation. - -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 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 any resolution are supported, even if they have different -resolutions in the horizontal and vertical directions. High resolution -output is supported for typesetters, including an option that compresses -the bitmap fonts so that typesetter virtual memory is 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 Metafont exists on -the system, or fonts can be converted from GF to PK format -on demand. 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 aesthetics of the resulting output. - -One of the most important features is the support of virtual fonts, -which add an entirely new level of flexibility to @TeX{}. Dvips even -comes with its own Afm2tfm program that can create the virtual fonts -and @TeX{} font metric files automatically from 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. - -@cindex Rokicki, Tomas -Tom Rokicki wrote and maintains the original Dvips program. - - -@node Installation -@chapter Installation - -@cindex configuration, of Dvips -@cindex compilation -@cindex installation, of Dvips - -@c ifset version -@c (A copy of this chapter is in the distribution file @file{dvipsk/INSTALL}.) -@c end ifset - -Installing Dvips is mostly the same as installing any Kpathsea-using -program. Therefore, for the basic steps involved, -@pxref{Installation,,, kpathsea, Kpathsea}. - -For solutions to common installation problems and information on how to -report a bug, see the file @file{kpathsea/BUGS} (@pxref{Bugs,,, -kpathsea, Kpathsea}). For solutions to Dvips-specific problems, -@pxref{Debug options}. - -Dvips does require some additional installation, detailed in the -sections below. Also, to configure color devices, @pxref{Color device -configuration}. - -@menu -* config.ps installation:: Printer and site Dvips configuration. -* PostScript font installation:: Many PostScript fonts are freely available. -* Ghostscript installation:: A free PostScript interpreter. -* Diagnosing problems:: Some common runtime difficulties. -@end menu - - -@node config.ps installation -@section @file{config.ps} installation - -@flindex config.ps @r{installation} -@cindex installation of @file{config.ps} -@cindex printer configuration -@cindex paper size, default -@cindex configuration files, creating - -Dvips has its own configuration files: a file @file{config.ps} for -sitewide defaults, and a file @file{config.@var{printer}} for each -printer (output device). Since these are site-specific, @code{make -install} does not create them; you must create them yourself. - -(These Dvips configuration files are independent of the Kpathsea -configuration file @file{texmf.cnf} (@pxref{Config files,,,kpathsea, -Kpathsea}). - -@flindex config.proto -@cindex prototype printer configuration file -@cindex printer configuration file, prototype -@cindex configuration files, prototype -Dvips configuration files contents and searching are described fully in -@ref{Config files}. The simplest way to create a new configuration file -is to copy and modify the file @file{dvipsk/contrib/config.proto}, -seasoning with options to your taste from @ref{Config files}. Here is -@file{config.proto} -for your reading pleasure: -@example -@include contrib/config.proto -@end example - - -@node PostScript font installation -@section PostScript font installation - -@cindex installation of PostScript fonts -@cindex fonts, installation of PostScript -@cindex PostScript fonts, installing - -To use PostScript fonts with @TeX{} and Dvips, you need both metric -files (@file{.tfm} and @file{.vf}) and the outlines (@file{.pfa} or -@file{.pfb}). @xref{Font concepts}. Current @TeX{} systems -come with support for 35 base PostScript fonts and many more. - -@cindex fonts, system PostScript -@cindex PostScript fonts, on your system -@flindex psfonts.map -If you have additional PostScript fonts, you can make them available -to Dvips by (1)@tie{}giving them appropriate filenames; and -(2)@tie{}running Afm2tfm (@pxref{Making a font available}) to make TFM -and VF metrics for @TeX{} and Dvips to use. Also add them to -@file{psfonts.map} (@pxref{psfonts.map}); this file must contain -everything available in the system. The @code{updmap} program is -usually used to maintain @file{psfonts.map}; run @samp{updmap --help} -for lots of information about how it works. - - -@node Ghostscript installation -@section Ghostscript installation - -@cindex Ghostscript installation -@pindex gs @r{installation} - -@cindex Deutsch, Peter -@cindex Epson printers -@cindex previewing Dvips output -@cindex PostScript previewers -@cindex PDF files, making -@cindex Aladdin Ghostscript -Ghostscript is a PostScript interpreter freely available to end-users, -originally written by Peter Deutsch. It can read the PostScript -produced by Dvips and render it on your monitor, or for another device -(e.g., an Epson printer) that does not support PostScript, or in PDF -format. The latest version is available via -@url{https://ghostscript.com}. - -@cindex Theisen, Tim -@pindex ghostview -@cindex Ghostview, and no @samp{N} -@cindex EPS, and Ghostview -@cindex standard PostScript, required by Ghostview -@findex %%Page@r{, required by Ghostview} -The program Ghostview, originally written by Johannes Plass and Tim -Theisen, provides typical previewing capabilities (next page/previous -page, magnification, etc.). It requires Ghostscript to run, and files -in structured Postscript, specifically with @samp{%%Page} comments (no -@samp{N} in @file{config.ps}). The current version is known as GV, -and is available from @url{https://www.gnu.org/software/gv}. - - -@node Diagnosing problems -@section Diagnosing problems - -@cindex problems -@cindex trouble -@cindex debugging - -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. The following sections provide some helpful hints if you find -yourself in such a situation. - -For details on effective bug reporting, common installation problems, -and @code{mktexpk} problems, @pxref{Bugs,,, kpathsea, Kpathsea}. - -A good first debugging operation is to set the environment variable -@env{DVIPSDEBUG}, which will display any configuration and map files -read by Dvips. This way you can be sure it's finding the files and -settings you expect. - -@menu -* Debug options:: Getting diagnostics. -* No output:: No output at all. -* Small or inverted:: Output too small or inverted. -* Printer errors:: The printer sends back errors. -* Long documents fail:: Long documents fail to print. -* Including graphics fails:: Figures don't work. -@end menu - - -@node Debug options -@subsection Debug options - -@cindex debugging options -@cindex options, debugging - -The @samp{-d} flag to Dvips helps in tracking 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, -specify the appropriate number given below; if you wish to track -multiple classes, sum the numbers of the classes you wish to track. -To track all classes, you can use @code{-1}. - -You can also set the environment variable @env{KPATHSEA_DEBUG} instead -of using @samp{-d}. Some of these debugging options are actually -provided by Kpathsea (@pxref{Debugging, , , kpathsea, Kpathsea}). - -The classes are: - -@table @asis -@item 1 -specials -@item 2 -paths -@item 4 -fonts -@item 8 -pages -@item 16 -headers -@item 32 -font compression -@item 64 -files -@item 128 -(omitted) -@item 256 -config files -@item 512 -Kpathsea @code{stat} calls -@item 1024 -Kpathsea hash table lookups -@item 2048 -Kpathsea path element expansion -@item 4096 -Kpathsea path searches -@end table - - -@node No output -@subsection No output at all - -@cindex output, none -@cindex no output at all -@cindex failure, to print at all - -If you are not getting any output at all, even from the simplest -one-character file (for instance, @samp{\ \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 -@samp{ehandler.ps}.) -@flindex ehandler.ps - -@cindex PowerPage PostScript implementation -@cindex Shinko CHC-S446i printer -@cindex Mitsubishi Shinko CHC-S446i printer -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. Dvips tries to work around as many bugs as possible in -common non-Adobe PostScript interpreters, but doubtless it misses a few. -PowerPage Revision 1, Interpreter Version 20001.001, on a Mitsubishi -Shinko CHC-S446i color thermal dye sublimation printer is known to be -unable to print with any but builtin fonts. - -If Dvips gives any strange error messages, or compilation on your -machine generated a lot of warnings, perhaps the Dvips program itself is -broken. Try using the debug options to determine where the error -occurred (@pxref{Debug options}). - -It is possible your spooler is broken and is misinterpreting the -structured comments. Try the @samp{-N} flag to turn off structured -comments and see what happens. - - -@node Small or inverted -@subsection Output too small or inverted - -@cindex output, too small -@cindex output, inverted -@cindex inverted output -@cindex too-small output - -@cindex save/restore, and inverted output -If some documents come out inverted or too small, probably your spooler -is not supplying an end of job indicator at the end of each file. (This -commonly happens on small machines that don't have spoolers.) You can -force Dvips to do this with the @samp{-F} flag (or @samp{F} config file -option), but this generates files with a terminating binary character -(control-D). You can also try using the @samp{-s} flag (or @samp{s} -config file option) to enclose the entire job in a save/restore pair. -@xref{Command-line options}, and @ref{Config files}. - - -@node Printer errors -@subsection Error messages from printer - -@cindex printer errors -@cindex error messages from printer -@cindex failure, and printer errors - -@cindex @t{bop undefined} error -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 @samp{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 @samp{-N} option, but it'd be best to get your spooling -software updated. - -@cindex VM exhausted -@cindex printer memory exhausted -@cindex memory of printer exhausted -Another error message is @samp{VM exhausted}. Some printers indicate -this error by locking up, others quietly reset. This is caused by Dvips -thinking that the printer has more memory than it actually does, and -then printing a complicated document. To fix this, try lowering the -@samp{m} parameter in the configuration file; use the debug option to -make sure you adjust the correct file. - -Other errors may indicate you are trying to include graphics that don't -nest properly in other PostScript documents, among other things. Try -the PostScript file on a QMS PS-810 or other Adobe PostScript printer if -you have one, or Ghostscript (@pxref{Ghostscript installation}); it -might be a problem with the printer itself. - - -@node Long documents fail -@subsection Long documents fail to print - -@cindex long documents not printing -@cindex failure, of long documents - -This is usually caused by incorrectly specifying the amount of memory -the printer has in the configuration file; see the previous section. - - -@node Including graphics fails -@subsection Including graphics fails - -@cindex including graphics fails -@cindex graphics inclusion fails -@cindex failure, to include graphics - -The most common problem with including graphics is an incorrect bounding -box (@pxref{Bounding box}). Complain to whoever wrote the software that -generated the file if the bounding box is indeed incorrect. - -@cindex Illustrator, workaround for -Another possible problem is that the figure you are trying to include -does not nest properly; there are certain rules PostScript applications -must 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 @samp{-K} flag which strips the comments -from an included figure. This might be necessary if the PostScript -spooling software does not read the structured 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. - -@cindex binary files, not supported -Any application which generates graphics output containing raw binary -(not ASCII hex) will probably fail with Dvips. - - -@node Invoking Dvips -@chapter Invoking Dvips - -@cindex command-line options -@cindex options, Dvips -@cindex invoking Dvips - -Dvips reads a DVI file as output by (for example) @TeX{}, and converts -it to PostScript, taking care of builtin or downloaded PostScript fonts, -font reencoding, color, etc. These features are described in other -chapters in this document. - -There many ways to control Dvips' behavior: configuration files, -environment variables, and command-line options. - -@menu -* Basic usage:: -* Command-line options:: -* Environment variables:: -* Config files:: -@end menu - - -@node Basic usage -@section Basic usage of Dvips - -@cindex usage, basic - -To use Dvips at its simplest, simply type - -@example -dvips foo -@end example - -@noindent -where @file{foo.dvi} is the output of @TeX{} that you want to print. -The default output is to a corresponding file @file{foo.ps}; Dvips may -also have been locally configured to output directly to a printer by -default. - -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, so -progress reports appear by default. The next time that document is -printed, these fonts will have been saved in the proper directories, so -printing will go much faster. (If Dvips tries to endlessly generate the -same fonts over and over again, it hasn't been installed properly. -@xref{Unable to generate fonts,,, kpathsea, Kpathsea}.) - -Many options are available (see the next section). For a brief summary -of available options, run - -@example -dvips --help -@end example - - -@node Command-line options -@section Command-line options - -Dvips has a plethora of command line options. Reading through this -section will give a good idea of the capabilities of the driver. - -@menu -* Option summary:: Quick listing, from Dvips --help. -* Option details:: More information about each option. -@end menu - - -@node Option summary -@subsection Option summary - -@cindex options, summary -Here is a handy summary of the options; it is printed out when you run -Dvips with no arguments or with the standard @samp{--help} option. -@opindex --help - -@verbatiminclude dvips.help - - -@node Option details -@subsection Option details - -@cindex option, details of - -Many of the parameterless options listed here can be turned off by -suffixing the option with a zero (@samp{0}); for instance, to turn off -page reversal, use @samp{-r0}. Such options are marked with a trailing -@samp{*}. - -@table @samp -@item - -@opindex - -@cindex options, reading from standard input -@cindex standard input, reading options from -Read additional options from standard input after processing the command -line. - -@item --help -@opindex --help -Print a usage message and exit. - -@item --version -@opindex --version -Print the version number and exit. - -@item -a* -@opindex -a -@cindex memory, conserving -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. - -@item -A -@opindex -A -@cindex odd pages only -Print only the odd pages. This option uses @TeX{} -page numbers, not physical page numbers. - -@item -b @var{num} -@opindex -b @var{num} -@vindex /#copies -@cindex copies, duplicated page bodies -@cindex color separations -Generate @var{num} copies of each page, but duplicating the page body -rather than using the @samp{/#copies} PostScript variable. This can -be useful in conjunction with a header file setting @samp{bop-hook} to -do color separations or other neat tricks. - -@item -B -@opindex -B -@cindex even pages only -@cindex double-sided printing -Print only the even pages. This option uses @TeX{} page numbers, not -physical page numbers. - -@item -bitmapfontenc @var{option} -@opindex -bitmapfontenc @var{option} -@cindex bitmap font encoding -Turns bitmap font encoding to @samp{off}, @samp{on} (no warnings -for missing bitmap font encodings), or @samp{strict} (with warnings -for missing bitmap font encodings). - -@item -c @var{num} -@opindex -c @var{num} -@vindex /#copies -@cindex copies, uncollated -@cindex uncollated copies -Generate @var{num} consecutive copies of every page, i.e., the output is -uncollated. This merely sets the builtin PostScript variable -@samp{/#copies}. - -@item -C @var{num} -@opindex -C @var{num} -@cindex copies, collated -@cindex collated copies -Generate @var{num} copies, but collated (by replicating the data in the -PostScript file). Slower than the @samp{-c} option, but easier on the -hands, and faster than resubmitting the same PostScript file multiple -times. - -@item -d @var{num} -@opindex -d @var{num} -@cindex debugging -Set the debug flags, showing what Dvips (thinks it) is doing. This will -work unless Dvips has been compiled without the @samp{DEBUG} option (not -recommended). @xref{Debug options}, for the possible values of -@var{num}. Use @samp{-d -1} as the first option for maximum output. - -@item -D @var{num} -@opindex -D @var{num} -@cindex resolution, setting -Set both the horizontal and vertical resolution to @var{num}, given in -dpi (dots per inch). This affects the choice of bitmap fonts that are -loaded and also the positioning of letters in resident PostScript -fonts. Must be between 10 and 10000. This affects both the horizontal -and vertical resolution. If a high resolution (something greater than -400 dpi, say) is selected, the @samp{-Z} flag should probably also be -used. If you are using fonts made with Metafont, such as Computer -Modern, @file{mktexpk} needs to know about the value for @var{num} -that you use or Metafont will fail. See the file -@url{ftp://ftp.tug.org/tex/modes.mf} for a list of resolutions and mode -names for most devices. - -@item -e @var{num} -@opindex -e @var{num} -@cindex maxdrift -@cindex accuracy in positioning -@cindex positioning accuracy -Maximum drift in pixels of each character from its `true' -resolution-independent position on the page. The default value of this -parameter is resolution dependent (it is the number of entries in the -list [100, 200, 300, 400, 500, 600, 800, 1000, 1200, 1600, 2000, 2400, -2800, 3200, @dots{}] that are less than or equal to the resolution in -dots per inch). Allowing individual characters to `drift' from their -correctly rounded positions by a few pixels, while regaining the true -position at the beginning of each new word, improves the spacing of -letters in words. - -@item -E* -@opindex -E -@cindex EPSF, generating -@cindex tight bounding box, finding -@cindex bounding box, finding tight -Generate an EPSF file with a tight bounding box. This only looks at -marks made by characters and rules, not by any included graphics. In -addition, it gets the glyph metrics from the TFM file, so characters -that print outside their enclosing TFM box may confuse it. In addition, -the bounding box might be a bit too loose if the character glyph has -significant left or right side bearings. Nonetheless, this option works -well enough for creating small EPSF files for equations or tables or the -like. (Of course, Dvips output, especially when using bitmap fonts, is -resolution-dependent and thus does not make very good EPSF files, -especially if the images are to be scaled; use these EPSF files with -care.) For multiple page input files, also specify @samp{-i} to get -each page as a separate EPSF file; otherwise, all the pages are overlaid -in the single output file. - -@item -f* -@opindex -f -@cindex filter, running as a -@cindex standard I/O -@cindex pipes, not readable -@vindex PRINTER@r{, avoided with @samp{-f}} -Run as a filter. Read the DVI file from standard input and write the -PostScript to standard output. The standard input must be seekable, so -it cannot be a pipe. If your input must be a pipe, write a shell script -that copies the pipe output to a temporary file and then points Dvips at -this file. This option also disables the automatic reading of the -@code{PRINTER} environment variable; use @samp{-P$PRINTER} after the -@samp{-f} to read it anyway. It also turns off the automatic sending of -control-D if it was turned on with the @samp{-F} option or in the -configuration file; use @samp{-F} after the @samp{-f} to send it anyway. - -@item -F* -@opindex -F -@cindex EOF -@cindex control-D -@cindex printer, driving directly -@cindex spooler, lacking -Write control-D (ASCII code 4) as the very last character of the -PostScript file. This is useful when Dvips is driving the printer -directly instead of working through a spooler, as is common on personal -systems. On systems shared by more than one person, this is not -recommended. - -@item -G* -@opindex -G -@cindex low characters, shifting -@cindex non-printing characters, shifting -Shift non-printing characters (ASCII 0-32, 127) to higher-numbered positions. -This was useful to work around bugs in old versions of Adobe's PDF -reader. It's more likely to cause problems nowadays. - -@item -h @var{name} -@opindex -h @var{name} -@cindex header file, downloading -@cindex userdict@r{, used for header files} -Prepend @var{name} as an additional header file, or, if @var{name} is -@samp{-}, suppress all header files. Any definitions in the header file -get added to the PostScript @samp{userdict}. - -@item -i* -@opindex -i -@cindex sections output, in separate files -@cindex multiple output files -@cindex output files, multiple -Make each section be a separate file; a @dfn{section} is a part of the -document processed independently, most often created to avoid memory -overflow. The filenames are created replacing the suffix of the -supplied output file name by a three-digit sequence number. This option -is most often used in conjunction with the @samp{-S} option which sets -the maximum section length in pages; if @samp{-i} is specified and -@samp{-S} is not, each page is output as a separate file. For instance, -some phototypesetters cannot print more than ten or so consecutive pages -before running out of steam; these options can be used to automatically -split a book into ten-page sections, each to its own file. - -On the other hand, if your document uses very large fonts or very -large included figures, Dvips might take it upon itself to split the -output into unwanted sections, to try to avoid overflowing printer -memory. @xref{Headers and memory usage}, for ways to handle this. - -@item -j* -@opindex -j @r{for partial font downloading} -Download only needed characters from Type 1 fonts. This is the -default in the current release. Some debugging flags trace this operation -(@pxref{Debug options}). You can also control partial downloading on a -per-font basis (@pxref{psfonts.map}). - -@item -k* -@opindex -k @r{for cropmarks} -@cindex cropmarks -@flindex crop.pro -Print crop marks. This option increases the paper size (which should be -specified, either with a paper size special or with the @samp{-T} -option) by a half inch in each dimension. It translates each page by a -quarter inch and draws cross-style crop marks. It is mostly useful with -typesetters that can set the page size automatically. This works by -downloading @file{crop.pro}. - -@item -K* -@opindex -K -@cindex comments, removing included -@findex %%Page@r{, removing} -Remove comments in included PostScript graphics, font files, and -headers; only necessary to get around bugs in spoolers or PostScript -post-processing programs. Specifically, the @samp{%%Page} -comments, when left in, often cause difficulties. Use of this flag can -cause other graphics to fail, however, since the PostScript header -macros from some software packages read portion the input stream line by -line, searching for a particular comment. - -@item -l [=]@var{num} -@opindex -l [=]@var{num} -@cindex last page printed -@cindex page, last printed -@cindex physical page number, and @samp{-l} -@cindex absolute page number, and @samp{-l} -The last page printed will be the first one numbered @var{num}. Default -is the last page in the document. If @var{num} is prefixed by an equals -sign, then it (and the argument to the @samp{-p} option, if specified) -is treated as a physical (absolute) page number, rather than a value to -compare with the @TeX{} @samp{\count0} values stored in the DVI file. -Thus, using @samp{-l =9} will end with the ninth page of the document, -no matter what the pages are actually numbered. - -@item -L* -@opindex -L -@cindex @samp{papersize} special, first vs.@: last -By default or with @code{-L1}, the last @samp{papersize} special wins; -with @code{-L0}, the first special wins. @xref{@samp{papersize} special}. - -@item -m* -@opindex -m -@cindex manual feed -Specify manual feed, if supported by the output device. - -@item -mode @var{mode} -@opindex -mode @var{mode} -@cindex mode name, specifying -@cindex Metafont mode, specifying -Use @var{mode} as the Metafont device name for path searching and font -generation. This overrides any value from configuration files. With -the default paths, explicitly specifying the mode also makes the program -assume the fonts are in a subdirectory named @var{mode}. -@xref{TeX directory structure,, @TeX{} directory structure, kpathsea, -Kpathsea}. If Metafont does not understand the @var{mode} name, see -@ref{Unable to generate fonts,,, kpathsea, Kpathsea}. - -@item -M* -@opindex -M -@cindex font generation, avoiding -@pindex mktexpk@r{, avoiding} -@flindex missfont.log -@comment this description repeated in kpathsea.texi -Turns off automatic font generation (@file{mktexpk}). If -@code{mktexpk}, the invocation is appended to a file -@file{missfont.log} (by default) in the current directory. You can then -execute the log file to create the missing files after fixing the -problem. -@vindex TEXMFOUTPUT -@vindex MISSFONT_LOG -If the current directory is not writable and the environment variable or -configuration file value @samp{TEXMFOUTPUT} is set, its value is used. -Otherwise, nothing is written. The name @samp{missfont.log} is -overridden by the @samp{MISSFONT_LOG} environment variable or -configuration file value. - -@item -n @var{num} -@opindex -n @var{num} -@cindex maximum pages printed -@cindex pages, maximum printed -Print at most @var{num} pages. Default is 100000. - -@item -N* -@opindex -N -@cindex structured comments -@cindex TranScript -@findex %%Page@r{, not generating} -Turns off generation of structured comments such as @samp{%%Page}; this -may be necessary on some systems that try to interpret PostScript -comments in weird ways, or on some PostScript printers. Old versions of -TranScript in particular cannot handle modern Encapsulated PostScript. -Beware: This also disables page movement, etc., in PostScript viewers -such as Ghostview. - -@item -noomega -@opindex -noomega -@cindex Omega extensions -@cindex p@TeX{} extensions -Disable the use of Omega extensions when interpreting DVI -files. By default, the additional opcodes @samp{129} and @samp{134} -are recognized by Dvips as Omega or p@TeX{} extensions and interpreted as -requests to set 2-byte characters. - -@item -noptex -@opindex -noptex -@cindex p@TeX{} extensions -Disable the use of p@TeX{} extensions when interpreting DVI files. By -default, the additional opcodes @samp{130} and @samp{135} are -recognized by Dvips as Omega extensions and interpreted as requests to -set 3-byte characters, and @samp{255} as request to change the -typesetting direction. - -The only drawback is that the virtual font array will (at least -temporarily) require 65536 or more positions instead of the default -256 positions, i.e., the memory requirements of Dvips will be somewhat -larger. If you find this unacceptable or encounter another problem -with the Omega or p@TeX{} extensions, you can switch off the p@TeX{} -extension by using @samp{-noptex}, or both by using @samp{-noomega} -(but please do send a bug report if you find such problems, -@pxref{Bugs,,, kpathsea, Kpathsea}). - -@item -o @var{name} -@opindex -o @var{name} -@cindex output, redirecting -@cindex standard output, output to -Send output to the file @var{name}. If @samp{-o} is specified without -@var{name} (i.e., it is the last thing on the command line), the -default is @samp{@var{file}.ps} where the input DVI file was -@samp{@var{file}.dvi}. If @samp{-o} isn't given at all, the -configuration file default is used. - -@findex popen @r{for output} -@kindex - @r{as output filename} -@kindex ! @r{starting output filename} -@kindex | @r{starting output filename} -@cindex lpr spooler, MS-DOS emulation -@cindex spooling to lpr on MS-DOS -If @var{name} is @samp{-}, output goes to standard output. If the first -character of @var{name} is @samp{!} or @samp{|}, then the remainder will -be used as an argument to @code{popen}; thus, specifying @samp{|lpr} as -the output file will automatically queue the file for printing as -usual. (The MS-DOS version will print to the local printer device -@file{PRN} when @var{name} is @samp{|lpr} and a program by that name -cannot be found.) - -@samp{-o} disables the automatic reading of the @code{PRINTER} -environment variable, and turns off the automatic sending of control-D. -See the @samp{-f} option for how to override this. - -@item -O @var{x-offset},@var{y-offset} -@opindex -O @var{x-offset},@var{y-offset} -@cindex offset pages -@cindex printer offset -Move the origin by @var{x-offset},@var{y-offset}, a comma-separated -pair of dimensions such as @samp{.1in,-.3cm} (@pxref{@samp{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 usually best specified in the -printer-specific configuration file. - -@flindex testpage.tex -This is useful for a printer that consistently offsets output pages by a -certain amount. You can use the file @file{testpage.tex} to determine -the correct value for your printer. Be sure to do several runs with the -same @code{O} value---some printers vary widely from run to run. - -@findex bop-hook@r{, and offset pages} -If your printer offsets every other page consistently, instead of every -page, your best recourse is to use @samp{bop-hook} (@pxref{PostScript -hooks}). - -@item -p [=]@var{num} -@opindex -p [=]@var{num} -@cindex first page printed -@cindex page, first printed -@cindex physical page number, and @samp{-p} -@cindex absolute page number, and @samp{-p} -The first page printed will be the first one numbered @var{num}. Default -is the first page in the document. If @var{num} is prefixed by an -equals sign, then it (and the argument to the @samp{-l} option, if -specified) is treated as a physical (absolute) page number, rather than -a value to compare with the @TeX{} @samp{\count0} values stored in the -DVI file. Thus, using @samp{-p =3} will start with the third page of -the document, no matter what the pages are actually numbered. - -@item -pp @var{first}-@var{last} -@opindex -pp @var{first}-@var{last} -@cindex page range -@opindex -pp @var{range} -Print pages @var{first} through @var{last}; equivalent to @samp{-p -@var{first} -l @var{last}}, except that multiple @samp{-pp} options -accumulate, unlike @samp{-p} and @samp{-l}. The @samp{-} separator can -also be @samp{:}. - -@item -P @var{printer} -@opindex -P @var{printer} -@flindex config.ps -Read the configuration file @file{config.@var{printer}} -(@file{@var{printer}.cfg} on MS-DOS), which typically sets the output -name (most likely @samp{o |lpr -P@var{printer}}), resolution, Metafont -mode, and perhaps other printer-specific defaults. It works best to -put sitewide defaults in the one master @samp{config.ps} file and only -things that vary from printer to printer in the -@samp{config.@var{printer}} files; @samp{config.ps} is read before -@samp{config.@var{printer}}. - -A configuration file for eventual creation of Adobe PDF files is -provided in @samp{config.pdf} and thus can be loaded with -@samp{-Ppdf}. It will try to include Type 1 outline fonts into the -PostScript file (@pxref{Hypertext caveats}). - -If no @samp{-P} or @samp{-o} is given, the environment variable -@code{PRINTER} is checked. If that variable exists, and a corresponding -@file{config.@var{printer}} (@file{@var{printer}.cfg} on MS-DOS) file -exists, it is read. -@xref{Configuration file searching}. - -@item -q* -@opindex -q -@cindex quiet operation -@cindex silent operation -@cindex warnings, suppressing -Run quietly. Don't chatter about pages converted, etc.@:, -and report no warnings (only errors) to standard error. - -@item -r* -@opindex -r -@cindex reverse pagination -Output pages in reverse order. By default, page 1 is output first. - -@item -R -@opindex -R -@cindex security -@cindex shell command execution, disabling -@cindex absolute filenames, disabling -@cindex @file{..}-relative filenames -Run securely. @samp{-R2} disables both shell command execution in -@code{\special} (via @samp{`}, @pxref{Dynamic creation of graphics}) -and config files (via the @samp{E} option, @pxref{Configuration file -commands}) and opening of any absolute or @file{..}-relative -filenames. @samp{-R1}, the default, forbids shell escapes but allows -absolute filenames. @samp{-R0} allows both. - -@item -s* -@opindex -s -@cindex save/restore, generating global -Enclose the output in a global save/restore pair. This causes the file -to not be truly conformant, and is thus not recommended, but is useful -if you are driving a deficient printer directly and thus don't care too -much about the portability of the output to other environments. - -@item -S @var{num} -@opindex -S @var{num} -Set the maximum number of pages in each `section'. This option is most -commonly used with the @samp{-i} option; see its description above for -more information. - -@item -t @var{papertype} -@opindex -t @var{papertype} -@cindex paper type -@cindex media -@cindex letter papertype -@cindex legal papertype -@cindex ledger papertype -@cindex a4 papertype -@cindex a3 papertype -@cindex landscape papertype -@cindex papersize special, and no @samp{-t} -Set the paper type to @var{papertype}, usually defined in one of the -configuration files, along with the appropriate PostScript code to -select it (@pxref{Config file paper sizes}). -@itemize @minus{} -@item You can also specify a @var{papertype} of @samp{landscape}, -which rotates a document by 90 degrees. -@item To rotate a document whose paper type is not the default, you -can use the @samp{-t} option twice, once for the paper type, and once -for @samp{landscape}. -@item In general, you should not use any @samp{-t} option when -using a @samp{papersize} special, which some @LaTeX{} packages (e.g., -@samp{hyperref}) insert. -@item One exception is when using a nonstandard paper size that is not -already defined in @file{config.ps}; in this case, you need to specify -@samp{-t@tie{}unknown}. -@item Another exception is when producing multi-page files for further -processing; use @samp{-t@tie{}nopaper} to omit any paper size -information in the output. (If you just have a single page document, -you can use @samp{-E} to get pure EPSF output.) -@end itemize - -@item -title @var{string} -@opindex -title @var{str} -@cindex title, specifying -@cindex output title, specifying -@cindex document title, specifying -@findex %%Title -Use @var{string} as the title in the generated PostScript -(@code{%%Title}). If not specified, the default is the basename of the -input file; for example, running @code{dvips /foo/bar.dvi} will have a -@code{%%Title} of @samp{bar.dvi}. - -@item -T @var{hsize},@var{vsize} -@opindex -T @var{hsize},@var{vsize} -Set the paper size to (@var{hsize},@var{vsize}), a comma-separated -pair of dimensions such as @samp{.1in,-.3cm} (@pxref{@samp{papersize} -special}). It overrides any paper size special in the DVI file. Be -careful, as the paper size will stick to a predefined size if there is -one close enough. To disable this behavior, use @samp{-tunknown}. - -@item -u @var{psmapfile} -@opindex -u @var{psmapfile} -@cindex PostScript font alias file -@cindex resident fonts, different in different printers -Set @var{psmapfile} to be the file that dvips uses for looking up -PostScript font aliases. If @var{psmapfile} begins with a @samp{+} -character, then the rest of the name is used as the name of the map file, -and the map file is appended to the list of map files (instead of replacing -the list). In either case, if the name has no extension, then @samp{.map} -is added at the end. - -@item -U* -@opindex -U -@cindex Xerox 4045 -Disable a PostScript virtual memory-saving optimization that stores the -character metric information in the same string that is used to store -the bitmap information. This is only necessary when driving the Xerox -4045 PostScript interpreter, which has a bug that puts garbage on the -bottom of each character. Not recommended unless you must drive this -printer. - -@item -v -@opindex -v -Print the dvips version number and exit. - -@item -V* -@opindex -V -Download non-resident PostScript fonts as bitmaps. This requires use -@pindex mtpk -@pindex gsftopk -@pindex pstopk -of @code{mtpk} or @code{gsftopk} or @code{pstopk} or some combination -thereof to generate the required bitmap fonts; these programs are -supplied with Dvips. The bitmap must be put into @file{psfonts.map} as -the downloadable file for that font. This is useful only for those -fonts for which you do not have real outlines, being downloaded to -printers that have no resident fonts, i.e., very rarely. - - -@item -x @var{num} -@opindex -x @var{num} -@cindex magnification, overriding DVI -Set the magnification ratio to @math{@var{num}/1000}. Overrides -the magnification specified in the DVI file. Must be between 10 and -100000. It is recommended that you use standard magstep values (1095, -1200, 1440, 1728, 2074, 2488, 2986, and so on) to help reduce the total -number of PK files generated. @var{num} may be a real number, not an -integer, for increased precision. - -@item -X @var{num} -@opindex -X @var{num} -@cindex resolution -Set the horizontal resolution in dots per inch to @var{num}. - -@item -y @var{num} -@cindex magnification, vertical -Set the magnification ratio to @math{@var{num}/1000} times the -magnification specified in the DVI file. See -@samp{-x} above. - -@item -Y @var{num} -@opindex -Y @var{num} -Set the vertical resolution in dots per inch to @var{num.} -@cindex resolution - -@item -z* -@opindex -z @r{for recognizing hyperdvi} -@cindex hyperdvi extensions, enabling -@cindex distillation, and @samp{-z} -@cindex PDF files, option for -@findex html @r{specials, and @samp{-z}} -Pass @samp{html} hyperdvi specials through to the output for eventual -distillation into PDF. This is not enabled by default to avoid -including the header files unnecessarily, and use of temporary files in -creating the output. @xref{Hypertext}. - -@item -Z* -@opindex -Z @r{for compressing bitmap fonts} -@cindex compressing bitmap fonts -Compress bitmap fonts in the output file, thereby reducing the size of -what gets downloaded. Especially useful at high resolutions or when -very large fonts are used. May slow down printing, especially on early -68000-based PostScript printers. Generally recommend today, and can be -enabled in the configuration file (@pxref{Configuration file commands}). - -@end table - - -@node Environment variables -@section Environment variables - -@cindex environment variables - -Dvips looks for many environment variables, to define search paths and -other things. The path variables are read as needed, after all -configuration files are read, so they override values in the -configuration files. (Except for @code{TEXCONFIG}, which defines where -the configuration files themselves are found.) - -@xref{Path specifications,,, kpathsea, Kpathsea}, for details of -interpretation of path and other environment variables common to all -Kpathsea-using programs. Only the environment variables specific to -Dvips are mentioned here. - -@vtable @code -@item DVIPSDEBUG -@vindex KPATHSEA_DEBUG -Write the absolute path names of any configuration or map files to -standard output, for debugging. This isn't done by default because -these files are read even before the banner is printed. For -voluminous additional debugging, set the environment variable -@env{KPATHSEA_DEBUG} to @samp{-1} -(@pxref{Debugging,,,kpathsea,Kpathsea}). (If @env{KPATHSEA_DEBUG} is -set to any value, it automatically turns on @env{DVIPSDEBUG}.) - -@item DVIPSFONTS -Default path to search for all fonts. Overrides all the font path -config file options and other environment variables (@pxref{Supported -file formats,,, kpathsea, Kpathsea}). - -@item DVIPSHEADERS -Default path to search for PostScript header files. Overrides the @samp{H} -config file option (@pxref{Configuration file commands}). - -@item DVIPSMAKEPK -@pindex mktexpk@r{, changing name} -Overrides @samp{mktexpk} as the name of the program to invoke to -create missing PK fonts. You can change the arguments passed to the -@code{mktexpk} program with the @code{MAKETEXPK} environment -variable; @pxref{MakeTeX script arguments,,, kpathsea, Kpathsea}. - -@item DVIPSRC -Specifies the name of the startup file (@pxref{Configuration file -searching}) which is read after @file{config.ps} but before any -printer-specific configuration files. - -@item DVIPSSIZES -@cindex last-resort font scaling, with @code{DVIPSSIZES} -Last-resort sizes for scaling of unfound fonts. Overrides the @samp{R} -definition in config files (@pxref{Configuration file commands}). - -@item PRINTER -Determine the default printer configuration file. (Dvips itself does -not use @code{PRINTER} to determine the output destination in any way.) - -@item TEXCONFIG -@cindex configuration file path -Path to search for Dvips' @file{config.@var{printer}} configuration -files, including the base @file{config.ps}. Using this single -environment variable, you can override everything else. (The -printer-specific configuration files are called @file{@var{printer}.cfg} -on MS-DOS, but @file{config.ps} is called by that name on all -platforms.) - -@item TEXPICTS -Path to search for included graphics files. Overrides the @samp{S} -config file option (@pxref{Configuration file commands}). If not set, -@code{TEXINPUTS} is looked for. @xref{Supported file formats,,, -kpathsea, Kpathsea}. - -@end vtable - - -@node Config files -@section Dvips configuration files - -@cindex configuration files - -This section describes in detail the Dvips-specific @file{config.*} -device configuration files (called @file{*.cfg} on MS-DOS), which -override the @file{texmf.cnf} -configuration files generic to Kpathsea which Dvips also reads -(@pxref{Config files,,, kpathsea, Kpathsea}). - -For information about installing these files, including a prototype file -you can copy, @pxref{config.ps installation}. - -@menu -* Configuration file searching:: Where config.* files are searched for. -* Configuration file commands:: What can go in a config.* file. -@end menu - - -@node Configuration file searching -@subsection Configuration file searching - -@cindex configuration file searching -@cindex searching config files, order of - -The Dvips program loads many different configuration files, so that -parameters can be set globally across the system, on a per-device basis, -or individually by each user. - -@enumerate -@item -@flindex config.ps@r{, searched for} -Dvips first reads (if it exists) @file{config.ps}; it is searched for -along the path for Dvips configuration files, as described in -@ref{Supported file formats,,, kpathsea, Kpathsea}. - -@item -@flindex .dvipsrc@r{, searched for} -A user-specific startup file is loaded, so individual users can override -any options set in the global file. The environment variable -@code{DVIPSRC}, if defined, is used as the specification of the startup -file. If this variable is undefined, Dvips uses a platform-specific -default name. On Unix Dvips looks for the default startup file under -the name @file{$HOME/.dvipsrc}, which is in the user's home directory. -On MS-DOS and MS-Windows, where users generally don't have their private -directories, the startup file is called @file{dvips.ini} and it is -searched for along the path for Dvips configuration files (as described -in @ref{Supported file formats,,, kpathsea, Kpathsea}.); users are -expected to set this path as they see fit for their taste. - -@item -@opindex -P@var{printer}@r{, and config file searching} -The command line is read and parsed: if the @samp{-P@var{device}} option -is encountered, at that point @file{config.@var{device}} is loaded. -Thus, the printer configuration file can override anything in the -site-wide or user configuration file, and it can also override options -in the command line up to the point that the @samp{-P} option was -encountered. (On MS-DOS, the printer configuration files are called -@file{@var{device}.cfg}, since DOS doesn't allow more than 3 characters -after the dot in filenames.) - -@item -@vindex PRINTER@r{, and config file searching} -If no @samp{-P} option was specified, and also the @samp{-o} and -@samp{-f} command line options were not used, Dvips checks the -environment variable @code{PRINTER}. If it exists, then -@file{config.@var{$PRINTER}} (@file{@var{$PRINTER}.cfg} on MS-DOS) is -loaded (if it exists). - -@end enumerate - -Because the @file{.dvipsrc} file is read before the printer-specific -configuration files, individual users cannot override settings in the -latter. On the other hand, the @code{TEXCONFIG} path can be set to -anything, so the users can always define their own printer-specific -configuration files to be found before the system's. - -A few command-line options are treated specially, in that they are not -overridden by configuration files: - -@table @samp -@item -D -As well as setting the resolution, this unsets the mode, if the mode was -previously set from a configuration file. If @file{config.$PRINTER} is -read, however, any @samp{D} or @samp{M} lines from there will take -effect. - -@item -mode -This overrides any mode setting (@samp{M} line) in configuration files. -@samp{-mode} does not affect the resolution. - -@item -o -This overrides any output setting (@samp{o} line) in configuration files. - -@end table - -The purpose of these special cases is to (1) minimize the chance of -having a mismatched mode and resolution (which @samp{mktexpk} cannot -resolve), and (2) let command-line options override config files where -possible. - - -@node Configuration file commands -@subsection Configuration file commands - -@cindex configuration file options -@cindex Dvips configuration file options - -Most of the configuration file commands are similar to corresponding -command line options, but there are a few exceptions. When they are the -same, we omit the description here. - -As with command line options, many may be turned off by suffixing the -letter with a zero (@samp{0}). - -@cindex comments, in configuration files -@cindex continuation lines, not supported -Within a configuration file, empty lines, and lines starting with a -space, asterisk, equal sign, percent sign, or pound sign are ignored. -There is no provision for continuation lines. - -@table @samp -@item @@ @var{name hsize vsize} -@opindex @@ @r{config command (define paper sizes)} -Define paper sizes. @xref{Config file paper sizes}. - -@item a* -@opindex a @r{config command (conserve memory)} -Memory conservation. Same as @samp{-a}, @pxref{Option details}. - -@item b @var{#copies} -@opindex b @r{config command (#copies)} -Multiple copies. Same as @samp{-b}, @pxref{Option details}. - -@item bitmapfontenc @var{option} -@opindex bitmapfontenc @r{config command (bitmap font encoding)} -Turns bitmap font encoding to @samp{off}, @samp{on} (no warnings -for missing bitmap font encodings), or @samp{strict} (with warnings -for missing bitmap font encodings). - -@item c @var{filename} -@opindex c @r{config command (include another config file)} -Include @var{filename} as an additional configuration file, read -immediately. - -@item D @var{dpi} -@opindex D @r{config command (dpi)} -Output resolution. Same as @samp{-D}, @pxref{Option details}. - -@item e @var{num} -@opindex e @r{config command (maxdrift)} -Max drift. Same as @samp{-e}, @pxref{Option details}. - -@item E @var{command} -@opindex E @r{config command (shell escape)} -@findex system @r{in config file} -@cindex datestamp, in output -@cindex shell escape, in config file -Executes the command listed with @code{system}(3); can be used to get -the current date into a header file for inclusion, for instance. -Possibly dangerous; this may be disabled, in which case a warning will -be printed if the option is used (and warnings are not suppressed). - -@item f* -@itemx F -@opindex f @r{config command (filter)} -@opindex F @r{config command (filter)} -Run as a filter. Same as @samp{-f}, @pxref{Option details}. - -@item G* -@opindex G @r{config command (character shifting)} -Shift low-numbered characters; obsolete. Same as @samp{-G}, -@pxref{Option details}. - -@item h @var{header} -@opindex h @r{config command (download additional header)} -Prepend @var{header} to output. Same as @samp{h-}, @pxref{Option details}. - -@item H @var{path} -@opindex H @r{config command (PostScript header path)} -@cindex header path, defining -@vindex DVIPSHEADERS@r{, overrides} H -Use @var{path} to search for PostScript header files. The environment -variable @code{DVIPSHEADERS} overrides this. - -@item i @var{n} -@opindex i @r{config command (pages/section)} -Make multiple output files. Same as @samp{-i -S @var{n}}, @pxref{Option -details}. - -@item j* -@opindex j @r{config command (partial font downloading)} -Partially download Type 1 fonts. Same as @samp{-j}, @pxref{Option details}. - -@item K* -@opindex K @r{config command (comment removal)} -Remove comments from included PostScript files. Same as @samp{-K}, -@pxref{Option details}. - -@item L* -@opindex L @r{config command (last paper size wins)} -If zero, the first paper size specified is effective, else the last. -Same as @samp{-L}, @pxref{Option details}. - -@item m @var{num} -@opindex m @r{config command (available memory)} -@cindex memory available -@cindex printer memory -Declare @var{num} as the memory available for fonts and strings in the -printer. The compile-time default is 180000, but this is typically -overridden by @file{config.ps} or other configuration files. 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: - -@example -%! Hey, we're PostScript -/Times-Roman findfont 30 scalefont setfont 144 432 moveto -vmstatus exch sub 40 string cvs show pop showpage -@end example - -@noindent -The number printed by this file is the total memory free; it is usually -best to tell Dvips that the printer has slightly less memory, because -many programs download permanent macros that can reduce the memory in -the printer. 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; for example, the NeXT computer -and Ghostscript. In these cases, a value of, say, 10 million is -likely fine. - -To go all out: If @var{num} is zero or negative, Dvips sets the -available memory to a very large number (the maximum integer value in -C), the idea being that output is not to a printer and thus no -splitting of the output is desirable. The Dvips config file -@file{config.maxmem} is provided to do this conveniently, namely with -@samp{dvips -Pmaxmem}. - -@item M @var{mode} -@opindex M @r{config command (mf mode)} -Metafont mode. Same as @samp{-mode}, @pxref{Option details}. - -@item N* -@opindex N @r{ config command (disable EPS)} -Disable structured comments. Beware: This also turns off displaying -page numbers or changing to specific pagenumbers in PostScript viewers. -Same as @samp{-N}, @pxref{Option details}. - -@item o @var{name} -@opindex o @r{config command (output destination)} -@cindex output file, setting -Send output to @var{name}. Same as @samp{-o}, @pxref{Option details}. -In the file @file{config.foo}, a setting like this is probably -appropriate: -@example -o |lpr -Pfoo -@end example -The MS-DOS version will emulate spooling to @code{lpr} by printing to -the local printer device @file{PRN} if it doesn't find an executable -program by that name in the current directory or along the @code{PATH}. - -@item O @var{xoff},@var{yoff} -@opindex O @r{config command (page offsets)} -Origin offset. Same as @samp{-O}, @pxref{Option details}. - -@item p @r{[+]}@var{name} -@opindex p @r{config command (font aliases)} -@cindex PostScript font alias file -@cindex resident fonts, different in different printers -@kindex +@var{psmapfile} -Examine @var{name} for PostScript font aliases. Default is -@file{psfonts.map}. This option allows you to specify different resident -fonts that different printers may have. If @var{name} starts with a -@samp{+} 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. This can be used for font families. - -@item P @var{path} -@opindex P @r{config command (PK path)} -@vindex PKFONTS@r{, overrides} P -@vindex TEXPKS@r{, overrides} P -@vindex GLYPHFONTS@r{, overrides} P -@vindex TEXFONTS@r{, overrides} P -Use @var{path} to search for bitmap PK font files is @var{path}. The -@code{PKFONTS}, @code{TEXPKS}, @code{GLYPHFONTS}, and @code{TEXFONTS} -environment variables override this. @xref{Supported file formats,,, -kpathsea, Kpathsea}. - -@item q* -@itemx Q -@opindex q @r{config command (quiet)} -@opindex Q @r{config command (quiet)} -Run quietly. Same as @samp{-q}, @pxref{Option details}. - -@item r* -@opindex r @r{config command (page reversal)} -Page reversal. Same as @samp{-r}, @pxref{Option details}. - -@item R @var{num1 num2 @dots{}} -@opindex R @r{config command (fallback resolution)} -@cindex fallback resolutions -@cindex default resolutions -@cindex last-resort scaling, with @code{R} -Define the list of default resolutions for PK fonts. If a font size -actually used in a document is not available and cannot be created, -Dvips will scale the font found at the closest of these resolutions to -the requested size, using PostScript scaling. The resulting output may -be ugly, and thus a warning is issued. To turn this last-resort scaling -off, use a line with just the @samp{R} and no numbers. - -The given numbers must be sorted in increasing order; any number smaller -than the preceding one is ignored. This is because it is better to -scale a font up than down; scaling down can obliterate small features in -the character shape. - -@vindex DVIPSSIZES@r{, overrides} R -@vindex TEXSIZES@r{, overrides} R -The environment and config file values @samp{DVIPSSIZES} or -@samp{TEXSIZES} override this configuration file setting. - -@vindex default_texsizes @r{Make variable} -If no @samp{R} settings or environment variables are specified, a list -compiled in during installation is used. This default list is defined by -the Makefile variable @samp{default_texsizes}, defined in the file -@file{make/paths.make}. - -@item s* -@opindex s @r{config command (global save/restore)} -Output global save/restore. Same as @samp{-s}, @pxref{Option details}. - -@item S @var{path} -@opindex S @r{config command (pict path)} -@vindex TEXPICTS@r{, overrides} S -@vindex TEXINPUTS@r{, overrides} S -Use @var{path} to search for special illustrations (Encapsulated -PostScript files or psfiles). The @code{TEXPICTS} and then -@code{TEXINPUTS} environment variables override this. - -@item T @var{path} -@opindex T @r{config command (TFM path)} -@vindex TFMFONTS@r{, overrides} T -@vindex TEXFONTS@r{, overrides} T -Use @var{path} to search for TFM files. The @code{TFMFONTS} and then -@code{TEXFONTS} environment variables overrides this. This path is used -for resident fonts and fonts that can't otherwise be found. - -@item U* -@opindex U @r{config command (Xerox 4045)} -Work around bug in Xerox 4045 printer. Same as @samp{-U}, @pxref{Option -details}. - -@item V @var{path} -@opindex V @r{config command (vf path)} -@cindex virtual font path -@cindex device dependency, and virtual fonts -Use @var{path} to search for virtual font files. This may be -device-dependent if you use virtual fonts to simulate actual fonts on -different devices. - -@item W @r{[@var{string}]} -@opindex W @r{config command (emit warning)} -@cindex warning messages, defining -If @var{string} is supplied, write it to standard error after reading -all the configuration files; with no @var{string}, cancel any previous -@samp{W} message. This is useful in the default configuration file to -remind users to specify a printer, for instance, or to notify users -about special characteristics of a particular printer. - -@item X @var{num} -@opindex X @r{config command (horizontal resolution)} -Horizontal resolution. Same as @samp{-X} (@pxref{Option details}). - -@item Y @var{num} -@opindex Y @r{config command (vertical resolution)} -Vertical resolution. Same as @samp{-Y} (@pxref{Option details}). - -@item Z* -@opindex Z @r{config command (compress fonts)} -Compress bitmap fonts. Same as @samp{-Z} (@pxref{Option details}). - -@item z* -@opindex z @r{config command (secure mode)} -Disables execution of system commands, like @samp{-R} -(@pxref{Option details}). If @samp{-R} is specified -on the command line, that takes precedence. - -@end table - - -@node Paper size and landscape -@chapter Paper size and landscape orientation - -@cindex paper size, general - -Most @TeX{} documents at a particular site are designed to use the -local standard paper size (letter size in the United States, A4 -elsewhere). The Dvips program can be customized either sitewide or -for a particular printer. - -@cindex landscape orientation, defined -@cindex portrait orientation, defined -On the other hand, plenty of documents are designed for other paper -sizes. For instance, you may want to design a document that has the -long edge of the paper horizontal. This can be useful when -typesetting booklets, brochures, complex tables, or many other -documents. This type of paper orientation is called @dfn{landscape} -orientation (the default orientation is called @dfn{portrait}). -Alternatively, a document might be designed for ledger or A3 paper. - -Since the intended paper size in these cases is a document design -decision, not a printing decision, such information should be given in -the @TeX{} file and not on the Dvips command line. For this reason, -Dvips supports a @samp{papersize} special. It is hoped that this -special will become standard over time for @TeX{} previewers and other -printer drivers. - -Some @LaTeX{} packages, e.g., @samp{hyperref.sty}, write a -@samp{papersize} special into the DVI file. In this case, you need -not and should not attempt to override it manually. - -@menu -* @samp{papersize} special:: Specifying the paper size in TeX. -* Config file paper sizes:: Specifying printer- and site-specific sizes. -* Paper trays:: Changing paper trays automatically. -@end menu - - -@node @samp{papersize} special -@section @samp{papersize} special - -@findex papersize @r{special} - -The format of the @samp{papersize} special is - -@example -\special@{papersize=@var{width},@var{height}@} -@end example - -@noindent -@var{width} is the horizontal size of the page, and @var{height} 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). - -@findex landscape@r{, as @code{\special}} -For a US letter size landscape document, the @samp{papersize} would be: -@example -\special@{papersize=11in,8.5in@} -@end example - -@noindent -An alternate specification of @code{landscape}: -@example -\special@{landscape@} -@end example - -@noindent -This is supported for backward compatibility, but it is hoped that -reventually the @samp{papersize} comment will dominate. - -Of course, such a @code{\special} only informs Dvips of the desired -paper size; you must also adjust @code{\hsize} and @code{\vsize} in your -@TeX{} document typeset to those dimensions. - -@findex unknown@r{, paper format for @samp{-t}} -When using the @samp{papersize} special, you generally should not also -specify @code{-t} on the command line (@pxref{Option details}). The -exception is when using a nonstandard paper size that isn't -predefined; in this case, use @code{-t@tie{}unknown}. - -The @samp{papersize} special must occur somewhere on the first page of -the document. Some packages, notably @samp{hyperref}, insert this special. - -By default, if a DVI file contains multiple @samp{papersize} specials, -the last one wins; this is also the behavior of the @code{dvipdfmx} -driver. If the @code{-L0} command line option or @code{L0} config -file command is specified, the first special wins---this was the -behavior of Dvips prior to the 2017 release. - - -@node Config file paper sizes -@section Configuration file paper size command - -@cindex paper size configuration file command -@cindex configuration file paper size command - -The @samp{@@} command in a configuration file sets the paper size -defaults and options. The first @samp{@@} command defines the default -paper size. It has three possible parameters: - -@example -@@ @r{[}@var{name} @r{[}@var{hsize} @var{vsize}@r{]]} -@end example - -If @samp{@@} is specified on a line by itself, with no parameters, it -instructs Dvips to discard all previous paper size information (possibly -from another configuration file). - -If three parameters are given, with the first parameter being a name and -the second and third being a dimension (as in @samp{8.5in} or -@samp{3.2cc}, just like in the @samp{papersize} special), then the -option is interpreted as starting a new paper size description, where -@var{name} is the name and @var{hsize} and @var{vsize} define the -horizontal and vertical size of the sheet of paper, respectively. For -example: - -@example -@@ letterSize 8.5in 11in -@end example - -If both @var{hsize} and @var{vsize} are zero (you must still specify -units!)@: then any page size will match. If the @samp{@@} character is -immediately followed by a @samp{+} sign, then the remainder of the line -(after skipping any leading blanks) is treated as PostScript code to -send to the printer, presumably to select that particular paper size: - -@example -@@ letter 8.5in 11in -@@+ %%BeginPaperSize: Letter -@@+ letter -@@+ %%EndPaperSize -@end example - -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 example: - -@example -@@ legal 8.5in 14in -@@+ ! %%DocumentPaperSizes: Legal -@@+ %%BeginPaperSize: Legal -@@+ legal -@@+ %%EndPaperSize -@end example - -When Dvips has a paper format name given on the command line, it looks -for a match by the @var{name}; when it has a @samp{papersize} special, -it looks for a match by dimensions. The best match found (from the -paper size information in the configuration file) is used. The -dimensions must match within 5bp. - -If nothing matches, a warning is printed and the first paper size with -zero dimensions is used; this should be the @code{unknown} paper size -definition mentioned below, resulting in the actual dimensions being -used. - -Landscape mode for all paper sizes is automatically supported. - -If your printer has a command to set a special paper size, then give -dimensions of @samp{0in 0in}; the PostScript code that sets the paper -size can refer to the dimensions the user requested as @samp{hsize} -and @samp{vsize}; these will be macros defined in the PostScript that -return the requested size in default PostScript units. Also, some -printers want @samp{BeginPaperSize} comments and paper size setting -commands; others (such as the NeXT) want @samp{PaperSize} comments and -they will handle setting the paper size. So paper size entries should -typically specify both. - -@findex unknown@r{, paper format for @samp{-t}} -When using a paper size that is not already defined in -@file{config.ps}, you probably want to say @samp{-t@tie{}unknown} on -the command line; the @code{unknown} paper size definition in -@file{config.ps} has the requisite PostScript incantation to set the -PostScript page size, as just described. - -@findex nopaper@r{, paper format for @samp{-t}} -If you want no paper size information in the output at all, use -@samp{-t@tie{}nopaper}. This is useful with multi-page output that -will be processed further. If you just have a single page document, -you can use @samp{-E} to get pure EPSF output. - -@flindex mkdvipspapers -The Perl 5 script @file{contrib/configs/mkdvipspapers} in the -distribution directory may help in determining appropriate paper size -definitions. - -@flindex config.ps @r{paper sizes} -@findex letter @r{paper size} -@findex a4 @r{paper size} -Notwithstanding the above, the default @code{letter} and @code{a4} -paper size definitions in @file{config.ps} execute the -@code{setpagedevice} operator if it exists (it was defined in -PostScript Level@tie{}2), or the @samp{letter} or @samp{a4} operator -if they exist (they are nonstandard and thus perhaps cause failures on -certain (unknown) printers). Not executing any page size definition -at all confuses PostScript conversion programs such as -@command{ps2pdf}, so we want to execute one if we can. - -@findex letterSize @r{paper size} -@findex A4size @r{paper size} -The @code{letterSize} and @code{A4Size} paper size definitions are now -synonyms for @code{letter} and @code{a4}. - - -@node Paper trays -@section Paper trays - -@cindex paper trays -@cindex dual paper trays -@cindex multiple paper trays -@cindex HP4Si printer and paper trays - -@findex bop-hook -Some printers, such as the Hewlett-Packard HP4si, have multiple paper -trays. You can set up Dvips to take advantage of this using the -@code{bop-hook} PostScript variable (@pxref{PostScript hooks}). - -@cindex letterhead tray -For example, suppose you have an alternate tray stocked with letterhead -paper; the usual tray has the usual paper. You have a document where -you want the first page printed on letterhead, and the remaining pages -on the usual paper. You can create a header file, say -@file{firstletterhead.PS}, with the following (PostScript) code -(@code{bop-hook} is passed the current physical page number, which -starts at zero): - -@example -/bop-hook @{ dup 0 eq @{ @var{alternatetray} @} @{ @var{normaltray} @} ifelse @} def -@end example - -@noindent where @var{alternatetray} and @var{normaltray} are the appropriate -commands to select the paper trays. On the 4SI, @var{alternatetray} is -@samp{statusdict begin 1 setpapertray end} and @var{normaltray} is -@samp{statusdict begin 0 setpapertray end}. - -Then, include the file with either -@itemize @bullet -@item the @samp{-h} command-line option (@pxref{Option details}); or - -@item the @samp{h} config file option (@pxref{Configuration file -commands}); or - -@item @samp{\special@{header=@var{file}@}} in your @TeX{} document -(@pxref{Including headers from TeX,, Including headers from @TeX{}}). - -@end itemize - - -@node Interaction with PostScript -@chapter Interaction with PostScript - -@cindex interaction with PostScript -@cindex PostScript interaction - -Dvips supports inclusion of PostScript figure files (e.g., Encapsulated -PostScript), downloading other header files (e.g., fonts), including -literal PostScript code, and hypertext. - -@menu -* PostScript figures:: Including an Encapsulated PostScript figure. -* Header files:: Downloading extra definitions. -* Literal PS:: Writing literal PostScript code. -* Hypertext:: Producing HyperPostScript to make PDF. -@end menu - - -@node PostScript figures -@section PostScript figures - -Scaling and including PostScript graphics is a breeze---if the PostScript -file is correctly formed. Even if it is not, however, the file can usually -be accommodated with just a little more work. - -@menu -* Bounding box:: The %%BoundingBox EPS comment. -* \includegraphics:: The LaTeX \includegraphics macro. -* EPSF macros:: Including the file in TeX. -* psfile special:: The basic special. -* Dynamic creation of graphics:: Handling compressed or generated figures. -* Fonts in figures:: The %*Font comment. -@end menu - - -@node Bounding box -@subsection The bounding box comment - -@cindex bounding box, comment for - -The most important feature of a good PostScript file from the standpoint -of including it in another document is an accurate bounding box comment. -Every well-formed PostScript file has a comment describing where on the -page the graphic is located, and how big that graphic is. - -@cindex big points -@cindex PostScript units -@cindex bounding box, defined -This information is given as the lower left and upper right corners of -the box just enclosing the graphic, and is thus referred to as the -@dfn{bounding box}. These coordinates are given in the default -PostScript units (there are precisely 72 PostScript units to the inch, -like @TeX{} big points) with respect to the lower left corner of the -sheet of paper. - -@findex %%BoundingBox -To see if a PostScript file has a bounding box comment, just look at the -first few lines of the file. PostScript files are standard ASCII, so -you can use any text editor to do this. If within the first few dozen -lines there is a line like - -@example -%%BoundingBox: 25 50 400 300 -@end example - -@noindent -(with any reasonable 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 - -@findex atend@r{, bounding box specification} -@findex (atend)@r{, bounding box specification} -@example -%%BoundingBox: (atend) -@end example - -@noindent -the file is still probably Encapsulated PostScript, but the bounding box -is given at the end of the file. Dvips needs it at the beginning. You -can move it with that same text editor, or a simple script. (The -bounding box is given in this way when the program that generated the -PostScript couldn't know the size in advance, or was too lazy to compute -it.) - -@pindex bbfig -@cindex bounding box, determining -If the document lacks a @samp{%%BoundingBox:} altogether, you can -determine one in a couple of ways. One is to use the @samp{bbfig} -program distributed with Dvips in the @file{contrib} directory. This can -usually find the correct bounding box automatically; it works best with -Ghostscript. - -@vindex 612 792 @r{bounding box size} -If the comment looks like this: -@example -%%BoundingBox: 0 0 612 792 -@end example - -@noindent -the graphic claims to take up an entire sheet of paper. This is -usually a symptom of a bug in the program that generated it. - -The other is to do it yourself: print the file. Now, take a ruler, and -make the following measurements (in PostScript units, so measure in -inches and multiply by 72): From the left edge of the paper to the -leftmost mark on the paper is @var{llx}, the first number. From the -bottom edge of the paper to the bottommost mark on the paper is -@var{lly}, the second number. From the left edge of the paper to the -rightmost mark on the paper is @var{urx}, the third number. The fourth -and final number, @var{ury}, is the distance from the bottom of the page -to the uppermost mark on the paper. - -Once you have the numbers, 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 @samp{%!}; if it is not, the file -probably isn't PostScript.) - -@example -%%BoundingBox: @var{llx} @var{lly} @var{urx} @var{ury} -@end example - -@noindent -Or, if you don't want to modify the file, you can simply write these -numbers down in a convenient place and give them in your @TeX{} document -when you import the graphic, as described in the next section. - -If the document does not have such a bounding box, or if the bounding -box is given at the end of the document, or the bounding box is wrong, -please complain to the authors of the software package that generated -the file. - - -@node \includegraphics -@subsection The \includegraphics macro for @LaTeX{} - -@cindex \includegraphics @LaTeX{} macro -@cindex macros for epsf inclusion - -Once the figure file has a bounding box comment (see the previous -section) you are ready to import the graphic into a La@TeX{} -document. For @LaTeX{}2e, you can use the epsf, graphics or graphicx -packages, but the last is recommended---it has the most flexible -syntax, and is briefly described here. Further information can be -found in @file{grfguide} or @file{epslatex}, which should be included -in your @LaTeX{} distribution in DVI, PDF, or other formats. (If you -are still using La@TeX{} 2.09, use epsf.sty). - -Just put the following command into your preamble: - -@example -\usepackage[dvips]@{graphicx@} -@end example - -Depending on your system, a suitable driver setup may already be -present, so that @LaTeX{} automatically produces DVI files suitable for -Dvips. In this case you can leave out the @samp{[dvips]} parameter. - -Now, at the point you want to include a file @file{foo.eps}, enter a -line such as: - -@example -\includegraphics@{foo.eps@} -@end example - -However, it is usually best to omit the file extension and only use - -@example -\includegraphics@{foo@} -@end example - -@noindent because then you can process the same LaTeX file with -different @TeX{} engines or DVI converters if you also provide -suitable graphics files for them, e.g., @file{foo.pdf} or -@file{foo.png}. - -@cindex bounding box, supplying to @TeX{} -The \includegraphics command has many options, specified in -@samp{key=value} syntax, to allow you to resize, rotate or trim the -included graphic---see @file{grfguide} or @file{epslatex}. If your -file does not have a bounding box comment, you can supply the numbers -as determined in the previous section, in the same order they would -have been in a normal bounding box comment: - -@example -\includegraphics[bb=100 100 500 500]@{foo.ps@} -@end example - -@noindent -Now, save your changes and run @LaTeX{} and Dvips; the output should -have your graphic positioned at precisely the point you indicated, -occupying the proper amount of space. - -PostScript graphics have their origin in the lower left -corner. Therefore, in @TeX{}, a graphic will occupy a box that extends -far above the line where it is put in, but has depth zero below it. -Combining @samp{\includegraphics} with @samp{\parbox} commands or -minipages can sometimes be confusing when this is not taken into -account. - - -@node EPSF macros -@subsection Using the EPSF macros - -@cindex EPSF macros -@cindex macros for epsf inclusion - -If you are using @LaTeX{}2e, use the @samp{graphics} or @samp{graphicx} -package. @xref{\includegraphics}. - -If you are using plain @TeX{} or La@TeX{} 2.09, you need @file{epsf.tex} -(for plain @TeX{}) and @file{epsf.sty} (for La@TeX{}). For plain -@TeX{}, add a line like this near the top of your input file: - -@flindex epsf.tex -@example -\input epsf -@end example - -@noindent -@flindex epsf.sty -If you are using @LaTeX{} 2.09, add the @samp{epsf} style option, as in: - -@example -\documentstyle[12pt,epsf]@{article@} -@end example - -@noindent -In any case, the above only needs to be done once, no matter how many -figures you plan to include. - -Now, at the point you want to include a file, enter a line such as: - -@example -\epsffile@{foo.eps@} -@end example - -@findex \leavevmode -@cindex bounding box, supplying to @TeX{} -If you are using @LaTeX{}, you may need to add @code{\leavevmode} -immediately before the @code{\epsffile} command to get certain -environments to work correctly. If your file does not have a bounding -box comment, you can supply the numbers as determined in the previous -section, in the same order they would have been in a normal bounding box -comment: - -@example -\epsffile[100 100 500 500]@{foo.ps@} -@end example - -@noindent -Now, save your changes and run @TeX{} and Dvips; the output should have -your graphic positioned at precisely the point you indicated, occupying -the proper amount of space. - -@findex \epsffile @r{macro} -@cindex figures, natural size -The @code{\epsffile} macro typesets the figure as a @TeX{} @code{\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 its natural height. By -default, the graphic will be scaled by any DVI magnification in effect, -just as is everything else in your document. See the next section for -more information on scaling. - -@vindex \epsfverbosetrue -@cindex verbose EPSF processing -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: - -@example -\epsfverbosetrue -@end example - -@menu -* EPSF scaling:: -* EPSF clipping:: -@end menu - - -@node EPSF scaling -@subsubsection EPSF scaling - -@cindex scaling of figures -@cindex figures, scaling - -Usually, you will want to scale an EPSF figure to some size appropriate -for your document, since its natural size is determined by the creator -of the EPS file. - -The best way to do this is to assign the desired size to the @TeX{} -@code{\epsfxsize} or @code{\epsfysize} variables, whichever is more -convenient for you. That is, put - -@vindex \epsfxsize -@example -\epsfxsize=@var{dimen} -@end example - -@noindent -right before the call to @code{\epsffile}. Then the width of the @TeX{} -box will be @var{dimen} and its height will be scaled proportionately. -Similarly, you can set the vertical size with - -@vindex \epsfysize -@example -\epsfysize=@var{dimen} -@end example - -@noindent -in which case the height will be set and the width scaled -proportionally. - -If you set both, both will be honored, but the aspect ratio of the -included graphic may necessarily be distorted, i.e., its contents -stretched in one direction or the other. - -@findex \epsfsize -You can resize graphics in a more general way by redefining the -@code{\epsfsize} macro. @code{\epsffile} calls this with two -parameters: the natural horizontal and vertical sizes of the PostScript -graphic. @code{\epsfsize} must expand to the desired horizontal size, -that is, the width of the @code{\vbox}. Schematically: - -@example -\def\epsfsize#1#2@{@var{body}@} -@end example - -Some useful definitions of @var{body}: - -@table @samp -@item \epsfxsize -This definition (the default) enables the default features listed above, -by setting @code{\epsfxsize} to the same value it had before the macro -was called. - -@item #1 -Force the natural size by returning the first parameter (the original -width). - -@item 0pt -A special case, equivalent to @samp{#1}. - -@item 0.5#1 -Scale to half the natural size. - -@item \hsize -Scale to the current @code{\hsize}. (In @LaTeX{}, use @code{\textwidth} -instead of @code{\hsize}.) - -@item \ifnum#1>\hsize\hsize\else#1\fi -If the natural width is greater than the current @code{\hsize}, scale to -@code{\hsize}, otherwise use the natural width. - -@end table - -@cindex DVI magnification -@cindex magnification, DVI -@vindex \magnification -For compatibility with other PostScript drivers, it is possible to turn -off the default scaling of included figures by the DVI magnification -with the following @TeX{} command: - -@vindex /magscale -@example -\special@{! /magscale false def@} -@end example - -@noindent -Use of this command is not recommended because it will make the -@code{\epsffile} graphics the ``wrong'' size if global magnification is -being used, 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. - -@findex bop-hook -DVI magnification is not applied to any output from code you write in -@samp{bop-hook} or its ilk (@pxref{PostScript hooks}), - - -@node EPSF clipping -@subsubsection EPSF clipping - -@cindex clipping of EPSF -@cindex bounding box, inaccurate -@cindex text in figures, chopped off -@cindex lines in figures, wrong width - -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 - -@example -\epsfclipon -@end example - -@noindent -and to turn clipping back off, use - -@example -\epsfclipoff -@end example - - -@node psfile special -@subsection @samp{psfile} special - -@findex psfile @r{special} - -The basic special for file inclusion is as follows: - -@example -\special@{psfile=@var{filename}.ps @r{[}@var{key}=@var{value}@r{]} @dots{} @} -@end example - -@noindent -This downloads the PostScript file @file{@var{filename}.ps} such that -the current point will be the origin of the PostScript coordinate -system. The optional @var{key}@t{=}@var{value} assignments allow you to -specify transformations on the PostScript. - -The possible @var{key}s are: - -@table @samp -@item hoffset -@opindex hoffset @r{(@samp{psfile} special option)} -The horizontal offset (default 0). - -@item voffset -@opindex voffset @r{(@samp{psfile} special option)} -The vertical offset (default 0). - -@item hsize -@opindex hsize @r{(@samp{psfile} special option)} -The horizontal clipping size (default 612). - -@item vsize -@opindex vsize @r{(@samp{psfile} special option)} -The vertical clipping size (default 792). - -@item hscale -@opindex hscale @r{(@samp{psfile} special option)} -The horizontal scaling factor, as a percentage (default 100). - -@item vscale -@opindex vscale @r{(@samp{psfile} special option)} -The vertical scaling factor, as a percentage (default 100). - -@item angle -@opindex angle @r{(@samp{psfile} special option)} -The rotation, in degrees (default 0). - -@item clip -@opindex clip @r{(@samp{psfile} special option)} -Enable clipping to the bounding box (default disabled). - -@item llx, lly, urx, ury -@opindex llx @r{(@samp{psfile} special option)} -@opindex lly @r{(@samp{psfile} special option)} -@opindex urx @r{(@samp{psfile} special option)} -@opindex ury @r{(@samp{psfile} special option)} -Bounding box of the included image, just as in a @code{%%BoundingBox} -comment. Values are in big points, and may be fractional. - -@item rhi, rwi -@opindex rhi @r{(@samp{psfile} special option)} -@opindex rwi @r{(@samp{psfile} special option)} -Desired width and height of the resulting figure in the output, in -tenths of big points (720 to the inch); may be fractional. - -If both @code{rwi} and @code{rhi} are nonzero, the picture is scaled, -possibly losing aspect ratio. If only one of @code{rwi} and -@code{rhi} is nonzero, the picture is scaled, preserving aspect ratio. - -@end table - -The offsets and sizes are given in PostScript units (big points). -Thus, for example: - -@example -\special@{psfile=foo.ps hoffset=72 hscale=90 vscale=90@} -@end example - -@noindent -will shift the graphics produced by file @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 @samp{hscale} and @samp{vscale} are given in. This can be -done by redefining @samp{@@scaleunit} -@vindex scaleunit -in @samp{SDict} -@vindex SDict -by a @TeX{} command such as - -@example -\special@{! /@@scaleunit 1 def@} -@end example - -@noindent -The @samp{@@scaleunit} variable, which is by default 100, is what -@samp{hscale} and @samp{vscale} are divided by to yield an absolute -scale factor. - - -@node Dynamic creation of graphics -@subsection Dynamic creation of PostScript graphics files - -@cindex dynamic creation of graphics -@cindex compressed PostScript -@cindex uncompressing PostScript - -PostScript is an excellent page description language---but it does tend -to be rather verbose. Compressing PostScript graphics files can reduce -them by factor of five or more. For this reason, if the name of an -included PostScript file ends with @file{.Z} or @file{.gz}, Dvips -automatically runs @samp{gzip -d}. For example: - -@example -\epsffile[72 72 540 720]@{foo.ps.gz@} -@end example - -@noindent -Since the results of such a command are not accessible to @TeX{}, if you -use this facility with the @file{epsf} macros, you need to supply the -bounding box parameter yourself, as shown. - -More generally, if the filename parameter to one of the graphics -inclusion techniques starts with a left quote (@samp{`}), the parameter -is instead interpreted as a command to execute that will send the actual -file to standard output. For example: - -@example -\special@{psfile="`gnuplot foo"@} -@end example - -@noindent -@flindex gnuplot -to include the file @file{foo}. Of course, the command to be executed -can be anything, including using a file conversion utility such as -@file{tek2ps} or whatever is appropriate. This feature can be disabled -with the @samp{-R} command-line option or @samp{R} configuration option. - - -@node Fonts in figures -@subsection Fonts in figures - -@cindex figures and fonts -@cindex fonts, in PostScript figures -@findex %*Font - -You can use any font available to @TeX{} and Dvips within a graphics -file by putting a @code{%*Font:} line in the leading commentary of the -file. Schematically, this looks like: - -@example -%*Font: @var{tfmname} @var{scaledbp} @var{designbp} @var{hex-start}:@var{hex-bitstring} -@end example - -Here is the meaning of each of these elements: - -@table @var -@item tfmname -The @TeX{} TFM filename, e.g., @file{cmr10}. You can give the same -@var{tfmname} on more than one @samp{%*Font} line; this is useful when -the number of characters from the font used needs a longer -@var{hex-bitstring} (see item below) than conveniently fits on one line. - -@item scaledbp -The size at which you are using the font, in PostScript points (@TeX{} -big points). 72@dmn{bp} = 72.27@dmn{pt} = 1@dmn{in}. - -@item designbp -The designsize of the font, again in PostScript points. This should -match the value in the TFM file @var{tfmname}. Thus, for @file{cmr10}, -it should be @samp{9.96265}. - -@item hex-start -The character code of the first character used from the font, specified -as two ASCII hexadecimal characters, e.g., @samp{4b} or @samp{4B} for -@samp{K}. - -@item hex-bitstring -An arbitrary number of ASCII hexadecimal digits specifying which -characters following (and including) @var{hex-start} are used. This is -treated as a bitmap. For example, if your figure used the single letter -@samp{K}, you would use @samp{4b:8} for @var{hex-start} and -@var{hex-bitstring}. If it used @samp{KLMNP}, you would use -@samp{4b:f4}. - -@end table - -MetaPost's output figures contain lines like this for bitmap fonts used -in a MetaPost label (@pxref{MetaPost,,, web2c, Web2c}). - - -@node Header files -@section PostScript header files - -@cindex header files, defined -@cindex PostScript header files - -@dfn{Header files} are bits of PostScript included in the output file; -generally they provide support for special features, rather than -producing any printed output themselves. You can explicitly request -downloading header files if necessary for some figure, or to achieve -some special effect. - -@vindex psheaderdir -@flindex .pro @r{prologue files} -@flindex .lpro @r{long prologue files} -Dvips includes some headers on its own initiative, to implement features -such as PostScript font reencoding, bitmap font downloading, handling of -@code{\special}'s, and so on. These standard headers are the -@file{.pro} files (for ``prologue'') in the installation directory -@samp{$(psheaderdir)}; they are created from the @file{.lpro} (``long -prologue'') files in the distribution by stripping -comments, squeezing blank lines, etc., for maximum efficiency. If you -want to peruse one of the standard header files, read the @file{.lpro} -version. - -@vindex userdict@r{, and dictionary files} -@cindex dictionary, @code{userdict} -The PostScript dictionary stack will be at the @samp{userdict} level -when header files are included. - -@menu -* Including headers from TeX:: -* Including headers from the command line:: -* Headers and memory usage:: -@end menu - - -@node Including headers from TeX -@subsection Including headers from @TeX{} - -@cindex including headers in @TeX{} -@findex header=@var{file} \special -@cindex @TeX{}, including headers in - -@cindex headers, including in @TeX{} -In order to get a particular graphic file to work, a certain font or -header file might need to be sent first. The Dvips program provides -support for this with the @samp{header} @code{\special}. For instance, -to ensure that @file{foo.ps} gets downloaded: - -@example -\special@{header=foo.ps@} -@end example - -@cindex fonts, as header files -As another example, if you have some PostScript code that uses a -PostScript font not built into your printer, you must download it to the -printer. If the font isn't used elsewhere in the document, Dvips can't -know you've used it, so you must include it in the same way, as in: - -@example -\special@{header=putr.pfa@} -@end example - -@noindent -to include the font definition file for Adobe Utopia Roman. - -The @code{header} also special allows for specifying some additional -code that should be inserted into the PostScript document before and after -the file itself, as follows: - -@example -\special@{header=@{foo.ps@} pre=@{pre code@} post=@{post code@}@} -@end example - -@cindex before header, inserting code -@cindex after header, inserting code -@findex pre @r{code before headers} -@findex post @r{code after headers} -This will insert @code{pre code} just before @file{foo.ps} and -@code{post code} just after. It is required to use the (balanced) -braces in @emph{all} of the arguments, including the @code{header}, -when using this extended syntax. - -This allows, for instance, dynamic headers, where some of the content -depends on settings from the user in (La)@TeX{}. Another application -is the inclusion of graphics inside the PostScript header, so that -they can be reused throughout the document, as with logs. That avoids -including the same graphic several times. This is implemented in the -@file{graphics/graphicx-psmin} package. - -This extended syntax has one additional feature. When Dvips finds the -extended syntax, it will also look in the installed @file{tex/} -tree(s) for the header file (@file{foo.ps} in our example), and not -only in the current directory and dvips tree as the original syntax -does. This is because common graphics may well come with packages -which are installed in the @file{tex/} tree. - - -@node Including headers from the command line -@subsection Including headers from the command line - -@cindex including headers from the command line -@cindex command line, including headers from -@cindex headers, including from the command line - -You can include headers when you run Dvips, as well as from your -document (see the previous section). To do this, run Dvips with the -option @samp{-P @var{header}}; this will read the file -@file{config.@var{header}}, which in turn can specify a header file to -be downloaded with the @samp{h} option. @xref{Configuration file -commands}. These files are called @file{@var{header}.cfg} on MS-DOS. - -@cindex duplex printers -@cindex simplex mode on duplex printers -@cindex screen frequencies, setting -You can arrange for the same file to serve as a @samp{-P} config file -and the downloadable header file, by starting the lines of PostScript -code with a space, leaving only the @samp{h} line and any comments -starting in the first column. As an example, see -@file{contrib/volker/config.*} (@file{contrib/volker/*.cfg} on MS-DOS). -(These files also perform useful functions: controlling duplex/simplex -mode on duplex printers, and setting various screen frequencies; -@file{contrib/volker/README} explains further.) - - -@node Headers and memory usage -@subsection Headers and memory usage - -@cindex headers and memory usage -@cindex memory usage, and headers - -@cindex sections of output file, and memory -@cindex output file, sectioning of -Dvips tries to avoid overflowing the printer's memory by splitting the -output files into ``sections'' (see the @samp{-i} option in @ref{Option -details}). Therefore, for all header files, Dvips debits the printer VM -budget by some value. If the header file has, in its leading -commentary a line of the form - -@findex VMusage -@findex %%VMusage -@example -%%VMusage: @var{min} @var{max} -@end example - -@noindent -then @var{max} is used. If there is no @code{%%VMusage} line, then -the size (in bytes) of the header file is used as an approximation. -If you want a file to be ignored in the sectioning calculations, use -@samp{%%VMusage: 0 0}. - -Illustrations (figure files) are also checked for @code{%%VMusage} line. - -Therefore, if your document uses very large fonts or very large -included figures, Dvips might take it upon itself to split the output -into unwanted sections. If this causes problems, the simplest -solution is to use @samp{dvips -Pmaxmem}, which reads the Dvips file -@file{config.maxmem}, which sets Dvips's idea of the memory available -to a very large number. (See the @samp{m} item in @ref{Configuration -file commands}.) - - -@node Literal PS -@section Literal PostScript - -@cindex literal PostScript, using -@cindex PostScript code, literal - -You can include literal PostScript code in your document in several ways. - -@menu -* " special:: To include inline PostScript code. -* ps special:: Inline PostScript without save/restore. -* Literal headers:: Literal PostScript for the whole document. -* PostScript hooks:: Specifying code to run in the PS interpreter. -* Literal examples:: Neat example. -@end menu - - -@node " special -@subsection @code{"} special: Literal PostScript - -@findex " @r{special (literal PostScript)} - -For simple graphics, or just for experimentation, literal PostScript -code can be included. Simply use a @code{\special} beginning with a -double quote character @samp{"}; there is no matching closing @samp{"}. - -For instance, the following (simple) graphic: - -@iftex -@tex -\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}} -@end tex -@end iftex -@ifinfo -[ picture of a grey triangle ] -@end ifinfo - -@noindent -was created by typing: - -@example -\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@}@} -@end example - -You are responsible for leaving space for such literal graphics, as with -the @code{\vbox} above. - - -@node ps special -@subsection @samp{ps} special - -@findex ps @r{special} - -@cindex save/restore, and specials -Generally, Dvips encloses specials in a PostScript save/restore pair, -guaranteeing that the special will have no effect on the rest of the -document. The @samp{ps} special, however, allows you to insert literal -PostScript instructions without this protective shield; you should -understand what you're doing (and you shouldn't change the PostScript -graphics state unless you are willing to take the consequences). This -command can take many forms because it has had a torturous history; any -of the following will work: - -@example -\special@{ps:@var{text}@} -\special@{ps::@var{text}@} -\special@{ps::[begin]@var{text}@} -\special@{ps::[end]@var{text}@} -\special@{ps::[nobreak]@var{text}@} -@end example - -@noindent -(with longer forms taking precedence over shorter forms, when they are -present). @samp{ps::} and @samp{ps::[end]} do no positioning, so they -can be used to continue PostScript literals started with @samp{ps:} or -@samp{ps::[begin]}. - -Literal PostScript instructions after @samp{ps::[nobreak]} are -@emph{not} broken into lines. This feature may be used to include -PostScript comments, for example. - -@findex plotfile@r{, @samp{ps} subspecial} -In addition, the variant - -@example -\special@{ps: plotfile @var{filename}@} -@end example - -@noindent -@flindex rotate.tex -inserts the contents of @var{filename} verbatim into the output (except -for omitting lines that begin with %). An example of the proper use of -literal specials can be found in the file @file{rotate.tex}, which makes -it easy to typeset text turned in multiples of 90 degrees. - - -@node Literal headers -@subsection Literal headers: @samp{!} @code{\special} - -@cindex literal headers -@vindex SDict @r{dictionary} - -@findex ! @r{special (literal PS header)} -@cindex dictionary, @code{SDict} -You can download literal PostScript header code in your @TeX{} document, -for use with (for example) literal graphics code that you include later. -The text of a @code{\special} beginning with an @samp{!} is copied into -the output file. A dictionary @code{SDict} will be current when this -code is executed; Dvips arranges for @code{SDict} to be first on the -dictionary stack when any PostScript graphic is included, whether -literally (the @samp{"} special) or through macros (e.g., -@file{epsf.tex}). - -For example: - -@example -\special@{! /reset @{ 0 0 moveto@} def@} -@end example - - -@node PostScript hooks -@subsection PostScript hooks - -@cindex PostScript hooks - -Besides including literal PostScript at a particular place in your -document (as described in the previous section), you can also arrange to -execute arbitrary PostScript code at particular times while the -PostScript is printing. - -@findex bop-hook -@findex eop-hook -@findex start-hook -@findex end-hook -If any of the PostScript names @code{bop-hook}, @code{eop-hook}, -@code{start-hook}, or @code{end-hook} are defined in @code{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. - -@cindex draft copies -@cindex dated output -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 @samp{-h} option or the @samp{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. - -@cindex physical page number, and @code{bop-hook} -The single argument to @code{bop-hook} is the physical page number; the -first page gets zero, the second one, etc. @code{bop-hook} must leave -this number on the stack. None of the other hooks are passed arguments. - -As an example of what can be done, the following special will write -a light grey `DRAFT' across each page in the document: - -@example -\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 grestore@}def end@} -@end example - -@findex %%Page@r{, and multi-page information} -Using @code{bop-hook} or @code{eop-hook} to preserve information across -pages breaks compliance with the Adobe document structuring conventions, -so if you use any such tricks, you may also want to use the @samp{-N} -option to turn off structured comments (such as @samp{%%Page}). -Otherwise, programs that read your file will assume its pages are -independent. - - -@node Literal examples -@subsection Literal examples - -@cindex literal PostScript, examples -@cindex examples of literal PostScript - -To finish off this section, the following examples of literal PostScript -are presented without explanation: - -@example -\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 -@end example - -@iftex -@tex -\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 -@end tex -@end iftex -@ifinfo -[ There are 4 @samp{A} characters, each rotated 90 degrees about a - common center point ] -@end ifinfo - - -@example -\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@} -@end example - -@iftex -@tex -\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} -@end tex -@end iftex -@ifinfo -[ There is a big gray box with the word @samp{NEAT} inside in big letters ] -@end ifinfo - -@findex \rotninety -@findex gsave@r{/}grestore@r{, and literal PS} -@findex save@r{/}restore@r{, and literal PS} -Some caveats are in order, however. Make sure that each @code{gsave} is -matched with a @code{grestore} on the same page. Do not use @code{save} -and @code{restore}; they 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 @code{\rotninety} macro especially -has a useful trick that appears again and again. - - -@node Hypertext -@section Hyper@TeX{}t - -@cindex hypertext support - -@opindex -z -@findex html @r{specials} -@findex pdfmark -Dvips has support for producing hypertext PostScript documents. If you -specify the @samp{-z} option, the @file{html:} specials described below -will be converted into @samp{pdfmark} PostScript operators to specify -links. Without @samp{-z}, @file{html:} specials are ignored. - -@cindex distiller, for PDF files -@cindex PDF files, making -The resulting PostScript can then be processed by a distiller program to -make a PDF file. (It can still be handled by ordinary PostScript -interpreters as well.) Various versions of both PC and Unix distillers -are supported; Ghostscript includes limited distiller support -(@pxref{Ghostscript installation}). - -By far the most common @LaTeX{} package used to create hyperlinked -output is @code{hyperref} (@url{https://ctan.org/pkg/hyperref}). For -plain @TeX{}, the Eplain package has some hyperlink support -(@url{https://tug.org/eplain}). - -@flindex @code{http://xxx.lanl.gov/hypertex} -@cindex Doyle, Mark -@cindex Bhattacharya, Tanmoy -@pindex dvihps@r{, hyperdvi to PostScript} -This hypertext support (and original form of the documentation) was -written by Mark Doyle and Tanmoy Bhattacharya as the @samp{dvihps} -program. - -@menu -* Hypertext caveats:: Font quality, missing character psi. -* Hypertext specials:: The details on the specials. -@end menu - - -@node Hypertext caveats -@subsection Hypertext caveats - -@cindex hypertext caveats - -@cindex Computer Modern in PostScript -@cindex hypertext and bitmap fonts -@cindex hypertext caveats -@cindex embedding Type 1 fonts -@cindex PDF files, font quality -If you intend to go all the way to PDF, you may want to use the standard -35 PostScript fonts exclusively, since other fonts are embedded as -bitmaps by default. The Adobe PDF readers are extremely slow when -dealing with bitmap fonts and the results look terrible on the screen. -Printouts will probably look fine, but may not take full advantage of a -high-resolution printer. Alternatively, you can have your fonts -embedded as Type 1 scalable outlines. The resulting PostScript files -may be larger, but can be effectively rasterized at any resolution. -They can also be converted to PDF files that can be used effectively at -any screen or printer resolution. - -To get the TeX fonts embedded in the PostScript file as Type 1 fonts, -add @samp{-Ppdf} to the dvips command line switches. The printout -for a run should look something like this: - -@smallexample - dvips report -Ppdf -o report.ps - This is dvips(k) 5.86 Copyright 1999 Radical Eye Software (www.radicaleye.com) - ' TeX output 2001.06.15:0837' -> report.ps - <tex.pro><alt-rule.pro><texc.pro><texps.pro><special.pro>. - <cmbx9.pfb><cmsy6.pfb><cmsy7.pfb><cmr5.pfb><cmex10.pfb><cmr9.pfb> - <cmmi7.pfb><cmsy10.pfb><cmmib10.pfb><cmmi10.pfb><cmti10.pfb> - <cmr7.pfb><cmbx10.pfb><cmr10.pfb><cmti9.pfb><cmr12.pfb><cmbx12.pfb> - [1] [2<mean1.ps>] [3<bounce1-00.ps>] [4] -@end smallexample - -An entry like "<cmr10.pfb>" indicates success: dvips found the Computer -Modern Roman 10 point font in a PostScript Font Binary file, translated -it to an ASCII encoding, and embedded it. You can confirm this by -examining the PostScript output file, looking for the section starting -@code{%%BeginFont: CMR10} followed by an entry @code{/FontType 1 def}. - -The @samp{-Ppdf} option requires that the relevant outline -(@file{.pfa} or @file{.pfb}) files be installed (@pxref{Font -concepts}). For example, the @file{cmr10} file might be in -@file{/usr/share/texmf/fonts/type1/bluesky/cm/cmr10.pfb}. Your TeX -distribution may make those fonts available in a separate optional -package (e.g., @code{tetex-extra} in Debian). Failing that, -commercial versions of the Computer Modern fonts are available from -Blue Sky; public domain versions, in particular, the lm -and cm-super font families, are available from CTAN and in @TeX{} -distributions. - -You can convert a PostScript file to PDF using @code{distill}, which -comes with Adobe Acrobat, or @code{ps2pdf}, which comes with -Ghostscript. The @code{ps2pdf} that comes with @code{Ghostscript} -version 6.0 or earlier will not embed Type 1 fonts. Current -recommendations are GNU Ghostscript 6.51 or Aladdin Ghostscript 7.0. -You can check the fonts in a PDF file with Acrobat Reader by selecting -the menu entries @samp{File|Document Info|Fonts}. - -@cindex psi character missing -@cindex trailing spaces, dropped -@cindex spaces, dropped trailing -Also, the Adobe distillers prior to 2.1 drop trailing space characters -(character code 32) from strings. Unfortunately, the PostScript fonts -use this character code for characters other than space (notably the -Greek letter psi in the @code{Symbol} font), and so these characters are -dropped. This bug is fixed in version 2.1. - -If you can't upgrade, one workaround is to change all the trailing -blanks in strings to a character code that isn't in the font. This works -because the default behavior is to substitute a blank for a missing -character, i.e., the distiller is fooled into substituting the right -character. For instance, with the Blue Sky fonts, you can globally -replace @samp{ )} with @samp{\200)} (with @code{sed}, for example) and -get the desired result. With the public domain fonts, you will probably -have to use a character code in the range 128 to 191 since these fonts -duplicate the first 32 characters starting at 192 to avoid MS-DOS -problems. - -For more information on the use of TeX to produce PDF files, see the -article ``Creating quality Adobe PDF files from @TeX{} with DVIPS'' by -Kendall Whitehouse of Adobe. Adobe seems not to offer the article any -more, but copies are available elsewhere: -@display -@url{http://www.math.hawaii.edu/~ralph/MathOnWeb/TeXPDF.html} -@url{http://www.utdallas.edu/~cantrell/online/543e.html} -@end display - -You may also want to check ``Notes on converting (La)@TeX{} documents -to robust PDF using Rokicki's dvips and Acrobat Distiller'' by -Timothy@tie{}P. Van Zandt:@* -@url{http://www.emrg.com/texpdf.htmlhttp://zandtwerk.insead.fr/tex2pdf.html}. - - -@node Hypertext specials -@subsection Hypertext specials - -@cindex hypertext specials -@cindex specials, hypertext - -@cindex Smith, Arthur -Current support for the World Wide Web in the @TeX{} system does not -involve modifying @TeX{} itself. We need only define some specials; -Arthur Smith (@email{apsmith@@aps.org}), Tanmoy Bhattacharya, and Paul -Ginsparg originally proposed and implemented the following: -@example -html:<a href="@var{xurl}"> -html:<a name="@var{name}"> -html:</a> -html:<img src="@var{xurl}"> -html:<base href="@var{xurl}"> -@end example - -Like all @TeX{} @code{\special}'s, these produce no visible output, and -are uninterpreted by @TeX{} itself. They are instructions to DVI -processors only. - -@cindex uniform resource locator -@cindex extended URL -@cindex URL, extended for @TeX{} -@cindex Murphy, Tim -Here, @var{xurl} is a standard WWW uniform resource locator (URL), -possibly extended with a @samp{#@var{type}.@var{string}} construct, -where @var{type} is @samp{page}, @samp{section}, @samp{equation}, -@samp{reference} (for bibliographic references), @samp{figure}, -@samp{table}, etc. For example, -@smallexample -\special@{html:<a href="http://www.maths.tcd.ie/~tim/ch1.dvi#equation.1.1">@} -@end smallexample -@noindent is a link to equation (1.1) in an example document by Tim Murphy. - -@cindex URL, definition -See the URL @url{http://www.w3.org/hypertext/WWW/Addressing/Addressing.html} -for a precise description of base URL's. - -Descriptions of the @code{\special}'s: -@ftable @samp -@item href -@cindex links, hypertext -Creates links in your @TeX{} document. For example: -@example -\special@{html:<a href="http://www.tug.org/">@}\TeX\ Users -Group\special@{html:</a>@} -@end example -@noindent The user will be able to click on the text `@TeX{} Users -Group' while running Xdvi and get to the TUG home page. (By the way, -this is for illustration. In practice, you most likely want to use -macros to insert the @code{\special} commands; reference above.) - -@item name -@cindex Anderson, Laurie -Defines URL targets in your @TeX{} documents, so links can be -resolved. For example: -@example -\special@{html:<a name="paradise">@}Paradise\special@{html:</a>@} -is exactly where you are right now. -@end example -This will resolve an @samp{href="#paradise"}. You'll also have to -change the catcode of @samp{#}, etc. It's usually easiest to use -existing macro packages which take care of all the details, such as -@file{hyperref} for @LaTeX{}. The @url{http://arxiv.org/hypertex/, -HyperTeX FAQ} has more information. - -@item img -@flindex mailcap @r{and hypertext} -Links to an arbitrary external file. Interactively, a viewer is spawned -to read the file according to the file extension and your @file{mailcap} -file (see the Xdvi documentation). - -@item base -Defines a base URL that is prepended to all the @code{name} targets. -Typically unnecessary, as the name of the DVI file being read is used by -default. -@end ftable - -The @samp{img} and @samp{base} tags are not yet implemented in Dvips or -the NeXTSTEP DVI viewer. - - -@node PostScript fonts -@chapter PostScript fonts - -@cindex PostScript fonts - -Dvips supports the use of PostScript fonts in @TeX{} documents. To use -a PostScript font conveniently, you need to prepare a corresponding -virtual font; the program Afm2tfm, supplied with Dvips, helps -with that. - -All the necessary support for the standard 35 PostScript fonts -(@samp{AvantGarde-Book} through @samp{ZapfDingbats}), plus other freely -or commonly available PostScript fonts is available along with Dvips. -To use these fonts, you need do nothing beyond what is mentioned in the -installation procedure (@pxref{Installation}). This chapter is -therefore relevant only if you are installing new PostScript fonts not -supplied with Dvips. (Or if you're curious.) - -@menu -* Font concepts:: Metrics, glyphs, virtual fonts, and encodings. -* Making a font available:: Installing and using a PostScript font. -* Invoking afm2tfm:: Creating TFM and AFM files for a virtual font. -* psfonts.map:: Defining available PostScript fonts. -@end menu - - -@node Font concepts -@section Font concepts - -@cindex font concepts - -The information needed to typeset using a particular font is contained -in two files: a @dfn{metric file} that contains shape-independent -information and a @dfn{glyph file} that contains the actual shapes of -the font's characters. A @dfn{virtual font} is an optional additional -file that can specify special ways to construct the characters. @TeX{} -itself (or @LaTeX{}) look only at the metric file, but DVI drivers such -as Dvips look at all three of these files. - -An @dfn{encoding file} defines the correspondence between the code -numbers of the characters in a font and their descriptive names. Two -encoding files used together can describe a reencoding that rearranges, -i.e., renumbers, the characters of a font. - -@menu -* Metric files:: Shape-independent font information. -* Glyph files:: Character shapes. -* Virtual fonts:: Constructing one font from others. -* Encodings:: Character codes and character names. -* Bitmap font encodings:: Encodings for bitmapped fonts. -* PostScript typesetting:: How PostScript typesets a character. -@end menu - - -@node Metric files -@subsection Metric files - -@cindex metric files - -A @dfn{metric file} describes properties of the font that are -independent of what the characters actually look like. Aside from -general information about the font itself, a metric file has two kinds -of information: information about individual characters, organized by -character code, and information about sequences of characters. - -The per-character information specifies the width, height, depth, and -italic correction of each character in the font. Any might be zero. - -@cindex kerning, defined -@cindex ligature, defined -In addition to information on individual characters, the metric file -specifies @dfn{kerning}, i.e., adding or removing space between -particular character pairs. It further specifies @dfn{ligature} -information: when a sequence of input characters should be typeset as a -single (presumably different) ``ligature'' character. For example, it's -traditional for the input @samp{fi} to be typeset as `fi', not as -`@r{f}@r{i}' (with the dot of the `i' colliding with `f'). (In English, -the only common ligatures are fi, fl, ff, ffi, and ffl.) - -Different typesetting systems use different metric file formats: - -@itemize @bullet -@item -@cindex afm files -@flindex .afm @r{Adobe metric files} -Each Postscript font has an @dfn{Adobe font metrics} (@samp{.afm}) -file. These files are plain text, so you can inspect them easily. You -can get AFM files for Adobe's fonts from -@url{ftp://ftp.adobe.com/pub/adobe/Fonts/AFMs}. - -@item -@cindex tfm files -@flindex .tfm @r{@TeX{} font metric files} -@TeX{} uses @dfn{@TeX{} font metrics} (@samp{.tfm}) files. When you say -@samp{\font = @var{font}} in your @TeX{} document, @TeX{} reads a file -named @samp{@var{font}.tfm}. (Well, except for the @file{texfonts.map} -feature; @pxref{Fontmap,,, kpathsea, Kpathsea}). @TeX{} can then -calculate the space occupied by characters from the font when -typesetting. In addition, the DVI drivers you use to print or view the -DVI file produced by @TeX{} may need to look at the TFM file. - -@cindex property list files -@pindex tftopl -@pindex pltotf -@flindex .pl @r{property list files} -TFM files are binary (and hence are typically much smaller than AFM -files). You can use the @code{tftopl} program (@pxref{tftopl -invocation,,, web2c, Web2c}) that comes with @TeX{} to transform a TFM -file into a human-readable ``property list'' (@samp{.pl}) file. You can -also edit a PL file and transform it back to a @TeX{}-readable TFM with -the companion program @code{pltotf} (@pxref{pltotf invocation,,, web2c, -Web2c}). Editing metrics by hand is not something you're likely to want -to do often, but the capability is there. - -@item -@cindex pfm files -@flindex .pfm @r{printer font metric files} -ATM and other typesetting systems use @dfn{printer font metric} -(@samp{.pfm}) files. These are binary files. They are irrelevant in the -@TeX{} world, and not freely available, so we will not discuss them -further. - -@end itemize - -The Afm2tfm program distributed with Dvips converts an AFM file -to a TFM file and performs other useful transformations as well. -@xref{Invoking afm2tfm}. - - -@node Glyph files -@subsection Glyph files - -@cindex glyph files - -Although a metric file (see the previous section) contains information -about the spatial and other properties of the character at position 75, -say, it contains nothing about what the character at position 75 -actually looks like. The glyphs---the actual shapes of the letterforms -in a font---are defined by other files, which we call glyph files. -@TeX{} itself only reads the TFM file for a font; it does not need to -know character shapes. - -A @dfn{glyph file} is a file that defines the shapes of the characters -in a font. The shapes can be defined either by outlines or by bitmaps. - -@cindex outline fonts -@cindex arcs -@cindex splines -PostScript fonts are defined as @dfn{outline fonts}: Each character in -the font is defined by giving the mathematical curves (lines, arcs, and -splines) that define its contours. Different sizes of a character are -generated by linearly scaling a single shape. For example, a 10-point -`A' is simply half the size of a 20-point `A'. Nowadays, outline fonts -usually also contain @dfn{hints}---additional information to improve the -appearance of the font at small sizes or low resolutions. - -@cindex Type 1 fonts -@cindex pfa files -@cindex pfb files -@flindex .pfa @r{printer font ascii files} -@flindex .pfb @r{printer font binary files} -Although various kinds of PostScript outline fonts exist, by far the -most common, and the only one we will consider, is called @dfn{Type 1}. -The glyph files for Postscript Type 1 fonts typically have names ending -in @samp{.pfa} (``printer font ASCII'') or @samp{.pfb} (``printer font -binary''). - -@cindex bitmap fonts -@flindex .mf @r{Metafont source files} -@cindex Metafont source files -In contrast, glyph files for Computer Modern and the other standard -@TeX{} fonts are @dfn{bitmap fonts}, generated from Metafont -(@samp{.mf}) descriptions. The Metafont program distributed with @TeX{} -generates bitmaps from these descriptions. - -@cindex pk files -@flindex .@var{nnn}pk @r{packed font bitmaps} -The glyph files for @TeX{} bitmap fonts are usually stored in -@dfn{packed font} (PK) files. The names of these files end in -@samp{.@var{nnn}pk}, where @var{nnn} is the resolution of the font in -dots per inch. For example, @file{cmr10.600pk} contains the bitmaps for -the @samp{cmr10} font at a resolution of 600@dmn{dpi}. (On DOS -filesystems, it's more likely @file{dpi600\cmr10.pk}.) - -@cindex gf files -@pindex gftopk -Metafont actually outputs @dfn{generic font} (GF) files, e.g., -@file{cmr10.600gf}, but the GF files are usually converted immediately -to PK format (using the @code{gftopk} utility that comes with @TeX{}) -since PK files are smaller and contain the same information. (The GF -format is a historical artifact.) - - -@node Virtual fonts -@subsection Virtual fonts - -@cindex virtual fonts - -A @dfn{virtual font} is constructed by extracting characters from one -or more existing fonts and rearranging them, or synthesizing new -characters in various ways. The explanation in this manual is -intended to suffice for understanding enough about virtual fonts to -use them with Dvips. It isn't a reference manual on virtual fonts. -For more information: The primary document on virtual fonts is -Donald@tie{}E. Knuth, @cite{TUGboat} 11(1), Apr.@: 1990, pp.@: 13--23, -``Virtual Fonts: More Fun for Grand Wizards'' -(@url{mirror.ctan.org/info/virtual-fonts.knuth}). (Don't be -intimidated by the subtitle.) - -@cindex vf files -@cindex vpl files -A virtual font (@samp{.vf}) file specifies, for each character in the -virtual font, a recipe for typesetting that character. A VF file, like -a TFM file, is in a compressed binary format. The @code{vftovp} and -@code{vptovf} programs convert a VF file to a human-readable VPL -(virtual property list) format and back again. @xref{vftovp -invocation,,, web2c, Web2c}, and @ref{vptovf invocation,,, web2c, -Web2c}. - -@cindex base fonts -In the case of a PostScript font @var{f} being used in a straightforward -way, the recipe says: character @var{i} in the VF font is character -@var{j} in font @var{f}. The font @var{f} is called a @dfn{base font}. -For example, the VF file could remap the characters of the PostScript -font to the positions where @TeX{} expects to find them. -@xref{Encodings}. - -Since @TeX{} reads only TFM files, not VF's, each VF must have a -corresponding TFM for use with @TeX{}. This corresponding TFM is -created when you run @code{vptovf}. - -@cindex expansion, of virtual fonts -@cindex virtual font expansion -You can @dfn{expand} virtual fonts into their base fonts with DVIcopy -(@pxref{dvicopy invocation,,, web2c, Web2c}). This is useful if you are -using a DVI translator that doesn't itself understand vf's. - -@pindex ptex @r{JFM} -@pindex uptex @r{JFM} -@cindex Japanese font metric file -@cindex JFM file, and virtual font fallback -If a virtual font has no entry at a given codepoint and the first -@code{MAPFONT} designates an (u)pTeX JFM, we designate the glyph of -the same codepoint in the TFM(JFM) with the smallest font ID. This -feature helps to reduce the size of Japanese virtual fonts. For more -information about the extensive support of Japanese in TeX, see -@url{https://github.com/texjporg}. - - -@node Encodings -@subsection Encodings - -@cindex encodings - -Every font, whatever its type, has an @dfn{encoding}, that specifies the -correspondence between ``logical'' characters and character codes. For -example, the ASCII encoding specifies that the character numbered 65 -(decimal) is an uppercase `A'. The encoding does not specify what the -character at that position looks like; there are lots of ways to draw an -`A', and a glyph file (@pxref{Glyph files}) tells how. Nor does it -specify how much space that character occupies; that information is in a -metric file (@pxref{Metric files}). - -@cindex Computer Modern, encoding of -@TeX{} implicitly assumes a particular encoding for the fonts you use -with it. For example, the plain @TeX{} macro @code{\'}, which typesets -an acute accent over the following letter, assumes the acute accent is -at position 19 (decimal). This happens to be true of standard @TeX{} -fonts such as Computer Modern, as you might expect, but it is not true -of normal PostScript fonts. - -It's possible but painful to change all the macros that assume -particular character positions. A better solution is to create a new -font with the information for the acute accent at position 19, where -@TeX{} expects it to be. @xref{Making a font available}. - -@cindex PostScript encoding -@cindex encoding files -@cindex encoding vectors, defined - -PostScript represents encodings as a sequence of 256 character names -called an @dfn{encoding vector}. An @dfn{encoding file} (@samp{.enc}) -gives such a vector, together with ligature and kerning information -(with which we are not concerned at the moment). These encoding files -are used by the Afm2tfm program. Encoding files are also downloaded to -the PostScript interpreter in your printer if you use one of them in -place of the default encoding vector for a particular PostScript font. - -@flindex dvips.enc -@flindex 8r.enc -@flindex texmext.enc -@flindex texmital.enc -@flindex texmsym.enc -@flindex reencode/*.enc -Examples of encodings: the @file{dvips.enc} encoding file that comes -with the Fontname distribution (@url{http://tug.org/fontname}) is a -good (but not perfect) approximation to the @TeX{} encoding for -@TeX{}'s Computer Modern text fonts. This is the encoding of the -fonts that originated with Dvips, such as @file{ptmr.tfm}. The -distribution includes many other encoding files; for example, -@file{8r.enc}, which is the base font for the current PostScript font -distribution, and three corresponding to the @TeX{} mathematics fonts: -@file{texmext.enc} for math extensions, @file{texmital.enc} for math -italics, and @file{texmsym.enc} for math symbols. - - -@node Bitmap font encodings -@subsection Bitmap font encodings - -@cindex bitmap font encodings -@cindex font encodings, bitmap -@cindex encodings, for bitmap fonts - -To dvips, bitmapped fonts do not have any notion of linguistics; they -are simply a vector of glyphs. By comparison, PostScript fonts are -required to contain an encoding vector that at least provides -glyph names; these names can permit PostScript and PDF viewers to -extract legible text from Postscript and PDF output. - -Unlike previous versions, dvips versions 2020 and later add glyph -naming information to Type 3 bitmapped fonts (if they can locate such -information) as an Encoding vector. This provides some support for -search, for copy and paste, and even some limited support for -accessibility. The @samp{bitmapfontenc} command line option -(@pxref{Option details} and @code{bitmapfontenc} configuration option -(@pxref{Configuration file commands}) enable and disable this -functionality; by default it is set to enabled, without warnings. - -@flindex dvips-all.enc -To do this, dvips must find encoding information for the bitmapped -fonts. It does this by first searching for a font-specific encoding -file; for instance, for cmr10, it will search for @file{dvips-cmr10.enc} -in the standard encoding path. If it does not find such a file, it -will search for a @file{dvips-all.enc} file which contains a base set of -encodings for many fonts. - -The specific syntax of an encoding file is unspecified, except that it -must be a PostScript fragment that leaves exactly one object on the -operand stack. (This is different from the encoding files used to -define encodings for PostScript fonts, described earlier). Normally -that object is just an array of 256 names; in this case, that array is -used as the encoding vector for the font. Alternatively, the object -can be a procedure that, when executed, leaves a legal encoding vector -on the stack. This second option is made available to support future -enhancements that may add additional constructs to the font dictionary -to enhance the interpretation of font characters. - -The @file{dvips-all.enc} file contains encodings for many fonts, and -it is loaded by dvips at most once. The format is just a sequence of -font names, one per line, each terminated by a colon, followed by the -encoding to use for those files. - -@cindex bounding box, for bitmap fonts -@cindex coordinate system, for bitmap fonts -As part of its operation, to enable heuristics in PostScript and -PDF viewers to properly identify word breaks and column gutters, -dvips also generates a modified font bounding box and a modified -font coordinate system. - - -@node PostScript typesetting -@subsection How PostScript typesets a character - -@cindex typesetting in PostScript -@cindex character lookup procedure in PostScript - -The output of Dvips is a program in the PostScript language that -instructs your (presumably PostScript-capable) printer how to typeset -your document by transforming it into toner on paper. Your printer, in -turn, contains a PostScript interpreter that carries out the -instructions in this typesetting program. - -The program must include the definition of any PostScript fonts that you -use in your document. Fonts built into your printer (probably the -standard 35: @samp{Times-Roman}, @samp{ZapfDingbats}, @dots{}) are -defined within the interpreter itself. Other fonts must be downloaded -as pfa or pfb files (@pxref{Glyph files}) from your host (the computer -on which you're running Dvips). - -You may be wondering exactly how a PostScript interpreter figures out -what character to typeset, with this mass of metrics, glyphs, encodings, -and other information. (If you're not wondering, skip this section -@dots{}) - -@findex show @r{PostScript operator} -The basic PostScript operator for imaging characters is -@code{show}. Suppose you've asked @TeX{} to typeset an `S'. This will -eventually wind up in the Dvips output as the equivalent of this -PostScript operation: - -@example -(S) show -@end example - -@noindent Here is how PostScript typesets the `S': - -@enumerate -@item -@cindex ASCII character codes, used by PostScript -PostScript interpreters use ASCII; therefore `S' is represented as the -integer 83. (Any of the 256 possible characters representable in a -standard 8-bit byte can be typeset.) - -@item -@cindex current font, in PostScript -@cindex dictionary, PostScript language -A PostScript @dfn{dictionary} is a mapping of names to arbitrary values. -A font, to the interpreter, is a dictionary which contains entries for -certain names. (If these entries are missing, the interpreter refuses -to do anything with that font.) - -PostScript has a notion of ``the current font''---whatever font is -currently being typeset in. - -@item -@cindex encoding vectors, in Type 1 fonts -@findex Encoding @r{Type 1 dictionary} -One of the mandatory entries in a font dictionary is @samp{Encoding}, -which defines the encoding vector (@pxref{Encodings}) for that font. -This vector of 256 names maps each possible input character to a name. - -@item -The interpreter retrieves the entry at position 83 of the encoding -vector. This value is a PostScript name: @code{/S}. - -@item -@findex CharStrings @r{Type 1 dictionary} -@cindex dictionary, @code{CharStrings} -For Type 1 fonts (we're not going to discuss anything else), the -interpreter now looks up @code{/S} as a key in a dictionary named -@code{CharStrings}, another mandatory entry in a font dictionary. - -@item -@cindex hints -@cindex character definitions in PostScript -The value of @code{S} in @code{CharStrings} is the equivalent of a -series of standard PostScript commands like @samp{curveto}, -@samp{lineto}, @samp{fill}, and so on. These commands are executed to -draw the character. There can also be @dfn{hint information} that helps -adapt the character to low-resolution rasters. (@xref{Glyph files}.) -The commands are actually represented in a more compact way than -standard PostScript source; see the Type 1 book for details. - -@end enumerate - -This method for typesetting characters is used in both Level 1 and Level -2 PostScript. See the PostScript reference manuals for more -information. - - -@node Making a font available -@section Making a PostScript font available - -@cindex installing fonts -@cindex fonts, installing - -To make a PostScript font available in a @TeX{} document, you need to -install the font on your system and then define it within the document. -Once you have installed the font, of course, it is available for any -document thereafter and you don't need to reinstall it. You must have -an AFM file for any font you install. Unless the font is built into your -printer, you must also have a PFA or PFB file. - -In the following examples, we use the font @samp{Times-Roman} to -illustrate the process. But you should use the prebuilt fonts for Times -and the other standard fonts, rather than rebuilding them. The prebuilt -fonts are made using a more complicated process than that described -here, to make them work as well as possible with @TeX{}. So following -the steps in this manual will not generate files identical to the -distributed ones. @xref{PostScript font installation}, for pointers to -the prebuilt fonts. - -Installation of a PostScript font proceeds in three steps. @xref{Font -concepts}, for descriptions of the various files involved. - -@enumerate -@item -Run @code{afm2tfm} to create a TFM file for the original font, -and the VPL form of the virtual font: -@example -afm2tfm Times-Roman -v ptmr rptmr -@end example - -@item -Run @code{vptovf} to generate a VF and TFM file for the virtual font -from the VPL file: -@example -vptovf ptmr.vpl ptmr.vf ptmr.tfm -@end example - -@item -Insert an entry for the font in @file{psfonts.map} (@pxref{psfonts.map}): -@example -rptmr Times-Roman <ptmr8a.pfa -@end example - -@item -Install the files in the standard locations, as in: -@example -cp ptmr.vf @var{fontdir}/vf/@dots{} -cp *ptmr.tfm @var{fontdir}/tfm/@dots{} -cp ptmr.afm @var{fontdir}/afm/@dots{} -cp ptmr.pf? @var{fontdir}/type1/@dots{} -@end example -@end enumerate - -The simplest invocation of Afm2tfm to make virtual fonts goes something -like this: - -@pindex afm2tfm -@example -afm2tfm Times-Roman -v ptmr rptmr -@end example - -@noindent -This reads the file @file{Times-Roman.afm}, and produces two files as -output, namely the virtual property list'file @file{ptmr.vpl}, and the -``raw'' font metric file @file{rptmr.tfm}. To use the font in @TeX{}, -you first run - -@pindex vptovf -@example -vptovf ptmr.vpl ptmr.vf ptmr.tfm -@end example - -@noindent -You should then install the virtual font file @file{ptmr.vf} where Dvips -will see it and install @file{ptmr.tfm} and @file{rptmr.tfm} where -@TeX{} and Dvips will see them. - -Using these raw fonts is not recommended; there are no raw fonts in the -prebuilt PostScript fonts distributed along with Dvips. But -nevertheless, that's how Afm2tfm presently operates, so that's what we -document here. The @samp{r} prefix convention is likewise historical -accident. - -You can also make more complex virtual fonts by editing @file{ptmr.vpl} -before running @samp{vptovf}; such editing might add the uppercase Greek -characters in the standard @TeX{} positions, for instance. (This has -already been done for the prebuilt fonts.) - -Once the files have been installed, you're all set. You can now do -things like this in @TeX{}: -@example -\font\myfont = ptmr at 12pt -\myfont Hello, I am being typeset in 12-point Times-Roman. -@end example - -Thus, we have two fonts, one actual (@samp{rptmr}, which is analogous to -the font in the printer) and one virtual (@samp{ptmr}, which has been -remapped to the standard @TeX{} encoding (almost)), and has typesetting -know-how added. You could also say - -@example -\font\raw = rptmr at 10pt -@end example - -@noindent -and typeset directly with that, but then you would have no ligatures or -kerning, and you would have to use Adobe character positions for special -letters like -@tex -\AE. -@end tex -@ifinfo -the ligature `AE'. -@end ifinfo -The virtual font @samp{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). @xref{Reencoding with Afm2tfm}. - -As a final step you need to record information about both the virtual -font and the original font (if you ever might want to use it) in the -@file{psfonts.map} file (@pxref{psfonts.map}). For our example, you'd -insert the following into @file{psfonts.map}: -@example -rptmr Times-Roman <ptmr8a.pfa -@end example - -@noindent Of course, @code{Times-Roman} is already built in to most every -printer, so there's no need to download any Type 1 file for it. But if -you are actually following these instructions for new fonts, most likely -they are not built in to the printer. - -@cindex memory, used by PostScript fonts -@cindex efficiency, and fonts -These PostScript fonts can be scaled to any size. Go wild! Using -PostScript fonts, however, does use up a great deal of the printer's -memory and it does take time. You may find downloading bitmap fonts -(possibly compressed, with the @samp{Z} option) to be faster than using -the built-in PostScript fonts. - - -@node Invoking afm2tfm -@section Invoking Afm2tfm - -@pindex afm2tfm - -The Afm2tfm program converts an AFM file for a PostScript font to a TFM -file and a VPL file for a corresponding virtual font (or, in its -simplest form, to a TFM file for the PostScript font itself). The -results of the conversion are affected by the command-line options and -especially by the reencodings you can specify with those options. You -can also obtain special effects such as an oblique font. - -@pindex fontinst -@cindex virtual fonts, creating -@cindex Jeffrey, Alan -Alternatives to Afm2tfm for creating virtual fonts include -@code{fontinst} @url{https://ctan.org/pkg/fontinst}, -@code{lcdf-typetools}, particularly @code{otftotfm} -(@url{https://ctan.org/pkg/lcdf-typetools}), and @code{afm2pl} -(@url{http://tex.aanhet.net/afm2pl/}), among others. - -@menu -* Changing font encodings:: Reencoding with -t, -p, -T. -* Special font effects:: Oblique fonts, small caps, and such. -* Afm2tfm options:: afm2tfm command-line options. -@end menu - - -@node Changing font encodings -@subsection Changing font encodings - -@cindex encoding changes -@cindex fonts, changing encoding of - -Afm2tfm allows you to specify a different encoding for a PostScript font -(for a general introduction to encodings, @pxref{Encodings}). The -@samp{-t} option changes the @TeX{} encoding, @samp{-p} changes the -PostScript encoding, and @samp{-T} changes both simultaneously, as -detailed in the sections below. - -@menu -* Changing TeX encodings:: Where TeX finds a character. -* Changing PostScript encodings:: Where PostScript finds a character. -* Changing both encodings:: One and the same, simultaneously. -* Reencoding with Afm2tfm:: Problems with the default encoding. -* Encoding file format:: Syntax of an encoding file. -@end menu - - -@node Changing TeX encodings -@subsubsection @samp{-t}: Changing @TeX{} encodings - -@cindex changing @TeX{} encodings -@cindex @TeX{} encoding, changing - -@opindex -t @var{tex-enc} -To build a virtual font with Afm2tfm, you specify the @samp{-v} or -@samp{-V} option. You can then specify an encoding for that virtual font -with @samp{-t @var{tex-enc}}. (@samp{-t} is ignored if neither -@samp{-v} nor @samp{-V} is present.) Any ligature and kerning -information you specify in @var{tex-enc} will be used in the VPL, in -addition to the ligature and kerning information from the AFM file. - -If the AFM file has no entry for a character specified in @var{tex-enc}, -that character will be omitted from the output VPL. - -@flindex texmsym.enc -The @samp{-t} option is likely to be needed when you have a PostScript -font corresponding to a @TeX{} font other than a normal text font such -as Computer Modern. For instance, if you have a PostScript font that -contains math symbols, you'd probably want to use the encoding in the -@file{texmsym.enc} file supplied with Dvips. (For a start; to actually -get usable math fonts, you have to define much more than just an -encoding.) - - -@node Changing PostScript encodings -@subsubsection @samp{-p}: Changing PostScript encodings - -@cindex changing PostScript encodings -@cindex PostScript encoding, changing -@opindex -p @var{ps-enc} - -By default, Afm2tfm uses the encoding it finds in the AFM file. You can -specify a different PostScript encoding with @samp{-p @var{ps-enc}}. -This makes the raw TFM file (the one output by Afm2tfm) have the -encoding specified in the encoding file @var{ps-enc}. Any ligature or -kern information specified in @var{ps-enc} is ignored by Afm2tfm, since -ligkern info is always omitted from the raw TFM. - -If you use this option, you must also arrange to download @var{ps-enc} -as part of any document that uses this font. You do this by adding a -line like the following one to @file{psfonts.map} (@pxref{psfonts.map}): -@example -zpopr Optima "MyEncoding ReEncodeFont" <myenc.enc -@end example - -@findex trademark @r{character, accessing} -@findex registered @r{character, accessing} -@cindex extra characters, accessing -Using @samp{-p} is the only way to access characters in a PostScript -font that are neither encoded in the AFM file nor constructed from other -characters. For instance, Adobe's @samp{Times-Roman} font contains the -extra characters @samp{trademark} and @samp{registered} (among others); -these can only be accessed through such a PostScript reencoding. - -@findex 8r @r{encoding, and extra characters} -The `8r' base encoding used for the current PostScript font -distribution does do this reencoding, for precisely this reason. - - -@node Changing both encodings -@subsubsection @samp{-T}: Changing both @TeX{} and PostScript encodings - -@opindex -T @var{enc-file} - -The option @samp{-T @var{enc-file}} is equivalent to @samp{-p -@var{enc-file} -t @var{enc-file}}. If you make regular use of a private -non-standard reencoding @samp{-T} is usually a better idea than the -individual options, to avoid unexpected inconsistencies in mapping -otherwise. An example of when you might use this option is a dingbats -font: when you have a @TeX{} encoding that is designed to be used with a -particular PostScript font. - - -@node Reencoding with Afm2tfm -@subsubsection Reencoding with Afm2tfm - -@cindex reencoding -@cindex remapping - -The Afm2tfm program creates the TFM and VF files for the virtual font -corresponding to a PostScript font by @dfn{reencoding} the PostScript -font. Afm2tfm generates these files from two encodings: one for @TeX{} -and one for PostScript. The @TeX{} encoding is used to map character -numbers to character names while the PostScript encoding is used to map -each character name to a possibly different number. In combination, you -can get access to any character of a PostScript font at any position for -@TeX{} typesetting. - -In the default case, when you specify none of the @code{-t}, @code{-p}, -or @code{-T} options, Afm2tfm uses a default @TeX{} encoding (which -mostly corresponds to the Computer Modern text fonts) and the PostScript -encoding found in the AFM file being read. The reencoding is also -sometimes called a @dfn{remapping}. - -For example, the default encodings reencode the acute accent in two -steps: first the default @TeX{} encoding maps the number 19 to the -character name @samp{acute}; then the default PostScript encoding, as -found in the AFM file for an ordinary PostScript font, maps the -character name @samp{acute} to the number 194. (The PostScript encoding -works in reverse, by looking in the encoding vector for the name and -then yielding the corresponding number.) The combined mapping of 19 to -194 shows up explicitly in the VF file and also implicitly in the fact -that the properties of PostScript character 194 appear in position 19 of -the TFM file for the virtual font. - -@cindex accents, in wrong position -@cindex Hungarian umlaut -@cindex dot accent -@cindex Scandinavian A ring -@cindex A ring, Scandinavian letter -The default encoding of the distributed fonts (e.g., @file{ptmr.tfm}) -mostly follows plain @TeX{} conventions for accents. The exceptions: -the Hungarian umlaut (which is at position @code{0x7D} in @samp{cmr10}, -but position @code{0xCD} in @samp{ptmr}); the dot accent (at positions -@code{0x5F} and @code{0xC7}, respectively); and the Scandinavian A ring -@code{\AA}, whose definition needs different tweaking. In order to use -these accents with PostScript fonts or in math mode when -@code{\textfont0} is a PostScript font, you will need to use the -following definitions. These definitions will not work with the -Computer Modern fonts for the relevant accents. They are already part -of the distributed @file{psfonts.sty} for use with @LaTeX{}. - -@findex \H -@findex \. -@findex \dot -@findex \AA -@example -\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@} -@end example - -@vindex CODINGSCHEME -As a kind of summary, here are the @samp{CODINGSCHEME}s that result from -the various possible choices for reencoding. - -@table @asis -@item default encoding -@example -(CODINGSCHEME TeX text + AdobeStandardEncoding) -@end example - -@item @samp{-p dc.enc} -@example -(CODINGSCHEME TeX text + DCEncoding) -@end example - -@item @samp{-t dc.enc} -@example -(CODINGSCHEME DCEncoding + AdobeStandardEncoding) -@end example - -@item @samp{-T dc.enc} -@example -(CODINGSCHEME DCEncoding + DCEncoding) -@end example - -@end table - -@noindent The @samp{CODINGSCHEME} line appears in the VPL file but is -ignored by Dvips. - - -@node Encoding file format -@subsubsection Encoding file format - -@cindex encoding file format - -Afm2tfm's encoding files have the same format as an encoding vector in a -PostScript font. Here is a skeletal example: - -@example -% @r{Comments are ignored, unless the first word after the percent sign} -% @r{is @samp{LIGKERN}; see below.} -/MyEncoding [ % @r{exactly 256 entries follow, each with a leading @samp{/}} - /Alpha /Beta /Gamma /Delta @dots{} - /A /B @dots{} /Z - @dots{} /.notdef /xfooaccent /yfooaccent /zfooaccent -] def -@end example - -These encoding files are downloaded as part of changing the encoding at -the PostScript level (see the previous section). - -@cindex comments, in encoding files -Comments, which start with a percent sign and continue until the end -of the line, are ignored unless they start with @samp{LIGKERN} (see below). - -The first non-comment word of the file must start with a forward slash -@samp{/} (i.e., a PostScript literal name) and defines the name of the -encoding. The next word must be an left bracket @samp{[}. Following -that must be precisely 256 character names; use @samp{/.notdef} for any -that you want to leave undefined. Then there must be a matching right -bracket @code{]}. A final @samp{def} token is optional. All names are -case-sensitive. - -Any ligature or kern information is given as a comment. If the first -word after the @samp{%} is @samp{LIGKERN}, 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 is terminated -by a space and a semicolon and (unless the semicolon is at the end of a -line) another space. - -@findex LIGKERN @r{encoding file command} -In these @code{LIGKERN} statements, three types of information may be -specified. These three types are ligature pairs, kerns to ignore, and -the character value of this font's boundary character. - -@cindex boundary character -Throughout a @code{LIGKERN} statement, the boundary character is -specified as @samp{||}. To set the font's boundary character value for -@TeX{}: - -@example -% LIGKERN || = 39 ; -@end example - -To indicate a kern to remove, give the names of the two characters -(without the leading slash) separated by @samp{@{@}}, as in @samp{one -@{@} one ;}. This is intended to be reminiscent of the way you might -use @samp{@{@}} 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 @samp{*}, which is a wild card matching any character; thus, all -kerns can be removed with @samp{* @{@} * ;}. - -@cindex ligature operations -@cindex Metafont ligature operations -To specify a ligature, specify the names of the pair of characters, -followed by the ligature operation (as in Metafont), followed by the -replacing character name. Either (but not both) of the first two -characters can be @samp{||} to indicate a word boundary. - -@findex =: @r{ligature operation} -The most common operation is @samp{=:} meaning that both characters are -removed and replaced by the third character, but by adding the @samp{|} -character on either side of the @samp{=:}, you can retain either or both -of the two leading characters. In addition, by suffixing the ligature -operation with one or two @samp{>} signs, you can make the ligature -scanning operation skip that many resulting characters before -proceeding. This works just like in Metafont. For example, the `fi' -ligature is specified with @w{@samp{f i =: fi ;}}. A more convoluted -ligature is @samp{one one |=:|>> exclam ;} which separates a pair of -adjacent @code{1}'s with an exclamation point, and then skips over two -of the resulting characters before continuing searching for ligatures -and kerns. You cannot give more @t{>}'s than @t{|}'s in an ligature -operation, so there are a total of eight possibilities: - -@example -=: |=: |=:> =:| =:|> |=:| |=:|> |=:|>> -@end example - -The default set of ligatures and kerns built in to Afm2tfm is: - -@example -% 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 ; 0 @{@} * ; * @{@} 0 ; -% LIGKERN 1 @{@} * ; * @{@} 1 ; 2 @{@} * ; * @{@} 2 ; 3 @{@} * ; * @{@} 3 ; -% LIGKERN 4 @{@} * ; * @{@} 4 ; 5 @{@} * ; * @{@} 5 ; 6 @{@} * ; * @{@} 6 ; -% LIGKERN 7 @{@} * ; * @{@} 7 ; 8 @{@} * ; * @{@} 8 ; 9 @{@} * ; * @{@} 9 ; -@end example - - -@node Special font effects -@subsection Special font effects - -@cindex oblique fonts -@cindex slanted fonts -@cindex fonts, slanted -Besides the reencodings described in the previous section, Afm2tfm can -do other manipulations. (Again, it's best to use the prebuilt fonts -rather than attempting to remake them.) - -@samp{-s @var{slant}} makes an obliqued variant, as in: - -@example -afm2tfm Times-Roman -s .167 -v ptmro rptmro -@end example - -@noindent -This creates @file{ptmro.vpl} and @file{rptmro.tfm}. To use this font, -put the line - -@findex SlantFont -@example -rptmro Times-Roman ".167 SlantFont" -@end example - -@noindent -@flindex psfonts.map -into @file{psfonts.map}. Then @samp{rptmro} (our name for the obliqued -Times) will act as if it were a resident font, although it is actually -constructed from Times-Roman via the PostScript routine @code{SlantFont} -(which will slant everything 1/6 to the right, in this case). - -@cindex expanded fonts -@cindex fonts, expanded -Similarly, you can get an expanded font with - -@example -afm2tfm Times-Roman -e 1.2 -v ptmrre rptmrre -@end example - -@noindent -and by recording the pseudo-resident font -@findex ExtendFont - -@example -rptmrre Times-Roman "1.2 ExtendFont" -@end example - -@noindent -in @file{psfonts.map}. - -You can also create a small caps font with a command such as -@cindex small caps fonts -@cindex fonts, small caps - -@example -afm2tfm Times-Roman -V ptmrc rptmrc -@end example - -@noindent -This will generate a set of pseudo-small caps mapped into the usual -lowercase positions and scaled down to 0.8 of the normal cap -dimensions. You can also specify the scaling as something other than -the default 0.8: - -@example -afm2tfm Times-Roman -c 0.7 -V ptmrc rptmrc -@end example - -It is unfortunately not possible to increase the width of the small caps -independently of the rest of the font. If you want a really -professional looking set of small caps, you need to acquire a small caps -font. - -@findex PaintType -@cindex outline fonts -@cindex fonts, outlined -To change the @code{PaintType} in a font from filled (0) to outlined -(2), you can add @code{"/PaintType 2 store"} to @file{psfonts.map}, as -in the following: - -@example -rphvrl Helvetica "/PaintType 2 store" -@end example - -Afm2tfm writes to standard output the line you need to add to -@file{psfonts.map} to use that font, assuming the font is resident in -the printer; if the font is not resident, you must add the -@samp{<@var{filename}} command to download the font. Each identical -line only needs to be specified once in the @samp{psfonts.map} file, -even though many different fonts (small caps variants, or ones with -different output encodings) may be based on it. - - -@node Afm2tfm options -@subsection Afm2tfm options - -@cindex options, to Afm2tfm -@cindex afm2tfm options - -Synopsis: -@example -afm2tfm [@var{option}]@dots{} @var{afmfile}[.afm] [@var{tfmfile}[.tfm]] -@end example - -Afm2tfm reads @var{afmfile} and writes a corresponding (but ``raw'', -see below) TFM file. If @var{tfmfile} is not supplied, the base name -of the AFM file is extended with @samp{.tfm} to get the output -filename. - -The simplest example: - -@example -afm2tfm Times-Roman rptmr -@end example - -@cindex accents, wrong -@cindex raw tfm files -@noindent -The TFM file thus created is @dfn{raw} because it omits ligature and -kern information, and does no character remapping; it contains only -the character information in the AFM file in TFM format, which is the form -that @TeX{} understands. The characters have the same code in the TFM -file as in the AFM file. For text fonts, this means printable ASCII -characters will work ok, but little else, because standard PostScript -fonts have a different encoding scheme than the one that plain @TeX{} -expects (@pxref{Encodings}). Although the encodings agree for most -printable ASCII characters, other characters such as ligatures and -accents vary. Thus, in practice, it's almost always desirable to create -a virtual font as well with the @samp{-v} or @samp{-V} option. -@xref{Making a font available}. - -The command line options to Afm2tfm: - -@table @samp -@item -a -@opindex -a -@cindex accent height adjustment, omitting -By default, Afm2tfm looks for precomposed accented characters, such as -tdieresis, and possibly adjusts the height of the basic letter (t) -upward so that the result of using @code{\accent} (as in @code{\"t}) -is visually the same as the precomposed characters. The @code{-a} -option omits such adjustments, so that all characters' heights remain -as they are given in the AFM file. (Until Afm2tfm 8.4, released in -2016, heights could also be adjusted downward, but this is no longer -the case.) - -@item -c @var{ratio} -@opindex -c @var{ratio} -@cindex scaling small caps -See @samp{-V}; overrides the default ratio of 0.8 for the -scaling of small caps. - -@item -e @var{ratio} -@opindex -e @var{ratio} -@cindex expanded fonts -@cindex condensed fonts -Stretch characters horizontally by @var{ratio}; if less than 1.0, you -get a condensed font. - -@item -O -@opindex -O -@cindex octal character codes -Output all character codes in the @samp{vpl} file as octal numbers, not -names; this is useful for symbol or other special-purpose fonts where -character names such as @samp{A} have no meaning. - -@item -p @var{ps-enc} -@opindex -p @var{ps-enc} -Use @var{ps-enc} for the destination (PostScript) encoding of the font; -@var{ps-enc} must be mentioned as a header file for the font in -@samp{psfonts.map}. -@xref{Changing PostScript encodings}. - -@item -s @var{slant} -@opindex -s @var{slant} -@cindex slanted fonts, making -Slant characters to the right by @var{slant}. If @var{slant} is -negative, the letters slope to the left (or they might be upright if you -start with an italic font). - -@item -t @var{tex-enc} -@opindex -t @var{tex-enc} -Use @var{tex-enc} for the target (@TeX{}) encoding of the font. -Ligature and kern information may also be specified in @var{file}. -@var{file} is not mentioned in @file{psfonts.map}. - -@item -T @var{ps-tex-enc} -@opindex -T @var{ps-tex-enc} -Use @var{ps-tex-enc} for both the PostScript and target @TeX{} encodings -of the font. Equivalent to @samp{-p @var{file} -t @var{file}}. - -@item -u -@opindex -u -Use only those characters specified in the @TeX{} encoding, and no -others. By default, Afm2tfm tries to include all characters in the -input font, even those not present in the @TeX{} encoding (it puts them -into otherwise-unused positions, arbitrarily). - -@item -v @var{vpl-file} -@opindex -v @var{vpl-file} -Output a VPL (virtual property list) file, as well as a TFM file. - -@item -V @var{vpl-file} -@opindex -V @var{vpl-file} -Same as @samp{-v}, but the virtual font generated is a pseudo small caps -font obtained by scaling uppercase letters by 0.8 to typeset -lowercase. This font handles accented letters and retains proper -kerning. -@end table - - -@node psfonts.map -@section @file{psfonts.map}: PostScript font catalog - -@flindex psfonts.map -@cindex non-resident fonts -@cindex downloading PostScript fonts -@cindex fonts, downloading - -The @file{psfonts.map} file associates a PostScript font with related -files and constructs. Each line has the format: - -@example -@var{filename} @var{PostScript-name} @var{options} -@end example - -@kindex < @r{font downloading} -For example, the line -@example -rpstrn StoneInformal <StoneInformal.pfb -@end example -@noindent -causes Dvips to download @file{StoneInformal.pfb} (just as if it were -a header file, @pxref{Header files}) if the DVI file (or a virtual -font, @pxref{Virtual fonts}) references the TFM file @samp{rpstrn}. -The PostScript @code{/FontName} of the font defined inside the @samp{pfb} -file should be @code{StoneInformal}. - -@cindex transforming downloaded fonts -@cindex expanded fonts -@cindex wide fonts -@cindex narrow fonts -You can generate transformed fonts with a line like this: -@example -rpstrc StoneInformal <StoneInformal.pfb ".8 ExtendFont" -@end example - -@noindent -@xref{Special font effects}, for a -complete list of font effects. - -@cindex reencoding PostScript fonts -You can change the encoding of the Type 1 font at the PostScript -level with a @samp{ReEncodeFont} instruction, plus the name of the -encoding file. This allows you access to characters that may be present -in the Type 1 font file, but not encoded by default---most of the -preaccented characters, for example. An example: -@smallexample -pstrn8r StoneInformal "TeXBase1Encoding ReEncodeFont" <8r.enc <pstrn8a.pfb -@end smallexample - -@cindex 8r font encoding -@cindex base encoding, recommended -The @samp{8r} encoding mentioned here has been designed to serve as a -base for all downloadable fonts; it allows access to all the characters -commonly present in a Type 1 font. For more details, see the -@file{8r.enc} source file that comes with (and is installed with) Dvips. - -@kindex <[ @r{encoding vector downloading} -You may notice that the same syntax is used for downloading encoding -vectors and Type 1 font files. To make your intentions clear, you can -also use @samp{<[} to explicitly indicate you are downloading an -encoding vector, as in: -@smallexample -pstrn8r StoneInformal "TeXBase1Encoding ReEncodeFont" <[8r.enc <pstrn8a.pfb -@end smallexample - -@flindex .enc @r{extension for encoding vectors} -If the filename of your encoding vector does not end in @samp{.enc}, and -you are using partial font downloading, you must use the @samp{<[} -syntax, or Dvips will not download the font properly. - -@flindex .pfa @r{extension required for partial downloading} -@flindex .pfb @r{extension required for partial downloading} -Similarly, the name of the Type 1 font file itself must have extension -@file{.pfa} or @file{.pfb} for partial downloading to work properly. - -@cindex pfb files, automatically unpacked -When using PFB files, Dvips is smart enough to unpack the binary PFB -format into printable ASCII so there is no need to perform this -conversion yourself. In addition, Dvips scans the font to determine its -memory usage, just as it does for other header files (@pxref{Header -files}). - -@cindex partial font downloading -@cindex downloading fonts partially -If the @samp{j} config file or command-line option is enabled (as it -is by default), @file{StoneInformal.pfb} will be @dfn{partially -downloaded}---only those characters your document actually uses will -be extracted and downloaded, and the remainder discarded. -@xref{Option details}. - -@cindex whole font downloading -@cindex multiple master fonts -@cindex Minion typeface family -@kindex << @r{whole font downloading} -Adobe Multiple Master fonts, such as Minion, cannot be partially -downloaded. To partially download in general, but avoid partial -downloading for individual fonts, use @samp{<<} instead @samp{<}: -@example -pmnr8r Minion <<Minion.pfb -@end example - -Here is a brief summary of how @file{psfonts.map} is read: - -@enumerate -@item If a line is empty or begins with a space, percent, asterisk, -semicolon, or hash mark, it is ignored. - -@item Otherwise, the line is separated into words, where words are -separated by spaces or tabs, except that if a word begins with a double -quote, it extends until the next double quote or the end of the line. - -@item If a word starts with @samp{<<}, it is taken as a font file to be -wholly downloaded. Use this to avoid partial downloading, as described -above. - -@item If a word starts with @samp{<[}, it is taken as an encoding file -to be downloaded. Use this if the name of the encoding file does end in -@samp{.enc}, also as described above. - -@item If a word starts with a @samp{<} character, it is -treated as a header file that needs to be downloaded. If the name ends -in @samp{.pfa} or @samp{.pfb}, it is taken as Type 1 font file that will -be partially downloaded if the @samp{j} option is in effect. There can -be more than one such header for a given font. If a @samp{<} is a word -by itself, the next word is taken as the name of the header file. - -@item If a word starts with a @samp{"} character, it is taken as PostScript -code used in generating that font, and is inserted into the output -verbatim at the appropriate point. (And the double quotes beginning and -ending the word are removed.) - -@item Otherwise the word is a name. The first such name is the TFM -file, that either a DVI file or a virtual font file can refer to. If -there is a second name, it is used as the PostScript name and should -match what is defined in the downloaded file; if there is only one -name, it is used for both the @TeX{} name and the PostScript name. - -@end enumerate - - -@node Color -@chapter Color - -@cindex color - -@cindex Hafner, Jim -Dvips supports one-pass multi-color printing of @TeX{} documents on any -color PostScript device. Initially added by Jim Hafner, IBM Research, -@email{hafner@@almaden.ibm.com}, the color support has gone through many -changes by Tomas Rokicki. Besides the source code support itself, there -are additional @TeX{} macro files: @samp{colordvi.tex} and -@samp{blackdvi.tex}, and corresponding @samp{.sty} versions for use with -@LaTeX{}. - -In this section we describe the use of color from the document -preparer's point of view and then add some instructions on installation -for the @TeX{} administrator. - -@menu -* Color macro files:: TeX macro definitions. -* User-definable colors:: Adding your own colors. -* Color subtleties:: Subtleties in using color. -* Ted Turner:: Printing in black/white after colorizing. -* Color device configuration:: Configuring Dvips for color devices. -* Color support details:: Color support details -@end menu - - -@node Color macro files -@section Color macro files - -@cindex macros for color -@cindex color macros - -All the color macro commands are defined in @samp{colordvi.tex} (or -@samp{colordvi.sty}). To access these macros simply add to the top of -your plain @TeX{} file the command: -@example -\input colordvi -@end example -@noindent -For (the obsolete) @LaTeX{} 2.09, add the @samp{colordvi} style option as in: -@example -\documentstyle[12pt,colordvi]@{article@} -@end example -@noindent -For @LaTeX{}2e, these examples are not applicable. Instead, please see -the documentation for the graphics package -(@url{https://ctan.org/pkg/graphics}), and the epslatex document -(@url{https://ctan.org/pkg/epslatex}). - -@cindex Crayola crayon box -@cindex Pantone colors -@cindex color names, mixed case -These macros provide two basic kinds of color macros: ones for local -color changes (a few words, a single symbol) and one for global color -changes (the whole document). All the color names use a mixed case -scheme to avoid conflicts with other macros. There are 68 predefined -colors, with names taken primarily from the Crayola crayon box of 64 -colors, and one pair of macros for the user to set his own color pattern -(@pxref{User-definable colors}). You can browse the file -@samp{colordvi.tex} for a list of the predefined colors. The comments -in this file also show a rough correspondence between the crayon names -and Pantones. - -A local color command has the form - -@example -\@var{ColorName}@{this is the color @var{ColorName}@} -@end example - -@findex \@var{ColorName} -@noindent -where @var{ColorName} is the name of a predefined color, e.g., -@samp{Blue}. As shown, these macros take one argument, the text to -print in the specified color. This can be used for nested color changes -since it restores the original color state when it completes. For -example: - -@example -This text is normal but here we are \Red@{switching to red, -\Blue@{nesting blue@}, recovering the red@} and back to original. -@end example - -@noindent -@cindex color nesting level -The color nesting level has no hard limit, but it is not advisable to -nest too deeply lest you and the reader lose track of the color history. - -The global color command has the form - -@example -\text@var{ColorName} -@end example - -@noindent -@findex \text@var{ColorName} -These macros take no arguments and changes the default color from that -point on to @var{ColorName}. This of course can be overridden globally -by another such command or locally by local color commands. For example, -expanding on the example above, we might have - -@example -\textGreen -This text is green but here we are \Red@{switching to red, -\Blue@{nesting blue@}, recovering the red@} and back to -original green. -\textCyan -The text from here on will be cyan until -\Yellow@{locally changed to yellow@}. Now we are back to cyan. -@end example - -The color commands will even work in math mode and across math mode -boundaries. This means that if you have a color before going into math -mode, the mathematics will be set in that color as well. In alignment -environments like @code{\halign}, @samp{tabular} or @samp{eqnarray}, -local color commands cannot extend beyond the alignment characters. - -Because local color commands respect only some environment and -delimiter changes besides their own, care must be taken in setting -their scope. It is best not to have them stretch too far. - -At the present time there are no macros for color environments in @LaTeX{} -which might have a larger range. This is primarily to keep the @TeX{} -and @LaTeX{} use compatible. - - -@node User-definable colors -@section User-definable colors - -@cindex user-definable colors -@cindex colors, user-definable - -There are two ways for the user to specify colors not already defined. -For local changes, there is the command @code{\Color} which takes two -arguments. The first argument is four numbers between zero and one and -specifies the intensity of cyan, magenta, yellow and black (CMYK) in -that order. The second argument is the text that should appear in the -given color. For example, suppose you want the words ``this color is -pretty'' to appear in a color which is 50% cyan, 85% magenta, 40% yellow -and 20% black. You would use the command - -@example -\Color@{.5 .85 .4 .2@}@{this color is pretty@} -@end example - -For global color changes, there is a command @code{\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 - -@example -\textColor@{.5 .85 .4 .2@} -The text from now on will be this pretty color -@end example - -@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. - - -@node Color subtleties -@section Color subtleties - -@cindex color subtleties - -Color macros are defined via @code{\special} keywords. As such, they -are put in the @samp{.dvi} file only as explicit message strings to the -driver. The (unpleasant) result is that certain unprotected regions of -the text can have unwanted color side effects. For example, if a color -region is split by @TeX{} across a page boundary, then the footers of -the current page (e.g., the page number) and the headers of the next -page can inherit that color. To avoid this effect globally, users -should make sure that these special regions of the text are defined with -their own local color commands. For example, to protect the -header and footer in plain @TeX{}, use - -@example -\headline@{\Black@{My Header@}@} -\footline@{\Black@{\hss\tenrm\folio\hss@}@} -@end example - -This warning also applies to figures and other insertions, so be careful! - -Of course, in @LaTeX{}, this is much more difficult to do because of the -complexity of the macros that control these regions. This is -unfortunate but inevitable, because @TeX{} and @LaTeX{} were -not written with color in mind. - -Even when writing your own macros, much care must be taken. The macros -that `colorize' a portion of the text work prefix the text work by -outputting one @code{\special} command to turn the color on before the -text, and outputting another @code{\special} command afterwards to -restore the original color. It is often useful to ensure that @TeX{} is -in horizontal mode before the first special command is issued; this can -be done by prefixing the color command with @code{\leavevmode}. - - -@node Ted Turner -@section Printing in black/white after colorizing - -If you have a @TeX{} or @LaTeX{} document written with color macros and -you want to print it in black and white there are two options. On all -(good) PostScript devices, printing a color file will print in -corresponding gray levels. This is useful to get a rough idea of the -colors without using expensive color printing devices. The second -option is to replace the call to input @file{colordvi.tex} with -@samp{blackdvi.tex} (and similarly for the @samp{.sty} files). So in -the above example, replacing the word @samp{colordvi} with -@samp{blackdvi} suffices. @file{blackdvi.tex} defines the color macros -as no-ops, and so will produce normal black/white printing. By this -simple mechanism, the user can switch to all black/white printing -without having to ferret out the color commands. Also, some device -drivers, particularly non-PostScript ones like screen previewers, will -simply ignore the color commands and so print in black/white. -Hopefully, in the future screen previewers for color displays will be -compatible with some form of color support. - - -@node Color device configuration -@section Color device configuration - -@cindex color configuration -@cindex configuration, of 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 -@samp{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 @samp{setcmykcolor} and -@samp{currentcmykcolor} in terms of a RGB equivalent so if your device -only understands RGB, there should be no problem. - -@cindex Phaser printer, used for color calibration -@cindex Tektronix Phaser printer, used for color calibration -The parameters set in this file were determined by comparing the Pantone -chart of a Tektronix Phaser printer with the actual Crayola Crayons. -Because these were defined for a particular device, the actual color -rendition on your device may be very different. There are two ways to -adjust this. One is to use the PAntone chart for your device to rewrite -@samp{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 (@pxref{Configuration file commands}) -for each device that defines, in @samp{userdict}, the color parameters -for those colors that need redefining. - -For example, if you need to change the parameters defining -@samp{Goldenrod} (approximately Pantone 109 on the Phaser) for your -device @samp{mycolordev}, do the following. In the Pantone chart for -your device, find the CMYK values for Pantone 109. Let's say they are -@samp{@{\ 0 0.10 0.75 0.03 @}}. Then create a header file named -@samp{mycolordev.pro} with the commands - -@example -userdict begin -/Goldenrod @{ 0 0.10 0.75 0.03 setcmykcolor@} bind def -@end example - -@noindent -Finally, in @samp{config.mycolordev} add the line - -@example -h mycolordev.pro -@end example - -@noindent -This will then define @samp{Goldenrod} in your device's CMYK values in -@file{userdict} which is checked before defining it in @file{TeXdict} by -@file{color.pro}. (On MS-DOS, you will have to call this file -@file{mycolordev.cfg}.) - -This mechanism, together with additions to @file{colordvi.tex} and -@file{blackdvi.tex} (and the @samp{.sty} files), can also be used to -predefine other colors for your users. - - -@node Color support details -@section Color support details - -To support color, Dvips recognizes a certain set of specials. These -specials start with the keyword @samp{color} or the keyword -@samp{background}, followed by a color specification. - -@menu -* Color specifications:: -* Color specials:: -@end menu - - -@node Color specifications -@subsection Color specifications - -@cindex color specifications - -What is a color specification? One of three things. First, it might be -a PostScript procedure as defined in a PostScript header file. The -@file{color.pro} file defines 64 of these, including @samp{Maroon}. -This PostScript procedure must set the current color to be some value; -in this case, @samp{Maroon} is defined as @samp{0 0.87 0.68 0.32 -setcmykcolor}. - -The second possibility is the name of a color model (initially, one of -@samp{rgb}, @samp{hsb}, @samp{cmyk}, or @samp{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 @samp{TeXcolor} to the color model. Thus, the color -specification @samp{rgb 0.3 0.4 0.5} would generate the PostScript code -@samp{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 -(@samp{Maroon}) above, where no changes to the name are made before it -is sent to the PostScript file. - -The third and final type of color specification is a double quote -followed by any sequence of PostScript. The double quote is stripped -from the output. For instance, the color specification -@samp{"AggiePattern setpattern} will set the `color' to the Aggie logo -pattern (assuming such exists.) - - -@node Color specials -@subsection Color specials - -We will describe @samp{background} first, since it is the simplest. The -@samp{background} keyword must be followed by a color specification. -That color specification is used as a fill color for the background. -The last @samp{background} special on a page is the one that gets -issued, and it gets issued at the very beginning of the page, before any -text or specials are sent. (This is possible because the prescan phase -of Dvips notices all of the color specials so that the appropriate -information can be written out during the second phase.) - -The @samp{color} special itself has three forms. -The first is just @samp{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 @samp{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 @samp{color} special is just @samp{color pop}, -with no color specification; this says to pop the color last pushed on -the color stack from the color stack and set the current color to be -that color. - -Dvips correctly handles these color specials across pages, even when the -pages are repeated or reversed. - -These color specials can be used for things such as patterns or screens -as well as simple colors. However, note that in the PostScript, only -one color specification can be active at a time. For instance, at the -beginning of a page, only the bottommost entry on the color stack is -sent; also, when a color is popped, all that is done is that the color -specification from the previous stack entry is sent. No @samp{gsave} or -@samp{grestore} is used. This means that you cannot easily mix usage of -the @samp{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. - - -@node Index -@unnumbered Index - -@printindex cp - -@bye |