diff options
author | Karl Berry <karl@freefriends.org> | 2013-04-07 18:26:53 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2013-04-07 18:26:53 +0000 |
commit | b04c2e1a42573e9735547702356c7b9a769a6855 (patch) | |
tree | c0753443f39500a062d7698fe6b94359c813f871 /Master/texmf-dist/doc/man/man1/dvips.1 | |
parent | fb0bf13304a356f197bfc1add17f98c07e96f17b (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.1 | 531 |
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. |