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.
In the examples below, `$' represents the shell prompt.

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:

   a. If you dare (I wouldn't):
      $ make install
   
   b. Otherwise:
      $ cp texk/xdvik/xdvi.bin /path/to/bin
      $ cp texk/xdvik/texmf/* DATADIR/texmf/xdvi

      See above for DATADIR; 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

      - Make sure that the XDVIINPUTS variable set in the system-wide
        texmf.cnf file, or in the environment (e.g. in your .profile)
        contains the path to the directory DATADIR/texmf/xdvi, and
        to the file ps2pk.map (usually in DATADIR/texmf/dvips);
        e.g. by setting:
	XDVIINPUTS = .;$TEXMF/{xdvi,dvips//}

   c. Update the kpathsea file database (teTeX users run 'texhash').

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 that 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/"

   - Users of teTeX > 1.0 should move the file xdvi-teTeX.cfg to xdvi.cfg:
     $ cd /path-to-xdvik-source/texk/xdvik/texmf/
     $ mv xdvi.cfg xdvi.cfg-bak
     $ mv xdvi-teTeX.cfg xdvi.cfg

   - Update the kpathsea file database (teTeX users run 'texhash').

C) post-installation:

   - Users of teTeX < 1.0 or other systems, please review xdvi.cfg
     to see what font maps are appropriate for you.
   - If you observe that xdvik is still generating PK versions of
     fonts that you think you have Type1 versions of, please consult
     texk/xdvik/README.t1fonts for more information on how to configure
     xdvik correctly for Type1 fonts.


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.

- In the unlikely case that you still have Ghostscript 4.0 or 4.01,
  get a more current version.  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 (at least) 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 its 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 the output of
  xdvi -debug PK
  reports for `bit order' and `bitmap unit' (in the section
  `Xserver properties info') 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:
-------------------------------------------

- See kpathsea/INSTALL for common system-dependent 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>
