##########################################################################
# This program is Copyright (C) 1986-2002 by Jonathan Payne.  JOVE is    #
# provided by Jonathan and Jovehacks without charge and without          #
# warranty.  You may copy, modify, and/or distribute JOVE, provided that #
# this notice is included in all the source files and documentation.     #
##########################################################################

[Updated in May 1996]

HOW TO GET STARTED WITH JOVE:
=============================

JOVE for MSDOS is distributed in two forms.  The source code version
allows you to easily understand and modify JOVE.  The executable
version allows you to easily install JOVE without using a C compiler.
Neither requires the other.

Each distribution may be in the form of a .zip or .zoo archive.  If
you use pkunzip, be sure to use the -d flag to get it to correctly
place files in subdirectories.  In the .zoo file, lines are terminated
with NL (LF), not CR LF.  This may cause some problems for certain DOS
commands such as MORE.

The source distribution for MSDOS (and WIN32 -- Windows/95 and
Windows/NT) is either called jovedoss.zip or given a name indicating
the version (for example, jove416s.zip).  The source archive contains
all the source files needed to compile JOVE on an MSDOS or WIN32
machine.  It differs in three ways from the generic JOVE source
distribution.  First, it is distributed in a conventional MSDOS
format, rather than as a tar file.  Second, certain files are left out
because they are of no use under MSDOS (for example, the X Window
System support) and may not fit the 8.3 naming straitjacket.  Third, a
few files are pre-built on UNIX and included because the tools to
build them are not generally available under MSDOS (for example, the
formatted documentation).  The source distribution for MSDOS can be
built from the generic distribution on UNIX with the command "make
jovedoss.zip".

The executable distribution for MSDOS on the IBM PC is either called
jovedosx.zip or given a name indication the version (like
jove416x.zip).  The executable archive contains all the files needed
to use jove: the executables and the documentation.  Here is quick
description of the files within the archive:

jove.exe        the JOVE executable file
doc\cmds.doc    contains text for the describe-command and describe
                varible command.  Should be moved into the directory
                described under SHAREDIR
doc\jove.man    the complete JOVE manual
doc\jove.doc    the "manpage" for JOVE: describes how to run JOVE
paths.h         This file shows what the default directories JOVE was
                compiled with.  The file itself is not used to run JOVE.
README.dos      This file.

ENVIRONMENT VARIABLES USED BY JOVE:
===================================

COMSPEC
This variable is used to specify the default program to run as the SHELL.
It can be overridden by the JOVE variable "shell".

TMPDIR (or TEMP)
JOVE uses the value of TMPDIR, or if that is not set, TEMP to
determine the directory where it should put its temporary file.  The
default is c:\tmp (set by TMPDIR in the makefile when JOVE was
compiled), and this is probably not what you want.  In general editing
is faster, if TEMP points to a ramdisk, like "set temp=d:".  You have
to know however that the temporary file can grow quite big when
editing many big files at once.  So please make sure that you have
enough space available on your ramdisk.  If JOVE runs out of space on
the device which holds the temporary file, you have to leave the
editor immediately.  You can save your work without any trouble, but
you have to start over.  Please note also that the Large Model version
of JOVE has a big cache for the temporary file in memory, which makes
it quite fast even if you don't have a ramdisk.  It is an MSDOS
convention to use TEMP; use TMPDIR if you intend that the directory
is solely for JOVE.

JOVESHARE
This variable specifies the path to the directory that will contain
(1) cmds.doc (the file of command and variable descriptions used by
the describe-command and desribe-variable commands) and (2) the
system-wide jove.rc (the first file that is sourced (executed) by JOVE
when it starts up).  The default is c:/jove (set by SHAREDIR in the
makefile when JOVE was compiled).

HOME
The directory which is to be considered the user's home (as in UNIX).
The default is the current directory on the current disk when JOVE was
started.  JOVE looks in this directory for the user's jove.rc startup
file (this will be sourced after the system-wide jove.rc, unless HOME
and JOVESHARE are the same).  In filenames, an initial ~/ denotes the
home directory.

METAKEY
If this environment variable is set, JOVE turns on its meta-key variable.

MSDOS ON MACHINES NOT COMPATIBLE WITH THE IBM PC
================================================

JOVE has been ported to MSDOS machines that are not IBM PC clones.
One example for which there is special code is the DEC Rainbow.
Another is the Atari ST (although the specific code for it is not
included in our current source).  Still others are generic MSDOS
machines such as the Nabu 1600.  Although the source code still has
provisions for these, it has not been tested recently and so is
probably no longer quite right.

The next two variables are not used by the IBM PC version, and have to
do with specifying the type of terminal in use on a generic MSDOS
computer.

TERM
This variable should specify the name of the terminal you are using.
For example, if you have a DEC vt-100 terminal attached to your MSDOS
computer, you should give the command "set TERM=vt100" prior to
starting JOVE.

TERMCAP
This environment variable holds the name of a database with
descriptions of different terminal types.  If you are familiar with the
UNIX operating system, you probably know about TERMCAP.  For each
terminal type, specified by TERM, the TERMCAP database holds an entry,
which describes how to set the cursor, how to scroll, and many other
things, for that particular terminal.  A small example TERMCAP file
comes with JOVE.  If your terminal is not included there, you should ask a
local UNIX guru for help.  If you don't have one, you can ask
jovehacks@cs.toronto.edu.


DIFFERENCES BETWEEN JOVE UNDER MSDOS AND UNIX JOVE:
===================================================

The MSDOS version of JOVE currently supports all of the features that
are possible to implement under MSDOS in a reasonable way.  The things
that are missing under MSDOS are:
	spell-buffer (obsolete under MSDOS)
	interactive shells in a window (not possible)

There are however some features added, which are specific to the PC
version:

Variables:
 text-attribute specifies the background and foreground colors of the
    screen.  The default value is 0x07, which stands for white on
    black.  The attribute used for writing to the screen is formed by
    (bg&7)<<4 & (fg&7).

 Mode-line-attribute specifies the background and foreground colors of
    the modeline.  Its default value is 0, and in that case it is drawn
    in reverse video.  If it has any other value, this value is used as
    the attribute in Bios calls.
 (note that on a monochrome monitor the best thing is to leave the
 default colors - anything else can lead to blank screens very easily)

General:
 JOVE on the IBM PC supports the whole 8 bit character set of the IBM PC.
 You can use all the line drawing characters in your files.  It also knows
 about some special foreign characters (Umlaute), which are treated
 correctly as part of words and in case conversions.  It knows about
 and has special bindings for most of the non-ASCII keys (such as the
 function keys and the ALT shift key).

VIDEO MODES ON THE IBM PC UNDER DOS:
====================================

When JOVE is started, it automatically checks which video mode is
currently used, and adjusts itself correspondingly.  This means that
JOVE will work correctly even in 40x25 mode.  If you have an EGA or VGA
card, and want to use a special mode with 25, 28, 43, or 50 lines, set
the environment variable TERM to the value EGAn.  This will tell JOVE
to set the screen in 80xn mode.  The regular 80x25 mode is restored upon
exit.  On a color monitor, you can change the screen colors by using
the commands mentioned above.

SPECIAL KEYS ON THE IBM PC UNDER DOS AND WIN32:
===============================================

JOVE checks to see if an enhanced AT-style keyboard is available and if so
it will recognize use of the F11 and F12 keys plus numerous Alt/Shift/Control
keys that cannot be generated with the basic keyboard BIOS.  This check can
be overridden by setting the enhanced-keyboard variable in the jove.rc file.

JOVE turns Ctrl-Space into NUL.  This makes the keyboard match most others,
and makes it easy to invoke the set-mark command.

JOVE turns a Delete keystroke into a DEL character.  Surprisingly, this isn't
done by the BIOS.  DEL is also generated by Ctrl-BackSpace, so a distinction
is lost.  If you are used to IBM PC conventions, you may wish to bind DEL to
delete-next-character (its standard binding is to delete-previous-character).

JOVE maps the shifted arrow, Insert, Delete, Home, End, PgUp, and PgDn keys
to codes distinct from the unshifted keys.  This allows them to be bound
differently.

If the meta-key variable is on, the ALT key acts like a META key --
any key typed while it is depressed generates an ESC before the normal
code.  Otherwise, any key typed while ALT is depressed generates a special
PCNONASCII code and the scan code for the key.  JOVE supplies a keymap
for the PCNONASCII code.

COMPILING JOVE UNDER MSDOS:
===========================

If JOVE is compiled using "Large Model", it can freely use all of the
available portion of the normal 640kB memory.  If it is compiled using
"Medium Model", all of its data (except for line descriptors) must fit
in 64kB; one consequence is that JOVE's tempfile cache is severely
reduced.  The advantage of Medium Model is that JOVE's object code is
considerably smaller.

JOVE has been compiled (1994 July) with version 3.1 of Borland's C compiler.
Use Makefile.bcc.

JOVE has been compiled with version 8.0 of the Microsoft C compiler
a.k.a. Visual C.  It will probabally also compile with versions 6 or 7
but this has not been confirmed.  Use the makefile called Makefile.msc.

JOVE has been compiled (1996 May) with version 10 of Watcom's C compiler.
Use Makefile.wat.

JOVE has been compiled (1996 May) with version 3.0 of Zortech's C compiler.
Use Makefile.zor.

JOVE once supported MSDOS on hardware that is not IBM PC compatible.
In particular, use -DRAINBOW for the DEC Rainbow computer (this
series hasn't been manufactured since the mid 1980s).  This hasn't
been tested recently.  JOVE was once ported to TOS on the Atari ST,
which is much like MSDOS but not at all like the IBM PC.

The original port of JOVE to the IBM PC was done by Karl
Gegenfurtner (karl@hipl.psych.nyu.edu).  Karl's port was modified
for Zortech C by D. Hugh Redelmeier (hugh@mimosa.com).  Joe Smith
(jes@mbio.med.upenn.edu) ported to Borland C.  Several others,
including Jim Patterson (jimp@cognos.com) and Gary Puckering
(garyp@cognos.com) updated the Microsoft port.
