##########################################################################
# 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 May 1996]

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

The support for WIN32 (that is, Windows/95 and Windows/NT) is integrated
into the generic JOVE source.  The source can be found in the generic JOVE
source distribution, or in the MSDOS source distribution.  The latter is
more useful because it includes pre-built documentation files which must be
created on a UNIX system, but excludes some things only of use on UNIX (for
example, X Window System support).  The filename of the MSDOS source
distribution is jovedoss.zip, or a name that includes the version number
(for example, jove416s.zip).

A pre-compiled and ready-to-run copie of JOVE for WIN32 is distributed in
archives with the name jovew32x.zip or a name that includes the version
number (for example, jove416w.zip).

Jove for WIN32 has been tested on both the Windows/NT and the Windows/95
platforms, and provides much the same advantages under Windows/95 as it does
for Windows/NT.  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.

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.

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
(hugh@mimosa.com) as well as early testing and feedback by Gary Puckering
(Gary.Puckering@Cognos.COM).

Advantages of WIN32 version
===========================

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 files of a considerable size).

4.  Non-Intel platforms.  Jove for WIN32 should be a simple port to other WIN32
platforms e.g. Alpha and PowerPC (though I haven't actually built it on any of
these).  The performance advantage of having native applications can be
considerable, since these platforms must use software emulation to run 16-bit
DOS applications.

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

6.  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)!

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 will contain
(1) cmds.doc (the file of command and variable descriptions used by
the describe-command and describe-variable commands) and (2) the
system-wide jove.rc (the first file that is sourced (executed) by JOVE
when it starts up).  The default is c:/jove (set by SHAREDIR in the
makefile when JOVE was compiled).

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!

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

In order to build JOVE for WIN32, you need a Windows/95 or Windows/NT system
with Visual C++ 2.0 or later installed.  If you don't already have a DOS
source archive, you'll need a UNIX system to build this on as well.

If you don't have the aforementioned source archive, then the first step is
to create a source archive containing the JOVE sources and related
documentation.  This needs to be done from a UNIX system, because it depends
on several unix tools (e.g. nroff and uudecode).  If you don't have a UNIX
system, get a friend to do this.  This step also requires either zoo or
pkzip, which are available elsewhere.  To extract the source from the
archive on the PC side, you'll need the corresponding DOS or WIN32 version
of zoo, pkunzip or unzip.  Use the following command on the UNIX system to
create the archive:

    make jovedoss.zip

(Substitute zoo for zip if a zoo archive is required).

Once the archive is created, move it to the Windows/NT or Windows/95 system.
Unpack the archive into its own source directory.

After unpacking, Jove can be built using the following command.  Note that
the 32-bit Visual C++ compiler must be on your path and the appropriate
INCLUDE and LIB environment variables must be set correctly.

    nmake /f makefile.msc WIN32=1

If you want to redistribute the WIN32 version of Jove to others, you can use
the jovew32x.zip or jovew32x.zoo targets to do so e.g.

    nmake /f makefile.msc WIN32=1 jovew32x.zoo

Jove can also be built from the Visual C++ 2.x workbench.  Just open
makefile.msc as a project, and set the build command to the above.  For the
DEBUG version add DEBUG=1 to the command line.

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

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.doc)

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.