Subject: Jove hack (4.6.14.32 patch #11).. _looong_
From: Karel Kubat <[email-masked]>
Date: 22 Jun 1994 19:32:29 GMT
Newsgroups: comp.os.linux.announce

================================================================
			   (Tom's Own Version of)

				    JOVE
		       (Jonathan's Own Version of Emacs)
			      Version 4.6.14.32

	       The Linux Port: by Tom Hageman ([email-masked])
	 	     and Karel Kubat ([email-masked])

	=================================================================

1. Introduction
---------------

You may have seen an older Jove version in Linux before; e.g., the as the
program jove or as the program TeXedit (or TeXeditor). These programs are
ports of the `original' Jove; a lightweight Emacs-look-alike, created by
Jonathan Payne.  Tom Hageman ([email-masked]) has been heavily involved with
Jove over the past few years, porting it to different platforms (DOS, Atari,
several Unix systems) and enhancing it.  The current version of Jove stands at
4.6.14.32 patch-level 11, and should be rightly named something like Tovj
(Tom's own version of Jove, except that that name is unpronounceable).  The
new Jove has a lot more bells and whistles than the old version and is better
portable. It may appear in the future under the name Jat: Jove According to
Tom :)

This document describes the efforts in porting Jove to Linux. I (Karel)
compiled Jove with help of Tom and installed it under Linux 0.99pl15, using
gcc 2.5.7 and libs 4.5.8. I enhanced the /etc/termcap entry for the console
driver, so that all keys in Jove can be named by a symbolic name. Furthermore,
I wrote some useful macros which you can use if you like them.

1.1. Obtaining Jove 4.6.14.32

This version of Jove and future versions can be obtained at ftp.icce.rug.nl by
anonymous ftp. A tar.gz'pped archive can be found under pub/tom/jove. You will
want to get the file jove-4.6.14.32#11.tar.gz (#11 stands for the patch level,
supply a different number for a different patch level). Subdirectories there
contain the MS-DOS and TOS ports, in zip format.

1.2. What are the advantages of Jove?

Why bother installing and using Jove? There is a couple of reasons. First of
all, Jove addresses all key sequences by their symbolic name. The resource
files can (and should) contain no reference to an exact key sequence. E.g., if
your /etc/termcap says that k1 (the F1 key) is Escape-[-A, then you can bind
an editor function to k1; instead of hardwiring ^[[A. That means that when you
use a different terminal type (say, a VT100 over a modem line), you can still
use Jove with the same resource files --- all that is needed is that
/etc/termcap defines k1 for VT100's too. (Incidentally, this means that you'll
have to modify /etc/termcap before you can start using Jove... see section 3.)
In my opinion this is Jove's big advantage over other editors, such as Joe or
Jed, which need hardwired key definitions (or at least often use them).

Second, Jove is very well documented. It contains an extensive on-line help
manual, which documents all built-in commands, variables and macros.  The
archive also contains a LaTeX-able user guide.

Third, Jove is compact. You get the complete editor for a 153k executable plus
some 10k resource files. A 145k online documentation file and a 40k teaching
course are optional.  Even though smaller than the Emacs mammoth, Jove has a
lot of similar functionality: major editing modes (C, Lisp, etc.), minor modes
(brace matching etc.), compiling and error parsing from within the program,
and so on. Jove can be customized to perform even more Emacs-lookalikes.  It
took me about 5 minutes to create a macro to read a manual page in a second
window and to clean up the boldface characters from it... after I had printed
out the documentation, which took the Laser-Jet 1 hour.

Fourth, Jove is memory-friendly. Jove lets you edit a 2-Meg file under
MS-Dog.. 

Finally, Jove is portable. Install the same Jove on your MS-Dog, TOS-Atari and
all Unix platforms you can connect to. You can have the same editor
everywhere.

2. Installing Jove
------------------

This section describes how you can install the `bare' Jove on your Linux box.
Refer to section 3 for my extra Linux hackxs.

2.1. Get the archive.

Obtain the archive through anonymous ftp from ftp.icce.rug.nl, directory
pub/tom/jove. The archive is named something like jove-V.WW.XX.YY#Z.tar.gz,
where V.WW.XX.YY is the version number. Z is the patch level.

Move the archive to your `sources' directory; e.g. to /usr/local/src. Then
unpack it. The archive will yield a subdirectory jove-V.WW.XX.YY. Change-dir
to this directory.

2.2. Modify the Makefile.

Please read the file README, which is created by unpacking the archive. This
file contains general installation guidelines.

Copy the file makefile.ux to Makefile. Edit the Makefile and perform the
following changes:

    o	Choose the program `rm -f' for RM:
	    RM = rm -f
    o	Choose `sed' for SED.
    o	Choose `diff -c2' for CDIFF.
    o	Choose `ctags -dt' for CTAGS.
    o	Choose `install' for INSTALL.
    o	Leave the macro DETEX-SYS empty:
	    DETEX-SYS =
    o   Choose for the macro DETEX-POST the command
	    DETEX-POST =	>$@;\
		${JOVE} -j $@ +j $(DOC)derofcmd.jc;\
                ${JOVE} -j $@ +j $(DOC)usedonly.jc;\
		mv Missing Rejected $(DOC)
    o   Choose for the macro MAKEDEP
	    MAKEDEP = ${SHELL} Makedep -n vars.h -n Local.h -n\
		version.h ${HEADERS} ${SOURCES}
    o   For the directory settings DESTDIR, TMPDIR, LIBDIR etc. I have used
	the following settings (choose your own set if you like):
	    DESTDIR =
	    TMPDIR = /tmp
	    LIBDIR = /usr/local/lib/jove
	    BINDIR = /usr/local/bin
	    MANDIR = /usr/man/man$(MANEXT)
	    MANEXT = 1
	    JSHELL = /bin/sh
    o   The debug/optimize flag for "cc" should be:
	    DEBUG = -O6
    o   Take for the extra libraries to be linked with Jove libtermcap.a:
	    LIBS = -ltermcap
    o   For the SYSTEM macro, which controls the compilation flags, you will
	need:
	    SYSTEM = SYSV_BSD -D_POSIX_SOURCE -D__POSIX__ -DSTDIO
    o   For other compiled-in options, choose from the possibilities. I have
	used
	    OPTIONS = -DLISP -DPERL -DBPC=8 -DCOLOR -DKEYALIAS=KEY_EXT -DCRLF
        The CRLF define allows you to edit DOS files (containing cr/lf
	combinations) just as easy as Unix files.
    o   For the CTABLE (character table) option, take
	    CTABLE = isolatin

2.3. Do a make

This will start the compilation and make the program `xjove'. You might get
warnings during the compilation about arguments to the `select()' function;
about an integer to pointer conversion. You can safely ignore these errors.

When `xjove' is built, test it by typing:
    xjove Makefile
Try moving around with ^B, ^F, ^P, ^N. If all looks well, press ^X^C (this
will exit Jove without saving).

2.4. Do a make INSTALL

This will copy the program to /usr/local/bin/jove, will make the directory
/usr/local/lib/jove and will place some startup resource files in that
directory. Furthermore a number of auxiliary programs is copied to
/usr/local/bin. You're all set now to work with Jove.

2.5. Print out the documentation.

If you want to print out Jove's documentation (strongly suggested, Jove has a
lot of options, functions, commands, etc.), changedir to the directory doc.
Copy the file make-tex to Makefile, and type `make jove.dvi'.

This will produce a dvi file which can be printed or viewed.

2.6. Using xon-xoff

The auxiliary program `xon-xoff' is built and installed to /usr/local/bin
together with Jove. This program attempts to guess whether Jove can use the
characters ^S and ^Q, or whether these characters are used to stop and
re-enable output.

When invoked with the flag `-s', xon-xoff prints a string which can be used to
set an environment variable, XONXOFF, later to be recognized by Jove. You
should therefore enter the line

    eval `xon-xoff -s`

in your startup login file. This file is, e.g., /etc/csh.login for the
tcsh. 

3. My own hackxs, Linux-specific or not
---------------------------------------

This section describes the specific Linux hacks which I made in order to use
Jove properly. Section 3.1 (long) shows my definitions file which, I think,
supplement Jove's standard startup files in a nice way. You can skip over this
section if you don't want to see any examples or think that `my handy'
settings are silly. Section 3.2 discusses some changes in /etc/termcap which I
had to make. Section 3.3 shows how a prompt can be changed for usage in Jove's
sub-shells. You should read the sections 3.2 and 3.3. There is a good chance
that they apply to your setup.

3.1. Jove's startup files

Jove's startup files are copied by the Makefile to /usr/local/lib/jove. The
main resource file here is joverc. I left the `standard' (Tom's standard, that
is) files intact and modified only the file joverc.local in
/usr/local/lib/jove, to include some files from /usr/local/lib/jove/local:

    # /usr/local/lib/jove/joverc.local
    source /usr/local/lib/jove/local/settings
    read-word-abbrev-file /usr/local/lib/jove/local/abbrevs
    source /usr/local/lib/jove/local/keybindings

That way I keep my general settings in a file .../local/settings, my
abbreviations in .../local/abbrevs and my keybindings in
.../local/keybindings.

3.1.1. My abbreviations file

The abbrevs file defines some handy abbreviations; e.g., if I type II, then
Jove expands it to #include <> and moves the cursor between the <> marks (yes,
I write C and C++ programs a lot). This file looks as follows:

    # /usr/local/lib/jove/local/abbrevs
    II:#include <>
    DD:#define
    EM:{\em }
    VV:\verb++
    BI:\begin{itemize}

^I\item
    EI:\end{itemize}
    BD:\begin{description}

^I\item []
    ED:\end{description}
    BV:\begin{verbatim}
    EV:\end{verbatim}

Note how you can place ^M-s in abbreviations; these are expanded to newlines.

3.1.2. My settings file

The settings file contains some settings which I find useful. The first part
of this file may be relevant: Jove collects initialization errors in a buffer
INIT. These errors may contain messages like "^:kH is a subsequence of ^:K1",
as is the case with my setup. Jove considers this message relevant because the
key `^:kh', the Home key on the numeric keyboard, produces the same character
sequence as the key `^:K1', the grey Home key. Jove is right about this: why
let two keys produce the same sequence, thereby making them indistinguishable?
However, my /etc/termcap is defined in this way, so there's not a lot I can do
or want to do about it right now. The first four lines of the file settings
let Jove collect all such messages in the INIT buffer, but remove the
`changed' flag from the buffer. Therefore, Jove won't ask for a filename to
save the buffer.

The other settings in this file define, e.g., the way I like my tabs: at
multiples of four columns.

    # /usr/local/lib/jove/local/settings
  
    # no hassle over keys producing the same code sequence, such as the
    # num-keypad home and the grey home:
    set quiet on
    pick-buffer INIT
    make-buffer-unmodified
    pick-buffer 1
    set quiet off

    # backup files off, scrolling at line 20,
    # searching irrespective to casing, name completion help on,
    # region saving is on for e.g. format command
    set make-backup-files off
    set auto-scroll 20
    set case-ignore-search on
    set completion-auto-help on
    set auto-save-region on

    # I like my tabstops to skip four positions..
    # that is: for non-C modes, 4 positions columns,
    # for C mode, 4 positions indentation level
    set column-format xxxx
    set c-indentation 4
    
    # interactive process end-of-line marker
    process-bind-to-key process-newline ^J

3.1.3.  My keybindings file.

The complete file .../local/keybindings follows. Note also the macro
open-help-window, which opens a second window and loads the file
.../local/help in it.

    # Extra abbrev macros (see the file abbrev)
    define-macro two-back ^B^B
    define-macro four-back ^B^B^B^B
    bind-macro-to-word-abbrev EM two-back
    bind-macro-to-word-abbrev BF two-back
    bind-macro-to-word-abbrev VV two-back
    bind-macro-to-word-abbrev II four-back
    bind-macro-to-word-abbrev ii four-back
    
    # Emacs emulation
    bind-to-key previous-page ^Z
    bind-to-key scroll-down ^X^P
    bind-to-key scroll-up ^X^N
    bind-to-key query-replace-string ^[^R
    
    # Home/End: beginning and end of line
    bind-to-key beginning-of-line ^:kh
    bind-to-key end-of-line ^:kH
    
    # M-Home/M-End: beginning and end of file
    bind-to-key beginning-of-file ^[^:kh
    bind-to-key end-of-file ^[^:kH
    
    # Function key rebinding: F1 to F10 follow here, together with the
    # Esc-F1 .. Esc-F10 definitions. The shifted F-keys are bound to
    # select-buffer-1 till select-buffer-10, see ../joverc
    
    # F1: open helpwindow
    define-macro open-help-window ^X1^X4F^X$jove-lib local/help^M^V^X^Z^X^Z^Xn
    bind-macro-to-key open-help-window ^:k1
    # MF1: exit
    bind-to-key quick-exit ^[^:k1
    
    # F2: set mark
    bind-to-key set-mark ^:k2
    # MF2: open window, ask for file
    define-macro open-file-window ^X2^X^F
    bind-macro-to-key open-file-window ^[^:k2
    
    # F3: copy to hold
    bind-to-key copy-region ^:k3
    # MF3: 
    bind-to-key delete-current-window ^[^:k3
    
    # F4: yank region
    bind-to-key yank ^:k4
    # MF4: next window
    bind-to-key next-window ^[^:k4
    
    # F5: delete region
    bind-to-key kill-region ^:k5
    # MF5: get manpage
    bind-macro-to-key man ^[^:k5
    
    # F6: format paragraph
    bind-to-key fill-paragraph ^:k6
    # MF6: switch file
    bind-to-key find-file ^[^:k6
    
    # F7: search
    bind-to-key i-search-forward ^:k7
    # MF7: shell
    bind-to-key shell-command ^[^:k7
    
    # F8: search next
    bind-macro-to-key find-next ^:k8
    # MF8: next buffer
    define-macro switch-to-next-buffer ^Xb^M
    bind-macro-to-key switch-to-next-buffer ^[^:k8
    
    # F9: goto line
    bind-to-key goto-line ^:k9
    # MF9: shrink window
    bind-to-key shrink-window ^[^:k9
    
    # F10: replace
    bind-to-key query-replace-string ^:k0
    # MF10: grow window
    bind-to-key grow-window ^[^:k0
    							  
3.1.4. The file /usr/local/lib/jove/local/help

Finally, here's the file /usr/local/lib/jove/local/help, which gets loaded by
the macro `open-help-window', bound to F1:

    ----Function keys:------------------------------------------------------
    F1:help       F2:set mark   F3:copy reg   F4:yank       F5:del region
    F6:format     F7:search     F8:srchnext   F9:gotoline   F10:replace
    ----Escape-function keys:-----------------------------------------------
    MF1:exit      MF2:open win  MF3:close win MF4:next win  MF5:manpage
    MF6:switch    MF7:shell     MF8:nextbuf   MF9:smaller   MF10:bigger
    ----Other help:---------------------------------------------------------
    M-h:apropos, M-M:long help

Well, that's about all about my own definitions files; at least as they are
currently. I hope that these listings provide either a starting point for your
own files, or at least some useful examples.

3.2. Changes in /etc/termcap

I had to patch /etc/termcap so that Jove would recognize the shifted function
keys. These keys select (as defined in the original /usr/local/lib/jove/joverc
startup file) the buffers 1 to 10, and are named in Jove F1 to F0 (a
suggestion of Tom's, the Mad Termcap Hatter), similarly to the unshifted
function keys, which are named k1 to k0.  /etc/termcap unfortunately contains
only the k1 to k0 definitions, not the F1 to F0 entries.

The way to make such extra entries in /etc/termcap is the following: in one
virtual console, edit /etc/termcap. Search for the `console' terminal
definition and enter a line

    :F1=

In a second virtual console, start the program `cat' (without arguments,
thereby copying stdin to stdout) and press Shift-F1. The output will show
something like ^[[23~, which you should read as: escape (^[), [, 2, 3, and a
tilde.

Now switch back to the edit session of /etc/termcap and finish the F1 entry,
which should then read:

    :F1=\E[23~:

Then you can move on to Shift-F2 etc. My whole console entry in /etc/termcap
now reads (only the last two lines are added):

    console|con80x25|dumb:\
	:do=^J:co#80:li#25:cl=\E[H\E[J:sf=\ED:sb=\EM:\
	:le=^H:bs:am:cm=\E[%i%d;%dH:nd=\E[C:up=\E[A:\
	:ce=\E[K:cd=\E[J:so=\E[7m:se=\E[27m:us=\E[4m:ue=\E[m:\
	:md=\E[1m:mr=\E[7m:mb=\E[5m:me=\E[m:is=\E[1;25r\E[25;1H:\
	:ll=\E[1;25r\E[25;1H:al=\E[L:dc=\E[P:dl=\E[M:\
	:it#8:ku=\E[A:kd=\E[B:kr=\E[C:kl=\E[D:kb=^H:ti=\E[r\E[H:\
	:ho=\E[H:kP=\E[5~:kN=\E[6~:kH=\E[4~:kh=\E[1~:kD=\E[3~:kI=\E[2~:\
	:k1=\E[[A:k2=\E[[B:k3=\E[[C:k4=\E[[D:k5=\E[[E:k6=\E[17~:\
	:k7=\E[18~:k8=\E[19~:k9=\E[20~:k0=\E[21~:\
	:K1=\E[1~:K2=\E[5~:K4=\E[4~:K5=\E[6~:\
	:pt:sr=\EM:vt#3:xn:km:bl=^G:vi=\E[?25l:ve=\E[?25h:vs=\E[?25h:\
	:sc=\E7:rc=\E8:cs=\E[%i%d;%dr:\
	:F1=\E[23~:F2=\E[24~:F3=\E[25~:F4=\E[26~:\
	:F5=\E[28~:F6=\E[29~:F7=\E[31~:F8=\E[32~:F9=\E[33~:F0=\E[34~:\

As mentioned earlier, /etc/termcap contains conflicting definitions for some
keys. E.g., the two lines:

    :K1=\E[1~:K2=\E[5~:K4=\E[4~:K5=\E[6~:\

and

    :ho=\E[H:kP=\E[5~:kN=\E[6~:kH=\E[4~:kh=\E[1~:kD=\E[3~:kI=\E[2~:\

will cause a conflict: :K1 sends the same as :kh, :K2 sends the same as :kP,
etc. While modifying /etc/termcap, you may wish to disable one of the
offending sequences. To accomplish this, you could change :K1 into :.K1
(notice the dot): this would disable the K1 definition.

3.3 Changing the prompt for subshells, using tcsh

One of Jove's nice features is that you can run a fully interactive shell
process in a secondary window. The nice thing about it is that you can then
paste the output of some program back into your text, or that you can use
Jove's editing capabilities in the shell window; e.g. to re-edit the command
and to run it again. Also you can scroll back as far as the shell output goes.

I ran into a small problem while using interactive shells (well, not really a
problem but an unesthetic feature). My prompt for the tcsh contains escape
sequences, such as the printing of the tty number in boldface. On a virtual
console this looks cool, but in Jove's shell window the escape sequence
doesn't get expanded to a `boldface' color but instead shows as the literal
escape sequence ^[b1 or something similar.

I deviced the following work-around: I reset the prompt to the string
`Subshell:'  for subshells, hence also for Jove's shell window. This is done
in /etc/csh.cshrc, the system-wide tcsh resource file.  The last lines of my
file /etc/csh.cshrc file look as follows:

    if ($shlvl == 1) then			    # system prompt
	set prompt="%s[$ttynum] %m\:%/%s\n"	    # with highlighting
    else
        set prompt='Subshell: '			    # prompt in subshells
    endif				            # without highlights

-- 
Karel Kubat ([email-masked]).
Incognito ergo sum.

--
Mail submissions for comp.os.linux.announce to: [email-masked]
PLEASE remember Keywords: and a short description of the software.