diff --git a/Makefile b/Makefile index 5ab86796..c0bf2e86 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ EMULATOR ?= simh -SRC = system syseng sysen1 sysen2 sysnet kshack midas _teco_ rms klh dragon channa -MINSYS = _ sys sys3 device +SRC = system syseng sysen1 sysen2 sysnet kshack dragon channa midas _teco_ emacs rms klh +MINSYS = _ sys sys3 device emacs _teco_ RAM = bin/boot/ram.262 NSALV = bin/boot/salv.rp06 DSKDMP = bin/boot/dskdmp.rp06 diff --git a/README.md b/README.md index 2a47c0d8..754afa00 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ from scratch. 5. Remaining programs are rebuilt: - TECO, editor. + - EMACS, binaries only. - DUMP, tape backup and restore. - PDSET, set time and date. - KSFEDR, manipulate front-end file system. diff --git a/bin/_teco_/tecpur.1211 b/bin/_teco_/tecpur.1211 new file mode 100755 index 00000000..b0d1dd85 Binary files /dev/null and b/bin/_teco_/tecpur.1211 differ diff --git a/bin/emacs/[pure].162 b/bin/emacs/[pure].162 new file mode 100755 index 00000000..1da555f8 Binary files /dev/null and b/bin/emacs/[pure].162 differ diff --git a/bin/emacs/emacs.:ej b/bin/emacs/emacs.:ej new file mode 100755 index 00000000..6f5955c5 Binary files /dev/null and b/bin/emacs/emacs.:ej differ diff --git a/bin/emacs/ts.126 b/bin/emacs/ts.126 new file mode 100755 index 00000000..ec3e872a Binary files /dev/null and b/bin/emacs/ts.126 differ diff --git a/bin/sys/ts.emacs b/bin/sys/ts.emacs new file mode 120000 index 00000000..fd6f98b9 --- /dev/null +++ b/bin/sys/ts.emacs @@ -0,0 +1 @@ +emacs/ts.> \ No newline at end of file diff --git a/bin/sys3/ts.emacs b/bin/sys3/ts.emacs new file mode 120000 index 00000000..798d9fdb --- /dev/null +++ b/bin/sys3/ts.emacs @@ -0,0 +1 @@ +emacs/ts.126 \ No newline at end of file diff --git a/doc/README.md b/doc/README.md index 42993c37..1c8f1851 100644 --- a/doc/README.md +++ b/doc/README.md @@ -9,6 +9,7 @@ - DUMP: [manual](_info_/dump.info), [format](sysdoc/dump.format) - TECO: [primer](_teco_/teco.primer), [manual](info/tecman.20), [commands](_teco_/tecord.1132) +- EMACS: [manual](emacs1/emacs.guide), [info](info/emacs.147) - CRTSTY: [manual](info/crtsty.39) - TCTYP: [manual](_info_/tctyp.order) - DSKDUMP: [commands](sysdoc/dskdmp.order) @@ -34,6 +35,7 @@ The `$` character represents typing ESC. | ln f1 f2 | $^O f1,f2 | :link f1,f2 | | mv f1 f2 | $$^O f1,f2 | :rename f1,f2 | | mv file dir | | :move file,dir | +| emacs | | :emacs | | ps | $$v | :listj | | killall -9 id | id$j $^X | :job id :kill | | sudo -u u cmd | u$^S cmd | | diff --git a/doc/emacs/emacs.index b/doc/emacs/emacs.index new file mode 100755 index 00000000..7f3a6441 --- /dev/null +++ b/doc/emacs/emacs.index @@ -0,0 +1,719 @@ + +Meta-< goes to beginning of buffer. + + (Previous Screen) + Meta-V + Rubout or Delete : Control-D +<-------------------- : ---------------------> + (Deletes Backward) : (Deletes Forward) + (Previous Line) + Control-P + : + : + Control-A ........ Control-B .... Cursor .... Control-F ........ Control-E +(Head of Line) (Move Backward) : (Move Forward) (End of Line) + : + Control-N + (Next Line) + ---------> : + Control-T : Control-K + <--------- : =====================> +(Transpose Characters) : (Kills to end of line) + : + Control-V + (Next Screen) + + + Meta-> goes to end of buffer. + +Emacs commands try to be very regular. There are Meta- commands similar +to these Control- commands which work on words in much the same way as +these commands work on characters. Control-Meta- commands work in similar +ways on Lisp S-Expressions. Watch for and make use of these trends. They +can really reduce the number of things you have to remember. + +--------------------------- Useful Sub-Topics ------------------------------ + + *** HELP *** + +The magic [Help] character is Top-H (or on Ascii keyboards: Control-_ H). +It will offer help of various sorts almost anywhere at any time. In most +places, it will offer you a menu of several possible kinds of +documentation, where you must type another character to get the desired +kind of help. At such times, the following are especially useful: + +[Help] C will read another character and describe its action. You should + use this to describe any commands you read about in this document + which you would like to understand in full detail. The info given + here is intended only as an index and is not complete. + +[Help] ? will give you a description of the several other very useful + options available through the [Help] facility. + + *** QUIT *** + +Control-G aborts all currently executing operations, flushes + typeahead, and leaves you at the innermost invocation of ^R-mode. + +Control-] aborts a recursive ^R-mode (such as RMail Reply -- exits + without sending any mail). + + Emacs Command Index Page 2 + + Useful META- Commands + (On an ascii keyboard, Meta- is Altmode ) + +Meta-[ goes to Beginning of Paragraph + + Control-X Rubout +<=========================== + (Delete Sentence Backward) + + Meta-Rubout or Meta-Delete Meta-D +<--------------------------- ---------------------> + (Deletes Word Backward) (Deletes Word Forward) + + Meta-A ........ Meta-B .... Cursor .... Meta-F ........ Meta-E +(Head of Sentence) (Back Word) (Forward Word) (End of Sentence) + + ---------> + Meta-T Meta-K + <--------- <====================> + (Transpose Words) (Kills Current sentence) + + + Meta-] goes to End of Paragraph + +------------------------------------------------------------------------------ + + Useful CONTROL-META- Commands + (On an ascii keyboard, C-M- is Control-C ) + +C-M-[ goes to Beginning of Defun + + + C-M-Rubout or C-M-Delete C-M-K + <---------------------- ---------------------> + (Deletes S-Expression Backward) (Deletes S-Expression Forward) + + (Backward Up List) + C-M-U + : + (Backward List) + C-M-P + : + C-M-A ............. C-M-B ....... Cursor ....... C-M-F .......... C-M-E +(Beginning of S-Exp) (Back S-Exp) : (Forward S-Exp) (End of S-Exp) + C-M-N + (Forward List) + ---------> : + C-M-T C-M-D + <--------- (Forward Down List) +(Transpose S-Expressions) + + C-M-] goes to End of Defun + Emacs Command Index Page 3 + + *** EXTENDED COMMANDS *** + +Meta-X runs the extended command set completing reader (MM Commands). + + *** SPECIAL PREFIX CHARACTERS *** + +Control-X (Dispatch Character) + reads exactly one more character. What that character is + will decide what command is run. These commands, called the + 'Control-X commands' can be documented by typing Control-X ? + +Control-U (Argument Prefix) + is the 'Universal' argument prefix. + + Control-U digit digit ... digit non-digit-command + + will accumulate the digits as a numerical argument to the + next command. For example, + + Control-U 1 2 3 Control-B + + moves backward 123 characters. If not followed by digits, + Control-U will multiply the arg to the next command by 4. eg, + + Control-U Control-B + + will move backward 4 characters - note that + + Control-U Control-U Control-B + + will move backward 16 characters. + + *** PREFIX CHARACTERS FOR ASCII TERMINALS (Non-TV's) *** + +Control-^ - Prefix Control Altmode - Prefix Meta +Control-C - Prefix Control-Meta Control-\ - Prefix Meta + +These commands read the next character and adjust it appropriately. +For example, Control-C C is equivalent to Control-Meta-C and Altmode C is +equivalent to Meta-C. + + *** QUOTE *** + +Control-Q is the EMACS quote character. The next character typed + after it will be inserted literally into the buffer rather than + having its normal effect. + +------------------------------------------------------------------------------ + +Disclaimer: This documentation lies about one thing. There is a difference + between Control-H and Backspace, Control-I and Tab, Control-J + and Linefeed, etc. but most of these pairs of keys do identical + things and the distinction would not be interesting to most + people, so for simplicity they are treated as synonymous here + when in fact they are not. Sophisticated users should see other + documentation for more details. + + Emacs Command Index Page 4 +****************************************************************************** +* Cursor Control * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + H : Backspace or : Backward Character + : Control-H : +------------------------------------------------------------------------------ + : Control-A : Beginning of Line + :----------------:------------------------------------------------- + A : Meta-A : Beginning of Sentence + :----------------:------------------------------------------------- + : Control-Meta-A : Beginning of Defun +------------------------------------------------------------------------------ + : Control-B : Backward Character + :----------------:------------------------------------------------- + B : Meta-B : Backward Word + :----------------:------------------------------------------------- + : Control-Meta-B : Backward S-Expression +------------------------------------------------------------------------------ + D : Control-Meta-D : Down List +------------------------------------------------------------------------------ + : Control-E : End of Line + :----------------:------------------------------------------------- + E : Meta-E : End of Sentence + :----------------:------------------------------------------------- + : Control-Meta-E : End of Defun +------------------------------------------------------------------------------ + : Control-F : Forward Character + :----------------:------------------------------------------------- + F : Meta-F : Forward Word + :----------------:------------------------------------------------- + : Control-Meta-F : Foward S-Expression +------------------------------------------------------------------------------ + : Meta-M : Move to beginning of text on current line + M :----------------:------------------------------------------------- + : Control-Meta-M : Move to beginning of text on current line +------------------------------------------------------------------------------ + : Meta-[ : Move to beginning of paragraph + :----------------:------------------------------------------------- + [ : Control-Meta-[ : Move to beginning of defun + :----------------:------------------------------------------------- + : Control-X [ : Move to beginning of page +------------------------------------------------------------------------------ + : Meta-] : Move to beginning of paragraph + :----------------:------------------------------------------------- + ] : Control-Meta-] : Move to beginning of DEFUN + :----------------:------------------------------------------------- + : Control-X ] : Move to beginning of page +------------------------------------------------------------------------------ + Emacs Command Index Page 5 +****************************************************************************** +* CURSOR CONTROL (cont'd) * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Control-N : Move to Next Line + :----------------:------------------------------------------------- + N : Meta-N : Move to Next Comment Line + :----------------:------------------------------------------------- + : Control-Meta-N : Move across Next List +------------------------------------------------------------------------------ + : Control-P : Move to Previous Line + :----------------:------------------------------------------------- + P : Meta-P : Move to Previous Comment Line + :----------------:------------------------------------------------- + : Control-Meta-P : Move across Previous List +------------------------------------------------------------------------------ + U : Control-Meta-U : Up List +------------------------------------------------------------------------------ + : Control-V : View Next Page + V :----------------:------------------------------------------------- + : Meta-V : View Previous Page +------------------------------------------------------------------------------ + X : Control-X ^X : Exchange point (cursor position) and mark +------------------------------------------------------------------------------ + +****************************************************************************** +* DISPLAY * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + L : Form or : Clears screen and redisplays + : Control-L : +------------------------------------------------------------------------------ + : Meta-R : Move cursor relative to screen position + R :----------------:------------------------------------------------- + : Control-Meta-R : Reposition window +------------------------------------------------------------------------------ + Emacs Command Index Page 6 +****************************************************************************** +* SEARCHING * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + R : Control-R : Reverse Search +------------------------------------------------------------------------------ + S : Control-S : Search (forward) +------------------------------------------------------------------------------ + +****************************************************************************** +* MOVING TEXT * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Control-T : Transpose Characters + :----------------:------------------------------------------------- + T : Meta-T : Transpose Words + :----------------:------------------------------------------------- + : Control-Meta-T : Transpose S-Expressions + :----------------:------------------------------------------------- + : Control-X ^T : Transpose Lines + :------------------------------------------------------------------ + : Control-X T : Transpose Regions +------------------------------------------------------------------------------ + +------------------------------------------------------------------------------ + +****************************************************************************** +* PREFIX CHARACTERS * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + Altmode : Altmode : Meta-Prefix Character + : : (doesn't do this in a mini-buffer) +------------------------------------------------------------------------------ + \ : Control-\ : Meta-Prefix Character + : : (good for use in mini-buffer) +------------------------------------------------------------------------------ + C : Control-C : Control-Meta Prefix Character +------------------------------------------------------------------------------ + Q : Control-Q : Quote Prefix (Inserts next character typed) +------------------------------------------------------------------------------ + U : Control-U : 'Universal' Argument Prefix +------------------------------------------------------------------------------ + X : Control-X : Control-X Command Prefix +------------------------------------------------------------------------------ + Emacs Command Index Page 7 +****************************************************************************** +* READING AND WRITING FILES * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + F : Control-X ^F : Find File +------------------------------------------------------------------------------ + Q : Control-X ^Q : Inhibit Auto-Writeback +------------------------------------------------------------------------------ + R : Control-X ^R : Read File +------------------------------------------------------------------------------ + S : Control-X ^S : Save File (under default filename) +------------------------------------------------------------------------------ + V : Control-X ^V : Visit File +------------------------------------------------------------------------------ + W : Control-X ^W : Write File (reads a filename) +------------------------------------------------------------------------------ + +****************************************************************************** +* BUFFER MANIPULATION * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + A : Control-X A : Append to Buffer +------------------------------------------------------------------------------ + : Control-X B : Select Buffer + B :----------------:------------------------------------------------- + : Control-X ^B : List Buffers +------------------------------------------------------------------------------ + K : Control-X K : Kill Buffer +------------------------------------------------------------------------------ + Emacs Command Index Page 8 +****************************************************************************** +* INDENTATION * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Tab or : + : Control-I : Indent According to Mode + :----------------:------------------------------------------------- + I : Meta-I : Indent to Tab Stop + :----------------:------------------------------------------------- + : Control-Meta-I : Indent for Lisp + :----------------:------------------------------------------------- + : ^X Tab : Indent Rigidly +------------------------------------------------------------------------------ + J : Linefeed or : + : Control-J : Indent New Line +------------------------------------------------------------------------------ + Q : Control-Meta-Q : Indent All Lines in Next S-Expression +------------------------------------------------------------------------------ + ; : Meta-; : Indent for Comment +------------------------------------------------------------------------------ + +****************************************************************************** +* BLANK LINES AND CARRIAGE RETURNS * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Control-M : Insert a Carriage-Return (TV's only) + M :----------------:------------------------------------------------- + : Return : Insert a Carriage-Return + Linefeed (CRLF) +------------------------------------------------------------------------------ + : Control-O : Open a Blank Line (insert a CRLF after cursor) + :----------------:------------------------------------------------- + O : Control-Meta-O : Open a Blank Line; move text vertically down + :----------------:------------------------------------------------- + : Control-X ^O : Kill Blank Lines around this line's end +------------------------------------------------------------------------------ + Emacs Command Index Page 9 +****************************************************************************** +* MARKING A REGION * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Meta-H : Mark Paragraph + :----------------:------------------------------------------------- + H : Control-Meta-H : Mark S-Expression + :----------------:------------------------------------------------- + : Control-X H : Mark Whole Buffer +------------------------------------------------------------------------------ + P : Control-X ^P : Mark Page +------------------------------------------------------------------------------ + +****************************************************************************** +* TEXT DELETION * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Rubout : Delete character backward + :----------------:------------------------------------------------- + : Meta-Rubout : Delete word backward + Rubout :----------------:------------------------------------------------- + or : Control-Meta- : Delete s-expression backward + Delete : Rubout : + :----------------:------------------------------------------------- + : Control-X : Delete sentence backward + : Rubout : +------------------------------------------------------------------------------ + : Control-D : Delete character forward + D :----------------:------------------------------------------------- + : Meta-D : Delete word forward +------------------------------------------------------------------------------ + : Control-K : Kill Line Forward + :----------------:------------------------------------------------- + K : Meta-K : Kill Sentence Forward + :----------------:------------------------------------------------- + : Control-Meta-K : Kill S-Expression Forward +------------------------------------------------------------------------------ + W : Control-W : Kill Region +------------------------------------------------------------------------------ + ; : Control-Meta-; : Kill Comment +------------------------------------------------------------------------------ + Emacs Command Index Page 10 +****************************************************************************** +* TEXT COPYING * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + A : Control-X A : Append Region to a Specified Buffer +------------------------------------------------------------------------------ + : Meta-W : Copy Region + W :----------------:------------------------------------------------- + : Control-Meta-W : Make next kill join previous in kill buffer +------------------------------------------------------------------------------ + +****************************************************************************** +* RESTORING DELETED/COPIED TEXT * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Control-Y : Yank last item from kill buffer into buffer. + :----------------:------------------------------------------------- + Y : Meta-Y : Yank 'the kill before that' (only after ^Y) + :----------------:------------------------------------------------- + : Control-Meta-Y : Mini-buffer only: Yank last mini-buffer + : : command string. + : : RMAIL Reply only: Yank text of message. + : : (Not defined anywhere else) +------------------------------------------------------------------------------- + +****************************************************************************** +* COMMENT FIELDS * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Meta-J : Indent New Comment Line + J :----------------:------------------------------------------------- + : Control-Meta-J : Indent New Comment Line +------------------------------------------------------------------------------ + N : Meta-N : Move to Next Comment Line +------------------------------------------------------------------------------ + P : Meta-P : Move to Previous Comment Line +------------------------------------------------------------------------------ + : Meta-; : Indent for Comment + :----------------:------------------------------------------------- + ; : Control-Meta-; : Kill Comment + :----------------:------------------------------------------------- + : Control-X ; : Set Comment Column +------------------------------------------------------------------------------ + Emacs Command Index Page 11 +****************************************************************************** +* SUBSYSTEMS * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + D : Control-X D : DIRED (a Directory Editor) +------------------------------------------------------------------------------ + I : Control-X I : INFO (like :INFO at DDT) +------------------------------------------------------------------------------ + M : Control-X M : MAIL (send MAIL to other users) +------------------------------------------------------------------------------ + R : Control-X R : RMAIL (like :RMAIL at DDT) +------------------------------------------------------------------------------ + +****************************************************************************** +* TECO RELATED COMMANDS * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + G : Control-X G : Get from Q-Register +------------------------------------------------------------------------------- + X : Control-X X : Put in Q-Register +------------------------------------------------------------------------------- + +****************************************************************************** +* EXTENDED COMMANDS * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Meta-X : Extended Command + X :----------------:------------------------------------------------- + : Control-Meta-X : Extended Command, reading its own arguments +------------------------------------------------------------------------------ + Emacs Command Index Page 12 +****************************************************************************** +* QUIT/EXIT COMMANDS * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Control-Meta-C : Exit recursive edit + C :----------------:------------------------------------------------- + : Control-X ^C : Exit Job Temporarily - Return to Superior +------------------------------------------------------------------------------ + G : Control-G : Abort currently executing command +------------------------------------------------------------------------------ + ] : Control-] : Abort a recursive ^R-mode + : : (eg, flush RMAIL Reply without sending mail) +------------------------------------------------------------------------------ + Z : Control-Z : Exit Job Temporarily - Return to superior +------------------------------------------------------------------------------ + +****************************************************************************** +* SETTING COLUMN VARIABLES * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + F : Control-X F : Set Fill Column +------------------------------------------------------------------------------ + N : Control-X ^N : Set goal column (for ^N and ^P commands) +------------------------------------------------------------------------------ + +****************************************************************************** +* DIRECTORY HACKING COMMANDS * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Control-X D : DIRED (a Directory Editor) + D :----------------:------------------------------------------------- + : Control-X ^D : Directory Listing (of files related to buffer) +------------------------------------------------------------------------------ + Emacs Command Index Page 13 +****************************************************************************** +* CASIFYING * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + C : Meta-C : Capitalize Word +------------------------------------------------------------------------------ + : Meta-L : Lowercasify word + L :----------------:------------------------------------------------- + : Control-X ^L : Lowercasify Region +------------------------------------------------------------------------------ + : Meta-U : Uppercasify word + U :----------------:------------------------------------------------- + : Control-X ^U : Uppercasify region +------------------------------------------------------------------------------ + +****************************************************************************** +* FORMATTING TEXT * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + : Meta-G : Fill Text Region + G :----------------:------------------------------------------------- + : Control-Meta-G : Grind Lisp or Macsyma code +------------------------------------------------------------------------------ + Q : Meta-Q : Fill paragraph +------------------------------------------------------------------------------ + S : Meta-S : Center text on line +------------------------------------------------------------------------------ + +****************************************************************************** +* INFORMATION ABOUT BUFFERED TEXT * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + L : Control-X L : Count Lines on Current Page +------------------------------------------------------------------------------ + = : Control-X = : Info about Screen and Buffer Position +------------------------------------------------------------------------------ + Emacs Command Index Page 14 +****************************************************************************** +* COMMANDS FOR DEALING WITH 2 WINDOWS * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + 1 : Control-X 1 : Return to 1-window mode +------------------------------------------------------------------------------ + 2 : Control-X 2 : Enter 2-window mode (use other window) +------------------------------------------------------------------------------ + 3 : Control-X 3 : Enter 2-window mode (use same window) +------------------------------------------------------------------------------ + 4 : Control-X 4 : Enter 2-window mode with fancy options +------------------------------------------------------------------------------ + O : Control-X O : Move to Other Window +------------------------------------------------------------------------------ + V : Control-Meta-V : View Next Page of other window +------------------------------------------------------------------------------ + ^ : Control-X ^ : Grow Window +------------------------------------------------------------------------------ + +****************************************************************************** +* CHANGING VIRTUAL BUFFER BOUNDARIES * +****************************************************************************** + +------------------------------------------------------------------------------ + : : +Character : Control-Bits : Meaning + : : +------------------------------------------------------------------------------ + N : Control-X N : Narrow Buffer Bounds (to size of region) +------------------------------------------------------------------------------- + P : Control-X P : Narrow Buffer Bounds (to current page) +------------------------------------------------------------------------------ + W : Control-X W : Widen buffer boundaries (to whole buffer) +------------------------------------------------------------------------------ diff --git a/doc/emacs1/emacs.guide b/doc/emacs1/emacs.guide new file mode 100755 index 00000000..fb78f0de --- /dev/null +++ b/doc/emacs1/emacs.guide @@ -0,0 +1,12937 @@ + + + + + + + MASSACHUSETTS INSTITUTE OF TECHNOLOGY + ARTIFICIAL INTELLIGENCE LABORATORY + + + + + + AI Memo 554 2 October 1981 + + + + + + + EMACS MANUAL FOR ITS USERSî EMACS MANUAL FOR ITS USERSî EMACS MANUAL FOR ITS USERS + + + BYî BYî BY + + + RICHARD M. STALLMANî RICHARD M. STALLMANî RICHARD M. STALLMAN + + + A REFERENCE MANUALî A REFERENCE MANUALî A REFERENCE MANUAL + + + FOR THE EXTENSIBLE, CUSTOMIZABLE, SELF-DOCUMENTINGî FOR THE EXTENSIBLE, CUSTOMIZABLE, SELF-DOCUMENTINGî FOR THE EXTENSIBLE, CUSTOMIZABLE, SELF-DOCUMENTING + + + REAL-TIME DISPLAY EDITORî REAL-TIME DISPLAY EDITORî REAL-TIME DISPLAY EDITOR + + + This manual corresponds to EMACS version 161 + + + + + + + + + + This report describes work done at the Artificial Intelligence + Laboratory of the Massachusetts Institute of Technology. Support + for the laboratory's research is provided in part by the Advanced + Research Projects Agency of the Department of Defense under + Office of Naval Research contract N00014-80-C-0505.î 1 EMACS Manual for ITS Users + + + + PREFACEî PREFACEî PREFACE + + + + This manual documents the use and simple customization of the + display editor EMACS with the ITS operating system. The reader + ___î is not expected to be a programmer. Even simple customizations + do not require programming skill, but the user who is not + interested in customizing can ignore the scattered customization + hints. + + This is primarily a reference manual, but can also be used as a + primer. However, I recommend that the newcomer first use the + on-line, learn-by-doing tutorial TEACHEMACS, by typing + :TEACHEMACS while in HACTRN. With it, you learn EMACS by + using EMACS on a specially designed file which describes + commands, tells you when to try them, and then explains the + results you see. This gives a more vivid introduction than a + printed manual. + + On first reading, you need not make any attempt to memorize + chapters 1 and 2, which describe the notational conventions of + the manual and the general appearance of the EMACS display + screen. It is enough to be aware of what questions are answered + in these chapters, so you can refer back when you later become + interested in the answers. After reading the Basic Editing + chapter you should practice the commands there. The next few + chapters describe fundamental techniques and concepts that are + referred to again and again. It is best to understand them + thoroughly, experimenting with them if necessary. + + To find the documentation on a particular command, look in the + index if you know what the command is. Both command characters + and function names are indexed. If you know vaguely what the + command does, look in the command summary. The command summary + contains a line or two about each command, and a cross reference + to the section of the manual that describes the command in more + detail; related commands are grouped together. There is also a + glossary, with a cross reference for each term. + + Many user-contributed libraries accompany EMACS, and often then + have no documentation except their on-line self-documentation. + Browsing through the catalogue of libraries in this manual is a + good way to find out what is available. + + This manual has in two versions, one for ITS, and one for + Twenex, DEC's "TOPS-20" system. Each version comes in three + forms: the published form, the LPT form, and the INFO form. You + can order the published form from the Publications Department ofî 2 EMACS Manual for ITS Users + + + + the Artificial Intelligence lab for $3.25 per copy; be sure to + specify the ITS version or the Twenex version. The LPT form is + available on line as EMACS;EMACS GUIDE for printing on + unsophisticated hard copy devices such as terminals and line + printers. The INFO form is for on-line perusal with the INFO + program. All three forms are substantially the same. + + EMACS is available for distribution for use on Tenex and Twenex + systems (It does not run on Bottoms-10, and the conversion would + not be easy). Mail us a 2400 foot mag tape if you want it. It + does not cost anything; instead, you must join the EMACS + software-sharing commune. The conditions of membership are that + you must send back any improvements you make to EMACS, including + any libraries you write, and that you must not redistribute the + system except exactly as you got it, complete. (You can also + distribute your customizations, separately.) + + Please do not attempt to get a copy of EMACS, for yourself or + any one else, by dumping it off of your local system. It is + almost certain to be incomplete or inconsistent. It is pathetic + to hear from sites that received incomplete copies lacking the + sources, asking me years later whether sources are available. If + you wish to give away a copy of EMACS, copy a distribution tape + from MIT, or mail me a tape and get a new one. + + For information on the underlying philosophy of EMACS and the + lessons learned from its development, write to me for a copy of + AI memo 519a, "EMACS, the Extensible, Customizable + Self-Documenting Display Editor", or send Arpanet mail to + RMS@MIT-AI. + + + Yours in hacking, + + + / 2 \ 1/2 + < X > + \ / + + + Richard M. Stallman + Artificial Intelligence Lab + 545 Tech Square, Rm 913 + Cambridge, MA 02139 + (617) 253-6765î 3 EMACS Manual for ITS Users + + + INTRODUCTIONî INTRODUCTIONî INTRODUCTION + + + + You are about to read about EMACS, an advanced, + self-documenting, customizable, extensible real-time display + editor. + + We say that EMACS is a display editor because normally the text + being edited is visible on the screen and is updated + automatically as you type your commands. See section 1 + [Display], page 5. + + We call it a real-time editor because the display is updated + very frequently, usually after each character or pair of + characters you type. This minimizes the amount of information + you must keep in your head as you edit. See section 3 [Basic], + page 15. + + We call EMACS advanced because it provides facilities that go + beyond simple insertion and deletion: filling of text; automatic + indentation of programs; viewing two files at once; and dealing + in terms of characters, words, lines, sentences, paragraphs, and + pages, as well as expressions and comments in several different + programming languages. It is much easier to type one command + meaning "go to the end of the paragraph" than to find the desired + spot with repetition of simpler commands. + + Self-documenting means that at any time you can type a special + character, the "Help" key, to find out what your options are. + You can also use it to find out what any command does, or to find + all the commands that pertain to a topic. See section 7 [Help], + page 33. + + Customizable means that you can change the definitions of EMACS + commands in little ways. For example, if you use a programming + language in which comments start with <** and end with **>, you + can tell the EMACS comment manipulation commands to use those + strings. Another sort of customization is rearrangement of the + command set. For example, if you prefer the four basic cursor + motion commands (up, down, left and right) on keys in a diamond + pattern on the keyboard, you can have it. See section 21.8 + [Customization], page 132. + + Extensible means that you can go beyond simple customization + and write entirely new commands, programs in the language TECO. + EMACS is an "on-line extensible" system, which means that it is + divided into many functions that call each other, any of which + can be redefined in the middle of an editing session. Any partî 4 EMACS Manual for ITS Users + + + + of EMACS can be replaced without making a separate copy of all of + EMACS. Many already written extensions are distributed with + EMACS, and some (including DIRED, PAGE, PICTURE, SORT, TAGS, and + WORDAB) are documented in this manual. Although only a + programmer can write an extension, anybody can use it afterward. + + Extension requires programming in TECO, a rather obscure + language. If you are clever and bold, you might wish to learn + how. See the file INFO;CONV, for advice on learning TECO. This + manual does not even try to explain how to write TECO programs, + but it does contain some notes that are useful primarily to the + extension writer.î 5 EMACS Manual for ITS Users + + + CHAPTER ONEî CHAPTER ONEî CHAPTER ONE + THE ORGANIZATION OF THE SCREENî THE ORGANIZATION OF THE SCREENî THE ORGANIZATION OF THE SCREEN + + + + EMACS divides the screen into several areas, each of which + contains its own sorts of information. The biggest area, of + course, is the one in which you usually see the text you are + editing. The terminal's cursor usually appears in the middle of + _____î the text, showing the position of point, the location at which + __î editing takes place. While the cursor appears to point at a + _______î character, point should be thought of as between two characters; + ______î it points before the character that the cursor appears on top of. + Terminals have only one cursor, and when output is in progress it + must appear where the typing is being done. This does not mean + that point is moving. It is only that EMACS has no way to show + you the location of point except when the terminal is idle. + + The top lines of the screen are usually available for text but + _____ _______î are sometimes pre-empted by an error message, which says that + some command you gave was illegal or used improperly, or by + _______î typeout from a command (such as, a listing of a file directory). + Error messages are typically one line, end with a question mark, + and are accompanied by ringing the bell. Typeout generally has + none of those characteristics. + + The error message or typeout appears there for your + information, but it is not part of the file you are editing, and + it goes away if you type any command. If you want to make it go + away immediately but not do anything else, you can type a Space. + (Usually a Space inserts itself, but when there is an error + message or typeout on the screen it does nothing but get rid of + that.) The terminal's cursor always appears at the end of the + error message or typeout, but this does not mean that point has + moved. The cursor moves back to the location of point after the + error message or typeout goes away. + + If you type a question mark when an error message is on the + screen, you enter the EMACS error handler. You probably don't + want to do this unless you know how to write TECO programs. If + you do it by accident, C-] (the standard abort character) will + get you out. Enough said. + + A few lines at the bottom of the screen compose what is called + ____ ____î the echo area. The variable Echo Area Height controls how many + _______î lines long it is. Echoing means printing out the commands that + you type. EMACS commands are usually not echoed at all, but if + you pause for more than a second in the middle of a + multi-character command then all the characters typed so far areî 6 EMACS Manual for ITS Users + + + + ______î echoed. This is intended to prompt you for the rest of the + command. The rest of the command is echoed, too, as you type it. + This behavior is designed to give confident users optimum + response, while giving hesitant users maximum feedback. + + EMACS also uses the echo area for reading and displaying the + arguments for some commands, such as searches, and for printing + brief information in response to certain commands. + + + + 1.1 The Mode Lineî 1.1 The Mode Lineî 1.1 The Mode Line + + + ____ ____î The line above the echo area is known as the mode line. It is + the line that usually starts with "EMACS (something)". Its + purpose is to tell you anything that may affect the meaning of + your commands aside from the text itself. + + Some EMACS commands read and process more commands. They are + __________ _________ _______ ______î known as subsystems or recursive editing levels. If you are + inside a subsystem or a recursive editing level, the mode line + tells you its name. Square brackets around the mode line + indicate a recursive editing level; See section 6.3 [Recursive + __________î Editing Levels], page 30. Parentheses indicate a minibuffer; See + section 23 [Minibuffer], page 156. Neither brackets nor + parentheses indicates a subsystem; See section 6.1 [Subsystems], + page 28. + + Subsystems and recursive editing levels are advanced features, + and you will not initially be using them. When you are not + inside a subsystem or recursive editing level, we say that you + ___ _____î are at top level; this implies that the characters you type are + interpreted as ordinary EMACS commands. When you are at top + level, the mode line tells you what file you are editing, where + you are in it, and what editing modes are enabled which may + affect the meaning of your commands. The top level mode line has + this format: + + + EMACS type (major minor) bfr: file (vrs) --pos-- * + + + ____î type is usually not there. When it is there, it indicates that + the EMACS job you are using is not an ordinary one, in that it is + acting as the servant of some other job. A type of "LEDIT" + indicates an EMACS serving one or more Lisps, while a type of + "MAILT" indicates an EMACS that you got by asking for an "edit + escape" while composing mail to send. The type can also indicateî 7 EMACS Manual for ITS Users + + + + a subsystem that is running, such as RMAIL. The type is stored + internally as a string in the variable Editor Type. The variable + is normally zero. + + _____ _____ ____î major is always the name of the major mode you are in. At any + time, EMACS is in one and only one of its possible major modes. + The major modes available include Fundamental mode (which EMACS + starts out in), Text mode, Lisp mode, PASCAL mode, and others. + See section 20.1 [Major Modes], page 102, for details of how the + modes differ and how to select one. Sometimes the name of the + major mode is followed immediately with another name inside + _______î square-brackets ("[ - ]"). This name is called the submode. The + submode indicates that you are "inside" of a command that causes + your editing commands to be changed temporarily, but does not + ____î change what text you are editing. A submode is a kind of + recursive editing level. See section 6.3 [Submodes], page 30. + + _____ _____ _____î minor is a list of some of the minor modes that are turned on + at the moment. "Fill" means that Auto Fill mode is on. "Save" + means that Auto-saving is on. "Save(off)" means that Auto-saving + is on by default but turned off at the moment in this buffer. + "Atom" means that Atom Word mode is on. "Abbrev" means that Word + Abbrev mode is on. "Ovwrt" means that Overwrite mode is on. See + section 22.1 [Minor Modes], page 133, for more information. + "Def" means that a keyboard macro is being defined; although this + is not exactly a minor mode, it is still useful to be reminded + about. See section 22.8 [Keyboard Macros], page 152. "Narrow" + means that editing is currently restricted to only a part of the + buffer. See section 17 [Narrowing], page 93. + + ___ ______î bfr is the name of the currently selected buffer. Each buffer + has its own name and holds a file being edited; this is how EMACS + can hold several files at once. But at any time you are editing + ________î only one of them, the selected buffer. When we speak of what + some command does to "the buffer", we are talking about the + currently selected buffer. Multiple buffers make it easy to + switch around between several files, and then it is very useful + that the mode line tells you which one you are editing at any + time. However, before you learn how to use multiple buffers, you + will always be in the buffer called "Main", which is the only one + that exists when EMACS starts up. If the name of the buffer is + the same as the first name of the file you are visiting, then the + buffer name is left out of the mode line. See section 14 + [Buffers], page 83, for how to use more than one buffer in one + EMACS. + + ____î file is the name of the file that you are editing. It is the + last file that was visited in the buffer you are in. It is + _______ ______î followed, in parentheses, by the file version number mostî 8 EMACS Manual for ITS Users + + + + recently visited or saved provided the second filename visited is + ">", so that version numbers are allowed. "(R-O)" after the + _________î filename means that the file or buffer is read-only; a file + visited read-only will not be saved unless you insist, while a + read-only buffer does not allow you to alter its contents at all. + See section 13.1 [Visiting], page 69, for more information. + + The star at the end of the mode line means that there are + changes in the buffer that have not been saved in the file. If + the file has not been changed since it was read in or saved, + there is no star. + + ___î pos tells you whether there is additional text above the top of + the screen, or below the bottom. If your file is small and it is + all on the screen, --pos-- is omitted. Otherwise, it is + --TOP-- if you are looking at the beginning of the file, + --BOT-- if you are looking at the end of the file, or + --nn%-- where nn is the percentage of the file above the top of + the screen. + + Sometimes you will see --MORE-- instead of --nn%--. This + happens when typeout from a command is too long to fit on the + screen. It means that if you type a Space the next screenful of + information will be printed. If you are not interested, typing + anything but a Space will cause the rest of the output to be + discarded. Typing a Rubout will discard the output and do + nothing else. Typing any other command will discard the rest of + the output and also do the command. When the output is + discarded, "FLUSHED" is printed after the --MORE--. + + If you are accustomed to other display editors, you may be + surprised that EMACS does not always display the page number and + line number of point in the mode line. This is because the text + is stored in a way that makes it difficult to compute this + information. Displaying them all the time would be too slow to + be borne. When you want to know the page and line number of + point, you must ask for the information with the M-X What Page + command. See section 18 [Pages], page 94. However, once you are + adjusted to EMACS, you will rarely have any reason to be + concerned with page numbers or line numbers. + + If you set the variable Display Mode Line Inverse nonzero, then + the mode line is displayed in inverse video if the terminal you + are using supports it. See section 22.3 [Variables], page 137. + + The libraries MODLIN and MODE2 allow you to customize the + information that is displayed in the mode line. MODLIN replaces + the standard EMACS mode line generation routines. MODE2 makes a + second mode line, above the first, whose contents are under yourî 9 EMACS Manual for ITS Users + + + + control. Refer to the self-documentation of these libraries; See + section 22.2 [Libraries], page 135.î 10 EMACS Manual for ITS Users + + + CHAPTER TWOî CHAPTER TWOî CHAPTER TWO + CHARACTER SETS AND COMMAND INPUT CONVENTIONSî CHARACTER SETS AND COMMAND INPUT CONVENTIONSî CHARACTER SETS AND COMMAND INPUT CONVENTIONS + + + + In this chapter we introduce the terminology and concepts used + to talk about EMACS commands. EMACS is designed to be used with + a kind of keyboard with two special shift keys which can type 512 + different characters, instead of the 128 different characters + which ordinary ASCII keyboards can send. The terminology of + EMACS commands is formulated in terms of these shift keys. So + that EMACS can be used on ASCII terminals, we provide + two-character ASCII circumlocutions for the command characters + which are not ASCII. + + + + 2.1 The 9-bit Command Character Setî 2.1 The 9-bit Command Character Setî 2.1 The 9-bit Command Character Set + + + EMACS is designed ideally to be used with terminals whose + keyboards have a pair of shift keys, labeled "Control" and + "Meta", either or both of which can be combined with any + _______î character that you can type. These shift keys produce Control + ____î characters and Meta characters, which are the editing commands of + EMACS. We name each of these characters by prefixing "Control-" + (or "C-"), "Meta-" (or "M-") or both to the basic character: + thus, Meta-F or M-F is the character which is F typed with the + Meta key held down. C-M-; is the Semicolon character with both + the Control and Meta keys. Control in the EMACS command + character set is not precisely the same as Control in the ASCII + character set, but the general purpose is the same. + + There are 128 basic characters. Multiplied by the four + possibilities of the Control and Meta keys, this makes 512 + characters in the EMACS command character set. So it is called + the 512-character set, to distinguish it from ASCII, which has + _____î only 128 characters. It is also called the 9-bit character set + because 9 bits are required to express a number from 0 to 511. + Note that the 512-character set is used only for keyboard + commands. Characters in files being edited with EMACS are ASCII + characters. + + Sadly, most terminals do not have ideal EMACS keyboards. In + fact, the only ideal keyboards are at MIT. On nonideal + keyboards, the Control key is somewhat limited (it can only be + combined with some characters, not with all), and the Meta key + may not exist at all. We make it possible to use EMACS on a + nonideal terminal by providing two-character circumlocutions,î 11 EMACS Manual for ITS Users + + + + made up of ASCII characters that you can type, for the characters + ___î that you can't type. These circumlocutions start with a bit + ______î prefix character; see below. For example, to use the Meta-A + command, you could type Altmode A. Also see the appendices for + more detailed information on what to do on your type of terminal. + + Both the EMACS 9-bit character set and ASCII have Control + characters, but the 9-bit character set has more different ones. + In ASCII, only letters and a few punctuation marks can be made + into Control characters; in the 9-bit character set every + character has a Control version. For example, we have + Control-Space, Control-1, and Control-=. We also have two + different characters Control-A and Control-a! But they always do + the same thing in EMACS, so you can ignore the distinction + between them, unless you are doing customization. In practice, + you can forget all about the distinction between ASCII Control + and EMACS Control, except to realize that EMACS uses some + "Control" characters which ASCII keyboards cannot type. + + In addition to the 9-bit command character set, there is one + additional EMACS command character called Help. It cannot be + combined with Control or Meta. Its use is to ask for + documentation, at any time. The Help character has its own key + on an ideal keyboard, but must be represented by something else + on other keyboards. The circumlocution we use is Control-_ H + (two characters). The code used internally for Help is 4110 + (octal). + + We have given some command characters special names which we + always capitalize. "Return" or "" stands for the carriage + return character, code 015 (all character codes are in octal). + Note that C-R means the character Control-R, never Return. + "Rubout" is the character with code 177, labeled "Delete" on some + keyboards. "Altmode" is the character with code 033, sometimes + labeled "Escape". Other command characters with special names + are Tab (code 011), Backspace (code 010), Linefeed (code 012), + Space (code 040), Excl ("!", code 041), Comma (code 054), and + Period (code 056). Control is represented in the numeric code + for a character by 200, and Meta by 400; thus, Meta-Period is + code 456 in the 9-bit character set. + + + + 2.2 Prefix Charactersî 2.2 Prefix Charactersî 2.2 Prefix Characters + + + A non-ideal keyboard can only send certain Control characters, + and may completely lack the ability to send Meta characters. To + use these commands on such keyboards, you need to useî 12 EMACS Manual for ITS Users + + + + ___ ______î two-character circumlocutions starting with a bit prefix + character which turns on the Control or Meta bit in the second + character. The Altmode character turns on the Meta bit, so + Altmode X can be used to type a Meta-X, and Altmode Control-O can + _______î be used to type a C-M-O. Altmode is known as the Metizer. Other + bit prefix characters are C-^ for Control, and C-C for Control + and Meta together. Thus, C-^ < is a way of typing a Control-<, + and C-C < can be used to type C-M-<. Because C-^ is awkward to + type on most keyboards, we have tried to minimize the number of + commands for which you will need it. + + The bit prefix characters are simply commands which run the + functions ^R Prefix Control, ^R Prefix Meta, and ^R Prefix + Control-Meta. + + There is another prefix character, Control-X which is used as + the beginning of a large set of two-character commands known as + ___ ________î C-X commands. C-X is not a bit prefix character; C-X A is not a + circumlocution for any single character, and it must be typed as + two characters on any terminal. You can create new prefix + characters when you customize. See the file INFO;CONV, node + Prefix. + + + + 2.3 Commands, Functions, and Variablesî 2.3 Commands, Functions, and Variablesî 2.3 Commands, Functions, and Variables + + + Most of the EMACS commands documented herein are members of + this 9-bit character set. Others are pairs of characters from + that set. However, EMACS doesn't really implement commands + _________î directly. Instead, EMACS is composed of functions, which have + long names such as "^R Down Real Line" and definitions which are + ________î programs that perform the editing operations. Then commands such + _______ ________î as C-N are connected to functions through the command dispatch + _____î table. When we say that C-N moves the cursor down a line, we are + glossing over a distinction which is unimportant for ordinary + use, but essential for customization: it is the function ^R Down + Real Line which knows how to move down a line, and C-N moves down + a line because it is connected to that function. We usually + ignore this subtlety to keep things simple. To give the + extension-writer the information he needs, we state the name of + the function which really does the work in parentheses after + mentioning the command name. For example: "C-N (^R Down Real + Line) moves the cursor down a line". In the EMACS wall chart, + the function names are used as a form of very brief documentation + for the command characters. See section 5.2 [Functions], + page 24.î 13 EMACS Manual for ITS Users + + + + The "^R " which appears at the front of the function name is + simply part of the name. By convention, a certain class of + functions have names which start with "^R ". + + While we are on the subject of customization information which + you should not be frightened of, it's a good time to tell you + _________î about variables. Often the description of a command will say "to + change this, set the variable Mumble Foo". A variable is a name + used to remember a value. EMACS contains many variables which + are there so that you can change them if you want to customize. + The variable's value is examined by some command, and changing + the value makes the command behave differently. Until you are + interested in customizing, you can ignore this information. When + you are ready to be interested, read the basic information on + variables, and then the information on individual variables will + make sense. See section 22.3 [Variables], page 137. + + + + 2.4 Notational Conventions for ASCII Charactersî 2.4 Notational Conventions for ASCII Charactersî 2.4 Notational Conventions for ASCII Characters + + + Control characters in files, your EMACS buffer, or TECO + programs, are ordinary ASCII characters. The special 9-bit + character set applies only to typing EMACS commands. ASCII + contains the printing characters, rubout, and some control + characters. Most ASCII control characters are represented in + this manual as uparrow or caret followed by the corresponding + ^î non-control character: control-E is represented as |E. + + Some ASCII characters have special names. These include tab + (011), backspace (010), linefeed (012), return (015), altmode + (033), space (040), and rubout (177). To make it clear whether + we are talking about a 9-bit character or an ASCII character, we + capitalize names of 9-bit characters and leave names of ASCII + characters in lower case. Note that the 9-bit characters Tab and + Control-I are different, but the ASCII characters tab and + control-I are the same. + + Lines in files are separated by a sequence of two ASCII control + characters, carriage return followed by linefeed. This sequence + ____î is called CRLF. Normally, EMACS treats this two-character + ____ _________î sequence as if it were a single character, a line separator. A + _____î return or a linefeed which is not part of a CRLF is called stray. + EMACS usually treats them as part of the text of a line and + displays them as ^M and ^J. If the variable Display Overprinting + is zero, they display as actual carriage return or linefeed. + + Most control characters when present in the EMACS buffer areî 14 EMACS Manual for ITS Users + + + + ^î displayed with a caret; thus, ^A for ASCII |A. Rubout is + displayed as ^?, because by stretching the meaning of "control" + it can be interpreted as ASCII control-?. A backspace is usually + displayed as ^H since it is ASCII control-H, because most + displays cannot do overprinting. If you want backspace and stray + return to display as overprinting, set the variable Display + Overprinting nonzero. + + Altmode is the ASCII code 033, sometimes labeled "Escape" or + "Alt". Altmode is often represented by itself in this document + (remember, it is an ASCII character and can therefore appear in + files). It looks like this: $. On most terminals, altmode looks + just like the dollar sign character. If that's so on yours, you + should assume that anything you see in the on-line documentation + which looks like a dollar sign is really an altmode unless you + are specifically told it's a dollar sign. The dollar sign + character is not particularly important in EMACS and we will + rarely have reason to mention it.î 15 EMACS Manual for ITS Users + + + CHAPTER THREEî CHAPTER THREEî CHAPTER THREE + BASIC EDITING COMMANDSî BASIC EDITING COMMANDSî BASIC EDITING COMMANDS + + + + We now give the basics of how to enter text, make corrections, + and save the text in a file. If this material is new to you, you + might learn it more easily by running the :TEACHEMACS program. + + + + 3.1 Inserting Textî 3.1 Inserting Textî 3.1 Inserting Text + + + To insert printing characters into the text you are editing, + just type them. When EMACS is at top level, all printing + characters you type are inserted into the text at the cursor + _____î (that is, at point), and the cursor moves forward. Any + characters after the cursor move forward too. If the text in the + buffer is FOOBAR, with the cursor before the B, then if you type + XX, you get FOOXXBAR, with the cursor still before the B. + + To correct text you have just inserted, you can use Rubout. + ______î Rubout deletes the character before the cursor (not the one that + _____î the cursor is on top of or under; that is the character after the + cursor). The cursor and all characters after it move backwards. + Therefore, if you type a printing character and then type Rubout, + they cancel out. + + To end a line and start typing a new one, type Return + (Customizers, note: this runs the function ^R CRLF). Return + operates by inserting a line separator, so if you type Return in + the middle of a line, you break the line in two. Return really + inserts two characters, a carriage return and a linefeed (a + CRLF), but almost everything in EMACS makes them look like just + one character, which you can think of as a line-separator + character. For example, typing Rubout when the cursor is at the + beginning of a line rubs out the line separator before the line, + joining that line with the preceding line. + + If you add too many characters to one line, without breaking it + with a Return, the line will grow to occupy two (or more) lines + on the screen, with a "!" at the extreme right margin of all but + the last of them. The "!" says that the following screen line is + ____________î not really a distinct line in the file, but just the continuation + of a line too long to fit the screen. + + Direct insertion works for printing characters and space, but + other characters act as editing commands and do not insertî 16 EMACS Manual for ITS Users + + + + themselves. If you need to insert a control character, Altmode, + _____î Tab or Rubout, you must quote it by typing the Control-Q + (^R Quoted Insert) command first. See section 2 [Characters], + ^î page 10. Inserting a |Z is harder because EMACS cannot even + receive the character; you must use the minibuffer as in Altmode + Altmode 26i Altmode Altmode. See section 23 [Minibuffer], + page 156. + + + + 3.2 Moving The Cursorî 3.2 Moving The Cursorî 3.2 Moving The Cursor + + + To do more than insert characters, you have to know how to move + the cursor. Here are a few of the commands for doing that. + + + C-A Move to the beginning of the line. + C-E Move to the end of the line. + C-F Move forward over one character. + C-B Move backward over one character. + C-N Move down one line, vertically. If you start in + the middle of one line, you end in the middle of + the next. From the last line of text, it creates + a new line. + C-P Move up one line, vertically. + C-L Clear the screen and reprints everything. + C-U C-L reprints just the line that the cursor is + on. + C-T Transpose two characters (the ones before and + after the cursor). + M-< Move to the top of your text. + M-> Move to the end of your text. + + + + 3.3 Erasing Textî 3.3 Erasing Textî 3.3 Erasing Text + + + Rubout Delete the character before the cursor. + C-D Delete the character after the cursor. + C-K Kill to the end of the line. + + + You already know about the Rubout command which deletes the + character before the cursor. Another command, Control-D, deletes + the character after the cursor, causing the rest of the text on + the line to shift left. If Control-D is typed at the end of a + line, that line and the next line are joined together.î 17 EMACS Manual for ITS Users + + + + To erase a larger amount of text, use the Control-K command, + which kills a line at a time. If Control-K is done at the + beginning or middle of a line, it kills all the text up to the + end of the line. If Control-K is done at the end of a line, it + joins that line and the next line. + + See section 9.1 [Killing], page 39, for more flexible ways of + killing text. + + + + 3.4 Filesî 3.4 Filesî 3.4 Files + + + The commands above are sufficient for creating text in the + EMACS buffer. The more advanced EMACS commands just make things + easier. But to keep any text permanently you must put it in a + ____î file. Files are the objects which ITS uses for storing data for + communication between different programs or to hold onto for a + length of time. To tell EMACS to edit text in a file, choose a + ________ ______î filename, such as FOO, and type C-X C-V FOO. This visits the + file FOO (actually, FOO > on your working directory) so that its + contents appear on the screen for editing. You can make changes, + ____î and then save the file by typing C-X C-S. This makes the changes + permanent and actually changes the file FOO. Until then, the + changes are only inside your EMACS, and the file FOO is not + really changed. If the file FOO doesn't exist, and you want to + create it, visit it as if it did exist. When you save your text + with C-X C-S the file will be created. + + Of course, there is a lot more to learn about using files. See + section 13 [Files], page 69. + + + + 3.5 Helpî 3.5 Helpî 3.5 Help + + + If you forget what a command does, you can find out with the + Help character. The Help character is Top-H if you have a Top + key, or Control-_ H (two characters!) otherwise. Type Help + followed by C and the command you want to know about. Help can + help you in other ways as well. See section 7 [Help], page 33.î 18 EMACS Manual for ITS Users + + + + 3.6 Using Blank Lines Can Make Editing Fasterî 3.6 Using Blank Lines Can Make Editing Fasterî 3.6 Using Blank Lines Can Make Editing Faster + + + C-O Insert one or more blank lines after the + cursor. + C-X C-O Delete all but one of many consecutive blank + lines. + + + It is much more efficient to insert text at the end of a line + than in the middle. So if you want to stick a new line before an + existing one, the best way is to make a blank line there first + and then type the text into it, rather than inserting the new + text at the beginning of the existing line and finally inserting + a line separator. Making the blank line first also makes the + meaning of the text clearer while you are typing it in. + + To make a blank line, you can type Return and then C-B. But + there is a single character for this: C-O (Customizers: this is + the built-in function ^R Open Line). So, FOO Return is + equivalent to C-O FOO. + + If you want to insert many lines, you can type many C-O's at + the beginning (or you can give C-O an argument to tell it how + many blank lines to make. See section 4 [Arguments], page 19, + for how). As you then insert lines of text, you will notice that + Return behaves strangely: it "uses up" the blank lines instead of + pushing them down. + + If you don't use up all the blank lines, you can type C-X C-O + (the function ^R Delete Blank Lines) to get rid of all but one. + When point is on a blank line, C-X C-O replaces all the blank + lines around that one with a single blank line. When point is on + a nonblank line, C-X C-O deletes any blank lines following that + nonblank line.î 19 EMACS Manual for ITS Users + + + CHAPTER FOURî CHAPTER FOURî CHAPTER FOUR + GIVING NUMERIC ARGUMENTS TO EMACS COMMANDSî GIVING NUMERIC ARGUMENTS TO EMACS COMMANDSî GIVING NUMERIC ARGUMENTS TO EMACS COMMANDS + + + + _______ ________î Any EMACS command can be given a numeric argument. Some + commands interpret the argument as a repetition count. For + example, giving an argument of ten to the C-F command (move + forward one character) moves forward ten characters. With these + commands, no argument is equivalent to an argument of 1. + + Some commands care only about whether there is an argument, and + not about its value; for example, the command M-Q (^R Fill + Paragraph) with no arguments fills text, but with an argument + justifies the text as well. + + Some commands use the value of the argument, but do something + peculiar when there is no argument. For example, the C-K + (^R Kill Line) command with an argument kills lines and + the line separators that follow them. But C-K with no argument + is special; it kills the text up to the next line separator, or, + if point is right at the end of the line, it kills the line + separator itself. Thus, two C-K commands with no arguments can + kill a nonblank line, just like C-K with an argument of one. + + The fundamental way of specifying an argument is to use the C-U + (^R Universal Argument) command followed by the digits of the + argument. Negative arguments are allowed. Often they tell a + command to move or act backwards. A negative argument is entered + with C-U followed by a minus sign and the digits of the value of + the argument. + + C-U followed by a character which is neither a digit nor a + minus sign has the special meaning of "multiply by four". It + multiplies the argument for the next command by four. Two such + C-U's multiply it by sixteen. Thus, C-U C-U C-F moves forward + sixteen characters. This is a good way to move forward "fast", + since it moves about 1/4 of a line on most terminals. Other + useful combinations are C-U C-N, C-U C-U C-N (move down a good + fraction of a screen), C-U C-U C-O (make "a lot" of blank lines), + and C-U C-K (kill four lines). With commands like M-Q that care + whether there is an argument but not what the value is, C-U is a + good way of saying "I want an argument". + + A few commands treat a plain C-U differently from an ordinary + argument. A few others may treat an argument of just a minus + sign differently from an argument of -1. These unusual cases + will be described when they come up; they are always for reasons + of convenience of use.î 20 EMACS Manual for ITS Users + + + + There are other, terminal-dependent ways of specifying + arguments. They have the same effect but may be easier to type. + See the appendix. If your terminal has a numeric keypad which + sends something recognizably different from the ordinary digits, + it is possible to program EMACS to allow use of the numeric + keypad for specifying arguments. The libraries VT52 and VT100 + provide such a feature for those two types of terminals. See + section 22.2 [Libraries], page 135. + + + + 4.1 Autoarg Modeî 4.1 Autoarg Modeî 4.1 Autoarg Mode + + + Users of ASCII keyboards may prefer to use Autoarg mode. + Autoarg mode means that you don't need to type C-U to specify a + numeric argument. Instead, you type just the digits. Digits + followed by an ordinary inserting character are themselves + inserted, but digits followed by an Altmode or Control character + serve as an argument to it and are not inserted. A minus sign + can also be part of an argument, but only at the beginning. If + you type a minus sign following some digits, both the digits and + the minus sign are inserted. + + To use Autoarg mode, set the variable Autoarg Mode nonzero. + See section 22.3 [Variables], page 137. + + Autoargument digits echo at the bottom of the screen; the first + nondigit causes them to be inserted or uses them as an argument. + To insert some digits and nothing else, you must follow them with + a Space and then rub it out. C-G cancels the digits, while + Rubout inserts them all and then rubs out the last.î 21 EMACS Manual for ITS Users + + + CHAPTER FIVEî CHAPTER FIVEî CHAPTER FIVE + EXTENDED (META-X) COMMANDS AND FUNCTIONSî EXTENDED (META-X) COMMANDS AND FUNCTIONSî EXTENDED (META-X) COMMANDS AND FUNCTIONS + + + + Not all EMACS commands are of the one or two character variety + you have seen so far. Most commands have long names composed of + English words. This is for two reasons: the long names are + easier to remember and more suggestive, and there are not enough + two-character combinations for every command to have one. + + ________ ________î The commands with long names are known as extended commands + because they extend the set of two-character commands. + + + + 5.1 Issuing Extended Commandsî 5.1 Issuing Extended Commandsî 5.1 Issuing Extended Commands + + + M-X Begin an extended command. Follow by + command name and arguments. + C-M-X Begin an extended command. Follow by the + command name only; the command will ask + for any arguments. + C-X Altmode Re-execute recent extended command. + + + ___ ________î Extended commands are also called M-X commands, because they + all start with the character Meta-X (^R Extended Command). The + M-X is followed by the command's long, suggestive name, actually + the name of a function to be called. Terminate the name of the + function with a Return (unless you are supplying string + arguments; see below). For example, Meta-X Auto Fill Mode + invokes the function Auto Fill Mode. This function when executed + turns Auto Fill mode on or off. + + We say that M-X Foo "calls the function Foo". When + documenting the individual extended commands, we will call them + _________î functions to avoid confusion between them and the one or two + ________î character commands. We will also use "M-X" as a title like "Mr." + for functions, as in "use M-X Foo". The "extended command" is + what you type, starting with M-X, and what the command does is + call a function. The name that goes in the command is the name + of the command and is also the name of the function, and both + terms will be used. + + Note: Extended commands and functions were once called "MM + commands", but this term is obsolete. If you see it used either + in INFO documentation of in Help documentation, please report it.î 22 EMACS Manual for ITS Users + + + + Ordinary one or two character commands used to be known as "^R" + commands; please report any occurrences of this obsolete term + also. + + There are a great many functions in EMACS for you to call. + They will be described elsewhere in the manual, according to what + they do. Here we are concerned only with extended commands in + general. + + + 5.1.1 Typing The Command Nameî 5.1.1 Typing The Command Nameî 5.1.1 Typing The Command Name + + + When you type M-X, the cursor moves down to the echo area at + the bottom of the screen. "M-X" is printed there, and when you + _______î type the command name it echoes there. This is known as reading + _ ____ __ ___ ____ ____î a line in the echo area. You can use Rubout to cancel one + character of the command name, or C-U or C-D to cancel the entire + command name. A C-G cancels the whole M-X, and so does a Rubout + when the command name is empty. These editing characters apply + any time EMACS reads a line in the echo area, not just within + M-X. + + The string "M-X" which appears in the echo area is called a + ______î prompt. The prompt always tells you what sort of argument is + required and what it is going to be used for; "M-X" means that + you are inside of the command M-X, and should type the name of a + function to be called. You can replace the prompt "M-X" with + some other string by defining the variable Read Command Prompt. + + + 5.1.2 Completionî 5.1.2 Completionî 5.1.2 Completion + + + You can abbreviate the name of the command, typing only the + beginning of the name, as much as is needed to identify the + command unambiguously. You can also use completion on the + function name. This means that you type part of the command + name, and EMACS visibly fills in the rest, or as much as can be + determined from the part you have typed. + + You request completion by typing an Altmode ($). For example, + if you type M-X Au$, the "Au" expands to "Auto " because all + command names which start with "Au" continue with "to ". If you + ask for completion when there are several alternatives for the + next character, the bell rings and nothing else happens. Altmode + is also the way to terminate the command name and begin the + string arguments, but it only does this if the command name + completes in full. In that case, an Altmode appears after theî 23 EMACS Manual for ITS Users + + + + command name in the echo area. In practice, these two meanings + of Altmode do not conflict, because if the command name does not + complete in full, it is ambiguous and would not be accepted. So + it would be useless to type the arguments yet. + + Space is another way to request completion, but it completes + only one word. Successive Spaces complete one word each, until + either there are multiple possibilities or the end of the name is + reached. If the first word of a command is Edit, List, Kill, + View or What, it is sufficient to type just the first letter and + complete it with a Space. (This does not follow from the usual + definition of completion, since the single letter is ambiguous; + it is a special feature added because these words are so common). + + Typing "?" in the middle of the command name prints a list of + all the command names which begin with what you have typed so + far. You can then go on typing the name. + + + 5.1.3 Numeric Arguments and String Argumentsî 5.1.3 Numeric Arguments and String Argumentsî 5.1.3 Numeric Arguments and String Arguments + + + Some functions can use numeric prefix arguments. Simply give + the Meta-X command an argument and Meta-X will pass it along to + the function which it calls. The argument appears before the + "M-X" in the prompt, as in "69 M-X", to remind you that the + function you call will receive a numeric argument. + + ______ _________î Some functions require string arguments (sometimes called + ______ _________î suffix arguments). To specify string arguments, terminate the + function name with a single Altmode, then type the arguments, + separated by Altmodes. After the last argument, type a Return to + cause the function to be executed. For example, the function + Describe prints the full documentation of a function (or a + variable) whose name must be given as a string argument. An + example of using it is + + + Meta-X Describe$Apropos + + + which prints the full description of the function named Apropos. + + An alternate way of calling extended commands is with the + command C-M-X (^R Instant Extended Command). It differs from + plain M-X in that the function itself reads any string arguments. + The function prompts for each argument individually. If an + argument is supposed to be a filename or a command name, + completion is available. However, there are compensatingî 24 EMACS Manual for ITS Users + + + + disadvantages. For one thing, since the function has already + been invoked, you can't rub out from the arguments into the + function name. For another, it is not possible to save the whole + thing, function name and arguments, for you to recall with C-X + Altmode (see below). So C-M-X saves nothing for C-X Altmode. + The prompt for C-M-X is "C-M-X". You can override it with the + variable Instant Command Prompt. + + + 5.1.4 Repeating an Extended Commandî 5.1.4 Repeating an Extended Commandî 5.1.4 Repeating an Extended Command + + + The last few extended commands you have executed are saved and + you can repeat them. We say that the extended command is saved, + rather than that the function is saved, because the whole + command, including arguments, is saved. + + To re-execute a saved command, use the command C-X Altmode + (^R Re-execute Minibuffer). It retypes the last extended command + and asks for confirmation. With an argument, it repeats an + earlier extended command: 2 means repeat the next to the last + command, etc. You can also use the minibuffer to edit a previous + extended command and re-execute it with changes (See section 23 + [Minibuffer], page 156.). + + + + 5.2 Arcane Information about M-X Commandsî 5.2 Arcane Information about M-X Commandsî 5.2 Arcane Information about M-X Commands + + + You can skip this section if you are not interested in + customization, unless you want to know what is going on behind + the scenes. + + + 5.2.1 MMî 5.2.1 MMî 5.2.1 MM + + + Extended commands were once called "MM" commands, because "MM" + is a TECO expression which looks up a command name to find the + associated program, and runs that program. Thus, the TECO + expression + + + MM Apropos$Word$ + + + means to run the Apropos command with the argument "word". You + could type this expression into a minibuffer and get the sameî 25 EMACS Manual for ITS Users + + + + results as you would get from Meta-X Apropos$Word. In fact, + for the first year or so, EMACS had no Meta-X command, and that's + what people did. See section 23 [Minibuffer], page 156, for + information on the minibuffer. + + "MM" actually tells TECO to call the subroutine in q-register + "M". The first "M" means "call", and the second "M" says what to + call. This subroutine takes a string argument which is the name + of a function and looks it up. Calling a function is built into + TECO, but looking up the name is not; it is implemented by the + program in q-register M. That's why "MM" is called that and not + ^î "Run" or "F|Q". + + + 5.2.2 Arguments in TECO Codeî 5.2.2 Arguments in TECO Codeî 5.2.2 Arguments in TECO Code + + + ______ _________ _______î Functions can use one or two prefix arguments or numeric + _________î arguments. These are numbers (actually, TECO expressions) which + go before the "MM". Meta-X can only give the MM command one + argument. If you want to give it two, you must type it in using + the minibuffer. When TECO code passes prefix arguments, they + don't have to be numbers; they can also be string objects, TECO + buffer objects, etc. However, no more about that here. + + ______ _________ ______ _________î TECO code can also pass string arguments or suffix arguments. + When TECO code passes a string argument, it appears, terminated + by an Altmode, after the Altmode which ends the function name. + There can be any number of string arguments. In fact, the + function can decide at run time how many string arguments to + read. This makes it impossible to compile TECO code! + + Since Altmode terminates a string argument, TECO has a quoting + convention to allow Altmodes to be part of a string argument. + ^î This convention is to use the two characters |] Altmode to cause + ^î just an Altmode to be part of the argument. |] also must be + ^ ^î quoted, as |] |]. The M-X command hides all of this: there is no + way to quote an Altmode; every Altmode always terminates a string + ^î argument; |] is not special, because M-X automatically replaces + ^ ^î each |] with two. If you understand the TECO meaning of |] you + can enable its use in M-X command arguments by setting the + variable Quote Execute Command nonzero. Then M-X does no special + ^î processing to |] characters. You can use them to quote Altmodes, + ^î and you must also take care of quoting |] characters themselves.î 26 EMACS Manual for ITS Users + + + + 5.2.3 Commands and Functionsî 5.2.3 Commands and Functionsî 5.2.3 Commands and Functions + + + Actually, every command in EMACS simply runs a function. For + example, when you type the command C-N, it runs the function + "^R Down Real Line". You could just as well do C-U 1 M-X ^R Down + Real Line and get the same effect. C-N can be thought of as + a sort of abbreviation. We say that the command C-N has been + _________î connected to the function ^R Down Real Line. The name is looked + up once when the command and function are connected, so that it + does not have to be looked up again each time the command is + used. For historical reasons, the default argument passed to a + function which is connected to a command you typed is 1, but the + default for MM and for M-X is 0. This is why the C-U 1 was + necessary in the example above. The documentation for individual + EMACS commands usually gives the name of the function which + really implements the command in parentheses after the command + itself. + + Just as any function can be called directly with M-X, so almost + any function can be connected to a command. You can use the + function Set Key to do this. Set Key takes the name of the + function as a string argument, then reads the character command + (including metizers or other prefix characters) directly from the + terminal. To define C-N, you could type + + + M-X Set Key$^R Down Real Line + + + and then type C-N. If you use the function View File often, you + could connect it to the command C-X V (not normally defined). + You could even connect it to the command C-M-V, replacing that + command's normal definition. Set Key is good for redefining + commands in the middle of editing. An init file or EVARS file + can do it each time you run EMACS. See section 22.6 [Init], + page 143. + + + 5.2.4 Subroutinesî 5.2.4 Subroutinesî 5.2.4 Subroutines + + + EMACS is composed of a large number of functions, each with a + name. Some of these functions are connected to commands; some + are there for you to call with M-X; some are called by other + functions. The last group are called subroutines. They usually + have names starting with "&", as in "& Read Line", the subroutine + which reads a line in the echo area. Although most subroutines + have such names, any function can be called as a subroutine.î 27 EMACS Manual for ITS Users + + + + Functions like ^R Down Real Line have names starting with ^R + because you are not expected to call them directly, either. The + purpose of the "&" or "^R" is to get those function names out of + the way of command completion in M-X. M-X allows the command + name to be abbreviated if the abbreviation is unique, and the + commands that you are not interested in might have names that + would interfere and make some useful abbreviation cease to be + unique. The funny characters at the front of the name prevent + this from happening. + + + 5.2.5 Built-in Functionsî 5.2.5 Built-in Functionsî 5.2.5 Built-in Functions + + + Not all of the functions in EMACS are written in TECO. A few + of the most frequently used single-character commands have + definitions written in machine language. These include + self-inserting characters, Rubout, C-F, and others. Such + functions defined in machine language as part of TECO are called + ________î built-in functions. Whereas the actual definition of an ordinary + function is a string, the definition of a built-in function is + just a number, the address of a routine in TECO. The EMACS + "definitions" of these commands exist only to give the commands + names and documentation, and live in a special library called + BARE which is loaded when necessary to make the names and + documentation available. For example, ^R Forward Character is + the name of the function which implements the C-F command.î 28 EMACS Manual for ITS Users + + + + CHAPTER SIXî CHAPTER SIXî CHAPTER SIX + MOVING UP AND DOWN LEVELSî MOVING UP AND DOWN LEVELSî MOVING UP AND DOWN LEVELS + + + + Subsystems and recursive editing levels are two states in which + you are temporarily doing something other than editing the + visited file as usual. For example, you might be editing a + message that you wish to send, or looking at a documentation file + with INFO. + + + + 6.1 Subsystemsî 6.1 Subsystemsî 6.1 Subsystems + + + _________î A subsystem is an EMACS function which is an interactive + program in its own right: it reads commands in a language of its + own, and displays the results. You enter a subsystem by typing + an EMACS command which invokes it. Once entered, the subsystem + runs until a specific command to exit the subsystem is typed. An + example of an EMACS subsystem is INFO, the documentation reading + program. Others are Backtrace and TDEBUG, used for debugging + TECO programs, and RMAIL and BABYL, used for reading and editing + mail files. + + The commands understood by a subsystem are usually not like + EMACS commands, because their purpose is something other than + editing text. For example, INFO commands are designed for moving + around in a tree-structured documentation file. In EMACS, most + commands are Control or Meta characters because printing + characters insert themselves. In most subsystems, there is no + insertion of text, so non-Control non-Meta characters can be the + commands. + + While you are inside a subsystem, the mode line usually gives + the name of the subsystem (as well as other information supplied + by the subsystem, such as the filename and node name in INFO). + You can tell that you are inside a subsystem because the mode + line does not start with "EMACS", or with an open bracket ("[") + which would indicate a recursive editing level. See section 1.1 + [Mode Line], page 6. + + Because each subsystem implements its own commands, we cannot + guarantee anything about them. However, there are conventions + for what certain commands ought to do: + + + C-] Aborts (exits without finishing up).î 29 EMACS Manual for ITS Users + + + + Backspace Scrolls backward, like M-V in EMACS. + Space Scrolls forward, like C-V in EMACS. + Q Exits normally. + X Begins an extended command, like M-X in + EMACS. + Help or ? Prints documentation on the subsystem's + commands. + + + Not all of these necessarily exist in every subsystem, however. + + + + 6.2 Reading Mailî 6.2 Reading Mailî 6.2 Reading Mail + + + The easiest way to look at your new mail is to use M-X View + Mail. This displays the mail file with View File. See + section 13.7 [View File], page 79. To view someone else's mail, + give his user name as an argument to M-X View Mail. + + When you want to edit your mail instead of just looking at it, + use C-X R (Read Mail). This invokes the mail reading subsystem + RMAIL. See the file INFO;RMAIL, node Top. If you prefer some + other mail reader, you can set the variable Mail Reader Library + to the name of the library to use. + + You can send mail from within RMAIL as well as edit your mail. + But if you want to send just one message, the easiest way is + Control-X M (Send Mail). You edit the message, exit with C-M-C, + and the message is sent; or else you abort with C-]. C-X M works + by invoking RMAIL or whatever library you use to read mail at a + special entry point named & Mail Message. The same library used + for reading mail is used, normally, but you can specify a + different one by setting the variable Mail Sender Library. + + The function Type Mailing List in the TMACS library is useful + for finding out where a mailing list forwards to. Invoke it with + + + + M-X Run Library$TMACS$Type Mailing List$ + + + and the equivalences of the mail address will be printed. Type + Mailing List prints the immediate equivalences of the mailing + list you specify, then traces their equivalences, down to + terminal addresses or addresses on non-ITS machines. Mailing + lists on other ITS machines can be traced; simply include theî 30 EMACS Manual for ITS Users + + + + site name in the argument. However, no lists on DM can be traced + because DM's forwarding data base is incompatible. See + section 22.2 [Libraries], page 135. + + + + 6.3 Recursive Editing Levelsî 6.3 Recursive Editing Levelsî 6.3 Recursive Editing Levels + + + _________ _______ _____î A recursive editing level is a state in which part of the + execution of one command involves doing some editing. You may be + editing the file you are working on, or you may be editing + completely something totally different from what you were working + on at top level. Recursive editing levels are indicated in the + mode line by square brackets ("[" and "]"). + + For example, the command M-X Edit Options allows you to change + the settings of EMACS options. During the execution of this + command, you enter a recursive editing level in which you edit a + list of options names and values using the usual EMACS editing + commands. While this is going on, the mode line says "[Edit + Options]" to inform you that you are in a recursive editing level + ____î and why. When you exit the recursive editing level, the Edit + Options command continues its work by looking at the changes you + have made in the list of options and changing the actual option + values accordingly. Only then is the original Edit Options + command finished. + + _____î Alternatively, you can abort the recursive editing level, which + gets you out of the Edit Options command and back to top level, + without allowing the command to finish. + + A recursive editing level differs from a subsystem in that the + commands are ordinary EMACS commands (though a handful may have + been changed slightly), whereas a subsystem defines its own + command language. + + The text you edit inside a recursive editing level depends on + the command which invoked the recursive editing level. It could + be a list of options and values, or a list of tab stop settings, + syntax table settings, a message to be sent, or any text that you + might wish to compose. + + Sometimes in a recursive editing level you edit text of the + file you are visiting, just as at top level. Why would this be? + Usually because a few commands are temporarily changed. For + example, Edit Picture in the PICTURE library defines commands + good for editing a picture made out of characters, then enters a + recursive editing level. When you exit, the specialî 31 EMACS Manual for ITS Users + + + + picture-editing commands go away. Until then, the brackets in + the mode line serve to remind you that, although the text you are + editing is your file, all is not normal. See section 26 + [PICTURE], page 183. + + In any case, if the mode line says "[...]" you are inside a + recursive editing level, and the way to exit (send the message, + redefine the options, get rid of the picture-editing commands, + etc.) is with the command C-M-C (^R Exit). See section 6.4 + [Exiting], page 31. If you change your mind about the command + (you don't want to send the message, or change your options, + etc.) then you should use the command C-] (Abort Recursive Edit) + to get out. See section 24.1 [Aborting], page 159. + + Inside recursive editing levels, the help option Help R is + defined to print the full documentation of the command which + invoked the recursive editing level. The other normal Help + options are still available for asking about commands you want to + use while inside the recursive edit. + + When the text in the mode line is surrounded by parentheses, it + __________î means that you are inside a Minibuffer. A minibuffer is a + special case of the recursive editing level. Like any other, it + can be aborted safely with C-]. See section 23 [Minibuffer], + page 156. + + + + 6.4 Exiting Levels; Exiting EMACSî 6.4 Exiting Levels; Exiting EMACSî 6.4 Exiting Levels; Exiting EMACS + + + C-X C-C Exit from EMACS to the superior job. + C-M-C Exit from EMACS or from a recursive editing + level. + + + The general EMACS command to exit is C-M-C (^R Exit). This + command is used to exit from a recursive editing level back to + the top level of EMACS, and to exit from EMACS at top level back + to HACTRN. If your keyboard does not have a Meta key, you must + type this command by means of a bit prefix character, as C-C C-C + or as Altmode C-C. Note carefully the difference between exiting + a recursive editing level and aborting it: exiting allows the + command which invoked the recursive editing level to finish its + job with the text as you have edited it, whereas aborting cancels + whatever the command was going to do. See section 24.1 + [Aborting], page 159. + + We cannot say in general how to exit a subsystem, since eachî 32 EMACS Manual for ITS Users + + + + subsystem defines its own command language, but the convention is + to use the character "Q". + + You can exit from EMACS back to the superior job, usually + HACTRN, at any time, even within a recursive editing level, with + the command C-X C-C (^R Return to Superior). If this is used + while you are inside a recursive editing level, then when EMACS + is re-entered you will still be inside the recursive editing + level. + + Exiting EMACS does not normally save the visited file, because + it is not the case that users exit EMACS only when they are + "finished editing". If you want the file saved, you must use C-X + C-S. Exiting does cause an auto save if Auto Save mode is in + use. + + Exiting from EMACS runs the function & Exit EMACS. This + function executes the value of the variable Exit Hook, if it is + nonzero; otherwise, it does auto-save if Auto Save mode is on. + & Exit EMACS also executes the value of the variable Exit to + Superior Hook, if it is defined. If EMACS is continued, the + value of Return from Superior Hook is executed.î 33 EMACS Manual for ITS Users + + + CHAPTER SEVENî CHAPTER SEVENî CHAPTER SEVEN + SELF-DOCUMENTATION COMMANDSî SELF-DOCUMENTATION COMMANDSî SELF-DOCUMENTATION COMMANDS + + + + EMACS provides extensive self-documentation features which + revolve around a single character, called the Help character. At + any time while using EMACS, you can type the Help character to + ask for help. How to type the Help character depends on the + terminal you are using, but aside from that the same character + always does the trick. If your keyboard has a key labeled Help + (above the H), type that key (together with the Top key). + Otherwise the way you type the Help character is actually C-_ + (Control-Underscore) followed by an H (this is two characters to + type, but let's not worry about that). Whatever it is you have + to type, to EMACS it is just the Help character. On some + terminals just figuring out how to type a Control-Underscore is + hard! Typing Underscore and adding the Control key is what + logically ought to work, but on some terminals it does not. + Sometimes Control-Shift-O works. On VT-100 terminals, typing + Control-/ or Control-? sends a Control-_ character. + + If you type Help while you are using a subsystem such as INFO, + it prints a list of the commands of that subsystem. + + If you type Help in the middle of a multi-character command, it + often tells you about what sort of thing you should type next. + For example, if you type M-X and then Help, it tells you about + M-X and how to type the name of the command. If you finish the + function name and the Altmode and then type Help, it tells you + about the function you have specified so you can know what + arguments it needs. If you type C-X and then type Help, it tells + you about the C-X commands. + + But normally, when it's time for you to start typing a new + command, Help offers you several options for asking about what + commands there are and what they do. It prompts with "Doc (? for + help):" at the bottom of the screen, and you should type a + character to say what kind of help you want. You could type Help + or "?" at this point to find out what options are available. The + ones you are most likely to need are described here. + + The most basic Help options are Help C and Help D. You can use + them to ask what a particular command does. Help C is for + character commands; type the command you want to know about after + the Help and the "C" ("C" stands for Character). Thus, Help C + M-F or Help C Altmode F tells you about the M-F command. Help D + is for asking about functions (extended commands); type the name + of the function and a Return. Thus, Help D Lisp Mode tellsî 34 EMACS Manual for ITS Users + + + + you about M-X Lisp Mode. Help D can also tell you the + documentation of a variable, if you give it a variable's name + instead of a function's name. "D" stands for "Describe", since + Help D actually uses the function Describe to do the work. + + A more complicated sort of question to ask is, "what are the + commands for working with files?" For this, you can type Help A, + followed by the string "file" and a Return. It prints a list of + all the functions that have "file" anywhere in their names, + including Save All Files, ^R Save File, Append to File, etc. If + some of the functions are connected to commands, it tells you + that too. For example, it would say that you can invoke ^R Save + File by typing C-X C-S. "A" stands for "Apropos", since Help A + actually uses the function Apropos to do the substring matching. + Help A does not list internal functions, only those the + nonprogrammer is likely to use. If you want subroutines to be + listed as well, you must call Apropos yourself. + + Because Apropos looks only for functions whose names contain + the string which you specify, you must use ingenuity in choosing + substrings. If you are looking for commands for killing + backwards and Help A Kill Backwards doesn't reveal any, don't + give up. Try just Kill, or just Backwards, or just Back. Be + persistent. Pretend you are playing Adventure. + + Here is a set of Apropos strings that covers many classes of + EMACS commands, since there are strong conventions for naming the + standard EMACS commands. By giving you a feel for the naming + conventions, this set should also serve to aid you in developing + a technique for picking Apropos strings. + + + character, line, word, sentence, paragraph, region, page, + buffer, screen, window, bounds, file, dir, beginning, + end, case, mode, forward, backward, next, previous, up, + down, search, kill, delete, mark, fill, indent, change. + + + There is also a convention for how command names start for + certain common kinds of operations: many commands start with one + of the words "Edit", "View", "Insert", "List", or "What". + + If you are inside a recursive editing level, Help R prints out + the complete documentation of that recursive editing level. See + section 6.3 [Recursive], page 30. Help ? also tells you briefly + what sort of recursive editing level you are in, in addition to + describing the available Help options. If you are not inside a + recursive editing level, Help R says that you are at top level.î 35 EMACS Manual for ITS Users + + + + If something surprising happens, and you are not sure what + commands you typed, use Help L. Help L prints the last 60 + command characters you typed in. This is also helpful if you + suffer from line noise. If you see commands that you don't know, + you can use Help C to find out what they do. + + If a command doesn't do what you thought you knew it should do, + you can ask to see whether it has changed recently. Help N + prints out the file called EMACS;EMACS NEWS which is an archive + of announcements of changes to EMACS. + + To find out about the other Help options, type Help Help. That + is, when the first Help asks for an option, type Help to ask what + is available. + + Finally, you should know about the documentation files for + EMACS, which are EMACS;EMACS GUIDE and EMACS;EMACS CHART. + EMACS GUIDE is a version of the manual formatted to be printed + out on a terminal or line printer. EMACS CHART has a brief + description of all the commands, known as the wall chart, because + it is good to post on the wall near your terminal.î 36 EMACS Manual for ITS Users + + + CHAPTER EIGHTî CHAPTER EIGHTî CHAPTER EIGHT + THE MARK AND THE REGIONî THE MARK AND THE REGIONî THE MARK AND THE REGION + + + + In general, a command which processes an arbitrary part of the + buffer must know where to start and where to stop. In EMACS, + ___î such commands usually operate on the text between point and the + ____ ___ ______î mark. This range of text is called the region. To specify a + region, you set point to one end of it and mark at the other. It + doesn't matter which one is set first chronologically, or which + one comes earlier in the text. Here are some commands for + setting the mark: + + + C-@ Set the mark where point is. + C-Space The same. + C-X C-X Interchange mark and point. + M-@ Set mark after end of next word. This + command and the following three do not move + point. + C-M-@ Set mark after end of next Lisp s-expression. + C-< Set mark at beginning of buffer. + C-> Set mark at end of buffer. + M-H Put region around current paragraph. + C-M-H Put region around current Lisp defun. + C-X H Put region around entire buffer. + C-X C-P Put region around current page. + + + For example, if you wish to convert part of the buffer to all + upper-case, you can use the C-X C-U command, which operates on + the text in the region. You can first go to the beginning of the + text to be capitalized, put the mark there, move to the end, and + then type C-X C-U. Or, you can set the mark at the end of the + text, move to the beginning, and then type C-X C-U. C-X C-U runs + the function ^R Uppercase Region, whose name signifies that the + region, or everything between point and the mark, is to be + capitalized. + + The most common way to set the mark is with the C-@ command or + the C-Space command (^R Set/Pop Mark). They set the mark where + point is. Then you can move point away, leaving the mark behind. + + It isn't actually possible to type C-Space on non-Meta + keyboards. Yet on many terminals the command appears to work + anyway! This is because trying to type a Control-Space on those + terminals actually sends the character C-@, which means the same + thing as C-Space. A few keyboards just send a Space. If you + have one of them, you type C-@, or customize your EMACS.î 37 EMACS Manual for ITS Users + + + + Since terminals have only one cursor, there is no way for EMACS + to show you where the mark is located. You have to remember. + The usual solution to this problem is to set the mark and then + use it soon, before you forget where it is. But you can see + where the mark is with the command C-X C-X (^R Exchange Point and + Mark) which puts the mark where point was and point where the + mark was. The extent of the region is unchanged, but the cursor + and point are now at the previous location of the mark. + + C-X C-X is also useful when you are satisfied with the location + of point but want to move the mark; do C-X C-X to put point there + and then you can move it. A second use of C-X C-X, if necessary, + puts the mark at the new location with point back at its original + location. + + If you insert or delete before the mark, the mark may drift + through the text. If the buffer contains "FOO BAR" and the mark + is before the "B", then if you delete the "F" the mark will be + before the "A". This is an unfortunate result of the simple way + the mark is implemented. It is best not to delete or insert at + places above the mark until you are finished using it and don't + care where it drifts to. + + + + 8.1 Commands to Mark Textual Objectsî 8.1 Commands to Mark Textual Objectsî 8.1 Commands to Mark Textual Objects + + + There are commands for placing the mark on the other side of a + certain object such as a word or a list, without having to move + there first. M-@ (^R Mark Word) puts the mark at the end of the + next word, while C-M-@ (^R Mark Sexp) puts it at the end of the + next s-expression. C-> (^R Mark End) puts the mark at the end of + the buffer, while C-< (^R Mark Beginning) puts it at the + beginning. These characters allow you to save a little typing or + redisplay, sometimes. + + Other commands set both point and mark, to delimit an object in + the buffer. M-H (^R Mark Paragraph) puts point at the beginning + of the paragraph it was inside of (or before), and puts the mark + at the end. M-H does all that's necessary if you wish to indent, + case-convert, or kill a whole paragraph. C-M-H (^R Mark Defun) + similarly puts point before and the mark after the current or + next defun. C-X C-P (^R Mark Page) puts point before the current + page (or the next or previous, according to the argument), and + mark at the end. The mark goes after the terminating page + delimiter (to include it), while point goes after the preceding + page delimiter (to exclude it). Finally, C-X H (^R Mark Whole + Buffer) makes the region the entire buffer by putting point at + the beginning and the mark at the end.î 38 EMACS Manual for ITS Users + + + + 8.2 The Ring of Marksî 8.2 The Ring of Marksî 8.2 The Ring of Marks + + + Aside from delimiting the region, the mark is also useful for + remembering a spot that you may want to go back to. To make this + feature more useful, EMACS remembers 16 previous locations of the + mark. Most commands that set the mark push the old mark onto + this stack. To return to a marked location, use C-U C-@ (or + C-U C-Space). This moves point to where the mark was, and + restores the mark from the stack of former marks. So repeated + use of this command moves point to all of the old marks on the + stack, one by one. Since the stack is actually a ring, enough + uses of C-U C-@ bring point back to where it was originally. + Insertion and deletion can cause the saved marks to drift, but + they will still be good for this purpose because they are + unlikely to drift very far. + + Some commands whose primary purpose is to move point a great + distance take advantage of the stack of marks to give you a way + to undo the command. The best example is M-<, which moves to the + beginning of the buffer. It sets the mark first, so that you can + use C-U C-@ or C-X C-X to go back to where you were. Searches + sometimes set the mark; it depends on how far they move. Because + of this uncertainty, searches type out "^@" if they set the mark. + The normal situation is that searches leave the mark behind if + they move at least 500 characters, but you can change that value + since it is kept in the variable Auto Push Point Option. By + setting it to 0, you can make all searches set the mark. By + setting it to a very large number such as ten million, you can + prevent all searches from setting the mark. The string to be + typed out when this option does its thing is kept in the variable + Auto Push Point Notification.î 39 EMACS Manual for ITS Users + + + + CHAPTER NINEî CHAPTER NINEî CHAPTER NINE + KILLING AND MOVING TEXTî KILLING AND MOVING TEXTî KILLING AND MOVING TEXT + + + + The commonest way of moving or copying text with EMACS is to + kill it, and get it back again in one or more places. This is + very safe because the last several pieces of killed text are all + remembered, and it is versatile, because the many commands for + killing syntactic units can also be used for moving those units. + There are also other ways of moving text for special purposes. + + + + 9.1 Deletion and Killingî 9.1 Deletion and Killingî 9.1 Deletion and Killing + + + Most commands which erase text from the buffer save it so that + you can get it back if you change your mind, or move or copy it + ____î to other parts of the buffer. These commands are known as kill + commands. The rest of the commands that erase text do not save + ______î it; they are known as delete commands. The delete commands + include C-D and Rubout, which delete only one character at a + time, and those commands that delete only spaces or line + separators. Commands that can destroy significant amounts of + nontrivial data generally kill. The commands' names and + individual descriptions use the words "kill" and "delete" to say + which they do. If you do a kill command by mistake, you can use + the Undo command to undo it (See section 24.3 [Undo], page 163.). + + + C-D Delete next character. + Rubout Delete previous character. + M-\ Delete spaces and tabs around point. + C-X C-O Delete blank lines around the current + line. + M-^ Join two lines by deleting the CRLF and + any indentation. + C-K Kill rest of line or one or more lines. + C-W Kill region (from point to the mark). + M-D Kill word. + M-Rubout Kill word backwards. + C-X Rubout Kill back to beginning of sentence. + M-K Kill to end of sentence. + C-M-K Kill s-expression. + C-M-Rubout Kill s-expression backwards. î 40 EMACS Manual for ITS Users + + + + 9.1.1 Deletionî 9.1.1 Deletionî 9.1.1 Deletion + + + The most basic delete commands are C-D and Rubout. C-D deletes + the character after the cursor, the one the cursor is "on top of" + or "underneath". The cursor doesn't move. Rubout deletes the + character before the cursor, and moves the cursor back. Line + separators act like single characters when deleted. Actually, + C-D and Rubout aren't always delete commands; if you give an + argument, they kill instead. This prevents you from losing a + great deal of text by typing a large argument to a C-D or Rubout. + + The other delete commands are those which delete only + formatting characters: spaces, tabs and line separators. M-\ + (^R Delete Horizontal Space) deletes all the spaces and tab + characters before and after point. C-X C-O (^R Delete Blank + Lines) deletes all blank lines after the current line, and if the + current line is blank deletes all blank lines preceding the + current line as well (leaving one blank line, the current line). + M-^ (^R Delete Indentation) joins the current line and the + previous line, or the current line and the next line if given an + argument. See section 11.3 [Indentation], page 54. + + A function ^R Delete Region used to exist, but it was too + dangerous. When you want to delete a large amount of text + without saving a copy of it (perhaps because it is very big), you + can set point and mark around the text and then type + + + M-Altmode + MRK$$ + + + (This is a use of the minibuffer. See section 23 [Minibuffer], + page 156.). + + + 9.1.2 Killing by Linesî 9.1.2 Killing by Linesî 9.1.2 Killing by Lines + + + The simplest kill command is the C-K command (^R Kill Line). + If given at the beginning of a line, it kills all the text on the + line, leaving it blank. If given on a blank line, the blank line + disappears. As a consequence, if you go to the front of a + non-blank line and type two C-K's, the line disappears + completely. + + More generally, C-K kills from point up to the end of the line, + unless it is at the end of a line. In that case it kills theî 41 EMACS Manual for ITS Users + + + + line separator following the line, thus merging the next line + into the current one. Invisible spaces and tabs at the end of + the line are ignored when deciding which case applies, so if + point appears to be at the end of the line, you can be sure the + line separator will be killed. + + If C-K is given a positive argument, it kills that many lines, + and the separators that follow them (however, text on the current + line before point is spared). With a negative argument, it kills + back to a number of line beginnings. An argument of -2 means + kill back to the second line beginning. If point is at the + beginning of a line, that line beginning doesn't count, so + C-U - 2 C-K with point at the front of a line kills the two + previous lines. + + C-K with an argument of zero kills all the text before point on + the current line. + + + 9.1.3 Other Kill Commandsî 9.1.3 Other Kill Commandsî 9.1.3 Other Kill Commands + + + A kill command which is very general is C-W (^R Kill Region), + which kills everything between point and the mark. With this + command, you can kill any contiguous characters, if you first set + the mark at one end of them and go to the other end. + + Other syntactic units can be killed: words, with M-Rubout and + M-D (See section 11.1 [Words], page 50.); s-expressions, with + C-M-Rubout and C-M-K (See section 20.6.1 [S-expressions], + page 111.); sentences, with C-X Rubout and M-K (See section 11.2 + [Sentences], page 52.). + + + + 9.2 Un-Killingî 9.2 Un-Killingî 9.2 Un-Killing + + + Un-killing is getting back text which was killed. The usual + way to move or copy text is to kill it and then un-kill it one or + more times. + + + C-Y Yank (re-insert) last killed text. + M-Y Replace re-inserted killed text with the + previously killed text. + M-W Save region as last killed text without killing. + C-M-W Append next kill to last batch of killed text. î 42 EMACS Manual for ITS Users + + + + ____ ______ ____ ____î Killed text is pushed onto a ring buffer called the kill ring + that remembers the last 8 blocks of text that were killed. (Why + it is called a ring buffer will be explained below). The command + C-Y (^R Un-kill) reinserts the text of the most recent kill. It + leaves the cursor at the end of the text, and puts the mark at + the beginning. Thus, a single C-W undoes the C-Y (M-X Undo also + does so). C-U C-Y leaves the cursor in front of the text, and + the mark after. This is only if the argument is specified with + just a C-U, precisely. Any other sort of argument, including C-U + and digits, has an effect described below. + + If you wish to copy a block of text, you might want to use M-W + (^R Copy Region), which copies the region into the kill ring + without removing it from the buffer. This is approximately + equivalent to C-W followed by C-Y, except that M-W does not mark + the buffer as "changed" and does not temporarily change the + screen. + + There is only one kill ring, and switching buffers or files has + no effect on it. After visiting a new file, whatever was last + killed in the previous file is still on top of the kill ring. + This is important for moving text between files. + + + 9.2.1 Appending Killsî 9.2.1 Appending Killsî 9.2.1 Appending Kills + + + Normally, each kill command pushes a new block onto the kill + ring. However, two or more kill commands in a row combine their + text into a single entry on the ring, so that a single C-Y + command gets it all back as it was before it was killed. This + means that you don't have to kill all the text in one command; + you can keep killing line after line, or word after word, until + you have killed it all, and you can still get it all back at + once. (Thus we join television in leading people to kill + thoughtlessly). + + Commands that kill forward from point add onto the end of the + previous killed text. Commands that kill backward from point add + onto the beginning. This way, any sequence of mixed forward and + backward kill commands puts all the killed text into one entry + without rearrangement. + + If a kill command is separated from the last kill command by + other commands, it starts a new entry on the kill ring, unless + you tell it not to by saying C-M-W (^R Append Next Kill) in front + of it. The C-M-W tells the following command, if it is a kill + command, to append the text it kills to the last killed text, + instead of starting a new entry. With C-M-W, you can killî 43 EMACS Manual for ITS Users + + + + several separated pieces of text and accumulate them to be yanked + back in one place. + + + 9.2.2 Un-killing Earlier Killsî 9.2.2 Un-killing Earlier Killsî 9.2.2 Un-killing Earlier Kills + + + To recover killed text that is no longer the most recent kill, + you need the Meta-Y (^R Un-kill Pop) command. The M-Y command + should be used only after a C-Y command or another M-Y. It takes + the un-killed text inserted by the C-Y and replaces it with the + text from an earlier kill. So, to recover the text of the + next-to-the-last kill, you first use C-Y to recover the last + kill, and then use M-Y to move back to the previous kill. + + You can think of all the last few kills as living in a ring. + After a C-Y command, the text at the front of the ring is also + present in the buffer. M-Y "rotates" the ring, bringing the + previous string of text to the front, and this text replaces the + other text in the buffer as well. Enough M-Y commands can rotate + any part of the ring to the front, so you can get at any killed + text as long as it is recent enough to be still in the ring. + Eventually the ring rotates all the way around and the most + recent killed text comes to the front (and into the buffer) + again. M-Y with a negative argument rotates the ring backwards. + If the region doesn't match the text at the front of the ring, + M-Y is not allowed. + + In any case, when the text you are looking for is brought into + the buffer, you can stop doing M-Y's and it will stay there. + It's really just a copy of what's at the front of the ring, so + editing it does not change what's in the ring. And the ring, + once rotated, stays rotated, so that doing another C-Y gets + another copy of what you rotated to the front with M-Y. + + If you change your mind about un-killing, a C-W or M-X Undo + gets rid of the un-killed text at any point, after any number of + M-Y's. C-W pushes the text onto the ring again. M-X Undo does + not. + + If you know how many M-Y's it would take to find the text you + want, then there is an alternative. C-Y with an argument greater + than one restores the text the specified number of entries down + on the ring. Thus, C-U 2 C-Y gets the next to the last block of + killed text. It differs from C-Y M-Y in that C-U 2 C-Y does not + permanently rotate the ring. + + A way of viewing the contents of the kill ring is î 44 EMACS Manual for ITS Users + + + + M-X View Q-register$..K + + + You must add one to the indices listed by this command, to get + the argument to use with C-Y to yank any particular string. + + + + 9.3 Other Ways of Copying Textî 9.3 Other Ways of Copying Textî 9.3 Other Ways of Copying Text + + + Usually we copy or move text by killing it and un-killing it, + but there are other ways that are useful for copying one block of + text in many places, or for copying many scattered blocks of text + into one place. In addition to those described here, see the + self-documentation of the MOVE library. + + + 9.3.1 Accumulating Textî 9.3.1 Accumulating Textî 9.3.1 Accumulating Text + + + You can accumulate blocks of text from scattered locations + either into a buffer or into a file if you like. + + To append them into a buffer, use the command C-X A + (^R Append to Buffer), which inserts a copy of + the region into the specified buffer at the location of point in + that buffer. If there is no buffer with the name you specify, + one is created. If you append text into a buffer which has been + used for editing, the copied text goes into the middle of the + text of the buffer, wherever point happens to be in it. + + Point in that buffer is left at the end of the copied text, so + successive uses of C-X A accumulate the text in the specified + buffer in the same order as they were copied. If C-X A is given + an argument, point in the other buffer is left before the copied + text, so successive uses of C-X A add text in reverse order. + + You can retrieve the accumulated text from that buffer with M-X + Insert Buffer$. This inserts a copy of the text + in that buffer into the selected buffer. You can also select the + other buffer for editing. See section 14 [Buffers], page 83, for + background information on buffers. + + Strictly speaking, C-X A does not always append to the text + already in the buffer. But if it is used on a buffer which + starts out empty, it does keep appending to the end. + + Instead of accumulating text within EMACS, in a buffer, you canî 45 EMACS Manual for ITS Users + + + + append text directly into a disk file with the command M-X Append + to File$. It adds the text of the region to the + end of the specified file. M-X Prepend to File adds the text to + the beginning of the file instead. The file is changed + immediately on disk. These commands are normally used with files + that are not being visited in EMACS. They have the advantage of + working even on files too large to fit into the EMACS address + space. + + + 9.3.2 Copying Text Many Timesî 9.3.2 Copying Text Many Timesî 9.3.2 Copying Text Many Times + + + When you want to insert a copy of the same piece of text + frequently, the kill ring becomes impractical, since the text + moves down on the ring as you edit, and will be in an + unpredictable place on the ring when you need it again. For this + case, you can use the commands C-X X (^R Put Q-register) and C-X + G (^R Get Q-register) to move the text. + + C-X X stores a copy of the text of the region in a place + called q-register . With an argument, C-X X deletes the text + as well. can be a letter or a digit. This gives 36 places + in which you can store a piece of text. C-X G inserts in the + buffer the text from q-register . Normally it leaves point + before the text and places the mark after, but with a numeric + argument it puts point after the text and the mark before. + + The q-registers are important temporary variables in TECO + programming, but you don't have to understand them, only to know + that what you save with C-X X A is what you will get with C-X G + A. + + Do not use q-registers M and R in this way, if you are going to + use the TECO commands MM and MR.î 46 EMACS Manual for ITS Users + + + CHAPTER TENî CHAPTER TENî CHAPTER TEN + SEARCHINGî SEARCHINGî SEARCHING + + + + Like other editors, EMACS has commands for searching for an + occurrence of a string. The search command is unusual in that it + ___________î is incremental; it begins to search before you have finished + typing the search string. As you type in the search string, + EMACS shows you where it would be found. When you have typed + enough characters to identify the place you want, you can stop. + Depending on what you will do next, you may or may not need to + terminate the search explicitly with an Altmode first. + + + C-S Search forward. + C-R Search backward. + C-S $ C-W Word search, ignoring whitespace. + + + The command to search is C-S (^R Incremental Search). C-S + reads in characters and positions the cursor at the first + occurrence of the characters that you have typed. If you type + C-S and then F, the cursor moves right after the first "F". Type + an "O", and see the cursor move to after the first "FO". After + another "O", the cursor is after the first "FOO" after the place + where you started the search. At the same time, the "FOO" has + echoed at the bottom of the screen. + + If you type a mistaken character, you can rub it out. After + the FOO, typing a rubout makes the "O" disappear from the bottom + of the screen, leaving only "FO". The cursor moves back to the + "FO". Rubbing out the "O" and "F" moves the cursor back to where + you started the search. + + When you are satisfied with the place you have reached, you can + type an Altmode, which stops searching, leaving the cursor where + the search brought it. Also, any command not specially + meaningful in searches stops the searching and is then executed. + Thus, typing C-A would exit the search and then move to the + beginning of the line. Altmode is necessary only if the next + command you want to type is a printing character, Rubout, + Altmode, C-Q, or another search command, since those are the + characters that have special meanings inside the search. + + Sometimes you search for "FOO" and find it, but not the one you + expected to find. There was a second FOO that you forgot about, + before the one you were looking for. Then type another C-S and + the cursor will find the next FOO. This can be done any number + of times. If you overshoot, you can rub out the C-S's.î 47 EMACS Manual for ITS Users + + + + After you exit a search, you can search for the same string + again by typing just C-S C-S: one C-S command to start the search + and then another C-S to mean "search again". + + If your string is not found at all, the echo area says "Failing + I-Search". The cursor is after the place where EMACS found as + much of your string as it could. Thus, if you search for FOOT, + and there is no FOOT, you might see the cursor after the FOO in + FOOL. At this point there are several things you can do. If + your string was mistyped, you can rub some of it out and correct + it. If you like the place you have found, you can type Altmode + or some other EMACS command to "accept what the search offered". + Or you can type C-G, which throws away the characters that could + not be found (the "T" in "FOOT"), leaving those that were found + (the "FOO" in "FOOT"). A second C-G at that point undoes the + search entirely. + + The C-G "quit" command does special things during searches; + just what, depends on the status of the search. If the search + has found what you specified and is waiting for input, C-G + cancels the entire search. The cursor moves back to where you + started the search. If C-G is typed while the search is actually + searching for something or updating the display, or after search + failed to find some of your input (having searched all the way to + the end of the file), then only the characters which have not + been found are discarded. Having discarded them, the search is + now successful and waiting for more input, so a second C-G will + cancel the entire search. Make sure you wait for the first C-G + to ding the bell before typing the second one; if typed too soon, + the second C-G may be confused with the first and effectively + lost. + + You can also type C-R at any time to start searching backwards. + If a search fails because the place you started was too late in + the file, you should do this. Repeated C-R's keep looking for + more occurrences backwards. A C-S starts going forwards again. + C-R's can be rubbed out just like anything else. If you know + that you want to search backwards, you can use C-R instead of C-S + to start the search, because C-R is also a command (^R Reverse + Incremental Search) to search backward. Note to all customizers: + all this command does is call the current definition of + ^R Incremental Search with a negative argument. + + All sorts of searches in EMACS normally ignore the case of the + text they are searching through; if you specify searching for + FOO, then Foo and foo are also considered a match. If you do not + want this feature, set the variable Case Search to zero. See + section 22.3 [Variables], page 137.î 48 EMACS Manual for ITS Users + + + + Recall that Altmode exits a search without doing anything else, + while other Control and Meta characters exit the search and then + have their normal function. The variable Search Exit Char says + which character should exit and do nothing else; its initial + value is 033 octal, for Altmode. This value is a 9-bit + character, so 300 octal means that Control-@ is the exit + character. Any other character whose definition indirects to the + specified one also serves as an exit character; so if you specify + C-B, C-b will also exit, and if you specify C-@, then C-Space + will also exit. Set the variable to -1, and there is no exit + character. + + Bit prefix characters are not processed before the decision as + to whether and how to exit, so if you specify M-: as the exit + character, you must have a meta key on your terminal in order to + type it. I do not know if this can be changed easily. + + Search Exit Option says what to do with other Control and Meta + characters. 0 says that they should be part of the search + string. A nonzero value says that they should exit and then have + their normal function. If this variable is nonzero, the Search + Exit Char is distinguished only by not having its normal function + when it exits. If this is zero, the Search Exit Char is the only + way to exit. + + A non-incremental search is also available. Type Altmode (or + the Search Exit Char) right after the C-S to get it. Do + + + M-X Describe$^R String Search + + + for details. Some people who prefer non-incremental searches put + that function on Meta-S, and ^R Character Search (do M-X + Describe$ for details) on C-S. It can do one useful thing which + incremental search cannot: search for words regardless of where + the line breaks. + + Word search searches for a sequence of words without regard to + how the words are separated. More precisely, you type a string + of many words, using single spaces to separate them, and the + string can be found even if there are multiple spaces or line + separators between the words. Other punctuation such as commas + or periods must match exactly. This is useful in conjunction + with documents formatted by text justifiers. If you edit while + looking at the printed, formatted version, you can't tell where + the line breaks are in the source file. With word search, you + can search without having to know.î 49 EMACS Manual for ITS Users + + + + Word search is a special case of non-incremental search and is + invoked with C-S Altmode C-W. This is followed by the search + string, which must always be terminated with an Altmode. + Searching does not start until the final Altmode is typed. + Search Exit Char and Search Exit Option do not apply to word + search. + + You do not even have to type each word in full, in a word + search. An abbreviation is good enough. Word search finds the + first occurrence of a sequence of words whose beginnings match + the words of the argument.î 50 EMACS Manual for ITS Users + + + CHAPTER ELEVENî CHAPTER ELEVENî CHAPTER ELEVEN + COMMANDS FOR ENGLISH TEXTî COMMANDS FOR ENGLISH TEXTî COMMANDS FOR ENGLISH TEXT + + + + EMACS enables you to manipulate words, sentences, or paragraphs + of text. In addition, there are commands to fill text, and + convert case. For text-justifier input files, there are commands + that may help manipulate font change commands and underlining. + + Editing files of text in a human language ought to be done + using Text mode rather than Fundamental mode. Invoke M-X Text + Mode to enter Text mode. See section 20.1 [Major Modes], + page 102. M-X Text Mode causes Tab to run the function ^R Tab to + Tab Stop, which allows you to set any tab stops with M-X Edit Tab + Stops (See section 11.3 [Indentation], page 54.). Features + concerned with comments in programs are turned off except when + explicitly invoked. Automatic display of parenthesis matching is + turned off, which is what most people want. Finally, the syntax + table is changed so that periods are not considered part of a + word, while apostrophes, backspaces and underlines are. + + If you are editing input for the text justifier TEX, you might + want to use TEX mode instead of Text mode. See the file INFO; + ETEX. For editing SCRIBE input, use SCRIBE mode. See + section 11.8 [SCRIBE], page 61. Someday there may be special + major modes for other text justifiers. + + + + 11.1 Word Commandsî 11.1 Word Commandsî 11.1 Word Commands + + + EMACS has commands for moving over or operating on words. By + convention, they are all Meta- characters. + + + M-F Move Forward over a word. + M-B Move Backward over a word. + M-D Kill up to the end of a word. + M-Rubout Kill back to the beginning of a word. + M-@ Mark the end of the next word. + M-T Transpose two words; drag a word forward or + backward across other words. + + + Notice how these commands form a group that parallels the + character based commands C-F, C-B, C-D, C-T and Rubout. M-@ is + related to C-@.î 51 EMACS Manual for ITS Users + + + + The commands Meta-F (^R Forward Word) and Meta-B (^R Backward + Word) move forward and backward over words. They are thus + analogous to Control-F and Control-B, which move over single + characters. Like their Control- analogues, Meta-F and Meta-B + move several words if given an argument. Meta-F with a negative + argument moves backward like Meta-B, and Meta-B with a negative + argument moves forward. Forward motion stops right after the + last letter of the word, while backward motion stops right before + the first letter. + + It is easy to kill a word at a time. Meta-D (^R Forward Kill + Word) kills the word after point. To be precise, it kills + everything from point to the place Meta-F would move to. Thus, + if point is in the middle of a word, only the part after point is + killed. If some punctuation comes after point and before the + next word, it is killed along with the word. If you wish to kill + only the next word but not the punctuation, simply do Meta-F to + get the end, and kill the word backwards with Meta-Rubout. + Meta-D takes arguments just like Meta-F. + + Meta-Rubout (^R Backward Kill Word) kills the word before + point. It kills everything from point back to where Meta-B would + move to. If point is after the space in "FOO, BAR", then "FOO, " + is killed. If you wish to kill just "FOO", then do a Meta-B and + a Meta-D instead of a Meta-Rubout. + + Meta-T (^R Transpose Words) moves the cursor forward over a + word, dragging the word preceding or containing the cursor + forward as well. A numeric argument serves as a repeat count. + Meta-T with a negative argument undoes the effect of Meta-T with + a positive argument; it drags the word behind the cursor backward + over a word. An argument of zero, instead of doing nothing, + transposes the word at point (surrounding or adjacent to it) with + the word at mark. In any case, the delimiter characters between + the words do not move. For example, "FOO, BAR" transposes into + "BAR, FOO" rather than "BAR FOO,". + + To operate on the next n words with an operation which applies + between point and mark, you can either set the mark at point and + then move over the words, or you can use the command + Meta-@ (^R Mark Word) which does not move point, but sets the + mark where Meta-F would move to. It can be given arguments just + like Meta-F. + + Note that if you are in Atom Word mode and in Lisp mode, all + the word commands regard an entire Lisp atom as a single word. + See section 22.1 [Minor Modes], page 133. + + The word commands' understanding of syntax is completelyî 52 EMACS Manual for ITS Users + + + + controlled by the syntax table. Any character can, for example, + be declared to be a word delimiter. See section 22.4 [Syntax], + page 139. + + + + 11.2 Sentence and Paragraph Commandsî 11.2 Sentence and Paragraph Commandsî 11.2 Sentence and Paragraph Commands + + + The EMACS commands for manipulating sentences and paragraphs + are mostly Meta- commands, so as to resemble the word-handling + commands. + + + M-A Move back to the beginning of the sentence. + M-E Move forward to the end of the sentence. + M-K Kill forward to the end of the sentence. + M-[ Move back to previous paragraph beginning. + M-] Move forward to next paragraph end. + M-H Put point and mark around this paragraph (around + the following one, if between paragraphs). + C-X Rubout + Kill back to the beginning of the sentence. + + + 11.2.1 Sentencesî 11.2.1 Sentencesî 11.2.1 Sentences + + + The commands Meta-A and Meta-E (^R Backward Sentence and + ^R Forward Sentence) move to the beginning and end of the current + sentence, respectively. They were chosen to resemble Control-A + and Control-E, which move to the beginning and end of a line. + Unlike them, Meta-A and Meta-E if repeated or given numeric + arguments move over successive sentences. EMACS considers a + sentence to end wherever there is a ".", "?" or "!" followed by + the end of a line or two spaces, with any number of ")"'s, "]"'s, + "'"'s, or '"' 's allowed in between. Neither M-A nor M-E moves + past the CRLF or spaces which delimit the sentence. + + Just as C-A and C-E have a kill command, C-K, to go with them, + so M-A and M-E have a corresponding kill command M-K (^R Kill + Sentence) which kills from point to the end of the sentence. + With minus one as an argument it kills back to the beginning of + the sentence. Larger arguments serve as a repeat count. + + There is a special command, C-X Rubout (^R Backward Kill + Sentence) for killing back to the beginning of a sentence, + because this is useful when you change your mind in the middle of + composing text.î 53 EMACS Manual for ITS Users + + + + 11.2.2 Paragraphsî 11.2.2 Paragraphsî 11.2.2 Paragraphs + + + Meta-[ (^R Backward Paragraph) moves to the beginning of the + current or previous paragraph, while Meta-] (^R Forward + Paragraph) moves to the end of the current or next paragraph. + Blank lines and text justifier command lines separate paragraphs + and are not part of any paragraph. Also, an indented line starts + a new paragraph. + + In major modes for programs (as opposed to Text mode), + paragraphs are determined only by blank lines. This makes the + paragraph commands continue to be useful even though there are no + paragraphs per se. + + When there is a fill prefix, then paragraphs are delimited by + all lines which don't start with the fill prefix. See + section 11.4 [Filling], page 56. + + When you wish to operate on a paragraph, you can use the + command Meta-H (^R Mark Paragraph) to set the region around it. + This command puts point at the beginning and mark at the end of + the paragraph point was in. Before setting the new mark at the + end, a mark is set at the old location of point; this allows you + to undo a mistaken Meta-H with two C-U C-@'s. If point is + between paragraphs (in a run of blank lines, or at a boundary), + the paragraph following point is surrounded by point and mark. + Thus, for example, Meta-H C-W kills the paragraph around or after + point. + + One way to make an "invisible" paragraph boundary that does not + show if the file is printed is to put space-backspace at the + front of a line. The space makes the line appear (to the EMACS + paragraph commands) to be indented, which usually means that it + starts a paragraph. + + The variable Paragraph Delimiter should be a TECO search string + (See section 19.3 [TECO search strings], page 101.) composed of + ^î various characters or character sequences separated by |O's. A + line whose beginning matches the search string is either the + beginning of a paragraph or a text justifier command line part of + no paragraph. If the line begins with period, singlequote, "-", + "\" or "@", it can be a text justifier command line; otherwise, + it can be the beginning of a paragraph; but it cannot be either + one unless Paragraph Delimiter is set up to recognize it. Thus, + ^î ".|O " as the Paragraph Delimiter string means that lines + starting with spaces start paragraphs, lines starting with + periods are text justifier commands, and all other nonblank lines + are nothing special.î 54 EMACS Manual for ITS Users + + + 11.3 Indentation Commands for Textî 11.3 Indentation Commands for Textî 11.3 Indentation Commands for Text + + + Tab Indents "appropriately" in a mode-dependent + fashion. + M-Tab Inserts a tab character. + Linefeed Is the same as Return followed by Tab. + M-^ Undoes a Linefeed. Merges two lines. + M-M Moves to the line's first nonblank character. + M-I Indent to tab stop. In Text mode, Tab does + this also. + C-M-\ Indent several lines to same column. + C-X Tab Shift block of lines rigidly right or left. + + + The way to request indentation is with the Tab command. Its + precise effect depends on the major mode. In Text mode, it + indents to the next tab stop. You can set the tab stops with + Edit Tab Stops (see below). If you just want to insert a tab + character in the buffer, you can use M-Tab or C-Q Tab. + + For English text, usually only the first line of a paragraph + should be indented. So, in Text mode, new lines created by Auto + Fill mode are not indented. Text mode tells Auto Fill mode not + to indent new lines by setting the variable Space Indent Flag to + zero. + + But sometimes you want to have an indented paragraph. In such + cases, use M-X Edit Indented Text, which enters a submode in + which Tab and Auto Fill indent each line under the previous line, + and only blank lines delimit paragraphs. Alternatively, you can + specify a fill prefix (see below). + + To undo a line-break, whether done manually or by Auto Fill, + use the Meta-^ (^R Delete Indentation) command to delete the + indentation at the front of the current line, and the line + boundary as well. They are replaced by a single space, or by no + space if before a ")" or after a "(", or at the beginning of a + line. To delete just the indentation of a line, go to the + beginning of the line and use Meta-\ (^R Delete Horizontal + Space), which deletes all spaces and tabs around the cursor. + + To insert an indented line before the current line, do C-A, + C-O, and then Tab. To make an indented line after the current + line, use C-E Linefeed. + + To move over the indentation on a line, do Meta-M or C-M-M + (^R Back to Indentation). These commands, given anywhere on a + line, position the cursor at the first nonblank character on the + line.î 55 EMACS Manual for ITS Users + + + + There are also commands for changing the indentation of several + lines at once. Control-Meta-\ (^R Indent Region) gives each line + which begins in the region the "usual" indentation by invoking + Tab at the beginning of the line. A numeric argument specifies + the indentation, and each line is shifted left or right so that + it has exactly that much. C-X Tab (^R Indent Rigidly) moves all + of the lines in the region right by its argument (left, for + negative arguments). The whole group of lines move rigidly + sideways, which is how the command gets its name. + + + 11.3.1 Tab Stopsî 11.3.1 Tab Stopsî 11.3.1 Tab Stops + + + For typing in tables, you can use Text mode's definition of + Tab, ^R Tab to Tab Stop, which may be given anywhere in a line, + and indents from there to the next tab stop. If you are not in + Text mode, this function can be found on M-I anyway. + + Set the tab stops using Edit Tab Stops, which allows you to + edit some text which defines the tab stops. Here is what it + would look like for ordinary tab stops every eight columns. + + + : : : : : : + 123456789 123456789 123456789 123456789 123456789 1234 + 0 10 20 30 40 50 + + + The first line contains a colon or period at each tab stop. + Colon indicates an ordinary tab, which fills with whitespace; a + period specifies that characters be copied from the corresponding + columns of the second line below it. Thus, you can tab to a + column automatically inserting dashes or periods, etc. It is + your responsibility to put in the second line the text to be + copied. In the example above there are no periods, so the second + line is not used, and is left blank. + + The third and fourth lines you see contain column numbers to + help you edit. They are only there while you are editing the tab + stops; they are not really part of the tab settings. The first + two lines reside in the variable Tab Stop Definitions when they + are not being edited. If the second line is not needed, Tab Stop + Definitions can be just one line, with no CRLFs. This makes it + easier to set the variable in a local modes list. See + section 22.7 [Locals], page 150. + + EMACS normally uses both tabs and spaces to indent lines, andî 56 EMACS Manual for ITS Users + + + + displays tab characters using eight-character tab stops. (How + the ASCII character tab is displayed has nothing to do with the + definition of the Tab character as a command). If you prefer, + all indentation can be made from spaces only. To request this, + turn off Indent Tabs mode with the command M-X Indent Tabs Mode. + To display tabs with different tab stops, set the TECO flag FS + TAB WIDTH$ to the desired interval. This is useful for + displaying files brought from other operating systems whose + normal tab stop spacing is not 8. See section 22.5 [FS Flags], + page 142. + + To convert all tabs in a file to spaces, you can use M-X + Untabify. M-X Tabify performs the opposite transformation, + replacing spaces with tabs whenever possible, but only if there + are at least three of them so as not to obscure ends of + sentences. A numeric argument to Tabify or Untabify specifies + the interval between tab stops to use for computing how to change + the file. By default, they use the same interval being used for + display. The visual appearance of the text should never be + changed by Tabify or Untabify without a numeric argument. + + + + 11.4 Text Fillingî 11.4 Text Fillingî 11.4 Text Filling + + + Space in Auto Fill mode, breaks lines when appropriate. + M-Q Fill paragraph. + M-G Fill region (G is for Grind, by analogy with + Lisp). + M-S Center a line. + C-X = Show current cursor position. + + + ______î Auto Fill mode lets you type in text that is filled (broken up + into lines that fit in a specified width) as you go. If you + alter existing text and thus cause it to cease to be properly + filled, EMACS can fill it again if you ask. + + Entering Auto Fill mode is done with M-X Auto Fill. From then + on, lines are broken automatically at spaces when they get longer + than the desired width. New lines created by Auto Fill are + usually indented, but in Text mode they are not. To leave Auto + Fill mode, execute M-X Auto Fill again. When Auto Fill mode is + in effect, the word "Fill" appears in the mode line. + + When you finish a paragraph, you can type Space with an + argument of zero. This doesn't insert any spaces, but it does + move the last word of the paragraph to a new line if it doesn'tî 57 EMACS Manual for ITS Users + + + + fit in the old line. Return also moves the last word, but it may + create another blank line. + + If you edit the middle of a paragraph, it may no longer be + correctly filled. To refill a paragraph, use the command Meta-Q + (^R Fill Paragraph). It causes the paragraph that point is + inside, or the one after point if point is between paragraphs, to + be refilled. All the line-breaks are removed, and then new ones + are inserted where necessary. M-Q can be undone with M-X Undo + (See section 24.3 [Undo], page 163.). + + If you are not happy with Meta-Q's idea of where paragraphs + start and end (the same as Meta-H's. See section 11.2 + [Paragraphs], page 52.), you can use Meta-G (^R Fill Region) + which refills everything between point and mark. Sometimes, it + is ok to fill a region of several paragraphs at once. Meta-G + recognizes a blank line or an indented line as starting a + paragraph and does not fill it in with the preceding line. The + sequence space-backspace at the front of a line prevents it from + being filled into the preceding line but is invisible when the + file is printed. However, the full sophistication of the + paragraph commands in recognizing paragraph boundaries is not + available. The purpose of M-G is to allow you to override + EMACS's usual criteria for paragraph boundaries. M-G can be + undone with M-X Undo. + + Giving an argument to M-G or M-Q causes the text to be + _________î justified as well as filled. This means that extra spaces are + inserted between the words so as to make the right margin come + out exactly even. I do not recommend doing this. If someone + else has uglified some text by justifying it, you can unjustify + it (remove the spaces) with M-G or M-Q without an argument. + + The command Meta-S (^R Center Line) centers a line within the + current line width. With an argument, it centers several lines + individually and moves past them. + + The maximum line width for filling is in the variable Fill + Column. Both M-Q and Auto Fill make sure that no line exceeds + this width. The easiest way to set the variable is to use the + command C-X F (^R Set Fill Column), which places the margin at + the column point is on, or at the column specified by a numeric + argument. The fill column is initially column 70. + + To fill a paragraph in which each line starts with a special + marker (which might be a few spaces, giving an indented + ____ ______î paragraph), use the fill prefix feature. Move point to a spot + right after the special marker and give the command C-X Period + (^R Set Fill Prefix). Then, filling the paragraph will removeî 58 EMACS Manual for ITS Users + + + + the marker from each line beforehand, and put the marker back in + on each line afterward. Auto Fill when there is a fill prefix + inserts the fill prefix at the front of each new line. Also, any + line which does not start with the fill prefix is considered to + start a paragraph. To turn off the fill prefix, do C-X Period + with point at the front of a line. The fill prefix is kept in + the variable Fill Prefix. + + The command C-X = (What Cursor Position) can be used to find + out the column that the cursor is in, and other miscellaneous + information about point which is quick to compute. It prints a + line in the echo area that looks like this: + + + X=5 Y=7 CH=101 .=3874(35% of 11014) H=<3051,4640> + + + In this line, the X value is the column the cursor is in (zero at + the left), the Y value is the screen line that the cursor is in + (zero at the top), the CH value is the octal value of the + character after point (101 is "A"), the "point" value is the + number of characters in the buffer before point, and the values + in parentheses are the percentage of the buffer before point and + the total size of the buffer. + + The H values are the virtual buffer boundaries, indicate which + part of the buffer is still visible when narrowing has been done. + If you have not done narrowing, the H values are omitted. For + more information about the virtual buffer boundaries, See + section 17 [Narrowing], page 93. + + + + 11.5 Case Conversion Commandsî 11.5 Case Conversion Commandsî 11.5 Case Conversion Commands + + + EMACS has commands for converting either a single word or any + arbitrary range of text to upper case or to lower case. + + + M-L Convert following word to lower case. + M-U Convert following word to upper case. + M-C Capitalize the following word. + C-X C-L Convert region to lower case. + C-X C-U Convert region to upper case. + + + The word conversion commands are the most useful. Meta-L + (^R Lowercase Word) converts the word after point to lower case,î 59 EMACS Manual for ITS Users + + + + moving past it. Thus, successive Meta-L's convert successive + words. Meta-U (^R Uppercase Word) converts to all capitals + instead, while Meta-C (^R Uppercase Initial) puts the first + letter of the word into upper case and the rest into lower case. + All these commands convert several words at once if given an + argument. They are especially convenient for converting a large + amount of text from all upper case to mixed case, because you can + move through the text using M-L, M-U or M-C on each word as + appropriate. + + When given a negative argument, the word case conversion + commands apply to the appropriate number of words before point, + but do not move point. This is convenient when you have just + typed a word in the wrong case. You can give the case conversion + command and continue typing. + + If a word case conversion command is given in the middle of a + word, it applies only to the part of the word which follows the + cursor, treating it as a whole word. + + The other case conversion commands are C-X C-U (^R Uppercase + Region) and C-X C-L (^R Lowercase Region), which convert + everything between point and mark to the specified case. Point + and mark do not move. These commands ask for confirmation if the + region contains more than Region Query Size characters; they also + save the original contents of the region so you can undo them + (See section 24.3 [Undo], page 163.). + + + + 11.6 Font-Changingî 11.6 Font-Changingî 11.6 Font-Changing + + + EMACS has commands to insert and move font change commands as + understood by the TJ6, R and BOLIO text justifiers. A font + ^î change is assumed to be of the form |F meaning select the + ^î specified font, or |F* meaning select the previously selected + font. + + + M-# Change previous word's font, or next word's. + C-X # Change font of region. + + + M-# (^R Change Font Word) is a command to change the font of a + word. Its action is rather complicated to describe, but that is + because it tries to be as versatile and convenient as possible in + practice.î 60 EMACS Manual for ITS Users + + + + If you type M-# with an argument, the previous word is put into + the font specified by the argument. Point is not changed. This + means that, if you want to insert a word and put it in a specific + font, you can type the word, then use M-# to change its font, and + ^î then go on inserting. The font is changed by putting a |F + ^î before the word and a |F* after. + + If you type M-# with no argument, it takes the last font change + ^ ^î (either a |F or |F*, whichever is later) and moves it one + word forward. What this implies is that you can change the font + of several consecutive words incrementally by moving after the + first word, issuing M-# with an argument to set that word's font, + and then typing M-# to extend the font change past more words. + Each M-# advances past one more word. + + M-# with a negative argument is the opposite of M-# with no + ____î argument; it moves the last font change back one word. If you + type too many M-#'s, you can undo them this way. If you move one + font change past another, one or both are eliminated, so as to do + the right thing. As a result, M-Minus M-# will undo a M-# with + an argument. Try it! + + You can also change the font of a whole region by putting point + and the mark around it and issuing C-X # (^R Change Font Region), + with the font number as argument. C-X # with a negative argument + removes all font changes inside or adjacent to the region. + + + + 11.7 Underliningî 11.7 Underliningî 11.7 Underlining + + + EMACS has two commands for manipulating text-justifier + underlining command characters. These commands do not produce + any sort of overprinting in the text file itself; they insert or + move command characters which direct text justifiers to produce + underlining. By default, commands for the text justifier R are + used. + + + M-_ Underline previous word or next word. + C-X _ Underline region. + + + M-_ is somewhat like M-# in that it either creates an underline + around the previous word or extends it past the next word. + However, where a font change requires that you specify a font + number, an underline is just an underline and has no parameter + for you to specify. Also, it is assumed that the textî 61 EMACS Manual for ITS Users + + + + justifier's commands for starting and ending underlines are + distinguishable, whereas you can't tell from a font change + whether it is "starting" something or "ending" something. M-_ + differs slightly from M-# as a result. + + M-_ with no argument creates an underline around the previous + word if there is none. If there is an underline there, it is + extended one word forward. Thus, you can insert an underlined + word by typing the word and then a M-_. Or you can underline + several existing words by moving past the first of them, and + typing one M-_ for each word. + + __î M-_ given in the vicinity of an underline-begin moves it + forward. Thus, it should be thought of as applying to any + boundary, where underlining either starts or stops, and moving it + forward. If a begin underlining is moved past an end, or vice + versa, they both disappear. + + Giving M-_ an argument merely tells it to apply to several + words at once instead of one. M-_ with a positive argument of n + underlines the next n words, either creating an underlined area + or extending an existing one. With a negative argument, that + many previous words are underlined. Thus, M-_ can do more things + with underlines than M-# can do with font changes, because of the + facts that you don't need to use the argument to say which font, + and you can tell a beginning from an end. + + For larger scale operations, you can use C-X _ to place + underlines from point to mark, or C-X _ with a negative argument + to remove all underlining between point and mark. + + ^ ^î By default, |B is used to begin an underline and |E is used to + end one. The variables Underline Begin and Underline End may be + created and set to strings to use instead. For a single + character you can use the numeric ASCII code for it. + + + + 11.8 SCRIBE Modeî 11.8 SCRIBE Modeî 11.8 SCRIBE Mode + + + SCRIBE mode provides many special editing commands for + manipulating the commands for the text justifier SCRIBE. + Instances of SCRIBE commands are referred to in EMACS as + ____________î environments, though strictly speaking it is the command name + which is the environment, and not all commands either. + + + C-M-N Move forward over SCRIBE environment.î 62 EMACS Manual for ITS Users + + + + C-M-P Move backward over SCRIBE environment. + C-M-U Move up to beginning of containing SCRIBE + environment. + C-M-D Move forward and down inside next SCRIBE + environment. + C-M-E Move up to end of containing SCRIBE + environment. + C-M-H Put point and mark around containing SCRIBE + environment. + C-M-G Change name of containing SCRIBE environment. + C-M-Q Change form of containing SCRIBE environment. + + + In SCRIBE mode the standard expression motion and killing + commands C-M-F, C-M-B, C-M-K and C-M-Rubout operate on units of + balanced SCRIBE delimiters. Additional commands specific to + SCRIBE mode move around the structure of SCRIBE environments. + C-M-N (^R Forward Environment) moves forward over an entire + SCRIBE expression (@, environment name and arguments), C-M-P + (^R Backward Environment) moves back, C-M-U (^R Backward Up + Environment) moves up, and C-M-D (^R Down Environment) moves + down. C-M-E (^R End of Environment) moves up to the end of the + containing SCRIBE environment. C-M-H (^R Mark Environment) puts + point and mark around the containing SCRIBE environment. + + Speaking of balanced delimiters, SCRIBE mode does not work + properly when the characters ' and ` are used as delimiters for + arguments. This is because the parser expects each character to + be either a parenthesis (which matches a different character) or + a string quote (which matches itself), not both. See + section 22.4 [Syntax Table], page 139. SCRIBE mode simply does + not treat these characters as possible delimiters, and it is best + not to use them. It is just as well, since if SCRIBE mode + actually tried to handle these delimiters it would be confused by + apostrophes in the text. + + Other commands transform SCRIBE environments. C-M-G (^R Change + Environment Name) changes the name of the SCRIBE environment that + point is inside. For example, if point is somewhere inside an + @I[...] environment, C-M-G could be used to change the @I to an + @U. C-M-G reads the new environment name from the terminal and + replaces the old environment name with it. + + C-M-Q (^R Change Form) changes the containing SCRIBE + environment between the brief form such as @Example[...] and the + longer form @Begin(Example)...@End(Example). If the environment + has the brief form, it is changed to the longer form, and vice + versa.î 63 EMACS Manual for ITS Users + + + + In SCRIBE mode, paragraphs are redefined to understand SCRIBE + commands in a way that is usually right. Any line that consists + entirely of one SCRIBE command is considered a + paragraph-separating line, just like a blank line. This does the + right thing for @Begin and @End, and for many other cases. So is + any line that starts with an @; or @' command. The @; and @' + commands are supposed to be no-ops at the beginning of a line, + and can therefore be used to mark lines that you think should + separate paragraphs. Which one works, and when, depends on the + version of SCRIBE. Eventually, @; will always work. + + Aside from the above cases, SCRIBE commands are considered part + of the text, so an @I command which happens to end up at the + front of a line will not separate paragraphs. SCRIBE mode + accomplishes this by redefining M-[ and the function ^R Backward + Paragraph to be the function ^R Backward SCRIBE Paragraph. Lines + starting with page delimiters are paragraph delimiters as usual, + and lines starting with space or tab start paragraphs as usual. + + The comment commands know that comments in SCRIBE files start + with "@Comment{" and end with "}". See section 20.5 [Comments], + page 107. + + You can use the M-X Compile command to invoke SCRIBE. See + section 20.2 [Compile], page 103. It operates on the file + currently visited. You can use a string argument to specify + switches. After SCRIBE is finished, you must type $P to resume + EMACS. Then, if there were any errors, EMACS splits the screen + and displays the errors in the bottom window. The command M-X + Next Scribe Error moves to the point in the file at which the + next error occurred. Currently the only ITS machine on which + SCRIBE is installed is MC. + + The functions listed in this section live in the library + SCRIBE, which is loaded automatically if you enter SCRIBE mode. + + + + 11.9 Dissociated Pressî 11.9 Dissociated Pressî 11.9 Dissociated Press + + + M-X Dissociated Press is a command for scrambling a file of + text either word by word or character by character. Starting + from a bufferfull of straight English, it produces extremely + amusing output. Dissociated Press prints its output on the + terminal. It does not change the contents of the buffer. + + Dissociated Press operates by jumping at random from one point + in the buffer to another. In order to produce plausible outputî 64 EMACS Manual for ITS Users + + + + rather than gibberish, it insists on a certain amount of overlap + between the end of one run of consecutive words or characters and + the start of the next. That is, if it has just printed out + "president" and then decides to jump to a different point in the + file, it might spot the "ent" in "pentagon" and continue from + there, producing "presidentagon". Long sample texts produce the + best results. + + A negative argument to M-X Dissociated Press tells it to + operate character by character, and specifies the number of + overlap characters. A positive argument tells it to operate word + by word and specifies the number of overlap words. In this mode, + whole words are treated as the elements to be permuted, rather + than characters. No argument is equivalent to an argument of + two. For your againformation, the output is only printed on the + terminal. The file you start with is not changed. + + Dissociated Press produces nearly the same results as a Markov + chain based on a frequency table constructed from the sample + text. It is, however, an independent, ignoriginal invention. + Dissociated Press techniquitously copies several consecutive + characters from the sample between random choices, whereas a + Markov chain would choose randomly for each word or character. + This makes for more plausible sounding results. + + It is a mustatement that too much use of Dissociated Press can + be a developediment to your real work. Sometimes to the point of + outragedy. And keep dissociwords out of your documentation, if + you want it to be well userenced and properbose. Have fun. Your + buggestions are welcome.î 65 EMACS Manual for ITS Users + + + CHAPTER TWELVEî CHAPTER TWELVEî CHAPTER TWELVE + COMMANDS FOR FIXING TYPOSî COMMANDS FOR FIXING TYPOSî COMMANDS FOR FIXING TYPOS + + + + In this section we describe the commands that are especially + useful for the times when you catch a mistake in your text just + after you have made it, or change your mind while composing text + on line. + + + Rubout Delete last character. + M-Rubout Kill last word. + C-X Rubout Kill to beginning of sentence. + C-T Transpose two characters. + C-X C-T Transpose two lines. + C-X T Transpose two arbitrary regions. + M-Minus M-L Convert last word to lower case. + M-Minus M-U Convert last word to all upper case. + M-Minus M-C Convert last word to lower case with + capital initial. + M-' Fix up omitted shift key on digit. + M-$ (Meta-Dollar Sign) Check and correct + spelling of word. + Correct Spelling + Check and correct spelling of entire + buffer. + + + + 12.1 Killing Your Mistakesî 12.1 Killing Your Mistakesî 12.1 Killing Your Mistakes + + + The Rubout command is the most important correction command. + When used among printing (self-inserting) characters, it can be + thought of as canceling the last character typed. + + When your mistake is longer than a couple of characters, it + might be more convenient to use M-Rubout or C-X Rubout. M-Rubout + kills back to the start of the last word, and C-X Rubout kills + back to the start of the last sentence. C-X Rubout is + particularly useful when you are thinking of what to write as you + type it, in case you change your mind about phrasing. M-Rubout + and C-X Rubout save the killed text for C-Y and M-Y to retrieve + (See section 9.2 [Un-killing], page 41.). + + M-Rubout is often useful even when you have typed only a few + characters wrong, if you know you are confused in your typing and + aren't sure exactly what you typed. At such a time, you cannotî 66 EMACS Manual for ITS Users + + + + correct with Rubout except by looking at the screen to see what + you did. It requires less thought to kill the whole word and + start over again, especially if the system is heavily loaded. + + + + 12.2 Transpositionî 12.2 Transpositionî 12.2 Transposition + + + The common error of transposing two characters can be fixed, + when they are adjacent, with the C-T command. Normally, C-T + transposes the two characters on either side of the cursor. When + given at the end of a line, rather than transposing the last + character of the line with the line separator, which would be + useless, C-T transposes the last two characters on the line. So, + if you catch your transposition error right away, you can fix it + with just a C-T. If you don't catch it so fast, you must move + the cursor back to between the two transposed characters. If you + transposed a space with the last character of the word before it, + the word motion commands are a good way of getting there. + Otherwise, a reverse search (C-R) is often the best way. See + section 10 [Search], page 46. + + To transpose two lines, use the C-X C-T command (^R Transpose + Lines). M-T transposes words and C-M-T transposes s-expressions. + + A more general transpose command is C-X T (^R Transpose + Regions). This transposes two arbitrary blocks of text, which + need not even be next to each other. To use it, set the mark at + one end of one block, then at the other end of the block; then go + to the other block and set the mark at one end, and put point at + the other. In other words, point and the last three marks should + be at the four locations which are the ends of the two blocks. + It does not matter which of the four locations point is at, or + which order the others were marked. C-X T transposes the two + blocks of text thus identified, and relocates point and the three + marks without changing their order. + + + + 12.3 Case Conversionî 12.3 Case Conversionî 12.3 Case Conversion + + + A very common error is to type words in the wrong case. + Because of this, the word case-conversion commands M-L, M-U and + M-C have a special feature when used with a negative argument: + they do not move the cursor. As soon as you see you have + mistyped the last word, you can simply case-convert it and go on + typing. See section 11.5 [Case], page 58.î 67 EMACS Manual for ITS Users + + + + Another common error is to type a special character and miss + the shift key, producing a digit instead. There is a special + command for fixing this: M-' (^R Upcase Digit), which fixes the + last digit before point in this way (but only if that digit + appears on the current line or the previous line. Otherwise, to + minimize random effects of accidental use, M-' does nothing). + Once again, the cursor does not move, so you can use M-' when you + notice the error and immediately continue typing. Because M-' + needs to know the arrangement of your keyboard, the first time + you use it you must supply the information by typing the row of + _______ ____ ___ _____ ___î digits 1, 2, ... , 9, 0 but holding down the shift key. This + tells M-' the correspondence between digits and special + characters, which is remembered for the duration of the EMACS in + the variable Digit Shift Table. This command is called M-' + because its main use is to replace "7" with a single-quote. + + + + 12.4 Checking and Correcting Spellingî 12.4 Checking and Correcting Spellingî 12.4 Checking and Correcting Spelling + + + When you write a paper, you should correct its spelling at some + point close to finishing it (and maybe earlier as well). To + correct the entire buffer, do M-X Correct Spelling. This invokes + the SPELL spelling corrector program, which will ask you what to + do with each misspelled word. Refer to its documentation. When + it finished, you will be back in EMACS. + + To check the spelling of the word before point, and optionally + correct it as well, use the command M-$ (^R Correct Word + Spelling). This is a Dollar sign, not an Altmode! This command + sends the word to the SPELL program for correction. + + If SPELL recognizes the word as a correctly spelled one + (although not necessarily the one you meant!) you will see "Found + it" or "Found it because of" followed by the word without its + suffix. If the program cannot at all recognize the word, it will + print "Couldn't find it." + + If SPELL recognizes the word as a misspelling, it displays on + the screen the other words which are possibilities for the + correct spelling, and gives each one a number. Then, you can + type one of the following things: + + + 0 to 9 Replace misspelled word with that spelling + (preserving case, just like Replace String + and Query Replace, unless Case Replace is + zero).î 68 EMACS Manual for ITS Users + + + + Space Exit and make no changes. + % Read a digit as above and Query Replace (M-%) + the incorrect spelling with the correct one + from the beginning of the buffer. + + + No other responses are allowed. + + The cursor need not be immediately after the word you want to + correct; it can be in the middle, or following any word-separator + characters after the end of the word. Note that the major mode + you are using affects which characters are word-separators. See + section 22.4 [Syntax Table], page 139. + + The first time you use an EMACS spelling correction command, it + creates a SPELL job for you. From then on it uses the same SPELL + job. It's ok to kill the job if you don't think you'll be using + M-$ again during that session. But if you do leave the + job around checking words will much quicker. Giving M-$ a + negative argument (as in M-- M-$) kills the SPELL job. Of + course, you can kill it from DDT also. + + If you are a regular user of the SPELL program, you might have + a dictionary file of words which you use but which are foreign to + SPELL. If there are words in this file which you might want to + use M-$ to correct, you can specify that you want this dictionary + to be loaded into the spell job which EMACS uses. To do this, + set the variable Spell Initialization to the string of + SPELL program commands you want to use. For loading a + dictionary, this string would be a "Load " followed by the + dictionary filename. Other initialization commands for SPELL can + appear there also. The commands must be separated by altmodes. + + You can also pass arbitrary commands to the SPELL job with + command M-X Command to Spell. + + Because of the way the handling of other jobs from EMACS is + implemented on ITS, it is not possible to use M-$ in an EMACS + whose superior is not DDT. This typically applies to EMACS jobs + running under LISP (LISPT) and under :MAIL (MAILT).î 69 EMACS Manual for ITS Users + + + CHAPTER THIRTEENî CHAPTER THIRTEENî CHAPTER THIRTEEN + FILE HANDLINGî FILE HANDLINGî FILE HANDLING + + + + The basic unit of stored data is the file. Each program, each + paper, lives usually in its own file. To edit a program or + paper, the editor must be told the name of the file that contains + ________î it. This is called visiting the file. To make your changes to + ____î the file permanent on disk, you must save the file. EMACS also + has facilities for deleting files conveniently, and for listing + your file directory. Special text in a file can specify the + modes to be used when editing the file. + + + + 13.1 Visiting Filesî 13.1 Visiting Filesî 13.1 Visiting Files + + + C-X C-V Visit a file. + C-X C-Q Change regular visiting to read only, or vice + versa. + C-X C-S Save the visited file. + Meta-~ Tell EMACS to forget that the buffer has been + changed. + + + ________î Visiting a file means copying its contents into EMACS where you + can edit them. EMACS remembers the name of the file you visited. + Unless you use the multiple buffer or window features of EMACS, + you can only be visiting one file at a time. The name of the + file you are visiting in the currently selected buffer is visible + in the mode line when you are at top level, followed by its + version number if it has one in parentheses. + + The changes you make with EMACS are made in a copy inside + EMACS. The file itself is not changed. The changed text is not + ____î permanent until you save it in a file. The first time you change + the text, a star appears at the end of the mode line; this + indicates that the text contains fresh changes which will be lost + unless you save them. + + To visit a file, use the command C-X C-V (^R Visit File). + Follow the command with the name of the file you wish to visit, + terminated by a Return. If you can see a filename in the mode + line, then that name is the default, and any component of the + filename which you don't specify is taken from it. If EMACS + thinks you can't see the defaults, they are included in the + prompt. You can abort the command by typing C-G, or edit theî 70 EMACS Manual for ITS Users + + + + filename with Rubout or C-U. If you do type a Return to finish + the command, the new file's text appears on the screen, and its + name and version appear in the mode line. + + When you wish to save the file and make your changes permanent, + type C-X C-S (^R Save File). After the save is finished, C-X C-S + prints "Written: " in the echo area at the bottom of + the screen. If there are no changes to save (no star at the end + of the mode line), the file is not saved; it would be redundant + to save a duplicate of the previous version. + + Because a system crash can cause you to lose everything you + have done since the last save, we provide Auto Save mode, which + saves the files you are visiting at regular intervals + automatically. See section 13.3 [Auto Save], page 72. + Alternatively, you can use journal files. See section 24.4 + [Journals], page 164. + + What if you want to create a file? Just visit it. EMACS + prints "(New File)" but aside from that behaves as if you had + visited an existing empty file. If you make any changes and save + them, the file is created. If you visit a nonexistent file + unintentionally (because you typed the wrong file name), go ahead + and visit the file you meant. If you don't save the unwanted + file, it is not created. + + If you visit a file which is a link, EMACS prints + "(Link to )" to inform you of this. When you read a + file which is a link, you get the contents of the target file, + but if you save under the name of the link, you replace the link + and the target does not change. If you would prefer to alter the + target file, use Set Visited Filename to change the visited name + to the target file's name. See section 13.7 [Advanced File + Commands], page 79. + + If you alter one file and then visit another in the same + buffer, EMACS offers to save the old one. If you answer Y, the + old file is saved; if you answer N, all the changes you have made + to it since the last save are lost. You should not type ahead + after a file visiting command, because your type-ahead might + answer an unexpected question in a way that you would regret. + The variable Visit File Save Old controls this offer; normally, + it is one, which means that the offer is made. If it is minus + one, then the old file is always saved when you visit a new one + in the same buffer; no question is asked. If it is zero, the old + file is never saved. + + _________î A nonzero argument to C-X C-V specifies read-only visiting. + This means that EMACS prevents you from modifying the file unlessî 71 EMACS Manual for ITS Users + + + + you insist. You should use this when you visit a file that you + do no want to change, just to avoid changing it accidentally. If + you give C-X C-V a positive argument, then the file is read-only. + This means you can change the text in the buffer, but EMACS + requires extra confirmation if you ask to save the file, and + never offers to save it. If you give C-X C-V a negative + argument, then the buffer itself is read-only; commands to change + the text are not allowed. If the visited file is visited + read-only, in either fashion, then the characters "(R-O)" appear + in the mode line after the filename. The command C-X C-Q (^R Set + File Read-Only) is used to switch between read-only and normal + visiting. Its numeric argument means the same thing as the + argument to C-X C-V: zero means changes are allowed, positive + makes the file read-only, and negative makes the text itself + read-only. + + Sometimes you will change a buffer by accident. Even if you + undo the change by hand, EMACS still knows that "the buffer has + been changed". You can tell EMACS to believe that there have + been no changes with the Meta-~ (^R Buffer Not Modified) command. + This command simply clears the "modified" flag which says that + the buffer contains changes which need to be saved. Even if the + buffer really is changed EMACS will still act as if it were not. + If we take "~" to mean "not", then Meta-~ is "not" metafied. + + If EMACS is about to do an unrequested save, and discovers that + the text is now a lot shorter than it used to be, it tells you so + and asks for confirmation (Y or N). If you aren't sure what to + answer (because you are surprised that it has shrunk), type C-G + to abort everything, and take a look around. + + If EMACS is about to save a file and sees that the date of the + latest version on disk does not match what EMACS last read or + wrote, EMACS notifies you of this fact, and asks what to do, + because this probably means that something is wrong. For + example, someone else may have been editing the same file. If + this is so, there is a good chance that your work or his work + will be lost if you don't take the proper steps. You should + first find out exactly what is going on. The C-X C-D command to + list the directory will help. If you determine that someone else + has modified the file, save your file under different names (or + at least making a new version) and then SRCCOM the two files to + merge the two sets of changes. Also get in touch with the other + person so that he doesn't continue editing.î 72 EMACS Manual for ITS Users + + + 13.2 How to Undo Drastic Changes to a Fileî 13.2 How to Undo Drastic Changes to a Fileî 13.2 How to Undo Drastic Changes to a File + + + If you have made extensive changes to a file and then change + your mind about them, you can get rid of them by reading in the + previous version of the file. To do this, use M-X Revert File. + If you have been using Auto Save mode, it reads in the last + version of the visited file or the last auto save file, whichever + is more recent. + + In Auto Save mode, saving under special Auto Save filenames, + then you can ask to revert to the last "real" save, ignoring + subsequent auto saves, with C-U M-X Revert File. If you are + using the style of auto saving which saves under the real + filenames, this is not possible. + + M-X Revert File does not change point, so that if the file was + only edited slightly, you will be at approximately the same piece + of text after the Revert as before. If you have made drastic + changes, the same value of point in the old file may address a + totally different piece of text. + + Because M-X Revert File can be a disaster if done by mistake, + it asks for confirmation (Y or N) before doing its work. A + pre-comma argument can be used to inhibit the request for + confirmation when you call the function Revert File from a TECO + program, as in 1,M(M.M Revert File$). + + + + 13.3 Auto Save Mode: Protection Against Disastersî 13.3 Auto Save Mode: Protection Against Disastersî 13.3 Auto Save Mode: Protection Against Disasters + + + In Auto Save mode, EMACS saves your file from time to time + (based on counting your commands) without being asked. Your file + is also saved if you stop typing for more than a few minutes when + there are changes in the buffer. This prevents you from losing + more than a limited amount of work in a disaster. (Another + method of protection is the journal file. See section 24.4 + [Journals], page 164.). + + You can turn auto saving on or off in an individual buffer with + M-X Auto Save. In addition, you can have auto saving by default + in all buffers by setting the option Auto Save Default. The + frequency of saving, and the number of saved versions to keep, + can both be specified. + + Each time you visit a file, no matter how, auto saving is + turned on for that file if Auto Save Default is nonzero. Onceî 73 EMACS Manual for ITS Users + + + + you have visited a file, you can turn auto saving on or off with + M-X Auto Save. Like other minor mode commands, M-X Auto Save + turns the mode on with a positive argument, off with a zero or + negative argument; with no argument, it toggles. If you start + typing a new file into a buffer without visiting anything, Auto + Save mode is initially off, but you can turn it on with M-X Auto + Save. + + When an auto save happens, "(Auto Save)" is printed in the echo + area (On a printing terminal, the bell is rung instead). An + error in the process of auto saving prints "(Auto Save Error!)". + + Let us suppose that it is time for an automatic save to be + done: where should the file be saved? + + Two workable methods have been developed: save the file under + the names you have visited, or save it under some special "auto + save file name". Each solution has its good and bad points. The + first one is excellent some of the time, but intolerable the rest + of the time. The second is usually acceptable. Auto saving + under the visited file's actual names means that you need do + nothing special to gobble the auto save file when you need it; + and it means that there is no need to worry about interference + between two users sharing a directory, as long as they aren't + editing the same file at once. However, this method can + sometimes have problems: + + + If you visit a file on a device other than DSK, auto + saves can't go there, because it would probably be slow. + + If the file is visited read-only, then auto saves should + certainly not go under the names that are visited. + + If your file does not have a numeric version number, or + you have visited a fixed version, auto saves can't go + under that name, because they would clobber the original + file. + + If you haven't visited a file, there aren't any names to + use. + + + If none of those cases apply then it is possible to store auto + saves under the visited name. This is done, provided that you + enable it by setting the variable Auto Save Visited File to a + nonzero value. Otherwise, or if one of the cases listed above + applies, then the filename used for auto saves is taken from the + variable Auto Save Filenames, modified slightly so that differentî 74 EMACS Manual for ITS Users + + + + buffers save under different names. If the last two characters + of the FN1 are "00", then they are replaced by the last two + digits (or the only digit) of the buffer number, the number which + appears at the beginning of each line printed by C-X C-B. Auto + Save Filenames is usually set up by the default init file to + DSK:;_SAV00 >. + + When you want to save your file "for real", use C-X C-S, as + always. C-U C-X C-S is a way to request an "auto" save + explicitly. When you are auto saving under the visited + filenames, there is not much difference between an auto save and + a "real" save, except that an auto save will eventually be + deleted automatically by EMACS a few auto saves later, while a + "real" save will be left around forever (at least, Auto Save + won't delete it). + + When it is time to recover from a system crash by reloading the + auto save file, if auto saving was using the visited file names + you have nothing special to do. If auto saving was using special + auto save filenames, read in the last auto save file and then use + C-X C-W (Write File) to write it out in its real location. If + you want to go back to an auto save file to throw away changes + that you don't like, you can use M-X Revert File, which knows how + to find the most recent save, permanent or not, under whatever + filenames. See section 13.2 [Revert], page 72. + + For your protection, if a file has shrunk by more than 30% + since the last save, auto saving does not save. Instead it + prints a message that the file has shrunk. You can save + explicitly if you wish; after that, auto saving will resume. + + Although auto saving generates large numbers of files, it does + not clog directories, because it cleans up after itself. Only + the last Auto Save Max auto save files are kept; as further saves + are done, old auto saves are deleted. However, only files made + by auto saving (or by explicitly requested auto-saves with C-U + C-X C-S) are deleted in this way. If Auto Save Max is 1, then + repeated auto saves rewrite the same version of the file; the + version number is only incremented after a real save. (It will + write a new version if it is unable to rewrite the old one). + + The variable Auto Save Max is initially 2. Changing the value + may not take effect in a given buffer until you turn auto saving + off and on in that buffer. + + The number of characters of input between auto saves is + controlled by the variable Auto Save Interval. It is initially + 500. Changing this takes effect immediately.î 75 EMACS Manual for ITS Users + + + + If you use the multiple-buffer features of EMACS (See + section 14 [Buffers], page 83.) then you may want to have auto + saving for all buffers, not just the one that is selected at the + moment. To get this, set the variable Auto Save All Buffers + nonzero. + + + + 13.4 Listing a File Directoryî 13.4 Listing a File Directoryî 13.4 Listing a File Directory + + + To look at a part of a file directory, use the C-X C-D command + (^R Directory Display). With no argument, it shows you the file + you are visiting, and related files with the same first name. + C-U C-X C-D reads a filename from the terminal and shows you the + files related to that filename. + + To see the whole directory in a brief format, use the function + List Files, which takes the directory name as a string argument. + The function View Directory prints a verbose listing of a whole + directory. + + The variable Auto Directory Display can be set to make many + file operations display the directory automatically. The + variable is normally 0; making it positive causes write + operations such as Write File to display the directory, and + making it negative causes read operations such as Insert File or + visiting to display it as well. The display is done using the + default directory listing function which is kept in the variable + Directory Lister. Normally this is the function & Subset + Directory that displays only the files related to the current + default file. An alternative type of directory listing can be + obtained by setting Directory Lister to the function & Rotated + Directory Listing. After this function display the particular + file you are interested in, it offers to display the rest. If + you say "yes" (with a Space), it displays through the end of the + directory, and around to the beginning of the directory, stopping + where it originally started. See section 22.6 [Init], page 143. + + The function List Directories prints an alphabetized list of + all the file directories on the system. + + + + 13.5 Cleaning a File Directoryî 13.5 Cleaning a File Directoryî 13.5 Cleaning a File Directory + + + The normal course of editing constantly creates new versions of + files. If you don't eventually delete the old versions, theî 76 EMACS Manual for ITS Users + + + + directory will fill up and further editing will be impossible. + EMACS has commands that make it easy to delete the old versions. + + For complete flexibility to delete precisely the files you want + to delete, you can use the DIRED package. See section 13.6 + [DIRED], page 76, for more details. + + M-X Reap File and M-X Clean Directory are more convenient ways + to do the usual thing: keep only the two (or other number) most + recent versions. + + M-X Reap File$ counts the number of versions of + . If there are more than two, you are told the names of + the recent ones (to be kept) and the names of the older ones (to + be deleted), and asked whether to do the deletion (answer Y or + N). + + Reap File makes a special offer to delete individual files + whose FN2 indicates that they are likely to be temporary. The + list of temporary names is contained in a TECO search string in + the variable Temp File FN2 List. See section 19.3 [TECO search + strings], page 101. + + If you give M-X Reap File a null filename argument, or no + argument, then it applies to the file you are visiting. + + M-X Clean Directory$; cleans a whole directory of + old versions. Each file in the directory is processed a la M-X + Reap File. M-X Clean Directory with a null argument, or no + argument, cleans the directory containing the file you are + visiting. + + M-X Reap File and M-X Clean Directory can be given a numeric + argument which specifies how many versions to keep. For example, + C-U 4 M-X Reap File would keep the four most recent versions. + The default when there is no argument is the value of the + variable File Versions Kept, which is initially 2. + + + + 13.6 DIRED, the Directory Editor Subsystemî 13.6 DIRED, the Directory Editor Subsystemî 13.6 DIRED, the Directory Editor Subsystem + + + DIRED makes it easy to delete many of the files in a single + directory at once. It presents a copy of a listing of the + directory, which you can move around in, marking files for + deletion. When you are satisfied, you can tell DIRED to go ahead + and delete the marked files.î 77 EMACS Manual for ITS Users + + + + Invoke DIRED with M-X DIRED to edit the current default + directory, or M-X DIRED$; to edit directory . You + are then given a listing of the directory which you can move + around in with all the normal EMACS motion commands. Some EMACS + commands are made illegal and others do special things, but it's + still a recursive editing level which you can exit normally with + C-M-C and abort with C-]. + + + 13.6.1 Basic DIRED Commandsî 13.6.1 Basic DIRED Commandsî 13.6.1 Basic DIRED Commands + + + You can mark a file for deletion by moving to the line + describing the file and typing D, C-D, K, or C-K. The deletion + mark is visible as a D at the beginning of the line. Point is + moved to the beginning of the next line, so that several D's + delete several files. Alternatively, if you give D an argument + it marks that many consecutive files. Given a negative argument, + it marks the preceding file (or several files) and puts point at + the first (in the buffer) line marked. Most of the DIRED + commands (D, U, !, $, P, S, C, E, Space) repeat this way with + numeric arguments. + + If you wish to remove a deletion mark, use the U (for Undelete) + command, which is invoked like D: it removes the deletion mark + from the current line (or next few lines, if given an argument). + The Rubout command removes the deletion mark from the previous + line, moving up to that line. Thus, a Rubout after a D precisely + cancels the D. + + For extra convenience, Space is made a command similar to C-N. + Moving down a line is done so often in DIRED that it deserves to + be easy to type. Rubout is often useful simply for moving up. + + If you are not sure whether you want to delete a file, you can + examine it by typing E. This enters a recursive editing mode on + the file, which you can exit with C-M-C. The file is not really + visited at that time, and you are not allowed to change it. When + you exit the recursive editing level, you return to DIRED. The V + command is like E but uses View File to look at the file. + + When you have marked the files you wish to mark, you can exit + DIRED with C-M-C. If any files were marked for deletion, DIRED + lists them in a concise format, several per line. A file with + "!" appearing next to it in this list has not been saved on tape + and will be gone forever if deleted. A file with ">" in front of + it is the most recent version of a sequence and you should be + wary of deleting it. Then DIRED asks for confirmation of the + list. You can type "YES" (Just "Y" won't do) to go ahead andî 78 EMACS Manual for ITS Users + + + + delete them, "N" to return to editing the directory so you can + change the marks, or "X" to give up and delete nothing. No + Return character is needed. No other inputs are accepted at this + point. + + + 13.6.2 Other DIRED Commandsî 13.6.2 Other DIRED Commandsî 13.6.2 Other DIRED Commands + + + The "!" command moves down (or up, with an argument of -1) to + the next undumped file (one with a "!" before its date). + + N finds the next "hog": the next file which has at least three + versions (or, more than File Versions Kept). + + T when given on a line describing a link marks for deletion the + file which the link points to. This file need not be in the + directory you are editing to be deleted in this way. + + 1 copies the file you are pointing at to the primary pack. 2 + copies it to SECOND:. 3 copies it to THIRD:. 4 copies it to + FOURTH:. + + $ complements the don't-reap attribute of the file; this is + displayed as a dollar sign to the left of the file date. + + M moves the file to any other directory or device. You must + say where to move it. + + C runs SRCCOM to compare the file version you are pointing at + with the latest version of the same file. You must confirm the + SRCCOM command with a Return before it is executed; you can add + extra SRCCOM switches before the Return. When you return to + EMACS, the cursor moves down a line to the next file. + + H helps you clean up. It marks "old" versions of the current + file, and versions with "temporary" second file names, for + deletion. You can then use the D and U commands to add and + remove marks before deleting the files. The variables File + Versions Kept and Temp File FN2 List control which files H picks + for deletion. With an argument (C-U H), it does the whole + directory instead of just the current file. + + ? displays a list of the DIRED commands.î 79 EMACS Manual for ITS Users + + + + 13.6.3 Invoking DIREDî 13.6.3 Invoking DIREDî 13.6.3 Invoking DIRED + + + There are some other ways to invoke DIRED. The command C-X D + (^R Dired) puts you in DIRED on the directory containing the file + you are currently editing. With a numeric argument of 1 (C-U 1 + C-X D), only the current file is displayed instead of the whole + directory. In combination with the H command this can be useful + for cleaning up excess versions of a file after a heavy editing + session. With a numeric argument of 4 (C-U C-X D), it asks you + for the directory name. Type a directory name followed by a + semicolon, and/or a file name. If you explicitly specify a file + name only versions of that file are displayed, otherwise the + whole directory is displayed. + + + 13.6.4 Editing the DIRED Buffer Yourselfî 13.6.4 Editing the DIRED Buffer Yourselfî 13.6.4 Editing the DIRED Buffer Yourself + + + It is unwise to try to edit the text of the directory listing + yourself, without using the special DIRED commands, unless you + know what you are doing, since you can confuse DIRED that way. + To make it less likely that you will do so accidentally, the + self-inserting characters are all made illegal inside DIRED. + However, deleting whole lines at a time is certainly safe. This + does not delete the files described by those lines; instead, it + makes DIRED forget that they are there and thus makes sure they + ___î will not be deleted. Thus, M-X Delete Non-Matching Lines$FOO + is useful if you wish to delete only files with a FOO in their + names. See section 19 [Replacement], page 98. + + For more complicated things, you can use the minibuffer. When + you call the minibuffer from within DIRED, you get a perfectly + normal one. The special DIRED commands are not present while you + are editing in the minibuffer. To mark a file for deletion, + replace the space at the beginning of its line with a "D". To + remove a mark, replace the "D" with a space. + + + + 13.7 Miscellaneous File Operationsî 13.7 Miscellaneous File Operationsî 13.7 Miscellaneous File Operations + + + EMACS has extended commands for performing many other + operations on files. + + M-X View File$ allows you to scan or read a file by + sequential screenfuls without visiting the file. It enters a + subsystem in which you type a Space to see the next screenful orî 80 EMACS Manual for ITS Users + + + + a Backspace to see the previous screenful. Typing anything else + exits the command. View File does not visit the file; it does + not alter the contents of any buffer. The advantage of View File + is that the whole file does not need to be loaded before you can + begin reading it. The inability to do anything but page forward + or backward is a consequence. + + M-X Write File$ writes the contents of the buffer + into the file , and then visits that file. It can be + thought of as a way of "changing the name" of the file you are + visiting. Unlike C-X C-S, Write File saves even if the buffer + has not been changed. C-X C-W is another way of getting at this + command. + + M-X Insert File$ inserts the contents of into + the buffer at point, leaving point unchanged before the contents + and mark after them. The current defaults are used for , + and are updated. + + M-X Write Region$ writes the region (the text between + point and mark) to the specified file. It does not set the + visited filenames. The buffer is not changed. + + M-X Append to File$ appends the region to . + The text is added to the end of . + + M-X Prepend to File$ adds the text to the beginning + of instead of the end. + + M-X Set Visited Filename$ changes the name of the + file being visited without reading or writing the data in the + buffer. M-X Write File is approximately equivalent to this + command followed by a C-X C-S. + + M-X Delete File$ deletes the file. If you did not + get a chance to see the default filenames before typing the + filename to delete, then Delete File asks for confirmation before + deleting the file. + + M-X Copy File$$ copies the file. + + M-X Rename File$$ renames the file. + + ____î The default filenames for all of these operations are TECO + _______ _________î default filenames. Most of these operations also leave the TECO + default names set to the file they operated on. The TECO default + ___ ______î is not always the same as the file you are visiting. When you + visit a file, they start out the same; the commands mentioned + above change the TECO default, but do not change the visited + filenames. Each buffer has its own TECO default filenames.î 81 EMACS Manual for ITS Users + + + + The operation of visiting a file is available as a function + under the name M-X Visit File$. In this form, it uses + the TECO default as its defaults, though it still sets both the + TECO default and the visited filenames. + + + + 13.8 The Directory Comparison Subsystemî 13.8 The Directory Comparison Subsystemî 13.8 The Directory Comparison Subsystem + + + The function Compare Directories makes it easy to compare two + directories to see which files are present in both and which are + present only in one. It compares a directory on the local + machine with the directory of the same name on another machine. + + Do M-X Compare Directories$: $, + where is AI, ML, MC or DM, and is not the machine you + are on, is an optional directory name and semicolon, + and the optional switch is a slash followed by S, D or L. + + After a while of crunching, you will be placed in a recursive + editing level on a listing of both directories. The reason for + the recursive editing level is simply to make it easy for you to + view the comparison; unlike DIRED, Compare Directories does not + have any commands for moving or deleting the files. To exit, do + C-M-C. + + Here is a sample of part of a directory comparison: + + + AI RMS #1=72 #2=78 #3=71 #4=77 #5=87 - + MC RMS #0=231 #1=254 #13=2844 + AI MC .DDT. (INIT) 1 11/18/76 01:08 10/21/76 05:06 + AI MC L .DDT_ (INIT) STAN.K ML EXIT + MC L .TECO. (INIT) .TECO. .TECO. (INIT) + AI AR2 1 16 2/6/77 17:51 + AI AR3 1 13 2/17/77 21:37 + AI L ATS ORDER .INFO. @ ORDER + MC FTPU 4 9 !3/4/77 16:46 + MC FTPU 5 9 !3/4/77 16:49 + AI MC MATCH 1 15 !3/4/77 15:39 !3/4/77 15:39 + + + It begins with one line for each of the two directories. These + lines say which two directories they are, and how much disk space + is available on each of the machines. + + Then there comes the list of files, one line for each distinct + pair of filenames that appears. At the beginning of the lineî 82 EMACS Manual for ITS Users + + + + appear the names of the machines on which the file exists. At + the end of the line come the creation dates (or names pointed at, + for links) of the file for the machines it is on. Note that all + the dates/link names for the first machine line up, and so do all + those for the second machine. + + The switches allow you to view only some of the files. The /S + switch shows only files present on both machines. /D shows only + those not present on both machines. /L shows only files which + are the most recent (largest-numbered) of a sequence. Only one + switch is allowed.î 83 EMACS Manual for ITS Users + + + CHAPTER FOURTEENî CHAPTER FOURTEENî CHAPTER FOURTEEN + USING MULTIPLE BUFFERSî USING MULTIPLE BUFFERSî USING MULTIPLE BUFFERS + + + + When we speak of "the buffer", which contains the text you are + editing, we have given the impression that there is only one. In + fact, there may be many of them, each with its own body of text. + ________î At any time only one buffer can be selected and available for + editing, but it isn't hard to switch to a different one. Each + buffer individually remembers which file it is visiting, what + modes are in effect, and whether there are any changes that need + saving. + + + C-X B Select or create a buffer. + C-X C-F Visit a file in its own buffer. + C-X C-B List the existing buffers. + C-X K Kill a buffer. + + + Each buffer in EMACS has a single name, which normally doesn't + change. A buffer's name can be any length. The name of the + currently selected buffer, and the name of the file visited in + it, are visible in the mode line when you are at top level. A + newly started EMACS has only one buffer, named "Main". + + As well as the visited file and the major mode, a buffer can, + _______î if ordered to, remember many other things locally, which means, + independently of all other buffers. See section 22.3 + [Variables], page 137. + + + + 14.1 Creating and Selecting Buffersî 14.1 Creating and Selecting Buffersî 14.1 Creating and Selecting Buffers + + + To create a new buffer, you need only think of a name for it + (say, "FOO") and then do C-X B FOO, which is the command C-X + B (Select Buffer) followed by the name. This makes a new, empty + buffer and selects it for editing. The new buffer is not + visiting any file, so if you try to save it you will be asked for + the filenames to use. Each buffer has its own major mode; the + new buffer's major mode is taken from the value of the variable + Default Major Mode, or from the major mode of the previously + selected buffer if the value of Default Major Mode is the null + string. Normally the Default Major Mode is Fundamental mode. + + To return to buffer FOO later after having switched to another,î 84 EMACS Manual for ITS Users + + + + the same command C-X B FOO is used, since C-X B can tell + whether a buffer named FOO exists already or not. It does not + matter whether you use upper case or lower case in typing the + name of a buffer. C-X B Main reselects the buffer Main that + EMACS started out with. Just C-X B reselects the previous + buffer. Repeated C-X B's alternate between the last two + buffers selected. + + You can also read a file into its own newly created buffer, all + with one command: C-X C-F (Find File), followed by the filename. + The first name of the file becomes the buffer name. C-F stands + for "Find", because if the specified file already resides in a + buffer in your EMACS, that buffer is reselected. So you need not + remember whether you have brought the file in already or not. A + buffer created by C-X C-F can be reselected later with C-X B or + C-X C-F, whichever you find more convenient. Nonexistent files + can be created with C-X C-F just as they can be with C-X C-V. A + nonzero argument to C-X C-F makes the file or buffer read-only; + it is like the argument to C-X C-V. See section 13.1 [Visiting], + page 69. + + Sometimes EMACS needs to visit a file as part of some other + operation. By default, it visits the file in whatever buffer was + selected. If you like to use C-X C-F and multiple buffers, you + can tell EMACS to use multiple buffers for implicit visiting by + setting the variable TAGS Find File to a nonzero value. This + causes automatic visiting to be done by means of C-X C-F instead + of C-X C-V. Automatic visiting is done by the TAGS package (See + section 21 [TAGS], page 122.) or by invoking EMACS with a + filename + + + :EMACS + + + If the buffer with the same name that C-X C-F wants to use + already exists but with the wrong contents (often a different + file with a similar name), then you are asked what to do. You + can type Return meaning go ahead and reuse that buffer for this + new file, or you can type another buffer name to use instead. If + C-X C-F does find the file already in a buffer, then it checks to + see whether the version on disk is the same as the last version + read or written from that buffer, for safety. If they are + different, you are warned that someone else may be editing the + file, and left with the version which was already in the EMACS. + To get the new version from disk instead, use M-X Revert File.î 85 EMACS Manual for ITS Users + + + + 14.2 Using Existing Buffersî 14.2 Using Existing Buffersî 14.2 Using Existing Buffers + + + To get a list of all the buffers that exist, do C-X C-B (List + Buffers). Each buffer's name, major mode, and visited filenames + are printed. A star at the beginning of a line indicates a + buffer which contains changes that have not been saved. The + number that appears before a buffer's name in a C-X C-B listing + ______ ______î is that buffer's buffer number. You can select a buffer by + giving its number as a numeric argument to C-X B, which then does + not need to read a string from the terminal. + + If several buffers have stars, you should save some of them + with M-X Save All Files. This finds all the buffers that need + saving and asks about each one individually. Saving the buffers + this way is much easier and more efficient than selecting each + one and typing C-X C-S. + + A quick way of glancing at another buffer, faster than + selecting it, is to use M-X View Buffer$. This + displays the contents of the other buffer and lets you move + forward and back a screen at a time with Space and Backspace. + See section 15 [Display], page 87. + + M-X Rename Buffer$ changes the name of the + currently selected buffer. If is the null string, the + first filename of the visited file is used as the new name of the + buffer. + + The commands C-X A (^R Append to Buffer) and M-X Insert Buffer + can be used to copy text from one buffer to another. See + section 9.3 [Copying], page 44. + + + + 14.3 Killing Buffersî 14.3 Killing Buffersî 14.3 Killing Buffers + + + After you use an EMACS for a while, it may fill up with buffers + which you no longer need. Eventually you can reach a point where + trying to create any more results in an "URK" error. So whenever + it is convenient you should do M-X Kill Some Buffers, which asks + about each buffer individually. You can say Y or N to kill it or + not. Or you can say Control-R to take a look at it first. This + does not actually select the buffer, as the mode line shows, but + gives you a recursive editing level in which you can move around + and look at things. When you have seen enough to make up your + mind, exit the recursive editing level with a C-M-C and you will + be asked the question again. If you say to kill a buffer thatî 86 EMACS Manual for ITS Users + + + + needs saving, you will be asked whether it should be saved. See + section 24.2.5 [Storage Exhausted], page 161. . + + You can kill the buffer FOO by doing C-X K FOO. You can + kill the selected buffer, a common thing to do if you use C-X + C-F, by doing C-X K. If you kill the selected buffer, in any + way, EMACS asks you which buffer to select instead. Saying just + at that point tells EMACS to choose one reasonably. C-X K + runs the function Kill Buffer.î 87 EMACS Manual for ITS Users + + + CHAPTER FIFTEENî CHAPTER FIFTEENî CHAPTER FIFTEEN + CONTROLLING THE DISPLAYî CONTROLLING THE DISPLAYî CONTROLLING THE DISPLAY + + + + Since only part of a large file fits on the screen, EMACS tries + to show the part that is likely to be interesting. The display + control commands allow you to ask to see a different part of the + file. + + + C-L Clear and redisplay screen, putting point at a + specified vertical position. + C-V Scroll forwards (a screen or a few lines). + M-V Scroll backwards. + M-R Move point to the text at a given vertical + position. + C-M-R Shift the function point is in onto the screen. + + + The terminal screen is rarely large enough to display all of + your file. If the whole buffer doesn't fit on the screen, EMACS + shows a contiguous portion of it, containing point. It continues + to show approximately the same portion until point moves outside + of it; then EMACS chooses a new portion centered around the new + point. This is EMACS's guess as to what you are most interested + in seeing. But if the guess is wrong, you can use the display + control commands to see a different portion. The finite area of + ___î screen through which you can see part of the buffer is called the + ______î window, and the choice of where in the buffer to start displaying + ___ ______î is also called the window. + + First we describe how EMACS chooses a new window position on + its own. The goal is usually to place point 35 percent of the + way down the screen. This is controlled by the variable Cursor + Centering Point, whose value is the percent of the screen down + from the top. However, if the end of the buffer is on the + screen, EMACS tries to leave at most 35 percent of the screen + blank beneath it, so that the screen is not wasted. This + percentage is controlled by the variable End of Buffer Display + Margin. These variables work by controlling FS flags, and their + values must never be negative or greater than 99. + + Normally EMACS only chooses a new window position if you move + point off the screen. However, you can ask for a new window + position to be computed whenever point gets too close to the top + of the screen by setting the variable Top Display Margin to the + percentage of the screen in which point must not appear. Bottom + Display Margin does the same thing for a region near the bottom.î 88 EMACS Manual for ITS Users + + + + The basic display control command is C-L (^R New Window). In + its simplest form, with no argument, it clears the screen and + tells EMACS to choose a new window position, centering point 35 + percent of the way from the top as usual. + + C-L with a positive argument chooses a new window so as to put + point that many lines from the top. An argument of zero puts + point on the very top line. Point does not move with respect to + the text; rather, the text and point move rigidly on the screen. + C-L with a negative argument puts point that many lines from the + bottom of the window. For example, C-U -1 C-L puts point on the + bottom line, and C-U -5 C-L puts it five lines from the bottom. + C-L with an argument does not clear the screen, so that it can + move the text on the screen instead of printing it again if the + terminal allows that. + + C-U C-L is different from C-L with any other sort of argument. + It causes just the line containing point to be redisplayed. + + _________î The scrolling commands C-V and M-V let you move the whole + display up or down a few lines. C-V (^R Next Screen) with an + argument shows you that many more lines at the bottom of the + screen, moving the text and point up together as C-L might. C-V + with a negative argument shows you more lines at the top of the + screen, as does Meta-V (^R Previous Screen) with a positive + argument. + + To read the buffer a screenful at a time, use the C-V command + with no argument. It takes the last two lines at the bottom of + the screen and puts them at the top, followed by nearly a whole + screenful of lines not visible before. Point is put at the top + of the screen. Thus, each C-V shows the "next screenful", except + for two lines of overlap to provide continuity. The variable + Next Screen Context Lines, if defined, controls how many lines + from the bottom of the screen move to the top; the default if the + variable is not defined is 2. To move backward, use M-V without + an argument, which moves a whole screenful backwards (again with + overlap). + + Scanning by screenfuls through the buffer for some distance is + most conveniently done with the M-X View Buffer command. This + command enters a simple subsystem in which Space moves a + screenful forward and Backspace moves a screenful backward. The + Return character exits, leaving point centered in whatever part + of the buffer was visible. Any other character exits and returns + point to its former location, and is then executed as a command + (unless it is a Rubout; Rubout exits but is not executed). View + Buffer can be used to view another buffer by giving the buffer's + name as a string argument. In this case, exiting with Returnî 89 EMACS Manual for ITS Users + + + + moves point permanently in the other buffer, but does not select + it. See section 14 [Buffers], page 83. + + With the M-X View File command, you can scan by screenfuls + through a file which you have not visited. See section 13.7 + [Advanced File Commands], page 79. + + To scroll the buffer so that the current function or paragraph + is positioned conveniently on the screen, use the C-M-R command + (^R Reposition Window). This command tries to get as much as + possible of the current function or paragraph onto the screen, + preferring the beginning to the end, but not moving point off the + screen. A "function" in Lisp mode is a defun; otherwise it is + defined to be a set of consecutive unindented lines, or a set of + consecutive indented lines. + + C-L in all its forms changes the position of point on the + screen, carrying the text with it. Another command moves point + the same way but leaves the text fixed. It is called Meta-R + (^R Move to Screen Edge). With no argument, it puts point at the + beginning of the line at the center of the screen. An argument + is used to specify the line to put it on, counting from the top + if the argument is positive, or from the bottom if it is + negative. Thus, Meta-R with an argument of 0 puts point on the + top line of the screen. Meta-R never causes any text to move on + the screen; it causes point to move with respect to the screen + and the text.î 90 EMACS Manual for ITS Users + + + CHAPTER SIXTEENî CHAPTER SIXTEENî CHAPTER SIXTEEN + TWO WINDOW MODEî TWO WINDOW MODEî TWO WINDOW MODE + + + + _______î EMACS allows you to split the screen into two windows and use + them to display parts of two files, or two parts of the same + file. + + + C-X 2 Start showing two windows. + C-X 3 Show two windows but stay "in" the top one. + C-X 1 Show only one window again. + C-X O Switch to the Other window + C-X 4 Find buffer, file or tag in other window. + C-X ^ Make this window bigger. + C-M-V Scroll the other window. + + + ___ ______î In two window mode, the text display portion of the screen is + _______î divided into two parts called windows, which display different + pieces of text. The two windows can display two different files, + or two parts of the same file. Only one of the windows is + selected; that is the window which the cursor is in. Editing + normally takes place in that window alone. To edit in the other + window, you would give a special command to move the cursor to + the other window, and then edit there. Since there is only one + mode line, it applies to the window you are in at the moment. + + The command C-X 2 (^R Two Windows) enters two-window mode. A + line of dashes appears across the middle of the screen, dividing + the text display area into two halves. Window one, containing + the same text as previously occupied the whole screen, fills the + top half, while window two fills the bottom half. The cursor + moves to window two. If this is your first entry to two-window + mode, window two contains a new buffer named W2. Otherwise, it + contains the same text it held the last time you looked at it. + + To return to viewing only one window, use the command C-X 1 + (^R One Window). Window one expands to fill the whole screen, + and window two disappears until the next C-X 2. C-U C-X 1 gets + rid of window one and makes window two use the whole screen. + Neither of these depends on which window the cursor is in when + the command is given. + + While you are in two window mode you can use C-X O (^R Other + Window) to switch between the windows. After doing C-X 2, the + cursor is in window two. Doing C-X O moves the cursor back to + window one, to exactly where it was before the C-X 2. Theî 91 EMACS Manual for ITS Users + + + + difference between this and doing C-X 1 is that C-X O leaves + window two visible on the screen. A second C-X O moves the + cursor back into window two, to where it was before the first + C-X O. And so on... + + Often you will be editing one window while using the other just + for reference. Then, the command C-M-V (^R Scroll Other Window) + is very useful. It scrolls the other window without switching to + it and switching back. It scrolls the same way C-V does: with + no argument, a whole screen up; with an argument, that many lines + up (or down, for a negative argument). With just a minus sign + (no digits) as an argument, C-M-V scrolls a whole screenful + backwards (what M-V does). + + The C-X 3 (^R View Two Windows) command is like C-X 2 but + leaves the cursor in window one. That is, it makes window two + appear at the bottom of the screen but leaves the cursor where it + was. C-X 2 is equivalent to C-X 3 C-X O. C-X 3 is equivalent to + C-X 2 C-X O, but C-X 3 is much faster. + + M-X Compare Windows compares the text in the two windows. + Starting from the existing values of point in each window, it + advances point in both windows to the first mismatch. The + variable Collapse in Comparison, if it exists, should be a string + containing all the "insignificant" characters; any string of + insignificant characters matches any other string of those + characters. If the variable does not exist, the insignificant + characters are return, linefeed, space and tab. + + If you quit with C-G in the middle of Compare Windows, point is + advanced in both windows as far as the matching has proceeded. + As a result, calling Compare Windows again resumes the + comparison. + + Normally, the screen is divided evenly between the two windows. + You can also redistribute screen space between the windows with + the C-X ^ (^R Grow Window) command. It makes the currently + selected window get one line bigger, or as many lines as is + specified with a numeric argument. With a negative argument, it + makes the selected window smaller. The allocation of space to + the windows is remembered while you are in one window mode and + the same allocation is used when you return to two window mode. + The allocation changes only when you give a C-X ^ command. + + After leaving two-window mode, you can still use C-X O, but its + meaning is different. Window two does not appear, but whatever + was being shown in it appears, in window one (the whole screen). + Whatever buffer used to be in window one is stuck, invisibly, + into window two. Another C-X O reverses the effect of the first.î 92 EMACS Manual for ITS Users + + + + For example, if window one shows buffer B and window two shows + buffer W2 (the usual case), and only window one is visible, then + after a C-X O window one shows buffer W2 and window two shows + buffer B. + + + + 16.1 Multiple Windows and Multiple Buffersî 16.1 Multiple Windows and Multiple Buffersî 16.1 Multiple Windows and Multiple Buffers + + + Buffers can be selected independently in each window. The C-X + B command selects a new buffer in whichever window the cursor is + in. The other window's buffer does not change. Window two's + buffer is remembered while you are in one window mode, and when + you return to two window mode that same buffer reappears in + window two. See section 14 [Buffers], page 83. + + You can view one buffer in both windows. Give C-X 2 an + argument as in C-U C-X 2 to go into two window mode, with both + windows showing the buffer which used to be in window one alone. + Although the same buffer appears in both windows, they have + different values of point, so you can move around in window two + while window one continues to show the same text. Then, having + found in window two the place you wish to refer to, you can go + back to window one with C-X O to make your changes. Finally you + can do C-X 1 to make window two leave the screen. If you are + already in two window mode, C-U C-X O switches windows carrying + the buffer from the old window to the new one so that both + windows show that buffer. + + If you have the same buffer in both windows, you must beware of + trying to visit a different file in one of the windows with C-X + C-V, because if you bring a new file into this buffer, it will + ____î replace the old file in both windows. To view different files in + the two windows again, you must switch buffers in one of the + windows first (with C-X B or C-X C-F, perhaps). + + A convenient "combination" command for viewing something in the + other window is C-X 4 (^R Visit in Other Window). With this + command you can ask to see any specified buffer, file or tag in + the other window. Follow the C-X 4 with either B and a buffer + name, F or C-F and a file name, or T or "." and a tag name (See + section 21 [TAGS], page 122.). This switches to the other window + and finds there what you specified. If you were previously in + one-window mode, two-window mode is entered. C-X 4 B is similar + to to C-X 2 C-X B. C-X 4 F is similar to C-X 2 C-X C-F. C-X 4 T + is similar to C-X 2 M-Period. The difference is one of + efficiency, and also that C-X 4 works equally well if you are + already using two windows.î 93 EMACS Manual for ITS Users + + + CHAPTER SEVENTEENî CHAPTER SEVENTEENî CHAPTER SEVENTEEN + NARROWINGî NARROWINGî NARROWING + + + + _________î Narrowing means focusing in on some portion of the buffer, + making the rest temporarily invisible and inaccessible. + + + C-X N Narrow down to between point and mark. + C-X P Narrow down to the page point is in. + C-X W Widen to view the entire buffer. + + + When you have narrowed down to a part of the buffer, that part + appears to be all there is. You can't see the rest, you can't + move into it (motion commands won't go outside the visible part), + you can't change it in any way. However, it is not gone, and if + you save the file all the invisible text will be saved. In + addition to sometimes making it easier to concentrate on a single + subroutine or paragraph by eliminating clutter, narrowing can be + used to restrict the range of operation of a replace command. + The word "Narrow" appears in the mode line whenever narrowing is + in effect. + + The primary narrowing command is C-X N (^R Narrow Bounds to + _______ ______ __________î Region). It sets the virtual buffer boundaries at point and the + mark, so that only what was between them remains visible. Point + and mark do not change. + + The way to undo narrowing is to widen with C-X W (^R Widen + Bounds). This makes all text in the buffer accessible again. + + Another way to narrow is to narrow to just one page, with C-X P + (^R Narrow Bounds to Page). See section 18 [Pages], page 94. + + You can get information on what part of the buffer you are + narrowed down to using the C-X = command. See section 11.4 + [Filling], page 56. + + The virtual buffer boundaries are a powerful TECO mechanism + used internally in EMACS in many ways. While only the commands + described here set them so as you can see, many others set them + temporarily using the TECO commands FS VB$ and FS VZ$, but + restore them before they are finished.î 94 EMACS Manual for ITS Users + + + CHAPTER EIGHTEENî CHAPTER EIGHTEENî CHAPTER EIGHTEEN + COMMANDS FOR MANIPULATING PAGESî COMMANDS FOR MANIPULATING PAGESî COMMANDS FOR MANIPULATING PAGES + + + + _____î Files are often thought of as divided into pages by the ASCII + ^î character formfeed (|L). For example, if a file is printed on a + line printer, each page of the file, in this sense, will start on + a new page of paper. Most editors make the division of a file + into pages extremely important. For example, they may be unable + to show more than one page of the file at any time. EMACS treats + a formfeed character just like any other character. It can be + inserted with C-Q C-L (or, C-M-L), and deleted with Rubout. + Thus, you are free to paginate your file, or not. However, since + pages are often meaningful divisions of the file, commands are + provided to move over them and operate on them. + + + C-M-L Insert formfeed. + C-X C-P Put point and mark around this page (or + another page). + C-X [ Move point to previous page boundary. + C-X ] Move point to next page boundary. + C-X P Narrow down to just this (or next) page. + C-X L Count the lines in this page. + M-X What Page + Print current page and line number. + + + The C-X [ (^R Previous Page) command moves point to the + previous page delimiter (actually, to right after it). If point + starts out right after a page delimiter, it skips that one and + stops at the previous one. A numeric argument serves as a repeat + count. The C-X ] (^R Next Page) command moves forward past the + next page delimiter. + + The command M-X What Page prints the page and line number of + the cursor in the echo area. There is a separate command to + print this information because it is likely to be slow and should + not slow down anything else. The design of TECO is such that it + is not possible to know the absolute number of the page you are + in, except by scanning through the whole file counting pages. + + The C-X C-P command (^R Mark Page) puts point at the beginning + of the current page and the mark at the end. The page delimiter + at the end is included (the mark follows it). The page delimiter + at the front is excluded (point follows it). This command can be + followed by a C-W to kill a page which is to be moved elsewhere. + If it is inserted after a page delimiter, at a place where C-X ]î 95 EMACS Manual for ITS Users + + + + or C-X [ would take you, then the page will be properly delimited + before and after once again. + + A numeric argument to C-X C-P is used to specify which page to + go to, relative to the current one. Zero means the current page. + One means the next page, and -1 means the previous one. + + The command C-X P (^R Narrow Bounds to Page) narrows down to + just one page. Everything before and after becomes temporarily + invisible and inaccessible (See section 17 [Narrowing], + page 93.). Use C-X W (^R Widen Bounds) to undo this. Both page + terminators, the preceding one and the following one, are + excluded from the visible region. Like C-X C-P, the C-X P + command normally selects the current page, but allows you to + specify which page explicitly relative to the current one with a + numeric argument. However, when you are already narrowed down to + one page, C-X P with no argument moves you to the next page + (otherwise, it would be a useless no-op). So several C-X P's in + a row get first the current page and then successive pages. + + If you prefer to see only one page of the file at a time as a + general rule, use the PAGE library. See section 18.1 [PAGE], + page 96. + + Just what delimits pages is controlled by the variable Page + Delimiter, which should contain a TECO search string (See + section 19.3 [TECO search strings], page 101.) which matches all + ^î page separators. Normally, it is a string containing just |L. + ^ ^ ^ ^î For an INFO file, it might usefully be changed to |_|L|O|_, which + ^ ^ ^î means that either a |_|L or just a |_ (either of the two strings + that separate INFO nodes) should be a page separator. Then each + node counts as a page. In any case, page separators are + recognized as such only at the beginning of a line. The + paragraph commands consider each page boundary a paragraph + boundary as well. + + The C-X L command (^R Count Lines Page) is good for deciding + where to break a page in two. It prints in the echo area the + total number of lines in the current page, and then divides it up + into those preceding the current line and those following, as in + + + Page has 96 lines (72+25) + + + Notice that the sum is off by one; this is correct if point is + not at the front of a line.î 96 EMACS Manual for ITS Users + + + 18.1 Editing Only One Page at a Timeî 18.1 Editing Only One Page at a Timeî 18.1 Editing Only One Page at a Time + + + The PAGE library allows you to edit only within a single page + at a time, with special commands to move between pages, and split + and join pages. It contrives to show the number of the page you + are looking at in the mode line. You can also ask to see a + _________î directory of the pages in the file, or to insert it into the + file. This is an extension of and replacement for the facility + provided by the C-X P command in standard EMACS. It is an + optional library because we do not think it is necessarily an + improvement. + + The commands in the PAGE library supplant and redefine commands + in standard EMACS. Therefore, you cannot use them unless you + give the command M-X Load Library$PAGE explicitly. See + section 22.2 [Libraries], page 135. + + + C-X ] Move to next page. + C-X [ Move to previous page. + C-X C-P Move to page by absolute number. + C-X P Split this page at point. + C-X J Join this page to the next or previous one. + C-X W See the whole file again. + + + The most fundamental thing to do with PAGE is to go to a + specific page. This can be done by giving the page number as an + argument to C-X C-P (^R Goto Page). If you give a number too + big, the last page in the file is selected. + + For convenience, C-X C-P with no argument when you are looking + at the whole file selects the page containing point. When you + are looking at only one page, C-X C-P with no argument goes to + the next page and with a negative argument goes to the previous + page. + + However, the main commands for moving forward or backward by + pages are C-X [ and C-X ] (^R Goto Previous Page and ^R Goto Next + Page). These take a numeric argument (either sign) and move that + many pages. + + To go back to viewing the whole file instead of just one page, + you can use the C-X W (^R PAGE Widen Bounds) command. These are + the same characters that you would use in standard EMACS, but + they run a different function that knows to remove the page + number from the mode line.î 97 EMACS Manual for ITS Users + + + + The C-S (^R Incremental Search) and C-R (^R Reverse Search) + commands are redefined to widen bounds first and narrow them + again afterwards. So you can search through the whole file, but + afterward see only the page in which the search ended. In fact, + PAGE goes through some trouble to work with whatever search + functions you prefer to use, and find them wherever you put them. + + ^î To split an existing page, you could insert a |L, but unless + you do this while viewing the whole file, PAGE might get + confused. The clean way is to use C-X P (^R Insert Pagemark) + which inserts the page mark, and narrows down to the second of + the two pages formed from the old page. The clean way to get rid + of a page mark is to use C-X J (^R Join Next Page). It gets rid + of the page mark after the current page; or, with a negative + argument, gets rid of the page mark before this page. + + ^î A page mark is defined as |L. If you set the variable + ^î PAGE Flush CRLF to 1, a page mark is |L, which has + the effect of making the CRLF at the beginning of each page + invisible. This may be desirable for EMACS library source files. + ^î You can also specify some other string in place of |L by setting + the variable Page Delimiter. If Page Delimiter specifies + ^î multiple alternatives, separated by |O, PAGE always inserts the + first of them, but recognizes them all. + + To see a list of all the pages in the file, each one + represented by its first nonempty line, use M-X View Page + Directory. It prints out the first non-blank line on each page, + preceded by its page number. M-X Insert Page Directory inserts + the same directory into the buffer at point. If you give it an + argument, it tries to make the whole thing into a comment by + putting the Comment Start string at the front of each line and + the Comment End string at the end. + + If the variable Page Setup Hook exists, PAGE will execute its + value as the function for placing PAGE's functions on keys. This + is done instead of the normal assignments to C-X [, C-X ], C-X + C-P, C-X P, and C-X J. î 98 EMACS Manual for ITS Users + + + CHAPTER NINETEENî CHAPTER NINETEENî CHAPTER NINETEEN + REPLACEMENT COMMANDSî REPLACEMENT COMMANDSî REPLACEMENT COMMANDS + + + + Global search-and-replace operations are not needed as often in + EMACS as they are in other editors, but they are available. In + addition to the simple Replace operation which is like that found + in most editors, there is a Query Replace operation which asks + you, for each occurrence of the pattern, whether to replace it. + + To replace every instance of FOO after point with BAR, you can + do + + + M-X Replace$FOO$BAR + + + Replacement occurs only after point, so if you want to cover the + whole buffer you must go to the beginning first. Replacement + continues to the end of the buffer, but you can restrict it by + narrowing. See section 17 [Narrowing], page 93. + + Unless the variable Case Replace is zero, Replace tries to + preserve case; give both FOO and BAR in lower case, and if a + particular FOO is found with a capital initial or all + capitalized, the BAR which replaces it will be given the same + case pattern. Thus, + + + M-X Replace$foo$bar + + + would replace "foo" with "bar", "Foo" with "Bar" and "FOO" with + "BAR". If Case Replace is zero, the replacement string is + inserted with the case you used when you typed it. If Case + Search is zero, the string to be replaced is found only when it + has the same case as what you typed. + + If you give Replace (or Query Replace) an argument, then it + replaces only occurrences of FOO delimited by break characters + (or an end of the buffer). So you can replace only FOO the word, + and not FOO when it is part of FOOBAR. + + The string FOO to be replaced is actually a TECO search string, + ^ ^ ^ ^ ^î a type of pattern, in which the characters |B, |N, |O, |Q, |S, + ^ ^î |X, and |] are special. See section 19.3 [TECO search strings], + page 101.î 99 EMACS Manual for ITS Users + + + + 19.1 Query Replaceî 19.1 Query Replaceî 19.1 Query Replace + + + If you want to change only some of the occurrences of FOO, not + all, then you cannot use an ordinary Replace. Instead, use M-X + Query Replace$FOO$BAR. This displays each occurrence of FOO + and waits for you to say whether to replace it with a BAR. The + things you can type when you are shown an occurrence of FOO are: + + + Space to replace the FOO (preserving case, just + like plain Replace, unless Case Replace is + zero). + Rubout to skip to the next FOO without replacing + this one. + Comma to replace this FOO and display the result. + You are then asked for another input + character, except that since the replacement + has already been made, Rubout and Space are + equivalent. + Altmode to exit without doing any more replacements. + Period to replace this FOO and then exit. + ! to replace all remaining FOO's without + asking. + ^ to go back to the previous FOO (or, where it + was), in case you have made a mistake. This + works by jumping to the mark (Query Replace + sets the mark each time it finds a FOO). + C-R to enter a recursive editing level, in case + the FOO needs to be edited rather than just + replaced with a BAR. When you are done, exit + the recursive editing level with C-M-C and + the next FOO will be displayed. + C-W to delete the FOO, and then start editing the + buffer. When you are finished editing + whatever is to replace the FOO, exit the + recursive editing level with C-M-C and the + next FOO will be displayed. + + + If you type any other character, the Query Replace is exited, + and the character executed as a command. To restart the Query + Replace, use C-X Altmode which is a command to re-execute the + previous minibuffer command or extended command. See section 5 + [M-X], page 21.î 100 EMACS Manual for ITS Users + + + + 19.1.1 Running Query Replace with the Minibufferî 19.1.1 Running Query Replace with the Minibufferî 19.1.1 Running Query Replace with the Minibuffer + + + Meta-% gives you a minibuffer pre-initialized with "MM Query + Replace$". See section 23 [Minibuffer], page 156. This is the + easiest way to invoke Query Replace. It also allows you to get + Returns and Altmodes into the arguments. + + With the minibuffer, Query Replace can be given a precomma + argument, which says that the second string argument is actually + a TECO program to be executed to perform the replacement, rather + than simply a string to replace with. + + When you invoke Query Replace from the minibuffer, the + ^î character |] becomes special (because it is special in TECO + ^î programs). In order to get a |] into the search string or the + replacement string, you must use two of them. You can also use a + ^î |] to quote an Altmode. In the minibuffer, Return has no + syntactic significance, so there is no need for a way to quote + it. However, in order to insert any control characters into the + ^î arguments, you need to quote them again with C-Q. So, to get |Q + ^ ^î |X into the search string so as to search for a |X, you have to + type C-Q C-Q C-Q C-X. + + + + 19.2 Other Search-and-loop Functionsî 19.2 Other Search-and-loop Functionsî 19.2 Other Search-and-loop Functions + + + Here are some other functions related to replacement. Their + arguments are TECO search strings (See section 19.3 [TECO search + strings], page 101.). They all operate from point to the end of + the buffer (or where narrowing stops them). + + + M-X List Matching Lines$FOO + prints each line containing FOO. With an + argument, it prints that many lines before and + after each occurrence. + + M-X Count Occurrences$FOO + prints the number of occurrences of FOO after + point. + + M-X Delete Non-Matching Lines$FOO + kills all lines after point that don't contain + FOO. + + M-X Delete Matching Lines$FOO + kills all lines after point that contain FOO. î 101 EMACS Manual for ITS Users + + + 19.3 TECO Search Stringsî 19.3 TECO Search Stringsî 19.3 TECO Search Strings + + + The first string argument to Replace and Query Replace is + actually a TECO search string. This means that the characters + ^ ^ ^ ^ ^ ^î |X, |B, |N, |S, |O, and |Q have special meanings. + + ^ ^î |X matches any character. |B matches any "delimiter" character + (anything which the word commands consider not part of a word, + according to the syntax table. See section 22.4 [Syntax], + ^ ^î page 139.). |N negates what follows, so that |N A matches + ^ ^ ^î anything but A, and |N |B matches any non-delimiter. |S is + followed by a parameter character, and matches anything whose + ^î Lisp syntax equals the parameter. So |S( matches any character + ^ ^î given the syntax of an open-parenthesis. |N|SA matches any + character which is not part of symbol names. + + ^ ^ ______î |O means "or", so that XYXY |O ZZZ matches either XYXY or ZZZ. + ^ ^î |O can be used more than once in a pattern. |Q quotes the + following character, in case you want to search for one of the + special control characters. However, you can't quote an Altmode + or a Return in this way because its specialness is at an earlier + stage of processing. + + Some variables are supposed to have TECO search strings as + their values. For example, Page Delimiter is supposed to be a + search string to match anything which should start a page. This + ^î is so that you can use |O to match several alternatives. In the + ^ ^ ^ ^ ^ ^ ^î values of such variables, |B, |N, |O, |Q, |S, |X and |] are + ^ ^ ^î special, but Altmode is not. |B through |X are quoted with a |Q, + ^ ^î and |] is quoted with another |]. + + The function Apropos (or, Help A) and all similar functions + actually take TECO search strings as arguments, so you can search + for more than one substring at a time. This is useful because + ^î doing Apropos on word|Opara is not really slower than searching + for just "word" or just "para".î 102 EMACS Manual for ITS Users + + + CHAPTER TWENTYî CHAPTER TWENTYî CHAPTER TWENTY + EDITING PROGRAMSî EDITING PROGRAMSî EDITING PROGRAMS + + + + Special features for editing programs include automatic + indentation, comment alignment, parenthesis matching, and the + ability to move over and kill balanced expressions. Many of + these features are parameterized so that they can work for any + programming language. + + _____ ____î For each language there is a special major mode which + customizes EMACS slightly to be better suited to editing programs + written in that language. These modes sometimes offer special + facilities as well. + + See section 11.1 [Words], page 50. Moving over words is useful + for editing programs as well as text. + + See section 11.2 [Paragraphs], page 52. Most programming + language major modes define paragraphs to be separated only by + blank lines and page boundaries. This makes the paragraph + commands useful for editing programs. + + See section 21 [Tags], page 122. The TAGS package can remember + all the labels or functions in a multi-file program and find any + one of them quickly. + + + + 20.1 Major Modesî 20.1 Major Modesî 20.1 Major Modes + + + _____ _____î EMACS has many different major modes, each of which customizes + EMACS for editing text of a particular sort. The major modes are + mutually exclusive, and one major mode is current at any time. + When at top level, EMACS always says in the mode line which major + mode you are in. + + ___________ ____î When EMACS starts up, it is in what is called Fundamental mode, + which means that the character commands are defined so as to be + convenient in general. More precisely, in Fundamental mode every + EMACS option is set in its default state. For editing any + specific type of text, such as Lisp code or English text, you + should switch to the appropriate major mode. This tells EMACS to + change the meanings of a few commands to become more specifically + adapted to the language being edited. Most commands remain + unchanged; the ones which usually change are Tab, Rubout, and + Linefeed. In addition, the commands which handle comments use + the mode to determine how comments are to be delimited.î 103 EMACS Manual for ITS Users + + + + Selecting a new major mode is done with an M-X command. Each + major mode is the name of the function to select that mode. + Thus, you can enter Lisp mode by executing M-X Lisp (short for + M-X Lisp Mode). You can specify which major mode should be used + for editing a certain file by putting -*--*- somewhere + in the first nonblank line of the file. For example, this file + has -*-SCRIBE-*-. In a program, this string is surrounded by + appropriate other characters to hide it from the compiler in a + comment. + + Many major modes redefine the syntactical properties of + characters appearing in the buffer. See section 22.4 [Syntax], + page 139. + + Most programming language major modes specify that only blank + lines separate paragraphs. This is so that the paragraph + commands remain useful. They also cause Auto Fill mode to use + the definition of Tab to indent the new lines it creates. This + is because most lines in a program are usually indented. + + To find out what a particular major mode redefines, use the + command M-X List Redefinitions while that mode is in effect. + This command describes all the local variables and commands of + the selected buffer, in a form designed to be easy to understand. + + Major modes are available for the languages LISP, MUDDLE, + MIDAS, PALX, IBM370 (assembler), CLU, FORTRAN, MACSYMA, PASCAL, + PL1, SAIL, and TECO. + + There is also Text mode, designed for editing English text, and + TEX and SCRIBE modes, for editing input to those text justifier + programs. See section 11 [Text], page 50. + + + + 20.2 Compiling Your Programî 20.2 Compiling Your Programî 20.2 Compiling Your Program + + + The command M-X Compile is used to compile the visited + file. It knows how to compile it based on the major mode; for + example, in TECO mode, it invokes the generator for EMACS + libraries. Usually it assumes that the major mode name is the + name of the compiler or assembler to use. + + The first thing M-X Compile does is offer to save each buffer. + This is because it is likely that other buffers contain parts of + the same program you are about to compile. + + Then M-X Compile invokes the appropriate compiler and passes itî 104 EMACS Manual for ITS Users + + + + the name of the visited file as the source file. If you give a + string argument to M-X Compile, that is passed to the compiler + also. This can be used to specify switches or the name of an + output file. + + The major mode or the file's local modes list can specify a + different compiler by setting the variable Compiler Filename + locally. They can specify switches to be used by setting the + variable Compiler Switches (the default is to use no switches + except those specified by the user in the string argument to M-X + Compile). + + After compilation, you must type $P to resume EMACS. When + EMACS starts up again, it executes the value of the variable + After Compilation Hook, if that is nonzero. This can be used for + such tasks as reading the compiler's file of error messages into + EMACS. + + The major mode or the file's local modes list can completely + override the normal processing of M-X Compile by giving a nonzero + local value to the variable Compile Command. This should be a + TECO expression which takes complete responsibility for the + compilation. It can find the filename to use in q-register 1. + ____ ^î It must use |\ to exit. All the other hooks described above are + ignored. This is often used when several input files must be + compiled together in order to compile any of them. See the file + AI:EMACS1;CCL > for an example of doing this for an EMACS + library. + + + + 20.3 Indentation Commands for Codeî 20.3 Indentation Commands for Codeî 20.3 Indentation Commands for Code + + + Tab Indents current line. + Linefeed Equivalent to Return followed by Tab. + M-^ Joins two lines, leaving one space between if + appropriate. + M-\ Deletes all spaces and tabs around point. + M-M Moves to the first nonblank character on the + line. + + + Most programming languages have some indentation convention. + For Lisp code, lines are indented according to their nesting in + parentheses. For assembler code, almost all lines start with a + single tab, but some have one or more spaces as well. Indenting + TECO code is an art rather than a science, but it is often useful + to indent a line under the previous one.î 105 EMACS Manual for ITS Users + + + + Whatever the language, to indent a line, use the Tab command. + Each major mode defines this command to perform the sort of + indentation appropriate for the particular language. In Lisp + mode, Tab aligns the line according to its depth in parentheses. + No matter where in the line you are when you type Tab, it aligns + the line as a whole. In MIDAS mode, Tab inserts a tab, that + being the standard indentation for assembly code. In TECO mode, + Tab realigns the current line to match a previous line. PL1 mode + (See the file INFO;EPL1.) knows in great detail about the + keywords of the language so as to indent lines according to the + nesting structure. + + The command Linefeed (^R Indent New Line) does a Return and + then does a Tab on the next line. Thus, Linefeed at the end of + the line makes a following blank line and supplies it with the + usual amount of indentation. Linefeed in the middle of a line + breaks the line and supplies the usual indentation in front of + the new line. + + The inverse of Linefeed is Meta-^ or C-M-^ (^R Delete + Indentation). This command deletes the indentation at the front + of the current line, and the line separator as well. They are + replaced by a single space, or by no space if before a ")" or + after a "(", or at the beginning of a line. To delete just the + indentation of a line, go to the beginning of the line and use + Meta-\ (^R Delete Horizontal Space), which deletes all spaces and + tabs around the cursor. + + To insert an indented line before the current one, do C-A, C-O, + and then Tab. To make an indented line after the current one, + use C-E Linefeed. + + To move over the indentation on a line, use Meta-M or C-M-M + (^R Back to Indentation). These commands move the cursor forward + or back to the first nonblank character on the line. + + + + 20.4 Automatic Display Of Matching Parenthesesî 20.4 Automatic Display Of Matching Parenthesesî 20.4 Automatic Display Of Matching Parentheses + + + The EMACS parenthesis-matching feature is designed to show + automatically how parentheses balance in text as it is typed in. + When this feature is enabled, after a close parenthesis or other + close bracket character is inserted the cursor automatically + moves for an instant to the open which balances the newly + inserted character. The cursor stays at the open parenthesis for + a second before returning home, unless you type another command + before the second is up.î 106 EMACS Manual for ITS Users + + + + It is worth emphasizing that the location of point, the place + where your type-in will be inserted, is not affected by the + parenthesis matching feature. It stays after the close + parenthesis, where it ought to be. Only the cursor on the screen + moves away and back. You can type ahead freely as if the + parenthesis display feature did not exist. In fact, if you type + fast enough, you won't see the cursor move. You must pause after + typing a close parenthesis to let the cursor move to the open + parenthesis. + + The variable Display Matching Paren controls parenthesis + display. If it is zero, the feature is disabled. If the + variable is nonzero, then its absolute value is the number of + seconds for the cursor to stay at the open parenthesis before + coming back to its real location. The sign of the variable is + also significant: if it is negative, then the open parenthesis is + shown only if it is already on the screen. If the variable is + positive, then EMACS will actually shift text on the screen to + show the open parenthesis. The default setting of the variable + is -1. + + An additional parameter is whether EMACS should warn you by + ringing the bell if you type an unmatched close parenthesis. The + default is to warn you if you are editing a language in which + parentheses are paramount, such as Lisp, but not to do so for + languages in which parentheses are not so crucial. This is + controlled by the variable Permit Unmatched Paren. When it is 1, + you are never warned (they are always "permitted"). When it is + 0, you are warned, regardless of major mode. When it is -1, you + are warned only in Lisp mode and similar modes (this is the + default). Note that these modes distinguish themselves by + setting the variable locally to 0 if it was -1. Unmatched parens + are always "permitted" in that EMACS will never refuse to insert + them. + + While this feature was intended primarily for Lisp, it can be + used just as well for any other language, and it is not dependent + on what major mode you are in. It is expected that you wouldn't + want it in Text mode, so Text mode sets the variable Display + Matching Paren locally to zero. If you do want the feature in + Text mode, you can create a Text Mode Hook variable which sets + the variable back to -1. See the file INFO;CONV, node Hooks, for + more info on Text Mode Hook. The way to control which characters + trigger this feature is with the syntax table. Any character + whose Lisp syntax is ")" causes the matching character with + syntax "(" to be shown. Most major modes automatically set up + the syntax table (See section 22.4 [Syntax], page 139.). + + The syntax table also controls what is done with the case ofî 107 EMACS Manual for ITS Users + + + + "mismatched" parens, as in "[ )". The third slot in a close + parenthesis character's syntax table entry should be the proper + matching open parenthesis character, if you want this feature + turned on. If that slot contains a space instead, then any open + parenthesis character is considered a legitimate match. If a + close parenthesis is mismatched, it is inserted as always, but it + rings the bell. + + The implementation of this feature uses the TECO flag FS + ^R PAREN$. See section 22.5 [FS Flags], page 142. + + + + 20.5 Manipulating Commentsî 20.5 Manipulating Commentsî 20.5 Manipulating Comments + + + The comment commands insert, kill and align comments. There + are also commands for moving through existing code and inserting + comments. + + + M-; Insert or align comment. + C-; The same. + C-M-; Kill comment. + Return Move past comment terminator and onto new + line. + C-X ; Set comment column. + M-N Move to Next line and insert comment. + M-P Move to Previous line and insert comment. + M-J Continue a comment on a new line. + M-Linefeed The same. + + + The command that creates a comment is Meta-; or Control-; + (^R Indent for Comment). If there is no comment already on the + line, a new comment is created, aligned at a specific column + _______ ______î called the comment column. The comment is created by inserting + whatever string EMACS thinks should start comments in the current + major mode. Point is left after the comment-starting string. If + the text of the line goes past the comment column, then the + indentation is done to a suitable boundary (usually, a multiple + of 8). + + Meta-; can also be used to align an existing comment. If a + line already contains the string that starts comments, then M-; + just moves point after it and re-indents it to the right column. + Exception: comments starting in column 0 are not moved. + + Even when an existing comment is properly aligned, M-; is still + useful for moving directly to the start of the comment.î 108 EMACS Manual for ITS Users + + + + Some languages require an explicit comment terminator, which is + not simply the end of the line. Although the language may then + allow comments in the middle of the line, the EMACS comment + commands assume that a comment is the last thing on the line. + When there is a comment terminator, M-; inserts the terminator as + well as the starter, and leaves point between them, so that you + are ready to insert the text of the comment. When you are done, + the Return command given immediately before the comment + terminator acts as if it were at the end of the line already: it + moves down to or creates a following blank line. It does not + break the existing line before the comment terminator as you + would expect. + + C-M-; (^R Kill Comment) kills the comment on the current line, + if there is one. The indentation before the start of the comment + is killed as well. If there does not appear to be a comment in + the line, nothing is done. To reinsert the comment on another + line, move to the end of that line, do C-Y, and then do M-; to + realign it. + + + 20.5.1 Multiple Lines of Commentsî 20.5.1 Multiple Lines of Commentsî 20.5.1 Multiple Lines of Comments + + + If you wish to align a large number of comments, you can give + Meta-; an argument and it indents what comments exist on that + many lines, creating none. Point is left after the last line + processed (unlike the no-argument case). + + When adding comments to a long stretch of existing code, the + commands M-N (^R Down Comment Line) and M-P (^R Up Comment Line) + may be useful. They are like C-N and C-P except that they do a + C-; automatically on each line as you move to it, and delete any + empty comment from the line as you leave it. Thus, you can use + M-N to move down through the code, putting text into the comments + when you want to, and allowing the comments that you don't fill + in to be removed because they remained empty. + + If you are typing a comment and find that you wish to continue + it on another line, you can use the command Meta-J or + Meta-Linefeed (^R Indent New Comment Line), which terminates the + comment you are typing, creates or gobbles a new blank line, and + begins a new comment indented under the old one. When Auto Fill + mode is on, going past the fill column while typing a comment + causes the comment to be continued in just this fashion. Note + that if the next line is not blank, a blank line is created, and + the continuation goes on that line. By comparison, M-N would + create a continuation comment on the next existing line of code.î 109 EMACS Manual for ITS Users + + + + 20.5.2 Double and Triple Semicolons in Lispî 20.5.2 Double and Triple Semicolons in Lispî 20.5.2 Double and Triple Semicolons in Lisp + + + In Lisp code there are conventions for comments which start + with more than one semicolon. Comments which start with two + semicolons are indented as if they were lines of code, instead of + at the comment column. Comments which start with three + semicolons are supposed to start at the left margin. EMACS + understands these conventions by indenting a double-semicolon + comment using Tab, and by not changing the indentation of a + triple-semicolon comment at all. (Actually, this rule applies + whenever the comment starter is a single character and is + duplicated). Note that the :@ program considers a four-semicolon + comment a subtitle in Lisp code. + + + 20.5.3 Options Controlling Commentsî 20.5.3 Options Controlling Commentsî 20.5.3 Options Controlling Comments + + + The comment column is stored in the variable Comment Column. + You can set it to a number explicitly. Alternatively, the + command C-X ; (^R Set Comment Column) sets the comment column to + the column point is at. C-U C-X ; sets the comment column to + match the last comment before point in the buffer, and then does + a Meta-; to align the current line's comment under the previous + one. + + Many major modes supply default local values for the comment + column. In addition, C-X ; automatically makes the variable + Comment Column local. Otherwise, if you change the variable + itself, it changes globally (for all buffers) unless it has been + made local in the selected one. See section 22.7 [Locals], + page 150. + + The string recognized as the start of a comment is stored in + the variable Comment Start, while the string used to start a new + comment is kept in Comment Begin (if that is zero, Comment Start + is used for new comments). This makes it possible for you to + have any ";" recognized as starting a comment but have new + comments begin with ";; ** ". + + The string used to end a comment is kept in the variable + Comment End. In many languages no comment end is needed as the + comment extends to the end of the line. Then, this variable is a + null string. + + If Comment Multi Line is nonzero, then Meta-Linefeed within a + comment does not close the old comment and start a new comment on + the new line. Instead it allows the original comment to extendî 110 EMACS Manual for ITS Users + + + + through the new line. This is legitimate if the language has + explicit comment terminators. Then it's a matter of taste. + + + + 20.6 Lisp Mode and Muddle Modeî 20.6 Lisp Mode and Muddle Modeî 20.6 Lisp Mode and Muddle Mode + + + Lisp's simple syntax makes it much easier for an editor to + understand; as a result, EMACS can do more for Lisp, and with + less work, than for any other language. + + Lisp programs should be edited in Lisp mode. In this mode, Tab + is defined to indent the current line according to the + conventions of Lisp programming style. It does not matter where + in the line Tab is used; the effect on the line is the same. The + function which does the work is called ^R Indent for Lisp. + Linefeed, as usual, does a Return and a Tab, so it moves to the + next line and indents it. + + As in most modes where indentation is likely to vary from line + to line, Rubout is redefined to treat a tab as if it were the + equivalent number of space (^R Backward Delete Hacking Tabs). + This makes it possible to rub out indentation one position at a + time without worrying whether it is made up of spaces or tabs. + Control-Rubout does the ordinary type of rubbing out which rubs + out a whole tab at once. + + Paragraphs are defined to start only with blank lines so that + the paragraph commands can be useful. Auto Fill indents the new + lines which it creates. Comments start with ";". If Atom Word + mode is in effect, them in Lisp mode the word-motion commands + regard each Lisp atom as one word. + + The LEDIT library allows EMACS and Lisp to communicate, telling + Lisp the new definitions of functions which you edit in EMACS. + See the file INFO;LEDIT. + + The language Muddle is a variant form of Lisp which shares the + concept of using parentheses (of various sorts) as the main + syntactical construct. It can be edited using Muddle mode, which + is almost the same as Lisp mode and provides the same features, + differing only in the syntax table used.î 111 EMACS Manual for ITS Users + + + 20.6.1 Moving Over and Killing Lists and S-expressionsî 20.6.1 Moving Over and Killing Lists and S-expressionsî 20.6.1 Moving Over and Killing Lists and S-expressions + + + C-M-F Move Forward over s-expression. + C-M-B Move Backward. + C-M-K Kill s-expression forward. + C-M-Rubout Kill s-expression backward. + C-M-U Move Up and backward in list structure. + C-M-( The same. + C-M-) Move up and forward in list structure. + C-M-D Move Down and forward in list structure. + C-M-N Move forward over a list. + C-M-P Move backward over a list. + C-M-T Transpose s-expressions. + C-M-@ Put mark after s-expression. + M-( Put parentheses around next + s-expression(s). + M-) Move past next close parenthesis and + re-indent. + + + By convention, EMACS commands that deal with balanced + parentheses are usually Control-Meta- characters. They tend to + be analogous in function to their Control- and Meta- equivalents. + These commands are usually thought of as pertaining to Lisp, but + can be useful with any language in which some sort of parentheses + exist (including English). + + To move forward over an s-expression, use C-M-F (^R Forward + Sexp). If the first significant character after point is an "(", + C-M-F moves past the matching ")". If the first character is a + ")", C-M-F just moves past it. If the character begins an atom, + C-M-F moves to the end of the atom. C-M-F with an argument + repeats that operation the specified number of times; with a + negative argument, it moves backward instead. + + The command C-M-B (^R Backward Sexp) moves backward over an + s-expression; it is like C-M-F with the argument negated. If + there are "'"-like characters in front of the s-expression moved + over, they are moved over as well. Thus, with point after + " 'FOO ", C-M-B leaves point before the "'", not before the "F". + + These two commands (and most of the commands in this section) + do not know how to deal with the presence of comments. Although + that would be easy to fix for forward motion, for backward motion + the syntax of Lisp makes it nearly impossible. Comments by + themselves can be dealt with, but handling both comments and + strings is impossible with local backward parsing. In a line î 112 EMACS Manual for ITS Users + + + + ((FOO ; " BAR + + + are the open parentheses inside a string? So C-M-B cannot handle + comments, and C-M-F does not either for simplicity's sake. + + For this reason, two other commands which move over lists + instead of s-expressions are often useful. They are C-M-N + (^R Forward List) and C-M-P (^R Backward List). They act like + C-M-F and C-M-B except that they don't stop on atoms; after + moving over an atom, they move over the next expression, stopping + after moving over a list. With this command, you can avoid + stopping after all of the words in a comment. + + Killing an s-expression at a time can be done with C-M-K and + C-M-Rubout (^R Forward Kill Sexp and ^R Backward Kill Sexp). + C-M-K kills the characters that C-M-F would move over, and + C-M-Rubout kills what C-M-B would move over. + + C-M-F and C-M-B stay at the same level in parentheses, when + __î that's possible. To move up one (or n) levels, use C-M-( or + C-M-) (^R Backward Up List and ^R Forward Up List). C-M-( moves + backward up past one containing "(". C-M-) moves forward up past + one containing ")". Given a positive argument, these commands + move up the specified number of levels of parentheses. C-M-U is + another name for C-M-(, which is easier to type, especially on + non-Meta keyboards. If you use that name, it is useful to know + that a negative argument makes the command move up forwards, like + C-M-). + + ____î To move down in list structure, use C-M-D (^R Down List). It + is nearly the same as searching for a "(". + + A somewhat random-sounding command which is nevertheless easy + to use is C-M-T (^R Transpose Sexps), which drags the previous + s-expression across the next one. An argument serves as a repeat + count, and a negative argument drags backwards (thus canceling + out the effect of C-M-T with a positive argument). An argument + of zero, rather than doing nothing, transposes the s-expressions + at the point and the mark. + + To make the region be the next s-expression in the buffer, use + or C-M-@ (^R Mark Sexp) which sets mark at the same place that + C-M-F would move to. C-M-@ takes arguments like C-M-F. In + particular, a negative argument is useful for putting the mark at + the beginning of the previous s-expression. + + The commands M-( ("^R Insert ()") and M-) ("^R Move Over )") + are designed for a style of editing which keeps parenthesesî 113 EMACS Manual for ITS Users + + + + balanced at all times. M-( inserts a pair of parentheses, either + together as in "()", or, if given an argument, around the next + several s-expressions, and leaves point after the open + parenthesis. Instead of typing "(FOO)", you can type M-( FOO, + which has the same effect except for leaving the cursor before + the close parenthesis. Then you type M-), which moves past the + close parenthesis, deleting any indentation preceding it (in this + example there is none), and indenting with Linefeed after it. + + The library LSPUTL contains two other list commands. Find Pat + searches for lists which contain several strings. ^R Extract + Sublist replaces a list with one of its sublists. See + section 22.2 [Libraries], page 135. + + M-X Find Pat$$$ searches + for a list which contains at a depth of + lists down, and contains and at any level. + There can be any number of such additional strings to search for; + there can be none of them. + + ^R Extract Sublist is meant to be connected to a character. + Given an argument of , it replaces the list levels + up from point with its sublist which starts after point. + + The library XLISP contains a functions for making various + transformations on Lisp code: + + Lowercase Lisp Buffer changes all the Lisp code in the buffer + to lower case, without changing comments, strings, or slashified + characters. Uppercase Lisp Buffer performs the inverse + transformation. Lowercase Lisp Region and Uppercase Lisp Region + are similar but act only between point and mark. + + Change / to \ takes Lisp code written with "/" as the + character-quote character and transforms it to use the new + character-quote character, "\". The meaning of the transformed + code in the new syntax is the same as that of the old code in the + old syntax. + + XLISP contains several other commands which transform old + constructs into new ones. They behave like Query Replace in that + they display each occurrence of the old construct and ask you + whether to change it to the new one. A Space means yes, a Rubout + means no. Here is a list of these commands, and what each one + transforms. + + + Modernize FUNCTION References + (FUNCTION ...) into #'...î 114 EMACS Manual for ITS Users + + + + Modernize QUOTE References + (QUOTE ...) into '... + + Modernize LAMBDA References + '(LAMBDA ...) into #'(LAMBDA ...) + + Modernize MAP References + (MAPxxx '... ...) into (MAPxxx #'... ...) + + Modernize NIL Occurrences + NIL into () + + Modernize LAMBDA Combinations + ((LAMBDA (X) Y) ARG) into (LET ((X ARG)) Y) + + Modernize Strings + '|...| into "..." + + + facility for replacing obsolete or old-fashioned Maclisp + constructs with equivalent modern ones. + + The list commands' understanding of syntax is completely + controlled by the syntax table. Any character can, for example, + be declared to act like an open parenthesis. See section 22.4 + [Syntax], page 139. + + + 20.6.2 Commands for Manipulating Defunsî 20.6.2 Commands for Manipulating Defunsî 20.6.2 Commands for Manipulating Defuns + + + C-M-[, C-M-A Move to beginning of defun. + C-M-], C-M-E Move to end of defun. + C-M-H Put region around wHole defun. + + + In EMACS, an expression at the top level in the buffer is + _____î called a defun, regardless of what function is actually called by + the expression, because such expressions usually call defun. + + In the remotest past, EMACS found defuns by moving upward a + level of parentheses until there were no more levels to go up. + This required scanning all the way back to the beginning of the + file. To speed up the operation, EMACS now assumes that any "(" + (or any character with "(" as its Lisp syntax) in column 0 is the + start of a defun. This heuristic is nearly always right and + avoids the costly scan. + + The commands to move to the beginning and end of the currentî 115 EMACS Manual for ITS Users + + + + defun are C-M-[ (^R Beginning of Defun) and C-M-] (^R End of + Defun). Alternate names for these two commands are C-M-A for + C-M-[ and C-M-E for C-M-]. The alternate names are easier to + type on many non-Meta keyboards. + + If you wish to operate on the current defun, use C-M-H (^R Mark + Defun) which puts point at the beginning and mark at the end of + the current or next defun. + + + + 20.7 Lisp Grindingî 20.7 Lisp Grindingî 20.7 Lisp Grinding + + + The best way to keep Lisp code properly indented ("ground") is + to use EMACS to re-indent it when it is changed. EMACS has + commands to indent properly either a single line, a specified + number of lines, or all of the lines inside a single + s-expression. + + + Tab In Lisp mode, re-indents line according to + parenthesis depth. + Linefeed Equivalent to Return followed by Tab. + M-^ Join two lines, leaving one space between + them if appropriate. + C-M-Q Re-indent all the lines within one list. + C-M-G Grind a list, moving code between lines. + + + The basic indentation function is ^R Indent for Lisp, which + gives the current line the correct indentation as determined from + the previous lines' indentation and parenthesis structure. This + function is normally found on C-M-Tab, but when in Lisp mode it + is placed on Tab as well (Use Meta-Tab or C-Q Tab to insert a + tab). If executed at the beginning of a line, it leaves point + after the indentation; when given inside the text on the line, it + leaves point fixed with respect to the characters around it. + + When entering a large amount of new code, use Linefeed + (^R Indent New Line), which is equivalent to a Return followed by + a Tab. In Lisp mode, a Linefeed creates or moves down onto a + blank line, and then gives it the appropriate indentation. + + To join two lines together, use the Meta-^ or Control-Meta-^ + command (^R Delete Indentation), which is approximately the + opposite of Linefeed. It deletes any spaces and tabs at the + front of the current line, and then deletes the line separator + before the line. A single space is then inserted, if EMACSî 116 EMACS Manual for ITS Users + + + + thinks that one is needed there. Spaces are not needed before a + close parenthesis, or after an open parenthesis. + + If you are dissatisfied about where Tab indents the second and + later lines of an s-expression, you can override it. If you + alter the indentation of one of the lines yourself, then Tab will + indent successive lines of the same list to be underneath it. + This is the right thing for functions which Tab indents + unaesthetically. + + When you wish to re-indent code which has been altered or moved + to a different level in the list structure, you have several + commands available. You can re-indent a specific number of lines + by giving the ordinary indent command (Tab, in Lisp mode) an + argument. This indents as many lines as you say and moves to the + line following them. Thus, if you underestimate, you can repeat + the process later. + + You can re-indent the contents of a single s-expression by + positioning point before the beginning of it and typing + Control-Meta-Q (^R Indent Sexp). The line the s-expression + starts on is not re-indented; thus, only the relative indentation + with in the s-expression, and not its position, is changed. To + correct the position as well, type a Tab before the C-M-Q. + + Another way to specify the range to be re-indented is with + point and mark. The command C-M-\ (^R Indent Region) applies Tab + to every line whose first character is between point and mark. + In Lisp mode, this does a Lisp indent. + + A more powerful grind command which can move text between lines + is C-M-G (^R Format Code). You might or might not like it. It + knows in different ways about Lisp code and Macsyma code. + + + 20.7.1 Customizing Lisp Indentationî 20.7.1 Customizing Lisp Indentationî 20.7.1 Customizing Lisp Indentation + + + The indentation pattern for a Lisp expression can depend on the + function called by the expression. For each Lisp function, you + can choose among several predefined patterns of indentation, or + define an arbitrary one with a TECO program. + + The standard pattern of indentation is as follows: the second + line of the expression is indented under the first argument, if + that is on the same line as the beginning of the expression; + otherwise, the second line is indented one space more than the + entire expression. Each following line is indented under the + previous line whose nesting depth is the same.î 117 EMACS Manual for ITS Users + + + + Another indentation pattern is used for functions whose names + start with "def". The second line of the expression is indented + two spaces more than the entire expression. The variable Lisp + Special Indent Offset (default 2) controls the increment in + depth. Each following line indents under the previous one. + Again, lines starting at lower depths do not count. Setting the + variable Lisp Indent DEFAnything to zero turns this feature off. + Then the standard pattern applies to def- functions by default. + + The indentation pattern for expressions that call the function + FOO is controlled specifically by the variable Lisp FOO Indent. + If this variable does not exist, the standard pattern or the + def- pattern is used. If the variable does exist, its value + should be one of these: + + + -3 selects the standard or def- indentation pattern, + as if the variable did not exist. + -2 selects the standard indentation pattern. The + def- pattern is not used, even if the function + name starts with "def". + -1 selects the def- indentation pattern, independent + of the function name and the setting of Lisp + Indent DEFAnything. + 0 or more selects special form with body indentation. The + value of the variable is the number of special + arguments that precede the body; thus, LET and + LAMBDA have one distinguished argument before the + body (the list of bound variables), PROGN has + none, and DO has two. The distinguished + expressions at the beginning are indented using + the standard pattern, but the first expression of + the body, if it should occur at the beginning of + a line, is indented two spaces deeper than the + entire expression. Following lines indent each + under the previous one as usual. The variable + Lisp Special Indent Offset (default 2) controls + the increment in depth. + a string should be a TECO expression which implements an + indentation pattern. Initially, Lisp PROG Indent + is defined as a string (the definition of & + Standard Lisp PROG Indent) which detects tags and + indents them specially. + + + The variable Lisp Indent Offset, if nonzero, selects a + different indentation pattern as the standard one. It indents + the second line of each expression that many spaces deeper than + the enclosing expression.î 118 EMACS Manual for ITS Users + + + + Implementing and selecting among the above indentation patterns + is the responsibility of the definition of the variable Lisp + Indentation Hook. This variable must exist and its value must be + a TECO program. By default its value is the definition of & + Standard Lisp Indentation Hook. + + Whatever its value, the hook is called with two arguments, + which are the position in the buffer of the most recent unclosed + "(" and the buffer position of the beginning of the line to be + indented. The buffer position of the cursor at the time the tab + was typed is stored as an offset from Z in qZ, so Z-qZ is that + buffer position. The hook should not modify the buffer. If it + returns 0 or no value, the caller will use the horizontal cursor + position of point as the column to indent to. Hence, to indent + under the "O" in PROG, it is sufficient to jump to that character + in the buffer and return. Alternatively, the hook can simply + return the desired indentation column number as a value. + + The hook should return a nonzero precomma value if following + lines of the same expression should be indented individually. If + it does not return a nonzero precomma value, the caller may + remember the indentation of this line and indent following lines + the same way. + + If Lisp FOO Indent has a TECO expression as its value, the same + interface conventions apply to it. + + Different Lisp-like languages can select an entirely different + set of indentation patterns by changing the value of the variable + Lisp Indent Language. Normally the value of this variable is the + string "Lisp". All the variables listed above with names + beginning with "Lisp" actually should have names beginning with + the Lisp Indent Language. Thus, if Lisp Indent Language is + changed to "Muddle", then the indentation commands will look for + variables Muddle Indent Offset, Muddle Indentation Hook, Muddle + PROG Indent, etc. + + + + 20.8 Editing Assembly-Language Programsî 20.8 Editing Assembly-Language Programsî 20.8 Editing Assembly-Language Programs + + + MIDAS mode is designed for editing programs written in the + MIDAS assembler. Major modes for other assemblers, such as PALX, + also exist but differ only in the syntax table and in the name of + the major mode hook that they will invoke. (There is also IBM370 + mode, for 370 assembler, which is completely different. Refer to + the self-documentation of the IBM370 library for information on + it).î 119 EMACS Manual for ITS Users + + + + In MIDAS mode, comments start with ";", and "<" and ">" have + the syntax of parentheses. In addition, there are five special + commands which understand the syntax of instructions and labels. + These commands are: + + + C-M-N Go to Next label. + C-M-P Go to Previous label. + C-M-A Go to Accumulator field of instruction. + C-M-E Go to Effective Address field. + C-M-D Kill next word and its Delimiting character. + + + + Two other commands with slightly different uses are + + + M-[ Move up to previous blank line. + M-] Move down to next blank line. + + + Any line which is not indented and is not just a comment is + taken to contain a label. The label is everything up to the + first whitespace (or the end of the line). C-M-N (^R Go to Next + Label) and C-M-P (^R Go to Previous Label) both position the + cursor right at the end of a label; C-M-N moves forward or down + and C-M-P moves backward or up. At the beginning of a line + containing a label, C-M-N moves past it. Past the label on the + same line, C-M-P moves back to the end of it. If you kill a + couple of indented lines and want to insert them right after a + label, these commands put you at just the right place. + + C-M-A (^R Go to AC Field) and C-M-E (^R Go to Address Field) + move to the beginning of the accumulator (AC) or effective + address fields of a PDP-10 instruction. They always stay on the + same line, moving either forward or backward as appropriate. If + the instruction contains no AC field, C-M-A positions to the + start of the address field. If the instruction is just an opcode + with no AC field or address field, a space is inserted after the + opcode and the cursor left after the space. In PDP-11 programs, + C-M-A moves to the first operand and C-M-E moves to the second + operand. + + Once you've gone to the beginning of the AC field you can often + use C-M-D (^R Kill Terminated Word) to kill the AC name and the + comma which terminates it. You can also use it at the beginning + of a line, to kill a label and its colon, or after a line's + indentation to kill the opcode and the following space. This is + very convenient for moving a label from one line to another. Inî 120 EMACS Manual for ITS Users + + + + general, C-M-D is equivalent to M-D C-D, except that all the + characters are saved on the kill ring, together. C-D, a + "deletion" command, doesn't save on the kill ring if not given an + argument. + + The M-[ and M-] commands are not, strictly speaking, redefined + by MIDAS mode. They go up or down to a paragraph boundary, as + usual. However, in MIDAS mode the criterion for a paragraph + boundary is changed by setting the variable Paragraph Delimiter + (See section 11.2 [Paragraphs], page 52.) so that only blank + lines (and pages) delimit paragraphs. So, M-[ moves up to the + previous blank line and M-] moves to the next one. + + + + 20.9 Major Modes for Other Languagesî 20.9 Major Modes for Other Languagesî 20.9 Major Modes for Other Languages + + + MACSYMA mode redefines the syntax of words and s-expressions in + an attempt to make it easier to move over MACSYMA syntactic + units. In addition, the C-M-G "grind" command is told to grind + text as MACSYMA instead of as Lisp. Also, the syntax of MACSYMA + comments is understood. + + TECO mode is good for editing EMACS library source files. It + connects Tab to ^R Indent Nested (see its self-documentation). + Comments start with "!* " and end with "!". In addition, the + PURIFY library, which contains many things useful for processing + library sources (including the commands to compile them), is + loaded. M-' and M-" are connected to functions ^R Forward TECO + Conditional and ^R Backward TECO Conditional which move forward + and backward over balanced TECO conditionals. In TECO mode on a + terminal with a Meta key, it may be useful to set the TECO flag + FS CTLMTA$ which causes Control-Meta commands to insert Control + characters. See section 22.5 [FS Flags], page 142. + + CLU mode is for editing CLU code. It is similar to LISP mode, + but it treats the statement nesting tokens like the appropriate + sorts of parentheses. It is in the library called CLU. See the + file INFO;ECLU. + + PL1 mode is for editing PL1 code, and causes Tab to indent an + amount based on the previous statement type. The body of the + implementation of PL1 mode is in the library PL1, which is loaded + automatically when necessary. See the file INFO;EPL1. + + PASCAL mode is similar to PL1 mode, for PASCAL. It is in the + library called PASCAL. See the file INFO;EPASC.î 121 EMACS Manual for ITS Users + + + + FORTRAN mode is implemented by the FORTRAN library. See the + file INFO;EFORTRAN. + + There are major modes for many other languages, but + documentation for them except that in the libraries themselves. + Any volunteers to write some? Meanwhile, you can look at the + documentation in the libraries. See section 22.2 [Libraries], + page 135.î 122 EMACS Manual for ITS Users + + + CHAPTER TWENTY-ONEî CHAPTER TWENTY-ONEî CHAPTER TWENTY-ONE + THE TAGS PACKAGE.î THE TAGS PACKAGE.î THE TAGS PACKAGE. + + + + The TAGS package remembers the locations of the function + definitions in a file and enables you to go directly to the + definition of any function, without searching the whole file. + + The functions of several files that make up one program can all + be remembered together if you wish; then the TAGS package will + automatically select the appropriate file as well. + + + + 21.1 How to Make a Tag Table for a Programî 21.1 How to Make a Tag Table for a Programî 21.1 How to Make a Tag Table for a Program + + + To use the TAGS package, you must create a tag table for the + source file or files in your package. Normally, the tag table + does not reside in any of those files, but in a separate tag + table file which contains the names of the text files which it + describes. Tag table files are generated by the :TAGS program. + The same program can be used to update the tag table if it + becomes very far out of date (slight inaccuracies do not matter). + Tag tables for INFO files work differently; the INFO file + contains its own tag table, which describes only that file. See + section 21.8 [INFO tag tables], page 131, for how to deal with + them. + + The normal mode of operation of the :TAGS program is to read in + an existing tag table and update it by rescanning the source + files that it describes. The old tag table file itself tells + :TAGS which source files to process. When making a new tag table + you must start by making a skeleton. Then :TAGS is used to turn + the skeleton into an accurate tag table. + + A skeleton tag table is like a real one except that it is + empty; there are no tags in it. It contains exactly this much + data, for each source file that it is going to describe: + + + + 0, + ^î |_ + + + The languages that :TAGS understands now are TECO, LISP, MIDAS, + FAIL, PALX, MUDDLE, MACSYMA, TJ6, and R. MIDAS will do forî 123 EMACS Manual for ITS Users + + + + MACRO-10 files. Any incompletely specified filenames will + default to > and to the directory on which the tag table file + ____î itself is stored. The "0," must be present, since :TAGS expects + that there will be a number in that place and will be completely + ^ ____î confused if there is not. The CRLF after each |_ also must be + ^î present. You can omit both the last |_ and its CRLF together, + however. + + Thus, a skeleton tag table for the files EMACS;USRCOM > and + EMACS;TAGS > would look like + + + EMACS;USRCOM > + 0,TECO + ^î |_ + EMACS;TAGS > + 0,TECO + ^î |_ + + + If this were written out as EMACS;EMACS TAGS, you could then do + + + + _______ ___ __ ____î :TAGS EMACS;EMACS (default FN2 is TAGS) + + + which would tell :TAGS to read in the tag table, and write back + an up-to-date tag table for the same set of source files. To + update the tag table because lots of changes have been made, the + same command to the :TAGS program will work. See section 21.6 + [Edit], page 129, for info on adding, deleting, or renaming files + in existing tag tables. + + The recently developed TAGGEN library is contains the function + Generate Tags File for updating a tag table. This library may + eventually replace the TAGS program, being easier to customize. + In the mean time, you are encouraged to try it out. Refer to its + self-documentation for more information. + + + + 21.2 How to Tell EMACS You Want to Use TAGSî 21.2 How to Tell EMACS You Want to Use TAGSî 21.2 How to Tell EMACS You Want to Use TAGS + + + Before you can use the TAGS package to find a tag, you must + tell EMACS the name of the tag table file you want to use. This + is done with the commandî 124 EMACS Manual for ITS Users + + + + M-X Visit Tag Table$ + + + The FN2 of "TAGS" need not be mentioned. + + EMACS can only know about one tag table file at a time, so + doing a second M-X Visit Tag Table causes the first one to be + forgotten (or written back if you have added definitions to it). + + Giving M-X Visit Tag Table a nonzero numeric argument, as in + + + C-U 1 M-X Visit Tag Table$ + + + has the additional effect of setting the variable Tags Find File + nonzero, which causes the TAGS package to use Find File rather + than Visit File when it needs to switch files. This causes all + the files to remain resident in the EMACS, in different buffers. + In the default mode, visiting a tag in a different file read it + in on top of the old file, in the same buffer (but it offers to + write out changes if there are any). Warning: you can easily run + out of address space by making too many buffers, this way. See + section 24.2.5 [Storage Exhausted], page 161. . + + Visit Tag Table is essentially equivalent to selecting the + buffer *TAGS* and visiting the tag table file in that buffer, + then returning to the previously selected buffer. Afterwards, + M-X List Buffers will show the buffer *TAGS* visiting that file. + The only difference is that Visit Tag Table causes the TAGS + library to be loaded. + + + + 21.3 Jumping to a Tagî 21.3 Jumping to a Tagî 21.3 Jumping to a Tag + + + To jump to the definition of a function, use the command + Meta-Period . You will go straight to the + definition of the tag. If the definition is in a different file + then TAGS visits that file. If it is in the same file, TAGS + leaves the mark behind and prints "^@" in the echo area. + + You do not need to type the complete name of the function to be + found; any substring will do. But this implies that sometimes + you won't get the function you intended. When that happens, C-U + Meta-Period will find the "next" function matching what you typed + (next, in the order of listing in the tag table). Thus, if you + want to find the definition of X-SET-TYPE-1 and you specify justî 125 EMACS Manual for ITS Users + + + + TYPE-1, you might find X-READ-TYPE-1 instead. You could then + type C-U Meta-Period until you reach X-SET-TYPE-1. + + If you want to make sure you reach a precise function the first + time, you should just include a character of context before and + after its name. Thus, in a Lisp program, put a space before and + after the function name. In a MIDAS program, put a linefeed + before it and a colon after. + + If Meta-Period is used before M-X Visit Tag Table has been + done, it asks for the name of a tag table file. After you type + this name and a , you type the name of the tag as usual. If + the variable Tag Table Filenames exists, it specifies the + defaults for the filename. + + Typing an Altmode as the first character of the argument to + Meta-Period allows you to switch to a new tag table. It prompts + for the tag table filenames, then prompts again for the tag. + + + + 21.4 Other Operations on Tag Tablesî 21.4 Other Operations on Tag Tablesî 21.4 Other Operations on Tag Tables + + + 21.4.1 Adding a New Function to a Tag Tableî 21.4.1 Adding a New Function to a Tag Tableî 21.4.1 Adding a New Function to a Tag Table + + + When you define a new function, its location doesn't go in the + tag table automatically. That's because EMACS can't tell that + you have defined a function unless you tell it by invoking the + function ^R Add Tag. Since the operation of adding a tag to a + tag table has proved not to be very necessary, this function no + longer placed on any character, by default. You can invoke with + M-X or connect it to a character if you like. For this section, + let's assume you have placed it on C-X Period. + + When you type the command C-X Period, the pointer should be on + the line that introduces the function definition, after the + function name and the punctuation that ends it. Thus, in a Lisp + program, you might type "(DEFUN FOO " (note the space after FOO) + and then type the C-X Period. In a MIDAS program, you might give + the C-X Period after typing "FOO:". In a TECO program in EMACS + format, you might type C-X Period after "!Set New Foo:!". + + ^R Add Tag modifies only the copy of the tag table loaded into + EMACS. To modify the tag table file itself, you must cause it to + be saved. M-X Save All Files is the easiest way to do this. + + Although local modifications to a file do not degrade theî 126 EMACS Manual for ITS Users + + + + efficiency of the TAGS package or require that the tag table be + updated with :TAGS, moving a function a great distance make it + much slower to find that function. In this case, you can "add" + the function to the tag table with C-X Period to give the table + its new location. Or you can just run :TAGS again to update + everything, as is usually done. + + + 21.4.2 How to Process All the Files in a Tag Tableî 21.4.2 How to Process All the Files in a Tag Tableî 21.4.2 How to Process All the Files in a Tag Table + + + The TAGS package contains a function M-X Next File which + visits, one by one, all the files described by the selected tag + table. This is useful when there is something to be done to all + of the files in the package. To start off the sequence, do C-U 1 + M-X Next File, which visits the first file. When you are + finished operating on one file, do M-X Next File (no argument) to + see the next. When all the files have been processed, M-X Next + File gives an error. + + The files of the package are visited in the order that they are + mentioned in the tag table, and the current place in the sequence + is remembered by the pointer in the buffer *TAGS* which holds the + tag table. Thus, if you visit a tag in a different file in the + middle of a M-X Next File sequence, you will screw it up unless + you return to the proper file again by visiting a tag (or go into + the buffer *TAGS* and reset the pointer). However, visiting any + other files directly, not using TAGS, does not interfere with the + sequence, and the next M-X Next File will go just where it would + have gone. + + Next File is also useful as a subroutine in functions that wish + to perform an automatic transformation (such as a Query Replace) + on each file. Such functions should call Next File with a + precomma argument as in 1,M(M.M Next File$) or 1,1M(M.M Next + File$). The precomma argument tells Next File to return 0 + instead of giving an error when there are no more files to + process. Normally, it returns -1. + + Here is an example of TECO code to do a Query Replace on all of + the files listed in the visited tag table: + + + 1M(M.M Next File$) + < M(M.M Query Replace$)FOO$BAR$ + 1,M(M.M Next File$);> + + + Tags Search and Tags Query Replace (see below) both work using + Next File.î 127 EMACS Manual for ITS Users + + + 21.4.3 Multi-File Searches and Replacementsî 21.4.3 Multi-File Searches and Replacementsî 21.4.3 Multi-File Searches and Replacements + + + The TAGS package contains a function Tags Search which will + search through all of the files listed in the visited tag table + in the order they are listed. Do + + + M-X Tags Search$ + + + to find every occurrence of . is a TECO search + ^ ^î string in which special TECO search characters such as |O, |X, + ^ ^ ^î |N, |B, and |Q are allowed. See section 19.3 [TECO Search + Strings], page 101. + + When M-X Tags Search reaches the end of the buffer, it visits + the next file automatically, typing its name in the echo area. + As soon as M-X Tags Search finds one occurrence, it returns. But + it defines the command Control-Period to resume the search from + wherever point is. + + M-X Tags Query Replace does a Query Replace over all the files + in a tag table. Like M-X Tags Search, it sets Control-. up to be + a command to continue the Query Replace, in case you wish to + exit, do some editing, and then resume scanning. + + With Tags Find File set nonzero, Tags Search or Tags Query + Replace could easily require more buffers than EMACS has room + for. To prevent such a problem, they do not always put each file + in a separate buffer. If Tags Search or Tags Query Replace wants + to search a file which is already visited in some buffer, it uses + the copy in that buffer. But if the file is not present, and + Tags Find File is 1, then instead of visiting it in its own + buffer, they visit it in a buffer named *Tags Search*. So at + most one new buffer is created. If Tags Find File is 2, a new + buffer is created for each file. + + The library MQREPL enables you to use Next File to repeat a + sequence of many Query Replace commands over a set of files, + performing all the replacements on one file at a time. + + + 21.4.4 Miscellaneous Applications of Tagsî 21.4.4 Miscellaneous Applications of Tagsî 21.4.4 Miscellaneous Applications of Tags + + + M-X List Tags$ lists all the tags in the specified + file. Actually, all the files in the tag table whose names + contain the string are listed.î 128 EMACS Manual for ITS Users + + + + M-X Tags Apropos$ lists all known tags whose names + contain . + + M-X Tags File List inserts in the buffer a list of the files + known in the visited tag table. + + M-X Tags Rescan runs :TAGS over the visited tag table and + revisits it. This is the most convenient way to update the tag + table. + + M-X View Arglist$ lets you look briefly at the line on + which a tag is defined, and at the lines of comments which + precede the definition. This is a good way to find out what + arguments a function needs. The file is always loaded into a + separate buffer, when this command is used. + + M-X What Tag? tells you which function's definition you are in. + It looks through the tag table for the tag which most nearly + precedes point. + + + + 21.5 What Constitutes a Tagî 21.5 What Constitutes a Tagî 21.5 What Constitutes a Tag + + + In Lisp code, a function definition must start with an "(" at + the beginning of a line, followed immediately with an atom which + starts with "DEF" (and does not start with "DEFP"), or which + starts with "MACRO", or which starts with "ENDF". The next atom + on the line is the name of the tag. If there is no second atom + on the line, there is no tag. + + In MIDAS code, a tag is any symbol that occurs at the beginning + of a line and is terminated with a colon or an equal sign. MIDAS + mode is good for MACRO-10 also. + + ^î FAIL code is like MIDAS code, except that one or two |A's or + "^"'s are allowed before a tag, spaces are allowed between the + tag name and the colon or equal sign, and _ is recognized as + equivalent to =. + + PALX code is like MIDAS code, except that spaces are allowed + between a tag and the following colon or equals, and local tags + such as "10$" are ignored. + + In TECO code, a tag starts with an "!" and ends with a ":!". + There may be any number of tags on a line, but the first one must + start at the beginning of a line.î 129 EMACS Manual for ITS Users + + + + In MUDDLE code, a tag is identified by a line that starts with + " + , + + ^î |_ + + + are the fully defaulted names of the file, + is one of the languages that TAGS knows how to + process, and are the actual tag information + ^ ____î (described below). The CRLF after each |_ must be present. You + ^î can omit both the last |_ and its CRLF together, however. + + A tags table file is for the most part an ordinary ASCII file, + and any changes you make in it, including changes to the source + files' names, will do what they appear to do. + + The one exception is that each entry contains a count, in + ^î decimal, of the number of characters in it, including the |_ and + CRLF. If you edit the contents of an individual source file'sî 130 EMACS Manual for ITS Users + + + + entry, and change its length, then the tag table is no good for + use in editing until the count is updated. This is usually done + by running :TAGS over it. :TAGS ignores the specified count and + always writes the correct count. If you are sure that the length + is unchanged, or if you change the count manually, then running + :TAGS is not necessary, but you do so at your own risk. + + Thus, if you are changing a source file's name, you should + simply change the name where it is present in the tag table, and + run :TAGS over it if necessary. + + To add a new source file, simply insert a dummy entry of the + sort used in making a new tag table. Then use :TAGS to update the + tag table. The dummy will turn into a real entry. + + You can delete a source file from a tag table by deleting its + entire entry. Since the counts of the remaining entries are + still valid, you need not run :TAGS over the file again. You can + also change the order of the entries without doing any harm. The + order of the entries matters if there are tags which appear in + more than one source file. + + You can edit everything else in the tag table too, if you want + to. You might want to change a language name once in a while, + but I doubt you will frequently want to add or remove tags, + especially since that would all be undone by the next use of + :TAGS! + + + + 21.7 How a Tag Is Described in the Tag Tableî 21.7 How a Tag Is Described in the Tag Tableî 21.7 How a Tag Is Described in the Tag Table + + + A tag table file consists of one or more entries in succession. + Each entry lists the tags of one source file, and has the overall + format described in the previous section, containing zero or more + lines describing tags. Here we give the format of each of those + lines. + + Starting with the third line of the tag table entry, each line + describes a tag. It starts with a copy of the beginning of the + line that the tag is defined on, up through the tag name and its + terminating punctuation. Then there is a rubout, followed by the + character position in decimal of the place in the line where + copying stopped. For example, if a line in a MIDAS program + starts with "FOO:" and the colon is at position 602 in the file, + then the line describing it in the tag table would beî 131 EMACS Manual for ITS Users + + + + FOO:603 + + + One line can describe several tags, if they are defined on the + same line; in fact, in that case, they must be on the same line + in the tag table, since it must contain everything before the tag + name on its definition line. For example, + + + !Foo:! !Bar:! + + + in a file of TECO code followed by character number 500 of the + file would turn into + + + !Foo:! !Bar:!500 + + + EMACS will be able to use that line to find either FOO or BAR. + :TAGS knows how to create such things only for TECO files, at the + moment. They aren't necessary in Lisp or MACSYMA files. In + MIDAS files, :TAGS simply ignores all but the first tag on a + line. + + + + 21.8 Tag Tables for INFO Structured Documentation Filesî 21.8 Tag Tables for INFO Structured Documentation Filesî 21.8 Tag Tables for INFO Structured Documentation Files + + + INFO files are divided up into nodes, which the INFO program + must search for. Tag tables for these files are designed to make + the INFO program run faster. Unlike a normal tag table, the tag + table for an INFO file resides in that file and describes only + that file. This is so that INFO, when visiting a file, can + automatically use its tag table if it has one. INFO uses the tag + tables of INFO files itself, without going through the normal + TAGS package, which has no knowledge of INFO file tag tables. + Thus, INFO file tag tables and normal ones resemble each other + only in their appearance and purpose, and that for convenience + the same :TAGS program generates both. In use, they are + unrelated. + + To create a tag table in an INFO file, you must first put in a + skeleton. This skeleton must be very close to the end of the + file (at most 8 lines may follow it, or INFO will not notice it), + ^ ^ ^î and it must start on the line following a |_ or |_|L which ends a + node. Its format is as follows:î 132 EMACS Manual for ITS Users + + + + ^ ^î |_|L + Tag Table: + ^î |_ + End Tag Table + + + No nodes may follow the tag table, or :TAGS will not put them + in it. :TAGS is one pass and after writing the tag table into + the file it copies the rest of the input file with no processing. + + To turn the skeleton into the real thing, or to update the tag + table, run :TAGS on the file and specify the /I switch, as in + + + :TAGS INFO;EMACS/I + + + :TAGS will process the file and replace the old tag table or + skeleton with an up-to-date tag table. The /I identifies the + specified file as an INFO file rather than a tag table file. + Also, it makes the default FN2 ">" rather than the usual "TAGS". + + Once the tag table is constructed, INFO will automatically make + use of it. A tag in an INFO file is just a node; whatever + ^î follows "Node:" on a line whose predecessor contains a "|_" is + taken to be a tag. The character which terminates the node name, + which may be a comma, tab, or CRLF, is not included in the tag + table. Instead, the rubout comes right after the tag name. This + is to make it easy for INFO to demand an exact match on node + names, rather than the substring match which the TAGS package + normally uses. + + Tag tables in INFO files must be kept close to up to date. + INFO will not find the node if its start has moved more than 1000 + characters before the position listed in the tag table. For best + results, you should update an INFO file's tag table every time + you modify more than a few characters of it.î 133 EMACS Manual for ITS Users + + + + CHAPTER TWENTY-TWOî CHAPTER TWENTY-TWOî CHAPTER TWENTY-TWO + SIMPLE CUSTOMIZATIONî SIMPLE CUSTOMIZATIONî SIMPLE CUSTOMIZATION + + + + In this chapter we describe the many simple ways of customizing + EMACS without knowing how to write TECO programs. + + One form of customization, reconnection of commands to + functions, was discussed above in the explanation of how M-X + commands work. See section 5.2.3 [Reconnecting Commands], + page 26. + + + + 22.1 Minor Modesî 22.1 Minor Modesî 22.1 Minor Modes + + + Minor modes are options which you can use or not. For example, + Auto Fill mode is a minor mode in which Spaces break lines + between words as you type. All the minor modes are independent + of each other and of the selected major mode. Most minor modes + say in the mode line when they are on; for example, "Fill" in the + mode line means that Auto Fill mode is on. + + Each minor mode is the name of the function that can be used to + turn it on or off. With no argument, the function turns the mode + on if it was off and off if it was on. This is known as + ________î toggling. A positive argument always turns the mode on, and an + explicit zero argument or a negative argument always turns it + off. All the minor mode functions are suitable for connecting to + single or double character commands if you want to enter and exit + a minor mode frequently. + + Auto Fill mode allows you to type text endlessly without + worrying about the width of your screen. Line separators are be + inserted where needed to prevent lines from becoming too long. + See section 11.4 [Filling], page 56. + + Auto Save mode protects you against system crashes by + periodically saving the file you are visiting. Whenever you + visit a file, auto saving is enabled if Auto Save Default is + nonzero; in addition, M-X Auto Save allows you to turn auto + saving on or off in a given buffer at any time. See section 13.3 + [Auto Save], page 72. + + Atom Word mode causes the word-moving commands, in Lisp mode, + to move over Lisp atoms instead of words. Some people like this, + and others don't. In any case, the s-expression motion commandsî 134 EMACS Manual for ITS Users + + + + can be used to move over atoms. If you like to use segmented + atom names like FOOBAR-READ-IN-NEXT-INPUT-SOURCE-TO-READ, then + you might prefer not to use Atom Word mode, so that you can use + M-F to move over just part of the atom, or C-M-F to move over the + whole atom. + + Overwrite mode causes ordinary printing characters to replace + existing text instead of shoving it over. It is good for editing + pictures. For example, if the point is in front of the B in + FOOBAR, then in Overwrite mode typing a G changes it to FOOGAR, + instead of making it FOOGBAR as usual. Also, Rubout is changed + to turn the previous character into a space instead of deleting + it. + + SAIL Character mode causes ASCII control characters in text to + display as themselves, with no conversion. This assumes that the + terminal uses codes 200 and above for cursor motion and erasure, + and can display all the ASCII control characters as graphic + ^î characters. The command Control-|B runs this command. + ^î Control-|B is a character which can generally only be typed on + terminals which can display the ASCII control characters in the + appropriate fashion. + + Word Abbrev mode allows you to define abbreviations that + automatically expand as you type them. For example, "wam" might + expand to "word abbrev mode". The abbreviations may depend on + the major (e.g. Lisp, Text, ...) mode you are currently in. To + use this, you must load the WORDAB library. See section 25 + [Wordab], page 172. + + Indent Tabs mode controls whether indentation commands use tabs + and spaces or just spaces to indent with. Usually they use both, + but you might want to use only spaces in a file to be processed + by a program or system which doesn't ignore tabs, or for a file + to be shipped to a system like Multics on which tab stops are not + every 8 characters. + + Most minor modes are actually controlled by variables. The + mode is on if the variable is nonzero. Setting the minor mode + with a command works by changing the variable. This means that + you can turn the modes on or off with Edit Options, or make their + values local to a buffer. See section 22.3 [Variables], + page 137. + + You could also put a minor mode in the local modes list of a + file, but that is usually bad practice. This is because usually + the preference for a minor mode is usually a matter of individual + style rather than a property of the file per se. To make this + more concrete, it is a property of a file that it be filled to aî 135 EMACS Manual for ITS Users + + + + certain column, but use of Auto Fill mode to accomplish that is a + matter of taste. So it would be good practice for the file to + specify the value of Fill Column, but bad practice for the file + to specify the value of Auto Fill Mode. + + If you find yourself constantly tempted to turn on Auto Fill + mode in local modes lists, what you probably really want is to + have Auto Fill mode on whenever you are in Text mode. This can + be accomplished with the following code in an EVARS file: + + + Text Mode Hook: 1M.LAuto Fill Mode$ + + + Suffice it to explain that this is TECO code to be executed + whenever Text mode is entered, which makes the variable Auto Fill + Mode local to the buffer with local value 1. + + + + 22.2 Libraries of Commandsî 22.2 Libraries of Commandsî 22.2 Libraries of Commands + + + All EMACS functions, including the ones described in this + document, reside in libraries. A function is not accessible + unless the library that contains it is loaded. Every EMACS + starts out with one library loaded: the EMACS library. This + contains all of the functions described in this document, except + those explicitly stated to be elsewhere. Other libraries are + provided with EMACS, and can be loaded automatically or on + request to make their functions available. See section + [Catalogue], page 234, for a list of them. + + To load a library, say M-X Load Library$. The + library is found, either on your own directory or whichever one + you specify, or on the EMACS directory, and loaded in. All the + functions in the library are then available for use. Whenever + you use M-X, the function name you specify is looked up in each + of the libraries which you have loaded, more recently loaded + libraries first. The first definition found is the one that is + used. + + For example, if you load the PICTURE library, you can then use + M-X Edit Picture to run the Edit Picture function which exists in + that library. + + In addition to making functions accessible to M-X, the library + may connect some of them to command characters. This is done by + the library's & Setup function (See the file INFO;CONV, nodeî 136 EMACS Manual for ITS Users + + + + Lib.). If you give Load Library an argument, the setup is not + done. + + You can also load a library temporarily, just long enough to + use one of the functions in it. This avoids taking up space + permanently with the library. Do this with the function Run + Library, as in M-X Run$$. The + library is loaded in, and executed. + Then the library is removed from the EMACS job. You can load it + in again later. + + M-X List Loaded Libraries types the names and brief + descriptions of all the libraries loaded, last loaded first. The + last one listed is always the EMACS library. + + You can get a brief description of all the functions in a + library with M-X List Library$, whether the library + is loaded or not. This is a good way to begin to find out what + is in a library that has no INFO documentation. Continue by + loading the library and using Help D to inquire further about + whichever functions looked interesting. + + The function Kill Libraries can be used to discard libraries + loaded with Load Library. (Libraries used with Run Library are + discarded automatically). However, of all the libraries + presently loaded, only the most recently loaded one can be + discarded. Kill Libraries offers to kill each loaded library, + most recently loaded first. It keeps killing libraries until you + say to keep one library. Then it returns, because the remaining + libraries cannot be deleted if that library is kept. + + Libraries are loaded automatically in the course of executing + certain functions. You will not normally notice this. For + example, the TAGS library is automatically loaded in whenever you + use M-. or Visit Tag Table for the first time. This process is + ___________î known as autoloading. It is used to make the functions in the + TAGS library available without the user's having to know to load + the library himself, while not taking up space in EMACSes of + people who aren't using them. It works by simply calling Load + Library on the library known to be needed. Another kind of + autoloading loads a library temporarily, the way Run Library + does. This is done when you use the DIRED function, for example, + since the DIRED library is not needed after the DIRED function + returns. (This does not use Run Library; it uses M.A, which is + what Run Library uses). + + You can make your own libraries, which you and other people can + then use, if you know how to write TECO code. See the file INFO; + CONV, node Lib, for more details.î 137 EMACS Manual for ITS Users + + + 22.3 Variablesî 22.3 Variablesî 22.3 Variables + + + A variable is a name which is associated with a value, either a + number or a string. EMACS uses many variables internally, and + has others whose purpose is to be set by the user for + customization. (They may also be set automatically by major + modes.) One example of such a variable is the Fill Column + variable, which specifies the position of the right margin (in + characters from the left margin) to be used by the fill and + justify commands. + + The easiest way for the beginner to set a named variable is to + use the function Edit Options. This shows you a list of selected + variables which you are likely to want to change, together with + their values, and lets you edit them with the normal editing + commands in a recursive editing level. Don't make any changes in + the names, though! Just change the values. Digits with maybe a + minus sign stand for a numeric value of the variable, while + string values are enclosed in doublequotes. Each option is + followed by a comment which says what the option is for. Type + the Help character for more information on the format used. + + When you are finished, exit Edit Options using C-M-C and the + changes will take effect. If you decide not to make the changes, + C-] gets out without redefining the options. See section 6.3 + [Recursive Editing Levels], page 30. + + If you give Edit Options a string argument, it shows you only + the options whose names include the string. For example, M-X + Edit Options$Fill shows only the options that have "Fill" in + their names. This is much more convenient, if you know what you + plan to do. + + However, Edit Options can be used only to set a variable which + already exists, and is marked as an option. Some commands refer + to variables which do not exist in the initial environment. Such + commands always use a default value if the variable does not + exist. In these cases you must create the variable yourself if + you wish to use it to alter the behavior of the command. Use M-X + Set Variable for this. You can set the variable to a numeric + value by doing + + + C-U M-X Set Variable$ + + + or to a string by doing î 138 EMACS Manual for ITS Users + + + + M-X Set Variable$$ + + + In fact, you can use Set Variable to set any variable, whether + it exists already or not. For existing variables, it does not + matter whether you use upper case or lower case letters, and you + are allowed to abbreviate the name as long as the abbreviation is + unique. If the variable might not exist yet, you must type the + name in full. While either upper case or lower case will still + work, you are encouraged to capitalize each word of the name for + aesthetic reasons since EMACS stores the name as you give it. + + To examine the value of a single variable, do + + + M-X View Variable$ + + + To print a complete list of all variables, do M-X List + Variables. List Variables with a string argument shows only the + variables whose names or values contain that string (like the + function Apropos). M-X Describe can be given a variable's name + instead of a function's name; it prints the variable's value and + its documentation, if it has any. + + If you want to set a variable a particular way each time you + use EMACS, you can use an init file or an EVARS file. This is + one of the main ways of customizing EMACS for yourself. An init + file is a file of TECO code to be executed when you start EMACS + up. They are very general, but writing one is a black art. You + might be able to get an expert to do it for you, or modify a copy + of someone else's. See the file INFO;CONV, node Init, for + details. An EVARS file is a much simpler thing which you can do + yourself. See section 22.6 [EVARS files], page 143. + + You can also set a variable with the TECO command + + + M.V $ + + + or + + + :I*$ M.V $ + + + This is useful in init files.î 139 EMACS Manual for ITS Users + + + + Any variable can be made local to a specific buffer with the + TECO command M.L$. Thus, if you want the comment + column to be column 50 in one buffer, whereas you usually like + 40, then in the one buffer do M.LComment Column$ using the + minibuffer. Then, you can do 50U$Comment Column$ in that buffer + and other buffers will not be affected. This is how local modes + lists in files work. M-X List Redefinitions describes the local + variables of the selected buffer in a verbose fashion. + + Most local variables are killed if you change major modes. + ____î Their global values come back. They are therefore called mode + ______ _________î locals. There are also permanent locals which are not killed by + changing modes; use 2,M.L to create one. Permanent locals are + used by things like Auto Save mode to keep internal information + about the buffer, whereas mode locals are used for customizations + intended only for one buffer. See the file INFO;CONV, node + Variables, for information on how local variables work, and + additional related features. + + Local values of variables can be specified by the file being + edited. For example, if a certain file ought to have a 50 column + width, it can specify a value of 50 for the variable Fill Column. + Then Fill Column will have the value 50 whenever this file is + edited, by anyone. Editing other files is not affected. See + section 22.7 [Locals], page 150, for how to do this. + + + + 22.4 The Syntax Tableî 22.4 The Syntax Tableî 22.4 The Syntax Table + + + All the EMACS commands which parse words or balance parentheses + ______ _____î are controlled by the syntax table. Each ASCII character has a + word syntax and a Lisp syntax. By changing the word syntax, you + can control whether a character is considered a word delimiter or + part of a word. By changing the Lisp syntax, you can control + which characters are parentheses, which ones are parts of + symbols, which ones are prefix operators, and which ones are just + ignored when parsing s-expressions. + + The syntax table is actually a string which is 128*5 characters + long. Each group of 5 consecutive characters of the syntax table + describe one ASCII character's syntax; but only the first three + of each group are used. To edit the syntax table, use M-X Edit + Syntax Table. But before we describe this command, let's talk + about the syntax of the syntax table itself. + + The first character in each group of five sets the word syntax. + This can be either "A" or a space. "A" signifies an alphabetic + character, whereas a space signifies a separator character.î 140 EMACS Manual for ITS Users + + + + The second character in each group is the Lisp syntax. It has + many possible values: + + + A an alphabetic character + Space a whitespace or nonsignificant character + ( an open parenthesis + ) a close parenthesis + ; a comment starter + ^î |M a comment ender + | a string quote + / a character quote + ' a prefix character + + + When a character has the syntax of an open parenthesis, that + means that the character is taken to be the beginning of a + parenthesized grouping when expressions are being parsed. Thus, + any number of different expression-starting characters can be + handled. + + The syntax of "prefix character" means that the character + becomes part of whatever object follows it, whether symbol or + list, and can also be in the middle of a symbol, but does not + constitute anything by itself if surrounded by whitespace. + + A character quote character causes itself and the next + character to be treated as alphabetic. + + A string quote is one which matches in pairs. All characters + inside a pair of string quotes are treated as alphabetic except + for the character quote, which retains its significance, and can + be used to force a string quote or character quote into a string. + + A comment starter is taken to start a comment, which ends at + the next comment ender, suppressing the normal syntax of all + characters between. Only the indentation commands give special + treatment to these two syntax codes; all other commands consider + them the same as Space (nonsignificant character). The commands + specifically for comments use the variables Comment Start, + Comment Begin, and Comment End to detect comments. This is so + that the comment delimiters can be multi-character strings. + + The third character in each group controls automatic + parenthesis matching display. It is defined only for characters + which have the Lisp syntax of close parentheses, and for them it + should contain the appropriate matching open parenthesis + character (or a space). If you insert a close parenthesis + character which is matched by the wrong kind of open parenthesisî 141 EMACS Manual for ITS Users + + + + character, it rings the bell. If the third syntax table + character of a close parenthesis is a space, any open parenthesis + is allowed to match it. + + The fourth and fifth characters in each group should always be + spaces, for now. They are not used. The reason they exist is so + that word-wise indexing can be used on the PDP-10 to access the + syntax of a character given in an accumulator. + + Edit Syntax Table displays the syntax table broken up into + labeled five-character groups. You can see easily what the + syntax of any character is. You are not editing the table + immediately, however. Instead, you are asked for the character + whose syntax you wish to edit. After typing it, you are + positioned at that character's five-character group. Overwrite + mode is on, so you can simply type the desired syntax entries, + which replace the old ones. You can also do arbitrary editing, + but be careful not to change the position of anything in the + buffer. When you exit the recursive editing level, you are asked + for another character to position to. An Altmode at this point + exits and makes the changes. A C-] at any time aborts the + operation. + + Many major modes alter the syntax table. Each such major mode + creates its own syntax table once and reselects the same string + whenever the mode is selected, in any buffer. Thus, all buffers + in Text mode at any time use the same syntax table. This is + important because if you ever change the syntax table of one + buffer that is in Text mode, you change them all. It is possible + to give one buffer a local copy with a TECO program: + + + MM Make Local Q-Register$..D$W :G..DU..D + + + The syntax tables belonging to the major modes are not + preinitialized in EMACS; they are created when the major mode is + invoked for the first time, by copying the default one and making + specific changes. Thus, any other changes you have made in the + default (Fundamental mode) syntax table at the beginning + propagate into all modes' syntax tables unless those modes + specifically override them. + + After a major mode has created its own syntax table, that table + is stored in the variable ..D. This makes a different + variable for each major mode, since the mode name is part of the + variable name. Further use of the major mode gets the syntax + table from that variable. If you create the variable yourself + before the first use of the major mode, the value you put there + will be used.î 142 EMACS Manual for ITS Users + + + + TECO programs and init files can most easily change the syntax + table with the function & Alter ..D (look at its documentation). + The syntax table is kept in the q-register named ..D, which + explains that name. + + + + 22.5 FS Flagsî 22.5 FS Flagsî 22.5 FS Flags + + + FS flags are variables defined and implemented by TECO below + the level of EMACS. Some of them are options which control the + behavior of parts of TECO such as the display processor. Some of + them control the execution of TECO programs; you are not likely + to want to change these. Others simply report information from + inside TECO. The list of FS flags is fixed when TECO is + assembled and each one exists for a specific purpose. + + FS flags are used mostly by the TECO programmer, but some of + them are of interest to the EMACS user doing minor customization. + For example, FS ECHO LINES$ is the number of lines in the echo + area. By setting this flag you can make the echo area bigger or + smaller. Many FS flags useful for customization are controlled + by EMACS variables; instead of setting the FS flag, you can set + the EMACS variable like any other. Setting the variable + automatically sets the FS flag as well. Here is a list of such + variables which control flags: + + + Auto Save Interval FS ^R MDLY$ + Bottom Display Margin FS %BOTTOM$ + Case Search FS BOTHCASE$ + Cursor Centering Point FS %CENTER$ + Display Mode Line Inverse FS INVMOD$ + Display Overprinting FS ^H PRINT$ and FS ^M PRINT$ + Echo Area Height FS ECHO LINES$ + End of Buffer Display Margin FS %END$ + Error Messages in Echo Area FS ECHO ERRORS$ + Fill Column FS ADLINE$ + Overwrite Mode FS ^R REPLACE$ + SAIL Character Mode FS SAIL$ + Top Display Margin FS %TOP$ + + + Setting one of these variables causes the flag to be set, but not + vice versa. To avoid confusion, always set these flags using the + associated variables, never directly, unless you are changingî 143 EMACS Manual for ITS Users + + + + them temporarily during one command and the user will not have + the opportunity to notice the confusion. + + To get the value of an FS flag, use the TECO command FS + followed by the name of the flag, terminated by an Altmode. + Spaces in the name of the flag are completely ignored, and case + does not matter. Thus, FS Tab Width$= executed in the minibuffer + prints the number of columns between tab stops used for display + of tab characters. See section 23 [Minibuffer], page 156. This + works only for flags with numeric values. The easiest way to + examine a flag's value with EMACS commands is + + + C-M-X View Variable (FS Tab Width$) + + + This works for both numeric and string values. + + To set the flag, give the FS command a numeric argument (which + must be a string pointer, if the intended value is a string). + For example, in the minibuffer or an init file, do + + + 10FS Tab Width$ + + + Be warned that FS always returns a value, so put a CRLF after it + to discard the value if necessary. + + It is possible to make an FS flag's value local to a buffer. + See the file INFO;CONV, node Vars. + + The documentation of individual FS flags can be found through + Help T. Help T FS Echo Lines prints the description of FS + ECHO LINES$. Spaces are not significant in Help T either. A + list of just the names of all FS flags is printed by the function + List TECO FS Flags, found in the library PURIFY. + + + + 22.6 Init Files and EVARS Filesî 22.6 Init Files and EVARS Filesî 22.6 Init Files and EVARS Files + + + EMACS is designed to be customizable; each user can rearrange + things to suit his taste. Simple customizations are primarily of + two types: moving functions from one character to another, and + setting variables which functions refer to so as to direct their + actions. Beyond this, extensions can involve redefining existing + functions, or writing entirely new functions and creating + sharable libraries of them.î 144 EMACS Manual for ITS Users + + + + The most general way to customize is to write an init file, a + TECO program which is executed whenever you start EMACS. The + init file is found by looking for a particular filename, ; EMACS. This method is general because the + program can do anything. It can ask you questions and do things, + rather than just setting up commands for later. However, TECO + code is arcane, and only a few people learn how to write it. If + you need an init file and don't feel up to learning to write TECO + code, ask a local expert to do it for you. See the file INFO; + CONV, for more about init files. + + However, simple customizations can be done in a simple way with + an EVARS file. Such a file serves the same sort of purpose as an + init file, but instead of TECO code, it contains just a list of + variables and values. Each line of the EVARS file names one + variable or one command character and says how to redefine it. + Empty lines, and lines starting with spaces or tabs, are ignored. + They can be used as comments. Your EVARS file is found by its + filename, as an init file is, but it should be called ; EVARS instead of EMACS. You can have both + an init file and an EVARS file if you want, as long as your init + file calls the default init file, since that is what processes + the EVARS file. + + To set a variable, include in the EVARS file a line containing + the name of the variable, a colon, and the value. A numeric + value is represented by the number. A string value is enclosed + ^î in double quotes. To include a double quote or a |] character in + ^î the value of the string, precede it with a |] to quote it. You + can also simply give the string value, with no quotes, as long as + it is not ambiguous (does not consist of digits or start with a + double quote); however, in this case, any spaces following the + colon become part of the value of the variable. They are not + ignored. Examples: + + + Comment Column: 70 + Comment Start: ";" + MM Foo:FTFOO$ + + + The last line defines a variable named MM Foo, which has the + effect of defining a function named Foo with the specified value + as its definition. + + To redefine a command character is a little more complicated. + ^î Instead of the name of a variable, give a |R (control-R) followed + by the character. Since the general Control and Meta character + cannot be part of a file, all Control and Meta characters areî 145 EMACS Manual for ITS Users + + + + ^î represented in a funny way: after the |R put the residue of the + ^î character after removing the Control and Meta, and before the |R + put periods, one for Control, two for Meta, and three for + ^î Control-Meta. Thus, C-D is represented by ".|RD" and C-M-; is + ^î represented by "...|R;". Lower case characters such as C-a are + usually defined as "execute the definition of the upper case + equivalent". Therefore, by redefining the C-A command you also + ^î change C-a; but if you redefine C-a, by saying ".|Ra" instead of + ^î ".|RA", you will not change C-A. So be careful about case. + + Instead of the value of a variable, for command character + redefinition you must give a TECO expression that returns the + desired definition. This is to make it easy to use any function + whose name you know, because M.MFOO$ is an expression that + returns the definition of the function FOO. Do not enclose the + TECO expression in quotes. Example: + + + ^î .|RK: M.M^R Kill Line$ + + + would give C-K the definition that it normally has. Remember + that in names of functions the "^R" is actually a "^" and an R, + not a control-R. The space before the M.M is part of the + expression, but it is ignored when the expression is executed. + + Some non-printing characters are a little tricky to redefine. + For example, you must know that Return, Linefeed, Tab, Backspace + and Altmode are not the same in TECO's command character set as + C-M, C-J, C-I, C-H and C-[, even though in ASCII they are + ^ ^î synonymous. By saying .|RJ you will redefine C-J; by saying |R + followed by a Linefeed (which you must insert in the EVARS file + by typing C-Q Linefeed) you can redefine Linefeed. Normally, C-J + is defined as "execute the definition of Linefeed", so you are + better off redefining Linefeed. + + You can also redefine a subcommand of a prefix character such + as C-X. For this, you have to know where the character's + dispatch table is stored. For C-X, the location of the dispatch + is called ".X"; you won't have any other prefix characters unless + you define them yourself. See the file INFO;CONV, node Prefix. + Knowing the location, you specify the subcommand by writing + ^î :location(|^character). This looks silly, but it is a TECO + expression with the right meaning. For example, redefining C-X + ^î C-S, the location is ".X" and the character is |S, so we say + + + ^ ^î :.X(|^|S): M.M^R Save File$î 146 EMACS Manual for ITS Users + + + + This gives C-X C-S the definition that it normally has. The + ^î subcommand character (|S in this case) can represent itself in + the EVARS file with no need for dots, because subcommand + characters are just ASCII, with no Meta allowed. + + You can include arbitrary TECO code in an EVARS file by writing + a definition for "*". The definition is executed as a TECO + expression but the value is ignored. Thus, to load the library + FOO, do + + + *: MM Load Library$FOO$ + + + Once the library is loaded, you can connect the functions in it + to commands as described above. + + Please refrain from giving newcomers to EMACS a copy of your + own init file before they understand what it does. Everyone + prefers his own customizations, and there is always a tendency to + proselytize, but by the same token your protege's tastes may be + different from yours. If you offer him your customizations at + the time when he is ready to understand what difference they make + and decide for himself what he prefers, then you will help him + get what he wants. Tell him about each individual change you + made, and let him judge them one by one. There is no reason for + him to choose all or nothing. + + + 22.6.1 EVARS File Examplesî 22.6.1 EVARS File Examplesî 22.6.1 EVARS File Examples + + + Here are some examples of how to do various useful things in an + EVARS file. + + This causes new buffers to be created in Lisp mode: + + + Default Major Mode: "LISP" + + + This causes new buffers to have Auto Fill mode turned on: + + + Buffer Creation Hook: "1M.L Auto Fill Mode$" + + + This causes all Text mode buffers to have Auto Fill mode turned + on: î 147 EMACS Manual for ITS Users + + + + Text Mode Hook: "1M.L Auto Fill Mode$" + + + This causes C-M-G to be undefined by copying the definition of + C-| (which is undefined): + + + ^ ^î ...|RG: Q.|R| + + + This redefines C-S to be a single character search command, and + M-S to be a non-incremental string search: + + + ^î .|RS: M.M ^R Character Search$ + ^î ..|RS: M.M ^R String Search$ + + + This redefines C-X V to run View File: + + + ^î :.X(|^V): M.M View File$ + + + This makes M-M a prefix character and defines M-M W to mark a + word and M-M P to mark a paragraph. It stores the dispatch + vector for the prefix character in the variable M-M Dispatch. + + + ^ ^ ^î ..|RM: MM Make Prefix Character$|]$M-M Dispatch|]$$ + Temp: "M-M $M-M Dispatch$ + " + Append the line in Temp to Prefix Char List. + ^ ^î *: Q$Prefix Char List$[1 Q$Temp$[2 :i$Prefix Char List$|]1|]2$ + ^î :$M-M Dispatch$(|^W): M.M ^R Mark Word$ + ^î :$M-M Dispatch$(|^P): M.M ^R Mark Paragraph$ + + + This loads the library LUNAR and defines C-Q to run a useful + function found in that library: + + + *: MM Load Library$LUNAR$ + ^î .|RQ: M.M ^R Various Quantities$ + + + This causes Auto Save mode to save under the visited filenames: + î 148 EMACS Manual for ITS Users + + + + Auto Save Visited File: 1 + + + This causes TAGS to bring new files into separate buffers: + + + TAGS Find File: 1 + + + This prevents the default init file from printing the message + "EMACS version nnn. Type ... for Help". + + + Inhibit Help Message: 1 + + + This redefines the list syntax of "%" to be ";" for "comment + starter", and that of ";" to be "A" for "alphabetic": + + + *: 1mm& Alter ..D$%;;A$ + + + 22.6.2 Init File Examplesî 22.6.2 Init File Examplesî 22.6.2 Init File Examples + + + Here are the ways to do exactly the same things in an init + file. Don't put more than one of these TECO expressions on a + line, or the first may leave behind a value which will affect the + operation of the second! + + This causes new buffers to be created in Lisp mode: + + + :I$Default Major Mode$LISP$ + + + This causes new buffers to have Auto Fill mode turned on: + + + ^î :I* 1M.L Auto Fill Mode|]$ $ M.VBuffer Creation Hook$ + + + It is different because the variable does not already exist. + ^î Note the |] used for getting the Altmode into the value. + + This causes all Text mode buffers to have Auto Fill mode turned + on: î 149 EMACS Manual for ITS Users + + + + ^î :I* 1M.L Auto Fill Mode|]$ $ M.VText Mode Hook$ + + + This causes C-M-G to be undefined by copying the definition of + C-| (which is undefined): + + + ^ ^î Q.|R| U...|RG + + + This redefines C-S to be a single character search command, and + M-S to be a non-incremental string search: + + + ^î M.M ^R Character Search$ U.|RS + ^î M.M ^R String Search$ U..|RS + + + This redefines C-X V to run View File: + + + ^î M.M View File$ U:.X(|^V) + + + This makes M-M a prefix character and defines M-M W to mark a + word and M-M P to mark a paragraph. It stores the dispatch + vector for the prefix character in the variable M-M Dispatch. + + + ^î MM Make Prefix Character$.Y$U..|RM + Q$Prefix Char List$[1 + ^ ^ ^î :i$Prefix Char List$|]1M-M |]$M-M Dispatch|]$ + $ ]1 + ^î M.M ^R Mark Word$ U:$M-M Dispatch$(|^W) + ^î M.M ^R Mark Paragraph$ U:$M-M Dispatch$(|^P) + + + This loads the library LUNAR and defines C-Q to run a useful + function found in that library: + + + MM Load Library$LUNAR$ + ^î M.M ^R Various Quantities$ U.|RQ + + + This causes Auto Save mode to save under the visited filenames: + î 150 EMACS Manual for ITS Users + + + + 1U$Auto Save Visited File$ + + + Compare this and the next example with the first two, in which + string values are used. + + This causes TAGS to bring new files into separate buffers: + + + 1M.VTAGS Find File$ + + + This prevents the default init file from printing the message + "EMACS version nnn. Type ... for Help". + + + 1M.VInhibit Help Message$ + + + This redefines the list syntax of "%" to be ";" for "comment + starter", and that of ";" to be "A" for "alphabetic": + + + 1mm& Alter ..D$%;;A$ + + + + 22.7 Local Variables in Filesî 22.7 Local Variables in Filesî 22.7 Local Variables in Files + + + _____ _____î By specifying local modes in a file you can cause certain major + or minor modes to be set, or certain character commands to be + defined, whenever you are visiting it. For example, EMACS can + select Lisp mode for that file, set up a special Comment Column, + or put a special command on the character C-M-Comma. Local modes + can specify the major mode, and the values of any set of named + variables and command characters. Local modes apply only while + the buffer containing the file is selected; they do not extend to + other files loaded into other buffers. + + The simplest kind of local mode specification sets only the + major mode. You put the mode's name in between a pair of + "-*-"'s, anywhere on the first nonblank line of the file. For + example, the first line of this file contains -*-Scribe-*-, + implying that this file should be edited in Scribe mode. + + _____î To specify more that just the major mode, you must use a local + _____ ____ ____î modes list, which goes in the last page of the file (it is best + to put it on a separate page). The local modes list starts withî 151 EMACS Manual for ITS Users + + + + a line containing the string "Local Modes:", and ends with a line + containing the string "End:". In between come the variable names + and values, just as in an EVARS file. See section 22.6 [EVARS + files], page 143. + + The line which starts the local modes list does not have to say + just "Local Modes:". If there is other text before "Local + ______î Modes:", that text is called the prefix, and if there is other + ______î text after, that is called the suffix. If these are present, + each entry in the local modes list should have the prefix before + it and the suffix after it. This includes the "End:" line. The + prefix and suffix are included to disguise the local modes list + as a comment so that the compiler or text formatter will not be + perplexed by it. If you do not need to disguise the local modes + list as a comment in this way, do not bother with a prefix or a + suffix. + + Aside from the "Local Modes:" and the "End:", and the prefix + and suffix if any, a local modes list looks like an EVARS file. + However, comments lines are not allowed, and you cannot redefine + C-X subcommands due to fundamental limitations of the data + structure used to remember local variables. Sorry. + + The major mode can be set by specifying a value for the + variable "Mode" (don't try setting the major mode this way except + in a local modes list!). It should be the first thing in the + local modes list, if it appears at all. A function M-X Foo can + be defined locally by putting in a local setting for a variable + named "MM Foo". See section 5.2 [Functions], page 24. + + Here is an example of a local modes list: + + + ;;; Local Modes: *** + ;;; Mode:Mumble *** + ;;; Comment Column:0 *** + ;;; Comment Start: ";;; " *** + ;;; Comment End:"***" *** + ^î ;;; ..|R/: m.m^R My Funny Meta-Slash$ *** + ;;; End: *** + + + Note that the prefix is ";;; " and the suffix is " ***". Note + also that comments in the file begin with ";;; " and end with + "***". Presumably the file contains code in the language Mumble, + in which comments must start and end that way. The prefix and + suffix are used in the local modes list to make the list appear + as comments when the file is read by the Mumble compiler.î 152 EMACS Manual for ITS Users + + + + The last page of the file must be no more than 10000 characters + long or the local modes list will not be recognized. This is + because EMACS finds the local modes list by scanning back only + 10000 characters from the end of the file for the last formfeed, + and then looking forward for the "Local Modes:" string. This + accomplishes these goals: a stray "Local Modes:" not in the last + page is not noticed; and visiting a long file that is all one + page and has no local mode list need not take the time to search + the whole file. + + + + 22.8 Keyboard Macrosî 22.8 Keyboard Macrosî 22.8 Keyboard Macros + + + C-X ( Start defining a keyboard macro. + C-X ) End the definition of a keyboard macro. + C-X E Execute the most recent keyboard macro. + C-U C-X ( Re-execute last keyboard macro and append to + its definition. + C-X Q Ask for confirmation when the keyboard macro + is executed. + C-U C-X Q Allow the user to edit for a while, each time + the keyboard macro is executed. + M-X Name Kbd Macro + Make the most recent keyboard macro into the + permanent definition of a command. + M-X Write Kbd Macro + Save a keyboard macro in a file. + + + ________ _____î A keyboard macro is a command defined by the user to abbreviate + a sequence of other commands. If you discover that you are about + to type C-N C-D forty times, you can define a keyboard macro to + do C-N C-D and call it with a repeat count of forty. + + Keyboard macros differ from ordinary EMACS commands, in that + they are written in the EMACS command language rather than in + TECO. This makes it easier for the novice to write them, and + makes them more convenient as temporary hacks. However, the + EMACS command language is not powerful enough as a programming + language to be useful for writing anything intelligent or + general. For such things, TECO must be used. + + EMACS functions were formerly known as macros (which is part of + the explanation of the name EMACS), because they were macros + within the context of TECO as an editor. We decided to change + the terminology because, when thinking of EMACS, we consider TECO + a programming language rather than an editor. The only "macros" + in EMACS now are keyboard macros.î 153 EMACS Manual for ITS Users + + + + You define a keyboard macro while executing the commands which + are the definition. Put differently, as you are defining a + keyboard macro, the definition is being executed for the first + time. This way, you can see what the effects of your commands + are, so that you don't have to figure them out in your head. + When you are finished, the keyboard macro is defined and also has + been, in effect, executed once. You can then do the whole thing + over again by invoking the macro. + + + 22.8.1 Basic Useî 22.8.1 Basic Useî 22.8.1 Basic Use + + + To start defining a keyboard macro, type the C-X ( command + (^R Start Kbd Macro). From then on, your commands continue to be + executed, but also become part of the definition of the macro. + "Def" appears in the mode line to remind you of what is going on. + When you are finished, the C-X ) command (^R End Kbd Macro) + terminates the definition (without becoming part of it!). + + The macro thus defined can be invoked again with the C-X E + command (^R Execute Kbd Macro), which may be given a repeat count + as a numeric argument to execute the macro many times. C-X ) can + also be given a repeat count as an argument, in which case it + repeats the macro that many times right after defining it, but + defining the macro counts as the first repetition (since it is + executed as you define it). So, giving C-X ) an argument of 2 + executes the macro immediately one additional time. An argument + of zero to C-X E or C-X ) means repeat the macro indefinitely + (until it gets an error). + + If you want to perform an operation on each line, then either + you should start by positioning point on the line above the first + one to be processed and then begin the macro definition with a + C-N, or you should start on the proper line and end with a C-N. + Either way, repeating the macro will operate on successive lines. + + After you have terminated the definition of a keyboard macro, + you can add to the end of its definition by typing C-U C-X (. + This is equivalent to plain C-X ( followed by retyping the whole + definition so far. As a consequence it re-executes the macro as + previously defined. + + If you wish to save a keyboard macro for longer than until you + define the next one, you must give it a name. If you do M-X Name + Kbd Macro$FOO, the last keyboard macro defined (the one which + C-X E would invoke) is turned into a function and given the name + FOO. M-X FOO will from then on invoke that particular macro. + Name Kbd Macro also reads a character from the keyboard andî 154 EMACS Manual for ITS Users + + + + redefines that character command to invoke the macro. You can + use a bit prefix character in specifying the command; you can + also type a C-X command to be redefined. When you have finished + typing the command characters, Name Kbd Macro asks you whether it + should go ahead and redefine the character. + + To save a keyboard macro permanently, do M-X Write Kbd Macro. + Supply the function name of the keyboard macro as a string + argument, or else it will ask you to type the character which + invokes the keyboard macro. The keyboard macro is saved as a + library which, when loaded, automatically redefines the keyboard + macro. The filename is read from the terminal. Its second name + should be :EJ, like other libraries; that is the default. + + To examine the definition of a keyboard macro, use the function + View Kbd Macro. Either supply the name of the function which + runs the macro, as a string argument, or type the command which + invokes the macro when View Kbd Macro asks for it. + + + 22.8.2 Executing Macros with Variationsî 22.8.2 Executing Macros with Variationsî 22.8.2 Executing Macros with Variations + + + If you want to be allowed to do arbitrary editing at a certain + point each time around the macro (different each time, and not + remembered as part of the macro), you can use the C-U C-X Q + command (^R Kbd Macro Query). When you are defining the macro, + ___î this lets you do some editing, which does not become part of the + macro. When you are done, exit with C-M-C to return to defining + the macro. When you execute the macro, at that same point, you + will again be allowed to do some editing. When you exit this + time with C-M-C, the execution of the macro will resume. If you + abort the recursive editing level with C-], you will abort the + macro definition or execution. + + You can get the effect of Query Replace, where the macro asks + you each time around whether to make a change, by using the + command C-X Q with no argument in your keyboard macro. When you + are defining the macro, the C-X Q does nothing, but when the + macro is invoked the C-X Q reads a character from the terminal to + decide whether to continue. The special answers are Space, + Rubout, Altmode, C-L, C-R. A Space means to continue. A Rubout + means to skip the remainder of this repetition of the macro, + starting again from the beginning in the next repetition. An + Altmode ends all repetitions of the macro, but only the innermost + macro (in case it was called from another macro). C-L clears the + screen and asks you again for a character to say what to do. C-R + enters a recursive editing level; when you exit, you are asked + again (if you type a Space, the macro will continue from whereverî 155 EMACS Manual for ITS Users + + + + you left things when you exited the C-R). Anything else exits + all levels of keyboard macros and is reread as a command.î 156 EMACS Manual for ITS Users + + + CHAPTER TWENTY-THREEî CHAPTER TWENTY-THREEî CHAPTER TWENTY-THREE + THE MINIBUFFERî THE MINIBUFFERî THE MINIBUFFER + + + + __________î The minibuffer is a facility by means of which EMACS commands + can read input from the terminal, allowing you to use EMACS + commands to edit the input while you are typing it. Usually it + is used to read a TECO program to be executed. + + + M-Altmode Invokes an empty minibuffer. + M-% Invokes a minibuffer initialized with a Query + Replace. + C-X Altmode Re-execute a recent minibuffer command. + C-X ^ Add more lines to the minibuffer. + C-\ Meta-prefix for use in the minibuffer. + C-C C-Y Rotate ring of recent minibuffer commands. + + + The primary use of the minibuffer is for editing and executing + simple TECO programs such as + + + MM Query Replace$FOO + $BAR + $ + + + (which could not be done with M-X Query Replace because when M-X + is used Return terminates the arguments). + + You can always tell when you are in a minibuffer, because the + mode line contains something in parentheses, such as + "(Minibuffer)" or "(Query Replace)". There is also a line of + dashes across the screen a few lines from the top. Strictly + speaking, the minibuffer is actually the region of screen above + the line of dashes, for that is where you edit the input that the + minibuffer is asking you for. Editing has been limited to a few + lines so that most of the screen can continue to show the file + you are visiting. + + If you want to type in a TECO command, use the minibuffer with + the command Meta-Altmode, (^R Execute Minibuffer). An empty + minibuffer will appear, into which you should type the TECO + command string. Exit with Altmode Altmode, and remember that + neither of the two Altmodes is inserted into your TECO command + although the first one may appear to be. When the TECO command + is executed, "the buffer" will be the text you were editing + before you invoked the minibuffer.î 157 EMACS Manual for ITS Users + + + + Often, a minibuffer starts out with some text in it. This + means that you are supposed to add to that text, or, sometimes, + to delete some of it so as to choose among several alternatives. + For example, Meta-% (^R Query Replace) provides you with a + minibuffer initially containing the string "MM Query Replace$". + The cursor comes at the end. You are then supposed to add in the + arguments to the Query Replace. + + In a minibuffer, you can edit your input until you are + satisfied with it. Then you tell EMACS you are finished by + typing two Altmodes. An Altmode not followed by another Altmode + is simply inserted in the buffer. This is because it is common + to want to put Altmodes into the minibuffer, which usually + contains a string of TECO commands. For example, in Meta-% + (^R Query Replace) each argument must be ended by an Altmode. + However, when you type two Altmodes in a row, neither one remains + in the buffer. The two Altmodes do nothing to the text in the + minibuffer, they just exit. + + Since Altmode is self-inserting, typing Meta characters can be + a problem. You can do it by using C-\ instead of Altmode as the + Meta-prefix. If you type a Control-Meta character on your + keyboard, the corresponding ASCII control character is inserted + in the minibuffer. This is because the Lisp commands are rarely + useful when editing TECO code, but insertion of control + characters is frequent. If you really want to use a Control-Meta + EMACS command, you must use C-C to type it. You cannot use C-\ + C-A to type C-M-A, because C-\ (unlike Altmode) ignores the + Control bit of the following character, so you must use C-C C-A. + The motivation for this quirk of C-\ is that C-\ C-B (to obtain + M-B) is easier to type than C-\ B, especially if it is typed + several times in a row. + + You can cancel your input in a minibuffer and start all over + again by typing C-G. That kills all the text in the minibuffer. + A C-G typed when the minibuffer is already empty exits from the + minibuffer. Usually, this aborts whatever command was using the + minibuffer, so it will return without doing anything more. For + example, if you type two C-G's at Meta-%'s minibuffer, you will + return to top level and no Query Replace will be done. Typing a + single C-G at a preinitialized minibuffer to empty the buffer is + not very useful, since you would have to retype all the initial + text. + + The last five distinct minibuffer commands or M-X commands you + have issued are remembered in a ring buffer in q-register .M. + The C-X Altmode command (^R Re-execute Minibuffer) re-executes + the last command in the ring. With an argument , it + re-executes the 'th previous command. The command is printedî 158 EMACS Manual for ITS Users + + + + out (only the first 40 characters or so) and you are asked to + confirm with "Y" or "N". + + You can also get your previous minibuffer and M-X commands back + into the minibuffer to be edited and re-executed with changes. + Giving M-Altmode an argument, as in C-U M-Altmode, causes the + minibuffer to be loaded up with the last command in the ring, as + if you had typed it in again from scratch. You can then edit it, + execute it by typing two Altmodes, or cancel it with C-G. To get + an earlier command string instead of the most recent one, use the + command C-C C-Y once you are in the minibuffer. This command + "rotates" the ring of saved commands much as M-Y rotates the ring + of killed text. Each C-C C-Y reveals an earlier command string, + until the ring has rotated all the way around and the most recent + one reappears. C-C C-Y is actually a way of saying C-M-Y, but in + the minibuffer that's the only way to type it, since Altmode + inserts itself and Control-Meta characters insert control + characters. + + If you exit from Meta-Altmode with a C-G, nothing is executed + and the previous minibuffered command string is still remembered + as the last one. + + While in a minibuffer, if you decide you want the minibuffer to + use more lines on the screen, you can use C-X ^ (^R Grow Window) + to get more. It gets one more line, or as many lines as its + argument says.î 159 EMACS Manual for ITS Users + + + + CHAPTER TWENTY-FOURî CHAPTER TWENTY-FOURî CHAPTER TWENTY-FOUR + CORRECTING MISTAKES AND EMACS PROBLEMSî CORRECTING MISTAKES AND EMACS PROBLEMSî CORRECTING MISTAKES AND EMACS PROBLEMS + + + + If you type an EMACS command you did not intend, the results + are often mysterious. This chapter tells what you can do to + cancel your mistake or recover from a mysterious situation. + EMACS bugs and system crashes are also considered. + + + + 24.1 Quitting and Abortingî 24.1 Quitting and Abortingî 24.1 Quitting and Aborting + + + C-G Quit. Cancel running or partially typed command. + C-] Abort recursive editing level and cancel the + command which invoked it. + M-X Top Level + Abort all recursive editing levels and subsystems + which are currently executing. + + + There are three ways of cancelling commands which are not + ________ ________î finished executing: quitting with C-G, and aborting with C-] or + M-X Top Level. Quitting is cancelling a partially typed command + or one which is already running. Aborting is cancelling a + command which has entered a recursive editing level or subsystem. + + Quitting with C-G is used for getting rid of a partially typed + command, or a numeric argument that you don't want. It also + stops a running command in the middle in a relatively safe way, + so you can use it if you accidentally give a command which takes + a long time. In particular, it is safe to quit out of killing; + ___ ___î either your text will all still be there, or it will all be in + the kill ring (or maybe both). Quitting an incremental search + does special things documented under searching; in general, it + may take two successive C-G's to get out of a search. C-G can + interrupt EMACS at any time, so it is not an ordinary command. + + Aborting with C-] (Abort Recursive Edit) is used to get out of + a recursive editing level and cancel the command which invoked + it. Quitting with C-G cannot be used for this, because it is + used to cancel a partially typed command within the recursive + editing level. Both operations are useful. For example, if you + are editing a message to be sent, C-G can be used to cancel the + commands you use to edit the message, and C-] cancels sending the + message. C-] either tells you how to resume the aborted command + or queries for confirmation before aborting.î 160 EMACS Manual for ITS Users + + + + When you are in a position to use M-X, you can use M-X Top + Level. This is equivalent to "enough" C-] commands to get you + out of all the levels of subsystems and recursive edits that you + are in. C-] gets you out one level at a time, but M-X Top Level + goes out all levels at once. Both C-] and M-X Top Level are like + all other commands, and unlike C-G, in that they are effective + only when EMACS is listening. + + + + 24.2 Dealing with Common Forms of EMACS Lossageî 24.2 Dealing with Common Forms of EMACS Lossageî 24.2 Dealing with Common Forms of EMACS Lossage + + + This section describes various conditions which can cause EMACS + not to work, or cause it to display strange things, and how you + can correct them. + + + 24.2.1 Error Messageî 24.2.1 Error Messageî 24.2.1 Error Message + + + When EMACS prints an error message, it occupies the top line of + the screen, ends with a "?", and is accompanied by the ringing of + the bell. Space causes the error message to disappear and be + replaced by the first line of text again. Any other command is + executed normally as if there had been no error message (the + error message disappears during the redisplay after the command). + However, "?" enters the error handler, which can be used to + inspect the function call stack. Most users will not be + interested in doing this. Type Help inside the error handler to + get its documentation, or C-] to exit it. + + If you prefer to have echo messages printed in the echo area, + set the variable Error Messages in Echo Area nonzero. + + + 24.2.2 Subsystems and Recursive Editing Levelsî 24.2.2 Subsystems and Recursive Editing Levelsî 24.2.2 Subsystems and Recursive Editing Levels + + + Subsystems and recursive editing levels are important and + useful features of EMACS, but they can seem like malfunctions to + the user who does not understand them. + + If the mode line starts with a bracket "[" or a parenthesis + "(", or does not start with the word "EMACS", then you have + entered a subsystem (See section 6.1 [Subsystems], page 28.) or a + recursive editing level (See section 6.3 [Recursive Editing + Levels], page 30.).î 161 EMACS Manual for ITS Users + + + + In such a situation, first try typing C-]. This will get out + of any recursive editing level and most subsystems. The usual + mode line and text display will reappear. If C-] does not seem + to have worked, type the Help character. Instead of printing + "Doc (Type ? for Help)" in the echo area, it will print a list of + the subsystem's commands. One of these should be a command to + exit or abort. + + If the above techniques fail, try restarting (see section + 24.2.7). + + + 24.2.3 Garbage on the Screenî 24.2.3 Garbage on the Screenî 24.2.3 Garbage on the Screen + + + If the data on the screen looks wrong, it could be due to line + noise on input or output, a bug in the terminal, a bug in EMACS + redisplay, or a bug in an EMACS command. To find out whether + there is really anything wrong with your text, the first thing to + do is type C-L. This is a command to clear the screen and + redisplay it. Often this will display the text you expected. + Think of it as getting an opinion from another doctor. + + + 24.2.4 Garbage Displayed Persistentlyî 24.2.4 Garbage Displayed Persistentlyî 24.2.4 Garbage Displayed Persistently + + + If EMACS persistently displays garbage on the screen, or if it + outputs the right things but scattered around all the wrong + places on the screen, it may be that EMACS has the wrong idea of + your terminal type. The first thing to do in this case is to + exit from EMACS and restart it. Each time EMACS is restarted it + asks the system what terminal type you are using. Whenever you + detach and move to a terminal of a different type you should + restart EMACS as a matter of course. If you stopped EMACS with + the exit command, or by interrupting it when it was awaiting a + command, then this is sure to be safe. + + The system itself may not know what type of terminal you have. + You should try telling the system with the :TCTYP command. + + + 24.2.5 URK Error (Address Space Exhausted)î 24.2.5 URK Error (Address Space Exhausted)î 24.2.5 URK Error (Address Space Exhausted) + + + If attempting to visit a file or load a library causes an "URK" + error, it means you have filled up the address space; there is no + room inside EMACS for any more files or libraries. In this + situation EMACS will try to run the function Make Space for you.î 162 EMACS Manual for ITS Users + + + + If EMACS is unable to do it for you, you may still be able to do + M-X Make Space yourself. This command compacts the data inside + EMACS to free up some space. It also offers to discard data that + may be occupying a lot of space, such as the kill ring (See + section 9.1 [Killing], page 39.), the undo memory (See + section 24.3 [Undo], page 163.), and buffers created by RMAIL, + TAGS and INFO. Another way of freeing space is to kill buffers + with M-X Kill Some Buffers (See section 14 [Buffers], page 83.) + or unload libraries with M-X Kill Libraries (See section 22.2 + [Libraries], page 135.). + + Use the command M-X What Available Space to find out how close + you are to running out of space. It tells you how many K of + space you have available for additional files or libraries. + + Visiting a file causes an URK error if the file does not fit in + the available virtual memory space, together with the other + buffers and the libraries loaded. A big enough file causes an + URK error all by itself. For editing such large files, use the + command Split File (in the SPLIT library) to break it into + subfiles. These will be fairly large files still, but not too + large to edit. After editing one or more of the subfiles, use + the command Unsplit File (also in SPLIT) to put them back + together again. + + + 24.2.6 All Type-in Echoes and Nothing Else Happensî 24.2.6 All Type-in Echoes and Nothing Else Happensî 24.2.6 All Type-in Echoes and Nothing Else Happens + + + If you find that EMACS is not responding to your commands + except for echoing them all at the bottom of the screen, + including the Return character, and that Rubout causes erased + characters to be retyped instead of erased, then you have managed + to exit from EMACS back to TECO. Often this follows an "Error in + error handler" message which indicates that a condition arose in + which the error handler could not function. You can get back + into EMACS by typing :M..L$$, or by restarting (see below). If + you ever want to exit back to TECO, you can do M-X Top Level with + an argument greater than zero. Before using :M..L$$, get rid of + any other characters you have typed by mistake by typing a C-G. + + + 24.2.7 EMACS Hung and Not Respondingî 24.2.7 EMACS Hung and Not Respondingî 24.2.7 EMACS Hung and Not Responding + + + Sometimes EMACS gets hung and C-G does not work. The more + drastic procedure of restarting EMACS may work at such times. + C-G can fail to work because it only takes effect between the + TECO commands which make up an EMACS program, never in the middleî 163 EMACS Manual for ITS Users + + + + of one (only a few TECO commands allow quitting at any time), so + as to prevent TECO's internal data structures from becoming + inconsistent. If EMACS is hung inside a TECO command, C-G is not + noticed, but restarting can still be tried. + + To restart EMACS, type CALL or C-Z to stop EMACS, then $G to + restart it. While restarting TECO in this way is usually safe + (especially at times when TECO is doing I/O), there are certain + times at which it will cause the TECO data structures to be + inconsistent, so do not try it unless other measures have failed. + + Your ultimate safeguard against a wedged EMACS is to save your + work frequently. + + + + 24.3 Undoing Changes to the Bufferî 24.3 Undoing Changes to the Bufferî 24.3 Undoing Changes to the Buffer + + + If you mistakenly issue commands that make a great change to + the buffer, you can often undo the change without having to know + precisely how it came about. This is done by using M-X Undo. + Type M-X Undo and the change is undone. It does not matter + if you have moved the cursor since you made the change; it is + undone where it was originally done. + + The first thing Undo does is tell you what kind of change it + plans to undo (kill, fill, undo, case-convert, etc). Then it + asks whether to go ahead. If you say "Y", the change is actually + undone. + + Not all changes to the buffer can be undone: deletion (as + opposed to killing) can't be, and changes in indentation can't + be, nor can many forms of insertion (but they aren't as important + since they don't destroy information). Also, a Replace String or + Query Replace can't be undone, which is a shame. The reason is + that actually they make many small changes, and Undo only knows + how to remember one contiguous change. Perhaps someday I will be + able to fix this. + + As a result, when you say Undo, it may undo something other + than the latest change if the latest change was not undoable. + This might seem to pile one disaster on another, but it doesn't, + ______î because you can always Undo the Undo if it didn't help. But you + can avoid even having to do that, if you look at what type of + change Undo says it will undo. + + If you want to undo a considerable amount of editing, not just + the last change, the Undo command can't help you, but M-X Revertî 164 EMACS Manual for ITS Users + + + + File (See section 13.2 [Revert], page 72.) might be able to. If + you have been writing a journal file (See section 24.4 + [Journals], page 164.), you can replay the journal after deleting + the part that you don't want. + + + + 24.4 Journal Filesî 24.4 Journal Filesî 24.4 Journal Files + + + A journal file is a record of all the commands you type during + an editing session. If you lose editing because of a system + crash, an EMACS bug, or a mistake on your part, and you have made + a journal file, you can replay the journal or part of it to + recover what you lost. Journal files offer an alternative to + auto saving, using less time and disk space if there is no crash, + but requiring more time when you recover from a crash. See + section 13.3 [Auto Save], page 72. + + + 24.4.1 Writing Journal Filesî 24.4.1 Writing Journal Filesî 24.4.1 Writing Journal Files + + + In order to make a journal file, you must load the JOURNAL + library and then execute M-X Start Journal File$. + Immediately, most of the current status of EMACS is recorded in + the journal file, and all subsequent commands are recorded as + they are typed. This happens invisibly and silently. The + journal file is made fully up to date on the disk after every + 50th character, so the last 50 characters of type in is the most + you can lose. + + The default filenames for the journal file are ; JRNL. There is rarely a reason to use any + other name, because you only need one journal file unless you are + running two EMACSes at the same time. + + + 24.4.2 Replaying Journal Filesî 24.4.2 Replaying Journal Filesî 24.4.2 Replaying Journal Files + + + To replay the journal file, get a fresh EMACS, load JOURNAL, + and do M-X Replay Journal File$. The filename can + usually be omitted since normally you will have used the defaults + when creating the journal. + + After a delay while the files, buffers and libraries are loaded + as they were when the journal file was written, EMACS will begin + replaying the commands in the journal before your very eyes.î 165 EMACS Manual for ITS Users + + + + Unlike keyboard macros, which execute invisibly until they are + finished, journal files display as they are executed. This + allows you to see how far the replay has gone. You can stop the + process at any time by typing C-G. Aside from that, you should + not type anything on the keyboard while the replay is going on. + + If the need for a replay is the result of a system crash or + EMACS crash, then you probably want to replay the whole file. + This is what happens naturally. If you are replaying because you + made a great mistake, you probably want to stop the replay before + the mistake. This is when it becomes useful to type C-G to stop + the replay. Alternatively, you can edit the journal file, and + delete everything from the point of the mistake to the end, + before you replay it. + + Once the replay is complete, save all your files immediately. + Don't tempt fate! + + If you quit with C-G in the middle of a command while writing a + journal file, there is no way to record in the journal file how + much of the command has already been completed. So, when the + journal is replayed, EMACS has to ask you to fill in for it. The + command which was interrupted will be replayed to completion; + then, you are given a recursive editing level in which to restore + the file to the desired state. This happens only if the C-G + originally interrupted an executing command. C-G typed to + discard an argument or partial command while EMACS is waiting for + input can be and is replayed correctly without asking you for + help. + + + 24.4.3 Journal File Formatî 24.4.3 Journal File Formatî 24.4.3 Journal File Format + + + To edit a journal file, you must know the format. It is + designed to be mostly transparent. + + The primary problem which the journal file format has to solve + is how to represent 9-bit command characters in a file which can + contain only 7-bit ASCII characters. (We could have filled the + journal file with 9-bit characters, but then you would not be + able to print it out or edit it). The solution we have used is + to represent each command by two characters in the file. + + So, a Control character is represented by a caret ("^") + followed by the basic character, as in "^E" for Control-E. This + was chosen to be mnemonically significant. A Meta character is + represented by "+" followed by the basic character, so that + Meta-[ is represented by "+[". A Control-Meta character isî 166 EMACS Manual for ITS Users + + + + represented by "*" followed by the basic character, as in "*X" + for C-M-X. + + A command which is not Control or Meta is represented as a + space followed by the command itself, except that Return is + represented by a CRLF rather than a space and a carriage return. + This prevents the journal file from being one huge line, and + makes insertion of text very recognizable: the text inserted + appears in the journal file alternating with spaces. + + The Help character, which is not covered by the scheme as + described so far, is represented by "??". + + An asynchronous quit, which is a problem for replaying, is + ^î represented by a single character, a |G, while a synchronous + ^î quit, which can be replayed reliably, is represented by ":|G". + ^î EMACS considers a quit synchronous, and uses ":|G" to record it, + if EMACS was waiting for terminal input when the C-G was typed. + + Your commands themselves are not the only information in the + journal file. EMACS records other information which is necessary + in replaying the journal properly. The colon character ":" + indicates a block of such information. Usually the extent of the + block is easily recognizable because its contents do not resemble + the representations of commands described above. A large block + of information starting with a colon appears at the beginning of + every journal file. + + Colons are also used to record the precise effects of certain + commands such as C-V whose actions depend on how the text was + displayed on the screen. Since the effects of such commands are + not completely determined by the text, replaying the command + could produce different results, especially if done on a terminal + with a different screen size. The extra information recorded in + the journal makes it possible to replay these commands with + fidelity. + + A semicolon in the journal file begins a comment, placed there + for the benefit of a human looking at the journal. The comment + ends at the beginning of the following line. + + + 24.4.4 Warningsî 24.4.4 Warningsî 24.4.4 Warnings + + + Proper replaying of a journal file requires that all the + surrounding circumstances be unchanged. + + In particular, replaying begins by visiting all the files thatî 167 EMACS Manual for ITS Users + + + + were visited when the writing of the journal file began; not the + latest versions of these files, but the versions which were the + latest at the earlier time. If those versions, which may no + longer be the latest, have been deleted, then replaying is + impossible. + + If your init file has been changed, the commands when replayed + may not do what they did before. + + These are the only things that can interfere with replaying, as + long as you start writing the journal file immediately after + starting EMACS. But as an editing session becomes longer and + files are saved, the journal file contains increasing amounts of + waste in the form of commands whose effects are already safe in + the newer versions of the edited files. Replaying the journal + will replay all these commands wastefully to generate files + identical to those already saved, before coming to the last part + of the session which provides the reason for replaying. + Therefore it becomes very desirable to start a new journal file. + However, many more precautions must be taken to insure proper + replaying of a journal file which is started after EMACS has been + used for a while. These precautions are described here. If you + cannot follow them, you must make a journal checkpoint (see + below). + + If any buffer contains text which is not saved in a file at the + time the journal file is started, it is impossible to replay the + journal correctly. This problem cannot possibly be overcome. To + avoid it, M-X Start Journal File offers to save all buffers + before actually starting the journal. + + Another problem comes from the kill ring and the other ways in + which EMACS remembers information from previous commands. If any + such information which originated before starting the journal + file is used after starting it, the journal file cannot be + replayed. For example, suppose you fill a paragraph, start a + journal file, and then do M-X Undo? When the journal is + replayed, it will start by doing M-X Undo, but it won't know what + to undo. It is up to you not to do anything that would cause + such a problem. It should not be hard. It would be possible to + eliminate this problem by clearing out all such data structures + when a journal file is started, if users would prefer that. + + A more difficult problem comes from customization. If you + change an option or redefine a command, then start a journal + file, the journal file will have no record of the change. It + will not replay correctly unless you remember to make the same + change beforehand. Customizations made in an init file do not + cause a problem because the init file has also been run when theî 168 EMACS Manual for ITS Users + + + + journal file is replayed. Customizations made directly by the + user while the journal file is being written are also no problem + because replaying will make the same changes at the right times. + However, a customization made while a journal file is being + written will be a problem if a new journal file is started. + + + 24.4.5 Journal Checkpointsî 24.4.5 Journal Checkpointsî 24.4.5 Journal Checkpoints + + + The only cure for the problems of starting a journal in + mid-session is to record the complete state of EMACS at the time + the journal is begun. This is not done normally because it is + slow; however, you can do this if you wish by giving M-X Start + Journal File a numeric argument. This writes the complete state + of EMACS into the file ;TS ESAVE. To replay the + journal, run ESAVE, the saved checkpoint, instead of EMACS; then + load JOURNAL and do M-X Replay Journal File as described above. + Be sure to delete the checkpoint if you are finished with it, + since it tends to be large. Delete them also when you log out; + it may be possible to have a command file which deletes them + automatically when you log out. Checkpoint files more than a day + old may be deleted by others without notice; but don't leave it + up to them. + + + + 24.5 Reporting Bugsî 24.5 Reporting Bugsî 24.5 Reporting Bugs + + + Sometimes you will encounter a bug in EMACS. To get it fixed, + you must report it. It is your duty to do so; but you must know + when to do so and how if it is to be constructive. + + + 24.5.1 When Is There a Bugî 24.5.1 When Is There a Bugî 24.5.1 When Is There a Bug + + + If EMACS executes an illegal instruction, or dies with an + operating system error message that indicates a problem in the + program (as opposed to "disk full"), then it is certainly a bug. + + If EMACS updates the display in a way that does not correspond + to what is in the buffer, then it is certainly a bug. If a + command seems to do the wrong thing but the problem is gone if + you type C-L, then it is a case of incorrect display updating. + + Taking forever to complete a command can be a bug, but you must + make certain that it was really EMACS's fault. Some commandsî 169 EMACS Manual for ITS Users + + + + simply take a long time. Quit or restart EMACS and type Help L + to see whether the keyboard or line noise garbled the input; if + ____î the input was such that you know it should have been processed + quickly, report a bug. If you don't know, try to find someone + who does know. + + If a command you are familiar with causes an EMACS error + message in a case where its usual definition ought to be + reasonable, it is probably a bug. + + If a command does the wrong thing, that is a bug. But be sure + you know for certain what it ought to have done. If you aren't + familiar with the command, or don't know for certain how the + command is supposed to work, then it might actually be working + right. Rather than jumping to conclusions, show the problem to + someone who knows for certain. + + Finally, a command's intended definition may not be best for + editing with. This is a very important sort of problem, but it + is also a matter of judgement. Also, it is easy to come to such + a conclusion out of ignorance of some of the existing features. + It is probably best not to complain about such a problem until + you have checked the documentation in the usual ways (INFO and + Help), feel confident that you understand it, and know for + certain that what you want is not available. If you feel + confused about the documentation instead, then you don't have + grounds for an opinion about whether the command's definition is + optimal. Make sure you read it through and check the index or + the menus for all references to subjects you don't fully + understand. If you have done this diligently and are still + confused, or if you finally understand but think you could have + said it better, then you have a constructive complaint to make + about the documentation. It is just as important to report + documentation bugs as program bugs. + + + 24.5.2 How to Report a Bugî 24.5.2 How to Report a Bugî 24.5.2 How to Report a Bug + + + When you decide that there is a bug, it is important to report + it and to report it in a way which is useful. What is most + useful is an exact description of what commands you type, + starting with a fresh EMACS just loaded, until the problem + happens. Send the bug report to BUG-EMACS@MIT-AI. + + The most important principle in reporting a bug is to report + _____î facts, not hypotheses or conditions. It is always easier to + report the facts, but people seem to prefer to strain to think up + explanations and report them instead. If the explanations areî 170 EMACS Manual for ITS Users + + + + based on guesses about how EMACS is implemented, they will be + useless; we will have to try to figure out what the facts must + have been to lead to such speculations. Sometimes this is + impossible. But in any case, it is unnecessary work for us. + + For example, suppose that you type C-X C-V GLORP;BAZ UGH, + visiting a file which (you know) happens to be rather large, and + EMACS prints out "I feel pretty today". The best way to report + the bug is with a sentence like the preceding one, because it + gives all the facts and nothing but the facts. + + Do not assume that the problem is due to the size of the file + and say "When I visit a large file, EMACS prints out 'I feel + pretty today'". This is what we mean by "guessing explanations". + The problem is just as likely to be due to the fact that there is + a "Z" in the filename. If this is so, then when we got your + report, we would try out the problem with some "big file", + probably with no "Z" in its name, and not find anything wrong. + There is no way in the world that we could guess that we should + try visiting a file with a "Z" in its name. + + Alternatively, the problem might be due to the fact that the + file starts with exactly 25 spaces. For this reason, you should + make sure that you don't change the file until we have looked at + it. Suppose the problem only occurs when you have typed the C-X + C-A command previously? This is why we ask you to give the exact + sequence of characters you typed since loading the EMACS. + + You should not even say "visit the file ..." instead of "C-X + C-V" unless you know that it makes no difference which visiting + command is used. Similarly, rather than saying "if I have three + characters on the line", say "after I type A B C C-P", + if that is the way you entered the text. A journal file + containing the commands you typed to reproduce the bug is a very + good form of report. + + If you are not in Fundamental mode when the problem occurs, you + should say what mode you are in. + + Be sure to say what version of EMACS and TECO are running. If + you don't know, type Meta-Altmode Q$EMACS Version$= FS Version$= + $$ and EMACS will print them out. (This is a use of the + minibuffer. See section 23 [Minibuffer], page 156.) + + If the bug occurred in a customized EMACS, or with several + optional libraries loaded, it is helpful to try to reproduce the + bug in a more standard EMACS with fewer libraries loaded. It is + best if you can make the problem happen in a completely standard + ___î EMACS with no optional libraries. If the problem does not occurî 171 EMACS Manual for ITS Users + + + + in a standard EMACS, it is very important to report that fact, + because otherwise we will try to debug it in a standard EMACS, + not find the problem, and give up. If the problem does depend on + an init file, then you should make sure it is not a bug in the + init file by complaining to the person who wrote the file, first. + He should check over his code, and verify the definitions of the + TECO commands he is using by looking in INFO;TECORD >. Then if + he verifies that the bug is in EMACS he should report it. We + cannot be responsible for maintaining users' init files; we might + not even be able to tell what they are supposed to do. + + If you can tell us a way to cause the problem without reading + in any files, please do so. This makes it much easier to debug. + If you do need files, make sure you arrange for us to see their + exact contents. For example, it can often matter whether there + are spaces at the ends of lines, or a line separator after the + last line in the buffer (nothing ought to care whether the last + line is terminated, but tell that to the bugs). + + If EMACS gets an operating system error message, such as for an + illegal instruction, then you can probably recover by restarting + it. But before doing so, you should make a dump file. If you + restart or continue the EMACS before making the dump, the trail + will be covered and it will probably be too late to find out what + happened. Use the DDT command + + + :PDUMP CRASH;EMACS + + + (or use any other suitable filename) to do this. Your bug report + should contain the filename you used for the dump, and the error + message printed when the EMACS stopped, as well as the events + leading up to the bug. The first number in the error message is + the PC, which is not recorded by :PDUMP, so it must be copied + precisely. Also type .JPC/ and include DDT's response in your + report. + + A dump is also useful if EMACS gets into a wedged state in + which commands that usually work do strange things.î 172 EMACS Manual for ITS Users + + + CHAPTER TWENTY-FIVEî CHAPTER TWENTY-FIVEî CHAPTER TWENTY-FIVE + WORD ABBREVIATION INPUTî WORD ABBREVIATION INPUTî WORD ABBREVIATION INPUT + + + + Word Abbrev mode allows you to abbreviate text with a single + "word", with EMACS expanding the abbreviation automatically as + soon as you have finished the abbreviation. + + Abbrevs are also useful for correcting commonly misspelled or + mistyped words ("thier" could expand to "their"), and for + uppercasing words like "EMACS" (abbrev "emacs" could expand to + "EMACS"). + + To use this mode, just do M-X Word Abbrev Mode. (Another + M-X Word Abbrev Mode will turn the mode off; it toggles.) + + For example, in writing this documentation we could have + defined "wam" to be an abbreviation for "word abbrev mode". + After typing just the letters "wam", we see just that, "wam", but + if we then finish the word by typing space or period or any other + punctuation, the "wam" is replaced by (and redisplays as) "word + abbrev mode". If we capitalize the abbrev, "Wam", the expansion + is capitalized: "Word abbrev mode". If we capitalize the whole + abbrev, WAM", each word in the expansion is capitalized: "Word + Abbrev Mode". In this particular example, though, we would + define "wam" to expand to "Word Abbrev mode" since it is always + to be capitalized that way. + + Thus, typing "I am in wam now" produces "I am in Word Abbrev + mode now". + + Word Abbrev mode does not interfere with the use of major + modes, such as Text, Lisp, TECO, PL1, or minor modes, such as + Auto Fill. Those modes (or the user) may redefine what functions + are connected to characters; this does not hamper Word Abbrev + mode. + + There are two kinds of word abbreviations: mode and global. A + mode word abbrev applies only in one major mode (for instance + only in Text mode), while a global word abbrev applies regardless + of major mode. If some abbrev is defined both as a mode word + abbrev for the current mode and as a global word abbrev, the mode + word abbrev expansion takes precedence. + + For instance, you might want an abbrev "foo" for "find outer + otter" in Text mode, an abbrev "foo" for + "FINAGLE-OPPOSING-OPINIONS" in Lisp, and an abbrev "foo" for + "meta-syntactic variable" in any other mode (the global word + abbrev).î 173 EMACS Manual for ITS Users + + + + Word abbrevs can be defined one at a time (adding them as you + think of them), or many at a time (from a definition list). You + can save them in a file and read them back later. If you turn + off Word Abbrev mode, abbrevs stop expanding automatically, but + their definitions are remembered in case you turn Word Abbrev + mode back on. + + + + 25.1 Basic Usageî 25.1 Basic Usageî 25.1 Basic Usage + + + C-X C-A Define a mode abbrev for some text before + point. + C-X + Define a global abbrev for some text before + point. + C-X C-H Define expansion for mode abbrev before + point. + C-X - Define expansion for global abbrev before + point. + C-M-Space Expand abbrev without inserting anything. + M-' Mark a prefix to be glued to an abbrev + following. + C-X U Unexpand the last abbrev, or undo a C-X U. + + + M-X List Word Abbrevs + Shows definitions of all abbrevs. + + M-X Edit Word Abbrevs + Lets you edit the definition list directly. + + M-X Read Word Abbrev File$ + Defines word abbrevs from a definition file. + + M-X Write Word Abbrev File$ + Makes a definition file from current abbrev + definitions. + + Readable Word Abbrev Files + Option variable to control abbrev file format. + + + This section describes the most common use of Word Abbrev mode. + If you don't read any more than this, you can still use Word + Abbrev mode quite effectively. + + Note that each of the above commands will also work when Word + Abbrev mode is turned off, unlike the automatic expanders (suchî 174 EMACS Manual for ITS Users + + + + as Space or Period), allowing you to manually define and expand + abbrevs. (If you want to do this, you might also see the M-X + Expand Word Abbrevs in Region command's self-documentation.) + + + 25.1.1 Adding Word Abbrevsî 25.1.1 Adding Word Abbrevsî 25.1.1 Adding Word Abbrevs + + + C-X C-A (^R Add Mode Word Abbrev) defines a mode abbrev for the + word before point (this does not include any punctuation between + that word and point, though). It prints the word before point in + the echo area and asks you for that word's abbreviation. Type + the abbrev (which you may edit with Rubout and C-U) followed by a + Return. The abbrev must be a "word": it must contain only + letters and digits; the case of the letters is irrelevant. If + you'd rather define a global abbrev, use C-X + (^R Add Global + Word Abbrev), which works similarly. + + You can redefine an abbrev with C-X C-A or C-X +. If the + abbrev already has a definition, it tells you what that was, and + asks for confirmation. + + To define an abbrev for more than one word of text, give C-X + C-A or C-X + a numeric argument: an argument greater than 0 + means the expansion is that many words before point; an argument + of 0 means to use the region (between point and mark). (By using + the region specification you can make an abbrev for any text, not + just a sequence of words.) The message in the echo area provides + you with confirmation of just what the expansion will be; you + might see: + + + Text Abbrev for "this is the expansion": + + + Sometimes you may think you already had an abbrev for some + text, use it, and see that it didn't expand. In this case, the + C-X C-H (^R Inverse Add Mode Word Abbrev) or C-X - (^R Inverse + Add Global Word Abbrev) commands are helpful: they ask you to + _________î type in an expansion rather than an abbrev. In addition to + defining the abbrev, they also expand it. If you give them a + numeric argument, n, they use the nth word before point as the + abbrev. + + You can kill abbrevs (cause them to no longer expand) by giving + a negative numeric argument to C-X C-A or C-X +. For instance, + to kill the global abbrev "foo" type C-U - C-X + foo.î 175 EMACS Manual for ITS Users + + + 25.1.2 Controlling Abbrev Expansionî 25.1.2 Controlling Abbrev Expansionî 25.1.2 Controlling Abbrev Expansion + + + When an abbrev expands, the capitalization of the expansion is + determined by the capitalization of the abbrev: If the abbrev is + all lowercase, the expansion is as defined. If the abbrev's + first letter is uppercase, the expansion's first letter is too. + If the abbrev is all uppercase, there are two possibilities: if + the expansion is a single word, it is all-uppercased; otherwise, + each of its words has its first letter uppercased (such as for + use in a title). (If you don't like this distinction between + single-word and multi-word expansions, set the variable WORDAB + All Caps to 1. Then an all-uppercase abbrev will always result + in an all-uppercase expansion.) + + Abbrevs normally expand when you type some punctuation + character; the abbrev expands and the punctuation character is + inserted. There are other ways of expanding abbrevs: C-M-Space + (^R Abbrev Expand Only) causes the abbrev just before point to be + expanded without inserting any other character. C-M-Space will + expand abbrevs even if Word Abbrev mode is currently off; this + can be useful if the system is slow, and you just want to + manually expand a few abbrevs. M-' (^R Word Abbrev Prefix Mark) + allows you to "glue" an abbrev onto any prefix: suppose you have + the abbrev "comm" for "committee", and wish to insert + "intercommittee "; type "inter", M-' (you will now see "inter-"), + and then "comm "; "inter-comm " becomes "intercommittee ". M-X + Expand Word Abbrevs in Region checks each word in the region and + offers to expand each word abbrev found; for more details see its + self-documentation. (It is similar to the M-X Query Replace + command.) + + + 25.1.3 Unexpanding Abbrevsî 25.1.3 Unexpanding Abbrevsî 25.1.3 Unexpanding Abbrevs + + + C-X U (^R Unexpand Last Word) "unexpands" the last abbrev's + expansion, replacing the last expansion with the abbrev that + caused it. If any auto-filling was done because of the expansion + (you had Auto Fill mode on), that too is undone. If you type + another C-X U, the first one is "undone" and the abbrev is + expanded again. Only the last expansion can be undone. + Sometimes you may find that C-X U unexpands an abbrev later than + the one you're looking at. In this case, do another C-X U and go + back and manually correct the earlier expansion. + + If you know beforehand that a word will expand, and want to + prevent it, you can simply "quote" the punctuation character with + C-Q. For example, typing "comm", a C-Q, and then "." gives + "comm." without expanding.î 176 EMACS Manual for ITS Users + + + 25.1.4 Listing Abbrevsî 25.1.4 Listing Abbrevsî 25.1.4 Listing Abbrevs + + + M-X List Word Abbrevs shows all currently defined abbrevs. + An abbrev "foo" that expands to "this is an abbrev" in Text mode + and has been expanded 3 times, is listed as: + + + foo: (Text) 3 "this is an abbrev" + + + An abbrev "gfoo" which expands to "this is a global abbrev" in + all modes, expanded 11 times, is listed as: + + + gfoo: 11 "this is a global abbrev" + + + Note that any use of the double-quote character (") inside an + expansion is doubled, to distinguish the use of " from the "s + that surround the whole expansion. Thus if the global abbrev + 'helpc' expands to 'the "Help" character', it is listed as: + + + helpc: 3 "the ""Help"" character" + + + 25.1.5 Editing the Definition Listî 25.1.5 Editing the Definition Listî 25.1.5 Editing the Definition List + + + M-X Edit Word Abbrevs places you in a recursive editing level, + editing the current word abbrev definition list. The abbrevs + appear in the same format used by M-X List Word Abbrevs. When + you exit (via C-M-C), the current word abbrevs are redefined from + the edited definition list: any abbrevs that have been deleted + from the list are killed, new ones added to the list are defined, + and old ones changed are modified. In effect, after exiting the + Edit Word Abbrev editing level, all previously-defined word + abbrevs are killed, and the edited list is used to define new + abbrevs. Typing C-] (Abort Recursive Edit) aborts Edit Word + Abbrevs, without killing or redefining any abbrevs. + + + 25.1.6 Saving Abbrev Definitionsî 25.1.6 Saving Abbrev Definitionsî 25.1.6 Saving Abbrev Definitions + + + M-X Write Word Abbrev File$ writes an "abbrev + definition file" which contains the definitions of all the + abbrevs in your EMACS now. M-X Read Word Abbrevî 177 EMACS Manual for ITS Users + + + + File$ reads in such a file and defines the abbrevs. + (Other abbrevs already defined are not affected unless the file + redefines them.) If you don't supply a filename, the last file + you used in either of these commands is used again, originally + defaulting to WORDAB DEFNS. With these two commands, you can + save the abbrevs you defined in one EMACS and restore them in + another EMACS another day. If you want abbrevs to be + automatically saved when you exit EMACS (with C-X C-C (^R Return + to Superior)), set the option variable Save Word Abbrevs to 1. + (They are saved only if the definitions have changed.) + + The format of the definition file is designed for fast loading, + not ease of human readability. (But if you have to, you can + figure it out enough to read or even edit it.) If you want M-X + Write Word Abbrev File to write a human-readable version instead, + set the option Readable Word Abbrev Files to 1. (M-X Read Word + Abbrev File will be able to read this format, but not as fast.) + + If you have an EVARS file, you might want to put the following + lines into it in order to turn on Word Abbrev mode, have your + abbrev definition file automatically read when EMACS starts up, + and enable automatic exit-saving: + + + *: 1 MM Word Abbrev Mode$ + *: MM Read Word Abbrev File$WORDAB DEFNS$ + Save Word Abbrevs:1 + + + Or if you have an init file, use the following Teco code: + + + 1 MM Word Abbrev Mode$ + MM Read Word Abbrev File$WORDAB DEFNS$ + 1u$Save Word Abbrevs$ + + + + 25.2 Advanced Usageî 25.2 Advanced Usageî 25.2 Advanced Usage + + + The use of Word Abbrev mode as discussed in the previous + section suffices for most users. However, some users who use + Word Abbrev mode a lot or have highly tailored environments may + desire more flexibility or need more power to handle extreme + situations than the basic commands provide.î 178 EMACS Manual for ITS Users + + + 25.2.1 Alternatives and Customizationsî 25.2.1 Alternatives and Customizationsî 25.2.1 Alternatives and Customizations + + + M-X Make Word Abbrev$$$ + + M-X Kill All Word Abbrevs + + M-X Make These Characters Expand$ + + M-X Attach Word Abbrev Keyboard Macro + + ^R Kill Mode Word Abbrev + + ^R Kill Global Word Abbrev + + Only Global Abbrevs + Set this option if you only use globals. + + Additional Abbrev Expanders + Variable for adding a few more expanders. + + WORDAB Ins Chars + Variable for replacing entire set of expanders. + + + The basic commands for defining a new mode abbrev, C-X C-A (^R + Add Mode Word Abbrev) and C-X C-H (^R Inverse Add Mode Word + Abbrev), work only in the current mode. A more general command + is M-X Make Word Abbrev which takes three string arguments: the + first is the abbrev, the second is the expansion, and the third + is the mode (such as "Text"). This command can also define + global abbrevs, by providing "*" as the mode name. + + M-X Kill All Word Abbrevs is a very quick way of killing + every abbrev currently defined. After this command, no abbrev + will expand. (A slower but more careful way is with M-X Edit + Word Abbrevs.) + + The functions ^R Kill Mode Word Abbrev and ^R Kill Global Word + Abbrev exist, but are not connected to any commands by default. + If you find having to specify negative arguments to C-X C-A + (^R Add Mode Word Abbrev) and C-X + (^R Add Global Word Abbrev) + inconvenient, you should connect these functions to commands. + (See section 5.2 [Set Key], page 24. Or See section 22.6 [Init], + page 143.) + + If you prefer to use only global abbrevs then you should set + the option variable Only Global Abbrevs to 1. You can do this + after or before turning on Word Abbrev mode; it makes noî 179 EMACS Manual for ITS Users + + + + difference. This causes the global abbrev definers which would + otherwise be on C-X + (^R Add Global Word Abbrev) and C-X - + (^R Inverse Add Global Word Abbrev) to be on the easier to type + characters C-X C-A and C-X C-H. In addition, the checking done + whenever you type an expander character (a punctuation character) + is about three times faster for the no-expansion case, which is + what happens most of the time. + + Normally, the following characters cause expansion (followed by + whatever they would normally do were Word Abbrev mode off; such + as, insert themselves): !~@#;$%^&*-_=+[]()\|:`"{},<.>'/? and + Space, Return, Linefeed, and Tab. You can, however, specify + additional characters to cause expansion (digits, for instance, + or greek letters on keyboards with Top-keys). M-X Make These + Characters Expand$ adds the characters in the + string argument to the list of expanders. Alternatively, you can + set the variable Additional Abbrev Expanders to contain the + string of characters. (This is particularly useful in an init or + EVARS file.) If you wish to completely replace the set of + characters that cause expansion, set the variable WORDAB Ins + Chars in your init file. See section 22.6 [init], page 143, for + details on setting variables in init and EVARS files. + + + 25.2.2 Manipulating Definition Listsî 25.2.2 Manipulating Definition Listsî 25.2.2 Manipulating Definition Lists + + + One reason you might want to manipulate the definition lists is + to provide more structure to the definition environment than just + the mode vs. global structure provided normally, such as to group + together in a file those abbrevs pertaining to one topic. + + M-X Insert Word Abbrevs inserts into the buffer a list of + the current word abbrev definitions, in the format that M-X List + Word Abbrevs uses. M-X Insert Word Abbrevs$ inserts + some of the abbrevs' definitions; See section 25.2.3 [Many + Abbrevs], page 180, for details. + + M-X Define Word Abbrevs defines a set of word abbrevs from + a definition list in the buffer. There should be nothing else + besides the definition list in the buffer; or, if there is, you + must narrow the buffer to just the definition list. See + section 17 [Narrowing], page 93.î 180 EMACS Manual for ITS Users + + + 25.2.3 Dealing with Many Abbrevsî 25.2.3 Dealing with Many Abbrevsî 25.2.3 Dealing with Many Abbrevs + + + Some users build up a very large number of abbrevs. This + causes a couple of problems: First, defining all those abbrevs + when EMACS starts up can become too slow; this problem is + discussed in the next section. Second, the commands that deal + with the entire definition list become unwieldy. + + M-X List Word Abbrevs$ shows you the definitions of + just the abbrev definitions containing (in the abbrev, + in the mode, or in the expansion). The argument is actually a + TECO search string (See section 19.3 [TECO search strings], + page 101.). If you want to see the abbrevs which contain either + ^î or , separate the strings with a |O; to see + abbrev definitions containing either "defn" or "wab", do M-X List + ^î Word Abbrevs$defn|Owab. + + You can provide M-X List Word Abbrevs with an argument to + control whether the filtering string applies to just the abbrev + (C-U 1), just the expansion (C-U 2), just the mode (C-U 4), or + any combination (the sum). C-U 3 M-X List Word Abbrevs$lisp + will match "lisp" against abbrevs and expansions, but not modes. + + M-X Insert Word Abbrevs$ works similarly, but + inserts the list into the buffer instead of typing it out. + + + 25.2.4 Dumped EMACS Environmentsî 25.2.4 Dumped EMACS Environmentsî 25.2.4 Dumped EMACS Environments + + + M-X Write Word Abbrev File$ + Writes a file of all abbrev definitions, before + dumping. + + M-X Read Word Abbrev File$ + Reads file of abbrev definitions at init-time. + + M-X Write Incremental Word Abbrev File$ + Writes a file of abbrev definitions changed since + dumping. + + M-X Read Incremental Word Abbrev File$ + Reads file of changed abbrev definitions at + startup-time. + + + Some users with highly customized EMACS environments (their + init files take a long time to run) "dump out" theirî 181 EMACS Manual for ITS Users + + + + environments, in effect creating another EMACS-like program (the + "dump") which starts up much faster. (For instance, 1.7 cpu + seconds instead of 70.5 cpu seconds. See the file INFO;MKDUMP, + for details about a simple method of dumping environments. See + the file INFO;CONV, for details about more general environment + dumping.) Since the dumped environment contains word abbrev + definitions, a dumped environment with hundreds of abbrevs can + start just as quickly as if it had none. (But reading all these + abbrevs with M-X Read Word Abbrev File in the init file + originally took a long time.) For these users it is important, + at dump-startup time, to read in only those abbrevs which were + _____î changed or defined since the environment was dumped out. A file + which contains only these new abbrev's definitions is called an + ___________ ____ ______ ____î incremental word abbrev file. (It also can specify that certain + abbrevs are to be killed if they were defined when the + environment was dumped out, but subsequently killed.) + + The startup for the dump should use the Read Incremental Word + Abbrev File function instead of Read Word Abbrev File. It takes + the filename as a string argument, which defaults to INCABS >. + The command M-X Write Incremental Word Abbrev File$ + writes such a file, writing out those abbrevs more recent than + the dump (ones read by Read Incremental Word Abbrev File and ones + defined in the current editing session). + + Setting Save Word Abbrevs to -1 will cause an incremental + abbrev file to be automatically written, if necessary, when EMACS + is exited. + + When you want to dump out a new EMACS, first create a new, + complete word abbrev definition file using M-X Write Word Abbrev + ___î File. This file now has all abbrevs in it, and you can thus + delete any incremental definition files you have. Then start up + the new EMACS from scratch, using the init file, and dump it. + (The init file in general should call Read Word Abbrev File and + then also call Read Incremental Word Abbrev File, just in case + there are both kinds of files around. The startup calls only + Read Incremental Word Abbrev File.) Note that these functions + will return without error if their files don't exist, as a + convenience. + + + + 25.3 Teco Details for Extension Writersî 25.3 Teco Details for Extension Writersî 25.3 Teco Details for Extension Writers + + + This section documents some details that users programming + extensions may need to know, in order to interact properly with + Word Abbrev mode operation or to build upon it.î 182 EMACS Manual for ITS Users + + + + The variable WORDAB Setup Hook, if non-0, is executed when the + WORDAB library is loaded and sets itself up. (M-X Word Abbrev + Mode in the default EMACS environment auto-loads the WORDAB + library.) If there is no hook, the normal key connections (C-X + C-A, C-X U, etc.) are made; if there is a hook, it must do the + connections. + + The variable Word Abbrevs Modified is non-0 when abbrev + definitions have changed. This is used to signal the + abbrev-saving mechanism. + + The abbrev definers, such as C-X C-A (^R Add Mode Word Abbrev), + check to see if the volatile TECO mark, FS ^R Mark$, is set; if + it is, then the region between point and FS ^R Mark$ is used as + the expansion. The intention is to provide a mechanism for + simple but safe expansion marking. See section 22.5 [FS Flags], + page 142. + + Finally, the general way that Word Abbrev mode works is this: + at certain times, when characters are likely to have been + reconnected, a Word Abbrev mode subroutine looks at each of the + expander characters to see if they are running an expander or + have been reconnected. If they don't have expanders, they are + connected to an expander function (which first checks for + expansion and then calls the "old" function, what the character + was connected to before). The problem is that it is not really + possible to efficiently catch all the times that characters of + interest are reconnected. So, as a good guess, Word Abbrev mode + looks at these characters when the & Set Mode Line function is + called. This happens when major or minor modes change, when + buffer switching happens, and when Set Key is used. These are + the standard times that connections are changed. However, the + extension writer must be careful about reconnecting expander + characters. If an extension might do this, it should do 1FS Mode + Change$ to cause expansions to be redefined.î 183 EMACS Manual for ITS Users + + + CHAPTER TWENTY-SIXî CHAPTER TWENTY-SIXî CHAPTER TWENTY-SIX + THE PICTURE SUBSYSTEM, AN EDITOR FOR TEXT PICTURESî THE PICTURE SUBSYSTEM, AN EDITOR FOR TEXT PICTURESî THE PICTURE SUBSYSTEM, AN EDITOR FOR TEXT PICTURES + + + + If you want to create a picture made out of text characters + (for example, a picture of the division of a register into + fields, as a comment in a program), the PICTURE package can make + it easier. + + Do M-X Load Lib$PICTURE, and then M-X Edit Picture is + available. Do M-X Edit Picture with point and mark surrounding + the picture to be edited. Edit Picture enters a recursive + editing level (which you exit with C-M-C, as usual) in which + certain commands are redefined to make picture editing more + convenient. + + While you are inside Edit Picture, all the lines of the picture + are padded out to the margin with spaces. This makes + two-dimensional motion very convenient; C-B and C-F move + horizontally, and C-N and C-P move vertically without the + inaccuracy of a ragged right margin. When you exit from Edit + Picture, spaces at the ends of lines are removed. Nothing stops + you from moving outside the bounds of the picture, but if you + make any changes there slightly random things may happen. + + Edit Picture makes alteration of the picture convenient by + redefining the way printing characters and Rubout work. Printing + characters are defined to replace (overwrite) rather than + inserting themselves. Rubout is defined to undo a printing + character: it replaces the previous character with a space, and + moves back to it. + + Return is defined to move to the beginning of the next line. + This makes it usable for moving to the next apparently blank (but + actually filled with nothing but spaces) line, just as you use + Return normally with lines that are really empty. C-O creates + new blank lines after point, but they are created full of spaces. + + Tab is redefined to indent (by moving over spaces, not + inserting them) to under the first non-space on the previous + line. Linefeed is as usual equivalent to Return followed by Tab. + + Four movement-control commands exist to aid in drawing vertical + or horizontal lines: If you give the command M-X Up Picture + Movement, each character you type thereafter will cause the + cursor to move up instead of to the right. Thus if you want to + draw a line of dashes up to some point, you can give the command + Up Picture Movement, type enough dashes to make the line, andî 184 EMACS Manual for ITS Users + + + + then give the command Right Picture Movement to put things back + to normal. Similarly, there are functions to cause downward and + leftward movement: Down Picture Movement and Left Picture + Movement. These commands remain in effect only until you exit + the Edit Picture function, (One final note: you can use these + cursor movement commands outside of Edit Picture too, even when + not in Overwrite mode. You have to be somewhat careful though.) + + Possible future extensions include alteration of the kill and + un-kill commands to replace instead of deleting and inserting, + and to handle rectangles if two corners are specified using point + and the mark. + + The DRAW library is a user-contributed library containing other + commands useful for editing pictures.î 185 EMACS Manual for ITS Users + + + CHAPTER TWENTY-SEVENî CHAPTER TWENTY-SEVENî CHAPTER TWENTY-SEVEN + SORTING FUNCTIONSî SORTING FUNCTIONSî SORTING FUNCTIONS + + + + The SORT library contains functions called Sort Lines, Sort + Paragraphs and Sort Pages, to sort the region alphabetically line + by line, paragraph by paragraph or page by page. For example, + Sort Lines rearranges the lines in the region so that they are in + alphabetical order. + + Paragraphs are defined in the same way as for the + paragraph-motion functions (See section 11.2 [Paragraphs], + page 52.) and pages are defined as for the page motion commands + (See section 18 [Pages], page 94.). All of these functions can + be undone by the Undo command (See section 24.3 [Undo], + page 163.). A numeric argument tells them to sort into reverse + alphabetical order. + + You can rearrange pages to any way you like using the functions + Make Page Permutation Table and Permute Pages From Table. Make + Page Permutation Table starts you editing a table containing the + first line of each page. This table is kept in a buffer named + *Permutation Table*. You specify the new ordering for the pages + by rearranging the first lines into the desired order. You can + also omit or duplicate pages by omitting or duplicating the + lines. + + When you are finished rearranging the lines, use Permute Pages + From Table to rearrange the entire original file the same way. + Reselect the original buffer first. The permuted version is + constructed in a buffer named *Permuted File*. The original + buffer is not changed. You can use Insert Buffer to copy the + data into the original buffer.î 186 EMACS Manual for ITS Users + + + + APPENDIX Iî APPENDIX Iî APPENDIX I + PARTICULAR TYPES OF TERMINALSî PARTICULAR TYPES OF TERMINALSî PARTICULAR TYPES OF TERMINALS + + + + I.1 Ideal Keyboardsî I.1 Ideal Keyboardsî I.1 Ideal Keyboards + + + An ideal EMACS keyboard can be recognized because it has a + Control key and a Meta key on each side, with another key labeled + Top above them. + + On an ideal keyboard, to type any character in the 9-bit + character set, hold down Control or Meta as appropriate while + typing the key for the rest of the character. To type C-M-K, + type K while holding down Control and Meta. + + You will notice that there is a key labeled "Escape" and a key + labeled "Alt". The Altmode character is the one labeled "Alt". + "Escape" has other functions entirely; it is handled by ITS and + has nothing to do with EMACS. While we are talking about keys + handled by ITS, on Meta keyboards the way to interrupt a program + is CALL, rather than Control-Z, and entering communicate mode + ^î uses the BACK-NEXT key rather than Control-_. CALL echoes as |Z, + but if you type C-Z it is just an ordinary character which + happens to be an EMACS command to return to the superior. + ^ ^î Similarly, BACK-NEXT echoes as |_ but if you type |_ it is just + an EMACS command which happens not to be defined. + + The key labeled "Top" is an extra shift key. It is used to + produce the peculiar "SAIL" graphics characters which appear on + the same keys as the letters. The "Shift" key gets you + upper-case letters, but "Top" gets you the SAIL characters. As + EMACS commands, these characters are normally self-inserting, + like all printing characters. But once inserted, SAIL characters + are really the same as ASCII control characters, and since + characters in files are just 7 bits there is no way to tell them + apart. EMACS can display them either as ASCII control + characters, using an uparrow or caret to indicate them, or it can + display them as SAIL characters, whichever you like. The command + Control-Alpha (SAIL Character Mode) toggles the choice. Alpha is + a SAIL character and you can only type it on a terminal with a + Top key, but only those terminals can display the SAIL characters + anyway. SAIL characters are displayed if the variable SAIL + Character Mode is nonzero. + + One other thing you can do with the Top key is type the Help + character, which is Top-H on these keyboards. BACK-NEXT H also + works, though.î 187 EMACS Manual for ITS Users + + + + For inserting an Altmode, on an ideal keyboard you can type + C-M-Altmode. C-Altmode is a synonym for C-M-C (^R Exit). + + The "bit prefix" characters that you must use on other + terminals are also available on terminals with Meta keys, in case + you find them more convenient or get into habits on those other + terminals. + + To type numeric arguments on these keyboards, type the digits + or minus sign while holding down either Control or Meta. + + + + I.2 Keyboards with an "Edit" keyî I.2 Keyboards with an "Edit" keyî I.2 Keyboards with an "Edit" key + + + Keyboards with Edit keys probably belong to Datamedia or + Teleray terminals. The Edit and Control keys are a pair of shift + keys. Use the Control key to type Control characters and the + Edit key to type Meta characters. Thus, the 9-bit EMACS + character C-M-Q is typed by striking the "Q" key while holding + down "Edit" and "Control". + + While the Edit key is a true independent bit which can be + combined with anything else you can type, the Control key really + means "ASCII control". Thus, the only Control characters you can + type are those which exist in ASCII. This includes C-A through + C-Y, C-], C-@, C-\, and C-^. C-Z and C-_ can be typed on the + terminal but they are intercepted by the operating system and + therefore unavailable as EMACS commands. C-[ is not available + because its spot in ASCII is pre-empted by Altmode. The + corresponding Control-Meta commands are also hard to type. If + you can't type C-; directly, then you also can't type C-M-; + directly. + + Though you can't type C-; directly, you can use the bit prefix + character C-^ and type C-^ ;. Similarly, while you can't type + C-M-;, you can use the Control-Meta prefix C-C and type C-C ;. + Because C-^ is itself awkward, we have designed the EMACS command + set so that the hard-to-type Control (non-Meta) characters are + rarely needed. + + In order to type the Help character you must actually type two + characters, C-_ and H. C-_ is an escape character for ITS + itself, and C-_ followed by H causes ITS to give the Help + character as input to EMACS. + + To type numeric arguments, it is best to type the digits or + minus sign while holding down the Edit key.î 188 EMACS Manual for ITS Users + + + I.3 ASCII Keyboardsî I.3 ASCII Keyboardsî I.3 ASCII Keyboards + + + An ASCII keyboard allows you to type in one keystroke only the + command characters with equivalents in ASCII. No Meta characters + are possible, and not all Control characters are possible either. + The Control characters which you can type directly are + C-A through C-Y, C-], C-@, C-\, and C-^. C-Z and C-_ can be + typed on the terminal but they are intercepted by the operating + system and therefore unavailable as EMACS commands. C-[ is not + available because its spot in ASCII is pre-empted by Altmode. + + Those characters which you can't type directly can be typed as + two character sequences using the bit prefix characters Altmode, + C-C and C-^. Altmode turns on the Meta bit of the character that + follows it. Thus, M-A can be typed as Altmode A, and C-M-A as + Altmode C-A. Altmode can be used to get almost all of the + characters that can't be typed directly. C-C can be used to type + any Control-Meta character, including a few that Altmode can't be + used for because the corresponding non-Meta character isn't on + the keyboard. Thus, while you can't type C-M-; as Altmode + Control-;, since there is no Control-; in ASCII, you can type + C-M-; as C-C ;. The Control (non-Meta) characters which can't be + typed directly require the use of C-^, as in C-^ < to get the + effect of C-<. Because C-^ by itself is hard to type, the EMACS + command set is arranged so that most of these non-ASCII Control + characters are not very important. Usually they have synonyms + which are easier to type. In fact, in this manual only the + easier-to-type forms are usually mentioned. + + In order to type the Help character you must actually type two + characters, C-_ and H. C-_ is an escape character for ITS + itself, and C-_ followed by H causes ITS to give the Help + character as input to EMACS. + + On ASCII keyboards, you can type a numeric argument by typing + an Altmode followed by the minus sign and/or digits. Then comes + the command for which the argument is intended. For example, + type Altmode 5 C-N to move down five lines. If the command is a + Meta command, it must have an Altmode of its own, as in Altmode 5 + Altmode F to move forward five words. + + Note to customizers: this effect requires redefining the + Meta-digit commands, since the Altmode and the first digit amount + to a Meta-digit character. The new definition is ^R Autoarg, and + the redefinition is done by the default init file. + + If you use numeric arguments very often, and you dislike having + to start one with an Altmode, you might enjoy using Autoarg mode,î 189 EMACS Manual for ITS Users + + + + in which you can specify a numeric argument by just typing the + digits. See section 4 [Arguments], page 19, for details. + + + + I.4 Upper-case-only Terminalsî I.4 Upper-case-only Terminalsî I.4 Upper-case-only Terminals + + + On terminals lacking the ability to display or enter lower case + characters, a special input and output case-flagging convention + has been defined for editing files which contain lower case + characters. + + The customary escape convention is that a slash prefixes any + upper case letter; all unprefixed letters are lower case (but see + below for the "lower case punctuation characters"). This + convention is chosen because lower case is usually more frequent + in files containing any lower case at all. Upper case letters + are displayed with a slash ("/") in front. Typing a slash + followed by a letter is a good way to insert an upper case + letter. Typing a letter without a slash inserts a lower case + letter. For the most part, the buffer will appear as if the + slashes had simply been inserted (type /A and it inserts an upper + case A, which displays as /A), but cursor-motion commands will + reveal that the slash and the A are really just one character. + Another way to insert an upper-case letter is to quote it with + C-Q. + + Note that this escape convention applies only to display of the + buffer and insertion in the buffer. It does not apply to + arguments of commands (it is hardly ever useful for them, since + case is ignored in command names and most commands' arguments). + Case conversion is performed when you type commands into the + minibuffer, but not when the commands are actually executed. + + The ASCII character set includes several punctuation characters + whose codes fall in the lower case range and which cannot be + typed or displayed on terminals that cannot handle lower case + letters. These are the curly braces ("{" and "}"), the vertical + bar ("|"), the tilde ("~"), and the accent grave ("`"). Their + upper case equivalents are, respectively, the square brackets + ("[" and "]"), the backslash ("\"), the caret ("^"), and the + atsign ("@"). For these punctuation characters, EMACS uses the + opposite convention of that used for letters: the ordinary, upper + case punctuations display as and are entered as themselves, while + the lower case forms are prefixed by slashes. This is because + the "lower case" punctuations are much less frequently used. So, + to insert an accent grave, type "/@".î 190 EMACS Manual for ITS Users + + + + When the slash escape convention is in effect, a slash is + displayed and entered as two slashes. + + This slash-escape convention is not normally in effect. To + turn it on, the TECO command -1$ (minus one dollar sign, not + Altmode!) must be executed. The easiest way to do this is to use + the minibuffer: Altmode Altmode -1$ Altmode Altmode. To turn + off the escape convention (for editing a file of all upper case), + the command is 0$ (zero dollar sign), or Altmode Altmode 0$ + Altmode Altmode. If you use such a bad terminal frequently, you + can define yourself an EMACS extension, a command to turn + slash-escape on and off. + + The lower case editing feature is actually more flexible than + described here. Refer to the TECO commands F$ (dollar sign) and + FS CASE$, using M-X TECDOC, for full details. See section 22.5 + [FS Flags], page 142. + + + + I.5 The SLOWLY Package for Slow Terminalsî I.5 The SLOWLY Package for Slow Terminalsî I.5 The SLOWLY Package for Slow Terminals + + + The SLOWLY library is intended as an aid for people using + display terminals at slow speeds. It provides means of limiting + redisplay to smaller parts of the screen, and for turning off + redisplay for a time while you edit. + + To use SLOWLY, do M-X Load Library$SLOWLY, and if your + terminal is a display operating at 1200 baud or less (or if its + speed is unknown) SLOWLY will set up the commands described here. + + Comments, bugs, and suggestions via Arpanet mail to RWK@MIT-MC, + or by US mail or phone to the author of this manual. + + + I.5.1. Brief Descriptionî I.5.1. Brief Descriptionî I.5.1. Brief Description + + + SLOWLY provides an alternate version of the incremental + searching commands on C-S and C-R, ^R Edit Quietly on C-X Q, a + way to shrink the screen at either the top or the bottom on M-O, + and more flexibility in where minibuffers get displayed. If + SLOWLY is loaded, it redefines these commands only if the + terminal speed is 1200 baud or less.î 191 EMACS Manual for ITS Users + + + I.5.2. SLOWLY Commandsî I.5.2. SLOWLY Commandsî I.5.2. SLOWLY Commands + + + The commands provided are: + + + M-O (^R Set Screen Size) + This function reduces the amount of the screen + used for displaying your text, down to a few + lines at the top or the bottom. If called + without an argument, it will use the same size as + last time (or 3 if it hasn't been called before). + If given a positive argument, that is taken to be + the number of lines to use at the top of the + screen. If given a negative argument, it is + taken to be the number of lines at the bottom of + the screen. If given an argument of 0, it + returns to the use of the entire screen. The + section of the screen that is in use is + (defaultly) delimited by a line of 6 dashes. + This command sets the variable Short Display + Size. + + C-S (^R Slow Display I-Search) + This function is just like the usual incremental + search, except if the search would run off the + screen and cause a redisplay, it narrows the + screen to use only a few lines at the top or + bottom of the screen to do the redisplay in. + When the search is exited, use of the full screen + resumes. The size of the window used for the + search is the value of the variable Slow Search + Lines. If it is positive, it is the number of + lines at top of screen; if negative, it is the + number of lines at bottom of screen. The default + is 1. The variable Slow Search Separator + contains the string used to show the end of the + search window. By default it is six dashes. See + section 10 [Search], page 46. + + C-R (^R Slow Reverse Display I-Search) + This searches in backwards in the style of ^R + Slow Display I-Search. + + C-X Q (^R Edit Quietly) + This function enters a recursive editing level + with redisplay inhibited. This means that your + commands are carried out but the screen does not + change. C-L with no argument redisplays. So youî 192 EMACS Manual for ITS Users + + + + can update the screen when you want to. Two + C-L's in a row clear the screen and redisplay. + C-L with an argument repositions the window, as + usual (See section 15 [C-L], page 87.). To exit + and resume continuous redisplay, use C-M-C. + + + I.5.3. Minibuffersî I.5.3. Minibuffersî I.5.3. Minibuffers + + + SLOWLY provides control over how minibuffers display on your + screen. The variable Minibuffer Size specifies how many lines it + takes up. If this is made negative, the minibuffer will appear + at the bottom of the screen instead of the top. Thus one mode of + operation which some people like is to use ^R Set Screen Size to + set up to not use the bottom 3 lines of the screen, and set + Minibuffer Size to -3. This will permanently reserve 3 lines at + the bottom of the screen for the minibuffer. See section 23 + [Minibuffer], page 156. + + The variable Minibuffer Separator holds the string used to + separate the minibuffer area from the rest of the screen. By + default, this is six dashes. + + SLOWLY installs its minibuffer by defining the variable MM & + Minibuffer. + + + I.5.4. SLOWLY Optionsî I.5.4. SLOWLY Optionsî I.5.4. SLOWLY Options + + + The simplest way to run SLOWLY is to simply load it, and use + the default key assignments, etc. SLOWLY sets up those key + assignments only if your terminal is no faster than 1200 baud. + + If you want SLOWLY to not set up these things unless your + terminal is running at 300 baud or slower (ugh!), set the + variable SLOWLY Maximum Speed to the highest speed at which + SLOWLY is desired. Put the following in your EMACS init file: + + + 300 M.VSLOWLY Maximum Speed$ + + + If you don't like the command assignments set up by SLOWLY, you + can override them by defining the variable SLOWLY Setup Hook + before loading SLOWLY. The value should be TECO commands to + define the command assignments you wish.î 193 EMACS Manual for ITS Users + + + + SLOWLY normally uses lines of six dashes to separate areas of + the screen. You can tell it to use something else instead. + Minibuffers use the value of Minibuffer Separator, searches use + the value of Slow Search Separator. If one of these is + unspecified (the variable does not exist), the value of Default + Separator is used. The separator for small screen mode is always + the value of Default Separator. If the value specified is the + null string, a blank line is used. If the value specified is + zero, nothing (not even a blank line) is used. This is useful + for searches, since you aren't going to be doing any editing in + the search window. + + Even though SLOWLY does not redefine the commands on a fast + terminal, you might wish to load it only on slow terminals to + save address space the rest of the time. This can be done in an + init file with + + + fsospeed$-1200:"g m(m.mLoad Library$)SLOWLY$'î 194 EMACS Manual for ITS Users + + + APPENDIX IIî APPENDIX IIî APPENDIX II + USE OF EMACS FROM PRINTING TERMINALSî USE OF EMACS FROM PRINTING TERMINALSî USE OF EMACS FROM PRINTING TERMINALS + + + + While EMACS was designed to be used from a display terminal, + you can use it effectively from a printing terminal. You cannot, + however, learn EMACS using one. + + All EMACS commands have the same editing effect from a printing + terminal as they do from a display. All that is different is how + they try to show what they have done. EMACS attempts to make the + same commands that you would use on a display terminal act like + an interactive line-editor. It does not do as good a job as + editors designed originally for that purpose, but it succeeds + well enough to keep you informed of what your commands are + accomplishing, provided you know what they are supposed to do and + know how they would look on a display. + + The usual buffer display convention for EMACS on a printing + terminal is that the part of the current line before the cursor + is printed out, with the cursor following (at the right position + in the line). What follows the cursor on the line is not + immediately visible, but normally you will have a printout of the + original contents of the line a little ways back up the paper. + For example, if the current line contains the word "FOOBAR", and + the cursor is after the "FOO", just "FOO" would appear on the + paper, with the cursor following it. Typing the C-F command to + move over the "B" would cause "B" to be printed, so that you + would now see "FOOB" with the cursor following it. All + forward-motion commands that move reasonably short distances + print out what they move over. + + Backward motion is handled in a complicated way. As you move + back, the terminal backspaces to the correct place. When you + stop moving back and do something else, a linefeed is printed + first thing so that the printing done to reflect subsequent + commands does not overwrite the text you moved back over and + become garbled by it. The Rubout command acts like backward + motion, but also prints a slash over the character rubbed out. + Other backwards deletion commands act like backward motion; they + do not print slashes (it would be an improvement if they did). + + One command is different on a printing terminal: C-L, which + normally means "clear the screen and redisplay". With no + argument, it retypes the entire current line. An argument tells + it to retype the specified number of lines around the current + line.î 195 EMACS Manual for ITS Users + + + + On printing terminals, C-S (^R Incremental Search) does not + print out the context automatically. To see what you have found + at any stage, type C-L. This types out the current line but does + not exit the search. All the normal facilities of incremental + searching are available for finding something else if you had not + found the right place initially. + + Unfortunately, EMACS cannot perfectly attain its goal of making + the text printed on the current line reflect the current line in + the buffer, and keeping the horizontal position of the cursor + correct. One reason is that it is necessary for complicated + commands to echo, but echoing them screws up the "display". The + only solution is to type a C-L whenever you have trouble + following things in your mind. The need to keep a mental model + of the text being edited is, of course, the fundamental defect of + all printing terminal editors. + + Note: it is possible to make a specific command print on a + printing terminal in whatever way is desired, if that is worth + while. For example, Linefeed knows explicitly how to display + itself, since the general TECO redisplay mechanism isn't able to + handle it. Suggestions for how individual commands can display + themselves are welcome, as long as they are algorithmic rather + than simply of the form "please do the right thing".î 196 EMACS Manual for ITS Users + + + + GLOSSARYî GLOSSARYî GLOSSARY + + + + Aborting Aborting a recursive editing level (q.v.) means + canceling the command which invoked the recursive + editing. For example, if you abort editing a + message to be sent, the message is not sent. + Aborting is done with the command C-]. See + section 24.1 [Aborting], page 159. + + Altmode Altmode is a character, labelled Escape on some + keyboards. It is the bit prefix character (q.v.) + used to enter Meta-characters when the keyboard + does not have a Meta (q.v.) key. See section 2 + [Characters], page 10. Also, it delimits string + arguments to extended commands. See section 5 + [Extended Commands], page 21. + + Balance Parentheses + EMACS can balance parentheses manually or + automatically. You can ask to move from one + parenthesis to the matching one. See + section 20.6.1 [Lists], page 111. When you + insert a close parenthesis, EMACS can show the + matching open. See section 20.4 [Matching], + page 105. + + Bit Prefix Character + A bit prefix character is a command which + combines with the next character typed to make + one character. They are used for effectively + typing commands which the keyboard being used is + not able to send. For example, to use a + Meta-character when there is no Meta key on the + keyboard, the bit prefix character Altmode (q.v.) + is needed. See section 2 [Characters], page 10. + + Buffer The buffer is the basic editing unit; one buffer + corresponds to one piece of text being edited. + You can have several buffers, but at any time you + are editing only one, the "selected" buffer, + though two can be visible when you are using two + windows. See section 14 [Buffers], page 83. + + C- C is an abbreviation for Control, in the name of + a character. See section 2 [Characters], + page 10.î 197 EMACS Manual for ITS Users + + + + C-M- C-M- is an abbreviation for Control-Meta, in the + name of a character. See section 2 [Characters], + page 10. + + Comment A comment is text in a program which is intended + only for humans reading the program, and is + marked specially so that the compiler will ignore + it. EMACS offers special commands for creating + and killing comments. See section 20.5 + [Comments], page 107. + + Command A command is a character or sequence of + characters which, when typed by the user, fully + specifies one action to be performed by EMACS. + For example, "X" and "Control-F" and "Meta-X Text + Mode" are commands. See section 2 + [Characters], page 10. Sometimes the first + character of a multi-character command is also + considered a command: M-X Text Mode is a + command (an extended command), and M-X is also a + command (a command to read a function name and + invoke the function). See section 5 [Extended + Commands], page 21. + + Completion Completion is what EMACS does when it + automatically fills out the beginning of an + extended command name into the full name, or as + much of it as can be deduced for certain. + Completion occurs when Altmode, Space or Return + is typed. See section 5 [Extended Commands], + page 21. + + Connected A character command in EMACS works by calling a + function which it is "connected" to. + Customization often involves connecting a + character to a different function. See "Dispatch + table". See section 2 [Characters], page 10. + + Continuation Line + When a line of text is longer than the width of + the screen, it is displayed on more than one line + of screen. We say that the line is continued, + and that all screen lines used but the first are + called continuation lines. See section 3 [Basic + Editing], page 15. + + Control Control is the name of a bit which each command + character does or does not contain. A + character's name includes the word Control if theî 198 EMACS Manual for ITS Users + + + + Control bit is part of that character. Ideally, + this means that the character is typed using the + Control key: Control-A is typed by typing "A" + while holding down Control. On most keyboards + the Control key works in only some cases; the + rest of the time, a bit prefix character (q.v.) + must be used. See section 2 [Characters], + page 10. + + Control-Character + A Control character is a character which includes + the Control bit. + + Control-X Command + A Control-X command is a two-character command + whose first character is the prefix character + Control-X. See section 2 [Characters], page 10. + + stands for the carriage return character, in + contexts where the word "Return" might be + confusing. See section 2 [Characters], page 10. + + CRLF CRLF stands for the sequence of two characters, + carriage return followed by linefeed, which is + used to separate lines in files and in text being + edited in EMACS. See section 2 [Characters], + page 10. + + Cursor The cursor is the object on the screen which + indicates the position called point (q.v.) at + which insertion and deletion takes place. The + cursor is part of the terminal, and often blinks + or underlines the character where it is located. + See section 1 [Screen], page 5. + + Customization Customization is making minor changes in the way + EMACS works. It is often done by setting + variables (See section 22.3 [Variables], + page 137.) or by reconnecting commands (See + section 5.2 [Functions], page 24.). + + Defun A defun is a list at the top level of list + structure in a Lisp program. It is so named + because most such lists are calls to the Lisp + function defun. See section 20.6.2 [Defuns], + page 114. + + Delete This is the label used on some keyboards for the + Rubout character.î 199 EMACS Manual for ITS Users + + + + Deletion Deletion means erasing text without saving it. + EMACS deletes text only when it is expected not + to be worth saving (all whitespace, or only one + character). The alternative is killing (q.v.). + See section 9.1 [Killing], page 39. + + Dispatch Table The dispatch table is what records the + connections (q.v.) from command characters to + functions. Think of a telephone switchboard + connecting incoming lines (commands) to + telephones (functions). A standard EMACS has one + set of connections; a customized EMACS may have + different connections. See section 5.2 + [Functions], page 24. + + Echo Area The echo area is the bottom three lines of the + screen, used for echoing the arguments to + commands, for asking questions, and printing + brief messages. See section 1 [Screen], page 5. + + Echoing Echoing is acknowledging the receipt of commands + by displaying them (in the echo area). Most + programs other than EMACS echo all their + commands. EMACS never echoes single-character + commands; longer commands echo only if you pause + while typing them. + + Error Messages Error messages are single lines of output printed + by EMACS when the user or a TECO program asks for + something impossible. They appear at the top of + the screen and end with a question mark. + + Escape Escape is the label used on some keyboards for + the Altmode character. + + Exiting Exiting EMACS means returning to EMACS's + superior, normally HACTRN. See section 6.4 + [Exiting], page 31. Exiting a recursive editing + level (q.v.) means allowing the command which + invoked the recursive editing to complete + normally. For example, if you are editing a + message to be sent, and you exit, the message is + sent. + + Extended Command + An extended command is a command which consists + of the character Meta-X followed by the command + name (really, the name of a function (q.v.)). An + extended command requires several characters ofî 200 EMACS Manual for ITS Users + + + + input, but its name is made up of English words, + so it is easy to remember. See section 5 + [Extended Commands], page 21. + + Extension Extension means making changes to EMACS which go + beyond the bounds of mere customization. If + customization is moving the furniture around in a + room, extension is building new furniture. See + the file INFO;CONV. + + Filling Filling text means moving text from line to line + so that all the lines are approximately the same + length. See section 11.4 [Filling], page 56. + + Function A function is a named subroutine of EMACS. When + you type a command, EMACS executes a function + which corresponds to the command, and the + function does the work. Character commands are + connected to functions through the dispatch table + (q.v.). Extended commands contain the name of + the function to be called; this allows you to + call any function. See section 5 [Extended + Commands], page 21. + + Global The global value of a variable or of a command + character definition applies to all buffers and + all files (except those which have their own + local values of the variable or definition). See + section 22.3 [Variables], page 137. + + Grinding Grinding means reformatting a program so that it + is indented according to its structure. See + section 20.7 [Grinding], page 115. + + Help You can type the Help character at any time to + ask what options you have, or to ask what any + command does. See section 7 [Help], page 33. + + Home Directory Your home directory is the one on which your mail + and your init files are stored. + + INFO INFO is the subsystem for perusing + tree-structured documentation files. The + documentation in INFO includes a version of the + EMACS manual. + + ITS ITS is the Incompatible Timesharing System + written at the MIT Artificial Intelligence Lab. + EMACS was first developed on this system. Justî 201 EMACS Manual for ITS Users + + + + what it is incompatible with has changed from + year to year. + + Kill Ring The kill ring is where killed text is saved. It + holds the last nine or so blocks of killed text. + It is called a ring because you can bring any of + the saved blocks to the front by rotating the + ring. See section 9.2 [Un-Killing], page 41. + + Killing Killing means erasing text and saving it inside + EMACS to be recovered later if desired. Most + EMACS commands to erase text do killing, as + opposed to deletion (q.v.). See section 9.1 + [Killing], page 39. + + List A list is, approximately, a text string beginning + with an open parenthesis and ending with the + matching close parenthesis. See section 20.6.1 + [Lists], page 111. Actually there are a few + complications to the syntax, which is controlled + by the syntax table (See section 22.4 [Syntax], + page 139.). + + Local A local value of a variable or of a command + character definition applies to only one buffer + or file. See section 22.7 [Locals], page 150. + + Local Modes List + A local modes list appears in a file to specify + local values for variables or command character + definitions, to be in effect while visiting that + file. + + M- M- in the name of a character is an abbreviation + for Meta. + + M-X M-X is the character which begins an extended + command (q.v.). Extended commands have come to + be known also as "M-X commands", and an + individual extended command is often referred to + as "M-X such-and such". See section 5 [M-X], + page 21. + + Major Mode The major modes are a mutually exclusive set of + options which configure EMACS for editing a + certain sort of text. Ideally, each programming + language has its own major mode. See + section 20.1 [Major Modes], page 102.î 202 EMACS Manual for ITS Users + + + + Mark The mark points, invisibly, to a position in the + text. Many commands operate on the text between + point and the mark (known as the region, q.v.). + See section 8 [Mark], page 36. + + Meta Meta refers to the Meta key. A character's name + includes the word Meta if the Meta key must be + held down in order to type the character. If + there is no Meta key, then the Altmode character + is used as a prefix instead. See section 2 + [Characters], page 10. + + Meta Character A Meta character is one whose character code + includes the Meta bit. These characters can be + typed only by means of a Meta key or by means of + the metizer command (q.v.). + + Metizer The metizer is another term for the bit prefix + character for the Meta bit; namely, Altmode + (q.v.). + + Minibuffer The minibuffer is a facility for editing and then + executing a TECO program. See section 23 + [Minibuffer], page 156. + + Minor mode A minor mode is an optional feature of EMACS + which can be switched on or off independently of + all other features. Each minor mode is both the + name of an option (q.v.) and the name of an + extended command to set the option. See + section 22.1 [Minor Modes], page 133. + + MM-command This is an obsolete synonym for "extended + command". + + Mode line The mode line is a line just above the echo area + (q.v.), used for status information. See + section 1.1 [Mode Line], page 6. + + Narrowing Narrowing means limiting editing to only a part + of the text in the buffer. Text outside that + part is inaccessible to the user until the + boundaries are widened again, but it is still + there, and saving the file saves it all. See + section 17 [Narrowing], page 93. + + Node The node is the unit of structure of INFO (q.v.) + files. When referring to documentation contained + only in INFO files, we sometimes refer to a nodeî 203 EMACS Manual for ITS Users + + + + of a specific name, in a specific file, as in + "See the file INFO;CONV, node Hooks". + + Numeric Argument + A numeric argument is a number specified before a + command to change the effect of the command. + Often the numeric argument serves as a repeat + count. See section 4 [Numeric Arguments], + page 19. + + Option An option is a variable which exists to be set by + the user to change the behavior of EMACS + commands. This is an important method of + customization. See section 22.3 [Variables], + page 137. + + Parse We say that EMACS parses words or expressions in + the text being edited. Really, all it knows how + to do is find the other end of a word or + expression. See section 22.4 [Syntax], page 139. + + Point Point is the place in the buffer at which + insertion and deletion occur. Point is + considered to be between two characters, not at + one character. The terminal's cursor (q.v.) + indicates the location of point. See section 3 + [Basic], page 15. + + Prefix Character + A prefix character is a command whose sole + function is to introduce a set of multi-character + commands. Control-X (q.v.) is a prefix + character. The bit prefix characters (q.v.) are + other examples. + + Prompt A prompt is text printed in the echo area to ask + the user for input. Printing a prompt is called + "prompting". EMACS can prompt when a command + requires an argument, or when only part of a + command has been typed. However, the prompt will + not appear unless you pause in your typing. See + section 5 [Extended Commands], page 21. + + Q-Registers Q-registers are internal TECO variables which can + be used by EMACS or by the user to store text or + numbers. See section 9.3.2 [Q-Registers], + page 45. + + Quitting Quitting means interrupting a command which isî 204 EMACS Manual for ITS Users + + + + partially typed in or already executing. It is + done with Control-G. See section 24.1 + [Quitting], page 159. + + Quoting Quoting means depriving a character of its usual + special significance. It is usually done with + Control-Q. What constitutes special significance + depends on the context and on convention. For + example, an "ordinary" character as an EMACS + command inserts itself; so you can insert any + other character, such as Rubout, by quoting it as + in Control-Q Rubout. Not all contexts allow + quoting. See section 3 [Basic Editing], page 15. + + Recursive Editing Level + A recursive editing level is a state in which + part of the execution of a command involves + asking the user to edit some text. This text may + or may not be the same as the text to which the + command was applied. The mode line indicates + recursive editing levels with square brackets + ("[" and "]"). See section 6.3 [Recursive + Editing Level], page 30. + + Redisplay Redisplay is the process of correcting the image + on the screen to correspond to changes that have + been made in the text being edited. See + section 1 [Screen], page 5. + + Region The region is the text between point (q.v.) and + the mark (q.v.). The terminal's cursor indicates + the location of point, but the mark is invisible. + Many commands operate on the text of the region. + See section 8 [Mark], page 36. + + Return Return is the carriage return character, used as + input to EMACS. Return is used as a command in + itself to insert a line separator. It also + terminates arguments for most commands. See + section 2 [Characters], page 10. + + Rubout Rubout is a character, sometimes labelled + "Delete". It is used as a command to delete one + character of text. It also deletes one character + when an EMACS command is reading an argument. + + S-expression An s-expression is the basic syntactic unit of + Lisp: either a list, or a symbol containing no + parentheses (actually, there are a few exceptionsî 205 EMACS Manual for ITS Users + + + + to the rule, based on the syntax of Lisp). See + section 20.6.1 [Lists], page 111. + + Selecting Selecting a buffer (q.v.) means making editing + commands apply to that buffer as opposed to any + other. At all times one buffer is selected and + editing takes place in that buffer. See + section 14 [Buffers], page 83. + + Self-documentation + Self-documentation is the feature of EMACS which + can tell you what any command does, or give you a + list of all commands related to a topic you + specify. You ask for self-documentation with the + Help character. See section 7 [Help], page 33. + + String Argument + A string argument is an argument which follows + the command name in an extended command. In "M-X + Apropos$word", "Word" is a string argument to + the Apropos command. See section 5 [Extended + Commands], page 21. + + Subsystem A subsystem of EMACS is an EMACS command which, + itself, reads commands and displays the results. + Examples are INFO, which is for perusing + documentation; DIRED, which is for editing + directories; RMAIL and BABYL, which are for + reading and editing mail. The word "subsystem" + implies that it offers many independent commands + which can be used freely. If an EMACS function + asks specific questions, we do not call it a + subsystem. + + Usually the subsystem continues in operation + until a specific command to exit (usually "Q") is + typed. The commands for a subsystem do not + usually resemble ordinary EMACS commands, since + editing text is not their purpose. The Help + character should elicit the subsystem's + documentation. See section 6.1 [Subsystems], + page 28. + + Syntax Table The syntax table tells EMACS which characters are + part of a word, which characters balance each + other like parentheses, etc. See section 22.4 + [Syntax], page 139. + + Tailoring This is a synonym for customization (q.v.).î 206 EMACS Manual for ITS Users + + + + TECO Search String + A TECO search string is a sort of pattern used by + the TECO search command, and also by various + EMACS commands which use the TECO search command. + See section 19.3 [TECO search strings], page 101. + + Top Level Top level is the normal state of EMACS, in which + you are editing the text of the file you have + visited. You are at top level whenever you are + not in a recursive editing level or a subsystem + (q.v.). + + Twenex Twenex is the operating system which DEC likes to + call "TOPS-20". However, a person should not be + forced to call a system "tops" unless he really + thinks so. Come now, DEC, don't you think people + will praise your products voluntarily? The name + "Twenex" is also more appropriate because Twenex + was developed from the Tenex system, and has no + relationship to "TOPS-10". What's more, it's + very euphonious. + + Typeout Typeout is a message, printed by an EMACS + command, which overwrites the area normally used + for displaying the text being edited, but which + does not become part of the text. Typeout is + used for messages which might be too long to fit + in the echo area (q.v.). See section 1 [Screen], + page 5. + + Undo Undo is a command which undoes the effect on the + buffer of a previous command. Only some commands + are undoable and only the most recent undoable + command can be undone. See section 24.3 [Undo], + page 163. + + Un-killing Un-killing means reinserting text previously + killed. It can be used to undo a mistaken kill, + or for copying or moving text. See section 9.2 + [Un-killing], page 41. + + User Name Your user name is the name you use to log in. It + identifies you as opposed to all the other users. + It may be the same as your home directory's name. + + Variable A variable is a name with which EMACS associates + a value, which can be a number or a string. See + section 22.3 [Variables], page 137. Some + variables ("options") are intended to be used orî 207 EMACS Manual for ITS Users + + + + set by the user; others are for purely internal + purposes. + + Virtual Boundaries + The virtual boundaries delimit the accessible + part of the buffer, when narrowing (q.v.) is in + effect. See section 17 [Narrowing], page 93. + + Visiting Visiting a file means loading its contents into a + buffer (q.v.) where they can be edited. See + section 13.1 [Visiting], page 69. + + Wall Chart The wall chart is a very brief EMACS reference + sheet giving one line of information about each + short command. + + Whitespace Whitespace is any run of consecutive formatting + characters (space, tab, carriage return, + linefeed, and backspace). + + Widening Widening is the operation which undoes narrowing + (q.v.). See section 17 [Narrowing], page 93. + + Window A window is a region of the screen in which text + being edited is displayed. EMACS can divide the + screen into two windows. See section 16 + [Windows], page 90. "The window" also means the + position in the buffer which is at the top of the + screen. See section 15 [Display], page 87. + + Working Directory + This is the directory which you have told the + system you wish to operate on primarily at the + moment. This is usually the same as your home + directory (q.v.). It is specified with the DDT + command :CWD . + + Yanking This is a synonym for un-killing (q.v.). + + ^R The string "^R" is the beginning of many function + names. See section 5.2 [Functions], page 24. + + ^R Mode ^R mode is the real time editing mode of TECO. + EMACS always operates in this mode.î 208 EMACS Manual for ITS Users + + + + COMMAND SUMMARYî COMMAND SUMMARYî COMMAND SUMMARY + + + + This summary contains brief descriptions with cross references + for all commands, grouped by topic. Within each topic, they are + in alphabetical order. Our version of alphabetical order places + non-control non-meta characters first, then control characters, + then meta characters, then control-meta characters. Control-X + and Meta-X commands come last. Not all Meta-X commands are + included. + + + + Prefix Charactersî Prefix Charactersî Prefix Characters + + + Altmode (^R Prefix Meta) + Altmode is a bit prefix character which turns on + the Meta bit in the next character. Thus, + Altmode F is equivalent to the single character + Meta-F, which is useful if your keyboard has no + Meta key. See section 2 [Characters], page 10. + + Control-^ (^R Prefix Control) + Control-^ is a bit prefix character which turns + on the Control bit in the following character. + Thus, Control-^ < is equivalent to the single + character Control-<. See section 2 [Characters], + page 10. + + Control-C (^R Prefix Control-Meta) + Control-C is a bit prefix character which turns + on the Control bit and the Meta bit in the + following character. Thus, Control-C ; is + equivalent to the single character Control-Meta-; + . See section 2 [Characters], page 10. + + Control-Q (^R Quoted Insert) + Control-Q inserts the following character. This + is a way of inserting control characters. See + section 3 [Basic Editing], page 15. + + Control-U (^R Universal Argument) + Control-U is a prefix for numeric arguments which + works the same on all terminals. See section 4 + [Arguments], page 19. + + Control-X î 209 EMACS Manual for ITS Users + + + + Control-X is a prefix character which begins a + two-character command. Each combination of + Control-X and another character is a "Control-X + command". Individual Control-X commands appear + in this summary according to their uses. + + Meta-X (^R Extended Command) + Meta-X is a prefix character which introduces an + extended command name. See section 5 [Meta-X], + page 21. + + Control-Meta-X (^R Instant Extended Command) + Control-Meta-X is another way of invoking an + extended command. Instead of putting the + arguments in the same line as the command name, + the command reads the arguments itself. See + section 5 [Meta-X], page 21. + + Control-digits, Meta-digits, Control-Meta-digits + These all specify a numeric argument for the next + command. See section 4 [Arguments], page 19. + + Control-Minus, Meta-Minus, Control-Meta-Minus + These all begin a negative numeric argument for + the next command. See section 4 [Arguments], + page 19. + + + + Simple Cursor Motionî Simple Cursor Motionî Simple Cursor Motion + + + Control-A (^R Beginning of Line, built-in function) + Control-A moves to the beginning of the line. + See section 3 [Basic Editing], page 15. + + Control-B (^R Backward Character, built-in function) + Control-B moves backward one character. See + section 3 [Basic Editing], page 15. + + Control-E (^R End of Line, built-in function) + Control-E moves to the end of the line. See + section 3 [Basic Editing], page 15. + + Control-F (^R Forward Character, built-in function) + Control-F moves forward one character. See + section 3 [Basic Editing], page 15. + + Control-H (^R Backward Character, built-in function) î 210 EMACS Manual for ITS Users + + + + Control-H moves backward one character. See + section 3 [Basic Editing], page 15. + + Control-N (^R Down Real Line) + Control-N moves vertically straight down. See + section 3 [Basic Editing], page 15. + + Control-P (^R Up Real Line) + Control-P moves vertically straight up. See + section 3 [Basic Editing], page 15. + + Control-R (^R Reverse Search) + Control-R is like Control-S but searches + backward. See section 10 [Search], page 46. + + Control-S (^R Incremental Search) + Control-S searches for a string, terminated by + Altmode. It searches as you type. See + section 10 [Search], page 46. + + Meta-< (^R Goto Beginning) + Meta-< moves to the beginning of the buffer. See + section 3 [Basic Editing], page 15. + + Meta-> (^R Goto End) + Meta-> moves to the end of the buffer. See + section 3 [Basic Editing], page 15. + + Control-X Control-N (^R Set Goal Column) + Control-X Control-N sets a horizontal goal for + the Control-N and Control-P commands. When there + is a goal, those commands try to move to the goal + column instead of straight up or down. + + + + Linesî Linesî Lines + + + Return (^R CRLF) + Return inserts a line separator, or advances onto + a following blank line. See section 3 [Basic + Editing], page 15. + + Control-O (^R Open Line, built-in function) + Control-O inserts a line separator, but point + stays before it. See section 3 [Basic Editing], + page 15.î 211 EMACS Manual for ITS Users + + + + Meta-= (^R Count Lines Region) + Meta-= prints the number of lines between point + and mark. See section 8 [Mark], page 36. + + Control-X Control-O (^R Delete Blank Lines) + Control-X Control-O deletes all but one of the + blank lines around point. If the current line is + not blank, all blank lines following it are + deleted. See section 3 [Basic Editing], page 15. + + Control-X Control-T (^R Transpose Lines) + Control-X Control-T transposes the contents of + two lines. See section 12 [Fixing Typos], + page 65. + + + + Killing and Un-killingî Killing and Un-killingî Killing and Un-killing + + + Rubout (^R Backward Delete Character, built-in function) + Rubout deletes the previous character. See + section 3 [Basic Editing], page 15. + + Control-Rubout (^R Backward Delete Hacking Tabs, built-in + function) + Control-Rubout deletes the previous character, + but converts a tab character into several spaces. + See section 20.6 [Lisp], page 110. + + Control-D (^R Delete Character, built-in function) + Control-D deletes the next character. See + section 3 [Basic Editing], page 15. + + Control-K (^R Kill Line) + Control-K kills to the end of the line, or, at + the end of a line, kills the line separator. See + section 9.1 [Killing], page 39. + + Control-W (^R Kill Region) + Control-W kills the region, the text between + point and the mark. See section 9.1 [Killing], + page 39. See section 8 [Region], page 36. + + Control-Y (^R Un-kill) + Control-Y reinserts the last saved block of + killed text. See section 9.2 [Un-Killing], + page 41.î 212 EMACS Manual for ITS Users + + + + Meta-W (^R Copy Region) + Meta-W saves the region as if it were killed + without removing it from the buffer. See + section 9.2 [Un-Killing], page 41. + + Meta-Y (^R Un-kill Pop) + Meta-Y rolls the kill ring to reinsert saved + killed text older than the most recent kill. See + section 9.2 [Un-Killing], page 41. + + Control-Meta-W (^R Append Next Kill) + Control-Meta-W causes an immediately following + kill command to append its text to the last saved + block of killed text. See section 9.2 + [Un-Killing], page 41. + + Control-X G (^R Get Q-reg) + Control-X G inserts in the buffer the contents of + a q-register. See section 9.3.2 [Q-registers], + page 45. + + Control-X T (^R Transpose Regions) + Control-X T transposes two arbitrary regions + defined by point and the last three marks. See + section 12 [Fixing Typos], page 65. + + Control-X X (^R Put Q-reg) + Control-X X inserts in the buffer the contents of + a q-register. See section 9.3.2 [Q-registers], + page 45. + + M-X Overwrite Mode + M-X Overwrite Mode turns Overwrite mode on or + off. In Overwrite mode, printing characters + overwrite existing text instead of pushing it to + the right. See section 22.1 [Minor Modes], + page 133. + + + + Scrolling and Display Controlî Scrolling and Display Controlî Scrolling and Display Control + + + Control-Alpha (SAIL Character Mode) + Control-Alpha toggles SAIL Character mode. When + this mode is on, control characters in the buffer + are displayed as themselves. See section 1 + [Screen], page 5.î 213 EMACS Manual for ITS Users + + + + Control-L (^R New Window) + Control-L clears the screen and centers point in + it. With an argument, it can put point on a + specific line of the screen. See section 15 + [Display], page 87. + + Control-V (^R Next Screen) + Control-V scrolls the text upward by a screenful + or several lines. See section 15 [Display], + page 87. + + Meta-R (^R Move to Screen Edge) + Meta-R moves point to beginning of the text on a + specified line of the screen. See section 15 + [Display], page 87. + + Meta-V (^R Previous Screen) + Meta-V scrolls downward by a screenful or several + lines. See section 15 [Display], page 87. + + Control-Meta-R (^R Reposition Window) + Control-Meta-R tries to center on the screen the + function or paragraph you are looking at. See + section 15 [Display], page 87. + + Control-Meta-V (^R Scroll Other Window) + Control-Meta-V scrolls the other window up or + down, when you are in two window mode. See + section 16 [Windows], page 90. + + M-X View Buffer + M-X View Buffer skips through a buffer by + screenfuls. See section 15 [Display], page 87. + + M-X View File + M-X View File lets you move through a file + sequentially by screenfuls forward and back. See + section 13.7 [View File], page 79. + + + + The Mark and the Regionî The Mark and the Regionî The Mark and the Region + + + Control-Space (^R Set/Pop Mark) + Control-Space sets the mark or moves to the + location of the mark. See section 8 [Mark], + page 36.î 214 EMACS Manual for ITS Users + + + + Control-< (^R Mark Beginning) + Control-< sets the mark at the beginning of the + buffer. See section 8 [Mark], page 36. + + Control-> (^R Mark End) + Control-> sets the mark at the end of the buffer. + See section 8 [Mark], page 36. + + Control-@ (^R Set/Pop Mark) + Control-@ sets the mark or moves to the location + of the mark. See section 8 [Mark], page 36. + + Meta-@ (^R Mark Word) + Meta-@ puts the mark at the end of the next word. + See section 11.1 [Words], page 50. + + Meta-H (^R Mark Paragraph) + Meta-H puts point at the beginning of the + paragraph and the mark at the end. See + section 11.2 [Sentences], page 52. + + Control-Meta-@ (^R Mark Sexp) + Control-Meta-@ puts the mark at the end of the + next s-expression. See section 20.6.1 [Lists], + page 111. + + Control-Meta-H (^R Mark Defun) + Control-Meta-H puts point at the beginning of the + current Defun and the mark at the end. See + section 20.6.2 [Defuns], page 114. + + Control-X H (^R Mark Whole Buffer) + Control-X H puts point at the beginning of the + buffer and the mark at the end. See section 8 + [Mark], page 36. + + Control-X Control-P (^R Mark Page) + Control-X Control-P puts point at the beginning + of the current page and the mark at the end. See + section 18 [Pages], page 94. + + Control-X Control-X (^R Exchange Point and Mark) + Control-X Control-X sets point where the mark was + and the mark where point was. See section 8 + [Mark], page 36.î 215 EMACS Manual for ITS Users + + + + Whitespace and Indentationî Whitespace and Indentationî Whitespace and Indentation + + + Tab (^R Indent According to Mode) + Tab either adjusts the indentation of the current + line or inserts some indentation, in a way that + depends on the major mode. See section 20.3 + [Indenting Programs], page 104. See section 11.3 + [Indenting Text], page 54. + + Linefeed (^R Indent New Line) + Linefeed is equivalent to Return followed by Tab. + It moves to a new line and indents that line. If + done in the middle of a line, it breaks the line + and indents the new second line. See + section 11.3 [Indenting Text], page 54. + + Meta-Tab (^R Tab to Tab Stop) + Meta-Tab indents to the next EMACS-defined tab + stop. See section 11.3 [Indenting Text], + page 54. + + Meta-M (^R Back to Indentation) + Meta-M positions the cursor on the current line + after any indentation. See section 11.3 + [Indenting Text], page 54. + + Meta-\ (^R Delete Horizontal Space) + Meta-\ deletes all spaces and tab characters + around point. See section 11.3 [Indenting Text], + page 54. + + Meta-^ (^R Delete Indentation) + Meta-^ joins two lines, replacing the indentation + of the second line with zero or one space, + according to the context. See section 11.3 + [Indenting Text], page 54. + + Control-Meta-O (^R Split Line) + Control-Meta-O breaks a line, preserving the + horizontal position of the second half by + indenting it to its old starting position. See + section 11.3 [Indenting Text], page 54. + + Control-Meta-\ (^R Indent Region) + Control-Meta-\ indents each line in the region, + either by applying Tab to each line, or by giving + each the same specified amount of indentation. + See section 11.3 [Indenting Text], page 54.î 216 EMACS Manual for ITS Users + + + + Control-X Tab (^R Indent Rigidly) + Control-X Tab shifts all the lines in the region + right or left the same number of columns. See + section 11.3 [Indenting Text], page 54. + + M-X Edit Indented Text + M-X Edit Indented Text enters a recursive editing + level designed for editing text in which each + line is indented. See section 11.4 [Filling], + page 56. + + M-X Edit Tab Stops + M-X Edit Tab Stops lets you edit the tab stops + used by ^R Tab to Tab Stop. See section 11.3 + [Indenting Text], page 54. + + M-X Edit Tabular Text + M-X Edit Tabular Text enters a recursive editing + level designed for editing text arranged in a + table. See section 11.4 [Filling], page 56. + + M-X Indent Tabs Mode + M-X Indent Tabs Mode turns Indent Tabs mode on or + off. When Indent Tabs mode is on, the + indentation commands use tab characters for + indentation whenever possible. Otherwise they + use only spaces. See section 22.1 [Minor Modes], + page 133. + + M-X Tabify + M-X Tabify converts spaces after point to tabs + when that can be done without changing the + appearance. See section 11.3 [Indenting Text], + page 54. + + M-X Untabify + M-X Untabify converts all tabs after point to + spaces. A numeric argument says how far apart + the tab stops are, which is good for converting + files brought from systems with tab stops at + intervals other than 8. See section 11.3 + [Indenting Text], page 54.î 217 EMACS Manual for ITS Users + + + + Words, Sentences and Paragraphsî Words, Sentences and Paragraphsî Words, Sentences and Paragraphs + + + Meta-A (^R Backward Sentence) + Meta-A moves to the beginning of the sentence. + See section 11.2 [Sentences], page 52. + + Meta-B (^R Backward Word) + Meta-B moves backward one word. See section 11.1 + [Words], page 50. + + Meta-D (^R Kill Word) + Meta-D kills one word forward. See section 11.1 + [Words], page 50. + + Meta-E (^R Forward Sentence) + Meta-E moves to the end of the sentence. See + section 11.2 [Sentences], page 52. + + Meta-F (^R Forward Word) + Meta-F moves forward one word. See section 11.1 + [Words], page 50. + + Meta-H (^R Mark Paragraph) + Meta-H puts point at the front of the current + paragraph and the mark at the end. See + section 11.2 [Sentences], page 52. + + Meta-K (^R Kill Sentence) + Meta-K kills to the end of the sentence. See + section 11.2 [Sentences], page 52. + + Meta-T (^R Transpose Words) + Meta-T transposes two consecutive words. See + section 11.1 [Words], page 50. + + Meta-[ (^R Backward Paragraph) + Meta-[ moves to the beginning of the paragraph. + See section 11.2 [Sentences], page 52. + + Meta-] (^R Forward Paragraph) + Meta-] moves to the end of the paragraph. See + section 11.2 [Sentences], page 52. + + Meta-Rubout (^R Backward Kill Word) + Meta-Rubout kills the previous word. See + section 11.1 [Words], page 50. + + Control-X Rubout (^R Backward Kill Sentence) î 218 EMACS Manual for ITS Users + + + + Control-X Rubout kills back to the beginning of + the sentence. See section 11.2 [Sentences], + page 52. + + M-X Atom Word Mode + M-X Atom Word Mode turns Atom Word mode on or + off. In Atom Word mode, the word commands + consider an entire Lisp atom as one word. See + section 22.1 [Minor Modes], page 133. + + M-X Edit Syntax Table + M-X Edit Syntax Table allows you to edit the + syntax table for word and list delimiters. See + section 22.4 [Syntax Table], page 139. + + + + Filling Textî Filling Textî Filling Text + + + Meta-G (^R Fill Region) + Meta-G fills the region, treating it (usually) as + one paragraph. See section 11.4 [Filling], + page 56. + + Meta-Q (^R Fill Paragraph) + Meta-Q fills the current or next paragraph. See + section 11.4 [Filling], page 56. + + Meta-S (^R Center Line) + Meta-S centers the current line. See + section 11.4 [Filling], page 56. + + Control-X . (^R Set Fill Prefix) + Control-X . specifies the fill prefix, which is + used for filling indented text. See section 11.4 + [Filling], page 56. + + Control-X F (^R Set Fill Column) + Control-X F sets the variable Fill Column which + controls the margin for filling and centering. + See section 11.4 [Filling], page 56. + + M-X Auto Fill Mode + M-X Auto Fill Mode turns Auto Fill mode on or + off. In Auto Fill mode, long lines are broken + between words automatically. See section 11.4 + [Filling], page 56.î 219 EMACS Manual for ITS Users + + + + Exiting, Quittingî Exiting, Quittingî Exiting, Quitting + + + Control-G + Control-G quits, interrupting a running command, + or discarding any partially typed command. See + section 24.1 [Quitting], page 159. + + Control-] (Abort Recursive Edit) + Control-] aborts a recursive editing level; that + is to say, exits it without allowing the command + which invoked it to finish. See section 24.1 + [Quitting], page 159. + + Control-Meta-C (^R Exit, built-in function) + Control-Meta-C exits from a recursive editing + level and allows the command which invoked the + recursive editing level to finish. At top level, + it exits from EMACS to its superior job. See + section 6.4 [Exiting], page 31. + + Control-X Control-C (^R Return to Superior) + Control-X Control-C returns from EMACS to its + superior job, even if EMACS is currently inside a + recursive editing level. In that case, + re-entering EMACS will find it still within the + recursive editing level. See section 6.4 + [Exiting], page 31. + + M-X Compile + M-X Compile recompiles the file you are visiting, + in a manner that depends on the major mode. See + section 20.2 [Compile], page 103. + + M-X Top Level + M-X Top Level returns to the top level EMACS + command loop or to TECO. See section 24.1 + [Quitting], page 159. + + M-X Undo + M-X Undo retracts the last undoable change to the + buffer. See section 24.2 [Lossage], page 160.î 220 EMACS Manual for ITS Users + + + + Pagesî Pagesî Pages + + + Control-X L (^R Count Lines Page) + Control-X L prints the number of lines on the + current page, and how many come before point and + how many come after. See section 18 [Pages], + page 94. + + Control-X P (^R Narrow Bounds to Page) + Control-X P narrows the virtual boundaries to the + current page. See section 17 [Narrowing], + page 93. + + Control-X [ (^R Previous Page) + Control-X [ moves backward to the previous page + boundary. See section 18 [Pages], page 94. + + Control-X ] (^R Next Page) + Control-X ] moves forward to the next page + boundary. See section 18 [Pages], page 94. + + Control-X Control-P (^R Mark Page) + Control-X Control-P puts point at the beginning + and the mark at the end of the current page. See + section 18 [Pages], page 94. + + M-X View Page Directory (in PAGE) + M-X View Page Directory prints a directory of the + pages of the file. See section 18.1 [PAGE], + page 96. + + M-X What Page + M-X What Page prints the current page and line + number in the file. See section 18 [Pages], + page 94. + + + + Lispî Lispî Lisp + + + Meta-( (^R Make ()) + Meta-( places a pair of parentheses around the + next several s-expressions. See section 20.6.1 + [Lists], page 111. + + Meta-) (^R Move Over )) + Meta-) moves past the next close parenthesis andî 221 EMACS Manual for ITS Users + + + + adjusts the indentation of the following line. + See section 20.6.1 [Lists], page 111. + + Control-Meta-Tab (^R Indent for Lisp) + Control-Meta-Tab adjusts the indentation of the + current line for proper Lisp style. See + section 20.3 [Indenting], page 104. + + Control-Meta-( (^R Backward Up List) + Control-Meta-( moves backward up one level of + list structure. See section 20.6.1 [Lists], + page 111. + + Control-Meta-) (^R Up List) + Control-Meta-) moves forward up one level of list + structure. See section 20.6.1 [Lists], page 111. + + Control-Meta-@ (^R Mark Sexp) + Control-Meta-@ puts the mark at the end of the + next s-expression. See section 8 [Mark], + page 36. + + Control-Meta-A (^R Beginning of Defun) + Control-Meta-A moves to the beginning of the + current Defun. See section 20.6.2 [Defuns], + page 114. + + Control-Meta-B (^R Backward Sexp) + Control-Meta-B moves backward over one + s-expression. See section 20.6.1 [Lists], + page 111. + + Control-Meta-D (^R Down List) + Control-Meta-D moves forward and down a level in + list structure. See section 20.6.1 [Lists], + page 111. + + Control-Meta-E (^R End of Defun) + Control-Meta-E moves to the end of the current + Defun. See section 20.6.2 [Defuns], page 114. + + Control-Meta-F (^R Forward Sexp) + Control-Meta-F moves forward over one + s-expression. See section 20.6.1 [Lists], + page 111. + + Control-Meta-G (^R Format Code) + Control-Meta-G grinds the s-expression after + point. See section 20.7 [Grinding], page 115.î 222 EMACS Manual for ITS Users + + + + Control-Meta-H (^R Mark Defun) + Control-Meta-H puts point before and the mark + after the current or next Defun. See + section 20.6.2 [Defuns], page 114. + + Control-Meta-K (^R Kill Sexp) + Control-Meta-K kills the following s-expression. + See section 20.6.1 [Lists], page 111. + + Control-Meta-N (^R Next List) + Control-Meta-N moves forward over one list, + ignoring atoms before the first open parenthesis. + See section 20.6.1 [Lists], page 111. + + Control-Meta-P (^R Previous List) + Control-Meta-P moves backward over one list, + ignoring atoms reached before the first close + parenthesis. See section 20.6.1 [Lists], + page 111. + + Control-Meta-Q (^R Indent Sexp) + Control-Meta-Q adjusts the indentation of each of + the lines in the following s-expression, but not + the current line. See section 20.3 [Indenting], + page 104. + + Control-Meta-T (^R Transpose Sexps) + Control-Meta-T transposes two consecutive + s-expressions. See section 20.6.1 [Lists], + page 111. + + Control-Meta-U (^R Backward Up List) + Control-Meta-U moves backward up one level of + list structure. See section 20.6.1 [Lists], + page 111. + + + + Filesî Filesî Files + + + Meta-. (^R Find Tag) + Meta-. moves to the definition of a specific + function, switching files if necessary. See + section 21 [TAGS], page 122. + + Meta-~ (^R Buffer Not Modified) + Meta-~ clears the flag which says that the buffer + contains changes that have not been saved. See + section 13.1 [Visiting], page 69.î 223 EMACS Manual for ITS Users + + + + Control-X Control-F (Find File) + Control-X Control-F visits a file in its own + buffer. See section 14 [Buffers], page 83. + + Control-X Control-Q (^R Set File Read Only) + Control-X Control-Q makes the visited fie read + only, or no longer read only. See section 13.1 + [Visiting], page 69. + + Control-X Control-S (^R Save File) + Control-X Control-S saves the visited file. See + section 13.1 [Visiting], page 69. + + Control-X Control-V (^R Visit File) + Control-X Control-V visits a file. See + section 13.1 [Visiting], page 69. + + Control-X Control-W (Write File) + Control-X Control-W saves the file, asking for + names to save it under. See section 13.7 + [Advanced File Commands], page 79. + + M-X Append to File + M-X Append to File appends the contents of the + region to the end of a specified file. See + section 13.7 [Advanced File Commands], page 79. + + M-X Auto Save Mode + M-X Auto Save Mode turns Auto Save mode on or + off. See section 13.3 [Auto Save], page 72. + + M-X Copy File + M-X Copy File copies a file to a new name. See + section 13.7 [Advanced File Commands], page 79. + + M-X Delete File + M-X Delete File deletes a file. See section 13.7 + [Advanced File Commands], page 79. + + M-X Insert File + M-X Insert File inserts the contents of a file + into the buffer (within the existing text). See + section 13.7 [Advanced File Commands], page 79. + + M-X Prepend to File + M-X Prepend to File appends the contents of the + region to the start of a specified file. See + section 13.7 [Advanced File Commands], page 79.î 224 EMACS Manual for ITS Users + + + + M-X Rename File + M-X Rename File changes the name of a file. See + section 13.7 [Advanced File Commands], page 79. + + M-X Revert File + M-X Revert File undoes changes to a file by + reading in the previous version. See + section 13.2 [Revert File], page 72. + + M-X Save All Files + M-X Save All Files offers to write back buffers + which may need it. See section 14 [Buffers], + page 83. + + M-X Set Visited Filename + M-X Set Visited Filename changes the visited + filename, without writing a file. See + section 13.7 [Advanced File Commands], page 79. + + M-X Write Region + M-X Write Region writes the contents of the + region into a file. See section 13.7 [Advanced + File Commands], page 79. + + + + File Directoriesî File Directoriesî File Directories + + + Control-X D (^R DIRED) + Control-X D invokes the directory editor DIRED, + useful for deleting many files. See section 13.6 + [DIRED], page 76. + + Control-X Control-D (^R Directory Display) + Control-X Control-D displays a subset of a + directory. See section 13.4 [Directories], + page 75. + + M-X Clean Directory + M-X Clean Directory deletes all but the most + recent versions of every file in a directory. + See section 13.5 [Cleaning Directories], page 75. + + M-X Compare Directories + M-X Compare Directories compare two directories + with the same name on different machines. See + section 13.8 [Compare Directories], page 81.î 225 EMACS Manual for ITS Users + + + + M-X List Directories + M-X List Directories list the names of all disk + directories. See section 13.4 [Directories], + page 75. + + M-X List Files + M-X List Files prints a very brief listing of a + directory, listing only the filenames, several + files per line. See section 13.4 [Directories], + page 75. + + M-X Reap File + M-X Reap File deletes all but the most recent + versions of a file. See section 13.5 [Cleaning + Directories], page 75. + + M-X View Directory + M-X View Directory prints a file directory. See + section 13.4 [Directories], page 75. + + + + Buffersî Buffersî Buffers + + + Control-X Control-B (List Buffers) + Control-X Control-B prints a list of all buffers, + their major modes and the files they are + visiting. See section 14 [Buffers], page 83. + + Control-X A (^R Append to Buffer) + Control-X A adds the text of region into another + buffer. See section 9.3 [Copying], page 44. + + Control-X B (Select Buffer) + Control-X B is the command for switching to + another buffer. See section 14 [Buffers], + page 83. + + Control-X K (Kill Buffer) + Control-X K kills a buffer. See section 14 + [Buffers], page 83. + + M-X Insert Buffer + M-X Insert Buffer inserts the contents of another + buffer into the existing text of this buffer. + See section 14 [Buffers], page 83. + + M-X Kill Some Buffers î 226 EMACS Manual for ITS Users + + + + M-X Kill Some Buffers offers to kill each buffer. + See section 14 [Buffers], page 83. + + M-X Make Space + M-X Make Space tries to free up space inside + EMACS for more libraries or buffers. See + section 24.2.5 [Storage Exhausted], page 161. + + M-X Rename Buffer + M-X Rename Buffer changes the name of the current + buffer. See section 14 [Buffers], page 83. + + M-X What Available Space + M-X What Available Space prints the amount of + space left inside EMACS for more libraries or + buffers. See section 24.2.5 [Storage Exhausted], + page 161. + + + + Commentsî Commentsî Comments + + + Meta-Linefeed (^R Indent New Comment Line) + Meta-Linefeed moves to a new line and indents it. + If point had been within a comment on the old + line, a new comment is started on the new line + and indented under the old one. See section 20.5 + [Comments], page 107. + + Meta-; (^R Indent for Comment) + Meta-; inserts a properly indented comment at the + end of the current line, or adjusts the + indentation of an existing comment. See + section 20.5 [Comments], page 107. + + Meta-N (^R Down Comment Line) + Meta-N moves down a line and starts a comment. + See section 20.5 [Comments], page 107. + + Meta-P (^R Up Comment Line) + Meta-P moves down a line and starts a comment. + See section 20.5 [Comments], page 107. + + Control-Meta-; (^R Kill Comment) + Control-Meta-; kills any comment on the current + line. See section 20.5 [Comments], page 107. + + Control-X ; (^R Set Comment Column) î 227 EMACS Manual for ITS Users + + + + Control-X ; sets the column at which comments are + indented, from an argument, the current column, + or the previous comment. See section 20.5 + [Comments], page 107. + + + + Case Conversionî Case Conversionî Case Conversion + + + Meta-C (^R Uppercase Initial) + Meta-C makes the next word lower case with a + capital initial. It moves over the word. See + section 11.5 [Case], page 58. + + Meta-L (^R Lowercase Word) + Meta-L moves over a word converting it to lower + case. See section 11.5 [Case], page 58. + + Meta-U (^R Uppercase Word) + Meta-U moves over a word converting it to upper + case. See section 11.5 [Case], page 58. + + Control-X Control-L (^R Lowercase Region) + Control-X Control-L converts the text of the + region to lower case. See section 11.5 [Case], + page 58. + + Control-X Control-U (^R Uppercase Region) + Control-X Control-U converts the text of the + region to upper case. See section 11.5 [Case], + page 58. + + + + Minor Correctionsî Minor Correctionsî Minor Corrections + + + Meta-# (^R Change Font Region) + Meta-# inserts a font-change command good for + certain text justifiers around a word. See + section 11.6 [Fonts], page 59. + + Meta-$ (^R Correct Word Spelling) + Meta-$ (Dollar sign, not Altmode) passes the word + before point to the SPELL program. If it is not + a correct spelling, you have the option of + replacing it with a corrected spelling. See + section 12 [Fixing Typos], page 65.î 228 EMACS Manual for ITS Users + + + + Meta-' (^R Upcase Digit) + Meta-' converts a digit before point on the same + or previous line to a punctuation character, + assuming that you failed to type the shift key + and thus typed the digit by mistake. See + section 12 [Fixing Typos], page 65. + + Meta-_ (^R Underline Word) + Meta-_ inserts underlining commands good for + certain text justifiers around a word. See + section 11.7 [Underlining], page 60. + + Control-X # (^R Change Font Region) + Control-X # inserts font change commands good for + certain text justifiers around the region. See + section 11.6 [Fonts], page 59. + + Control-X _ (^R Underline Region) + Control-X _ inserts underlining commands good for + certain text justifiers around the region. See + section 11.7 [Underlining], page 60. + + + + Windowsî Windowsî Windows + + + Control-Meta-V (^R Scroll Other Window) + Control-Meta-V scrolls the other window up or + down. See section 15 [Display], page 87. + + Control-X 1 (^R One Window) + Control-X 1 returns to one-window mode. See + section 16 [Windows], page 90. + + Control-X 2 (^R Two Windows) + Control-X 2 splits the screen into two windows. + See section 16 [Windows], page 90. + + Control-X 3 (^R View Two Windows) + Control-X 3 splits the screen into two windows + but stays in window one. See section 16 + [Windows], page 90. + + Control-X 4 (^R Visit in Other Window) + Control-X 4 displays two windows and selects a + buffer or visits a file in the other window. See + section 16 [Windows], page 90.î 229 EMACS Manual for ITS Users + + + + Control-X O (^R Other Window) + Control-X O switches from one window to the + other. See section 16 [Windows], page 90. + + Control-X ^ (^R Grow Window) + Control-X ^ changes the allocation of screen + space to the two windows. See section 16 + [Windows], page 90. + + M-X Compare Windows + M-X Compare Windows compares the text in window + one after point with that in window two after + point. It advances point in both windows to the + first non-matching text. See section 16 + [Windows], page 90. + + + + Narrowingî Narrowingî Narrowing + + + Control-X N (^R Narrow Bounds to Region) + Control-X N narrows the virtual boundaries to the + region. See section 17 [Narrowing], page 93. + + Control-X P (^R Narrow Bounds to Page) + Control-X P narrows the virtual boundaries to the + current page. See section 18 [Pages], page 94. + + Control-X W (^R Widen Bounds) + Control-X W widens the virtual boundaries back to + the entire buffer. See section 17 [Narrowing], + page 93. + + + + Status Informationî Status Informationî Status Information + + + Control-X = (What Cursor Position) + Control-X = prints information on the screen + position and character position of the cursor, + the size of the file, and the character after the + cursor. See section 11.4 [Filling], page 56. + + Control-X L (^R Count Lines Page) + Control-X L prints the number of lines in the + current page, and how many come before or after + point. See section 18 [Pages], page 94.î 230 EMACS Manual for ITS Users + + + + M-X List Loaded Libraries + M-X List Loaded Libraries lists the names of all + loaded libraries. See section 22.2 [Libraries], + page 135. + + M-X List Variables + M-X List Variables lists the names and values of + all variables, or of those whose names contain a + specified string. See section 22.3 [Variables], + page 137. + + M-X List Redefinitions + M-X List Redefinitions describes all the ways + which the major mode and local modes of the + selected buffer modify the standard EMACS. See + section 20.1 [Major Modes], page 102. + + M-X What Page + M-X What Page prints the page and line number of + point. See section 18 [Pages], page 94. + + + + Keyboard Macrosî Keyboard Macrosî Keyboard Macros + + + Control-X ( (^R Start Kbd Macro) + Control-X ( begins defining a keyboard macro. + See section 22.8 [KBDMAC], page 152. + + Control-X ) (^R End Kbd Macro) + Control-X ) terminates the definition of a + keyboard macro. See section 22.8 [KBDMAC], + page 152. + + Control-X E (^R Call Last Kbd Macro) + Control-X E executes the most recently defined + keyboard macro. See section 22.8 [KBDMAC], + page 152. + + Control-X Q (^R Kbd Macro Query) + Control-X Q in a keyboard macro can ask the user + whether to continue or allow him to do some + editing before continuing with the keyboard + macro. See section 22.8 [KBDMAC], page 152. + + M-X Name Kbd Macro + M-X Name Kbd Macro gives a permanent name to the + last keyboard macro defined. See section 22.8 + [KBDMAC], page 152.î 231 EMACS Manual for ITS Users + + + + M-X View Kbd Macro + M-X View Kbd Macro prints the definition of a + keyboard macro. See section 22.8 [KBDMAC], + page 152. + + + + Librariesî Librariesî Libraries + + + M-X Kill Libraries + M-X Kill Libraries discards one or more libraries + from core. See section 22.2 [Libraries], + page 135. + + M-X List Library + M-X List Library describes briefly all the + functions in a library. See section 22.2 + [Libraries], page 135. + + M-X Load Library + M-X Load Library loads one library, permanently. + See section 22.2 [Libraries], page 135. + + M-X Run Library + M-X Run Library loads a library temporarily, + invokes a function in it, and then discards the + library. See section 22.2 [Libraries], page 135. + + + + Variablesî Variablesî Variables + + + M-X Edit Options + M-X Edit Options lets you edit, in a recursive + editing level, the values of many variables. See + section 22.3 [Variables], page 137. + + M-X Kill Local Q-register + M-X Kill Local Q-register makes a q-register or + command character definition no longer local to + the selected buffer. See the file INFO;CONV, + node Vars. + + M-X Kill Local Variable M-X Kill Local Variable makes a variable + value no longer local to the selected buffer. + See the file INFO;CONV, node Vars.î 232 EMACS Manual for ITS Users + + + + M-X Kill Variable + M-X Kill Variable eliminates a particular + variable. See section 22.3 [Variables], + page 137. + + M-X Make Local Q-register M-X Make Local Q-register makes a + q-register or command character definition local + to the selected buffer. See the file INFO;CONV, + node Vars. + + M-X Make Local Variable M-X Make Local Variable makes a variable + value local to the selected buffer. See the file + INFO;CONV, node Vars. + + M-X Set Key + M-X Set Key connects a function to a command + character. See section 5.2 [M-X Commands], + page 24. + + M-X Set Variable + M-X Set Variable sets the value of a variable. + See section 22.3 [Variables], page 137. + + M-X View Variable + M-X View Variable displays the value and comment + of a variable. See section 22.3 [Variables], + page 137. + + + + Mailî Mailî Mail + + + Control-X M (Send Mail) + Control-X M allows you to edit and send a message + using your favorite mail-reading program. The + default is RMAIL. See section 6.2 [Mail], + page 29. + + Control-X R (Read Mail) + Control-X R runs your choice of mail-reading + program to read and edit your mail. The default + is RMAIL. See section 6.2 [Mail], page 29. + + M-X View Mail + M-X View Mail displays your own or another user's + mail file using View File. See section 6.2 + [Mail], page 29.î 233 EMACS Manual for ITS Users + + + + Minibufferî Minibufferî Minibuffer + + + Control-% (^R Replace String) + Control-% invokes a minibuffer containing a call + to Replace String. You fill in the arguments. + See section 19 [Replace], page 98. + + Meta-Altmode (^R Execute Minibuffer) + Meta-Altmode invokes an empty minibuffer which + you can fill in with a TECO program to be + executed. See section 23 [Minibuffer], page 156. + + Meta-% (^R Query Replace) + Meta-% invokes a minibuffer containing a call to + Query Replace. You fill in the arguments. See + section 19 [Replace], page 98. + + Control-X Altmode (^R Re-execute Minibuffer) + Control-X Altmode re-executes a TECO program + previously executed in the minibuffer. It can + also re-execute an extended command. See + section 23 [Minibuffer], page 156.î 234 EMACS Manual for ITS Users + + + + CATALOG OF LIBRARIESî CATALOG OF LIBRARIESî CATALOG OF LIBRARIES + + + + Libraries Used Explicitlyî Libraries Used Explicitlyî Libraries Used Explicitly + + + These are libraries which you must load with M-X Load + Library$ to use. If no cross-reference is given, + the only documentation for the library is the self-documentation + contained in it. Use M-X List Library$ to print a + brief description of each function in the library. For more + detailed information, load the library and use M-X Describe on + individual functions. + + + ABSTR contains commands for making documentation files: + wall charts, and abstracts of libraries. See the + file INFO;CONV. + + BABYL is a subsystem for reading, sending and editing + mail. See the file INFO;BABYL. + + BSHACK has functions for operating on lines containing + overprinting. + + BUGHUNT contains commands for putting your name into each + comment you edit. This is to record who changed + what. + + CACHE implements a cache for speeding up EMACS + subroutine calls. + + CHESS implements commands for editing pictures of chess + boards. + + CLU implements CLU mode. See the file INFO;ECLU. + + COLUMNS implements commands for converting single-column + text into double-column text and vice versa. + + COMPLT provides completion for buffer names and variable + names. + + DELIM implements commands for moving over balanced + groupings of various kinds of parentheses. There + are a pair of commands for square brackets, a + pair for angle brackets, etc.î 235 EMACS Manual for ITS Users + + + + DOCLSP prints documentation from the MacLisp manual on a + specified Lisp function. + + DOCIX constructs indexes of Lisp manual files for + DOCLSP. + + DOCOND is a macro processor and conditionalizer for text + files, useful for maintaining multiple versions + of documents with one source. + + DOCTOR contains DOCTOR mode, a psychiatrist. + + DRAW offers functions for editing pictures made of + characters. These partially duplicate the + facilities of the PICTURE library, but contain + other distinct features. + + FIXLIB has functions for examining and patching EMACS + functions. + + FORTRAN implements FORTRAN mode. See the file INFO; + EFORTRAN. + + HAZ1510 redefines commands to be convenient on Hazeltine + 1510 terminals. + + IBM370 implements IBM370 mode, for editing 370 assembler + code. + + INFO peruses tree-structured documentation files. + + IVORY is EAK and ECC's alternate generator for EMACS + libraries, which uses a slightly nonstandard + input format. The libraries BABYL, BABYLM, + CACHE, FIXLIB, IVORY, MKDUMP, OUTLINE-MODE, PL1, + TEACH-C100, TMACS and WORDAB are generated with + IVORY. See the file INFO;IVORY. + + JOURNAL implements journal files. See section 24.4 + [Journals], page 164. + + JUSTIFY implements an auto-justfy mode similar to auto + fill mode. + + LABELS has functions for arranging a file of addresses + for printing mailing labels. + + LEDIT is the EMACS side of the EMACS-to-MacLisp + interface. See the file INFO;LEDIT.î 236 EMACS Manual for ITS Users + + + + LISPT is the EMACS side of another EMACS-to-MacLisp + interface. See the file INFO;LISPT. + + LSPUTL contains a couple of useful functions for + searching and manipulating Lisp code. + + LUNAR is Moon's personal library, which contains some + useful commands. + + MACCNV does part of the work of converting MACRO-10 code + to MIDAS code. + + MAZLIB is a game for solving mazes. It's fun to play. + + MKDUMP aids in dumping your own customized environment. + See the file INFO;MKDUMP. + + MODE2 implements a second additional mode line with + additional information. + + MODLIN implements a fancier mode line display. + + MOVE provides commands specially for copying and + moving many pieces of text from one file to + another. + + MQREPL works with TAGS to perform several Query Replaces + on each of the files in a tag table. + + NEWS is for reading the latest AP or New York Times + news summary. + + NCOLUMNS has functions for turning single-column text into + many columns, but not vice-versa. + + NOVICE implements restricted subsets of EMACS, for + beginners. The beginner can turn commands back + on when he feels ready. See the file INFO;CONV, + node Novice. + + OUTLINE implements Outline Mode, for editing outlines. + + PAGE defines commands for viewing only one page of the + file at a time. See section 18.1 [PAGE], + page 96. + + PASCAL implements PASCAL mode. See the file INFO;EPASC. + + PERSONAL has functions for keeping notes on your current + projects.î 237 EMACS Manual for ITS Users + + + + PHRASE has commands for moving over and killing phrases + of text. + + PICTURE contains Edit Picture, the command for editing + text pictures. See section 26 [PICTURE], + page 183. + + PURIFY generates libraries from EMACS source files, and + contains other functions useful for editing the + source files. See the file INFO;CONV. + + QSEND sends a message to another logged-in user, like + :QSEND. + + RENUM renumbers figures, equations, theorems or + chapters. + + RMAIL is for reading, editing and sending mail. See + the file INFO;RMAIL. + + RUNOFF is for text-justified documents divided into + separate source files. It rejustifies the files + which have changed, then runs :@ to print only + the pages which have changed. + + SAIL implements SAIL mode. + + SCHEME implements SCHEME mode. + + SCRLIN contains alternative definitions of C-N and C-P + which move by screen lines instead of by real + lines. + + SLOWLY redefines commands and options to suit slow + terminals. + + SORT implements the sorting commands. + + SPLIT contains the commands Split File and Unsplit File + for breaking up large files into subfiles small + enough to be edited. See section 24.2 [Split], + page 160. + + TDEBUG is a debugger for TECO programs. It displays the + buffer in one window and the program in the + other, while stepping by lines or setting + breakpoints. See the file INFO;TDEBUG. + + TIME causes the current time of day to be displayed in + the mode line.î 238 EMACS Manual for ITS Users + + + + TMACS contains miscellaneous useful functions + + VT100 defines the arrow keys and numeric keypad of the + VT-100 terminal to move the cursor and supply + numeric arguments. + + VT52 defines the numeric keypad of the VT-52 terminal + to supply numeric arguments. + + XLISP contains functions for global stylistic + transformations of Lisp code. See section 20.6 + [Lisp], page 110. + + + + Automatically Loaded Librariesî Automatically Loaded Librariesî Automatically Loaded Libraries + + + These are libraries which the user need not know about to use. + + + AUX implements several commands described in the + manual as part of the standard EMACS. Loaded + automatically when needed. + + BABYLM contains the part of Babyl that implements mail + sending. + + BARE contains the definitions of all built-in + functions. These definitions are not needed for + executing the built-in functions, only so that + Help can describe them properly. Loaded + automatically by documentation commands when + needed. See section 5.2 [BARE], page 24. + + DIRED implements the commands for editing and listing + directories. Loaded automatically when needed. + See section 13.6 [DIRED], page 76. + + EINIT is used in building and dumping EMACS. See the + file INFO;CONV. + + EMACS is the main body of standard EMACS. Always + loaded. + + GRIND implements C-M-G. Loaded automatically when + needed. See section 20.7 [Grinding], page 115. + + KBDMAC implements keyboard macros. Loaded automaticallyî 239 EMACS Manual for ITS Users + + + + when needed. See section 22.8 [Keyboard Macros], + page 152. + + MUDDLE implements Muddle mode. + + PL1 implements PL1 mode. See the file INFO;EPL1. + + SCRIBE implements SCRIBE mode. See section 11.8 + [SCRIBE], page 61. Loaded automatically when + needed. + + TAGS implements the TAGS package. See section 21 + [TAGS], page 122. Loaded automatically when + needed. + + TEX implements TEX mode. See the file INFO;ETEX. + Loaded automatically when needed. + + WORDAB implements Word Abbrev mode. Loaded + automatically when needed. See section 25 + [WORDAB], page 172.î 240 EMACS Manual for ITS Users + + + + INDEX OF VARIABLESî INDEX OF VARIABLESî INDEX OF VARIABLES + + + + An option is a variable whose value Edit Options offers for + editing. A hook variable is a variable which is normally not + defined, but which you can define if you wish for customization. + Most hook variables require TECO programs as their values. + + The default value of the variable is given in parentheses after + its name. If no value is given, the default value is zero. If + the word "nonexistent" appears, then the variable does not exist + unless you create it. + + + Abort Resumption Message + This is the message to be printed by C-] to tell + you how to resume the aborted command. If this + variable is zero, there is no way to resume, so + C-] asks for confirmation. See section 24.1 + [Quitting], page 159. + + Additional Abbrev Expanders (nonexistent) + If this variable exists when Word Abbrev mode is + turned on, it is a string of characters which + should terminate and expand an abbrev, in + addition to the punctuation characters which + normally do so. See also WORDAB Ins Chars. + + After Compilation Hook (nonexistent) + If this variable exists and is nonzero, then it + is executed as a TECO expression by the function + Compile, after compilation itself is finished. + Exception: If the variable Compile Command is + also nonzero, it overrides this hook. See + section 20.2 [Compile], page 103. + + Atom Word Mode The minor mode Atom Word mode is on if this + variable is nonzero. See section 22.1 [Minor + Modes], page 133. + + Auto Directory Display + If this is nonzero, certain file operations + automatically display the file directory. See + section 13.4 [Directories], page 75. + + Auto Fill Mode The minor mode Auto Fill mode is on if this + variable is nonzero. See section 11.4 [Filling], + page 56.î 241 EMACS Manual for ITS Users + + + + Auto Push Point Notification + The value of this variable is the string printed + in the echo area by some commands to notify you + that the mark has been set to the old location of + point. See section 10 [Search], page 46. + + Auto Push Point Option (500) + Searches set the mark if they move at least this + many characters. See section 10 [Search], + page 46. + + Auto Save All Buffers + If this is nonzero, auto save saves all buffers + that are modified, not just the selected buffer. + See section 13.3 [Auto Save], page 72. + + Auto Save Default + The minor mode Auto Save mode is on by default + for newly visited files if this variable is + nonzero. See section 13.3 [Auto Save], page 72. + + Auto Save Filenames (DSK:;_SAV00 >) + These are the filenames used for auto saving if + the visited filenames are not used. If the last + two characters of the first filename are "00", as + they are by default, then they are replaced by + the last two characters of the buffer number to + get the filename actually used for saving. See + section 13.3 [Auto Save], page 72. + + Auto Save Interval (500) + This is the number of characters between auto + saves. See section 13.3 [Auto Save], page 72. + + Auto Save Max (2) + This is the maximum number of auto saves to keep. + See section 13.3 [Auto Save], page 72. + + Auto Save Mode If this is nonzero, Auto Save mode is enabled. + See section 13.3 [Auto Save], page 72. + + Auto Save Visited File + If this is nonzero, auto saving saves as the + visited filenames. If this is zero, auto saving + saves as the names which are the value of Auto + Save Filenames (q.v.). See section 13.3 [Auto + Save], page 72. + + Autoarg Mode When Autoarg Mode is nonzero, numeric argumentsî 242 EMACS Manual for ITS Users + + + + can be specified just by typing the digits. See + section 4 [Arguments], page 19. + + Bottom Display Margin + This controls the size of the region at the + bottom of the screen which the cursor is not + allowed to be in. If the cursor would normally + move there, the window is recentered instead. + The value is represented as a percentage of the + screen size, and must not be negative or more + than 99. It controls the TECO flag FS %BOTTOM$. + See section 15 [Display], page 87. + + Buffer Creation Hook (nonexistent) + If this variable exists and is nonzero, its value + should be a TECO program to be executed whenever + a newly created buffer is selected for the first + time. See section 14 [Buffers], page 83. + + Buffer Deselection Hook (nonexistent) + If this variable exists and is nonzero, its value + should be a TECO program to be executed whenever + a buffer is about to be deselected. The + difference between this and Buffer Selection Hook + is that, while both are executed (if they exist) + when you switch buffers, this is executed before + the switch, and Buffer Selection Hook is executed + after the switch. See section 14 [Buffers], + page 83. + + Buffer Selection Hook (nonexistent) + If this variable exists and is nonzero, its value + should be a TECO program to be executed whenever + a buffer is selected. See section 14 [Buffers], + page 83. + + Case Replace (1) + When Case Replace is nonzero, Replace String and + Query Replace attempt to preserve case when they + replace. See section 19 [Replace], page 98. + + Case Search (1) + If Case Search is nonzero, searches of all sorts + allow upper case letters and lower case letters + to match each other. It controls the TECO flag + FS BOTH CASE$. See section 10 [Search], page 46. + + Collapse in Comparison (nonexistent) + If this variable exists and is not zero, itî 243 EMACS Manual for ITS Users + + + + should be a string of characters for M-X Compare + Windows to regard as insignificant. See + section 16 [Windows], page 90. + + Comment Begin This is the string used to start new comments. + If it is zero, the value of Comment Start is + used. See section 20.5 [Comments], page 107. + + Comment Column This is the column at which comments are aligned. + See section 20.5 [Comments], page 107. + + Comment End This is the string which is used to end comments. + It is often empty for languages in which comments + end at the end of the line. See section 20.5 + [Comments], page 107. + + Comment Multi Line (nonexistent) + If this variable exists and is nonzero, then when + Auto Fill mode breaks a comment line, it does not + insert a new comment starter on the new line. + This is for use with languages that have explicit + comment terminators, if you want single + multi-line comments instead of single-line + comments on consecutive lines. See section 20.5 + [Comments], page 107. + + Comment Rounding (/8+1*8) + This is the TECO program used to decide what + column to start a comment in when the text of the + line goes past the comment column. The argument + to the program is the column at which text ends. + See section 20.5 [Comments], page 107. + + Comment Start This is the string used for recognizing existing + comments, and for starting new ones if Comment + Begin is zero. If Comment Start is zero, + semicolon is used. See section 20.5 [Comments], + page 107. + + Compile Command (nonexistent) + If this variable exists and is nonzero, its value + should be a TECO program to be used by the M-X + Compile command to compile the file. See + section 20.2 [Compile], page 103. + + Compiler Filename (nonexistent) + If this variable exists and is nonzero, its value + should be the name of the compiler to use, + suitable for a colon command. By default, theî 244 EMACS Manual for ITS Users + + + + name of the major mode is used as the name of the + compiler. See section 20.2 [Compile], page 103. + + Compiler Switches (nonexistent) + If this variable exists and is nonzero, its value + is used as switches for compilation. See + section 20.2 [Compile], page 103. + + Cursor Centering Point (40) + This specifies how far from the top of the screen + point ought to appear when a new window position + is chosen. The value of the variable is the + percentage of the screen size. It must not be + negative or more than 99. It controls the TECO + flag FS %CENTER$. See section 15 [Display], + page 87. + + Default Major Mode (Fundamental) + This is the major mode in which new buffers are + created. If it is the null string, new buffers + are created in the same mode as the previously + selected buffer. See section 14 [Buffers], + page 83. + + Digit Shift Table (nonexistent) + If this variable exists and is nonzero, its value + should be a string containing the ten characters + which are the upper case equivalents of the + digits 0 through 9 on the keyboard being used. + Meta-' (^R Upcase Digit) uses this table, and + reads it from the user if the variable does not + exist. See section 12 [Fixing Typos], page 65. + + Directory Lister (& Subset Directory Listing) + This is the TECO program used for listing a + directory for C-X C-D and the Auto Directory + Display option. The default value is the + definition of the function & Subset Directory + Listing. Another useful value is the definition + of the function & Rotated Directory Listing. See + section 13.4 [Directories], page 75. + + Display Matching Paren (-1) + This variable controls automatic display of the + matching open parenthesis when a close + parenthesis is inserted. See section 20.4 + [Matching], page 105. + + Display Mode Line Inverse î 245 EMACS Manual for ITS Users + + + + If this is nonzero, the mode line is displayed in + inverse video or otherwise highlighted, on + terminals which can support it. This controls + the TECO flag FS INVMOD$. See section 1.1 [Mode + Line], page 6. + + Display Overprinting + If this is nonzero, backspace characters and + stray carriage return characters in the buffer + display as actual overprinting rather than as ^H + and ^M. This variable controls the TECO flags FS + ^H PRINT$ and FS ^M PRINT$. See section 2 + [Characters], page 10. + + Echo Area Height (3) + This is the number of lines in the echo area. + Its value should be at least one. It controls + the TECO flag FS ECHO LINES$. See section 1 + [Screen], page 5. + + EMACS Version This variable's value is the EMACS version + number. + + End of Buffer Display Margin (35) + This specifies how far up the screen the end of + the buffer is placed, if it is on screen at all, + when a new window position is chosen. It is + represented as a percentage of the screen size, + and must not be negative or more than 99. Its + value controls the TECO flag FS %END$. See + section 15 [Display], page 87. + + Error Messages in Echo Area + If this is nonzero, error messages are printed in + the echo area instead of at the top of the + screen. It controls the TECO flag FS ECHO + ERRORS$. See section 24.2 [Lossage], page 160. + + Exit Hook (nonexistent) + If this variable exists and is nonzero, its value + is a TECO program to be executed whenever EMACS + is exited, instead of the normal action of doing + an auto save. The subroutine & Exit EMACS is + responsible for executing it. See section 6.4 + [Exiting], page 31. + + Exit to Superior Hook (nonexistent) + If this variable exists and is nonzero, its value + is a TECO program to be executed whenever EMACSî 246 EMACS Manual for ITS Users + + + + is about to return to its superior job, in + addition to all normal actions. + + Fill Column (70) + The value of Fill Column is the width used for + filling text. It controls the TECO flag FS + ADLINE$. See section 11.4 [Filling], page 56. + + Fill Extra Space List (.?!) + The characters in this string are the ones which + ought to be followed by two spaces when text is + filled. See section 11.4 [Filling], page 56. + + Fill Prefix The value of this variable is the prefix expected + on every line of text before filling and placed + at the front of every line after filling. It is + usually empty, for filling nonindented text. See + section 11.4 [Filling], page 56. + + Indent Tabs Mode (-1) + If Indent Tabs Mode is nonzero, then tab + characters are used by the indent commands. + Otherwise, only spaces are used. See + section 11.3 [Indenting Text], page 54. + + Setup Hook (nonexistent) + If this variable exists and is nonzero, its value + should be a TECO program to be executed when the + library is loaded. The library's + & Setup function is responsible for doing this. + If the library has no & Setup function, it will + not handle a setup hook either. See section 22.2 + [Libraries], page 135. + + Kill Hook (nonexistent) + Some libraries may execute the value of this + variable, if it exists and is nonzero, when the + library is being removed from core with Kill + Libraries. This is done by the library's & Kill + function; if the library has no & Kill + Library function, it will not handle a kill hook. + See section 22.2 [Libraries], page 135. + + Lisp Indent + This variable controls the indentation within + calls to the function . Actually, the + variable used is not always Lisp + Indent, but rather Indent, + where is the value of Lisp Indentî 247 EMACS Manual for ITS Users + + + + Language. See section 20.3 [Indenting], + page 104. + + Lisp Indent DEFanything (1) + The value of this variable controls indentation + within calls to functions whose names start with + "def". Actually, the variable used is not always + Lisp Indent DEFanything, but rather + Indent DEFanything, where is the value + of Lisp Indent Language. See section 20.3 + [Indenting], page 104. + + Lisp Indent Language (Lisp) + The value of this variable is the string used as + the language name when looking for + Indent variables. See section 20.3 + [Indenting], page 104. + + Lisp Indent Offset + If nonzero, this selects an alternative default + style of indentation for Lisp. Actually, the + variable used is not always Lisp Indent Offset, + but rather Indent Offset, where + is the value of Lisp Indent Language. + See section 20.3 [Indenting], page 104. + + Mail Reader Library (nonexistent) + If this variable exists and is nonzero, it is the + name of the library to be used by M-X Read Mail + for reading mail and by M-X Send Mail for sending + mail. The former calls the function "" in + the library, and the latter calls the function + "& Mail Message". If the variable does not + exist, the library RMAIL is used. See + section 6.2 [Mail], page 29. + + Mail Sender Library (nonexistent) + If this variable exists and is nonzero, it + specifies the library to be used by M-X Send Mail + only, overriding Mail Reader Library. See + section 6.2 [Mail], page 29. + + ..D (nonexistent) + This variable is used by the major mode to + record the syntax table for that mode. It is + created by the first use of the mode, and if you + supply your value, that value will be accepted + instead. For example, Text mode uses Text ..D. + Not all major modes have their own syntax tables. + See section 22.4 [Syntax], page 139.î 248 EMACS Manual for ITS Users + + + + Mode Hook (nonexistent) + If this variable exists and is nonzero, its value + is a TECO program to be executed when the major + mode is entered. For example, Text Mode + Hook is executed when Text mode is entered. See + section 20.1 [Major Modes], page 102. + + Next Screen Context Lines (nonexistent) + If this variable exists, its value specifies the + number of lines of overlap between one screenful + and the next, when scrolling by screens with C-V + and M-V. See section 15 [Display], page 87. + + Only Global Abbrevs (nonexistent) + If this variable exists and its value is nonzero, + then Word Abbrev Mode assumes that you are not + using any mode-specific abbrevs. See + section 25.2.1 [Customizing WORDAB], page 178. + + Overwrite Mode If this is nonzero, the minor mode Overwrite mode + is in effect. It controls the TECO flag FS ^R + REPLACE$. See section 22.1 [Minor Modes], + page 133. + + ^î Page Delimiter (|L) + This is the TECO search string used to recognize + page boundaries. See section 18 [Pages], + page 94. + + PAGE Flush CRLF + If this variable exists and is nonzero, the PAGE + library expects every page to start with a blank + line, which is not considered part of the + contents of the page. See section 18.1 [PAGE], + page 96. + + ^ ^ ^ ^î Paragraph Delimiter (.|O|I|O |O') + This is the TECO search string used to recognize + beginnings of paragraphs. See section 11.2 + [Sentences], page 52. + + Permit Unmatched Paren (-1) + Controls whether the bell is run if you insert an + unmatched close parenthesis. See section 20.4 + [Matching], page 105. + + Prefix Char List + This variable's value is a string which lists all + the prefix characters defined, so thatî 249 EMACS Manual for ITS Users + + + + self-documentation facilities can find any + subcommands of prefix characters which call a + given function. See the file INFO;CONV, node + Prefix. + + Quote Execute Command (nonexistent) + If this variable exists and is zero, then M-X + ^î does not quote |] characters which appear in the + string arguments of the command. See section 5.2 + [Extended Commands], page 24. + + Read Line Delay + This is the amount of time, in 30'ths of a + second, which EMACS should wait after starting to + read a line of input, before it prompts and + starts echoing the input. + + Readable Word Abbrev Files (nonexistent) + If this variable exists and is nonzero, word + abbrev files will be written in the format that + M-X List Word Abbrevs uses, instead of in a less + readable but faster loading format. See + section 25.1.6 [Saving Abbrevs], page 176. + + Region Query Size (5000) + Many commands which act on the region require + confirmation if the region contains more than + this many characters. See section 8 [Mark], + page 36. + + Return from Superior Hook (nonexistent) + If this variable exists and is nonzero, its value + should be a TECO program to be executed whenever + EMACS is resumed after being exited. See + section 6.4 [Exiting], page 31. + + SAIL Character Mode + If this is nonzero, characters in the buffer with + ASCII codes 0 through 37 are displayed without + conversion. Do not try to use this feature + except on terminals specially equipped to handle + it. The variable controls the TECO flag FS + SAIL$. See section I.1 [Ideal Keyboards], + page 186. + + Save Word Abbrevs (nonexistent) + If this variable exists, its value determines + which abbrevs will be saved upon exit from EMACS + when abbrevs have been modified. Setting it to 1î 250 EMACS Manual for ITS Users + + + + causes all abbrevs to be saved. See + section 25.1.6 [Saving Abbrevs], page 176. + Setting it to -1 causes just the incremental + abbrevs to be saved. See section 25.2.4 [Dumped + Environments], page 180. + + Search Exit Char (27) + This is the numeric code for the 9-bit character + which should exit incremental search and not have + its normal command meaning in that case. The + default, 27, is the code for Altmode. + + Search Exit Option (nonexistent) + If this variable is 0, Control and Meta + characters without special meanings do not exit + incrementatl search; instead, they are part of + the string to be searched for. If this variable + does not exist, or is nonzero, then those + characters exit the search and then have their + normal function. + + Set Mode Line Hook + This is a hook which is executed every time the + mode line is recomputed. It can insert text in + the buffer to put it in the mode line after the + minor modes. See section 1.1 [Mode Line], + page 6. + + SLOWLY Maximum Speed (nonexistent) + If this variable is defined, it is the maximum + output speed for which SLOWLY, if loaded, should + define its commands. See section I.5.4 [SLOWLY], + page 192. + + Space Indent Flag + If this flag is nonzero, then Auto Fill indents + the new lines which it creates, by performing a + Tab. Most major modes for programming languages + set this nonzero. See section 11.4 [Filling], + page 56. + + Tab Stop Definitions (a string) + The value of Tab Stop Definitions is a string + defining the tab stops to be used by the command + M-I (^R Tab to Tab Stop). See section 11.3 + [Indenting Text], page 54. + + Tags Find File (nonexistent) + If this variable exists and is not zero, TAGSî 251 EMACS Manual for ITS Users + + + + uses C-X C-F to switch files. Otherwise, TAGS + uses C-X C-V. See section 21 [TAGS], page 122. + Some other things may decide to use multiple + buffers if this variable is nonzero. See + section 14 [Buffers], page 83. + + Tags Search Verbose (nonexistent) + If this variable exists and is zero, Tags Search + does not print out the name of each file that it + begins to search. If the variable is + nonexistent, that is equivalent to a value of 1. + See section 21.4.3 [Tags Search], page 127. + + ^ ^î Temp File FN2 List (MEMO|OXGP|O ...) + This is a TECO search string which recognizes the + filenames which indicate that the file is + probably temporary. See section 13.5 [Clean + Directory], page 75. + + Top Display Margin + This controls the size of the region at the top + of the screen which the cursor is not allowed to + be in. If the cursor would normally move there, + the window is recentered instead. The value is + represented as a percentage of the screen size, + and must not be negative or more than 99. It + controls the TECO flag FS %TOP$. See section 15 + [Display], page 87. + + Underline Begin (nonexistent) + If this variable exists, its value should be the + character or string to use to begin underlines + for the M-_ command. See section 11.7 + [Underlining], page 60. + + Underline End (nonexistent) + If this variable exists, its value should be the + character or string to use to end underlines for + the M-_ command. See section 11.7 [Underlining], + page 60. + + Visit File Hook (nonexistent) + If this variable exists and is nonzero, its value + should be a TECO program to be executed whenever + a file is visited. See section 13.1 [Visiting], + page 69. + + Visit File Save Old (1) + This variable controls whether visiting a fileî 252 EMACS Manual for ITS Users + + + + offers to save the file previously visited in the + same buffer, if it has changes. See section 13.1 + [Visiting], page 69. + + WORDAB All Caps (nonexistent) + If this variable exists and is nonzero, expanding + an all-upper-case abbrev to a multi-word + expansion will cause the words in the expansion + to be all-upper-case, instead of just having + their first letters uppercased. See + section 25.1.2 [Controlling Expansion], page 175. + + WORDAB Ins Chars (nonexistent) + If this variable exists when Word Abbrev Mode is + turned on, it should be a string containing + precisely those characters which should terminate + and expand an abbrev. This variable overrides + Additional Abbrev Expanders (q.v.). See + section 25.2.1 [Customizing WORDAB], page 178.î 253 EMACS Manual for ITS Users + + + + INDEXî INDEXî INDEX + + + + 133, 134, 150 + ! 15, 99 Auto Push Point Notification 38 + Auto Push Point Option 38 + % 67 Auto Save All Buffers 74 + Auto Save Default 72, 133 + & (in function names) 26 Auto Save Filenames 73 + & Alter ..D 142 Auto Save Interval 74 + & Exit EMACS 32 Auto Save Max 74 + & Mail Message 29 Auto Save mode 7, 72, 133 + Auto Save Visited File 73 + *Permutation Table* (buffer)Autoarg mode 20, 188 + 185 Autoloading 136 + *Permuted File* (buffer) 185 + *Tags Search* (buffer) 127 Backspace 13 + *TAGS* (buffer) 124, 126 BARE library 27 + Bit prefix characters 188 + --MORE-- 8 Blank lines 18, 40, 53, 108, + 110 + . 99 BOLIO 59 + Bottom Display Margin 87 + 11 Buffers 7, 83, 92, 124, 127, + 150 + @Begin 62 Buggestion 64 + @End 62 Bugs 168 + Built-in functions 27 + Abbrev definition files 176, + 180 C- 10 + Abbrev definition lists 173,C-. 127 + 176, 179, 180 C-; 107 + Abbrevs 172 C-< 37 + Abort Recursive Edit 137, 159 C-> 37 + Aborting 159 C-@ 36 + Accumulator 119 C-A 16, 52, 105 + Additional Abbrev Expanders 179C-B 16, 101 + Address 119 C-C 11, 157 + Altmode 11, 13, 14, 22, 99,C-C C-Y 158 + 100, 141, 154, 157 C-D 16, 22, 39 + Append to File 44, 79 C-E 16, 52, 105 + Apropos 34 C-F 16 + Argument 174, 180 C-G 22, 31, 47, 69, 157, 159, + ASCII 10, 13 164 + Atom Word mode 7, 51, 133 C-K 16, 39, 52 + Auto Directory Display 75 C-L 16, 87, 154, 194 + Auto Fill 110 C-M-( 112 + Auto Fill mode 7, 54, 56, 108,C-M-) 112î 254 EMACS Manual for ITS Users + + + + C-M-; 108 C-X . 57 + C-M-@ 37, 112 C-X 1 90 + C-M-A 114, 119 C-X 145, 150 + C-M-B 62, 111 C-X 2 90 + C-M-C 31, 76, 137 C-X 3 91 + C-M-D 62, 112, 119 C-X 4 92 + C-M-E 62, 114, 119 C-X ; 109 + C-M-F 62, 111 C-X = 58 + C-M-G 62, 116, 120 C-X A 44 + C-M-H 37, 62, 114 C-X Altmode 24, 99, 157 + C-M-K 39, 62, 112 C-X B 83 + C-M-L 94 C-X C-A 174, 178, 181 + C-M-M 54, 105 C-X C-B 85 + C-M-N 62, 112, 119 C-X C-C 31, 176 + C-M-P 62, 112, 119 C-X C-D 75 + C-M-Q 62, 116 C-X C-F 84 + C-M-R 89 C-X C-H 174, 181 + C-M-Rubout 39, 62, 112 C-X C-L 59 + C-M-Space 175, 181 C-X C-O 18, 40 + C-M-T 112 C-X C-P 37, 94, 96 + C-M-Tab 115 C-X C-Q 70 + C-M-U 62, 112 C-X C-S 17, 70, 74, 85 + C-M-V 91 C-X C-T 66 + C-M-W 42 C-X C-U 36, 59 + C-M-X 23 C-X C-V 17, 69 + C-M-[ 114 C-X C-W 74 + C-M-\ 55, 116 C-X C-X 37 + C-M-] 114 C-X D 79 + C-M-^ 105, 115 C-X E 153 + C-N 16, 101 C-X F 57, 133 + C-O 18, 19, 101, 105 C-X G 45 + C-P 16 C-X H 37 + C-Q 15, 54, 94, 101, 175, 180 C-X J 97 + C-R 46, 96, 99, 154, 191 C-X K 85 + C-Rubout 110 C-X L 95 + C-S 46, 96, 191 C-X M 29 + C-Space 36 C-X N 93 + C-T 16, 66 C-X O 90 + C-U 19, 22, 69, 180 C-X P 93, 95, 97 + C-U C-@ 38, 53 C-X Q 154, 191 + C-U C-Space 38 C-X R 29 + C-V 88 C-X Rubout 39, 52, 65 + C-W 39, 53, 94, 99 C-X T 66 + C-X 11, 101 C-X Tab 55 + C-X # 60 C-X U 181 + C-X ( 153 C-X W 93, 95, 96 + C-X ) 153 C-X X 45 + C-X + 174, 178, 181 C-X [ 94, 96 + C-X - 174, 178, 181 C-X ] 94, 96î 255 EMACS Manual for ITS Users + + + + C-X ^ 91, 158 CRLF 13, 15 + C-X _ 61 Cursor 5, 15 + C-Y 41 Cursor Centering Point 87 + C-\ 157 Customization 12, 26, 116, 143, + C-] 76, 100, 137, 141, 159 150, 178 + C-^ 11 + C-_ 33 Default Major Mode 83 + Capitalization 175 Default Separator 192 + Caret 13 Define Word Abbrevs 179 + Case conversion 58, 66, 98,Defining abbrevs 174, 176 + 172, 189 Defuns 37, 114 + Case Replace 98 Delete File 80 + Case Search 47, 98 Delete Matching Lines 100 + Centering 57 Delete Non-Matching Lines 79, + Character Search 48 100 + Character set 10 Deletion 15, 39, 65, 100, 163 + Clean Directory 76 Describe 33, 138 + Clear screen 87 Digit Shift Table 66 + Collapse in Comparison 91 Directory 75, 79, 81 + Comma 99 Directory Lister 75 + Command completion 22, 26 DIRED 76, 136 + Commands 21 Disasters 72 + Comment Begin 109, 140 Display Matching Paren 106 + Comment Column 109, 151 Display Mode Line Inverse 8 + Comment End 109, 140 Display Overprinting 13 + Comment Start 109, 140, 151 Dissociated Press 63 + Comments 50, 97, 102, 107, 110,Documentation 35 + 111, 119, 140 Dollar Sign 14 + Compare Directories 81 Down Picture Movement 183 + Compare Windows 91 Drastic Changes 72 + Compile 103 Dumped environments 180 + Compile Command 104 + Compiler Filename 104 Echo area 5, 22, 58, 94, 174 + Compiler Switches 104 Echo Area Height 5 + Confirmation 59, 71, 72, 77,Edit Indented Text 54 + 157, 174 Edit key 187, 188 + Connected 12, 26 Edit Options 30, 137 + Continuation line 15 Edit Picture 30, 183 + Control 10, 13, 165 Edit Syntax Table 141 + Control characters, display ofEdit Tab Stops 50, 55 + 13 Edit Word Abbrevs 176 + Control characters, insertingEditor Type 6 + 15 End of Buffer Display Margin 87 + Control-Meta 111 Environments 61 + Copy File 80 Error handler 5 + Correct Spelling 67 Error message 5 + Count Matching Lines 100 Error Messages in Echo Area 160 + Crashes 72 Escape key 186 + Create File 70 EVARS 134, 143, 150î 256 EMACS Manual for ITS Users + + + + EVARS files 177, 178 Insertion 15, 79, 94 + Exit Hook 32 Instant Command Prompt 23 + Exit to Superior Hook 32 INTER 110 + Exiting 31 + Exiting EMACS 176, 181 Join pages 97 + Expand Word Abbrevs in RegionJournal files 164 + 175 Justification 57 + Expander characters 179 + Expanding abbrevs 175 Keyboard macros 7, 152 + Extended commands 21 Kill All Word Abbrevs 178 + Kill Buffer 85 + FAIL 118 Kill Libraries 136, 161 + File dates 71 Kill ring 41, 161 + File deletion 75, 76 Kill Some Buffers 85, 161 + File directory 75 Killing 39, 41, 51, 52, 65, + File Versions Kept 76 112, 163 + Files 7, 17, 69, 72, 79, 92,Killing abbrevs 174, 176, 178 + 150 + Fill Column 57, 133, 137 Labels 119 + Fill Prefix 53, 57 LEDIT 6, 110 + Filling 56 Left Picture Movement 183 + Find File 84, 124 Libraries 96, 135, 172, 183 + Find Pat 113 Line noise 34 + FLUSHED 8 Line separator 13, 15 + Fonts 59 Linefeed 13, 54, 102, 105, 115 + Formatting 54, 115 Linefeed, stray 13 + Formfeed 94 Lines 39, 185 + FS Flags 55, 87, 107, 120, 142,Lisp 104, 133 + 170, 190 Lisp FOO Indent 117 + Functions 12, 21, 26 Lisp Indent DEFAnything 116 + Lisp Indent Language 118 + Global abbrevs 172, 178 Lisp Indent Offset 117 + Grinding 115 Lisp Indentation Hook 117 + Lisp mode 110 + Help 11, 33, 166 Lisp PROG Indent 117 + Home Directory 144, 164 Lisp Special Indent Offset 116 + Hooks 181 List Buffers 85 + List Directories 75 + Ignoriginal 64 List Files 75 + Incremental abbrev definitionList Library 136 + files 180 List Loaded Libraries 136 + Indent Tabs Mode 55, 134 List Matching Lines 100 + Indentation 54, 104, 107, 115 List Redefinitions 103, 138 + Init file 188 List Tags 127 + Init files 143, 177, 178 List Variables 138 + Insert Buffer 185 List Word Abbrevs 176, 179, 180 + Insert File 79 Lists 37, 111, 140 + Insert Page Directory 97 Load Library 135 + Insert Word Abbrevs 179, 180 Loading 135î 257 EMACS Manual for ITS Users + + + + Local modes lists 134 M-W 42 + Local variables 83, 138, 139,M-X 21, 24 + 150 M-Y 43 + Lowercase Lisp Buffer 113 M-[ 53, 62, 119 + Lowercase Lisp Region 113 M-\ 40, 54, 105 + LSPUTL 113 M-] 53, 119 + M-^ 40, 54, 105, 115 + M- 10 M-_ 60 + M-" 120 M-~ 71 + M-# 59 M.L 138 + M-$ 67 Macro-10 118 + M-% 100, 157 Macsyma 116 + M-' 66, 120, 175, 181 Macsyma mode 120 + M-( 112 Mail 29 + M-) 112 Mail Reader Library 29 + M-- M-C 66 Mail Sender Library 29 + M-- M-L 66 MAILT 6 + M-- M-U 66 Major modes 7, 83, 102, 103, + M-. 124 109, 141, 150, 172 + M-; 107 Make Page Permutation Table 185 + M-< 16 Make Space 161 + M-> 16 Make These Characters Expand + M-@ 37, 51 179 + M-A 52 Make Word Abbrev 178 + M-Altmode 156 Mark 36, 41, 42, 51, 53, 80, + M-B 50 94, 112, 114, 124 + M-C 58 Markov Chain 64 + M-D 39, 51 Matching 105, 140 + M-E 52 Meta 10, 50, 165, 186, 187, 188 + M-F 50 Metizer 11, 157, 188 + M-G 57 MIDAS 104, 118 + M-H 37, 53, 57 MIDAS mode 118 + M-I 55 Minibuffer 6, 15, 24, 31, 79, + M-J 108 87, 100, 156, 170 + M-K 39, 52 Minibuffer Separator 192 + M-L 58 Minor modes 7, 55, 133, 172 + M-Linefeed 108 MM 24, 45 + M-M 54, 105 MM Commands 21 + M-N 108 Mode abbrevs 172, 178 + M-O 191 Mode line 6, 30, 83, 96, 103, + M-P 108 133, 156 + M-Q 57 Motion 50, 52, 94, 111, 114 + M-R 89 Moving text 41 + M-Rubout 39, 51, 65 MQREPL 127 + M-S 57 Muddle mode 110 + M-T 51 + M-Tab 54 Name Kbd Macro 153 + M-U 58 Narrowing 58, 93, 95, 98 + M-V 88 Next File 126î 258 EMACS Manual for ITS Users + + + + Next Screen Context Lines 88 Reap File 76 + Numeric argument 174, 180 Recursive editing level 6, 30, + Numeric arguments 19, 23, 25, 76, 85, 141, 159, 165, + 41, 43, 51, 55, 56, 59, 176 + 61, 72, 75, 88, 91, 92,Redefining abbrevs 174 + 98, 108, 116, 133, 137,Redefining commands 144, 150 + 158, 187, 188 Region 36, 41, 42, 53, 59, 60, + 61, 80, 93, 94, 114, + Only Global Abbrevs 178 116, 174, 185 + Options 137 Region Query Size 59 + Outragedy 64 Rename Buffer 85 + Overprinting 13 Rename File 80 + Overwrite mode 7, 134 Replace String 98 + Replacement 98, 100 + PAGE 96 Replay Journal File 164 + Page Delimiter 53, 95 Restarting 162 + PAGE Flush CRLF 97 Return 11, 13, 15, 69 + Pages 37, 53, 94, 96, 185 Return from Superior Hook 32 + Paragraph Delimiter 53, 120 Return, stray 13 + Paragraphs 37, 52, 57, 62, 110,Revert File 72, 74 + 119, 185 Right Picture Movement 183 + Parentheses 50, 105, 140 RMAIL 6, 29 + Permit Unmatched Paren 106 Rubout 11, 13, 15, 16, 22, 39, + Permute Pages From Table 185 65, 99, 102, 110, 134, + Pictures 183 154 + Point 5, 15 Run Library 136 + Prefix characters 11, 145, 150 + Prepend to File 44, 79 S-expressions 111, 140 + Preventing abbrev expansion 175SAIL Character Mode 134, 186 + Printing characters 15 SAIL characters 186 + Printing terminal 194 Save All Files 85 + Prompting 5, 22 Save Word Abbrevs 176, 181 + PURIFY library 120 Saving 69, 72 + Saving abbrevs 176 + Q-registers 45 Screen 5, 87 + Query Replace 68, 99, 154, 157 SCRIBE 61 + Quit 164 Scrolling 87, 88, 91 + Quitting 47, 159 Search Exit Char 47 + Quote Execute Command 25 Search Exit Option 47 + Quoting 15, 180 Searching 46, 96, 98 + Select Buffer 83 + R 59, 60 Send Mail 29 + Read Command Prompt 22 Sentences 52, 65 + Read Incremental Word Abbrev FileSet Key 26, 178 + 180 Set Variable 137 + Read Mail 29 Set Visited Filename 70, 80 + Read Word Abbrev File 176, 180 Short Display Size 191 + Read-Only Visiting 70 Slow Search Lines 191 + Readable Word Abbrev Files 177 Slow Search Separator 192î 259 EMACS Manual for ITS Users + + + + SLOWLY Maximum Speed 192 Text mode 50, 106 + Sort Lines 185 Text Mode Hook 106 + Sort Pages 185 TJ6 59 + Sort Paragraphs 185 TMACS 29 + Sorting 185 Toggling 133 + Space 11, 13, 22, 56, 67, 99,Top Display Margin 87 + 154 Top level 6, 159, 162 + Space Indent Flag 54 Transposition 51, 66, 112 + Spell Program 67 Two window mode 90 + SPLIT 162 Type Mailing List 29 + Split File 162 Typeout 5 + Split pages 97 Typos 65, 66 + SRCCOM 71, 78 + Start Journal File 164 Underline Begin 61 + String arguments 23, 25, 75,Underline End 61 + 137 Underlining 60 + String Search 48 Undo 41, 59, 72, 161, 163 + Submode 7 Unexpanding abbrevs 175 + Subroutines 26 Unsplit File 162 + Subsystem 6 Untabify 56 + Syntax table 50, 51, 106, 110,Up Picture Movement 183 + 114, 139 Uparrow 13 + Uppercase Lisp Buffer 113 + Tab 13, 50, 54, 102, 104, 110,Uppercase Lisp Region 113 + 115 URK 85, 161 + Tab Stop Definitions 55 User Name 144 + Tabify 56 + Tag Table Filenames 125 Variables 13, 137, 144 + TAGGEN 123 View Arglist 128 + TAGS 84, 92, 136 View Buffer 88 + Tags Apropos 127 View Directory 75 + Tags File List 128 View File 79, 89 + TAGS Find File 84, 124, 127 View Kbd Macro 154 + Tags Query Replace 127 View Mail 29 + Tags Rescan 128 View Page Directory 97 + Tags Search 127 Visit File 81 + TCTYP 161 Visit File Save Old 70 + Techniquitous 64 Visit Tag Table 123 + TECO 22, 24, 27, 45, 53, 58,Visiting 17, 69, 72, 84, 92 + 80, 87, 101, 104, 106, + 118, 136, 138, 142,W2 90 + 144, 152, 162, 190 What Available Space 162 + TECO default filenames 80 What Cursor Position 58 + TECO mode 120 What Page 94 + TECO search string 127 What Tag? 128 + TECO search strings 76, 98, 101Windows 90 + Temp File FN2 List 76 Word Abbrev Hook 181 + Terminal type 161 Word abbrev mode 7, 134, 172, + Text justifiers 59, 60 173, 178î 260 EMACS Manual for ITS Users + + + + Word Search 48 ^R Beginning of Line 16 + WORDAB 172 ^R Buffer Not Modified 71 + WORDAB All Caps 175 ^R Center Line 57 + WORDAB DEFNS 176 ^R Change Environment Name 62 + WORDAB Ins Chars 179 ^R Change Font Region 60 + WORDAB Setup Hook 181 ^R Change Font Word 59 + Words 37, 50, 58, 59, 60, 65,^R Change Form 62 + 66, 139 ^R Commands 21 + Write File 74, 79 ^R Copy Region 42 + Write Incremental Word Abbrev^R Correct Word Spelling 67 + File 180 ^R Count Lines Page 95 + Write Kbd Macro 154 ^R CRLF 15 + Write Word Abbrev File 176, 180^R Delete Blank Lines 18, 40 + ^R Delete Character 39 + XLISP 113 ^R Delete Horizontal Space 40, + 54, 105 + ^ 13, 99 ^R Delete Indentation 40, 54, + ^R (in function names) 12 105, 115 + ^R Abbrev Expand Only 175 ^R Directory Display 75 + ^R Add Global Word Abbrev 174,^R DIRED 79 + 178 ^R Down Comment Line 108 + ^R Add Mode Word Abbrev 174,^R Down Environment 62 + 178 ^R Down List 112 + ^R Add Tag 125 ^R Down Real Line 16 + ^R Append Next Kill 42 ^R Edit Quietly 191 + ^R Append to Buffer 44 ^R End Kbd Macro 153 + ^R Back to Indentation 54 ^R End of Defun 114 + ^R Backward Character 16 ^R End of Environment 62 + ^R Backward Delete Character^R End of Line 16 + 15, 39, 65, 110 ^R Exchange Point and Mark 37 + ^R Backward Delete Hacking Tabs^R Execute Kbd Macro 153 + 110 ^R Execute Minibuffer 156 + ^R Backward Environment 62 ^R Exit 31, 137 + ^R Backward Kill Sentence 39,^R Extract Sublist 113 + 52, 65 ^R Fill Paragraph 57 + ^R Backward Kill Sexp 39, 112 ^R Fill Region 57 + ^R Backward Kill Word 39, 51,^R Format Code 116 + 65 ^R Forward Character 16 + ^R Backward List 112 ^R Forward Environment 62 + ^R Backward Paragraph 53, 119 ^R Forward List 112 + ^R Backward SCRIBE Paragraph 62^R Forward Paragraph 53, 119 + ^R Backward Sentence 52 ^R Forward Sentence 52 + ^R Backward Sexp 111 ^R Forward Sexp 111 + ^R Backward TECO Conditional^R Forward TECO Conditional 120 + 120 ^R Forward Up List 112 + ^R Backward Up Environment 62 ^R Forward Word 50 + ^R Backward Up List 112 ^R Get Q-reg 45 + ^R Backward Word 50 ^R Go to AC Field 119 + ^R Beginning of Defun 114 ^R Go to Address Field 119î 261 EMACS Manual for ITS Users + + + + ^R Go to Next Label 119 ^R Narrow Bounds to Page 93, 95 + ^R Go to Previous Label 119 ^R Narrow Bounds to Region 93 + ^R Goto Beginning 16 ^R New Window 16, 87, 194 + ^R Goto End 16 ^R Next Page 94 + ^R Goto Next Page 96 ^R Next Screen 88 + ^R Goto Page 96 ^R One Window 90 + ^R Goto Previous Page 96 ^R Open Line 18, 19 + ^R Grow Window 91, 158 ^R Other Window 90 + ^R Incremental Search 46, 96 ^R PAGE Widen Bounds 96 + ^R Indent for Comment 107 ^R Prefix Control 11 + ^R Indent for Lisp 110, 115 ^R Prefix Control-Meta 11 + ^R Indent Nested 120 ^R Prefix Meta 11 + ^R Indent New Comment Line 108 ^R Previous Page 94 + ^R Indent New Line 54, 102,^R Previous Screen 88 + 105, 115 ^R Put Q-reg 45 + ^R Indent Region 55, 116 ^R Query Replace 100, 157 + ^R Indent Rigidly 55 ^R Quoted Insert 15 + ^R Indent Sexp 116 ^R Re-execute Minibuffer 24, + ^R Insert () 112 99, 157 + ^R Insert Pagemark 97 ^R Reposition Window 89 + ^R Instant Extended Command 23 ^R Return to Superior 31 + ^R Inverse Add Global Word Abbrev^R Reverse Search 46, 96 + 174, 178 ^R Save File 17, 70, 85 + ^R Inverse Add Mode Word Abbrev^R Scroll Other Window 91 + 174, 178 ^R Set Comment Column 109 + ^R Join Next Page 97 ^R Set File Read-Only 70 + ^R Kbd Macro Query 154 ^R Set Fill Column 57, 133 + ^R Kill Comment 108 ^R Set Fill Prefix 57 + ^R Kill Global Word Abbrev 178 ^R Set Screen Size 191 + ^R Kill Line 39 ^R Set/Pop Mark 36 + ^R Kill Mode Word Abbrev 178 ^R Slow Display I-Search 191 + ^R Kill Region 39 ^R Slow Reverse Display I-search + ^R Kill Sentence 39, 52 191 + ^R Kill Sexp 39, 112 ^R Start Kbd Macro 153 + ^R Kill Terminated Word 119 ^R Tab to Tab Stop 50, 55 + ^R Kill Word 39, 51 ^R Transpose Characters 16, 66 + ^R Lowercase Region 59 ^R Transpose Lines 66 + ^R Lowercase Word 58, 66 ^R Transpose Regions 66 + ^R Mark Beginning 37 ^R Transpose Sexps 112 + ^R Mark Defun 37, 114 ^R Transpose Words 51 + ^R Mark End 37 ^R Two Windows 90 + ^R Mark Environment 62 ^R Un-kill 41 + ^R Mark Page 37, 94 ^R Un-kill Pop 43 + ^R Mark Paragraph 37, 53 ^R Underline Region 61 + ^R Mark Sexp 37, 112 ^R Underline Word 60 + ^R Mark Whole Buffer 37 ^R Universal Argument 19 + ^R Mark Word 37, 51 ^R Up Comment Line 108 + ^R Move Over ) 112 ^R Up Real Line 16 + ^R Move to Screen Edge 89 ^R Upcase Digit 66î 262 EMACS Manual for ITS Users + + + + ^R Uppercase Initial 58, 66 + ^R Uppercase Region 36, 59 + ^R Uppercase Word 58, 66 + ^R View Two Windows 91 + ^R Visit File 17, 69 + ^R Visit in Other Window 92 + ^R Widen Bounds 93, 95 + ^R Word Abbrev Prefix Mark 175î i EMACS Manual for ITS Users + + + + TABLE OF CONTENTSî TABLE OF CONTENTSî TABLE OF CONTENTS + + + + Introductionî Introductionî Introduction 3 + + + 1. The Organization of the Screenî 1. The Organization of the Screenî 1. The Organization of the Screen 5 + + 1.1 The Mode Line 6 + + + 2. Character Sets and Command Input Conventionsî 2. Character Sets and Command Input Conventionsî 2. Character Sets and Command Input Conventions 10 + + 2.1 The 9-bit Command Character Set 10 + 2.2 Prefix Characters 11 + 2.3 Commands, Functions, and Variables 12 + 2.4 Notational Conventions for ASCII Characters 13 + + + 3. Basic Editing Commandsî 3. Basic Editing Commandsî 3. Basic Editing Commands 15 + + 3.1 Inserting Text 15 + 3.2 Moving The Cursor 16 + 3.3 Erasing Text 16 + 3.4 Files 17 + 3.5 Help 17 + 3.6 Using Blank Lines Can Make Editing Faster 18 + + + 4. Giving Numeric Arguments to EMACS Commandsî 4. Giving Numeric Arguments to EMACS Commandsî 4. Giving Numeric Arguments to EMACS Commands 19 + + 4.1 Autoarg Mode 20 + + + 5. Extended (Meta-X) Commands and Functionsî 5. Extended (Meta-X) Commands and Functionsî 5. Extended (Meta-X) Commands and Functions 21 + + 5.1 Issuing Extended Commands 21 + 5.2 Arcane Information about M-X Commands 24 + + + 6. Moving Up And Down Levelsî 6. Moving Up And Down Levelsî 6. Moving Up And Down Levels 28 + + 6.1 Subsystems 28 + 6.2 Reading Mail 29 + 6.3 Recursive Editing Levels 30 + 6.4 Exiting Levels; Exiting EMACS 31î ii EMACS Manual for ITS Users + + + + 7. Self-Documentation Commandsî 7. Self-Documentation Commandsî 7. Self-Documentation Commands 33 + + + 8. The Mark and the Regionî 8. The Mark and the Regionî 8. The Mark and the Region 36 + + 8.1 Commands to Mark Textual Objects 37 + 8.2 The Ring of Marks 38 + + + 9. Killing and Moving Textî 9. Killing and Moving Textî 9. Killing and Moving Text 39 + + 9.1 Deletion and Killing 39 + 9.2 Un-Killing 41 + 9.3 Other Ways of Copying Text 44 + + + 10. Searchingî 10. Searchingî 10. Searching 46 + + + 11. Commands for English Textî 11. Commands for English Textî 11. Commands for English Text 50 + + 11.1 Word Commands 50 + 11.2 Sentence and Paragraph Commands 52 + 11.3 Indentation Commands for Text 54 + 11.4 Text Filling 56 + 11.5 Case Conversion Commands 58 + 11.6 Font-Changing 59 + 11.7 Underlining 60 + 11.8 SCRIBE Mode 61 + 11.9 Dissociated Press 63 + + + 12. Commands for Fixing Typosî 12. Commands for Fixing Typosî 12. Commands for Fixing Typos 65 + + 12.1 Killing Your Mistakes 65 + 12.2 Transposition 66 + 12.3 Case Conversion 66 + 12.4 Checking and Correcting Spelling 67 + + + 13. File Handlingî 13. File Handlingî 13. File Handling 69 + + 13.1 Visiting Files 69 + 13.2 How to Undo Drastic Changes to a File 72 + 13.3 Auto Save Mode: Protection Against Disasters 72 + 13.4 Listing a File Directory 75 + 13.5 Cleaning a File Directory 75î iii EMACS Manual for ITS Users + + + + 13.6 DIRED, the Directory Editor Subsystem 76 + 13.7 Miscellaneous File Operations 79 + 13.8 The Directory Comparison Subsystem 81 + + + 14. Using Multiple Buffersî 14. Using Multiple Buffersî 14. Using Multiple Buffers 83 + + 14.1 Creating and Selecting Buffers 83 + 14.2 Using Existing Buffers 85 + 14.3 Killing Buffers 85 + + + 15. Controlling the Displayî 15. Controlling the Displayî 15. Controlling the Display 87 + + + 16. Two Window Modeî 16. Two Window Modeî 16. Two Window Mode 90 + + 16.1 Multiple Windows and Multiple Buffers 92 + + + 17. Narrowingî 17. Narrowingî 17. Narrowing 93 + + + 18. Commands for Manipulating Pagesî 18. Commands for Manipulating Pagesî 18. Commands for Manipulating Pages 94 + + 18.1 Editing Only One Page at a Time 96 + + + 19. Replacement Commandsî 19. Replacement Commandsî 19. Replacement Commands 98 + + 19.1 Query Replace 99 + 19.2 Other Search-and-loop Functions 100 + 19.3 TECO Search Strings 101 + + + 20. Editing Programsî 20. Editing Programsî 20. Editing Programs 102 + + 20.1 Major Modes 102 + 20.2 Compiling Your Program 103 + 20.3 Indentation Commands for Code 104 + 20.4 Automatic Display Of Matching Parentheses 105 + 20.5 Manipulating Comments 107 + 20.6 Lisp Mode and Muddle Mode 110 + 20.7 Lisp Grinding 115 + 20.8 Editing Assembly-Language Programs 118 + 20.9 Major Modes for Other Languages 120î iv EMACS Manual for ITS Users + + + + 21. The TAGS Package.î 21. The TAGS Package.î 21. The TAGS Package. 122 + + 21.1 How to Make a Tag Table for a Program 122 + 21.2 How to Tell EMACS You Want to Use TAGS 123 + 21.3 Jumping to a Tag 124 + 21.4 Other Operations on Tag Tables 125 + 21.5 What Constitutes a Tag 128 + 21.6 Adding or Removing Source Files 129 + 21.7 How a Tag Is Described in the Tag Table 130 + 21.8 Tag Tables for INFO Structured Documentation Files 131 + + + 22. Simple Customizationî 22. Simple Customizationî 22. Simple Customization 133 + + 22.1 Minor Modes 133 + 22.2 Libraries of Commands 135 + 22.3 Variables 137 + 22.4 The Syntax Table 139 + 22.5 FS Flags 142 + 22.6 Init Files and EVARS Files 143 + 22.7 Local Variables in Files 150 + 22.8 Keyboard Macros 152 + + + 23. The Minibufferî 23. The Minibufferî 23. The Minibuffer 156 + + + 24. Correcting Mistakes and EMACS Problemsî 24. Correcting Mistakes and EMACS Problemsî 24. Correcting Mistakes and EMACS Problems 159 + + 24.1 Quitting and Aborting 159 + 24.2 Dealing with Common Forms of EMACS Lossage 160 + 24.3 Undoing Changes to the Buffer 163 + 24.4 Journal Files 164 + 24.5 Reporting Bugs 168 + + + 25. Word Abbreviation Inputî 25. Word Abbreviation Inputî 25. Word Abbreviation Input 172 + + 25.1 Basic Usage 173 + 25.2 Advanced Usage 177 + 25.3 Teco Details for Extension Writers 181 + + + 26. The PICTURE Subsystem, an Editor for Text Picturesî 26. The PICTURE Subsystem, an Editor for Text Picturesî 26. The PICTURE Subsystem, an Editor for Text Pictures 183 + + + 27. Sorting Functionsî 27. Sorting Functionsî 27. Sorting Functions 185î v EMACS Manual for ITS Users + + + + Appendix I. Particular Types of Terminalsî Appendix I. Particular Types of Terminalsî Appendix I. Particular Types of Terminals 186 + + I.1 Ideal Keyboards 186 + I.2 Keyboards with an "Edit" key 187 + I.3 ASCII Keyboards 188 + I.4 Upper-case-only Terminals 189 + I.5 The SLOWLY Package for Slow Terminals 190 + + + Appendix II. Use of EMACS from Printing Terminalsî Appendix II. Use of EMACS from Printing Terminalsî Appendix II. Use of EMACS from Printing Terminals 194 + + + Glossaryî Glossaryî Glossary 196 + + + Command Summaryî Command Summaryî Command Summary 208 + + + Catalog of Librariesî Catalog of Librariesî Catalog of Libraries 234 + + + Index of Variablesî Index of Variablesî Index of Variables 240 + + + Indexî Indexî Index 253î \ No newline at end of file diff --git a/doc/info/conv.85 b/doc/info/conv.85 new file mode 100755 index 00000000..66dfedec --- /dev/null +++ b/doc/info/conv.85 @@ -0,0 +1,1686 @@ +-*-Text-*- + +File: CONV Node: Top Up: (DIR) Next: Init + +Programming in TECO for EMACS + +* Menu: + +* Init Files: Init INIT files and what they can do. +* Syntax: Syntax Syntax library source files to be compiled by + the EMACS library compiler in the PURIFY library. + Description of TECO mode, good for editing + source code for libraries. +* Libraries: Lib Other conventions for Libraries and sources. +* Ivory: (Ivory)Top The IVORY library has an alternative + compressor and purifier mechanism. +* Programming: Prog Conventions for TECO programs to be operated + in the EMACS enviromnment. +* Buffers:: Data structures for EMACS buffers. +* Windows:: Data structures for two window mode. +* Complete:: How to read names with completion. +* Variables: Vars Named variable (QFoo, etc) conventions. +* Major Modes: Major How to define new major modes. +* Submodes:: How to define submodes. +* Prefix:: Prefix characters, such as C-X. +* Hooks:: Variables which EMACS will call at specific times. +* Novice:: Setting up restricted subsets for beginners. +* Dump:: Dumping EMACS environments. +* Build:: Building and dumping the standard EMACS environment. +* Wall Charts:: Making wall charts. +* Abstracts:: Making abstracts of libraries (for documentation) + and source listings and source indexes of + TECO code (good for studying the code). +* Q-registers: Qregs Conventions for use of Q-registers. +* FS ^R PREV: FS^RPREV Conventions for setting/examining FS ^R PREV. +* Debugging: Debug Debugging aids in EMACS. +* TDEBUG: (TDEBUG) TDEBUG is a package for stepping and + breakpoints in TECO code. + + +File: CONV Node: Init, Up: Top, Previous: Top, Next: Syntax + +INIT Files. + + This is not a full description of how to write init files, +because such a description has to include a full course on TECO +programming. People who want to learn to program in TECO should +follow this course of action: find a DEC TECO manual and read it +(much of that will apply to this TECO as well, though many individual +commands are different or missing in DEC TECO), look through the +TECORD file, then read this file. After that, you can read some EMACS +source code and init files using TECORD and this file as a reference. + + Each user can have his own file of TECO commands for EMACS to +execute each time he starts it up. EMACS looks for the file +; EMACS and then for ;* EMACS, where +stands for the user's home directory. If neither file exists, the +file EMACS;* EMACS (the default init file) is used instead. +On Twenex, the init file is called EMACS.INIT in your login directory, +and the default init file is EMACS.INIT. + + You can cause an EMACS to read another user's init file by giving it +that user's name as its XUNAME; just do ^S in DDT immediately +before starting the EMACS. To avoid running your own init file, +specify a name like FOO which has no init file. + + Setting up the default character definitions and named variables +need not be done in an init file, since that is done before the EMACS +environment is dumped out. As a result, your init file need only +define those commands which you wish to change. Use MM Load Lib to +load any additional libraries (or the :EJ command, for libraries which +have no & Setup Library function). To obtain a function as a +value so you can put it on a character, simply use M.M . The +U command can define a character, as in for example U..^RX which puts +its argument on Meta-X. The character is specified in the same manner +as in an EVARS file; *Note EVARS: (EMACS)Init. Use M.V to create and +assign a variable, or better yet M.C to give it some documentation as +well. *Note Vars: Vars, for details of how to use M.V and M.C. + + When the init file is started, all q-registers not used by EMACS +(and described herein) will probably be zero. One exception is Q1, +which contains the version number of EMACS :EJ (on ITS, [PURE] >), as +a string. The default init file types this out as the "EMACS version +number". + + If you have no init file, EMACS runs the default init file, which is +the init file on the EMACS directory. This does various things such +as processing a command line from the superior, loading LISPT if +necessary, printing the EMACS version number and offering help, ... + + Most people will find that they wish to perform the actions of the +default init file after their own peculiar initializations. +To do this, just end your own init file with + + ER EMACS;* EMACS @Y ET@ > :M(HFX*) + +(On Twenex, do EREMACS;EMACS INIT or EREMACS.INIT instead) +This practice is recommended because some of the things in the default +init file are important for the proper functioning of EMACS. + +The above sample of code calls the default init file with an empty +buffer. If you call it with text in the buffer, that text is used +instead of the job's command line arguments. + +To prevent the default init file from printing its help message, +create the variable Inhibit Help Message and make it nonzero. + + If you have enough of your own functions to have a private library of +them, you need not have both the library and an init file to load the +library. You can just call your library EMACS and give it a +~Filename~ of INIT and a & Setup INIT Library function to perform the +other initialization. The & Setup INIT Library function should end by +jumping to the default init file, just like an ordinary init file made +of text should. + +File: CONV Node: Syntax, Up: Top, Previous: Init, Next: Lib + +Syntactic Conventions for EMACS Library Source Files + + The fundamental basis of EMACS is the library, which contains a set +of functions written in TECO, together with their names and +documentation. There is one standard library which contains the main +body of EMACS, and there are other libraries that are loaded sometimes +automatically or by request. For more information on how to use +libraries, *Note Use: (EMACS)Libraries. This node describes how to +write library source files, and the next node describes how to compile +them. + + A source file of EMACS functions contains one function on each page. +Each function has a name and documentation as well as its definition. +These source files are processed by a compressor which deletes spaces +and comments and performs other syntactic transformations before they +are run. You can also ask to compress and install a single function, +for testing, by pointing at it and using MM Compile. + + Every function definition should end with a CRLF, after which may +come a ^L and the next function definition. Function definitions are +separated only by CRLF ^L CRLF. A ^L in the middle of the line is +just part of a function. If you want to put CRLF ^L CRLF inside a +function, use CRLF ^]^Q^L CRLF. + +The Function Name + + Every function's definition begins with the function name, which is +preceded by a ! and followed by :!. You must not ever put a :!, even +with spaces in between, in a source file except to end a function +name. The function name must be the first thing on a page except for a +CRLF which must follow the previous formfeed on pages after the first. +The name conventions are that subroutine names start with "& " and +names of commands intended to be put on characters start with "^R ". +This is to keep them from limiting the user's ability to abbreviate +the names of commands he wishes to type. Another convention is that +"#" begins the names of commands which form a dispatch table. For +example, in INFO, the command M causes # INFO M to be run. If you +define a command named # INFO +, that will automatically give you an +INFO command called +. + +The Function Documentation + + After the function name comes a space, an !, and then the function +class. Then, after another space, the rest of the line is the "brief" +documentation which is used when only a single line is wanted. It +should be a complete sentence. The function class should be the +character C for a command which users should call by name, S for a +command intended to be used as a subroutine, and ^R for a command +intended to be placed on a character. The function class does not +restrict how the function can actually be used; some of the +documentation commands filter commands to be described by class. + + The function may have only the brief documentation. In this case, +the brief documentation should be followed by an !. Otherwise, the +lines following the brief documentation are the full documentation, +which ends with the first !. The ! must be at the end of its line, +and should not be an excuse to omit punctuation for the last sentence, +since it will not be seen by the user. To put an ! in the text of the +documentation, use control-^. + + If you wish to refer to one or two character commands in the +documentation, you should not just put in the characters of the +command, since that would make the documentation wrong for users who +move their commands around. The thing to do instead is to put in the +full name of the function which you are referring to, surrounded by  +characters. When the documentation is printed out, this is replaced +by the name of the character which is connected to the function, if +there is one. If there isn't one, the function's name is used +instead. For example, you could use ^R Exit to refer to the command +to exit from a recursive edit, which in the standard environment can +be invoked with either Control-Altmode or C-M-C, and when the +documentation is printed it will say "Control-Altmode" or +"Control-Meta-C". The  construct cannot be used in the brief +documentation because only the command which prints the full +documentation knows how to process it. + + For even more flexibility in the documentation of a function, if the +string between the  characters starts with an Altmode, it is +considered a TECO program to be executed, rather than a function name +to be looked up. It does not undergo the same syntactic preprocessing +that the function definitions do;; spaces are represented as spaces, +not as underlines, etc. The TECO program can either print text out or +insert it in the buffer (from which M-X Describe will print it out). +When this TECO program is run, it receives the name of the function as +a postcomma argument (a string pointer) or the numeric code for the +character being described as a precomma argument, or both. A string +containing the command character sequence being described can be +passed as a precomma argument instead of a number. + +The Function Definition + + After the line ending with !, the next line contains the beginning +of the function definition proper. Usually, a blank line is put there +to improve readability. You must remember that the definition will +not be used as written, but will be processed syntactically first: all +spaces and tabs, except those following a ^Q, will be deleted. all +_'s not following a ^Q will be turned into spaces. !* is taken to +start a comment and everything from there up to and including the +following ! is deleted (again, a ^Q will prevent this). Double CRLFs +are converted to single ones. Normally, you should use ^]^Q to do +such quoting, since that is safe in all contexts. Inside search +commands and file commands a ^Q by itself is enough. + +TECO Mode + + The major mode TECO Mode is useful for editing EMACS source files. +Comments are defined to start with !* and end with !. Tab is set to +the command ^R Indent Nested, which normally moves the current line to +be under the previous line. With an argument, it takes the argument +to be the number of levels "up" to go, where up means a lesser amount +of indentation. Thus, Tab with an argument of 2 or more is good for +the first line after the end of a conditional or iteration. In +addition, unindented lines and lines containing only comments are +ignored. In addition, Meta-' is defined to move forward over a TECO +conditional, and Meta-" to move back. These commands ignore quotes +that are inside comments. + +File: CONV Node: Lib, Up: Top, Previous: Syntax, Next: Prog + +Library File Conventions + + The command Generate Library, in the library PURIFY, is used to +generate :EJ'able libraries from source files following the syntactic +conventions. The operation has two logical subparts: compression, +which removes spaces and comments, and extracts the documentation into +separately named functions; and purification, which converts the +intermediate form into a :EJ'able library. It is possible to divide +the source for a large library into several subfiles, which will be +compressed separately but purified together. This saves time if only +some of the subfiles are modified, since the compressed versions are +saved in separate files and reused if more recent than the sources. +Generate Library handles such multi-file sources automatically if all +the source files' names are given to it. + + One of the source files going into a library should define a +"function" named ~Filename~. The "definition" of this function should +be some kind of identification for the file. It should usually be the +same as the first filename of the library. The documentation for +~Filename~ should describe the purpose of the library as a whole. It +should NOT have a function class ("S", "C" or "^R") at the front. + + Generate Library automatically creates a ~Directory~ object which +contains a list of all the functions in the file. A library should +never contain two functions with the same name (~Filename~ is an +exception: see below). + + Sometimes it is desirable to merge several library sources into one +:EJ file. If you always like to use, say, TAGS :EJ, and have a +private library, you may save space and increase speed by including +the source of TAGS when generating your private library. This, +however, means that you need to be able to override the ~Filename~ +function which comes from the source of TAGS. Generate Library solves +this problem by deleting all but the first ~Filename~. Your private +source file must come first, and contain a ~Filename~, to override the +one in the TAGS source. + + Libraries intended to be accessed via the Run Library command should +contain a function named , which will be the default entry +point, so that the user need not specify the entry point name. In +addition, they MUST have a ~FILENAME~ which is identical to the actual +first name of the file, so that Run Library can tell whether the +library is already loaded. + + If a library contains a function named & Setup Library, +where is the library's ~Filename~ name, then whenever the +library is loaded with MM Load Library that function will be called. +It can be used to connect some of the library's functions to +characters, for example. If it is used for that purpose, then it +should allow the user to override it by setting up a named variable. +For example, the TAGS library has an & Setup TAGS Library function, +which defines Meta-. as a command. However, if the variable TAGS +Setup Hook is nonzero, & Setup TAGS Library executes that variable +instead of its default actions. Thus, a user's init file can specify +where the TAGS commands should go if TAGS is ever loaded, by defining +TAGS Setup Hook. + + If you wish, you can put a function called & Kill Library +in the library. If the library is killed with the Kill Libraries +command, this function will be called. A string pointer to the +library in core will be passed to it as an argument. The & Kill +function might try to remove pointers into the library from important +places where they were put by the & Setup Library function. +It is probably not worth while looking for characters which have been +connected to functions in the library, since this is painful and slow, +and the worst that can happen is that those commands will cause errors +when used. However, if pointers into the library were placed in +important FS flags, it may be essential to remove them if TECO is to +continue functioning properly. + + It is a good idea for an & Kill library function to +execute the value of Kill Hook if it exists and is nonzero. + + In addition to the names of functions, there are several names that +(usually or always) be found in libraries. For every function FOO, an +object named ~DOC~ FOO is available, that contains FOO's +documentation. In addition, ~DIRECTORY~ contains a list (one per +line) of all the functions that the file wishes to advertise that it +contains. Special things such as described in this section, and all +commands with ~ in their names, are not included. + + ~INVERT~ is supposed to be a function that is the inverse of the +loader function. That is, , fed to +the ~INVERT~ function should return a string containing the name of +the object. You should not have to be aware of ~INVERT~, because it +will be provided automatically, and called by & Macro Name when +necessary. + + The BARE library, which contains "definitions" for the sake of +documentation of the built-in functions used to define some command +characters, has a different loader function and so must be generated +in a special way. The command MM BARE Library +Generatesource-file-name will generate and write out the BARE +library. The difference in the loader function is simply that if a +function's definition is three characters long or fewer then it is +treated as the name of a command character (as in .^RA for C-A) and +that character's initial raw-TECO definition is returned instead. If +the function's definition as found in the ordinary way is longer than +three characters, it really is the definition. This way, +documentation strings act normally but the command names themselves +can return the raw TECO commands as their definitions. BARE has a +~INVERT~ function which knows how to find the names of raw TECO +commands as well as strings in the library. However, & Macro Name has +to know specially that such commands, which are positive numbers +rather than strings, should be passed to the BARE library to invert. + +File: CONV Node: Prog, Up: Top, Previous: Lib, Next: Buffers + +Programming Conventions + + For good programming practise, every CRLF that is not +part of a string argument should be followed by an indentation +to a position that indicates the current depth in iterations +and conditionals. Use of the Tab command will make this easy. + + Since the FS S ERROR flag is normally set in EMACS, searches that +are followed by ";" must always be given the ":" modifier; otherwise, +they will cause errors when they fail, before noticing the ";". This +is because, if FS S ERROR is not set, a user who types an iteration +in the minibuffer and omits the ";" is likely to cause himself extreme +lossage. The Tab TECO command is disabled in the EMACS environment, +and is a no-op. Use 9I or I^]^Q to insert a tab. + +Calling Subroutines + + Use named subroutines whenever convenient. The subroutine +should usually have documentation beginning with "S " +so that users doing a "List Commands" will not see it, and +a name beginning with "& " so that it will not interfere with the +user's attempt to abbreviate command names. +Call the subroutine with M( M.M&_Subroutine) (note the +_ is used to get a space). MM&_Subroutine would work, but +functions are not supposed to depend on having no-dot q-regs +set up. + + Use M.A to run a function in a specific library, loading the library +temporarily if necessary. For example: M(M.A DIRED& DIRED Enter) +calls the function & DIRED Enter in the DIRED library. M.A is +analogous to M.M. Both M.A and M.M accept a variable named MM Foo as +a definition of the function named Foo, and this takes precedence over +an actual definition of Foo in a loaded library. + +^R Mode + + The normal EMACS command level is precisely the TECO ^R command, +with characters redefined to run EMACS functions or user-supplied +functions. All of the information in TECORD on the ^R command, +facilities available for functions which are definitions of +characters, and what values should be returned by such functions, are +very important for anyone who writes functions which are to be placed +on characters. + +The Mark + + The mark is kept in TECO's "Ring buffer of point". It's value can +be obtained with :^V with no argument; :^V will push a new value +of the mark. ^V with no colon can be used to pop the mark (read TECO +ORDER for details). One consequence of this scheme is that there is +always a mark somewhere. Note that the C-W EMACS command POPS the +mark, rather than leaving a useless mark at point. + +Recursive Editing Levels + + A recursive editing level is implemented by the TECO command ^R. + Commands that call ^R on data that the user is likely not to regard +as "the thing he is editing" should do 0[..F before the ^R, to turn +off auto-saving, and inhibit window, buffer or file switching (either +of which would cause garbage results if allowed to proceed). See the +& Check Top Level subroutine. They should also bind the default +filenames to GAZONK .DEL, which will prevent the user from screwing +himself with a C-X C-W. + + No non-dotted Q-regs should be reserved by functions, except for +user interfaces like MM. Also, avoid using double-dot Q-regs except +as defined in TECORD. All temporary Q-regs should be pushed and +popped. All functions should return with ^\ if possible, except for +those like M.A which need to leave something on the stack to be popped +later. + +Numeric Arguments + + The TECO commands ^X and ^Y refer to the values of the precomma and +postcomma arguments. (A function invoked with a character command +gets only a postcomma argument). If there was no argument, the +default value (zero or one, depending) is returned. To find out +whether there was an argument, use F^XF^Y. +F^XF^Y"N succeeds if there was an explicit argument (C-U or +otherwise). This makes it convenient to use the function as a +subroutine, since then one can give it any argument to mean +"C-U", and no argument to mean "no C-U". F^XF^Y can also be used to +check individually for precomma arguments or postcomma arguments. + +The Mode Line + + Anything that changes information which is displayed in the mode +line should do 1FS MODE CHANGE so that FS MODE MACRO will eventually +be run to update q-register ..J and thus the mode line. + +Printing in the Echo Area + + The @FT command can be used to print in the echo area. To clear the +echo area, do :I*^PC FS ECHO DISP. The echo area is normally +cleared after each command which uses it. If you want to print in the +echo area and prevent the message from being erased after the command, +you must set FS ECHO ACTIVE to zero after printing the message. + +Reading Input + + Commands that read input should do M.I before actually doing the FI +to read a character of input. M.I is in charge of prompting. It also +supplies a definition for FS HELP MAC that will handle the Help +character if it is typed at that time. The user may redefine .I if he +wishes to eliminate prompting, but even so he should still define all +his functions to use M.I so that other users will receive the behavior +they want. For more info on using M.I, do M-X Describe& Prepare for +Input. + + M.I is useful for input read a character at a time. Other ways of +reading input are & Read Line, which reads a line terminated by a +Return, and & Minibuffer, which reads input allowing the user to edit +it in the minibuffer. See the code of those two functions for calling +conventions. + + The TECO command F^K allows a function to take a string argument if +called with M-X, or read a line if invoked with a character command. +Do 1,F^KFoo:_ to read the argument in whichever fashion is +appropriate, prompting with "Foo: " if the argument is read from the +terminal, and return a pointer to the string containing the value. +This can be followed with a [1 command to store the string in +q-register 1. + +File: CONV Node: Buffers, Up: Top, Previous: Prog, Next: Windows + +EMACS Buffer Data Structures + + An EMACS buffer is not the same thing as a TECO buffer object. A +TECO buffer an anonymous object which is a string stored in a special +way, so that it can be edited by the TECO program. It contains text, +the cursor location, and virtual boundaries, plus flags for modified +and read-only, and that is all. Selection is controlled by the +q-register ..O: whichever buffer object is put in ..O, that buffer +is the one edited by all TECO commands. An EMACS buffer is a more +complicated structure and a TECO buffer is just part of it. + + All information about EMACS buffers is stored in a qvector called +the buffer table, which lives in q-register .B. This table contains a +sequence of variable-length entries, each describing one buffer. The +first word in each entry is its length in words; the next 12 have fixed +meanings; the remained describe the EMACS buffer's local variables, 2 +words per variable. The index in words of the start of a buffer's +entry is called the buffer's index. The index of a buffer is needed +to access the components of the buffer's entry; but it can't be +expected to stay fixed while other buffers are selected, since a +buffer earlier in the table might have to make its entry larger to +create new local variables. Therefore, to remember one buffer for a +while, you must always use its name, not its index. Killing a buffer +that is not selected can change the current buffer's index! It knows +how to change the value of QBuffer Index if this happens. + + An EMACS buffer has, among other things, a name, a TECO buffer, a +major mode, and visited filenames. + + It also has a buffer number which identifies it uniquely from all +other buffers ever created earlier or later in the same EMACS. This +number is not the same as the buffer index. It is computed when the +buffer is created (by incrementing QNext Buffer Number) and +remembered while the buffer exists. + + A buffer also has some "TECO-default filenames". These are not the +same in meaning to the visited filenames, though often they are equal. +When the buffer is selected, these names are made the TECO filename +defaults. When the buffer is deselected, the TECO filename defaults +are remembered here for the next selection. + +Format of a Buffer Table Entry + +Each fixed word in the buffer table entry has a symbolic name. These +names are just comments, so the numeric offset must be used as well, +but the name helps clarify the code and makes it easier to identify +places that need to be changed if the entry format is changed. +For example, to refer to the name of a buffer whose buffer index is in +Q1, you would write Q:.B(Q1+1!*Bufnam!) + +Word 0: the length of this entry, in words. +Word 1!*bufnam!: the name of this buffer, a string. +Word 2!*bufvis!: the filenames visited in the buffer, a string, or 0. +Word 3!*bufmod!: the name of the major mode the buffer is in, a string, such as "LISP". + This may not be accurate for the buffer which is selected. +Word 4!*bufbuf!: the TECO buffer used to hold the text. +Word 5!*buftdf!: the TECO-default filenames remembered for this buffer. + They are 0 in a buffer that has never been selected. + This is not accurate for the buffer which is selected. +Word 6!*bufwin!: the FS WINDOW associated with the buffer. + This is not accurate for the buffer which is selected. +Word 7!*bufnum!: the buffer's buffer number. +Word 8!*bufdat!: the creation date of last file visited or saved. + This is used to give the warnings about files changed + on disk since they were visited. +Word 9!*bufver!: the version number of the last file read or written. +Word 10!*bufsav!: controlls auto-save for this buffer. Zero if no + auto saving. If 1, auto save as the visited file name. + Otherwise it should be a string which contains the names to + save as. +Word 11!*bufsiz!: the size of the buffer at the time of the last visit + or real save or auto save. +Word 12!*bufnwr!: the read protection flag for the buffer. + Positive means the buffer can be changed but the file cannot + be saved unless you insist. Negative means the buffer cannot + be changed. +Word 13!*buflcl!: the beginning of the local variables of the buffer. + +Words 13,14: these describe one local variable of this buffer. + Word 13 is the string which is the variable's name. + Word 14 is the value. When the buffer is selected, this is + the global value. When the buffer is not selected, this is + the local value. The TECO command F^G is used for swapping + the local and global values of variables. +Words 15,16: the next local variable, etc. + + +The Current Buffer + + The index of the current buffer is kept in QBuffer Index. All +information about it could be obtained from that through the buffer +table. However, the most important information is kept redundantly in +variables to be convenient to access. The name of the buffer is kept +in QBuffer Name, and the visited filenames are in QBuffer +Filenames, which will be zero if no file is visited. The current +major mode is in QMode, but looking at the name of the mode is +usually the wrong way to do something. The TECO buffer of the current +EMACS buffer can normally be found in ..O. + + Switching between EMACS buffers officially is slow. For specific +temporary purposes, it is often enough to put an EMACS buffer's TECO +buffer object into Q..O temporarily so that the text of the buffer can +be manipulated. This is how Kill Some Buffers lets you examine a +buffer that you might want to kill. + +Special Purpose Buffers + + Often an EMACS subsystem will need to store data permanently. +Sometimes it is convenient to create a special EMACS buffer for this. +For example, TAGS keeps the tag table in a buffer called *TAGS*. This +allows the EMACS file visiting operations to be used as subroutines by +Visit Tag Table. It also allows the tag table to be selected by the +EMACS user when he wants to examine it. + + Since M-. needs to look at the tag table, for efficiency a redundant +pointer to the TECO buffer object of the *TAGS* buffer is kept in a +variable. This saves M-. from having to search for the *TAGS* buffer +in the buffer table. + + The convention for such special purpose buffers is that their names +start and end with stars. + +The Previous Buffer + + QPrevious Buffer contains the name of the buffer selected before +the current one. C-X B will use this as the default buffer to select. + +Searching the Buffer Table + + To refer to a buffer given its name or its buffer number, it is +necessary to search the buffer table, which contains the entries of +the buffers in order of creation. The subroutine & Find Buffer does +this. & Find File searches for a buffer visiting a given filename. +In either case, the buffer index is returned. + +File: CONV Node: Windows, Up: Top, Previous: Buffers, Next: Complete + +Data Structures for Two Window Mode + + TECO can only deal with a single display window. When EMACS is in +two window mode, TECO is just displaying one buffer in a small window. +Only one EMACS buffer is selected, as always. Various information +about the buffer in the other window is remembered in a special set of +variables. Some information is kept which overrides what is +remembered in the buffer table, so that it is possible to select the +same buffer in both windows with different values of point, for +example. + + When in two window mode, each window has several variables +describing its contents. Some of them are set up only when the window +is not selected; some are always valid. For window one, these are: + +Window 1 Buffer the name of the EMACS buffer in window 1. +Window 1 Window the FS WINDOW setting for window 1. Valid only when + the window is not selected. +Window 1 Point the value of point in window 1. Valid only when the + window is not selected. +Window 1 Size the height of the window, in lines. + + Window two has a similar set of variables. These variables stay +around when two window mode is left, so that if it is used again +things can be as they were before. To get information about either +window 1 or window 2, deciding which one at run time, put either +character (1 or 2) in a q-register such as Q1 and look at +QWindow_1_Buffer, etc. + + In addition, there are these variables: + +Other Window Buffer + the TECO buffer object of the EMACS buffer in the + other window. +Total Size the total size of the two windows plus the line + between them. +Default Size the setting of FS LINES in one window mode, saved + here while in two window mode. + + To tell whether two window mode is in effect, see if QWindow 2 +Size exists. If it does, two windows are being shown. This variable +can be killed with no loss of information when reentering one window +mode because its value can be deduced from QWindow 1 Size together +with QTotal Size. When two window mode is in effect, to tell which +window is selected, use FS TOPLINE. Window 1 is selected if it is +zero. + + Redisplay of both windows when EMACS is continued is done by putting +& Multi-Window Refresh in FS REFRESH. This uses the variable QOther +Window Buffer to redisplay without having to do an EMACS buffer +switch. + +File: CONV Node: Complete, Up: Top, Previous: Windows, Next: Vars + +Completion + + Completion is the feature whereby, when a command name is being read +in, Altmode and Space cause the appearance of characters determined by +the ones already read. It is possible to provide completion when +reading something other than a command name. Here is how. + + The basic way to read something with completion is to use the F +command with the 8 bit set in its precomma argument. For example, + + 8,F Command:_ + +reads a command name with completion and returns it as a string. + + To read something other than a command name, you must supply a table +of allowed strings. This table has the same form as the variable +table (that which lives in Q..Q): it is a qvector whose first element +is a number, the number of elements per entry, and whose following +elements are any number of entries. The first element of each entry +should be the string which is the name of the entry. + + For completion's sake, it does not matter how long the entries are, +since only the name of each entry is used. The table can have one +element per entry, if its only purpose is completion. It can have +more than one element per entry if you wish. For example, the actual +variable table itself, which has three elements per entry, can be used +for completion of variable names. + + Specify the table to be used for completion by putting it in the +variable CRL List before doing the F , and setting the 2 bit in the +argument to the F . Thus, + + Q..Q[CRL_List + 12.,F Variable_to_frobnicate:_ + + To allow the user to specify names which are not in the table, turn +on the 20. bit in the precomma argument. If this bit is set, the user +can type any string at all, followed by Return, and it will be +accepted. Only if the user types Altmode will it be rejected. +Normally, Return also rejects any string which is not in the table. +If you like, you can use Linefeed to specify names not in the table, +and make Return continue to insist on an existing name. To do this, +set the variable CRL Non-match Method to 4. (The normal behavior is +obtained with the value 2). + + The 40. bit in the precomma arg says that Return should be allowed +as the first character typed. An empty string is returned as the +specified name. + + You can additionally restrict completion to those names which start +with a prefix, at the same time making the prefix invisible to the +user (he does not have to type it, and does not see it echo). For +example, suppose your library LOSER uses variables with names such as +LOSER Object FOO to represent LOSER's definition of the object FOO. +Then you can read the name of a LOSER object with completion by doing + + :I*LOSER_Object[CRL_Prefix + Q..Q[CRL_List + 12.,F LOSER_Object:_ + + Then only variables with names starting with LOSER Object will be +considered. The user can type F and complete it to FOO; he does not +see the "LOSER Object" as part of the string, and just "FOO" is +returned. + + You should set the variable CRL Name Type to a string which +describes what sort of name is being read. It is used as part of the +message printed if the user asks for help while typing the name. + + The value of CRL Help is printed as additional help, after the +standard completion help, if that variable is not zero. + + The hook CRL Name Lister allows you to customize the display done +if the user types "?" to list the possible completions of what he has +typed. It is called at two different times, with arguments to allow +it to distinguish the reason it was called. + + For each possible completion, the CRL Name Lister is called once, +with a postcomma arg which is an index into the table in CRL List. +That table is also in Q.1 at the time. The function should insert +information about that name into the buffer beginning at point, and +include a CRLF at the end. + + The function CRL Name Lister is called again after all the possible +completions have been processed. This time it will receive 1 as a +precomma arg. The text previously inserted in the temporary buffer +for all the alternatives is still there. The function might take the +opportunity to sort the list of names, or insert a heading. + +File: CONV Node: Vars, Up: Top, Previous: Complete, Next: Major + +Named Variable Conventions + + EMACS makes extensive use of named variables, and provides features +for creating, destroying, editing, and listing them. + + The basic way of getting the value of a named variable that already +exists is to do Q. See TECORD for details. If you are +not sure whether a variable exists, you can do FO..Q  +which will return the value if the variable exists, or if +the variable does not exist. :FO can be used to tell whether a +variable exists. Any TECO command that can use a q-register, except +for ^], can also use an existing named variable if it is given the +name of the variable, surrounded by Altmodes, as the q-reg name. +Although TECO allows unambiguous abbreviations of the name to be used, +it is unwise to use abbreviations in a program. + + To create a variable, do M.V. Unlike Q and FO, M.V +deliberately does not handle abbreviations. It does discard leading +and trailing spaces (in a library source file, spaces and tabs are +deleted anyway, and to get a real space you must use "_"). If the +variable already exists, nothing will happen, but its value will be +returned. If it does not exist, it will be created with a value of 0, +and 0 will be returned. + + M.V can also be used. This creates the variable if it +doesn't exist, but also in any case sets its value to . The +value returned by the M.V will be . + + To give a variable a comment, use M.C. This sets +the variable's comment to , creating the variable first if +necessary. M.C will set the variable to + if it creates the variable. It will not change the value if +the variable already exists. This is NOT the same as what M.V does! +What M.C does is good for defaulting variables which are options, +whereas what M.V does is good for setting a variable for internal use +while making sure that it exists. M.C's value is the value of the +variable. + + Sometimes it is more efficient for changing a variable's value to +redefine some command characters, instead of having one definition +which always checks the value of the variable. Do this by providing a +function to be run whenever the variable's value is changed. This function +is supplied by making it the variable's comment. Whenever the comment +begins with a "!" it is taken to be a function to be run in this manner. +The function is given the variable's new value as an argument. For +example, the comment could be "!! FS^rmdly" to copy the variable's +value into the FS ^R MDLY flag. This is (approximately) what is used +for the variable Auto Save Interval. + + If you want a variable to be presented for editing by MM Edit +Options, you should give the variable a comment which starts with a +"*". If the variable is to have a function to run when it changes, and +so the comment must start with a "!", then the variable is an option +if the comment starts with "!*". NOTE: if you are not careful, the +TECO code to set up such a variable will contain "!*" which will be +taken as the beginning of a comment. Leaving a space (which will be +removed by compression) between the "!" and the "*" will prevent such +lossage. See where the file EINIT sets up such variables if this +isn't clear. + + You can examine the value, and comment if any, of a variable by +doing MM Describe, just as you would ask for the documentation +of a function. + +Overriding Command Definitions + + You can override the library definition of a function by defining +a variable named "MM " followed by the function name. M.M checks for +such a variable before looking the name up in the loaded libraries. +MM Compile installs the compiled function in just this way. A few such +MM variables are present in the default environment. This is to make +calling certain key subroutines more efficient; M.M takes less time +finding the variable than searching the libraries. + +Listing and Killing Variables + + To see a list of all existing variables, do MM List Variables with +a null string argument. Each variable's name and value (abbreviated +if too long) will be shown. A list of variables whose names contain + can be seen by doing MM List Variables. + + To destroy a variable, do M(M.M Kill Variable) to run +MM Kill Variable. This is necessary only in special situations. + +Local Variables + + Variables can be local to an individual buffer. To make a variable +local to the current buffer, do M.L. From then on, +setting the variable when the current buffer is selected will not +affect its global value, which other buffers will continue to see, +nor will changing that global value affect the local value. Each +buffer in which the variable is made local has its own value for the +variable, while all other buffers share one global value. +Doing M.L has the side-effect of creating the variable globally +with the value of 0 if it did not already exist globally. Local +variables will be created automatically when a file is visited which +contains a local modes specification at the end. They are also the +way in which major modes perform their redefinitions. + + Not only variables, but q-registers as well, and command +character definitions, can be made local. To make a q-register +local, use the Make Local Q-register command, with the q-register name +as a string argument: M(M.M Make Local Q-reg)A makes QA local, and +M(M.M Make Local Q-reg).^RF makes the definition of Control-F local. +You can also make a TECO FS flag local by specifying "FS" followed by +the name of the flag as the "q-register" name. For example, M(M.M +Make Local Q-register)FSCTLMTA. Inside Major Mode functions, this +function is available as M.Q. + +Temporary and Permanent Locals + + There are two types of local variables: permanent ones and temporary +ones. The permanent ones have to be the first on the list; they +remain forever local in the buffer that has them. All others are +temporary; these disappear when you switch major modes. The locals +created by major modes are temporary, which is how one major mode gets +undone when a new one is selected. Other locals created by local mode +lists and by random use of M.L are also temporary. + + The initial buffer is given a set of permanent local variables when +the EMACS environment is built. The way permanent locals are told +from temporary ones is that the number of permanent ones is kept in +the variable QInitial Local Count, and the first that many locals +are permanent. + + When a new buffer is created, some or all of the locals of the +previously selected buffer are copied into it. If Default Major Mode +is empty, they are all copied (thus, the major mode is copied). If +Default Major Mode specifies a mode, then only the permanent locals +are copied into the new buffer. The value of Initial Local Count is +used to tell how many there are. Some of these locals are +reinitialized, however; and you can reinitialize others in the Buffer +Creation Hook. + + To add a new permanent local to a buffer, use 2,M.L. This +adds a local at the front of the list instead of at the end, and +increments the value of Initial Local Count (which requires making IT +into a permanent local as well, if it isn't one already, but that +happens automatically). + + To increase the set of permanent local variables of all buffers, you +can simply create a few locals in your init file with M.L and then +increase QInitial Local Count. This will give the initial buffer +extra locals, and all other buffers will get them through the copying. +To do this for all users at your site, you can modify & Load Essential +Environment at the end where it creates the standard set, to create a +few extra. + + You can also cause each buffer to get extra permanent locals when it +is created, in the Buffer Creation Hook, by using 2,M.L inside it. + +File: CONV Node: Major, Up: Top, Previous: Vars, Next: Submodes + +Defining Major Modes. + + Each major mode is embodied by a command, such as MM TECO Mode or +MM Lisp Mode. A major mode can be created simply by defining an +appropriate command. However, major mode commands must work in a +particular way. + + Major modes make all their redefinitions by creating local +variables. This is how each buffer can have its own major mode. +Buffer switching does not consciously "switch" modes; it just swaps the +local variables, which has that effect. + + The first thing which each major mode command must do is eliminate +the local variables, if any, made by the previous major mode. This is +done by calling M(M.M &_Init_Buffer_Locals). All local variables of +the current buffer, except those made when the buffer was created, are +killed, and the global values reassert themselves. In addition, & +Init Buffer Locals leaves Q.Q bound to the Make Local Q-register +command until the major mode command returns with . + + Then, the major mode function should create any local variables and +local q-registers that it wants. Supplying a 1, argument to M.L +causes M.L to run much faster, assuming that the specified variable is +not already local. Example: 1,(:I*;) M.L Comment_Start. This is +recommended for cuatious use by major mode commands. Command +characters can be redefined by using M.Q, since character definitions +count as q-registers. Example: M.M ^R_Indent_for_Lisp M.Q ^^I makes +the Tab character local to the current buffer, and redefines it for +Lisp. The "1," argument can be used with M.Q also. + + Many major modes have their own values of the delimiter dispatch +table Q..D. They construct these values by making Q..D a local +q-register, copying the value of Q..D that is lying around with +:I..D..D, and then changing the necessary entries with the +command MM & Alter ..D. This is so that any other changes to ..D made +by the user will not be discarded. A new ..D should be constructed +only the first time a mode is entered. It should be saved in a +variable such as Text ..D or Lisp ..D, and retrieved from there when +the mode is entered again. This way, if the user changes ..D with the +command Edit ..D, his changes remain in effect whenever he is in that +mode. He can also define the variable in advance in his initfile if +he knows that, whenever he is in a certain mode, he wants his ..D to +be just so. + + Finally, the major mode function should do + + 1M(M.M &_Set_Mode_Line  ^\ + +& Set Mode Line makes the new mode appear in the mode line, and the 1 +as argument tells it to do everything else appropriate for finishing +up the change of major mode: Setting the variable QMode, running +the value of Mode Hook if it is defined. + + Exiting with ^\ causes the binding of Q.Q, left by & Init Buffer +Locals, to be popped, as well as any other bindings made by the major +mode function. + +File: CONV Node: Submodes, Up: Top, Previous: Major, Next: Prefix + +Submodes and ..F + + A submode is just a command which rebinds commands or variables and +then calls ^R recursively on the same buffer. A submode's name +usually starts with the word "Edit", as in "Edit Picture". Submodes +are to be distinguished from commands such as Edit ..D which call ^R +recursively on some other text. + + For submodes to indicate that they are active, the variable Submode +is provided. Binding QSubmode to FOO causes [FOO] to appear in the +mode line after the name of the major mode. However, you must call +& Set Mode Line yourself before entering ^R, and you must do an FN +command to cause & Set Mode Line to be called on the way out (even if +you come out via a throw or an MM Top Level). Usually, the Edit FOO +submode will put FOO in the Submode variable. + + Submodes need not bind ..F to zero. Because the buffer is not +bound, it works reasonably well to switch files, buffers or windows +inside a submode. However, you stay inside the submode when you +switch, which you may not like. Someday there may be a different +implementation of Submodes which makes them local to a buffer. In +fact, submodes are not fully worked out at this time. + +File: CONV Node: Prefix, Up: Top, Previous: Submodes, Next: Hooks + +Defining Prefix Characters. + + An EMACS environment can contain any number of prefix characters, +although EMACS normally contains only one - C-X. + + To define a prefix character, you must choose a place to put the +dispatch table for it. This can be a q-register or a variable. Call +MM Make Prefix Character which returns a string which is +a definition of a prefix character which will look in the specified +q-register for the dispatch table. Then put this string into the +desired character's definition. Normally, dispatch tables are made 96 +characters long. If you want Rubout to be available as a subcommand, +you must make it 128 characters long, which you can do by providing +128 as an argument to Make Prefix Character. + + For example, a prefix character C-Y can be defined to dispatch +through q-register .Y by doing + + M(M.M Make Prefix Character).Y U.Y + +After this, you can define individual subcommands by doing things like +M.MFOO U:.Y(A) which puts MM FOO on C-Y A. + + To use a variable to hold the dispatch table, first create the +variable using M.V. Then create the prefix chararacter definition by +calling MM Make Prefix Character, supplying the variable name +surrounded by quoted altmodes in place of a q-register name. For +example, + + M.V My Prefix Table + M(M.M Make Prefix Character)My Prefix Table U.Y + +The altmodes are quoted by  characters so that they become part of +the argument to Make Prefix Character. + +How Prefix Characters Dispatch. + + All prefix characters made by Make Prefix Character, including the +initially present C-X, do their work by calling the contents of +q-register .P, providing the dispatch table as an argument. .P reads +the input character, extracts the definition of the subcommand, and +returns it. The prefix character itself then calls whatever .value P +returns. You are free to redefine .P to get different behavior, as +long as you respect the interface conventions. Take a look at the +source code for & Prefix Character Driver, which is the default +contents of .P. + + +Making Self-documentation Work for Prefix Characters. + + In order for Where Is and Apropos to list all the ways a command can +be reached as a subcommand of a prefix character, all prefix +characters must be listed in QPrefix Char List. The value of this +variable is a string containing one line for each prefix character. +first on the line comes the way this prefix character should be named +when a command character is printed out (for example, "Control-X"). +This is followed by two spaces (two, so that single spaces can be part +of the string to be printed) and a TECO expression which evaluates to +the dispatch table. For the default EMACS Control-X command, the +value of the string is "Control-X Q.X". + +File: CONV Node: Hooks, Up: Top, Previous: Prefix, Next: Novice + +Hooks Provided by EMACS + + EMACS offers several hooks in the form of variables whose values +will be executed, if nonzero, at specific times. + +Buffer Creation Hook + + This variable is executed when a new EMACS buffer is made by Select +Buffer, just after that buffer has been selected. If you wish to use +this to create local variables, you should see under "Temporary and +Permanent Locals" in *Note Locals: Vars. + + The Buffer Creation Hook is not run when a buffer is created by +Append to Buffer. This is obviously wrong, but since the buffer thus +created is never actually selected, there is no easy way to fix this. +However, if the buffer is eventually selected, the Buffer Creation +Hook will be run then. + +Buffer Selection Hook + + This variable is executed whenever a buffer has just been selected. +It is most likely to be useful when made local to a particular buffer. + +Buffer Deselection Hook + + This variable is executed whenever a buffer is just about to be +deselected. It is most likely to be useful when made local to a +particular buffer. + +Visit File Hook + + This variable is executed whenever a file has been visited. All the +normal actions of visiting are already complete. It is also called +when the name of the visited file is changed by the commands Write +File and Set Visited Filename. In that case (change of name but the +text is not newly read in) an argument of 1 will be passed to the +function in Visit File Hook. In the case of actual visiting, the +argument will be zero. + +Exit Hook + + This variable is executed by the function & Exit EMACS, which is +called when EMACS is about to be exited other than momentarily. This +is in addition to auto saving and possibly a real save. A useful +thing to put in this hook might be MM Save All Files, if you want +that. + +Exit to Superior Hook + + This variable is executed by ^R Return to Superior after it calls +& Exit EMACS, but before it actually returns to the superior. + +Return from Superior Hook + + This variable is executed by ^R Return to Superior after EMACS is +continued by the superior. + +Exit to Inferior Hook + + This variable is executed by various Twenex-only commands that +invoke inferior forks, before they do so. + +Return from Inferior Hook + + This variable is executed by various Twenex-only commands that +invoke inferior forks, on return from the inferior fork. These +commands all run Exit to Inferior Hook before invoking the inferior. + + Not all commands which invoke inferior forks run the two hooks. If +the fork is expected to return almost immediately, then the hooks are +not used. If the fork is expected to run indefinitely then the hooks +are executed. + +Compile Command + + This variable is executed to perform the compilation of the visited +file. It can find the filename in q-register 1, and it MUST exit with +. + +After Compilation Hook + + This variable is executed by M-X Compile after the compiler returns +to EMACS. The Return from Superior Hook or Return from Inferior Hook +is NOT executed. This hook only applies if Compile Command has not +been specified. + +Set Mode Line Hook + + This variable is executed by & Set Mode Line. When it is called, +the buffer contains the first part mode line as it is going to appear, +everything up to just before the closeparen. The Set Mode Line Hook +can insert text in the buffer to get it into the mode line at that +point. The purpose of this variable is to allow libraries which have +state variables to display them in the mode line. So that several +libraries can do this without interfering with each other, each +library should append its own hook to the variable Set Mode Line Hook +instead of setting it. + + When Set Mode Line Hook is called, the currently selected TECO +buffer (which normally belongs to the selected EMACS buffer) can be +found in Q8. + + Setup Hook + + Each library's & Setup Library function should check for +the existence of a Setup Hook variable, using 0FO..Q. If +the variable exists and is nonzero, the setup function should execute +the variable INSTEAD of its normal actions. + + Mode Hook + + Each major mode executes a mode hook variable after making its +normal redefinitions, but before updating the mode line. Mode hooks +can create additional local variables or local q-registers (including +local character command redefinitions). + +Hooks on Variables + + Each variable can have a hook to be executed when it is set. The +hook is stored in the variable's comment: if the comment starts with +an exclamation mark, then it is executed when the variable changes, +and the new value is supplied as an argument. The hook does not need +to change the actual value of the variable; that is done +automatically after the hook is finished. Unfortunately there is no +way for the hook to change the value of the variable. + + Sometimes you want the hook for each of two variables to change the +other. To avoid an infinite recursion in hooks, bind F[VARMAC to +zero in each hook before setting the other variable. + + If you want the variable to be an option also, the exclamation mark +can be followed with a star, followed by the real comment. + +File: CONV Node: Novice, Up: Top, Previous: Hooks, Next: Dump + +Creating Restricted EMACS Subsets for Beginners. + + When dealing with large communities of beginning users, it is +sometimes desirable to give them limited subsets of EMACS, in which +commands that they are unlikely to want to use and might be confusing +to them are not allowed. This could be done simply with an init file +that redefined those commands to be undefined; however, this would +prevent the beginners from learning to use those commands. The NOVICE +library solves this problem by allowing the user to read about, +experiment and eventually re-enable the commands that were initially +disabled for him. + + To set up a limited EMACS subset with NOVICE, the biggest piece of +work is to decide which commands you want to allow. Then you must +create the user's command profile, a file which says which commands +are enabled for him. This file contains 512 characters, one for each +EMACS command character, and each character of the file should be an +"E" to enable the EMACS command or a "D" to disable it. The file +should be named ; EPRFIL on ITS, or EMACS.PROFILE +on Twenex. + + Finally, you must make the user's init file load and invoke the +NOVICE library. This can be done with + + M(M.M Load Library)NOVICE + M(M.M & Load Disable Profile) + +Alternatively, the default init file at your site could do the work: + + FS :EJPAGE[1 !* Remember what libraries we have.! + M(M.M Load Library)NOVICE !* Load this library.! + M(M.M & Load Disable Profile)"E !* try to process profile.! + Q1FS:EJ PAGE' !* If there is none, flush NOVICE.! + ]1 !* restore q-reg 1.! + +This discards the NOVICE library if it says that it does not find a +profile file for this user. + + One way to create a profile file is to edit it with NOVICE. Load +NOVICE and then use the command Disable Commands to turn off some +commands. This creates or modifies a profile file for you +automatically. To turn commands back on, try using them and answer +the questions appropriately. This also edits your profile. When you +are done, give a copy of that profile to the user you made it for. +You will probably want to delete the original! + +File: CONV Node: Dump, Up: Top, Previous: Novice, Next: Build + +Dumping an EMACS Environment. + + Dumping an EMACS environment so that it can be loaded and run again +is no simple feat. Since the environment, when dumped (with @EJ), +contains absolute pointers into the main EMACS library, we must make +sure that when the environment is run again the same version of that +library will be at the same place in the address space. This is +accomplished by the Dump Environment command in the PURIFY library. + + The Dump Environment command in the PURIFY library has the ability +to dump out an EMACS environment so that, when loaded, it will reload +the same libraries that were loaded at dumping time - the same +versions, even, if multiple versions of the libraries are maintained. +Before calling Dump Environment, you must decide which of the loaded +libraries are to be reloaded by the dump file. Given such a library, +called (say) "Mumble", you must set up a variable QMumble Library +Filename containing the filename to be used to reload that library. +This filename can contain a version number, if you are interested in +loading the same version as the dumped environment was made with (this +is necessary if any pointers to functions in that library exist in +q-registers or character definitions, etc.). +Only libraries for which such variables are created will be reloaded +by the dumped environment. Not all loaded libraries must be included, +but any which are not included must all have been loaded after the +ones which are included. + + In addition, before calling Dump Environment you must specify the +TECO commands to be executed when the dump file is reloaded. This is +done by creating a variable named QMM & Startup Mumble, where Mumble +stands for the contents of QEditor Name. For EMACS, it is called +QMM & Startup EMACS. The QMM & Startup Mumble variable is killed +by Dump Environment, since it will be no use afterward. Actually, if +you wish, you can have a command named just & Startup Mumble in one of +the libraries to be reloaded by the dump file, instead. + + The contents of q-register ..L when Dump Environment is called are +NOT used to initialize the dump file when it is reloaded. However, +they do persist in ..L when the reloaded dumped environment is +running, and if that job is stopped and restarted again, the ..L will +be used. + + EMACS actually happens to make MM & Startup EMACS the same as ..L, +despite all the emphasis above on allowing them to be different. ..L +and & Startup EMACS both point to the function & Toplevel ^R, which +simply enters the TECO real-time editing mode. The user's init file +is executed after entering real-time editing. When the outermost +level of ^R mode is entered, the hook variable *Initialization* is +executed if it is nonzero, and also set to zero. Thus, it is only +done the first time the top level ^R is entered. When EMACS is +dumped, *Initialization* contains the TECO code to find, read and +execute the user's init file. The code to implement this is in the +TECO init file for EMACS, and in & Recursive ^R Set Mode. + + If your EMACS init file takes a long time to run, you can use Dump +Environment yourself after running the init file. The QEMACS Library +Filename variable remains set up, so you need not worry about getting +the right version of it. You must create similar variables for any +other libraries you want loaded when the dump is restarted (Load +Library can make them for you automatically). Just provide a suitable +variable MM & Startup EMACS (or make that variable a copy of Q..L and +supply *Initialization*), and call Dump Environment. + + If you do this, it is best not to call the default init file +from your own init file, but instead call it from the & Startup or the +*Initialization* variable. This way, various actions will be +performed when the dump is started, based on the terminal type, user +name and command string that you have at that time, rather than being +done when you build the dump, based on the terminal type, user name +and command line at the time the dump was built. + +File: CONV Node: Build, Up: Top, Previous: Dump, Next: Wall Charts + +How to Build and Dump a New EMACS + + Before building a new dumped EMACS, you may wish to Generate +up-to-date versions of the essential libraries. This can be done by + + M-X RunEINIT? Generate + +However, there is no need to do this if the new versions of functions +to be changed are present in the patch files (see below). + + The visible procedure for building a new EMACS is simply to do + + EMACS + :NTECO + +which runs NTECO using EMACS's TECO init file. On Twenex, simply run +TECO while connected to . This leaves you in the +TECO top-level loop, typing TECO command strings, and should display +an EMACS-style mode line. Then, to dump the EMACS, type + + MMRunPURIFYDump + +which will dump the environment you have built. Then kill the job. + + +How Building and Dumping Work + + Building a new EMACS environment has three phases: loading +libraries, creating the "essential environment" necessary for EMACS +functions to work at all, and making the default set of command +bindings. Two other minor operations are the loading of the patch +file, and the purification of variable names. The first phase is +straightforward: it simply loads the latest version of EMACS :EJ, and +also the EINIT library which contains the code for performing the rest +of the initialization. + + Loading the essential environment is done by the & Load Essential +Environment command in EINIT. This sets up things like q-registers +.M, .L, .V, .A, etc. as well as the option variables which many +commands assume the existence of. Part of loading the essential +environment is loading the patch file EMACS;PATnnn >, which contains +corrected versions of functions changed since EMACS :EJ was generated. +nnn stands for the version number of EMACS; thus, different versions +can coexist with different patch files. The format of PATnnn is just +that of a library source file, with a function on each page. It is +read in and MM TCompile is done on each page of it. Thus, the +function definitions in the patch file exist as impure strings which +override the definitions in the library. Another file named +EMACS;PATCH > is also loaded. This file is intended to have site +specific changes, which are not generally expected to become obsolete +in the next version, wheras PATnnn's fixes will all be incorporated +therein. + + Loading the default EMACS environment is done by & Load Default +Environment in EINIT. This is what defines C-N to run ^R Down Real. +The reason why it and & Load Essential Environment are not combined is +so that other command environments which use the EMACS execution +environment can be easily built. Building such an environment would +involve calling & Load Essential Environment, and then using something +else instead of & Load Default Environment. Also, loading the patch +files requires using the essential environment, and must precede +loading the default environment so that the command character +definitions use the patched versions of functions instead of the +original versions. + + At the end of building the environment, the variable names are +purified. In order to save a few hundred words of impure core for all +users, the predefined variables' names and their comments are made to +live inside EMACS :EJ instead of in impure string space. The +necessary strings are created in the library by the special file VARS, +which is included in the generation of the library. It inserts the +strings into the EMACS :EJ file inside of another string, so that they +are conveniently out of the way. Then, the Purify Variables command +in EINIT is used to look at each variable and replace its impure name +with the corresponding pure string, if there is one. + + +How Stand-alone RMAIL and INFO are Built and Dumped. + + Stand-alone INFO differs from an EMACS in that, on start-up, instead +of running the user's or the default init file, a particular procedure +(that of entering ^R-mode and then running MM INFO) is followed. +INFO is built by an EMACS init file which calls Dump Environment, +setting Editor Name to INFO and providing an appropriate MM & Startup +INFO function to be used to start up the dump file when it is reloaded. +On the practical level, the EMACS init file for INFO actually +dumps the INFO, instead of returning and letting the user dump it. + + Stand-alone RMAIL differs from INFO because it is presumed that since +users will be doing things such as editing replies from Rmail, he probably +wants his EMACS init run. Therefore the program TS RMAIL actually just +loads an EMACS into itself, passing it the JCL string 2,MMRMAIL. The +argument of 2, is merely used to instruct Rmail to kill the job upon exit, +instead of returning into Emacs. The MM RMAIL command in Emacs just runs +the Rmail library, which by convention on ITS is kept in EMACS;[RMAI] >. +Effectively users could just as well enter EMACS themselves and run Rmail. +TS RMAIL is only there because many people seem to prefer thinking of it +as a different program. + + The TRMAIL command is a version of RMAIL that runs in a bare Teco ^R +environment. It exists purely because RMAIL used to run that way +itself, and some RMAIL users who are not EMACS users want it that way. +TRMAIL must be dumped by a TECO init file to avoid getting the Emacs +character command definitions in the dumped library. The file +AI:EMACS1;RMAIL TECO must be loaded into a bare teco and executed to +do this. + + New versions of stand-alone TRMAIL and INFO must be made for each new +TECO or EMACS version, just like new versions of the EMACS dump file. +The stand-alone TRMAIL and INFO always load up the current version of +the RMAIL and INFO libraries, rather than the version which was +current when they were dumped, so new TRMAIL and INFO dump files do not +generally need to be made when new versions of those libraries are +installed. + +File: CONV Node: Wall Charts, Up: Top, Previous: Build, Next: Abstracts + +Making Wall Charts + + Wall Charts are made by MM RunABSTRWall Chart +with an empty buffer. This produces a wall chart in the buffer, +describing the environment as it exists. is a list of +names of prefix characters, each of which should get a page describing +all of its subcommands. The prefix characters are named as if you +were accessing their definitions as q-registers, such as ".X" for +C-X. The names should be separated by Altmodes. Two Altmodes end the +list of prefix character names. + + +Writing the Documentation Files EMACS CHART and EMACS DOC. + + These two files are produced from the self-documentation strings +within EMACS by the functions in the library ABSTR. Simply doing + + M-X RunEINIT? Document + +will update them according to the current environment. Make sure that +you do this as a user who does not have an init file! Otherwise, the +files will reflect your command definitions rather than the default. + +File: CONV Node: Abstracts, Up: Top, Previous: Wall Charts, Next: Qregs + +Library Abstracts, Source Listings and Source Indexes + + Library Abstracts are a form of automatically generated +documentation files for libraries. Source listings and indices are +files useful in hardcopy form for studying code. This node tells +about making all three. + + An abstract of a library is a file of the documentation of all the +commands in the library. Abstracts are useful for documentation of +the library. They can follow the order of the functions in the library +itself or can be alphabetized. + + To make an abstract, load the ABSTR library and then call either +Abstract File or Alphabetical Abstract. Abstract File makes an +abstract using the order functions appear in the library sources; +usually this order is a logical classification of the functions if the +sources are arranged carefully. It takes three arguments; a name +prefix, a documentation prefix, and the library name. The name prefix +and documentation prefix are used as filters; only functions whose +name and documentation start with those prefixes are included in the +abstract. The prefixes can be null. + + Alphabetical Abstract takes just a library filename as its argument, +and abstracts all functions in the library. The functions are first +sorted by documentation class (S, C or ^R) and then alphabetically +within each class. + +Listings of TECO Code + + There are two ways to make a listing of TECO code. + + One is the function @ TECO, in the PURIFY library. This function +takes the library file name as a string argument and writes an XGP +listing as ; XGP. You can supply a font +name as a second string argument and a number of lines per page as a +numeric argument. + + If you don't have an XGP or anything that can print XGP files, you +can use instead two functions in the TMACS library. Load the TECO +source file into EMACS, then do M-X Run LibraryTMACSUncontrolify. +This replaces each control character with an "^" and a letter. +Then do M-X Run LibraryTMACSSave Trees. This combines consecutive +short pages together so that the listing uses fewer pages. Otherwise, +each function would come out on a separate page of the listing, which +would be very wasteful for the many small functions that often exist. +After Save Trees, the listing is now in the buffer. + +Source Indexes + + A source index describes the contents of several TECO source files. +It is sorted alphabetically by function name and says which file each +function is in. It is useful for studying listings of those source +files. + + To make a source index, create a buffer and put in it the names of +the source files, one filename per line. Then load ABSTR and call +Make Source Index. When it is finished, the buffer contains the +source index. + +File: CONV Node: Qregs, Up: Top, Previous: Abstracts, Next: FS^RPREV + +Usage of Q-registers in EMACS and Functions Intended for EMACS + + EMACS makes no use of non-dot q-regs except as saved and restored +local variables, unless the user explicitly requests such use with +(say) C-X X, except for M and R, and even those are not depended on by +the EMACS functions. User functions may use non-dot q-regs freely, +but those intended for general use should not do so except as local +variables (pushed and popped). + + User functions should not use single or double dot q-regs except as +listed here. If it is really essential, you should ask RMS to +allocate another single-dot q-reg for a specific use. Normally, a +named variable is just as good. + + .A MM & Autoload. This function loads a library temporarily + and returns a pointer to a specified function in it. + For example, M.A DIREDClean Dir loads the DIRED + library and returns a pointer to the Clean Dir function + in it. FS :EJPAGE is pushed and left on the stack, + so that the library will be flushed when the function + which invoked M.A exits and unwinds the stack. + .B The buffer table. This is a q-vector which is + subdivided into a section for each EMACS named buffer. + The details of the format are described in a comment + at the front of the EMACS source file BUFFER. + + .C Set Variable Comment. + Like .V, but creates a comment for the variable. + M.C   creates if necessary, + giving it the comment and the value . + defaults to 0. If the comment starts with + "*", then the variable is an "option" + and MM Alter Options will let the user edit it. + .F The "normal" (top-level) contents of ..F. + When .F and ..F are not the same, EMACS knows that + it is not safe to switch buffers, windows or files. + .F should not be zero; that would lose. See ..F. + .H The horizontal position "goal" for ^N and ^P + commands. If it is a small positive number, it + is a temporary goal, which will be reset by + each ^N or ^P not following another such. The + other possible values in .H are 1000000. plus a + small number, which indicates a semipermanent goal + that was established by ^R Set Goal Column and + which it alone can alter. + .I & Prepare for Input. Do M.I before doing an + FI to read input. The second argument, if any + is the character to prompt with (default is in Q..0). + The first argument is bit-decoded: 1 means that + the control and meta prefix characters should be + noticed, and 2 suppresses prompting and echoing + (acts as if the characater being read is an independent + command). + .L Make Local Variable. Do M.L  to make + into a local variable of the current buffer. + If it already is local, nothing is changed. If + didn't exist at all, 0M.V is implied. + The global value of is not changed; the local + starts off with that same value as well. + If M.L is given a numeric argument, it becomes + the new value of the (local) . + .M & Macro Get. M.M returns a pointer to + the function . Normally, an error will + occur if the name is undefined or ambiguous, + but if 1, is given as argument, instead of an error, + the value 0 or 1 will be returned. Independently, + a pointer to a file can be given as an argument, + and the function will be looked for in that file. + .N The ring buffer of minibuffer commands. All commands + that use the minibuffer and execute its contents + normally push their commands onto this ring, + so you can run them again easily. Q.N is a q-vector + whose 0th element is the most recent minibuffer. + .P M.P is the driver for prefix commands such as C-X + which read another character and dispatch on it. + Whatever you put in .P should work like what is + usually put there: & Prefix Character Driver. + See Make Prefix Character. + .Q Inside major mode functions, this contains the + function Make Local Q-register. + .V Named Variable maker. (Teco "altmode" Q-regs) + .W Is a flag that determines whether the word commands + refer to LISP atoms. It holds either a null string + (if they do not) or an "@" (if they do). + .X Is the dispatch table for the C-X prefix command. + It is a qvector 128 elements long, indexed by + subcommand. This is only in the default environment. + If you build a completely separate environment, .X + is available. + + ..F normally holds the auto-filing secretary function. + Auto-saving is turned off by zeroing FS ^R MDLY, + not by changing ..F. Normally, .F contains the + same thing as ..F. Functions which call ^R recursively + should bind ..F to 0, thus inhibiting auto-saving. + Also, the fact that .F and ..F will then be different + will serve as an indication that it is not safe to + switch buffers, files or windows. If you use a + modified version of the secretary function, you must + store it in both ..F and .F for proper operation. + To turn off the secretary function globally, you should + not simply set .F and ..F to zero, because then the + functions that bind ..F to zero will not make it + different from .F. You must make a null string and + put it in .F and ..F. + ..K A qvector used to hold strings of deleted text + by the ^R Kill ... and ^R Un-kill commands. + The elements are the strings, in the order they + were killed. The beginning may be filled with zeros, + if there are not enough remembered killed strings + to use the whole qvector. + ..M holds the keyboard macro call stack. + See the file KBDMAC. + ..U holds the data base for the Undo command. + It is a qvector containing these 5 objects which + describe the most recent undoable change. + :..U(0) is the buffer in which the change was made. + :..U(1) is the text that was deleted. + :..U(2) is the number of characters which preceded + that text. + :..U(3) is the number which followed that text. + :..U(4) is a string like "kill" or "sort" which says + what sort of operation made the change. + +File: CONV Node: FS^RPREV, Up: Top, Previous: Qregs, Next: Debug + +FS ^R LAST / FS ^R PREV Convention + + Some commands set FS ^R LAST to a special value not in +the range of 9-bit characters, to make it possible to test +whether the previous command was in a certain class without +having to know which characters various functions are on. +These are the values used: + +512+27 is set at times in minibuffering, when the + (1033 octal) most recent character was an altmode but a + following altmode should not exit. + +1001 (decimal) is set by deleting commands. + This allows multiple consecutive deletions + to be combined in the ..K ring. + +1002 is set by the vertical-motion commands + so that repeated vertical motion commands + can use the same horizontal position as a goal. + +1003 signals that it is OK for m-Y (^R Un-kill Pop) + to work even though the current region is not + on the kill-ring. This is used by commands like + Fill Region which save the region then do a simple + but possibly dangerous transformation to it. + +File: CONV Node: Debug, Up: Top, Previous: FS^RPREV + +Debugging + + For debugging, make use of the function TCompile, which compresses +the definition of the function you are pointing at and makes it +available to M.M. This makes it possible to test a new version of a +function without purifying the whole file containing it. Insert a ^R +command into the definition to make a "breakpoint" which will allow +you to look around. Exiting the ^R will cause execution of the +function to resume. To test-compile the function and put it on a +character, use the fact that TCompile returns the definition as its +value; thus, do MM TcompileU.N to set C-N's definition. + + The default EMACS error handler runs MM Backtrace after every +error, if the first character you type is "?". Inside the backtrace +you can examine the functions on the call stack, look at the buffer +being edited, and resume execution either at the place it stopped or +elsewhere. To find out the details of how, type "?" while inside +Backtrace. If QDebug is nonzero, you can type "?" to get a +backtrace after a quit as well as after an error. + +*note TDEBUG: (TDEBUG)Top, for info on the superb TDEBUG package +which allows you to step through the execution of a function, +and examine the macro and q-register pdls. diff --git a/doc/info/emacs.147 b/doc/info/emacs.147 new file mode 100755 index 00000000..308e5a5a --- /dev/null +++ b/doc/info/emacs.147 @@ -0,0 +1,9203 @@ + +This file documents the EMACS editor. -*-Text-*- +Don't edit this file! It is produced by SCRIBE from another file. +Be sure to run TAGS over this file after you make it with SCRIBE. + + +EMACS Node: Top, Up: (DIR) +The EMACS Editor + +This is an INFO-ized version of the EMACS reference manual. + + +* Menu: + +* Intro:: An introduction to this documentation. +* Glossary:: Definitions of important concepts, and cross refs. +* CommandIndex::Brief info on all commands ordered by topic, + and cross refs. +* LibCat:: Brief info on available libraries. +* VarIndex:: Brief info on meanings of specific variables. +* Screen:: How to interpret what you see on the screen. +* Characters:: EMACS's character sets; usage from deficient + (ie, standard ASCII or upper case only) keyboards. +* Basic:: The most basic editing commands. + +Important General Concepts +* Arguments:: Giving numeric arguments to commands. +* M-X:: Issuing long-named "extended" commands. +* Subsystems:: Commands that themselves read commands in a distinctive + language, such as INFO and Backtrace. +* Recursive:: Recursive editing levels; situations when you are + using ordinary EMACS commands but editing something + special-purpose (such as a message to send). +* Exiting:: Exiting EMACS, subsystems, or recursive editing levels. +* Help:: Commands for asking EMACS about its commands. + +Important Text-Changing Commands +* Mark:: The mark: how to delimit a "region" of text. +* Killing:: Killing text. +* Un-killing:: Recovering killed text. Moving text. +* Copying:: Other ways of copying text. +* Search:: Finding or replacing occurrences of a string. +* Text:: Commands and modes for editing English. +* Fixit:: Commands especially useful for fixing typos. +* Abbrev: (WORDAB), How to define text abbreviations to reduce + the number of characters you must type. + +Larger Units of Text +* Files:: All about handling files. +* Buffers:: Multiple buffers; editing several files at once. +* Display:: Controlling what text is displayed. +* Windows:: Viewing two pieces of text at once. +* Narrowing:: Commands for narrowing view to part of the buffer. +* Pages:: Commands for dealing with pages in files. +* Replace:: Repetitive search and replace commands. +* TECOSearch:: TECO search strings. + +Editing Programs +* MajorModes:: Text mode vs. Lisp mode vs. MIDAS mode ... +* Programs:: Commands and modes for editing programs. +* Tags: (TAGS), The Tags subsystem remembers the location of each + "tag" or function definition in one or more files, + and allows you to go directly to any of them. + +Customization +* MinorModes:: Some useful options you can turn on and off. +* Libraries:: Loading additional libraries of commands. +* Variables:: Named variables: what they do and how to use them. +* Syntax:: The syntax table. +* FS Flags:: FS flags: TECO's variables. +* Init:: Init files and EVARS files. +* Locals:: Local modes lists in files. +* KBDMAC:: Making an abbreviation for a sequence of commands. +* Minibuffer:: Executing small TECO programs interactively. + +Recovery from Lossage +* Quitting:: Quitting and Aborting. +* Lossage:: What to do if EMACS is hung. +* Undo:: Undoing a command that destroyed your text. +* Journals:: Journal files save all your commands in case of crash. +* Bugs:: How and when to report a bug. + +Other Available Libraries +* PICTURE:: Subsystem for editing pictures made out of characters. +* Sort:: Commands for sorting part of the buffer. +* SLOWLY: (SLOWLY), A package of macros for people using slow + terminals. +* RENUM: (RENUM), A package of macros for renumbering sections, + references, equations, etc. in manuscripts. +* DOCOND: (DOCOND), Subsystem for "assembly conditionals" + in documentation files. +* RMAIL: (RMAIL), Subsystem for editing mail. +* Babyl: (Babyl), Babyl is, like RMail, an EMACS mail subsystem. + It differs from RMail in some respects, in + particular: it runs on TENEX and TWENEX. +* LEDIT: (LEDIT), Interface between EMACS and MacLisp. +* INFO: (INFO), Subsystem for reading documentation files. +* CLU: (ECLU), Subsystem containing CLU mode, a major mode. +* PL1: (EPL1), Subsystem containing PL1 mode, a major mode. +* PASCAL: (EPASC), Subsystem containing PASCAL mode, a major mode. +* TDEBUG: (TDEBUG), EMACS macro 2 window real-time debugger. +* Internals: (CONV), EMACS internals. Customization. Init files. +* TMACS: (TMACS)Top, Assorted useful commands and subroutines. + +Here are some other nodes which are really inferiors of the ones +already listed, so you can get to them in one step: + +* ModeLine:: How to interpret the mode line at top level. +* MMArcana:: Hows and whys of MM commands. +* Mail:: Reading mail. +* Visiting:: How to visit a file for editing. +* ListDir:: How to list a directory. +* Revert:: How to cancel some changes you have made. +* AutoSave:: Protection from system crashes. +* CleanDir:: Deleting piled up old versions of files. +* DIRED:: Deleting files by "editing your directory". +* Filadv:: Miscellaneous file commands. +* DirComp:: Comparing two directories. +* Compile:: M-X Compile: compile the visited file. +* Indenting:: Indentation commands for programs. +* Matching:: Automatic display of how parens balance. +* Lisp:: Commands for Lisp code. +* Lists:: Commands for moving over lists. +* Defuns:: Commands for top level lists (defuns). +* Comments:: Commands that understand comments in code. +* Grinding:: Reformatting Lisp code. +* MIDAS:: Commands for assembler language code. +* Other Langs:: Programming languages other than Lisp and assembler. +* Words:: Commands for moving over words. +* Sentences:: Commands for sentences and paragraphs. +* TextIndent:: Commands for indenting text. +* Filling:: Commands for filling and centering text. +* Case:: Case conversion commands. +* NoLowerCase:: What to do on terminals with no lower case. +* Fonts:: Font change commands. +* Underlining:: Underlining commands. +* SCRIBE:: Editing SCRIBE input files. +* Dissociation::Dissociated Press. +* PAGE Lib: PAGE. Macros for editing only one page at a time. +* Printing:: Printing terminals. + + + +EMACS Node: Intro, Previous: Top, Up: Top, Next: Glossary + +Introduction + +You are about to read about EMACS, an advanced, self-documenting, +customizable, extensible real-time display editor. + +We say that EMACS is a display editor because normally the text being +edited is visible on the screen and is updated automatically as you type +your commands. *Note Display: Screen. + +We call it a real-time editor because the display is updated very +frequently, usually after each character or pair of characters you type. +This minimizes the amount of information you must keep in your head as +you edit. *Note Real-time: Basic. + +We call EMACS advanced because it provides facilities that go beyond +simple insertion and deletion: filling of text; automatic indentation of +programs; viewing two files at once; and dealing in terms of characters, +words, lines, sentences, paragraphs, and pages, as well as expressions +and comments in several different programming languages. It is much +easier to type one command meaning "go to the end of the paragraph" than +to find the desired spot with repetition of simpler commands. + +Self-documenting means that at any time you can type a special +character, the "Help" key, to find out what your options are. You can +also use it to find out what any command does, or to find all the +commands that pertain to a topic. *Note Help: Help. + +Customizable means that you can change the definitions of EMACS commands +in little ways. For example, if you use a programming language in which +comments start with <** and end with **>, you can tell the EMACS comment +manipulation commands to use those strings. Another sort of +customization is rearrangement of the command set. For example, if you +prefer the four basic cursor motion commands (up, down, left and right) +on keys in a diamond pattern on the keyboard, you can have it. *Note +Customization: MinorModes. + +Extensible means that you can go beyond simple customization and write +entirely new commands, programs in the language TECO. EMACS is an +"on-line extensible" system, which means that it is divided into many +functions that call each other, any of which can be redefined in the +middle of an editing session. Any part of EMACS can be replaced without +making a separate copy of all of EMACS. Many already written extensions +are distributed with EMACS, and some (including DIRED, PAGE, PICTURE, +SORT, TAGS, and WORDAB) are documented in this manual. Although only a +programmer can write an extension, anybody can use it afterward. + +Extension requires programming in TECO, a rather obscure language. If +you are clever and bold, you might wish to learn how. *Note TECO: +(CONV), for advice on learning TECO. This manual does not even try to +explain how to write TECO programs, but it does contain some notes that +are useful primarily to the extension writer. + + +EMACS Node: Glossary, Previous: Intro, Up: Top, Next: CommandIndex + +Glossary + +Aborting Aborting a recursive editing level (q.v.) means + canceling the command which invoked the recursive + editing. For example, if you abort editing a message to + be sent, the message is not sent. Aborting is done with + the command C-]. *Note Aborting: Quitting. + +Altmode Altmode is a character, labelled Escape on some + keyboards. It is the bit prefix character (q.v.) used + to enter Meta-characters when the keyboard does not have + a Meta (q.v.) key. *Note Characters: Characters. Also, + it delimits string arguments to extended commands. + *Note Extended Commands: M-X. + +Balance Parentheses + EMACS can balance parentheses manually or automatically. + You can ask to move from one parenthesis to the matching + one. *Note Lists: Lists. When you insert a close + parenthesis, EMACS can show the matching open. *Note + Matching: Matching. + +Bit Prefix Character + A bit prefix character is a command which combines with + the next character typed to make one character. They + are used for effectively typing commands which the + keyboard being used is not able to send. For example, + to use a Meta-character when there is no Meta key on the + keyboard, the bit prefix character Altmode (q.v.) is + needed. *Note Bit Prefix: Characters. + +Buffer The buffer is the basic editing unit; one buffer + corresponds to one piece of text being edited. You can + have several buffers, but at any time you are editing + only one, the "selected" buffer, though two can be + visible when you are using two windows. *Note Buffers: + Buffers. + +C- C is an abbreviation for Control, in the name of a + character. *Note C-: Characters. + +C-M- C-M- is an abbreviation for Control-Meta, in the name of + a character. *Note C-M-: Characters. + +Comment A comment is text in a program which is intended only + for humans reading the program, and is marked specially + so that the compiler will ignore it. EMACS offers + special commands for creating and killing comments. + *Note Comments: Comments. + +Command A command is a character or sequence of characters + which, when typed by the user, fully specifies one + action to be performed by EMACS. For example, "X" and + "Control-F" and "Meta-X Text Mode" are commands. + *Note Command: Characters. Sometimes the first + character of a multi-character command is also + considered a command: M-X Text Mode is a command (an + extended command), and M-X is also a command (a command + to read a function name and invoke the function). *Note + Extended Commands: M-X. + +Completion Completion is what EMACS does when it automatically + fills out the beginning of an extended command name into + the full name, or as much of it as can be deduced for + certain. Completion occurs when Altmode, Space or + Return is typed. *Note Completion: M-X. + +Connected A character command in EMACS works by calling a function + which it is "connected" to. Customization often + involves connecting a character to a different function. + See "Dispatch table". *Note Connected: Characters. + +Continuation Line + When a line of text is longer than the width of the + screen, it is displayed on more than one line of screen. + We say that the line is continued, and that all screen + lines used but the first are called continuation lines. + *Note Continuation: Basic. + +Control Control is the name of a bit which each command + character does or does not contain. A character's name + includes the word Control if the Control bit is part of + that character. Ideally, this means that the character + is typed using the Control key: Control-A is typed by + typing "A" while holding down Control. On most + keyboards the Control key works in only some cases; the + rest of the time, a bit prefix character (q.v.) must be + used. *Note Control: Characters. + +Control-Character + A Control character is a character which includes the + Control bit. + +Control-X Command + A Control-X command is a two-character command whose + first character is the prefix character Control-X. + *Note Control-X Command: Characters. + + stands for the carriage return character, in + contexts where the word "Return" might be confusing. + *Note : Characters. + +CRLF CRLF stands for the sequence of two characters, carriage + return followed by linefeed, which is used to separate + lines in files and in text being edited in EMACS. *Note + CRLF: Characters. + +Cursor The cursor is the object on the screen which indicates + the position called point (q.v.) at which insertion and + deletion takes place. The cursor is part of the + terminal, and often blinks or underlines the character + where it is located. *Note Cursor: Screen. + +Customization Customization is making minor changes in the way EMACS + works. It is often done by setting variables (*Note + Variables: Variables.) or by reconnecting commands + (*Note Reconnect: MMArcana.). + +Defun A defun is a list at the top level of list structure in + a Lisp program. It is so named because most such lists + are calls to the Lisp function defun. *Note Defuns: + Defuns. + +Delete This is the label used on some keyboards for the Rubout + character. + +Deletion Deletion means erasing text without saving it. EMACS + deletes text only when it is expected not to be worth + saving (all whitespace, or only one character). The + alternative is killing (q.v.). *Note Deletion: Killing. + +Dispatch Table The dispatch table is what records the connections + (q.v.) from command characters to functions. Think of a + telephone switchboard connecting incoming lines + (commands) to telephones (functions). A standard EMACS + has one set of connections; a customized EMACS may have + different connections. *Note Dispatch Table: MMArcana. + +Echo Area The echo area is the bottom three lines of the screen, + used for echoing the arguments to commands, for asking + questions, and printing brief messages. *Note + Echo Area: Screen. + +Echoing Echoing is acknowledging the receipt of commands by + displaying them (in the echo area). Most programs other + than EMACS echo all their commands. EMACS never echoes + single-character commands; longer commands echo only if + you pause while typing them. + +Error Messages Error messages are single lines of output printed by + EMACS when the user or a TECO program asks for something + impossible. They appear at the top of the screen and + end with a question mark. + +Escape Escape is the label used on some keyboards for the + Altmode character. + +Exiting Exiting EMACS means returning to EMACS's superior, + normally HACTRN. *Note Exiting: Exiting. Exiting a + recursive editing level (q.v.) means allowing the + command which invoked the recursive editing to complete + normally. For example, if you are editing a message to + be sent, and you exit, the message is sent. + +Extended Command + An extended command is a command which consists of the + character Meta-X followed by the command name (really, + the name of a function (q.v.)). An extended command + requires several characters of input, but its name is + made up of English words, so it is easy to remember. + *Note Extended Commands: M-X. + +Extension Extension means making changes to EMACS which go beyond + the bounds of mere customization. If customization is + moving the furniture around in a room, extension is + building new furniture. *Note Extension: (CONV). + +Filling Filling text means moving text from line to line so that + all the lines are approximately the same length. *Note + Filling: Filling. + +Function A function is a named subroutine of EMACS. When you + type a command, EMACS executes a function which + corresponds to the command, and the function does the + work. Character commands are connected to functions + through the dispatch table (q.v.). Extended commands + contain the name of the function to be called; this + allows you to call any function. *Note Functions: M-X. + +Global The global value of a variable or of a command character + definition applies to all buffers and all files (except + those which have their own local values of the variable + or definition). *Note Global: Variables. + +Grinding Grinding means reformatting a program so that it is + indented according to its structure. *Note Grinding: + Grinding. + +Help You can type the Help character at any time to ask what + options you have, or to ask what any command does. + *Note Help: Help. + +Home Directory Your home directory is the one on which your mail and + your init files are stored. + +INFO INFO is the subsystem for perusing tree-structured + documentation files. The documentation in INFO includes + a version of the EMACS manual. + +ITS ITS is the Incompatible Timesharing System written at + the MIT Artificial Intelligence Lab. EMACS was first + developed on this system. Just what it is incompatible + with has changed from year to year. + +Kill Ring The kill ring is where killed text is saved. It holds + the last nine or so blocks of killed text. It is called + a ring because you can bring any of the saved blocks to + the front by rotating the ring. *Note Kill ring: + Un-Killing. + +Killing Killing means erasing text and saving it inside EMACS to + be recovered later if desired. Most EMACS commands to + erase text do killing, as opposed to deletion (q.v.). + *Note Killing: Killing. + +List A list is, approximately, a text string beginning with + an open parenthesis and ending with the matching close + parenthesis. *Note Lists: Lists. Actually there are a + few complications to the syntax, which is controlled by + the syntax table (*Note Syntax: Syntax.). + +Local A local value of a variable or of a command character + definition applies to only one buffer or file. *Note + Locals: Locals. + +Local Modes List + A local modes list appears in a file to specify local + values for variables or command character definitions, + to be in effect while visiting that file. + +M- M- in the name of a character is an abbreviation for + Meta. + +M-X M-X is the character which begins an extended command + (q.v.). Extended commands have come to be known also as + "M-X commands", and an individual extended command is + often referred to as "M-X such-and such". *Note M-X: + M-X. + +Major Mode The major modes are a mutually exclusive set of options + which configure EMACS for editing a certain sort of + text. Ideally, each programming language has its own + major mode. *Note Major Modes: MajorModes. + +Mark The mark points, invisibly, to a position in the text. + Many commands operate on the text between point and the + mark (known as the region, q.v.). *Note Mark: Mark. + +Meta Meta refers to the Meta key. A character's name + includes the word Meta if the Meta key must be held down + in order to type the character. If there is no Meta + key, then the Altmode character is used as a prefix + instead. *Note Meta: Characters. + +Meta Character A Meta character is one whose character code includes + the Meta bit. These characters can be typed only by + means of a Meta key or by means of the metizer command + (q.v.). + +Metizer The metizer is another term for the bit prefix character + for the Meta bit; namely, Altmode (q.v.). + +Minibuffer The minibuffer is a facility for editing and then + executing a TECO program. *Note Minibuffer: Minibuffer. + +Minor mode A minor mode is an optional feature of EMACS which can + be switched on or off independently of all other + features. Each minor mode is both the name of an option + (q.v.) and the name of an extended command to set the + option. *Note Minor Modes: MinorModes. + +MM-command This is an obsolete synonym for "extended command". + +Mode line The mode line is a line just above the echo area (q.v.), + used for status information. *Note Mode Line: ModeLine. + +Narrowing Narrowing means limiting editing to only a part of the + text in the buffer. Text outside that part is + inaccessible to the user until the boundaries are + widened again, but it is still there, and saving the + file saves it all. *Note Narrowing: Narrowing. + +Node The node is the unit of structure of INFO (q.v.) files. + +Numeric Argument + A numeric argument is a number specified before a + command to change the effect of the command. Often the + numeric argument serves as a repeat count. *Note + Numeric Arguments: Arguments. + +Option An option is a variable which exists to be set by the + user to change the behavior of EMACS commands. This is + an important method of customization. *Note Options: + Variables. + +Parse We say that EMACS parses words or expressions in the + text being edited. Really, all it knows how to do is + find the other end of a word or expression. *Note + Parse: Syntax. + +Point Point is the place in the buffer at which insertion and + deletion occur. Point is considered to be between two + characters, not at one character. The terminal's cursor + (q.v.) indicates the location of point. *Note Point: + Basic. + +Prefix Character + A prefix character is a command whose sole function is + to introduce a set of multi-character commands. + Control-X (q.v.) is a prefix character. The bit prefix + characters (q.v.) are other examples. + +Prompt A prompt is text printed in the echo area to ask the + user for input. Printing a prompt is called + "prompting". EMACS can prompt when a command requires + an argument, or when only part of a command has been + typed. However, the prompt will not appear unless you + pause in your typing. *Note Prompt: M-X. + +Q-Registers Q-registers are internal TECO variables which can be + used by EMACS or by the user to store text or numbers. + *Note Q-Registers: Copying. + +Quitting Quitting means interrupting a command which is partially + typed in or already executing. It is done with + Control-G. *Note Quitting: Quitting. + +Quoting Quoting means depriving a character of its usual special + significance. It is usually done with Control-Q. What + constitutes special significance depends on the context + and on convention. For example, an "ordinary" character + as an EMACS command inserts itself; so you can insert + any other character, such as Rubout, by quoting it as in + Control-Q Rubout. Not all contexts allow quoting. + *Note Quoting: Basic. + +Recursive Editing Level + A recursive editing level is a state in which part of + the execution of a command involves asking the user to + edit some text. This text may or may not be the same as + the text to which the command was applied. The mode + line indicates recursive editing levels with square + brackets ("[" and "]"). *Note Recursive Editing Level: + Recursive. + +Redisplay Redisplay is the process of correcting the image on the + screen to correspond to changes that have been made in + the text being edited. *Note Redisplay: Screen. + +Region The region is the text between point (q.v.) and the mark + (q.v.). The terminal's cursor indicates the location of + point, but the mark is invisible. Many commands operate + on the text of the region. *Note Region: Mark. + +Return Return is the carriage return character, used as input + to EMACS. Return is used as a command in itself to + insert a line separator. It also terminates arguments + for most commands. *Note Return: Characters. + +Rubout Rubout is a character, sometimes labelled "Delete". It + is used as a command to delete one character of text. + It also deletes one character when an EMACS command is + reading an argument. + +S-expression An s-expression is the basic syntactic unit of Lisp: + either a list, or a symbol containing no parentheses + (actually, there are a few exceptions to the rule, based + on the syntax of Lisp). *Note S-expressions: Lists. + +Selecting Selecting a buffer (q.v.) means making editing commands + apply to that buffer as opposed to any other. At all + times one buffer is selected and editing takes place in + that buffer. *Note Select: Buffers. + +Self-documentation + Self-documentation is the feature of EMACS which can + tell you what any command does, or give you a list of + all commands related to a topic you specify. You ask + for self-documentation with the Help character. *Note + Self-documentation: Help. + +String Argument + A string argument is an argument which follows the + command name in an extended command. In "M-X + Aproposword", "Word" is a string argument to the + Apropos command. *Note String Arguments: M-X. + +Subsystem A subsystem of EMACS is an EMACS command which, itself, + reads commands and displays the results. Examples are + INFO, which is for perusing documentation; DIRED, which + is for editing directories; RMAIL and BABYL, which + are for reading and editing mail. The word "subsystem" + implies that it offers many independent commands which + can be used freely. If an EMACS function asks specific + questions, we do not call it a subsystem. + + Usually the subsystem continues in operation until a + specific command to exit (usually "Q") is typed. The + commands for a subsystem do not usually resemble + ordinary EMACS commands, since editing text is not their + purpose. The Help character should elicit the + subsystem's documentation. *Note Subsystems: + Subsystems. + +Syntax Table The syntax table tells EMACS which characters are part + of a word, which characters balance each other like + parentheses, etc. *Note Syntax: Syntax. + +Tailoring This is a synonym for customization (q.v.). + +TECO Search String + A TECO search string is a sort of pattern used by the + TECO search command, and also by various EMACS commands + which use the TECO search command. *Note + TECO search strings: TECOsearch. + +Top Level Top level is the normal state of EMACS, in which you are + editing the text of the file you have visited. You are + at top level whenever you are not in a recursive editing + level or a subsystem (q.v.). + +Twenex Twenex is the operating system which DEC likes to call + "TOPS-20". However, a person should not be forced to + call a system "tops" unless he really thinks so. Come + now, DEC, don't you think people will praise your + products voluntarily? The name "Twenex" is also more + appropriate because Twenex was developed from the Tenex + system, and has no relationship to "TOPS-10". What's + more, it's very euphonious. + +Typeout Typeout is a message, printed by an EMACS command, which + overwrites the area normally used for displaying the + text being edited, but which does not become part of the + text. Typeout is used for messages which might be too + long to fit in the echo area (q.v.). *Note Typeout: + Screen. + +Undo Undo is a command which undoes the effect on the buffer + of a previous command. Only some commands are undoable + and only the most recent undoable command can be undone. + *Note Undo: Undo. + +Un-killing Un-killing means reinserting text previously killed. It + can be used to undo a mistaken kill, or for copying or + moving text. *Note Un-killing: Un-killing. + +User Name Your user name is the name you use to log in. It + identifies you as opposed to all the other users. It + may be the same as your home directory's name. + +Variable A variable is a name with which EMACS associates a + value, which can be a number or a string. *Note + Variables: Variables. Some variables ("options") are + intended to be used or set by the user; others are for + purely internal purposes. + +Virtual Boundaries + The virtual boundaries delimit the accessible part of + the buffer, when narrowing (q.v.) is in effect. *Note + Virtual Boundaries: Narrowing. + +Visiting Visiting a file means loading its contents into a buffer + (q.v.) where they can be edited. *Note Visiting: + Visiting. + +Wall Chart The wall chart is a very brief EMACS reference sheet + giving one line of information about each short command. + +Whitespace Whitespace is any run of consecutive formatting + characters (space, tab, carriage return, linefeed, and + backspace). + +Widening Widening is the operation which undoes narrowing (q.v.). + *Note Widening: Narrowing. + +Window A window is a region of the screen in which text being + edited is displayed. EMACS can divide the screen into + two windows. *Note Windows: Windows. "The window" also + means the position in the buffer which is at the top of + the screen. *Note The Window: Display. + +Working Directory + This is the directory which you have told the system you + wish to operate on primarily at the moment. This is + usually the same as your home directory (q.v.). It is + specified with the DDT command :CWD . + +Yanking This is a synonym for un-killing (q.v.). + +^R The string "^R" is the beginning of many function names. + *Note ^R: MMArcana. + +^R Mode ^R mode is the real time editing mode of TECO. EMACS + always operates in this mode. + + + +EMACS Node: CommandIndex, Previous: Glossary, Up: Top, Next: LibCat + +Command Summary + +This summary contains brief descriptions with cross references for all +commands, grouped by topic. Within each topic, they are in alphabetical +order. Our version of alphabetical order places non-control non-meta +characters first, then control characters, then meta characters, then +control-meta characters. Control-X and Meta-X commands come last. Not +all Meta-X commands are included. + +Each command has a footnote whose name is the same as the command name. +Thus, you do not need to find the entry for a command to use the +footnote. Just do F. For example, F Control-S +goes directly to the node which documents the Control-S command. For an +extended command, the footnote name does not include the "Meta-X". + +Prefix Characters + +Altmode (^R Prefix Meta) + Altmode is a bit prefix character which turns on the + Meta bit in the next character. Thus, Altmode F is + equivalent to the single character Meta-F, which is + useful if your keyboard has no Meta key. *Note Altmode: + Characters. + +Control-^ (^R Prefix Control) + Control-^ is a bit prefix character which turns on the + Control bit in the following character. Thus, Control-^ + < is equivalent to the single character Control-<. + *Note Control-^: Characters. + +Control-C (^R Prefix Control-Meta) + Control-C is a bit prefix character which turns on the + Control bit and the Meta bit in the following character. + Thus, Control-C ; is equivalent to the single character + Control-Meta-;. *Note Control-C: Characters. + +Control-Q (^R Quoted Insert) + Control-Q inserts the following character. This is a + way of inserting control characters. *Note Control-Q: + Basic. + +Control-U (^R Universal Argument) + Control-U is a prefix for numeric arguments which works + the same on all terminals. *Note Control-U: Arguments. + +Control-X + Control-X is a prefix character which begins a + two-character command. Each combination of Control-X + and another character is a "Control-X command". + Individual Control-X commands appear in this summary + according to their uses. + +Meta-X (^R Extended Command) + Meta-X is a prefix character which introduces an + extended command name. *Note Meta-X: M-X. + +Control-Meta-X (^R Instant Extended Command) + Control-Meta-X is another way of invoking an extended + command. Instead of putting the arguments in the same + line as the command name, the command reads the + arguments itself. *Note Control-Meta-X: M-X. + +Control-digits, Meta-digits, Control-Meta-digits + These all specify a numeric argument for the next + command. *Note Arguments: Arguments. + +Control-Minus, Meta-Minus, Control-Meta-Minus + These all begin a negative numeric argument for the next + command. *Note Arguments: Arguments. + +Simple Cursor Motion + +Control-A (^R Beginning of Line, built-in function) + Control-A moves to the beginning of the line. *Note + Control-A: Basic. + +Control-B (^R Backward Character, built-in function) + Control-B moves backward one character. *Note + Control-B: Basic. + +Control-E (^R End of Line, built-in function) + Control-E moves to the end of the line. *Note + Control-E: Basic. + +Control-F (^R Forward Character, built-in function) + Control-F moves forward one character. *Note Control-F: + Basic. + +Control-H (^R Backward Character, built-in function) + Control-H moves backward one character. *Note + Control-H: Basic. + +Control-N (^R Down Real Line) + Control-N moves vertically straight down. *Note + Control-N: Basic. + +Control-P (^R Up Real Line) + Control-P moves vertically straight up. *Note + Control-P: Basic. + +Control-R (^R Reverse Search) + Control-R is like Control-S but searches backward. + *Note Control-R: Search. + +Control-S (^R Incremental Search) + Control-S searches for a string, terminated by Altmode. + It searches as you type. *Note Control-S: Search. + +Meta-< (^R Goto Beginning) + Meta-< moves to the beginning of the buffer. *Note + Meta-<: Basic. + +Meta-> (^R Goto End) + Meta-> moves to the end of the buffer. *Note Meta->: + Basic. + +Control-X Control-N (^R Set Goal Column) + Control-X Control-N sets a horizontal goal for the + Control-N and Control-P commands. When there is a goal, + those commands try to move to the goal column instead of + straight up or down. + +Lines + +Return (^R CRLF) + Return inserts a line separator, or advances onto a + following blank line. *Note Return: Basic. + +Control-O (^R Open Line, built-in function) + Control-O inserts a line separator, but point stays + before it. *Note Control-O: Basic. + +Meta-= (^R Count Lines Region) + Meta-= prints the number of lines between point and + mark. *Note Meta-=: Mark. + +Control-X Control-O (^R Delete Blank Lines) + Control-X Control-O deletes all but one of the blank + lines around point. If the current line is not blank, + all blank lines following it are deleted. *Note + Control-X Control-O: Basic. + +Control-X Control-T (^R Transpose Lines) + Control-X Control-T transposes the contents of two + lines. *Note Control-X Control-T: Fixit. + +Killing and Un-killing + +Rubout (^R Backward Delete Character, built-in function) + Rubout deletes the previous character. *Note Rubout: + Basic. + +Control-Rubout (^R Backward Delete Hacking Tabs, built-in function) + Control-Rubout deletes the previous character, but + converts a tab character into several spaces. *Note + Control-Rubout: Lisp. + +Control-D (^R Delete Character, built-in function) + Control-D deletes the next character. *Note Control-D: + Basic. + +Control-K (^R Kill Line) + Control-K kills to the end of the line, or, at the end + of a line, kills the line separator. *Note Control-K: + Killing. + +Control-W (^R Kill Region) + Control-W kills the region, the text between point and + the mark. *Note Control-W: Killing. *Note Region: + Mark. + +Control-Y (^R Un-kill) + Control-Y reinserts the last saved block of killed text. + *Note Control-Y: Un-Killing. + +Meta-W (^R Copy Region) + Meta-W saves the region as if it were killed without + removing it from the buffer. *Note Meta-W: Un-Killing. + +Meta-Y (^R Un-kill Pop) + Meta-Y rolls the kill ring to reinsert saved killed text + older than the most recent kill. *Note Meta-Y: + Un-Killing. + +Control-Meta-W (^R Append Next Kill) + Control-Meta-W causes an immediately following kill + command to append its text to the last saved block of + killed text. *Note Control-Meta-W: Un-Killing. + +Control-X G (^R Get Q-reg) + Control-X G inserts in the buffer the contents of a + q-register. *Note Copying: Copying. + +Control-X T (^R Transpose Regions) + Control-X T transposes two arbitrary regions defined by + point and the last three marks. *Note Control-X T: + Fixit. + +Control-X X (^R Put Q-reg) + Control-X X inserts in the buffer the contents of a + q-register. *Note Copying: Copying. + +M-X Overwrite Mode + M-X Overwrite Mode turns Overwrite mode on or off. In + Overwrite mode, printing characters overwrite existing + text instead of pushing it to the right. *Note + Overwrite Mode: MinorModes. + +Scrolling and Display Control + +Control-Alpha (SAIL Character Mode) + Control-Alpha toggles SAIL Character mode. When this + mode is on, control characters in the buffer are + displayed as themselves. *Note Control-Alpha: Screen. + +Control-L (^R New Window) + Control-L clears the screen and centers point in it. + With an argument, it can put point on a specific line of + the screen. *Note Control-L: Display. + +Control-V (^R Next Screen) + Control-V scrolls the text upward by a screenful or + several lines. *Note Control-V: Display. + +Meta-R (^R Move to Screen Edge) + Meta-R moves point to beginning of the text on a + specified line of the screen. *Note Meta-R: Display. + +Meta-V (^R Previous Screen) + Meta-V scrolls downward by a screenful or several lines. + *Note Meta-V: Display. + +Control-Meta-R (^R Reposition Window) + Control-Meta-R tries to center on the screen the + function or paragraph you are looking at. *Note + Control-Meta-R: Display. + +Control-Meta-V (^R Scroll Other Window) + Control-Meta-V scrolls the other window up or down, when + you are in two window mode. *Note Control-Meta-V: + Windows. + +M-X View Buffer + M-X View Buffer skips through a buffer by screenfuls. + *Note View Buffer: Display. + +M-X View File + M-X View File lets you move through a file sequentially + by screenfuls forward and back. *Note View File: + FilAdv. + +The Mark and the Region + +Control-Space (^R Set/Pop Mark) + Control-Space sets the mark or moves to the location of + the mark. *Note Control-Space: Mark. + +Control-< (^R Mark Beginning) + Control-< sets the mark at the beginning of the buffer. + *Note Control-<: Mark. + +Control-> (^R Mark End) + Control-> sets the mark at the end of the buffer. *Note + Control->: Mark. + +Control-@ (^R Set/Pop Mark) + Control-@ sets the mark or moves to the location of the + mark. *Note Control-@: Mark. + +Meta-@ (^R Mark Word) + Meta-@ puts the mark at the end of the next word. *Note + Meta-@: Words. + +Meta-H (^R Mark Paragraph) + Meta-H puts point at the beginning of the paragraph and + the mark at the end. *Note Meta-H: Sentences. + +Control-Meta-@ (^R Mark Sexp) + Control-Meta-@ puts the mark at the end of the next + s-expression. *Note Control-Meta-@: Lists. + +Control-Meta-H (^R Mark Defun) + Control-Meta-H puts point at the beginning of the + current Defun and the mark at the end. *Note + Control-Meta-H: Defuns. + + + Control-X H (^R Mark Whole Buffer) + Control-X H puts point at the beginning of the buffer + and the mark at the end. *Note Control-X H: Mark. + +Control-X Control-P (^R Mark Page) + Control-X Control-P puts point at the beginning of the + current page and the mark at the end. *Note + Control-X Control-P: Pages. + +Control-X Control-X (^R Exchange Point and Mark) + Control-X Control-X sets point where the mark was and + the mark where point was. *Note Control-X Control-X: + Mark. + +Whitespace and Indentation + +Tab (^R Indent According to Mode) + Tab either adjusts the indentation of the current line + or inserts some indentation, in a way that depends on + the major mode. *Note Tab: Indenting. *Note + Indenting Text: TextIndent. + +Linefeed (^R Indent New Line) + Linefeed is equivalent to Return followed by Tab. It + moves to a new line and indents that line. If done in + the middle of a line, it breaks the line and indents the + new second line. *Note Linefeed: TextIndent. + +Meta-Tab (^R Tab to Tab Stop) + Meta-Tab indents to the next EMACS-defined tab stop. + *Note Meta-Tab: TextIndent. + +Meta-M (^R Back to Indentation) + Meta-M positions the cursor on the current line after + any indentation. *Note Meta-M: TextIndent. + +Meta-\ (^R Delete Horizontal Space) + Meta-\ deletes all spaces and tab characters around + point. *Note Meta-\: TextIndent. + +Meta-^ (^R Delete Indentation) + Meta-^ joins two lines, replacing the indentation of the + second line with zero or one space, according to the + context. *Note Meta-^: TextIndent. + +Control-Meta-O (^R Split Line) + Control-Meta-O breaks a line, preserving the horizontal + position of the second half by indenting it to its old + starting position. *Note Control-Meta-O: TextIndent. + +Control-Meta-\ (^R Indent Region) + Control-Meta-\ indents each line in the region, either + by applying Tab to each line, or by giving each the same + specified amount of indentation. *Note Control-Meta-\: + TextIndent. + +Control-X Tab (^R Indent Rigidly) + Control-X Tab shifts all the lines in the region right + or left the same number of columns. *Note + Control-X Tab: TextIndent. + +M-X Edit Indented Text + M-X Edit Indented Text enters a recursive editing level + designed for editing text in which each line is + indented. *Note Edit Indented Text: Filling. + +M-X Edit Tab Stops + M-X Edit Tab Stops lets you edit the tab stops used by + ^R Tab to Tab Stop. *Note Edit Tab Stops: TextIndent. + +M-X Edit Tabular Text + M-X Edit Tabular Text enters a recursive editing level + designed for editing text arranged in a table. *Note + Edit Tabular Text: Filling. + +M-X Indent Tabs Mode + M-X Indent Tabs Mode turns Indent Tabs mode on or off. + When Indent Tabs mode is on, the indentation commands + use tab characters for indentation whenever possible. + Otherwise they use only spaces. *Note Indent Tabs Mode: + MinorModes. + +M-X Tabify + M-X Tabify converts spaces after point to tabs when that + can be done without changing the appearance. *Note + Tabify: TextIndent. + +M-X Untabify + M-X Untabify converts all tabs after point to spaces. A + numeric argument says how far apart the tab stops are, + which is good for converting files brought from systems + with tab stops at intervals other than 8. *Note + Untabify: TextIndent. + +Words, Sentences and Paragraphs + +Meta-A (^R Backward Sentence) + Meta-A moves to the beginning of the sentence. *Note + Meta-A: Sentences. + +Meta-B (^R Backward Word) + Meta-B moves backward one word. *Note Meta-B: Words. + +Meta-D (^R Kill Word) + Meta-D kills one word forward. *Note Meta-D: Words. + +Meta-E (^R Forward Sentence) + Meta-E moves to the end of the sentence. *Note Meta-E: + Sentences. + +Meta-F (^R Forward Word) + Meta-F moves forward one word. *Note Meta-F: Words. + +Meta-H (^R Mark Paragraph) + Meta-H puts point at the front of the current paragraph + and the mark at the end. *Note Meta-H: Sentences. + +Meta-K (^R Kill Sentence) + Meta-K kills to the end of the sentence. *Note Meta-K: + Sentences. + +Meta-T (^R Transpose Words) + Meta-T transposes two consecutive words. *Note Meta-T: + Words. + +Meta-[ (^R Backward Paragraph) + Meta-[ moves to the beginning of the paragraph. *Note + Meta-[: Sentences. + +Meta-] (^R Forward Paragraph) + Meta-] moves to the end of the paragraph. *Note Meta-]: + Sentences. + +Meta-Rubout (^R Backward Kill Word) + Meta-Rubout kills the previous word. *Note Meta-Rubout: + Words. + +Control-X Rubout (^R Backward Kill Sentence) + Control-X Rubout kills back to the beginning of the + sentence. *Note Control-X Rubout: Sentences. + +M-X Atom Word Mode + M-X Atom Word Mode turns Atom Word mode on or off. In + Atom Word mode, the word commands consider an entire + Lisp atom as one word. *Note Atom Word Mode: + MinorModes. + +M-X Edit Syntax Table + M-X Edit Syntax Table allows you to edit the syntax + table for word and list delimiters. *Note + Edit Syntax Table: Syntax. + +Filling Text + +Meta-G (^R Fill Region) + Meta-G fills the region, treating it (usually) as one + paragraph. *Note Meta-G: Filling. + +Meta-Q (^R Fill Paragraph) + Meta-Q fills the current or next paragraph. *Note + Meta-Q: Filling. + +Meta-S (^R Center Line) + Meta-S centers the current line. *Note Meta-S: Filling. + +Control-X . (^R Set Fill Prefix) + Control-X . specifies the fill prefix, which is used for + filling indented text. *Note Control-X Period: Filling. + +Control-X F (^R Set Fill Column) + Control-X F sets the variable Fill Column which controls + the margin for filling and centering. *Note + Control-X F: Filling. + +M-X Auto Fill Mode + M-X Auto Fill Mode turns Auto Fill mode on or off. In + Auto Fill mode, long lines are broken between words + automatically. *Note Auto Fill Mode: Filling. + +Exiting, Quitting + +Control-G + Control-G quits, interrupting a running command, or + discarding any partially typed command. *Note + Control-G: Quitting. + +Control-] (Abort Recursive Edit) + Control-] aborts a recursive editing level; that is to + say, exits it without allowing the command which invoked + it to finish. *Note Control-]: Quitting. + +Control-Meta-C (^R Exit, built-in function) + Control-Meta-C exits from a recursive editing level and + allows the command which invoked the recursive editing + level to finish. At top level, it exits from EMACS to + its superior job. *Note Control-Meta-C: Exiting. + +Control-X Control-C (^R Return to Superior) + Control-X Control-C returns from EMACS to its superior + job, even if EMACS is currently inside a recursive + editing level. In that case, re-entering EMACS will + find it still within the recursive editing level. *Note + Control-X Control-C: Exiting. + +M-X Compile + M-X Compile recompiles the file you are visiting, in a + manner that depends on the major mode. *Note Compile: + Compile. + +M-X Top Level + M-X Top Level returns to the top level EMACS command + loop or to TECO. *Note Top Level: Quitting. + +M-X Undo + M-X Undo retracts the last undoable change to the + buffer. *Note Undo: Lossage. + +Pages + +Control-X L (^R Count Lines Page) + Control-X L prints the number of lines on the current + page, and how many come before point and how many come + after. *Note Control-X L: Pages. + +Control-X P (^R Narrow Bounds to Page) + Control-X P narrows the virtual boundaries to the + current page. *Note Control-X P: Narrowing. + +Control-X [ (^R Previous Page) + Control-X [ moves backward to the previous page + boundary. *Note Control-X [: Pages. + +Control-X ] (^R Next Page) + Control-X ] moves forward to the next page boundary. + *Note Control-X ]: Pages. + +Control-X Control-P (^R Mark Page) + Control-X Control-P puts point at the beginning and the + mark at the end of the current page. *Note + Control-X Control-P: Pages. + +M-X View Page Directory (in PAGE) + M-X View Page Directory prints a directory of the pages + of the file. *Note View Page Directory: PAGE. + +M-X What Page + M-X What Page prints the current page and line number in + the file. *Note What Page: Pages. + +Lisp + +Meta-( (^R Make ()) + Meta-( places a pair of parentheses around the next + several s-expressions. *Note Meta-(: Lists. + +Meta-) (^R Move Over )) + Meta-) moves past the next close parenthesis and adjusts + the indentation of the following line. *Note Meta-): + Lists. + +Control-Meta-Tab (^R Indent for Lisp) + Control-Meta-Tab adjusts the indentation of the current + line for proper Lisp style. *Note Control-Meta-Tab: + Indenting. + +Control-Meta-( (^R Backward Up List) + Control-Meta-( moves backward up one level of list + structure. *Note Control-Meta-(: Lists. + +Control-Meta-) (^R Up List) + Control-Meta-) moves forward up one level of list + structure. *Note Control-Meta-): Lists. + +Control-Meta-@ (^R Mark Sexp) + Control-Meta-@ puts the mark at the end of the next + s-expression. *Note Control-Meta-@: Mark. + +Control-Meta-A (^R Beginning of Defun) + Control-Meta-A moves to the beginning of the current + Defun. *Note Control-Meta-A: Defuns. + +Control-Meta-B (^R Backward Sexp) + Control-Meta-B moves backward over one s-expression. + *Note Control-Meta-B: Lists. + +Control-Meta-D (^R Down List) + Control-Meta-D moves forward and down a level in list + structure. *Note Control-Meta-D: Lists. + +Control-Meta-E (^R End of Defun) + Control-Meta-E moves to the end of the current Defun. + *Note Control-Meta-E: Defuns. + +Control-Meta-F (^R Forward Sexp) + Control-Meta-F moves forward over one s-expression. + *Note Control-Meta-F: Lists. + +Control-Meta-G (^R Format Code) + Control-Meta-G grinds the s-expression after point. + *Note Control-Meta-G: Grinding. + +Control-Meta-H (^R Mark Defun) + Control-Meta-H puts point before and the mark after the + current or next Defun. *Note Control-Meta-H: Defuns. + +Control-Meta-K (^R Kill Sexp) + Control-Meta-K kills the following s-expression. *Note + Control-Meta-K: Lists. + +Control-Meta-N (^R Next List) + Control-Meta-N moves forward over one list, ignoring + atoms before the first open parenthesis. *Note + Control-Meta-N: Lists. + +Control-Meta-P (^R Previous List) + Control-Meta-P moves backward over one list, ignoring + atoms reached before the first close parenthesis. *Note + Control-Meta-P: Lists. + +Control-Meta-Q (^R Indent Sexp) + Control-Meta-Q adjusts the indentation of each of the + lines in the following s-expression, but not the current + line. *Note Control-Meta-Q: Indenting. + +Control-Meta-T (^R Transpose Sexps) + Control-Meta-T transposes two consecutive s-expressions. + *Note Control-Meta-T: Lists. + +Control-Meta-U (^R Backward Up List) + Control-Meta-U moves backward up one level of list + structure. *Note Control-Meta-U: Lists. + +Files + +Meta-. (^R Find Tag) + Meta-. moves to the definition of a specific function, + switching files if necessary. *Note Meta-.: (TAGS)Top. + +Meta-~ (^R Buffer Not Modified) + Meta-~ clears the flag which says that the buffer + contains changes that have not been saved. *Note + Meta-~: Visiting. + +Control-X Control-F (Find File) + Control-X Control-F visits a file in its own buffer. + *Note Control-X Control-F: Buffers. + +Control-X Control-Q (^R Set File Read Only) + Control-X Control-Q makes the visited fie read only, or + no longer read only. *Note Control-X Control-Q: + Visiting. + +Control-X Control-S (^R Save File) + Control-X Control-S saves the visited file. *Note + Control-X Control-S: Visiting. + +Control-X Control-V (^R Visit File) + Control-X Control-V visits a file. *Note + Control-X Control-V: Visiting. + +Control-X Control-W (Write File) + Control-X Control-W saves the file, asking for names to + save it under. *Note Control-X Control-W: FilAdv. + +M-X Append to File + M-X Append to File appends the contents of the region to + the end of a specified file. *Note Append to File: + FilAdv. + +M-X Auto Save Mode + M-X Auto Save Mode turns Auto Save mode on or off. + *Note Auto Save Mode: AutoSave. + +M-X Copy File + M-X Copy File copies a file to a new name. *Note + Copy File: FilAdv. + +M-X Delete File + M-X Delete File deletes a file. *Note Delete File: + FilAdv. + +M-X Insert File + M-X Insert File inserts the contents of a file into the + buffer (within the existing text). *Note Insert File: + FilAdv. + +M-X Prepend to File + M-X Prepend to File appends the contents of the region + to the start of a specified file. *Note + Prepend to File: FilAdv. + +M-X Rename File + M-X Rename File changes the name of a file. *Note + Rename File: FilAdv. + +M-X Revert File + M-X Revert File undoes changes to a file by reading in + the previous version. *Note Revert File: Revert. + +M-X Save All Files + M-X Save All Files offers to write back buffers which + may need it. *Note Save All Files: Buffers. + +M-X Set Visited Filename + M-X Set Visited Filename changes the visited filename, + without writing a file. *Note Set Visited Filename: + FilAdv. + +M-X Write Region + M-X Write Region writes the contents of the region into + a file. *Note Write Region: FilAdv. + +File Directories + +Control-X D (^R DIRED) + Control-X D invokes the directory editor DIRED, useful + for deleting many files. *Note Control-X D: DIRED. + +Control-X Control-D (^R Directory Display) + Control-X Control-D displays a subset of a directory. + *Note Control-X Control-D: ListDir. + +M-X Clean Directory + M-X Clean Directory deletes all but the most recent + versions of every file in a directory. *Note + Clean Directory: CleanDir. + +M-X Compare Directories + M-X Compare Directories compare two directories with the + same name on different machines. *Note + Compare Directories: DirComp. + +M-X List Directories + M-X List Directories list the names of all disk + directories. *Note List Directories: ListDir. + +M-X List Files + M-X List Files prints a very brief listing of a + directory, listing only the filenames, several files per + line. *Note List Files: ListDir. + +M-X Reap File + M-X Reap File deletes all but the most recent versions + of a file. *Note Reap File: CleanDir. + +M-X View Directory + M-X View Directory prints a file directory. *Note + View Directory: ListDir. + +Buffers + +Control-X Control-B (List Buffers) + Control-X Control-B prints a list of all buffers, their + major modes and the files they are visiting. *Note + Control-X Control-B: Buffers. + +Control-X A (^R Append to Buffer) + Control-X A adds the text of region into another buffer. + *Note Control-X A: Copying. + +Control-X B (Select Buffer) + Control-X B is the command for switching to another + buffer. *Note Control-X B: Buffers. + +Control-X K (Kill Buffer) + Control-X K kills a buffer. *Note Control-X K: Buffers. + +M-X Insert Buffer + M-X Insert Buffer inserts the contents of another buffer + into the existing text of this buffer. *Note + Insert Buffer: Buffers. + +M-X Kill Some Buffers + M-X Kill Some Buffers offers to kill each buffer. *Note + Kill Some Buffers: Buffers. + +M-X Make Space + M-X Make Space tries to free up space inside EMACS for + more libraries or buffers. *Note Make Space: Lossage. + +M-X Rename Buffer + M-X Rename Buffer changes the name of the current + buffer. *Note Rename Buffer: Buffers. + +M-X What Available Space + M-X What Available Space prints the amount of space left + inside EMACS for more libraries or buffers. *Note + What Available Space: Lossage. + +Comments + +Meta-Linefeed (^R Indent New Comment Line) + Meta-Linefeed moves to a new line and indents it. If + point had been within a comment on the old line, a new + comment is started on the new line and indented under + the old one. *Note Meta-Linefeed: Comments. + +Meta-; (^R Indent for Comment) + Meta-; inserts a properly indented comment at the end of + the current line, or adjusts the indentation of an + existing comment. *Note Meta-;: Comments. + +Meta-N (^R Down Comment Line) + Meta-N moves down a line and starts a comment. *Note + Meta-N: Comments. + +Meta-P (^R Up Comment Line) + Meta-P moves down a line and starts a comment. *Note + Meta-P: Comments. + +Control-Meta-; (^R Kill Comment) + Control-Meta-; kills any comment on the current line. + *Note Control-Meta-;: Comments. + +Control-X ; (^R Set Comment Column) + Control-X ; sets the column at which comments are + indented, from an argument, the current column, or the + previous comment. *Note Control-X ;: Comments. + +Case Conversion + +Meta-C (^R Uppercase Initial) + Meta-C makes the next word lower case with a capital + initial. It moves over the word. *Note Meta-C: Case. + +Meta-L (^R Lowercase Word) + Meta-L moves over a word converting it to lower case. + *Note Meta-L: Case. + +Meta-U (^R Uppercase Word) + Meta-U moves over a word converting it to upper case. + *Note Meta-U: Case. + +Control-X Control-L (^R Lowercase Region) + Control-X Control-L converts the text of the region to + lower case. *Note Control-X Control-L: Case. + +Control-X Control-U (^R Uppercase Region) + Control-X Control-U converts the text of the region to + upper case. *Note Control-X Control-U: Case. + +Minor Corrections + +Meta-# (^R Change Font Region) + Meta-# inserts a font-change command good for certain + text justifiers around a word. *Note Fonts: Fonts. + +Meta-$ (^R Correct Word Spelling) + Meta-$ (Dollar sign, not Altmode) passes the word before + point to the SPELL program. If it is not a correct + spelling, you have the option of replacing it with a + corrected spelling. *Note Meta-$: Fixit. + +Meta-' (^R Upcase Digit) + Meta-' converts a digit before point on the same or + previous line to a punctuation character, assuming that + you failed to type the shift key and thus typed the + digit by mistake. *Note Meta-': Fixit. + +Meta-_ (^R Underline Word) + Meta-_ inserts underlining commands good for certain + text justifiers around a word. *Note Meta-_: + Underlining. + +Control-X # (^R Change Font Region) + Control-X # inserts font change commands good for + certain text justifiers around the region. *Note Fonts: + Fonts. + +Control-X _ (^R Underline Region) + Control-X _ inserts underlining commands good for + certain text justifiers around the region. *Note + Control-X _: Underlining. + +Windows + +Control-Meta-V (^R Scroll Other Window) + Control-Meta-V scrolls the other window up or down. + *Note Control-Meta-V: Display. + +Control-X 1 (^R One Window) + Control-X 1 returns to one-window mode. *Note + Control-X 1: Windows. + +Control-X 2 (^R Two Windows) + Control-X 2 splits the screen into two windows. *Note + Control-X 2: Windows. + +Control-X 3 (^R View Two Windows) + Control-X 3 splits the screen into two windows but stays + in window one. *Note Control-X 3: Windows. + +Control-X 4 (^R Visit in Other Window) + Control-X 4 displays two windows and selects a buffer or + visits a file in the other window. *Note Control-X 4: + Windows. + +Control-X O (^R Other Window) + Control-X O switches from one window to the other. + *Note Control-X O: Windows. + +Control-X ^ (^R Grow Window) + Control-X ^ changes the allocation of screen space to + the two windows. *Note Control-X ^: Windows. + +M-X Compare Windows + M-X Compare Windows compares the text in window one + after point with that in window two after point. It + advances point in both windows to the first non-matching + text. *Note Compare Windows: Windows. + +Narrowing + +Control-X N (^R Narrow Bounds to Region) + Control-X N narrows the virtual boundaries to the + region. *Note Control-X N: Narrowing. + +Control-X P (^R Narrow Bounds to Page) + Control-X P narrows the virtual boundaries to the + current page. *Note Control-X P: Pages. + +Control-X W (^R Widen Bounds) + Control-X W widens the virtual boundaries back to the + entire buffer. *Note Control-X W: Narrowing. + +Status Information + +Control-X = (What Cursor Position) + Control-X = prints information on the screen position + and character position of the cursor, the size of the + file, and the character after the cursor. *Note + Control-X =: Filling. + +Control-X L (^R Count Lines Page) + Control-X L prints the number of lines in the current + page, and how many come before or after point. *Note + Control-X L: Pages. + +M-X List Loaded Libraries + M-X List Loaded Libraries lists the names of all loaded + libraries. *Note List Loaded Libraries: Libraries. + +M-X List Variables + M-X List Variables lists the names and values of all + variables, or of those whose names contain a specified + string. *Note List Variables: Variables. + +M-X List Redefinitions + M-X List Redefinitions describes all the ways which the + major mode and local modes of the selected buffer modify + the standard EMACS. *Note List Redefinitions: + MajorModes. + +M-X What Page + M-X What Page prints the page and line number of point. + *Note What Page: Pages. + +Keyboard Macros + +Control-X ( (^R Start Kbd Macro) + Control-X ( begins defining a keyboard macro. *Note + Control-X (: KBDMAC. + +Control-X ) (^R End Kbd Macro) + Control-X ) terminates the definition of a keyboard + macro. *Note Control-X ): KBDMAC. + +Control-X E (^R Call Last Kbd Macro) + Control-X E executes the most recently defined keyboard + macro. *Note Control-X E: KBDMAC. + +Control-X Q (^R Kbd Macro Query) + Control-X Q in a keyboard macro can ask the user whether + to continue or allow him to do some editing before + continuing with the keyboard macro. *Note Control-X Q: + KBDMAC. + +M-X Name Kbd Macro + M-X Name Kbd Macro gives a permanent name to the last + keyboard macro defined. *Note Name Kbd Macro: KBDMAC. + +M-X View Kbd Macro + M-X View Kbd Macro prints the definition of a keyboard + macro. *Note View Kbd Macro: KBDMAC. + +Libraries + +M-X Kill Libraries + M-X Kill Libraries discards one or more libraries from + core. *Note Kill Libraries: Libraries. + +M-X List Library + M-X List Library describes briefly all the functions in + a library. *Note List Library: Libraries. + +M-X Load Library + M-X Load Library loads one library, permanently. *Note + Load Library: Libraries. + +M-X Run Library + M-X Run Library loads a library temporarily, invokes a + function in it, and then discards the library. *Note + Run Library: Libraries. + +Variables + +M-X Edit Options + M-X Edit Options lets you edit, in a recursive editing + level, the values of many variables. *Note + Edit Options: Variables. + +M-X Kill Local Q-register + M-X Kill Local Q-register makes a q-register or command + character definition no longer local to the selected + buffer. *Note Kill Local Q-register: (CONV)Vars. + +M-X Kill Local Variable M-X Kill Local Variable makes a variable value + no longer local to the selected buffer. *Note + Kill Local Variable: (CONV)Vars. + +M-X Kill Variable + M-X Kill Variable eliminates a particular variable. + *Note Kill Variable: Variables. + +M-X Make Local Q-register M-X Make Local Q-register makes a q-register + or command character definition local to the selected + buffer. *Note Make Local Q-register: (CONV)Vars. + +M-X Make Local Variable M-X Make Local Variable makes a variable value + local to the selected buffer. *Note + Make Local Variable: (CONV)Vars. + +M-X Set Key + M-X Set Key connects a function to a command character. + *Note Set Key: MMArcana. + +M-X Set Variable + M-X Set Variable sets the value of a variable. *Note + Set Variable: Variables. + +M-X View Variable + M-X View Variable displays the value and comment of a + variable. *Note View Variable: Variables. + +Mail + +Control-X M (Send Mail) + Control-X M allows you to edit and send a message using + your favorite mail-reading program. The default is + RMAIL. *Note Control-X M: Mail. + +Control-X R (Read Mail) + Control-X R runs your choice of mail-reading program to + read and edit your mail. The default is RMAIL. *Note + Control-X R: Mail. + +M-X View Mail + M-X View Mail displays your own or another user's mail + file using View File. *Note View Mail: Mail. + +Minibuffer + +Control-% (^R Replace String) + Control-% invokes a minibuffer containing a call to + Replace String. You fill in the arguments. *Note + Control-%: Replace. + +Meta-Altmode (^R Execute Minibuffer) + Meta-Altmode invokes an empty minibuffer which you can + fill in with a TECO program to be executed. *Note + Meta-Altmode: Minibuffer. + +Meta-% (^R Query Replace) + Meta-% invokes a minibuffer containing a call to Query + Replace. You fill in the arguments. *Note Meta-%: + Replace. + +Control-X Altmode (^R Re-execute Minibuffer) + Control-X Altmode re-executes a TECO program previously + executed in the minibuffer. It can also re-execute an + extended command. *Note Control-X Altmode: Minibuffer. + + + +EMACS Node: LibCat, Previous: CommandIndex, Up: Top, Next: VarIndex + +Catalog of Libraries + +Libraries Used Explicitly + +These are libraries which you must load with M-X Load +Library to use. If no cross-reference is given, the only +documentation for the library is the self-documentation contained in it. +Use M-X List Library to print a brief description of each +function in the library. For more detailed information, load the +library and use M-X Describe on individual functions. + +ABSTR contains commands for making documentation files: wall + charts, and abstracts of libraries. *Note ABSTR: + (CONV). + +BABYL is a subsystem for reading, sending and editing mail. + *Note BABYL: (BABYL). + +BCPL implements BCPL mode. + +BLISS implements BLISS mode. + +CACHE implements a cache for speeding up EMACS subroutine + calls. + +CHESS implements commands for editing pictures of chess + boards. + +CLU implements CLU mode. *Note CLU: (ECLU). + +COBOL implements COBOL mode. + +COLUMNS implements commands for converting single-column text + into double-column text and vice versa. + +DELIM implements commands for moving over balanced groupings + of various kinds of parentheses. There are a pair of + commands for square brackets, a pair for angle brackets, + etc. + +DOCLSP prints documentation from the MacLisp manual on a + specified Lisp function. + +DOCIX constructs indexes of Lisp manual files for DOCLSP. + +DOCOND is a macro processor and conditionalizer for text files, + useful for maintaining multiple versions of documents + with one source. + +DOCTOR contains DOCTOR mode, a psychiatrist. + +DRAW offers functions for editing pictures made of + characters. These partially duplicate the facilities of + the PICTURE library, but contain other distinct + features. + +FIXLIB functions for examining and patching EMACS functions. + +FORTRAN implements FORTRAN mode. *Note FORTRAN: (EFORTRAN). + +HAZ1510 redefines commands to be convenient on Hazeltine 1510 + terminals. + +INFO peruses tree-structured documentation files. + +IVORY is EAK and ECC's alternate generator for EMACS + libraries, which uses a slightly nonstandard input + format. The libraries BABYL, BABYLM, CACHE, FIXLIB, + IVORY, MKDUMP, OUTLINE-MODE, PL1, TEACH-C100, TMACS and + WORDAB are generated with IVORY. *Note IVORY: (IVORY). + +JOURNAL implements journal files. *Note Journals: Journals. + +LEDIT is the EMACS side of the EMACS-to-MacLisp interface. + *Note LEDIT: (LEDIT). + +LISPT is the EMACS side of another EMACS-to-MacLisp interface. + *Note LISPT: (LISPT). + +LSPUTL contains a couple of useful functions for searching and + manipulating Lisp code. + +LUNAR is Moon's personal library, which contains some useful + commands. + +MACCNV does part of the work of converting MACRO-10 code to + MIDAS code. + +MAZLIB is a game for solving mazes. It's fun to play. + +MKDUMP aids in dumping your own customized environment. *Note + MKDUMP: (MKDUMP). + +MODLIN implements a fancier mode line display. + +MQREPL works with TAGS to perform several Query Replaces on + each of the files in a tag table. + +NEWS is for reading the latest AP or New York Times news + summary. + +NOVICE implements restricted subsets of EMACS, for beginners. + The beginner can turn commands back on when he feels + ready. *Note Novice: (CONV)Novice. + +OUTLINE implements Outline Mode, for editing outlines. + +PAGE defines commands for viewing only one page of the file + at a time. *Note PAGE: PAGE. + +PASCAL implements PASCAL mode. *Note PASCAL: (EPASC). + +PHRASE has commands for moving over and killing phrases of + text. + +PICTURE contains Edit Picture, the command for editing text + pictures. *Note PICTURE: PICTURE. + +PL1 implements PL1 mode. *Note PL1: (EPL1). + +PURIFY generates libraries from EMACS source files, and + contains other functions useful for editing the source + files. *Note PURIFY: (CONV). + +QSEND sends a message to another logged-in user, like :QSEND. + +RENUM renumbers figures, equations, theorems or chapters. + +RMAIL is for reading, editing and sending mail. *Note RMAIL: + (RMAIL). + +RUNOFF is for text-justified documents divided into separate + source files. It rejustifies the files which have + changed, then runs :@ to print only the pages which have + changed. + +SAIL implements SAIL mode. + +SCRLIN contains alternative definitions of C-N and C-P which + move by screen lines instead of by real lines. + +SLOWLY redefines commands and options to suit slow terminals. + +SORT implements the sorting commands. + +SPLIT contains the commands Split File and Unsplit File for + breaking up large files into subfiles small enough to be + edited. *Note Split: Lossage. + +TDEBUG is a debugger for TECO programs. It displays the buffer + in one window and the program in the other, while + stepping by lines or setting breakpoints. *Note TDEBUG: + (TDEBUG). + +TIME causes the current time of day to be displayed in the + mode line. + +TMACS contains miscellaneous useful functions + +VT100 defines the arrow keys and numeric keypad of the VT-100 + terminal to move the cursor and supply numeric + arguments. + +VT52 defines the numeric keypad of the VT-52 terminal to + supply numeric arguments. + +Automatically Loaded Libraries + +These are libraries which the user need not know about to use. + +AUX implements several commands described in the manual as + part of the standard EMACS. Loaded automatically when + needed. + +BABYLM contains the part of Babyl that implements mail sending. + +BARE contains the definitions of all built-in functions. + These definitions are not needed for executing the + built-in functions, only so that Help can describe them + properly. Loaded automatically by documentation + commands when needed. *Note BARE: MMArcana. + +DIRED implements the commands for editing and listing + directories. Loaded automatically when needed. *Note + DIRED: DIRED. + +EINIT is used in building and dumping EMACS. *Note EINIT: + (CONV). + +EMACS is the main body of standard EMACS. Always loaded. + +GRIND implements C-M-G. Loaded automatically when needed. + *Note Grinding: Grinding. + +KBDMAC implements keyboard macros. Loaded automatically when + needed. *Note Keyboard Macros: KBDMAC. + +MUDDLE implements Muddle mode. Loaded automatically when + needed. + +SCRIBE implements SCRIBE mode. *Note SCRIBE: SCRIBE. Loaded + automatically when needed. + +TAGS implements the TAGS package. *Note TAGS: (TAGS)Top. + Loaded automatically when needed. + +TEX implements TEX mode. *Note TEX: (ETEX). Loaded + automatically when needed. + +WORDAB implements Word Abbrev mode. Loaded automatically when + needed. *Note WORDAB: (WORDAB)Top. + + + +EMACS Node: VarIndex, Previous: LibCat, Up: Top, Next: Screen + +Index of Variables + +An option is a variable whose value Edit Options offers for editing. A +hook variable is a variable which is normally not defined, but which you +can define if you wish for customization. Most hook variables require +TECO programs as their values. + +The default value of the variable is given in parentheses after its +name. If no value is given, the default value is zero. If the word +"nonexistent" appears, then the variable does not exist unless you +create it. + +Abort Resumption Message + This is the message to be printed by C-] to tell you how + to resume the aborted command. If this variable is + zero, there is no way to resume, so C-] asks for + confirmation. *Note Quitting: Quitting. + +Additional Abbrev Expanders (nonexistent) + If this variable exists when Word Abbrev mode is turned + on, it is a string of characters which should terminate + and expand an abbrev, in addition to the punctuation + characters which normally do so. See also WORDAB Ins + Chars. + +After Compilation Hook (nonexistent) + If this variable exists and is nonzero, then it is + executed as a TECO expression by the function Compile, + after compilation itself is finished. Exception: If the + variable Compile Command is also nonzero, it overrides + this hook. *Note After Compilation Hook: Compile. + +Atom Word Mode The minor mode Atom Word mode is on if this variable is + nonzero. *Note Atom Word Mode: MinorModes. + +Auto Directory Display + If this is nonzero, certain file operations + automatically display the file directory. *Note + Auto Directory Display: ListDir. + +Auto Fill Mode The minor mode Auto Fill mode is on if this variable is + nonzero. *Note Auto Fill Mode: Filling. + +Auto Push Point Notification + The value of this variable is the string printed in the + echo area by some commands to notify you that the mark + has been set to the old location of point. *Note + Auto Push Point Notification: Search. + +Auto Push Point Option (500) + Searches set the mark if they move at least this many + characters. *Note Auto Push Point Option: Search. + +Auto Save All Buffers + If this is nonzero, auto save saves all buffers that are + modified, not just the selected buffer. *Note + Auto Save All Buffers: AutoSave. + +Auto Save Default + The minor mode Auto Save mode is on by default for newly + visited files if this variable is nonzero. *Note + Auto Save Default: AutoSave. + +Auto Save Filenames (DSK:;_SAV00 >) + These are the filenames used for auto saving if the + visited filenames are not used. If the last two + characters of the first filename are "00", as they are + by default, then they are replaced by the last two + characters of the buffer number to get the filename + actually used for saving. *Note Auto Save Filenames: + AutoSave. + +Auto Save Interval (500) + This is the number of characters between auto saves. + *Note Auto Save Interval: AutoSave. + +Auto Save Max (2) + This is the maximum number of auto saves to keep. *Note + Auto Save Max: AutoSave. + +Auto Save Mode If this is nonzero, Auto Save mode is enabled. *Note + Auto Save Mode: AutoSave. + +Auto Save Visited File + If this is nonzero, auto saving saves as the visited + filenames. If this is zero, auto saving saves as the + names which are the value of Auto Save Filenames (q.v.). + *Note Auto Save Visited File: AutoSave. + +Autoarg Mode When Autoarg Mode is nonzero, numeric arguments can be + specified just by typing the digits. *Note + Autoarg Mode: Arguments. + +Bottom Display Margin + This controls the size of the region at the bottom of + the screen which the cursor is not allowed to be in. If + the cursor would normally move there, the window is + recentered instead. The value is represented as a + percentage of the screen size, and must not be negative + or more than 99. It controls the TECO flag FS %BOTTOM. + *Note Bottom Display Margin: Display. + +Buffer Creation Hook (nonexistent) + If this variable exists and is nonzero, its value should + be a TECO program to be executed whenever a newly + created buffer is selected for the first time. *Note + Buffer Creation Hook: Buffers. + +Buffer Deselection Hook (nonexistent) + If this variable exists and is nonzero, its value should + be a TECO program to be executed whenever a buffer is + about to be deselected. The difference between this and + Buffer Selection Hook is that, while both are executed + (if they exist) when you switch buffers, this is + executed before the switch, and Buffer Selection Hook is + executed after the switch. *Note + Buffer Deselection Hook: Buffers. + +Buffer Selection Hook (nonexistent) + If this variable exists and is nonzero, its value should + be a TECO program to be executed whenever a buffer is + selected. *Note Buffer Selection Hook: Buffers. + +Case Replace (1) + When Case Replace is nonzero, Replace String and Query + Replace attempt to preserve case when they replace. + *Note Case Replace: Replace. + +Case Search (1) + If Case Search is nonzero, searches of all sorts allow + upper case letters and lower case letters to match each + other. It controls the TECO flag FS BOTH CASE. *Note + Case Search: Search. + +Collapse in Comparison (nonexistent) + If this variable exists and is not zero, it should be a + string of characters for M-X Compare Windows to regard + as insignificant. *Note Collapse in Comparison: + Windows. + +Comment Begin This is the string used to start new comments. If it is + zero, the value of Comment Start is used. *Note + Comment Begin: Comments. + +Comment Column This is the column at which comments are aligned. *Note + Comment Column: Comments. + +Comment End This is the string which is used to end comments. It is + often empty for languages in which comments end at the + end of the line. *Note Comment End: Comments. + +Comment Multi Line (nonexistent) + If this variable exists and is nonzero, then when Auto + Fill mode breaks a comment line, it does not insert a + new comment starter on the new line. This is for use + with languages that have explicit comment terminators, + if you want single multi-line comments instead of + single-line comments on consecutive lines. *Note + Comment Multi Line: Comments. + +Comment Rounding (/8+1*8) + This is the TECO program used to decide what column to + start a comment in when the text of the line goes past + the comment column. The argument to the program is the + column at which text ends. *Note Comment Rounding: + Comments. + +Comment Start This is the string used for recognizing existing + comments, and for starting new ones if Comment Begin is + zero. If Comment Start is zero, semicolon is used. + *Note Comment Start: Comments. + +Compile Command (nonexistent) + If this variable exists and is nonzero, its value should + be a TECO program to be used by the M-X Compile command + to compile the file. *Note Compile Command: Compile. + +Compiler Filename (nonexistent) + If this variable exists and is nonzero, its value should + be the name of the compiler to use, suitable for a colon + command. By default, the name of the major mode is used + as the name of the compiler. *Note Compiler Filename: + Compile. + +Compiler Switches (nonexistent) + If this variable exists and is nonzero, its value is + used as switches for compilation. *Note + Compiler Switches: Compile. + +Cursor Centering Point (40) + This specifies how far from the top of the screen point + ought to appear when a new window position is chosen. + The value of the variable is the percentage of the + screen size. It must not be negative or more than 99. + It controls the TECO flag FS %CENTER. *Note + Cursor Centering Point: Display. + +Default Major Mode (Fundamental) + This is the major mode in which new buffers are created. + If it is the null string, new buffers are created in the + same mode as the previously selected buffer. *Note + Default Major Mode: Buffers. + +Digit Shift Table (nonexistent) + If this variable exists and is nonzero, its value should + be a string containing the ten characters which are the + upper case equivalents of the digits 0 through 9 on the + keyboard being used. Meta-' (^R Upcase Digit) uses this + table, and reads it from the user if the variable does + not exist. *Note Digit Shift Table: Fixit. + +Directory Lister (& Subset Directory Listing) + This is the TECO program used for listing a directory + for C-X C-D and the Auto Directory Display option. The + default value is the definition of the function & Subset + Directory Listing. Another useful value is the + definition of the function & Rotated Directory Listing. + *Note Directory Lister: ListDir. + +Display Matching Paren (-1) + This variable controls automatic display of the matching + open parenthesis when a close parenthesis is inserted. + *Note Display Matching Paren: Matching. + +Display Mode Line Inverse + If this is nonzero, the mode line is displayed in + inverse video or otherwise highlighted, on terminals + which can support it. This controls the TECO flag FS + INVMOD. *Note Display Mode Line Inverse: ModeLine. + +Display Overprinting + If this is nonzero, backspace characters and stray + carriage return characters in the buffer display as + actual overprinting rather than as ^H and ^M. This + variable controls the TECO flags FS ^H PRINT and FS ^M + PRINT. *Note Display Overprinting: Characters. + +Echo Area Height (3) + This is the number of lines in the echo area. Its value + should be at least one. It controls the TECO flag FS + ECHO LINES. *Note Echo Area Height: Screen. + +EMACS Version This variable's value is the EMACS version number. + +End of Buffer Display Margin (35) + This specifies how far up the screen the end of the + buffer is placed, if it is on screen at all, when a new + window position is chosen. It is represented as a + percentage of the screen size, and must not be negative + or more than 99. Its value controls the TECO flag FS + %END. *Note End of Buffer Display Margin: Display. + +Error Messages in Echo Area + If this is nonzero, error messages are printed in the + echo area instead of at the top of the screen. It + controls the TECO flag FS ECHO ERRORS. *Note + Error Messages in Echo Area: Lossage. + +Exit Hook (nonexistent) + If this variable exists and is nonzero, its value is a + TECO program to be executed whenever EMACS is exited. + The subroutine & Exit EMACS is responsible for executing + it. *Note Exit Hook: Exiting. + +Fill Column (70) + The value of Fill Column is the width used for filling + text. It controls the TECO flag FS ADLINE. *Note + Fill Column: Filling. + +Fill Extra Space List (.?!) + The characters in this string are the ones which ought + to be followed by two spaces when text is filled. *Note + Fill Extra Space List: Filling. + +Fill Prefix The value of this variable is the prefix expected on + every line of text before filling and placed at the + front of every line after filling. It is usually empty, + for filling nonindented text. *Note Fill Prefix: + Filling. + +Indent Tabs Mode (-1) + If Indent Tabs Mode is nonzero, then tab characters are + used by the indent commands. Otherwise, only spaces are + used. *Note Indent Tabs Mode: TextIndent. + + Setup Hook (nonexistent) + If this variable exists and is nonzero, its value should + be a TECO program to be executed when the library + is loaded. The library's & Setup function is + responsible for doing this. If the library has no + & Setup function, it will not handle a setup hook + either. *Note Libraries: Libraries. + + Kill Hook (nonexistent) + Some libraries may execute the value of this variable, + if it exists and is nonzero, when the library is being + removed from core with Kill Libraries. This is done by + the library's & Kill function; if the library has no + & Kill Library function, it will not handle a + kill hook. *Note Libraries: Libraries. + +Lisp Indent + This variable controls the indentation within calls to + the function . Actually, the variable used is + not always Lisp Indent, but rather + Indent, where is the value of Lisp + Indent Language. *Note Lisp Indent: + Indenting. + +Lisp Indent DEFanything (1) + The value of this variable controls indentation within + calls to functions whose names start with "def". + Actually, the variable used is not always Lisp Indent + DEFanything, but rather Indent DEFanything, + where is the value of Lisp Indent Language. + *Note Lisp Indent DEFanything: Indenting. + +Lisp Indent Language (Lisp) + The value of this variable is the string used as the + language name when looking for + Indent variables. *Note Lisp Indent Language: + Indenting. + +Lisp Indent Offset + If nonzero, this selects an alternative default style of + indentation for Lisp. Actually, the variable used is + not always Lisp Indent Offset, but rather + Indent Offset, where is the value of Lisp + Indent Language. *Note Lisp Indent Offset: Indenting. + +Mail Reader Library (nonexistent) + If this variable exists and is nonzero, it is the name + of the library to be used by M-X Read Mail for reading + mail and by M-X Send Mail for sending mail. The former + calls the function "" in the library, and the + latter calls the function "& Mail Message". If the + variable does not exist, the library RMAIL is used. + *Note Mail Reader Library: Mail. + +Mail Sender Library (nonexistent) + If this variable exists and is nonzero, it specifies the + library to be used by M-X Send Mail only, overriding + Mail Reader Library. *Note Mail Sender Library: Mail. + + ..D (nonexistent) + This variable is used by the major mode to record + the syntax table for that mode. It is created by the + first use of the mode, and if you supply your value, + that value will be accepted instead. For example, Text + mode uses Text ..D. Not all major modes have their own + syntax tables. *Note Syntax: Syntax. + + Mode Hook (nonexistent) + If this variable exists and is nonzero, its value is a + TECO program to be executed when the major mode + is entered. For example, Text Mode Hook is executed + when Text mode is entered. *Note Major Modes: + MajorModes. + +Next Screen Context Lines (nonexistent) + If this variable exists, its value specifies the number + of lines of overlap between one screenful and the next, + when scrolling by screens with C-V and M-V. *Note + Next Screen Context Lines: Display. + +Only Global Abbrevs (nonexistent) + If this variable exists and its value is nonzero, then + Word Abbrev Mode assumes that you are not using any + mode-specific abbrevs. *Note Only Global Abbrevs: + (WORDAB)Alternatives. + +Overwrite Mode If this is nonzero, the minor mode Overwrite mode is in + effect. It controls the TECO flag FS ^R REPLACE. + *Note Overwrite Mode: MinorModes. + +Page Delimiter ( ) + This is the TECO search string used to recognize page + boundaries. *Note Page Delimiter: Pages. + +PAGE Flush CRLF + If this variable exists and is nonzero, the PAGE library + expects every page to start with a blank line, which is + not considered part of the contents of the page. *Note + PAGE Flush CRLF: PAGE. + +Paragraph Delimiter (.  ') + This is the TECO search string used to recognize + beginnings of paragraphs. *Note Paragraph Delimiter: + Sentences. + +Permit Unmatched Paren (-1) + Controls whether the bell is run if you insert an + unmatched close parenthesis. *Note + Permit Unmatched Paren: Matching. + +Prefix Char List + This variable's value is a string which lists all the + prefix characters defined, so that self-documentation + facilities can find any subcommands of prefix characters + which call a given function. *Note Prefix Characters: + (CONV)Prefix. + +Quote Execute Command (nonexistent) + If this variable exists and is zero, then M-X does not + quote  characters which appear in the string arguments + of the command. *Note Quote Execute Command: MMArcana. + +Read Line Delay + This is the amount of time, in 30'ths of a second, which + EMACS should wait after starting to read a line of + input, before it prompts and starts echoing the input. + +Readable Word Abbrev Files (nonexistent) + If this variable exists and is nonzero, word abbrev + files will be written in the format that M-X List Word + Abbrevs uses, instead of in a less readable but faster + loading format. *Note Readable Word Abbrev Files: + (WORDAB)Saving. + +Region Query Size (5000) + Many commands which act on the region require + confirmation if the region contains more than this many + characters. *Note Region Query Size: Mark. + +Return from Superior Hook (nonexistent) + If this variable exists and is nonzero, its value should + be a TECO program to be executed whenever EMACS is + resumed after being exited. *Note + Return from Superior Hook: Exiting. + +SAIL Character Mode + If this is nonzero, characters in the buffer with ASCII + codes 0 through 37 are displayed without conversion. Do + not try to use this feature except on terminals + specially equipped to handle it. The variable controls + the TECO flag FS SAIL. *Note SAIL Character Mode: + Ideal. + +Save Word Abbrevs (nonexistent) + If this variable exists, its value determines which + abbrevs will be saved upon exit from EMACS when abbrevs + have been modified. Setting it to 1 causes all abbrevs + to be saved. *Note Save Word Abbrevs: (WORDAB)Saving. + Setting it to -1 causes just the incremental abbrevs to + be saved. *Note Save Word Abbrevs: (WORDAB)Dumping. + +Set Mode Line Hook + This is a hook which is executed every time the mode + line is recomputed. It can insert text in the buffer to + put it in the mode line after the minor modes. *Note + Set Mode Line Hook: ModeLine. + +SLOWLY Maximum Speed (nonexistent) + If this variable is defined, it is the maximum output + speed for which SLOWLY, if loaded, should define its + commands. *Note SLOWLY Maximum Speed: (SLOWLY)Options. + +Space Indent Flag + If this flag is nonzero, then Auto Fill indents the new + lines which it creates, by performing a Tab. Most major + modes for programming languages set this nonzero. *Note + Space Indent Flag: Filling. + +Tab Stop Definitions (a string) + The value of Tab Stop Definitions is a string defining + the tab stops to be used by the command M-I (^R Tab to + Tab Stop). *Note Tab Stop Definitions: TextIndent. + +Tags Find File (nonexistent) + If this variable exists and is not zero, TAGS uses C-X + C-F to switch files. Otherwise, TAGS uses C-X C-V. + *Note TAGS: (TAGS)Top. Some other things may decide to + use multiple buffers if this variable is nonzero. *Note + Tags Find File: Buffers. + +Tags Search Verbose (nonexistent) + If this variable exists and is zero, Tags Search does + not print out the name of each file that it begins to + search. If the variable is nonexistent, that is + equivalent to a value of 1. *Note Tags Search Verbose: + (TAGS)Search. + +Temp File FN2 List (MEMOXGP ...) + This is a TECO search string which recognizes the + filenames which indicate that the file is probably + temporary. *Note Temp File FN2 List: CleanDir. + +Top Display Margin + This controls the size of the region at the top of the + screen which the cursor is not allowed to be in. If the + cursor would normally move there, the window is + recentered instead. The value is represented as a + percentage of the screen size, and must not be negative + or more than 99. It controls the TECO flag FS %TOP. + *Note Top Display Margin: Display. + +Underline Begin (nonexistent) + If this variable exists, its value should be the + character or string to use to begin underlines for the + M-_ command. *Note Underline Begin: Underlining. + +Underline End (nonexistent) + If this variable exists, its value should be the + character or string to use to end underlines for the M-_ + command. *Note Underline End: Underlining. + +Visit File Hook (nonexistent) + If this variable exists and is nonzero, its value should + be a TECO program to be executed whenever a file is + visited. *Note Visit File Hook: Visiting. + +Visit File Save Old (1) + This variable controls whether visiting a file offers to + save the file previously visited in the same buffer, if + it has changes. *Note Visit File Save Old: Visiting. + +WORDAB All Caps (nonexistent) + If this variable exists and is nonzero, expanding an + all-upper-case abbrev to a multi-word expansion will + cause the words in the expansion to be all-upper-case, + instead of just having their first letters uppercased. + *Note WORDAB All Caps: (WORDAB)Expanding. + +WORDAB Ins Chars (nonexistent) + If this variable exists when Word Abbrev Mode is turned + on, it should be a string containing precisely those + characters which should terminate and expand an abbrev. + This variable overrides Additional Abbrev Expanders + (q.v.). *Note WORDAB: (WORDAB)Alternatives. + + + +EMACS Node: Screen, Previous: VarIndex, Up: Top, Next: Characters + +The Organization of the Screen + +EMACS divides the screen into several areas, each of which contains its +own sorts of information. The biggest area, of course, is the one in +which you usually see the text you are editing. The terminal's cursor +usually appears in the middle of the text, showing the position of +"point", the location at which editing takes place. While the cursor +appears to point AT a character, point should be thought of as BETWEEN +two characters; it points BEFORE the character that the cursor appears +on top of. Terminals have only one cursor, and when output is in +progress it must appear where the typing is being done. This does not +mean that point is moving. It is only that EMACS has no way to show you +the location of point except when the terminal is idle. + +The top lines of the screen are usually available for text but are +sometimes pre-empted by an "error message", which says that some command +you gave was illegal or used improperly, or by "typeout" from a command +(such as, a listing of a file directory). Error messages are typically +one line, end with a question mark, and are accompanied by ringing the +bell. Typeout generally has none of those characteristics. + +The error message or typeout appears there for your information, but it +is not part of the file you are editing, and it goes away if you type +any command. If you want to make it go away immediately but not do +anything else, you can type a Space. (Usually a Space inserts itself, +but when there is an error message or typeout on the screen it does +nothing but get rid of that.) The terminal's cursor always appears at +the end of the error message or typeout, but this does not mean that +point has moved. The cursor moves back to the location of point after +the error message or typeout goes away. + +If you type a question mark when an error message is on the screen, you +enter the EMACS error handler. You probably don't want to do this +unless you know how to write TECO programs. Enough said. + +A few lines at the bottom of the screen compose what is called the "echo +area". The variable Echo Area Height controls how many lines long it +is. "Echoing" means printing out the commands that you type. For +example, INFO echoes its commands in the echo area. EMACS commands are +usually not echoed at all, but if you pause for more than a second in +the middle of a multi-character command then all the characters typed so +far are echoed. This is intended to "prompt" you for the rest of the +command. The rest of the command is echoed, too, as you type it. This +behavior is designed to give confident users optimum response, while +giving hesitant users maximum feedback. + +EMACS also uses the echo area for reading and displaying the arguments +for some commands, such as searches, and for printing brief information +in response to certain commands. + +The line above the echo area is known as the "mode line". It is the +line that usually starts with "EMACS (something)". Its purpose is to +tell what is going on in the EMACS, and to show any reasons why commands +may not be interpreted in the standard way. The mode line is very +important, and if you are surprised by how EMACS reacts to your commands +you should look there for enlightenment. + + +* Menu: + +* Modeline:: Interpreting the mode line. + + + +EMACS Node: ModeLine, Previous: Screen, Up: Screen + +The Mode Line + +The line above the echo area is known as the "mode line". It is the +line that usually starts with "EMACS (something)". Its purpose is to +tell you anything that may affect the meaning of your commands aside +from the text itself. + +Some EMACS commands read and process more commands. They are known as +"subsystems" or "recursive editing levels". If you are inside a +subsystem or a recursive editing level, the mode line tells you its +name. Square brackets around the mode line indicate a recursive editing +level; *Note Recursive Editing Levels: Recursive. Parentheses indicate +a "minibuffer"; *Note Minibuffer: Minibuffer. Neither brackets nor +parentheses indicates a subsystem; *Note Subsystems: Subsystems. + +Subsystems and recursive editing levels are advanced features, and you +will not initially be using them. When you are not inside a subsystem +or recursive editing level, we say that you are at "top level"; this +implies that the characters you type are interpreted as ordinary EMACS +commands. When you are at top level, the mode line tells you what file +you are editing, where you are in it, and what editing modes are enabled +which may affect the meaning of your commands. The top level mode line +has this format: + + EMACS type (major minor) bfr: file (vrs) --pos-- * + +"type" is usually not there. When it is there, it indicates that the +EMACS job you are using is not an ordinary one, in that it is acting as +the servant of some other job. A type of "LEDIT" indicates an EMACS +serving one or more Lisps, while a type of "MAILT" indicates an EMACS +that you got by asking for an "edit escape" while composing mail to +send. The type can also indicate a subsystem that is running, such as +RMAIL. The type is stored internally as a string in the variable Editor +Type. The variable is normally zero. + +"major" is always the name of the "major mode" you are in. At any time, +EMACS is in one and only one of its possible major modes. The major +modes available include Fundamental mode (which EMACS starts out in), +Text mode, Lisp mode, PASCAL mode, and others. *Note Major Modes: +MajorModes, for details of how the modes differ and how to select one. +Sometimes the name of the major mode is followed immediately with +another name inside square-brackets ("[ - ]"). This name is called the +"submode". The submode indicates that you are "inside" of a command +that causes your editing commands to be changed temporarily, but does +not change WHAT text you are editing. A submode is a kind of recursive +editing level. *Note Submodes: Recursive. + +"minor" is a list of some of the "minor modes" that are turned on at the +moment. "Fill" means that Auto Fill mode is on. "Save" means that +Auto-saving is on. "Save(off)" means that Auto-saving is on by default +but turned off at the moment in this buffer. "Atom" means that Atom +Word mode is on. "Abbrev" means that Word Abbrev mode is on. "Ovwrt" +means that Overwrite mode is on. *Note Minor Modes: MinorModes, for +more information. "Def" means that a keyboard macro is being defined; +although this is not exactly a minor mode, it is still useful to be +reminded about. *Note Keyboard Macros: KBDMAC. "Narrow" means that +editing is currently restricted to only a part of the buffer. *Note +Narrowing: Narrowing. + +"bfr" is the name of the currently selected "buffer". Each buffer has +its own name and holds a file being edited; this is how EMACS can hold +several files at once. But at any time you are editing only one of +them, the "selected" buffer. When we speak of what some command does to +"the buffer", we are talking about the currently selected buffer. +Multiple buffers make it easy to switch around between several files, +and then it is very useful that the mode line tells you which one you +are editing at any time. However, before you learn how to use multiple +buffers, you will always be in the buffer called "Main", which is the +only one that exists when EMACS starts up. If the name of the buffer is +the same as the first name of the file you are visiting, then the buffer +name is left out of the mode line. *Note Buffers: Buffers, for how to +use more than one buffer in one EMACS. + +"file" is the name of the file that you are editing. It is the last +file that was visited in the buffer you are in. It is followed, in +parentheses, by the file "version number" most recently visited or saved +provided the second filename visited is ">", so that version numbers are +allowed. "(R-O)" after the filename means that the file or buffer is +"read-only"; a file visited read-only will not be saved unless you +insist, while a read-only buffer does not allow you to alter its +contents at all. *Note Visiting: Visiting, for more information. + +The star at the end of the mode line means that there are changes in the +buffer that have not been saved in the file. If the file has not been +changed since it was read in or saved, there is no star. + +"pos" tells you whether there is additional text above the top of the +screen, or below the bottom. If your file is small and it is all on the +screen, --pos-- is omitted. Otherwise, it is --TOP-- if you are looking +at the beginning of the file, --BOT-- if you are looking at the end of +the file, or --nn%-- where nn is the percentage of the file above the +top of the screen. + +Sometimes you will see --MORE-- instead of --nn%--. This happens when +typeout from a command is too long to fit on the screen. It means that +if you type a Space the next screenful of information will be printed. +If you are not interested, typing anything but a Space will cause the +rest of the output to be discarded. Typing a Rubout will discard the +output and do nothing else. Typing any other command will discard the +rest of the output and also do the command. When the output is +discarded, "FLUSHED" is printed after the --MORE--. + +If you are accustomed to other display editors, you may be surprised +that EMACS does not always display the page number and line number of +point in the mode line. This is because the text is stored in a way +that makes it difficult to compute this information. Displaying them +all the time would be too slow to be borne. When you want to know the +page and line number of point, you must ask for the information with the +M-X What Page command. *Note What Page: Pages. However, once you are +adjusted to EMACS, you will rarely have any reason to be concerned with +page numbers or line numbers. + + +EMACS Node: Characters, Previous: Screen, Up: Top, Next: Basic + +Character Sets and Command Input Conventions + +In this chapter we introduce the terminology and concepts used to talk +about EMACS commands. EMACS is designed to be used with a kind of +keyboard with two special shift keys which can type 512 different +characters, instead of the 128 different characters which ordinary ASCII +keyboards can send. The terminology of EMACS commands is formulated in +terms of these shift keys. So that EMACS can be used on ASCII +terminals, we provide two-character ASCII circumlocutions for the +command characters which are not ASCII. + +The 9-bit Command Character Set + +EMACS is designed ideally to be used with terminals whose keyboards have +a pair of shift keys, labeled "Control" and "Meta", either or both of +which can be combined with any character that you can type. These shift +keys produce "Control" characters and "Meta" characters, which are the +editing commands of EMACS. We name each of these characters by +prefixing "Control-" (or "C-"), "Meta-" (or "M-") or both to the basic +character: thus, Meta-F or M-F is the character which is F typed with +the Meta key held down. C-M-; is the Semicolon character with both the +Control and Meta keys. Control in the EMACS command character set is +not precisely the same as Control in the ASCII character set, but the +general purpose is the same. + +There are 128 basic characters. Multiplied by the four possibilities of +the Control and Meta keys, this makes 512 characters in the EMACS +command character set. So it is called the 512-character set, to +distinguish it from ASCII, which has only 128 characters. It is also +called the "9-bit" character set because 9 bits are required to express +a number from 0 to 511. Note that the 512-character set is used only +for keyboard commands. Characters in files being edited with EMACS are +ASCII characters. + +Sadly, most terminals do not have ideal EMACS keyboards. In fact, the +only ideal keyboards are at MIT. On nonideal keyboards, the Control key +is somewhat limited (it can only be combined with some characters, not +with all), and the Meta key may not exist at all. We make it possible +to use EMACS on a nonideal terminal by providing two-character +circumlocutions, made up of ASCII characters that you can type, for the +characters that you can't type. These circumlocutions start with a "bit +prefix" character; see below. For example, to use the Meta-A command, +you could type Altmode A. Also see the appendices for more detailed +information on what to do on your type of terminal. + +Both the EMACS 9-bit character set and ASCII have Control characters, +but the 9-bit character set has more different ones. In ASCII, only +letters and a few punctuation marks can be made into Control characters; +in the 9-bit character set every character has a Control version. For +example, we have Control-Space, Control-1, and Control-=. We also have +two different characters Control-A and Control-a! But they always do +the same thing in EMACS, so you can ignore the distinction between them, +unless you are doing customization. In practice, you can forget all +about the distinction between ASCII Control and EMACS Control, except to +realize that EMACS uses some "Control" characters which ASCII keyboards +cannot type. + +In addition to the 9-bit command character set, there is one additional +EMACS command character called Help. It cannot be combined with Control +or Meta. Its use is to ask for documentation, at any time. The Help +character has its own key on an ideal keyboard, but must be represented +by something else on other keyboards. The circumlocution we use is +Control-_ H (two characters). The code used internally for Help is 4110 +(octal). + +We have given some command characters special names which we always +capitalize. "Return" or "" stands for the carriage return +character, code 015 (all character codes are in octal). Note that C-R +means the character Control-R, never Return. "Rubout" is the character +with code 177, labeled "Delete" on some keyboards. "Altmode" is the +character with code 033, sometimes labeled "Escape". Other command +characters with special names are Tab (code 011), Backspace (code 010), +Linefeed (code 012), Space (code 040), Excl ("!", code 041), Comma (code +054), and Period (code 056). Control is represented in the numeric code +for a character by 200, and Meta by 400; thus, Meta-Period is code 456 +in the 9-bit character set. + +Prefix Characters + +A non-ideal keyboard can only send certain Control characters, and may +completely lack the ability to send Meta characters. To use these +commands on such keyboards, you need to use two-character +circumlocutions starting with a "bit prefix" character which turns on +the Control or Meta bit in the second character. The Altmode character +turns on the Meta bit, so Altmode X can be used to type a Meta-X, and +Altmode Control-O can be used to type a C-M-O. Altmode is known as the +"Metizer". Other bit prefix characters are C-^ for Control, and C-C for +Control and Meta together. Thus, C-^ < is a way of typing a Control-<, +and C-C < can be used to type C-M-<. Because C-^ is awkward to type on +most keyboards, we have tried to minimize the number of commands for +which you will need it. + +The bit prefix characters are simply commands which run the functions ^R +Prefix Control, ^R Prefix Meta, and ^R Prefix Control-Meta. + +There is another prefix character, Control-X which is used as the +beginning of a large set of two-character commands known as "C-X +commands". C-X is not a bit prefix character; C-X A is not a +circumlocution for any single character, and it must be typed as two +characters on any terminal. + +Commands, Functions, and Variables + +Most of the EMACS commands documented herein are members of this 9-bit +character set. Others are pairs of characters from that set. However, +EMACS doesn't really implement commands directly. Instead, EMACS is +composed of "functions", which have long names such as "^R Down Real +Line" and definitions which are programs that perform the editing +operations. Then "commands" such as C-N are connected to functions +through the "command dispatch table". When we say that C-N moves the +cursor down a line, we are glossing over a distinction which is +unimportant for ordinary use, but essential for customization: it is the +function ^R Down Real Line which knows how to move down a line, and C-N +moves down a line because it is connected to that function. We usually +ignore this subtlety to keep things simple. To give the +extension-writer the information he needs, we state the name of the +function which really does the work in parentheses after mentioning the +command name. For example: "C-N (^R Down Real Line) moves the cursor +down a line". In the EMACS wall chart, the function names are used as a +form of very brief documentation for the command characters. *Note +Functions: MMArcana. + +The "^R " which appears at the front of the function name is simply part +of the name. By convention, a certain class of functions have names +which start with "^R ". + +While we are on the subject of customization information which you +should not be frightened of, it's a good time to tell you about +"variables". Often the description of a command will say "to change +this, set the variable Mumble Foo". A variable is a name used to +remember a value. EMACS contains many variables which are there so that +you can change them if you want to customize. The variable's value is +examined by some command, and changing the value makes the command +behave differently. Until you are interested in customizing, you can +ignore this information. When you are ready to be interested, read the +basic information on variables, and then the information on individual +variables will make sense. *Note Variables: Variables. + +Notational Conventions for ASCII Characters + +Control characters in files, your EMACS buffer, or TECO programs, are +ordinary ASCII characters. The special 9-bit character set applies only +to typing EMACS commands. ASCII contains the printing characters, +rubout, and some control characters. Most ASCII control characters are +represented in this manual as uparrow or caret followed by the +corresponding non-control character: control-E is represented as . + +Some ASCII characters have special names. These include tab (011), +backspace (010), linefeed (012), return (015), altmode (033), space +(040), and rubout (177). To make it clear whether we are talking about +a 9-bit character or an ASCII character, we capitalize names of 9-bit +characters and leave names of ASCII characters in lower case. Note that +the 9-bit characters Tab and Control-I are different, but the ASCII +characters tab and control-I are the same. + +Lines in files are separated by a sequence of two ASCII control +characters, carriage return followed by linefeed. This sequence is +called "CRLF". Normally, EMACS treats this two-character sequence as if +it were a single character, a "line separator". A return or a linefeed +which is not part of a CRLF is called "stray". EMACS usually treats +them as part of the text of a line and displays them as ^M and ^J. If +the variable Display Overprinting is zero, they display as actual +carriage return or linefeed. + +Most control characters when present in the EMACS buffer are displayed +with a caret; thus, ^A for ASCII . Rubout is displayed as ^?, because +by stretching the meaning of "control" it can be interpreted as ASCII +control-?. A backspace is usually displayed as ^H since it is ASCII +control-H, because most displays cannot do overprinting. If you want +backspace and stray return to display as overprinting, set the variable +Display Overprinting nonzero. + +Altmode is the ASCII code 033, sometimes labeled "Escape" or "Alt". +Altmode is often represented by itself in this document (remember, it is +an ASCII character and can therefore appear in files). It looks like +this: . This is also how it appears on the screen if you insert it in +your file. On most terminals, altmode looks just like the dollar sign +character. If that's so on yours, you should assume that anything you +see in this document which looks like a dollar sign is really an altmode +unless you are specifically told it's a dollar sign. The dollar sign +character is not particularly important in EMACS and we will rarely have +reason to mention it. + +Now turn to the node that describes the keyboard you are using. + + +* Menu: + +* Ideal:: for keyboards that have a "Meta" key. +* EditKey:: for keyboards that have an "Edit" key. +* Losers:: for keyboards that have neither "Meta" nor "Edit." + + + + There are special commands designed to make life tolerable on +terminals which cannot send or display lower case. +* NoLowerCase:: for how to use them. + + The SLOWLY library changes a few commands to perform less redisplay. +This is useful on slow terminals. +* SLOWLY: (SLOWLY), for more information. + + You can even use EMACS on a printing terminal or glass teletype. +* Printing:: for how. + + + +EMACS Node: Basic, Previous: Characters, Up: Top, Next: Arguments + +Basic Editing Commands + +We now give the basics of how to enter text, make corrections, and save +the text in a file. If this material is new to you, you might learn it +more easily by running the :TEACHEMACS program. + +Inserting Text + +To insert printing characters into the text you are editing, just type +them. When EMACS is at top level, all printing characters you type are +inserted into the text at the cursor (that is, at "point"), and the +cursor moves forward. Any characters after the cursor move forward too. +If the text in the buffer is FOOBAR, with the cursor before the B, then +if you type XX, you get FOOXXBAR, with the cursor still before the B. + +To correct text you have just inserted, you can use Rubout. Rubout +deletes the character BEFORE the cursor (not the one that the cursor is +on top of or under; that is the character AFTER the cursor). The cursor +and all characters after it move backwards. Therefore, if you type a +printing character and then type Rubout, they cancel out. + +To end a line and start typing a new one, type Return (Customizers, +note: this runs the function ^R CRLF). Return operates by inserting a +line separator, so if you type Return in the middle of a line, you break +the line in two. Return really inserts two characters, a carriage +return and a linefeed (a CRLF), but almost everything in EMACS makes +them look like just one character, which you can think of as a +line-separator character. For example, typing Rubout when the cursor is +at the beginning of a line rubs out the line separator before the line, +joining that line with the preceding line. + +If you add too many characters to one line, without breaking it with a +Return, the line will grow to occupy two (or more) lines on the screen, +with a "!" at the extreme right margin of all but the last of them. The +"!" says that the following screen line is not really a distinct line in +the file, but just the "continuation" of a line too long to fit the +screen. + +Direct insertion works for printing characters and space, but other +characters act as editing commands and do not insert themselves. If you +need to insert a control character, Altmode, Tab or Rubout, you must +"quote" it by typing the Control-Q (^R Quoted Insert) command first. +*Note Control: Characters. Inserting a  is harder because EMACS +cannot even receive the character; you must use the minibuffer as in +Altmode Altmode 26I Altmode Altmode. *Note Minibuffer: Minibuffer. + +Moving The Cursor + +To do more than insert characters, you have to know how to move the +cursor. Here are a few of the commands for doing that. + + C-A Move to the beginning of the line. + C-E Move to the end of the line. + C-F Move forward over one character. + C-B Move backward over one character. + C-N Move down one line, vertically. If you start in the + middle of one line, you end in the middle of the next. + From the last line of text, it creates a new line. + C-P Move up one line, vertically. + C-L Clear the screen and reprints everything. C-U C-L + reprints just the line that the cursor is on. + C-T Transpose two characters (the ones before and after the + cursor). + M-< Move to the top of your text. + M-> Move to the end of your text. + +Erasing Text + + Rubout Delete the character before the cursor. + C-D Delete the character after the cursor. + C-K Kill to the end of the line. + +You already know about the Rubout command which deletes the character +before the cursor. Another command, Control-D, deletes the character +after the cursor, causing the rest of the text on the line to shift +left. If Control-D is typed at the end of a line, that line and the +next line are joined together. + +To erase a larger amount of text, use the Control-K command, which kills +a line at a time. If Control-K is done at the beginning or middle of a +line, it kills all the text up to the end of the line. If Control-K is +done at the end of a line, it joins that line and the next line. + +*Note Killing: Killing, for more flexible ways of killing text. + +Files + +The commands above are sufficient for creating text in the EMACS buffer. +The more advanced EMACS commands just make things easier. But to keep +any text permanently you must put it in a "file". Files are the objects +which ITS uses for storing data for communication between different +programs or to hold onto for a length of time. To tell EMACS to edit +text in a file, choose a "filename", such as FOO, and type C-X C-V +FOO. This "visits" the file FOO (actually, FOO > on your working +directory) so that its contents appear on the screen for editing. You +can make changes, and then "save" the file by typing C-X C-S. This +makes the changes permanent and actually changes the file FOO. Until +then, the changes are only inside your EMACS, and the file FOO is not +really changed. If the file FOO doesn't exist, and you want to create +it, visit it as if it did exist. When you save your text with C-X C-S +the file will be created. + +Of course, there is a lot more to learn about using files. *Note Files: +Files. + +Help + +If you forget what a command does, you can find out with the Help +character. The Help character is Top-H if you have a Top key, or +Control-_ H (two characters!) otherwise. Type Help followed by C and +the command you want to know about. Help can help you in other ways as +well. *Note Help: Help. + +Using Blank Lines Can Make Editing Faster + + C-O Insert one or more blank lines after the cursor. + C-X C-O Delete all but one of many consecutive blank lines. + + +It is much more efficient to insert text at the end of a line than in +the middle. So if you want to stick a new line before an existing one, +the best way is to make a blank line there first and then type the text +into it, rather than inserting the new text at the beginning of the +existing line and finally inserting a line separator. Making the blank +line first also makes the meaning of the text clearer while you are +typing it in. + +To make a blank line, you can type Return and then C-B. But there is a +single character for this: C-O (Customizers: this is the built-in +function ^R Open Line). So, FOO Return is equivalent to C-O FOO. + +If you want to insert many lines, you can type many C-O's at the +beginning (or you can give C-O an argument to tell it how many blank +lines to make. *Note Arguments: Arguments, for how). As you then +insert lines of text, you will notice that Return behaves strangely: it +"uses up" the blank lines instead of pushing them down. + +If you don't use up all the blank lines, you can type C-X C-O (the +function ^R Delete Blank Lines) to get rid of all but one. When point +is on a blank line, C-X C-O replaces all the blank lines around that one +with a single blank line. When point is on a nonblank line, C-X C-O +deletes any blank lines following that nonblank line. + + +EMACS Node: Arguments, Previous: Basic, Up: Top, Next: M-X + +Giving Numeric Arguments to EMACS Commands + +Any EMACS command can be given a "numeric argument". Some commands +interpret the argument as a repetition count. For example, giving an +argument of ten to the C-F command (move forward one character) moves +forward ten characters. With these commands, no argument is equivalent +to an argument of 1. + +Some commands care only about whether there is an argument, and not +about its value; for example, the command M-Q (^R Fill Paragraph) with +no arguments fills text, but with an argument justifies the text as +well. + +Some commands use the value of the argument, but do something peculiar +when there is no argument. For example, the C-K (^R Kill Line) command +with an argument kills lines and the line separators that follow +them. But C-K with no argument is special; it kills the text up to the +next line separator, or, if point is right at the end of the line, it +kills the line separator itself. Thus, two C-K commands with no +arguments can kill a nonblank line, just like C-K with an argument of +one. + +The fundamental way of specifying an argument is to use the C-U +(^R Universal Argument) command followed by the digits of the argument. +Negative arguments are allowed. Often they tell a command to move or +act backwards. A negative argument is entered with C-U followed by a +minus sign and the digits of the value of the argument. + +C-U followed by a character which is neither a digit nor a minus sign +has the special meaning of "multiply by four". It multiplies the +argument for the next command by four. Two such C-U's multiply it by +sixteen. Thus, C-U C-U C-F moves forward sixteen characters. This is a +good way to move forward "fast", since it moves about 1/4 of a line on +most terminals. Other useful combinations are C-U C-N, C-U C-U C-N +(move down a good fraction of a screen), C-U C-U C-O (make "a lot" of +blank lines), and C-U C-K (kill four lines). With commands like M-Q +that care whether there is an argument but not what the value is, C-U is +a good way of saying "I want an argument". + +A few commands treat a plain C-U differently from an ordinary argument. +A few others may treat an argument of just a minus sign differently from +an argument of -1. These unusual cases will be described when they come +up; they are always for reasons of convenience of use. + +There are other, terminal-dependent ways of specifying arguments. They +have the same effect but may be easier to type. *Note +Terminal-specific: Characters. If your terminal has a numeric keypad +which sends something recognizably different from the ordinary digits, +it is possible to program EMACS to allow use of the numeric keypad for +specifying arguments. The libraries VT52 and VT100 provide such a +feature for those two types of terminals. *Note Libraries: Libraries. + +Autoarg Mode + +Users of ASCII keyboards may prefer to use Autoarg mode. Autoarg mode +means that you don't need to type C-U to specify a numeric argument. +Instead, you type just the digits. Digits followed by an ordinary +inserting character are themselves inserted, but digits followed by an +Altmode or Control character serve as an argument to it and are not +inserted. A minus sign can also be part of an argument, but only at the +beginning. If you type a minus sign following some digits, both the +digits and the minus sign are inserted. + +To use Autoarg mode, set the variable Autoarg Mode nonzero. *Note +Variables: Variables. + +Autoargument digits echo at the bottom of the screen; the first nondigit +causes them to be inserted or uses them as an argument. To insert some +digits and nothing else, you must follow them with a Space and then rub +it out. C-G cancels the digits, while Rubout inserts them all and then +rubs out the last. + + +EMACS Node: M-X, Previous: Arguments, Up: Top, Next: Subsystems + +Extended (Meta-X) Commands and Functions + +Not all EMACS commands are of the one or two character variety you have +seen so far. Most commands have long names composed of English words. +This is for two reasons: the long names are easier to remember and more +suggestive, and there are not enough two-character combinations for +every command to have one. + +The commands with long names are known as "extended commands" because +they extend the set of two-character commands. + +Issuing Extended Commands + + M-X Begin an extended command. Follow by command + name and arguments. + C-M-X Begin an extended command. Follow by the + command name only; the command will ask for any + arguments. + C-X Altmode Re-execute recent extended command. + +Extended commands are also called "M-X commands", because they all start +with the character Meta-X (^R Extended Command). The M-X is followed by +the command's long, suggestive name, actually the name of a function to +be called. Terminate the name of the function with a Return (unless you +are supplying string arguments; see below). For example, Meta-X Auto +Fill Mode invokes the function Auto Fill Mode. This function when +executed turns Auto Fill mode on or off. + +We say that M-X Foo "calls the function Foo". When documenting the +individual extended commands, we will call them "functions" to avoid +confusion between them and the one or two character "commands". We will +also use "M-X" as a title like "Mr." for functions, as in "use M-X Foo". +The "extended command" is what you type, starting with M-X, and what the +command does is call a function. The name that goes in the command is +the name of the command and is also the name of the function, and both +terms will be used. + +Note: Extended commands and functions were once called "MM commands", +but this term is obsolete. If you see it used either in INFO +documentation of in Help documentation, please report it. Ordinary one +or two character commands used to be known as "^R" commands; please +report any occurrences of this obsolete term also. + +There are a great many functions in EMACS for you to call. They will be +described elsewhere in the manual, according to what they do. Here we +are concerned only with extended commands in general. + +Typing The Command Name + +When you type M-X, the cursor moves down to the echo area at the bottom +of the screen. "M-X" is printed there, and when you type the command +name it echoes there. This is known as "reading a line in the echo +area". You can use Rubout to cancel one character of the command name, +or C-U or C-D to cancel the entire command name. A C-G cancels the +whole M-X, and so does a Rubout when the command name is empty. These +editing characters apply any time EMACS reads a line in the echo area, +not just within M-X. + +The string "M-X" which appears in the echo area is called a "prompt". +The prompt always tells you what sort of argument is required and what +it is going to be used for; "M-X" means that you are inside of the +command M-X, and should type the name of a function to be called. You +can replace the prompt "M-X" with some other string by defining the +variable Read Command Prompt. + +Completion + +You can abbreviate the name of the command, typing only the beginning of +the name, as much as is needed to identify the command unambiguously. +You can also use completion on the function name. This means that you +type part of the command name, and EMACS visibly fills in the rest, or +as much as can be determined from the part you have typed. + +You request completion by typing an Altmode (). For example, if you +type M-X Au, the "Au" expands to "Auto " because all command names +which start with "Au" continue with "to ". If you ask for completion +when there are several alternatives for the next character, the bell +rings and nothing else happens. Altmode is also the way to terminate +the command name and begin the string arguments, but it only does this +if the command name completes in full. In that case, an Altmode appears +after the command name in the echo area. In practice, these two +meanings of Altmode do not conflict, because if the command name does +not complete in full, it is ambiguous and would not be accepted. So it +would be useless to type the arguments yet. + +Space is another way to request completion, but it completes only one +word. Successive Spaces complete one word each, until either there are +multiple possibilities or the end of the name is reached. If the first +word of a command is Edit, List, Kill, View or What, it is sufficient to +type just the first letter and complete it with a Space. (This does not +follow from the usual definition of completion, since the single letter +is ambiguous; it is a special feature added because these words are so +common). + +Typing "?" in the middle of the command name prints a list of all the +command names which begin with what you have typed so far. You can then +go on typing the name. + +Numeric Arguments and String Arguments + +Some functions can use numeric prefix arguments. Simply give the Meta-X +command an argument and Meta-X will pass it along to the function which +it calls. The argument appears before the "M-X" in the prompt, as in +"69 M-X", to remind you that the function you call will receive a +numeric argument. + +Some functions require "string arguments" (sometimes called "suffix +arguments"). To specify string arguments, terminate the function name +with a single Altmode, then type the arguments, separated by Altmodes. +After the last argument, type a Return to cause the function to be +executed. For example, the function Describe prints the full +documentation of a function (or a variable) whose name must be given as +a string argument. An example of using it is + + Meta-X DescribeApropos + +which prints the full description of the function named Apropos. + +An alternate way of calling extended commands is with the command C-M-X +(^R Instant Extended Command). It differs from plain M-X in that the +function itself reads any string arguments. The function prompts for +each argument individually. If an argument is supposed to be a filename +or a command name, completion is available. However, there are +compensating disadvantages. For one thing, since the function has +already been invoked, you can't rub out from the arguments into the +function name. For another, it is not possible to save the whole thing, +function name and arguments, for you to recall with C-X Altmode (see +below). So C-M-X saves nothing for C-X Altmode. The prompt for C-M-X +is "C-M-X". You can override it with the variable Instant Command +Prompt. + +Repeating an Extended Command + +The last few extended commands you have executed are saved and you can +repeat them. We say that the extended command is saved, rather than +that the function is saved, because the whole command, including +arguments, is saved. + +To re-execute a saved command, use the command C-X Altmode +(^R Re-execute Minibuffer). It retypes the last extended command and +asks for confirmation. With an argument, it repeats an earlier extended +command: 2 means repeat the next to the last command, etc. You can also +use the minibuffer to edit a previous extended command and re-execute it +with changes (*Note Minibuffer: Minibuffer.). + +*Note MM: MMArcana, for more information on this and other topics +related to how extended commands work, how they are really the +foundation of everything in EMACS, and how they relate to customization. + + +EMACS Node: MMArcana, Previous: M-X, Up: M-X + +Arcane Information about M-X Commands + +You can skip this section if you are not interested in customization, +unless you want to know what is going on behind the scenes. + +MM + +Extended commands were once called "MM" commands, because "MM" is a TECO +expression which looks up a command name to find the associated program, +and runs that program. Thus, the TECO expression + + MM AproposWord + +means to run the Apropos command with the argument "word". You could +type this expression into a minibuffer and get the same results as you +would get from Meta-X AproposWord. In fact, for the first year or +so, EMACS had no Meta-X command, and that's what people did. *Note +Minibuffer: Minibuffer, for information on the minibuffer. + +"MM" actually tells TECO to call the subroutine in q-register "M". The +first "M" means "call", and the second "M" says what to call. This +subroutine takes a string argument which is the name of a function and +looks it up. Calling a function is built into TECO, but looking up the +name is not; it is implemented by the program in q-register M. That's +why "MM" is called that and not "Run" or "F". + +Arguments in TECO Code + +Functions can use one or two "prefix arguments" or "numeric arguments". +These are numbers (actually, TECO expressions) which go before the "MM". +Meta-X can only give the MM command one argument. If you want to give +it two, you must type it in using the minibuffer. When TECO code passes +prefix arguments, they don't have to be numbers; they can also be string +objects, TECO buffer objects, etc. However, no more about that here. + +TECO code can also pass "string arguments" or "suffix arguments". When +TECO code passes a string argument, it appears, terminated by an +Altmode, after the Altmode which ends the function name. There can be +any number of string arguments. In fact, the function can decide at run +time how many string arguments to read. This makes it impossible to +compile TECO code! + +Since Altmode terminates a string argument, TECO has a quoting +convention to allow Altmodes to be part of a string argument. This +convention is to use the two characters  Altmode to cause just an +Altmode to be part of the argument.  also must be quoted, as  . +The M-X command hides all of this: there is no way to quote an Altmode; +every Altmode always terminates a string argument;  is not special, +because M-X automatically replaces each  with two. If you understand +the TECO meaning of  you can enable its use in M-X command arguments +by setting the variable Quote Execute Command nonzero. Then M-X does no +special processing to  characters. You can use them to quote +Altmodes, and you must also take care of quoting  characters +themselves. + +Commands and Functions + +Actually, every command in EMACS simply runs a function. For example, +when you type the command C-N, it runs the function "^R Down Real Line". +You could just as well do C-U 1 M-X ^R Down Real Line and get the +same effect. C-N can be thought of as a sort of abbreviation. We say +that the command C-N has been "connected" to the function ^R Down Real +Line. The name is looked up once when the command and function are +connected, so that it does not have to be looked up again each time the +command is used. For historical reasons, the default argument passed to +a function which is connected to a command you typed is 1, but the +default for MM and for M-X is 0. This is why the C-U 1 was necessary in +the example above. The documentation for individual EMACS commands +usually gives the name of the function which really implements the +command in parentheses after the command itself. + +Just as any function can be called directly with M-X, so almost any +function can be connected to a command. You can use the function Set +Key to do this. Set Key takes the name of the function as a string +argument, then reads the character command (including metizers or other +prefix characters) directly from the terminal. To define C-N, you could +type + + M-X Set Key^R Down Real Line + +and then type C-N. If you use the function View File often, you could +connect it to the command C-X V (not normally defined). You could even +connect it to the command C-M-V, replacing that command's normal +definition. Set Key is good for redefining commands in the middle of +editing. An init file or EVARS file can do it each time you run EMACS. +*Note Init: Init. + +Subroutines + +EMACS is composed of a large number of functions, each with a name. +Some of these functions are connected to commands; some are there for +you to call with M-X; some are called by other functions. The last +group are called subroutines. They usually have names starting with +"&", as in "& Read Line", the subroutine which reads a line in the echo +area. Although most subroutines have such names, any function can be +called as a subroutine. Functions like ^R Down Real Line have names +starting with ^R because you are not expected to call them directly, +either. The purpose of the "&" or "^R" is to get those function names +out of the way of command completion in M-X. M-X allows the command +name to be abbreviated if the abbreviation is unique, and the commands +that you are not interested in might have names that would interfere and +make some useful abbreviation cease to be unique. The funny characters +at the front of the name prevent this from happening. + +Built-in Functions + +Not all of the functions in EMACS are written in TECO. A few of the +most frequently used single-character commands have definitions written +in machine language. These include self-inserting characters, Rubout, +C-F, and others. Such functions defined in machine language as part of +TECO are called "built-in" functions. Whereas the actual definition of +an ordinary function is a string, the definition of a built-in function +is just a number, the address of a routine in TECO. + +Built-in functions can be confusing because the Help features know their +names, but M-X normally does not. Their EMACS "definitions" are needed +only for the sake of documentation and not for actually executing the +functions, so they are put in a special library called BARE which is +loaded only while the Help features are working. + +For example, ^R Forward Character is the name of the function which +implements the C-F command. If you try to invoke ^R Forward Character +with M-X, since BARE is not loaded, the name is not defined. Set Key +and EVARS files have the same difficulties. You can make the names +permanently available for all these purposes by loading BARE with M-X +Load LibraryBARE. (You could kill the BARE library after using it, +since the definitions work fine once installed even if BARE is not +loaded). However, in EVARS files, it is better to use the FS ^R INIT +command to obtain the definition of a built-in function. + + +EMACS Node: Subsystems, Previous: M-X, Up: Top, Next: Recursive + +Subsystems + +A "subsystem" is an EMACS function which is an interactive program in +its own right: it reads commands in a language of its own, and displays +the results. You enter a subsystem by typing an EMACS command which +invokes it. Once entered, the subsystem runs until a specific command +to exit the subsystem is typed. An example of an EMACS subsystem is +INFO itself. Others are Backtrace and TDEBUG, used for debugging TECO +programs, and RMAIL and BABYL, used for reading and editing mail files. + +The commands understood by a subsystem are usually not like EMACS +commands, because their purpose is something other than editing text. +For example, INFO commands are designed for moving around in a +tree-structured documentation file. In EMACS, most commands are Control +or Meta characters because printing characters insert themselves. In +most subsystems, there is no insertion of text, so non-Control non-Meta +characters can be the commands. + +While you are inside a subsystem, the mode line usually gives the name +of the subsystem (as well as other information supplied by the +subsystem, such as the filename and node name in INFO). You can tell +that you are inside a subsystem because the mode line does not start +with "EMACS", or with an open bracket ("[") which would indicate a +recursive editing level. *Note Mode Line: ModeLine. + +Because each subsystem implements its own commands, we cannot guarantee +anything about them. However, there are conventions for what certain +commands ought to do: + + C-] Aborts (exits without finishing up). + Backspace Scrolls backward, like M-V in EMACS. + Space Scrolls forward, like C-V in EMACS. + Q Exits normally. + X Begins an extended command, like M-X in EMACS. + Help or ? Prints documentation on the subsystem's + commands. + +Not all of these necessarily exist in every subsystem, however. + +One important subsystem is RMAIL, used for reading mail. *Note Mail: +Mail. + + +EMACS Node: Mail, Previous: Subsystems, Up: Subsystems + +Reading Mail + +The easiest way to look at your new mail is to use M-X View Mail. This +displays the mail file with View File. *Note View File: FilAdv. To +view someone else's mail, give his user name as an argument to M-X View +Mail. + +When you want to edit your mail instead of just looking at it, use C-X R +(Read Mail). This invokes the mail reading subsystem RMAIL. *Note +RMAIL: (RMAIL)Top. If you prefer some other mail reader, you can set +the variable Mail Reader Library to the name of the library to use. + +You can send mail from within RMAIL as well as edit your mail. But if +you want to send just one message, the easiest way is Control-X M (Send +Mail). You edit the message, exit with C-M-C, and the message is sent; +or else you abort with C-]. C-X M works by invoking RMAIL or whatever +library you use to read mail at a special entry point named & Mail +Message. The same library used for reading mail is used, normally, but +you can specify a different one by setting the variable Mail Sender +Library. + +The function Type Mailing List in the TMACS library is useful for +finding out where a mailing list forwards to. Invoke it with + + M-X Run LibraryTMACSType Mailing List + +and the equivalences of the mail address will be printed. Type Mailing +List prints the immediate equivalences of the mailing list you specify, +then traces their equivalences, down to terminal addresses or addresses +on non-ITS machines. Mailing lists on other ITS machines can be traced; +simply include the site name in the argument. However, no lists on DM +can be traced because DM's forwarding data base is incompatible. *Note +Libraries: Libraries. + + +EMACS Node: Recursive, Previous: Subsystems, Up: Top, Next: Exiting + +Recursive Editing Levels + +A "recursive editing level" is a state in which part of the execution of +one command involves doing some editing. You may be editing the file +you are working on, or you may be editing completely something totally +different from what you were working on at top level. Recursive editing +levels are indicated in the mode line by square brackets ("[" and "]"). + +For example, the command M-X Edit Options allows you to change the +settings of EMACS options. During the execution of this command, you +enter a recursive editing level in which you edit a list of options +names and values using the usual EMACS editing commands. While this is +going on, the mode line says "[Edit Options]" to inform you that you are +in a recursive editing level and why. When you "exit" the recursive +editing level, the Edit Options command continues its work by looking at +the changes you have made in the list of options and changing the actual +option values accordingly. Only then is the original Edit Options +command finished. + +Alternatively, you can "abort" the recursive editing level, which gets +you out of the Edit Options command and back to top level, without +allowing the command to finish. + +A recursive editing level differs from a subsystem in that the commands +are ordinary EMACS commands (though a handful may have been changed +slightly), whereas a subsystem defines its own command language. + +The text you edit inside a recursive editing level depends on the +command which invoked the recursive editing level. It could be a list +of options and values, or a list of tab stop settings, syntax table +settings, a message to be sent, or any text that you might wish to +compose. + +Sometimes in a recursive editing level you edit text of the file you are +visiting, just as at top level. Why would this be? Usually because a +few commands are temporarily changed. For example, Edit Picture in the +PICTURE library defines commands good for editing a picture made out of +characters, then enters a recursive editing level. When you exit, the +special picture-editing commands go away. Until then, the brackets in +the mode line serve to remind you that, although the text you are +editing is your file, all is not normal. *Note PICTURE: PICTURE. + +In any case, if the mode line says "[...]" you are inside a recursive +editing level, and the way to exit (send the message, redefine the +options, get rid of the picture-editing commands, etc.) is with the +command C-M-C (^R Exit). *Note Exiting: Exiting. If you change your +mind about the command (you don't want to send the message, or change +your options, etc.) then you should use the command C-] (Abort Recursive +Edit) to get out. *Note C-]: Quitting. + +Inside recursive editing levels, the help option Help R is defined to +print the full documentation of the command which invoked the recursive +editing level. The other normal Help options are still available for +asking about commands you want to use while inside the recursive edit. + +When the text in the mode line is surrounded by parentheses, it means +that you are inside a "Minibuffer". A minibuffer is a special case of +the recursive editing level. Like any other, it can be aborted safely +with C-]. *Note Minibuffer: Minibuffer. + + +EMACS Node: Exiting, Previous: Recursive, Up: Top, Next: Help + +Exiting Levels; Exiting EMACS + + C-X C-C Exit from EMACS to the superior job. + C-M-C Exit from EMACS or from a recursive editing level. + +The general EMACS command to exit is C-M-C (^R Exit). This command is +used to exit from a recursive editing level back to the top level of +EMACS, and to exit from EMACS at top level back to HACTRN. If your +keyboard does not have a Meta key, you must type this command by means +of a bit prefix character, as C-C C-C or as Altmode C-C. Note carefully +the difference between exiting a recursive editing level and aborting +it: exiting allows the command which invoked the recursive editing level +to finish its job with the text as you have edited it, whereas aborting +cancels whatever the command was going to do. *Note Aborting: Quitting. + +We cannot say in general how to exit a subsystem, since each subsystem +defines its own command language, but the convention is to use the +character "Q". + +You can exit from EMACS back to the superior job, usually HACTRN, at any +time, even within a recursive editing level, with the command C-X C-C +(^R Return to Superior). If this is used while you are inside a +recursive editing level, then when EMACS is re-entered you will still be +inside the recursive editing level. + +Exiting EMACS does not normally save the visited file, because it is not +the case that users exit EMACS only when they are "finished editing". +If you want the file saved, you must use C-X C-S. Exiting does cause an +auto save if Auto Save mode is in use. + +Exiting from EMACS runs the function & Exit EMACS, which executes the +value of the variable Exit Hook, if it is defined. If EMACS is +continued, the value of Return from Superior Hook is executed. + + +EMACS Node: Help, Previous: Exiting, Up: Top, Next: Mark + +Self-Documentation Commands + +EMACS provides extensive self-documentation features which revolve +around a single character, called the Help character. At any time while +using EMACS, you can type the Help character to ask for help. How to +type the Help character depends on the terminal you are using, but aside +from that the same character always does the trick. If your keyboard +has a key labeled Help (above the H), type that key (together with the +Top key). Otherwise the way you type the Help character is actually C-_ +(Control-Underscore) followed by an H (this is two characters to type, +but let's not worry about that). Whatever it is you have to type, to +EMACS it is just the Help character. On some terminals just figuring +out how to type a Control-Underscore is hard! Typing Underscore and +adding the Control key is what logically ought to work, but on some +terminals it does not. Sometimes Control-Shift-O works. On VT-100 +terminals, typing Control-/ or Control-? sends a Control-_ character. + +If you type Help while you are using a subsystem such as INFO, it prints +a list of the commands of that subsystem. + +If you type Help in the middle of a multi-character command, it often +tells you about what sort of thing you should type next. For example, +if you type M-X and then Help, it tells you about M-X and how to type +the name of the command. If you finish the function name and the +Altmode and then type Help, it tells you about the function you have +specified so you can know what arguments it needs. If you type C-X and +then type Help, it tells you about the C-X commands. + +But normally, when it's time for you to start typing a new command, Help +offers you several options for asking about what commands there are and +what they do. It prompts with "Doc (? for help):" at the bottom of the +screen, and you should type a character to say what kind of help you +want. You could type Help or "?" at this point to find out what options +are available. The ones you are most likely to need are described here. + +The most basic Help options are Help C and Help D. You can use them to +ask what a particular command does. Help C is for character commands; +type the command you want to know about after the Help and the "C" ("C" +stands for Character). Thus, Help C M-F or Help C Altmode F tells you +about the M-F command. Help D is for asking about functions (extended +commands); type the name of the function and a Return. Thus, Help D +Lisp Mode tells you about M-X Lisp Mode. Help D can also tell you +the documentation of a variable, if you give it a variable's name +instead of a function's name. "D" stands for "Describe", since Help D +actually uses the function Describe to do the work. + +A more complicated sort of question to ask is, "what are the commands +for working with files?" For this, you can type Help A, followed by the +string "file" and a Return. It prints a list of all the functions that +have "file" anywhere in their names, including Save All Files, ^R Save +File, Append to File, etc. If some of the functions are connected to +commands, it tells you that too. For example, it would say that you can +invoke ^R Save File by typing C-X C-S. "A" stands for "Apropos", since +Help A actually uses the function Apropos to do the substring matching. +Help A does not list internal functions, only those the nonprogrammer is +likely to use. If you want subroutines to be listed as well, you must +call Apropos yourself. + +Because Apropos looks only for functions whose names contain the string +which you specify, you must use ingenuity in choosing substrings. If +you are looking for commands for killing backwards and Help A Kill +Backwards doesn't reveal any, don't give up. Try just Kill, or just +Backwards, or just Back. Be persistent. Pretend you are playing +Adventure. + +Here is a set of Apropos strings that covers many classes of EMACS +commands, since there are strong conventions for naming the standard +EMACS commands. By giving you a feel for the naming conventions, this +set should also serve to aid you in developing a technique for picking +Apropos strings. + + character, line, word, sentence, paragraph, region, page, + buffer, screen, window, bounds, file, dir, beginning, end, case, + mode, forward, backward, next, previous, up, down, search, kill, + delete, mark, fill, indent, change. + +There is also a convention for how command names start for certain +common kinds of operations: many commands start with one of the words +"Edit", "View", "Insert", "List", or "What". + +If you are inside a recursive editing level, Help R prints out the +complete documentation of that recursive editing level. *Note +Recursive: Recursive. Help ? also tells you briefly what sort of +recursive editing level you are in, in addition to describing the +available Help options. If you are not inside a recursive editing +level, Help R says that you are at top level. + +If something surprising happens, and you are not sure what commands you +typed, use Help L. Help L prints the last 60 command characters you +typed in. This is also helpful if you suffer from line noise. If you +see commands that you don't know, you can use Help C to find out what +they do. + +If a command doesn't do what you thought you knew it should do, you can +ask to see whether it has changed recently. Help N prints out the file +called EMACS;EMACS NEWS which is an archive of announcements of changes +to EMACS. + +To find out about the other Help options, type Help Help. That is, when +the first Help asks for an option, type Help to ask what is available. + +Finally, you should know about the documentation files for EMACS, which +are EMACS;EMACS GUIDE and EMACS;EMACS CHART. EMACS GUIDE is a version +of the manual formatted to be printed out on a terminal or line printer. +EMACS CHART has a brief description of all the commands, known as the +wall chart, because it is good to post on the wall near your terminal. + + +EMACS Node: Mark, Previous: Help, Up: Top, Next: Killing + +The Mark and the Region + +In general, a command which processes an arbitrary part of the buffer +must know where to start and where to stop. In EMACS, such commands +usually operate on the text between point and "the mark". This range of +text is called "the region". To specify a region, you set point to one +end of it and mark at the other. It doesn't matter which one is set +first chronologically, or which one comes earlier in the text. Here are +some commands for setting the mark: + + C-@ Set the mark where point is. + C-Space The same. + C-X C-X Interchange mark and point. + M-@ Set mark after end of next word. This command and + the following three do not move point. + C-M-@ Set mark after end of next Lisp s-expression. + C-< Set mark at beginning of buffer. + C-> Set mark at end of buffer. + M-H Put region around current paragraph. + C-M-H Put region around current Lisp defun. + C-X H Put region around entire buffer. + C-X C-P Put region around current page. + +For example, if you wish to convert part of the buffer to all +upper-case, you can use the C-X C-U command, which operates on the text +in the region. You can first go to the beginning of the text to be +capitalized, put the mark there, move to the end, and then type C-X C-U. +Or, you can set the mark at the end of the text, move to the beginning, +and then type C-X C-U. C-X C-U runs the function ^R Uppercase Region, +whose name signifies that the region, or everything between point and +the mark, is to be capitalized. + +The most common way to set the mark is with the C-@ command or the +C-Space command (^R Set/Pop Mark). They set the mark where point is. +Then you can move point away, leaving the mark behind. + +It isn't actually possible to type C-Space on non-Meta keyboards. Yet +on many terminals the command appears to work anyway! This is because +trying to type a Control-Space on those terminals actually sends the +character C-@, which means the same thing as C-Space. A few keyboards +just send a Space. If you have one of them, you type C-@, or customize +your EMACS. + +Since terminals have only one cursor, there is no way for EMACS to show +you where the mark is located. You have to remember. The usual +solution to this problem is to set the mark and then use it soon, before +you forget where it is. But you can see where the mark is with the +command C-X C-X (^R Exchange Point and Mark) which puts the mark where +point was and point where the mark was. The extent of the region is +unchanged, but the cursor and point are now at the previous location of +the mark. + +C-X C-X is also useful when you are satisfied with the location of point +but want to move the mark; do C-X C-X to put point there and then you +can move it. A second use of C-X C-X, if necessary, puts the mark at +the new location with point back at its original location. + +If you insert or delete before the mark, the mark may drift through the +text. If the buffer contains "FOO BAR" and the mark is before the "B", +then if you delete the "F" the mark will be before the "A". This is an +unfortunate result of the simple way the mark is implemented. It is +best not to delete or insert at places above the mark until you are +finished using it and don't care where it drifts to. + +Commands to Mark Textual Objects + +There are commands for placing the mark on the other side of a certain +object such as a word or a list, without having to move there first. +M-@ (^R Mark Word) puts the mark at the end of the next word, while +C-M-@ (^R Mark Sexp) puts it at the end of the next s-expression. C-> +(^R Mark End) puts the mark at the end of the buffer, while C-< (^R Mark +Beginning) puts it at the beginning. These characters allow you to save +a little typing or redisplay, sometimes. + +Other commands set both point and mark, to delimit an object in the +buffer. M-H (^R Mark Paragraph) puts point at the beginning of the +paragraph it was inside of (or before), and puts the mark at the end. +M-H does all that's necessary if you wish to indent, case-convert, or +kill a whole paragraph. C-M-H (^R Mark Defun) similarly puts point +before and the mark after the current or next defun. C-X C-P (^R Mark +Page) puts point before the current page (or the next or previous, +according to the argument), and mark at the end. The mark goes after +the terminating page delimiter (to include it), while point goes after +the preceding page delimiter (to exclude it). Finally, C-X H (^R Mark +Whole Buffer) makes the region the entire buffer by putting point at the +beginning and the mark at the end. + +The Ring of Marks + +Aside from delimiting the region, the mark is also useful for +remembering a spot that you may want to go back to. To make this +feature more useful, EMACS remembers 16 previous locations of the mark. +Most commands that set the mark push the old mark onto this stack. To +return to a marked location, use C-U C-@ (or C-U C-Space). This moves +point to where the mark was, and restores the mark from the stack of +former marks. So repeated use of this command moves point to all of the +old marks on the stack, one by one. Since the stack is actually a ring, +enough uses of C-U C-@ bring point back to where it was originally. +Insertion and deletion can cause the saved marks to drift, but they will +still be good for this purpose because they are unlikely to drift very +far. + +Some commands whose primary purpose is to move point a great distance +take advantage of the stack of marks to give you a way to undo the +command. The best example is M-<, which moves to the beginning of the +buffer. It sets the mark first, so that you can use C-U C-@ or C-X C-X +to go back to where you were. Searches sometimes set the mark; it +depends on how far they move. Because of this uncertainty, searches +type out "^@" if they set the mark. The normal situation is that +searches leave the mark behind if they move at least 500 characters, but +you can change that value since it is kept in the variable Auto Push +Point Option. By setting it to 0, you can make all searches set the +mark. By setting it to a very large number such as ten million, you can +prevent all searches from setting the mark. The string to be typed out +when this option does its thing is kept in the variable Auto Push Point +Notification. + + +EMACS Node: Killing, Previous: Mark, Up: Top, Next: Un-killing + +Deletion and Killing + +Most commands which erase text from the buffer save it so that you can +get it back if you change your mind, or move or copy it to other parts +of the buffer. These commands are known as "kill" commands. The rest +of the commands that erase text do not save it; they are known as +"delete" commands. The delete commands include C-D and Rubout, which +delete only one character at a time, and those commands that delete only +spaces or line separators. Commands that can destroy significant +amounts of nontrivial data generally kill. The commands' names and +individual descriptions use the words "kill" and "delete" to say which +they do. If you do a kill command by mistake, you can use the Undo +command to undo it (*Note Undo: Undo.). + + C-D Delete next character. + Rubout Delete previous character. + M-\ Delete spaces and tabs around point. + C-X C-O Delete blank lines around the current line. + M-^ Join two lines by deleting the CRLF and any + indentation. + C-K Kill rest of line or one or more lines. + C-W Kill region (from point to the mark). + M-D Kill word. + M-Rubout Kill word backwards. + C-X Rubout Kill back to beginning of sentence. + M-K Kill to end of sentence. + C-M-K Kill s-expression. + C-M-Rubout Kill s-expression backwards. + +Deletion + +The most basic delete commands are C-D and Rubout. C-D deletes the +character after the cursor, the one the cursor is "on top of" or +"underneath". The cursor doesn't move. Rubout deletes the character +before the cursor, and moves the cursor back. Line separators act like +single characters when deleted. Actually, C-D and Rubout aren't always +delete commands; if you give an argument, they kill instead. This +prevents you from losing a great deal of text by typing a large argument +to a C-D or Rubout. + +The other delete commands are those which delete only formatting +characters: spaces, tabs and line separators. M-\ (^R Delete Horizontal +Space) deletes all the spaces and tab characters before and after point. +C-X C-O (^R Delete Blank Lines) deletes all blank lines after the +current line, and if the current line is blank deletes all blank lines +preceding the current line as well (leaving one blank line, the current +line). M-^ (^R Delete Indentation) joins the current line and the +previous line, or the current line and the next line if given an +argument. *Note M-^: TextIndent. + +A function ^R Delete Region used to exist, but it was too dangerous. +When you want to delete a large amount of text without saving a copy of +it (perhaps because it is very big), you can set point and mark around +the text and then type + + M-Altmode + MRK + +(This is a use of the minibuffer. *Note Minibuffer: Minibuffer.). + +Killing by Lines + +The simplest kill command is the C-K command (^R Kill Line). If given +at the beginning of a line, it kills all the text on the line, leaving +it blank. If given on a blank line, the blank line disappears. As a +consequence, if you go to the front of a non-blank line and type two +C-K's, the line disappears completely. + +More generally, C-K kills from point up to the end of the line, unless +it is at the end of a line. In that case it kills the line separator +following the line, thus merging the next line into the current one. +Invisible spaces and tabs at the end of the line are ignored when +deciding which case applies, so if point appears to be at the end of the +line, you can be sure the line separator will be killed. + +If C-K is given a positive argument, it kills that many lines, and the +separators that follow them (however, text on the current line before +point is spared). With a negative argument, it kills back to a number +of line beginnings. An argument of -2 means kill back to the second +line beginning. If point is at the beginning of a line, that line +beginning doesn't count, so C-U - 2 C-K with point at the front of a +line kills the two previous lines. + +C-K with an argument of zero kills all the text before point on the +current line. + +Other Kill Commands + +A kill command which is very general is C-W (^R Kill Region), which +kills everything between point and the mark. With this command, you can +kill any contiguous characters, if you first set the mark at one end of +them and go to the other end. + +Other syntactic units can be killed: words, with M-Rubout and M-D (*Note +Words: Words.); s-expressions, with C-M-Rubout and C-M-K (*Note +S-expressions: Lists.); sentences, with C-X Rubout and M-K (*Note +Sentences: Sentences.). + + +EMACS Node: Un-Killing, Previous: Killing, Up: Top, Next: Copying + +Un-Killing + +Un-killing is getting back text which was killed. The usual way to move +or copy text is to kill it and then un-kill it one or more times. + + C-Y Yank (re-insert) last killed text. + M-Y Replace re-inserted killed text with the previously + killed text. + M-W Save region as last killed text without killing. + C-M-W Append next kill to last batch of killed text. + +Killed text is pushed onto a "ring buffer" called the "kill ring" that +remembers the last 8 blocks of text that were killed. (Why it is called +a ring buffer will be explained below). The command C-Y (^R Un-kill) +reinserts the text of the most recent kill. It leaves the cursor at the +end of the text, and puts the mark at the beginning. Thus, a single C-W +undoes the C-Y (M-X Undo also does so). C-U C-Y leaves the cursor in +front of the text, and the mark after. This is only if the argument is +specified with just a C-U, precisely. Any other sort of argument, +including C-U and digits, has an effect described below. + +If you wish to copy a block of text, you might want to use M-W (^R Copy +Region), which copies the region into the kill ring without removing it +from the buffer. This is approximately equivalent to C-W followed by +C-Y, except that M-W does not mark the buffer as "changed" and does not +temporarily change the screen. + +There is only one kill ring, and switching buffers or files has no +effect on it. After visiting a new file, whatever was last killed in +the previous file is still on top of the kill ring. This is important +for moving text between files. + +Appending Kills + +Normally, each kill command pushes a new block onto the kill ring. +However, two or more kill commands in a row combine their text into a +single entry on the ring, so that a single C-Y command gets it all back +as it was before it was killed. This means that you don't have to kill +all the text in one command; you can keep killing line after line, or +word after word, until you have killed it all, and you can still get it +all back at once. (Thus we join television in leading people to kill +thoughtlessly). + +Commands that kill forward from point add onto the end of the previous +killed text. Commands that kill backward from point add onto the +beginning. This way, any sequence of mixed forward and backward kill +commands puts all the killed text into one entry without rearrangement. + +If a kill command is separated from the last kill command by other +commands, it starts a new entry on the kill ring, unless you tell it not +to by saying C-M-W (^R Append Next Kill) in front of it. The C-M-W +tells the following command, if it is a kill command, to append the text +it kills to the last killed text, instead of starting a new entry. With +C-M-W, you can kill several separated pieces of text and accumulate them +to be yanked back in one place. + +Un-killing Earlier Kills + +To recover killed text that is no longer the most recent kill, you need +the Meta-Y (^R Un-kill Pop) command. The M-Y command should be used +only after a C-Y command or another M-Y. It takes the un-killed text +inserted by the C-Y and replaces it with the text from an earlier kill. +So, to recover the text of the next-to-the-last kill, you first use C-Y +to recover the last kill, and then use M-Y to move back to the previous +kill. + +You can think of all the last few kills as living in a ring. After a +C-Y command, the text at the front of the ring is also present in the +buffer. M-Y "rotates" the ring, bringing the previous string of text to +the front, and this text replaces the other text in the buffer as well. +Enough M-Y commands can rotate any part of the ring to the front, so you +can get at any killed text as long as it is recent enough to be still in +the ring. Eventually the ring rotates all the way around and the most +recent killed text comes to the front (and into the buffer) again. M-Y +with a negative argument rotates the ring backwards. If the region +doesn't match the text at the front of the ring, M-Y is not allowed. + +In any case, when the text you are looking for is brought into the +buffer, you can stop doing M-Y's and it will stay there. It's really +just a copy of what's at the front of the ring, so editing it does not +change what's in the ring. And the ring, once rotated, stays rotated, +so that doing another C-Y gets another copy of what you rotated to the +front with M-Y. + +If you change your mind about un-killing, a C-W or M-X Undo gets rid of +the un-killed text at any point, after any number of M-Y's. C-W pushes +the text onto the ring again. M-X Undo does not. + +If you know how many M-Y's it would take to find the text you want, then +there is an alternative. C-Y with an argument greater than one restores +the text the specified number of entries down on the ring. Thus, +C-U 2 C-Y gets the next to the last block of killed text. It differs +from C-Y M-Y in that C-U 2 C-Y does not permanently rotate the ring. + +A way of viewing the contents of the kill ring is + + M-X View Q-register..K + +You must add one to the indices listed by this command, to get the +argument to use with C-Y to yank any particular string. + + +EMACS Node: Copying, Previous: Un-killing, Up: Top, Next: Search + +Other Ways of Copying Text + +Usually we copy or move text by killing it and un-killing it, but there +are other ways that are useful for copying one block of text in many +places, or for copying many scattered blocks of text into one place. + +Accumulating Text + +You can accumulate blocks of text from scattered locations either into a +buffer or into a file if you like. + +To append them into a buffer, use the command C-X A +(^R Append to Buffer), which inserts a copy of the region into the +specified buffer at the location of point in that buffer. If there is +no buffer with the name you specify, one is created. If you append text +into a buffer which has been used for editing, the copied text goes into +the middle of the text of the buffer, wherever point happens to be in +it. + +Point in that buffer is left at the end of the copied text, so +successive uses of C-X A accumulate the text in the specified buffer in +the same order as they were copied. If C-X A is given an argument, +point in the other buffer is left before the copied text, so successive +uses of C-X A add text in reverse order. + +You can retrieve the accumulated text from that buffer with M-X Insert +Buffer. This inserts a copy of the text in that buffer +into the selected buffer. You can also select the other buffer for +editing. *Note Buffers: Buffers, for background information on buffers. + +Strictly speaking, C-X A does not always append to the text already in +the buffer. But if it is used on a buffer which starts out empty, it +does keep appending to the end. + +Instead of accumulating text within EMACS, in a buffer, you can append +text directly into a disk file with the command M-X Append to +File. It adds the text of the region to the end of the +specified file. M-X Prepend to File adds the text to the beginning of +the file instead. The file is changed immediately on disk. These +commands are normally used with files that are not being visited in +EMACS. They have the advantage of working even on files too large to +fit into the EMACS address space. + +Copying Text Many Times + +When you want to insert a copy of the same piece of text frequently, the +kill ring becomes impractical, since the text moves down on the ring as +you edit, and will be in an unpredictable place on the ring when you +need it again. For this case, you can use the commands C-X X (^R Put +Q-register) and C-X G (^R Get Q-register) to move the text. + +C-X X stores a copy of the text of the region in a place called +q-register . With an argument, C-X X deletes the text as well. +can be a letter or a digit. This gives 36 places in which you can store +a piece of text. C-X G inserts in the buffer the text from +q-register . Normally it leaves point before the text and places the +mark after, but with a numeric argument it puts point after the text and +the mark before. + +The q-registers are important temporary variables in TECO programming, +but you don't have to understand them, only to know that what you save +with C-X X A is what you will get with C-X G A. + +Do not use q-registers M and R in this way, if you are going to use the +TECO commands MM and MR. + + +EMACS Node: Search, Previous: Copying, Up: Top, Next: Text + +Searching + +Like other editors, EMACS has commands for searching for an occurrence +of a string. The search command is unusual in that it is "incremental"; +it begins to search before you have finished typing the search string. +As you type in the search string, EMACS shows you where it would be +found. When you have typed enough characters to identify the place you +want, you can stop. Depending on what you will do next, you may or may +not need to terminate the search explicitly with an Altmode first. + + C-S Search forward. + C-R Search backward. + C-S  C-W Word search, ignoring whitespace. + +The command to search is C-S (^R Incremental Search). C-S reads in +characters and positions the cursor at the first occurrence of the +characters that you have typed. If you type C-S and then F, the cursor +moves right after the first "F". Type an "O", and see the cursor move +to after the first "FO". After another "O", the cursor is after the +first "FOO" after the place where you started the search. At the same +time, the "FOO" has echoed at the bottom of the screen. + +If you type a mistaken character, you can rub it out. After the FOO, +typing a rubout makes the "O" disappear from the bottom of the screen, +leaving only "FO". The cursor moves back to the "FO". Rubbing out the +"O" and "F" moves the cursor back to where you started the search. + +When you are satisfied with the place you have reached, you can type an +Altmode, which stops searching, leaving the cursor where the search +brought it. Also, any command not specially meaningful in searches +stops the searching and is then executed. Thus, typing C-A would exit +the search and then move to the beginning of the line. Altmode is +necessary only if the next command you want to type is a printing +character, Rubout, Altmode, C-Q, or another search command, since those +are the characters that have special meanings inside the search. + +Sometimes you search for "FOO" and find it, but not the one you expected +to find. There was a second FOO that you forgot about, before the one +you were looking for. Then type another C-S and the cursor will find +the next FOO. This can be done any number of times. If you overshoot, +you can rub out the C-S's. + +After you exit a search, you can search for the same string again by +typing just C-S C-S: one C-S command to start the search and then +another C-S to mean "search again". + +If your string is not found at all, the echo area says "Failing +I-Search". The cursor is after the place where EMACS found as much of +your string as it could. Thus, if you search for FOOT, and there is no +FOOT, you might see the cursor after the FOO in FOOL. At this point +there are several things you can do. If your string was mistyped, you +can rub some of it out and correct it. If you like the place you have +found, you can type Altmode or some other EMACS command to "accept what +the search offered". Or you can type C-G, which throws away the +characters that could not be found (the "T" in "FOOT"), leaving those +that were found (the "FOO" in "FOOT"). A second C-G at that point +undoes the search entirely. + +The C-G "quit" command does special things during searches; just what, +depends on the status of the search. If the search has found what you +specified and is waiting for input, C-G cancels the entire search. The +cursor moves back to where you started the search. If C-G is typed +while the search is actually searching for something or updating the +display, or after search failed to find some of your input (having +searched all the way to the end of the file), then only the characters +which have not been found are discarded. Having discarded them, the +search is now successful and waiting for more input, so a second C-G +will cancel the entire search. Make sure you wait for the first C-G to +ding the bell before typing the second one; if typed too soon, the +second C-G may be confused with the first and effectively lost. + +You can also type C-R at any time to start searching backwards. If a +search fails because the place you started was too late in the file, you +should do this. Repeated C-R's keep looking for more occurrences +backwards. A C-S starts going forwards again. C-R's can be rubbed out +just like anything else. If you know that you want to search backwards, +you can use C-R instead of C-S to start the search, because C-R is also +a command (^R Reverse Incremental Search) to search backward. Note to +all customizers: all this command does is call the current definition of +^R Incremental Search with a negative argument. + +All sorts of searches in EMACS normally ignore the case of the text they +are searching through; if you specify searching for FOO, then Foo and +foo are also considered a match. If you do not want this feature, set +the variable Case Search to zero. *Note Variables: Variables. + +A non-incremental search is also available. Type Altmode right after +the C-S to get it. Do + + M-X Describe^R String Search + +for details. Some people who prefer non-incremental searches put that +function on Meta-S, and ^R Character Search (do M-X Describe for +details) on C-S. It can do one useful thing which incremental search +cannot: search for words regardless of where the line breaks. + +Word search searches for a sequence of words without regard to how the +words are separated. More precisely, you type a string of many words, +using single spaces to separate them, and the string can be found even +if there are multiple spaces or line separators between the words. +Other punctuation such as commas or periods must match exactly. This is +useful in conjunction with documents formatted by text justifiers. If +you edit while looking at the printed, formatted version, you can't tell +where the line breaks are in the source file. With word search, you can +search without having to know. + +Word search is a special case of non-incremental search and is invoked +with C-S Altmode C-W. This is followed by the search string, which must +always be terminated with an Altmode. Searching does not start until +the final Altmode is typed. + +You do not even have to type each word in full, in a word search. An +abbreviation is good enough. Word search finds the first occurrence of +a sequence of words whose beginnings match the words of the argument. + + +EMACS Node: Text, Previous: Search, Up: Top, Next: Fixit + +Commands for English Text + +Editing files of text in a human language ought to be done using Text +mode rather than Fundamental mode. Invoke M-X Text Mode to enter Text +mode. *Note Major Modes: MajorModes. M-X Text Mode causes Tab to run +the function ^R Tab to Tab Stop, which allows you to set any tab stops +with M-X Edit Tab Stops (*Note Tab Stops: Textindent.). Features +concerned with comments in programs are turned off except when +explicitly invoked. Automatic display of parenthesis matching is turned +off, which is what most people want. Finally, the syntax table is +changed so that periods are not considered part of a word, while +apostrophes, backspaces and underlines are. + +If you are editing input for the text justifier TEX, you might want to +use TEX mode instead of Text mode. *Note TEX mode: (ETEX). For editing +SCRIBE input, use SCRIBE mode. *Note SCRIBE: SCRIBE. Someday there may +be special major modes for other text justifiers. + + +* Menu: + +* Words:: moving over and killing words +* Sentences:: moving over sentences and paragraphs +* TextIndent:: manipulation of indentation +* Filling:: filling or justifying text +* Case:: changing the case of text +* Fonts:: changing the font of text (for text justifiers) +* Underlining:: underlining (for text justifiers) +* SCRIBE:: editing SCRIBE files +* Dissociation:: Dissociated Press + + + +EMACS Node: Words, Previous: Text, Up: Text, Next: Sentences + +Word Commands + +EMACS has commands for moving over or operating on words. By +convention, they are all Meta- characters. + + M-F Move Forward over a word. + M-B Move Backward over a word. + M-D Kill up to the end of a word. + M-Rubout Kill back to the beginning of a word. + M-@ Mark the end of the next word. + M-T Transpose two words; drag a word forward or backward + across other words. + +Notice how these commands form a group that parallels the character +based commands C-F, C-B, C-D, C-T and Rubout. M-@ is related to C-@. + +The commands Meta-F (^R Forward Word) and Meta-B (^R Backward Word) move +forward and backward over words. They are thus analogous to Control-F +and Control-B, which move over single characters. Like their +Control- analogues, Meta-F and Meta-B move several words if given an +argument. Meta-F with a negative argument moves backward like Meta-B, +and Meta-B with a negative argument moves forward. Forward motion stops +right after the last letter of the word, while backward motion stops +right before the first letter. + +It is easy to kill a word at a time. Meta-D (^R Forward Kill Word) +kills the word after point. To be precise, it kills everything from +point to the place Meta-F would move to. Thus, if point is in the +middle of a word, only the part after point is killed. If some +punctuation comes after point and before the next word, it is killed +along with the word. If you wish to kill only the next word but not the +punctuation, simply do Meta-F to get the end, and kill the word +backwards with Meta-Rubout. Meta-D takes arguments just like Meta-F. + +Meta-Rubout (^R Backward Kill Word) kills the word before point. It +kills everything from point back to where Meta-B would move to. If +point is after the space in "FOO, BAR", then "FOO, " is killed. If you +wish to kill just "FOO", then do a Meta-B and a Meta-D instead of a +Meta-Rubout. + +Meta-T (^R Transpose Words) moves the cursor forward over a word, +dragging the word preceding or containing the cursor forward as well. A +numeric argument serves as a repeat count. Meta-T with a negative +argument undoes the effect of Meta-T with a positive argument; it drags +the word behind the cursor backward over a word. An argument of zero, +instead of doing nothing, transposes the word at point (surrounding or +adjacent to it) with the word at mark. In any case, the delimiter +characters between the words do not move. For example, "FOO, BAR" +transposes into "BAR, FOO" rather than "BAR FOO,". + +To operate on the next n words with an operation which applies between +point and mark, you can either set the mark at point and then move over +the words, or you can use the command Meta-@ (^R Mark Word) which does +not move point, but sets the mark where Meta-F would move to. It can be +given arguments just like Meta-F. + +Note that if you are in Atom Word mode and in Lisp mode, all the word +commands regard an entire Lisp atom as a single word. *Note +Minor Modes: MinorModes. + +The word commands' understanding of syntax is completely controlled by +the syntax table. Any character can, for example, be declared to be a +word delimiter. *Note Syntax: Syntax. + + +EMACS Node: Sentences, Previous: Words, Up: Text, Next: TextIndent + +Sentence and Paragraph Commands + +The EMACS commands for manipulating sentences and paragraphs are mostly +Meta- commands, so as to resemble the word-handling commands. + + M-A Move back to the beginning of the sentence. + M-E Move forward to the end of the sentence. + M-K Kill forward to the end of the sentence. + M-[ Move back to previous paragraph beginning. + M-] Move forward to next paragraph end. + M-H Put point and mark around this paragraph (around the + following one, if between paragraphs). + C-X Rubout + Kill back to the beginning of the sentence. + +Sentences + +The commands Meta-A and Meta-E (^R Backward Sentence and ^R Forward +Sentence) move to the beginning and end of the current sentence, +respectively. They were chosen to resemble Control-A and Control-E, +which move to the beginning and end of a line. Unlike them, Meta-A and +Meta-E if repeated or given numeric arguments move over successive +sentences. EMACS considers a sentence to end wherever there is a ".", +"?" or "!" followed by the end of a line or two spaces, with any number +of ")"'s, "]"'s, "'"'s, or '"' 's allowed in between. Neither M-A nor +M-E moves past the CRLF or spaces which delimit the sentence. + +Just as C-A and C-E have a kill command, C-K, to go with them, so M-A +and M-E have a corresponding kill command M-K (^R Kill Sentence) which +kills from point to the end of the sentence. With minus one as an +argument it kills back to the beginning of the sentence. Larger +arguments serve as a repeat count. + +There is a special command, C-X Rubout (^R Backward Kill Sentence) for +killing back to the beginning of a sentence, because this is useful when +you change your mind in the middle of composing text. + +Paragraphs + +Meta-[ (^R Backward Paragraph) moves to the beginning of the current or +previous paragraph, while Meta-] (^R Forward Paragraph) moves to the end +of the current or next paragraph. Blank lines and text justifier +command lines separate paragraphs and are not part of any paragraph. +Also, an indented line starts a new paragraph. + +In major modes for programs (as opposed to Text mode), paragraphs are +determined only by blank lines. This makes the paragraph commands +continue to be useful even though there are no paragraphs per se. + +When there is a fill prefix, then paragraphs are delimited by all lines +which don't start with the fill prefix. *Note Filling: Filling. + +When you wish to operate on a paragraph, you can use the command Meta-H +(^R Mark Paragraph) to set the region around it. This command puts +point at the beginning and mark at the end of the paragraph point was +in. Before setting the new mark at the end, a mark is set at the old +location of point; this allows you to undo a mistaken Meta-H with two +C-U C-@'s. If point is between paragraphs (in a run of blank lines, or +at a boundary), the paragraph following point is surrounded by point and +mark. Thus, for example, Meta-H C-W kills the paragraph around or after +point. + +One way to make an "invisible" paragraph boundary that does not show if +the file is printed is to put space-backspace at the front of a line. +The space makes the line appear (to the EMACS paragraph commands) to be +indented, which usually means that it starts a paragraph. + +The variable Paragraph Delimiter should be a TECO search string (*Note +TECO search strings: TECOsearch.) composed of various characters or +character sequences separated by 's. A line whose beginning matches +the search string is either the beginning of a paragraph or a text +justifier command line part of no paragraph. If the line begins with +period, singlequote, "-", "\" or "@", it can be a text justifier command +line; otherwise, it can be the beginning of a paragraph; but it cannot +be either one unless Paragraph Delimiter is set up to recognize it. +Thus, ". " as the Paragraph Delimiter string means that lines starting +with spaces start paragraphs, lines starting with periods are text +justifier commands, and all other nonblank lines are nothing special. + + +EMACS Node: TextIndent, Previous: Sentences, Up: Text, Next: Filling + +Indentation Commands for Text + + Tab Indents "appropriately" in a mode-dependent fashion. + M-Tab Inserts a tab character. + Linefeed Is the same as Return followed by Tab. + M-^ Undoes a Linefeed. Merges two lines. + M-M Moves to the line's first nonblank character. + M-I Indent to tab stop. In Text mode, Tab does this + also. + C-M-\ Indent several lines to same column. + C-X Tab Shift block of lines rigidly right or left. + +The way to request indentation is with the Tab command. Its precise +effect depends on the major mode. In Text mode, it indents to the next +tab stop. You can set the tab stops with Edit Tab Stops (see below). +If you just want to insert a tab character in the buffer, you can use +M-Tab or C-Q Tab. + +For English text, usually only the first line of a paragraph should be +indented. So, in Text mode, new lines created by Auto Fill mode are not +indented. Text mode tells Auto Fill mode not to indent new lines by +setting the variable Space Indent Flag to zero. + +But sometimes you want to have an indented paragraph. In such cases, +use M-X Edit Indented Text, which enters a submode in which Tab and Auto +Fill indent each line under the previous line, and only blank lines +delimit paragraphs. Alternatively, you can specify a fill prefix (see +below). + +To undo a line-break, whether done manually or by Auto Fill, use the +Meta-^ (^R Delete Indentation) command to delete the indentation at the +front of the current line, and the line boundary as well. They are +replaced by a single space, or by no space if before a ")" or after a +"(", or at the beginning of a line. To delete just the indentation of a +line, go to the beginning of the line and use Meta-\ (^R Delete +Horizontal Space), which deletes all spaces and tabs around the cursor. + +To insert an indented line before the current line, do C-A, C-O, and +then Tab. To make an indented line after the current line, use C-E +Linefeed. + +To move over the indentation on a line, do Meta-M or C-M-M (^R Back to +Indentation). These commands, given anywhere on a line, position the +cursor at the first nonblank character on the line. + +There are also commands for changing the indentation of several lines at +once. Control-Meta-\ (^R Indent Region) gives each line which begins in +the region the "usual" indentation by invoking Tab at the beginning of +the line. A numeric argument specifies the indentation, and each line +is shifted left or right so that it has exactly that much. C-X Tab +(^R Indent Rigidly) moves all of the lines in the region right by its +argument (left, for negative arguments). The whole group of lines move +rigidly sideways, which is how the command gets its name. + +Tab Stops + +For typing in tables, you can use Text mode's definition of Tab, ^R Tab +to Tab Stop, which may be given anywhere in a line, and indents from +there to the next tab stop. If you are not in Text mode, this function +can be found on M-I anyway. + +Set the tab stops using Edit Tab Stops, which allows you to edit some +text which defines the tab stops. Here is what it would look like for +ordinary tab stops every eight columns. + + : : : : : : + + 123456789 123456789 123456789 123456789 123456789 1234 + 0 10 20 30 40 50 + +The first line contains a colon or period at each tab stop. Colon +indicates an ordinary tab, which fills with whitespace; a period +specifies that characters be copied from the corresponding columns of +the second line below it. Thus, you can tab to a column automatically +inserting dashes or periods, etc. It is your responsibility to put in +the second line the text to be copied. In the example above there are +no periods, so the second line is not used, and is left blank. + +The third and fourth lines you see contain column numbers to help you +edit. They are only there while you are editing the tab stops; they are +not really part of the tab settings. The first two lines reside in the +variable Tab Stop Definitions when they are not being edited. If the +second line is not needed, Tab Stop Definitions can be just one line, +with no CRLFs. This makes it easier to set the variable in a local +modes list. *Note Locals: Locals. + +EMACS normally uses both tabs and spaces to indent lines, and displays +tab characters using eight-character tab stops. (How the ASCII +character tab is displayed has nothing to do with the definition of the +Tab character as a command). If you prefer, all indentation can be made +from spaces only. To request this, turn off Indent Tabs mode with the +command M-X Indent Tabs Mode. To display tabs with different tab stops, +set the TECO flag FS TAB WIDTH to the desired interval. This is useful +for displaying files brought from other operating systems whose normal +tab stop spacing is not 8. *Note FS Flags: FS Flags. + +To convert all tabs in a file to spaces, you can use M-X Untabify. M-X +Tabify performs the opposite transformation, replacing spaces with tabs +whenever possible, but only if there are at least three of them so as +not to obscure ends of sentences. A numeric argument to Tabify or +Untabify specifies the interval between tab stops to use for computing +how to change the file. By default, they use the same interval being +used for display. The visual appearance of the text should never be +changed by Tabify or Untabify without a numeric argument. + + +EMACS Node: Filling, Previous: TextIndent, Up: Text, Next: Case + +Text Filling + + Space in Auto Fill mode, breaks lines when appropriate. + M-Q Fill paragraph. + M-G Fill region (G is for Grind, by analogy with Lisp). + M-S Center a line. + C-X = Show current cursor position. + +Auto Fill mode lets you type in text that is "filled" (broken up into +lines that fit in a specified width) as you go. If you alter existing +text and thus cause it to cease to be properly filled, EMACS can fill it +again if you ask. + +Entering Auto Fill mode is done with M-X Auto Fill. From then on, lines +are broken automatically at spaces when they get longer than the desired +width. New lines created by Auto Fill are usually indented, but in Text +mode they are not. To leave Auto Fill mode, execute M-X Auto Fill +again. When Auto Fill mode is in effect, the word "Fill" appears in the +mode line. + +When you finish a paragraph, you can type Space with an argument of +zero. This doesn't insert any spaces, but it does move the last word of +the paragraph to a new line if it doesn't fit in the old line. Return +also moves the last word, but it may create another blank line. + +If you edit the middle of a paragraph, it may no longer be correctly +filled. To refill a paragraph, use the command Meta-Q (^R Fill +Paragraph). It causes the paragraph that point is inside, or the one +after point if point is between paragraphs, to be refilled. All the +line-breaks are removed, and then new ones are inserted where necessary. +M-Q can be undone with M-X Undo (*Note Undo: Undo.). + +If you are not happy with Meta-Q's idea of where paragraphs start and +end (the same as Meta-H's. *Note Paragraphs: Sentences.), you can use +Meta-G (^R Fill Region) which refills everything between point and mark. +Sometimes, it is ok to fill a region of several paragraphs at once. +Meta-G recognizes a blank line or an indented line as starting a +paragraph and does not fill it in with the preceding line. The sequence +space-backspace at the front of a line prevents it from being filled +into the preceding line but is invisible when the file is printed. +However, the full sophistication of the paragraph commands in +recognizing paragraph boundaries is not available. The purpose of M-G +is to allow you to override EMACS's usual criteria for paragraph +boundaries. M-G can be undone with M-X Undo. + +Giving an argument to M-G or M-Q causes the text to be "justified" as +well as filled. This means that extra spaces are inserted between the +words so as to make the right margin come out exactly even. I do not +recommend doing this. If someone else has uglified some text by +justifying it, you can unjustify it (remove the spaces) with M-G or M-Q +without an argument. + +The command Meta-S (^R Center Line) centers a line within the current +line width. With an argument, it centers several lines individually and +moves past them. + +The maximum line width for filling is in the variable Fill Column. Both +M-Q and Auto Fill make sure that no line exceeds this width. The +easiest way to set the variable is to use the command C-X F (^R Set Fill +Column), which places the margin at the column point is on, or at the +column specified by a numeric argument. The fill column is initially +column 70. + +To fill a paragraph in which each line starts with a special marker +(which might be a few spaces, giving an indented paragraph), use the +"fill prefix" feature. Move point to a spot right after the special +marker and give the command C-X Period (^R Set Fill Prefix). Then, +filling the paragraph will remove the marker from each line beforehand, +and put the marker back in on each line afterward. Auto Fill when there +is a fill prefix inserts the fill prefix at the front of each new line. +Also, any line which does not start with the fill prefix is considered +to start a paragraph. To turn off the fill prefix, do C-X Period with +point at the front of a line. The fill prefix is kept in the variable +Fill Prefix. + +The command C-X = (What Cursor Position) can be used to find out the +column that the cursor is in, and other miscellaneous information about +point which is quick to compute. It prints a line in the echo area that +looks like this: + + X=5 Y=7 CH=101 .=3874(35% of 11014) H=<3051,4640> + +In this line, the X value is the column the cursor is in (zero at the +left), the Y value is the screen line that the cursor is in (zero at the +top), the CH value is the octal value of the character after point (101 +is "A"), the "point" value is the number of characters in the buffer +before point, and the values in parentheses are the percentage of the +buffer before point and the total size of the buffer. + +The H values are the virtual buffer boundaries, indicate which part of +the buffer is still visible when narrowing has been done. If you have +not done narrowing, the H values are omitted. For more information +about the virtual buffer boundaries, *Note Narrowing: Narrowing. + + +EMACS Node: Case, Previous: Filling, Up: Text, Next: Fonts + +Case Conversion Commands + +EMACS has commands for converting either a single word or any arbitrary +range of text to upper case or to lower case. + + M-L Convert following word to lower case. + M-U Convert following word to upper case. + M-C Capitalize the following word. + C-X C-L Convert region to lower case. + C-X C-U Convert region to upper case. + +The word conversion commands are the most useful. Meta-L (^R Lowercase +Word) converts the word after point to lower case, moving past it. +Thus, successive Meta-L's convert successive words. Meta-U +(^R Uppercase Word) converts to all capitals instead, while Meta-C +(^R Uppercase Initial) puts the first letter of the word into upper case +and the rest into lower case. All these commands convert several words +at once if given an argument. They are especially convenient for +converting a large amount of text from all upper case to mixed case, +because you can move through the text using M-L, M-U or M-C on each word +as appropriate. + +When given a negative argument, the word case conversion commands apply +to the appropriate number of words before point, but do not move point. +This is convenient when you have just typed a word in the wrong case. +You can give the case conversion command and continue typing. + +If a word case conversion command is given in the middle of a word, it +applies only to the part of the word which follows the cursor, treating +it as a whole word. + +The other case conversion commands are C-X C-U (^R Uppercase Region) and +C-X C-L (^R Lowercase Region), which convert everything between point +and mark to the specified case. Point and mark do not move. These +commands ask for confirmation if the region contains more than Region +Query Size characters; they also save the original contents of the +region so you can undo them (*Note Undo: Undo.). + + +EMACS Node: Fonts, Previous: Case, Up: Text, Next: Underlining + +Font-Changing + +EMACS has commands to insert and move font change commands as understood +by the TJ6, R and BOLIO text justifiers. A font change is assumed to be +of the form  meaning select the specified font, or * meaning +select the previously selected font. + + M-# Change previous word's font, or next word's. + C-X # Change font of region. + +M-# (^R Change Font Word) is a command to change the font of a word. +Its action is rather complicated to describe, but that is because it +tries to be as versatile and convenient as possible in practice. + +If you type M-# with an argument, the previous word is put into the font +specified by the argument. Point is not changed. This means that, if +you want to insert a word and put it in a specific font, you can type +the word, then use M-# to change its font, and then go on inserting. +The font is changed by putting a  before the word and a * +after. + +If you type M-# with no argument, it takes the last font change (either +a  or *, whichever is later) and moves it one word forward. +What this implies is that you can change the font of several consecutive +words incrementally by moving after the first word, issuing M-# with an +argument to set that word's font, and then typing M-# to extend the font +change past more words. Each M-# advances past one more word. + +M-# with a negative argument is the opposite of M-# with no argument; it +moves the last font change BACK one word. If you type too many M-#'s, +you can undo them this way. If you move one font change past another, +one or both are eliminated, so as to do the right thing. As a result, +M-Minus M-# will undo a M-# with an argument. Try it! + +You can also change the font of a whole region by putting point and the +mark around it and issuing C-X # (^R Change Font Region), with the font +number as argument. C-X # with a negative argument removes all font +changes inside or adjacent to the region. + + +EMACS Node: Underlining, Previous: Fonts, Up: Text, Next: SCRIBE + +Underlining + +EMACS has two commands for manipulating text-justifier underlining +command characters. These commands do not produce any sort of +overprinting in the text file itself; they insert or move command +characters which direct text justifiers to produce underlining. By +default, commands for the text justifier R are used. + M-_ Underline previous word or next word. + C-X _ Underline region. + +M-_ is somewhat like M-# in that it either creates an underline around +the previous word or extends it past the next word. However, where a +font change requires that you specify a font number, an underline is +just an underline and has no parameter for you to specify. Also, it is +assumed that the text justifier's commands for starting and ending +underlines are distinguishable, whereas you can't tell from a font +change whether it is "starting" something or "ending" something. M-_ +differs slightly from M-# as a result. + +M-_ with no argument creates an underline around the previous word if +there is none. If there is an underline there, it is extended one word +forward. Thus, you can insert an underlined word by typing the word and +then a M-_. Or you can underline several existing words by moving past +the first of them, and typing one M-_ for each word. + +M-_ given in the vicinity of an underline-begin moves IT forward. Thus, +it should be thought of as applying to any boundary, where underlining +either starts or stops, and moving it forward. If a begin underlining +is moved past an end, or vice versa, they both disappear. + +Giving M-_ an argument merely tells it to apply to several words at once +instead of one. M-_ with a positive argument of n underlines the next n +words, either creating an underlined area or extending an existing one. +With a negative argument, that many previous words are underlined. +Thus, M-_ can do more things with underlines than M-# can do with font +changes, because of the facts that you don't need to use the argument to +say which font, and you can tell a beginning from an end. + +For larger scale operations, you can use C-X _ to place underlines from +point to mark, or C-X _ with a negative argument to remove all +underlining between point and mark. + +By default,  is used to begin an underline and  is used to end one. +The variables Underline Begin and Underline End may be created and set +to strings to use instead. For a single character you can use the +numeric ASCII code for it. + + +EMACS Node: SCRIBE, Previous: Underlining, Up: Text, Next: Dissociation + +SCRIBE Mode + +SCRIBE mode provides many special editing commands for manipulating the +commands for the text justifier SCRIBE. Instances of SCRIBE commands +are referred to in EMACS as "environments", though strictly speaking it +is the command name which is the environment, and not all commands +either. + C-M-N Move forward over SCRIBE environment. + C-M-P Move backward over SCRIBE environment. + C-M-U Move up to beginning of containing SCRIBE + environment. + C-M-D Move forward and down inside next SCRIBE + environment. + C-M-E Move up to end of containing SCRIBE environment. + C-M-H Put point and mark around containing SCRIBE + environment. + C-M-G Change name of containing SCRIBE environment. + C-M-Q Change form of containing SCRIBE environment. + +In SCRIBE mode the standard expression motion and killing commands +C-M-F, C-M-B, C-M-K and C-M-Rubout operate on units of balanced SCRIBE +delimiters. Additional commands specific to SCRIBE mode move around the +structure of SCRIBE environments. C-M-N (^R Forward Environment) moves +forward over an entire SCRIBE expression (@, environment name and +arguments), C-M-P (^R Backward Environment) moves back, C-M-U +(^R Backward Up Environment) moves up, and C-M-D (^R Down Environment) +moves down. C-M-E (^R End of Environment) moves up to the end of the +containing SCRIBE environment. C-M-H (^R Mark Environment) puts point +and mark around the containing SCRIBE environment. + +Speaking of balanced delimiters, SCRIBE mode does not work properly when +the characters ' and ` are used as delimiters for arguments. This is +because the parser expects each character to be either a parenthesis +(which matches a different character) or a string quote (which matches +itself), not both. *Note Syntax Table: Syntax. SCRIBE mode simply +does not treat these characters as possible delimiters, and it is best +not to use them. It is just as well, since if SCRIBE mode actually +tried to handle these delimiters it would be confused by apostrophes in +the text. + +Other commands transform SCRIBE environments. C-M-G (^R Change +Environment Name) changes the name of the SCRIBE environment that point +is inside. For example, if point is somewhere inside an @I[...] +environment, C-M-G could be used to change the @I to an @U. C-M-G reads +the new environment name from the terminal and replaces the old +environment name with it. + +C-M-Q (^R Change Form) changes the containing SCRIBE environment between +the brief form such as @Example[...] and the longer form +@Begin(Example)...@End(Example). If the environment has the brief form, +it is changed to the longer form, and vice versa. + +In SCRIBE mode, paragraphs are redefined to understand SCRIBE commands +in a way that is usually right. Any line that consists entirely of one +SCRIBE command is considered a paragraph-separating line, just like a +blank line. This does the right thing for @Begin and @End, and for many +other cases. So is any line that starts with an @; or @' command. The +@; and @' commands are supposed to be no-ops at the beginning of a line, +and can therefore be used to mark lines that you think should separate +paragraphs. Which one works, and when, depends on the version of +SCRIBE. Eventually, @; will always work. + +Aside from the above cases, SCRIBE commands are considered part of the +text, so an @I command which happens to end up at the front of a line +will not separate paragraphs. SCRIBE mode accomplishes this by +redefining M-[ and the function ^R Backward Paragraph to be the function +^R Backward SCRIBE Paragraph. Lines starting with page delimiters are +paragraph delimiters as usual, and lines starting with space or tab +start paragraphs as usual. + +The comment commands know that comments in SCRIBE files start with +"@Comment{" and end with "}". *Note Comments: Comments. + +You can use the M-X Compile command to invoke SCRIBE. *Note Compile: +Compile. It operates on the file currently visited. You can use a +string argument to specify switches. After SCRIBE is finished, you must +type P to resume EMACS. Then, if there were any errors, EMACS splits +the screen and displays the errors in the bottom window. The command +M-X Next Scribe Error moves to the point in the file at which the next +error occurred. Currently the only ITS machine on which SCRIBE is +installed is MC. + +The functions listed in this section live in the library SCRIBE, which +is loaded automatically if you enter SCRIBE mode. + + +EMACS Node: Dissociation, Previous: SCRIBE, Up: Text + +Dissociated Press + +M-X Dissociated Press is a command for scrambling a file of text either +word by word or character by character. Starting from a bufferfull of +straight English, it produces extremely amusing output. Dissociated +Press prints its output on the terminal. It does not change the +contents of the buffer. + +Dissociated Press operates by jumping at random from one point in the +buffer to another. In order to produce plausible output rather than +gibberish, it insists on a certain amount of overlap between the end of +one run of consecutive words or characters and the start of the next. +That is, if it has just printed out "president" and then decides to jump +to a different point in the file, it might spot the "ent" in "pentagon" +and continue from there, producing "presidentagon". Long sample texts +produce the best results. + +A negative argument to M-X Dissociated Press tells it to operate +character by character, and specifies the number of overlap characters. +A positive argument tells it to operate word by word and specifies the +number of overlap words. In this mode, whole words are treated as the +elements to be permuted, rather than characters. No argument is +equivalent to an argument of two. For your againformation, the output +is only printed on the terminal. The file you start with is not +changed. + +Dissociated Press produces nearly the same results as a Markov chain +based on a frequency table constructed from the sample text. It is, +however, an independent, ignoriginal invention. Dissociated Press +techniquitously copies several consecutive characters from the sample +between random choices, whereas a Markov chain would choose randomly +for each word or character. This makes for more plausible sounding +results. + +It is a mustatement that too much use of Dissociated Press can be a +developediment to your real work. Sometimes to the point of outragedy. +And keep dissociwords out of your documentation, if you want it to be +well userenced and properbose. Have fun. Your buggestions are welcome. + + +EMACS Node: Fixit, Previous: Text, Up: Top, Next: Files + +Commands for Fixing Typos + +In this section we describe the commands that are especially useful for +the times when you catch a mistake in your text just after you have made +it, or change your mind while composing text on line. + + Rubout Delete last character. + M-Rubout Kill last word. + C-X Rubout Kill to beginning of sentence. + C-T Transpose two characters. + C-X C-T Transpose two lines. + C-X T Transpose two arbitrary regions. + M-Minus M-L Convert last word to lower case. + M-Minus M-U Convert last word to all upper case. + M-Minus M-C Convert last word to lower case with capital + initial. + M-' Fix up omitted shift key on digit. + M-$ (Meta-Dollar Sign) Check and correct spelling of + word. + +Killing Your Mistakes + +The Rubout command is the most important correction command. When used +among printing (self-inserting) characters, it can be thought of as +canceling the last character typed. + +When your mistake is longer than a couple of characters, it might be +more convenient to use M-Rubout or C-X Rubout. M-Rubout kills back to +the start of the last word, and C-X Rubout kills back to the start of +the last sentence. C-X Rubout is particularly useful when you are +thinking of what to write as you type it, in case you change your mind +about phrasing. M-Rubout and C-X Rubout save the killed text for C-Y +and M-Y to retrieve (*Note Un-killing: Un-killing.). + +M-Rubout is often useful even when you have typed only a few characters +wrong, if you know you are confused in your typing and aren't sure +exactly what you typed. At such a time, you cannot correct with Rubout +except by looking at the screen to see what you did. It requires less +thought to kill the whole word and start over again, especially if the +system is heavily loaded. + +Transposition + +The common error of transposing two characters can be fixed, when they +are adjacent, with the C-T command. Normally, C-T transposes the two +characters on either side of the cursor. When given at the end of a +line, rather than transposing the last character of the line with the +line separator, which would be useless, C-T transposes the last two +characters on the line. So, if you catch your transposition error right +away, you can fix it with just a C-T. If you don't catch it so fast, +you must move the cursor back to between the two transposed characters. +If you transposed a space with the last character of the word before it, +the word motion commands are a good way of getting there. Otherwise, a +reverse search (C-R) is often the best way. *Note Search: Search. + +To transpose two lines, use the C-X C-T command (^R Transpose Lines). +M-T transposes words and C-M-T transposes s-expressions. + +A more general transpose command is C-X T (^R Transpose Regions). This +transposes two arbitrary blocks of text, which need not even be next to +each other. To use it, set the mark at one end of one block, then at +the other end of the block; then go to the other block and set the mark +at one end, and put point at the other. In other words, point and the +last three marks should be at the four locations which are the ends of +the two blocks. It does not matter which of the four locations point is +at, or which order the others were marked. C-X T transposes the two +blocks of text thus identified, and relocates point and the three marks +without changing their order. + +Case Conversion + +A very common error is to type words in the wrong case. Because of +this, the word case-conversion commands M-L, M-U and M-C have a special +feature when used with a negative argument: they do not move the cursor. +As soon as you see you have mistyped the last word, you can simply +case-convert it and go on typing. *Note Case: Case. + +Another common error is to type a special character and miss the shift +key, producing a digit instead. There is a special command for fixing +this: M-' (^R Upcase Digit), which fixes the last digit before point in +this way (but only if that digit appears on the current line or the +previous line. Otherwise, to minimize random effects of accidental use, +M-' does nothing). Once again, the cursor does not move, so you can use +M-' when you notice the error and immediately continue typing. Because +M-' needs to know the arrangement of your keyboard, the first time you +use it you must supply the information by typing the row of digits 1, 2, +... , 9, 0 but HOLDING DOWN THE SHIFT KEY. This tells M-' the +correspondence between digits and special characters, which is +remembered for the duration of the EMACS in the variable Digit Shift +Table. This command is called M-' because its main use is to replace +"7" with a single-quote. + +Checking and Correcting Spelling + +To check the spelling of the word before point, and optionally correct +it as well, use the command M-$ (^R Correct Word Spelling). This is a +Dollar sign, not an Altmode! This command sends the word to the +SPELL program for correction. + +If SPELL recognizes the word as a correctly spelled one (although not +necessarily the one you meant!) you will see "Found it" or "Found it +because of" followed by the word without its suffix. If the program +cannot at all recognize the word, it will print "Couldn't find it." + +If SPELL recognizes the word as a misspelling, it displays on the screen +the other words which are possibilities for the correct spelling, and +gives each one a number. Then, you can type one of the following +things: + + 0 to 9 Replace misspelled word with that spelling + (preserving case, just like Replace String and Query + Replace, unless Case Replace is zero). + Space Exit and make no changes. + % Read a digit as above and Query Replace (M-%) the + incorrect spelling with the correct one from the + beginning of the buffer. + +No other responses are allowed. + +The cursor need not be immediately after the word you want to correct; +it can be in the middle, or following any word-separator characters +after the end of the word. Note that the major mode you are using +affects which characters are word-separators. *Note Syntax Table: +Syntax. + +The first time you use M-$, it creates a SPELL job for you. From then +on it uses the same SPELL job. It's ok to kill the job if you don't +think you'll be using M-$ again during that session. But if you do +leave the job around checking words will much quicker. Giving M-$ a +negative argument (as in M-- M-$) kills the SPELL job. Of course, you +can kill it from DDT also. + +If you are a regular user of the SPELL program, you might have a +dictionary file of words which you use but which are foreign to SPELL. +If there are words in this file which you might want to use M-$ to +correct, you can specify that you want this dictionary to be loaded into +the spell job which EMACS uses. To do this, set the variable Spell +Initialization to the string of SPELL program commands you want to use. +For loading a dictionary, this string would be a "Load " followed by the +dictionary filename. Other initialization commands for SPELL can appear +there also. The commands must be separated by altmodes. + +Because of the way the handling of other jobs from EMACS is implemented +on ITS, it is not possible to use M-$ in an EMACS whose superior is not +DDT. This typically applies to EMACS jobs running under LISP (LISPT) +and under :MAIL (MAILT). + + +EMACS Node: Files, Previous: Fixit, Up: Top, Next: Buffers + +File Handling + +The basic unit of stored data is the file. Each program, each paper, +lives usually in its own file. To edit a program or paper, the editor +must be told the name of the file that contains it. This is called +"visiting" the file. To make your changes to the file permanent on +disk, you must "save" the file. EMACS also has facilities for deleting +files conveniently, and for listing your file directory. Special text +in a file can specify the modes to be used when editing the file. + + +* Menu: + + +* Visiting:: How to select a file for editing +* Revert:: How to cancel some changes you have made +* AutoSave:: Protection from crashes +* CleanDir:: Deleting old versions to clean up +* DIRED:: Selectively deleting files (Directory Editor) +* Filadv:: Advanced file commands +* DirComp:: Directory comparison + + + +EMACS Node: Visiting, Previous: Files, Up: Files, Next: Revert + +Visiting Files + + C-X C-V Visit a file. + C-X C-Q Change regular visiting to read only, or vice versa. + C-X C-S Save the visited file. + Meta-~ Tell EMACS to forget that the buffer has been + changed. + +"Visiting" a file means copying its contents into EMACS where you can +edit them. EMACS remembers the name of the file you visited. Unless +you use the multiple buffer or window features of EMACS, you can only be +visiting one file at a time. The name of the file you are visiting in +the currently selected buffer is visible in the mode line when you are +at top level, followed by its version number if it has one in +parentheses. + +The changes you make with EMACS are made in a copy inside EMACS. The +file itself is not changed. The changed text is not permanent until you +"save" it in a file. The first time you change the text, a star appears +at the end of the mode line; this indicates that the text contains fresh +changes which will be lost unless you save them. + +To visit a file, use the command C-X C-V (^R Visit File). Follow the +command with the name of the file you wish to visit, terminated by a +Return. If you can see a filename in the mode line, then that name is +the default, and any component of the filename which you don't specify +is taken from it. If EMACS thinks you can't see the defaults, they are +included in the prompt. You can abort the command by typing C-G, or +edit the filename with Rubout or C-U. If you do type a Return to finish +the command, the new file's text appears on the screen, and its name and +version appear in the mode line. + +When you wish to save the file and make your changes permanent, type C-X +C-S (^R Save File). After the save is finished, C-X C-S prints +"Written: " in the echo area at the bottom of the screen. If +there are no changes to save (no star at the end of the mode line), the +file is not saved; it would be redundant to save a duplicate of the +previous version. + +Because a system crash can cause you to lose everything you have done +since the last save, we provide Auto Save mode, which saves the files +you are visiting at regular intervals automatically. *Note Auto Save: +AutoSave. Alternatively, you can use journal files. *Note Journals: +Journals. + +What if you want to create a file? Just visit it. EMACS prints +"(New File)" but aside from that behaves as if you had visited an +existing empty file. If you make any changes and save them, the file is +created. If you visit a nonexistent file unintentionally (because you +typed the wrong file name), go ahead and visit the file you meant. If +you don't save the unwanted file, it is not created. + +If you visit a file which is a link, EMACS prints +"(Link to )" to inform you of this. When you read a file +which is a link, you get the contents of the target file, but if you +save under the name of the link, you replace the link and the target +does not change. If you would prefer to alter the target file, use Set +Visited Filename to change the visited name to the target file's name. +*Note Set Visited Filename: Filadv. + +If you alter one file and then visit another in the same buffer, EMACS +offers to save the old one. If you answer Y, the old file is saved; if +you answer N, all the changes you have made to it since the last save +are lost. You should not type ahead after a file visiting command, +because your type-ahead might answer an unexpected question in a way +that you would regret. The variable Visit File Save Old controls this +offer; normally, it is one, which means that the offer is made. If it +is minus one, then the old file is always saved when you visit a new one +in the same buffer; no question is asked. If it is zero, the old file +is never saved. + +A nonzero argument to C-X C-V specifies "read-only" visiting. This +means that EMACS prevents you from modifying the file unless you insist. +You should use this when you visit a file that you do no want to change, +just to avoid changing it accidentally. If you give C-X C-V a positive +argument, then the file is read-only. This means you can change the +text in the buffer, but EMACS requires extra confirmation if you ask to +save the file, and never offers to save it. If you give C-X C-V a +negative argument, then the buffer itself is read-only; commands to +change the text are not allowed. If the visited file is visited +read-only, in either fashion, then the characters "(R-O)" appear in the +mode line after the filename. The command C-X C-Q (^R Set File +Read-Only) is used to switch between read-only and normal visiting. Its +numeric argument means the same thing as the argument to C-X C-V: zero +means changes are allowed, positive makes the file read-only, and +negative makes the text itself read-only. + +Sometimes you will change a buffer by accident. Even if you undo the +change by hand, EMACS still knows that "the buffer has been changed". +You can tell EMACS to believe that there have been no changes with the +Meta-~ (^R Buffer Not Modified) command. This command simply clears the +"modified" flag which says that the buffer contains changes which need +to be saved. Even if the buffer really is changed EMACS will still act +as if it were not. If we take "~" to mean "not", then Meta-~ is "not" +metafied. + +If EMACS is about to do an unrequested save, and discovers that the text +is now a lot shorter than it used to be, it tells you so and asks for +confirmation (Y or N). If you aren't sure what to answer (because you +are surprised that it has shrunk), type C-G to abort everything, and +take a look around. + +If EMACS is about to save a file and sees that the date of the latest +version on disk does not match what EMACS last read or wrote, EMACS +notifies you of this fact, and asks what to do, because this probably +means that something is wrong. For example, someone else may have been +editing the same file. If this is so, there is a good chance that your +work or his work will be lost if you don't take the proper steps. You +should first find out exactly what is going on. The C-X C-D command to +list the directory will help. If you determine that someone else has +modified the file, save your file under different names (or at least +making a new version) and then SRCCOM the two files to merge the two +sets of changes. Also get in touch with the other person so that he +doesn't continue editing. + + +EMACS Node: Revert, Previous: Visiting, Up: Files, Next: AutoSave + +How to Undo Drastic Changes to a File + +If you have made extensive changes to a file and then change your mind +about them, you can get rid of them by reading in the previous version +of the file. To do this, use M-X Revert File. If you have been using +Auto Save mode, it reads in the last version of the visited file or the +last auto save file, whichever is more recent. + +In Auto Save mode, saving under special Auto Save filenames, then you +can ask to revert to the last "real" save, ignoring subsequent auto +saves, with C-U M-X Revert File. If you are using the style of auto +saving which saves under the real filenames, this is not possible. + +M-X Revert File does not change point, so that if the file was only +edited slightly, you will be at approximately the same piece of text +after the Revert as before. If you have made drastic changes, the same +value of point in the old file may address a totally different piece of +text. + +Because M-X Revert File can be a disaster if done by mistake, it asks +for confirmation (Y or N) before doing its work. A pre-comma argument +can be used to inhibit the request for confirmation when you call the +function Revert File from a TECO program, as in 1,M(M.M Revert File). + + +EMACS Node: AutoSave, Previous: Revert, Up: Files, Next: ListDir + +Auto Save Mode: Protection Against Disasters + +In Auto Save mode, EMACS saves your file from time to time (based on +counting your commands) without being asked. Your file is also saved if +you stop typing for more than a few minutes when there are changes in +the buffer. This prevents you from losing more than a limited amount of +work in a disaster. (Another method of protection is the journal file. +*Note Journals: Journals.). + +You can turn auto saving on or off in an individual buffer with M-X Auto +Save. In addition, you can have auto saving by default in all buffers +by setting the option Auto Save Default. The frequency of saving, and +the number of saved versions to keep, can both be specified. + +Each time you visit a file, no matter how, auto saving is turned on for +that file if Auto Save Default is nonzero. Once you have visited a +file, you can turn auto saving on or off with M-X Auto Save. Like other +minor mode commands, M-X Auto Save turns the mode on with a positive +argument, off with a zero or negative argument; with no argument, it +toggles. If you start typing a new file into a buffer without visiting +anything, Auto Save mode is initially off, but you can turn it on with +M-X Auto Save. + +When an auto save happens, "(Auto Save)" is printed in the echo area (On +a printing terminal, the bell is rung instead). An error in the process +of auto saving prints "(Auto Save Error!)". + +Let us suppose that it is time for an automatic save to be done: where +should the file be saved? + +Two workable methods have been developed: save the file under the names +you have visited, or save it under some special "auto save file name". +Each solution has its good and bad points. The first one is excellent +some of the time, but intolerable the rest of the time. The second is +usually acceptable. Auto saving under the visited file's actual names +means that you need do nothing special to gobble the auto save file when +you need it; and it means that there is no need to worry about +interference between two users sharing a directory, as long as they +aren't editing the same file at once. However, this method can +sometimes have problems: + + If you visit a file on a device other than DSK, auto saves can't + go there, because it would probably be slow. + + If the file is visited read-only, then auto saves should + certainly not go under the names that are visited. + + If your file does not have a numeric version number, or you have + visited a fixed version, auto saves can't go under that name, + because they would clobber the original file. + + If you haven't visited a file, there aren't any names to use. + +If none of those cases apply then it is possible to store auto saves +under the visited name. This is done, provided that you enable it by +setting the variable Auto Save Visited File to a nonzero value. +Otherwise, or if one of the cases listed above applies, then the +filename used for auto saves is taken from the variable Auto Save +Filenames, modified slightly so that different buffers save under +different names. If the last two characters of the FN1 are "00", then +they are replaced by the last two digits (or the only digit) of the +buffer number, the number which appears at the beginning of each line +printed by C-X C-B. Auto Save Filenames is usually set up by the +default init file to DSK:;_SAV00 >. + +When you want to save your file "for real", use C-X C-S, as always. C-U +C-X C-S is a way to request an "auto" save explicitly. When you are +auto saving under the visited filenames, there is not much difference +between an auto save and a "real" save, except that an auto save will +eventually be deleted automatically by EMACS a few auto saves later, +while a "real" save will be left around forever (at least, Auto Save +won't delete it). + +When it is time to recover from a system crash by reloading the auto +save file, if auto saving was using the visited file names you have +nothing special to do. If auto saving was using special auto save +filenames, read in the last auto save file and then use C-X C-W (Write +File) to write it out in its real location. If you want to go back to +an auto save file to throw away changes that you don't like, you can use +M-X Revert File, which knows how to find the most recent save, permanent +or not, under whatever filenames. *Note Revert: Revert. + +For your protection, if a file has shrunk by more than 30% since the +last save, auto saving does not save. Instead it prints a message that +the file has shrunk. You can save explicitly if you wish; after that, +auto saving will resume. + +Although auto saving generates large numbers of files, it does not clog +directories, because it cleans up after itself. Only the last Auto Save +Max auto save files are kept; as further saves are done, old auto saves +are deleted. However, only files made by auto saving (or by explicitly +requested auto-saves with C-U C-X C-S) are deleted in this way. If Auto +Save Max is 1, then repeated auto saves rewrite the same version of the +file; the version number is only incremented after a real save. + +The variable Auto Save Max is initially 2. Changing the value may not +take effect in a given buffer until you turn auto saving off and on in +that buffer. + +The number of characters of input between auto saves is controlled by +the variable Auto Save Interval. It is initially 500. Changing this +takes effect immediately. + +If you use the multiple-buffer features of EMACS (*Note Buffers: +Buffers.) then you may want to have auto saving for all buffers, not +just the one that is selected at the moment. To get this, set the +variable Auto Save All Buffers nonzero. + + +EMACS Node: ListDir, Previous: AutoSave, Up: Files, Next: CleanDir + +Listing a File Directory + +To look at a part of a file directory, use the C-X C-D command +(^R Directory Display). With no argument, it shows you the file you are +visiting, and related files with the same first name. C-U C-X C-D reads +a filename from the terminal and shows you the files related to that +filename. + +To see the whole directory in a brief format, use the function List +Files, which takes the directory name as a string argument. The +function View Directory prints a verbose listing of a whole directory. + +The variable Auto Directory Display can be set to make many file +operations display the directory automatically. The variable is +normally 0; making it positive causes write operations such as Write +File to display the directory, and making it negative causes read +operations such as Insert File or visiting to display it as well. The +display is done using the default directory listing function which is +kept in the variable Directory Lister. Normally this is the function +& Subset Directory that displays only the files related to the current +default file. An alternative type of directory listing can be obtained +by setting Directory Lister to the function & Rotated Directory Listing. +After this function display the particular file you are interested in, +it offers to display the rest. If you say "yes" (with a Space), it +displays through the end of the directory, and around to the beginning +of the directory, stopping where it originally started. *Note Init: +Init. + +The function List Directories prints an alphabetized list of all the +file directories on the system. + + +EMACS Node: CleanDir, Previous: ListDir, Up: Files, Next: DIRED + +Cleaning a File Directory + +The normal course of editing constantly creates new versions of files. +If you don't eventually delete the old versions, the directory will fill +up and further editing will be impossible. EMACS has commands that make +it easy to delete the old versions. + +For complete flexibility to delete precisely the files you want to +delete, you can use the DIRED package. *Note DIRED: DIRED, for more +details. + +M-X Reap File and M-X Clean Directory are more convenient ways to do the +usual thing: keep only the two (or other number) most recent versions. + +M-X Reap File counts the number of versions of . If +there are more than two, you are told the names of the recent ones (to +be kept) and the names of the older ones (to be deleted), and asked +whether to do the deletion (answer Y or N). + +Reap File makes a special offer to delete individual files whose +FN2 indicates that they are likely to be temporary. The list of +temporary names is contained in a TECO search string in the variable +Temp File FN2 List. *Note TECO search strings: TECOsearch. + +If you give M-X Reap File a null filename argument, or no argument, then +it applies to the file you are visiting. + +M-X Clean Directory; cleans a whole directory of old +versions. Each file in the directory is processed a la M-X Reap File. +M-X Clean Directory with a null argument, or no argument, cleans the +directory containing the file you are visiting. + +M-X Reap File and M-X Clean Directory can be given a numeric argument +which specifies how many versions to keep. For example, C-U 4 M-X Reap +File would keep the four most recent versions. The default when there +is no argument is the value of the variable File Versions Kept, which is +initially 2. + + +EMACS Node: DIRED, Previous: CleanDir, Up: Files, Next: Filadv + +DIRED, the Directory Editor Subsystem + +DIRED makes it easy to delete many of the files in a single directory at +once. It presents a copy of a listing of the directory, which you can +move around in, marking files for deletion. When you are satisfied, you +can tell DIRED to go ahead and delete the marked files. + +Invoke DIRED with M-X DIRED to edit the current default directory, or +M-X DIRED; to edit directory . You are then given a +listing of the directory which you can move around in with all the +normal EMACS motion commands. Some EMACS commands are made illegal and +others do special things, but it's still a recursive editing level which +you can exit normally with C-M-C and abort with C-]. + +Basic DIRED Commands + +You can mark a file for deletion by moving to the line describing the +file and typing D, C-D, K, or C-K. The deletion mark is visible as a D +at the beginning of the line. Point is moved to the beginning of the +next line, so that several D's delete several files. Alternatively, if +you give D an argument it marks that many consecutive files. Given a +negative argument, it marks the preceding file (or several files) and +puts point at the first (in the buffer) line marked. Most of the DIRED +commands (D, U, !, $, P, S, C, E, Space) repeat this way with numeric +arguments. + +If you wish to remove a deletion mark, use the U (for Undelete) command, +which is invoked like D: it removes the deletion mark from the current +line (or next few lines, if given an argument). The Rubout command +removes the deletion mark from the previous line, moving up to that +line. Thus, a Rubout after a D precisely cancels the D. + +For extra convenience, Space is made a command similar to C-N. Moving +down a line is done so often in DIRED that it deserves to be easy to +type. Rubout is often useful simply for moving up. + +If you are not sure whether you want to delete a file, you can examine +it by typing E. This enters a recursive editing mode on the file, which +you can exit with C-M-C. The file is not really visited at that time, +and you are not allowed to change it. When you exit the recursive +editing level, you return to DIRED. The V command is like E but uses +View File to look at the file. + +When you have marked the files you wish to mark, you can exit DIRED with +C-M-C. If any files were marked for deletion, DIRED lists them in a +concise format, several per line. A file with "!" appearing next to it +in this list has not been saved on tape and will be gone forever if +deleted. A file with ">" in front of it is the most recent version of a +sequence and you should be wary of deleting it. Then DIRED asks for +confirmation of the list. You can type "YES" (Just "Y" won't do) to go +ahead and delete them, "N" to return to editing the directory so you can +change the marks, or "X" to give up and delete nothing. No Return +character is needed. No other inputs are accepted at this point. + +Other DIRED Commands + +The "!" command moves down (or up, with an argument of -1) to the next +undumped file (one with a "!" before its date). + +N finds the next "hog": the next file which has at least three versions +(or, more than File Versions Kept). + +T when given on a line describing a link marks for deletion the file +which the link points to. This file need not be in the directory you +are editing to be deleted in this way. + +1 copies the file you are pointing at to the primary pack. 2 copies it +to SECOND:. 3 copies it to THIRD:. 4 copies it to FOURTH:. + +$ complements the don't-reap attribute of the file; this is displayed as +a dollar sign to the left of the file date. + +M moves the file to any other directory or device. You must say where +to move it. + +C runs SRCCOM to compare the file version you are pointing at with the +latest version of the same file. You must confirm the SRCCOM command +with a Return before it is executed; you can add extra SRCCOM switches +before the Return. When you return to EMACS, the cursor moves down a +line to the next file. + +H helps you clean up. It marks "old" versions of the current file, and +versions with "temporary" second file names, for deletion. You can then +use the D and U commands to add and remove marks before deleting the +files. The variables File Versions Kept and Temp File FN2 List control +which files H picks for deletion. With an argument (C-U H), it does the +whole directory instead of just the current file. + +? displays a list of the DIRED commands. + +Invoking DIRED + +There are some other ways to invoke DIRED. The command C-X D (^R Dired) +puts you in DIRED on the directory containing the file you are currently +editing. With a numeric argument of 1 (C-U 1 C-X D), only the current +file is displayed instead of the whole directory. In combination with +the H command this can be useful for cleaning up excess versions of a +file after a heavy editing session. With a numeric argument of 4 (C-U +C-X D), it asks you for the directory name. Type a directory name +followed by a semicolon, and/or a file name. If you explicitly specify +a file name only versions of that file are displayed, otherwise the +whole directory is displayed. + +Editing the DIRED Buffer Yourself + +It is unwise to try to edit the text of the directory listing yourself, +without using the special DIRED commands, unless you know what you are +doing, since you can confuse DIRED that way. To make it less likely +that you will do so accidentally, the self-inserting characters are all +made illegal inside DIRED. However, deleting whole lines at a time is +certainly safe. This does not delete the files described by those +lines; instead, it makes DIRED forget that they are there and thus makes +sure they will NOT be deleted. Thus, M-X Delete Non-Matching +LinesFOO is useful if you wish to delete only files with a FOO in +their names. *Note Keep Lines: Replace. + +For more complicated things, you can use the minibuffer. When you call +the minibuffer from within DIRED, you get a perfectly normal one. The +special DIRED commands are not present while you are editing in the +minibuffer. To mark a file for deletion, replace the space at the +beginning of its line with a "D". To remove a mark, replace the "D" +with a space. + + +EMACS Node: Filadv, Previous: DIRED, Up: Files, Next: DirComp + +Miscellaneous File Operations + +EMACS has extended commands for performing many other operations on +files. + +M-X View File allows you to scan or read a file by sequential +screenfuls without visiting the file. It enters a subsystem in which +you type a Space to see the next screenful or a Backspace to see the +previous screenful. Typing anything else exits the command. View File +does not visit the file; it does not alter the contents of any buffer. +The advantage of View File is that the whole file does not need to be +loaded before you can begin reading it. The inability to do anything +but page forward or backward is a consequence. + +M-X Write File writes the contents of the buffer into the +file , and then visits that file. It can be thought of as a way +of "changing the name" of the file you are visiting. Unlike C-X C-S, +Write File saves even if the buffer has not been changed. C-X C-W is +another way of getting at this command. + +M-X Insert File inserts the contents of into the +buffer at point, leaving point unchanged before the contents and mark +after them. The current defaults are used for , and are updated. + +M-X Write Region writes the region (the text between point +and mark) to the specified file. It does not set the visited filenames. +The buffer is not changed. + +M-X Append to File appends the region to . The text is +added to the end of . + +M-X Prepend to File adds the text to the beginning of +instead of the end. + +M-X Set Visited Filename changes the name of the file being +visited without reading or writing the data in the buffer. M-X Write +File is approximately equivalent to this command followed by a C-X C-S. + +M-X Delete File deletes the file. If you did not get a +chance to see the default filenames before typing the filename to +delete, then Delete File asks for confirmation before deleting the file. + +M-X Copy File copies the file. + +M-X Rename File renames the file. + +The default filenames for all of these operations are "TECO default +filenames". Most of these operations also leave the TECO default names +set to the file they operated on. The TECO default is NOT ALWAYS the +same as the file you are visiting. When you visit a file, they start +out the same; the commands mentioned above change the TECO default, but +do not change the visited filenames. Each buffer has its own TECO +default filenames. + +The operation of visiting a file is available as a function under the +name M-X Visit File. In this form, it uses the TECO default as +its defaults, though it still sets both the TECO default and the visited +filenames. + + +EMACS Node: DirComp, Previous: Filadv, Up: Files + +The Directory Comparison Subsystem + +The function Compare Directories makes it easy to compare two +directories to see which files are present in both and which are present +only in one. It compares a directory on the local machine with the +directory of the same name on another machine. + +Do M-X Compare Directories: , where + is AI, ML, MC or DM, and is not the machine you are on, is an optional directory name and semicolon, and the optional +switch is a slash followed by S, D or L. + +After a while of crunching, you will be placed in a recursive editing +level on a listing of both directories. The reason for the recursive +editing level is simply to make it easy for you to view the comparison; +unlike DIRED, Compare Directories does not have any commands for moving +or deleting the files. To exit, do C-M-C. + +Here is a sample of part of a directory comparison: + + AI RMS #1=72 #2=78 #3=71 #4=77 #5=87 - + MC RMS #0=231 #1=254 #13=2844 + AI MC .DDT. (INIT) 1 11/18/76 01:08 10/21/76 05:06 + AI MC L .DDT_ (INIT) STAN.K ML EXIT + MC L .TECO. (INIT) .TECO. .TECO. (INIT) + AI AR2 1 16 2/6/77 17:51 + AI AR3 1 13 2/17/77 21:37 + AI L ATS ORDER .INFO. @ ORDER + MC FTPU 4 9 !3/4/77 16:46 + MC FTPU 5 9 !3/4/77 16:49 + AI MC MATCH 1 15 !3/4/77 15:39 !3/4/77 15:39 + +It begins with one line for each of the two directories. These lines +say which two directories they are, and how much disk space is available +on each of the machines. + +Then there comes the list of files, one line for each distinct pair of +filenames that appears. At the beginning of the line appear the names +of the machines on which the file exists. At the end of the line come +the creation dates (or names pointed at, for links) of the file for the +machines it is on. Note that all the dates/link names for the first +machine line up, and so do all those for the second machine. + +The switches allow you to view only some of the files. The /S switch +shows only files present on both machines. /D shows only those not +present on both machines. /L shows only files which are the most recent +(largest-numbered) of a sequence. Only one switch is allowed. + + +EMACS Node: Buffers, Previous: Files, Up: Top, Next: Display + +Using Multiple Buffers + +When we speak of "the buffer", which contains the text you are editing, +we have given the impression that there is only one. In fact, there may +be many of them, each with its own body of text. At any time only one +buffer can be "selected" and available for editing, but it isn't hard to +switch to a different one. Each buffer individually remembers which +file it is visiting, what modes are in effect, and whether there are any +changes that need saving. + + C-X B Select or create a buffer. + C-X C-F Visit a file in its own buffer. + C-X C-B List the existing buffers. + C-X K Kill a buffer. + +Each buffer in EMACS has a single name, which normally doesn't change. +A buffer's name can be any length. The name of the currently selected +buffer, and the name of the file visited in it, are visible in the mode +line when you are at top level. A newly started EMACS has only one +buffer, named "Main". + +As well as the visited file and the major mode, a buffer can, if ordered +to, remember many other things "locally", which means, independently of +all other buffers. *Note Variables: Variables. + +Creating and Selecting Buffers + +To create a new buffer, you need only think of a name for it (say, +"FOO") and then do C-X B FOO, which is the command C-X B (Select +Buffer) followed by the name. This makes a new, empty buffer and +selects it for editing. The new buffer is not visiting any file, so if +you try to save it you will be asked for the filenames to use. Each +buffer has its own major mode; the new buffer's major mode is taken from +the value of the variable Default Major Mode, or from the major mode of +the previously selected buffer if the value of Default Major Mode is the +null string. Normally the Default Major Mode is Fundamental mode. + +To return to buffer FOO later after having switched to another, the same +command C-X B FOO is used, since C-X B can tell whether a buffer +named FOO exists already or not. It does not matter whether you use +upper case or lower case in typing the name of a buffer. C-X B Main +reselects the buffer Main that EMACS started out with. Just C-X B +reselects the previous buffer. Repeated C-X B's alternate between +the last two buffers selected. + +You can also read a file into its own newly created buffer, all with one +command: C-X C-F (Find File), followed by the filename. The first name +of the file becomes the buffer name. C-F stands for "Find", because if +the specified file already resides in a buffer in your EMACS, that +buffer is reselected. So you need not remember whether you have brought +the file in already or not. A buffer created by C-X C-F can be +reselected later with C-X B or C-X C-F, whichever you find more +convenient. Nonexistent files can be created with C-X C-F just as they +can be with C-X C-V. A nonzero argument to C-X C-F makes the file or +buffer read-only; it is like the argument to C-X C-V. *Note Visiting: +Visiting. + +Sometimes EMACS needs to visit a file as part of some other operation. +By default, it visits the file in whatever buffer was selected. If you +like to use C-X C-F and multiple buffers, you can tell EMACS to use +multiple buffers for implicit visiting by setting the variable TAGS Find +File to a nonzero value. This causes automatic visiting to be done by +means of C-X C-F instead of C-X C-V. Automatic visiting is done by the +TAGS package (*Note TAGS: (TAGS)Top.) and by invoking EMACS with a +filename + + :EMACS + +If the buffer with the same name that C-X C-F wants to use already +exists but with the wrong contents (often a different file with a +similar name), then you are asked what to do. You can type Return +meaning go ahead and reuse that buffer for this new file, or you can +type another buffer name to use instead. If C-X C-F does find the file +already in a buffer, then it checks to see whether the version on disk +is the same as the last version read or written from that buffer, for +safety. If they are different, you are warned that someone else may be +editing the file, and left with the version which was already in the +EMACS. To get the new version from disk instead, use M-X Revert File. + +Using Existing Buffers + +To get a list of all the buffers that exist, do C-X C-B (List Buffers). +Each buffer's name, major mode, and visited filenames are printed. A +star at the beginning of a line indicates a buffer which contains +changes that have not been saved. The number that appears before a +buffer's name in a C-X C-B listing is that buffer's "buffer number". +You can select a buffer by giving its number as a numeric argument to +C-X B, which then does not need to read a string from the terminal. + +If several buffers have stars, you should save some of them with M-X +Save All Files. This finds all the buffers that need saving and asks +about each one individually. Saving the buffers this way is much easier +and more efficient than selecting each one and typing C-X C-S. + +A quick way of glancing at another buffer, faster than selecting it, is +to use M-X View Buffer. This displays the contents of +the other buffer and lets you move forward and back a screen at a time +with Space and Backspace. *Note View Buffer: Display. + +M-X Rename Buffer changes the name of the currently +selected buffer. If is the null string, the first filename +of the visited file is used as the new name of the buffer. + +The commands C-X A (^R Append to Buffer) and M-X Insert Buffer can be +used to copy text from one buffer to another. *Note Copying: Copying. + +Killing Buffers + +After you use an EMACS for a while, it may fill up with buffers which +you no longer need. Eventually you can reach a point where trying to +create any more results in an "URK" error. So whenever it is convenient +you should do M-X Kill Some Buffers, which asks about each buffer +individually. You can say Y or N to kill it or not. Or you can say +Control-R to take a look at it first. This does not actually select the +buffer, as the mode line shows, but gives you a recursive editing level +in which you can move around and look at things. When you have seen +enough to make up your mind, exit the recursive editing level with a +C-M-C and you will be asked the question again. If you say to kill a +buffer that needs saving, you will be asked whether it should be saved. +*Note URK Error: Lossage. + +You can kill the buffer FOO by doing C-X K FOO. You can kill the +selected buffer, a common thing to do if you use C-X C-F, by doing C-X +K. If you kill the selected buffer, in any way, EMACS asks you +which buffer to select instead. Saying just at that point tells +EMACS to choose one reasonably. C-X K runs the function Kill Buffer. + + +EMACS Node: Display, Previous: Buffers, Up: Top, Next: Windows + +Controlling the Display + +Since only part of a large file fits on the screen, EMACS tries to show +the part that is likely to be interesting. The display control commands +allow you to ask to see a different part of the file. + + C-L Clear and redisplay screen, putting point at a specified + vertical position. + C-V Scroll forwards (a screen or a few lines). + M-V Scroll backwards. + M-R Move point to the text at a given vertical position. + C-M-R Shift the function point is in onto the screen. + +The terminal screen is rarely large enough to display all of your file. +If the whole buffer doesn't fit on the screen, EMACS shows a contiguous +portion of it, containing point. It continues to show approximately the +same portion until point moves outside of it; then EMACS chooses a new +portion centered around the new point. This is EMACS's guess as to what +you are most interested in seeing. But if the guess is wrong, you can +use the display control commands to see a different portion. The finite +area of screen through which you can see part of the buffer is called +"the window", and the choice of where in the buffer to start displaying +is also called "the window". + +First we describe how EMACS chooses a new window position on its own. +The goal is usually to place point 35 percent of the way down the +screen. This is controlled by the variable Cursor Centering Point, +whose value is the percent of the screen down from the top. However, if +the end of the buffer is on the screen, EMACS tries to leave at most 35 +percent of the screen blank beneath it, so that the screen is not +wasted. This percentage is controlled by the variable End of Buffer +Display Margin. These variables work by controlling FS flags, and their +values must never be negative or greater than 99. + +Normally EMACS only chooses a new window position if you move point off +the screen. However, you can ask for a new window position to be +computed whenever point gets too close to the top of the screen by +setting the variable Top Display Margin to the percentage of the screen +in which point must not appear. Bottom Display Margin does the same +thing for a region near the bottom. + +The basic display control command is C-L (^R New Window). In its +simplest form, with no argument, it clears the screen and tells EMACS to +choose a new window position, centering point 35 percent of the way from +the top as usual. + +C-L with a positive argument chooses a new window so as to put point +that many lines from the top. An argument of zero puts point on the +very top line. Point does not move with respect to the text; rather, +the text and point move rigidly on the screen. C-L with a negative +argument puts point that many lines from the bottom of the window. For +example, C-U -1 C-L puts point on the bottom line, and C-U -5 C-L puts +it five lines from the bottom. C-L with an argument does not clear the +screen, so that it can move the text on the screen instead of printing +it again if the terminal allows that. + +C-U C-L is different from C-L with any other sort of argument. It +causes just the line containing point to be redisplayed. + +The "scrolling" commands C-V and M-V let you move the whole display up +or down a few lines. C-V (^R Next Screen) with an argument shows you +that many more lines at the bottom of the screen, moving the text and +point up together as C-L might. C-V with a negative argument shows you +more lines at the top of the screen, as does Meta-V (^R Previous Screen) +with a positive argument. + +To read the buffer a screenful at a time, use the C-V command with no +argument. It takes the last two lines at the bottom of the screen and +puts them at the top, followed by nearly a whole screenful of lines not +visible before. Point is put at the top of the screen. Thus, each C-V +shows the "next screenful", except for two lines of overlap to provide +continuity. The variable Next Screen Context Lines, if defined, +controls how many lines from the bottom of the screen move to the top; +the default if the variable is not defined is 2. To move backward, use +M-V without an argument, which moves a whole screenful backwards (again +with overlap). + +Scanning by screenfuls through the buffer for some distance is most +conveniently done with the M-X View Buffer command. This command enters +a simple subsystem in which Space moves a screenful forward and +Backspace moves a screenful backward. The Return character exits, +leaving point centered in whatever part of the buffer was visible. Any +other character exits and returns point to its former location, and is +then executed as a command (unless it is a Rubout; Rubout exits but is +not executed). View Buffer can be used to view another buffer by giving +the buffer's name as a string argument. In this case, exiting with +Return moves point permanently in the other buffer, but does not select +it. *Note Buffers: Buffers. + +With the M-X View File command, you can scan by screenfuls through a +file which you have not visited. *Note View File: FilAdv. + +To scroll the buffer so that the current function or paragraph is +positioned conveniently on the screen, use the C-M-R command +(^R Reposition Window). This command tries to get as much as possible +of the current function or paragraph onto the screen, preferring the +beginning to the end, but not moving point off the screen. A "function" +in Lisp mode is a defun; otherwise it is defined to be a set of +consecutive unindented lines, or a set of consecutive indented lines. + +C-L in all its forms changes the position of point on the screen, +carrying the text with it. Another command moves point the same way but +leaves the text fixed. It is called Meta-R (^R Move to Screen Edge). +With no argument, it puts point at the beginning of the line at the +center of the screen. An argument is used to specify the line to put it +on, counting from the top if the argument is positive, or from the +bottom if it is negative. Thus, Meta-R with an argument of 0 puts point +on the top line of the screen. Meta-R never causes any text to move on +the screen; it causes point to move with respect to the screen and the +text. + + +EMACS Node: Windows, Previous: Display, Up: Top, Next: Narrowing + +Two Window Mode + +EMACS allows you to split the screen into two "windows" and use them to +display parts of two files, or two parts of the same file. + + C-X 2 Start showing two windows. + C-X 3 Show two windows but stay "in" the top one. + C-X 1 Show only one window again. + C-X O Switch to the Other window + C-X 4 Find buffer, file or tag in other window. + C-X ^ Make this window bigger. + C-M-V Scroll the other window. + +In "two window" mode, the text display portion of the screen is divided +into two parts called "windows", which display different pieces of text. +The two windows can display two different files, or two parts of the +same file. Only one of the windows is selected; that is the window +which the cursor is in. Editing normally takes place in that window +alone. To edit in the other window, you would give a special command to +move the cursor to the other window, and then edit there. Since there +is only one mode line, it applies to the window you are in at the +moment. + +The command C-X 2 (^R Two Windows) enters two-window mode. A line of +dashes appears across the middle of the screen, dividing the text +display area into two halves. Window one, containing the same text as +previously occupied the whole screen, fills the top half, while window +two fills the bottom half. The cursor moves to window two. If this is +your first entry to two-window mode, window two contains a new buffer +named W2. Otherwise, it contains the same text it held the last time +you looked at it. + +To return to viewing only one window, use the command C-X 1 (^R One +Window). Window one expands to fill the whole screen, and window two +disappears until the next C-X 2. C-U C-X 1 gets rid of window one and +makes window two use the whole screen. Neither of these depends on +which window the cursor is in when the command is given. + +While you are in two window mode you can use C-X O (^R Other Window) to +switch between the windows. After doing C-X 2, the cursor is in window +two. Doing C-X O moves the cursor back to window one, to exactly where +it was before the C-X 2. The difference between this and doing C-X 1 is +that C-X O leaves window two visible on the screen. A second C-X O +moves the cursor back into window two, to where it was before the first +C-X O. And so on... + +Often you will be editing one window while using the other just for +reference. Then, the command C-M-V (^R Scroll Other Window) is very +useful. It scrolls the other window without switching to it and +switching back. It scrolls the same way C-V does: with no argument, a +whole screen up; with an argument, that many lines up (or down, for a +negative argument). With just a minus sign (no digits) as an argument, +C-M-V scrolls a whole screenful backwards (what M-V does). + +The C-X 3 (^R View Two Windows) command is like C-X 2 but leaves the +cursor in window one. That is, it makes window two appear at the bottom +of the screen but leaves the cursor where it was. C-X 2 is equivalent +to C-X 3 C-X O. C-X 3 is equivalent to C-X 2 C-X O, but C-X 3 is much +faster. + +M-X Compare Windows compares the text in the two windows. Starting from +the existing values of point in each window, it advances point in both +windows to the first mismatch. The variable Collapse in Comparison, if +it exists, should be a string containing all the "insignificant" +characters; any string of insignificant characters matches any other +string of those characters. If the variable does not exist, the +insignificant characters are return, linefeed, space and tab. + +If you quit with C-G in the middle of Compare Windows, point is advanced +in both windows as far as the matching has proceeded. As a result, +calling Compare Windows again resumes the comparison. + +Normally, the screen is divided evenly between the two windows. You can +also redistribute screen space between the windows with the C-X ^ +(^R Grow Window) command. It makes the currently selected window get +one line bigger, or as many lines as is specified with a numeric +argument. With a negative argument, it makes the selected window +smaller. The allocation of space to the windows is remembered while you +are in one window mode and the same allocation is used when you return +to two window mode. The allocation changes only when you give a C-X ^ +command. + +After leaving two-window mode, you can still use C-X O, but its meaning +is different. Window two does not appear, but whatever was being shown +in it appears, in window one (the whole screen). Whatever buffer used +to be in window one is stuck, invisibly, into window two. Another C-X O +reverses the effect of the first. For example, if window one shows +buffer B and window two shows buffer W2 (the usual case), and only +window one is visible, then after a C-X O window one shows buffer W2 and +window two shows buffer B. + +Multiple Windows and Multiple Buffers + +Buffers can be selected independently in each window. The C-X B command +selects a new buffer in whichever window the cursor is in. The other +window's buffer does not change. Window two's buffer is remembered +while you are in one window mode, and when you return to two window mode +that same buffer reappears in window two. *Note Buffers: Buffers. + +You can view one buffer in both windows. Give C-X 2 an argument as in +C-U C-X 2 to go into two window mode, with both windows showing the +buffer which used to be in window one alone. Although the same buffer +appears in both windows, they have different values of point, so you can +move around in window two while window one continues to show the same +text. Then, having found in window two the place you wish to refer to, +you can go back to window one with C-X O to make your changes. Finally +you can do C-X 1 to make window two leave the screen. If you are +already in two window mode, C-U C-X O switches windows carrying the +buffer from the old window to the new one so that both windows show that +buffer. + +If you have the same buffer in both windows, you must beware of trying +to visit a different file in one of the windows with C-X C-V, because if +you bring a new file into this buffer, it will replace the old file in +BOTH windows. To view different files in the two windows again, you +must switch buffers in one of the windows first (with C-X B or C-X C-F, +perhaps). + +A convenient "combination" command for viewing something in the other +window is C-X 4 (^R Visit in Other Window). With this command you can +ask to see any specified buffer, file or tag in the other window. +Follow the C-X 4 with either B and a buffer name, F or C-F and a file +name, or T or "." and a tag name (*Note TAGS: (TAGS)Top.). This +switches to the other window and finds there what you specified. If you +were previously in one-window mode, two-window mode is entered. C-X 4 B +is similar to to C-X 2 C-X B. C-X 4 F is similar to C-X 2 C-X C-F. C-X +4 T is similar to C-X 2 M-Period. The difference is one of efficiency, +and also that C-X 4 works equally well if you are already using two +windows. + + +EMACS Node: Narrowing, Previous: Windows, Up: Top, Next: Pages + +Narrowing + +"Narrowing" means focusing in on some portion of the buffer, making the +rest temporarily invisible and inaccessible. + + C-X N Narrow down to between point and mark. + C-X P Narrow down to the page point is in. + C-X W Widen to view the entire buffer. + +When you have narrowed down to a part of the buffer, that part appears +to be all there is. You can't see the rest, you can't move into it +(motion commands won't go outside the visible part), you can't change it +in any way. However, it is not gone, and if you save the file all the +invisible text will be saved. In addition to sometimes making it easier +to concentrate on a single subroutine or paragraph by eliminating +clutter, narrowing can be used to restrict the range of operation of a +replace command. The word "Narrow" appears in the mode line whenever +narrowing is in effect. + +The primary narrowing command is C-X N (^R Narrow Bounds to Region). It +sets the "virtual buffer boundaries" at point and the mark, so that only +what was between them remains visible. Point and mark do not change. + +The way to undo narrowing is to widen with C-X W (^R Widen Bounds). +This makes all text in the buffer accessible again. + +Another way to narrow is to narrow to just one page, with C-X P +(^R Narrow Bounds to Page). *Note Pages: Pages. + +You can get information on what part of the buffer you are narrowed down +to using the C-X = command. *Note C-X =: Filling. + +The virtual buffer boundaries are a powerful TECO mechanism used +internally in EMACS in many ways. While only the commands described +here set them so as you can see, many others set them temporarily using +the TECO commands FS VB and FS VZ, but restore them before they are +finished. + + +EMACS Node: Pages, Previous: Narrowing, Up: Top, Next: Replace + +Commands for Manipulating Pages + +Files are often thought of as divided into "pages" by the ASCII +character formfeed ( ). For example, if a file is printed on a line +printer, each page of the file, in this sense, will start on a new page +of paper. Most editors make the division of a file into pages extremely +important. For example, they may be unable to show more than one page +of the file at any time. EMACS treats a formfeed character just like +any other character. It can be inserted with C-Q C-L (or, C-M-L), and +deleted with Rubout. Thus, you are free to paginate your file, or not. +However, since pages are often meaningful divisions of the file, +commands are provided to move over them and operate on them. + + C-M-L Insert formfeed. + C-X C-P Put point and mark around this page (or another + page). + C-X [ Move point to previous page boundary. + C-X ] Move point to next page boundary. + C-X P Narrow down to just this (or next) page. + C-X L Count the lines in this page. + M-X What Page + Print current page and line number. + +The C-X [ (^R Previous Page) command moves point to the previous page +delimiter (actually, to right after it). If point starts out right +after a page delimiter, it skips that one and stops at the previous one. +A numeric argument serves as a repeat count. The C-X ] (^R Next Page) +command moves forward past the next page delimiter. + +The command M-X What Page prints the page and line number of the cursor +in the echo area. There is a separate command to print this information +because it is likely to be slow and should not slow down anything else. +The design of TECO is such that it is not possible to know the absolute +number of the page you are in, except by scanning through the whole file +counting pages. + +The C-X C-P command (^R Mark Page) puts point at the beginning of the +current page and the mark at the end. The page delimiter at the end is +included (the mark follows it). The page delimiter at the front is +excluded (point follows it). This command can be followed by a C-W to +kill a page which is to be moved elsewhere. If it is inserted after a +page delimiter, at a place where C-X ] or C-X [ would take you, then the +page will be properly delimited before and after once again. + +A numeric argument to C-X C-P is used to specify which page to go to, +relative to the current one. Zero means the current page. One means +the next page, and -1 means the previous one. + +The command C-X P (^R Narrow Bounds to Page) narrows down to just one +page. Everything before and after becomes temporarily invisible and +inaccessible (*Note Narrowing: Narrowing.). Use C-X W (^R Widen Bounds) +to undo this. Both page terminators, the preceding one and the +following one, are excluded from the visible region. Like C-X C-P, the +C-X P command normally selects the current page, but allows you to +specify which page explicitly relative to the current one with a numeric +argument. However, when you are already narrowed down to one page, C-X +P with no argument moves you to the next page (otherwise, it would be a +useless no-op). So several C-X P's in a row get first the current page +and then successive pages. + +If you prefer to see only one page of the file at a time as a general +rule, use the PAGE library. *Note PAGE: PAGE. + +Just what delimits pages is controlled by the variable Page Delimiter, +which should contain a TECO search string (*Note TECO search strings: +TECOsearch.) which matches all page separators. Normally, it is a +string containing just . For an INFO file, it might usefully be +changed to  , which means that either a  or just a  (either +of the two strings that separate INFO nodes) should be a page separator. +Then each node counts as a page. In any case, page separators are +recognized as such only at the beginning of a line. The paragraph +commands consider each page boundary a paragraph boundary as well. + +The C-X L command (^R Count Lines Page) is good for deciding where to +break a page in two. It prints in the echo area the total number of +lines in the current page, and then divides it up into those preceding +the current line and those following, as in + + Page has 96 lines (72+25) + +Notice that the sum is off by one; this is correct if point is not at +the front of a line. + + +EMACS Node: PAGE, Previous: Pages, Up: Pages + +Editing Only One Page at a Time + +The PAGE library allows you to edit only within a single page at a time, +with special commands to move between pages, and split and join pages. +It contrives to show the number of the page you are looking at in the +mode line. You can also ask to see a "directory" of the pages in the +file, or to insert it into the file. This is an extension of and +replacement for the facility provided by the C-X P command in standard +EMACS. It is an optional library because we do not think it is +necessarily an improvement. + +The commands in the PAGE library supplant and redefine commands in +standard EMACS. Therefore, you cannot use them unless you give the +command M-X Load LibraryPAGE explicitly. *Note Libraries: +Libraries. + + C-X ] Move to next page. + C-X [ Move to previous page. + C-X C-P Move to page by absolute number. + C-X P Split this page at point. + C-X J Join this page to the next or previous one. + C-X W See the whole file again. + +The most fundamental thing to do with PAGE is to go to a specific page. +This can be done by giving the page number as an argument to C-X C-P +(^R Goto Page). If you give a number too big, the last page in the file +is selected. + +For convenience, C-X C-P with no argument when you are looking at the +whole file selects the page containing point. When you are looking at +only one page, C-X C-P with no argument goes to the next page and with a +negative argument goes to the previous page. + +However, the main commands for moving forward or backward by pages are +C-X [ and C-X ] (^R Goto Previous Page and ^R Goto Next Page). These +take a numeric argument (either sign) and move that many pages. + +To go back to viewing the whole file instead of just one page, you can +use the C-X W (^R PAGE Widen Bounds) command. These are the same +characters that you would use in standard EMACS, but they run a +different function that knows to remove the page number from the mode +line. + +The C-S (^R Incremental Search) and C-R (^R Reverse Search) commands are +redefined to widen bounds first and narrow them again afterwards. So +you can search through the whole file, but afterward see only the page +in which the search ended. In fact, PAGE goes through some trouble to +work with whatever search functions you prefer to use, and find them +wherever you put them. + +To split an existing page, you could insert a , but unless you do this +while viewing the whole file, PAGE might get confused. The clean way is +to use C-X P (^R Insert Pagemark) which inserts the page mark, and +narrows down to the second of the two pages formed from the old page. +The clean way to get rid of a page mark is to use C-X J (^R Join Next +Page). It gets rid of the page mark after the current page; or, with a +negative argument, gets rid of the page mark before this page. + +A page mark is defined as . If you set the variable PAGE Flush +CRLF to 1, a page mark is , which has the effect of making +the CRLF at the beginning of each page invisible. This may be desirable +for EMACS library source files. You can also specify some other string +in place of by setting the variable Page Delimiter. If Page +Delimiter specifies multiple alternatives, separated by , PAGE always +inserts the first of them, but recognizes them all. + +To see a list of all the pages in the file, each one represented by its +first nonempty line, use M-X View Page Directory. It prints out the +first non-blank line on each page, preceded by its page number. M-X +Insert Page Directory inserts the same directory into the buffer at +point. If you give it an argument, it tries to make the whole thing +into a comment by putting the Comment Start string at the front of each +line and the Comment End string at the end. + +If the variable Page Setup Hook exists, PAGE will execute its value as +the function for placing PAGE's functions on keys. This is done instead +of the normal assignments to C-X [, C-X ], C-X C-P, C-X P, and C-X J. + + +EMACS Node: Replace, Previous: Pages, Up: Top, Next: TECOsearch + +Replacement Commands + +Global search-and-replace operations are not needed as often in EMACS as +they are in other editors, but they are available. In addition to the +simple Replace operation which is like that found in most editors, there +is a Query Replace operation which asks you, for each occurrence of the +pattern, whether to replace it. + +To replace every instance of FOO after point with BAR, you can do + + M-X ReplaceFOOBAR + +Replacement occurs only after point, so if you want to cover the whole +buffer you must go to the beginning first. Replacement continues to the +end of the buffer, but you can restrict it by narrowing. *Note +Narrowing: Narrowing. + +Unless the variable Case Replace is zero, Replace tries to preserve +case; give both FOO and BAR in lower case, and if a particular FOO is +found with a capital initial or all capitalized, the BAR which replaces +it will be given the same case pattern. Thus, + + M-X Replacefoobar + +would replace "foo" with "bar", "Foo" with "Bar" and "FOO" with "BAR". +If Case Replace is zero, the replacement string is inserted with the +case you used when you typed it. If Case Search is zero, the string to +be replaced is found only when it has the same case as what you typed. + +If you give Replace (or Query Replace) an argument, then it replaces +only occurrences of FOO delimited by break characters (or an end of the +buffer). So you can replace only FOO the word, and not FOO when it is +part of FOOBAR. + +The string FOO to be replaced is actually a TECO search string, a type +of pattern, in which the characters , , , , , and  are +special. *Note TECO search strings: TECOSearch. + +Query Replace + +If you want to change only some of the occurrences of FOO, not all, then +you cannot use an ordinary Replace. Instead, use M-X Query +ReplaceFOOBAR. This displays each occurrence of FOO and waits for +you to say whether to replace it with a BAR. The things you can type +when you are shown an occurrence of FOO are: + + Space to replace the FOO (preserving case, just like plain + Replace, unless Case Replace is zero). + Rubout to skip to the next FOO without replacing this one. + Comma to replace this FOO and display the result. You are + then asked for another input character, except that + since the replacement has already been made, Rubout + and Space are equivalent. + Altmode to exit without doing any more replacements. + Period to replace this FOO and then exit. + ! to replace all remaining FOO's without asking. + ^ to go back to the previous FOO (or, where it was), + in case you have made a mistake. This works by + jumping to the mark (Query Replace sets the mark + each time it finds a FOO). + C-R to enter a recursive editing level, in case the FOO + needs to be edited rather than just replaced with a + BAR. When you are done, exit the recursive editing + level with C-M-C and the next FOO will be displayed. + C-W to delete the FOO, and then start editing the + buffer. When you are finished editing whatever is + to replace the FOO, exit the recursive editing level + with C-M-C and the next FOO will be displayed. + +If you type any other character, the Query Replace is exited, and the +character executed as a command. To restart the Query Replace, use C-X +Altmode which is a command to re-execute the previous minibuffer command +or extended command. *Note C-X Altmode: M-X. + +Running Query Replace with the Minibuffer + +Meta-% gives you a minibuffer pre-initialized with "MM Query Replace". +*Note Minibuffer: Minibuffer. This is the easiest way to invoke Query +Replace. It also allows you to get Returns and Altmodes into the +arguments. + +With the minibuffer, Query Replace can be given a precomma argument, +which says that the second string argument is actually a TECO program to +be executed to perform the replacement, rather than simply a string to +replace with. + +When you invoke Query Replace from the minibuffer, the character  +becomes special (because it is special in TECO programs). In order to +get a  into the search string or the replacement string, you must use +two of them. You can also use a  to quote an Altmode. In the +minibuffer, Return has no syntactic significance, so there is no need +for a way to quote it. However, in order to insert any control +characters into the arguments, you need to quote them again with C-Q. +So, to get   into the search string so as to search for a , you +have to type C-Q C-Q C-Q C-X. + +Other Search-and-loop Functions + +Here are some other functions related to replacement. Their arguments +are TECO search strings (*Note TECO search strings: TECOsearch.). They +all operate from point to the end of the buffer (or where narrowing +stops them). + +M-X List Matching LinesFOO + prints each line containing FOO. With an argument, it + prints that many lines before and after each occurrence. + +M-X Count OccurrencesFOO + prints the number of occurrences of FOO after point. + +M-X Delete Non-Matching LinesFOO + kills all lines after point that don't contain FOO. + +M-X Delete Matching LinesFOO + kills all lines after point that contain FOO. + + + +EMACS Node: TECOsearch, Previous: Replace, Up: Top, Next: MajorModes + +TECO Search Strings + +The first string argument to Replace and Query Replace is actually a +TECO search string. This means that the characters , , , , and + have special meanings.  matches any character.  matches any +"delimiter" character (anything which the word commands consider not +part of a word, according to the syntax table. *Note Syntax: Syntax.). + negates what follows, so that  A matches anything but A, and   +matches any non-delimiter.  means "or", so that XYXY  ZZZ matches +EITHER XYXY or ZZZ.  can be used more than once in a pattern.  +quotes the following character, in case you want to search for one of +the special control characters. However, you can't quote an Altmode or +a Return in this way because its specialness is at an earlier stage of +processing. + +Some variables are supposed to have TECO search strings as their values. +For example, Page Delimiter is supposed to be a search string to match +anything which should start a page. This is so that you can use  to +match several alternatives. In the values of such variables, , , +, ,  and  are special, but Altmode is not.  through  are +quoted with a , and  is quoted with another . + +The function Apropos (or, Help A) and all similar functions actually +take TECO search strings as arguments, so you can search for more than +one substring at a time. This is useful because doing Apropos on +wordpara is not really slower than searching for just "word" or just +"para". + + +EMACS Node: MajorModes, Previous: TECOSearch, Up: Top, Next: Programs + +Major Modes + +EMACS has many different "major modes", each of which customizes EMACS +for editing text of a particular sort. The major modes are mutually +exclusive, and one major mode is current at any time. When at top +level, EMACS always says in the mode line which major mode you are in. + +When EMACS starts up, it is in what is called "Fundamental mode", which +means that the character commands are defined so as to be convenient in +general. More precisely, in Fundamental mode every EMACS option is set +in its default state. For editing any specific type of text, such as +Lisp code or English text, you should switch to the appropriate major +mode. This tells EMACS to change the meanings of a few commands to +become more specifically adapted to the language being edited. Most +commands remain unchanged; the ones which usually change are Tab, +Rubout, and Linefeed. In addition, the commands which handle comments +use the mode to determine how comments are to be delimited. + +Selecting a new major mode is done with an M-X command. Each major mode +is the name of the function to select that mode. Thus, you can enter +Lisp mode by executing M-X Lisp (short for M-X Lisp Mode). You can +specify which major mode should be used for editing a certain file by +putting -*--*- somewhere in the first nonblank line of the +file. For example, this file has -*-Text-*-. In a program, this string +is surrounded by appropriate other characters to hide it from the +compiler in a comment. + +Many major modes redefine the syntactical properties of characters +appearing in the buffer. *Note Syntax: Syntax. + +Most programming language major modes specify that only blank lines +separate paragraphs. This is so that the paragraph commands remain +useful. They also cause Auto Fill mode to use the definition of Tab to +indent the new lines it creates. This is because most lines in a +program are usually indented. + +To find out what a particular major mode redefines, use the command M-X +List Redefinitions while that mode is in effect. This command describes +all the local variables and commands of the selected buffer, in a form +designed to be easy to understand. + + +* Menu: + + Here are pointers to descriptions of the several major modes. + +* Text:: Text mode is for editing English text. +* Lisp:: Lisp mode is for Lisp. +* Muddle: Lisp, Muddle is like Lisp. +* MIDAS:: MIDAS mode is good for assembler code. +* PL1: (EPL1), PL1 mode is the archetype from which modes + for many block structured languages are + defined. +* FORTRAN: (EFORTRAN), FORTRAN mode. +* TEX: (ETEX), TEX mode. TEX is a text justifier. +* CLU: (ECLU), CLU mode. +* PASCAL: (EPASC), PASCAL, BCPL and BLISS also have modes. +* Other: Other Langs, Other modes without documentation. + + + +EMACS Node: Programs, Previous: MajorModes, Up: Top, Next: MinorModes + +Commands for Editing Programs + +Special features for editing programs include automatic indentation, +comment alignment, parenthesis matching, and the ability to move over +and kill balanced expressions. Many of these features are parameterized +so that they can work for any programming language. For each language +there is usually a separate major mode which sets all parameters in the +way which is best for that language. These modes sometimes offer +special facilities individually as well. + + +* Menu: + +* Compile:: M-X Compile for compiling your program. +* Indenting:: Automatic indentation of code. +* Matching:: Automatic display of matching parentheses. +* Comments:: Inserting, deleting, aligning comments. +* Lisp:: Lisp mode. +* Lists:: Moving over and killing Lisp objects. +* Defuns:: Moving over and marking Lisp functions. +* Grinding:: Grinding Lisp code. +* MIDAS:: Editing assembler-language code. +* Other Langs:: Modes for other languages. + + +*Note Words: Words. Moving over words is useful for editing programs as +well as text. + +*Note Paragraphs: Sentences. Most programming language major modes +define paragraphs to be separated only by blank lines and page +boundaries. This makes the paragraph commands useful for editing +programs. + +*Note Tags: (TAGS)Top. The TAGS package can remember all the labels or +functions in a multi-file program and find any one of them quickly. + + +EMACS Node: Compile, Previous: Programs, Up: Programs, Next: Indenting + +Compiling Your Program + +The command M-X Compile is used to compile the visited file. It +knows how to compile it based on the major mode; for example, in TECO +mode, it invokes the generator for EMACS libraries. Usually it assumes +that the major mode name is the name of the compiler or assembler to +use. + +The first thing M-X Compile does is offer to save each buffer. This is +because it is likely that other buffers contain parts of the same +program you are about to compile. + +Then M-X Compile invokes the appropriate compiler and passes it the name +of the visited file as the source file. If you give a string argument +to M-X Compile, that is passed to the compiler also. This can be used +to specify switches or the name of an output file. + +The major mode or the file's local modes list can specify a different +compiler by setting the variable Compiler Filename locally. They can +specify switches to be used by setting the variable Compiler Switches +(the default is to use no switches except those specified by the user in +the string argument to M-X Compile). + +After compilation, you must type P to resume EMACS. When EMACS starts +up again, it executes the value of the variable After Compilation Hook, +if that is nonzero. This can be used for such tasks as reading the +compiler's file of error messages into EMACS. + +The major mode or the file's local modes list can completely override +the normal processing of M-X Compile by giving a nonzero local value to +the variable Compile Command. This should be a TECO expression which +takes complete responsibility for the compilation. It can find the +filename to use in q-register 1. It MUST use  to exit. All the other +hooks described above are ignored. This is often used when several +input files must be compiled together in order to compile any of them. +See the file AI:EMACS1;CCL > for an example of doing this for an EMACS +library. + + +EMACS Node: Indenting, Previous: Compile, Up: Programs, Next: Matching + +Indentation Commands for Code + + Tab Indents current line. + Linefeed Equivalent to Return followed by Tab. + M-^ Joins two lines, leaving one space between if + appropriate. + M-\ Deletes all spaces and tabs around point. + M-M Moves to the first nonblank character on the line. + +Most programming languages have some indentation convention. For Lisp +code, lines are indented according to their nesting in parentheses. For +assembler code, almost all lines start with a single tab, but some have +one or more spaces as well. Indenting TECO code is an art rather than a +science, but it is often useful to indent a line under the previous one. + +Whatever the language, to indent a line, use the Tab command. Each +major mode defines this command to perform the sort of indentation +appropriate for the particular language. In Lisp mode, Tab aligns the +line according to its depth in parentheses. No matter where in the line +you are when you type Tab, it aligns the line as a whole. In MIDAS +mode, Tab inserts a tab, that being the standard indentation for +assembly code. In TECO mode, Tab realigns the current line to match a +previous line. PL1 mode (*Note PL1: (EPL1).) knows in great detail +about the keywords of the language so as to indent lines according to +the nesting structure. + +The command Linefeed (^R Indent New Line) does a Return and then does a +Tab on the next line. Thus, Linefeed at the end of the line makes a +following blank line and supplies it with the usual amount of +indentation. Linefeed in the middle of a line breaks the line and +supplies the usual indentation in front of the new line. + +The inverse of Linefeed is Meta-^ or C-M-^ (^R Delete Indentation). +This command deletes the indentation at the front of the current line, +and the line separator as well. They are replaced by a single space, or +by no space if before a ")" or after a "(", or at the beginning of a +line. To delete just the indentation of a line, go to the beginning of +the line and use Meta-\ (^R Delete Horizontal Space), which deletes all +spaces and tabs around the cursor. + +To insert an indented line before the current one, do C-A, C-O, and then +Tab. To make an indented line after the current one, use C-E Linefeed. + +To move over the indentation on a line, use Meta-M or C-M-M (^R Back to +Indentation). These commands move the cursor forward or back to the +first nonblank character on the line. + + +EMACS Node: Matching, Previous: Indenting, Up: Programs, Next: Comments + +Automatic Display Of Matching Parentheses + +The EMACS parenthesis-matching feature is designed to show automatically +how parentheses balance in text as it is typed in. When this feature is +enabled, after a close parenthesis or other close bracket character is +inserted the cursor automatically moves for an instant to the open which +balances the newly inserted character. The cursor stays at the open +parenthesis for a second before returning home, unless you type another +command before the second is up. + +It is worth emphasizing that the location of point, the place where your +type-in will be inserted, is not affected by the parenthesis matching +feature. It stays after the close parenthesis, where it ought to be. +Only the cursor on the screen moves away and back. You can type ahead +freely as if the parenthesis display feature did not exist. In fact, if +you type fast enough, you won't see the cursor move. You must pause +after typing a close parenthesis to let the cursor move to the open +parenthesis. + +The variable Display Matching Paren controls parenthesis display. If it +is zero, the feature is disabled. If the variable is nonzero, then its +absolute value is the number of seconds for the cursor to stay at the +open parenthesis before coming back to its real location. The sign of +the variable is also significant: if it is negative, then the open +parenthesis is shown only if it is already on the screen. If the +variable is positive, then EMACS will actually shift text on the screen +to show the open parenthesis. The default setting of the variable is +-1. + +An additional parameter is whether EMACS should warn you by ringing the +bell if you type an unmatched close parenthesis. The default is to warn +you if you are editing a language in which parentheses are paramount, +such as Lisp, but not to do so for languages in which parentheses are +not so crucial. This is controlled by the variable Permit Unmatched +Paren. When it is 1, you are never warned (they are always +"permitted"). When it is 0, you are warned, regardless of major mode. +When it is -1, you are warned only in Lisp mode and similar modes (this +is the default). Note that these modes distinguish themselves by +setting the variable locally to 0 if it was -1. Unmatched parens are +always "permitted" in that EMACS will never refuse to insert them. + +While this feature was intended primarily for Lisp, it can be used just +as well for any other language, and it is not dependent on what major +mode you are in. It is expected that you wouldn't want it in Text mode, +so Text mode sets the variable Display Matching Paren locally to zero. +If you do want the feature in Text mode, you can create a Text Mode Hook +variable which sets the variable back to -1. *Note Hooks: (CONV)Hooks, +for more info on Text Mode Hook. The way to control which characters +trigger this feature is with the syntax table. Any character whose Lisp +syntax is ")" causes the matching character with syntax "(" to be shown. +Most major modes automatically set up the syntax table (*Note Syntax: +Syntax.). + +The syntax table also controls what is done with the case of +"mismatched" parens, as in "[ )". The third slot in a close parenthesis +character's syntax table entry should be the proper matching open +parenthesis character, if you want this feature turned on. If that slot +contains a space instead, then any open parenthesis character is +considered a legitimate match. If a close parenthesis is mismatched, it +is inserted as always, but it rings the bell. + +The implementation of this feature uses the TECO flag FS ^R PAREN. +*Note FS Flags: FS Flags. + + +EMACS Node: Comments, Previous: Matching, Up: Programs, Next: Lisp + +Manipulating Comments + +The comment commands insert, kill and align comments. There are also +commands for moving through existing code and inserting comments. + + M-; Insert or align comment. + C-; The same. + C-M-; Kill comment. + Return Move past comment terminator and onto new line. + C-X ; Set comment column. + M-N Move to Next line and insert comment. + M-P Move to Previous line and insert comment. + M-J Continue a comment on a new line. + M-Linefeed The same. + +The command that creates a comment is Meta-; or Control-; (^R Indent for +Comment). If there is no comment already on the line, a new comment is +created, aligned at a specific column called the "comment column". The +comment is created by inserting whatever string EMACS thinks should +start comments in the current major mode. Point is left after the +comment-starting string. If the text of the line goes past the comment +column, then the indentation is done to a suitable boundary (usually, a +multiple of 8). + +Meta-; can also be used to align an existing comment. If a line already +contains the string that starts comments, then M-; just moves point +after it and re-indents it to the right column. Exception: comments +starting in column 0 are not moved. + +Even when an existing comment is properly aligned, M-; is still useful +for moving directly to the start of the comment. + +Some languages require an explicit comment terminator, which is not +simply the end of the line. Although the language may then allow +comments in the middle of the line, the EMACS comment commands assume +that a comment is the last thing on the line. When there is a comment +terminator, M-; inserts the terminator as well as the starter, and +leaves point between them, so that you are ready to insert the text of +the comment. When you are done, the Return command given immediately +before the comment terminator acts as if it were at the end of the line +already: it moves down to or creates a following blank line. It does +not break the existing line before the comment terminator as you would +expect. + +C-M-; (^R Kill Comment) kills the comment on the current line, if there +is one. The indentation before the start of the comment is killed as +well. If there does not appear to be a comment in the line, nothing is +done. To reinsert the comment on another line, move to the end of that +line, do C-Y, and then do M-; to realign it. + +Multiple Lines of Comments + +If you wish to align a large number of comments, you can give Meta-; an +argument and it indents what comments exist on that many lines, creating +none. Point is left after the last line processed (unlike the +no-argument case). + +When adding comments to a long stretch of existing code, the commands +M-N (^R Down Comment Line) and M-P (^R Up Comment Line) may be useful. +They are like C-N and C-P except that they do a C-; automatically on +each line as you move to it, and delete any empty comment from the line +as you leave it. Thus, you can use M-N to move down through the code, +putting text into the comments when you want to, and allowing the +comments that you don't fill in to be removed because they remained +empty. + +If you are typing a comment and find that you wish to continue it on +another line, you can use the command Meta-J or Meta-Linefeed (^R Indent +New Comment Line), which terminates the comment you are typing, creates +or gobbles a new blank line, and begins a new comment indented under the +old one. When Auto Fill mode is on, going past the fill column while +typing a comment causes the comment to be continued in just this +fashion. Note that if the next line is not blank, a blank line is +created, and the continuation goes on that line. By comparison, M-N +would create a continuation comment on the next existing line of code. + +Double and Triple Semicolons in Lisp + +In Lisp code there are conventions for comments which start with more +than one semicolon. Comments which start with two semicolons are +indented as if they were lines of code, instead of at the comment +column. Comments which start with three semicolons are supposed to +start at the left margin. EMACS understands these conventions by +indenting a double-semicolon comment using Tab, and by not changing the +indentation of a triple-semicolon comment at all. (Actually, this rule +applies whenever the comment starter is a single character and is +duplicated). Note that the :@ program considers a four-semicolon +comment a subtitle in Lisp code. + +Options Controlling Comments + +The comment column is stored in the variable Comment Column. You can +set it to a number explicitly. Alternatively, the command C-X ; (^R Set +Comment Column) sets the comment column to the column point is at. C-U +C-X ; sets the comment column to match the last comment before point in +the buffer, and then does a Meta-; to align the current line's comment +under the previous one. + +Many major modes supply default local values for the comment column. In +addition, C-X ; automatically makes the variable Comment Column local. +Otherwise, if you change the variable itself, it changes globally (for +all buffers) unless it has been made local in the selected one. *Note +Locals: Locals. + +The string recognized as the start of a comment is stored in the +variable Comment Start, while the string used to start a new comment is +kept in Comment Begin (if that is zero, Comment Start is used for new +comments). This makes it possible for you to have any ";" recognized as +starting a comment but have new comments begin with ";; ** ". + +The string used to end a comment is kept in the variable Comment End. +In many languages no comment end is needed as the comment extends to the +end of the line. Then, this variable is a null string. + +If Comment Multi Line is nonzero, then Meta-Linefeed within a comment +does not close the old comment and start a new comment on the new line. +Instead it allows the original comment to extend through the new line. +This is legitimate if the language has explicit comment terminators. +Then it's a matter of taste. + + +EMACS Node: Lisp, Previous: Comments, Up: Programs, Next: Lists + +Lisp Mode and Muddle Mode + +Lisp's simple syntax makes it much easier for an editor to understand; +as a result, EMACS can do more for Lisp, and with less work, than for +any other language. + +Lisp programs should be edited in Lisp mode. In this mode, Tab is +defined to indent the current line according to the conventions of Lisp +programming style. It does not matter where in the line Tab is used; +the effect on the line is the same. The function which does the work is +called ^R Indent for Lisp. Linefeed, as usual, does a Return and a Tab, +so it moves to the next line and indents it. + +As in most modes where indentation is likely to vary from line to line, +Rubout is redefined to treat a tab as if it were the equivalent number +of space (^R Backward Delete Hacking Tabs). This makes it possible to +rub out indentation one position at a time without worrying whether it +is made up of spaces or tabs. Control-Rubout does the ordinary type of +rubbing out which rubs out a whole tab at once. + +Paragraphs are defined to start only with blank lines so that the +paragraph commands can be useful. Auto Fill indents the new lines which +it creates. Comments start with ";". If Atom Word mode is in effect, +them in Lisp mode the word-motion commands regard each Lisp atom as one +word. + +The LEDIT library allows EMACS and Lisp to communicate, telling Lisp the +new definitions of functions which you edit in EMACS. *Note LEDIT: +(LEDIT). + +The language Muddle is a variant form of Lisp which shares the concept +of using parentheses (of various sorts) as the main syntactical +construct. It can be edited using Muddle mode, which is almost the same +as Lisp mode and provides the same features, differing only in the +syntax table used. + + +EMACS Node: Lists, Previous: Lisp, Up: Programs, Next: Defuns + +Moving Over and Killing Lists and S-expressions + + C-M-F Move Forward over s-expression. + C-M-B Move Backward. + C-M-K Kill s-expression forward. + C-M-Rubout Kill s-expression backward. + C-M-U Move Up and backward in list structure. + C-M-( The same. + C-M-) Move up and forward in list structure. + C-M-D Move Down and forward in list structure. + C-M-N Move forward over a list. + C-M-P Move backward over a list. + C-M-T Transpose s-expressions. + C-M-@ Put mark after s-expression. + M-( Put parentheses around next s-expression(s). + M-) Move past next close parenthesis and re-indent. + + +By convention, EMACS commands that deal with balanced parentheses are +usually Control-Meta- characters. They tend to be analogous in function +to their Control- and Meta- equivalents. These commands are usually +thought of as pertaining to Lisp, but can be useful with any language in +which some sort of parentheses exist (including English). + +To move forward over an s-expression, use C-M-F (^R Forward Sexp). If +the first significant character after point is an "(", C-M-F moves past +the matching ")". If the first character is a ")", C-M-F just moves +past it. If the character begins an atom, C-M-F moves to the end of the +atom. C-M-F with an argument repeats that operation the specified +number of times; with a negative argument, it moves backward instead. + +The command C-M-B (^R Backward Sexp) moves backward over an +s-expression; it is like C-M-F with the argument negated. If there are +"'"-like characters in front of the s-expression moved over, they are +moved over as well. Thus, with point after " 'FOO ", C-M-B leaves point +before the "'", not before the "F". + +These two commands (and most of the commands in this section) do not +know how to deal with the presence of comments. Although that would be +easy to fix for forward motion, for backward motion the syntax of Lisp +makes it nearly impossible. Comments by themselves can be dealt with, +but handling both comments and strings is impossible with local backward +parsing. In a line + + ((FOO ; " BAR + +are the open parentheses inside a string? So C-M-B cannot handle +comments, and C-M-F does not either for simplicity's sake. + +For this reason, two other commands which move over lists instead of +s-expressions are often useful. They are C-M-N (^R Forward List) and +C-M-P (^R Backward List). They act like C-M-F and C-M-B except that +they don't stop on atoms; after moving over an atom, they move over the +next expression, stopping after moving over a list. With this command, +you can avoid stopping after all of the words in a comment. + +Killing an s-expression at a time can be done with C-M-K and C-M-Rubout +(^R Forward Kill Sexp and ^R Backward Kill Sexp). C-M-K kills the +characters that C-M-F would move over, and C-M-Rubout kills what C-M-B +would move over. + +C-M-F and C-M-B stay at the same level in parentheses, when that's +possible. To move UP one (or n) levels, use C-M-( or C-M-) (^R Backward +Up List and ^R Forward Up List). C-M-( moves backward up past one +containing "(". C-M-) moves forward up past one containing ")". Given +a positive argument, these commands move up the specified number of +levels of parentheses. C-M-U is another name for C-M-(, which is easier +to type, especially on non-Meta keyboards. If you use that name, it is +useful to know that a negative argument makes the command move up +forwards, like C-M-). + +To move DOWN in list structure, use C-M-D (^R Down List). It is nearly +the same as searching for a "(". + +A somewhat random-sounding command which is nevertheless easy to use is +C-M-T (^R Transpose Sexps), which drags the previous s-expression across +the next one. An argument serves as a repeat count, and a negative +argument drags backwards (thus canceling out the effect of C-M-T with a +positive argument). An argument of zero, rather than doing nothing, +transposes the s-expressions at the point and the mark. + +To make the region be the next s-expression in the buffer, use or +C-M-@ (^R Mark Sexp) which sets mark at the same place that C-M-F would +move to. C-M-@ takes arguments like C-M-F. In particular, a negative +argument is useful for putting the mark at the beginning of the previous +s-expression. + +The commands M-( ("^R Insert ()") and M-) ("^R Move Over )") are +designed for a style of editing which keeps parentheses balanced at all +times. M-( inserts a pair of parentheses, either together as in "()", +or, if given an argument, around the next several s-expressions, and +leaves point after the open parenthesis. Instead of typing "(FOO)", you +can type M-( FOO, which has the same effect except for leaving the +cursor before the close parenthesis. Then you type M-), which moves +past the close parenthesis, deleting any indentation preceding it (in +this example there is none), and indenting with Linefeed after it. + +The library LSPUTL contains two other list commands. Find Pat searches +for lists which contain several strings. ^R Extract Sublist replaces a +list with one of its sublists. *Note Libraries: Libraries. + +M-X Find Pat searches for a list +which contains at a depth of lists down, and +contains and at any level. There can be any number +of such additional strings to search for; there can be none of them. + +^R Extract Sublist is meant to be connected to a character. Given an +argument of , it replaces the list levels up from point +with its sublist which starts after point. + +The list commands' understanding of syntax is completely controlled by +the syntax table. Any character can, for example, be declared to act +like an open parenthesis. *Note Syntax: Syntax. + + +EMACS Node: Defuns, Previous: Lists, Up: Programs, Next: Grinding + +Commands for Manipulating Defuns + + C-M-[, C-M-A Move to beginning of defun. + C-M-], C-M-E Move to end of defun. + C-M-H Put region around wHole defun. + +In EMACS, an expression at the top level in the buffer is called a +defun, regardless of what function is actually called by the expression, +because such expressions usually call defun. There are EMACS commands +to move to the beginning or end of the current defun: C-M-[ +(^R Beginning of Defun) moves to the beginning, and C-M-] (^R End of +Defun) moves to the end. If you wish to operate on the current defun, +use C-M-H (^R Mark Defun) which puts point at the beginning and mark at +the end of the current or next defun. Alternate names for these two +commands are C-M-A for C-M-[ and C-M-E for C-M-]. The alternate names +are easier to type on many non-Meta keyboards. + + +EMACS Node: Grinding, Previous: Defuns, Up: Programs, Next: MIDAS + +Lisp Grinding + +The best way to keep Lisp code properly indented ("ground") is to use +EMACS to re-indent it when it is changed. EMACS has commands to indent +properly either a single line, a specified number of lines, or all of +the lines inside a single s-expression. + + Tab In Lisp mode, re-indents line according to + parenthesis depth. + Linefeed Equivalent to Return followed by Tab. + M-^ Join two lines, leaving one space between them if + appropriate. + C-M-Q Re-indent all the lines within one list. + C-M-G Grind a list, moving code between lines. + +The basic indentation function is ^R Indent for Lisp, which gives the +current line the correct indentation as determined from the previous +lines' indentation and parenthesis structure. This function is normally +found on C-M-Tab, but when in Lisp mode it is placed on Tab as well (Use +Meta-Tab or C-Q Tab to insert a tab). If executed at the beginning of a +line, it leaves point after the indentation; when given inside the text +on the line, it leaves point fixed with respect to the characters around +it. + +When entering a large amount of new code, use Linefeed (^R Indent New +Line), which is equivalent to a Return followed by a Tab. In Lisp mode, +a Linefeed creates or moves down onto a blank line, and then gives it +the appropriate indentation. + +To join two lines together, use the Meta-^ or Control-Meta-^ command +(^R Delete Indentation), which is approximately the opposite of +Linefeed. It deletes any spaces and tabs at the front of the current +line, and then deletes the line separator before the line. A single +space is then inserted, if EMACS thinks that one is needed there. +Spaces are not needed before a close parenthesis, or after an open +parenthesis. + +If you are dissatisfied about where Tab indents the second and later +lines of an s-expression, you can override it. If you alter the +indentation of one of the lines yourself, then Tab will indent +successive lines of the same list to be underneath it. This is the +right thing for functions which Tab indents unaesthetically. + +When you wish to re-indent code which has been altered or moved to a +different level in the list structure, you have several commands +available. You can re-indent a specific number of lines by giving the +ordinary indent command (Tab, in Lisp mode) an argument. This indents +as many lines as you say and moves to the line following them. Thus, if +you underestimate, you can repeat the process later. + +You can re-indent the contents of a single s-expression by positioning +point before the beginning of it and typing Control-Meta-Q (^R Indent +Sexp). The line the s-expression starts on is not re-indented; thus, +only the relative indentation with in the s-expression, and not its +position, is changed. To correct the position as well, type a Tab +before the C-M-Q. + +Another way to specify the range to be re-indented is with point and +mark. The command C-M-\ (^R Indent Region) applies Tab to every line +whose first character is between point and mark. In Lisp mode, this +does a Lisp indent. + +A more powerful grind command which can move text between lines is C-M-G +(^R Format Code). You might or might not like it. It knows in +different ways about Lisp code and Macsyma code. + +Customizing Lisp Indentation + +The indentation pattern for a Lisp expression can depend on the function +called by the expression. For each Lisp function, you can choose among +several predefined patterns of indentation, or define an arbitrary one +with a TECO program. + +The standard pattern of indentation is as follows: the second line of +the expression is indented under the first argument, if that is on the +same line as the beginning of the expression; otherwise, the second line +is indented one space more than the entire expression. Each following +line is indented under the previous line whose nesting depth is the +same. + +Another indentation pattern is used for functions whose names start with +"def". The second line of the expression is indented two spaces more +than the entire expression. The variable Lisp Special Indent Offset +(default 2) controls the increment in depth. Each following line +indents under the previous one. Again, lines starting at lower depths +do not count. Setting the variable Lisp Indent DEFAnything to zero +turns this feature off. Then the standard pattern applies to +def- functions by default. + +The indentation pattern for expressions that call the function FOO is +controlled specifically by the variable Lisp FOO Indent. If this +variable does not exist, the standard pattern or the def- pattern is +used. If the variable does exist, its value should be one of these: + + -3 selects the standard or def- indentation pattern, as if + the variable did not exist. + -2 selects the standard indentation pattern. The + def- pattern is not used, even if the function name + starts with "def". + -1 selects the def- indentation pattern, independent of the + function name and the setting of Lisp Indent + DEFAnything. + 0 or more selects special form with body indentation. The value + of the variable is the number of special arguments that + precede the body; thus, LET and LAMBDA have one + distinguished argument before the body (the list of + bound variables), PROGN has none, and DO has two. The + distinguished expressions at the beginning are indented + using the standard pattern, but the first expression of + the body, if it should occur at the beginning of a line, + is indented two spaces deeper than the entire + expression. Following lines indent each under the + previous one as usual. The variable Lisp Special Indent + Offset (default 2) controls the increment in depth. + a string should be a TECO expression which implements an + indentation pattern. Initially, Lisp PROG Indent is + defined as a string (the definition of & Standard Lisp + PROG Indent) which detects tags and indents them + specially. + +The variable Lisp Indent Offset, if nonzero, selects a different +indentation pattern as the standard one. It indents the second line of +each expression that many spaces deeper than the enclosing expression. + +Implementing and selecting among the above indentation patterns is the +responsibility of the definition of the variable Lisp Indentation Hook. +This variable must exist and its value must be a TECO program. By +default its value is the definition of & Standard Lisp Indentation Hook. + +Whatever its value, the hook is called with two arguments, which are the +position in the buffer of the most recent unclosed "(" and the buffer +position of the beginning of the line to be indented. The buffer +position of the cursor at the time the tab was typed is stored as an +offset from Z in qZ, so Z-qZ is that buffer position. The hook should +not modify the buffer. If it returns 0 or no value, the caller will use +the horizontal cursor position of point as the column to indent to. +Hence, to indent under the "O" in PROG, it is sufficient to jump to that +character in the buffer and return. Alternatively, the hook can simply +return the desired indentation column number as a value. + +The hook should return a nonzero precomma value if following lines of +the same expression should be indented individually. If it does not +return a nonzero precomma value, the caller may remember the indentation +of this line and indent following lines the same way. + +If Lisp FOO Indent has a TECO expression as its value, the same +interface conventions apply to it. + +Different Lisp-like languages can select an entirely different set of +indentation patterns by changing the value of the variable Lisp Indent +Language. Normally the value of this variable is the string "Lisp". +All the variables listed above with names beginning with "Lisp" actually +should have names beginning with the Lisp Indent Language. Thus, if +Lisp Indent Language is changed to "Muddle", then the indentation +commands will look for variables Muddle Indent Offset, Muddle +Indentation Hook, Muddle PROG Indent, etc. + + +EMACS Node: MIDAS, Previous: Grinding, Up: Programs, Next: Other Langs + +Editing Assembly-Language Programs + +MIDAS mode is designed for editing programs written in MIDAS or other +PDP-10 or PDP-11 assemblers. In MIDAS mode, comments start with ";", +and "<" and ">" have the syntax of parentheses. In addition, there are +five special commands which understand the syntax of instructions and +labels. These commands are: + + C-M-N Go to Next label. + C-M-P Go to Previous label. + C-M-A Go to Accumulator field of instruction. + C-M-E Go to Effective Address field. + C-M-D Kill next word and its Delimiting character. + +Two other commands with slightly different uses are + + M-[ Move up to previous blank line. + M-] Move down to next blank line. + +Any line which is not indented and is not just a comment is taken to +contain a label. The label is everything up to the first whitespace (or +the end of the line). C-M-N (^R Go to Next Label) and C-M-P (^R Go to +Previous Label) both position the cursor right at the end of a label; +C-M-N moves forward or down and C-M-P moves backward or up. At the +beginning of a line containing a label, C-M-N moves past it. Past the +label on the same line, C-M-P moves back to the end of it. If you kill +a couple of indented lines and want to insert them right after a label, +these commands put you at just the right place. + +C-M-A (^R Go to AC Field) and C-M-E (^R Go to Address Field) move to the +beginning of the accumulator (AC) or effective address fields of a +PDP-10 instruction. They always stay on the same line, moving either +forward or backward as appropriate. If the instruction contains no AC +field, C-M-A positions to the start of the address field. If the +instruction is just an opcode with no AC field or address field, a space +is inserted after the opcode and the cursor left after the space. In +PDP-11 programs, C-M-A moves to the first operand and C-M-E moves to the +second operand. + +Once you've gone to the beginning of the AC field you can often use +C-M-D (^R Kill Terminated Word) to kill the AC name and the comma which +terminates it. You can also use it at the beginning of a line, to kill +a label and its colon, or after a line's indentation to kill the opcode +and the following space. This is very convenient for moving a label +from one line to another. In general, C-M-D is equivalent to M-D C-D, +except that all the characters are saved on the kill ring, together. +C-D, a "deletion" command, doesn't save on the kill ring if not given an +argument. + +The M-[ and M-] commands are not, strictly speaking, redefined by MIDAS +mode. They go up or down to a paragraph boundary, as usual. However, +in MIDAS mode the criterion for a paragraph boundary is changed by +setting the variable Paragraph Delimiter (*Note Paragraphs: Sentences.) +so that only blank lines (and pages) delimit paragraphs. So, M-[ moves +up to the previous blank line and M-] moves to the next one. + + +EMACS Node: Other Langs, Previous: MIDAS, Up: Programs + +Major Modes for Other Languages + +MACSYMA mode redefines the syntax of words and s-expressions in an +attempt to make it easier to move over MACSYMA syntactic units. In +addition, the C-M-G "grind" command is told to grind text as MACSYMA +instead of as Lisp. Also, the syntax of MACSYMA comments is understood. + +TECO mode is good for editing EMACS library source files. It connects +Tab to ^R Indent Nested (see its self-documentation). Comments start +with "!* " and end with "!". In addition, the PURIFY library, which +contains many things useful for processing library sources (including +the commands to compile them), is loaded. M-' and M-" are connected to +functions ^R Forward TECO Conditional and ^R Backward TECO Conditional +which move forward and backward over balanced TECO conditionals. In +TECO mode on a terminal with a Meta key, it may be useful to set the +TECO flag FS CTLMTA which causes Control-Meta commands to insert +Control characters. *Note FS Flags: FS Flags. + +CLU mode is for editing CLU code. It is similar to LISP mode, but it +treats the statement nesting tokens like the appropriate sorts of +parentheses. It is in the library called CLU. *Note CLU: (ECLU). + +PL1 mode is for editing PL1 code, and causes Tab to indent an amount +based on the previous statement type. The body of the implementation of +PL1 mode is in the library PL1, which is loaded automatically when +necessary. *Note PL1: (EPL1). + +PASCAL mode is similar to PL1 mode, for PASCAL. It is in the library +called PASCAL. *Note PASCAL: (EPASC). + +FORTRAN mode is implemented by the FORTRAN library. *Note FORTRAN: +(EFORTRAN). + +There are also modes for BLISS, BCPL, COBOL, Muddle, and SAIL, but no +documentation for them except that in the libraries themselves. Any +volunteers to write some? Meanwhile, you can look at the documentation +in the libraries. *Note Libraries: Libraries. + + +EMACS Node: MinorModes, Previous: Programs, Up: Top, Next: Libraries + +Minor Modes + +Minor modes are options which you can use or not. For example, Auto +Fill mode is a minor mode in which Spaces break lines between words as +you type. All the minor modes are independent of each other and of the +selected major mode. Most minor modes say in the mode line when they +are on; for example, "Fill" in the mode line means that Auto Fill mode +is on. + +Each minor mode is the name of the function that can be used to turn it +on or off. With no argument, the function turns the mode on if it was +off and off if it was on. This is known as "toggling". A positive +argument always turns the mode on, and an explicit zero argument or a +negative argument always turns it off. All the minor mode functions are +suitable for connecting to single or double character commands if you +want to enter and exit a minor mode frequently. + +Auto Fill mode allows you to type text endlessly without worrying about +the width of your screen. Line separators are be inserted where needed +to prevent lines from becoming too long. *Note Filling: Filling. + +Auto Save mode protects you against system crashes by periodically +saving the file you are visiting. Whenever you visit a file, auto +saving is enabled if Auto Save Default is nonzero; in addition, M-X Auto +Save allows you to turn auto saving on or off in a given buffer at any +time. *Note Auto Save: AutoSave. + +Atom Word mode causes the word-moving commands, in Lisp mode, to move +over Lisp atoms instead of words. Some people like this, and others +don't. In any case, the s-expression motion commands can be used to +move over atoms. If you like to use segmented atom names like +FOOBAR-READ-IN-NEXT-INPUT-SOURCE-TO-READ, then you might prefer not to +use Atom Word mode, so that you can use M-F to move over just part of +the atom, or C-M-F to move over the whole atom. + +Overwrite mode causes ordinary printing characters to replace existing +text instead of shoving it over. It is good for editing pictures. For +example, if the point is in front of the B in FOOBAR, then in Overwrite +mode typing a G changes it to FOOGAR, instead of making it FOOGBAR as +usual. Also, Rubout is changed to turn the previous character into a +space instead of deleting it. + +SAIL Character mode causes ASCII control characters in text to display +as themselves, with no conversion. This assumes that the terminal uses +codes 200 and above for cursor motion and erasure, and can display all +the ASCII control characters as graphic characters. The command +Control- runs this command. Control- is a character which can +generally only be typed on terminals which can display the ASCII control +characters in the appropriate fashion. + +Word Abbrev mode allows you to define abbreviations that automatically +expand as you type them. For example, "wam" might expand to "word +abbrev mode". The abbreviations may depend on the major (e.g. Lisp, +Text, ...) mode you are currently in. To use this, you must load the +WORDAB library. *Note Wordab: (WORDAB)Top. + +Indent Tabs mode controls whether indentation commands use tabs and +spaces or just spaces to indent with. Usually they use both, but you +might want to use only spaces in a file to be processed by a program or +system which doesn't ignore tabs, or for a file to be shipped to a +system like Multics on which tab stops are not every 8 characters. + +Most minor modes are actually controlled by variables. The mode is on +if the variable is nonzero. Setting the minor mode with a command works +by changing the variable. This means that you can turn the modes on or +off with Edit Options, or make their values local to a buffer. *Note +Variables: Variables. + +You could also put a minor mode in the local modes list of a file, but +that is usually bad practice. This is because usually the preference +for a minor mode is usually a matter of individual style rather than a +property of the file per se. To make this more concrete, it is a +property of a file that it be filled to a certain column, but use of +Auto Fill mode to accomplish that is a matter of taste. So it would be +good practice for the file to specify the value of Fill Column, but bad +practice for the file to specify the value of Auto Fill Mode. + +If you find yourself constantly tempted to turn on Auto Fill mode in +local modes lists, what you probably really want is to have Auto Fill +mode on whenever you are in Text mode. This can be accomplished with +the following code in an EVARS file: + + Text Mode Hook: 1M.LAuto Fill Mode + +Suffice it to explain that this is TECO code to be executed whenever +Text mode is entered, which makes the variable Auto Fill Mode local to +the buffer with local value 1. + + +EMACS Node: Libraries, Previous: MinorModes, Up: Top, Next: Variables + +Libraries of Commands + +All EMACS functions, including the ones described in this document, +reside in libraries. A function is not accessible unless the library +that contains it is loaded. Every EMACS starts out with +one library loaded: the EMACS library. This contains all of the +functions described in this document, except those explicitly stated to +be elsewhere. Other libraries are provided with EMACS, and can be +loaded automatically or on request to make their functions available. +*Note Catalogue: LibCat, for a list of them. + +To load a library, say M-X Load Library. The library is +found, either on your own directory or whichever one you specify, or on +the EMACS directory, and loaded in. All the functions in the library +are then available for use. Whenever you use M-X, the function name you +specify is looked up in each of the libraries which you have loaded, +more recently loaded libraries first. The first definition found is the +one that is used. + +For example, if you load the PICTURE library, you can then use M-X Edit +Picture to run the Edit Picture function which exists in that library. + +In addition to making functions accessible to M-X, the library may +connect some of them to command characters. This is done by the +library's & Setup function (*Note Lib: (CONV)Lib.). If you give Load +Library an argument, the setup is not done. + +You can also load a library temporarily, just long enough to use one of +the functions in it. This avoids taking up space permanently with the +library. Do this with the function Run Library, as in M-X +Run. The library is loaded in, +and executed. Then the library is removed from the +EMACS job. You can load it in again later. + +M-X List Loaded Libraries types the names and brief descriptions of all +the libraries loaded, last loaded first. The last one listed is always +the EMACS library. + +You can get a brief description of all the functions in a library with +M-X List Library, whether the library is loaded or not. +This is a good way to begin to find out what is in a library that has no +INFO documentation. Continue by loading the library and using Help D to +inquire further about whichever functions looked interesting. + +The function Kill Libraries can be used to discard libraries loaded with +Load Library. (Libraries used with Run Library are discarded +automatically). However, of all the libraries presently loaded, only +the most recently loaded one can be discarded. Kill Libraries offers to +kill each loaded library, most recently loaded first. It keeps killing +libraries until you say to keep one library. Then it returns, because +the remaining libraries cannot be deleted if that library is kept. + +Libraries are loaded automatically in the course of executing certain +functions. You will not normally notice this. For example, the TAGS +library is automatically loaded in whenever you use M-. or Visit Tag +Table for the first time. This process is known as "autoloading". It +is used to make the functions in the TAGS library available without the +user's having to know to load the library himself, while not taking up +space in EMACSes of people who aren't using them. It works by simply +calling Load Library on the library known to be needed. Another kind of +autoloading loads a library temporarily, the way Run Library does. This +is done when you use the DIRED function, for example, since the DIRED +library is not needed after the DIRED function returns. (This does not +use Run Library; it uses M.A, which is what Run Library uses). + +You can make your own libraries, which you and other people can then +use, if you know how to write TECO code. *Note Making Libraries: +(CONV)Lib, for more details. + + +EMACS Node: Variables, Previous: Libraries, Up: Top, Next: Syntax + +Variables + +A variable is a name which is associated with a value, either a number +or a string. EMACS uses many variables internally, and has others whose +purpose is to be set by the user for customization. (They may also be +set automatically by major modes.) One example of such a variable is +the Fill Column variable, which specifies the position of the right +margin (in characters from the left margin) to be used by the fill and +justify commands. + +The easiest way for the beginner to set a named variable is to use the +function Edit Options. This shows you a list of selected variables +which you are likely to want to change, together with their values, and +lets you edit them with the normal editing commands in a recursive +editing level. Don't make any changes in the names, though! Just +change the values. Digits with maybe a minus sign stand for a numeric +value of the variable, while string values are enclosed in doublequotes. +Each option is followed by a comment which says what the option is for. +Type the Help character for more information on the format used. + +When you are finished, exit Edit Options using C-M-C and the changes +will take effect. If you decide not to make the changes, C-] gets out +without redefining the options. *Note Recursive Editing Levels: +Recursive. + +If you give Edit Options a string argument, it shows you only the +options whose names include the string. For example, M-X Edit +OptionsFill shows only the options that have "Fill" in their names. +This is much more convenient, if you know what you plan to do. + +However, Edit Options can be used only to set a variable which already +exists, and is marked as an option. Some commands refer to variables +which do not exist in the initial environment. Such commands always use +a default value if the variable does not exist. In these cases you must +create the variable yourself if you wish to use it to alter the behavior +of the command. Use M-X Set Variable for this. You can set the +variable to a numeric value by doing + + C-U M-X Set Variable + +or to a string by doing + + M-X Set Variable + +In fact, you can use Set Variable to set any variable, whether it exists +already or not. For existing variables, it does not matter whether you +use upper case or lower case letters, and you are allowed to abbreviate +the name as long as the abbreviation is unique. If the variable might +not exist yet, you must type the name in full. While either upper case +or lower case will still work, you are encouraged to capitalize each +word of the name for aesthetic reasons since EMACS stores the name as +you give it. + +To examine the value of a single variable, do + + M-X View Variable + +To print a complete list of all variables, do M-X List Variables. List +Variables with a string argument shows only the variables whose names or +values contain that string (like the function Apropos). M-X Describe +can be given a variable's name instead of a function's name; it prints +the variable's value and its documentation, if it has any. + +If you want to set a variable a particular way each time you use EMACS, +you can use an init file or an EVARS file. This is one of the main ways +of customizing EMACS for yourself. An init file is a file of TECO code +to be executed when you start EMACS up. They are very general, but +writing one is a black art. You might be able to get an expert to do it +for you, or modify a copy of someone else's. *Note Init: (CONV)Init, +for details. An EVARS file is a much simpler thing which you can do +yourself. *Note EVARS files: Init. + +You can also set a variable with the TECO command + + M.V  + +or + + :I* M.V  + +This is useful in init files. + +Any variable can be made local to a specific buffer with the TECO +command M.L. Thus, if you want the comment column to be +column 50 in one buffer, whereas you usually like 40, then in the one +buffer do M.LComment Column using the minibuffer. Then, you can do +50UComment Column in that buffer and other buffers will not be +affected. This is how local modes lists in files work. M-X List +Redefinitions describes the local variables of the selected buffer in a +verbose fashion. + +Most local variables are killed if you change major modes. Their global +values come back. They are therefore called "mode locals". There are +also "permanent" locals which are not killed by changing modes; use +2,M.L to create one. Permanent locals are used by things like Auto Save +mode to keep internal information about the buffer, whereas mode locals +are used for customizations intended only for one buffer. *Note +Variables: (CONV)Variables, for information on how local variables work, +and additional related features. + +Local values of variables can be specified by the file being edited. +For example, if a certain file ought to have a 50 column width, it can +specify a value of 50 for the variable Fill Column. Then Fill Column +will have the value 50 whenever this file is edited, by anyone. Editing +other files is not affected. *Note Locals: Locals, for how to do this. + + +EMACS Node: Syntax, Previous: Variables, Up: Top, Next: FS Flags + +The Syntax Table + +All the EMACS commands which parse words or balance parentheses are +controlled by the "syntax table". Each ASCII character has a word +syntax and a Lisp syntax. By changing the word syntax, you can control +whether a character is considered a word delimiter or part of a word. +By changing the Lisp syntax, you can control which characters are +parentheses, which ones are parts of symbols, which ones are prefix +operators, and which ones are just ignored when parsing s-expressions. + +The syntax table is actually a string which is 128*5 characters long. +Each group of 5 consecutive characters of the syntax table describe one +ASCII character's syntax; but only the first three of each group are +used. To edit the syntax table, use M-X Edit Syntax Table. But before +we describe this command, let's talk about the syntax of the syntax +table itself. + +The first character in each group of five sets the word syntax. This +can be either "A" or a space. "A" signifies an alphabetic character, +whereas a space signifies a separator character. + +The second character in each group is the Lisp syntax. It has many +possible values: + + A an alphabetic character + Space a whitespace or nonsignificant character + ( an open parenthesis + ) a close parenthesis + ; a comment starter + î a comment ender + | a string quote + / a character quote + ' a prefix character + +When a character has the syntax of an open parenthesis, that means that +the character is taken to be the beginning of a parenthesized grouping +when expressions are being parsed. Thus, any number of different +expression-starting characters can be handled. + +The syntax of "prefix character" means that the character becomes part +of whatever object follows it, whether symbol or list, and can also be +in the middle of a symbol, but does not constitute anything by itself if +surrounded by whitespace. + +A character quote character causes itself and the next character to be +treated as alphabetic. + +A string quote is one which matches in pairs. All characters inside a +pair of string quotes are treated as alphabetic except for the character +quote, which retains its significance, and can be used to force a string +quote or character quote into a string. + +A comment starter is taken to start a comment, which ends at the next +comment ender, suppressing the normal syntax of all characters between. +Only the indentation commands give special treatment to these two syntax +codes; all other commands consider them the same as Space +(nonsignificant character). The commands specifically for comments use +the variables Comment Start, Comment Begin, and Comment End to detect +comments. This is so that the comment delimiters can be multi-character +strings. + +The third character in each group controls automatic parenthesis +matching display. It is defined only for characters which have the Lisp +syntax of close parentheses, and for them it should contain the +appropriate matching open parenthesis character (or a space). If you +insert a close parenthesis character which is matched by the wrong kind +of open parenthesis character, it rings the bell. If the third syntax +table character of a close parenthesis is a space, any open parenthesis +is allowed to match it. + +The fourth and fifth characters in each group should always be spaces, +for now. They are not used. The reason they exist is so that word-wise +indexing can be used on the PDP-10 to access the syntax of a character +given in an accumulator. + +Edit Syntax Table displays the syntax table broken up into labeled +five-character groups. You can see easily what the syntax of any +character is. You are not editing the table immediately, however. +Instead, you are asked for the character whose syntax you wish to edit. +After typing it, you are positioned at that character's five-character +group. Overwrite mode is on, so you can simply type the desired syntax +entries, which replace the old ones. You can also do arbitrary editing, +but be careful not to change the position of anything in the buffer. +When you exit the recursive editing level, you are asked for another +character to position to. An Altmode at this point exits and makes the +changes. A C-] at any time aborts the operation. + +Many major modes alter the syntax table. Each such major mode creates +its own syntax table once and reselects the same string whenever the +mode is selected, in any buffer. Thus, all buffers in Text mode at any +time use the same syntax table. This is important because if you ever +change the syntax table of one buffer that is in Text mode, you change +them all. It is possible to give one buffer a local copy with a TECO +program: + + MM Make Local Q-Register..DW :G..DU..D + +The syntax tables belonging to the major modes are not preinitialized in +EMACS; they are created when the major mode is invoked for the first +time, by copying the default one and making specific changes. Thus, any +other changes you have made in the default (Fundamental mode) syntax +table at the beginning propagate into all modes' syntax tables unless +those modes specifically override them. + +After a major mode has created its own syntax table, that table is +stored in the variable ..D. This makes a different variable +for each major mode, since the mode name is part of the variable name. +Further use of the major mode gets the syntax table from that variable. +If you create the variable yourself before the first use of the major +mode, the value you put there will be used. + +TECO programs and init files can most easily change the syntax table +with the function & Alter ..D (look at its documentation). The syntax +table is kept in the q-register named ..D, which explains that name. + + +EMACS Node: FS Flags, Previous: Syntax, Up: Top, Next: Init + +FS Flags + +FS flags are variables defined and implemented by TECO below the level +of EMACS. Some of them are options which control the behavior of parts +of TECO such as the display processor. Some of them control the +execution of TECO programs; you are not likely to want to change these. +Others simply report information from inside TECO. The list of FS flags +is fixed when TECO is assembled and each one exists for a specific +purpose. + +FS flags are used mostly by the TECO programmer, but some of them are of +interest to the EMACS user doing minor customization. For example, FS +ECHO LINES is the number of lines in the echo area. By setting this +flag you can make the echo area bigger or smaller. Many FS flags useful +for customization are controlled by EMACS variables; instead of setting +the FS flag, you can set the EMACS variable like any other. Setting the +variable automatically sets the FS flag as well. Here is a list of such +variables which control flags: + + Auto Save Interval FS ^R MDLY + Bottom Display Margin FS %BOTTOM + Case Search FS BOTHCASE + Cursor Centering Point FS %CENTER + Display Mode Line Inverse FS INVMOD + Display Overprinting FS ^H PRINT and FS ^M PRINT + Echo Area Height FS ECHO LINES + End of Buffer Display Margin FS %END + Error Messages in Echo Area FS ECHO ERRORS + Fill Column FS ADLINE + Overwrite Mode FS ^R REPLACE + SAIL Character Mode FS SAIL + Top Display Margin FS %TOP + +Setting one of these variables causes the flag to be set, but not vice +versa. To avoid confusion, always set these flags using the associated +variables, never directly, unless you are changing them temporarily +during one command and the user will not have the opportunity to notice +the confusion. + +To get the value of an FS flag, use the TECO command FS followed by the +name of the flag, terminated by an Altmode. Spaces in the name of the +flag are completely ignored, and case does not matter. Thus, FS Tab +Width= executed in the minibuffer prints the number of columns between +tab stops used for display of tab characters. *Note Minibuffer: +Minibuffer. This works only for flags with numeric values. The easiest +way to examine a flag's value with EMACS commands is + + C-M-X View Variable (FS Tab Width) + +This works for both numeric and string values. + +To set the flag, give the FS command a numeric argument (which must be a +string pointer, if the intended value is a string). For example, in the +minibuffer or an init file, do + + 10FS Tab Width + +Be warned that FS always returns a value, so put a CRLF after it to +discard the value if necessary. + +It is possible to make an FS flag's value local to a buffer. *Note +Locals: (CONV)Vars. + +The documentation of individual FS flags can be found through Help T. +Help T FS Echo Lines prints the description of FS ECHO LINES. +Spaces are not significant in Help T either. A list of just the names +of all FS flags is printed by the function List TECO FS Flags, found in +the library PURIFY. + + +EMACS Node: Init, Previous: FS Flags, Up: Top, Next: Locals + +Init Files and EVARS Files + +EMACS is designed to be customizable; each user can rearrange things to +suit his taste. Simple customizations are primarily of two types: +moving functions from one character to another, and setting variables +which functions refer to so as to direct their actions. Beyond this, +extensions can involve redefining existing functions, or writing +entirely new functions and creating sharable libraries of them. + +The most general way to customize is to write an init file, a TECO +program which is executed whenever you start EMACS. The init file is +found by looking for a particular filename, ; +EMACS. This method is general because the program can do anything. It +can ask you questions and do things, rather than just setting up +commands for later. However, TECO code is arcane, and only a few people +learn how to write it. If you need an init file and don't feel up to +learning to write TECO code, ask a local expert to do it for you. *Note +Init: (CONV), for more about init files. + +However, simple customizations can be done in a simple way with an EVARS +file. Such a file serves the same sort of purpose as an init file, but +instead of TECO code, it contains just a list of variables and values. +Each line of the EVARS file names one variable or one command character +and says how to redefine it. Empty lines, and lines starting with +spaces or tabs, are ignored. They can be used as comments. Your EVARS +file is found by its filename, as an init file is, but it should be +called ; EVARS instead of EMACS. You can +have both an init file and an EVARS file if you want, as long as your +init file calls the default init file, since that is what processes the +EVARS file. + +To set a variable, include in the EVARS file a line containing the name +of the variable, a colon, and the value. A numeric value is represented +by the number. A string value is enclosed in double quotes. To include +a double quote or a  character in the value of the string, precede it +with a  to quote it. You can also simply give the string value, with +no quotes, as long as it is not ambiguous (does not consist of digits or +start with a double quote); however, in this case, any spaces following +the colon become part of the value of the variable. They are not +ignored. Examples: + + Comment Column: 70 + Comment Start: ";" + MM Foo:FTFOO + +The last line defines a variable named MM Foo, which has the effect of +defining a function named Foo with the specified value as its +definition. + +To redefine a command character is a little more complicated. Instead +of the name of a variable, give a  (control-R) followed by the +character. Since the general Control and Meta character cannot be part +of a file, all Control and Meta characters are represented in a funny +way: after the  put the residue of the character after removing the +Control and Meta, and before the  put periods, one for Control, two +for Meta, and three for Control-Meta. Thus, C-D is represented by +".D" and C-M-; is represented by "...;". Lower case characters such +as C-a are usually defined as "execute the definition of the upper case +equivalent". Therefore, by redefining the C-A command you also change +C-a; but if you redefine C-a, by saying ".a" instead of ".A", you +will not change C-A. So be careful about case. + +Instead of the value of a variable, for command character redefinition +you must give a TECO expression that returns the desired definition. +This is to make it easy to use any function whose name you know, because +M.MFOO is an expression that returns the definition of the function +FOO. Do not enclose the TECO expression in quotes. Example: + + .K: M.M^R Kill Line + +would give C-K the definition that it normally has. Remember that in +names of functions the "^R" is actually a "^" and an R, not a control-R. +The space before the M.M is part of the expression, but it is ignored +when the expression is executed. + +Some non-printing characters are a little tricky to redefine. For +example, you must know that Return, Linefeed, Tab, Backspace and Altmode +are not the same in TECO's command character set as C-M, C-J, C-I, C-H +and C-[, even though in ASCII they are synonymous. By saying .J you +will redefine C-J; by saying  followed by a Linefeed (which you must +insert in the EVARS file by typing C-Q Linefeed) you can redefine +Linefeed. Normally, C-J is defined as "execute the definition of +Linefeed", so you are better off redefining Linefeed. + +You can also redefine a subcommand of a prefix character such as C-X. +For this, you have to know where the character's dispatch table is +stored. For C-X, the location of the dispatch is called ".X"; you won't +have any other prefix characters unless you define them yourself. *Note +Defining prefixes: (CONV)Prefix. Knowing the location, you specify the +subcommand by writing :location(character). This looks silly, but it +is a TECO expression with the right meaning. For example, redefining +C-X C-S, the location is ".X" and the character is , so we say + + :.X(): M.M^R Save File + +This gives C-X C-S the definition that it normally has. The subcommand +character ( in this case) can represent itself in the EVARS file with +no need for dots, because subcommand characters are just ASCII, with no +Meta allowed. + +You can include arbitrary TECO code in an EVARS file by writing a +definition for "*". The definition is executed as a TECO expression but +the value is ignored. Thus, to load the library FOO, do + + *: MM Load LibraryFOO + +Once the library is loaded, you can connect the functions in it to +commands as described above. + +Please refrain from giving newcomers to EMACS a copy of your own init +file before they understand what it does. Everyone prefers his own +customizations, and there is always a tendency to proselytize, but by +the same token your protege's tastes may be different from yours. If +you offer him your customizations at the time when he is ready to +understand what difference they make and decide for himself what he +prefers, then you will help him get what he wants. Tell him about each +individual change you made, and let him judge them one by one. There is +no reason for him to choose all or nothing. + +EVARS File Examples + +Here are some examples of how to do various useful things in an EVARS +file. + +This causes new buffers to be created in Lisp mode: + + Default Major Mode: "LISP" + +This causes new buffers to have Auto Fill mode turned on: + + Buffer Creation Hook: "1M.L Auto Fill Mode" + +This causes all Text mode buffers to have Auto Fill mode turned on: + + Text Mode Hook: "1M.L Auto Fill Mode" + +This causes C-M-G to be undefined by copying the definition of C-| +(which is undefined): + + ...G: Q.| + +This redefines C-S to be a single character search command, and M-S to +be a non-incremental string search: + + .S: M.M ^R Character Search + ..S: M.M ^R String Search + +This redefines C-X V to run View File: + + :.X(V): M.M View File + +This makes M-M a prefix character and defines M-M W to mark a word and +M-M P to mark a paragraph. It stores the dispatch vector for the prefix +character in the variable M-M Dispatch. + + ..M: MM Make Prefix CharacterM-M Dispatch + Temp: "M-M M-M Dispatch + " + Append the line in Temp to Prefix Char List. + *: QPrefix Char List[1 QTemp[2 :iPrefix Char List12 + :M-M Dispatch(W): M.M ^R Mark Word + :M-M Dispatch(P): M.M ^R Mark Paragraph + +This loads the library LUNAR and defines C-Q to run a useful function +found in that library: + + *: MM Load LibraryLUNAR + .Q: M.M ^R Various Quantities + +This causes Auto Save mode to save under the visited filenames: + + Auto Save Visited File: 1 + +This causes TAGS to bring new files into separate buffers: + + TAGS Find File: 1 + +This prevents the default init file from printing the message "EMACS +version nnn. Type ... for Help". + + Inhibit Help Message: 1 + +This redefines the list syntax of "%" to be ";" for "comment starter", +and that of ";" to be "A" for "alphabetic": + + *: 1mm& Alter ..D%;;A + +Init File Examples + +Here are the ways to do exactly the same things in an init file. Don't +put more than one of these TECO expressions on a line, or the first may +leave behind a value which will affect the operation of the second! + +This causes new buffers to be created in Lisp mode: + + :IDefault Major ModeLISP + +This causes new buffers to have Auto Fill mode turned on: + + :I* 1M.L Auto Fill Mode  M.VBuffer Creation Hook + +It is different because the variable does not already exist. Note the + used for getting the Altmode into the value. + +This causes all Text mode buffers to have Auto Fill mode turned on: + + :I* 1M.L Auto Fill Mode  M.VText Mode Hook + +This causes C-M-G to be undefined by copying the definition of C-| +(which is undefined): + + Q.| U...G + +This redefines C-S to be a single character search command, and M-S to +be a non-incremental string search: + + M.M ^R Character Search U.S + M.M ^R String Search U..S + +This redefines C-X V to run View File: + + M.M View File U:.X(V) + +This makes M-M a prefix character and defines M-M W to mark a word and +M-M P to mark a paragraph. It stores the dispatch vector for the prefix +character in the variable M-M Dispatch. + + MM Make Prefix Character.YU..M + QPrefix Char List[1 + :iPrefix Char List1M-M M-M Dispatch +  ]1 + M.M ^R Mark Word U:M-M Dispatch(W) + M.M ^R Mark Paragraph U:M-M Dispatch(P) + +This loads the library LUNAR and defines C-Q to run a useful function +found in that library: + + MM Load LibraryLUNAR + M.M ^R Various Quantities U.Q + +This causes Auto Save mode to save under the visited filenames: + + 1UAuto Save Visited File + +Compare this and the next example with the first two, in which string +values are used. + +This causes TAGS to bring new files into separate buffers: + + 1M.VTAGS Find File + +This prevents the default init file from printing the message "EMACS +version nnn. Type ... for Help". + + 1M.VInhibit Help Message + +This redefines the list syntax of "%" to be ";" for "comment starter", +and that of ";" to be "A" for "alphabetic": + + 1mm& Alter ..D%;;A + + + +EMACS Node: Locals, Previous: Init, Up: Top, Next: KBDMAC + +Local Variables in Files + +By specifying "local modes" in a file you can cause certain major or +minor modes to be set, or certain character commands to be defined, +whenever you are visiting it. For example, EMACS can select Lisp mode +for that file, set up a special Comment Column, or put a special command +on the character C-M-Comma. Local modes can specify the major mode, and +the values of any set of named variables and command characters. Local +modes apply only while the buffer containing the file is selected; they +do not extend to other files loaded into other buffers. + +The simplest kind of local mode specification sets only the major mode. +You put the mode's name in between a pair of "-*-"'s, anywhere on the +first nonblank line of the file. For example, the first line of this +file contains -*-Text-*-, implying that this file should be edited in +Text mode. + +To specify more that just the major mode, you must use a "local modes +list", which goes in the LAST page of the file (it is best to put it on +a separate page). The local modes list starts with a line containing +the string "Local Modes:", and ends with a line containing the string +"End:". In between come the variable names and values, just as in an +EVARS file. *Note EVARS files: Init. + +The line which starts the local modes list does not have to say just +"Local Modes:". If there is other text before "Local Modes:", that text +is called the "prefix", and if there is other text after, that is called +the "suffix". If these are present, each entry in the local modes list +should have the prefix before it and the suffix after it. This includes +the "End:" line. The prefix and suffix are included to disguise the +local modes list as a comment so that the compiler or text formatter +will not be perplexed by it. If you do not need to disguise the local +modes list as a comment in this way, do not bother with a prefix or a +suffix. + +Aside from the "Local Modes:" and the "End:", and the prefix and suffix +if any, a local modes list looks like an EVARS file. However, comments +lines are not allowed, and you cannot redefine C-X subcommands due to +fundamental limitations of the data structure used to remember local +variables. Sorry. + +The major mode can be set by specifying a value for the variable "Mode" +(don't try setting the major mode this way except in a local modes +list!). It should be the first thing in the local modes list, if it +appears at all. A function M-X Foo can be defined locally by putting in +a local setting for a variable named "MM Foo". *Note Functions: +MMArcana. + +Here is an example of a local modes list: + + ;;; Local Modes: *** + ;;; Mode:Mumble *** + ;;; Comment Column:0 *** + ;;; Comment Start: ";;; " *** + ;;; Comment End:"***" *** + ;;; ../: m.m^R My Funny Meta-Slash *** + ;;; End: *** + +Note that the prefix is ";;; " and the suffix is " ***". Note also that +comments in the file begin with ";;; " and end with "***". Presumably +the file contains code in the language Mumble, in which comments must +start and end that way. The prefix and suffix are used in the local +modes list to make the list appear as comments when the file is read by +the Mumble compiler. + +The last page of the file must be no more than 10000 characters long or +the local modes list will not be recognized. This is because EMACS +finds the local modes list by scanning back only 10000 characters from +the end of the file for the last formfeed, and then looking forward for +the "Local Modes:" string. This accomplishes these goals: a stray +"Local Modes:" not in the last page is not noticed; and visiting a long +file that is all one page and has no local mode list need not take the +time to search the whole file. + + +EMACS Node: KBDMAC, Previous: Locals, Up: Top, Next: Minibuffer + +Keyboard Macros + + C-X ( Start defining a keyboard macro. + C-X ) End the definition of a keyboard macro. + C-X E Execute the most recent keyboard macro. + C-X Q Ask for confirmation when the keyboard macro is + executed. + C-U C-X Q Allow the user to edit for a while, each time the + keyboard macro is executed. + M-X Name Kbd Macro + Make the most recent keyboard macro into the + permanent definition of a command. + +A "keyboard macro" is a command defined by the user to abbreviate a +sequence of other commands. If you discover that you are about to type +C-N C-D forty times, you can define a keyboard macro to do C-N C-D and +call it with a repeat count of forty. + +Keyboard macros differ from ordinary EMACS commands, in that they are +written in the EMACS command language rather than in TECO. This makes +it easier for the novice to write them, and makes them more convenient +as temporary hacks. However, the EMACS command language is not powerful +enough as a programming language to be useful for writing anything +intelligent or general. For such things, TECO must be used. + +EMACS functions were formerly known as macros (which is part of the +explanation of the name EMACS), because they were macros within the +context of TECO as an editor. We decided to change the terminology +because, when thinking of EMACS, we consider TECO a programming language +rather than an editor. The only "macros" in EMACS now are keyboard +macros. + +You define a keyboard macro while executing the commands which are the +definition. Put differently, as you are defining a keyboard macro, the +definition is being executed for the first time. This way, you can see +what the effects of your commands are, so that you don't have to figure +them out in your head. When you are finished, the keyboard macro is +defined and also has been, in effect, executed once. You can then do +the whole thing over again by invoking the macro. + +Basic Use + +To start defining a keyboard macro, type the C-X ( command (^R Start Kbd +Macro). From then on, your commands continue to be executed, but also +become part of the definition of the macro. "Def" appears in the mode +line to remind you of what is going on. When you are finished, the +C-X ) command (^R End Kbd Macro) terminates the definition (without +becoming part of it!). + +The macro thus defined can be invoked again with the C-X E command +(^R Execute Kbd Macro), which may be given a repeat count as a numeric +argument to execute the macro many times. C-X ) can also be given a +repeat count as an argument, in which case it repeats the macro that +many times right after defining it, but defining the macro counts as the +first repetition (since it is executed as you define it). So, giving +C-X ) an argument of 2 executes the macro immediately one additional +time. An argument of zero to C-X E or C-X ) means repeat the macro +indefinitely (until it gets an error). + +If you want to perform an operation on each line, then either you should +start by positioning point on the line above the first one to be +processed and then begin the macro definition with a C-N, or you should +start on the proper line and end with a C-N. Either way, repeating the +macro will operate on successive lines. + +If you wish to save a keyboard macro for longer than until you define +the next one, you must give it a name. If you do M-X Name Kbd +MacroFOO, the last keyboard macro defined (the one which C-X E +would invoke) is turned into a function and given the name FOO. M-X FOO +will from then on invoke that particular macro. Name Kbd Macro also +reads a character from the keyboard and redefines that character command +to invoke the macro. You can use a bit prefix character in specifying +the command; you can also type a C-X command to be redefined. When you +have finished typing the command characters, Name Kbd Macro asks you +whether it should go ahead and redefine the character. + +To examine the definition of a keyboard macro, use the function View Kbd +Macro. Either supply the name of the function which runs the macro, as +a string argument, or type the command which invokes the macro when View +Kbd Macro asks for it. + +Executing Macros with Variations + +If you want to be allowed to do arbitrary editing at a certain point +each time around the macro (different each time, and not remembered as +part of the macro), you can use the C-U C-X Q command (^R Kbd Macro +Query). When you are defining the macro, this lets you do some editing, +which does NOT become part of the macro. When you are done, exit with +C-M-C to return to defining the macro. When you execute the macro, at +that same point, you will again be allowed to do some editing. When you +exit this time with C-M-C, the execution of the macro will resume. If +you abort the recursive editing level with C-], you will abort the macro +definition or execution. + +You can get the effect of Query Replace, where the macro asks you each +time around whether to make a change, by using the command C-X Q with no +argument in your keyboard macro. When you are defining the macro, the +C-X Q does nothing, but when the macro is invoked the C-X Q reads a +character from the terminal to decide whether to continue. The special +answers are Space, Rubout, Altmode, C-L, C-R. A Space means to +continue. A Rubout means to skip the remainder of this repetition of +the macro, starting again from the beginning in the next repetition. An +Altmode ends all repetitions of the macro, but only the innermost macro +(in case it was called from another macro). C-L clears the screen and +asks you again for a character to say what to do. C-R enters a +recursive editing level; when you exit, you are asked again (if you type +a Space, the macro will continue from wherever you left things when you +exited the C-R). Anything else exits all levels of keyboard macros and +is reread as a command. + + +EMACS Node: Minibuffer, Previous: KBDMAC, Up: Top, Next: Quitting + +The Minibuffer + +The "minibuffer" is a facility by means of which EMACS commands can read +input from the terminal, allowing you to use EMACS commands to edit the +input while you are typing it. Usually it is used to read a TECO +program to be executed. + + M-Altmode Invokes an empty minibuffer. + M-% Invokes a minibuffer initialized with a Query + Replace. + C-X Altmode Re-execute a recent minibuffer command. + C-X ^ Add more lines to the minibuffer. + C-\ Meta-prefix for use in the minibuffer. + C-C C-Y Rotate ring of recent minibuffer commands. + +The primary use of the minibuffer is for editing and executing simple +TECO programs such as + + MM Query ReplaceFOO + BAR +  + +(which could not be done with M-X Query Replace because when M-X is used +Return terminates the arguments). + +You can always tell when you are in a minibuffer, because the mode line +contains something in parentheses, such as "(Minibuffer)" or "(Query +Replace)". There is also a line of dashes across the screen a few lines +from the top. Strictly speaking, the minibuffer is actually the region +of screen above the line of dashes, for that is where you edit the input +that the minibuffer is asking you for. Editing has been limited to a +few lines so that most of the screen can continue to show the file you +are visiting. + +If you want to type in a TECO command, use the minibuffer with the +command Meta-Altmode, (^R Execute Minibuffer). An empty minibuffer will +appear, into which you should type the TECO command string. Exit with +Altmode Altmode, and remember that neither of the two Altmodes is +inserted into your TECO command although the first one may appear to be. +When the TECO command is executed, "the buffer" will be the text you +were editing before you invoked the minibuffer. + +Often, a minibuffer starts out with some text in it. This means that +you are supposed to add to that text, or, sometimes, to delete some of +it so as to choose among several alternatives. For example, Meta-% +(^R Query Replace) provides you with a minibuffer initially containing +the string "MM Query Replace". The cursor comes at the end. You are +then supposed to add in the arguments to the Query Replace. + +In a minibuffer, you can edit your input until you are satisfied with +it. Then you tell EMACS you are finished by typing two Altmodes. An +Altmode not followed by another Altmode is simply inserted in the +buffer. This is because it is common to want to put Altmodes into the +minibuffer, which usually contains a string of TECO commands. For +example, in Meta-% (^R Query Replace) each argument must be ended by an +Altmode. However, when you type two Altmodes in a row, neither one +remains in the buffer. The two Altmodes do nothing to the text in the +minibuffer, they just exit. + +Since Altmode is self-inserting, typing Meta characters can be a +problem. You can do it by using C-\ instead of Altmode as the +Meta-prefix. If you type a Control-Meta character on your keyboard, the +corresponding ASCII control character is inserted in the minibuffer. +This is because the Lisp commands are rarely useful when editing TECO +code, but insertion of control characters is frequent. If you really +want to use a Control-Meta EMACS command, you must use C-C to type it. +You cannot use C-\ C-A to type C-M-A, because C-\ (unlike Altmode) +ignores the Control bit of the following character, so you must use C-C +C-A. The motivation for this quirk of C-\ is that C-\ C-B (to obtain +M-B) is easier to type than C-\ B, especially if it is typed several +times in a row. + +You can cancel your input in a minibuffer and start all over again by +typing C-G. That kills all the text in the minibuffer. A C-G typed +when the minibuffer is already empty exits from the minibuffer. +Usually, this aborts whatever command was using the minibuffer, so it +will return without doing anything more. For example, if you type two +C-G's at Meta-%'s minibuffer, you will return to top level and no Query +Replace will be done. Typing a single C-G at a preinitialized +minibuffer to empty the buffer is not very useful, since you would have +to retype all the initial text. + +The last five distinct minibuffer commands or M-X commands you have +issued are remembered in a ring buffer in q-register .M. The C-X +Altmode command (^R Re-execute Minibuffer) re-executes the last command +in the ring. With an argument , it re-executes the 'th previous +command. The command is printed out (only the first 40 characters or +so) and you are asked to confirm with "Y" or "N". + +You can also get your previous minibuffer and M-X commands back into the +minibuffer to be edited and re-executed with changes. Giving M-Altmode +an argument, as in C-U M-Altmode, causes the minibuffer to be loaded up +with the last command in the ring, as if you had typed it in again from +scratch. You can then edit it, execute it by typing two Altmodes, or +cancel it with C-G. To get an earlier command string instead of the +most recent one, use the command C-C C-Y once you are in the minibuffer. +This command "rotates" the ring of saved commands much as M-Y rotates +the ring of killed text. Each C-C C-Y reveals an earlier command +string, until the ring has rotated all the way around and the most +recent one reappears. C-C C-Y is actually a way of saying C-M-Y, but in +the minibuffer that's the only way to type it, since Altmode inserts +itself and Control-Meta characters insert control characters. + +If you exit from Meta-Altmode with a C-G, nothing is executed and the +previous minibuffered command string is still remembered as the last +one. + +While in a minibuffer, if you decide you want the minibuffer to use more +lines on the screen, you can use C-X ^ (^R Grow Window) to get more. It +gets one more line, or as many lines as its argument says. + + +EMACS Node: Quitting, Previous: Minibuffer, Up: Top, Next: Lossage + +Quitting and Aborting + + C-G Quit. Cancel running or partially typed command. + C-] Abort recursive editing level and cancel the command + which invoked it. + M-X Top Level + Abort all recursive editing levels and subsystems which + are currently executing. + +There are three ways of cancelling commands which are not finished +executing: "quitting" with C-G, and "aborting" with C-] or M-X Top +Level. Quitting is cancelling a partially typed command or one which is +already running. Aborting is cancelling a command which has entered a +recursive editing level or subsystem. + +Quitting with C-G is used for getting rid of a partially typed command, +or a numeric argument that you don't want. It also stops a running +command in the middle in a relatively safe way, so you can use it if you +accidentally give a command which takes a long time. In particular, it +is safe to quit out of killing; either your text will ALL still be +there, or it will ALL be in the kill ring (or maybe both). Quitting an +incremental search does special things documented under searching; in +general, it may take two successive C-G's to get out of a search. C-G +can interrupt EMACS at any time, so it is not an ordinary command. + +Aborting with C-] (Abort Recursive Edit) is used to get out of a +recursive editing level and cancel the command which invoked it. +Quitting with C-G cannot be used for this, because it is used to cancel +a partially typed command within the recursive editing level. Both +operations are useful. For example, if you are editing a message to be +sent, C-G can be used to cancel the commands you use to edit the +message, and C-] cancels sending the message. C-] either tells you how +to resume the aborted command or queries for confirmation before +aborting. + +When you are in a position to use M-X, you can use M-X Top Level. This +is equivalent to "enough" C-] commands to get you out of all the levels +of subsystems and recursive edits that you are in. C-] gets you out one +level at a time, but M-X Top Level goes out all levels at once. Both +C-] and M-X Top Level are like all other commands, and unlike C-G, in +that they are effective only when EMACS is listening. + + +EMACS Node: Lossage, Previous: Quitting, Up: Top, Next: Undo + +Dealing with Common Forms of EMACS Lossage + +This section describes various conditions which can cause EMACS not to +work, or cause it to display strange things, and how you can correct +them. + +Error Message + +When EMACS prints an error message, it occupies the top line of the +screen, ends with a "?", and is accompanied by the ringing of the bell. +Space causes the error message to disappear and be replaced by the first +line of text again. Any other command is executed normally as if there +had been no error message (the error message disappears during the +redisplay after the command). However, "?" enters the error handler, +which can be used to inspect the function call stack. Type Help inside +the error handler to get its documentation. Most users will not be +interested in doing this. + +If you prefer to have echo messages printed in the echo area, set the +variable Error Messages in Echo Area nonzero. + +Subsystems and Recursive Editing Levels + +Subsystems and recursive editing levels are important and useful +features of EMACS, but they can seem like malfunctions to the user who +does not understand them. + +If the mode line starts with a bracket "[" or a parenthesis "(", or does +not start with the word "EMACS", then you have entered a subsystem +(*Note Subsystems: Subsystems.) or a recursive editing level (*Note +Recursive Editing Levels: Recursive.). + +In such a situation, first try typing C-]. This will get out of any +recursive editing level and most subsystems. The usual mode line and +text display will reappear. If C-] does not seem to have worked, type +the Help character. Instead of printing "Doc (Type ? for Help)" in the +echo area, it will print a list of the subsystem's commands. One of +these should be a command to exit or abort. + +If the above techniques fail, try restarting (see below). + +Garbage on the Screen + +If the data on the screen looks wrong, it could be due to line noise on +input or output, a bug in the terminal, a bug in EMACS redisplay, or a +bug in an EMACS command. To find out whether there is really anything +wrong with your text, the first thing to do is type C-L. This is a +command to clear the screen and redisplay it. Often this will display +the text you expected. Think of it as getting an opinion from another +doctor. + +Garbage Displayed Persistently + +If EMACS persistently displays garbage on the screen, or if it outputs +the right things but scattered around all the wrong places on the +screen, it may be that EMACS has the wrong idea of your terminal type. +The first thing to do in this case is to exit from EMACS and restart it. +Each time EMACS is restarted it asks the system what terminal type you +are using. Whenever you detach and move to a terminal of a different +type you should restart EMACS as a matter of course. If you stopped +EMACS with the exit command, or by interrupting it when it was awaiting +a command, then this is sure to be safe. + +The system itself may not know what type of terminal you have. You +should try telling the system with the :TCTYP command. + +URK Error (Address Space Exhausted) + +If attempting to visit a file or load a library causes an "URK" error, +it means you have filled up the address space; there is no room inside +EMACS for any more files or libraries. In this situation EMACS will try +to run the function Make Space for you. If EMACS is unable to do it for +you, you may still be able to do M-X Make Space yourself. This command +compacts the data inside EMACS to free up some space. It also offers to +discard data that may be occupying a lot of space, such as the kill ring +(*Note Killing: Killing.), the undo memory (*Note Undo: Undo.), and +buffers created by RMAIL, TAGS and INFO. Another way of freeing space +is to kill buffers with M-X Kill Some Buffers (*Note Buffers: Buffers.) +or unload libraries with M-X Kill Libraries (*Note Libraries: +Libraries.). + +Use the command M-X What Available Space to find out how close you are +to running out of space. It tells you how many K of space you have +available for additional files or libraries. + +Visiting a file causes an URK error if the file does not fit in the +available virtual memory space, together with the other buffers and the +libraries loaded. A big enough file causes an URK error all by itself. +For editing such large files, use the command Split File (in the SPLIT +library) to break it into subfiles. These will be fairly large files +still, but not too large to edit. After editing one or more of the +subfiles, use the command Unsplit File (also in SPLIT) to put them back +together again. + +All Type-in Echoes and Nothing Else Happens + +If you find that EMACS is not responding to your commands except for +echoing them all at the bottom of the screen, including the Return +character, and that Rubout causes erased characters to be retyped +instead of erased, then you have managed to exit from EMACS back to +TECO. Often this follows an "Error in error handler" message which +indicates that a condition arose in which the error handler could not +function. You can get back into EMACS by typing :M..L, or by +restarting (see below). If you ever want to exit back to TECO, you can +do M-X Top Level with an argument greater than zero. Before using +:M..L, get rid of any other characters you have typed by mistake by +typing a C-G. + +EMACS Hung and Not Responding + +Sometimes EMACS gets hung and C-G does not work. The more drastic +procedure of restarting EMACS may work at such times. C-G can fail to +work because it only takes effect between the TECO commands which make +up an EMACS program, never in the middle of one (only a few TECO +commands allow quitting at any time), so as to prevent TECO's internal +data structures from becoming inconsistent. If EMACS is hung inside a +TECO command, C-G is not noticed, but restarting can still be tried. + +To restart EMACS, type CALL or C-Z to stop EMACS, then G to restart it. +While restarting TECO in this way is usually safe (especially at times +when TECO is doing I/O), there are certain times at which it will cause +the TECO data structures to be inconsistent, so do not try it unless +other measures have failed. + +Your ultimate safeguard against a wedged EMACS is to save your work +frequently. + + +EMACS Node: Undo, Previous: Lossage, Up: Top, Next: Journals + +Undoing Changes to the Buffer + +If you mistakenly issue commands that make a great change to the buffer, +you can often undo the change without having to know precisely how it +came about. This is done by using M-X Undo. Type M-X Undo and the +change is undone. It does not matter if you have moved the cursor since +you made the change; it is undone where it was originally done. + +The first thing Undo does is tell you what kind of change it plans to +undo (kill, fill, undo, case-convert, etc). Then it asks whether to go +ahead. If you say "Y", the change is actually undone. + +Not all changes to the buffer can be undone: deletion (as opposed to +killing) can't be, and changes in indentation can't be, nor can many +forms of insertion (but they aren't as important since they don't +destroy information). Also, a Replace String or Query Replace can't be +undone, which is a shame. The reason is that actually they make many +small changes, and Undo only knows how to remember one contiguous +change. Perhaps someday I will be able to fix this. + +As a result, when you say Undo, it may undo something other than the +latest change if the latest change was not undoable. This might seem to +pile one disaster on another, but it doesn't, because you can ALWAYS +Undo the Undo if it didn't help. But you can avoid even having to do +that, if you look at what type of change Undo says it will undo. + +If you want to undo a considerable amount of editing, not just the last +change, the Undo command can't help you, but M-X Revert File (*Note +Revert: Revert.) might be able to. If you have been writing a journal +file (*Note Journals: Journals.), you can replay the journal after +deleting the part that you don't want. + + +EMACS Node: Journals, Previous: Undo, Up: Top, Next: Bugs + +Journal Files + +A journal file is a record of all the commands you type during an +editing session. If you lose editing because of a system crash, an +EMACS bug, or a mistake on your part, and you have made a journal file, +you can replay the journal or part of it to recover what you lost. +Journal files offer an alternative to auto saving, using less time and +disk space if there is no crash, but requiring more time when you +recover from a crash. *Note Auto Save: AutoSave. + +Writing Journal Files + +In order to make a journal file, you must load the JOURNAL library and +then execute M-X Start Journal File. Immediately, most +of the current status of EMACS is recorded in the journal file, and all +subsequent commands are recorded as they are typed. This happens +invisibly and silently. The journal file is made fully up to date on +the disk after every 50th character, so the last 50 characters of type +in is the most you can lose. + +The default filenames for the journal file are ; JRNL. There is rarely a reason to use any other name, because you +only need one journal file unless you are running two EMACSes at the +same time. + +Replaying Journal Files + +To replay the journal file, get a fresh EMACS, load JOURNAL, and do M-X +Replay Journal File. The filename can usually be omitted +since normally you will have used the defaults when creating the +journal. + +After a delay while the files, buffers and libraries are loaded as they +were when the journal file was written, EMACS will begin replaying the +commands in the journal before your very eyes. Unlike keyboard macros, +which execute invisibly until they are finished, journal files display +as they are executed. This allows you to see how far the replay has +gone. You can stop the process at any time by typing C-G. Aside from +that, you should not type anything on the keyboard while the replay is +going on. + +If the need for a replay is the result of a system crash or EMACS crash, +then you probably want to replay the whole file. This is what happens +naturally. If you are replaying because you made a great mistake, you +probably want to stop the replay before the mistake. This is when it +becomes useful to type C-G to stop the replay. Alternatively, you can +edit the journal file, and delete everything from the point of the +mistake to the end, before you replay it. + +Once the replay is complete, save all your files immediately. Don't +tempt fate! + +If you quit with C-G in the middle of a command while writing a journal +file, there is no way to record in the journal file how much of the +command has already been completed. So, when the journal is replayed, +EMACS has to ask you to fill in for it. The command which was +interrupted will be replayed to completion; then, you are given a +recursive editing level in which to restore the file to the desired +state. This happens only if the C-G originally interrupted an executing +command. C-G typed to discard an argument or partial command while +EMACS is waiting for input can be and is replayed correctly without +asking you for help. + +Journal File Format + +To edit a journal file, you must know the format. It is designed to be +mostly transparent. + +The primary problem which the journal file format has to solve is how to +represent 9-bit command characters in a file which can contain only +7-bit ASCII characters. (We could have filled the journal file with +9-bit characters, but then you would not be able to print it out or edit +it). The solution we have used is to represent each command by two +characters in the file. + +So, a Control character is represented by a caret ("^") followed by the +basic character, as in "^E" for Control-E. This was chosen to be +mnemonically significant. A Meta character is represented by "+" +followed by the basic character, so that Meta-[ is represented by "+[". +A Control-Meta character is represented by "*" followed by the basic +character, as in "*X" for C-M-X. + +A command which is not Control or Meta is represented as a space +followed by the command itself, except that Return is represented by a +CRLF rather than a space and a carriage return. This prevents the +journal file from being one huge line, and makes insertion of text very +recognizable: the text inserted appears in the journal file alternating +with spaces. + +The Help character, which is not covered by the scheme as described so +far, is represented by "??". + +An asynchronous quit, which is a problem for replaying, is represented +by a single character, a , while a synchronous quit, which can be +replayed reliably, is represented by ":". EMACS considers a quit +synchronous, and uses ":" to record it, if EMACS was waiting for +terminal input when the C-G was typed. + +Your commands themselves are not the only information in the journal +file. EMACS records other information which is necessary in replaying +the journal properly. The colon character ":" indicates a block of such +information. Usually the extent of the block is easily recognizable +because its contents do not resemble the representations of commands +described above. A large block of information starting with a colon +appears at the beginning of every journal file. + +Colons are also used to record the precise effects of certain commands +such as C-V whose actions depend on how the text was displayed on the +screen. Since the effects of such commands are not completely +determined by the text, replaying the command could produce different +results, especially if done on a terminal with a different screen size. +The extra information recorded in the journal makes it possible to +replay these commands with fidelity. + +A semicolon in the journal file begins a comment, placed there for the +benefit of a human looking at the journal. The comment ends at the +beginning of the following line. + +Warnings + +Proper replaying of a journal file requires that all the surrounding +circumstances be unchanged. + +In particular, replaying begins by visiting all the files that were +visited when the writing of the journal file began; not the latest +versions of these files, but the versions which were the latest at the +earlier time. If those versions, which may no longer be the latest, +have been deleted, then replaying is impossible. + +If your init file has been changed, the commands when replayed may not +do what they did before. + +These are the only things that can interfere with replaying, as long as +you start writing the journal file immediately after starting EMACS. +But as an editing session becomes longer and files are saved, the +journal file contains increasing amounts of waste in the form of +commands whose effects are already safe in the newer versions of the +edited files. Replaying the journal will replay all these commands +wastefully to generate files identical to those already saved, before +coming to the last part of the session which provides the reason for +replaying. Therefore it becomes very desirable to start a new journal +file. However, many more precautions must be taken to insure proper +replaying of a journal file which is started after EMACS has been used +for a while. These precautions are described here. If you cannot +follow them, you must make a journal checkpoint (see below). + +If any buffer contains text which is not saved in a file at the time the +journal file is started, it is impossible to replay the journal +correctly. This problem cannot possibly be overcome. To avoid it, M-X +Start Journal File offers to save all buffers before actually starting +the journal. + +Another problem comes from the kill ring and the other ways in which +EMACS remembers information from previous commands. If any such +information which originated before starting the journal file is used +after starting it, the journal file cannot be replayed. For example, +suppose you fill a paragraph, start a journal file, and then do M-X +Undo? When the journal is replayed, it will start by doing M-X Undo, +but it won't know what to undo. It is up to you not to do anything that +would cause such a problem. It should not be hard. It would be +possible to eliminate this problem by clearing out all such data +structures when a journal file is started, if users would prefer that. + +A more difficult problem comes from customization. If you change an +option or redefine a command, then start a journal file, the journal +file will have no record of the change. It will not replay correctly +unless you remember to make the same change beforehand. Customizations +made in an init file do not cause a problem because the init file has +also been run when the journal file is replayed. Customizations made +directly by the user while the journal file is being written are also no +problem because replaying will make the same changes at the right times. +However, a customization made while a journal file is being written will +be a problem if a new journal file is started. + +Journal Checkpoints + +The only cure for the problems of starting a journal in mid-session is +to record the complete state of EMACS at the time the journal is begun. +This is not done normally because it is slow; however, you can do this +if you wish by giving M-X Start Journal File a numeric argument. This +writes the complete state of EMACS into the file ;TS +ESAVE. To replay the journal, run ESAVE, the saved checkpoint, instead +of EMACS; then load JOURNAL and do M-X Replay Journal File as described +above. Be sure to delete the checkpoint if you are finished with it, +since it tends to be large. Delete them also when you log out; it may +be possible to have a command file which deletes them automatically when +you log out. Checkpoint files more than a day old may be deleted by +others without notice; but don't leave it up to them. + + +EMACS Node: Bugs, Previous: Journals, Up: Top, Next: PICTURE + +Reporting Bugs + +Sometimes you will encounter a bug in EMACS. To get it fixed, you must +report it. It is your duty to do so; but you must know when to do so +and how if it is to be constructive. + +When Is There a Bug + +If EMACS executes an illegal instruction, or dies with an operating +system error message that indicates a problem in the program (as opposed +to "disk full"), then it is certainly a bug. + +If EMACS updates the display in a way that does not correspond to what +is in the buffer, then it is certainly a bug. If a command seems to do +the wrong thing but the problem is gone if you type C-L, then it is a +case of incorrect display updating. + +Taking forever to complete a command can be a bug, but you must make +certain that it was really EMACS's fault. Some commands simply take a +long time. Quit or restart EMACS and type Help L to see whether the +keyboard or line noise garbled the input; if the input was such that you +KNOW it should have been processed quickly, report a bug. If you don't +know, try to find someone who does know. + +If a command you are familiar with causes an EMACS error message in a +case where its usual definition ought to be reasonable, it is probably a +bug. + +If a command does the wrong thing, that is a bug. But be sure you know +for certain what it ought to have done. If you aren't familiar with the +command, or don't know for certain how the command is supposed to work, +then it might actually be working right. Rather than jumping to +conclusions, show the problem to someone who knows for certain. + +Finally, a command's intended definition may not be best for editing +with. This is a very important sort of problem, but it is also a matter +of judgement. Also, it is easy to come to such a conclusion out of +ignorance of some of the existing features. It is probably best not to +complain about such a problem until you have checked the documentation +in the usual ways (INFO and Help), feel confident that you understand +it, and know for certain that what you want is not available. If you +feel confused about the documentation instead, then you don't have +grounds for an opinion about whether the command's definition is +optimal. Make sure you read it through and check the index or the menus +for all references to subjects you don't fully understand. If you have +done this diligently and are still confused, or if you finally +understand but think you could have said it better, then you have a +constructive complaint to make about the documentation. It is just as +important to report documentation bugs as program bugs. + +How to Report a Bug + +When you decide that there is a bug, it is important to report it and to +report it in a way which is useful. What is most useful is an exact +description of what commands you type, starting with a fresh EMACS just +loaded, until the problem happens. Send the bug report to +BUG-EMACS@MIT-AI. + +The most important principle in reporting a bug is to report FACTS, not +hypotheses or conditions. It is always easier to report the facts, but +people seem to prefer to strain to think up explanations and report them +instead. If the explanations are based on guesses about how EMACS is +implemented, they will be useless; we will have to try to figure out +what the facts must have been to lead to such speculations. Sometimes +this is impossible. But in any case, it is unnecessary work for us. + +For example, suppose that you type C-X C-V GLORP;BAZ UGH, visiting a +file which (you know) happens to be rather large, and EMACS prints out +"I feel pretty today". The best way to report the bug is with a +sentence like the preceding one, because it gives all the facts and +nothing but the facts. + +Do not assume that the problem is due to the size of the file and say +"When I visit a large file, EMACS prints out 'I feel pretty today'". +This is what we mean by "guessing explanations". The problem is just as +likely to be due to the fact that there is a "Z" in the filename. If +this is so, then when we got your report, we would try out the problem +with some "big file", probably with no "Z" in its name, and not find +anything wrong. There is no way in the world that we could guess that +we should try visiting a file with a "Z" in its name. + +Alternatively, the problem might be due to the fact that the file starts +with exactly 25 spaces. For this reason, you should make sure that you +don't change the file until we have looked at it. Suppose the problem +only occurs when you have typed the C-X C-A command previously? This is +why we ask you to give the exact sequence of characters you typed since +loading the EMACS. + +You should not even say "visit the file ..." instead of "C-X C-V" unless +you know that it makes no difference which visiting command is used. +Similarly, rather than saying "if I have three characters on the line", +say "after I type A B C C-P", if that is the way you entered +the text. A journal file containing the commands you typed to reproduce +the bug is a very good form of report. + +If you are not in Fundamental mode when the problem occurs, you should +say what mode you are in. + +Be sure to say what version of EMACS and TECO are running. If you don't +know, type Meta-Altmode QEMACS Version= FS Version=  and EMACS will +print them out. (This is a use of the minibuffer. *Note Minibuffer: +Minibuffer.) + +If the bug occurred in a customized EMACS, or with several optional +libraries loaded, it is helpful to try to reproduce the bug in a more +standard EMACS with fewer libraries loaded. It is best if you can make +the problem happen in a completely standard EMACS with no optional +libraries. If the problem does NOT occur in a standard EMACS, it is +very important to report that fact, because otherwise we will try to +debug it in a standard EMACS, not find the problem, and give up. If the +problem does depend on an init file, then you should make sure it is not +a bug in the init file by complaining to the person who wrote the file, +first. He should check over his code, and verify the definitions of the +TECO commands he is using by looking in INFO;TECORD >. Then if he +verifies that the bug is in EMACS he should report it. We cannot be +responsible for maintaining users' init files; we might not even be able +to tell what they are supposed to do. + +If you can tell us a way to cause the problem without reading in any +files, please do so. This makes it much easier to debug. If you do +need files, make sure you arrange for us to see their exact contents. +For example, it can often matter whether there are spaces at the ends of +lines, or a line separator after the last line in the buffer (nothing +ought to care whether the last line is terminated, but tell that to the +bugs). + +If EMACS gets an operating system error message, such as for an illegal +instruction, then you can probably recover by restarting it. But before +doing so, you should make a dump file. If you restart or continue the +EMACS before making the dump, the trail will be covered and it will +probably be too late to find out what happened. Use the DDT command + + + :PDUMP CRASH;EMACS + +(or use any other suitable filename) to do this. Your bug report should +contain the filename you used for the dump, and the error message +printed when the EMACS stopped, as well as the events leading up to the +bug. The first number in the error message is the PC, which is not +recorded by :PDUMP, so it must be copied precisely. Also type .JPC/ and +include DDT's response in your report. + +A dump is also useful if EMACS gets into a wedged state in which +commands that usually work do strange things. + + +EMACS Node: PICTURE, Previous: Bugs, Up: Top, Next: Sort + +The PICTURE Subsystem, an Editor for Text Pictures + +If you want to create a picture made out of text characters (for +example, a picture of the division of a register into fields, as a +comment in a program), the PICTURE package can make it easier. + +Do M-X Load LibPICTURE, and then M-X Edit Picture is available. Do +M-X Edit Picture with point and mark surrounding the picture to be +edited. Edit Picture enters a recursive editing level (which you exit +with C-M-C, as usual) in which certain commands are redefined to make +picture editing more convenient. + +While you are inside Edit Picture, all the lines of the picture are +padded out to the margin with spaces. This makes two-dimensional motion +very convenient; C-B and C-F move horizontally, and C-N and C-P move +vertically without the inaccuracy of a ragged right margin. When you +exit from Edit Picture, spaces at the ends of lines are removed. +Nothing stops you from moving outside the bounds of the picture, but if +you make any changes there slightly random things may happen. + +Edit Picture makes alteration of the picture convenient by redefining +the way printing characters and Rubout work. Printing characters are +defined to replace (overwrite) rather than inserting themselves. Rubout +is defined to undo a printing character: it replaces the previous +character with a space, and moves back to it. + +Return is defined to move to the beginning of the next line. This makes +it usable for moving to the next apparently blank (but actually filled +with nothing but spaces) line, just as you use Return normally with +lines that are really empty. C-O creates new blank lines after point, +but they are created full of spaces. + +Tab is redefined to indent (by moving over spaces, not inserting them) +to under the first non-space on the previous line. Linefeed is as usual +equivalent to Return followed by Tab. + +Four movement-control commands exist to aid in drawing vertical or +horizontal lines: If you give the command M-X Up Picture Movement, each +character you type thereafter will cause the cursor to move up instead +of to the right. Thus if you want to draw a line of dashes up to some +point, you can give the command Up Picture Movement, type enough dashes +to make the line, and then give the command Right Picture Movement to +put things back to normal. Similarly, there are functions to cause +downward and leftward movement: Down Picture Movement and Left Picture +Movement. These commands remain in effect only until you exit the Edit +Picture function, (One final note: you can use these cursor movement +commands outside of Edit Picture too, even when not in Overwrite mode. +You have to be somewhat careful though.) + +Possible future extensions include alteration of the kill and un-kill +commands to replace instead of deleting and inserting, and to handle +rectangles if two corners are specified using point and the mark. + +The DRAW library is a user-contributed library containing other commands +useful for editing pictures. + + +EMACS Node: Sort, Previous: PICTURE, Up: Top + +Sorting Functions + +The SORT library contains functions called Sort Lines, Sort Paragraphs +and Sort Pages, to sort the region alphabetically line by line, +paragraph by paragraph or page by page. For example, Sort Lines +rearranges the lines in the region so that they are in alphabetical +order. + +Paragraphs are defined in the same way as for the paragraph-motion +functions (*Note Paragraphs: Sentences.) and pages are defined as for +the page motion commands (*Note Pages: Pages.). All of these functions +can be undone by the Undo command (*Note Undo: Undo.). They take no +arguments. + +You can rearrange pages to any way you like using the functions Make +Page Permutation Table and Permute Pages From Table. Make Page +Permutation Table starts you editing a table containing the first line +of each page. This table is kept in a buffer named *Permutation Table*. +You specify the new ordering for the pages by rearranging the first +lines into the desired order. You can also omit or duplicate pages by +omitting or duplicating the lines. + +When you are finished rearranging the lines, use Permute Pages From +Table to rearrange the entire original file the same way. Reselect the +original buffer first. The permuted version is constructed in a buffer +named *Permuted File*. The original buffer is not changed. You can use +Insert Buffer to copy the data into the original buffer. + + +EMACS Node: Ideal, Previous: Characters, Up: Characters + +Ideal Keyboards + +An ideal EMACS keyboard can be recognized because it has a Control key +and a Meta key on each side, with another key labeled Top above them. + +On an ideal keyboard, to type any character in the 9-bit character set, +hold down Control or Meta as appropriate while typing the key for the +rest of the character. To type C-M-K, type K while holding down Control +and Meta. + +You will notice that there is a key labeled "Escape" and a key labeled +"Alt". The Altmode character is the one labeled "Alt". "Escape" has +other functions entirely; it is handled by ITS and has nothing to do +with EMACS. While we are talking about keys handled by ITS, on Meta +keyboards the way to interrupt a program is CALL, rather than Control-Z, +and entering communicate mode uses the BACK-NEXT key rather than +Control-_. CALL echoes as , but if you type C-Z it is just an +ordinary character which happens to be an EMACS command to return to the +superior. Similarly, BACK-NEXT echoes as  but if you type  it is +just an EMACS command which happens not to be defined. + +The key labeled "Top" is an extra shift key. It is used to produce the +peculiar "SAIL" graphics characters which appear on the same keys as the +letters. The "Shift" key gets you upper-case letters, but "Top" gets +you the SAIL characters. As EMACS commands, these characters are +normally self-inserting, like all printing characters. But once +inserted, SAIL characters are really the same as ASCII control +characters, and since characters in files are just 7 bits there is no +way to tell them apart. EMACS can display them either as ASCII control +characters, using an uparrow or caret to indicate them, or it can +display them as SAIL characters, whichever you like. The command +Control-Alpha (SAIL Character Mode) toggles the choice. Alpha is a SAIL +character and you can only type it on a terminal with a Top key, but +only those terminals can display the SAIL characters anyway. SAIL +characters are displayed if the variable SAIL Character Mode is nonzero. + +One other thing you can do with the Top key is type the Help character, +which is Top-H on these keyboards. BACK-NEXT H also works, though. + +For inserting an Altmode, on an ideal keyboard you can type C-M-Altmode. +C-Altmode is a synonym for C-M-C (^R Exit). + +The "bit prefix" characters that you must use on other terminals are +also available on terminals with Meta keys, in case you find them more +convenient or get into habits on those other terminals. *Note Bit +Prefix: Characters. + +To type numeric arguments on these keyboards, type the digits or minus +sign while holding down either Control or Meta. + + +EMACS Node: EditKey, Previous: Characters, Up: Characters + +Keyboards with an "Edit" key + +Keyboards with Edit keys probably belong to Datamedia or Teleray +terminals. The Edit and Control keys are a pair of shift keys. Use the +Control key to type Control characters and the Edit key to type Meta +characters. Thus, the 9-bit EMACS character C-M-Q is typed by striking +the "Q" key while holding down "Edit" and "Control". + +While the Edit key is a true independent bit which can be combined with +anything else you can type, the Control key really means "ASCII +control". Thus, the only Control characters you can type are those +which exist in ASCII. This includes C-A through C-Y, C-], C-@, C-\, and +C-^. C-Z and C-_ can be typed on the terminal but they are intercepted +by the operating system and therefore unavailable as EMACS commands. +C-[ is not available because its spot in ASCII is pre-empted by Altmode. +The corresponding Control-Meta commands are also hard to type. If you +can't type C-; directly, then you also can't type C-M-; directly. + +Though you can't type C-; directly, you can use the bit prefix character +C-^ and type C-^ ;. Similarly, while you can't type C-M-;, you can use +the Control-Meta prefix C-C and type C-C ;. Because C-^ is itself +awkward, we have designed the EMACS command set so that the hard-to-type +Control (non-Meta) characters are rarely needed. + +In order to type the Help character you must actually type two +characters, C-_ and H. C-_ is an escape character for ITS itself, and +C-_ followed by H causes ITS to give the Help character as input to +EMACS. + +To type numeric arguments, it is best to type the digits or minus sign +while holding down the Edit key. + + +EMACS Node: Losers, Previous: Characters, Up: Characters + +ASCII Keyboards + +An ASCII keyboard allows you to type in one keystroke only the command +characters with equivalents in ASCII. No Meta characters are possible, +and not all Control characters are possible either. The Control +characters which you can type directly are C-A through C-Y, C-], C-@, +C-\, and C-^. C-Z and C-_ can be typed on the terminal but they +are intercepted by the operating system and therefore unavailable as +EMACS commands. C-[ is not available because its spot in ASCII is +pre-empted by Altmode. + +Those characters which you can't type directly can be typed as two +character sequences using the bit prefix characters Altmode, C-C and +C-^. Altmode turns on the Meta bit of the character that follows it. +Thus, M-A can be typed as Altmode A, and C-M-A as Altmode C-A. Altmode +can be used to get almost all of the characters that can't be typed +directly. C-C can be used to type any Control-Meta character, including +a few that Altmode can't be used for because the corresponding non-Meta +character isn't on the keyboard. Thus, while you can't type C-M-; as +Altmode Control-;, since there is no Control-; in ASCII, you can type +C-M-; as C-C ;. The Control (non-Meta) characters which can't be typed +directly require the use of C-^, as in C-^ < to get the effect of C-<. +Because C-^ by itself is hard to type, the EMACS command set is arranged +so that most of these non-ASCII Control characters are not very +important. Usually they have synonyms which are easier to type. In +fact, in this manual only the easier-to-type forms are usually +mentioned. + +In order to type the Help character you must actually type two +characters, C-_ and H. C-_ is an escape character for ITS itself, and +C-_ followed by H causes ITS to give the Help character as input to +EMACS. + +On ASCII keyboards, you can type a numeric argument by typing an Altmode +followed by the minus sign and/or digits. Then comes the command for +which the argument is intended. For example, type Altmode 5 C-N to move +down five lines. If the command is a Meta command, it must have an +Altmode of its own, as in Altmode 5 Altmode F to move forward five +words. + +Note to customizers: this effect requires redefining the Meta-digit +commands, since the Altmode and the first digit amount to a Meta-digit +character. The new definition is ^R Autoarg, and the redefinition is +done by the default init file. + +If you use numeric arguments very often, and you dislike having to start +one with an Altmode, you might enjoy using Autoarg mode, in which you +can specify a numeric argument by just typing the digits. *Note +Arguments: Arguments, for details. + + +EMACS Node: NoLowerCase, Up: Characters + +Upper-case-only Terminals + +On terminals lacking the ability to display or enter lower case +characters, a special input and output case-flagging convention has been +defined for editing files which contain lower case characters. + +The customary escape convention is that a slash prefixes any upper case +letter; all unprefixed letters are lower case (but see below for the +"lower case punctuation characters"). This convention is chosen because +lower case is usually more frequent in files containing any lower case +at all. Upper case letters are displayed with a slash ("/") in front. +Typing a slash followed by a letter is a good way to insert an upper +case letter. Typing a letter without a slash inserts a lower case +letter. For the most part, the buffer will appear as if the slashes had +simply been inserted (type /A and it inserts an upper case A, which +displays as /A), but cursor-motion commands will reveal that the slash +and the A are really just one character. Another way to insert an +upper-case letter is to quote it with C-Q. + +Note that this escape convention applies only to display of the buffer +and insertion in the buffer. It does not apply to arguments of commands +(it is hardly ever useful for them, since case is ignored in command +names and most commands' arguments). Case conversion is performed when +you type commands into the minibuffer, but not when the commands are +actually executed. + +The ASCII character set includes several punctuation characters whose +codes fall in the lower case range and which cannot be typed or +displayed on terminals that cannot handle lower case letters. These are +the curly braces ("{" and "}"), the vertical bar ("|"), the tilde ("~"), +and the accent grave ("`"). Their upper case equivalents are, +respectively, the square brackets ("[" and "]"), the backslash ("\"), +the caret ("^"), and the atsign ("@"). For these punctuation +characters, EMACS uses the opposite convention of that used for letters: +the ordinary, upper case punctuations display as and are entered as +themselves, while the lower case forms are prefixed by slashes. This is +because the "lower case" punctuations are much less frequently used. +So, to insert an accent grave, type "/@". + +When the slash escape convention is in effect, a slash is displayed and +entered as two slashes. + +This slash-escape convention is not normally in effect. To turn it on, +the TECO command -1$ (minus one dollar sign, not Altmode!) must be +executed. The easiest way to do this is to use the minibuffer: Altmode +Altmode -1$ Altmode Altmode. To turn off the escape convention (for +editing a file of all upper case), the command is 0$ (zero dollar sign), +or Altmode Altmode 0$ Altmode Altmode. If you use such a bad terminal +frequently, you can define yourself an EMACS extension, a command to +turn slash-escape on and off. + +The lower case editing feature is actually more flexible than described +here. Refer to the TECO commands F$ (dollar sign) and FS CASE, using +M-X TECDOC, for full details. *Note FS Flags: FS Flags. + +* Note Case: Case, for commands to change the case of text already in +the buffer. + + +EMACS Node: Printing, Up: Characters + +Use of EMACS from Printing Terminals + +While EMACS was designed to be used from a display terminal, you can use +it effectively from a printing terminal. You cannot, however, learn +EMACS using one. + +All EMACS commands have the same editing effect from a printing terminal +as they do from a display. All that is different is how they try to +show what they have done. EMACS attempts to make the same commands that +you would use on a display terminal act like an interactive line-editor. +It does not do as good a job as editors designed originally for that +purpose, but it succeeds well enough to keep you informed of what your +commands are accomplishing, provided you know what they are supposed to +do and know how they would look on a display. + +The usual buffer display convention for EMACS on a printing terminal is +that the part of the current line before the cursor is printed out, with +the cursor following (at the right position in the line). What follows +the cursor on the line is not immediately visible, but normally you will +have a printout of the original contents of the line a little ways back +up the paper. For example, if the current line contains the word +"FOOBAR", and the cursor is after the "FOO", just "FOO" would appear on +the paper, with the cursor following it. Typing the C-F command to move +over the "B" would cause "B" to be printed, so that you would now see +"FOOB" with the cursor following it. All forward-motion commands that +move reasonably short distances print out what they move over. + +Backward motion is handled in a complicated way. As you move back, the +terminal backspaces to the correct place. When you stop moving back and +do something else, a linefeed is printed first thing so that the +printing done to reflect subsequent commands does not overwrite the text +you moved back over and become garbled by it. The Rubout command acts +like backward motion, but also prints a slash over the character rubbed +out. Other backwards deletion commands act like backward motion; they +do not print slashes (it would be an improvement if they did). + +One command is different on a printing terminal: C-L, which normally +means "clear the screen and redisplay". With no argument, it retypes +the entire current line. An argument tells it to retype the specified +number of lines around the current line. + +Unfortunately, EMACS cannot perfectly attain its goal of making the text +printed on the current line reflect the current line in the buffer, and +keeping the horizontal position of the cursor correct. One reason is +that it is necessary for complicated commands to echo, but echoing them +screws up the "display". The only solution is to type a C-L whenever +you have trouble following things in your mind. The need to keep a +mental model of the text being edited is, of course, the fundamental +defect of all printing terminal editors. + +Note: it is possible to make a specific command print on a printing +terminal in whatever way is desired, if that is worth while. For +example, Linefeed knows explicitly how to display itself, since the +general TECO redisplay mechanism isn't able to handle it. Suggestions +for how individual commands can display themselves are welcome, as long +as they are algorithmic rather than simply of the form "please do the +right thing". + + +Tag Table: +EMACS Node: Top²09 +EMACS Node: Intro¶773 +EMACS Node: Glossary¹681 +EMACS Node: CommandIndex³5973 +EMACS Node: LibCat·9137 +EMACS Node: VarIndex¸7509 +EMACS Node: Screen±13989 +EMACS Node: ModeLine±17438 +EMACS Node: Characters±24071 +EMACS Node: Basic±35352 +EMACS Node: Arguments±42615 +EMACS Node: M-X±46508 +EMACS Node: MMArcana±54326 +EMACS Node: Subsystems±61347 +EMACS Node: Mail±63506 +EMACS Node: Recursive±65270 +EMACS Node: Exiting±68660 +EMACS Node: Help±70488 +EMACS Node: Mark±76595 +EMACS Node: Killing±83199 +EMACS Node: Un-Killing±88085 +EMACS Node: Copying±93435 +EMACS Node: Search±96759 +EMACS Node: Text²03278 +EMACS Node: Words²04795 +EMACS Node: Sentences²08183 +EMACS Node: TextIndent²12433 +EMACS Node: Filling²18122 +EMACS Node: Case²23213 +EMACS Node: Fonts²25209 +EMACS Node: Underlining²27288 +EMACS Node: SCRIBE²29869 +EMACS Node: Dissociation²34626 +EMACS Node: Fixit²36762 +EMACS Node: Files²44553 +EMACS Node: Visiting²45495 +EMACS Node: Revert²52094 +EMACS Node: AutoSave²53412 +EMACS Node: ListDir²59263 +EMACS Node: CleanDir²60970 +EMACS Node: DIRED²62835 +EMACS Node: Filadv²69240 +EMACS Node: DirComp²72123 +EMACS Node: Buffers²74572 +EMACS Node: Display²81550 +EMACS Node: Windows²87927 +EMACS Node: Narrowing²95219 +EMACS Node: Pages²97077 +EMACS Node: PAGE³01621 +EMACS Node: Replace³05800 +EMACS Node: TECOsearch³11533 +EMACS Node: MajorModes³13114 +EMACS Node: Programs³16133 +EMACS Node: Compile³17752 +EMACS Node: Indenting³19773 +EMACS Node: Matching³22387 +EMACS Node: Comments³26155 +EMACS Node: Lisp³32485 +EMACS Node: Lists³34325 +EMACS Node: Defuns³40477 +EMACS Node: Grinding³41431 +EMACS Node: MIDAS³50058 +EMACS Node: Other Langs³53152 +EMACS Node: MinorModes³55133 +EMACS Node: Libraries³59964 +EMACS Node: Variables³63888 +EMACS Node: Syntax³69225 +EMACS Node: FS Flags³75231 +EMACS Node: Init³78574 +EMACS Node: Locals³89226 +EMACS Node: KBDMAC³93093 +EMACS Node: Minibuffer³99272 +EMACS Node: Quitting´05330 +EMACS Node: Lossage´07693 +EMACS Node: Undo´14100 +EMACS Node: Journals´15918 +EMACS Node: Bugs´25961 +EMACS Node: PICTURE´33799 +EMACS Node: Sort´36916 +EMACS Node: Ideal´38378 +EMACS Node: EditKey´41130 +EMACS Node: Losers´42869 +EMACS Node: NoLowerCase´45618 +EMACS Node: Printing´48845 + End Tag Table: diff --git a/src/emacs/*.emacs b/src/emacs/*.emacs new file mode 100755 index 00000000..6cec2d84 --- /dev/null +++ b/src/emacs/*.emacs @@ -0,0 +1,76 @@ +!* -*-TECO-*- *! + +!* This is the default init file for EMACS. + Anything in the buffer when you start this + will be used instead of the JCL. + +It is generally a bad idea to try to make an init file +by copying this one with changes. The right way, usually, is +to make your own small init file which jumps to this one at the end, +as described in INFO;CONV >. *! + + fs qp ptr[9 !* save pdl pointer for unwinding! + + FQ(0FO..QAuto Save Filenames)-1"L + FS MSNAME:F6[0 + :I*DSK:0;_SAV00 > M.VAuto Save Filenames ]0' + +!* On non-meta keyboards, allow Alt 1 2 to mean an arg of 12, as long as user! +!* has not reconnected meta-digits. Similarly for meta-minus.! + FS %TOFCI"E !* 9-bit keyboard.! + M.M ^R Autoarg[0 460.-1[1 f..0fs^RInit[2 + 10< %1@fs^RCMac-q2"e q0,q1@fs^RCMac' > + f..-fs^RInit-q..-"e Q0U..-' + ]2 ]1 ]0' + + fsxunamef(:f6[1)-(fshsname)"e et.FOO. >'"# et1 >' ]1 + FS MSNAME FS D SNAME + +!* Now we have done enough that things will be OK if the EVARS file gets an! +!* error and throws back to the ^R. The EVARS file should not be processed! +!* twice, e.g. in case it loads libraries, and a dumped EMACS should be able! +!* to jump to the default init. Hence the variable check.! + + 0fo..qInit Vars Processed"e !* If not yet done it, process! + M(M.M & Process Init Vars) !* FOO;FOO EVARS or EMACS.VARS.! + 1m.vInit Vars Processedw' !* Do not do it again.! + + FS XJNAME :F6 [J + F[D FILE + FS %OPLSP(F~JLISPT"'E)(F~JMACST"'E)"N + 1,M(M.M& Get Library Pointer)LISPT"e !* Load LISPT if not! + m(m.m Load Library)LISPT'' !* loaded already.! + F~JMAILT "E :IEditor TypeMAILT + :iDefault Major ModeText + f~ModeText"n M(M.MTEXT MODE)' fr !* Text mode if not in it yet.! + 0FO..Q Inhibit Help Message"E + FTEdit escape from :MAIL to EMACS. Type ^C^C to return to MAIL. +'' + F]D FILE + + 1:< QFind File Inhibit Write UInhibit Write > + +!* Process the JCL! + 0[0 0[1 + Z"E FJ' ZJ !* Get JCL, or use whatever previous init file left in buffer.! + ."N !* Process JCL command - extract filenames and commands! + 0,-1A-î"E -2D' !* REMOVE CRLF AT END IF ANY *! + J :S"N .,Z^ FX1 -D' !* IF COMMANDS TO EXECUTE, PUT THEM IN Q1! + HFX0' !* IF FILE TO BE READ, PUT NAME IN Q0! + HK 0FS MODIFIED + 0FO..Q Inhibit Help Message"E + Q0"E Q1"E !* If no commands / file to read, offer help.! + qEMACS Version:\[1 !* get version no. as string! + FTEMACS Editor, version 1 - type Help + FS %TOFCI"N FT(Top-H)' + "# FT(^_H)' + FT for help. + ]1 + ''' + FQ0"G + 0fo..qTags Find File"e + QInhibit Write, M(M.M Visit File)0' !* Visit file specified.! + "# m(m.mFind File)0'' !* unless user generally likes Find File,! + !* in which case use it! + Q1"N M1' !* Execute any commands from JCL! + q9fsqpunwind