| 1 |
########################################################################## |
| 2 |
# This program is Copyright (C) 1986-2002 by Jonathan Payne. JOVE is # |
| 3 |
# provided by Jonathan and Jovehacks without charge and without # |
| 4 |
# warranty. You may copy, modify, and/or distribute JOVE, provided that # |
| 5 |
# this notice is included in all the source files and documentation. # |
| 6 |
########################################################################## |
| 7 |
|
| 8 |
[Updated in February 2023] |
| 9 |
|
| 10 |
HOW TO GET STARTED WITH JOVE: |
| 11 |
============================= |
| 12 |
|
| 13 |
JOVE for MSDOS is distributed in two forms. The source code version |
| 14 |
allows you to easily understand and modify JOVE. The executable |
| 15 |
version allows you to easily install JOVE without using a C compiler. |
| 16 |
Neither requires the other. |
| 17 |
|
| 18 |
Each distribution may be in the form of a .zip archive, so you will need |
| 19 |
a command like unzip, pkunzip, 7-zip or other un-archiver that supports |
| 20 |
the zip format. Note that some firewalls or endpoint protection software |
| 21 |
may not allow downloads of .zip files. If you use pkunzip to unpack, |
| 22 |
be sure to use the -d flag to get it to correctly place files |
| 23 |
in subdirectories. |
| 24 |
|
| 25 |
A source archive in .zip form can be generated on Posix using |
| 26 |
make zip |
| 27 |
if you have a zip command installed. If you use 7-zip, something like |
| 28 |
make ZIP=7z ZIPOPTS=a zip ZIPEXT=7z |
| 29 |
should work (though 7z does not make filenames DOS-friendly 8.3, |
| 30 |
probably does not matter for modern Windows machines) |
| 31 |
|
| 32 |
The source distribution for MSDOS (and WIN32 -- Windows/95 or later) |
| 33 |
is an archive called joveNNNs.zip, where NNN is a version |
| 34 |
number (for example, jove500s.zip for 5.0). The source archive |
| 35 |
contains all the source files needed to compile JOVE on an MSDOS or |
| 36 |
WIN32 machine. It differs in three ways from the generic JOVE source |
| 37 |
distribution. First, it is distributed in a conventional MSDOS |
| 38 |
format, rather than as a tar file. Second, certain files are left out |
| 39 |
because they are of no use under MSDOS (for example, the X Window |
| 40 |
System support) and may not fit the 8.3 naming straitjacket. Third, a |
| 41 |
few files are pre-built on UNIX and included because the tools to |
| 42 |
build them are not generally available under MSDOS (for example, the |
| 43 |
formatted documentation). |
| 44 |
|
| 45 |
The executable distribution for MSDOS on the IBM PC is an archive called |
| 46 |
joveNNNd.zip where NNN is a version number (e.g. 417 for 4.17). The |
| 47 |
archive contains all the files needed to use jove: the executables and |
| 48 |
the documentation. The executables are built for large model (maximum |
| 49 |
line length of 2048 bytes, can usually go upto 32K total lines across |
| 50 |
many buffers). Jove can also be compiled for medium model (slightly |
| 51 |
smaller memory footprint, maximum line lengths of 512 bytes, but likely |
| 52 |
to run out of memory or hit a temp file limit when editing lots of files |
| 53 |
at the same time, so not recommended, not recently tested) |
| 54 |
|
| 55 |
jove.exe JOVE editor executable. |
| 56 |
recover.exe This is the recover program to pull data back out |
| 57 |
of the temporary working file if JOVE or the PC |
| 58 |
previously crashed while editing. It is invoked |
| 59 |
by the JOVE -r option. May need to set the JOVELIB |
| 60 |
environment variable, or use the -l option to locate it |
| 61 |
if stored in a different location than the compiled-in |
| 62 |
default (lib-dir-pathname variable in JOVE, LIBDIR |
| 63 |
in paths.h, empty means same dir as jove.exe) |
| 64 |
doc\cmds.txt contains text for the describe-command and describe- |
| 65 |
variable command. If the compiled-in default does not work, |
| 66 |
then may need to set the JOVESHARE environment variable |
| 67 |
or use -s JOVE option |
| 68 |
doc\jove.man the complete JOVE manual |
| 69 |
doc\jove.txt the "manpage" for JOVE: describes how to run JOVE |
| 70 |
doc\jove.qre a plain text quick reference card with JOVE commands/variables |
| 71 |
doc\joveman.ps PostScript version of the JOVE manual for printing |
| 72 |
doc\jove.rc a system-default startuup file, see JOVESHARE |
| 73 |
doc\teachjov.txt Jove tutorial for -T option or teach-jove command, |
| 74 |
see JOVESHARE |
| 75 |
doc\example.rc other example startup configuration |
| 76 |
paths.h This file shows what the default directories JOVE was |
| 77 |
compiled with. The file itself is not used to run JOVE. |
| 78 |
README.dos This file. |
| 79 |
|
| 80 |
ENVIRONMENT VARIABLES USED BY JOVE: |
| 81 |
=================================== |
| 82 |
|
| 83 |
COMSPEC |
| 84 |
This variable is used to specify the default program to run as the SHELL. |
| 85 |
It can be overridden by the JOVE variable "shell". |
| 86 |
|
| 87 |
TMPDIR (or TEMP) |
| 88 |
JOVE uses the value of TMPDIR, or if that is not set, TEMP to |
| 89 |
determine the directory where it should put its temporary file. The |
| 90 |
default is c:\tmp (set by TMPDIR in the makefile when JOVE was |
| 91 |
compiled), and this is probably not what you want. In general editing |
| 92 |
is faster, if TEMP points to a ramdisk, like "set temp=d:". You have |
| 93 |
to know however that the temporary file can grow quite big when |
| 94 |
editing many big files at once. So please make sure that you have |
| 95 |
enough space available on your ramdisk. If JOVE runs out of space on |
| 96 |
the device which holds the temporary file, you have to leave the |
| 97 |
editor immediately. You can save your work without any trouble, but |
| 98 |
you have to start over. Please note also that the Large Model version |
| 99 |
of JOVE has a big cache for the temporary file in memory, which makes |
| 100 |
it quite fast even if you don't have a ramdisk. It is an MSDOS |
| 101 |
convention to use TEMP; use TMPDIR if you intend that the directory |
| 102 |
is solely for JOVE. Remember to create the temporary directory, |
| 103 |
since JOVE does not do that automatically (newer DOS versions |
| 104 |
usually have a temporary directory and set TEMP) |
| 105 |
|
| 106 |
JOVESHARE |
| 107 |
This variable specifies the path to the directory in which the |
| 108 |
documentation and support files for JOVE can be found |
| 109 |
(1) cmds.txt (the file of command and variable descriptions used by |
| 110 |
the describe-command and desribe-variable commands) and (2) the |
| 111 |
system-wide jove.rc (the first file that is sourced (executed) by JOVE |
| 112 |
when it starts up) and (3) the TEACHJOV.TXT tutorial that |
| 113 |
can be accessed with the "teach-jove" command within JOVE, |
| 114 |
or by starting JOVE with the -T option (different from -t; |
| 115 |
unlikes typical DOS programs, JOVE options are case-sensitive) |
| 116 |
If this is a relative path, JOVE will interpret it |
| 117 |
as relative to the directory containing the JOVE |
| 118 |
executable. The default is "doc" (set by SHAREDIR in the |
| 119 |
makefile when JOVE was compiled), which works if you either |
| 120 |
run a compiled JJOVE executable out of the source directory, |
| 121 |
or from the ZIP or (self-extracting) EXE file with the JOVE |
| 122 |
DOS binaries. |
| 123 |
|
| 124 |
JOVELIB |
| 125 |
This variable specifies the path to the directory in which the |
| 126 |
RECOVER.EXE program can be found, needed when JOVE is invoked |
| 127 |
with the -r option. As with JOVESHARE, a relative directory |
| 128 |
will be interpreted as relative to the same directory as the JOVE |
| 129 |
executable was found. The default is the empty string, which |
| 130 |
means the same directory as the JOVE executable, which works |
| 131 |
for either a source directory that was just compiled, or the |
| 132 |
pre-packaged ZIP or self-extracting EXE binary distributions. |
| 133 |
|
| 134 |
HOME |
| 135 |
The directory which is to be considered the user's home (as in UNIX). |
| 136 |
The default is the current directory on the current disk when JOVE was |
| 137 |
started. JOVE looks in this directory for the user's jove.rc startup |
| 138 |
file (this will be sourced after the system-wide jove.rc, unless HOME |
| 139 |
and JOVESHARE are the same). In filenames, an initial ~/ denotes the |
| 140 |
home directory. |
| 141 |
|
| 142 |
METAKEY |
| 143 |
If this environment variable is set, JOVE turns on its meta-key variable. |
| 144 |
|
| 145 |
DIFFERENCES BETWEEN JOVE UNDER MSDOS AND UNIX JOVE: |
| 146 |
=================================================== |
| 147 |
|
| 148 |
The MSDOS version of JOVE currently supports all of the features that |
| 149 |
are possible to implement under MSDOS in a reasonable way. The things |
| 150 |
that are missing under MSDOS are: |
| 151 |
spell-buffer (obsolete under MSDOS) |
| 152 |
interactive shells in a window (not possible) |
| 153 |
|
| 154 |
There are however some features added, which are specific to the PC |
| 155 |
version: |
| 156 |
|
| 157 |
Variables: |
| 158 |
text-attribute specifies the background and foreground colors of the |
| 159 |
screen. The default value is 0x07, which stands for white on |
| 160 |
black. The attribute used for writing to the screen is formed by |
| 161 |
(bg&7)<<4 & (fg&7). |
| 162 |
|
| 163 |
Mode-line-attribute specifies the background and foreground colors of |
| 164 |
the modeline. Its default value is 0, and in that case it is drawn |
| 165 |
in reverse video. If it has any other value, this value is used as |
| 166 |
the attribute in Bios calls. |
| 167 |
(note that on a monochrome monitor the best thing is to leave the |
| 168 |
default colors - anything else can lead to blank screens very easily) |
| 169 |
|
| 170 |
General: |
| 171 |
JOVE on the IBM PC supports the whole 8 bit character set of the IBM PC. |
| 172 |
You can use all the line drawing characters in your files. It also knows |
| 173 |
about some special foreign characters (Umlaute), which are treated |
| 174 |
correctly as part of words and in case conversions. It knows about |
| 175 |
and has special bindings for most of the non-ASCII keys (such as the |
| 176 |
function keys and the ALT shift key). |
| 177 |
|
| 178 |
VIDEO MODES ON THE IBM PC UNDER DOS: |
| 179 |
==================================== |
| 180 |
|
| 181 |
When JOVE is started, it automatically checks which video mode is |
| 182 |
currently used, and adjusts itself correspondingly. This means that |
| 183 |
JOVE will work correctly even in 40x25 mode. If you have an EGA or VGA |
| 184 |
card, and want to use a special mode with 25, 28, 43, or 50 lines, set |
| 185 |
the environment variable TERM to the value EGAn. This will tell JOVE |
| 186 |
to set the screen in 80xn mode. The regular 80x25 mode is restored upon |
| 187 |
exit. On a color monitor, you can change the screen colors by using |
| 188 |
the commands mentioned above. |
| 189 |
|
| 190 |
SPECIAL KEYS ON THE IBM PC UNDER DOS AND WIN32: |
| 191 |
=============================================== |
| 192 |
|
| 193 |
JOVE checks to see if an enhanced AT-style keyboard is available and if so |
| 194 |
it will recognize use of the F11 and F12 keys plus numerous Alt/Shift/Control |
| 195 |
keys that cannot be generated with the basic keyboard BIOS. This check can |
| 196 |
be overridden by setting the enhanced-keyboard variable in the jove.rc file. |
| 197 |
|
| 198 |
JOVE turns Ctrl-Space into NUL. This makes the keyboard match most others, |
| 199 |
and makes it easy to invoke the set-mark command. |
| 200 |
|
| 201 |
JOVE turns a Delete keystroke into a DEL character. Surprisingly, this isn't |
| 202 |
done by the BIOS. DEL is also generated by Ctrl-BackSpace, so a distinction |
| 203 |
is lost. If you are used to IBM PC conventions, you may wish to bind DEL to |
| 204 |
delete-next-character (its standard binding is to delete-previous-character). |
| 205 |
|
| 206 |
JOVE maps the shifted arrow, Insert, Delete, Home, End, PgUp, and PgDn keys |
| 207 |
to codes distinct from the unshifted keys. This allows them to be bound |
| 208 |
differently. |
| 209 |
|
| 210 |
If the meta-key variable is on, the ALT key acts like a META key -- |
| 211 |
any key typed while it is depressed generates an ESC before the normal |
| 212 |
code. Otherwise, any key typed while ALT is depressed generates a special |
| 213 |
PCNONASCII code and the scan code for the key. JOVE supplies a keymap |
| 214 |
for the PCNONASCII code. |
| 215 |
|
| 216 |
COMPILING JOVE UNDER MSDOS: |
| 217 |
=========================== |
| 218 |
|
| 219 |
If JOVE is compiled using "Large Model", it can freely use all of the |
| 220 |
available portion of the normal 640kB memory. If it is compiled using |
| 221 |
"Medium Model", all of its data (except for line descriptors) must fit |
| 222 |
in 64kB; one consequence is that JOVE's tempfile cache is severely |
| 223 |
reduced. The advantage of Medium Model is that JOVE's object code is |
| 224 |
somewhat smaller. |
| 225 |
|
| 226 |
JOVE has been compiled (2023 February) for DOS with the Open Watcom |
| 227 |
1.9.0 compiler (which was downloaded circa 2020 from |
| 228 |
http://ftp.openwatcom.org/install/open-watcom-c-dos-1.9.exe), |
| 229 |
tested under FreeDOS 1.2 and the dosbox emulator |
| 230 |
(0.74-4.2+deb9u2build0.16.04.1 on Ubuntu 16.04) using |
| 231 |
wmake -f Makefile.wat |
| 232 |
in the source unpacked from jove417s.zip (made on a |
| 233 |
Unix/Linux machine) Since this is not a primary platform for |
| 234 |
current JOVE maintainers, new testers (and bug |
| 235 |
reports/patches) are welcome. |
| 236 |
The following AUTOEXEC.BAT was used: |
| 237 |
PATH C:\WATCOM\BINW;%PATH% |
| 238 |
SET INCLUDE=C:\WATCOM\H |
| 239 |
SET WATCOM=C:\WATCOM |
| 240 |
SET EDPATH=C:\WATCOM\EDDAT |
| 241 |
SET WIPFC=C:\WATCOM\WIPFC |
| 242 |
The following CONFIG.SYS was used: |
| 243 |
FILES=20 |
| 244 |
A wildargv.c file was downloaded from https://tinyurl.com/ow-wildargv |
| 245 |
a.k.a |
| 246 |
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 |
| 247 |
though that link may not work after varioius acquisitions. |
| 248 |
|
| 249 |
JOVE was once compiled with version 8.0 of the Microsoft C compiler |
| 250 |
a.k.a. Visual C. It might have also compiled with versions 6 or 7 |
| 251 |
but that was never confirmed. The makefile called Makefile.msc might |
| 252 |
be adaptable to this, patches are welcome. Try |
| 253 |
nmake /f Makefile.msc WIN32=0 |
| 254 |
|
| 255 |
JOVE was once compiled (1994 July) with version 3.1 of |
| 256 |
Borland's C compiler. Extract relevant files/definitions from |
| 257 |
old/Makefile.bcc and old/sysdep.h, which will likely |
| 258 |
require some tweaking in order to be brought uptodate. |
| 259 |
Patches are welcome. |
| 260 |
Without newer build validation and test, this support |
| 261 |
is likely to be deleted from future versions of JOVE. |
| 262 |
|
| 263 |
JOVE was once compiled (1996 May) with version 3.0 of |
| 264 |
Zortech's C compiler. If that is desired again, try |
| 265 |
old/Makefile.zor and definitions from old/sysdep.h, patches are welcome. |
| 266 |
Without newer build validation and test, this support |
| 267 |
is likely to be deleted from future versions of JOVE. |
| 268 |
|
| 269 |
JOVE once supported MSDOS on hardware that is not IBM PC compatible. |
| 270 |
In particular, use -DRAINBOW for the DEC Rainbow computer (this |
| 271 |
series hasn't been manufactured since the mid 1980s). This hasn't |
| 272 |
been tested recently. JOVE was once ported to TOS on the Atari ST, |
| 273 |
which is much like MSDOS but not at all like the IBM PC. |
| 274 |
Without newer build validation and test, this support |
| 275 |
is likely to be deleted from future versions of JOVE. |
| 276 |
|
| 277 |
MSDOS ON MACHINES NOT COMPATIBLE WITH THE IBM PC |
| 278 |
================================================ |
| 279 |
|
| 280 |
JOVE was once ported to MSDOS machines that were not IBM PC clones. One |
| 281 |
example for which there is special code is the DEC Rainbow. Another was |
| 282 |
the Atari ST (although the specific code for it is not included in our |
| 283 |
current source). Still others were generic MSDOS machines such as the |
| 284 |
Nabu 1600. Although the source code still has provisions for these, it |
| 285 |
has not been tested for a very long time and so is probably no longer |
| 286 |
quite right. |
| 287 |
|
| 288 |
The next two variables are not used by the IBM PC version, and have to |
| 289 |
do with specifying the type of terminal in use on a generic MSDOS |
| 290 |
computer. |
| 291 |
|
| 292 |
TERM |
| 293 |
This variable should specify the name of the terminal you are using. |
| 294 |
For example, if you have a DEC vt-100 terminal attached to your MSDOS |
| 295 |
computer, you should give the command "set TERM=vt100" prior to |
| 296 |
starting JOVE. |
| 297 |
|
| 298 |
TERMCAP |
| 299 |
This environment variable holds the name of a database with |
| 300 |
descriptions of different terminal types. If you are familiar with the |
| 301 |
UNIX operating system, you probably know about TERMCAP. For each |
| 302 |
terminal type, specified by TERM, the TERMCAP database holds an entry, |
| 303 |
which describes how to set the cursor, how to scroll, and many other |
| 304 |
things, for that particular terminal. A small example TERMCAP file |
| 305 |
comes with JOVE. If your terminal is not included there, you should ask a |
| 306 |
local UNIX guru for help. If you don't have one, you can ask |
| 307 |
github.com/jonmacs/jove |
| 308 |
|
| 309 |
|
| 310 |
The original port of JOVE to the IBM PC was done by Karl |
| 311 |
Gegenfurtner ([email protected]). Karl's port was modified |
| 312 |
for Zortech C by D. Hugh Redelmeier). Joe Smith |
| 313 |
([email protected]) ported to Borland C. Several others, |
| 314 |
including Jim Patterson ([email protected]) and Gary Puckering |
| 315 |
([email protected]) updated the Microsoft port. |
| 316 |
Mark Moraes re-ported to Win32 and DOS in in Feb 2020 |
| 317 |
and continues to test sporadically on those platforms. |