path: root/Build/source/texk/dvipsk/vms/dvips.hlp

1  DVIPS

! Modified 07-Jul-1996 - EJG
! Fix description of filter (can write to stdout, but not read from stdin!
! Change mode description, landscape used with others just gives
! landscape. So took that out. Removed warning about quotes (not
! necessary). Added tabloid.
! Changed qualifier ctrl_d to ctrld to agree with cld file
! Changed default for inc_com to be noinc_com to agree with dvips
! Fix header qualifier
!
! Added comment about the manual to front and also under the
! special heading.

The dvips  program converts a TEX dvi file into a PostScript file for
printing or distribution.  Seldom has such a seemingly easy programming
task required so much effort. The dvips program has a number of features
that set it apart from other PostScript drivers for TEX.  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. 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.

A manual for dvips may be printed with the command:

     printps tex_root:[local]dvips.ps

In this manual, the command line options are for the unix variant
of dvips. Our version has the qualifiers as detailed in this help
file. Also, some of the latest options are not in the manual (in
particular, the /hyperps option).

    usage:
         DVIPS filename[.dvi]

2 /COPIES
    /COPIES=num
    
    Generate num copies of every page.  Default is 1. 
    (For collated copies, see the /COLLATE option.)

2 /DEBUG
    /DEBUG=num
    
    Set  the  debug  flags.  This  is  intended  only  for 
    emergencies  or  for  unusual  fact-finding  expeditions;  it 
    will  work  only  if  dvips    has  been  compiled  with  the 
    DEBUG option.  Use

        num=1   for special
        
        num=2   for paths

        num=4   for fonts

        num=8   for pages

        num=16  for headers

        num=32  for font compression

        num=64  for files

        num=128 for memory allocation

      Use a value of -1 for maximum output.

2 /MAXDRIFT 
    /MAXDRIFT=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 (it is the
    number of entries in the list [100, 200, 300, 400, 500, 600, 800,
    1000, 1200, 1600, 2000, 2400, 2800, 3200, : : :] 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.

2 /FILTER
    
    Run  as  a  filter writing the output to the standard output.
    (The input must still be specified as the argument.)

2 /LAST
    /LAST=num

    The last page printed will be the first one numbered num.  Default
    is the last page in the document.


2 /MANUAL

   Specify manual feed for printer.

2 /NUMBER
     /NUMBER=num
     At most num pages will be printed.  Default is 100000.

2 /OUTPUT
     /OUTPUT=filename.ext
  
    The output will be sent to file name.  If no file name is given,
    the default name is file.ps   where the dvi   file was called
    file.dvi .

2 /START
     /START=num

    The  first  page  printed  will  be  the  first  one  numbered 
    num.  Default  is  the  first page in the document.

2 /QUIET

    Run  in  quiet  mode.   Don't  chatter  about  pages  converted, 
    etc.;  report  nothing  but errors to standard error.

2 /REVERSE

    Stack pages in reverse order.  Normally, page 1 will be printed
    first.

2 /SAV_RES
   
    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.

2 /MODE
    /MODE=modename

    This sets the paper mode to modename.  Currently, the only modes
    allowable are 

    "letter", which selects an 8.5 by 11 inch page, 
    "a3", which selects an a3 sized page, 
    "a4" , which selects an a4 sized page, 
    "legal", which selects an 8.5 by 14 inch page,
    "ledger", which selects an 11 by 17 inch page, and 
    "tabloid", which selects a 17 by 11 inch page, and
    "landscape", which rotates a letter size document by 90 degrees. 


    The default mode is "letter". The  upper left corner of each page in
    the dvi file is placed one inch from the left and one inch from the top.

2 /MAGNIFICATION
    /MAGNIFICATION=num

    Set the magnification ratio to num/1000.  Overrides the
    magnification specified in the dvi   file.  Must be between 10 and
    100000.

2 /COLLATE
    /COLLATE=num
     
    Create num copies, but collated (by replicating the data in the
    PostScript file). Slower than the /COPIES option, but easier on
    the hands, and faster than resubmitting the same PostScript file
    multiple times.

2 /DPI
    /DPI=num

    Set  the  resolution  in  dpi  (dots  per  inch)  to  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 /COMPRESS flag should probably also
    be used.

2 /CTRLD

    Causes  Control-D  (ASCII  code  4)  to  be  appended  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 extremely small systems. 
    Otherwise, it is not recommended.

2 /INC_COM
     /INC_COM
     /NOINC_COM (default)

    /NOINC_COM 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. 

2 /COMMENT
   /COMMENT (default)
   /NOCOMMENT
   
    /NOCOMMENT 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.

2 /PRINTER
    /PRINTER=printername

    Sets  up  the  output  for  the  appropriate  printer. This is
    implemented  by  reading  in  config.printername , which can set
    various parameters such  as the font paths and any other defaults
    for that printer only.  It is recommended that all standard
    defaults go in the one master config.ps file and only things that
    vary printer to printer go in the config.printername files. Note 
    that  config.ps  is  read  before  config.printername. In 
    addition,  another file called "/.dvipsrc   is searched for
    immediately after config.ps;  this file is intended for user
    defaults.  If no /PRINTER command is given, the environment
    variable PRINTER is  checked.  If  that  variable  exists,  and  a 
    corresponding  configuration  file exists, that configuration file
    is read in.

2 /HEADER
    /HEADER=(file1,file2,...)
    /NOHEADER

    Prepend file1, file2, ... as additional header files.
    This header file gets added to the PostScript userdict.
    With /NOHEADER, suppress all header output.


2 /VM_SAVE       
     /VM_SAVE (default)
     /NOVM_SAVE
    
    /NOVM_SAVE disables 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, and 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.

2 /H_DPI
     /H_DPI=num

    Set the horizontal resolution in dots per inch to num.


2 /V_DPI
     /V_DPI=num

    Set the vertical resolution in dots per inch to num.

2 /COMPRESS

    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.

2 /ABSOLUTE

    Makes references to page numbers absolute (rather than TeX
    page numbers).

2 /EPSF
    /EPSF
    /NOEPSF (default)

    /EPSF makes 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 tfm file, so characters that lie 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 for creating small EPSF files for equations
    or tables or the like. (Note, of course, that 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.)


2 /PRESCAN
    /PRESCAN
    /NOPRESCAN (default)

    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.

2 /PAGECOPIES
    /PAGECOPIES=num (default=1)

    Number of times to print each page. Executes the postscript
    for each page this number of times (unlike /COPIES which
    executes the postscript once and prints multiple times.)

2 /SEPARATE
    /SEPARATE
    /NOSEPARATE (default)

    Make each section be a separate file.  Under certain
    circumstances, dvips will split the document up into
    `sections' to be processed independently; this is most often
    done for memory reasons.  Using this option tells dvips to
    place each section into a separate file; the new file names
    are created 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 /SEC_SIZE 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.

2 /CROPMARKS
    /CROPMARKS
    /NOCROPMARKS (default)

    Print crop marks. This option increases the paper size
    (which should be specified, either with a paper size special
    or with the /PSIZE 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.


2 /SEC_SIZE
    /SEC_SIZE=number

    Set the maximum number of pages in each `section'. This
    option is most commonly used with the /SEPARATE option; see
    that documentation above for more information.


2 /HELP
    /HELP

    Given with a dummy file name, causes dvips to output a one
    page listing of options in unix form. Not very useful!

    

2 /MAKEFONT
    /MAKEFONT (default)
    /NOMAKEFONT

    The /NOMAKEFONT option turns off the automatic font
    generation facility.  If any fonts are missing, commands to
    generate the fonts are appended to the file missfont.log in
    the current directory; this file can then be executed and
    deleted to create the missing fonts.

2 /PSIZE
    /PSIZE="dim,dim"

    Set the paper size to the given pair of dimensions.  This
    option takes its arguments in the same syntax as the
    papersize special, for example 8.5in,11in. It overrides any
    paper size special in the dvi file. The dimensions must
    resolve to a papersize specified in the configuration files.


2 /POFFSET
    /POFFSET="dim,dim"

    Move the origin by a certain amount. The offset is a
    comma-separated pair of dimensions, such as .1in,-.3cm (in
    the same syntax used in the papersize special). The origin
    of the page is shifted from the default position (of one inch
    down, one inch to the right from the upper left corner of the
    paper) by this amount.


2 /SECURE
    /SECURE
    /NOSECURE (default)

    With the /SECURE option, dvips will not attempt to open pipes
    or run commands (such as commands to make fonts).

2 /ODDPAGES
    /ODDPAGES
    /NOODDPAGES (default)

    Print only odd pages (TeX pages, not sequence pages).

2 /EVENPAGES
    /EVENPAGES
    /NOEVENPAGES (default)

    Print only even pages (TeX pages, not sequence pages).

2 /DOWNLOADPS
    /DOWNLOADPS
    /NODOWNLOADPS (default)

    Downloadable postscript fonts are set in PK (compressed
    bitmap) format.

2 /HYPERPS
    /HYPERPS
    /NOHYPERPS (default)

    Outputs \specials containing hyperlinks to the output file as
    pdf marks embedded in postscript comments. These can then be
    turned into hyperlinks with Adobe Distiller and viewed with
    Adobe Acrobat.

2 Specials 

    The specials are described in the manual which may be printed
    with the command

         printps tex_root:[local]dvips.ps

    In this manual, the command line options are for the unix
    variant of dvips. Our version has the qualifiers as detailed
    in this help file. Also, some of the latest options are not
    in the manual (in particular, the /hyperps option).