START-INFO-DIR-ENTRY

* Jade: (jade).			An editor for X11 and AmigaDOS

END-INFO-DIR-ENTRY

This is Edition 1.3, last updated 7 October 1994, of The Jade Manual, for Jade, Version 3.2.

Jade is a text editor for X11 (on Unix) and the Amiga.

Copyright 1993, 1994 John Harper.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Jade
****

Jade is a highly flexible Emacs-style text editor for X11 (on Unix) and AmigaDOS.

This is Edition 1.3 of its documentation, last updated 7 October 1994 for Jade version 3.2.

Copying
*******

Jade is distributed under the terms of the GNU General Public License, this basically means that you can give it to anyone for any price as long as full source code is included. For the actual legalese see the file COPYING in the distribution. I reserve the right to use a different licence in future releases.

The only parts of Jade which are not my own work are the regexp code, this is by Henry Spencer (though I have made some small modifications) and is distributed under his conditions, and the ARexx interface in the Amiga version which is based on MinRexx by Radical Eye Software.

Be aware that there is absolutely NO WARRANTY for this program, you use it at your own risk. Obviously I hope there are no bugs, but I make no promises regarding the reliability of this software.

Introduction
************

Jade is a text editor primarily designed for programmers. It is easily customised through a Lisp-style extension language and can be tailored to the user's own requirements.

Jade is designed to run under a graphical windowing system, systems currently supported are the Commodore Amiga and the X Window System version 11 (but only under Unix).

It is the successor to the editor Jed 2.10 which I released for the Amiga in early 1993. I have decided to rename it now that I have made an X11 version since there is already an editor called Jed available (there is no connection between the two, I haven't even looked at the other one). ``Jade'' is an anagram of ``A Jed'', if you want an acronym you could use ``Just Another Damn Editor'', if you can think of anything better please tell me.

Jade is compatible with GNU Emacs in terms of key presses and command names to a certain extent but it is not intended as a simple copy of Emacs (indeed, when I started this I had never actually used Emacs!). I have tried to take my favourite aspects of all the editors I have used as well as adding features that I have not found elsewhere. Consequently, it is very much the editor that I want --- you may not find it so appealing.

News
****

This chapter lists the major changes to Jade and which release they occurred in. Only changes relevant to you, the user, are detailed; for more explicit history see the ChangeLog files with the sources.

Version 3.2
===========

  * The programmer's manual has finally be written.

  * Undo; devote as much memory as you want to keep track of all modifications to a buffer which can then be wound back.

  * Arguments can be given to commands as they're invoked.

  * Buffer menu for interactive buffer manipulation.

  * An Emacs-style local variables section can be embedded in a file; replaces the naff ::jade-code:: thing.

  * Ctrl-k (kill-line) works at last.

  * Now possible to interrupt jade while it's working (i.e. to let you kill infinite loops).

  * The Help system now has commands to list key bindings, display what is bound to any key sequence.

  * Use of the Latin-1 character set is now controlled by the minor mode latin-1-mode.

  * Can load and save compressed (compress or gzip) files into/out of buffers transparently when running on Unix.

  * Transposing commands; transpose-chars, transpose-words, transpose-exps. Bound to Ctrl-t, Meta-t and Ctrl-Meta-t respectively.

  * Can now run a shell in an editor buffer, very basic (no completion) but it works okay.

  * Support for using gdb through the shell interface, the current frame's source code is highlighted in a separate window.

  * Ctrl-z moves to Ctrl-W so that Ctrl-z can (de)iconify the current window.

  * Some programs written for the previous incarnation will need to be altered; all will have to be recompiled.

Version 3.1
===========

  * Now properly supports characters which print as more than one character (i.e. proper tabs, ^L, \123, etc...). In general any character can print as any sequence of up to four character-images.

  * Doesn't expand tabs to spaces anymore, this means that loading and saving of largish files is noticeably quicker.

  * Files containing NUL characters can be edited (more or less) successfully. Some commands (notably the regexp matcher) still don't like these characters but, in the main, binary files can be edited successfully.

  * Searching and replacing has changed, it's easier to use now and replacing globally is built in.

  * Many improvements to the Info viewer, not least, the dir file doesn't have to have a tag-table anymore.

  * Client editing. This lets you load files into a running editor from a shell. For example, if your mailer runs an editor on the message you're writing you can use the client to edit the message in a Jade that you are running.

  * The buffer prompt's completion is now controllable by the mouse as well as the keyboard. Click the right button to complete the current word. Double-clicking the left mouse button on one of the lines under the ::Completions:: line selects that completion.

  * text-mode and indented-text-mode major-modes for editing English language (as opposed to programming languages).

  * Minor-modes. These provide small variations to the major-modes. For example, overwrite-mode makes typed keys overwrite whatever's under the cursor. Also included is a minor mode to do auto-filling (word wrap).

  * On Unix, a tilde (~) in a filename is handled properly in most cases

  * It is now possible to Meta qualify a key press and it will pretend that you pressed ESC then the un-Meta'd key.

Requirements
************

Jade will only run on certain operating systems, this chapter details just what it needs as well as some notes relevant to each system.

Amiga Jade
==========

The only real requirement for Jade running on an Amiga is that it must run an operating system revision of at least V37 (thats V2.04) and have about 300K free memory available.

It also needs more stack than the average Amiga application. For normal use 20K should be okay. If you want to use the Lisp compiler 50K would be a better bet.

It assumes that its directory is pointed to by the JADE: assignment. This means that the main Lisp files are stored in JADE:lisp/ and the file of doc-strings is JADE:DOC.

X11 Jade
========

Jade will only run on version 11 of X, it has absolutely no support for character terminals or different windowing systems. As long as it compiles it should work on your system.

One problem you might find is that the Backspace and Delete keys don't work properly. As far as I have been able to find out, most X terminals map both the Backspace (normally at the top-right of the alpha-keyboard) and the Delete (normally somewhere above the cursor keys) keys to the Delete keysym. Obviously, since I want these keys to have different effects  (Backspace should rub out the key before the cursor and Delete should delete the character under the cursor) this is no good. What I decided to do about this was two things,

 1. Use xmodmap to map the Delete key to the Backspace keysym. This may sound backwards but most programs seem to use the Delete keysym as what I call Backspace so mapping as I described doesn't break this.

     To do this, I have the following in my .Xmodmap file

          keycode 107 = Backspace

     Note that the 107 is the Delete key's key code on my keyboard, your keyboard may, and probably will, be different.

 2. In the function which binds descriptions of key presses to Lisp forms, swap the meanings of the Backspace and Delete keysyms.

This means that everything works okay! You can bind to Delete key and it will work properly.

Editor Concepts
***************

Before I describe the editor in detail there are several concepts which you should be familiar with. Some will be explained in more detail later.

buffer
     Buffers are used by the editor to store the text that you are editing. Broadly speaking, each buffer holds the contents of one text-file loaded into the editor (it is not necessary for each buffer to be associated with a file, some buffers exist for other purposes for example the *jade* buffer is used to interact with the Lisp system).

current buffer
     The buffer being edited in the current window (see below), most editor commands work on this buffer unless told otherwise.

window
     Corresponds to a window in the window-system. Each window can display one buffer at a single time (although a buffer may be displayed in more than one window at once).

current window
     Jade always keeps track of which one of its windows is active. It is called the current window. Whenever you type a key or press a mouse button in one of Jade's windows, that window automatically becomes the current window. Amongst other things, all messages from the editor are displayed in the status line of the current window.

cursor
     The cursor marks your current position in the current buffer (see above), when you type something it is inserted into the buffer between the cursor and the character preceding it (unless you type a command).

status line
     One line in a window is devoted to displaying messages from the editor, Using Windows.

Lisp
     The programming language which Jade uses, although the internals of the editor are written in C, all commands are written in a dialect of Lisp (even if the command only calls a C function). Jade contains an interpreter, compiler and debugger for this language. See Programming Jade.

variable
     Variables are used to store Lisp values, each variable has a unique name. Note that unlike many programming languages variables in Lisp are not typed, the data values themselves have a type associated with them.

form
     A form is a single Lisp expression. For example, all of these are forms:

          foo
          42
          "hello"
          (setq foo 200)

command
     A command is a sequence of Lisp forms which may be called interactively (i.e. from the keyboard). It may be a key sequence (such as Ctrl-x Ctrl-f) or a Lisp function to evaluate (such as find-file).

regular expression
     A regular expression is a string which is used to match against other strings. It has a special syntax which allows you to form a kind of template against which the other strings can be matched. They are used extensively by the editor, but you --- the user --- will mainly encounter them when searching and replacing strings in buffers.

Key Names
*********

In this manual I have adopted a consistent notation for all key presses, since most editor commands are invoked via a typed key sequence it is very important that you can decipher this notation.

Note that the term input event (or event) and the term key press have been used interchangeably throughout this manual. A key press may mean a mouse event, they don't always come from the keyboard.

Every key press has a set of modifiers; these are the keys such as ``Shift'' or ``Control'' which don't actually produce a character when typed, they only effect the rest of the keyboard. Each key, then, can have one or more modifiers.

The name of an event consists of zero or more hyphen-separated modifier names, followed by a hyphen and the name of the actual event.

Some commands are triggered by more than one of these key presses; press each key (or do whatever is necessary to precipitate the input event) in turn to invoke the command.

Note that the case of modifiers is not important, however some of the keys are, so you should always specify them in their correct case.

Modifiers
=========

Shift
SFT
     The shift key.

Ctrl
CTL
     The control key, or its equivalent.

Meta
     This depends on the window-system, on X11 it is the ``Mod1'' modifier, on the Amiga the ``Alt'' key. When the meta-sends-esc variable is non-nil the Meta modifier is treated specially,

      -- Variable: meta-sends-esc
          When non-nil, any Meta-modified key presses are expanded into a sequence of two key presses, ESC and the pressed key minus its Meta modifier. For example typing Meta-f would expand to ESC f. This feature is provided for compatibility with GNU Emacs.

          What this really means is that when the option is enabled (it is by default) you can either type the key sequence ESC X or the sequence Meta-X (where Meta is your keyboard's meta key) to invoke a command described as Meta-X.

LMB
     The left mouse button.

MMB
     The middle mouse button.

RMB
     The right mouse button.

As well as these, there are also some others, Mod1 to Mod5 represent the X11 modifiers of the same name. Button1 to Button5 also correspond to their X11 counterparts (Button1 to Button3 are LMB to RMB). For Amiga users, Amiga corresponds to the Amiga key (this is the same as Mod2).

Keys
====

As far as possible each single character key-definition corresponds to where that character is on the keyboard (a is a, etc...).

When using an Amiga this should be true for all keys since the Amiga's ``keymap.library'' makes it easy to look up what key a character belongs to. However, this is not so easy on X11. All of the standard ASCII character set should be okay, but the more esoteric characters may have to be specified by the names of their X11 keysym (without the XK_ prefix). Look in the <X11/keysymdef.h> include file for all keysyms, for example XK_question would have to be used for ? if the editor didn't treat it, and many others, specially.

Some keys which don't follow this pattern are

SPC
Space
     The space bar.

TAB
     The tab key.

RET
Return
     The return key.

ESC
Escape
     The escape key.

BS
Backspace
     The backspace key.

DEL
Delete
     The delete key.

Help
     The help key, not all keyboards have this.

Up
     The cursor up key.

Down
     The cursor down key

Left
     The cursor left key.

Right
     The cursor right key.

KP_Enter
KP_Multiply
KP_Divide
KP_Minus
KP_Add
KP_Decimal
KP_N
     Keys on the numeric keypad. For KP_N, N is a digit.

Click1
     Single clicking a mouse button.

Click2
     Double clicking a mouse button.

Off
     Releasing a mouse button.

Move
     Moving the mouse. This doesn't work on X11 yet.

Example Keys
============

Some examples of proper key names are,

Ctrl-x
     Hold down Control, type x.

Meta-Shift-RET
     Hold down Meta and Shift, then type the Return key, or alternatively, type the Escape key then hold down Shift and type Return.

LMB-Click1
     Click the left mouse button once.

Ctrl-RMB-Click1
     Hold down Ctrl then click the right mouse button once.

Starting Jade
*************

This chapter describes Jade's initialisation process. This includes how to start it, what options it will accept and what it actually does after being started.

Invocation
==========

Since Jade supports two vastly different operating systems they both need to be covered separately.

Amiga
-----

The normal way to start Jade on the Amiga is to type its name at the Shell (or CLI) together with any options (see Startup Options) you want. Note that these options are in the traditional Unix style, a dash followed by the option name and any arguments, not the standard AmigaDOS method.

It is also possible to invoke the editor from the Workbench, simply double clicking on its icon will cause Jade to open its initial window. Unfortunately there is no support for passing arguments via Tool Types, nor is there any way to create icons with saved files. This is largely due to the fact that I rarely use the Workbench --- if enough people complain about this I will probably fix it. Jade doesn't have an icon yet, you'll have to make one yourself.

X11
---

Jade should be started like most other Unix programs, type its name and any arguments to a shell. It must be able to connect to an X server (preferably the one controlling your terminal), the -display option can be used if needed.

Startup Options
===============

The acceptable options can be split into three classes. Note that they must be specified on the command line in order of their class. This means that, for example, the -rc option must be after the -font option.

So, the general usage pattern is

     jade [SYSTEM-DEPENDENT-OPTIONS] [STANDARD-OPTIONS] [LISP-OPTIONS]

Note that the LISP-OPTIONS may include files to be loaded.

 1. System dependent options.

       * Options for the Amiga system.

          -pubscreen SCREEN-NAME
               Defines the name of the public screen on which the first window is opened. By default (or if SCREEN-NAME doesn't exits) the Workbench screen is used.

          -font FONT-STRING
               Defines the font used in the first window. FONT-STRING is the font to use, it is the name of the font (for example, topaz.font), followed by a hyphen and the point size to use. For example, a FONT-STRING of topaz.font-8 gives 8-point topaz. This is the default.

          -stack STACK-SIZE
               When this argument is given Jade allocates a new stack. STACK-SIZE is a decimal number defining the size (in bytes) of the new stack.

               If this argument is not given Jade simply uses the stack that AmigaDOS gave it.

       * Options for X11.

          There are two types of options to the X11 version of the editor, those specified on the command line and those defined in the resource database (i.e. in your .Xdefaults file). Resources are looked for under two names, firstly the name under which the editor was invoked (normally jade), if this fails it tries again with the name Jade. Naturally, options specified on the command line override those in the resource database.

          -display DISPLAY-NAME
               Defines the name of the X display to open, by default the contents of the environment variable DISPLAY. It is a string of the form HOST-NAME:NUMBER.SCREEN-NUMBER.

          -name NAME
               The name to use when looking up resource values, this replaces the base name of the executable (normally jade).

          -geometry GEOM-SPEC
               Specifies where to place the first window on the screen. This is a standard X style geometry specification.

          -fg FOREGROUND-COLOUR
          Resource: fg: FOREGROUND-COLOUR
               The colour of the window's foreground (i.e. the text).

          -bg BACKGROUND-COLOUR
          Resource: bg: BACKGROUND-COLOUR
               The background colour of the window.

          -font FONT-NAME
          Resource: font: FONT-NAME
               The name of the font used for all text in the initial window.

 2. Standard options.

     -rc LISP-FILE
          Load the Lisp script LISP-FILE instead of the normal initialisation script (init). Warning: the editor depends heavily on the normal file, if you change this without due care the editor could be unusable --- no keys will be bound and many standard functions won't exist.

     -v
          Print the version and revision numbers of this copy of the editor then quit.

     -log-msgs
          This option makes all messages which are displayed in the status line also be written to the standard error stream. This is sometimes useful for debugging purposes.

 3. All other options are passed to the Lisp initialisation process in the variable command-line-args, these are available to any Lisp packages loaded in the initialisation script. Any left after that are scanned for the following options,

     -f FUNCTION
          Call the Lisp function FUNCTION.

     -l FILE
          Load the Lisp file FILE.

     -q
          Quit cleanly.

     FILE
          Load the file of text FILE into a new buffer.

An example command line for starting Jade from a Unix shell could be

     $ jade -fg white -bg black -log-msgs foo.c bar.jl

This means white text, black background, save messages and load the files foo.c and bar.jl.

Startup Procedure
=================

This is a description of what happens when the editor initialises itself.

 1. Firstly lots of internal data structures are created, memory pools, symbols and their symbol-table (including all the primitive Lisp functions).

 2. The window-system is initialised (parse the system-dependent options, and the xrdb resources if in X).

 3. Parse the standard options.

 4. Create the initial window and the first buffer to display in it (this is the buffer called *jade*).

 5. Load the initialisation script, this is either the Lisp file called init or whatever was given to the -rc command line option.

     Some selected highlights of what the standard file does are,

       * Load lots of Lisp files, some notable ones are

          autoload
               Initialise the autoload stubs.

          loadkeys
               Creates the standard keymaps and key bindings.

       * Try to find the user's personal startup file, this is normally the file .jaderc in their home directory  (The Amiga has no notion of a user's home directory, Jade uses the contents of the environment variable HOME, or if this doesn't exist the SYS: assignment.).

       * Load any files which were specified on the command line.

 6. Start the top-level recursive edit, this doesn't exit until the editor does.

     [file user.texi not included]

     [file programmer.texi not included]

Reporting Bugs
**************

If you think you've found a bug in Jade I want to know about it, there is a list of problems that I am aware of in the src/BUGS file, if yours appears in there tell me anyway to make me fix it.

When submitting bug reports I need to know as much as possible, both about the problem and the circumstances in which it occurs. In general, send me as much information as possible, even if you think it's probably irrelevant.

If you can, contact me via email, my address is jsh@ukc.ac.uk. If you don't get a reply within about a week it's probably a university vacation --- this means that I won't get your message for a while; if it's important try my postal address, this is,

     John Harper
     91 Springdale Road
     Broadstone
     Dorset
     BH18 9BW
     England

As well as bugs I'm interested in any comments you have about the editor, even if you just tell me you hate it (as long as you say why you hate it!).