0707070000020101571006660001460001440000011022270355716530200000500000000004Size500 0707070000020102111007770001460001440000011007240366732312500001000000001703Install# Emacsdocs Install Script NAME=EMACS FOLDER=/u/$LOGNAME/Filecabinet/DOCS if [ -d $FOLDER ] then message -i "A new folder called $NAME will be created in your Filecabinet/DOCS folder. The document you are installing will be placed there.\n\nTouch to continue." else message -i "A folder called DOCS is being created in your Filecabinet. A folder called DOCS/$NAME will then be created to hold the document you are installing.\n\nTouch to continue." mkdir $FOLDER chown $LOGNAME $FOLDER fi DEST=${FOLDER}/$NAME if [ ! -d $DEST ] then mkdir $DEST chown $LOGNAME $DEST fi chown $LOGNAME * for i in EMACS.MODS EMACS.UNIX.PC dired.man emacs.man emacs.tm emacs_vt.mm macro.mm recent_changes term_support do ln $i ${DEST}/$i done cat README echo "\n ........ Touch Enter to continue .....\c" read xyzzy message -i "If you want to order the actual EMACS executable, order the package [7mEMACS[0m from THE STORE!\n\nTouch Enter to continue." 0707070000020012411006660001460001440000010555640366732420600000500000000070NameEMACS Documents version 4.6d and 4.7c - from THE STORE! 0707070000020001201007770001460001440000011012570366732430600000700000000060Removerm -rf $HOME/Filecabinet/DOCS/EMACS 2>/dev/null 0707070000020104201006660001460001440000010637410366732353200000600000000301Files./Size ./Install ./Name ./Remove ./Files ./dired.man ./emacs.man ./emacs.tm ./emacs_vt.mm ./macro.mm ./recent_changes ./term_support ./EMACS.MODS ./README ./MAKEcpio ./MAKEflop ./EMACS.UNIX.PC 0707070000020102101006660001460001440000011012620355555305500001200000004141dired.man.ds Tm \ \ .TH dired 1 local .SH NAME dired - interactive directory editor .SH SYNOPSIS .nf dired [file] .SH DESCRIPTION .ad b .fi Dired is a variant of emacs that allows a user to view the contents of a directory and selectively delete files, edit the mode of files, or edit the owner and group of files. A "ls -l" listing of the directory is displayed on the screen, and emacs commands for searching and cursor movement can be used to move around in the display. The following commands can be used to mark or unmark files for deletion: .nf .sp ^?, ^H: Mark the current file for deletion D, D: Same as above if cursor is at beginning of line U, u: Unmark the current file. (cursor at beginnning of line) e: Invoke emacs emacs on the current file or dired on the current directory .fi .sp Ordinary emacs editing commands can be used to modify the owner, group, and mode fields of the display. You are put in overwrite mode, so that as you type over a field, the characters you type replace what is there. DIRED will mark files whose modes have been modified with 'M', and files with modified owner with 'O'. Once marked, a file stays marked. You can cause DIRED to ignore a change by overwriting the 'M' or 'O'. .PP When you exit, a list of marked files will be displayed, and you will be asked whether or not they are OK for editing. Next to each file will appear a 'D' if the file is to be deleted, 'O' if the owner and group are being modified, or 'M' if the mode is being modified. If you type 'y', the files will be edited. Typing anything else returns you to the buffer display. .PP Most of the usual emacs commands work with the anticipated results. In particular, you can use ^X^B, ^X^F, ^X^R, ^X^S, ^X^W, ^X2, ^X1, and ^X^O in order to control editing of several directories with dired. .SH ENVIRONMENT The environment variable TERM if set is used to determine the terminal type. .ne 5 .SH FILES .nf /n1/warren/emacs/helpfile /n1/warren/emacs/errfile .fi .SH SEE ALSO emacs (1), .I An Interactive Screen Editor for UNIX, by Warren Montgomery TM-5343-80-2 (Updated copy maintained online in /n1/warren/emacs/emacs.xopr), 0707070000020101411006660001460001440000011012650355555305600001200000005113emacs.man.ds Tm \ \ .TH emacs 1 local .SH NAME emacs - interactive screen editor .SH SYNOPSIS .nf emacs [file] .SH DESCRIPTION .ad b .fi Emacs is an interactive screen editor which can be used to construct and edit files on UNIX. A window of text from the file being edited is displayed on the terminal screen, along with a status line describing the editor version and file being edited. Ordinary characters typed are inserted in the file, while escape sequences and control characters are used to invoke editing functions. Several files can be edited at the same time in different editing buffers, and two of the active buffers can be displayed on the same screen. .PP Emacs can be customized by the user through user defined macro commands, which can re-define the effect of the basic editing commands. Emacs has a number of built in editing modes that customize some of the commands to support editing of particular types of files, such as C source programs or word processing source documents. .PP There are a number of self-help features in emacs to aid in learning how to use the editor. Complete documentation appears in: .sp .ti +10 An Interactive Screen Editor for Unix .br and .ti +10 Writing macros for EMACS. .PP Emacs supports editiing on most of the commonly commonly used dislay terminals including vt100, vt52, adm (adm3a), adm31, soroc (iq 120), and hp (hp 2621a). The terminal type can be entered when emacs is envoked, or set in the environment variable TERM. If you have a hardwired port to the NSS unix system, you can set TERM automatically by putting the lines: .sp TERM=`ttype` .br export $TERM .sp in your .profile .PP If a file name is given in the command line, emacs starts with that file in the buffer Main; otherwise emacs starts with an empty buffer. .SH ENVIRONMENT The environment variable TERM if set is used to determine the terminal type. .ne 5 .SH FILES .nf $HOME/.emacs_init /n1/warren/emacs/helpfile /n1/warren/emacs/errfile .fi The file .emacs_init, if present, contains a standard set of initializations to be made when you start emacs. The characters in the file will be interpreted as if you had entered them from your terminal. The most common application of this is to set modes different from the default modes. .PP The other two files contain the help descriptions and the error messages used by emacs. .SH SEE ALSO dired (1), .I An Interactive Screen Editor for UNIX, by Warren Montgomery TM-5343-80-2 (Updated copy maintained online in /n1/warren/emacs/emacs.xopr), .I Writing Macros for EMACS, by Warren Montgomery (Updated copy maintained online in /n1/warren/emacs/macro.xopr), 0707070000020101251006660001460001440000011012700355555306000001100000221773emacs.tm.tr ~ .\" EMACS_MODES: fill !c .TL 49358-003 40309-300 An Interactive Screen Editor for UNIX .AU "Warren Montgomery" WAM IH 5343 2494 6E-314 80-5343-2 .TM 80-5343-2 .SA 1 .NR Pt 0 .AS 1 High speed data communication and display screen terminals make possible a fundamentally different mode of entering and editing text to a computer system. An interactive screen editor allows a user to enter and edit files, and to see the effects of the editing immediately. .P A good screen editor can improve productivity in several ways. The need for paper listings, and thus the expense and delay in dealing with them, is greatly reduced with the availability of a screen editor. The editor can provide a customized environment for particular tasks, such as editing program source or word processing, which can relieve the user of the mechanical parts of the task (such as maintaining proper indentation). The immediate feedback provided reduces mistakes, and speeds up their detection. A simple set of editing commands can be used effectively by relatively unskilled users, because of the feedback obtained by seeing the effects of editing. .P This memorandum describes an interactive screen editor for UNIX known as EMACS. The editor is patterned after a very popular screen editor originally developed at the Artificial Intelligence Laboratory M.I.T. It was developed by the author as a tool for his own work and is currently used by a large number of users in Bell Laboratories. Emacs is available through the experimental tools facility at Indian Hill, and is supported on most of the computer center administered unix systems in other locations. The editor provides a friendly editing environment with the advantages outlined above, while running in the small address space provided to the UNIX user on the PDP 11/70. This memorandum describes the commands and editing environment of EMACS, and some experience with its use. .AE .MT 1 .H 1 "INTRODUCTION" Text editing is the most common task of many computer users. The creation and modification of programs, data bases, and memoranda occupies much of the time that a user spends with a computer system. The ability to edit programs and recompile them was one of the primary reasons for the success of early time-sharing systems over batch processing systems. .P Many of the text editing tools now in use are based on the editors for the early timesharing systems. These editors were developed for an environment that included mostly low-speed (110 baud) printing terminals, and expensive computer systems that were not prepared to interact with the user on a character at a time basis. In such a environment, it was appropriate to minimize the amount of output produced by the editor, and to allow the user to specify a lot of changes to be made by a single editor "command". Editors such as the standard UNIX editor (ed) are ideal for this environment. .P In recent years, printing terminals have been repaced by display terminals capable of handling high data rates in many applications. The cost of computing has steadily dropped. The text editing tools made available to users must evolve to take advantage of these changes. With a high-speed display terminal, minimizing output is no longer appropriate. Instead, the display can be used to provide feedback for the user on the results of editing. The lower cost of computing, and better hardware support for terminals, make character at a time interaction with the computing system feasible. The EMACS editor described in this report is one attempt to take advantage of these effects in order to provide the user with a simple and powerful editing environment. .P EMACS is a screen editor that can be used to build or to edit files using a display terminal, such as an ADM3A or SOROC. The user interface to this editor is quite simple. The user is presented with a display of the contents of a portion of the buffer being edited. This display indicates _e_x_a_c_t_l_y what is in the area being displayed, including any non-printing characters. The contents of the buffer being edited can be read from or written to a UNIX file. Characters typed by the user will be inserted into the buffer (and reflected in the display) at the point indicated by the terminal's cursor. This is the primary mechanism for entering and modifying text. .P Control characters and escape sequences can be used to perform other editing functions, such as moving the cursor to a different position in the buffer, deleting text, replacing text, or searching. Thus there is only one mode of interpretation of characters typed to EMACS, in which either text to be entered or commands can be entered. This simple interface relieves the user of the need to remember what mode he is in, and prevents the disastrous mistakes that can occur when text to be inserted is evaluated as an editor command. A simple mechanism is provided to allow a user to insert control and escape characters when needed. .P Although there is a rich vocabulary of commands available, including commands that perform functions tailored to a particular application (such as indenting a C program), the most common way in which EMACS is used to edit is simply to position the cursor over the area to be changed, and enter the changes. The immediate feedback provided by the visual display appears to be very important to the user. .P This editor was written by the author as an aide to his other work, and patterned after the EMACS editor written for the PDP-10 systems at the M.I.T. Artificial Intelligence Laboratory. The interface to the user closely follows that provided by the M.I.T. version, because the author was familiar with that version. The implementation of EMACS for UNIX described in this report was done by the author, and is entirely different from that used at M.I.T. The author was not familiar with the implementation techniques used in the M.I.T. version, only with the language in which EMACS was implemented. .P The author and his organization are not supporting EMACS. The author is, however, willing to distribute copies of the software for use within Bell Laboratories, and is interested in comments regarding features or problems with EMACS. The author will repair problems as time allows, but makes no guarantees to fix problems promptly. .P The remainder of this report contains a user's manual for the EMACS editor, and a discussion of the experience that we have had with EMACS in our department. EMACS continues to evolve to provide more commands and remove implementation restrictions. The users manual here describes EMACS version 4.6, which was in use in October, 1983. .P The display screen contains a window of approximately 20 lines into the buffer being edited. The terminal cursor is positioned at the point where the editor cursor is in the buffer. Each line of the buffer (delimited by a newline character) begins at the beginning of a display line. A line that exceeds the screen width is continued on the next screen line. Whenever a line must be continued on the next screen line an exclamation mark (!) is displayed in the last column of the first screen line. If the editor is in line number (lnumb) mode, then a line number is printed at the beginning of each line in the buffer. .P Printable characters are displayed normally, while tabs are displayed as white space up to the next screen column that is a multiple of eight. Each non-printing control character is displayed as a two character sequence of '^' followed by the control character + 100 octal. This causes a control-x to display as '^X'. This mapping produces a reasonable display for most of the control characters. There are several other non-printing characters for which the character displayed is not obvious. Rubout displays as ^?. The "us" character (037) displays as ^_. The "rs" character (036) displays as ^^. The "gs" character (035) displays as ^]. The "fs" character (034) displays as ^\e, and the escape character (033) displays as ^[. A character which has the high order bit set (0200 octal) is displayed with an M- in front of it. This bit is normally not set in ASCII characters. .P In addition to the display buffer, several lines of the screen are used for status information and for displaying parameters entered into EMACS, such a file name. One of these lines known as the status line contains the editor name, editor version, buffer number and name, and file name. Some of the more recently introduced commands described in this document indicate the version in which they were introduced, so that you can determine whether or not a particular command is in the version that you are running. If the buffer has not been modified since the file was read or written, an '=' will be displayed between the buffer and file names. Otherwise, a '>' will appear. .P The lines below the status line are used for the time of day display (if time mode is on), and for emacs to prompt for parameters for commands. Some commands cause the buffer display to be erased in order to display other information in place of the buffer. The word "Continue?" will be displayed at the bottom of the screen when this happens. Typing 'y', ' ', or return will bring back the buffer display. Typing 'n' may allow you to re execute the command producing the display. .P Figure 1 shows a typical screen during a EMACS session. The buffer "Main", number 0, is being used to edit a program test.c. The buffer has been modified since the last write to the file test.c. .DF .ce Figure 1 EMACS screen Display .SP 2 1 #include 2 /* EMACS_MODES: c, !fill, comcol=43 */ 3 4 5 /* This is a c program */ 6 7 main() 8 { 9 int i; 10 char c; 11 12 for (i = 0;i > 0; i++) { 13 printf("i = %d\en",i); /* print i */ 14 } 15 } 16 EMACS 2.8 (0) Main > test.c .DE .H 1 "EDITING WITH EMACS" As noted above, when the buffer is displayed by EMACS, one can enter characters into the buffer being edited simply by typing them on the keyboard. Editing functions use control characters or escape sequences. This section provides a brief description of the basic editing commands available, and the way in which they are invoked. .H 2 "The Character Set" EMACS operates on characters from an alphabet of 256 different characters. These include the 128 ASCII characters that can be entered from a terminal, and 128 "Meta" characters. A Meta character is entered by preceding it with an escape (ESC key). In this document, and in characters displayed by EMACS, control characters are represented as a character preceded by '^', and Meta characters are represented as a character preceded by 'M-'. Thus the character 'M-a' (Meta a) can be entered by hitting the ESC key, followed by the a key. The character '^X' is the character obtained by hitting the control key and the x key. .P Each character that is typed into EMACS is interpreted as a command. All of the ordinary printing characters insert themselves into the buffer being edited at the point defined by the cursor. Thus in order to enter text, simply type it. The control and meta characters are used for editing commands that manipulate the text in the buffer, or move the cursor, or both. .H 2 "Arguments and Parameters" All commands, including the printing characters, take a numeric argument that has some effect on their interpretation. The default argument given to a command for which no argument is specified is 1. To specify some other argument to a command, you can enter escape, followed by a sequence of digits, and then the command. If a '-' precedes the sequence of digits, a negative argument is given Numbers starting with a 0 are interpreted as octal, while numbers starting with any other digit are decimal. A second way of specifying the argument is to precede the command by one or more ^U (control-u) characters. Each ^U multiplies the value of the argument by 4. .P For most commands, the effect of the argument is to multiply the number of times that the command is applied. Thus the sequence ^U^Ux inserts 16 x's into the buffer at the current location. The sequence ESC13^N moves forward 13 lines in the buffer. .P In addition to the numeric argument given to all commands, some commands will prompt the user for additional character string parameters. The commands that take parameters, and the method of entering parameters are described in the section on file and buffer commands. .H 2 "Simple cursor movement commands" There are many ways to move the cursor around in the buffer without modifying the text in the buffer. Most of these use their argument to specify how many times the movement is to be repeated. These commands include: .VL 10 .LI "^F" Move forward one character. On reaching the end of a line, the cursor moves to the first position of the next line. .LI "^B" Move backward one character. On reaching the beginning of a line, the cursor moves to the end of the previous line. .LI "^N" Move down one line. The cursor is moved to the same character position in the next higher number line in the buffer. Note that if the buffer contains tab or control characters, the same character position in the lines in the buffer may display at different points in the screen. .LI "^P" Move up one line. The cursor is moved to the same character position in the next lower number line number in the buffer. .LI "^A" Move to the beginning of the current line of the buffer. Note that both this and the following command work on the current line in the buffer, which may be displayed on two or more screen lines if it is too long to fit on one screen line. .LI "^E" Move to the end of the current line. .LI "M-<" Move the cursor to the beginning of the buffer. .LI "M->" Move the cursor to the end of the buffer. .LI "M-f" Move the cursor forward one word. Note that words are delimited by non- alphabetic or non-numeric characters. .LI "M-b" Move the cursor backward one word. .LI "M-g" Move the cursor to the line number specified by the argument given to the command. .LI "^V" Move to next page. The cursor is moved forward so that a new window, beginning with the first line not currently displayed, will be displayed. .LI "M-v" Move to previous page. .LE .H 2 "Inserting 'odd' characters" Because EMACS uses control and escape characters for commands, you cannot directly insert them into the buffer by typing them. The following three commands are useful for the occasional need to get such characters into a buffer. .VL 10 .LI "^Q" Quote the next character(s). ^Q accepts one or more characters (the number of characters specified by its argument) from the terminal and inserts them "blindly" into the buffer without interpretation. Only the newline (line feed) character is interpreted. EMACS strips the parity bit from all characters read from the terminal, so all characters inserted this way have zero parity. .LI "M-q" Quote characters and turn on parity bit. This acts just like ^Q, however it turns on the parity bit in the character before inserting. Characters inserted this way will be displayed as meta characters by EMACS. .LI "M-\e" Convert the argument to a character. This command takes its argument and converts it to a character and inserts it. This provides an easy way to convert from octal or decimal to ASCII, and is occasionally useful for creating "funny" character strings. .LE .H 2 "Text Deleting commands" Several commands are available to delete text from the buffer. All of these commands operate on text near the current cursor position. The deletion commands are: .VL 10 .LI "^?" (rubout) Delete the character before the cursor. The character before the cursor usually the last character typed. A rubout deletes it. .LI "^H" (backspace) Backspace is a synonym for rubout, also deleting the previous character. .LI "^D" Delete the character under the cursor. If a newline is deleted (rubout at the beginning of the line or ^D at the end), lines are joined. .LI "^K" Delete to the end of this line. If invoked without an argument, ^K deletes the remaining text on this line (if any). If no text follows the cursor on the current line, ^K deletes the newline. With an argument of 0, ^K deletes all text on the current line up to the cursor position. With an argument of n greater than zero, it deletes n lines forward from the cursor position. The text from the cursor up to and including the nth newline is deleted. With an argument less than zero, the deletion is backwards from the cursor position. .LI "M-~" (Meta space) The command Meta space or ^@ (control @) places an invisible mark on the current cursor position. This mark can be used in subsequent editing. EMACS maintains 12 marks, one for each buffer. If an argument is specified to this or to other commands that use marks, it is used to select which mark to use. If no argument is given, the buffer number is used to select a mark. Thus ordinarily, EMACS acts is if there is one mark in each buffer, however you can use as many as 12 marks in a single buffer by explicitly specifying which mark to use. Each mark is simply a position in the buffer (line number and character within the line.) Thus if you add or delete text in front of a position where a mark was placed, the mark may not remain on the same character, but stays on the same position. .LI "^W" The command '^W' deletes the text between the current cursor position and the mark. This is a convenient way to delete a well defined block of text. If an argument is specified, it is used to select the mark number The mark can be either before or after the cursor position and achieve the same effect. .LI "M-^?" (Meta rubout). This command deletes the previous word of text. The definition of a word is the same as for M-f and M-b .LI "M-d" This command deletes the next word of text. .LE .H 2 "File and buffer Commands" Most of the file accessing commands are invoked through the ^X command. ^X is a prefix for several useful commands, most of which involve file or buffer access. These commands are invoked by a ^X followed by a second character. .P Many of these commands prompt for parameters, such as a buffer name or file name. With all of these commands, you can enter text, just like you enter it into a buffer. Rubout (or backspace) deletes the last character entered and @ or ^K deletes the entire entry and lets you start over again. ^Y enters the current file name (sometimes useful), and ^X enters the current line from the buffer. ^G aborts the command without doing anything. Escape, newline or return terminate the parameter being entered. Environment variables, such as $HOME, that appear in file names are expanded. Thus the file name $HOME/.profile will resolve to your .profile file. Other special characters used by the shell in expanding command lines can also be used, although they are somewhat slow to execute. Thus giving "`logdir warren`/.pro*" to ^X^R will read in the .profile file (provided that it is the only file starting with .pro) for user warren. When the expansion produces more than one name, only the first name is used by emacs. Environment variables and shell special characters are not interpreted in parameters used for other purposes, such as buffer names, command lines, or search strings. .VL 10 .LI "^X^R" Read file. EMACS will prompt for a file name, which you enter as described above. When the file name for ^X^R has been entered, EMACS will read the specified file into the buffer. If you invoke ^X^R with an argument of one (the default argument), it clears the buffer before reading. If you invoke ^X^R with an argument that is not 1 (i.e. ^U^X^R) it inserts the file into the buffer at the current cursor position. If the cursor is in the middle of a line, reading will be much slower, so it is best to open up a blank line when reading a file into the middle of a buffer, and then delete any unwanted lines after the file is read. If ^X^R is invoked with a negative argument, no error message is produced if the specified file cannot be read. .LI "^X^W" Write file. Prompting for file name is as above. If the specified file exists and has two or more links to it, EMACS will ask whether to overwrite the existing copy of the file or to unlink the specified file name and create a new file to write to, leaving any other names that were previously linked to the specified file unchanged. If emacs fails or the unix system crashes during an attempted write (either ^X^W or ^X^S), the previous contents of the file are saved in a file .EMACS in your current working directory. Passing an argument to ^X^W (i.e. ^U^X^W) causes the contents of the current buffer to be appended to the specified file rather than replacing it. .LI "^X^S" Save file. This writes out the buffer to the last file read or written if the file has been modified. .LI "^X^B" Change buffer. EMACS allows up to 12 named buffers to be edited concurrently. '^X^B' prompts for the name of a buffer, and makes that buffer the current buffer. If the buffer name "..." is entered, a new, empty buffer with a unique name is created. If a null buffer name is given (just type newline when asked for buffer name) a list of the active buffers is displayed. Typing 'n' in response will cause EMACS to ask for the buffer name again, while typing anything else will return you to the buffer display. All commands that ask for a buffer name will also accept a buffer number. The buffer number is displayed in parentheses next to the buffer name on the status line. .LI "^X^F" Find file. This command prompts for a file name and switches to a buffer that holds the specified file. If the specified file has been read into a buffer, the effect of find file is to change to that buffer. If no buffer holds the specified file, the effect of find file is to create a new buffer and read the specified file into it. Find file is a convenient way to switch between editing several files. If ^X^F is invoked with a negative argument, no error message is produced if the specified file cannot be found. .LI "^X^K" Kill Buffer. This command prompts for a buffer name and destroys the specified buffer. You can delete any buffer except for a buffer currently being displayed. .LI "^X^X" Exchange the cursor position and the mark. An argument can be specified to indicate the mark to exchange with. .LI "^X^I" Re-direct input. This command directs EMACS to take input from a file. The file is assumed to contain EMACS commands, and can be created by editing with EMACS, using ^Q to enter control and escape characters. One use for this command is to perform a series of commands on the current buffer, or to set up a standard set of modes. Note that if the file contains only printable ASCII text, tabs, and newlines, ^X^I will effectively read the file into the buffer at the current location. Note, however, that this is very slow, and much better done with ^X^R. Just like ^X^R, if ^X^I is passed a negative argument, no error is printed if the input file is non-existent. ^X^I returns as its result 1 if the input file was found and successfully executed and 0 otherwise. .LI "^X( Begin Keyboard Macro. This command starts remembering the keystrokes you enter so that they can later be executed as a keyboard macro. .LI "^X) End Keyboard Macro. This command stops remembering keystrokes for a keyboard macro. .LI "^XE Execute Keyboard Macro. This command retrieves and executes the keystrokes typed between ^X( and ^X). Emacs executes them just like they came from your terminal. Keyboard macros are saved in the file .emacs_kbd in your home directory. These are saved between sessions, so that ^XE is in fact the same as invoking ^X^I (Input file) and giving $HOME/.emacs_kbd as the file name to execute. .LI "^X^C" Quit Emacs. If any buffers have been modified since the last write, EMACS will ask whether or not to write out each such buffer before exiting. EMACS will not ask whether or not to save an empty buffer. .LI "^Z" Quit Emacs. In most circumstances, ^Z and ^X^C are identical. If you are using macros that invoke the recursive edit command to allow editing in the middle of a macro execution, ^Z entered during the recursive edit returns to the macro, while ^X^C tries to exit emacs immediately. See the macro programming document for more details. .LI "^X^T" Send text to another buffer. This command sends the text between the mark and the current cursor position in the current buffer to another buffer. EMACS prompts for the name of the other buffer, and the text is inserted into that buffer at the current cursor position for that buffer. The current buffer remains unchanged. If an argument is given, it selects the mark to use. .LE .H 2 "Miscellaneous commands" The above set of commands are sufficient to do a substantial amount of editing quite easily. Here are more commands for special situations. .VL 10 .LI "^G" Abort. Typing ^G at any point that emacs is asking for input (except ^Q and M-q) will abort the current command. This applies at any step (specifying arguments, typing escape, entering parameters that emacs asks for, etc.). This is a convenient way of aborting anything that you are not sure that you want to complete (or how you got there). .LI "^X2" Enter Two window mode. In two window mode, the screen is split in half vertically, and each half displays a different buffer. One window is current, as indicated by the cursor position and the file name on the status line, and one window is dormant, and continues to display the text last put there. Two window mode is a good way to keep a display of something like an include file containing definitions handy while editing another file. ^X2 will prompt for the name of the buffer to display in the second window, and move to that window. Once in two window mode, the buffer displayed in the current window can be changed by any of the buffer switching commands. You can have two windows on one buffer, but only one is "active", so that changes made are only reflected in the active window. Text in the dormant window is wiped out by any command that re-writes the screen with something other than the buffer, such as M-?. .LI "^X^^" Grow window. Makes the current window grow by the number of lines specified by the argument to ^X^^. This command works only when you are in two window mode. You can use a negative argument to cause the current window to shrink. .LI "^X1" Enter one window mode. Return to one window mode from two window mode .LI "^X^O" Switch windows. Make the dormant window current and the current window dormant. .LI "^X=" Status. Displays status information (current line, number of lines in buffer, current character position, number of characters in buffer, etc.). .LI "^Y" Insert last killed text. All text that is deleted is saved in a "kill stack". The kill stack can hold the last 8 deletions. There is also a limit on the total amount of text that can be held in the kill stack, but you are unlikely to encounter it. ^Y retrieves the most recently deleted text. The most frequent use of this command is in moving text around. The procedure is: kill the text to be moved, move the cursor to where you want it, and enter ^Y. Another use of ^Y is to undo an unwanted deletion. ^Y leaves the mark (the one corresponding to the buffer number) at the beginning of the inserted text, and puts the cursor at the end. Both ^Y and M-y work much faster if the cursor is on a blank line. Thus if you are moving or retrieving lots of text, it is best to open up a blank line to do the retrieve to, and then delete any unwanted text when done. .LI "M-y" Replace last retrieved text. This command kills the text between the cursor and the mark corresponding to the buffer number, and replaces it with the next to last item on the kill stack. This command only really makes sense when it is issued immediately after ^Y, where it can be used to change the text that has just been retrieved. By entering ^Y followed by some number of M-y's, any text in the kill stack can be retrieved. .LI "M-p" Pickup the region of text. This command picks up the text between the current position and the mark and puts it in the kill stack, without changing the buffer. This is useful for duplicating blocks of text in the buffer. An argument can be used to specify which mark to use .LI "^O" Open up a line. This command creates one or more empty lines at the current cursor position. This is useful for inserting text in the middle of the buffer, while minimizing the amount of screen refresh needed. .LI "^T" Transpose the next two characters. .LI "^S" Incremental search. EMACS will prompt for a search string and as the search string is entered, begin searching for the next occurrence. At any point, the cursor sits at the beginning of the text that was found, and the search string is displayed at the bottom of the screen. Rubout can be used to delete the last character in the search string. If no match is found, the terminal bell rings. A message indicating the failure is typed as the prompt. Entering ^S in place of another search character causes the search to proceed to the next occurrence of the search string. Entering ^R cause the search to proceed backwards. Entering either ^R or ^S with a null search string causes the last search string (from the last search) to be retrieved. Entering ^G quits the search and returns the cursor to its previous position. Entering ESC stops the search, leaving the cursor where the search took it. Entering any control character stops the search, and then interprets the command specified by the control character. In all searches, the eighth bit (parity or meta bit) on characters in the buffers is ignored, and if caseless mode is set, lower case characters in the search string match either case in the buffer. .LI "^R" Reverse search --, like above, only starts backward. .LI "M-R" Query replace. You will be prompted for a From string and a To string. Each can be edited as the filenames above. In the To string, the '&' character can be used to designate replacement with the From string. To get a real '&', prefix it with a '\e'. To get a real '\e', prefix it with another '\e'. EMACS then searches for the from string and positions the cursor in front of it. You can control the replacement of the item in question by what you type: .VL 15 .LI "'~' or 'y'" Replace this occurance and move on to the next one. .LI "'n' or (rubbout)" Skip thiss occurance and move on to the next. .LI "'.'" Replace this occurance and exit query replace. .LI "^G^" Quit. (Exit query replace without replacing the current match.) .LI "b" Go back to the previous occurance of the "To" string. It won't find one that you have already replaced! .LI "r" Replace the rest without stopping to ask after each, and show the result of the replacement after each. .LI "R" Replace the rest silently. (i.e. don't show the result after each replacement.) .LI " (Version 4.6)" Causes emacs to ask for a new string to replace the search string with. The current occurance will be replaced with what you type, and emacs will go on to the next occurance. .LE Query replace stops when the from string is no longer matched. '?' prints a summary of the options. .LI "M-^S" Regular Expression Search (Version 2.1) This will prompt for a regular expression to search for. You can edit the expression like editing filenames. The syntax is standard UNIX regular expression syntax. In addition to all of the special characters used by ed in regular expressions, the two sequences "\e<" and "\e>" can be used to match the beginning and end of words. Thus the string \e will match any occurrence of the word "the", but not any word containing the sequence of letters "the", such as "other". .P Note that to put control characters into a search expression, you must quote them with ^Q. Characters that are special in regular expressions, such as *, can be proceeded with \e to make them non-special. You can search forward or backward, either ending at the beginning or end of buffer, or wrapping around (like ed) depending on the argument given to the search command. With a positive argument, the search is forward, while a negative argument searches backwards. An argument of 1 or -1 causes the search to wrap, failing only if there is no occurrence of the expression in the buffer. Any other argument causes the search to stop at the beginning or end of file. Entering ^S or ^R immediately following a regular expression search will find the next or previous occurrence of the expression. Searching for expressions that span line boundaries will not work. .LI "M-^R" Regular expression query replace (Version 2.1) This is just like query replace, except that a regular expression is allowed in the search string. You may also use the special character sequence \en, where n is a digit, to specify that the characters matched by the nth subexpression (delimited by \e( and \e)) are to be used in the replacement string. .LI M-/ Begin comment. This command begins a C program comment by moving to the appropriate column and putting a /* in the buffer. The next newline will close the comment and automatically append a */ .LI "M-!" Unix escape. Prompts for and executes a unix command line. If this command is given an argument (i.e. ^UM-!), it passes the contents of the current buffer to the command as standard input. .LI "M-$" Unix escape. This works just like the above, except that it also traps all of the standard output from the command executed and saves it in a buffer called .exec as well as sending it to the terminal. If you don't give M-$ an argument, the buffer .exec is cleared first, while if an argument is given (i.e. ^UM-$) the output is appended to whatever was in buffer .exec before. This is useful for saving a copy of the error messages produced by a C compilation of a file being edited, for example. The file name of the .exec buffer is set to the command line that produced it. This can be useful if you want to re-execute the same command, as you can make .exec your current buffer, enter M-$, and enter ^Y followed by newline as the command line. ^Y gets the old command line back, and newline will execute it. .P For both M-$ and M-!, the command to be run is exeucted using your default shell (as set by the $SHELL) environment variable, or /bin/sh otherwise. Starting in version 4.6, the environment variable "filename" will be defined in the environment of the program executed as the name of the file being edited. This facilitates running scripts that process the current file. .LI "M-^M" Mail. This command takes the current buffer as unix mail, and sends it. The buffer must contain at least one line starting To: , which specifies the recipients of the mail. Each recipient is delimited by a space. Any number of recipients may be listed in a single line, however to improve readability, additional To: or Cc: lines may be used in specifying lists of recipients. Any errors encountered by mail are printed. If the environment variable $MAILER is set, then it is taken as the name of the command to run to send the mail. Otherwise, emacs runs "mail". .LI "M-_" Underline word. This command underlines the following word of text. Useful for generating underlined text for mm. .LI "^C" Capitalize. This command capitalizes the letter under the cursor and moves the cursor forward one position. Lower case alphabetic characters are converted to upper case, while other letters are unchanged. .LI "M-c" Capitalize word. The letter under the cursor is capitalized, and the cursor is moved to the beginning of the next word. .LI "M-l (4.6) Lowercase letter. The letter under the cursor is capatilized and the cursor is moved to the right. .tr ~~ .LI "M-~" Unmodify Buffer. This command causes a buffer to be marked as unmodified even if it has been modified since the last write. Doing this will avoid having EMACS ask whether or not to write the buffer when you exit if you know that you do not want to rewrite the buffer. With an argument greater than 1 (i.e. ^UM-~) this command marks the buffer as modified. With an argument of zero or a negative argument, it does not change the state of the buffer but returns the buffer modified flag as its result. .LI "M-a" Beginning of Sentence. This command goes backwards to the beginning of the current sentence. Sentences are delimited by a punctuation mark followed by two spaces or space and newline. .LI "M-e" End of Sentence. Moves to the end of the current sentence. .tr ~ .LI "M-t" set terminal type. Prompts for terminal type and sets the character sequences used to display text to be appropriate for that terminal. Available terminal types include soroc, adm, adm31, vt100 (ANSII mode, 132 columns), vt52 (vt52 or vt100 in vt52 mode), and the hp26xx terminals. A wide variety of other terminals are supported as well. EMACS uses terminal commands for relative and absolute cursor position, clear screen, clear from the cursor to the end of line, insert and delete lines, and insert and delete characters. The number of characters transmitted for re-display will depend on which of these functions are available. Thus EMACS transmits fewer characters on an adm-31, which has all of these functions, than with an adm-3a, which has only cursor positioning and clear screen. Most terminals fall between these extremes. .LI "M-?" Explain. This command prompts for a character and prints a brief explanation of what that character does. .LI "M-w" Wall Chart. This command puts a listing of all commands (including those prefixed by ^X) into the current buffer. This command is a convenient way of producing a "wall chart" of the commands. The list is inserted into the buffer at the current position, so that normally one would want to execute it in an empty buffer. The appendix to this report contains a current copy of the wall chart. .LI "^L" Refresh. refresh the display. Occasionally, some error may cause the display to become garbled. ^L re-creates it from scratch. If you give an argument to ^L, it is used to specify how many lines will appear on the screen before the current line. When invoked with an argument, this command does not re-create the display from scratch. .LI "M-^L" Redisplay top. Redisplay the window with the current line at the top. This is useful for viewing the lines that follow the current line. Note that this does not re-create the entire display, as does ^L, so it will not correct garbling. .LI M-" Auto Fill Buffer. This command re-adjusts the lines in the buffer so that each line contains 72 or fewer characters. The adjustment is done like nroff (mm) by moving words from one line to another. nroff or mm command lines and blank lines are preserved as is. This command can be used to improve the way in which an nroff or mm source file displays, by getting rid of long lines, without affecting the output. .LI "M-:" Remap character (version 3.4). The command M-: allows you to re-map character commands. It prompts for a character (or a meta or ^X sequence) and a command (also a character sequence) to put on that character. This allows you to re-configure EMACS to your liking. .LE .H 2 "Macro Commands (version 3.0)" EMACS provides a facility to allow a user to define his own commands. These "macro commands" provide a way to implement specialized editing functions for particular applications. A macro command is actually a sequence of EMACS editing commands that are invoked in response to a single character entered from the keyboard. Macros can contain ordinary emacs editing commands, invocations of other macro commands, or one of the commands described in this section that are of little use in interactive editing, but are quite useful in macros. .P Because there are a large number of commands related to defining and using macros, and because these are of limited interest to most users, macros are documented in a separate manual. .H 2 "Modes" EMACS has a variety of modes and other parameters that can be changed from commands entered in the terminal. There are two types of modes: on/off modes and integer modes. The '^X^M' command can be used to display or set these parameters. '^X^M' will prompt for the name of the mode to set. If you enter a return in response to the prompt, the current mode settings are displayed. Normally, emacs will display the value of each integer mode, and the name of each on/off mode that is currently on. If you enter return in response to '^U^X^M', emacs will display the names of the on/off modes currently off preceeded by a '!' in addition to the normal display. .P Modes are set by giving the name of the mode to set in response to '^X^M'. If an on/off mode is given, it is turned on if no argument is given to '^X^M', and turns it off if an argument is specified. (Thus '^X^M' turns on, '^U^X^M' turns off). For an integer mode, the mode is set to the value of the argument. The modes and types are listed below, along with their default values. For ON/OFF modes, the default is highlighted. .VL 15 .LI "save" Auto Save Mode (ON/_O_F_F) .br If auto save mode is on, EMACS will automatically write the current buffer after savetype characters have been entered since the last save. This mode reduces the chance of disaster in the event of a crash, but can be annoying by causing a lot of writing. .LI "savetype" Save type ahead (INTEGER=256) .br If auto save mode is on, this is the number of keystrokes between saves. .LI "fill" Auto Fill Mode (_O_N/OFF) .br If this mode is on, emacs will automatically move to the next line whenever the cursor moves to the end of the line, breaking the line at a word boundary. This is very useful for entering text, as no newlines need be entered in the middle of the text. .LI "fillcol" Auto Fill Column (INTEGER=72) .br This is the character position beyond which auto fill mode will cause the line to be broken. .LI "lnumb" Line Number Mode (_O_N/OFF) .br This mode causes the current line number to display at the left of each line. .LI "c" C Mode (ON/_O_F_F) .br This mode automatically indents for a C source file. Each line is indented with the number of tabs in the last non-comment line plus the net excess { characters over } characters in the last line. This mode is particularly useful for entering c program text. .LI "tabstop" Tabstop (INTEGER=8) .br This mode is the number of characters per tab that are displayed. Displaying a deeply indented c program may look much better if tabstop is set to something smaller than the eight default. .LI "comcol" Comment Column (INTEGER=40) .br This is the column in which comments entered via M-/ begin. .LI "backspace" Backspace Mode (ON/_O_F_F). .br Turning on backspace mode causes backspace characters (^H) to display as moving back one column rather than as a ^H. This is very useful for viewing runoff output, or manuals, but editing the resulting text can be a bit tricky, because it is impossible to tell whether the character under the cursor is the one being displayed, or one that has been overprinted, or a backspace. .LI "time" Time mode (ON/_O_F_F) .br When time mode is on, EMACS will display the time of day below the mode line (the one that says EMACS and the buffer name). The time is updated every time a character is read. Using time mode when entering lots of text is expensive. .LI "verbose" Verbose mode (_O_N/OFF) .br When verbose mode is on, EMACS will prompt for more input when ^X, ^Q, escape, or ^U are entered. This makes it easier to keep track of where you are. .LI "overwrite" Overwrite mode (ON/_O_F_F) .br In overwrite mode, text entered will overwrite text already there. Text entered when the cursor is at the end of a line will be inserted as before. Overwrite mode may be more natural for some people when making corrections. .LI "nobell" No Bell (ON/_O_F_F) .br Ordinarily, unexpected conditions, such as errors or quitting out of commands, cause the terminal bell to ring. On some adm3a terminals, This causes some kind of disaster to occur. Turning on nobell mode prevents EMACS from ringing the terminal bell. .LI "keepscroll" scroll keep lines (INTEGER=0) .br This parameter specifies how many lines are to be preserved on the screen when forward page or backward page is invoked. .LI "lnowid" line number width (INTEGER=4) .br This parameter specifies how many character positions are reserved for the line number when in line number mode .LI "height" Display height (INTEGER=) .br This parameter dictates how many lines from the buffer will be displayed on the screen. It is automatically set based on the terminal type whenever the terminal type is set, and is changed by the one and two window commands. This parameter and the width is intented to help accommodate a terminal whose control sequences match one of the available types but has a different size of screen. (i.e. a vt100 with only 80 columns of display). This parameter is also useful for limiting the display on a slow line. .LI "width" Screen Width (INTEGER = ) .br This mode specifies the width of the display screen. See the height mode for possible applications. .LI rigid_newline rigidly insert newlines (ON/_O_F_F). .br This mode causes any newline to insert a newline into the file. With this mode off (the default). a newline will not insert anything if the following line is empty, but will simply move to the next line. .LI "caseless" ignore case in searches .br This mode causes case lower case characters in the search string to match either case in the buffer on all searches and query replace. .LI "mailtype" check mail interval (INT=100) .br This parameter determines the number of input characters between checks of your mailbox ($MAIL). When emacs discovers something in your mailbox, a warning is displayed at the bottom of the screen. .LI "end_newline" Behavior of ^N at end of buffer (ON/_O_F_F) .br This parameter determines whether executing the ^N command in the last line of the buffer adds a new line to the buffer (mode ON) or whether it signals an error (mode OFF). .LI "tspeed" Terminal Speed (INT=) .br This parameter is the speed of your terminal in milliseconds per character. This parameter is set whenever you enter emacs and is used in determining how to update the display most efficiently. .LI "readonly" Read only buffer (ON/OFF___) .br If this mode is turned on, saving the current buffer is disabled. ^X^S will complain with an error message, autosaving will not take place, and emacs will not complain if you try to exit without writing buffers. .LI "usilent" Silent UNIX commands (ON/_O_F_F) .br If set, this parameter causes emacs not to display the command name or output for M-$. This is useful for invoking a unix command in a macro and capturing the output. .LI "display percent (4.5)" Display cursor as percent of buffer (ON/_O_F_F) .br If set, emacs will display the percentage of the current buffer beyond the current cursor position on th mode line .LI "picture (4.5)" Tailor editing for two dimensional displays (ON/_O_F_F) .br If set, emacs treats the buffer as an "electronic blackboard", rather than the exact contents of a unix file. The display shows a rectangular region of the blackboard through a window. Characters beyond the right margin are not displayed, but are indicated by a '!' in the right margin. The window is moved left or right to keep the cursor in the window. If the window is not at the left edge of the blackboard, then the character offset of the left edge of the display is given on the mode line, in front of the editor name. .P Picture mode changes the behavior of several basic commands to be more suitable for two dimensional editing. .VL 10 .LI "^N/^P" These move to the same column in the target line, extending the target line with spaces if necessary. .LI "^F/^B" These will not move off the current line. ^B will stick at the left margin, while ^F will continue to extend the line to move to the request column. .LI "^W/^Y" These treat the region to be deleted as a rectangle, bounded by the mark and the cursor position at the corners. All text in the rectangle defined by these positions is killed by ^W. ^Y brings text back in the same way. All text deleting commands behave like ^W, in that the start and end positions of the text region to be deleted are taken as corners of a rectangle. When the text region being deleted is all on one line, behavior is identical to normal emacs, however deletion accross line boundaries via commands like M-d may not do anything sensible. .LE .P Picture mode is probably most useful with nodelete mode, notabs mode, and overwrite mode all set. Other combinations may not necessarily give the expected results. This mode is intended to edit files containing picture images. The presence of tabs, backspaces, and control characters in the file may cause unexpected behavior. .LI "nodelete" No deletion (ON/_O_F_F) .br With this mode set, text deleted in the file is not closed up but instead is overwritten with spaces. After any deletion, the cursor reverts to the first character of the region deleted. "nodelete" mode should probably be part of overwrite mode, however overwrite mode considerably pre-dated it and was left alone for upward compatibity. .LI "controlify" Controlify mode (ON/_O_F_F) .br When on, this mode causes a particular character (normaly ^\, but settable to another character with the ctl_char described below), to act as a prefix specifying that the next character is to be interpreted as a control character. This mapping takes place at any time, not just when entering commands. Thus the sequence ^X^|s will be mapped into ^X^S, and cause the save command to be invoked. The sequence ^\q^\m typed in response to a request for a file name will be mapped into ^Q^M, which will be interpreted as asking for a file name of ^M. Controlify mode is primarily intended to allow you to enter characters which cannot be sent transparently from your terminal to emacs. The most frequent examples are ^S and ^Q, which cannot be sent by some terminals and some local area networks. By setting controlify mode, you can send these characters with ^\es and ^\eq. .LI "ctl_char (4.6)" Controlify Character (INT=30) .br This parameter sets the value of the character used when in controlify mode to indicate that the next keystroke should be interpreted as a control character. It is the ascii value of the character to be used. .LI "flow_lim (4.6)" Flow Control Limit (INT=0) This parameter enables the use of xon/xoff flow control during output to control the rate of output to the terminal. Emacs normally turns xon/xoff flow control off to allow ^S and ^Q to be passed to emacs to be used in specifying commands. If flow_lim is non-zero, then whenever more than flow_lim characters are sent to the terminal at once, xon/xoff flow control will be temporarily enabled to allow the terminal to send ^S to request that unix stop output. xon/xoff flow control is disabled when output is complete. The only effect you will see is that you cannot type ^S or ^Q ahead while emacs is updating the screen. Normally, emacs supplies sufficient padding to allow it to run without xon/xoff flow control, however for some terminals at high speeds xon/xoff flow control is required. In this case only, set flow_lim to a number somewhat larger than the terminal's character buffer (typically 32, 64, or 128). .LI "eofnl (4.6)" Write newline at eof. (_O_N/OFF) This mode when on causes emacs to append a newline character to any file written by emacs from a buffer that does not end in a newline. Emacs allows you to create files that do not end in newline. Unfortunately, many unix tools get confused when reading such a file. This mode is on by default, and prevents you from writing a file that will cause troubles. For editing files which you do not want to end in a newline, turn this mode off. .LE .P You can specify the modes to be used while editing a particular file by putting the string "EMACS_MODES: " somewhere in the first 10 lines of the file. The text on the same line following EMACS_MODES: will be taken as names of modes to set on or off. A mode name preceded by '!' will be set off, while mode names just listed will be set on. If '=' immediately follows a mode name, then the characters immediately following the '=' will be taken as the value for the mode name. Any text on the line that does not correspond to a mode name will be ignored. Thus the line: .SP /* EMACS_MODES: !fill c, comcol=43 */ .SP in a c source file will set c mode on, fill mode off, and set the column for starting comments to 43. These modes are set whenever the file is read, and whenever you switch buffers. .H 2 "Getting started" When EMACS is invoked, it does a number of things to set up for your editing session, These include finding out the type of your terminal, processing an initialization file that allows you to customize EMACS for your needs, and processing command line arguments. .H 3 "Setting your Terminal Type" Emacs must know what type of terminal terminal that you are using in order to know the appropriate control commands to display text on your screen. The terminal type is taken from the shell variable TERM. To make it work, you must set the value of $TERM in your .profile, and export it. .P On some systems, there is a utility program called "ttype" which figures out your terminal type for you. It works either by accessing a database for hard-wired lines, or by sending something to your terminal and testing for a response. Thus the lines: .SP export HOME PATH MAIL LOGNAME LOGTTY TERM INFO .br TERM=`ttype` .SP will set the terminal type correctly if ttype is available. If TERM is set to an unrecognizable type, EMACS will prompt for terminal type, however the prompting message may come out in a strange place on the screen due to lack of knowledge about terminal controls. Most terminals commonly used at Bell Labs are acceptable for use with emacs. Support for other terminals could easily be added if needed. If you need support for an unsupported terminal, either consult the document ~EMACS/term_support for a description of how to do it yourself, or contact ihnss!warren for details. .P There are two "features" of the adm3a terminals that sometimes cause trouble in EMACS. One of the internal switches on that terminal is labeled space/advance. That switch must be in the space position for EMACS to work properly. A second problem is that many of these terminals are set up to use one of the "undefined" pins of the rs-232 interface for some internal diagnostic. This causes the terminal to go wild every time it receives a bell character when connected to a 1200 baud modem (which uses the same pin for something else). If this happens to you in EMACS, set nobell mode, which will prevent EMACS from sending bell characters to your terminal. A better and more permanent solution is to modify the terminal to disconnect this lead, use a cable that does not carry the undefined signals between the modem and the terminal, or use a different kind of modem. .P The BLIT or Teletype 5620 terminals can be used in a number of different ways. The terminal types "blit" and "jerq" will work well on a stand-alone blit. The only difficulty is that the terminal will not transmit ^S and ^Q, requiring you to use controlify mode to send these characters. Emacs will also run in a layer defined on the terminal. Emacs discovers the size of the screen in the layer using the ioctl call defined for this purpose or using the environment variables "LINES" and "COLUMNS" to define the screen size. This initialization is performed whenever the terminal type is specified, so you can re-dimension your layer and tell emacs. The terminal type "layer" will work with the layer terminal driver, but it is very crude in buggy. It is strongly recommended that you download one of the available terminal emulators into the blit and use that. The hp emulator works acceptibly, as does the vitty emulator. There is an improved emulator avialble that has been called "etty" which works even better, since it transmits ^S and ^Q, and it allows you to use the mouse with a macro package (blit) to do text and menu selection. .H 3 "Initialization file. Once terminal type has been established, EMACS consults an initialization file that allows you to initialize the various modes the way that you want them. This file is called ".emacs_init" and should be put in your home directory. The file should contain exactly what you would type from the terminal in order to set it up. Thus the file: .SP .DS ^U^X^Mfill ^X^Mc ^X^L~EMACS/macros/loader .DE .SP sets 'c' mode, unsets fill mode, and loads the loader macro package. If you do not have a .emacs_init file, emacs will run the standard initialization file for your system, which you can examine by looking at the file ~EMACS/.emacs_init. It will not run both. You can also cause initializations to take place by command line arguments (see below). .H 3 "Command line arguments" Emacs accepts a number of arguments on the command line that effect processing. These are: .VL 10 .LI "-i" Emacs interprets the next argument as the name of an init file to run in addition to the standard init file (Yours or the system's). The specified file is run after .emacs_init. .LI ".i" Emacs interprets the next argument as the name of an init file to run instead of the standard file. .LI "+n" 'n' is an integer. Emacs moves to line n of the specified file after it is read in. .LI " The last argument on the command line should be the name of the file to be edited. This file (if present) is read into the buffer Main. If no filename is specified, emacs edits the buffer Main with no associated file. .H 2 "Helpful hints" This editor is very easy to use, once you know a few of the basic commands. Learn a few of the basic commands at a time. EMACS tries to be reasonably efficient about the refreshing of the screen. Some sequences, however, will cause lots of text to be redisplayed. While you can insert anything into the middle of a buffer by typing it, it is much better to open up some lines where you want to insert, insert, and then kill unneeded lines. .P Use M-? when in doubt about a command. The explanations are brief, but should be sufficient to tell you what you want to know. Like most editors, EMACS maintains a local buffer, so that changes made do not go into the file until the next write. Type ^X^S reasonably frequently so as to avoid being wiped out by machine crashes, editor bugs, or other unpredictable events. .P Because EMACS tries to avoid unnecessary refreshing of the screen, it will get confused if characters are sent to your terminal from some other program while running EMACS, such as a "background" program, or by a write command from another user. If you suspect that the display does not correspond to the buffer that you are editing, type ^L to refresh the screen. After typing ^L, the screen will match the buffer being edited. .H 2 "Limitations of the editor" There are some limits that you may encounter: .BL .LI Each line can hold at most 512 characters. .LI Each buffer can hold a maximum of approximately 15,000 lines. .LI You can have at most 12 buffers. .LI The kill stack contains the 8 most recent deletions, or a total of 256K characters. .LI Filenames are limited to 128 characters. .LE .H 2 "Problems with EMACS" Because EMACS puts your terminal in "raw" mode, there is no way to transmit a "quit" signal to EMACS if something goes wrong. (On a hard-wired port, you may have to kill the EMACS process from another terminal, as there may be no way to send a hang up signal). If EMACS encounters an error that causes a fault trap (memory fault, bus error, etc.) EMACS will put your terminal back in cooked mode before exiting. If EMACS is killed via the kill command (except kill -9), it will try to save your buffers before terminating. The buffers are saved in the files emacs0-emacs11 in your home directory. A message to this effect is printed, although it is easy to miss. .H 1 "DIRED" The program DIRED (DIRectory EDitor) allows editing of a directory. DIRED takes an argument which is the name of a directory, and displays the result of a ls -al executed on that directory. The EMACS commands for cursor movement, search, etc. can be used to move around in the displayed buffer. Entering '^D', '^?' or ^K marks the file designated by the current line for deletion. 'D' and 'd' mark the current file if the cursor is at the beginning of the line. Typing 'u' or 'U' at the beginning of a line entering 'u' removes such marks. All files marked for deletion are displayed with a D in the first column. You can edit the mode, owner, and group fields in files. DIRED will mark such changes by putting 'O' or 'M' at the front of the edited entry. DIRED runs in overwrite mode, so that what you type writes over the field that is there. This simplifies filling in the fixed format fields of a directory entry. .P None of the changes implied by editing with dired take place until you do a save (^X^S), write (^X^W), or exit. Dired will present a list of the entries to be edited, along with an indication of what is being done to each (D, O, or M). Dired will then ask for approval. If yes is entered, DIRED will delete the files marked with 'D', and make the changes to the mode, group, and owner fields. Doing a read (^X^R) will read another directory for display without deleting any files. .P Another feature of dired is that typing 'e' (with the cursor at the beginning of the line) will cause the file or directory designated by the current line to be edited by DIRED or EMACS as appropriate. This is a convenient way of exploring the useful files in some directory. DIRED is a nice way to clean up a "dirty" directory, because it allows the user to go back and forth over the contents of a directory, marking files for deletion. .P Ordinarily, the buffer listing for dired is created with a "ls -al" command. You can specify additional options for the display by giving dired an argument beginning with a "-" to specify options. Thus "dired~-t~/usr/bin" will invoke dired on /usr/bin with a listing sorted in time order. .P DIRED is not very robust, and can be confused if, for example, you try to edit the filename field in the display lines or delete the header line. .H 1 EXPERIENCE The author originally wrote EMACS as an aide to his own work of programming and memorandum composition. EMACS was made available to other members of the author's department (5343) and now has a user community of about 15. The observations in the following sections come from the author's experiences and those of the other users. .H 2 "Feature Use" The most commonly used "feature" of EMACS is simply the ability to enter text and see the result. The simple cursor movement commands appear to be much more frequently used than the more complicated commands, such as those moving forward or backward by sentences. .P The following is a summary of the user reaction to some of the unique features of EMACS. .AL .LI "Multiple Buffers" .br The ability to maintain several editing buffers at the same time is widely used for many purposes. These include examining several source files while making modifications, holding source, compiler output, and program output while debugging, and holding the output of the spell utility while scanning a document for misspelled words. The availability of multiple buffers allows the user to manage several different tasks, such as writing a program, editing a memorandum, and helping a friend locate a system problem, concurrently. .LI "Two Window Mode" .br Two window mode is less heavily used than some of the other features, but appears to be quite useful for a variety of tasks. These include viewing a buffer containing declarations at the same time that a program is being entered in the second window, and viewing the output of the spell program at the same time that the document is being edited. The fact that only one of the two displays is actively maintained does not seem to be a problem, nor does the limitation of only two display windows. The author has not received any user comments on these limitations. .LI "Incremental Search" .br With a high speed terminal, incremental search seems to be very effective. The ability to quickly move from one occurrence of a string to the next seems to meet most user's needs. With significantly less than 9600 baud communication, the amount of re-display created by incremental search becomes bothersome, and the regular expression search is preferred. The fact that incremental search does not "wrap around", seems to be a significant problem to many users. .LI "C mode and Fill mode" .br These two modes provide customized facilities for editing certain kinds of files. The user reaction to these is mixed. Some users make extensive use of these, while others have their own styles for entering memorandum or program source and do not use these modes. They are a very small part of EMACS, and as such are worthwhile even if they are not extensively used. .LI "Line Numbers" .br The display of the line number (lnumb mode) is one aspect of EMACS that was not taken from the M.I.T. version. This appears to be extremely useful for use with UNIX, primarily because of the widespread use of line numbers to indicate position within a file. Line numbers also serve to provide the user with some feedback as to what part of the buffer is currently being displayed. .LE .H 2 "Performance" While computer resources are not as expensive as they once were, they are far from free. An interactive screen editor such as EMACS consumes more in computer resources than a conventional editor. EMACS was designed to be as efficient as possible, some price must be paid for the benefits gained. .P The Processor time consumption of EMACS is comparable to the UNIX editor for most "commands", including reading and writing files, searching, and substitution. The major discrepancy in performance comes in entering text. In entering text, EMACS consumes approximately 2.5 times as much processor time as the UNIX editor. .P If we examine how each editor uses its time, we see that almost all of the time spent by the UNIX editor is spent in the UNIX operating system reading characters. About two thirds of the time spent in EMACS is spent reading and writing, while the remaining third is spent re-creating the display. EMACS uses almost twice as much UNIX operating system processor time, because it is re-writing the display after each character is typed, in addition to reading the characters. In addition, EMACS spends a significant amount of user processor figuring out how to most efficiently re-display the screen. .P While EMACS does consume more time editing than does the UNIX editor, the processor time spent editing does not appear to be a significant problem. Based on the use of EMACS in our department, about .01 seconds of PDP 11/70 processor time are consumed for each character input to EMACS. This is an average over all users doing many different kinds of editing tasks. There is substantial variance from one case to another. This rate suggests that a substantial number of users could be supported by a PDP 11/70. In our department, we typically have around 8 users running EMACS during the afternoon, with no significant complaints about the response that can be attributed to EMACS. .H 1 CONCLUSIONS The EMACS editor provides an effective means of using a high-speed display terminal for text editing. EMACS provides a variety of unique features that seem to be very useful in editing. User reaction indicates that using EMACS has improved their productivity, however there are no quantitative measurements of this effect. .P EMACS uses more computing resources than the standard UNIX editor, however the resources utilized do not appear to be a serious problem. We have not yet experienced any performance problems attributable to the widespread use of EMACS on the PDP 11/70 used by our department. .P EMACS was written by the author as a tool for his own work, but is available to anyone desiring a copy. There are no currently known bugs, however there may be undiscovered problems. The author is interested in user reaction to EMACS and in reports of problems, however, the author's job does not include supporting EMACS, and thus the author does not promise any prompt response to suggestions or trouble reports. .SG UNIX .SK .tr ~~ .nr Hu 1 .nr Hc 1 .HU "APPENDIX -- EMACS Command Summary" .SP 2 .nf EMACS version 4.6 Date: 10/1/83 ^@: sets the mark at the cursor position ^A: moves to the beginning of the line ^B: moves back one character ^C: capitalizes the current character ^D: deletes forward one character ^E: moves to the end of the line ^F: moves forward one character ^G: quits from any command in progress ^H: deletes backward one character ^I: inserts a tab ^J: opens a new line and moves to the beginning of it if the next line is non-empty, otherwise down one line ^K: Kills to end of line (with argument, kills multiple lines) ^L: refreshes the screen ^M: opens a new line and moves to the beginning of it if the next line is non-empty, otherwise down one line ^N: moves down one line ^O: opens up a new line ^P: moves up one line ^Q: quotes the next character ^R: starts a reverse search ^S: starts a search ^T: transposes the next two characters ^U: multiplies the argument by 4 ^V: moves to the next page ^W: kills the current region (between cursor and mark) ^X: is a prefix for more single character commands, type character or '*' for all ^Y: restores last killed text (leaves cursor and mark around it) ^Z: exits one level ^[: Makes the next character a meta character ^]: makes a local variable of a macro invocation the argument to the next command ^^: Causes the last returned result to become the argument ^?: deletes backward one character M-^L: Re-displays with current line at top of page M-^M: Mails the current buffer M-^Q: Returns the next input character (in a macro) M-^R: Regular expression query replace M-^S: Regular expression search M-^X: Executes argument 0 as a character command. M-^]: Assigns the result of the next command to a macro local variable M- : sets the mark at the cursor position M-!: gets and executes a shell command M-": Auto Fills the whole buffer M-$: Executes a command, saving the output in buffer .exec M-/: starts a comment M-:: Maps a character to a command M-<: moves to top of file M->: moves to bottom of file M-?: explains the next character M-E: Expands an environment variable and returns the result on the kill stack. M-\: Converts its argument to a character and inserts it M-_: Underlines the next word M-a: Moves to beginning of sentence M-b: moves back one word M-c: capitalizes the next word M-d: deletes the next word M-e: Moves to End of Sentence M-f: moves forward one word M-g: Moves to a specific line (its argument) M-l: Converts the next letter to lower case M-m: Displays active modes M-p: Puts the current region in the kill buffer without killing it M-q: Quotes the next character and adds the 0200 bit M-r: starts query replace M-s: Gives EMACS statistics M-t: Prompts for terminal type M-v: moves back one page M-w: Puts a wall chart of explanations in the buffer M-x: Calls a macro by name M-y: Replaces the last restore() with the next text in the kill stack. M-z: kills emacs with a core dump (for debugging) M-{: Enters a command sequence (in a macro) M-}: Exits a command sequence (in a macro) M-~: Marks a buffer as being unmodified (up to date) M-^?: deletes the last word Control-X commands: ^X^A: Accesses the argument list to emacs ^X^B: Changes Buffers (Change to * lists active buffers) ^X^C: exits gracefully (after asking whether or not to save the buffer) ^X^D: Changes the working directory ^X^E: Calls emacs recursively taking input from the terminal ^X^F: Edits a file in its own buffer (if file has been read into a buffer, moves to it) ^X^I: Re-directs input from a file ^X^K: Kills a buffer ^X^L: Loads a file full of macro definitions ^X^M: Sets mode from argument (prompts for mode name) and string if necessary ^X^N: Changes the buffer or file name ^X^O: Switches between windows ^X^Q: Returns the character under the cursor (in a macro) ^X^R: reads a new file ^X^S: saves the buffer in the current file (if modified) ^X^T: Prompts for a buffer name and inserts the text between the cursor and the mark into the named buffer. ^X^U: Updates the display and delays for a specified time ^X^V: Puts the current version on the kill stack. ^X^W: writes a new or old file ^X^X: exchanges the mark and the cursor ^X^^: Causes the current window to grow one by line ^X!: Begins a case statement (in a macro) ^X%: Exchanges the top of the kill stack with another item ^X&: Compares two strings ^X(: Starts a keyboard macro ^X): Ends a keyboard macro ^X+: Causes the next entry to the kill stack to append to the previous entry ^X-: Pops the kill stack ^X1: Exits two window mode ^X2: Enters two window mode ^X<: Pushes a string from the tty or macro text into the kill stack ^X=: Gives statistics about the buffer ^X>: Duplicates an item on the kill stack ^X@: Prompts the user with a string from the kill stack and returns the result. ^XB: Puts the buffer name into the kill stack ^XE: Executes the keyboard macro ^XF: Puts the file name into the stack ^X^: Enters a "while" loop (in a macro) ^Xd: Defines macros from the current buffer ^Xg: Moves to a screen position (arg=128*y+x); ^X|: Begins a conditional execution sequence (in a macro) ^X~: Performs arithmetic or logical operations (in a macro) ^.fi .CS .SK .NS "" All Supervision Lab 534 All Members Department 5343 All Department Heads Lab 364 S. A. Bauman C. Christensen W. E. Danielson J. D. De Treville J. R. Fleming J. A. Githens R. D. Gordon H. M. Jackson II R. K. Kanodia L. E. McMahon D. M. Mcilroy E. Nussbaum R. A. Reed D. Ritchie R. F. Rosin J. M. Scanlon K. Thompson R. A. Thompson .NE .TC 0707070000020075001006660001460001440000011011770355555307700001400000042222emacs_vt.mm.tr ~ .ND "February 3, 1981" .\" EMACS_MODES: fill !c .TL 40309-300 Display Terminal Management Functions .AU "Warren A. Montgomery" WAM IH 5343 2494 6E-320 55343-81-0203.01EN .SA 1 .NR Pt 0 .AS 2 Efficient handling of a display screen is a difficult problem. This document describes a collection of functions based on the EMACS screen editor that update a display efficiently, using the cursor addressing and editing functions of the terminal. These functions provide a relatively simple, uniform interface to allow a program to manipulate a display terminal with minimal knowledge of the terminals display characteristics. The functions have been used with a number of display-oriented programs to implement various tools. .AE .NS All Members Department 55343 All Members Laboratory 5534 C. A. Brooks L. L. Crume G. R. Guthrie J. D. DeTreville A. G. Kegel E. Nussbaum M. A. Plotnick .NE .MT 3 .H 1 "Introduction" Display screen terminals are frequently used to display an image of an object or a collection of objects. Examples include the text file display of a screen editor, the picture display of a game, or the directory display of a directory editing tool. If the display memory were directly accessible to the machine on which the program was being run, the display could be instantly updated from the program. Updates to a remote terminal must take place through a slow communication link and make use of a limited vocabulary of commands for altering the display on the screen. .P The problem of updating a display is complicated by the fact that every terminal provides a different set of commands for updating. Even the simplest terminals differ in how they address the screen and how they move the cursor. "Intelligent" terminals each provide a different set of primitives for altering the screen image. As if matters were not complicated enough, there are many other problems that must be solved by a screen display program, such as putting the terminal in the right state for information display, restoring the terminal to a state usable with UNIX commands when the program terminates, mapping non-printing characters in the objects to be displayed into some printable representation, and keeping track of the size and shape of the display. .P When I wrote the display processor for the EMACS editor, I programmed several general purpose functions for solving many of the above problems. The display processor allows the program to update the display with minimal knowledge of the characteristics of the terminal. The display processor uses the updating functions provided by the terminal to update the display with a minimum number of characters sent to the terminal, and thus minimum delay. These display functions are available for use in other display programs. The remainder of this report describes these functions and their use. .H 1 "General Information" The display processor is available in an object file: emacs_vt.o. This file should be loaded with your program, as in: .P cc /n1/warren/emacs/emacs_vt.o .P The display processor works by maintaining in memory an image of what is currently on the real terminal, and allowing the application program to manipulate this image. As the image is manipulated, the display processor determines how best to manipulate the terminal in order to make it correspond to the screen image. For this to work properly, all output appearing on the terminal must be sent via the display processor. Extraneous output, such as output from commands running in the background or from echoing of characters input, will confuse the display processor and will result in the display not looking as desired. .P The basic interface to the display processor provides a "virtual cursor", which describes a location on the screen image, and a set of functions to move the virtual cursor and write characters to the image at the current virtual cursor. .P The display processor operates the terminal in "raw" mode, with no echoing, no erase/kill processing, no xon/xoff processing (It provides delays as needed), and single character at a time input. Functions are provided to put the terminal into this mode and to take it out when you exit. You do not have to operate in all of these modes if you provide your own input and initialization functions. What is needed is that carriage return and newline characters output that character only, and that no output is sent to the screen without going through the display processor (as is done by unix echoing). .P Because all display programs tend to generate a lot of output, it is strongly recommended that the output be buffered. This is done by declaring a buffer of appropriate size (BUFSIZ), and calling setbuf to set a buffer for standard output. The standard startup does this for you. Beware, however, that output is not sent until a full buffer is available or explicitly flushed. The input functions in the display processor flush output before reading, however you must do this for yourself if you call any input reading functions not provided by the display processor. .P The display processor makes use of a terminal description database that gives the display commands and parameters available for most of the commonly used types of terminals. The terminal type must be initialized before any other display processing is done, and the terminal must be placed in the propper mode. The usual convention for setting the terminal type is to have an environment variable ($TERM) that contains the type of the terminal passed to all programs that do screen display. .P The interface between the display processor and the application program consists of functions and parameters. The following sections describe this interface in more detail. .H 1 "Display Parameters" Some of the processing performed by the display processor is controlled by display parameters that can be set by the applications program. In addition, certain parameters describing characteristics of the terminal may be useful to the application program in deciding what to display. .H 2 "Display Processor Parameters" All of the following display processor parameters are integers, which should be declared as external to the application program. These parameters control the behavior of the display processor. .VL 10 .LI "mline" This is the line number of the "virtual cursor". The top line of the screen is line 0, and the line numbers increase going down the screen. .LI "mcol" This is the column number of the virtual cursor. The left-hand column is 0, and column numbers increase going to the right. The application program should not modify mline and mcol except through the interfaces provided. .LI "WRAPON" This is a flag indicating to the display processor whether or not to perform "logical screen wrapping" If this variable is set to 1, an attempt to write into the furthest right screen position (greatest mcol) will instead result in an exclamation mark being put in this position and the character written being put in the first position of the next line. If this parameter is off, then the last position can be written, and subsequent characters will be put into the next line. The default value is off. .LI "INSON" This flag controls whether or not the display processor will use insert and delete character functions of the terminal automatically in updating the display. The display processor was written for an application that re-creates an entire line of the image each time that the image is accessed. This allows the processor to use insert or delete character terminal functions to line up the new image with the old, if the new image is simply shifted one position left or right from the old. If your application does not re-create the entire line each time that a line is altered, turn this flag off, because the display processor may mis-align subsequent characters on the same line. .P The display processor is relatively dumb about the use of insert/delete character automatically. It will use insert only when the first difference between the old and new images on the line appears to be correctable by inserting a single character, and will use delete only when the character being written to the image is not what that is not the same as the character that is there is the character one position to the right. There are other application-accessible functions for inserting and deleting characters when the application program determines that this is necessary. The default value for this parameter is off. .LE .H 2 "Terminal Parameters" In addition to the parameters that control the display processor, some of the terminal characteristics may be of interest to the application. These are both integers and character strings which indicate the size and shape of the screen, and the intelligent terminal functions available. .VL 10 .LI "SCRWID" This integer is the column number of the far right column (i.e. number of columns -1). .LI "SCRNLIN" This integer is the number of lines that can be displayed on the terminal. .LI "INSERTC" This string pointer is NULL if terminal has no insert character function and non-null if the terminal can do character insertion. .LI "DELC" This string pointer is NULL if the terminal has no delete character function, and non-null if the terminal can delete characters. .LI "OPENL" This string pointer is NULL if the terminal has no insert and delete line functions (can't do vshift), and non-null if not. .LI "VCOST" This integer is the approximate time (in milliseconds) required to scroll a region of the screen by one line. This can be used by the application in estimating whether to modify an image by scrolling it or by re-writing it. .LE .P The above parameters are mainly useful in choosing a strategy for updating the screen. A simple application can choose not to use insertion and deletion in updating the screen, and still obtain a substantial improvement in display speed from using the other display processor functions. .H 1 "Display Functions" The following functions provide the main interface to the display processor. These functions are organized into groups according to their purpose. .H 2 "Initialization and exiting" The functions in this group are used to set up the terminal for display processing or to handle errors. A simple application can use the display processor by calling ttystart() to initialize the display processor, and die(0) in order to exit. The other functions are available to allow the application to have more precise control over the display processor. .VL 20 .LI "ttystart()" This function performs a "standard" startup, calling uncook, setting ttype from $TERM, and setting up die() as the handler for all signals. .LI "die()" This function calls uncook to restore the terminal modes, flushes standard output, and exits. It is useful as a handler to catch unexpected signal and as a clean-up function for exiting. .LI "uncook()" This function puts the terminal into raw mode to begin working with the display processor. .LI "cook()" This function restores the terminal to the mode in which it was before uncook was called .LI "sttype(term_type)" This sets the terminal type to the character string passed as term_type. An error message is printed if term_type is not a valid terminal type. A non-zero return indicates success. .LI "ttype()" This function prompts the user for a terminal type and sets it according to what was typed. .LE .H 2 "Cursor Movement" Three functions are provided for cursor movement. These functions control the movement of the real and virtual cursors. Cursor movements that must be sent to the screen will be done by using either direct cursor addressing, or some combination relative cursor movement, carriage return, and re-writing the characters on the display to move the cursor forward. The method resulting in the minimum number of characters being displayed will be used. .VL 20 .LI "xgo(x,y)" This function moves the virtual cursor to line x, column y, without moving the real cursor. .LI "sgo(x,y)" This function moves the real cursor to p line x, column y, without moving the virtual cursor. .LI "mgo(x,y)" This function moves both the real and virtual cursors. .LE .H 2 "Output" The output functions all take characters or strings to be displayed on the terminal at the current virtual cursor position and do so. All of the output is compared against the characters known to be on the screen already, so that characters that output is sent to the terminal only when it differs from what is on the screen already. .VL 20 .LI "xputc(c)" This function puts the character c into the display image at the current position. If c is not a printing character, it will be translated to a character sequence by the same rules as are used in emacs. Control characters display with '^' in front, and characters with the high order bit set display with 'M-' in front. As a result, xputc will advance the virtual cursor one or more positions depending on c. Wrapping at the right edge of the image is controlled by the parameter WRAPON. .LI "sputc(c)" This function puts out the character c into the image at the current virtual cursor, advancing the cursor by one. Screen wrapping is performed, but no character translations take place. .LI "sputs(s)" This function takes a character string pointer s, and puts all of the characters out via xputc. .LI "xprintf(f,a1,a2,...) This function works like printf, putting the output at the current virtual cursor via xputc. Newlines in the output cause the remainder of the line to be cleared and the virtual cursor to move to column 0 of the next line. .LI "putout(f,a1,a2,...)" This prints the string generated by sprintf (f,a1,a2,...) at the current position and moves to the next line. If the current line is lower than two lines from the bottom, putout prints -MORE- at the bottom of the screen and waits for input, then puts the line on the top of the screen. The return from putout is 1 unless user input was required and the user entered a control-g. .LI "clear()" This function clears the screen, and resets the virtual cursor to the top right corner of the screen. .LI "rfrsh()" This function clears the screen and re-displays what it thinks should be on the screen. This is intended to clean up after output that has not gone through emacs_vt gets to the screen, such as the messages from talk, write, or from background processes. .LI "clrl()" This function clears the current line from the virtual cursor to the end of the line. .LE .H 2 "Input functions" The input functions provided here all flush standard output before reading, so that buffered output can be used. .VL 10 .LI "mgetchar()" This function is just like getchar, but flushes standard output before reading. .LI "getname(f,a1,a2,...)" This function displays the string generated by sprintf(f,a1,a2,...) on the next to bottom line of the screen, and reads a line of input from the terminal. Characters read are echoed after the prompt. The user can edit the line with his normal unix erase and kill characters. Line-Feed or Return end the line, and cause a pointer to the input to be returned. Control-G, or the user's interrupt character causes NULL to be returned. .LE .H 2 "Screen Manipulation" These functions are provided to manipulate the screen using intelligent terminal functions. These functions return 1 if the manipulation could be done, and 0 if the terminal did not have the necessary capability. They are intended for advanced applications, where the application programmer needs efficient display handling and knows what he is doing. .VL 20 .LI "insrtc(c)" This function inserts the character c at the current virtual cursor position, using the terminal insert capability to shift the remainder of the line right by one. The virtual cursor advances by one position. .LI "delc()" This function deletes the character in the current position, shifting the remainder of the line left by one. .LI "vadjust(from,to,dir)" This function shifts the region of the screen between lines from and to (inclusive) by dir lines either up or down. If dir is negative, the lines move down, while if dir is positive, they move up. Lines shifted out of the window are lost, and new lines shifted in are blank. .LI "sscroll(x)" This function scrolls the whole screen up by x lines. This is done with newlines at the bottom of the screen (provided that this works on the particular terminal being used), not with partial scrolling or line insertion and deletion. On most terminals, this is much more efficient, and faster than vadjust. .LE .H 2 "Miscellaneous functions" These functions may be useful for some applications using a display terminal. They do not directly effect the screen at all. .VL 20 .LI "beep()" This function rings the bell on the terminal (If it has one). .LI "sdelay(x)" This function causes a real time delay of x milliseconds, by printing pad characters to the terminal. This is a useful way of generating a short real-time delay, which is not easily done via unix system calls, because they are not synchronized to the output and have poor resolution. .LE .H 1 "Summary" The display processor described here form a useful base for building display oriented programs. It have been used in a number of display oriented programs written in department 55343. I expect that the display processor will continue to evolve to support new terminal functions, and to provide a better application interface. .SG UNIX 0707070000020101621006660001460001440000011012220355555310200001100000055426macro.mm.\" EMACS_MODES: fill !c .TL 40309-300 Writing Macros for EMACS .AU "Warren A. Montgomery" WAM IH 5343 2494 6E-320 5343-80 .SA 1 .NR Pt 0 .AS A macro command facility is now available for writing your own EMACS commands. Writing macros is not simple, because EMACS was not intended as a programming language. This note describes how to write macros and what commands are available to help. Some sample macros are available in /n1/warren/emacs/macros. This facility was first available in version 3.0. Commands added in later versions are noted. This describes the macro facility in EMACS 4.0, the current version in late October, 1980 .AE .MT 3 .H 1 "Macro Commands" EMACS provides a facility to allow a user to define his own commands. These "macro commands" provide a way to implement specialized editing functions for particular applications. A macro command is actually a sequence of EMACS editing commands that are invoked in response to a single character entered from the keyboard, or called by name with the M-x command (see below) Macros can contain ordinary emacs editing commands, invocations of other macro commands, or one of the commands described in this section that are of little use in interactive editing, but are quite useful in macros. .H 2 "The Programming Environment" As noted above, an EMACS macro is essentially a sequence of character commands that is executed as if it were received from the keyboard. Each command accepts an integer argument and produces an integer result. The argument is specified the same way as in interactive editing. .P The result returned by most commands is either 1 if the command is successful, or zero if unsuccessful. These results are ignored in interactive editing, but can be used effectively for controlling execution in a macro. .P When macros are executed, the kill stack is used for storage of string values used as arguments to commands. The commands that ordinarily read parameters from the keyboard take their parameters from the top of the kill stack instead. There are also a number of commands that manipulate the kill stack in useful ways to facilitate its use as local variable storage. Each time a parameter is read from the kill stack, the stack is popped. Programming macros is thus somewhat analogous to using reverse polish notation. .H 2 "Defining macros" Macros can be defined by placing macro descriptions in a buffer and invoking the define macros command. The buffer contains the character sequence on which the macro is to be invoked, followed by the commands to be executed, terminated by a ^Z at the end of a line. Several macro definitions can appear in the same buffer. .P In general, the characters in the macro text are exactly the same as characters entered from the terminal. When the macro is invoked, the macro text will be executed as if it had been entered from the terminal. Meta commands can either be represented as escape followed by a character, or as characters with the 0200 bit set (entered via M-q). Either form can be used, with two exceptions: .AL .LI Numeric arguments must be represented as escape followed by a sequence of digits. .LI The M-{ and M-} characters must be represented as single characters with the 0200 bit on. .LE .P Comments can be put in macros. All text after a ^\e up to the end of line is taken as a comment in a macro definition. Also, spaces and tabs that are executed as commands in a macro perform no operation and return a value of one. This allows macros to be formated somewhat more legibly. To insert spaces or tabs into the buffer from a macro, they must be quoted with ^Q (i.e. ^Q must appear in the buffer, requiring you to type ^Q^Q to enter it with emacs.) .H 2 "Special effects of commands executed in macros" Several commands behave differently when executed as macros than when entered from the terminal. One example of this is the space and tab characters, described above. The other differences are: .BL .LI All of the commands that normally prompt for input from the terminal take that input from the kill stack instead. The top item on the kill stack will be used each time that a response is needed, and the item taken will be removed from the kill stack. .LI The ^Z command exits one level of invocation, not all of emacs. Thus a ^Z encountered in the definition of a macro exits the macro, a ^Z in a condition block exits the condition block, and a ^Z entered from the terminal during the execution of ^X^E exits ^X^E. ^X^C always causes an exit from EMACS. .LI Errors occurring during the execution of macros will cause an error message to be printed on the screen, and wait for input from the terminal before continuing. .LE .P These differences allow EMACS to act as a very primitive programming language for macro commands. .H 2 "Commands related to macros" The following character commands and sequences all perform functions relevant to defining and executing macro commands. .VL 10 .LI "^Xd" Define Macros. The current buffer is scanned for macro definitions. Each definition consists of the character sequence on which the macro is to be put followed by the macro text, terminated by a line ending in ^Z. If a comment immediately follows the character sequence on which the macro is to be put, the comment becomes the description of the macro given in response to M-?. The first word of the comment becomes the name of the macro and can be used to invoke the macro via M-x. If several macros are assigned to the same character, only the last macro assigned is invoked by the character, however all of the macros can be called via M-x, providing that their names are distinct. .P Normally, macro definitions are incremental, and new definitions made via ^Xd do not make previously defined macros inaccessible unless they assign new macros to the same character that old macros were accessed through. If you give ^Xd an argument (^U^X^D), previous macro definitions will be cleared before the new macros are defined. .LI "^X^L" Load Macros. EMACS will prompt for a file to read, read it into a temporary buffer, define macros from the buffer, and discard the temporary buffer. This is a convenient way of loading a macro library Passing an argument to ^X^L works just like passing an argument to ^Xd .LI "M-x" Call Macro. EMACS will take the text up to the next newline as the name of a macro to call and invoke it. The name of a macro is the first word (up to the first space) in the comment on the macro definition line. The matching algorithm will find the first macro defined whose name matches up until the first space in the macro name or the end of the macro name given to M-x. This is a very convenient way of calling subroutines within a macro, however there are some limitations: Only the first 50 macros can be called this way, and the calling mechanism is somewhat slow. .P When you are calling a macro "subroutine" inside of a macro, the use of M-x instead of calling the macro by the character that it was put on is strongly recommended. The limited number of characters available for invoking commands will probably result in naming conflicts if two different macro packages are loaded together. Remember that if several macros are assigned to the same character, entering the character will invoke the most recently assigned macro. All of the definitions remain callable by name through M-x. .LI "^\e" Macro Comment. In a macro, the rest of the line (including the newline) is taken as a comment. .LI "^X^E" Recursive Edit. Takes input from the terminal and interprets it as commands until a ^Z is entered. The kill stack is restored to its previous state when ^Z is entered so that user editing does not interfere with argument passing in EMACS. .LI "^X^U" Update Display. Causes the display to be updated, and then waits for n seconds, where n is the argument. .LI "^X<" Get parameter. This command performs a variety of functions that allow a macro to interact with the user. ^X< reads the characters following ^X< up to a newline as a parameter. Characters are read until a newline is encountered, thus there should be no comment on the line with the ^X<, as the newline is discarded when the macro is defined along with the comment. Newlines can be put into the parameter by quoting them with ^Q. Thus .SP ^X" Pull kill stack. Takes an item from inside the kill stack and copies it to the top of the kill stack. The argument to the command indicates which item is to be duplicated. Thus if the top item on the kill stack is "foo", and the next to top item is "bar", ^X> would cause "bar" to be pushed on top of the kill stack in addition to the other two entries. .LI "^X-" Pop the kill stack. Removes and discards items from the kill stack. The argument indicates the number of items to remove. .LI "^X+" Append to Kill Stack. This command causes the next item pushed into the kill stack (either through a kill or through ^X<) to be appended to the last item pushed into the kill stack. Note that this command appends to the last item actually pushed into the stack, not the item on top of the stack. The only propper use of this command is to cause two consecutive items to be appended. Several commands (newline and query replace, for example) that do not change the top of the kill stack may under some circumstances cause text to be pushed into the kill stack and later discarded. ^X+ will not work if any such commands come between the two items to be appended. .LI "^X%" Swap Kill Stack (Version 3.1). The top item of the kill stack is exchanged with the element identified by the argument. Thus with an argument of zero, the command does nothing, with no argument or an argument of one, the top two items on the kill stack are reversed. .LI "^XB" Push buffer name. Pushes the current buffer name into the kill stack. .LI "^XF" Push file name. Pushes the file name into the kill stack. .LI "M-E" Expand Environment Variable. (Version 4.5) Reads an environment variable (i.e. HOME) from the kill stack and expands it, returning the result on the kill stack. 1 is returned as the value of M-E if the specified environment variable exists, otherways a null string is pushed onto the kill stack and M-E returns 0. .LI "^X^A" Process argument. (Version 4.3) Pushes the first unprocessed command line argument into the kill stack. Without an argument to ^X^A, each invocation marks the argument that is accessed as "processed", so that the next invocation will get a new command line argument. With an argument to ^X^A, the command line argument is not marked as processed, so that the next invocation gets the same one. .LI "M-^Q" Literal character. Reads the next input character and returns it as its return value. In a macro, this will take the character after M-^Q in the macro definition. .LI "^^" Makes the result of the previous command become the argument to the next command. This command and the ^] command are useful for argument manipulation inside of a macro. .LI "^]" This command is used to access local numeric variables in a macro, including the argument given to the macro. Each macro invocation has 10 local variables, numbered 0-9. Local variable number 1 is initialized to the argument passed to the macro invocation. Local variable number 0 is initialized to the character from which the current macro was invoked. (See M-^X for more details.) ^] accesses the variable that corresponds to its argument, and makes the value of that variable become the argument to the next command. Thus if the second local variable of the current macro has a value of 17, the sequence: 2^]M-g will go to the 17th line of the file. .LI M-^] This command makes assignments to local variables in a macro invocation. The value returned by the following command is assigned to the variable specified by the argument to M-^]. The value returned by M-^] is the previous value of the specified variable. This behavior makes it possible to constructs loops such equivalent to the c construct: .DS while (arg--) { do something; }; .DE .LI ^Z The ^Z command has many uses. ^Z can be used to exit one level of interpretation. This causes an exit from the last macro or from the last level of M-{. ^Z in a case in a conditional skips to the end of a conditional. ^Z in a while loop acts like continue in C. Another useful feature of ^Z is that it returns its argument as its result. .LI ^X= When invoked in a macro, the ^X= command returns status information as its result. The particular information returned depends on the argument passed to ^X=: .VL 5 .LI 0 The file line number on which the cursor sits (First line is line one). .LI 1 The character number within the line on which the cursor sits (First character after a newline is 0). .LI 2 The line number on the display at which the cursor displays. (The upper left hand corner is line 0, column 0, and positions increase downward and right). If the current line is not on the display, -1 is returned. .LI 3 The column number on the screen at which the cursor displays. Again, this is -1 if the current line is not on the screen. .LE .P This command has all kinds of applications in drawing, and in controling the display output. .LI "^X^Q" Buffer Character. Returns the character under the cursor as its value. .LI "^X~" Logical operations. This command performs an arithmetic comparison or logical operation, returning the result as its value. The operation performed is determined by the argument to the command. The operands (if any) are the return values of subsequent commands. The operations are: .AL .LI 0 arg1 <= arg2 .LI 1 arg1 == arg2 .LI 2 arg1 < arg2 .LI 3 arg1 > arg2 .LI 4 arg1 != arg2 .LI 5 arg1 >= arg2 .LI 6 arg1 OR arg2 .LI 7 arg1 AND arg2 .LI 8 NOT arg1 .LI 9 FALSE .LI 10 TRUE .LI 11 arg1 PLUS arg2 .LI 12 arg1 MINUS arg2 .LI 13 arg1 TIMES arg2 .LI 14 arg1 DIVIDED_BY arg2 .LI 15 arg1 MOD arg2 .LI 16 Convert arg1 to a string and leave it on the kill stack. .LI 17 Convert the top string on the kill stack and return it as the value of ^X~. .LE .tr ~ .LI "^X&" String Comparison. This command takes two string parameters from the kill stack and compares them character by character. The argument dictates the comparison performed. The same argument conventions are used here as are used with arithmetic comparisons. Thus M-0^X& will return 1 if the top string on the kill stack compares less than or equal to the next to top string. ^X& without a argument returns 1 if the two strings are equal, and 0 otherwise, etc. .LI "^X|" Conditional Execution. This command is a generalized conditional execution control structure, somewhat like the cond function of LISP. The general format is: .nf .SP ^X|M-{ M-{(condition~1)(body~1)M-} M-{(condition~2)(body~2)M-} ... M-{(condition~n)(body~n)M-}M-} .SP .fi Each condition is a single EMACS command, while each body is a sequence of EMACS commands. The conditions are executed one at a time until one is found that returns TRUE. The corresponding body is then executed and the rest of the conditional is skipped. The result returned by the conditional command will be the result of the executed body clause, which is the argument passed to the M-} that terminates it. The conditional structure can be used to implement an if-then-else structure, by putting the test in the first condition, with the then clause as the body, and putting a space (which returns true with no other effects in a macro) as the second condition with the else clause as the body. Many other structures are possible. Note that the braces (M-{ and M-}) must be represented as single characters and not as escape sequences. .LI "^X!" Case statement. This command begins a C style case construct. The general format is: .nf .SP ^X!M-{(expression) M-{(case~1)(body~1)M-} M-{(case~2)(body~2)M-} ... M-{(case~n)(body~n)M-}M-} .SP .fi The expression is a single EMACS command, while each case is a single character. The expression is evaluated, and the result returned is compared with each of the cases. Each case is a single character whose value is compared with the expression. The one special character 'M-^?' (octal 377) matches any expression. The body of the first case that exactly matches the result of the expression is executed, and the rest of the bodies are ignored. The result from the case command is the result returned by the body of the case executed, or 0 if none of the cases match. The case construction is really just a shorthand for a particular use of the more general conditional. It is particularly useful for analyzing a single character, doing something different depending on what the value of the character is. .LI "^X^" Iteration. This command implements an iteration of the following form: .SP ^X^M-{(condition)(body)M-} .SP The condition is a single command, and the body is a command sequence. The effect is the same as the C construct: while (condition) body; .LI "M-{" (4.0) Begin Block. A M-{ that is not part of the definition of a conditional, iteration, or case construct acts much like a { in a C program. The sequence of commands up to the next } are treated like a single command syntactically. This command is most useful for grouping a sequence of commands in a context where a single command is executed, such as an expression for a conditional, case statement, or arithmetic operation. .LI "^X^N" (4.0) Change Name. This command allows you to change the buffer name or file name associated with the current buffer. ^X^N changes the buffer name while ^U^X^N changes the file name. Both commands prompt for input when run from the terminal, or take input from the top of the kill stack when run from a macro. .LI "^Xg" (4.6) goto screen position. .br This command interprets it's argument as a coded screen address and moves the cursor to the selected position. The argument is coded as the Collumn position * 128 + the line position, where 0,0 is the upper left corner of the screen. If the position is not in an area where a buffer is displayed, the command fails and does nothing. It will, however switch windows if it is in 2 window mode and the selected text is in the other window. .LI "M-^X" (4.1) Execute. This command executes the command (emacs command or macro) corresponding to the character value of macro variable number 0. The argument to M-^X is passed as the argument to the command. The execute command is mainly useful to allow you to read a character from the terminal (via ^X<) and interpret some characters specially, giving the standard emacs treatment to any character you don't want to treat specially. Another application of this is a macro which when called loads a macro package and re-executes itself. This saves startup time and buffer space if you have lots of macros that you only use rarely. The mapping of characters to commands is as follows: .BL .LI "0000-0177" ASCII characters. .LI "0200-0377" Meta characters .LI "0400-0577" Control-X characters .LE .LE .H 2 "Notes on Macros" Macro programming in EMACS is not simple. The syntax is obscure, because emacs was not intended as a programming language. Errors in macros can cause all kinds of troubles, such as garbage being interpreted as emacs commands, clobbered buffers, and core dumps. Therefore, anyone writing macros should be careful. There is also nothing to prevent you from re-defining useful commands with macros. .P Some guidelines on developing and defining macros: .BL .LI Always leave the kill stack at the same "level" when a macro returns. If a macro leaves garbage on the kill stack, it will cause trouble if called from another macro, as the caller won't be able to depend on the state that the kill stack is left in. .LI Check carefully for balanced braces. This is probably the most dangerous thing that can happen. EMACS will print out a warning when a macro that is not apparently balanced is defined. .LI Use Comments to describe what the macro does, step by step. The obscure syntax makes the code completely unreadable. .LE .P There are some implementation issues that you should be aware of when writing macros. Macro definitions occupy some of the space that is used for in memory buffering of the buffer file. This will cause additional I/O to do simple editing as the number of macro definitions increase. It is therefore a good idea to minimize the number of characters used in macro definitions. Comments are not saved when a macro is defined, so they do not take up any space. Space can be reduced by using the one character representation for meta commands instead of using escape sequences. In any case, the maximum space for macro definitions is about 7K bytes. .P Each macro entered, conditional, while loop, or brace causes another stack frame to be used. There is no absolute restriction on the amount of space available, however it is a good idea to minimize the nesting depth. .P While all characters can be re-defined via macros, the special meanings attached to M-{ and M-} in grouping operations for loops and conditionals cannot be changed. In addition, re-defining characters will not change the effects of characters used in editing string parameters such as filenames. These characters include: Rubout, ^H, ^K, @, ^X, ^Y, and ^G. .SG UNIX 0707070000020102451006660001460001440000011011020355555310400001700000075502recent_changesSUBJECT: new features and old bugs Version 2.4 will soon be installed as EMACS (it is now NEMACS). This version allows longer files to be edited (up to about 9,000 lines), and has several other changes. The M-w command puts a "wall chart" of commands (the combined output of "M-?*" and "M-?^X*" into the current buffer. This is a handy reference. If you try to quit via ^X^C and tell emacs to write a buffer that has been modified, it will not quit if it encounters a problem (such as a protection violation). Several problems in the manual have been fixed. These were first discovered when Brad, a new user totally unfamiliar with emacs, tried to learn emacs from the manual. The manual is in /n1/warren/emacs/emacs.doc SUBJECT: Version 2.6 Version 2.6 (now /usr/obin/nemacs) has several new features. This version has some modifications to the file and buffer handling, and there may be bugs that cause garbled files. It will probably stay as nemacs for some time until I am sure that it is sound. Non-Destructive buffer reading: The ^X^R and M-$ commands now take the value of their argument to specify whether or not clear the buffer before reading. If no argument is given (just invoke ^X^R or M-$), they clear, as they did in past versions. If an argument is given, the text read is inserted into the buffer at the current cursor position, or at the end for M-$. Thus if you type ^U^X^R and a file name, it is inserted. If you type ^UM-$ and a command line, the output of the command is appended to the buffer .exec. (almost) Unlimited Kill Buffer. The limit on the amount of text you can kill and still receive is now 256K characters. The kill buffer is kept in a file, and the only limit is the amount of stuff you want to clutter up the file system with. As before, only the last 8 deletions are remembered. Reading a file without re-initializing the buffer, or retrieving lots of killed text, take lots of time if the cursor is in the middle of a line (i.e. there is text to the right of the cursor). You can save a lot of time by opening up a line, doing the read or retrieval, and then killing the leftovers. SUBJECT: version 2.7 version 2.7 contains many non-visible changes to reduce memory usage and improve efficiency. The visible changes in version 2.7 are support for HP terminals (terminal type hp) An improved re-display algorithm that sometimes scrolls the screen. ^Z now does exactly what ^X^C did. The ^X^T command takes the marked region in the current buffer and inserts it into a second buffer. Mail will now take any number of lines starting TO: or CC: for the destination of the mail. EMACS will not try to write buffers with a null file name after ^X^C or ^X^S SUBJECT: new features in EMACS 2.8 New commands: ^X= will print out the character position of the cursor in the buffer and the total number of characters in the buffer. M-" will re-adjust the lines in the buffer so that each line has 72 or fewer characters. Blank lines, or lines starting with '.' or '`' are not changed (these are nroff control lines). Other new features: You now have 12 marks available for the commands dealing with marks. If you specify no argument to commands using marks, they will use a different mark in each buffer. By specifying an argument to commands using marks, you can explicitly set two or more marks in the same buffer. See the documentation for more details. You can now set default modes for a file by putting the string EMACS_MODES: anywhere in the first 10 lines of a file, followed by a description of the modes to set. For example, the string /* EMACS_MODES: c, !fill, tabstop=3 */ in a c source file will turn on c mode, turn off fill mode, and set the number of spaces per tab in the display to 3. For more details, see the document. When EMACS asks "continue?" after executing a unix command or listing active buffers, if you type 'y', ' ', or (return), EMACS will go back to the buffer. Otherwise, it will ask for another unix command or another buffer name. You can also get a list of active buffers by entering (return) in response to any of the commands that ask for a buffer name. SUBJECT: new features in EMACS 3.0 There is now a way to pass the contents of the current buffer as standard input to a command. Preceding meta-! (execute unix command) with ^U causes it to pass the buffer as standard input. This does not work for meta-$. (Sorry, but there is no obvious way to do this without the possibility of deadlock.) There are several minor bug fixes in this version. The undocumented game of life command (M-#) has been deleted. If there is any interest in it, I will keep a version that has this feature. The big change here is the ability to define new commands. Basically, any sequence of emacs commands can be defined as a command. There are additional commands for sequencing execution, and for obtaining information from the terminal. A brief description of the new commands is available in /n1/warren/emacs/macro.mm (mm source) or /n1/warren/emacs/macro.xopr (xopr'able copy). Some sample macro definitions are available in the directory /n1/warren/emacs/macros. SUBJECT: new features in EMACS 3.1 Several new features relating to macros: The ^X% command which exchanges the top of the kill stack with the item identified by the argument. All of the commands that access the kill stack (^Y,^X-,^X>,^X%, etc) now return 1 as a result if successful and 0 if there are not enough items in the kill stack to satisfy the request. EMACS will not ask Continue? after commands, buffer display, statistics, and similar commands when the command is invoked in a macro. You can use ^X< to ask Continue? if you like. M-s now displays the amount of buffer space left for editing or macro text. You need a minimum of 1024 characters. The buffer name ... is now special. If you create a buffer named ..., it will create a new buffer with a unique name instead. This is useful for creating temporary buffers in macros. M-x can now be used to call macros by names, rather than always invoking a macro by a character. This should help in the construction of macro libraries. ^X& compares two strings for a macro SUBJECT: new features in EMACS 3.2 Several miscelaneous display bugs have been fixed A new mode parameter (keepscroll) has been added. This is initially 0 and can be set to the number of lines that you wish to keep from the last screen when going forward or backward by pages (^V or M-V) If you give an argument to ^L, it specifies the number of lines to appear on the screen before the current line when the display is rereshed. The command ^X^^ causes one line to be added to the current window when in two window mode. The command ^X^U causes the display to be updated and causes EMACS to delay for n seconds, where n is the argument to ^X^U. This is useful in macros. The command M-] causes the last numeric argument to a macro to be passed as the argument to the current command. By popular demand, EMACS will now ask whether or not to write a buffer that contains text and has no file name associated with it. SUBJECT: new features in EMACS 3.3 The command ^X! starts a case statement in a macro (see the macros memo for details) The redisplay heuristics have been improved for terminals that have insert/delete line and insert/delete character capabilities (hp, adm31, vt100, etc.) The command M-~ marks a buffer as not being up to date without writing it out. The .emacs_init file is now run before reading in a file specified on the command line. This should reduce unwanted display on starting up. I am now maintaining a library of macros in /n1/warren/emacs/macros. There are macros for various purposes, such as dealing with unix mail, keeping track of refrences for mm, a help function for emacs commands, balancing parentheses, etc. Anyone interested in submitting macros should follow the rules outlined in the LIBRARY_RULES file, and send them to me. SUBJECT: new features in EMACS 3.4 EMACS will now expand environment variables, such as $HOME or $MAIL, in pathnames for reading, writing, and finding files. Asteristisks in file names (ie *.c) are still not expanded. EMACS will not print prompts from commands read from an init file or form files read with ^X^I. This should cut down on annoying output at startup. A negative argument to a command can be specified with escape, '-', followed by the number. Most commands treat their argument as unsigned, so a negative argument is treated like a large positive argument. For some commands, negative arguments cause special effects. Passing a negative argument to ^X< causes a prompt to be given, and a single character to be read from the terminal as the result. The command M-: allows you to re-map character commands. It prompts for a character (or a meta or ^X sequence) and a command (also a character sequence) to put on that character. This allows you to re-configure EMACS to your liking. The regular expression search facility (M-^S) has been improved. You can now search forward or backward, either ending at the beginning or end of buffer, or wrapping around (like ed). With a positive argument, the search is forward, while a negative argument searches backwards. An argument of 1 or -1 causes the search to wrap, failing only if there is no occurance of the expression in the buffer. Any other argument causes the search to stop at the beginning or end of file. Note that the default (argument = 1) does exactly what the old one did. Entering ^S or ^R immediately following a regular expression search will find the next or previous occurance of the expression. ***********Note to EMACS maintainers************* As of version 3.4, the file regexp.h is no longer needed. The makefile has been updated to reflect this, and you will not receive this file in future updates. Beginning with version 3.5, EMACS will maintain error messages in a separate file (errfile). This is produced like the helpfile. Also beginning with this version the pathnames for the help and error files will be automatically set to the directory from which make is invoked. Thus you do not need to change any pathnames unless you plan to keep the error, help, and statistics files in some other location on your system. This should simplify making EMACS. *************************************************************** SUBJECT: new features in EMACS 3.5 Passing an argument to ^X^W (i.e. ^U^X^W) will cause the contents of the buffer to be appended to the specified file, rather than replacing it. There is a new mode: caseless. Setting this mode will cause case to be ignored in searches and replaces. EMACS will now periodically check to see if you have received mail. If so, it will print a warning at the bottom of the screen and beep. You can now use \ folowed by a single digit in the "To? " string for regular expression query replace to specify replacement by a sub-expression of what was matched. This works just like it does in ed. You can now have local variables within a macro. This is done through the ^] ad M-^] commands. ^] returns as its result the value of a local variable selected by its argument. M-^] assigns the result of the following command to a local variable selected by the argument to M-^] and returns as its result the previous value held by the variable. You can have up to 10 local variables in each macro. For compatibility with the previous definition of ^], local variable number 1 in each macro invocation is initialized to the argument given to the macro. There is a new mode, rigid_newline, that will cause a newline or carriage return to always insert a newline into the file, even if the following line is blank. Typing ^Z in response to an error message will no longer result in a core dump, but will ask if you want to write out modified buffers before exiting. Regular expression querry replace will check for matching something at the end of a line, and move to the next line if so, so that you will not get into an infinite loop replacing the end of a line with something else. ^N will no longer go beyond the end of the buffer. The displays for search and querry replace have been changed somewhat to give you immediate feedback in response to characters typed before long searches. SUBJECT: new features in EMACS 3.6 There is now a default match in the macro case construct. See the macro memo for details. The display algorithm has been changed somewhat to avoid centering the window every time that you change buffers. This should make macros like abbrev, that changes to another buffer to look up the abbreviation, more acceptable on slow terminals. The special character sequences \< and \> can be used to delimit a word in a regular expression. The regular expression "\" matches an occurance of the word "the" (but not the delimiters on either side). Words are delimited by line boundaries, white space, punctuation, and control characters. The new command ^X+ causes the next item put in the kill stack to be appended to the last item put in the kill stack. See the macros manual for more details and cautions. Minor changes: ^X^S on a buffer without a file name will fail in a macro, rather than asking for a file name. The algorithm used to find sentence beginning and end has been changed somewhat. The change mode command (^X^M) now returns the previous value of the mode set as its result. There is a new mode (end_newline) which when set causes ^N at the end of a buffer to extend the buffer by one line like it used to before version 3.5. New Macros: There is a new macro package called tags in /n1/warren/emacs/macros that facilitates working with a group of related files. See /n1/warren/emacs/macros/CATALOG for details DIRED changes: If you give dired an argument beginning with a dash, it is taken as additional arguments to the ls -al command used to produce a listing for dired. Thus "dired -t" produces a time sorted listing of the current directory, "dired -t /usr/bin" produces a similar listing of /usr/bin. SUBJECT: new features in EMACS 4.0 There is a new terminal support mechanism in EMACS 3.7. This allows me (or anyone) to construct terminal description files for terminals without re-compiling. This will allow many more terminal descriptions and synonyms, easing compatibility problems with EX. It also lets us define "funny" terminals, such as vt100 in 80 column mode. This version makes use of the (crude) terminal improvements in UNIX 3.0 to read-ahead, and hopefully reduce re-display somewhat on slow terminals. System support for this is still very poor, thus there is little I can do. There are lots of new features for DIRED, see the manual page or memo for details. ^X= has been changed to give lots more information. There are two new modes, tspeed and usilent. tspeed is the speed of your terminal in miliseconds per character. tspeed is used by emacs in determining how to update the screen, and is set automatically whenever you enter or exit emacs. usilent causes emacs not to display the command line or output of M-$ commands. This is useful for running unix commands silently from macros. The new command ^X^N allows you to change the buffer name or the file name associated with a buffer without changing the contents of the buffer. The buffer re-display algorithm has been changed. This should eliminate several display bugs and make it much easier to maintain. Report any bugs in terminal support or display. There is a new macro library (/n1/warren/emacs/macros/crypt) for those who like encrypted files. See /n1/warren/emacs/macros/CATALOG for details. SUBJECT: new features in EMACS 4.2 There is a new command line option, "-i " which lets you specify an additional initialization file. The file will be run after your standard init file and before any file name specified on the command line is read in. Recall that init files contain sequences of emacs commands. The algorithm for determining terminal type has changed slightly. It first checks $TERM, then runs your init file, and if terminal type still hasn't been determined, asks for it. The command ^X= has been changed to return status information when invoked in a macro, depending on its argument. You can get file or screen line and character positions. See the macros document for details. ^X^F or ^X^R will not give an error if the file cannot be read when invoked with a negative argument. You can now re-map any command using M-:. This allows, for example, mapping some more convenient key to escape on a terminal where escape is not in a convenient place. NEW modes: notabs mode causes emacs to display tabs as ^I (rather than white space), and to insert spaces up to the next tab boundary when the tab key is pressed (unless the tab is quoted with ^Q). readonly mode causes emacs to refuse to save the current buffer back to the associated file and to not save the buffer in auto save mode. You can still save by writting to a file explicitly with ^X^W. controlify mode allows you to use the character ^^ (control-uparrow) to make the next character a control character. This is primarily useful for using emacs over cu (uucall, cuu) links, which swallow ^S and ^Q, or on a console terminal, which swallows ^O. SUBJECT: new features in EMACS 4.3 Failing Searches inside of macros no longer beep. The mail command has been modified to support the header format used by other unix tools and by the arpanet community. The principal changes are to define the header of a mail item to be all of the lines up to the first blank line, and to have M-^M look for lines beginning To: or Cc: (Instead of TO: and CC:) to specify the recipients. The old format will continue to be supported for some time, and old header lines will be converted to new headers before the mail is sent. New support has been added for terminals that underline, and terminals with a forms-editing style insert character mode (like the concept-100). On terminals with underlining capabilities, the backspace mode is on by default, and positions that are over struck with an underscore will be underscored on the display. Turning backspace mode off causes backspaces to appear as ^H, and nothing to be underscored. Emacs will now send you mail when it is killed (i.e. hung up on from a dialup terminal) and saves buffers. Emacs will only ring the terminal bell after the first "you have mail" warning. If you don't read the mail, the warning will stay on the screen but emacs will not beep. Emacs will now preserve owner and group when writing files. It also warns you when you try to write to a file that you do not own. New command: ^X^A. This command puts the first un-processed command line argument on the kill stack. See macros document for details. MACRO changes: rmail has been extended to provide local, btl-wide, and arpanet signatures, for mail replies depending on the destination. It has also been modified to support standard mail headers. There is a new macro package (vmail) that automatically responds to your mail while you are on vacation. SUBJECT: changes in emacs_4.4 Several bugs in regular expressions having to do with ranges of repeats (\{n,m\}) have been fixed. Also, a new operator '+' has been defined to mean 1 or more occurance of what preceeds it, as it does in common use of regular expressions. The newline function has been changed so that the only time it does not insert a new line is when you are at the end of the current line, the next line is blank, and you are not in "rigid_newline" mode. Autofill and fill buffer have been slightly modified. Autofill will now consider the whole line for possible breaking whenever you type a space or tab. This means that if the line is several words over the line length, and you type space, several words will move to the next line instead of just the last word. Fill buffer will now act just on the marked region (Actually the first character of the first line marked to the last character of the last line marked) when given an argument. The whole region is considered as one block to fill, irrespective of paragraph boundaries or blank lines, although it still avoids breaking lines in such a way that a '.' or ''' is put at the front of a line. The new command ^X@ works just like ^^X<, except that it takes the string used for prompting from the kill stack (or from the user if invoked from the terminal) This allows you to alter the string used for prompting rather than compiling it in. The ^X^O command now returns 1 if both windows contain the same buffer, 0 if the windows contain different buffers, and -1 if it is called in one window mode. Querry replace will now display the from and to strings at the bottom of the screen. It also has a new option 'b' which causes it to go backwards to the previous occurance of the To string. (Note that this means find the previous occurance in the current file and does not find something that has already been replaced!). Query replace also remembers the most recent replacement string and will substitute it for a replacement string consisting of a single '%' character. The grow/shrink window command (^X^^) will now expand or contract the display window while in 1 window mode as well as two window mode. The mode and echo lines remain at the bottom of the screen independent of window size. Emacs will now expand all of the usual shell meta characters in filenames. Thus you can read "*.c", or `logdir usa`/.profile. In all cases, only the first "word" (up to the first whitespace character) is used from the expansion. Thus when specifying files with "*", only the first match is found. The expansion of shell meta characters is slow, since emacs runs a subshell to do it. There is a new mode (display_percent) which will display the current file position as a percentage of the number of lines in the file when turned on. Two new operators have been added to convert between numeric and string values. With an argument of 16, ^X~ will convert the result of the next command to a string and put it on the kill stack. With an argument of 17, The top item on the kill stack is converted to an integer and returned as the result of ^X~. See the macros document for details. Emacs now strips leading tabs and blanks from macro definitions when they are loaded in order to reduce storage requirements. Although it is possible to construct a macro that would be effected by this change, it does not occur with normal coding practices. SUBJECT: changes in emacs_4.5 Added a new command (M-E) which expands an environment variable and returns its value (or a null string) on the kill stack. The return value of M-E is 1 if the string fed to it matched an environment variable, and 0 otherwise. (12/22/81) Added a new option to query replace. When you respond with ".", query replace replaces the current occurance and exits query replace. (12/29/81) New Meta character for file names: (12/30/81) Emacs now interprets the tilde character (~) in filenames as meaning "home directory" like the C shell. Emacs will take the characters following the ~ up to the next word separator as the login name of a user and translate the entire sequence to that user's home directory. A null user name is taken as your own, while the special user name EMACS is mapped to the emacs data directry (contains the macro library and other emacs related files). Thus ~/.profile references your .profile, ~foo/.profile references the .profile for user foo, and ~EMACS/macros/crypt references the crypt macro package. Emacs will now take a full path name to specify the terminal description file either in the TERM environment variable or with the M-t command. This allows a user who does not have control of the terminals database to customize his own terminal description to meet special needs. Emacs now responds to a break signal. When a break is detected, emacs stops what it is doing and prompts the user. You have 5 options: 'y' or ' ' causes a "recursive edit" to be invoked on top of whatever you were doing. Entering ^Z from the recursive edit will return you to the break message. 'n' (no break) causes emacs to resume whatever was in progress when break was detected. '^G' (quit) causes emacs to abandon what was interrupted and unwind to the top level. Any macros or init files being executed are abandoned. '^Z' Causes emacs to exit, after asking about saving any modified buffers. '^]' Causes emacs to crash leaving behind a core dump. (Not terribly useful except for my debugging!) This allows you to interrupt a looping macro or long running search and to escape from it if necessary. MAILER parameter: If you set the environment variable $MAILER, emacs will take it as the name of the command to run to send mail when M-^M is invoked. More editing for string parameters: (3/1/82) You can now edit string-valued parameters (Like filenames or unix commands) Using ^A, ^E, ^F, ^B, ^D, ^K ^U and ^? If you type characters in the middle of a line, they are inserted in place. Keyboard Macros: (6/15/82) You can now tell emacs to remember a sequence of keystrokes to be re-executed whenever you want. ^X( tells emacs to start remembering, ^X) ends the remembered sequence, and ^XE executes it. ^X( and ^X) do not interfere with normal editing, however the saving causes some overhead, as characters received from the keyboard are written one at a time into a file ($HOME/.emacs_kbd) to be re-invoked. Note that you can use this feature to record a backup script of your editing session. Picture Editing Modes: (6/6/82) Two new modes have been added to facilitate editing of pictures: "picture" mode treats the buffer as an electronic blackboard extending infinitely to the right and down. The screen is a window into this blackboard. Text to the right of the window is not shown (As in normal mode, a ! appears at the right margin, but the rest of the line is invisible.) The horizontal position of the left most character position displayed is given on the mode line to the left of the editor name, if it is not zero. The screen automatically scrolls left or right to keep the cursor in view. Several commands behave differently in picture mode: ^N/^P These keep the same character position. If the line being moved to is not long enough, it is extended. ^F/^B These will not go off of the current line. Movement to the right causes the line to extend, movement to the left stops at the left margin. Deletions and ^Y. These treat the region to be deleted as a rectangle on the screen. For example, ^W takes the mark as one corner and the cursor position as the other corner of a rectangle and deletes its contents. Likewise, ^Y retrieves text in the same fashion. (This makes most sense with nodelete mode and overwrite mode. See below). "nodelete" mode directs emacs not to remove text that is deleted via text deletion commands, but to overwrite it with blanks. This should probably be the behavior associated with overwrite mode, but for compatibility, they are treated separaterly. These two modes are intended to work together with overwrite mode to give you an editor designed to work with two dimensional displays of textual information. Using these modes in other combinations may cause somewhat strange behavior. In addition, commands may not behave exactly as expected if the file being edited contains tabs, backspaces, or control and meta characters. If this is a serious problem, I can consider fixing it, but this would not be a simple fix! Enjoy SUBJECT: changes in emacs_4.6 Dired now does recursive edits in the same process, allowing you to peruse a directory structure much quicker. If you try to read a file with dired, it will display the contents, not the directory listing. Emacs has some hooks to interface to the blit terminal. These include a new command (^Xg) for use in positioning from input from the mouse, and a new method of spewing out raw text to the terminal (M-3^X<) that can be used to download control information directly into the terminal, and a feature that enables emacs to discover the window size of the current layer. For more information, see the blit.info file in the macros directory. Emacs will read and write encrypted files via the unix crypt program. The command ^Xk prompts for an encryption key. All subsequent reads, writes, and saves use that key in saving. This also applies to files saved in case of crashes, and to the temporary files used by emacs (though the encryption algorithm used for temporary files is not the standard one). Running emacs with the command line flag "-x" will cause emacs to prompt for a key name before reading the file specified on the command line. For both this and ^Xk, the key is echoed on the screen, but disappears as soon as you hit return. Performance on editing large files should be improved substantially. Startup for all size files should be faster. There is a new option to querry replace. Typing to the prompt during querry replace will cause it to ask for a new string to substitute. Unless you type ^G, this will become the new string to substitute in subsequent instances (^G exits querry replace). Lowercase letter command: M-l. Converts the next character to lower case. Screen goto command: ^Xg This command goes to a screen position. It is intended to help interface to terminals with a mouse, or other positioning device. The command takes its argument and decodes it as: Row=arg%128,Col=arg/128, where row 0,col 0 is the upper left hand corner of the screen. It then goes to the requested position, changing windows if appropriate. Attempts to position to most "illegal" positions result in going to the nearest legal position, however positioning into the echo area or off the bottom of the screen result in no movement. The display of time and "you have mail" has been changed somewhat. The effect should be that both messages will now appear on the line below the mode line when appropriate, and both will be updated when your terminal sits idle. You may notice the mail message appearing and disappearing at different times than it did before. New Modes: ctl_char: The character to be used to specify that the next character is to be made a control character when controlify mode is on. The mode is the ascii value of the character. flow_lim: An integer specifying control over xon/xoff flow control. If flow_lim is non-zero, emacs will enable xon/xoff flow control whenever more than flow_lim characters are sent to the terminal at one time. This will also cause typeahead of ^S or ^Q to be mis-interpreted. This mode should be set only if xon/xoff flow control is absolutely required for correct operation. Under normal conditions, emacs supplies sufficient padding to terminals to allow operation at all speeds without xon/xoff flow control. eofnl: an on/off mode specifying that a newline will be appended to any file written from a buffer not containing a newline. This mode defaults to ON. If you want to edit files that you do not want to end in a newline, turn this mode off. 0707070000020054451006660001460001440000010717550355700317300001500000025030term_supportThe terminal support for EMACS is driven from a directory of terminal type descriptions. This directory contains one file (or link) for each terminal type. The file contains a set of lines of the form: parameter=value EMACS comes with terminal type files to support many of the common types. These are normally kept in the TERMINALS archive file and will be put in the terminals sub-directory of the directory from which emacs is made by the makefile. You can change the makefile to change the location of these files for your location. The terminal support is not the same as the termcap file used by EX. The format that I have chosen is simple, easy to parse by both human and machine, and easy to extend. Each parameter is identified by a two character code. Those parameters that are exactly as in termcap are named as so. The format of the parameter values is quite simple, so as to allow parsing with a simple, efficient, parser. Parameters are either a decimal number, starting with any digit, or are a string, starting with anything else. String parameters contain exactly the characters desired (up to a newline). The only mapping done on string parameters is to map sequences starting with a backslash (\) as follows: \n maps to a newline \(anything else) maps to the backslashed character. (useful for backslashes or for parameters starting with digits. Notice that I do not map octal character specifications, or any of the other commonly used character specifications. The parameters can appear in any order, and only those that apply to a particular terminal should be specified. String parameters contain a printf style string to be sent to the terminal to produce the desired effect. Because printf strings are used, If you need to put a '%' in a string parameter put two % characters (%%) to get a single % output. The exact mappings used are similar to printf, with some limitations. The general format is: %nc, where n is an optional field width (one or more ascii characters), and c is a character specifier. What is done depends on c as follows: %%: Print a single % sign %c: Print the next arg as a character %o: Print the next arg (an int) in octal, with width at least n. %d: Like o, only decimal %p: Print width milliseconds of pad characters. %P: Print width*region number of pad characters. Region is the number of lines or characters in the region effected by the current command. %m: Print the substring in tm determined by the next arg. Width*arg is used as an index into the string parameter "tm", (terminal map) and the next width characters are put out. This is an "escape hatch", which allows you to specify the cursor positioning algorithm for any terminal not covered by the above mechanisms. See the description of the "tm" parameter for more details. %M: Like %m above, except that the map is taken from the parameter "tM". This is provided for terminals which need 2 maps, one for horizantal and one for vertical. The following parameters are available: up=(string) move up one line do=(string) move down one line bc=(string) backward one character nd=(string) forward one character (use only if this is a single character, otherwise omit) ho=(string) home cl=(string) clear entire screen (from any position, leaving cursor at home) cd=(string) clear from here to end of screen ce=(string) clear from cursor to end of line bl=(string) ring the bell cm=(string) absolute cursor addressing (a printf style character string that will produce the correct escape sequence when evaluated with the row and column.) see xbase and ybase. ru=(string) relative up (see relative cursor addressing below) rd=(string) relative down (see relative cursor addressing below) rl=(string) relative left (see relative cursor addressing below) rr=(string) relative right (see relative cursor addressing below) relative cursor addressing: same as cm (above) except moves the cursor relative to its current position. This is meant for terminals like the Tektronix 4025 which have only relative cursor movement commands. If you specify any of the relative values you must specify them all. Don't specify both absolute (cm) and relative cursor positioning because EMACS will use absolute (cm) cursor positioning if both are specified. tm=(string) Terminal Map. tM=(string) Alternate Terminal Map. Terminal maps. These specify the output produced by %m or %M conversions in cursor positioning strings. A "terminal map" is used for terminals that use cursor positioning addresses that are not decimal or octal numbers. The "tm" and "tM" string are tables that EMACS will go into for cursor position addresses. As an example, suppose a terminal with a view width of 80 and a view height of 24. Suppose also that the terminal accepts three digit decimal cursor addresses except that only even numbers are used. EMACS will calculate cursor addresses in ranges of 00-23 and 00-79. The terminal map would look like: tm=\000002004006008010...158 (Note the leading zero must be backslashed to make this a character string.) The corresponding "cm" string might look like: cm=^W%3m%3m If the number of position-dependent characters varies, null characters in tm should be used in tm to pad out shorter map entries. (Real nulls to be output should be have the high order bit set (enter with M-q in EMACS)). pc=(string) pad character. (string containing a single character to be used for padding). al=(string) insert line sequence (see below). dl=(string) delete line sequence These two parameters are used to cause the screen to scroll selectively. The insert line sequence is assumed to insert a single blank line at the line containing the cursor, and scroll the remaining lines on the screen downward. The delete line sequence is assumed to delete the current line, scrolling the remaining lines upward.) im (string) enter insert character mode. This function is assumed to put the terminal into insert character mode. Insert character mode is assumed to push the character under the cursor and those beyond it to the right to accomodate new characters. ic (string) insert character sequence. If the terminal has no insert character mode, but has a sequence that opens up one blank position at the cursor, specify it with ic, and leave im and ei blank. For terminals that need to go into a mode to do inserts, and need a special sequence to open up each position, give both im and ic. ip (string) Insert padding. This string will be printed after every character inserted. It should be a padding specification (%P or %p) to specify delay. Note that you only need to specify this on a terminal that needs padding, and has an insert mode but no ic. Otherwise, just put the padding into ic. ei=(string)overwrite mode sequence (see above). dc=(string)delete character sequence (the character sequence which deletes the character under the cursor and causes the remaining characters on the screen line to move over by one). dm=(int) delete mode. If the terminal needs to be in the same mode used for insert character in order to make delete character work, then this should be 1. The only terminals I know of that need this are the datamedia 2500 and ann arbor ambassador. in=(int) insert mode type. If this is 0, insert and delete character are assumed to move all of the characters to the right of the curssor on the same line, like the adm31, and hp terminals. If this is 1, then insert and delete are assumed to move every character in the rest of the display until a position that has not been written since the last clear is encountered, like the concept-100. sf=(string)scroll sequence (the character sequence needed to scroll the screen with the cursor at the bottom. NULL if the screen can't be scrolled simply.) sr=(string)scroll in reverse (The character sequence needed to scroll the screen down when the cursor is at the top. This is only used to scroll in a region with a terminal like the vt100. This should be NULL if there is no such capability) cs=(string) Scrolling region sequence. If non null, this is a printf style string that will define the scrolling region on the screen when given the top and bottom lines (offset by xbase) as parameters. The only known terminal which uses this feature is the vt100 and its relatives. If cs is set, sr and sf must also be set. vs=(string) initialization escape sequence needed to put terminal in the mode described by these parameters. ve=(string) exit sequence. If present, this sequence is printed whenever you exit from emacs to undo the effects of vs. Vs will be printed whenever you enter emacs. bx=(number) xbase. offset to add to first cursor address parameter by=(number) ybase. offset to add to second cursor address parameter. To accommodate the variety of cursor address escape sequences, the curad parameter is a printf string that when evaluated with the row and column positions, with xbase and ybase added to them, will move to the proper position. rc=(number) 1 if cursor addressing is row and column, 0 if column and row. co=(number) width of screen li=(number) number of lines on screen am=(number) 1 if cursor moves to next line after end of line, 0 otherwise vc=(number) milliseconds of real time needed by terminal for insert/delete line sequence ul= Underline (see below) ue = End underline (see below) eo = (see below) Underscore processing. relevant variables are 'eo', 'ul' and 'ue'. 'eo' should be one if writing over an underlined position clears it, otherwise, make it zero, and emacs will clear the line to get rid of unwanted underscores. 'ul' is a string parameter that contains whatever is needed to print the character with an underline. If the terminal underscores naturally, then 'ul' is %c_. If the terminal has an underscore character mode, then 'ul' is underscore mode on and 'ue' is underscore mode off. If the terminal has an underscore single character command, then 'ul' is 'underscore character command' %c. This is inefficient in underscoring giant blocks of text, but this should be rare. If the terminal does not have underscore but does have reverse video you may use reverse video for underscore. Any escape sequence not available should be omitted. emacs needs some form of cursor addressing (absolute or relative) and clear screen in order to work at all. Other capabilities speed up the display or enhance what is displayed, but are not strictly necessary. The program ttest (made by "make ttest") can be used to test out a new terminal description file. The output is relatively self-explanatory. 0707070000020064371006660001460001440000011010400366732214000001300000011773EMACS.MODSNOTE FROM THE STORE!keeper: With version 4.7c, distributed 6/86, there have been several features added for the UNIX PC. As I have no great desire to redo this file and merge it with EMACS.UNIX.PC - I suggest that you take a peek at both. Note that the OTHER document overrides this one. ========================================================================= You have just received Warren Montgomery's EMACS version 4.6d, compiled for the UNIX PC. This version includes several improvements over the last distribution: * All the "standard" Montgomery macros are included in /usr/lib/emacs/macros. Note that some of these won't work on the UNIX PC because our version of UNIX does not include all the standard UNIX commands (like "egrep"). I have modified the Emacs spell macro though. More on that later. ****************************************************************** THE FOLLOWING DOCUMENTS HAVE BEEN PACKAGED SEPARATELY BY THE STORE! PLEASE ORDER THE PACKAGE EMACSDOCS TO RECEIVE THEM. - the STORE!keeper * All the nroff script files for generating the Emacs Manuals are included in EMACSDOCS. Use "nroff -man filename | col | lp" to print them on a ATT 470 printer (I think this will work for other printers too, but I've only tried it on the 470). * A file describing all the recent changes to emacs is included in EMACSDOCS. Print it out for details. ******************************************************************* * This version includes a shell program interface to emacs that I wrote to allow use of emacs through the default User Agent Unix window, or from a full screen Unix window. See details below. Using the Emacs Spell Macro =========================== For those of you who want to use the interactive spelling error feature you'll need to load and execute the Emacs spell macro. Here's how: 0. You'll need the "Document Preparation" package to use this feature because it uses the "spell" command thats part of the package. Make sure you have it loaded before proceeding. 1. Create a spell variable named "spell" in your .profile file as follows: spell=/usr/lib/emacs/macros/spell export spell Note: this won't get executed until you login again, so be careful if you intend to test Emacs-spell immediately. 2. To use the spell checking macro on a document you've loaded with Emacs you must load the spell macro then execute it. To load the macro you type: ^X^L Emacs will prompt you with "Read file: ". If you've set up your shell variable correctly you can respond with $spell Emacs will silently read the file. If you did'nt set up the shell variable you'll have to enter the full path name of the spell macro instead. Its... /usr/lib/emacs/macros/spell 3. To execute the spell macro, first save any document changes to disk (via ^X^S) then type: ==== === ======== ======= == ==== Esc x Emacs will prompt you with "Macro Name?". Type in: spell Emacs will run the Unix "spell" program on your document and then split the screen into two windows. The upper window displays the misspelled words, the lower window displays your document. Emacs will automatically go through the list of misspelled words one at a time. For each word you may enter one of four characters: ? - Display help information. Type SPACE to exit help. n - Next Word, i.e., you accept this "misspelling", go on to the next misspelled word in the list. d - Add to Dictionary. Emacs will add this word to your extension dictionary (kept in $HOME/.dict) and will not flag this word as a misspelled in the future. SPACE - (Space Bar on keyboard). The word is misspelled and you want to fix it. Emacs positions the cursor to the first occurrance of the word. At this point you can use any Emacs command(s) to correct the error(s). Type ^Z to go to the next occurrance of the misspelled word, or if there are none, back to the Emacs speller. When the misspelled word list is exhausted Emacs will restore full-screen display of your document. Be sure to save your spelling changes to disk before quitting Emacs. I use the spell macro a lot. I suggest you try it! The Emacs Shell Interface ========================= Because I use emacs in the User Agent window environment, I created an interface shell that simplifies emac's window handling on the PC. The shell program is called "e". To run emacs through the interface you would type: e filename instead of: emacs filename The "e" program will ask you for the kind of window you are currently running. There are three choices: f - Full screen window (no User Agent borders on the window). d - Default. The default User Agent Unix window (12 lines). b - Biggest. The biggest User Agent Unix window (i.e., you've resized the default Unix window to the biggest possible via the mouse). Enter the appropriate choice and press RETURN. Emacs will be configured to the appropriate window size and display your file in the window. Good Luck, Don deCourcelle ATT-IS Freehold NJ (201) 577-4480 0707070000020064211006660001460001440000010637430366732361100000700000001023READMETHE FOLLOWING DOCUMENTS ARE NOW IN YOUR DOCS/EMACS FOLDER: dired.man man page for interactive directory editor emacs.man man page for emacs emacs.tm Warren Montgomery's tutorial on EMACS emacs_vt.mm Warren Montgomery's memo on terminal management macro.mm Warren Montgomery's memo on how to write macros recent_changes version by version record of EMACS improvements term_support notes on how terminals are supported EMACS.MODS Don deCourcelle's notes on UNIX PC changes EMACS.UNIX.PC Version 4.7c notes on UNIX PC modifications 0707070000020007621007770001460001440000011007360355716760100001100000000046MAKEcpiocat Files | cpio -ocBv > EMACSDOCS+IN 0707070000020075721007770001460001440000011007370355716753700001100000000044MAKEflopcat Files | cpio -ocBv > /dev/fp021 0707070000020100371006440001460001440000011007400366732137400001600000040141EMACS.UNIX.PCWelcome to emacs for the unix/pc. You should have all of the files necessary for installation of emacs. To do the installation, log in as root on the machine and run the file "install". This will unpack several archives and install them in /usr/lib/emacs, where the binary files distributed here expect them. It will install the binaries of emacs, dired, and ecomp, in /usr/bin. THE SCREEN: Emacs for the unix/pc is exactly the same as conventional emacs, except for a few additions that exploit the mouse and screen on the pc. Emacs will run in any size window, though remember that it uses 4 lines for status and prompting, so you should create a large window for it. Emacs determines the window size from the values returned by WIOCGETD, not from the LINES and COLUMNS environment variables, which are frequently inacurate. As distributed, emacs comes with a standard .emacs_init that loads a set of macros designed to work with the mouse, and another that loads a "standard" environment, that includes some commonly used macros and also a macro that will automatically set your file modes depending on what type of file you are editing. If you do not wish this, take the line that loads "standard" out of the file /usr/lib/emacs/.emacs_init. You can also install your own private init file in your home directory, in which case it will not read the one in /usr/lib/emacs. THE MOUSE: On the console of the Unix/PC, emacs exploits the mouse. The mouse interface loaded by default is built almost entirely using macros, so that you may customize it if you wish. (See the description below of the mouse software). The interface is patterned after the interface given by the "empty" terminal emulator on the dmd5620, but other mouse based interfaces could easily be implemented. Basically, button 1 of the mouse (on the left with the cord away from you) is used for pointing at text. Pushing and releasing this button causes the cursor to move to the text you pointed at. Pushing the button twice with the mouse in the same place not only moves you to that spot but also retrieves the result of the last deletion and places it there. In either case, if you click on an area of the screen in which no text is being displayed, it will move you to the closest "real" position. If you push down button one and hold it down while moving the mouse, you will mark a region between the point where you push down and where you release it. Emacs will set a mark where you first pushed and leave the cursor where you release it. Emacs will highlight the region in inverse video. If you are in picture mode, the region is marked as a rectangle with corners where your starting and stopping points were, whereas otherwise it is simply the text in between. The highlighting for this and other actions will disappear when you type anything. If you use this method to define a region, and then click (push down and release) the mouse again while you are still at the endpoint of the region, emacs will delete the highlighted region. Recall that you can restore it by clicking twice on any point on the screen. This is a simple way to do cut and paste editing with the mouse. Button 2 of the mouse (the middle one) is used for selecting objects and picking up text without deleting it. If you click once on button 2, you cause the object that you are pointing at to be marked. The definition of what constitutes an object depends on what kind of file you are editing and what character you pointed at. In general, the macro package recognizes 3 kinds of files, C program source (ends in .c or .h), lisp source (ends in .l or .e), and text (anything else). For all files, if you point at a printing character, it selects and marks the word containing that character. If you point at a position beyond the end of a line on the screen, it selects that line. For text, if you point at a blank or tab, it selects the sentence containing that blank (or the one preceding it if you point between sentences). For C and Lisp, pointing at a blank causes emacs to try to locate the nearest enclosing object, which may be a character string, a balanced set of parentheses, braces, or brackets, or a matching pair of slashes (comments in C or eml, the lisp-like emacs macro language). Since it is impossible to determine the exact structure without parsing the whole file, it will occasionally get confused and not mark what you intended. Positioning the mouse over a brace, bracket, slash, quote, or parenthesis and clicking button two will also try to find the match for that character. Again, the selected area is highlighted temporarily so you can see what you have selected. If you hold down button two and sweep out a region before releasing it, the area marked is all of the text between the WORDS that you clicked on. This can be useful in moving text around in making it easier to get the cursor in the right place to pick up whole words. Just as with button 1, button two operates slightly differently when hit for a second time in the same place. It causes the marked area to be picked up without deleting it. This is useful for copying text. The text picked up this way can be placed by clicking twice with button 1 where you want it. Here is a summary of all of the useful combinations. Single click of button 1: Move cursor to mouse Single click of button 2: Move cursor and mark around an object Sweep out area with button 1: Mark a region around the area Sweep out area with button 2: Mark a region on word boundaries Sweep (1 or 2) and then click button 1: Kill the region Sweep and click button 2: Pickup the region. Click button 1 twice: Restore the list kill or pickup Click button 2 twice: Pick up the selected object Click 2 then 1 in same place: Kill the selected object MENUES: Button 3 provides a crude menu capability. Emacs menus are at this point not the same as those of other unix/pc software. When you push down button 3, emacs will display a list of choices on the screen. You should move the cursor to the same line as the choice you want and release it to make a selection. If you want none of the listed choices, just move to another line before releasing the mouse. These menus work a lot like the pull-down menus on the 5620. One thing to note is that emacs will get very confused if your window is not large enough to hold the menu. All of the menus will fit in the default window, but may not fit in smaller ones. The macros implement a hierarchy of menus, each one displaying functions to be performed or other menus. Selecting a menu causes it to be displayed the next time button 3 is depressed. Some menus return immediately to the top level (standard menu) while others remain active. You can customize any menus you like by reprogramming the macros (see below). The following menus can be reached by various selections: Standard menu: This is the top level menu and lists only other menus and the command to exit emacs. Invoking exit will exit gracefully, asking first about modified buffers. Browser menu: This menu has functions appropriate to browsing through the text, such as setting and showing where the mark is. Edit menu: This menu has commands for cutting and pasting text. Re-paste causes the last thing pasted to be removed and replaced by the next most recent deletion (or picked up text). You can go back through up to 16 deletions by repeatedly invoking this function. Modes menu: This menu displays the current state of some of the mode parameters by showing the mode name in lowercase if it is off and in uppercase if it is on. You can toggle one of these modes by selecting it from the menu. Buffer Menu: This menu displays your buffers. You can change buffers by selecting one of the displayed buffers. If you select anything else, you stay in your current buffer. Graphics Menu: This menu has operations that allow you to draw crude "typewriter art" in the buffer. To invoke these, you should select "graphics on", which sets picture mode and some of the related modes to allow you to use the buffer as a blackboard. You will notice that regions are marked as rectangles when you have graphics mode on. You will also notice that cutting regions results in having a rectangular area blanked out, rather than having it removed from the buffer. Likewise, restoring a cut causes it to overlay what is there already. These simplifications provide a simple cut and paste model of editing for editing pictures. You should turn graphics off on the menu before trying to edit normal information. The various entries work as follows: Draw box -- Draws a box around the current region using underscores and vertical bars. Draw ellipse -- Draws an approximation of an ellipse in the current region using '@' characters. Some such ellipses come out sensibly when run through the gc filter. Draw line -- Draws an approximation of a line between the mark and current cursor position. Center text -- Centers what you type in as you type it until you hit escape. CUSTOMIZING EMACS: The UNIX/PC version of emacs comes with a lot of custom features implemented in macros. You can change these macros to customize the behavior of Emacs to your liking. The following is a rough roadmap of the macros used to implement the mouse and keyboard features. You should read the macros manual for more complete information, however simple modifications, like changing the behavior of function keys, can be made without extensive knowledge of macro programming. In general, for safety make a copy of any macro file you change. After you get it to successfully compile with ecomp, install it in /usr/lib/emacs/macros and it will automatically become current when you next invoke emacs. THE KEYBOARD KEYS: The special keys on the UNIX/PC send escape codes, which are interpreted by macros. The macros that do this are all in pc7300.e. Basically, the arrow keys and many of the others on the lower right of the keyboard send a sequence of escape followed by '[' followed by a single letter. The ansii-keys macro is bound to escape-[ and reads the next letter to determine what was hit. It uses a case statement to dispatch to an action for each key. You can change these or add new keys by changing or adding cases. Be very careful to balance parentheses if you do. Most of the keys on the lower left of the keyboard send sequences beginning with escape-N. There is a similar macro that reads the next key and dispatches them. Some of the other special keys (I think most of the grey keys above), send sequences beginning escape-O. I have no handler for these at present, but if you wish, simply add one similar to the others. THE MOUSE: The mouse sends a sequence beginning escape-[-?. Thus it too is dispatched by ansii-keys. All of the work, however, is done in the mouse macro. The mouse macro decodes the sequence sent by the mouse to determine the screen position and button state. The screen position is translated from pixels to characters, and then recoded as column*128+line for the goto-screen command. The decoding depends on the font size, which is initialized in the macro Load_Macro_Hook for the default font. If you change font size, change the assignments in this macro. The mouse macro implements a finite machine driven by transitions in the button state. The state machine is in a case command, driven by the previous and current button states (held in a global variable). Basically the macro simply records the current position on a down-push of button 1 or 2 for later reference. The cases for an up transition of buttons 1 and 2 do all of the positioning. The button 1 case looks at the previously stored down position to determine whether this is a touch or a sweep, and also looks at the previous touch position to see if this is a double touch. The case for button 2 does similar work, but also invokes the appropriate object selection procedure based on a global variable "MM", which indicates the Mouse Mode determined by the file type. MM is set by the fmodes macro. The selection procedures are in other macro files. MENUS: Menus are driven by transitions of mouse button 3. On a down transition, the mouse macro invokes the current "menu" macro with an argument of 0. On an up transition, it invokes it with an argument of the item selected. In order to allow the current menu macro to be re-selected, the menu macro is actually invoked by running a character command through a somewhat tricky piece of code. It works by assigning the command to run to the "invocation character", and then running "execute", that causes that command to be run. The macros that implement menus are all similar in form. They have a case statement to decode the argument, and on an argument of 0 put up the appropriate menu. The menuhit macro used to do this sets a global variable used by the mouse macro to determine whether an up transition of button 3 falls in the menu or not. The menuhit macro takes the strings to put up (bottom to top), and the count. The top string returns '1' when selected, so the arguments to menuhit are essentially in reverse order. The other cases implement the selections. Many of these simply assign another macro to the menu selection character command. This must be done with the rather funny sequence given, of pushing the macro name onto the kill stack and then running assign-macro-to-key due to limitations in the ecomp compiler. It is fairly easy to change any of these menu items or their actions just by changing or adding cases and changing the menu text. One other technique deserves mention, which is that a couple of the selections work by putting characters into the input stream which will be seen as user input when the macros exit. (Exit is a good example of this). This is perfectly safe to do, but a maximum of two characters can be pushed back this way. The macros reached by selection from the menus are all in the source provided. They are automatically loaded when first invoked if not part of pc7300. Note that there is a small trick to be observed in that automatic loading works only when the macro is invoked, not when it is bound to a key. To avoid errors here, there are gateway macros defined in pc7300 for some functions that are implemented elsewhere. These gateways simply call other macros, but are needed to avoid getting a macro not found error when the key binding for the menu is made. The modes menu is one that you may wish to customize. It is straight-forward, and you can use the cases already there as a model. Be sure that the count of menu items passed to menuhit matches the number of modes you put in the menu. Unlike the netty version of the modes menu, this version does not do any fiddling in the buffer, so it will handle all modes without trouble. HIGHLIGHTING: The screen highlighting of regions is done by "show-region". This macro calls a hook in emacs (xor-region) to invert the region. All of the intelligence for figuring out how to show the region is in the underlying hook, however the logic for doing it is in the macro. If you change this, be aware that emacs does not record the fact that the screen has been inverted, so the display will become confused if you do any writing to the screen between inversions. AUTOMATIC FILE MODES: The automatic setting of file modes is done by the fmodes macro. This macro is invoked by the Post_Read_Hook and Enter_Buffer_Hook macros defined in the standard package. Note that these are invoked on every buffer change or file read, including those for internal purposes. This uses lots of cycles, but the pc7300 seems to have a lot of cycles to burn and it doesn't slow you down. The algorithm for determining file type is quite simple, it just looks at the name. Some of the customizations are in the fmodes package, while others are in other macro packages. You may wish to change the settings to your liking, or even generate your own new file types. If you do so, remember to set MM appropriate, or if you wish add new types to the mouse macro for this. If you find bugs or create interesting additions to the library, I would appreciate comments and macro source for additions for inclusion in future distributions. 0707070000020100371006440001460001440000011007400366732137400001300000000000TRAILER!!!the menu or not. The menuhit macro takes the strings to put up (bottom to top), and the count. The top string returns '1' when selected, so the arguments to menuhit are essentially in reverse order. The other cases implement the selections. Many of these simply assign another macro to the menu selection character command. This must be done with the rather funny sequence given, of pushing the macro name onto the kill stack and then running assign-macro-to-key due to limitations in the ecomp compiler. It is fairly easy to change any of these menu items or their actions just by changing or adding cases and changing the menu text. One other technique deserves mention, which is that a couple of the selections work by putting characters into the input stream which will be seen as user input when the macros exit. (Exit is a good example of this). This is perfectly safe to do, but a maximum of two characters can be pushed back this way. The macros reached by selection from the menus are all in the source provided. They are automatically loaded when first invoked if not part of pc7300. Note that there is a small trick to be observed in that automatic loading works only when the macro is invoked, not when it is bound to a key. To avoid errors here, there are gateway macros defined in pc7300 for some functions that are implemented elsewhere. These gateways simply call other macros, but are needed to avoid getting a macro not found error when the key binding for the menu is made. The modes menu is one that you may wish to customize. It is straight-forward, and you can use the cases already there as a model. Be sure that the count of menu items passed to menuhit matches the