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.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
kill-line) works at last.
latin-1-mode.
transpose-chars, transpose-words,
transpose-exps. Bound to Ctrl-t, Meta-t and
Ctrl-Meta-t respectively.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
text-mode and indented-text-mode major-modes for editing
English language (as opposed to programming languages).
overwrite-mode makes typed keys overwrite whatever’s under the cursor.
Also included is a minor mode to do auto-filling (word wrap).
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Jade will only run on certain operating systems, this chapter details just what it needs as well as some notes relevant to each system.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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’.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 (1) this is no
good. What I decided to do about this was two things,
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.
Backspace and Delete keysyms.
This means that everything works okay! You can bind to <Delete> key and it will work properly.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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).
The buffer being edited in the current window (see below), most editor commands work on this buffer unless told otherwise.
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).
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.
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).
One line in a window is devoted to displaying messages from the editor, @ref{Using Windows}.
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.
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.
A form is a single Lisp expression. For example, all of these are forms:
foo 42 "hello" (setq foo 200)
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).
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.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| 6.1 Modifiers | Names of modifier keys | |
| 6.2 Keys | Names of actual keys | |
| 6.3 Example Keys | Some examples and what they mean |
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The shift key.
The control key, or its equivalent.
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,
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.
The left mouse button.
The middle mouse button.
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>).
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
The space bar.
The tab key.
The return key.
The escape key.
The backspace key.
The delete key.
The help key, not all keyboards have this.
The cursor up key.
The cursor down key
The cursor left key.
The cursor right key.
Keys on the numeric keypad. For <KP_n>, n is a digit.
Single clicking a mouse button.
Double clicking a mouse button.
Releasing a mouse button.
Moving the mouse. This doesn’t work on X11 yet.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Some examples of proper key names are,
Hold down Control, type <x>.
Hold down Meta and Shift, then type the Return key, or alternatively, type the Escape key then hold down Shift and type Return.
Click the left mouse button once.
Hold down Ctrl then click the right mouse button once.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| 7.1 Invocation | How to start the editor | |
| 7.2 Startup Options | Arguments specified on the command line | |
| 7.3 Startup Procedure | What happens on startup |
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Since Jade supports two vastly different operating systems they both need to be covered separately.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The normal way to start Jade on the Amiga is to type its name at the Shell (or CLI) together with any options (see section 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.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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.
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.
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.
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.
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’.
The name to use when looking up resource values, this replaces the base name of
the executable (normally jade).
Specifies where to place the first window on the screen. This is a standard X style geometry specification.
The colour of the window’s foreground (i.e. the text).
The background colour of the window.
The name of the font used for all text in the initial window.
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.
Print the version and revision numbers of this copy of the editor then quit.
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.
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,
Call the Lisp function function.
Load the Lisp file file.
Quit cleanly.
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’.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This is a description of what happens when the editor initialises itself.
Some selected highlights of what the standard file does are,
Initialise the autoload stubs.
Creates the standard keymaps and key bindings.
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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!).
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| Jump to: | M |
|---|
| Index Entry | Section | ||
|---|---|---|---|
| | |||
| M | |||
meta-sends-esc | 6.1 Modifiers | ||
| | |||
| Jump to: | M |
|---|
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| Jump to: | A B C D E F I K L M N O R S V W |
|---|
| Jump to: | A B C D E F I K L M N O R S V W |
|---|
| [Top] | [Contents] | [Index] | [ ? ] |
<Backspace> should rub out the key before the cursor and <Delete> should delete the character under the cursor
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.
| [Top] | [Contents] | [Index] | [ ? ] |
| [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on September 19, 2022 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
| Button | Name | Go to | From 1.2.3 go to |
|---|---|---|---|
| [ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
| [ < ] | Back | Previous section in reading order | 1.2.2 |
| [ Up ] | Up | Up section | 1.2 |
| [ > ] | Forward | Next section in reading order | 1.2.4 |
| [ >> ] | FastForward | Next chapter | 2 |
| [Top] | Top | Cover (top) of document | |
| [Contents] | Contents | Table of contents | |
| [Index] | Index | Index | |
| [ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on September 19, 2022 using texi2html 5.0.