1 Using Jade

This chapter of the manual is meant to teach you to use the editor, because of this I have attempted to reduce references to the Lisp extension language to an absolute minimum.

1.1 Invoking Commands

Throughout this manual I have documented the key sequences you have to enter to make the editor perform a certain action. In fact, the key sequences are mapped to commands when they are typed and it is the command which performs the action.

Commands are simply pieces of Lisp code, usually with a unique name associated with that command. If you know the name of a command it is possible to invoke it using the Meta-x key sequence; simply type Meta-x command <RET> where command is the name of the command you wish to invoke.

Meta-x

Prompt for the name of a command (completion is available) then invoke it.

For the sake of simplicity I have often referred to key sequences as commands; what I actually mean is that the key sequence is bound to the command. For example the key sequence Ctrl-x Ctrl-f opens a file, in fact the key sequence Ctrl-x Ctrl-f is bound to the command find-file, this Lisp function actually loads the file.

More detailed information about commands is available in the programmer’s manual, see @ref{Programming Jade}.

1.2 Command Arguments

The actions of many commands can be altered by giving them a numeric argument, this argument is entered immediately prior to invoking the command (they are technically called prefix arguments).

Each argument is built using a number of special key sequences,

Meta-0 to Meta-9

Append a digit to the end of the current prefix argument. Use a sequence of these keys to build up a decimal number. For example typing Meta-1 Meta-0 Meta-0 creates an argument of 100 for the following command.

Meta--

(That’s Meta-minus.) Negates the value of current argument, if the command is invoked after a single Meta-- prefix the actual argument is -1.

Ctrl-u

Successive Ctrl-u key presses multiply the argument by 4 each time. Note that any existing argument entered by the numeric or minus commands (described above) is discarded with the first Ctrl-u.

1.3 The Help System

To invoke the help system type the key sequence Ctrl-h or if your keyboard has it the <HELP> key.

A prompt will be displayed in the status line showing you which keys you can press next to enter one of the main options of the help system explained below. Alternatively, you can type either Ctrl-h or <HELP> again to display some text telling you more about the help system and how to use it.

The help system is exited after successfully invoking one of the commands described below or typing anything which is not a recognised command to the help system.

a

To list all function names matching regexp, type a regexp <RET> when in the help system.

b

Prints all key bindings and their associated commands which are installed in the current buffer.

e

Similarly to the a command, to list all variable names matching regexp, type e regexp <RET> when in the help system.

f

Displays the online documentation for a function. After invoking this option type the name of the function.

h

Shows some helpful text describing how to use the help system.

i

Enters the Info viewer. This allows you to browse through files written in the Info hypertext format. For more information see Info Mode, for more information on Info files in general see (info)Info.

k

Displays the command (with its documentation) for a key sequence. After typing Ctrl-h k enter the key sequence you want documented as if you were going to invoke the command.

m

Display the documentation for the current major mode.

v

Displays the online documentation and current value of a variable. Type the name of the variable after invoking this option.

1.4 Loading and Saving Files

Since Jade is a text editor its main function is to edit files of text. This means that you must be able to read the text contained in a file into one of the editor’s buffers, then save it back to disk when you have finished editing it. That is what this section deals with.

1.4.1 Commands To Load Files

There are several commands used to load files into buffers, these are,

Ctrl-x Ctrl-f

Prompts for the name of a file (using file-completion) and display the buffer containing that file. If the file has not already been loaded it will be read into a new buffer.

Ctrl-x Ctrl-v

Prompts for the name of a file, the current buffer is killed and the buffer in which the prompted-for file is being edited is displayed. As in find-file it will be read into a new buffer if it is not already in memory.

Ctrl-x Ctrl-r

Similar to find-file except that the buffer is marked as being read-only. This means that no modifications can be made to the buffer.

Ctrl-x i

Prompts for a file, then inserts it into the current buffer at the cursor position.

You can use the prompt’s completion feature to expand abbreviated filenames typed to the prompt, for more information see The Buffer Prompt.

1.4.2 Commands To Save Files

These are the commands used to save buffers and the key sequences associated with them,

Ctrl-x Ctrl-s

Saves the current buffer to the file that it is associated with (this is either the file that it was loaded from or something else set by the function set-file-name). If no modifications have been made to the file since it was loaded it won’t be saved (a message will be displayed warning you of this).

Ctrl-x Ctrl-w

Prompts for a name to save the file as. The file associated with this buffer is renamed and the file is saved as its new name.

Ctrl-x s

For each buffer which has been modified since it was loaded, ask the user if it should be saved or not. If so, the command save-file is used to save the file

1.4.3 File Variables

It is often useful to define ‘local’ values of certain variables which only come into effect when a particular file is being edited. Jade allows you to include a special section in a file which, when the file is loaded, is used to give the variables specified buffer-local values. (For more information about buffer-local variables see @ref{Buffer-Local Variables}.)

The special section must be somewhere in the last twenty lines of a file, and must be formatted as in the following example,

XXX Local Variables: YYY
XXX variable:value YYY
…
XXX End: YYY

That is, the string ‘Local Variables:’ followed by as many lines defining local values as necessary then the string ‘End:’. The two strings ‘XXX’ and ‘YYY’ may be anything (even nothing!) as long as they are the same on each line. They are normally used to put the local variable section into a comment in a source file.

For example, in a Texinfo source file the following piece of text at the bottom of the file would set the column at which lines are broken to 74 (note that ‘@c’ introduces a comment in Texinfo).

@c Local Variables:
@c fill-column:74
@c End:

Two pseudo-variables which can be set using a local variables section are ‘mode’ and ‘eval’. Setting the ‘mode’ variable actually defines the major mode to use with the file (see section Editing Modes) while setting ‘eval’ actually evaluates the Lisp form VALUE then discards its value.

For example,

/* Local Variables: */
/* mode:C */
/* eval:(message "How pointless!") */
/* End: */

This Forces the file to be edited with the C mode and displays a pointless message. Note that no variables called mode or eval are actually set.

Several variables are used to control how the local variables feature works.

Variable: enable-local-variables

Defines how to process the ‘Local Variables:’ section of a file: nil means to ignore it, t means process it as normal and anything else means that each variable being set has to be confirmed by the user. Its default value it t.

Variable: enable-local-eval

This variable defines how the pseudo-variable ‘eval’ is treated in a local variables list, it works in the same way as the enable-local-variables variable does. Its default value is maybe, making each form be confirmed before being evaluated.

Variable: local-variable-lines

Defines how many lines at the bottom of a file are scanned for the ‘Local Variables:’ marker, by default it is 20.

Note that this feature is compatible with GNU Emacs, and since I have tried to keep the names of variables compatible as well, there should be few problems.

1.4.4 Backup Files

The editor can optionally preserve the previous contents of a file when it is about to be overwritten by the saving of a buffer. It does this by renaming the old file, ‘foo’ as ‘foo~’ (the original name plus a tilde appended to it) before it is obliterated.

Variable: make-backup-files

This variable controls whether or not backups are made of files about to overwritten by the function write-buffer (i.e. the commands save-file and save-file-as). When non-nil the old instance of the file is renamed so that it has a tilde appended to its old name.

Variable: backup-by-copying

When non-nil all backups are made by copying the original file instead of renaming it as the backup file. This is slower but less destructive.

Variable: else-backup-by-copying

If backup-by-copying is nil and renaming the original file would not be a good idea (i.e. it might break a link or something) and this variable is non-nil the backup will be made by copying the original file.

1.4.5 Auto-Saving Files

Jade is able to save snapshots of a buffer’s contents at set time intervals. When this time interval expires and the buffer has been modified since it was last (auto-) saved to disk (and the editor is idle) the buffer is saved to a special file (usually the base component of the file’s name surrounded by ‘#’ characters in the file’s directory).

Variable: auto-save-p

When non-nil this makes the function open-file (and therefore the commands find-file, etc) flag that the file it just read should be auto saved regularly.

Variable: default-auto-save-interval

This is the default number of seconds between each auto save. This variable is only referenced when each file is opened.

Its standard value is 120 seconds.

Variable: auto-save-interval

This buffer-local variable controls the number of seconds between each auto-save of the buffer it belongs to. A value of zero means never auto-save.

When the buffer is saved properly (i.e. with save-file and friends) its auto-save file is deleted. Note that this doesn’t happen when you kill a buffer and an auto-save file exists (in case you didn’t mean to kill the buffer).

To recover an auto-saved file (i.e. after an editor crash or something!) use the command recover-file.

Meta-x recover-file

Loads the auto-saved copy of the file stored in this buffer overwriting its current contents (if any changes are to be lost you will have to agree to losing them).

1.4.6 Accessing Compressed Files

Jade contains basic support for reading, inserting and writing buffers which have been compressed using the gzip or compress compression programs. When this feature is enabled such files are transparently decompressed when loaded into the buffer and compressed when saved back to a file.

Unfortunately this doesn’t work on Amigas yet. To install it the Lisp form,

(require 'gzip)

should be in your ‘.jaderc’ file (or you can do this by hand in the *jade* buffer if you want).

After the gzip package has been installed any files loaded into buffers whose filename end in ‘.gz’ or ‘.Z’ are uncompressed, this suffix is stripped when searching for a major mode to install in the buffer but otherwise the buffer’s filename is left intact.

Any buffer saved whose filename ends in one of the above suffixes is automatically compressed (‘.gz’ is compressed by gzip, ‘.Z’ by compress).

1.4.7 Other File Commands

Meta-x delete-file <RET> file-name <RET>

Deletes the file called file-name.

Meta-x rename-file <RET> source <RET> dest <RET>

Renames the file called source as the file dest.

Meta-x copy-file <RET> source <RET> dest <RET>

Makes a copy of the file called source as the file dest.

1.5 Editing Buffers

The majority of keys when typed will simply insert themselves into the buffer (this is not always true but it’s a good assumption) since they have not been bound. Typically this includes all normal characters (i.e. alphanumeric, punctuation, etc) as well as any of the more obtuse key-sequences which have not been bound to a function (Ctrl-l is one of the more useful of these).

The behaviour of the <TAB> key is different to many other editors — it doesn’t insert anything (unless a specific editing mode has bound it to something else, like c-mode for example), generally it just moves the cursor to the next tab stop. This is partly because Jade doesn’t use “proper” tabs and partly because it makes it easier to move around a line (because the key sequence Shift-<TAB> moves to the previous tab stop).

Some miscellaneous editing commands follow.

<RET>

This generally splits the line into two at the position of the cursor, some editing modes may provide an option which automatically indents the line after it’s split.

<Backspace>

Deletes the character before the cursor.

<DEL>

Ctrl-d

Deletes the character under the cursor.

Shift-<Backspace>

Kills the characters between the start of the line and the cursor. See section Killing.

Shift-<DEL>

Kills the characters from the cursor to the end of the line.

Ctrl-<DEL>

Kills the whole line.

Ctrl-o

Splits the line in two at the cursor, but leaves the cursor in its original position.

Meta-d

Meta-<DEL>

Kills from the cursor to the end of the current word.

Ctrl-k

Kills from the cursor to the end of the line, or if the cursor is at the end of the line from the cursor to the start of the next line. Each successive Ctrl-k appends to the text in the kill buffer.

Meta-l

Makes the characters from the cursor to the end of the word lower case.

Meta-u

Upper cases the characters from the cursor to the end of the word.

Meta-c

Capitalises the characters from the cursor to the end of the word, this means make the first character upper case and the rest lower.

Meta-<Backspace>

Kills from the cursor to the beginning of the word.

1.6 Moving Around Buffers

Here is a selection of the most commonly used commands which move the cursor around the current buffer.

<Up>

Ctrl-p

Move one line up.

<Down>

Ctrl-n

Move one line down.

<Left>

Move one column to the left, stopping at the first column.

Ctrl-b

Move to the previous character, at the beginning of the line moves to the end of the previous line.

<Right>

Move one column to the right. This keeps moving past the end of the line.

Ctrl-f

Move to the next character, at the end of a line moves to the start of the next line.

Shift-<Up>

Move to the first line in the buffer.

Shift-<Down>

Move to the last line in the buffer.

Meta-<

Move to the first character in the buffer.

Meta->

Move to the last character in the buffer.

Shift-<Left>

Ctrl-a

Move to the beginning of the current line.

Shift-<Right>

Ctrl-e

Move to the last character in the current line.

Ctrl-<Up>

Meta-v

Move to the previous screen of text.

Ctrl-<Down>

Ctrl-v

Move to the next screen of text.

Meta-<Left>

Meta-b

Move to the previous word.

Meta-<Right>

Meta-f

Move to the next word.

Meta-<Up>

Meta-[

Move to the start of the previous paragraph.

Meta-<Down>

Meta-]

Move to the start of the next paragraph.

<TAB>

Meta-i

Insert a tab character, indenting the cursor to the next tab position.

Note that some editing modes redefine <TAB> to make it indent the current line to its correct depth.

Shift-<TAB>

Move to the position of the previous tab.

Ctrl-<TAB>

Move to the position of the next tab.

Meta-j

Prompt for a line number and go to it.

Meta-m

Move to the first non-space character in the current line.

1.7 Undo

Jade makes it very easy to undo changes to a buffer, this is very useful when you realise that actually, that wasn’t the part of the file you wanted to delete!

Basically to undo the last command type either Ctrl-_ or Ctrl-x u. If the last thing you did was to type some text into the buffer all the consecutively-typed characters count as one command.

To undo more than one command, simply type more than one Ctrl-_ (or Ctrl-x u) consecutively; this will progressively work its way back through the buffer’s history. The first non-undo command cancels this effect, so if you undo too far back invoke a command which doesn’t modify the buffer, then undo whatever you undid.

Ctrl-_

Ctrl-x u

Undo the previous command, or the last block of consecutively typed characters. Successive undo commands work backwards though the undo-history until a non-undo command is invoked.

The exact amount of undo-information kept for each buffer is controlled by the max-undo-size variable. This defines the maximum number of bytes which may be devoted to undo-information in a single buffer, the default is 10000. No matter what this is set to, the last command is always recoverable.

Variable: max-undo-size

The maximum memory which may be devoted to recording undo-information in each buffer.

1.8 Editing Units

To make it easier to remember which key sequences do what Jade provides a number of commands which are similar to one another but operate on different units in the buffer. These related-commands are bound to the same key but with a different prefix or modifier. For example Ctrl-f moves forward one character while Meta-f moves forward one word.

1.8.1 Editing Characters

These are the commands which operate on characters. Note that when an argument (see section Command Arguments) is given to one of these commands it actually operates on number of characters. For example, if you want to delete the next 5 characters starting at the cursor type Meta-5 Ctrl-d.

Ctrl-f

Move forward one character.

Ctrl-b

Move back one character.

<Right>

Move one character to the right, when the end of the line is encountered it’s ignored and the cursor keeps moving to the right.

<Left>

Move one character to the left, stops when the beginning of the line is reached.

Ctrl-d

<DEL>

Deletes the character beneath the cursor.

<Backspace>

Deletes the character before the cursor.

Ctrl-t

Transposes the character before the cursor with the one under the cursor. When given an argument the character before the cursor is dragged forward over that many characters.

Meta-<SPC>

Delete all white space characters surrounding the cursor leaving a single space in their place. If a prefix argument is given that many spaces are left.

Meta-\

Delete all white space characters surrounding the cursor. This is equivalent to the key sequence Meta-0 Meta-<SPC>.

1.8.2 Editing Words

The following commands operate on words. When given a prefix argument they operate on that number of words all in one go.

The syntax of a word depends largely on the major mode being used to edit the buffer with, see Editing Modes.

Meta-f

Meta-<Right>

Move forward one word.

Meta-b

Meta-<Left>

Move back one word.

Meta-d

Meta-<DEL>

Kills characters from the cursor to the start of the next word. See section Killing.

Meta-<Backspace>

Kills characters from the start of the previous word to the cursor position.

Meta-t

Transpose words: the word before the cursor is dragged over the following word. An argument means to drag the word over that number of words.

Meta-u

Convert the characters from the cursor to the start of the next word to upper-case.

Meta-l

Similar to Meta-u but converts to lower-case.

Meta-c

Capitalise the word beginning at the cursor position. What happens is that the next alphabetic character is converted to upper-case then the rest of the word is converted to lower-case. Note that an argument to this command currently has no effect.

1.8.3 Editing Expressions

Expressions are used when editing programming languages; the editing mode for a particular programming language defines the syntax of an expression element in that language. In other editing modes an expression is defined as a single word.

These commands use prefix arguments in the normal manner.

Ctrl-Meta-f

Move forward over one expression element.

Ctrl-Meta-b

Move backwards over one expression.

Ctrl-Meta-k

Kills the following expression, starting from the current cursor position. A negative argument means kill backwards. See section Killing.

Ctrl-Meta-t

Transpose the previous expression with the following one. An argument means to drag the previous one over that many expressions.

1.8.4 Editing Lines

These commands all operate on one or more lines of text. Most use a prefix argument (if entered) to define how many lines to move or operate on.

Ctrl-n

<Down>

Move down one line.

Ctrl-p

<Up>

Move to the previous line.

Ctrl-a

Shift-<Left>

Move to the beginning of the current line.

Ctrl-e

Shift-<Right>

Move to the end of the current line.

Meta-j

Prompts for the number of a line to jump to. If a prefix argument was entered that defines the line number.

Ctrl-<DEL>

Kill the current line. See section Killing.

Shift-<DEL>

Kill from the cursor to the end of the current line.

Shift-<Backspace>

Kill from the cursor to the beginning of the line.

Ctrl-k

If the cursor is not at the end of the line kill the text from the cursor to the end of the line, else kill from the end of the line to the start of the next line.

If this command is given an argument it kills that number of whole lines, either backwards or forwards from the cursor, depending on whether or not the argument is negative or positive. An argument of zero kills from the cursor to the start of the current line.

Ctrl-o

Create a blank new line, leaving the cursor in its original position. A prefix argument says to create that many blank lines.

1.9 Cutting And Pasting

One of the main functions of any editor is to allow you to move around chunks of text, Jade makes this very easy.

Generally, to paste down some text you have to get the text to be inserted into the window-system’s clipboard (1). If the text you wish to paste is in one of the editor’s buffers Jade has a number of commands for doing this, this is sometimes referred to as killing the text. For details of how to kill a piece of text see Killing.

If the text to be pasted is in the same buffer as the position to which you want to copy it there is an easier way than putting it into the clipboard. For more details see Commands on Blocks and the command Ctrl-i.

Once the text to be pasted is in the clipboard there are two commands which can be used to insert it into the buffer before the cursor,

Ctrl-y

Inserts text into the buffer before the cursor. The text inserted is either the current contents of the kill buffer, or the block marked in this window, if one exists.

Ctrl-Y

This is a variant of Ctrl-y, it treats the string that it is pasting as a “rectangle” of text. That is, each successive line in the string (each separated by a newline character) is inserted on successive lines in the buffer but at the same column position. For more details see Rectangular Blocks and the function insert-rect.

1.10 Using Blocks

A block is a section of a buffer, you mark it by specifying its edges (i.e. the first and last characters). This part of the buffer can then have various things done to it, for example insert it somewhere else.

Each window can only have a single block marked at any one time, it will be displayed in the reverse of normal text (i.e. white on black, not black on white).

1.10.1 Marking Blocks

To mark a block you must specify its outermost points, note that the text marked by the block ends one character before the marked position (this is so that it easy to mark whole lines).

Rectangular blocks are a bit different for more information, see Rectangular Blocks.

Note also that block marks shrink and grow as text is deleted and inserted inside them, similar to what normal marks do.

These are the commands used to mark a block,

Ctrl-m

Ctrl-SPC

If a block is currently marked in this window it will unmark it. Otherwise it will either mark the beginning or end of the block depending on whether or not a block has previously been partially marked.

The normal method for marking a few characters is to first make sure that no block is currently marked (the status line displays the status of the block marks, a ‘b’ means that one end of a block has been marked and a ‘B’ means that both ends of a block are marked in which case it will be highlighted somewhere in the buffer) then press Ctrl-m at one end, move the cursor to the opposite end and press Ctrl-m again.

Ctrl-x h

Mark the whole of the buffer.

Meta-@

Mark the current word.

Meta-h

Mark the current paragraph.

Another method for marking a block is to use the mouse, double clicking the left mouse button on a character has the same effect as moving to that character and typing Ctrl-m. Similarly, clicking the left mouse button while pressing the <SHIFT> key clears a marked block.

1.10.2 Commands on Blocks

Ctrl-i

Inserts the block marked in this window, at the cursor position, then unmarks the block.

Ctrl-w

Kills the contents of the marked block, for information about killing see Killing.

Meta-w

Similar to Ctrl-w except that the text is not actually deleted, just stored for later recall.

Ctrl-W

Deletes the text in the currently marked block.

Ctrl-x Ctrl-l

Makes all alpha characters in the current block lower case.

Ctrl-x Ctrl-u

Makes all characters in the block upper case.

1.10.3 Rectangular Blocks

Normally blocks are thought of sequentially from their first to last characters. It is also possible to mark rectangular blocks, the block marks being thought of as the opposite corners of the rectangle.

The commands which operate on blocks automatically check whether the current block is a rectangle; if so they change their function accordingly. For example, the Ctrl-i command (insert-block) understands that rectangular blocks have to be inserted in a different manner to normal, sequential, blocks.

Ctrl-M

Toggle between marking sequential and rectangular blocks, each window has its own value of this attribute (i.e. one window can be marking rectangles while the rest don’t).

Ctrl-Y

Similar to Ctrl-y except that the string inserted is treated as a rectangle — newline characters don’t get inserted, instead the next line is inserted in the next line in the buffer at the same column as that inserted into the previous line. For more details see the function insert-rect.

At present there is a problem with changing the case of a rectangular block with Ctrl-x Ctrl-l or Ctrl-x Ctrl-u, they treat it as a sequential block. This will be fixed soon.

1.11 Killing

Killing is the general method for deleting a piece of text so that it can later be re-inserted into a buffer. Each time you kill some text it is stored in the window-system’s clipboard (see see section Cutting And Pasting) where it can be accessed by Jade or other programs.

The text copied by successive kill commands are concatenated together, this makes it easy to incrementally save text a piece at a time.

The main commands for killing are as follows, they are only described in brief since their full descriptions are in other parts of the manual.

Ctrl-w

Kill the current block. See section Using Blocks.

Meta-w

Kill the current block without actually deleting it from the buffer.

Ctrl-k

Kills the current line. See section Editing Lines.

Meta-d

Kill the word starting from the cursor. See section Editing Words.

Meta-<Backspace>

Kills from the cursor to the beginning of the current word.

Ctrl-Meta-k

Kill the expression following the cursor. See section Editing Expressions.

1.12 Searching and Replacing

It is very easy to search any of Jade’s buffers for a specific string, the standard search command will search the current buffer for a specified regular expression.

Once you have found an occurrence of the string you are looking for it is then possible to replace it with something else.

1.12.1 Regular Expressions

Jade uses the regexp(3) package by Henry Spencer, with some modifications that I have added. It comes with this heading:

Copyright (c) 1986 by University of Toronto.
Written by Henry Spencer. Not derived from licensed software.

Permission is granted to anyone to use this software for any purpose on any computer system, and to redistribute it freely, subject to the following restrictions:

1. The author is not responsible for the consequences of use of this software, no matter how awful, even if they arise from defects in it.
2. The origin of this software must not be misrepresented, either by explicit claim or by omission.
3. Altered versions must be plainly marked as such, and must not be misrepresented as being the original software.

The syntax of a regular expression (or regexp) is as follows (this is quoted from the regexp(3) manual page):

A regular expression is zero or more branches, separated by ‘|’. It matches anything that matches one of the branches.

A branch is zero or more pieces, concatenated. It matches a match for the first, followed by a match for the second, etc.

A piece is an atom possibly followed by ‘*’, ‘+’, or ‘?’. An atom followed by ‘*’ matches a sequence of 0 or more matches of the atom. An atom followed by ‘+’ matches a sequence of 1 or more matches of the atom. An atom followed by ‘?’ matches a match of the atom, or the null string.

An atom is a regular expression in parentheses (matching a match for the regular expression), a range (see below), ‘.’ (matching any single character), ‘^’ (matching the null string at the beginning of the input string), ‘$’ (matching the null string at the end of the input string), a ‘\’ followed by a single character (matching that character), or a single character with no other significance (matching that character).

A range is a sequence of characters enclosed in ‘[]’. It normally matches any single character from the sequence. If the sequence begins with ‘^’, it matches any single character not from the rest of the sequence. If two characters in the sequence are separated by ‘-’, this is shorthand for the full list of ASCII characters between them (e.g. ‘[0-9]’ matches any decimal digit). To include a literal ‘]’ in the sequence, make it the first character (following a possible ‘^’). To include a literal ‘-’, make it the first or last character.

Some example legal regular expressions could be:

‘ab*a+b’

Matches an ‘a’ followed by zero or more ‘b’ characters, followed by one or more ‘a’ characters, followed by a ‘b’. For example, ‘aaab’, ‘abbbab’, etc…

‘(one|two)_three’

Matches ‘one_three’ or ‘two_three’.

‘^cmd_[0-9]+’

Matches ‘cmd_’ followed by one or more digits, it must start at the beginning of the line.

As well as being matched against, regexps also provide a means of “remembering” portions of the string that they match. The first nine parenthesised expressions that are matched and the whole match are recorded so that they can be used later.

The main use for this is in the command to replace a previously found regexp with the Lisp functions regexp-expand, regexp-expand-line and replace-regexp. The string which is given as the template (i.e. the string that replaces the matched string) is expanded inserting these recorded strings where asked to.

Each occurrence of ‘\C’ in the template is a candidate for expansion. C can be one of:

‘&’

‘0’

Replaces the whole substring matched by the regular expression.

‘1’ to ‘9’

The numbered parenthesised expression.

‘\’

The character ‘\’.

For example, if a regexp of ‘:([0-9]+):’ matches a line ‘foo:123:bar’, the expansion template ‘x_\1’ would produce ‘x_123’.

1.12.2 Incremental Search

Jade’s main command for searching buffers is an Emacs-style incremental search (or isearch). This is a subsystem of the editor which lets you interactively search for regular expressions in a buffer.

Ctrl-s

Start an incremental search, initially searching forwards through the buffer.

Ctrl-r

Similar to Ctrl-s except that searching is initially in the backwards direction.

When you are in an isearch the general idea is to type in a regular expression and see what it matches in the buffer. As more characters are added to the string being searched for the cursor indicates strings which match. To backtrack your steps (i.e. the characters you have typed) the backspace key is used.

The special commands which are available when isearching are,

Ctrl-s

Search forwards for another occurrence of the search regexp. This can also be used to wrap around to the start of the buffer if no more matches exist between the cursor and the end of the buffer.

Ctrl-r

Search backwards for the regexp.

Ctrl-g

Cancels the isearch. If the search is currently failing (the string you’ve typed doesn’t match anything) characters are deleted from the regexp until either a match is found or the original cursor position is reached. If the search is not failing the cursor is returned to its original position and the isearch is exited.

Ctrl-w

Copies the word under the cursor to the regexp being searched for.

Ctrl-y

The rest of the current line is appended to the regexp being searched for.

Ctrl-q

The next character typed is appended to the regexp no matter what it is, this can be used to enter control characters. Note that currently you can’t search for newline characters.

<RET>

<ESC>

Accept the cursor’s current position, the isearch is exited leaving the cursor as it is.

<Backspace>

Moves back up the stack which represents the current isearch, i.e. deletes characters from the search regexp or moves the cursor through the positions it had to reach its current position.

Any other keys are appended to the regular expression being searched for.

1.12.3 Global Replace

Meta-x replace-all <RET> regexp <RET> template

For all occurrences of the regular expression regexp replace it with the string obtained by expanding template. For details of how the template works see Regular Expressions.

1.12.4 Query Replace

The query-replace function provides an interactive method of replacing strings in a buffer which match a specific regular expression.

For each occurrence found you, the user, have a number of options; for example, you could replace this occurrence with a prespecified template.

Meta-% regexp <RET> template <RET>

Invoke a query-replace, for all occurrences of the regular expression, regexp you will be prompted for what you want to do with it. Usually this will be to replace it with the expansion provided by the template (see see section Regular Expressions) template.

Special commands which come into effect each time the query-replace finds a match are,

<SPC>

y

Replace this occurrence with the expansion of template and search for the next match.

<Backspace>

n

Ignore this match and search for the next.

,

Replace this occurrence, then wait for another command.

<RET>

<ESC>

q

Exit this query-replace.

.

Replace this occurrence then exit.

!

Replace the current match and all the rest between here and the end of the buffer.

^

Retrace your steps through each match which has been found.

Ctrl-r

Enter a recursive-edit, this is allows you to edit this match by hand. When you exit the recursive-edit (with the Ctrl-Meta-c command) the next match is searched for.

Ctrl-w

Delete the current match, then enter a recursive-edit, as in the Ctrl-r command.

1.13 Editing Modes

Modes are used to tailor the editor to the type of the file being edited in a buffer. They are normally a file of Lisp which installs the buffer-local key bindings and variables which are needed for that type of file.

For example, C-mode is a mode used to edit C source code, its main function is to try to indent each line to its correct position automatically.

The name of the mode active in the current buffer is displayed in the status line, inside the square brackets.

At present there are only a small number of modes available. It is fairly straightforward to write a mode for other classes of file though. @xref{Writing Modes}.

Most of the modes for editing programming languages use the command Meta-; to insert a comment place-holder, the cursor is moved to where you should type the body of the comment.

  — Modes for editing programming languages —

  — Modes for natural language —

1.13.1 Invoking a Mode

When a new file is loaded the function init-mode tries to find the mode that it should be edited with. If it is successful the mode will be automatically invoked.

It is also possible to install a mode manually, simply invoke the command which is the name of the mode. For example to install the ‘C mode’ in a buffer type Meta-x c-mode.

1.13.2 Generic mode

This is not a mode as such since there is no Lisp code associated with it. When no mode is being used to edit the buffer, it is said to use the “Generic” mode.

This is the base from which all other modes build, it consists of all the standard key bindings. Words are defined as one or more alphanumeric characters, paragraphs are separated by a single blank line.

1.13.3 C mode

c-mode is used for editing C source code files. Any files which end in ‘.c’ or ‘.h’ are automatically edited in this mode.

It’s one and only function is to try and indent lines to their correct depth, it doesn’t always get it right but it works fairly well. The keys that it rebinds to achieve this are,

It also defines the syntax of an expression in the C language for use with the expression commands, see Editing Expressions.

<TAB>

Indents the current line to what the editor thinks is the correct position.

{

}

:

These keys are handled specially since the indentation of the line that they are inserted on may have to be adjusted.

Ctrl-Meta-\

Indents all lines which are marked by the current block.

Command: c-mode

Editing mode for C source code. Automatically used for files ending in ‘.c’ or ‘.h’.

Hook: c-mode-hook

This hook is called by c-mode each time the mode is invoked.

Variable: c-mode-tab

Size of tab stops used by c-mode.

Variable: c-mode-auto-indent

When non-nil <RET> will indent the line after splitting it.

1.13.4 Lisp mode

lisp-mode is used to edit files of Lisp intended to be read by the editor. Its main function is to manage the indentation of Lisp expressions for you. Each form is regarded as an expression by the commands which operate on expressions, see Editing Expressions.

There is also support for using a buffer as a simple shell-interface to the editor’s Lisp subsystem.

The method used for indenting lines of Lisp is fairly straightforward, the first symbol in the expression containing this line is found. This symbol’s lisp-indent property is then used to decide which indentation method to apply to this line. It can be one of the following,

nil

The standard method (also used if the symbol doesn’t have a lisp-indent property).

If the first argument to the function is on the same line as the name of the function then subsequent lines are placed under the first argument. Otherwise, the following lines are indented to the same depth as the function name.

For example,

(setq foo 20
      bar 1000)

(setq
 foo 20
 bar 1000)

defun

This method is used for all functions (or special-forms, macros) whose name begins with ‘def’ and any lambda-expressions.

All arguments to the function are indented lisp-body-indent columns from the start of the expression.

For example,

(defun foo (bar)
  "A test"
  (let
      ((foo bar))
    ...

A number, n

The first n arguments to the function are indented twice the value of lisp-body-indent, the remaining arguments are indented by lisp-body-indent.

For example the special-form if has a lisp-indent property of 2,

(if condition
    t-expression
  nil-expressions...)

Special commands for Lisp mode are,

Ctrl-j

Evaluates the expression preceding the cursor, prints the value on the next line. This is designed to be used like a shell, you type a Lisp expression, press Ctrl-j and Jade prints the value for you.

<TAB>

Indents the current line.

Ctrl-Meta-\

Indents all lines which are marked by the current block.

Ctrl-Meta-x

Evaluates the expression before the cursor, prints it’s value in the status line.

Command: lisp-mode

Editing mode for Jade’s Lisp. Automatically invoked for files ending in ‘.jl’.

Hook: lisp-mode-hook

This hook is evaluated each time lisp-mode is invoked.

Variable: lisp-body-indent

The number of characters which the body of a form is indented by, the default value is 2.

1.13.5 Asm mode

A basic mode for editing assembler source files with, provides automatic indentation of labels and instructions.

The special commands are,

<RET>

Breaks the line as normal, if asm-indent is non-nil a tab characters is inserted as well.

:

Deletes all indentation from the start of the current line, then inserts the string ‘:\t’ to move to the next tab stop. This is used to enter labels.

.

If the line is not empty, all indentation is deleted from the start of the line. A dot (‘.’) is then inserted.

Command: asm-mode

Major mode for generic assembler source files.

Hook: asm-mode-hook

The hook which is called when asm-mode is entered.

Variable: asm-indent

When this variable is non-nil the <RET> key inserts the string ‘\n\t’ instead of just ‘\n’. This indents the cursor to the first tab stop of the new line.

Variable: asm-comment

This variable defines the string which denotes the start of a comment in the assembler that you are using. By default this is ‘;’.

1.13.6 Text mode

This is the most basic mode for editing English-style text in. The main difference over generic-mode and is that words are allowed to contain underscores and there are some extra commands,

Meta-s

Centres the current line. The position of the fill-column is used to calculate the centre of the line. For more information on the fill-column variable see Fill mode.

Meta-S

Centres the current paragraph.

Command: text-mode

Major mode for editing English text.

Hook: text-mode-hook

Evaluated when text-mode is invoked. Variants of text-mode also use this hook.

1.13.7 Indented-Text mode

This is a variant of text-mode, see Text mode. It’s only difference is in the way the <TAB> key is handled — tab stops are calculated from the previous non-empty line. Each transition from a sequence of one or more spaces to a non-space character is used as a tab stop. If there are none of these to the right of the cursor normal the standard tabbing command is used.

Command: indented-text-mode

Variant of text-mode.

Hook: indented-text-mode-hook

Evaluated when indented-text-mode is invoked. The hook text-mode-hook is also evaluated (before this one).

1.13.8 Texinfo mode

texinfo-mode is used to edit Texinfo source files, it is automatically selected for files ending in ‘.texi’ or ‘.texinfo’. It provides a few basic key bindings to take some of the tedium out of editing these files.

Paragraphs are separated by the regexp ‘^@node’, i.e. each node is a separate paragraph.

The special commands are,

<TAB>

Inserts as many spaces as are needed to move the cursor to the next tab position. The reason tab characters aren’t used is that TeX doesn’t agree with them.

Ctrl-c Ctrl-c c

Insert the string ‘@code{}’, positioning the cursor between the braces.

Ctrl-c Ctrl-c d

Insert the string ‘@dfn{}’, positioning the cursor between the braces.

Ctrl-c Ctrl-c e

Inserts the string ‘@end’.

Ctrl-c Ctrl-c f

Inserts the string ‘@file{}’, the cursor is put between the braces.

Ctrl-c Ctrl-c i

Inserts the string ‘@item’.

Ctrl-c Ctrl-c l

Inserts the string ‘@lisp\n’.

Ctrl-c Ctrl-c m

Inserts the string ‘@menu\n’.

Ctrl-c Ctrl-c Ctrl-m

Prompts for the name of a node and makes a menu-item for it.

Ctrl-c Ctrl-c n

Prompts for each part of a node definition (name, next, prev, up) and inserts the ‘@node …’ string needed.

Ctrl-c Ctrl-c s

Inserts the string ‘@samp{}’ and puts the cursor between the braces.

Ctrl-c Ctrl-c v

Inserts the string ‘@var{}’, the cursor is put between the braces.

Ctrl-c Ctrl-c {

Inserts a pair of braces with the cursor between them.

Ctrl-c Ctrl-c }

Ctrl-c Ctrl-c ]

Moves the cursor to the character after the next closing brace.

Command: texinfo-mode

Major mode for editing Texinfo source files.

Hook: texinfo-mode-hook

Evaluated when texinfo-mode is invoked. The hook text-mode-hook is evaluated first.

1.14 Minor Modes

The editing modes described in the previous section were “Major modes”, each mode was designed for a particular class of file. Minor modes work on top of the major modes, each minor mode provides a single extra feature for editing the buffer they are used in. For example overwrite-mode is a minor mode which makes any keys you type overwrite the character beneath the cursor, instead of inserting themselves before the cursor.

The names of the minor modes currently active in the current buffer are displayed in the status line, to the right of the name of the major mode.

1.14.1 Overwrite mode

When enabled, characters typed replace the existing character under the cursor instead of just moving it to the right.

The command to toggle this mode on and off is Meta-x overwrite-mode.

Command: overwrite-mode

Toggles overwriting character insertion in the current buffer.

1.14.2 Fill mode

Filling splits lines so that they aren’t longer than a certain number of characters. The fill-mode checks if you have passed this threshold when you type the <SPC> key. Any words passed the threshold get moved to the next line.

Ctrl-x f

Sets the fill-column variable (see below) to the cursor’s current column position.

Command: fill-mode

Toggles the auto-filling minor mode.

Variable: fill-column

The maximum number of characters allowed in a single line. This is used by the filling and centring functions.

1.14.3 Auto-Save mode

This is not really a minor mode but it obeys the same calling conventions (i.e. calling its function toggles its action).

Command: auto-save-mode

Toggles whether or not the current buffer is regularly saved to a temporary file.

For more details about auto-saving see Auto-Saving Files.

1.14.4 Latin-1 mode

This minor mode toggles the display of characters in the Latin-1 character set, by default these characters are displayed as octal escape sequences.

This only works properly if the font that you are using defines glyphs for these characters!

Command: latin-1-mode

Toggles the display of characters in the Latin-1 character set. This is a global setting.

For more information about what is displayed for each character see Character Images.

1.15 Using Buffers

As you have probably realised, buffers are probably the most important part of the editor. Each file that is being edited must be stored in a buffer. They are not restricted to editing files though, all buffers are regarded as simply being a list of lines which can be displayed in a window and modified as needed.

This means that they are very flexible, for example, the Lisp debugger uses a buffer for its user interface, the Info reader uses two buffers – one to display the current node, the other to store the file’s tag table (never displayed, just used to look up the position of nodes).

Each buffer has a name, generally buffers which contain proper files use the base part of the filename, while buffers which don’t correspond to files use a word which starts and ends with asterisks (i.e. ‘*jade*’).

Each window can display one buffer at any one time. There is no restriction on the number of windows which may display the same buffer at once.

1.15.1 Displaying Buffers

There are two main commands for switching to a different buffer,

Ctrl-x b

Prompt for the name of a buffer and display it in the current window.

Ctrl-x 4 b

In a different window (opens a new window if there is currently only one) prompt for the name of a buffer and display it in that window.

Both commands are very similar, the Ctrl-x 4 b variant simply invokes a command to switch to a different window before calling the Ctrl-x b command.

When typing the name of the new buffer you can use the prompt’s completion mechanism to expand abbreviations (see see section The Buffer Prompt). If you just press <RET> with an empty prompt the default choice will be used. This will be the the buffer that was being shown in this window before the current buffer was selected (its name is displayed in the prompt’s title).

The Ctrl-x Ctrl-f command and its variants also switch buffers since they look for an existing copy of the file in a buffer before loading it from disk, see Commands To Load Files.

1.15.2 Deleting Buffers

There is no real need to delete buffers, those that haven’t been used for a while just hang around at the end of the list. If you’re short on memory though it can help to kill some of the unused buffers which you have accumulated.

The command to kill a buffer is,

Ctrl-x k

Prompts for the name of a buffer (with completion) then deletes that buffer (if the buffer contains unsaved modifications you are asked if you really want to lose them). It is removed from all window’s buffer-lists and any window which is displaying it is switched to another buffer (the next in its list).

Any marks which point to the buffer are made “non-resident” (that is, they point to the name of the file in the buffer) and the buffer is discarded.

1.15.3 Other Buffer Commands

Meta-x rotate-buffers-forward

Rotates the current window’s list of buffers.

Meta-x revert-buffer

Restores the contents of the current buffer to the contents of the file that it was loaded from, if an auto-save file exists you are asked if you want to revert to that instead.

Ctrl-x s

Ask whether to save any modified buffers that exist.

Meta-x clear-buffer

Deletes the contents of the current buffer. Beware, you won’t be warned if you’re about to lose any unsaved modifications!

1.15.4 The Buffer Menu

The buffer menu presents you with a list of all the buffers accessible from the current window in most-recently-used order. You are then able to manipulate the buffer list using several simple commands.

Ctrl-x Ctrl-b

Enters the buffer menu; the buffer ‘*Buffer Menu*’ is selected and a list of available buffers is printed in it.

The following example shows how the buffer list is printed.

   MR   Name            Mode            File
   --   ----            ----            ----
    -   *Buffer Menu*   Buffer Menu
   +    user.texi       Texinfo         man/user.texi
        *jade*          Lisp

The column headed ‘M’ shows whether the buffer has been modified since it was last saved and the column ‘R’ shows whether or not the buffer is read-only. The other columns should be self-explanatory.

When the ‘*Buffer Menu*’ buffer is selected the following commands are available. When a single buffer is to be manipulated by a command, the buffer described by the line which the cursor is on is chosen.

d

Mark the buffer for deletion and move to the next buffer. A ‘D’ is displayed in the first column of a line if that buffer is marked for deletion.

s

Ctrl-s

Mark the buffer to be saved then move to the next buffer in the list. A ‘S’ in the second column of a line denotes a buffer which has been marked to be saved.

x

Execute previously-marked saves and deletions.

u

Unmark the current line (i.e. clear any ‘D’ or ‘S’ markers) then move to the next entry in the buffer list.

~

Toggle the modified flag of the current line’s buffer, then move down.

%

-

Toggle the read-only status of the current line’s buffer, then move to the next entry.

1

<RET>

Select the current line’s buffer in this window.

o

Select the current line’s buffer in the other window.

Ctrl-f

<TAB>

Move to the next line in the buffer list.

Ctrl-b

Move to the previous line in the buffer list.

Ctrl-l

Redraw the buffer list, incorporating any changes made to the available buffers.

q

Quit the buffer menu.

1.16 Using Windows

Windows have two main functions: to display the contents of buffers (but only one buffer at a time) and to collect input from you, the user.

The editor must have at least one window open at all times, when you close the last window Jade will exit, there is no limit to the number of windows which you may have open at once.

Each window is split into two parts, they are

The Main Display Area

This is the largest part of the window, it is where the buffer that this window is displaying is drawn.

The Status Line

A single line of text associated with the window, under X11 this is the area of the beneath the horizontal line at the bottom of the window, on the Amiga it is the title of the window. The status line is normally used to display information about this window and what it is displaying, it has this format,

buffer-name (mode-names) (col,row) n line(s) [flags]

Where the individual parts mean,

buffer-name

The name of the buffer being edited, it can have either a ‘+’ or a ‘-’ appended to it, a plus means the buffer has been modified since it was saved, a minus means that the buffer is read-only.

mode-names

This tells you which editing modes are being used by this buffer, the first word is the name of the major mode, any subsequent words correspond to the names of the minor modes for this buffer. If this section is surrounded by square brackets ‘[…]’ instead of parentheses it means that you are currently in a recursive edit, for example, inside the Lisp debugger.

col

The column that the cursor is at.

row

The row number of the cursor.

n

The number of lines in this buffer

flags

General one-character flags related to the status of the window and its buffer.

Each window maintains a list of all buffers which are available for displaying, this is kept in order, from the most recently used to the least. This list (called buffer-list) is used by some of the buffer manipulation commands when they are working out which buffer should be displayed.

1.16.1 Creating Windows

Ctrl-x 2

Opens a new window, it will have the most of the attributes that the current window does, things like: size, buffer, font, etc… If you are using X11 you will probably have to use your mouse to select its position, depending on the window manager you use, on the Amiga it will be created at the same position as the current window.

Ctrl-x 4 Ctrl-f

Ctrl-x 4 f

In a different window, one will be created if only one window is open, find a file, for more details see Commands To Load Files.

Ctrl-x 4 a

In a different window add an entry to a change-log file. See section Keeping ChangeLogs.

Ctrl-x 4 b

In a different window, choose a buffer to display, similar to the Ctrl-x b command. See section Displaying Buffers.

Ctrl-x 4 h

Enter the help system in a different window. See section The Help System.

Ctrl-x 4 i

Enter the Info browser in a different window. See section Info Mode.

Ctrl-x 4 `

Display the next error (or whatever) in the *compilation* buffer in a different window. See section Finding Errors.

Note that for each Ctrl-x 4 command there is a corresponding Ctrl-x 5 command. Instead of using a different window to the current one, a new window is opened for each Ctrl-x 5 command typed.

1.16.2 Killing Windows

Ctrl-x 0

Close the current window, if it is the last window that the editor has open it will exit (after asking you if you wish to lose any unsaved modifications to buffers).

Ctrl-x 1

Close all windows except the current one.

1.16.3 Other Window Commands

Ctrl-x o

Activate the next window of the editor’s. Under X11 this involves warping the mouse-pointer to the top left corner of the newly activated window.

Meta-x set-font

Choose a font to use in the current window. This command prompts for the name of the font then installs it in the window. Font names are the same as for the shell argument ‘-font’ (@pxref{Startup Options}).

1.17 Using the Prompt

There are two different styles of prompt that the editor uses when it wants you to enter a string.

1.17.1 The Simple Prompt

The simplest prompt uses the the bottom-most line in the window, it prints the prompt’s title on the left hand side, you should type your response and then press the <RET> key. This prompt is very primitive, the only special commands that it has are,

<Backspace>

Delete the previous character.

<Up>

<Down>

Replace the contents of the prompt with the last string entered. When you type <Up> or <Down> again the original contents are restored.

<ESC>

Cancel the prompt.

All other keys are simply printed in the prompt — whatever they are.

1.17.2 The Buffer Prompt

This type of prompt is more sophisticated. It creates a new buffer for you to type your response into (called *prompt*), the title of the prompt is displayed in the buffer’s first line.

Normally you type the answer to the prompt into the buffer and then press the <RET> key. All normal editor commands are available while you are using the prompt, you can switch buffers, load new files, whatever you like.

Another advantage of this type of prompt is that it supports completion, this allows you to type the beginning of your response then press the <TAB> key. What you have typed will be matched against the list of responses that the editor has (i.e. when being prompted for the name of a file it will be matched against all available files), if a unique match is found your response will be completed to that match.

If several potential completions are found, these will be displayed after the line ::Completions:: in the buffer and your response will only be completed as far as the potential completions are similar. For example, if you enter ‘fo’ then press <TAB> and files called ‘foo’ and ‘foobar’ exist, the contents of the prompt will become ‘foo’.

Completion is provided for many different things, some are: files, buffers, symbols, functions, variables, Info nodes, etc…

The special commands for this type of prompt are,

<TAB>

<RMB>-<CLICK1>

Complete the contents of the prompt. If more than one potential completion exists they are printed in the buffer.

<RET>

<LMB>-<CLICK2>

Enter the result of this prompt. If you invoke this command while the cursor is on a printed potential completion (those under the ::Completions:: line) the whole line will be entered. Otherwise, just the text to the left of the cursor is entered.

Meta-?

Print all possible completions of the current prompt but do not try to actually change the contents of the prompt.

Ctrl-g

Cancel the prompt.

1.18 Using Marks

Marks are used to record a position in a file, as the file’s buffer is modified so does the position that the mark points to — a mark will keep pointing at the same character no matter what happens (unless the character is deleted!).

The other good thing about marks is that they point to files not buffers. This means that you can set a mark in a buffer, delete the buffer and then move to the position of the mark, the file will be reloaded and the cursor will point at the original character.

Normally there are three user-accessible marks (2) and one special auto-mark which is used, amongst other things, to record the “previous” position of the cursor, allowing you to retrace your last major step.

The commands available on marks are,

<F1>

<F2>

<F3>

Move to the mark #1, #2 or #3, depending on which function key is pressed (<F1> means mark #1, etc…). If the file pointed to is not in memory it will be loaded into a new buffer.

Shift-<F1>

Shift-<F2>

Shift-<F3>

Set the position of mark #1, #2 or #3, depending on the function key.

Ctrl-x Ctrl-x

Swap the positions of the cursor and the auto-mark.

Ctrl-@

Set the position of the auto-mark.

1.19 Interrupting Jade

It is often useful to be able to tell Jade to quit whatever it is doing and wait for more commands; this is called interrupting Jade. When the editor receives an interrupt signal it will abort what it is doing and rewind itself back to the inner-most recursive edit (see see section Recursive Editing).

The interrupt signal differs with the operating system being used,

• Under Unix the SIGINT signal is used, this can be sent via the intr character (get the editor into the foreground of the shell it was started from and type Ctrl-c in the shell’s terminal), or directly through the kill shell command. For example, look at the following shell session extract,

  /var/src/jade/man$ ps
    PID TT STAT  TIME COMMAND
     60  1 SW    0:02 (xinit)
     87  1 S     0:08 fvwm
    127 p0 S     0:00 /bin/bash
    155 p0 S     0:04 jade
    156 p1 S     0:00 /bin/bash
    159 p1 R     0:00 ps
  /var/src/jade/man$ kill -INT 155
  

  First the ps command is used to find the Jade process’ pid (155), then the kill command is used to send the INT signal to this process.

• The Ctrl-c signal is also used on Amigas, either type this in the console window that Jade was launched from or use the break (or possibly breaktask) command to send the signal.

1.20 Recursive Editing

Recursive editing is the act of editing a file while the current command is still being evaluated. For example, when using the query-replace command (Meta-%) the Ctrl-r command enters a recursive edit to let you edit the buffer, even though you are still doing a query-replace (which will be resumed when the recursive edit finishes).

As the name suggests a recursive edit calls the editor’s main command loop recursively from within a command. Any number of recursive edits may be stacked up and then unwound back to the top-level of the editor.

When a recursive edit is in progress the name of the mode being used to edit the buffer is shown in square brackets, not parentheses as in the top-level instance.

The commands for manipulating recursive edits are as follows,

Ctrl-]

Ctrl-Meta-c

Exit the innermost recursive edit, this has no effect at the top-level.

Meta-x top-level

Return to the outermost edit — the top-level. This is useful when you get “lost” inside a sequence of recursive edits.

Meta-x recursive-edit

Enter a new recursive edit; this command is usually best avoided to save confusion.

In general, recursive editing is rarely used except in unavoidable circumstances (i.e. in the Lisp debugger).

1.21 Character Images

In general any character can be mapped to any sequence of up to four character sized images (called glyphs) when it is drawn into a window. The TAB character is a notable exception; it expands to as many spaces as are needed to fill up to the next tab stop.

By default, the editor is set up to display the following,

0 to 31

A caret (‘^’) followed by the ASCII value of the character exclusive-or’d with 0x40, i.e. ‘^@’ to ‘^_’.

32 to 126

Printed literally, this includes all “normal” characters and punctuation.

127

‘^?’

128 to 255

Represented by the octal escape sequence (i.e. ‘\200’) for that character’s numeric value.

If you want to edit files containing characters in the Latin1 character set (numerically, from 160 to 255) you can put the following in your ‘.jaderc’ file,

(latin-1-mode)

this will redefine the necessary characters.

If you want more details about this sort of thing see @ref{Glyph Tables}.

1.22 Client Editing

Normally you will only have one instance of Jade executing at a single time. Often though, another program will want you to edit a file, for example when you are composing a mail message. There is normally a way to specify which editor you want to use, for example the EDITOR environment variable.

If you were to ask to edit the file in jade an additional process executing Jade would be started, totally separate from the original. It is possible to use the original instance.

Firstly Jade must be set up to listen for clients wanting files edited, this is done with the server-open command. You can either put this in your ‘.jaderc’ file (with a line like ‘(server-open)’) or call it manually with the command Meta-x server-open.

Only one instance of Jade may be a server at once. If you know that there is no other Jade running but it still won’t let you open a server, and you are running on Unix, look for a dead socket called ‘~/.Jade_rendezvous’ and delete it if necessary.

Once the editor is listening for client messages the separate program jadeclient may be used to load files into the server from an external source. The format of jadeclient invocation is,

jadeclient [+line-number] file-name …

When invoked, it will ask the server to edit each file-name (initially positioned at line line-number) in turn, exiting only after each file has finished being edited.

If when the jadeclient program is invoked their is no server open (i.e. either Jade is not running or you haven’t used the server-open function) a message ‘Jade not running, waiting...’ will be printed and jadeclient will sit waiting for you to open a Jade server.

So, simply get the program you want to use Jade to use the jadeclient program as its editor. For example, I use mh to handle my electronic mail; in my ‘~/.mh_profile’ file I have the line,

Editor: jadeclient

to tell it that I want to edit my mail in Jade.

The one special command for client/server editing is,

Ctrl-x #

If the file being edited in the current buffer is a client file, tell the client program which loaded it that it has finished being edited. The actual buffer is not deleted.

It is also possible to finish editing a client file by simple deleting its buffer in the normal way (Ctrl-x k), Deleting Buffers.

1.23 Compiling Programs

Jade has a number of features to help you develop programs, foremost is the ability to run a compilation inside one of the editor’s buffers. Unfortunately, this is only possible when using the Unix operating system at the present.

Once the compilation has finished you can then step through each error produced.

1.23.1 Running a Compilation

The command to run a shell command in a buffer is,

Meta-x compile

Prompts you for the command to execute, with a default of the last command you ran (starts as ‘make’). A shell process is created which runs asynchronously to the editor in the same directory as the current buffer’s file was loaded from. The buffer *compilation* is selected and this is where all output from the program is printed.

When the process finishes running a message is printed in the *compilation* buffer telling you its exit-code.

Only one process may be run with the compile function at once.

This command is not available on the Amiga version yet.

1.23.2 Finding Errors

When you have compiled something with the Meta-x compile command it is possible to step through each of the errors that it produces. To do this use the command,

Ctrl-x `

Displays the next error in the *compilation* buffer. The file that is in is loaded (if necessary) and the line with the error is found.

If you edit a file which has errors in it, then try to find the next error (which is in the same file) everything will still work. The positions of errors are updated as the buffers are modified.

The only exception to this is when you invoke the next-error function while the *compilation* buffer is still being written to. If more errors are produced in a file which has been modified since the compilation started it is likely that the positions will get out of sync.

By default, the next-error function understands the type of error output that gcc produces. This is of the form,

file:line-number:description

It is possible to use other formats though, the variables which control this are,

Variable: compile-error-regexp

Regular expression to match a line containing an error. For gcc this is ‘^(.*):([0-9]+):(.+)’.

Variable: compile-file-expand

Expansion template to produce the name of the file with the error, using compile-error-regexp and the line containing the error. By default this is ‘\1’.

Variable: compile-line-expand

Similar to compile-file-expand except that it expands to a string defining the number of the line with the error. By default, ‘\2’.

Variable: compile-error-expand

Similar to compile-file-expand, but produces the description of the error. By default, ‘\3’.

1.23.3 Debugging Programs

Jade allows you to run the GDB debugger in a buffer. Some of the advantages of this over the usual terminal based interaction are,

• The current position of the target program (its frame) is highlighted; the source file is displayed in a separate window with the current frame marked (in the same way that a block is marked).
• You are able to set and delete breakpoints simply by putting the cursor on the line you wish the target to stop at and typing an editor command.

To start a gdb subprocess use the Meta-x gdb command, you will be asked to enter the name of the program to debug then gdb will be started in a new buffer (called ‘*gdb*’ or similar). You are then able to type commands into the buffer, they will be sent to gdb each time you type the <RET> key.

The commands for controlling the gdb subprocess are as follows (the Ctrl-c prefixed commands are only available within the *gdb* buffer whereas the Ctrl-x Ctrl-a variations are accessible globally so that they can be invoked from within the target’s source files),

Ctrl-c Ctrl-n

Ctrl-x Ctrl-a Ctrl-n

Continue execution to the next source line, this is the gdb command next.

Ctrl-c Ctrl-s

Ctrl-x Ctrl-a Ctrl-s

Continue execution until a different source line is reached, this is the gdb command step.

Ctrl-c Ctrl-f

Ctrl-x Ctrl-a Ctrl-f

Continue running until the current stack frame exits, the finish command.

Ctrl-c Ctrl-r

Ctrl-x Ctrl-a Ctrl-r

Resume execution until a breakpoint is reached or the target exits.

Ctrl-c Ctrl-<

Ctrl-x Ctrl-a Ctrl-<

Display the stack frame above the current one.

Ctrl-c Ctrl->

Ctrl-x Ctrl-a Ctrl->

Display the stack frame under the current one.

Ctrl-c Ctrl-b

Ctrl-x Ctrl-a Ctrl-b

Set a breakpoint at the current source line, if the *gdb* buffer is active the line selected is where the program last stopped.

Ctrl-c Ctrl-t

Ctrl-x Ctrl-a Ctrl-t

Set a temporary breakpoint at the current source line.

Ctrl-c Ctrl-d

Ctrl-x Ctrl-a Ctrl-d

Remove all breakpoints which are set at the current source line.

Ctrl-c Ctrl-l

Ctrl-x Ctrl-a Ctrl-l

Redisplay the current frame, centring it in its window.

For a summary of these commands type Ctrl-h m in the *gdb* buffer.

Since the gdb process runs on top of the Shell mode the bindings from that mode are also available.

There is no limit to the number of gdb processes you may run at once, each will get its own buffer. When a gdb command is invoked in a buffer which doesn’t have a gdb subprocess (i.e. a source file’s buffer) the command will be sent to the gdb process which either was last sent a command, or last made the editor display a new frame. Hopefully this will work fairly intuitively.

1.23.4 Using Grep

It is often very useful to grep through a set of files looking for a regular expression, this is what the grep command does. With Jade it is possible to run an external grep program in the *compilation* buffer. This then enables you to step through each grep hit using the Ctrl-x ` command, Finding Errors.

The commands to use grep are,

Meta-x grep

Prompt for a string of arguments to give grep, you do not need to provide the name of the program, or the ‘-n’ switch, this is done automatically. The shell will do any filename-globbing on the arguments so it is advisable to surround the regular expression with single quotes.

Note that the regular expression syntax will be different to that which Jade uses. Also this command won’t work on an Amiga.

Meta-x grep-buffer

This command provides a method for scanning the current buffer for all lines matching a regular expression (which you are prompted for). It is written entirely in Lisp — this means that the normal regular expression syntax is needed and it will work on an Amiga.

1.23.5 Keeping ChangeLogs

A ChangeLog is a file (usually called ‘ChangeLog’) which keeps a log of all changes you have made to the files in its directory. For example, the ‘src/ChangeLog’ file for Jade keeps a list of changes made to the editor’s source code.

There is no magic involved, you simply use a command to add a new entry to a directory’s log after modifying a file in that directory. You then have to enter a summary of the changes that you made.

The command to do this is,

Meta-a

Prompts for the name of a directory then lets you type a description of the changes you have made.

If you enter more than one change in the same day (and from the same host) the same heading will be used. The heading consists of the time and date, your name, your login and the name of the host you’re on. (3)

1.23.6 Info Mode

Despite the name of this section there is actually no such thing as the info-mode. The Lisp file ‘info.jl’ is what this section documents — it is a set of Lisp functions which make a buffer (the ‘*Info*’ buffer) into a simple browser for Info files(4).

To invoke it type Ctrl-h i, the ‘*Info*’ buffer will be selected showing the ‘(dir)’ node (the root of the Info documentation tree).

When in the ‘*Info*’ buffer the following key bindings are available.

<SPC>

Displays the next page of the current node.

<Backspace>

Displays the previous page.

1

Move to the specified menu-item (1 means the first, etc) in the menu in this node. The keys 1 to 9 work in this way.

b

Move to the beginning of the current node.

d

Display the directory node (‘(dir)’) of the Info documentation tree.

f

Follow a reference, the one under the cursor if one exists.

g

Prompt for the name of a node and try to display it.

h

Display the Info tutorial node (‘(info)Help’).

l

Go back to the last node that was displayed before this one.

m

Prompts for a menu-item (the one on the same line as the cursor is the default) and display the node it points to.

n

Display the next node.

p

Display the previous node.

u

Display the node “above” this one.

q

Quit the Info browser.

?

Display a piece of text describing all commands available in Info mode.

RET

Go to the link (menu item or xref) described on the current line.

LMB-Click2

Go to the link you double clicked on.

TAB

Put the cursor on the next link in this node.

Meta-TAB

Put the cursor on the previous link.

This mode has a number of disadvantages over the other Info browsers available (i.e. the stand-alone info program, or Emacs’ Info viewer):

• It depends wholly on being able to find a tag table in the Info file, if it can’t it will simply load the whole file into the buffer.
• There is no support for the * node name.
• Seems not to work 100% with files formatted by Emacs, makeinfo formatted files work properly though.
• No editing of nodes.

Of course, its main advantage is that it runs in Jade!

1.24 Shell

When running on a Unix-style operating system Jade allows you to run a shell subprocess in a buffer (usually the ‘*shell*’ buffer). Each line you type in the buffer is sent to the shell and the output from the shell is displayed in the buffer.

Meta-x shell

Start a new shell subprocess running in a buffer called ‘*shell*’.

If a buffer ‘*shell*’ already exists a new buffer with a unique name will be opened (i.e. ‘*shell*<2>’).

The working directory of the shell subprocess will be the directory which the contents of the current buffer was read from.

This command won’t work on Amigas!

Each ‘*shell*’ buffer installs the major mode shell-mode. This provides the following commands.

Ctrl-a

Move the cursor to the beginning of the current line, after the prompt which the shell printed (if one exists).

Ctrl-d

If the cursor is at the end of the buffer send the shell process the eof character (‘^D’) (signifying the end of the file). Otherwise delete the character under the cursor.

<RET>

Send the current line to the shell (minus any prompt at the beginning of the line). If the cursor is not on the last line of the buffer (i.e. the most recent prompt) the current line is copied to the end of the buffer before being sent.

Ctrl-c Ctrl-n

Move the cursor to the next prompt in the buffer.

Ctrl-c Ctrl-p

Move to the previous prompt.

Ctrl-c Ctrl-c

Send the intr character (‘^C’) to the shell process.

Ctrl-c Ctrl-d

Send the eof character (‘^D’) to the shell.

Ctrl-c Ctrl-z

Send the susp character (‘^Z’) to the shell.

Ctrl-c Ctrl-\

Send the quit character (‘^\’) to the shell.

Hook: shell-mode-hook

This hook is evaluated by the Shell mode after it has initialised itself (and started its subprocess).

The following variables customise the actions of the Shell mode.

Variable: shell-file-name

This variable defines the file name of the shell to run. Its default value is either the value of the environment variable SHELL or if that doesn’t exist the file ‘/bin/sh’.

Variable: shell-whole-line

When this variable’s value is non-nil the <RET> command always sends the whole of the current line (minus any prompt) even when the cursor is not at the end of the line. Otherwise only the part of the line before the cursor is sent.

The default value of this variable is t.

Variable: shell-prompt-regexp

This buffer-local variable defines the regular expression used to match the prompt printed by the shell each time it waits for you to enter a shell command. By default it has the value ‘^[^]#$%>)]*[]#$%>)] *’ but this may be incorrect if you have modified your shell’s prompt.

1.25 Simple Customisation

The best way to tailor the editor to your own requirements is with your personal startup file. This is called ‘.jaderc’ in your home directory (5), it is a file of Lisp forms evaluated when Jade initialises itself.

Usually, setting the values of variables in your startup file is enough to configure Jade how you want, the Lisp function to set a variable is called setq, it’s first argument is the name of the variable, it’s second the value you wish to set it to. This value will usually be one of the following data types,

"xyz"

A string ‘xyz’.

123

0173

0x7b

A number, all of the above have the value 123 (in decimal, octal and hexadecimal).

nil

t

A boolean value, nil means false, or not true. t is the opposite (in fact, any value not nil is true).

My ‘.jaderc’ file looks something like this (note that semicolons introduce comments),

;;;; .jaderc -*-Lisp-*-

;; Size of tabs for Lisp source is 2
(setq lisp-body-indent 2)

;; When on an Amiga, flag that I don't want pull down menus
(when (amiga-p)
  (setq amiga-no-menus t))

;; When editing English-text use auto-filling
(add-hook 'text-mode-hook 'fill-mode-on)

;; -with a maximum of 74 characters in a line
(setq fill-column 74)

;; Start the edit server
(server-open)

Most simple customisations can be achieved by simply giving a variable a new value. Use the setq special form to do this (a special form is a type of function) as in the examples above. If you wish to set variables interactively use the set command:

Meta-x set <RET> variable-name <RET> new-value <RET>.

The add-hook function adds a function (in this case fill-mode-on) to be called when the specified hook (in this case text-mode-hook) is evaluated. The single-quote before the names means that the names are passed as constants; not their values. If you don’t quite understand what I’m talking about don’t worry.

For full documentation of Jade’s programming language see @ref{Programming Jade}.

Footnotes

(1)

When using an Amiga, unit zero of the clipboard.device is used. For X11, the first cut-buffer.

(2)

There is no reason why you can’t have more, the editor sets no limitation on the number of marks available. This is just how I have set the editor up.

(3)

On the Amiga there is no way to get these details. So, Jade looks for some environment variables, USERNAME for the login name, HOSTNAME for the name of the host and REALNAME for your actual name.

(4)

Info is the GNU way of creating hypertext documents, for more information see (info)Info.

(5)

On the Amiga, your home directory is defined as the contents of the environment variable HOME.

About This Document

This document was generated on September 19, 2022 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on September 19, 2022 using texi2html 5.0.