XDVI(1)                                                   XDVI(1)

NAME
       xdvi - DVI Previewer for the X Window System

SYNOPSIS
       xdvi  [+[page]] [-s shrink] [-S density] [-nogrey] [-gamma
       g] [-install] [-noinstall] [-p  pixels]  [-margins  dimen]
       [-sidemargin  dimen]  [-topmargin  dimen] [-offsets dimen]
       [-xoffset  dimen]  [-yoffset  dimen]  [-paper   papertype]
       [-altfont  font]  [-nomakepk]  -mfmode mode-def[:dpi] [-l]
       [-rv] [-expert]  [-shrinkbuttonn  shrink]  [-mgs[n]  size]
       [-warnspecials]   [-hush]   [-hushchars]  [-hushchecksums]
       [-hushspecials] [-safer]  [-fg  color]  [-bg  color]  [-hl
       color]  [-bd color] [-cr color] [-bw width] [-grid1 color]
       [-grid2  color]  [-grid3  color]  [-bw  width]   [-display
       host:display]    [-geometry    geometry]    [-icongeometry
       geometry]   [-iconic]   [-font   font]   [-keep]   [-copy]
       [-thorough]    [-nopostscript]   [-noscan]   [-allowshell]
       [-noghostscript]  [-nogssafer]  [-gsalpha]   [-interpreter
       path]    [-gspalette   palette]   [-underlink]   [-browser
       WWWbrowser] [-base base URL] [-debug  bitmask]  [-version]
       [dvi_file]

DESCRIPTION
       xdvi is a program which runs under the X window system. It
       is used to preview dvi files,  such  as  are  produced  by
       tex(1).

       This  program  has  the  capability  of  showing  the file
       shrunken by various (integer)  factors,  and  also  has  a
       ``magnifying  glass'' which allows one to see a small part
       of the unshrunk image momentarily.

       Before displaying any page or part thereof, it  checks  to
       see if the dvi file has changed since the last time it was
       displayed.  If this is the case, then xdvi will reinitial-
       ize  itself for the new dvi file.  For this reason, expos-
       ing parts of the xdvi window while TeX is  running  should
       be  avoided.  This feature allows you to preview many ver-
       sions of the same file while running xdvi only once.

       In addition to using keystrokes to move within  the  file,
       xdvi  provides  buttons  on  the right side of the window,
       which are synonymous with various sequences of keystrokes.

       xdvi  can  show  PostScript<tm>  specials  by any of three
       methods.  It will try first to use Display PostScript<tm>,
       then  NeWS,  then it will try to use Ghostscript to render
       the images.  All of these  options  depend  on  additional
       software  to work properly; moreover, some of them may not
       be compiled into this copy of xdvi.

       For performance reasons, xdvi does not  render  PostScript
       specials in the magnifying glass.

       If  dvi_file  is not specified, a file-selection widget is
       popped up for you to choose the dvi file.

OPTIONS
       In addition to specifying the dvi file  (with  or  without
       the  .dvi  extension), xdvi supports the following command
       line options.  If the option begins with a `+' instead  of
       a  `-',  the  option is restored to its default value.  By
       default, these options can be set via the  resource  names
       given in parentheses in the description of each option.

       +page  Specifies  the  first  page to show.  If + is given
              without a number, the last  page  is  assumed;  the
              first page is the default.

       -allowshell
              (.allowShell)  This option enables the shell escape
              in PostScript  specials.   (For  security  reasons,
              shell  escapes  are disabled by default.)  This op-
              tion should be rarely used; in particular it should
              not be used just to uncompress files: that function
              is done automatically if the file name ends in  .Z,
              .gz, or .bz2 Shell escapes are always turned off if
              the -safer option is used.

       -altfont font
              (.altFont) Declares a default font to use when  the
              font in the dvi file cannot be found.  This is use-
              ful, for example, with PostScript <tm> fonts.

       -background color
              (.background) Determines the  color  of  the  back-
              ground.  Same as -bg.

       -base base URL
              (.urlBase)  Sets  the  base URL value that external
              links given in the dvi file are assumed relative to
              -  normally  this should be the URL of the document
              itself (?).

       -bd color
              (.borderColor) Determines the color of  the  window
              border.

       -bg color
              (.background)  Determines  the  color  of the back-
              ground.

       -bordercolor color
              Same as -bd.

       -borderwidth width
              (.borderWidth) Specifies the width of the border of
              the window.  Same as -bw.

       -browser WWWbrowser
              (.wwwBrowser) Defines the World Wide Web browser to
              be used to handle external URL's, for example mosa-
              ic.   If  neither the command-line option nor the X
              resource are set,  uses  the  environment  variable
              WWWBROWSER.

       -bw width
              (.borderWidth) Specifies the width of the border of
              the window.

       -copy  (.copy) Always use the copy operation when  writing
              characters to the display.  This option may be nec-
              essary for correct operation on  a  color  display,
              but  overstrike  characters  will be incorrect.  If
              greyscale anti-aliasing is in use, the -copy opera-
              tion  will  disable the use of colorplanes and make
              overstrikes come out incorrectly.  See also  -thor-
              ough.

       -cr color
              (.cursorColor)  Determines the color of the cursor.
              The default is the color of the page border.

       -debug bitmask
              (.debugLevel) If nonzero, prints additional  infor-
              mation  on standard output.  The number is taken as
              a set of independent bits.  The meaning of each bit
              follows.  1=bitmaps;  2=dvi translation; 4=pk read-
              ing; 8=batch operation; 16=events; 32=file opening;
              64=PostScript  communication;  128=Kpathsea stat(2)
              calls; 256=Kpathsea hash table lookups;  512=Kpath-
              sea path definitions; 1024=Kpathsea path expansion;
              2048=Kpathsea searches.  To trace everything having
              to  do  with  file searching and opening, use 4000.
              Some of these debugging options are  actually  pro-
              vided  by  Kpathsea.   See the Debugging section in
              the Kpathsea manual.

       -density density
              (.densityPercent) Determines the density used  when
              shrinking  bitmaps  for fonts.  A higher value pro-
              duces a lighter font.  The default value is 40.  If
              greyscaling is in use this argument does not apply;
              use -gamma instead.  See also the `S'.   keystroke.
              Same as -S

       -display host:display
              Specifies  the  host and screen to be used for dis-
              playing the dvi file.  By default this is  obtained
              from the environment variable DISPLAY.

       -expert
              (.expert)  Prevent the buttons from appearing.  See
              also the `x' keystroke.

       -fg color
              (.foreground) Determines  the  color  of  the  text
              (foreground).

       -foreground color
              Same as -fg.

       -font font
              (*font) Sets the font for use in the buttons.

       -gamma gamma
              (.gamma)  Controls  the  interpolation of colors in
              the greyscale anti-aliasing color palette.  Default
              value is 1.0.  For 0 < gamma < 1, the fonts will be
              lighter (more like the background), and for gamma >
              1,  the  fonts  will be darker (more like the fore-
              ground).  Negative values behave the same way,  but
              use  a slightly different algorithm.  For color and
              greyscale displays; for monochrome,  see  -density.
              See also the `S' keystroke

       -grid1 color
              (.grid1Color)  Determines the color of level 1 grid
              (default as foreground)

       -grid2 color
              (.grid2Color) Determines the color of level 2  grid
              (default as foreground)

       -grid3 color
              (.grid3Color)  Determines the color of level 3 grid
              (default as foreground)

       -geometry geometry
              (*geometry) Specifies the initial geometry  of  the
              window.

       -gspalette palette
              (.palette)  Specifies  the  palette to be used when
              using Ghostscript  for  rendering  PostScript  spe-
              cials.   Possible  values are Color, Greyscale, and
              Monochrome.  The default is Color.

       -gsalpha
              (.gsAlpha) Causes Ghostscript to be called with the
              x11alpha  driver  instead  of  the x11 driver.  The
              x11alpha driver enables anti-aliasing in PostScript
              figures,  for  a nicer appearance.  It is available
              on newer versions of Ghostscript.  This option  can
              also be toggled with the `V' keystroke.

       -hl color
              (.highlight)  Determines the color of the page bor-
              der.  The default is the foreground color.

       -hush  (.Hush) Causes xdvi to  suppress  all  suppressible
              warnings.

       -hushchars
              (.hushLostChars)  Causes  xdvi to suppress warnings
              about references to characters which  are  not  de-
              fined in the font.

       -hushchecksums
              (.hushChecksums)  Causes  xdvi to suppress warnings
              about checksum mismatches between the dvi file  and
              the font file.

       -hushspecials
              (.hushSpecials)  Causes  xdvi  to suppress warnings
              about \special strings that it cannot process.

       -icongeometry geometry
              (.iconGeometry) Specifies the initial position  for
              the icon.

       -iconic
              (.iconic)  Causes  the  xdvi window to start in the
              iconic state.  The default is  to  start  with  the
              window open.

       -install
              (.install)  If  xdvi is running under a PseudoColor
              visual, then (by default) it will check  for  True-
              Color  visuals with more bits per pixel, and switch
              to such a visual if one exists.  If no such  visual
              exists,  it  will  use  the current visual and col-
              ormap.  If -install is selected, however,  it  will
              still  use a TrueColor visual with a greater depth,
              if one is available; otherwise, it will install its
              own colormap on the current visual.  If the current
              visual is  not  PseudoColor,  then  xdvi  will  not
              switch  the  visual  or colormap, regardless of its
              options.  The default value of the install resource
              is  the special value, maybe.  There is no +install
              option.  See also -noinstall, and  the  GREYSCALING
              AND COLORMAPS section.

       -interpreter filename
              (.interpreter)  Use filename as the Ghostscript in-
              terpreter.  By default it uses gs.

       -keep  (.keepPosition) Sets a flag to indicate  that  xdvi
              should not move to the home position when moving to
              a new page.  See also the `k' keystroke.

       -l     (.listFonts) Causes the names of the fonts used  to
              be listed.

       -margins dimen
              (.Margin) Specifies the size of both the top margin
              and side margin.  This determines the ``home''  po-
              sition  of  the  page within the window as follows.
              If the entire page fits in  the  window,  then  the
              margin settings are ignored.  If, even after remov-
              ing the margins from the left, right, top, and bot-
              tom,  the page still cannot fit in the window, then
              the page is put in the window such that the top and
              left  margins  are hidden, and presumably the upper
              left-hand corner of the text on the page will be in
              the  upper  left-hand corner of the window.  Other-
              wise, the text is centered in the window.  The  di-
              mension  should be a decimal number optionally fol-
              lowed by any of the  two-letter  abbreviations  for
              units  accepted by TeX (pt, pc, in, bp, cm, mm, dd,
              cc, or sp).  By default, the unit will be cm  (cen-
              timeters).   See  also -sidemargin, -topmargin, and
              the keystroke `M.'

       -mfmode mode-def
              (.mfMode) Specifies a mode-def string, which can be
              used  in  searching for fonts (see ENVIRONMENT, be-
              low).  Generally, when changing the mode-def, it is
              also  necessary  to change the font size to the ap-
              propriate value for that mode.   This  is  done  by
              adding  a colon and the value in dots per inch; for
              example, -mfmode ljfour:600.  This method overrides
              any  value  given  by the pixelsPerInch resource or
              the -p command-line argument.  The metafont mode is
              also  passed  to metafont during automatic creation
              of fonts.  By default, it is unspecified.

       -mgs size
              Same as -mgs1.

       -mgs[n] size
              (.magnifierSize[n]) Specifies the size of the  win-
              dow  to  be  used  for the ``magnifying glass'' for
              Button n.  The size may be given as an integer (in-
              dicating   that  the  magnifying  glass  is  to  be
              square), or it may be given  in  the  form  widthx-
              height.   See  the MOUSE ACTIONS section.  Defaults
              are  200x150,  400x250,  700x500,   1000x800,   and
              1200x1200.

       -noghostscript
              (.ghostscript)  Inhibits the use of Ghostscript for
              displaying PostScript<tm> specials.  (For this  op-
              tion,  the  logic  of the corresponding resource is
              reversed:     -noghostscript     corresponds     to
              ghostscript:off; +noghostscript to ghostscript:on.)

       -nogrey
              (.grey) Turns off the use of greyscale  anti-alias-
              ing  when printing shrunken bitmaps.  (For this op-
              tion, the logic of the  corresponding  resource  is
              reversed:  -nogrey corresponds to grey:off; +nogrey
              to grey:on.)  See also the `G' keystroke.

       -nogssafer
              (.gsSafer) Normally, if Ghostscript is used to ren-
              der  PostScript  specials,  the  Ghostscript inter-
              preter  is  run  with  the  option  -dSAFER.    The
              -nogssafer option runs Ghostscript without -dSAFER.
              The  -dSAFER   option   in   Ghostscript   disables
              PostScript operators such as deletefile, to prevent
              possibly malicious PostScript programs from  having
              any  effect.   If  the  -safer option is specified,
              then this  option  has  no  effect;  in  that  case
              Ghostscript  is  always run with -dSAFER.  (For the
              -nogssafer option, the logic of  the  corresponding
              resource  is  reversed:  -nogssafer  corresponds to
              gsSafer:off; +nogssafer to gsSafer:on.)

       -noinstall
              (.install) Inhibit the default behavior of  switch-
              ing  to a TrueColor visual if one is available with
              more bits per pixel than the current visual.   This
              option  corresponds  to  a resource of install:off.
              There is no +noinstall option.  See also  -install,
              and the GREYSCALING AND COLORMAPS section.

       -nomakepk
              (.makePk)  Turns  off  automatic generation of font
              files that cannot be found by  other  means.   (For
              this  option,  the  logic  of the corresponding re-
              source  is  reversed:  -nomakepk   corresponds   to
              makePk:off; +nomakepk to makePK:on.)

       -nopostscript
              (.postscript) Turns off rendering of PostScript<tm>
              specials.  Bounding boxes, if known, will  be  dis-
              played  instead.   This  option can also be toggled
              with the `v' keystroke.  (For this option, the log-
              ic  of the corresponding resource is reversed: -no-
              postscript    corresponds    to     postscript:off;
              +postscript to postscript:on.)

       -noscan
              (.prescan)  Normally, when PostScript<tm> is turned
              on, xdvi will do a  preliminary  scan  of  the  dvi
              file,  in  order to send any necessary header files
              before sending the PostScript  code  that  requires
              them.  This option turns off such prescanning.  (It
              will be automatically be turned back on if xdvi de-
              tects any specials that require headers.)  (For the
              -noscan option, the logic of the corresponding  re-
              source  is  reversed:  -noscan corresponds to pres-
              can:off; +noscan to prescan:on.)

       -offsets dimen
              (.Offset) Specifies the size of both the horizontal
              and vertical offsets of the output on the page.  By
              decree of the Stanford TeX Project, the default TeX
              page origin is always 1 inch over and down from the
              top-left page corner, even when non-American  paper
              sizes are used.  Therefore, the default offsets are
              1.0 inch.  The argument dimen should be  a  decimal
              number optionally followed by any of the two-letter
              abbreviations for units accepted by  TeX  (pt,  pc,
              in,  bp,  cm,  mm, dd, cc, or sp).  By default, the
              unit will be cm (centimeters).  See  also  -xoffset
              and -yoffset.

       -p pixels
              (.pixelsPerInch)  Defines  the size of the fonts to
              use, in pixels per inch.  The default value is 600.
              This option is provided only for backwards compati-
              bility; the preferred way of setting the font  size
              is  by  setting the Metafont mode at the same time;
              see the -mfmode option.

       -paper papertype
              (.paper) Specifies the size of  the  printed  page.
              This  may  be  of  the form widthxheight optionally
              followed by a unit, where width and height are dec-
              imal numbers giving the width and height of the pa-
              per, respectively, and the unit is any of the  two-
              letter abbreviations for units accepted by TeX (pt,
              pc, in, bp, cm, mm, dd, cc, or  sp).   By  default,
              the  unit will be cm (centimeters).  There are also
              synonyms which may  be  used:  us  (8.5x11in),  usr
              (11x8.5in), legal (8.5x14in), foolscap (13.5x17in),
              as well as the ISO sizes a1-a7, b1-b7, c1-c7,  a1r-
              a7r (a1-a7 rotated), etc.  The default size is 21 x
              29.7 cm (A4 size).

       -rv    (.reverseVideo) Causes the  page  to  be  displayed
              with  white  characters  on a black background, in-
              stead of vice versa.

       -s shrink
              (.shrinkFactor) Defines the initial shrink  factor.
              The  default  value is 8.  If shrink is given as 0,
              then the initial shrink factor is computed so  that
              the  page  fits  within  the  window (as if the `s'
              keystroke were given without a number).

       -S density
              (.densityPercent) Same as -density, q.v.

       -safer (.safer) This option turns on all available securi-
              ty  options;  it  is  designed for use when xdvi is
              called by a browser that obtains a dvi or TeX  file
              from  another  site.  In the present case, this op-
              tion selects +nogssafer and +allowshell.

       -shrinkbuttonn shrink
              (.shrinkButtonn)  Specifies  that  the  nth  button
              changing shrink factors shall change to shrink fac-
              tor factor.  This is not very usefull in the normal
              run  of  things.   xdvik scales the scaling factors
              according  to  resolution  (currently  300dpi   and
              600dpi).  Here n may be a number from 1 to 4.  Typ-
              ical factors are powers of 2.

       -sidemargin dimen
              (.sideMargin) Specifies the side margin (see  -mar-
              gins).

       -thorough
              (.thorough)  xdvi  will  usually try to ensure that
              overstrike characters (e.g.,  \notin)  are  printed
              correctly.   On monochrome displays, this is always
              possible with one logical operation, either and  or
              or.   On color displays, however, this may take two
              operations, one to set the appropriate bits and one
              to  clear other bits.  If this is the case, then by
              default xdvi will instead use the  copy  operation,
              which  does not handle overstriking correctly.  The
              -thorough option chooses the slower but  more  cor-
              rect choice.  See also -copy.

       -topmargin dimen
              (.topMargin)  Specifies  the top and bottom margins
              (see -margins).

       -underlink
              (.underLink) Underline links.  Default is true.

       -version
              Print information on the version of xdvi.

       -warnspecials
              (.warnSpecials) Causes xdvi to issue warnings about
              \special strings that it cannot process.

       -xoffset dimen
              (.xOffset)  Specifies  the  size  of the horizontal
              offset of the output on the page.  See -offsets.

       -yoffset dimen
              (.yOffset) Specifies the size of the vertical  off-
              set of the output on the page.  See -offsets.

KEYSTROKES
       xdvi recognizes the following keystrokes when typed in its
       window.  Each may optionally be preceded by a (positive or
       negative)  number, whose interpretation will depend on the
       particular  keystroke.   Also,  the  ``Help'',   ``Home'',
       ``Prior'',  ``Next'',  and  arrow cursor keys are synonyms
       for `?', `^', `b', `f', `l', `r', `u', and `d'  keys,  re-
       spectively.

       q      Quits the program.  Control-C and control-D will do
              this, too.

       Q      Quits the program with exit status 2.

       n      Moves to the next page (or to the nth next page  if
              a  number  is given).  Synonyms are `f', Space, Re-
              turn, and Line Feed.

       p      Moves to the previous page (or back n pages).  Syn-
              onyms are `b', control-H, and Delete.

       g      Moves  to the page with the given number.  Initial-
              ly, the first page is assumed to be page number  1,
              but this can be changed with the `P' keystroke, be-
              low.  If no page number is given, then it  goes  to
              the last page.

       P      ``This  is  page  number  n.''  This can be used to
              make the `g' keystroke refer to actual page numbers
              instead of absolute page numbers.

       Control-L
              Redisplays the current page.

       ^      Move to the ``home'' position of the page.  This is
              normally the upper left-hand corner  of  the  page,
              depending  on the margins as described in the -mar-
              gins option, above.

       u      Moves up two thirds of a window-full.

       d      Moves down two thirds of a window-full.

       l      Moves left two thirds of a window-full.

       r      Moves right two thirds of a window-full.

       c      Moves the page so that the point currently  beneath
              the  cursor  is  moved to the middle of the window.
              It also (gasp!) warps the cursor to the same place.

       M      Sets  the margins so that the point currently under
              the cursor is the upper  left-hand  corner  of  the
              text  in  the  page.  Note that this command itself
              does not move the image at all.  For details on how
              the margins are used, see the -margins option.

       s      Changes  the shrink factor to the given number.  If
              no number is given, the smallest factor that  makes
              the  entire  page  fit  in the window will be used.
              (Margins are ignored in this computation.)

       S      Sets the density factor to be used  when  shrinking
              bitmaps.   This  should  be  a number between 0 and
              100; higher numbers produce lighter characters.  If
              greyscaling  mode  is  in  effect, this changes the
              value of gamma instead.  The new value of gamma  is
              the  given  number  divided by 100; negative values
              are allowed.

       t      Toggles to the next unit in a sorted  list  of  TeX
              dimension units for the popup magnifier ruler.

       R      Forces  the dvi file to be reread.  This allows you
              to preview many versions of  the  same  file  while
              running xdvi only once.

       k      Normally  when xdvi switches pages, it moves to the
              home position as well.  The `k' keystroke toggles a
              `keep-position' flag which, when set, will keep the
              same position when moving between pages.  Also `0k'
              and  `1k'  clear  and  set this flag, respectively.
              See also the -keep option.

       x      Toggles expert mode (in which the  buttons  do  not
              appear).   Also  `0x' and `1x' clear and reset this
              mode, respectively.  See also the -expert option.

       G      This key toggles the use of greyscale anti-aliasing
              for  displaying shrunken bitmaps.  In addition, the
              key sequences `0G' and  `1G'  clear  and  set  this
              flag, respectively.  See also the -nogrey option.

       If  given a numeric argument that is not 0 or 1, greyscale
       anti-aliasing is turned on, and the gamma resource is  set
       to  the  value  divided  by  100.  E.g.,  `150G'  turns on
       greyscale and sets gamma to 1.5.

       D      This key toggles the use of grid over the document.
              If  no  number is given, the grid mode toggles.  By
              prepending number, 3 grid levels can be  set.   The
              grid  in  each  level is drawn in the colour speci-
              fied.  See also the -grid1, -grid2, and -grid3  op-
              tions.

       v      This  key  toggles  the rendering of PostScript<tm>
              specials.  If rendering is turned off, then  bound-
              ing  boxes  are displayed when available.  In addi-
              tion the key sequences `0v' and `1v' clear and  set
              this   flag,   respectively.   See  also  the  -no-
              postscript option.

       V      This   key    toggles    tha    anti-aliasing    of
              PostScript<tm> specials when Ghostscript is used as
              renderer.  In addition the key sequences  `0V'  and
              `1V'  clear  and  set  this  flag, See also the +.B
              -gsalpha option.

       F      Read a new dvi file.  A  file-selection  widget  is
              popped up for you to choose the dvi file from.

MOUSE ACTIONS
       If  the shrink factor is set to any number other than one,
       then clicking mouse button 3 will pop  up  a  ``magnifying
       glass''  which shows the unshrunk image in the vicinity of
       the mouse click.  This subwindow disappears when the mouse
       button  is released.  Different mouse buttons produce dif-
       ferent sized windows, as indicated  by  the  -mgs  option.
       Moving  the cursor while holding the button down will move
       the magnifying glass.

       If the cursor is on a hypertext link  (underlined  by  de-
       fault),  then that link overrides the magnifying glass for
       Buttons 1 and 2.  If Button 1 is clicked over a link, then
       xdvi jumps to the target in the current window.  If Button
       2 is clicked over a link, then xdvi opens a new window  on
       the target.

       More  precisely, for internal links, Button 1 jumps in the
       same window to the link, while Button 2 starts  up  a  new
       xdvi on the link.  For external links to dvi files, Button
       1 changes the current xdvi to be reading that file,  while
       Button  2  starts a new xdvi on that file.  For other file
       types, mime.types and mailcap are parsed to determine  the
       viewer;  finally,  if no suitable mailcap entry was found,
       if the WWWBROWSER environment variable is set, or -browser
       was specified on the command line, it is started up on the
       file.

       The scrollbars (if present) behave in  the  standard  way:
       pushing Button 2 in a scrollbar moves the top or left edge
       of the scrollbar to that point and  optionally  drags  it;
       pushing  Button 1 moves the image up or right by an amount
       equal to the distance from the button press to  the  upper
       left-hand corner of the window; pushing Button 3 moves the
       image down or left by the same amount.

SIGNALS
       When xdvi receives a SIGUSR1 signal, it  rereads  the  dvi
       file.

GREYSCALING AND COLORMAPS
       The  greyscale anti-aliasing feature in xdvi will not work
       at its best if the display does  not  have  enough  colors
       available.   This can happen if other applications are us-
       ing most of the colormap (even if they are iconified).  If
       this  occurs,  then  xdvi  will print an error message and
       turn on the -copy option.  This will result in  overstrike
       characters  appearing  wrong;  it  may also result in poor
       display quality if the number of available colors is  very
       small.

       Typically  this  problem  occurs on displays that allocate
       eight bits of video memory per pixel.   To  see  how  many
       bits  per  pixel  your  display  uses, type xwininfo in an
       xterm window, and then click the mouse on the root  window
       when  asked.   The ``Depth:'' entry will tell you how many
       bits are allocated per pixel.

       Displays using at least 15 bits per  pixel  are  typically
       TrueColor  visuals,  which do not have this problem, since
       their colormap is permanently allocated and  available  to
       all  applications.  (The visual class is also displayed by
       xwininfo.)  For more information on visual classes see the
       documentation for the X Window System.

       To alleviate this problem, therefore, one may (a) run with
       more bits per pixel (this may require  adding  more  video
       memory  or  replacing the video card), (b) shut down other
       applications that may be using much of  the  colormap  and
       then  restart  xdvi, or (c) run xdvi with the -install op-
       tion.

       One application which is often the cause of  this  problem
       is Netscape.  In this case there are two more alternatives
       to remedying the situation.  One can run  ``netscape  -in-
       stall''  to  cause Netscape to install a private colormap.
       This can cause colors to change in bizarre ways  when  the
       mouse  is  moved  to  a different window.  Or, one can run
       ``netscape -ncols 220'' to limit  Netscape  to  a  smaller
       number of colors.  A smaller number will ensure that other
       applications have more colors available, but will  degrade
       the color quality in the Netscape window.

ENVIRONMENT
       Please see the kpathsea documentation.

HANDLING OF POSTSCRIPT FIGURES
       xdvi  can  display  PostScript  files  included in the dvi
       file.  Such files are first searched for in the  directory
       where  the  dvi  file  is,  and then using normal Kpathsea
       rules.  There is an exception to this,  however:   if  the
       file  name  begins with a backtick (`), then the remaining
       characters in the file name give a  shell  command  (often
       zcat)  which is executed; its standard output is then sent
       to be interpreted as PostScript.  Note that there is  some
       potential  for security problems here; see the -allowshell
       command-line option.  It is better to use compressed files
       directly (see below).

       If  a  file name is given (as opposed to a shell command),
       if that file name ends in ``.Z'', ``.gz'', or ``.bz2'' and
       if  the  first  two bytes of the file indicate that it was
       compressed with compress(1), gzip(1), or bzip2(1)  respec-
       tively,  then  the  file is first uncompressed with uncom-
       press -c, gunzip -c, or bunzip2 -c, respectively.  This is
       preferred  over  using  a backtick to call the command di-
       rectly, since you do not have to specify  -allowshell  and
       since it allows for path searching.

ENVIRONMENT
       xdvik  uses  the same environment variables and algorithms
       for finding font files as TeX and friends.  See the  docu-
       mentation  for the Kpathsea library for details (repeating
       it here is too cumbersome).  In  addition,  xdvik  accepts
       the following variables:

       DISPLAY
              Specifies which graphics display terminal to use.

       KPATHSEA_DEBUG
              Trace  Kpathsea  lookups; set it to -1 for complete
              tracing.

       MIMELIBDIR
              Directory  containing  the  mime.types   file,   if
              ~/.mime-types does not exist.

       MAILCAPDIR
              Directory containing the .mailcap file, if ~/.mail-
              cap does not exist.

       WWWBROWSER
              The browser used to  open  URL's,  if  neither  the
              -browser  option  nor  the .wwwBrowser resource are
              set.  For more information  on  hyper-TeX  support,
              see the `Hypertext' node in the dvipsk manual.

       TMPDIR The  directory  to  use for storing temporary files
              created when uncompressing PostScript files.

LIMITATIONS
       xdvi accepts many but not all types of PostScript specials
       accepted  by dvips.  For example, it accepts most specials
       generated by epsf and psfig, It does not, however, support
       bop-hook, nor does it do the ``NEAT'' or rotated ``A'' ex-
       ample in the dvips manual.  These restrictions are due  to
       the design of xdvi; in all likelihood they will always re-
       main.

       LaTeX2e color and rotation specials are not currently sup-
       ported.

FILES
       Please see the kpathsea documentation.

COPYRIGHTS
       xdvi  itself  is Copyrighted by Paul Vojta and distributed
       under the X-Consortium license.  xdvi uses the libwww  li-
       brary  of  the  World  Wide Web Consortium, which includes
       computer software creaded and made available by CERN.   It
       also  uses the kpathsea library which is distributed under
       the GNU LIBRARY General Public License.

       THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
       KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
       WARRANTIES OF MERCHANTABILITY, FITNESS  FOR  A  PARTICULAR
       PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL PAUL VOJTA
       OR ANY OTHERS BE LIABLE FOR ANY CLAIM,  DAMAGES  OR  OTHER
       LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTH-
       ERWISE, ARISING FROM, OUT OF OR  IN  CONNECTION  WITH  THE
       SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

SEE ALSO
       X(1), dvips(1), Kpathseadocumentation

AUTHORS
       Eric  Cooper,  CMU,  did  a version for direct output to a
       QVSS. Modified for X by Bob Scheifler, MIT Laboratory  for
       Computer  Science.  Modified  for  X11 by Mark Eichin, MIT
       SIPB. +Additional enhancements by many others.   The  cur-
       rent  maintainer  of the original xdvi is Paul Vojta, U.C.
       Berkeley; the maintainer of the xdvik variant  is  Nicolai
       Langfeldt,  Dept.  of  Math, UiO, Norway, with the help of
       many others.

X Version 11             15 February 1999                       1