Debian Codegraph @

README.dos

raw
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.