# The jedit Text Editor

## Introduction

The `jedit` application is a customisable multimode X Windows text editor. It is distributed as part of the jstools package.
I have intended `jedit` to be flexible and configurable. Preferences panels let you choose among sets of text bindings, including Emacs and rudimentary `vi`(1) emulation, and general aspects of the application's behaviour, and hooks are provided to let you further customise the application's behaviour via startup files written in Tcl. For instance, if you find you frequently need to insert a list of all the users on your system into a file you're editing, sorted alphabetically, you can add a menu command (or a keystroke, or both) to do that.

The editor supports a number of keyboard shortcuts for menu commands, as well as a few keyboard shortcuts for buttons in dialogue boxes. Documentation is available describing the jstools conventions for notation of keyboard shortcuts.

The editor can be incorporated into other Tkbased applications as a set of libraries; this is described under Embedding jedit in Other Applications in Programming with jedit.

This document describes `jedit` version 1998.11.04.

Copyright and contact information is available in the jstools documentation.

### Thanks

Thanks to David Svoboda `<svoboda@ece.cmu.edu>` for the code to match parentheses (taken from Beth, the predecessor of Elsbeth), and to Christian Artigues `<artigues@ensta.fr>` and Maurice Diamantini `<diam@ensta.fr>` for the work of integrating it with the editor.

Thanks to Achim Bohnet `<ach@rosat.mpe-garching.mpg.de>` for the EDT bindings (still in progress), improvements to the `vi` bindings, and valuable suggestions about the bindings mechanism.

## Invocation

`jedit` [`-mode` mode]`` [`-for` interpreter]`[-iconic`]`` [[`+`line]`` [`-width` width]`` [`-height` height]`` [filename]]...
most typically, just
`jedit` filename...

To edit a file, type ``jedit` filename' at the Unix shell prompt, assuming `jedit` is in your path. The file need not already exist; if it doesn't, it'll be created on disk when you first save it. If you leave off the filename, you'll be asked to supply a name for the file when you first save your work.

You can give more than one filename on the command line; `jedit` will open a separate window for each file you specify, and different windows can be in different modes. (Note that there's a distinction between two copies of `jedit` each displaying one window, and one copy of `jedit` displaying two windows. Among other things, there are more ways to copy and paste among windows displayed by the same copy of `jedit` than between separate invocations of `jedit`.)

Each file can be preceded by an argument consisting of a plus sign (`+`) followed (with no intervening space) by a line number; this will cause the cursor to be positioned at the given line when the following file is read in. This is for the convenience of programs like mail and news programs and debuggers, which may want to let the user edit a file at a particular position (e.g. where a syntax error occurred). It follows that filename can't start with a plus sign, or it will be misinterpreted as a line number; you can work around this if necessary by preceding filename with ``./`' or with a full path.

If you specify an editing mode with the `-mode` option, `jedit` will use the mode you specify instead of guessing what mode to use based on the type of the file. (In general, different modes are intended for editing different types of files. For instance, `mail` mode, intended for composing mail messages, provides a button to sign your mail. For more information, see the section Editing Modes below.)

You can specify a width and/or height on the command line. If you do so, the specified width and/or height will be used for all the windows initially created by the editor, when they are first created. (You can also specify preferred window sizes for particular editing modes on the Mode Preferences panel, described below.) The actual window may end up being wider than the width you specify, so that all the menu items and buttons can be displayed.

If you give the `-iconic` flag, then all windows initially started by `jedit` (the initial blank one if you don't specify a filename, or the windows for each of the files specified on the command line) will be created iconified. This is useful, for instance, if you want to start `jedit` whenever you log in. You can start it iconified, so it won't pop up a window that might obscure other windows, and then just deiconify it when you want it.

(The `-for` option assists coöperation between `jedit` and other Tkbased applications; it can be used by another Tkbased application to tell a new `jedit` session it starts what the name of the parent interpreter is; for instance, `exmh-mode` uses this to tell a new copy of `jedit` what the name of the `exmh` interpreter is. The `-for` option is only used by certain modes, and you wouldn't ordinarily use it on the command line.)

## Getting Help

The leftmost menu, labelled `Help', lets you get help on various topics related to the editor. The topmost choice, `Help on jedit', displays the documentation for the editor - this document. The second choice, `Help on Customisation', brings up the same document, but jumps directly to the section about customising `jedit`. The third choice, `Help on Programming with jedit', displays a document which describes writing new editing modes for `jedit` and using it in your own Tk applications. The last choice, `Help on jstools', displays general documentation for the jstools applications.

Depending what editing mode you're in, there may also be another choice which describes the particular mode you're in. For instance, if you're editing a Tcl script (in `tcl` mode), you'll see a `Help with Tcl Mode' choice, which brings up a document describing the particular features of `tcl` mode, such as automatic indentation and special commands.

All of these menu choices invoke the `jdoc` application to display the documentation.`
`

## The Editor Menu

The editor menu has commands to get information about `jedit`, to manage modes and preferences, and to issue Tcl and Unix commands.

### About the Editor...

The `About the Editor...' command displays an information panel with copyright information. The panel also lets you get more information about the author, and about the Tk/Tcl scripting environment.

### Global Preferences...
Editor Preferences...
Mode Preferences...

These bring up preferences panels, described in the section Preferences below.

### Mode...

This brings up a panel that lets you type in the name of an editing mode, and switches the editor into the specified mode. Editing modes are described in the section Editing Modes below.

### Issue Tcl Command...

This brings up a panel that prompts you for a Tcl command to be executed. This is an advanced feature intended primarily for use in designing and debugging configuration files; it's not normally useful for editing files.

### Issue Unix Command...

This brings up a panel that prompts you for a Unix command to be executed. If the command produces any output, it will be displayed; otherwise you'll see a notice to that effect. If there are any errors in the execution of the command, you'll see an error dialogue box with the error message returned by the command. This command doesn't (necessarily) have any effect on your document; it's just a convenience.

## Working with Files and Windows

The commands on the `File' menu let you load and save files, insert another file into the one you're working with, control editor windows, and quit the `jedit` application.

The label at the top of the text window, below the menu bar (and the buttonbar, if it's displayed), displays the name of the file you're editing and the current editing mode.

Note that specific editing modes may implement the `Load...', `Save', and `Save As...' commands a little differently from the default behaviour described below.

### Load...

`Load...' will prompt you for a file name and attempt to load the file into the editor. If the file doesn't exist, ``(new file)'' will appear in the label to let you know the file doesn't actually exist on disk yet, and it will be created (if possible) when you next save the file.

(Depending on the editing mode you're in and your modespecific preferences, the current state of the text - the position of the selection and the insert point, any highlighting information, etc. - may be restored as well, if it was saved. See Preferences for more information.)

### Save

`Save' will save the file, using the name that appears in the filename label. If the file hasn't been named yet, a panel will appear asking you to choose a name for the file.

(Depending on the editing mode you're in and/or your modespecific preferences, the current state of the text - the position of the selection and the insert point, fonts and colours, etc. - may be saved as well. If so, the additional state information may be stored in a file called .state.filename in the same directory as filename, where filename is the name of the text file, or the file itself may be stored in a special format that contains that information. See Preferences for more information.)

### Save As...

`Save As...' asks you for a name, and saves the file under that name.

(As with `Save', additional state information may be saved, depending on your editing mode and preferences.)

### Print...

After asking for confirmation, `Print...' uses the `lpr`(1) command to print your document.

(If your document uses multiple fonts or colours, or underlining, those attributes won't be preserved in the printout; the `Print...' command is really only suitale for plaintext email, program listings, and the like. If you need to print a richtext document with font changes intact, see Printing MultiFont Text under Working with Fonts and Colours below.)

You can select a printer using the Global Preferences panel; the default printer is `lp`.

### Insert File...

`Insert File...' asks you for the name of a file, which is inserted into the current file at the insertion point (the blinking vertical bar). For instance, if the insertion point is at the end of a letter you're composing, you can insert the file .signature (if that file exists) to sign your letter.

### New Window

The `New Window' command starts up a new, empty `jedit` document window. You can then click in the new window and start typing, or load a document into it.

### Done

The `Done' command saves your document and then closes the window (which will cause `jedit` to quit if you only have one window open). Chosing `Done' is just a convenient shortcut for choosing `Save' and then `Close Window'.

### Close Window

If there's only one window open, `Close Window' does the same thing as `Quit'; i.e., it exits the editor.

If there's more than one window open, `Close Window' will only close the current window (the one you choose it from). By default, you will be asked to confirm that you want to close the window. (You can change this with the jstools Global Preferences panel.) When you close a window, any changes you may have made to your file since you last saved it will be lost - choosing `Close Window' does not automatically save your file.

### Quit

This should be selfexplanatory. By default, you will be asked to confirm that you want to quit. (You can change this with the jstools Global Preferences panel.) As with `Close Window', any changes you may have made to your file since you last saved it will be lost. Be warned that the `Quit' command will close all windows belonging to a single `jedit` application, so if you have changes you haven't saved in any of the windows, they'll be lost.

## Selecting, Copying, and Pasting Text

To select text, just drag across it with the mouse, as in any X Windows application. The selected text will be highlighted. (You can change how selected text is displayed with the Editor Preferences panel.)

Note that `jedit`, unlike most X Windows applications based on the Athena widget set, distinguishes the selection from the insertion point - they don't have to be in the same place.

### The X Selection

The currentlyhighlighted selection is exported as the X Windows selection. The selection is shared among all the applications running on the display, so if you highlight text in some other application, the text you've selected in the editor will be deselected. Using the X selection is the only way to copy text between `jedit` and another application, or between two separate copies of `jedit` (although you can use the cutbuffer, described below, to copy text between two separate document windows belonging to the same `jedit` application).

You can paste the X selection into another application - a different program, like `xedit`(1) or `xterm`(1), or another copy of `jedit` - using whatever mechanism that program provides. (In Athenabased applications like `xedit` and `xterm`, for instance, you press the middle mouse button.)

To paste the current X selection in `jedit`, choose `Insert X Selection' from the `Edit' menu (or type Meta-Shift-V). You can also insert the X selection by clicking the middle mouse button. If you're using `Basic' keyboard bindings (see Preferences), you can also insert the X selection by typing Control-v. (Control-v is the normal way of inserting the X selection into other Tkbased applications.)

### The Cutbuffer

In addition to the X selection, there's another mechanism for cutting and pasting text - the cutbuffer. When you select some text (by dragging with the mouse) and choose `Copy' from the `Edit' menu, the highlighted text is copied into the cutbuffer - it's remembered for future reference. When you later choose `Paste' from the `Edit' menu, the thencurrent contents of the cutbuffer are inserted into your text at the insertion point. `Cut' works like `Copy', but also deletes the selected text from its original location. You use `Cut' and `Paste' to move text, and `Copy' and `Paste' to duplicate text.

This method of copying and pasting text works like copying and pasting on a Macintosh or a NeXT, except that it only works within a single `jedit` application. (You can, however, use the cutbuffer to copy or move text between different windows maintained by the same `jedit` application.)

### Select All...

Choosing `Select All...' from the `File' menu (or typing its keyboard equivalent) is a shortcut to select all the text in the document.

### Making Notes

Sometimes you may wish to refer to one part of a long file while editing another part. Or you may want to look at the original version of the file while you make changes. You can do this by selecting the part you wish to refer to and choosing `Note' from the `Edit' menu. A new window will pop up containing the selected portion of the text. The contents of that window won't change if you edit the original file in the main window, nor can you edit the contents of the new note window.

## Search and Replace

### Find...

The `Find...' command under the `Edit' menu will bring up the jstools Find panel, which lets you search for a string of text, and optionally replace it with another string of text.

### Find Again

The `Find Again' command works like clicking the `Search' button on the find panel: it repeats the previous search. It is convenient because you don't have to bring up the find panel, and you don't have to use the mouse to invoke it (if you use the keyboard equivalent, Meta-g). The search will be backwards and/or casesensitive and/or regularexpressionbased if the previous one was.

If there isn't currently anything entered in the find panel's `Search for:' field (e.g., if you haven't yet tried to find anything since starting the editor), `Find Again' will just bring up the find panel, like `Find...'.

### Replace

The `Replace' command replaces whatever is currently selected (whether or not you selected it by searching for it with the Find panel) with the last thing you entered into the `Replace with:' field in the Find panel. It's mainly there so that once you've used the Find panel to set search and replace strings, you can search and replace from the keyboard without bringing up the Find panel again.

## Inserting Special Characters

In addition to a few commands to quickly insert commonlyused but hard-to-type characters, the `Characters' submenu under the `Edit' menu has a `Select Character...' command, which brings up a Characters panel which lets you insert any printable character into your document by clicking on it, even if you can't type it on your keyboard (or can't remember how to :-). You can leave the Characters panel up for the next time you need it while you go back to the main window and type, or you can click the `Done' button to close it.

## Undo, Redo, and Checkpoint

The editor supports a limited version of undo. Up to ten recent states of the file you're working on are saved in an undo buffer. (This number is configurable with the `Undo Levels' slider on the Editor Preferences panel, described under Preferences. If you set it to zero, no undo information will be kept and the undorelated commands won't be available.) You can choose `Undo' from the `Edit' menu to revert to successively earlier states of the file. If you `overshoot', you can choose `Redo' to return to successively later states - a `Redo' is the converse of an `Undo'. (This is hard to describe, but fairly easy to use.)

You can't undo each little modification to the file (each character typed, for instance); you can only undo to a particular state if a checkpoint of that state has been saved. In general, checkpoints are saved each time you issue an editor command (i.e., a menu entry, or the keyboard equivalent of a menu entry) that changes or is likely to change the text. They're also saved whenever you type certain punctuation characters, such as commas, periods, and closing parentheses.

For example, choosing `Cut' or `Paste' will save a checkpoint, as will piping the selection through a command. Bringing up the Find panel saves a checkpoint, because you might do a `Replace' or `Replace All'. However, clicking on the replace buttons on the Find panel doesn't save a checkpoint, because they aren't menu entries. Also, editing commands that are exclusively keyboardbased (such as Control-w if you're using Emacs keyboard bindings) won't save a checkpoint.

You can, however, explicitly save a checkpoint by choosing `Checkpoint' from the `Edit' menu. You might do this, for instance, periodically while typing a large amount of text without invoking editor commands, or before issuing a keyboardonly command that might change the text.

Checkpoints are stored in memory, so the more checkpoints you save (the more levels of undo information you ask for), and the longer your files are, the more memory you'll need. If you edit small files, you can save lots of undo information, but if you're editing very large files, having a lot of (or any) undo information saved may cause the editor to crash or misbehave due to running out of memory. Also, having checkpointing turned on (i.e., setting `Undo Levels' to anything other than zero) may cause delays as the checkpoint is made.

For these and other reasons, the current undo mechanism is not really satisfactory. I hope to implement a more intuitive and less limited undo mechanism in a future version of the editor.

## Navigating by Line Number

### Go To Line...

The `Go to Line...' command under the `Edit' menu lets you type in a line number and moves the insertion point to the beginning of that line. It's useful, among other things, for finding the place in a file of program source code where an error is reported.

### Show Current Position...

The `Show Current Position...' command under the `Edit' menu pops up a panel telling you where in the file the insertion point is, by line number and character position within the line.

## Making Transformations to the Selection

The commands under the `Filter' menu lets you perform various transformations on your text by applying a substitution to the selection, or running it through a Unix command, and replacing the original selected text with the output of the command.

### Formatting Paragraphs

The `Format Lines with ``fmt''' command lets you run the selected text through the Unix `fmt`(1) command, which tries to format paragraphs so that the lines are about the same length, breaking long lines, and filling in short ones (except for the last line in a paragraph, of course). For information on exactly what it does, see the `fmt`(1) manual page on your system.

Warning: Many versions of `fmt`(1) have a limit on the length of the input lines they can handle; if a single input line is longer than that limit, it will be truncated. So if you type a long paragraph (longer than about eight or ten lines) without pressing Return at the end of any of the lines, if you run that paragraph through `fmt`(1) you will lose some of your text. Also, `fmt`(1) requires a newline on the end of its input, so you should make sure the last line is entirely selected, including the newline. The easiest way to do this is to select by tripleclicking the mouse and dragging, which selects entire lines at a time.

### Changing Case

`Uppercase', `Lowercase', and `Toggle Case' should be fairly selfexplanatory; they pipe the selected text through various invocations of the `tr`(1) command. (`tr`(1) discards the trailing newline from its input, so if the selected text ends in a newline, it will be lost.)

### Indentation

#### Indent

The `Indent' command inserts two spaces at the beginning of each line in the selection.

#### Unindent/Unquote

The `Unindent/Unquote' command deletes two spaces, or one of a small number of punctuation characters typically used to indicate quoted material, followed by a space, from the beginning of any line in the selection that has them. It will also change a tab at the beginning of a line to six spaces.

#### Quote Email

The `Quote Email' command inserts a greaterthan symbol and a space at the beginning of each selected line, to indicate quoted material in email or news postings.

### Sorting

#### Sort by ASCII Sequence

The `Sort by Character Codes' command uses the Unix `sort`(1) command to sort the lines of the selection.

#### Sort Numerically

`Sort Numerically' uses `sort -n`, which sorts by number rather than by ASCII character code.

#### Sort Alphabetically

`Sort Alphabetically' uses `sort -if`, which ignores nonalphabetic characters and doesn't distinguish between capitals and lowercase.

For input to `sort`(1), the selection should end in a newline. The easiest way to insure this is to select by tripleclicking and dragging the mouse, which selects whole lines at a time.

### Pipe Through...

The `Pipe Through...' command prompts you for a Unix command to be used as a filter on your selected text. (I.e., the selected text is fed into the command as input, and the output of the command then replaces the selection.) For instance, you could sort the lines of the selected text in reverse order by piping them through the command `sort -r.`

### Insert Output of...

The `Insert Output of...' command prompts you for a Unix command, runs it, and inserts its output into your document at the insertion point. For instance, you could insert a listing of the files in the current directory by entering `ls -lA`. (This isn't really a filter, because it doesn't use the selection, but it didn't seem to deserve a whole new menu to itself.)

## Working with Multiple Windows

You can get `jedit` to display more than one window in one of two ways: by specifying more than one filename on the command line, or by choosing `New Window' from the `Editor' menu. Each window normally displays a separate document; windows can be in different modes, and each window can have its own filename. Each window has its own menu.

You can copy and paste between windows belonging to the same copy of `jedit` with the `Cut', `Copy', and `Paste' commands. (You can only copy and paste between windows belonging to different copies of `jedit`, or between `jedit` and another application, by using the X selection.)

### Caveats

The support for multiple windows in `jedit` isn't completely seamless yet, and there are a few things you should be careful about:

- It's possible to open the same file more than one time in the same copy of `jedit` (or, for that matter, in two different copies) but it is Strongly Not Recommended. It's easy to accidentally wipe out your work that way; changes you make in one window won't be reflected in the other, and whichever version you save last wins.
- Panels like the Find Panel and the Characters panel apply only to the window you started them from. If you open a Find Panel from within window A, and then click in window B and start typing, that Find Panel will still search only in window A. If you want to search in window B, you need to choose `Find...' again from within window B. This is not how most multidocument applications work, and it's definitely on my list of things to fix.
- Command shortcuts apply to the window you're typing into. (Exactly what this means depends on which version of Tk you have installed; in Tk 4.0 and later, it's probably the window your mouse pointer is over; in earlier versions it's probably the last window you were typing in.)
- Menu commands, reasonably enough, apply to the window under the menubar you choose them from.

## Preferences

Three different preference panels, available under the `Editor' menu, allow you to change the lookandfeel of the editor, and a little bit of its behaviour.

The Global Preferences panel lets you set preferences that apply to all the jstools applications (such as `jmore` and `jdoc`), and any other Tk applications that choose to honour them. The Editor Preferences panel lets you set preferences that only apply to the `jedit` application itself, but apply to all its modes. And the Mode Preferences panel lets you set preferences that only apply to the current mode.

On all three of the panels, clicking `Save' will save the currentlydisplayed preferences, so they'll be used the next time you start up `jedit`, while clicking `Done' won't save them for future use, but will apply them to your current editing session. (Currently, this is broken on the Mode Preferences panel; clicking `Done' cancels your changes.)

### Global Preferences...

This command brings up the jstools Global Preferences panel. The most important global preferences for working with `jedit` are probably the binding preferences, which let you choose Emacs emulation, `vi` emulation, or neither, and determines whether selecting text and typing will delete the selected text (as it does in Windows, Macintosh, and Motif applications) or not..

### Editor Preferences...

The Editor Preferences panel lets you customise the appearance of the big text area that contains your document. It lets you set the colours used to display your text, the width of the vertical line that marks the insertion point, the width of the raised border drawn around selected text, and the width of the blank border around the entire text window.

It also lets you select the amount of undo information, if any, that's kept. For more information about this, see the section Undo, Redo, and Checkpoint.

The buttons labelled `RGB' let you select a colour by manipulating sliders that represent the individual red, green, and blue components of the colour you're choosing. The buttons labelled `Name' let you select a colour by name, from the list of colours known on your system.

(Note: If the name of the colour database on your system isn't /usr/lib/X11/rgb.txt, then the `Name' colour buttons won't list all the colours available.)

Editor preferences are saved in the file ~/.tk/jedit-defaults.

### Mode Preferences...

The Mode Preferences panel lets you set preferences for the current editting mode (i.e., the current kind of file).

#### Menus and Buttonbar

On the left of the Mode Preferences panel is a column of checkbuttons that let you choose which menus are displayed in the current mode, and whether the buttonbar is displayed. On the right are controls for the other modespecific preferences.

#### Save/Load Visual State

The `Save/Load Visual State' checkbox controls whether state information such as the position of the insertion point within a file, the current selection, and any other highlighting a particular mode may support are saved along with the text of a file. If this checkbox is selected, such information will be saved into a file called .state.filename in the same directory as filename, where filename is the name of the ordinary text file. (This checkbox controls the behaviour of the `Load...', `Save', and `Save As...' commands, but not the `Insert File' command. Also, not all editing modes may honour the state of this checkbox, and some that do may save state information in some other fashion..)

#### Break Lines on <space>

If `Break Lines on <space>' is selected, then when you press the space bar near the end of a line of text (as displayed on the screen), the line will be broken by inserting a newline marker after the space. (The exact rules are that if you press the spacebar when the current line is longer than fifteen characters less than the width of the text window, as specified on the preferences panel, a space and a newline are inserted; otherwise just the space is inserted. This doesn't work well with variablewidth fonts like Helvetica or New Century Schoolbook.)

#### Indent Lines on <Return>

If `Indent Lines on <Return>' is selected, then when you press the Return key, the indentation of the previous line (i.e., any leading spaces and/or tabs) will be duplicated in the new line. This is useful, for instance, for editing program code.

#### Flash Matching Brackets

If `Flash Matching Brackets' is selected, then whenever you type a right curly brace (``}`'), square bracket (``]`'), or parenthesis (``)`'), the corresponding left brace, bracket, or parenthesis is flashed briefly. You'll only be able to see this if the opening character is already visible on the screen. If there's no matching character, the entire window will flash to warn you.

#### Static and Dynamic Abbreviation

`Static Abbreviation' and `Dynamic Abbreviation' control whether abbreviations are expanded as you type; for more information see the section Abbreviations below.

#### Line Wrapping

The following three radio buttons control how lines which are longer than the width of the window are displayed. They should be fairly selfexplanatory.

#### Font

The `Font:' field lets you choose what font is used to display the file you're editing. You can type in an X font specification, or click the `Choose...' button to select a font visually using the `xfontsel`(1) application. (Use `xfontsel`'s menus to choose a font based on its various attributes, such as size and weight, and click `xfontsel`'s `Quit' button to enter the font you have chosen into the editor's `Font:' field.) You can click the `Default' button to set the font field to ``default`', which means to use the X default font (using the X default specification ``Tk*Font`:'), or 12point Courier if there is no X default. See the man page for the X server for more information about X font specifications and X defaults.

#### Width and Height

The `Width:' and `Height:' fields let you change the width (in characters) and height (in lines) of the editor.

Modespecific preferences are saved in the file ~/.tk/jeditmodes/mode-defaults, where mode is the current editing mode.

## The Prefs Menu

A `Prefs' menu is available which lets you set some of the modespecific preferences without having to bring up the Mode Preferences panel. None of the provided editing modes (see Editing Modes) displays the `Prefs' menu by default, you have to ask for it to be displayed in a particular mode on the Mode Preferences panel.

The preferences available on the `Prefs' menu are:

- Save/Load Visual State
- Break Lines on <space>
- Indent Lines on <Return>
- Flash Matching Brackets
- Static Abbreviation
- Dynamic Abbreviation
- Don't Wrap Lines
- Wrap Lines Anywhere
- Wrap Lines at Words

You can also set some abbreviationrelated preferences using the `Abbrev' menu.

## The Buttonbar

Below the menubar and above the main text area, a buttonbar is available. The buttonbar is intended to make the most frequentlyused operations available conveniently, and the particular buttons available vary depending what mode you're in. For instance, the `mail-mode` buttonbar provides a `Sign' button to sign your mail. The default buttonbar, used in plain mode and by any mode that doesn't have a modespecific buttonbar, provides `Print', `Load', `Save', and `Done' buttons, which do the same things as the corresponding menu commands.

You can turn off the buttonbar on the Mode Preferences panel.

## Abbreviations

The editor supports two different models of abbreviation expansion: dynamic abbreviation and static abbreviation, inspired by Emacs' `dabbrev-mode` and `abbrev-mode`, respectively. Both are intended to save keystrokes by allowing you to type a short sequence of characters and have the editor expand it to an entire word. Both are enabled through entries on the `Abbrev' menu or through checkboxes on the Mode Preferences panel (described under Preferences); there are also keyboard equivalents.

### Dynamic Abbreviation

In dynamic abbreviation, you can type the beginning of a word you've used earlier in the text and press the Tab key. The editor will search backwards in the text and try to find a word that starts with the letters (and/or numbers) you've typed. If such a word is found, the word you're typing will be expanded to match (and a space will be inserted to end the word). If no matching word is found, nothing happens.

If you have dynamic abbrevs turned on and you want to insert an actual tab, you can type Control-I. (That's a capital letter i.)

If you've chosen `Emacs bindings' on the Global Preferences panel, then you can also use the keyboard command Escape-/ (M-/ in Emacs terms) to expand the word before the insertion point, whether or not you have dynamic abbrevs turned on. (This allows you to use the Tab key to insert actual tabs.)

### Static Abbreviation

In static abbreviation, you maintain an explicit list of abbreviations and their expansions. When you press the space bar or one of a number of punctuation marks, the `word' before the insert point is examined to see if it matches a static abbreviation you've defined; if so, the abbreviation is expanded.

The intention of static abbreviation is that you can type normally, except for using abbreviations for common or long words, and the abbreviations will be expanded for you as you type. With static abbreviations, the `abbreviation' doesn't necessarily have to have any similarity to its expansion; you can make `qv' expand to `theology' if you like.

### The Abbrev Menu

#### Toggling Abbreviation Modes

The first two items on the Abbrev menu, `Static Abbreviation' and `Dynamic Abbreviation', let you turn the two abbreviation modes on and off without bringing up the Preferences panel. You can also toggle dynamic abbreviation by typing MetaTab, and static abbreviation by typing MetaSpace. (However, if your window manager is `mwm`, MetaSpace may be intercepted. You can change this in your `.mwmrc` file; see the man page for `mwm`(1) for more information.)

#### Explicitly Expanding Abbreviations

The `Expand Static Abbreviation' and `Expand Dynamic Abbreviation' commands try to expand the static or dynamic abbreviation before the insert point. This is useful if you don't have automatic abbreviationexpansion turned on, but have an abbreviation for a long word or phrase you'd like to have expanded. You can also invoke these commands by typing ControlSpace and ControlTab.

#### Creating and Editing Abbreviations

The `Edit Static Abbreviations' command runs the `jabbrevs` command, which lets you maintain your list of static abbreviations. (See the `jabbrevs` documentation for more information.) When you quit `jabbrevs`, `jedit` will reread your list of abbreviations. Your list of static abbreviations is stored in the file ~/.tk/abbrevs.tcl.

#### Rereading Abbreviations

The `Reread Static Abbreviations' command rescans the file ~/.tk/abbrevs.tcl and updates the editor's list of abbreviations. You need to do this after modifying this file, in order for them to take effect immediately. However, `jedit` does this for you automatically when you quit `jabbrevs` if you started it with the `Edit Static Abbreviations' command.

### How Static Abbreviations Work

A static abbreviation can consist of letters, numbers, and the apostrophe (`'`). Its expansion can be any string. The apostrophe is treated a little differently in an abbreviation: it can form part of an abbreviation to be expanded, but when typed, it also triggers expansion of the preceding word. So a typed word that contains an apostrophe can trigger two expansions. For example, if you have abbreviations ``q`' for ``and`' and ``and'n`' for ``question`' and you type ``q'n`', it will (ultimately) expand to ``question`'.

When creating static abbrevs, you may want to include noun plurals and other inflected forms; if you have an abbrev for `professor', for instance, you may also want to have an abbrev for `professors'.

Capitalisation of static abbreviations is handled specially: if you have an abbreviation which starts with two lowercase letters, and you type it with an initial capital, the corresponding expansion will be capitalised and inserted for you. This doesn't happen if the static abbreviation is only one letter long, or if the first two letters of the abbreviation are both capitalised, because often single capital letters or sequences of capital letters are intended to be written as abbreviations (as in I.W.W., NATO, or Boston, MA). What this means is that if you have the abbreviations ``c`' for ``can`' and ``cert`' for ``certainly`' in your abbreviations list and you type ``Cert`', it'll be expanded to ``Certainly`'. If you just type ``C`', though, it won't be expanded to ``Can`'. However, if you want a single capital letter (or a capitalised word) to expand to something, you can always add it explicitly as a separate abbreviatiion.

## Gesture Commands and Popup Menus

Gesture commands are commands associated with a particular mouse movement. In `jedit`, gesture commands are invoked with mouse button 3 (typically the right mouse button). To invoke a gesture command, press and hold mouse button 3, drag the mouse quickly a short distance in the appropriate direction, and release mouse button 3.

The `Cut' command is bound to gestureup; to cut text, press and hold mouse button 3, drag the mouse quickly upwards, and release mouse button 3. (A range of text must already be selected.)

The `Paste' command is bound to gesturedown; to cut text, press and hold mouse button 3, drag the mouse quickly down, and release mouse button 3.

There's no gesture command for `Copy', but you can simulate a copy operation by cutting text and then immediately pasting it, without moving the insert point. You can then move elsewhere and paste it again.

There are also two popup menus associated with mouse button 3. They're invoked similarly to the two gesture commands above: press and hold mouse button 3, drag the mouse quickly left of or right, and release mouse button 3.

The menu you get by dragging right with mouse button 3 depressed has a subset of the commands available on the Filter menu (described under Making Transformations to the Selection), along with the `Note' and `Select All' commands (described under Selecting, Copying, and Pasting Text) from the Edit menu. The menu you get by dragging left with mouse button 3 depressed has a subset of the commands available on the File menu (described under Working with Files and Windows), as well as the Undo, Redo, and Checkpoint commands from the Edit menu.

## Working with Fonts and Colours

Many editing modes are designed to work with plain, unformatted text. Some, however, let you manipulate the appearance of the text, so that you can use multiple fonts and colours and underlining. Modes that support such rich text provide a `Format' menu, with commands to set display attributes, and also commands to insert special characters and write your document out in various formats. (There are also keyboard shortcuts for some of the format commands.)

### Setting Display Attributes

The commands to set display attributes (font, colour, and underlining) control the appearance of text you subsequently type. However, if you've made a selection in the text (and if the insert point touches the selection, i.e., if you haven't moved away from the selection since making it), they also change the appearance of the selected text. So you can choose `Bold' to start typing in bold text, but you can also select a word or two and choose `Bold' to make it bold.

Unlike most word processors, however, the font commands aren't toggles. So if you're typing in bold, you can't choose `Bold' to turn bold off and go back to typing in roman; you have to explicitly choose `Roman'. Also, you can't choose `Bold' and then `Italic' to type in bold italic, you have to choose `Bold Italic' separately (as far as `jedit` is concerned, it's a completely different font. Also unlike most word processors, the font you choose is kept until you explicitly choose another, even if you move the cursor. So if you choose `Bold' and type a word or two in boldface at the end of your document, and then click in the middle of the paragraph above, you're still typing in bold. (The same applies to underlining and colours.)

### The Format Menu

#### Rich Cut, Copy, and Paste

The `Rich Cut', `Rich Copy', and `Rich Paste' commands work analogously to the `Cut', `Copy', and `Paste' commands under the `Edit' menu, except that they preserve fonts, colours, and underlining, as well as the text itself. (Actually, what they preserve is text tags, described in the Tk `text`(1) manual page.)

The cutbuffer used by these commands is completely separate from the one used by the corresponding commands under the `Edit' menu. So `Rich Paste' will insert the last thing you saved with `Rich Copy' or `Rich Cut', even if you've used the plain `Copy' or `Cut' commands since then.

The `Rich Cut' and `Rich Copy' commands are fairly slow; they should be fine for a couple of paragraphs, but may be painful for very long selections of text.

#### The Font SubMenu

The `Font' submenu contains commands to set and change the font of text you type (or text you've selected). The jstools libraries' notion of font in this context is fairly abstract - you don't get to choose between Courier Italic by IBM and Charter Bold by Bitstream, for instance, but only among broad categories like Bold and Typewriter font. Currently, the actual font used is hardcoded; I hope to change this in the future.

The font categories available are aimed at constructing documents like help files, which may contain example code and are divided up into sections and subsections. In addition to `Roman', `Italic', `Bold', and `Bold Italic', which are useful in normal text, a fixedpitch `Typewriter' font is available which may be useful for example code or commands, and six levels of headings are available which you can use to divide your document up into sections.

A `Plain Font' command lets you cancel any font attributes (from the selection and from text you subsequently type); text without any font attributes will be displayed in whatever font you've chosen in the Mode Preferences panel for the current mode (but it may still be displayed underlined or coloured). Generally, it's preferable just to use `Roman'.

#### The Background and Foreground SubMenus

The `Background' submenu includes the `Plain Background' command, which clears the background colour, as well as a selection of background colours. The `Foreground' menu has corresponding commands for setting the text colour.

You should be careful using colour in documents that you might share with other people. Putting a phrase in dark grey for emphasis may look fine on your screen (against your white background), but if somebody else has configured `jedit` to use a black background - or worse yet, dark grey -, it won't look so good. You can get around this by specifying both the background and foreground colours; that at least guarantees that the text will be legible, although it may not mesh well next to somebody else's default colours. Moreover, blue text on a dark grey background may look fine on your colour screen, but might appear blackonblack on a monochrome screen.

#### Underline

The `Underline' command turns underlining on or off (unlike the font and colour commands, it is a toggle). A checkbox by the `Underline' command indicates the current state of underlining.

#### Type in Plain

The `Type in Plain' command cancels all display attributes for subsequent text you type. The text will be displayed with the font you've selected in the Mode Preferences panel and the colours you've selected in the Editor Preferences panel. If you're working with multifont text (rather than, say, just using colour to highlight a phrase), it probably makes more sense to use the `Roman' font command and the `Plain Background' and `Plain Foreground' commands.

#### Saving MultiFont Text in Other Formats

The `Rich Save As...' command lets you write out your document in one of several formats. As of this writing, the formats supported include PostScript, TeX, HTML, and the Tclbased richtext format used by the jrichtext.tcl and jabout.tcl libraries. This process (currently) only saves font information, not underlining, colours, or other attributes. For more information, including tips for composing documents that will convert well, see RichText Format Conversions.

#### Printing MultiFont Text

If you have a PostScript printer available, you can print multifont text with the `Print PostScript' command. As with format conversion, this only preserves font changes, not underlining or colour. It asks you to confirm before printing.

## Customising the Editor

`jedit` supports the standard jstools customisation mechanisms. You should consult the document Customising jstools Applications as well as the description below.

### The ~/.tk/jeditrc.tcl startup script

The file ~/.tk/jeditrc.tcl can contain Tcl code to customise your editing environment. You can define a `User' menu in this file, or make other changes to the user interface. You can also define new procedures, and tie them into the user interface. For instance, you could create procedures to encrypt or decrypt your files.

One important thing you can change in your ~/.tk/jeditrc.tcl script is the `FILE_MODES` variable, which is a list of filename patterns and the corresponding modes to use. The editor consults this variable when it's deciding what mode to use for editing a particular file. Here's an example of adding filename - mode correspondences to the `FILE_MODES` variable:

`global FILE_MODES
lappend FILE_MODES \
{*.pl code {Perl or Prolog source}} \
{*.pbm bitmap {Portable Bitmap files}} \
{*.des des {DES-encrypted files}}
`
(This example assumes you've created new `bitmap` and `des` modes to deal with these kinds of files.)

There's also a `LINE_MODES` variable which is similar to `FILE_MODES`, but selects a mode based on the first line of a file. It's used if none of the patterns in `FILE_MODES` matches. Here's an example of adding line - mode correspondences to the `LINE_MODES` variable:

`global LINE_MODES
set LINE_MODES [concat {
{%!* ps {PostScript source}}
{#!*/bin/awk* awk {awk script}}]
} $LINE_MODES]
`
(Again, this example assumes you've created approprate modes to handle PostScript and `awk`(1) files.)

I hope to add a panel to let you set the correspondence between filenames or firstline patterns and editing modes interactively in a future version.

### Modes

You can create new editing modes by copying or creating Tcl files and defaults files that define them. New editing modes can be just for your own personal use, or they can be installed for everyone's use at a site. Also, you can copy the systemwide files that define a particular editing mode, and modify them to your taste.

Creating new editing modes and modifying existing ones are described in Programming with jedit.

### Sample files

If `jedit` was installed in the typical place at your site, the directory /usr/local/lib/jstools/samples should contain some example files which you can copy, rename appropriately, and modify to your liking. (You may also find it useful to look at the `jedit` script and library files themselves, and for information about Tcl syntax you should consult the various Tcl and Tk man pages. Typically, the `jedit` library files are in the directory /usr/local/lib/jstools.)

## Editing Modes

The editor supports the notion of distinct editing modes for different types of file. There are a few modes distributed with the editor, and it's easy to create additional modes, or modify the existing ones. There's a list of available editing modes in Editing Modes Distributed with jedit.

The editor will behave differently depending on which mode it's in. For instance, an editing mode for C code might try to automatically change the indentation of each line based on the structure of the code, or a mode for TeX source might display TeX keywords in a different font from ordinary text. (Both of these modes are hypothetical.)

In the simplest case, two modes can differ simply in the default values of certain modespecific preferences (which you can override for each mode as described under Preferences). For instance, a mode for editing plain naturallanguage text probably would not have automatic indentation set on by default, but a mode for editing program code probably would. At the other extreme, the richtext documentation editing mode distributed with the editor (`jdoc-mode`) modifies the editor's behaviour extensively, changing the way files are saved, loaded, and displayed, and providing commands that let you manupulate text with hypertext links.

You can force the editor to use a particular mode by specifying ``-mode` modename' on the command line. Unless you do, though, the editor will try to choose an appropriate mode itself. The mode is set before the file is read in.

To choose an editing mode for a file, the editor first tries to match the filename against a list of patterns. If a match is found, it uses a corresponding mode. If no match is found, then the editor reads in the first the first line or so of the file and tries to match it against another list of patterns and modes. (This is mainly for the benefit of scripts using the Unix ``#!`interpreter_path' syntax, so you can distinguish between `wish`(1) scripts and `csh`(1) scripts, for instance. You could also use this mechanism to make `jedit` honour Emacsstyle ``-*-`mode`-*-`' lines.) If no match is found, the builtin plain mode is used.

You can change the correspondence between filenames (or initial string) and modes by setting or adding to the `FILE_MODES` or `LINE_MODES` variables in your ~/.tk/jeditrc.tcl file, as described under Customising the Editor. Note that if you want to override builtcorrespondences (rather than add an entirely new pattern), you'll need to make sure you add to the beginning of these lists rather than the end.

The filename correspondences currently built into the editor are as follows:

`*.c` `code` `C source
*.f` `code` `Fortran source
*.h` `code` `C header files
*.jdoc` `jdoc` `document for jdoc app.
*.jrt` `richtext` `rich-text w/fonts et al.
*.p` `code` `Pascal source
*.sh` `code` `Bourne shell script
*.shar` `code` `Bourne shell archive
*.tcl` `tcl` `Tcl scripts
*.tk` `tcl` `Tk/Tcl scripts
*.exp` `tcl` `Expect scripts
*/.letter` `mail` `Mail from tin
.letter` `mail` `Mail from tin
*/.[a-zA-Z]*` `code``~/.login, etc.
.[a-zA-Z]*` `code``.login, etc.
*/draft*/[0-9]*` `mh` `MH, exmh, xmh, etc.
*/tmp/snd.[0-9]*` `mail` `elm
*/tmp/R*[0-9]` `mail` `UCB Mail
*.note note short multi-font note
`
(The latter is no longer recommended; I suggest using `richtext` mode instead.)

The firstline patterns used if none of the filename patterns match are:

`%!*` `code` `PostScript file
{#!*/wish*}` `tcl` `Tk/Tcl scripts
{#!*/tclsh*}` `tcl` `Tcl scripts
{#!*/expect*}` `tcl` `Expect or Expectk scripts
#!*` `code` `executable script
`

## Bugs and Misfeatures

- The Find panel interacts strangely with multiple windows. It only searches in the window you started it from; you might expect it to search in whatever window you were typing in most recently.
- The commandkey equivalents for selecting display attributes don't toggle the way they typically do in wordprocessors.
- The modeselection dialogue should let you choose a mode from a list, since it's a constrained set.
- The `Find' and `Note' panels are likely to be in your way.
- When piping text through a command, handling of trailing newlines is inconsistent and arbitrary.
- Vertical motion with the cursor keys doesn't work with lines that contain tabs, and it arguably works wrong with proportional fonts.
- The undo mechanism is clumsy, inefficient, and incomplete.

## Future Directions

- I'd like to create special panels to deal with the correspondence between filename patterns and editing modes.
- I intend to add commandline flags to select different intialisation and preference files. (This is less important now that I have support for multiple modes.)
- I hope to add a generalised undo facility; several people have asked for that. This essentially requires wrapping all the commands that modify the text in a journalling mechanism; it will be done in jtext.tcl. (The jstools applications and libraries use jtext.tcl exclusively to modify text widgets; except for jtext.tcl itself, they don't use the text widget commands directly in ways that would modify the text.) The current undo facility is inadequate.
- There should be a way to copy just the tags (not the text) in effect at a particular place and apply them to another range of text.
- Instead of several sorting commands, there should be a sort panel with sorting options.
- I hope to extend the provided modes, and work on creating more. In particular, I need more and smarter modes for programming. (There should certainly be a C mode, for instance.)

`
`