summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/dvips.1
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
committerKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
commitb04c2e1a42573e9735547702356c7b9a769a6855 (patch)
treec0753443f39500a062d7698fe6b94359c813f871 /Master/texmf-dist/doc/man/man1/dvips.1
parentfb0bf13304a356f197bfc1add17f98c07e96f17b (diff)
texmf -> texmf-dist: doc
git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/dvips.1')
-rw-r--r--Master/texmf-dist/doc/man/man1/dvips.1531
1 files changed, 531 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/man/man1/dvips.1 b/Master/texmf-dist/doc/man/man1/dvips.1
new file mode 100644
index 00000000000..c8bd77995d4
--- /dev/null
+++ b/Master/texmf-dist/doc/man/man1/dvips.1
@@ -0,0 +1,531 @@
+.TH DVIPS 1 "4 May 2010"
+.SH NAME
+dvips \- convert a TeX DVI file to PostScript
+.SH SYNOPSIS
+.B dvips
+.RI [ OPTIONS ]
+.IR file [\fB.dvi\fP]
+.SH DESCRIPTION
+THIS MAN PAGE IS OBSOLETE!
+See the Texinfo documentation instead.
+You can read it either in Emacs or with the standalone
+.B info
+program which comes with the GNU texinfo distribution as
+ftp.gnu.org:pub/gnu/texinfo/texinfo*.tar.gz.
+.PP
+The program
+.B dvips
+takes a DVI file
+.IR file [\fB.dvi\fP]
+produced by TeX (or by some other processor such as GFtoDVI) and
+converts it to PostScript, sending the output to a file or directly to a
+printer. The DVI file may be specified without the
+.B .dvi
+extension. Fonts used may either be resident in the printer or defined
+as bitmaps in PK files, or a `virtual' combination of both. If the
+.B mktexpk
+program is installed,
+.B dvips
+will automatically invoke METAFONT to generate fonts that don't already
+exist.
+.PP
+For more information, see the Texinfo manual
+.IR dvips.texi ,
+which should be installed somewhere on your system, hopefully accessible
+through the standard Info tree.
+.SH OPTIONS
+.TP
+.B -a
+Conserve memory by making three passes over the .dvi file instead of two
+and only loading those characters actually used. Generally only useful
+on machines with a very limited amount of memory, like some PCs.
+.TP
+.B -A
+Print only odd pages (TeX pages, not sequence pages).
+.TP
+.B -b num
+Generate
+.I num
+copies of each page, but duplicating the page body rather than using the
+.I #numcopies
+option. This can be useful in conjunction with a header file setting
+.I \ebop-hook
+to do color separations or other neat tricks.
+.TP
+.B -B
+Print only even pages (TeX pages, not sequence pages).
+.TP
+.B -c num
+Generate
+.I num
+copies of every page. Default is 1. (For collated copies, see the
+.I -C
+option below.)
+.TP
+.B -C num
+Create
+.I num
+copies, but collated (by replicating the data in the PostScript file).
+Slower than the
+.I -c
+option, but easier on the hands, and faster than resubmitting the same
+PostScript file multiple times.
+.TP
+.B -d num
+Set the debug flags. This is intended only for emergencies or for
+unusual fact-finding expeditions; it will work only if
+.B dvips
+has been compiled with the DEBUG option. If nonzero, prints additional
+information on standard error. For maximum information, you can use
+`-1'. See the Dvips Texinfo manual for more details.
+.TP
+.B -D num
+Set the resolution in dpi (dots per inch) to
+.IR num .
+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
+.I -Z
+flag should probably also be used.
+.TP
+.B -e num
+Make sure that each character is placed at most this many pixels from
+its `true' resolution-independent position on the page. The default
+value of this parameter is resolution dependent. 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.
+.TP
+.B -E
+makes
+.B dvips
+attempt to generate an EPSF file with a tight bounding box. This only
+works on one-page files, and it only looks at marks made by characters
+and rules, not by any included graphics. In addition, it gets the glyph
+metrics from the
+.I tfm
+file, so characters that lie outside their enclosing
+.I 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 for creating small EPSF
+files for equations or tables or the like. (Note, of course, that
+.B dvips
+output 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 a great deal of care.)
+.TP
+.B -f
+Run as a filter. Read the
+.I .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 you
+must use a pipe, write a shell script that copies the pipe output to a
+temporary file and then points
+.B dvips
+at this file. This option also disables the automatic reading of the
+.I PRINTER
+environment variable, and turns off the automatic sending of control D
+if it was turned on with the
+.I -F
+option or in the configuration file; use
+.I -F
+after this option if you want both.
+.TP
+.B -F
+Causes Control-D (ASCII code 4) to be appended as the very last
+character of the PostScript file. This is useful when
+.B dvips
+is driving the printer directly instead of working through a spooler,
+as is common on extremely small systems. NOTE! DO NOT USE THIS OPTION!
+.TP
+.B -G
+Causes
+.B dvips
+to shift non-printing characters to higher-numbered positions.
+This may be useful sometimes.
+.TP
+.B -h name
+Prepend file
+.I name
+as an additional header file. (However, if the name is simply `-'
+suppress all header files from the output.) This header file gets added
+to the PostScript
+.IR userdict .
+.TP
+.B -i
+Make each section be a separate file. Under certain circumstances,
+.B dvips
+will split the document up into `sections' to be processed
+independently; this is most often done for memory reasons. Using this
+option tells
+.B dvips
+to place each section into a separate file; the new file names 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
+.I -S
+option which sets the maximum section length in pages. 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.
+.TP
+.B -j
+Download only needed characters from Type 1 fonts. This is the
+default in the current release. Some debugging flags trace this operation.
+You can also control partial downloading on a per-font basis, via the
+.B psfonts.map
+file.
+.TP
+.B -k
+Print crop marks. This option increases the paper size (which should be
+specified, either with a paper size special or with the
+.I -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.
+.TP
+.B -K
+This option causes comments in included PostScript graphics, font files,
+and headers to be removed. This is sometimes necessary to get around
+bugs in spoolers or PostScript post-processing programs. Specifically,
+the %%Page comments, when left in, often cause difficulties. Use of
+this flag can cause some included graphics to fail, since the PostScript
+header macros from some software packages read portions of the input
+stream line by line, searching for a particular comment. This option
+has been turned off by default because PostScript previewers and
+spoolers have been getting better.
+.TP
+.B -l num
+The last page printed will be the first one numbered
+.I num
+Default is the last page in the document. If the
+.I num
+is prefixed by an equals sign, then it (and any argument to the
+.I -p
+option) is treated as a sequence number, rather than a value to compare
+with
+.I \ecount0
+values. Thus, using
+.I -l =9
+will end with the ninth page of the document, no matter what the pages
+are actually numbered.
+.TP
+.B -m
+Specify manual feed for printer.
+.TP
+.B -mode mode
+Use
+.I 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
+.IR mode .
+.TP
+.B -M
+Turns off the automatic font generation facility. If any fonts are
+missing, commands to generate the fonts are appended to the file
+.I missfont.log
+in the current directory; this file can then be executed and deleted to
+create the missing fonts.
+.TP
+.B -n num
+At most
+.I num
+pages will be printed. Default is 100000.
+.TP
+.B -N
+Turns off structured comments; this might 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.
+.TP
+.BR -noomega
+This will disable the use of Omega extensions when interpreting DVI
+files. By default, the additional opcodes
+.I 129
+and
+.I 134
+are recognized by dvips as Omega or pTeX extensions and interpreted as
+requests to set 2-byte characters.
+.TP
+.BR -noptex
+This will disable the use of pTeX extensions when interpreting DVI files.
+By default, the additional opcodes
+.I 130
+and
+.I 135
+are recognized by dvips as pTeX extensions and interpreted as requests to
+set 3-byte characters, and
+.I 255
+as request to change the typesetting direction.
+.sp
+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 pTeX extensions,
+you can switch off the pTeX extension by using
+.BR -noptex ,
+or both by using
+.B -noomega
+(but please do send a bug report if you find such problems - see the bug
+address in the
+.B AUTHORS
+section below).
+.TP
+.B -o name
+The output will be sent to file
+.I name
+If no file name is given (i.e., -o is last on the command line), the
+default name is
+.I file.ps
+where the .dvi file was called
+.IR file.dvi ;
+if this option isn't given, any default in the configuration file is
+used. If the first character of the supplied output file name is an
+exclamation mark, then the remainder will be used as an argument to
+.IR popen ;
+thus, specifying
+.I !lpr
+as the output file will automatically queue the file for printing.
+This option also disables the automatic reading of the
+.I PRINTER
+environment variable, and turns off the automatic sending of control D
+if it was turned on with the
+.I -F
+option or in the configuration file; use
+.I -F
+after this option if you want both.
+.TP
+.B -O offset
+Move the origin by a certain amount. The
+.I offset
+is a comma-separated pair of dimensions, such as
+.I .1in,-.3cm
+(in the same syntax used in the
+.I 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.
+.TP
+.B -p num
+The first page printed will be the first one numbered
+.IR num .
+Default is the first page in the document. If the
+.I num
+is prefixed by an equals sign, then it (and any argument to the
+.I -l
+option) is treated as a sequence number, rather than a value to compare
+with
+.I \ecount0
+values. Thus, using
+.I -p =3
+will start with the third page of the document, no matter what the pages
+are actually numbered.
+.TP
+.B -pp pagelist
+A comma-separated list of pages and ranges (a-b) may be given, which
+will be interpreted as
+.I \ecount0
+values. Pages not specified will not be printed. Multiple
+.B -pp
+options may be specified or all pages and page ranges can be
+specified with one
+.B -pp
+option.
+.TP
+.B -P printername
+Sets up the output for the appropriate printer. This is implemented by
+reading in
+.I config.printername
+, which can then set the output pipe (as in,
+.I !lpr -Pprintername
+as well as the font paths and any other
+.I config.ps
+defaults for that printer only. Note that
+.I config.ps
+is read before
+.I config.printername
+In addition, another file called
+.I ~/.dvipsrc
+is searched for immediately after
+.IR config.ps ;
+this file is intended for user defaults. If no
+.I -P
+command is given, the environment variable
+.I PRINTER
+is checked. If that variable exists, and a corresponding configuration
+file exists, that configuration file is read in.
+.TP
+.B -q
+Run in quiet mode. Don't chatter about pages converted, etc.; report
+nothing but errors to standard error.
+.TP
+.B -r
+Stack pages in reverse order. Normally, page 1 will be printed first.
+.TP
+.B -R[0|1|2]
+Run securely.
+.BR -R2
+disables both shell command execution in
+.I \especial'{}
+(via backticks
+.BR `
+) and config files (via the
+.I E
+option), and opening of any absolute filenames.
+.BR -R1
+, the default, forbids shell escapes but allows absolute filenames.
+.BR -R0
+allows both. The config file option is
+.I z
+.TP
+.B -s
+Causes the entire global output to be enclosed in a save/restore pair.
+This causes the file to not be truly conformant, and is thus not
+recommended, but is useful if you are driving the printer directly and
+don't care too much about the portability of the output.
+.TP
+.B -S num
+Set the maximum number of pages in each `section'. This option is most
+commonly used with the
+.I -i
+option; see that documentation above for more information.
+.TP
+.B -t papertype
+This sets the paper type to
+.IR papertype .
+The
+.I papertype
+should be defined in one of the configuration files, along with the
+appropriate code to select it. (Currently known types include
+.BR letter ,
+.BR legal ,
+.BR ledger ,
+.BR a4 ,
+.BR a3 ).
+You can also specify
+.BR -t " " landscape ,
+which rotates a document by 90 degrees. To rotate a document whose size
+is not letter, you can use the
+.I -t
+option twice, once for the page size, and once for landscape.
+You should not use any
+.I -t
+option when the DVI file already contains a
+.I papersize
+special, as is done by some LaTeX packages, notably hyperref.sty.
+
+The upper left corner of each page in the
+.I .dvi
+file is placed one inch from the left and one inch from the top. Use of
+this option is highly dependent on the configuration file. Note that
+executing the
+.B letter
+or
+.B a4
+or other PostScript operators cause the document to be nonconforming and
+can cause it not to print on certain printers, so the paper size should
+not execute such an operator if at all possible.
+.TP
+.B -T papersize
+Set the paper size to the given pair of dimensions. This option takes
+its arguments in the same style as
+.IR -O .
+It overrides any paper size special in the dvi file.
+.TP
+.B -u psmapfile
+Set
+.I psmapfile
+to be the file that dvips uses for looking up PostScript font aliases. If
+.I psmapfile
+begins with a
+.B +
+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
+.I psmapfile
+has no extension, then
+.B .map
+is added at the end.
+.TP
+.B -U
+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. It is caused by a bug in that interpreter
+that results in `garbage' on the bottom of each character. Not
+recommended unless you must drive this printer.
+.TP
+.B -v
+Print the
+.B dvips
+version number and exit.
+.TP
+.B -V
+Download non-resident PostScript fonts as bitmaps. This requires use of
+`gsftopk' or `pstopk' or some other such program(s) in order to generate
+the required bitmap fonts; these programs are supplied with
+.BR dvips .
+.TP
+.B -x num
+Set the
+magnification ratio to
+.IR num /1000.
+Overrides the magnification specified in the .dvi file. Must be
+between 10 and 100000. Instead of an integer,
+.I num
+may be a real number for increased precision.
+.TP
+.B -X num
+Set the horizontal resolution in dots per inch to
+.IR num .
+.TP
+.B -y num
+Set the
+magnification ratio to
+.IR num /1000
+times the magnification specified in the .dvi file.
+See
+.B -x
+above.
+.TP
+.B -Y num
+Set the vertical resolution in dots per inch to
+.IR num .
+.TP
+.B -z
+Pass
+.B 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.
+.TP
+.B -Z
+Causes bitmapped fonts to be compressed before they are downloaded,
+thereby reducing the size of the PostScript font-downloading
+information. Especially useful at high resolutions or when very large
+fonts are used. Will slow down printing somewhat, especially on early
+68000-based PostScript printers.
+.SH "SEE ALSO"
+mf(1), afm2tfm(1), tex(1), latex(1), lpr(1),
+.IR dvips.texi ,
+http://tug.org/dvips.
+.SH ENVIRONMENT
+Dvipsk uses the same environment variables and algorithms for finding
+font files as TeX and its friends do. See the documentation for the
+Kpathsea library for details. (Repeating it here is too cumbersome.)
+.PP
+KPATHSEA_DEBUG: Trace Kpathsea lookups; set to -1 for complete tracing.
+.PP
+PRINTER: see above.
+.SH NOTES
+PostScript is a registered trademark of Adobe Systems Incorporated.
+.SH AUTHOR
+Tomas Rokicki <rokicki@cs.stanford.edu>; extended to virtual fonts
+by Don Knuth. Path searching and configuration modifications by
+Karl Berry.