###########################################################################
# This program is Copyright (C) 1991-1999 by C.H.Lindsey, University of   #
# Manchester.  (X)JOVETOOL is provided to you without charge, and with no #
# warranty.  You may copy, modify, and/or distribute (X)JOVETOOL,         #
# provided that this notice is included in all the files, except insofar  #
# as a more specific copyright notices attaches to the file (x)jovetool.c #
###########################################################################

The two programs in this directory 'xjove' and 'jovetool' are front ends for
the 'jove' editor to enable it to be controlled by the mouse in windowing
environments. 'Jovetool' is for use with Sunview. 'Xjove' is for use with
X-windows.

Both programs were originally based on the 'emacstool' program (although
there is now little resemblance left), and for this reason their Copyright
notices are GNU-like, as opposed to the Copyright notices in the rest of
the 'jove' system.

The full goodies provided by these programs are described in the manual page
{jove}/doc/xjove.nr.

Briefly, it is possible to change windows and to set the point and the mark
by pressing mouse buttons over the appropriate places. It is also possible
to do copy/cut/paste (i.e. copy-region, kill-region, yank) by using the CTRL
and SHIFT keys at the same time.

The third mouse button brings up a menu from which any 'jove' command can be
activated or any 'jove' variable set. This menu is rather large and complex,
so it is suggested that its use will mainly be for browsing through when
searching for the more obscure 'jove' commands. Where a particular command is
in fact bound to some key, that is indicated in the menu, so you can see how
to access it more quickly the next time it is needed.

It is also possible to scroll to any arbitrary point within the file by
clicking the mouse at a proportional position in the modeline below the
particular window. If the 'scrollbar' variable is on (which it always should
be when using 'xjove') the portion of the total buffer visible within the
window has its highlighting reversed.

To compile 'jovetool' you need a Sun running OS4.x. You also need to set the
DEFINES and SYSDEFS macros in the Makefile.  If you build it through the
makejovetool or installjovetool targets of the JOVE Makefile, these will
be set automatically.

To compile 'xjove' you need the XView toolkit which is normally supplied as
part of the Openwindows package on Suns and some other machines. If you do
not have XView, then it may be obtained from the MIT X-distribution. You
need to set the SYSDEFS macro in the Makefile (it is only used to
distinguish SYSVR4 (which includes SunOS 5, also known as Solaris 2) from
any other system). There is also a difference in the 'LDFLAGS' for SunOS 5.
It is also necessary for the OPENWINHOME environment variable to be set
correctly. If you are are a user rather than a hacker of the system, you
may wish to replace the '-g' in the OPTFLAGS macro by '-O'. If you build xjove
through the makexjove or installxjove targets of the main JOVE Makefile,
most of these settings will be inherited (check xjove/Makefile for details).

In the menus brought up by pressing the third mouse button under 'xjove', the
key bindings shown against each command use the function keys (of which
there are an awful lot on the Sun keyboard) as set in the file
{jove}/doc/jove.rc.sun-cmd. If you are not using this binding, or if you
have modified it in any way, then you will need to edit the file jovemenu.c
accordingly. This file consists mostly of preprocessor macros, structured in
a reasonably obvious way. Note that 'xjove' automatically sets the TERM
environment variable of 'jove' to 'sun-cmd'. There is nothing that can
be done to change this, because it is a "feature" of XView. Note that
anyone who has a private TERMCAP database will have to ensure that this
includes sun-cmd, or else write a wrapper to disable it.

All the keys on the keyboard are bound to something accessible, even those
not normally useable under shelltool (e.g. the Help key and the keys around
the edge of the keypad). The one exception is the keypad decimal point, also
marked Del. Under normal, default, conditions pressing this is
indistinguishable from pressing the official Delete key. To overcome this,
the following line may usefully be kept in your .xinitrc file
	xmodmap -e 'keycode 57 = KP_Decimal'
xjove will then catch it and send a sequence which can be bound to some
suitable command in a jove.rc file (see jove.rc.sun-cmd).

'Xjove' should understand all of the command line options and X-resources
mentioned in the Sun manual page for 'xview' (in particular -font, -Ww,
-Wh), but do not expect it to work with a proportional font.

'Xjove' is in essence a terminal emulator rather like 'shelltool'. Indeed you
can run a shell in it by saying 'xjove -rc sh', and I regularly run the 'nn'
newsreader in it so that I can then use 'jove' to generate postings and email
in reply to articles. If you call 'jove' from within such a shell (or
newsreader), the mouse facilities will immediately become available.
Similarly, it is possible to call up another machine from the shell (or use
'xjove -rc rsh other_machine') and then use 'jove' on that other machine,
with full benefit of the mouse. Most usually, however, and by default, xjove
immediately calls jove and passes the remaining parameters to it (you can
even run the recover program by typing 'xjove -r').

Because 'xjove' is just a fancy terminal emulator, and because 'jove' itself
is still fundamentally a terminal-based editor, the communication between
'xjove' and 'jove' is only one-way. Information about mouse events can be
passed to 'jove', but there is no feedback from 'jove' to 'xjove'. This is
why such a crude "scrollbar" had to be employed, rather than a more
conventional scrollbar at the side as normally provided by windowing
systems. Someday, someone should write a really good windows-based editor,
but it will be an entirely differently structured program from the
'xjove/jove' combination.

Unusually for an X-Application, xjove normally forks a separate process to
run its window, so that the shell which issued the xjove command can
immediately accept other commands. This was done on the grounds that it is
what most users will require most of the time. Some people, however,
complain that this is not the X or UNIX tradition (they expect you to type
xjove filename &). To avoid religious wars on this issue, command line flags
-f and -nf (fork/no fork) have been provided, and the default state is taken
from the resource xjove.forking (in jovetool, only the -nf flag is provided).

Within 'jove' itself, mouse events passed to it by 'xjove' are acted upon by
code within the file mouse.c. To be sure that this code is included, the
preprocessor variable MOUSE must be defined in sysdep.h. This is done
automatically for any UNIX system.

If you use the 'xterm' terminal emulator, a simplified subset of the
facilities provided by 'xjove' is provided, using a rather similar mechanism
to that used by 'xjove'.

'Xjove' and 'jovetool' were written by Charles Lindsey. Comments, bug
reports, and whatever may be sent to chl@clw.cs.man.ac.uk (or alternatively
to hugh@mimosa.com along with reports on the rest of jove).


KNOWN XVIEW BUG:

xjove terminal emulation is described by the "sun-cmd" termcap and
terminfo entries.  Due to an XView bug, the environment variable
TERMCAP is set to "sun-cmd:te=\E[>4h:ti=\E[>4l:tc=sun:".  (This may be
fixed some day.)  To be correct, the tc capability should be replaced
by the contents of the /etc/termcap entry for "sun".

Any program that uses the termcap-based library will fail.  If a
program uses terminfo, it will avoid this problem.  Solaris programs
normally use terminfo.  At least some Linux systems use terminfo.  One
workaround would be to write a shell script wrapper to unset TERMCAP
before invoking the "real" program.  Use the xjove -rc flag to specify
which program to run.
