##########################################################################
# 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 February 2023]

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 archive (smaller) or
a .sfx archive (self-extracting executable zip, larger, may be disallowed
by various security tools, though that may also be true for .zip). You can
create a suitable archive (source on Un*x, executable on DOS/Windows) using
	make zip
if you have a zip command installed.  If you use pkunzip to unpack,
be sure to use the -d flag to get it to correctly place files
in subdirectories.  If you need/prefer to use 7-zip, something like
	make ZIP=7z ZIPOPTS=a zip ZIPEXT=7z
should work (though 7z does not make filenames DOS-friendly 8.3,
probably does not matter for modern Windows machines)

The source distribution for MSDOS (and WIN32 -- Windows/95 or later)
is an archive called joveNNNs.zip, where NNN is a version
number (for example, jove417s.zip for 4.17).  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 zip".

The executable distribution for MSDOS on the IBM PC is an archive called
joveNNNd.zip where NNN is a version number (e.g. 417 for 4.17).  The
archive contains all the files needed to use jove: the executables and
the documentation.  The executables are built for large model (maximum
line length of 2048 bytes, can usually go upto 32K total lines across
many buffers).  Jove can also be compiled for medium model (slightly
smaller memory footprint, maximum line lengths of 512 bytes, but likely
to run out of memory or hit a temp file limit when editing lots of files
at the same time, so not recommended, not recently tested)

jove.exe        JOVE editor executable.
recover.exe	This is the recover program to pull data back out
		of the temporary working file if JOVE or the PC
		previously crashed while editing. It is invoked 
		by the JOVE -r option. May need to set the JOVELIB
		environment variable, or use the -l option to locate it
		if stored in a different location than the compiled-in
		default (lib-dir-pathname variable in JOVE, LIBDIR
		in paths.h, empty means same dir as jove.exe)
doc\cmds.txt    contains text for the describe-command and describe-
                variable command.  If the compiled-in default does not work,
		then may need to set the JOVESHARE environment variable
		or use -s JOVE option
doc\jove.man    the complete JOVE manual
doc\jove.txt    the "manpage" for JOVE: describes how to run JOVE
doc\jove.qre    a plain text quick reference card with JOVE commands/variables
doc\joveman.ps  PostScript version of the JOVE manual for printing
doc\jove.rc     a system-default startuup file, see JOVESHARE
doc\teachjov.txt Jove tutorial for -T option or teach-jove command,
		see JOVESHARE
doc\example.rc  other example startup configuration
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.  Remember to create the temporary directory,
since JOVE does not do that automatically (newer DOS versions
usually have a temporary directory and set TEMP)

JOVESHARE
This variable specifies the path to the directory in which the
documentation and support files for JOVE can be found
(1) cmds.txt (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) and (3) the TEACHJOV.TXT tutorial that
can be accessed with the "teach-jove" command within JOVE,
or by starting JOVE with the -T option (different from -t;
unlikes typical DOS programs, JOVE options are case-sensitive)
If this is a relative path, JOVE will interpret it
as relative to the directory containing the JOVE
executable. The default is "doc" (set by SHAREDIR in the
makefile when JOVE was compiled), which works if you either
run a compiled JJOVE executable out of the source directory,
or from the ZIP or (self-extracting) EXE file with the JOVE
DOS binaries.

JOVELIB
This variable specifies the path to the directory in which the
RECOVER.EXE program can be found, needed when JOVE is invoked
with the -r option.  As with JOVESHARE, a relative directory
will be interpreted as relative to the same directory as the JOVE
executable was found.  The default is the empty string, which
means the same directory as the JOVE executable, which works
for either a source directory that was just compiled, or the
pre-packaged ZIP or self-extracting EXE binary distributions.

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.

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
somewhat smaller.

JOVE has been compiled (2023 February) for DOS with the Open Watcom
1.9.0 compiler (which was downloaded circa 2020 from
http://ftp.openwatcom.org/install/open-watcom-c-dos-1.9.exe), 
tested under FreeDOS 1.2 and the dosbox emulator 
(0.74-4.2+deb9u2build0.16.04.1 on Ubuntu 16.04) using
	wmake -f Makefile.wat
in the source unpacked from jove417s.zip (made on a
Unix/Linux machine) Since this is not a primary platform for
current JOVE maintainers, new testers (and bug
reports/patches) are welcome.
The following AUTOEXEC.BAT was used:
PATH C:\WATCOM\BINW;%PATH%
SET INCLUDE=C:\WATCOM\H
SET WATCOM=C:\WATCOM
SET EDPATH=C:\WATCOM\EDDAT
SET WIPFC=C:\WATCOM\WIPFC
The following CONFIG.SYS was used:
FILES=20
A wildargv.c file was downloaded from https://tinyurl.com/ow-wildargv
a.k.a
http://perforce.openwatcom.org:4000/@md=d&cd=//depot/openwatcom/bld/clib/startup/c/&cdf=//depot/openwatcom/bld/clib/startup/c/wildargv.c&sr=28826&c=7po@//depot/openwatcom/bld/clib/startup/c/wildargv.c 
though that link may not work after varioius acquisitions.

JOVE was once compiled with version 8.0 of the Microsoft C compiler
a.k.a. Visual C.  It might  have also compiled with versions 6 or 7
but that was never confirmed.  The makefile called Makefile.msc might
be adaptable to this, patches are welcome.  Try
	nmake /f Makefile.msc WIN32=0

JOVE was once compiled (1994 July) with version 3.1 of
Borland's C compiler. Extract relevant files/definitions from
 old/Makefile.bcc and old/sysdep.h, which will likely
require some tweaking in order to be brought uptodate.
Patches are welcome.
Without newer build validation and test, this support
is likely to be deleted from future versions of JOVE.

JOVE was once compiled (1996 May) with version 3.0 of
Zortech's C compiler.  If that is desired again, try
old/Makefile.zor and definitions from old/sysdep.h, patches are welcome.
Without newer build validation and test, this support
is likely to be deleted from future versions of JOVE.

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.
Without newer build validation and test, this support
is likely to be deleted from future versions of JOVE.

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

JOVE was once ported to MSDOS machines that were not IBM PC clones.  One
example for which there is special code is the DEC Rainbow.  Another was
the Atari ST (although the specific code for it is not included in our
current source).  Still others were generic MSDOS machines such as the
Nabu 1600.  Although the source code still has provisions for these, it
has not been tested for a very long time 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
github.com/jonmacs/jove


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).  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.
Mark Moraes re-ported to Win32 and DOS in in Feb 2020
and continues to test sporadically on those platforms.
