########################################################################## # 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, so you will need a command like unzip, pkunzip, 7-zip or other un-archiver that supports the zip format. Note that some firewalls or endpoint protection software may not allow downloads of .zip files. If you use pkunzip to unpack, be sure to use the -d flag to get it to correctly place files in subdirectories. A source archive in .zip form can be generated on Posix using make zip if you have a zip command installed. If you 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, jove500s.zip for 5.0). 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 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.