                  IDVI 1.1 INSTALLATION GUIDE

These are the installation notes for IDVI version 1.1.
Complete documentation and examples can be found at the URL
<http://www.geom.umn.edu/java/idvi/>.  See the URL
<http://www.geom.umn.edu/java/idvi/userguide/releasenotes.html>
for a list of changes between versions 1.0 and 1.1.

A full IDVI installation consists of two parts: local files and
server files.  The local files are a few scripts and libraries,
and are used when preparing dvi files for presentation on the
web.  The server files are a package of java classes and a copy
of all or part of the pk font files from your TeX installation,
and are used by the Java applet when presenting dvi files in a
browser window.  The local files use about 1.7MB.  The base set
of server files uses about .5MB.  If you choose to copy all of
your pk font files to the server, they may use another 8MB,
depending on how many fonts are installed on your system.

Some limitations:
	IDVI requires a unix system, because the Java portions
	of the application are controlled by shell scripts.
	
	IDVI requires a java interpreter.  Usually, the interpreter
	which is built into Netscape will work.  However, the
	interpreter is broken in version 3.01 of Netscape, and 
	under Linux.  If you have version 3.01 of Netscape or
	Linux, then you need to obtain and install the Java
	Developer's Kit (JDK).  The JDK is available for Solaris 
	at <http://www.javasoft.com/products/JDK/1.0.2/index.html>,
	and for Linux at <http://www.blackdown.org/java-linux.html>.

    The DVI viewer applet (which people use to view your dvi
    files on the web) seems to really stress most Java runtime
    environments.  In particular, it has some trouble running
    inside Netscape for Macintosh, and has some display problems
    running inside Netscape for Windows NT.

    The software doesn't know how to deal with virtual fonts.
    It has been suggested to me that `dvicopy' can be used to
    remove references to virtual fonts.

    Ghostscript and PBMPlus are required for the processing of
    encapsulated postscript images.  Unzip is required for the
    installation script.

Here are the steps necessary for installation:


1. EDIT THE MAKEFILE

Define the variables in the first few lines of the file
`Makefile' as follows:

 FONTSOURCE  The name of a directory containing pk font files,
             either directly or in subdirectories.  These files
             must have names of the form "cmr10.300pk".  The
             location of this directory depends on the TeX
             installation on your system, and might be something
             like "/usr/tex/fonts/pk" or
             "/usr/local/lib/TeX/pk".

             If this directory contains any subdirectories, then
             a directory will be created in the IDVILIB directory
             containing soft links to each of the font files in
             the FONTSOURCE hierarchy, since the software itself
             will not find fonts in subdirectories.  The process
             of creating these links may take a noticeable
             amount of time during the `make install' phase.

 DPI         The dots-per-inch of the pk font files in the
             directory FONTSOURCE (usually 300).

 IDVILIB     The name of the directory where libraries should
             be installed (usually /usr/local/lib/idvi).

 IDVIBIN     The name of the directory where binaries should be
             installed (usually /usr/local/bin).

 IDVIWWW     The URL of the directory on your web server where
             class files and pk font files should be installed
             (something like "http://my.server/lib/idvi").

 IDVIWWWDIR  The name of the above directory as part of your
             filesystem (something like "/usr/www/lib/idvi").

 NETSCAPE    The name of a netscape 2.0 or 3.0 executable.
             (It is best to find the actual executable rather than
             a wrapper script, since a wrapper script may change
             the CLASSPATH out from under us, or not pass strange
             parameters through to netscape correctly.)
 
 JAVA        The name of a Java interpreter.  If you have Netscape
			 2.0 or 3.0 and are not using Linux, then the default
			 value will work.  Otherwise, change this to the full
			 name of the Java interpreter included with the JDK
			 (something like ..../bin/java).

 DEFAULTS    Any default options for the `idvi' and `idvi.local'
             commands.  If your server appends a suffix other
             than "index.html" to directory URLs, for example,
             then you can specify that suffix here.  (If the suffix
             is "welcome.html", then use "-index welcome.html".)


2. BUILD THE SCRIPTS

Type `make' to configure the scripts `idvi' and `copyfont' using
the variables defined in step 1.


3. CHECK THE INSTALLATION COMMANDS

Type `make -n install' and `make -n installwww' to check that
the commands `make install' and `make installwww' won't do
anything terrible.  (They won't -- do this for your own peace of
mind.)


4. INSTALL THE SOFTWARE

If you are installing version 1.1 over a version 1.0 install,
type `make install' and `make installwww' as suggested below,
and skip ahead to Section 6.

Type `make install' to copy the scripts `idvi' and `idvi.local'
to the directory IDVIBIN, to copy the files `jdkclasses.zip',
`idviclasses.zip', `images.prefix', `fonts.prefix', `copyfont',
`template.html', and `psheader.ps' to the directory IDVILIB, and
to create a directory in IDVILIB containing links to the pk font
files in FONTSOURCE (if FONTSOURCE has any subdirectories).
These steps can be carried out one at a time, using
`make installbin', `make installlib', and `make installfonts'.

Type `make installwww' to copy the classes contained in the
archive `idviclasses.zip' to the directory IDVIWWWDIR/classes,
and to create a directory on the server for pk font files.



5. MAKE A DECISION ABOUT FONTS

There are several ways of making pk font files available to your
web server.  The simplest is to just copy your whole collection
of pk font files to the server, using `make installwwwfonts'.
This will take a while, and will probably use around 8MB of
space on your server.  However, it doesn't pose any difficult
problems about file permissions, and you never have to worry
about it again.

If you don't copy all of your pk font files to the server ahead
of time, then they will be copied by the `idvi' script as they
are needed.  This is accomplished with a separate script, called
`copyfont'.  This will only work if you are the sole user of
`idvi', or if all users of `idvi' will have write permission to
the IDVIWWWLIB directory.  If you must use this option, try
creating a new group (`idviusers'?).  Make this the group of the
directory IDVIWWWLIB/pk, make the directory group writable, and
add users to the group at their request.

There is one other possibility.  If the directories FONTSOURCE
and IDVILIB are visible from your web server (this is unusual)
then you can set IDVIWWWDIR equal to IDVILIB, and IDVIWWW equal
to the URL for the IDVILIB directory (and type `make installbin'
and `make installlib' again).  Then no fonts will ever need to
be copied.


6. TEST THE INSTALLATION

You can test the installation in three ways.

Local viewing:  To test local viewing after a `make install' has
completed, type `make test'.  HTML files will be prepared in the
directory `testdir' using the script `idvi.local', and Netscape
will be launched with a request to view the files produced by
the script.  You should see a list of some features of IDVI in
the browser window.  (Use xdvi to look at the file test.dvi for
another view of the same file).  Exit from Netscape after this
test.

Web viewing:  To test viewing on the web after `make install'
and `make installwww' have completed, type `make testwww'.  HTML
files will be prepared in the directory `IDVIWWWDIR/test' using
the script `idvi', and Netscape will be launched with a request
to view the files produced by the script.  You should see the
same file as in the previous test.  Exit from Netscape after
this test.

Postscript files:  To test the inclusion of postscript images in
dvi files, type `make testepsf'.  HTML files and GIF images will
be prepared in the directory `testepsfdir' using the script
`idvi.local', and Netscape will be launched with a request to
view the files produced by the script.  You will see a similar
file, but including a postscript image of an octahedron.  Exit
from Netscape after this test.  (This portion of the software is
the most fragile.  It requires that both Ghostscript and PBMPlus
are installed on your machine.  If it does not work, take a look
at the script `images.prefix' to see if you can fix the problem.)

After testing, you can use `make clean' to remove the test
directories `testdir', `testepsfdir', and `IDVIWWWDIR/test', and
the configured scripts `idvi' and `copyfont'.


6. MAKE SURE THAT USERS CAN USE THE SOFTWARE

If the directory IDVIBIN is not in the standard path, then
either let users know where it is, add the directory IDVIBIN to
the standard path, or put soft links to the commands `idvi' and
`idvi.local' in IDVIBIN into a directory such as /usr/local/bin
which is in the standard path.

If you wish to allow users to prepare dvi files for local
viewing using idvi.local, then Netscape must be able to find the
IDVI class files.  This is done by adding IDVILIB/idviclasses.zip
to the CLASSPATH environment variable passed to Netscape.
You could do this by putting a line such as
    CLASSPATH=/usr/local/lib/idvi/idviclasses.zip
into the system login script, or by putting a similar line into
a carefully written Netscape wrapper script, or by encouraging
users to put such a line into their own .login script.  The
online documentation for idvi takes the last approach.

Putting the IDVI class files into the standard class path has
another advantage, in that your users will be able to view files
on the web which are presented using IDVI, without having to
wait for the browser to download the IDVI software.

Full documentation for the scripts `idvi' and `idvi.local' is
at <http://www.geom.umn.edu/java/idvi/userguide/>.


7. IF YOU NEED TO UNINSTALL IDVI

If you need to uninstall IDVI, you can use the installation
makefile to remove all of the files which it installed earlier.
(You may have to remove some empty directories by hand, however.)

Type `make uninstall' and `make uninstallwww' to remove the IDVI
shell scripts, class files, and libraries.  Type `make uninstallfonts'
and `make uninstallwwwfonts' to remove the links to pk font files
and the pk font files which have been copied to the server.
