Be careful if you're installing this into an existing teTeX or texk
installation.  In most cases you only want to install the xdvi binary
and some config files, not everything "make install" installs.

0. Documentation:

   Did you read the README* files?  And the ones in the texk/xdvik
   subdirectory?


1. Compiling:

   In the directory where this INSTALL file is located, do:

   ./configure --datadir=DATADIR && make

   DATADIR is the directory where the main texmf tree is located.
   To locate this path on a standard teTeX system, use the command:

      kpsewhich --expand-path='$TEXMFMAIN'

   Use that path name *without* the `texmf' component as DATADIR.

   See ./configure --help for an overview of the options available.


2. Installing:

In teTeX, xdvi is a shell script that invokes xdvi.bin.  This means
that you only need to update xdvi.bin, not the xdvi script.

A) System-wide installation:

   In most cases, you'll want to install only the new binary xdvi.bin
   and maybe some configuration files, depending on how outdated your
   existing TeX installation is. Be careful with `make install', since
   this might overwrite existing configuration files.

   a. If you dare (I wouldn't):
      make install
   
   b. Otherwise:
      cp texk/xdvik/xdvi.bin /path/to/bin
      cp texk/xdvik/texmf/* TEXMF_PREFIX/texmf/xdvi
   
      (see above for TEXMF_PREFIX; you could also try
      `locate xdvi.cfg' to see if these files are already
      present on your system).
   
      - Users of teTeX-beta or teTeX > 2.0 won't need to install xdvi.cfg,
	since it's already present in the teTeX installation.

      - Users of teTeX > 1.0: Use the file
        xdvi-teTeX.cfg instead of xdvi.cfg, i.e.:
        cp texk/xdvik/texmf/xdvi-teTeX.cfg /usr/local/texmf/share/lib/xdvi/xdvi.cfg
        That file uses ps2pk.map which will be automatically
        updated by teTeX's `updmap' script.

      - Make sure that the XDVIINPUTS variable (set in the
        system-wide texmf.cnf file or in the environment) contains
        the path to the `texmf' files.

B) Private installation:

   cp texk/xdvik/xdvi.bin /your/private/bindir

   - Make sure that /your/private/bindir appears in your PATH before
     the system-wide directory which contains the original xdvi.bin
     (use `which xdvi.bin' to check this).

   - Make the XDVIINPUTS variable point to the texmf subdirectory
     of the source distribution. E.g. (ba)sh users could put the
     following line into their ~/.profile or ~/.bashrc:
     export XDVIINPUTS="/path-to-xdvik-source/texk/xdvik/texmf/"

     (t)csh users could put the following line into their ~/.(t)cshrc:
     setenv XDVIINPUTS "/path-to-xdvik-source/texk/xdvik/texmf/"

C) post-installation:

   - Please review xdvi.cfg to see what font maps are appropriate for
     you.  Update the texk file database (teTeX users run 'texhash').

   - Users of teTeX 1.x: Use the file
     xdvi-teTeX.cfg instead of xdvi.cfg, i.e.:
     cp texk/xdvik/texmf/xdvi-teTeX.cfg /usr/local/texmf/share/lib/xdvi/xdvi.cfg
     That file uses ps2pk.map which will be automatically
     updated by teTeX's `updmap' script.

   - See texk/xdvik/XDVIFONTS for how to install additional type1
     fonts for xdvi.




Some more details and remarks:
-------------------------------------------

- Please submit bug reports, suggestions etc. to the sourceforge
  xdvik project page:
  http://sourceforge.net/projects/xdvi/

- Installing xdvik is essentially the same as installing any other
  Kpathsea-using program.  Therefore, for the basic steps involved,
  see the file `kpathsea/INSTALL'.

- Be careful if you have older kpathsearch header files in your default
  search path; xdvi has no configure option to link with an existing
  kpathsearch library, and using old headers but a new version of the
  library might lead to conflicts and unresolved symbols. In general,
  you'll want to use/install the new version of kpathsearch.

- If you have Ghostscript 4.0 or 4.01, get 4.02.  Otherwise,
  xdvi will not be able to run gs to show included eps files.  (You can
  fix this bug by adding a line
    .clearerror
  before the `% Close up systemdict.' comment.)

- By default, Ghostscript is used to render PostScript specials.
  To disable this, specify `--without-ps' to configure.
  To use Display PostScript instead of gs, specify `--with-ps=dps'.
  To use NeWS instead of gs, specify `--with-ps=news'.
  (Naturally you must have the dps and news libraries for these to work!)
  You can specify more than one --with-ps option if desired; then Ghostscript
  is used last.

- Xdvik needs Xt/Xaw. If you are using an HP, IBM, or
  other system that does not include the Xaw library by default,
  consider installing the freely available X11 distribution, available
  from ftp://ftp.x.org and mirrors.

- Things you might want to add to the DEFS or CFLAGS or XCFLAGS Make variables:
  -DA4 to get A4 size windows by default.
  -DALTFONT=\"myfont\" to change the fallback font from cmr10.
  -DBDPI=num to change default resolution to num from 600.
  -DMFMODE=\"mode\" to set the default mode.
  -DSHRINK=\"num\" to change the default shrink factor (yes, a string) from 6.
  -DNOBUTTONS to disable radio buttons for common commands.
  -DNOGREY to disable using grayscale to display shrunken bitmaps 
     (which also works on monochrome monitors).
  -DNOSELFILE to disable the file selector widget.
  -DNOTEXXET to disable DVI opcodes 250 and 251.
   
- The following can be set according to what xdvi's CONTROL-P command
  reports for `bitord' and `Unit' for your most common display:
     bitord = 1  =>  -DMSBITFIRST
     Unit = 32   =>  -DBMLONG
     Unit = 16   =>  -DBMSHORT
  If this makes any substantial performance difference in your
  environment, please let us know.


In case of problems:
-------------------------------------------

- If you run out of file descriptors (``Too many open files''),
  typically when MakeTeXPK is invoked, you may need to recompile the
  kernel on your system (e.g., SunOS).  Alternatively, the ulimit command
  might allow you to increase this limit (e.g., Solaris).  xdvi tries to
  close files as necessary to avoid this, but if you use lots of fonts on
  one page, it's unavoidable.

- SCO: download libXaw from sosco.sco.com:/TLS/tls005.tar.Z.
  <lieder@skyler.mavd.honeywell.com>

- Tadpole Sparcbook: Comes with obsolete X11 libraries in
  /usr/openwin/lib. You must install more recent libraries.
  <ato@bellcore.com>
