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

Jove for WIN32
==============

While Windows (or DOS) are not primary platforms for the JOVE developers,
some effort is been made to test JOVE on both.

Jove can be built for WIN32 (that is, Windows versions after Windows/95)
natively with Microsoft Visual C (MSVC), or cross-compiled with
{i686,x86-64}-w64-mingw32 on Linux.  The MSDOS source distribution zip may
be preferable for MSVC builds because it contains pre-built documentation
files which must be created on a UNIX system, and excludes some things
only of use on UNIX (for example, X Window System support).  The filename
of the MSDOS source distribution is a name that includes the version
number joveNNNs.zip (for example, jove417s.zip for version 4.17), created
by running 'make zip' on a Unix/Linux/*BSD system,
	make zip

A pre-compiled (via MINGW) and ready-to-run copy of JOVE for WIN32 is
distributed in archives with the names
jove-N.N.N.N-x86_64-w64-mingw32.zip (64bit binaries, 4.17.0.5 on),
jove-N.N.N.N-i686-w64-mingw32.zip (32bit binaries).  Older distributions
(4.16, early 4.17) used joveNNNw.zip (for example, jove416w.zip for
version 4.16).

Jove for WIN32 has usually been lightly tested on the Win7 platform, but
is expected to work on older versions like Windows/95, 98, NT, 2000, XP,
etc, and might work on newer versions like Win8 and Win10.  Test and bug
reports are welcome, though the Jove developers are primarily from Unix-land.

Jove for WIN32 does not function under the WIN32s environment (which is a
special subsystem of Windows 3.1).  The primary reason is that WIN32s
doesn't support the WIN32 Console API, which Jove for WIN32 depends on in
order to display text on the screen and accept and interpret keystrokes.
For such environments, use the MSDOS version.

The original port of Jove to WIN32 was performed by Jim Patterson
(Jim.Patterson@Cognos.COM) with the help and advice of D. Hugh Redelmeier
as well as early testing and feedback by Gary Puckering
(Gary.Puckering@Cognos.COM).

Building Jove for WIN32
=======================

To build for WIN32 natively using Microsoft Visual C++ (2.0 or later),
unpack a source distribution, setup the Visual C environment (typically,
by running vcvars32.bat or starting a Developer Command window from
Visual Studio), and use
	
	nmake /f Makefile.msc

To cross-compile on a Unix/Linux machine with MinGW installed
(e.g. on a modern Debian/Ubuntu/Mint, try "apt install mingw-w64"),
and then use

	JMAKE_UNAME=i686-w64-mingw32 ./jmake.sh

(DESTDIR=/none is a hack to avoid some Makefile
complaints, it does not get used otherwise)

Advantages of WIN32 version (over DOS)
======================================

Since Windows/NT and Windows/95 support native DOS applications like Jove,
using the 16-bit version of JOVE is a perfectly acceptable alternative to
using the WIN32 version.  However, the WIN32 version does provide several
advantages, as follows:

1.  Long filenames.  Windows/NT and Windows/95 allow filenames that go
beyond DOS's 8.3 naming limitations.  Jove for WIN32 uses long filenames by
default, whereas Jove for DOS can only see the 8.3 versions of filenames.
Jove for WIN32 is also able to directly access files in UNC format, i.e.
with an explicit network name.  Jove for DOS can only access network files
via an associated drive letter.

2.  Window sizing.  WIN32 consoles can be dynamically resized.  When running
a 16-bit application like JOVE, resizing is disabled.  However, Jove for
WIN32 responds to resizing events and reconfigures its display, just like it
does under UNIX when it receives a SIGWINCH signal.

3.  32-bit limits.  Jove for WIN32 is a 32-bit application, and so is less
prone to size constraints than its 16-bit DOS cousin (though through clever
coding even 16-bit DOS Jove is able to handle a lot files of a considerable size).
It is hoped that Jove works on 64bit Windows as well.

4.  32-bit Performance.  Jove for WIN32 should perform, and behave, better
than Jove for DOS on a suitable platform for several reasons.
- Flat address space (no segment register loading).
- Poll-free operation.  Jove for DOS uses a polling loop as it waits for
  input if it needs to display the time on the mode line or wait for a
  delayed refresh.  Jove for WIN32 can use WIN32 Wait... functions to do
  this, which permit it to cooperate with other tasks more effectively.

5.  Its own Icon.  Since Jove for WIN32 is a Windows executable, it can have
its own icon.  No more hunting around in MORICONS.DLL for something
suitable.  (If you don't like my planet icon, feel free to craft another;
I'm not an artist)!

6.  Non-Intel platforms, in theory.  Jove for WIN32 might port easily to other WIN32
platforms e.g. Alpha and PowerPC (though it hasn't actually been built on any of
these).  The performance advantage of having native applications might be
considerable, since these platforms must use software emulation to run 16-bit
DOS applications. (If anyone has such a platform, and wants to use JOVE on it,
please open a github issue, would love to hear about the port)

One functional difference is that under Windows/95 there is
apparently no way to dynamically resize the console window as there is under
Windows/NT.  There is no code specifically to support Windows/95, though
some design decisions were based on the need to support it.

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" or by the SHELL environment
variable.

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 contains
(1) cmds.txt (the file of command and variable descriptions used by
the describe-command and describe-variable commands) (2) the
system-wide jove.rc (the first file that is sourced (executed) by JOVE
when it starts up) and (3) The teach-jove tutorial, which can be
loaded by either starting JOVE with the -T option (case-sensitive options)
or by invoking the teach-jove command within JOVE. 
A relative path will be interpreted as relative to the location of
the JOVE executable binary.  The default is "doc" (set by JSHAREDIR in the
Makefile when JOVE was compiled), which is fine for either running
JJOVE.EXE from the source directory, or JOVE.EXE from the binary
distributions.

JOVELIB
This variable specifies the path to the directory that contains
RECOVER.EXE, needed for the JOVE -r option, to recover any data
after a machine or JOVE crash (hopefully rare). Default is empty,
which means the same directory as the JOVE executable (same 
relative interpretation as JOVESHARE)

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.

HOMEDRIVE, HOMEPATH
These variables are used together, or not at all.  If HOME is not set but
HOMEDRIVE and HOMEPATH are, then the home directory is taken to be the
concatenation of their values.  HOMEDRIVE and HOMEPATH are part of the
default Windows NT user environment.  They are not typically set on a
Windows 95 system (but Jove will use them as described if they are).

SHELL
This defines an alternate shell for JOVE to use when running commands with
shell-command.  It overrides COMSPEC if provided.

Managing the console for Jove
=============================

In many (but not all) respects, WIN32 Consoles are more flexible than DOS
shell windows.  Here are a few tricks for setting up a Jove console the way
you like it.

- Jove will set up its screen to match the current Window.  This is often
  the same size as the current "console buffer" but the window may be
  smaller in size in which case scroll bars will appear.  When the screen
  buffer changes size, Jove will resize its screen buffer.  However, Jove
  can't always tell if the window size changes.  Use a clear-and-redraw
  (typically bound to ESC ^L) to force Jove to resize its screen.

- You can use a MODE command to interactively cause Jove to resize its
  window if you want to do this, say, from a jove.rc file.  For example,
  this sets up a 40 line 100 column window:

	shell-command-no-buffer mode con lines=40 cols=100

- A better way to set up the screen size under NT is to use the window
  properties.  If you choose to save these settings, they will then apply
  whenever you run that application.

- You can set up a "file association" for Jove under NT, and set up the
  Jove as the program to handle a file.  It's not immediately obvious how
  to change the default screen size.  The problem is that with an
  association, the file you launch is what the settings are tied to; each
  different file gets its own file settings.  To get around this, use this
  as the command line instead:

	start jove %1

  This works because the window settings are associated with the window
  title, not the application.  When started this way the window title is
  always "Jove", so settings can be used for all files launched with that
  association.

  This has an unfortunate size effect of obscuring the Jove window,
  however.  If someone finds a better setup, please broadcast it!

Development Notes:
==================

Since Jove was originally developed on Unix, and is still primarily
developed/tested in the Linux/Unix/*BSD world, it is still an awkward
fit for Windows, unfortunately.

Jove for WIN32 and Jove for DOS share some code, but also have considerable
OS-specific code.  The following manifests are used to flag code for the
MS-DOS and/or WIN32 versions of Jove (they are explained more fully in
sysdep.txt)

IBMPCDOS - flags features specific to IBM PC hardware running DOS.
MSDOS - describes code that is specific to the 16-bit DOS version of Jove.
WIN32 - describes code specific to the 32-bit Windows version of Jove.
MSFILESYSTEM - enables aspects of Jove to support Microsoft file systems.
MSDOS_PROCS	- enables use of the spawn series of APIs that replace fork/exec.
DIRECTORY_ADD_SLASH indicates that file browsing will flag directories.
TEXTFILE_ADD_CR instructs Jove to strip/add CRs from lines of text files.
FILENAME_CASEINSENSITIVE indicates that case is not significant for filenames.

Most of the support code for Jove for WIN32 resides in the file win32.c.
The MSDOS files MSDOS.C and PCSCR.C are not used for Jove for WIN32.

TO DO
=====

There are some opportunities for additional work to make Jove for WIN32 more
useable and functional.

1.  Add IPROC support.  WIN32 supports pipes, which mean that it's
conceptually possible to support IPROCs using methods similar to that of the
UNIX PIPEPROC support.  In fact, WIN32 IPROC should be somewhat cleaner than
PIPEPROCs because the API avoids the need for a third process.  However, the
reality of WIN32 pipes seems to be somewhat different, and my own attempts
to get them to work have so far failed (though the single direction pipes
used for a simple SUBSHELL do seem to function okay).

2.  Add MOUSE support.  The current input model for WIN32 could easily be
extended to support mouse events.  It's just necessary to enable the mouse
in the SetConsoleMode call, and then process the mouse events as they
arrive.  The main obstacle is in coming up with a good command model.  There
are two different mouse command models supported by Jove right now, one for
X and one for SunView; no doubt there are reasons that neither one is
totally appropriate in the Windows world.

Known Bugs:
==========

- Under Windows 95, the CAPS LOCK key also shifts non-alpha keys (e.g.
  numerics and []).  This seems to be a bug in the Windows 95 Console API
  implementation: the Event.KeyEvent.uChar.AsciiChar field for the keyboard
  event is set incorrectly.

- The much touted icon doesn't appear under Windows 95.  Once Windows 95 sees
  that it's not a "real Windows application", it assumes that a standard
  console icon is good enough.

- Occasionally, when Jove is started under Windows 95, it does not display
  anything until a key is pressed.  We haven't tracked down what
  circumstances cause this; it seems to happen more often with certain
  machine configurations.
