This is Info file jade.info, produced by Makeinfo-1.55 from the input file jade.texi. This is Edition 1, last updated 19 April 1994, of `The Jade Manual', for Jade, Version 3.0. Jade is a text editor for Unix (with X11) 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. This is so that jade doesn't try to eval the example use. ::jade-code:: ::end:: File: jade.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) Jade is a highly flexible text editor for the Unix (with X11) and Amiga operating systems. This is Edition 1 of its documentation, last updated 19 April 1994 for Jade version 3.0. * Menu: * Copying:: Distribution conditions * Introduction:: Brief introduction to Jade * Systems Supported:: The Operating Systems Jade supports * Editor Concepts:: Some key ideas you should understand * Key Definitions:: 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 license 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 reguarding the reliability of this software. File: jade.info, Node: Introduction, Next: Systems Supported, 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 a Unix 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 keystrokes 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. The feature that the most people will dislike is that it doesn't support "proper" tabs. By this I mean that it expands all tabs to a sequence of spaces when loading a file, they are not converted back to tabs until the file is saved back to disk (though this is optional). File: jade.info, Node: Systems Supported, Next: Editor Concepts, Prev: Introduction, 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. * Menu: * Amiga Jade:: * Unix and X11 Jade :: File: jade.info, Node: Amiga Jade, Next: Unix and X11 Jade, Up: Systems Supported 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-strings'. File: jade.info, Node: Unix and X11 Jade, Prev: Amiga Jade, Up: Systems Supported Unix and 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 keycode on *my* keyboard, your keyboard may, and probably will, be different. 2. In the function which binds descriptions of keystrokes 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 Definitions, 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 (ie, from the keyboard). It may be a key sequence (such as `Ctrl-x Ctrl-f') or a Lisp function to evaluate (such as `ESC x 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 Definitions, Next: Starting Jade, Prev: Editor Concepts, Up: Top Key Definitions *************** In this manual I have adopted a consistent notation for all keypresses, since most editor commands are invoked via a typed key-sequence it is very important that you can decipher this notation. Every keypress 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 actual key definition consists of zero or more hyphen-separated modifiers, followed by a hyphen and the name of the actual key (or event). Some commands are triggered by a sequence of one or more of these key definitions, press each key definition 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 Definitions 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. "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 "Mod2" represent the X11 modifiers of the same name. "Button1" to "Button5" also correspond to their X11 conterparts (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 Definitions 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 "Space" "SPC" "SpaceBar" 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 Definitions Example Keys ============ Some examples of proper key definitions are, `Ctrl-x' Hold down Control, type x. `Meta-Shift-RET' Hold down Meta and Shift, then type the Return key. `LMB-Click1' Click the left mouse button once. `Meta-RMB-Click1' Hold down Meta then click the right mouse button once. File: jade.info, Node: Starting Jade, Next: Using Jade, Prev: Key Definitions, 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. * Unix with X11 Jade should be started like most other Unix programs, type its name and any arguments to a shell. It must be able to connect to an X server (preferably the one controlling your terminal), the `-display' option can be used if needed. 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-DEPENDANT-OPTIONS] [STANDARD-OPTIONS] [LISP-OPTIONS] Note that the LISP-OPTIONS may include files to be loaded. 1. System dependant 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. * 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 (ie, 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 overide those in the resource database. `-display DISPLAY-NAME' Defines the name of X display to open, by default the contents of the environment variable `DISPLAY'. It is a string of the form `hostname: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' `fg: FOREGROUND-COLOUR' *RESOURCE* The colour of the window's foreground (ie, the text). `-bg BACKGROUND-COLOUR' `bg: BACKGROUND-COLOUR' *RESOURCE* The background colour of the window. `-font FONT-NAME' `font: FONT-NAME' *RESOURCE* 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-dependant 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 `loadsyms' Initialise the autoload stubs. `loadkeys' Creates the standard keymaps and keybindings. * 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. The only things that you need to know about at this time are how to set or reference Lisp variables and how to invoke Lisp commands. Luckily, it is very easy to do this by typing one of the following sequences to the editor, `ESC x FUN' Calls the command called FUN and displays its result in the status line. `ESC x set-variable RET FOO RET BAR' This sets the Lisp variable FOO to the value BAR. `ESC x show-variable RET FOO' This displays the value of the variable FOO in the status line. Note that throughout this manual it is assumed that you press the RET (return) key after each `ESC x' command. For example, to invoke the command `ESC x find-file' you would actually type the following (but not the spaces -- they are for readability). `ESC x f i n d - f i l e RET' * Menu: * The Help System:: Online help facilities * Loading and Saving Files:: Manipulating files into buffers * Editing Buffers:: Simple editing commands * Moving Around Buffers:: Commands for moving the cursor * Using Blocks:: Highlighting regions to manipulate * Cutting And Pasting:: How to insert text from the clipboard * Searching and Replacing:: Searching the buffer for a regexp * Editing Modes:: Editing different types of files * Using Buffers:: Selecting & deleting buffers * Using Windows:: Opening new windows * Using the Prompt:: Entering strings and completion * Using Marks:: Recording positions in files * Compiling Programs:: Help for developing programs * Simple Customisation:: Configuring Jade File: jade.info, Node: The Help System, Next: Loading and Saving Files, 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. Similarly, 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. Display the current editing modes documentation. 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:: Keystrokes to load files * Commands To Save Files:: How to save a buffer * Backup Files:: Making backups * Auto-Saving Files:: Files can be saved periodically * Loading and Saving Tabs:: How tabs are handled * Automatic Mode Selection:: File suffixes can select editing modes * Embedding Lisp In Files:: Lisp to evaluate when a file is loaded 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: Backup Files, Prev: Commands To Load Files, Up: Loading and Saving Files Commands To Save Files ---------------------- These are the commands used to save buffers and the keystrokes 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: Backup Files, Next: Auto-Saving Files, Prev: Commands To Save Files, Up: Loading and Saving Files Backup Files ------------ The editor can optionally preserve the previous contents of a file when they are about to be overwritten by saving a buffer. It does this by renaming the old file, `foo' as `foo~' (the original name plus a tilde appended to it). - Variable: make-backup-files This variable controls whether or not backups are made of files about to overwritten by the function `write-buffer' (ie, 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. If `backup-by-copying' is nil and renaming the original file as its backup would be damaging (ie, changing the ownership of the file or breaking a link) no backup will be made. File: jade.info, Node: Auto-Saving Files, Next: Loading and Saving Tabs, 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 (ie, 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). If you want to change the format of the name of auto-saved files look at the function `make-auto-save-name' and its documentation. File: jade.info, Node: Loading and Saving Tabs, Next: Automatic Mode Selection, Prev: Auto-Saving Files, Up: Loading and Saving Files Tab Expansion ------------- The editor does not leave tab characters (ASCII 9) as they are. They are expanded into one or more spaces when the file is read into its buffer. The size of the expansion depends upon the column number at which the tab has occured and the value of the variable `disk-tab'. - Variable: disk-tab This buffer-local variable determines the size of tab stops used when a file is read from disk (by the `read-buffer' function) into a buffer. It is desirable that the files which the editor produces have tabs in them though, so something has to be done. The variable `save-tabs' controls exactly how files are saved (in respect to saving tab characters). - Variable: save-tabs The value of this buffer-local variable is used to decide exactly which sequences of spaces are changed to tab characters when a buffer is saved to disk (with the `write-buffer' and `write-buffer-area' functions). There are three possible options (all of which are Lisp symbols): `nil' *No* tabs are saved at all. All whitespace is left untouched, this may be necessary with some types of file whose format is strongly defined. `leading' Any whitespace at the start of each line is translated into tabs and spaces such that the first non-whitespace character in the line is at the same logical position as it was in the buffer. `all' Any sequence of two or more space characters is translated into tab characters when the logical structure of the line would be unaltered by doing so. *No* translations take place after the first quote character (ie, `'', ``' or `"') in the line (this is to try and prevent errors). File: jade.info, Node: Automatic Mode Selection, Next: Embedding Lisp In Files, Prev: Loading and Saving Tabs, Up: Loading and Saving Files Automatic Mode Selection ------------------------ As described elsewhere in this manual, each buffer can have an editing mode associated with it (ie, `c-mode' for editing buffers of C source code). Since it would be extremely tedious to have to invoke the mode's initialisation function manually whenever a new file is loaded the editor can initialise the mode automatically. It does this by scanning an association list called `mode-alist' for a regular expression matching the name of the file (or the string in the buffer-local variable `mode-name' if it is non-nil). If a match is found the function associated with the matching regular expression is called, thereby initialising the mode. If you don't understand this, don't worry -- it works. For example, the mode-alist contains this fragment as one of its elements: ("\\.[ch]$" . c-mode) which means call the function `c-mode' for any file ending in `.c' or `.h'. - Variable: mode-alist A list of elements of `(MATCH-REGEXP . MODE-FUN)'. When a file is loaded each MATCH-REGEXP is compared with the name of the file in question (or it's `mode-name' value). When a match is found the corresponding MODE-FUN function is called. File: jade.info, Node: Embedding Lisp In Files, Prev: Automatic Mode Selection, Up: Loading and Saving Files Embedding Lisp In Files ----------------------- It is possible to include Lisp commands in the text of a file so that they will be read and evaluated when that file is loaded into a buffer. This is normally used to set buffer-local options which are specific to one particular file, ie, to set the name of the editing mode, or the size of tab characters in this file. The way to do this is to include a section of text of the form in the file: ... XXX ::jade-code:: XXX Lisp Line1 XXX Lisp Line2 XXX ... XXX Lisp LineN XXX ::end:: ... The `XXX' just means that any text to the left of the column in which the `jade-code' begins is ignored (This is mainly to allow for any comments needed to make sure that the Lisp text is not used by whatever uses the file). Only one block such as this is allowed per file, it is not evaluated until the whole of the file has been read. Some examples uses of this could be, In a lisp file: ;;; ::jade-code:: ;;; (setq lisp-mode-tab 4) ;;; (setq mode-name "lisp-mode") ;;; ::end:: Or in a C source file: /* ::jade-code:: * (setq c-mode-tab 4) * (setq mode-name "c-mode") */::end:: It is also possible to prohibit the evaluation of these special sections. - Variable: no-file-code-p When non-nil the section of a file marked for auto-evaluation (with the `::jade-code::' marker) is *not* evaluated. 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 (ie, alphanumeric, puntuation, 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 keystroke `Shift-TAB' moves to the previous tab stop). Some miscellaneous editing commands are, `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. Deletes the character before the cursor. `DEL' Deletes the character under the cursor. `Shift-BS' Kills the characters between the start of the line and the cursor. `Shift-DEL' `Ctrl-d' 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. `ESC d' `ESC DEL' Kills from the cursor to the end of the current word. `ESC i' Inserts spaces to fill from the cursor to the next tab stop. `ESC l' Makes the characters from the cursor to the end of the word lower case. `ESC u' Upper cases the characters from the cursor to the end of the word. `ESC BS' Kills from the cursor to the beginning of the word. File: jade.info, Node: Moving Around Buffers, Next: Cutting And Pasting, Prev: Editing Buffers, Up: Using Jade Moving Around Buffers ===================== These are the commands which are used to 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. `ESC <' Move to the first character in the buffer. `ESC >' 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' `ESC v' Move to the previous screenful of text. `Ctrl-DOWN' `Ctrl-v' Move to the next screenful of text. `Meta-LEFT' `ESC b' Move to the previous word. `Meta-RIGHT' `ESC f' Move to the next word. `Meta-UP' `ESC [' Move to the start of the previous paragraph. `Meta-DOWN' `ESC ]' Move to the start of the next paragraph. `TAB' `ESC TAB' Move to the next tab position. Note that some editing modes redefine TAB to make it indent the current line. `Shift-TAB' Move to the position of the previous tab. `Ctrl-TAB' `ESC i' Insert a tab (ie, enough spaces to move to the next tab position). `Ctrl-j' `ESC x goto-line' Prompt for a line number and go to it. `ESC m' Move to the first non-space character in the current line. There are several variables which affect the commands described above, these are, - Variable: screen-tab This buffer-local variable controls the size of tab characters in a buffer. Its standard value is 8. This variable does not affect the size of tabs in files read into the buffer, that is controlled by `disk-tab'. - Variable: y-scroll-step-ratio A window-local variable which controls what happens when you move the cursor off the top or bottom of the window. A value of zero means move as much as needed to get the cursor back into view, for example, if you move down one line, it will scroll the window one line only. If the value is not zero the screen is moved by the number of rows in the window divided by the value. For example, a value of 2 means scroll the window in chunks half the size of the window -- this is useful for when you are working with a slow updating display. - Variable: x-scroll-step-ratio Similar to `y-scroll-step-ratio' except for horizontal movement. File: jade.info, Node: Cutting And Pasting, Next: Using Blocks, Prev: Moving Around Buffers, Up: Using Jade Cutting And Pasting =================== One of the main functions of any editor is to allow you to move around chunks of text, jade makes this very easy. Generally, to paste down some text you have to get the text to be inserted into the window-system's clipboard (1). If the text you wish to paste is in one of the editor's buffers jade has a number of commands for doing this, this is sometimes referred to as "killing" the text. If the text to be pasted is in the same buffer as the position to which you want to copy it there is an easier way than putting it into the clipboard. For more details see *Note Commands on Blocks:: and the command `Ctrl-i'. Once the text to be pasted is in the clipboard there are two commands which can be used to insert it into the buffer before the cursor, `Ctrl-y' Inserts the contents of the standard clipboard into the buffer at the cursor position. `Ctrl-Y' This is a variant of `Ctrl-y', it treats the string that it is pasting as a "rectangle" of text. That is, each successive line in the string (each separated by a newline character) is inserted on successive lines in the buffer but at the same column position. For more details see *Note Rectangular Blocks:: and the function `insert-rect'. ---------- Footnotes ---------- (1) When using an Amiga, unit zero of the `clipboard.device' is used. For X11, the first cut-buffer. File: jade.info, Node: Using Blocks, Next: Searching and Replacing, Prev: Cutting And Pasting, Up: Using Jade Using Blocks ============ A "block" is a section of a buffer, you mark it by specifying its edges (ie, the first and last characters). This part of the buffer can then have various things done to it, for example insert it somewhere else. Each window can only have a single block marked at any one time, it will be displayed in the reverse of normal text (ie white on black, not black on white). * Menu: * Marking Blocks:: Commands to define the current block * Commands on Blocks:: How to work with blocks * Rectangular Blocks:: Columns of text as blocks File: jade.info, Node: Marking Blocks, Next: Commands on Blocks, Up: Using Blocks Marking Blocks -------------- To mark a block you must specify its outermost points, note that the text marked by the block ends one character before the marked position (this is so that it easy to mark whole lines). Rectangular blocks are a bit different for more information, see *Note Rectangular Blocks::. Note also that block marks shrink and grow as text is deleted and inserted inside them, similar to what normal marks do. These are the commands used to mark a block, `Ctrl-m' If a block is currently marked in this window it will unmark it. Otherwise it will either mark the beginning or end of the block depending on whether or not a block has previously been partially marked. The normal method for marking a few characters is to first make sure that no block is currently marked (the status line displays the status of the block marks, a `b' means that one end of a block has been marked and a `B' means that both ends of a block are marked in which case it will be highlighted somewhere in the buffer) then press `Ctrl-m' at one end, move the cursor to the opposite end and press `Ctrl-m' again. `Meta-m' Set the beginning of the block to the current cursor position. `Meta-M' Set the end of the block. `Ctrl-x h' Mark the whole of the buffer. `ESC @' Mark the current word. `ESC h' Mark the current paragraph. `Ctrl-SPC' Mark from the position of the auto-mark to the cursor. Another method for marking a block is to use the mouse, double clicking the left mouse button on a character has the same effect as moving to that character and typing `Ctrl-m'. Similarly, clicking the left mouse button while pressing the SHIFT key clears a marked block. File: jade.info, Node: Commands on Blocks, Next: Rectangular Blocks, Prev: Marking Blocks, Up: Using Blocks Commands on Blocks ------------------ `Ctrl-i' Inserts the block marked in this window, at the cursor position, then unmarks the block. `Ctrl-w' Copies the contents of the marked block to the standard clipboard and then deletes the block. `ESC w' Copies the marked block to the standard clipboard, then unmarks the block. This is a less destructive version of `Ctrl-w'. `Ctrl-z' Deletes the text in the currently marked block. `Ctrl-x Ctrl-l' Makes all alpha characters in the current block lower case. `Ctrl-x Ctrl-u' Makes all characters in the block upper case. File: jade.info, Node: Rectangular Blocks, Prev: Commands on Blocks, Up: Using Blocks Rectangular Blocks ------------------ Normally blocks are thought of sequentially from their first to last characters, this does not have to be so. It is also possible to mark rectangles, the block marks being thought of as the opposite corners of the rectangle. `Ctrl-M' Toggle between marking sequential and rectangular blocks, each window has its own value for this attribute (ie one window can be marking rectangles while the rest don't). `Ctrl-Y' Similar to `Ctrl-y' except that the string inserted is treated as a rectangle -- newline characters don't get inserted, instead the next line is inserted in the next line in the buffer at the same column as that inserted into the previous line. For more details see the function `insert-rect'. At present there is a problem with changing the case of a rectangular block with `Ctrl-x Ctrl-l' or `Ctrl-x Ctrl-u', they treat it as a sequential block. This will be fixed soon. File: jade.info, Node: Searching and Replacing, Next: Editing Modes, Prev: Using Blocks, Up: Using Jade Searching and Replacing ======================= It is very easy to search any of jade's buffers for a specific string, the standard search command will search the current buffer for a specified regular expression. Once you have found an occurrence of the string you are looking for it is then possible to replace it with something else. * Menu: * Regular Expressions:: The syntax of regular expressions * Commands for Searching:: How to search for regexps * Commands for Replacing:: Replacing found regexps File: jade.info, Node: Regular Expressions, Next: Commands for Searching, Up: Searching and Replacing Regular Expressions ------------------- Jade uses the regexp(3) package by Henry Spencer, with some modifications that I have added. It comes with this heading: Copyright (c) 1986 by University of Toronto. Written by Henry Spencer. Not derived from licensed software. Permission is granted to anyone to use this software for any purpose on any computer system, and to redistribute it freely, subject to the following restrictions: 1. The author is not responsible for the consequences of use of this software, no matter how awful, even if they arise from defects in it. 2. The origin of this software must not be misrepresented, either by explicit claim or by omission. 3. Altered versions must be plainly marked as such, and must not be misrepresented as being the original software. The syntax of a regular expression (or regexp) is as follows (this is quoted from the regexp(3) manual page): A regular expression is zero or more "branches", separated by `|'. It matches anything that matches one of the branches. A branch is zero or more "pieces", concatenated. It matches a match for the first, followed by a match for the second, etc. A piece is an "atom" possibly followed by `*', `+', or `?'. An atom followed by `*' matches a sequence of 0 or more matches of the atom. An atom followed by `+' matches a sequence of 1 or more matches of the atom. An atom followed by `?' matches a match of the atom, or the null string. An atom is a regular expression in parentheses (matching a match for the regular expression), a "range" (see below), `.' (matching any single character), `^' (matching the null string at the beginning of the input string), `$' (matching the null string at the end of the input string), a `\' followed by a single character (matching that character), or a single character with no other significance (matching that character). A "range" is a sequence of characters enclosed in `[]'. It normally matches any single character from the sequence. If the sequence begins with `^', it matches any single character *not* from the rest of the sequence. If two characters in the sequence are separated by `-', this is shorthand for the full list of ASCII characters between them (e.g. `[0-9]' matches any decimal digit). To include a literal `]' in the sequence, make it the first character (following a possible `^'). To include a literal `-', make it the first or last character. Some example legal regular expressions could be: `ab*a+b' Matches an `a' followed by zero or more `b' characters, followed by one or more `a' characters, followed by a `b'. For example, `aaab', `abbbab', etc... `(one|two)_three' Matches `one_three' or `two_three'. `^cmd_[0-9]+' Matches `cmd_' followed by one or more digits, it must start at the beginning of the line. As well as being matched against, regexps also provide a means of "remembering" portions of the string that they match. The first 9 parenthesised expressions and the whole string that matched are recorded so that they can be used later. The main use for this is in the command to replace a previously found regexp (`ESC p') and the Lisp functions `regexp-expand', `regexp-expand-line' and `replace-regexp'. The string which is given as the template (ie, the string that replaces the matched string) is expanded inserting these recorded strings where asked to. Each occurrence of `\C' in the template is a candidate for expansion. C can be one of: Replaces the whole substring matched by the regular expression. `1' to `9' The numbered parenthesised expression. The character `\'. For example, if a regexp of `:([0-9]+):' matches a line `foo:123:bar', the expansion template `x_\1' would produce `x_123'.