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

JOVE on UNIX/Linux/MacOS X/*BSD/CygWin Systems
----------------------------------------------

Getting JOVE
------------

JOVE releases are available at http://github.com/jonmacs/jove/ in
various source (github's automatically packed tar.gz, or a manually
packed .tgz which are essentialy identical, as well as a manually packed
.zip or .exe for MS-DOS), and some binary forms for various OS architectures
(Linux, DOS, Windows).  All distributions include formatted manuals
(PDF, text) -- in the doc/ subdirectory for source and some binary,
or in share/doc/jove, share/jove or man/man1 (relative to 
a top-level installation directory, such as /usr or /usr/local)

For information about other systems, see the other README files in
the source, zip or exe distributions:
  README.dos for MS-DOS
  README.win for MS Win32

Quick Summary of Installation
-----------------------------

Unpack the tar file somewhere convenient and cd into it:
    tar tzf jove-VERSION.tgz
    cd jove-VERSION

Ensure you have the tools required to build Jove.  You need a C compiler
(classic Unix cc, gcc or clang should work), the make utility, 
and basic headers for libc, which may require extra packages on
some Linux distributions.
    Debian, Ubuntu, Mint: apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install --no-install-recommends gcc make ncurses-dev pkg-config exuberant-ctags
    Alpine: apk update && apk add gcc make musl-dev ncurses-dev pkgconfig ctags
    MacOSX/Darwin: brew install make ncurses 
    Nix: nix-shell -p gnumake 
    Arch: pacman -Sy gcc make # pkgconf ncurses
    Gentoo: # comes with gcc and make and headers by default!

For many modern systems (Linux, various BSDs, MacOSX/Darwin,
Solaris, OpenIndiana), an auxiliary script called
jmake.sh is provided that auto-detects what the SYSDEFS
and EXTRALIBS should be, and then invokes 'make'
without any manual configuration needed:  just
specify JOVEHOME to change where you want jove installed
(default JOVEHOME is /usr/local, which puts the binaries in
$JOVEHOME/bin, manuals in $JOVEHOME/man/man1, other
documents and help and config in $JOVEHOME/share/jove,
helper programs in $JOVEHOME/lib/jove e.g. to put jove in
/opt/jove/{bin,share,...}

     ./jmake.sh JOVEHOME=/opt/jove # to build
     ./jmake.sh JOVEHOME=/opt/jove install # to install

To build a relocatable version of Jove (i.e. an install
directory that can be copied or moved freely to other paths)
in /foo

     ./jmake.sh DESTDIR=/foo/ JOVEHOME= JBINDIR= JSHAREDIR=doc JLIBDIR= clean install

If jmake.sh does not work, please do file a bug, indicating
your system.  One can also pass SYSDEFS, TERMCAPLIB and
EXTRALIBS (and other variables in the Makefile) by hand.

BSD/Darwin/Mac OS X:
  use the first of the following that works:
  make install
  make SYSDEFS=-DXBSD install
  make SYSDEFS="-DBSDPOSIX_STDC -DUSE_OPENPTY -DHAS_LIBUTILS_H" LDLIBS=-lutil install
  make SYSDEFS="-DBSDPOSIX_STDC" install
  make SYSDEFS="-DBSDPOSIX" install

Linux:
  Using RPM (if sufficiently close to Red Hat; make sure RPMHOME is correct
  in the Makefile, that you have the rpm-build package, a compiler and
  and use:
    make rpm
  and them install the resulting rpm from
  $HOME/rpmbuild/RPMS with "rpm -i"

  To compile and install from source, set JOVEHOME
  appropriately.  By default, Jove has internal support for
  ansi/vt[1234]xx terminals that are emulated by every
  modern desktop environment (i.e xterm, rxvt, st, vte,
  konsole, {gnome,mate}-terminal, ...), so unless you have
  some very special terminal, you should not need a general
  purpose terminal handling library like termcap or curses.
  But if you need one, the packages go by different names on
  various Linux.  If you install pkgconf (for the pkg-config
  program) and the ncurses (which sometimes goes by names
  like ncursesw, ncurses-base, ncurses-dev, ncurses-devel,
  libncurses-dev, libtinfo-dev, sys-libs), that should be
  enough on most Linux systems.  Otherwise, you can
  explicitly ask for it is using something like
     make SYSDEFS=-D`uname` LDLIBS=-lncursesw
   
  If you link with one of the general terminal handling
  libraries rather than using Jove's builtin handling, then
  you will also need to ensure you have terminal
  descriptions, which are sometimes in separate packages
  (e.g. called ncurses-terminfo-base or ncurses-base or ncurses-term)

  Older Linux may need either SYSDEFS=-DXLINUX or SYSDEFS=-DBSDPOSIX_STDC
  (but do test how interactive-shell works once built; the main
  issues are pty-handling, even if they seem to compile without error)

Solaris 5.1 or newer:
  make install

Other systems:
  Read comments about SYSDEFS settings below, check sysdep.h
  for recently tested system settings or old/sysdep.h for once-working
  but currently untested settings that will need to be copied into sysdep.h,
  or just set on the command-line with SYSDEFS="-D...", LDLIBS
  if needed.

Cross-Compiling:

If your cross-compiler for some target FOO is FOO-gcc, then
you can probably cross-compile with
	env JMAKE_UNAME=FOO-gcc ./jmake.sh
e.g.
	env JMAKE_UNAME=i686-w64-mingw32 ./jmake.sh
or
	env JMAKE_UNAME=i486-linux-musl ./jmake.sh

More generally, the Jove Makefile has some support for
cross-compiling.  You need to set CC to the cross-compiler,
but please do not override CFLAGS, which consists of
SYSDEFS, (for any -I or -D cross-compiler options) and
OPTFLAGS (for any optimizer flags or special cross-compiler
options e.g. target arch).

For linking, you can set LDFLAGS (e.g. -L) or
LDLIBS for the cross-linker for the target system, while you
can set LOCALCC, LOCALCFLAGS, LOCALLDFLAGS, LOCALEXTRALIBS
and LOCALEXT for the local host machine compiler and linker
(usually none other than LOCALCC are needed, since they are
used when locally building the setmaps program on the host,
which is run to generate keys.c, which will then be
cross-compiled for the target) e.g.
    make CC=/cross/bin/cc-armv7 SYSDEFS="-DLinux -DJTC" OPTFLAGS=-O2 LDFLAGS="-L/cross/lib" LDLIBS="-lutil" LOCALCC=cc

For another example, see README.win for cross-compiling
using MinGW for a Windows target.

Please help us keep up with new systems.  If your system
isn't covered in jmake.sh or on in the SYSDEFS section
of Makefile, tell us what works.  If your system is covered,
but the documented procedure doesn't work, tell us by filing
a bug on http://github.com/jonmacs/jove

Full Story of Installation
--------------------------

JOVE does not use any automatic configuring mechanism other
than the very simple jmake.sh script, which only works
on modern Linux/*BSD/MacOSX/Darwin/Solaris.  System-specific
configuring is done by defining specific symbols from sysdep.h
in SYSDEFS in the Makefile (in most situations it is
handier to override definitions by supplying them on the make 
command line rather than the classic technique of editing the Makefile).

JOVE has been around for a *long* time, and a lot of care has been taken
to make it work on many systems, new and old.  For current systems,
less configuring is require -- hurray for standards!

Makefile specifies paths for installing JOVE components (JOVEHOME,
JSHAREDIR, JLIBDIR, JBINDIR, JMANDIR, MANEXT), tempfiles (JTMPDIR, JRECDIR),
and the default shell (DFLTSHELL).  Although the defaults are
reasonable, you may wish to change them.

For many systems, you will need to change the definition of SYSDEFS.
to the symbol that identifies your system's characteristics, using the
notation for a macro-setting flag to the C compiler.  For modern
systems, that symbol is often the output of the uname command.
For example, on a machine running NetBSD, use "SYSDEFS=-DNetBSD".
The Makefile describes suitable settings of SYSDEFS for many configurations.
If yours isn't mentioned, use "grep System: sysdep.h" to find all
currently supported system configurations.  If there is no canned
configuration for your system, you will have to define a new symbol
and edit sysdep.h suitably.  See "sysdep.txt" for the possible set of
system-dependent aspects that you can select/tune. 

On some systems, you may need to change the flags passed to
the compiler (SYSDEFS, OPTFLAGS) or the linker (LDFLAGS,
LDLIBS).  [These supersede the older Jove-specific
conventions of defining OPTFLAGS, SYSDEFS, TERMCAPLIB,
EXTRALIBS, which should still work]

Systems on which 4.17 was tested include the following
(and their SYSDEFS and LDLIBS will usually be
correctly set by the jmake.sh script that can be used
to to invoke make with auto-guessed values)

The following explicit settings also work
and may provide a guide to customization.

#	Cygwin 3.1.2			SYSDEFS=-DCYGWIN LDLIBS= # builtin vt100/xterm/rxvt etc support, no need for curses dependency
#	Darwin aka MacOS X onwards	SYSDEFS=-DDarwin LDLIBS=-ltermcap
#	FreeBSD 12.1			SYSDEFS=-DFreeBSD LDLIBS="-ltermcap -lutil"
#	Linux (modern, glibc pty.h)	SYSDEFS=-DLinux LDLIBS="-lncursesw -lutil"
#	Linux (recent, UNIX98 PTYS)	SYSDEFS=-DXLINUX LDLIBS=-lncursesw
#	Linux (old, BSD PTYS)		SYSDEFS=-DBSDPOSIX_STDC LDLIBS=-lncurses
#	NetBSD 8.1			SYSDEFS=-DNetBSD LDLIBS="-ltermcap -lutil"
#	OpenBSD 6.6			SYSDEFS=-DOpenBSD LDLIBS="-ltermcap -lutil"
#	SunOS5.1 onwards (Solaris/OpenIndiana/Illumos/Joyent)	SYSDEFS=-DSunOS LDLIBS=-ltermcap
#	Debian Hurd 0.9			SYSDEFS="-DGNU -DJTC" LDLIBS=-lutil  # LDLIBS="-lncursesw -lutil" might work, did not try

Next you may edit "tune.h" to select the compile time features you care
about.  See "tune.txt" for a description of all the compile time options.
The default options are quite reasonable so, in most cases, you should
leave them alone.  If you are really short on space, or are porting JOVE
to a new system, you may want to define -DBAREBONES in SYSDEFS to avoid
some of the less-portable features of JOVE initially.

You can type "make" to compile "jjove", "portsrv" (this is compiled on
every system, but is only used if JOVE is compiled with the PIPEPROCS
feature selection, typically on UNIX systems without pseudo ttys),
"recover" and "teachjove".  Test jjove to see if it works (remember that it
won't be able to access its subsidiary files until they are installed, so
you will need to call it with "./jjove -l . -s doc ..." -- assuming you are
in the main JOVE directory).  If it works, type "make install" to install
everything where it belongs.

Here are some things to consider when choosing a definition for
JTMPDIR, the directory where JOVE puts temporary files.  The obvious
place is /tmp, but many systems delete all files in /tmp when they are
rebooting.  If you hope to recover buffers from a system crash, TMPDIR
lets you specify a safer place.  If your system does not remove
subdirectories of /tmp on reboot (lots do remove them these days) then
it makes sense to make TMPDIR be /tmp/jove; otherwise, /var/tmp may be
better.  But if you use /tmp and want to recover buffers on system
crashes, you should put the lines:
	(echo preserving JOVE files)	>/dev/console
	(cd /tmp; /usr/local/lib/jovelib/recover -syscrash) >/dev/console
in the /etc/rc file BEFORE /tmp is cleared, so that you can recover
files after reboots (hint: look for the equivalent code to preserve vi
tempfiles).  You should then create a crontab entry to clear out old files
in /usr/preserve.

If you plan on using JOVE with a xterm, look at doc/XTermresource.
This file contains resource declarations that allow JOVE to respond to
more function keys and mouse gestures.

For RPM-based Linux, jspec.in specifies how an RPM should be created.
On most modern Red Hat Linux (Fedora, CentOS, etc), "make rpm" will build
source and binary RPMs -- rpm looks inside the .tgz to find jove.spec.
(Need to 'yum install rpm-build groff' or similar first)

It is possible to build a widely portable Linux binary using
static compilation, perhaps using the musl library to keep
size small.  E.g., using the small Alpine Linux docker image,
one can use:
	docker pull alpine
	apk add gcc musl-dev make
	make 'CC=gcc --static'
The resulting jjove can be run standalone pretty-much anywhere,
though the doc/jove.rc file might also be useful.

Some features.
--------------

"doc/jove.rc" and "doc/example.rc" are JOVE initialization
files.  "jove.rc" is the recommended "system" rc file (until
you are ready to roll your own, that is).  It gets read
every time JOVE starts up FOR EVERYONE ("make install"
should copy it to the right place automatically).  After
that JOVE reads the initialization file .joverc in the
user's home directory.  "example.rc" is taken from a
personal .joverc.

The files intro.nr and cmds.nr in the doc directory are the
official JOVE manual.  Jonathan got permission from Richard
Stallman to use his manual for the original EMACS, modifying
it where necessary for JOVE.  Lots of work was done by Brian
Harvey on this manual.  When formatted, these are usually
in some system doc directory, typically /usr/share/doc/jove/
or /usr/local/share/doc/jove, as a PDF and a text form.
There is also a quick-reference card with most JOVE key-bindings,
commands and variables, best printed in landscape mode.

There are Unix-style manual pages for jove and teachjove.  Teachjove is
an interactive tutorial for people who have never used EMACS style
editors -- it can be started from within JOVE as the "teach-jove"
command, usually bound to ESC t or historically, using the special Unix
command "teachjove".  It is THE tutorial written by Stallman for the
original EMACS, only slightly modified for JOVE in the appropriate
places.  The manual pages are hopefully up to date.

Optionally, if you want to use Jove to work with C source code, and
know/like tags, you will need ctags or etags on your system so that you
can generate tags files to use with jove -t or Jove's find-tag command
(bound to the keys "^X t").

If you use Jove to work with text documents, and use the built-in
spell-check support (i.e. Jove's spell-buffer command), you will
need to install spell-checker program (spell on classic Unix, aspell
on Linux/BSD).

Optionally, if you want to modify, rebuild or reformat the
documents, you will need a troff-style formatter (the package
called groff on modern Linux/*BSD.  You will also need the "ms"
macros, should be included with most modern groff, though not
in the scaled-down groff-base packages)

Optionally, if you want to use 'make zip' to build a source 
archive suited to DOS/Windows, you will need the zip program
(generally, a package called zip on most Linux/*BSD)

Older, once-working systems
----------------------------
For the pdp11 version there was once the Ovmakefile, which had only been
tested on 2.9bsd once upon a very long ago.  It supposedly worked.
and it was possible to turn on all the compile time options with that
version. Maybe someone will try a PDP-11 emulator one day with 2.11BSD
and report back?!

The following used to work circa Jove 4.16 in the 1990s and have probably not
been tested in the 21st century, they may still work but some of this
ancient support may be deleted from Jove at some point, we welcome
any recent success stories from jove builders/packagers to refresh
or maintain these. Pretty please! Most need LDLIBS=-ltermcap,
but if you get link errors for tputs or tparm, try LDLIBS=-lcurses

#	Apple A/UX on macIIs		SYSDEFS=-DA_UX
#	BSD4.2,4.3			SYSDEFS=-DBSD4
#	BSD4.1				SYSDEFS=-DBSD4 LDLIBS = -ljobs
#	BSDI, 386BSD, BSD4.4		SYSDEFS=-DBSDPOSIX
#	Consensys V4			SYSDEFS="-DSYSVR4 -DGRANTPT_BUG"
#	Compaq Tru64 UNIX V4.0g, 5.1	SYSDEFS=-DSYSVR4
#	DEC OSF R1.3MK			SYSDEFS=-DSYSVR4
#	DEC OSF/1 V1.3			SYSDEFS="-DBSDPOSIX -DNO_TIOCREMOTE -DNO_TIOCSIGNAL"
#	DEC OSF/1 V2.0 and later	SYSDEFS=-DSYSVR4
#	DEC Ultrix 4.2			SYSDEFS=-DBSDPOSIX
#	DEC Ultrix 4.3			SYSDEFS="-DBSDPOSIX -DJVDISABLE=255"
#	Digital UNIX V4.0 and later	SYSDEFS="-DSYSVR4 -DGRANTPT_BUG"
#	DG AViiON 5.3R4			SYSDEFS="-DSYSVR4 -DBSD_SIGS"
#	HP/UX 8 or 9			SYSDEFS="-DHPUX -Ac"
#	HP/UX 11 (-Ac redundant)	SYSDEFS=-DHPUX
#	IBM AIX 3.2			SYSDEFS=-DAIX3_2
#	IBM AIX 4.2, 5.2		SYSDEFS="-DAIX4_2" LDLIBS="-lcurses -ltermcap -ls"
#	Irix 3.3-4.0.5			SYSDEFS="-DIRIX -DIRIX4"
#	Irix 5.0 onwards		SYSDEFS="-DIRIX -prototypes"
#	Linux (ancient e.g. RedHat 4,5)	SYSDEFS=-DBSDPOSIX
#	MIPS RiscOS4.x			SYSDEFS="-systype bsd43 -DBSD4"
#	SCO Unix			SYSDEFS=-DSCO LDLIBS=-lcurses
#	SunOS3.x			SYSDEFS=-DSUNOS3
#	SunOS4.0*			SYSDEFS=-DSUNOS40
#	SunOS4.1*			SYSDEFS=-DSUNOS41
#	SunOS5.0 (Solaris 2.0)		SYSDEFS="-DSYSVR4 -DGRANTPT_BUG"
#	Sys III, Sys V R 2,3		SYSDEFS=-DSYSV PORTSRVINST='$(PORTSRV)' LDLIBS=-lcurses
#	Sys V Release 4.0		SYSDEFS="-DSYSVR4 -DGRANTPT_BUG" LDLIBS=-lcurses
#	Sys V Release 4.x		SYSDEFS=-DSYSVR4 LDLIBS=-lcurses
#
Some systems based on System V release 4 have a bug affecting interactive
processes.  This bug can be worked around by defining GRANTPT_BUG.
Read the explanation of GRANTPT_BUG in sysdep.txt.

Notes for invoking make:

# For SYSVR4 (/usr/ucb/cc will NOT work because of setjmp.h):
#	CC = /usr/bin/cc
# To use the SunPro compiler under SunOS 4.n:
#	CC = acc
# To use the official Sun compiler under Solaris 2.n:
#	CC = /opt/SUNWspro/bin/cc
# For DG AViiON, expect compile errors unless you use the GNU C compiler:
#	CC=gcc

LDCC is the load invocation of CC which can be changed to invoke
link-time tools e.g. to use Purify(TM), try:
LDCC = purify $(CC)

Systems that used to need LDFLAGS 
#	SysV Rel. 2: LDFLAGS = -Ml
#	SCO Xenix: LDFLAGS = -Ml -F 3000
#	AIX Unix: LDFLAGS = -bloadmap:$@.map # only if loadmap
#
# To optimize the use of the address spaces, add to the LDFLAGS:
#	PDP-11 with separate I&D: -i
#	PDP-11 without separate I&D: -n


For SCO Xenix, this might need to be set
#	LOCALCFLAGS = -Mle
#	OPTFLAGS = -LARGE -O -F 3000 -K -Mle  (say -Mle2 for an 80286)


For compiler OPTFLAGS set in the Makefile:
# On the official Sun ANSI C compiler and the standard System V Release 4
# compiler, adding -Xa -v will increase compiler checking.
# On DEC OSF/1 and Digital UNIX VV4.0, add -std1 to enable ANSI C features
# and perhaps -g3 for more debugging info with optimization.
# Some old versions of the HPUX C compiler have a bug in handling forward
# struct tag declarations.  Using the -Ac flag in place of -Ae will avoid
# this problem (and reduce the compiler's error checking, unfortunately).

# For install on 4BSD, SunOS
#XINSTALL=/usr/ucb/install $(INSTALLFLAGS) -c -m 755 # -s
#TINSTALL=/usr/ucb/install $(INSTALLFLAGS) -c -m 644
# newer Solaris 2.x aka SunOS 5.x
#XINSTALL=/usr/gnu/bin/install $(INSTALLFLAGS) -m 755
#TINSTALL=/usr/gnu/bin/install $(INSTALLFLAGS) -m 444
# SysV-derivatives, or non-BSD Unix (V7, etc)
#XINSTALL=cp
#TINSTALL=cp

Some acknowledgments.
---------------------

Thanks to Jay (hack) Fenlason for writing the original pty code.

Thanks to Dave Curry at Purdue for putting in tons of time and effort
into getting JOVE ready.  It just wouldn't be working without his help.

Thanks to Jeff Mc Carrell at Berkeley for finding bugs and adding
features, in particular, the comment formatter.

Thanks to Karl Gegenfurtner for making the PC version.

Thanks to Ken Mitchum for the Macintosh version.

Thanks to Hugh Redelmeier for his input, his experience, countless bug
fixes, and ... that's it, I guess.

Thanks to Arlindo da Silva and Dave Curry for the original Cygwin ports.

Thanks to Ken Mitchum for the original Mac port.

(Thanks to Brian Harvey for teaching me about linked lists ...)

Good luck, have fun.

	Jonathan Payne (once jpayne@starwave.com, sun.com, marimba.com :-)

Thanks to Charles Lindsey for the xjove/jovetool and xterm mouse support.

Thanks to Jim Patterson for the Win 32 port.

Thanks to the other JoveHacks for testing and for contributing numerous
fixes, portability enhancements, and pieces of sage advice.

	D. Hugh Redelmeier

Thanks to Cord Beermann for Debian packaging, Peter Cock for conda packaging,
Paul Vixie for FreeBSD packaging and many fixes.

        Mark Moraes

Changes in 4.17.*
-----------------

- github
- Portability fixes, mainly removal of overlapping strcpy
  for Linux, *BSD, Darwin/MacOS, but also Windows and MinGW
  fixes, FreeDOS (!), OpenIndiana.
- Much build cleanup/revamp. Remove some ancient systems from
  sysdep.h since there seems no hope of testing them.
- Use aspell if available on Linux
- Handle terminals wider than 256 chars!
- Handle line-numbering correctly if >1M lines!
- Default line length max to 32K now
- Fast/simple code to directly handle 99.9% of all currently
  used terminals (vt100+ derivatives) without needing termcap/terminfo/curses.
- Do not allow writeback of files if lines were too long, and thus truncated,
  do not conflate shell output windows with files of the same name.
- Horizontal scroll of the minibuffer.

Changes in 4.16.*
------------------

- Portability fixes.  Most important: work around a never-to-be-fixed
  bug in ncurses (the freely redistributable termcap/terminfo
  database).

- Various minor bug fixes.  Highlights:
  + use mkstemp to avoid a security loophole
  + avoid bad interaction between metakey and xterm mouse support
    in windows wider than 95 characters
  + handle symlinks better
  + obscure bug in text justification that could hang JOVE
  + misuse of stat that only misbehaved on LINUX

Changes since 4.16beta
----------------------

- Added the variable paragraph-delimiter-pattern to customize paragraph
  recognition.

- Ported to Win 32 (but not Win 32s)

- Several variables have been renamed to more clearly indicate their function.
  The old name will still work, but eventually it will be eliminated.
	allow-bad-filenames => allow-bad-characters-in-filenames
	display-bad-filenames => display-filenames-with-bad-extensions
	internal-tabstop => tab-width

- Several minor bugs fixed.  Several portability improvements.
  + MSDOS: avoid date rollover problem
  + Borland C: support version 4
  + Borland and Microsoft C: enable HIGHLIGHTING
  + NetBSD: dodge ssize_t redefinition
  + SCO UNIX: use <ctype.h>
  + SunOS + Solaris: make charp effective
  + generic: Ensure screen is maintained during non-interactive processes,
    even if the user has typed ahead

- The xterm mousing interface has been completely revamped.
  Some small ancillary consequences of this are
  + A next-line (prev-line) landing in the middle of a Tab selects the Tab
    character (rather than the following one)
  + A yank-pop is no longer permitted to follow a copy-region.

Changes since version 4.14.6.
-----------------------------

JOVE now works on many newer systems.  For example, it compiles
under Solaris 2.n (SYSDEFS=-DSYSVR4).

The uninstalled binary in the JOVE directory is jjove instead of xjove
(xjove is now something else).

The new command line flag -J inhibits the reading of the global
jove.rc file.  Similarly, -j inhibits ~/.joverc.

JOVE's auxiliary files are kept in two directories (actually, they can be
the same directory).  The sharedir holds the system jove.rc and cmds.txt,
the data used to implement the describe-command and describe-variable
commands; these files are meant to be machine-independent.  The libdir
holds portsrv and recover; these are compiled programs, and are
machine-dependent.

There are three ways JOVE uses to determine each of the directories, two
of them new.  If JOVE was invoked with -l dirname, dirname is taken as
the LibDir; otherwise, if the environment contains JOVELIB, its value is
taken as the LibDir; otherwise, the value of the make variable $(LIBDIR)
when JOVE was compiled is used as LibDir.  Similarly, -s dirname,
JOVESHARE, and $(SHAREDIR) specify ShareDir.  As a shortcut, -ls dirname
specifies both directories.  Now, a good way to test an uninstalled
version of JOVE is to say, within the JOVE directory,
	jjove -s doc -l . other_parameters

A new command "pushlibd" effectively does a pushd command with ShareDir as
the operand.  This is for use within startup files such as jove.rc.

The global startup file is now in doc/jove.rc (was doc/system.rc), so the
-s flag can find it as above.  It contains lots of goodies (you might not
want all of them), including an ability to call up additional TERMinal
specific startup files depending on the $TERM environment variable.
Among other things, these provide support for the many wacky keys that
terminal makers provide.  See doc/README.

The old make-keymap and bind-keymap-to-key commands are no longer needed.
Instead, bind-to-key can accept character strings of any length (they had
better not be a prefix of any other binding).  This enables, among other
things, binding commands to the function keys on Sun keyboards.  Buffer-
specific bindings are now supported (local-bind-* commands).

All system dependencies are now gathered together in the file sysdep.h, to
make it easier to select the bits of code which should or should not be
included for various flavors of UNIX.

The position of the mark is now indicated by underlining it (the position of
point is, of course, indicated by the cursor, so the extent of the region is
now easily seen).  The bad news is that, although this works well on
terminals, underlining is broken in some environments (notably SunView
and the versions of OpenWindows with SUNOS4.1.x and Solaris 2.0 -- Solaris
2.1+ is OK).  For the broken OpenWindows versions, you can include the
following in your .Xdefaults file
	term.boldStyle:				Offset_X_and_Y
	term.underlineStyle:			Same_as_Bold
The stock X11 terminfo entry for xterm was broken until X11R6 in a way that
will cause the screen to be scrambled when JOVE tries to use underlining.
The following fixes to the entry solve this problem and more:
	replace "blink=@," with "blink@,"
	replace "rs2=@" with "rs2@," [note the added comma!]
	add "kf1=\EOP," [if not already be present]
	delete "smul@,"	and "rmul@," [if present]
	add "smul=\E[4m, rmul=\E[m," [xterm does support underlining]

The portion of the buffer visible in the window is now indicated by
"uninverting" a part of the modeline in proportion.  This feature is really
intended for use with "xjove" (described next), and there is a variable
"scroll-bar" to enable it.

xjove is a complete front-end for JOVE which will be found in the directory
xjove (see the README there).  It enables setting of point and mark with the
mouse, cutting and pasting of text via the region, and scrolling by pointing
into the modeline.  It is written using the XView library (supplied with
Suns, or with the X-distribution from MIT); there is also a version for
Sunview known as jovetool.  See its man entry in doc/xjove.nr.

An alternative way of using the mouse is provided in the form of commands
designed to recognize the mouse events coded by Xterm.  These facilities
are not nearly as extensive or convenient as those provided via xjove or
jovetool.

Within SHELL windows, the TERM environment variable is now set to "dumb",
mainly to discourage running programs which might have depended on something
else.  Some shells (tcsh, for example) might prefer the emacs
terminal type;  JOVE also sets the INSIDE_JOVE variable, which can
be used to set things up for shells, as well as the proc-env-export,
and proc-env-unset commands for subshells and corresponding
iproc-env-export and iproc-env-unset commands for interactive processes.

By default, commands requiring a "y" or "n" response require a Return as
well.  When variable "one-key-confirmation" is set "on", a single
character "y" or "n" is expected.

Some features have been removed.  Marks always float, so the variable
"marks-should-float" is gone.  The IBMPC-specific commands scroll-*-page
are gone.

JOVE is now 8-bit clean (the old behavior can be retained by setting NCHARS
to 128 in sysdep.h, but no known system requires this setting).  In operating
systems with the necessary support (USE_CTYPE set in sysdep.h) it is
possible to set the environment variable LC_CTYPE (or the JOVE variable
lc-ctype) to a "locale" such as "iso_8859_1", whereupon characters with the
8th bit set sent from the keyboard (using the Alt Graph key, or the Compose
key, or the Meta key, or whatever the particular hardware provides) will be
displayed correctly, and will be treated as upper/lower case, etc in the
correct manner.  The default locale is "C", which reverts to 7-bit ASCII with
the top 128 characters being displayed in octal.

The format of the "jrec" file (now "jr*" ) has changed.
This means that previous versions of recover cannot deal
with the files left by crashes of the new JOVE, and vice versa.
4.17+ recover will realize this.

Here is a list of reasons why your .joverc might no longer work.  JOVE
places diagnostics about the user and system .joverc files in the buffer
"RC errors".

- JOVE no longer ignores extra stuff on the end of binding commands.

- All keymap creation is implicit.  You no longer can or need to create
  new keymaps explicitly.

- auto-execute-command no longer magically supplies a numeric argument
  for its command.  If the command is intended to set a mode, you should
  supply the argument.  If you don't set the numeric argument, the mode
  will be flipped.  Here is an example from the system jove.rc:
	1 auto-execute-command c-mode .*\.[chy]$

- Within regular expressions, alternatives are separated by "\|".
  Previously, alternatives within braces were separated by ",".
  For example, "/tmp/\{Re,article,rnmail,pn\}" must be changed to
  "/tmp/\{Re\|article\|rnmail\|pn\}".

- auto-execute-command and auto-execute-macro both require explicit
  patterns.  Previously, the pattern would default to match every filename.

- Certain commands and variables have been eliminated or renamed:

	bind-keymap-to-key, make-keymap, process-bind-keymap-to-key --
		no longer needed
	unbind-key -- bind the "unbound" command instead
	marks-should-float -- they always do now
	physical-tabstop -- now picked up from termcap
	scroll-next-page, scroll-previous-page -- IBM PC only, and useless
	background-color => background-attribute -- IBM PC only
	foreground-color => foreground-attribute
	mode-line-color => mode-line-attribute

- On the IBM PC, the Delete key now generates the ASCII DEL character;
  Control-@ and Control-Space now generate the ASCII NUL character.


Known problems
--------------

In an interactive process buffer, JOVE sometimes fails to
receive an end-of-file through the pseudo-tty, reporting
"[Process i-shell: Exited 0; not EOFed]" rather than
"[Process i-shell: Done]".  In this case, the process window
will not be considered done, even though the child and all
its ancestors are dead.  The only consequences are that the
status display continues to report that the process is not
done and that another process may not be started up in that
buffer.  This only happens on certain systems, not sure why.
For example, this worked fine upto Debian 9, and broke in
Debian 10 (using SYSVR4 ptys), and is fixed by switching to
GLIBCPTY.  e.g. https://github.com/jonmacs/jove/issues/6

If a window-find command is issued while the current window's lines
are numbered, the numbering may become wrong temporarily.  We are
working on this bug.

JOVE can not handle lines longer than JBUFSIZ characters
(usually 4096, but 512 on some small systems).  Eliminating
this limit is not easy.  JBUFSIZ is 2^LG_JBUFSIZ, which can
be raised; JOVE keeps NBUF such buffers in memory and
reads/writes these from/to a temporary file, and lines may
not exceed a buffer, so making LG_JBUFSIZ larger increases
the max line length.  However, it increases memory
consumption, though that only matters on machines in the
sub-megabyte range.

JOVE can not handle NUL characters in the buffer.  In most cases,
they are discarded silently, another dubious feature.

JOVE does not handle Unicode (aka UTF-8), it silently ignores LANG,
locale etc.  Fixing this limitation is not easy.

Bug Reports and Maintenance.
----------------------------

Jonathan Payne no longer works on JOVE.

A group of JOVE maintainers supports the
github.com/jonmacs/jove releases and welcomes:

- help or success reports or issues with porting for additional systems

- bug reports (we may already have an explanation or fix)

- suggestions for and implementations of improvements or additional
  features (we do try to keep JOVE small)

See https://github.com/jonmacs/jove for JOVE updates.

A mailing list for discussions and mutual help amongst JOVE users exists
at jove-users _at_ freelists _DOT_ org
