This is Info file jade.info, produced by Makeinfo-1.55 from the input file jade.texi. START-INFO-DIR-ENTRY * Jade: (jade). An editor for X11 and AmigaDOS END-INFO-DIR-ENTRY This is Edition 1.3, last updated 7 October 1994, of `The Jade Manual', for Jade, Version 3.2. Jade is a text editor for X11 (on Unix) and the Amiga. Copyright 1993, 1994 John Harper. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. File: jade.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) Jade is a highly flexible Emacs-style text editor for X11 (on Unix) and AmigaDOS. This is Edition 1.3 of its documentation, last updated 7 October 1994 for Jade version 3.2. * Menu: * Copying:: Distribution conditions * Introduction:: Brief introduction to Jade * News:: New features in this release * Systems Supported:: The operating systems Jade supports * Editor Concepts:: Some ideas you should understand * Key Names:: How keys are described in this manual * Starting Jade:: How to start the editor * Using Jade:: Instructions for using the editor * Programming Jade:: How to extend Jade -- its Lisp system * Reporting Bugs:: How to contact me * Function Index:: Menu of all documented functions * Variable Index:: All variables which have been mentioned * Key Index:: Menu of all key bindings * Concept Index:: Main index, references to all sections File: jade.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top Copying ******* Jade is distributed under the terms of the GNU General Public License, this basically means that you can give it to anyone for any price as long as full source code is included. For the actual legalese see the file `COPYING' in the distribution. I reserve the right to use a different licence in future releases. The only parts of Jade which are not my own work are the regexp code, this is by Henry Spencer (though I have made some small modifications) and is distributed under his conditions, and the ARexx interface in the Amiga version which is based on `MinRexx' by Radical Eye Software. Be aware that there is absolutely NO WARRANTY for this program, you use it at your own risk. Obviously I hope there are no bugs, but I make no promises regarding the reliability of this software. File: jade.info, Node: Introduction, Next: News, Prev: Copying, Up: Top Introduction ************ Jade is a text editor primarily designed for programmers. It is easily customised through a Lisp-style extension language and can be tailored to the user's own requirements. Jade is designed to run under a graphical windowing system, systems currently supported are the Commodore Amiga and the X Window System version 11 (but only under Unix). It is the successor to the editor `Jed 2.10' which I released for the Amiga in early 1993. I have decided to rename it now that I have made an X11 version since there is already an editor called `Jed' available (there is no connection between the two, I haven't even looked at the other one). "Jade" is an anagram of "A Jed", if you want an acronym you could use "Just Another Damn Editor", if you can think of anything better please tell me. Jade is compatible with GNU Emacs in terms of key presses and command names to a certain extent but it is not intended as a simple copy of Emacs (indeed, when I started this I had never actually used Emacs!). I have tried to take my favourite aspects of all the editors I have used as well as adding features that I have not found elsewhere. Consequently, it is very much the editor that *I* want -- you may not find it so appealing. File: jade.info, Node: News, Next: Systems Supported, Prev: Introduction, Up: Top This chapter lists the major changes to Jade and which release they occurred in. Only changes relevant to you, the user, are detailed; for more explicit history see the `ChangeLog' files with the sources. Version 3.2 =========== * The programmer's manual has finally be written. * Undo; devote as much memory as you want to keep track of all modifications to a buffer which can then be wound back. * Arguments can be given to commands as they're invoked. * Buffer menu for interactive buffer manipulation. * An Emacs-style local variables section can be embedded in a file; replaces the naff `::jade-code::' thing. * `Ctrl-k' (`kill-line') works at last. * Now possible to interrupt jade while it's working (i.e. to let you kill infinite loops). * The Help system now has commands to list key bindings, display what is bound to any key sequence. * Use of the Latin-1 character set is now controlled by the minor mode `latin-1-mode'. * Can load and save compressed (compress or gzip) files into/out of buffers transparently when running on Unix. * Transposing commands; `transpose-chars', `transpose-words', `transpose-exps'. Bound to `Ctrl-t', `Meta-t' and `Ctrl-Meta-t' respectively. * Can now run a shell in an editor buffer, very basic (no completion) but it works okay. * Support for using gdb through the shell interface, the current frame's source code is highlighted in a separate window. * `Ctrl-z' moves to `Ctrl-W' so that `Ctrl-z' can (de)iconify the current window. * Some programs written for the previous incarnation will need to be altered; all will have to be recompiled. Version 3.1 =========== * Now properly supports characters which print as more than one character (i.e. proper tabs, `^L', `\123', etc...). In general any character can print as any sequence of up to four character-images. * Doesn't expand tabs to spaces anymore, this means that loading and saving of largish files is noticeably quicker. * Files containing NUL characters can be edited (more or less) successfully. Some commands (notably the regexp matcher) still don't like these characters but, in the main, binary files can be edited successfully. * Searching and replacing has changed, it's easier to use now and replacing globally is built in. * Many improvements to the Info viewer, not least, the dir file doesn't have to have a tag-table anymore. * Client editing. This lets you load files into a running editor from a shell. For example, if your mailer runs an editor on the message you're writing you can use the client to edit the message in a Jade that you are running. * The buffer prompt's completion is now controllable by the mouse as well as the keyboard. Click the right button to complete the current word. Double-clicking the left mouse button on one of the lines under the `::Completions::' line selects that completion. * `text-mode' and `indented-text-mode' major-modes for editing English language (as opposed to programming languages). * Minor-modes. These provide small variations to the major-modes. For example, `overwrite-mode' makes typed keys overwrite whatever's under the cursor. Also included is a minor mode to do auto-filling (word wrap). * On Unix, a tilde (`~') in a filename is handled properly in most cases * It is now possible to Meta qualify a key press and it will pretend that you pressed ESC then the un-Meta'd key. File: jade.info, Node: Systems Supported, Next: Editor Concepts, Prev: News, Up: Top Requirements ************ Jade will only run on certain operating systems, this chapter details just what it needs as well as some notes relevant to each system. Amiga Jade ========== The only real requirement for Jade running on an Amiga is that it must run an operating system revision of at least V37 (thats V2.04) and have about 300K free memory available. It also needs more stack than the average Amiga application. For normal use 20K should be okay. If you want to use the Lisp compiler 50K would be a better bet. It assumes that its directory is pointed to by the `JADE:' assignment. This means that the main Lisp files are stored in `JADE:lisp/' and the file of doc-strings is `JADE:DOC'. X11 Jade ======== Jade will only run on version 11 of X, it has absolutely no support for character terminals or different windowing systems. As long as it compiles it should work on your system. One problem you might find is that the Backspace and Delete keys don't work properly. As far as I have been able to find out, most X terminals map both the Backspace (normally at the top-right of the alpha-keyboard) and the Delete (normally somewhere above the cursor keys) keys to the `Delete' keysym. Obviously, since I want these keys to have different effects (1) this is no good. What I decided to do about this was two things, 1. Use `xmodmap' to map the Delete key to the `Backspace' keysym. This may sound backwards but most programs seem to use the `Delete' keysym as what I call `Backspace' so mapping as I described doesn't break this. To do this, I have the following in my `.Xmodmap' file keycode 107 = Backspace Note that the `107' is the Delete key's key code on *my* keyboard, your keyboard may, and probably will, be different. 2. In the function which binds descriptions of key presses to Lisp forms, swap the meanings of the `Backspace' and `Delete' keysyms. This means that everything works okay! You can bind to Delete key and it will work properly. ---------- Footnotes ---------- (1) Backspace should rub out the key before the cursor and Delete should delete the character under the cursor File: jade.info, Node: Editor Concepts, Next: Key Names, Prev: Systems Supported, Up: Top Editor Concepts *************** Before I describe the editor in detail there are several concepts which you should be familiar with. Some will be explained in more detail later. "buffer" Buffers are used by the editor to store the text that you are editing. Broadly speaking, each buffer holds the contents of one text-file loaded into the editor (it is not necessary for each buffer to be associated with a file, some buffers exist for other purposes for example the `*jade*' buffer is used to interact with the Lisp system). "current buffer" The buffer being edited in the current window (see below), most editor commands work on this buffer unless told otherwise. "window" Corresponds to a window in the window-system. Each window can display one buffer at a single time (although a buffer may be displayed in more than one window at once). "current window" Jade always keeps track of which one of its windows is active. It is called the current window. Whenever you type a key or press a mouse button in one of Jade's windows, that window automatically becomes the current window. Amongst other things, all messages from the editor are displayed in the status line of the current window. "cursor" The cursor marks your current position in the current buffer (see above), when you type something it is inserted into the buffer between the cursor and the character preceding it (unless you type a command). "status line" One line in a window is devoted to displaying messages from the editor, *Note Using Windows::. "Lisp" The programming language which Jade uses, although the internals of the editor are written in C, all commands are written in a dialect of Lisp (even if the command only calls a C function). Jade contains an interpreter, compiler and debugger for this language. *Note Programming Jade::. "variable" Variables are used to store Lisp values, each variable has a unique name. Note that unlike many programming languages variables in Lisp are *not* typed, the data values themselves have a type associated with them. "form" A form is a single Lisp expression. For example, all of these are forms: foo 42 "hello" (setq foo 200) "command" A command is a sequence of Lisp forms which may be called interactively (i.e. from the keyboard). It may be a key sequence (such as `Ctrl-x Ctrl-f') or a Lisp function to evaluate (such as `find-file'). "regular expression" A regular expression is a string which is used to match against other strings. It has a special syntax which allows you to form a kind of template against which the other strings can be matched. They are used extensively by the editor, but you -- the user -- will mainly encounter them when searching and replacing strings in buffers. File: jade.info, Node: Key Names, Next: Starting Jade, Prev: Editor Concepts, Up: Top Key Names ********* In this manual I have adopted a consistent notation for all key presses, since most editor commands are invoked via a typed key sequence it is very important that you can decipher this notation. Note that the term `input event' (or `event') and the term `key press' have been used interchangeably throughout this manual. A `key press' may mean a mouse event, they don't always come from the keyboard. Every key press has a set of "modifiers"; these are the keys such as "Shift" or "Control" which don't actually produce a character when typed, they only effect the rest of the keyboard. Each key, then, can have one or more modifiers. The name of an event consists of zero or more hyphen-separated modifier names, followed by a hyphen and the name of the actual event. Some commands are triggered by more than one of these key presses; press each key (or do whatever is necessary to precipitate the input event) in turn to invoke the command. Note that the case of modifiers is not important, however some of the keys *are*, so you should always specify them in their correct case. * Menu: * Modifiers:: Names of modifier keys * Keys:: Names of actual keys * Example Keys:: Some examples and what they mean File: jade.info, Node: Modifiers, Next: Keys, Up: Key Names Modifiers ========= "Shift" "SFT" The shift key. "Ctrl" "CTL" The control key, or its equivalent. "Meta" This depends on the window-system, on X11 it is the "Mod1" modifier, on the Amiga the "Alt" key. When the `meta-sends-esc' variable is non-nil the Meta modifier is treated specially, - Variable: meta-sends-esc When non-nil, any Meta-modified key presses are expanded into a sequence of two key presses, ESC and the pressed key minus its Meta modifier. For example typing `Meta-f' would expand to `ESC f'. This feature is provided for compatibility with GNU Emacs. What this really means is that when the option is enabled (it is by default) you can either type the key sequence `ESC X' or the sequence `Meta-X' (where Meta is your keyboard's meta key) to invoke a command described as `Meta-X'. "LMB" The left mouse button. "MMB" The middle mouse button. "RMB" The right mouse button. As well as these, there are also some others, "Mod1" to "Mod5" represent the X11 modifiers of the same name. "Button1" to "Button5" also correspond to their X11 counterparts (Button1 to Button3 are LMB to RMB). For Amiga users, "Amiga" corresponds to the Amiga key (this is the same as Mod2). File: jade.info, Node: Keys, Next: Example Keys, Prev: Modifiers, Up: Key Names As far as possible each single character key-definition corresponds to where that character is on the keyboard (a is `a', etc...). When using an Amiga this should be true for *all* keys since the Amiga's "keymap.library" makes it easy to look up what key a character belongs to. However, this is not so easy on X11. All of the standard ASCII character set should be okay, but the more esoteric characters may have to be specified by the names of their X11 keysym (without the `XK_' prefix). Look in the include file for all keysyms, for example `XK_question' would have to be used for `?' if the editor didn't treat it, and many others, specially. Some keys which don't follow this pattern are "SPC" "Space" The space bar. "TAB" The tab key. "RET" "Return" The return key. "ESC" "Escape" The escape key. "Backspace" The backspace key. "DEL" "Delete" The delete key. "Help" The help key, not all keyboards have this. The cursor up key. "Down" The cursor down key "Left" The cursor left key. "Right" The cursor right key. "KP_Enter" "KP_Multiply" "KP_Divide" "KP_Minus" "KP_Add" "KP_Decimal" "KP_N" Keys on the numeric keypad. For KP_N, N is a digit. "Click1" Single clicking a mouse button. "Click2" Double clicking a mouse button. "Off" Releasing a mouse button. "Move" Moving the mouse. This doesn't work on X11 yet. File: jade.info, Node: Example Keys, Prev: Keys, Up: Key Names Example Keys ============ Some examples of proper key names are, `Ctrl-x' Hold down Control, type x. `Meta-Shift-RET' Hold down Meta and Shift, then type the Return key, or alternatively, type the Escape key then hold down Shift and type Return. `LMB-Click1' Click the left mouse button once. `Ctrl-RMB-Click1' Hold down Ctrl then click the right mouse button once. File: jade.info, Node: Starting Jade, Next: Using Jade, Prev: Key Names, Up: Top Starting Jade ************* This chapter describes Jade's initialisation process. This includes how to start it, what options it will accept and what it actually does after being started. * Menu: * Invocation:: How to start the editor * Startup Options:: Arguments specified on the command line * Startup Procedure:: What happens on startup File: jade.info, Node: Invocation, Next: Startup Options, Up: Starting Jade Invocation ========== Since Jade supports two vastly different operating systems they both need to be covered separately. Amiga ----- The normal way to start Jade on the Amiga is to type its name at the Shell (or CLI) together with any options (*note Startup Options::.) you want. Note that these options are in the traditional Unix style, a dash followed by the option name and any arguments, not the standard AmigaDOS method. It is also possible to invoke the editor from the Workbench, simply double clicking on its icon will cause Jade to open its initial window. Unfortunately there is no support for passing arguments via Tool Types, nor is there any way to create icons with saved files. This is largely due to the fact that I rarely use the Workbench -- if enough people complain about this I will probably fix it. Jade doesn't have an icon yet, you'll have to make one yourself. Jade should be started like most other Unix programs, type its name and any arguments to a shell. It must be able to connect to an X server (preferably the one controlling your terminal), the `-display' option can be used if needed. File: jade.info, Node: Startup Options, Next: Startup Procedure, Prev: Invocation, Up: Starting Jade Startup Options =============== The acceptable options can be split into three classes. Note that they must be specified on the command line in order of their class. This means that, for example, the `-rc' option must be after the `-font' option. So, the general usage pattern is jade [SYSTEM-DEPENDENT-OPTIONS] [STANDARD-OPTIONS] [LISP-OPTIONS] Note that the LISP-OPTIONS may include files to be loaded. 1. System dependent options. * Options for the Amiga system. `-pubscreen SCREEN-NAME' Defines the name of the public screen on which the first window is opened. By default (or if SCREEN-NAME doesn't exits) the `Workbench' screen is used. `-font FONT-STRING' Defines the font used in the first window. FONT-STRING is the font to use, it is the name of the font (for example, `topaz.font'), followed by a hyphen and the point size to use. For example, a FONT-STRING of `topaz.font-8' gives 8-point topaz. This is the default. `-stack STACK-SIZE' When this argument is given Jade allocates a new stack. STACK-SIZE is a decimal number defining the size (in bytes) of the new stack. If this argument is not given Jade simply uses the stack that AmigaDOS gave it. * Options for X11. There are two types of options to the X11 version of the editor, those specified on the command line and those defined in the resource database (i.e. in your `.Xdefaults' file). Resources are looked for under two names, firstly the name under which the editor was invoked (normally `jade'), if this fails it tries again with the name `Jade'. Naturally, options specified on the command line override those in the resource database. `-display DISPLAY-NAME' Defines the name of the X display to open, by default the contents of the environment variable `DISPLAY'. It is a string of the form `HOST-NAME:NUMBER.SCREEN-NUMBER'. `-name NAME' The name to use when looking up resource values, this replaces the base name of the executable (normally `jade'). `-geometry GEOM-SPEC' Specifies where to place the first window on the screen. This is a standard X style geometry specification. `-fg FOREGROUND-COLOUR' Resource: `fg: FOREGROUND-COLOUR' The colour of the window's foreground (i.e. the text). `-bg BACKGROUND-COLOUR' Resource: `bg: BACKGROUND-COLOUR' The background colour of the window. `-font FONT-NAME' Resource: `font: FONT-NAME' The name of the font used for all text in the initial window. 2. Standard options. `-rc LISP-FILE' Load the Lisp script LISP-FILE instead of the normal initialisation script (`init'). Warning: the editor depends heavily on the normal file, if you change this without due care the editor could be unusable -- no keys will be bound and many standard functions won't exist. `-v' Print the version and revision numbers of this copy of the editor then quit. `-log-msgs' This option makes all messages which are displayed in the status line also be written to the standard error stream. This is sometimes useful for debugging purposes. 3. All other options are passed to the Lisp initialisation process in the variable `command-line-args', these are available to any Lisp packages loaded in the initialisation script. Any left after that are scanned for the following options, `-f FUNCTION' Call the Lisp function FUNCTION. `-l FILE' Load the Lisp file FILE. `-q' Quit cleanly. `FILE' Load the file of text FILE into a new buffer. An example command line for starting Jade from a Unix shell could be $ jade -fg white -bg black -log-msgs foo.c bar.jl This means white text, black background, save messages and load the files `foo.c' and `bar.jl'. File: jade.info, Node: Startup Procedure, Prev: Startup Options, Up: Starting Jade Startup Procedure ================= This is a description of what happens when the editor initialises itself. 1. Firstly lots of internal data structures are created, memory pools, symbols and their symbol-table (including all the primitive Lisp functions). 2. The window-system is initialised (parse the system-dependent options, and the xrdb resources if in X). 3. Parse the standard options. 4. Create the initial window and the first buffer to display in it (this is the buffer called `*jade*'). 5. Load the initialisation script, this is either the Lisp file called `init' or whatever was given to the `-rc' command line option. Some selected highlights of what the standard file does are, * Load lots of Lisp files, some notable ones are `autoload' Initialise the autoload stubs. `loadkeys' Creates the standard keymaps and key bindings. * Try to find the user's personal startup file, this is normally the file `.jaderc' in their home directory (1). * Load any files which were specified on the command line. 6. Start the top-level recursive edit, this doesn't exit until the editor does. ---------- Footnotes ---------- (1) The Amiga has no notion of a user's home directory, Jade uses the contents of the environment variable `HOME', or if this doesn't exist the `SYS:' assignment. File: jade.info, Node: Using Jade, Next: Programming Jade, Prev: Starting Jade, Up: Top 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. * Menu: * Invoking Commands:: How to use the commands and key-sequences described in this manual. * Command Arguments:: Many commands can be modified by prefixing them with a numeric argument * The Help System:: Online help facilities * Loading and Saving Files:: Manipulating files * Editing Buffers:: Simple editing commands * Moving Around Buffers:: Commands for moving the cursor * Undo:: Go back in time * Editing Units:: Characters, words, lines, etc... * Cutting And Pasting:: How to insert text from the clipboard * Using Blocks:: Highlighting regions to manipulate * Killing:: Deleting text for later insertion * Searching and Replacing:: Searching the buffer for a regexp * Editing Modes:: Editing different types of files * Minor Modes:: Small alterations to editing modes * Using Buffers:: Selecting & deleting buffers * Using Windows:: Opening new windows * Using the Prompt:: Entering strings and completion * Using Marks:: Recording positions in files * Interrupting Jade:: Breaking out of commands * Recursive Editing:: Editing within a command * Character Images:: How to get a Latin1 character set * Client Editing:: Using Jade from other programs * Compiling Programs:: Help for developing programs * Info Mode:: Reading Info files with Jade * Shell:: Using a shell inside a buffer * Simple Customisation:: Configuring Jade File: jade.info, Node: Invoking Commands, Next: Command Arguments, Up: Using Jade 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 *Note Programming Jade::. File: jade.info, Node: Command Arguments, Next: The Help System, Prev: Invoking Commands, Up: Using Jade 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'. File: jade.info, Node: The Help System, Next: Loading and Saving Files, Prev: Command Arguments, Up: Using Jade 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. To list all function names matching REGEXP, type `a REGEXP RET' when in the help system. Prints all key bindings and their associated commands which are installed in the current buffer. Similarly to the `a' command, to list all variable names matching REGEXP, type `e REGEXP RET' when in the help system. Displays the online documentation for a function. After invoking this option type the name of the function. Shows some helpful text describing how to use the help system. Enters the Info viewer. This allows you to browse through files written in the Info hypertext format. For more information see *Note Info Mode::, for more information on Info files in general see *Note Info: (info)Top. 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. Display the documentation for the current major mode. Displays the online documentation and current value of a variable. Type the name of the variable after invoking this option. File: jade.info, Node: Loading and Saving Files, Next: Editing Buffers, Prev: The Help System, Up: Using Jade 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. * Menu: * Commands To Load Files:: Key sequences to load files * Commands To Save Files:: How to save a buffer * File Variables:: Local variables defined in files * Backup Files:: Making backups * Auto-Saving Files:: Files can be saved periodically * Accessing Compressed Files:: Reading and writing gzipped files * Other File Commands:: How to delete, rename or copy files File: jade.info, Node: Commands To Load Files, Next: Commands To Save Files, Up: Loading and Saving Files Commands To Load Files ---------------------- There are several commands used to load files into buffers, these `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 *Note The Buffer Prompt::. File: jade.info, Node: Commands To Save Files, Next: File Variables, Prev: Commands To Load Files, Up: Loading and Saving Files 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 File: jade.info, Node: File Variables, Next: Backup Files, Prev: Commands To Save Files, Up: Loading and Saving Files 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 *Note 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 (*note 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. File: jade.info, Node: Backup Files, Next: Auto-Saving Files, Prev: File Variables, Up: Loading and Saving Files 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. File: jade.info, Node: Auto-Saving Files, Next: Accessing Compressed Files, Prev: Backup Files, Up: Loading and Saving Files 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). File: jade.info, Node: Accessing Compressed Files, Next: Other File Commands, Prev: Auto-Saving Files, Up: Loading and Saving Files 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'). File: jade.info, Node: Other File Commands, Prev: Accessing Compressed Files, Up: Loading and Saving Files 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. File: jade.info, Node: Editing Buffers, Next: Moving Around Buffers, Prev: Loading and Saving Files, Up: Using Jade 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. *Note 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. File: jade.info, Node: Moving Around Buffers, Next: Undo, Prev: Editing Buffers, Up: Using Jade Moving Around Buffers ===================== Here is a selection of the most commonly used commands which move the cursor around the current buffer. `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. File: jade.info, Node: Undo, Next: Editing Units, Prev: Moving Around Buffers, Up: Using Jade 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. File: jade.info, Node: Editing Units, Next: Cutting And Pasting, Prev: Undo, Up: Using Jade 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. * Menu: * Editing Characters:: Commands operating on characters, * Editing Words:: words, * Editing Expressions:: expressions, * Editing Lines:: and lines. File: jade.info, Node: Editing Characters, Next: Editing Words, Up: Editing Units Editing Characters ------------------ These are the commands which operate on characters. Note that when an argument (*note 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'.