summaryrefslogtreecommitdiff
path: root/Build/source/texk/dvipsk/dvips.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/dvipsk/dvips.texi')
-rw-r--r--Build/source/texk/dvipsk/dvips.texi4738
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