@make(INFO)@Comment[-*-Text-*-] @Device(INFO) @Comment[ This is the SCRIBE source from which the INFO file for EMACS and the EMACS GUIDE are generated. Control characters are represented as two characters, an uparrow ( ) and the letter. SCRIBE requires two @'s whenever one is wanted. The SCRIBE "@:" construct must be used when a sentence ends with a one-letter word. "@." must be used when a sentence end appears to occur after an abbreviation. The SCRIBE constructs @U and @I cannot be used. Instead, use @XXU and @XXI for underlining and italicizing. These do nothing in the INFO version. Alternatively, use @XXUU and @XXII, which turn into all caps in the INFO version. ] @Define(Commands=Description,LeftMargin 16,Indent -8,Spread 0) @Define(WideCommands=Description,LeftMargin 20,Indent -12,Spread 0) @Define(DoubleWideCommands=Description,LeftMargin 24,Indent -16,Spread 0) @Define(GrossCommands=Description,LeftMargin 16,Indent -16,Spread 1) @Case(draft,ITS {@Textform[Twenex="",ITS="@Parm(text)",CC="C-C",CMC="C-M-C",TAGS=":TAGS"]}) @Case(draft,Twenex {@Textform[ITS="",Twenex="@Parm(text)",CC="C-Z",CMC="C-M-Z",TAGS="TAGS"]}) @Comment< These do not work! @ITS{@Textform[C-C="C-C", C-M-C="C-M-C"]} @Twenex{@Textform[C-C="C-Z", C-M-C="C-M-Z"]} They all get "Textform not at beginning of manuscript"> @style(stringmax=20000) @string(Filename="EMACS") @Comment( Here starts the actual text of the manual ) @INFO{@Verbatim{ 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. }} @Node(Name="Top", Up="(DIR)") @String(Next-Node-Name="") @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. * Characters:: EMACS's character sets; usage from deficient (ie, standard ASCII or upper case only) keyboards. * Screen:: How to interpret what you see on the screen. * Basic:: The most basic editing commands. * Arguments:: Giving numeric arguments to 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. * M-X:: Issuing long-named "extended" commands. * Help:: Commands for asking EMACS about its commands. * Subsystems:: Commands which 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. * Unwedging:: What to do if EMACS is hung. * Undo:: Undoing a command which destroyed your text. * Bugs:: How and when to report a bug. * Display:: Controlling what text is displayed. * Files:: All about handling files. * Search:: Finding or replacing occurrences of a string. * Fixit:: Commands especially useful for fixing typos. * Windows:: Viewing two pieces of text at once. * MajorModes:: Text mode vs. Lisp mode vs. MIDAS mode ... * MinorModes:: Some other useful options you can turn on and off. * Libraries:: Loading additional libraries of commands (subsystems). * Variables:: Named variables: what they do and how to use them. * Init:: Init files and how to customize your EMACS. * Text:: Commands and modes for editing English. * Programs:: Commands and modes for editing programs. * Narrowing:: Commands for narrowing view to part of the buffer. * Paging:: Commands for dealing with pages in files. * Minibuffer:: How to escape to TECO. * KBDMAC:: Subsystem for abbreviating a sequence of commands. * PICTURE:: Subsystem for editing pictures made out of characters. * Sort:: Commands for sorting part of the buffer. @Twenex{* Misc:: A few random functions }* Abbrev: (WORDAB) How to define text abbreviations to reduce the number of characters you must type. * 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. * 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. @ITS{* RMAIL:(RMAIL) Subsystem for editing mail. }* Babyl: (Babyl)@ITS{ Babyl is, like RMail, an EMACS mail subsystem. It differs from RMail in some respects, in particular: it runs on TENEX and TWENEX. }@Twenex{ For reading mail. }* INFO: (INFO) Subsystem for reading documentation files. * 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: (EMACS;CONV) EMACS internals. Customization. Init files. * TMACS: (TMACS)Top The TMACS library contains an assortment of EMACS commands and subroutines. Here are some other nodes which are really inferiors of the ones already listed, just 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. * Syntax:: The syntax table. * Visiting:: How to visit a file for editing. * Revert:: How to cancel some changes you have made. * Buffers:: How to keep several files in core at once. * Locals:: How to make a file say what mode it should be edited with. * AutoSave:: Protection from system crashes. * CleanDir:: Deleting piled up old versions of files. * DIRED:: Deleting files by "editing your directory". * Filadv:: Miscellaneous file commands. @ITS{* DirComp:: Comparing two directories. }* Replace:: Replace one string by another, etc. * TECOsearch:: TECO search strings. * 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 which 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. @ITS{* Fonts:: Font change commands. * Underlining:: Underlining commands. }* PAGE:: Macros for editing only one page at a time. * Printing:: Printing terminals. ] @Manual{ @begin(TitlePage) @begin(TitleBox) @MajorHeading(EMACS Manual for @ITS{ITS}@Twenex{Twenex} Users) @MajorHeading(by) @MajorHeading(Richard M. Stallman) This manual corresponds to EMACS version 146, @Value(Date) @end(TitleBox) @Begin(ResearchCredit) 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-75-C-0643. @End(ResearchCredit) @End(TitlePage) @PrefaceSection(Preface) This manual documents the use and simple customization of the display editor EMACS with the @ITS{ITS}@Twenex{Twenex (officially known as "Tops-20")} 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 a newcomer to EMACS first use the on-line learn-by-doing tutorial @Twenex{TEACH-EMACS}@Its{TEACHEMACS}. With the tutorial, written specifically for new users, 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 this, go straight through the manual, reading each section until it becomes more detailed than you are interested in, stopping before the chapter on customization. To find the documentation on a particular command, look in the index if you know what the command is. If you know vaguely what the command does, look in the command index. The command index contains a line or two about each commands, with related commands grouped together. Each command also has a cross reference to the section of the manual which describes the command in more detail. There is also a glossary, with a cross reference for each term. The manual is available in three forms: the published version, the LPT version, and the INFO version. The published version is printed by the Artificial Intelligence lab. The LPT version is available on line for printing on unsophisticated hard copy devices such as terminals and line printers. The INFO version is for on-line perusal with the INFO program. All three are substantially the same. @ITS{EMACS also runs on the Twenex ("Tops-20") operating system.} For a copy of EMACS for use on Twenex systems, write to me, Richard M. Stallman, at @display[ MIT Artificial Intelligence Lab 545 Tech Square, rm 913 Cambridge, MA 02139 ] The similarity in their DEC-given names often leads people to think that "Tops-10" and "Tops-20" are similar and that a program which works on Twenex should also run on Bots-10. In fact, they are as different as can be, and Bots-10 has deficiencies which would make it difficult to convert EMACS and maintain its efficiency. If you are seriously interested in attempting a conversion project, please talk with me. For more information on the philosophy of EMACS and the lessons learned from its development, write to me for a copy of the paper, "EMACS, the Extensible, Customizable Self-Documenting Display Editor". @verbatim[ / 2 \ 1/2 < X > \ / ] } @Comment(from now on, things are mostly version-independent) @Node(Name="Intro", Prev="Top", Next="Glossary") @Chapter[Introduction] You are about to read about EMACS, an advanced, extensible, customizable, self-documenting 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 the user types his commands. @Note(Node="Screen", Name="Display"). We call it a real-time editor because the display is updated very frequently, usually after each character or pair of characters the user types. This minimizes the amount of information the user must keep in his head as he edits. @Note(Node="Basic", Name="Real-time"). 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-documentation 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(Node="Help"). Customization means changing 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(Node="MajorModes", Name="Customization"). Extensibility means that you can go beyond simple customization and write entirely new commands, programs in the language TECO. EMACS is an "online extensible" system, which means that it is divided into many functions which call each other, any of which can be redefined by the user. 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. Though 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. @InfoNote(Name="TECO", File="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 which are useful primarily to the extension writer. @INFO{ @Node(Name="Glossary", Prev="Intro", Next="CommandIndex") @Include(GLOSS.MSS) @Node(Name="CommandIndex", Prev="Glossary", Next="Characters") @Include(COMMANDS.MSS) } @Node(Name="Characters", Prev="CommandIndex", Next="Screen") @Chapter[Character Sets and Command Input Conventions] In this chapter we introduce the terminology and concepts used to talk about EMACS commands. In particular, EMACS is designed for a kind of keyboard which can type 512 different characters, instead of the 128 which ordinary ASCII keyboards can send. @Section[The 9-bit Command Character Set] @index{control}@index{meta}@index{Altmode}@index{Rubout}@index{Space}@index{}@index{Return}@index{character set} @index{C-}@index{M-}@index{ASCII}@index{metizer} EMACS uses a special 512-character "9-bit" character set for its keyboard commands. Some keyboards can generate the whole 9-bit character set themselves. Ordinary ASCII keyboards cannot, so two-character sequences are used to represent the characters which have no equivalents in ASCII. The 9-bit character set applies only to keyboard input. Characters in files edited with EMACS are ordinary 7-bit ASCII characters. The 9-bit character set starts with the 7-bit ASCII character set and adds two modifier bits called "Control" and "Meta", abbreviated "C" and "M". Ideally, EMACS is used with a terminal equipped with keys for both Control and Meta. Thus, the character which is made up of the ASCII character "A" and the Control and Meta bits is called "Control-Meta-A" or "C-M-A". On an ideal terminal, this character is made by typing an "A" while holding down the Control and Meta keys. "C-Space" is the ASCII character space plus the Control bit, and on an ideal terminal it is made by typing a space while holding down the Control key. Since "A" and "a" are distinct characters, so are Control-A and Control-a. However, the normal definition of Control-a is "do a Control-A", so until you start customizing you can ignore the distinction. Unfortunately, not all terminals are ideal. Nonideal terminals are unable to send all of the 9-bit characters directly, so EMACS provides circumlocutions known as "bit prefix characters" (see below). In fact, the only ideal terminals are at MIT. @Twenex(So your terminal is certain to be more or less non-ideal.) Some 9-bit characters have special names which we always capitalize. Return or stands for the carriage return character, code 015. 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). In addition to the 9-bit command character set, there is one extra character called Help. It cannot be combined with Control or Meta. Its use is to ask for documentation, at any time. @ITS{How to type this character depends on the type of terminal you have.}@Twenex{ Because this character does not appear on the keyboard, some other character is used to represent it. The usual choice is Control-Underscore, code 337. What this means is that the 9-bit character Control-Underscore cannot be used because it is translated to Help instead.} The code used internally for Help is 4110. @section[Prefix Characters] @index{C-X}@index{prefix characters}@Index{Altmode}@Index{C-^}@Index{@CC[]} 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 @CC[] for Control and Meta together. Thus, C-^ < is a way of typing a Control-<, and @CC[] < can be used to type C-M-<. 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. @section[Commands versus Functions] 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 define commands directly. Instead, EMACS defines "functions", which have long names such as "^R Down Real Line", and then the functions are paired up with commands such as C-N through a 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 @xxi[because] it is connected to that function. We usually ignore this subtlety to keep things simple for the beginner. 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. 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 ". @Note(Name="Functions", Node="MMArcana"), for more information on this. @section[Notational Conventions for ASCII Characters] Control characters in files, your EMACS buffer, or TECO programs, are ordinary ASCII characters and are represented as uparrow or caret followed by the corresponding non-control character: control-E is represented as E. The special 9-bit character set applies only to typing EMACS commands. CRLF is the traditional term for a carriage return followed by a linefeed. This sequence of two characters is what separates lines in text being edited. Normally, EMACS commands make this sequence appear to be a single character, but TECO code must deal with the realities. A return or a linefeed which is not part of a CRLF is called "stray". EMACS usually treats them as just part of a line and displays them as M and J. Other ASCII characters with special names include tab (control-I, 011), backspace (control-H, 010), linefeed (control-J, 012), altmode (033), space (040), and rubout (177). Tab and control-I are different as 9-bit command characters, but when reduced to ASCII they become the same. Our convention is that names of ASCII characters are in lower case, while names of 9-bit command characters are in upper case. Most control characters when present in the EMACS buffer are 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. 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: . @INFO[This is also how it appears on the screen if you insert it in your file.] On some terminals, altmode looks just like the dollar sign character. If that's so on yours, you should assume that anything you see in @INFO{this document}@manual{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. @INFO{ 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. You can even use EMACS on a printing terminal or glass teletype. * Printing:: for how. }} @Node(Name="Screen", Prev="Characters", Next="Basic") @Chapter[The Organization of the Screen] @index{cursor}@index{screen} EMACS divides the screen into several areas, which contain different 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 @xxii[at] a character, point should be thought of as @xxii[between] two characters; it points @xxii[before] the character that the cursor appears on top of. Terminals have only one cursor, and when type out is in progress it must appear where the typing is being done. At those times, unfortunately, there is no way to tell where point is except by memory or dead reckoning. @index{error message} 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, documentation printed by Help C)@. 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 them. @index{echo area}@index{prompting} A few lines at the bottom of the screen compose what is called "the echo area". @INFO{It is the place where INFO types out the commands that you give it.} EMACS does not normally echo the commands it is given, but if you pause for more than a second in the middle of a multi-character command then the whole command (including what you have typed so far) will be echoed. This behavior is designed to give confident users optimum response, while giving nervous users information on what they are doing. EMACS also uses the echo area for reading and displaying the arguments for some commands, such as searches, and for printing information in response to certain commands such as C-X =. 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 the user at all times what is going on in the EMACS, and to show any reasons why commands will 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. } @Node(Name="ModeLine", Prev="Screen", Up="Screen") @Section[The Mode Line] @index{mode line}@index{more line} @Info{ The line above the echo area is known as the "more line" or the "mode line". It is the line that usually starts with "EMACS (something)". Its purpose is to tell the user at all times what is going on in the EMACS - primarily, to state any reasons why commands will 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. } The normal situation is that characters you type are interpreted as EMACS commands. When this is so, you are at "top level", and the mode line has this format: @Begin[Example,need 5lines] EMACS@ITS{ type} (major minor) bfr: file --pos-- * @end[Example] @ITS{ @index{Editor Type}@index{LEDIT}@index{MAILT}@index{RMAIL} "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 which you got by asking for an "edit escape" while composing mail to send. The type can also indicate a subsystem which is running, such as RMAIL. The variable Editor Type holds the type.} @index{major modes}@index{submode} "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 Text mode, Fundamental mode (which EMACS starts out in), Lisp mode, and others. @Note(Name="Major", Node="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 which causes your editing commands to be changed temporarily, but does not change @xxii[what] text you are editing. You can get out of any submode with @CMC[] or with C-]. @index{minor modes}@index{auto fill mode}@index{auto save mode}@index{atom word mode} @index{word abbrev mode}@index{overwrite mode}@index{keyboard macros} "minor" is a list of some of the minor modes which 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 in general but momentarily turned off (it was overridden the last time a file was selected). "Atom" means that Atom Word mode is on. "Abbrev" means that Word Abbrev mode is on. "Ovwrt" means that Overwrite mode is on. "Def" means that a keyboard macro is being defined; this is not exactly a minor mode but still useful to be told about. @Note(Name="Minor", Node="MinorModes") for more information. @index{buffers} "bfr" is the name of the currently selected buffer. A buffer is an object in EMACS which can hold a file being edited. There can be many buffers in one EMACS, each with its own name and holding its own file, 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 makes 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 which 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(Name="Buffers",Node="Buffers"), for how to use more than one buffer in one EMACS. @index{files} "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. If "(RO)" (for "read only") appears after the filename, it means that if you visit another file then changes you have made to this file will be lost unless you have explicitly asked to save them. @Note(Node="Visiting"), for more information. If there is no "(RO)", then visiting another file will always make EMACS offer to save your changes first, if there are any changes. The star at the end of the mode line means that there are changes in the buffer which 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--. @Section[Where is the Cursor in the File? In the Screen?] Other editors usually display, in their status line, things like the current page number and line number in the file. The way EMACS stores its text, there is no way to know those particular quantities without a lot of work. Displaying them all the time would be too slow to be borne. EMACS has commands for asking for this information, and other similar information. @index{C-X =}@index{echo area}@index{What Cursor Position} 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 the cursor which is quick to compute. It prints a line in the echo area that looks like this: @example[ 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 the cursor (101 is "A"), the point value is the number of characters in the buffer before the cursor, and the values in parentheses are the percentage of the buffer before the cursor and the total size of the buffer. @index{narrowing}@index{TECO} 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(Node="Narrowing"). @index{What Page} 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. So much for what the mode line says at top level. When the mode line doesn't start with "EMACS", and doesn't look anything like the breakdown given above, then EMACS is not at top level, and your typing will not be understood in the usual way. This is because you are inside a subsystem, such as INFO (@Note(Node="Subsystems").), or in a recursive editing level, such as Edit Options (@Note(Node="Recursive").). The mode line tells you what command you are inside. @Node(Name="Basic", Prev="Screen", Next="Arguments") @Chapter[Basic Editing Commands] We now give the basics of how to enter text with EMACS, 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 @ITS{TEACHEMACS}@Twenex{TEACH-EMACS} program. @Section[Inserting Text] @index{C-Q}@index{insertion}@index{quoting}@index{^R Quoted Insert} To insert printing characters into the text you are editing, just type them. Normally (when EMACS is at top levl), they are inserted into the text at the cursor, which moves forward. Any characters after the cursor move forward too. If the cursor is in between a FOO and a BAR, typing XX produces and displays FOOXXBAR with the cursor before the "B". This method of 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 C-Q command first. "C" refers to the Control bit. @Note(Name="Control", Node="Characters"). @index{Rubout}@index{deletion}@index{^R Backward Delete Character} To correct text you have just inserted you can use Rubout. Rubout deletes the character @xxii[before] the cursor (not the one that the cursor is on top of or under; that is the character @xxii[after] the cursor). The cursor and all characters after it move backwards. You can rub out a line boundary by typing Rubout when the cursor is at the beginning of a line. @index{Return}@index{CRLF}@index{^R CRLF} To end a line and start typing a new one, just type Return (^R CRLF). You can also type Return to break an existing line into two. A Rubout after a Return will undo it. 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. @index{continuation 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. @Section[Moving The Cursor] To do more than insert, you have to know how to move the cursor. Here are a few of the commands for doing that. @index{C-A}@index{C-E}@index{C-F}@index{C-B}@index{C-N}@index{C-P}@index{C-L}@index{C-T}@index{M->}@index{M-<} @index{^R Beginning of Line}@index{^R End of Line}@index{^R Forward Character} @index{^R Backward Character}@index{^R Down Real Line}@index{^R Up Real Line} @index{^R New Window}@index{^R Transpose Characters}@index{^R Goto Beginning} @index{^R Goto End} @Commands[ C-A@\moves to the beginning of the line. C-E@\moves to the end of the line. C-F@\moves forward over one character. C-B@\moves backward over one character. C-N@\moves 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@\moves up one line, vertically. C-L@\clears the screen and reprints everything. C-U C-L reprints just the line that the cursor is on. C-T@\transposes two characters (the ones before and after the cursor). M-<@\moves to the top of your text. M->@\moves to the end of your text. ] @Section[Files] @index{files}@index{C-X C-V}@index{visiting}@index{C-X C-S} @index{^R Visit File}@index{^R Save File} 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. You do that by choosing a filename, such as FOO, and typing C-X C-V FOO. This "visits" the file FOO @ITS{(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 were only inside your EMACS, and the file FOO was not really changed. If the file FOO doesn't exist, and you want to create it, that's no problem; just 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(Node="Files"). @Section[Help] If you forget what a command does, you can find out with the Help character. @Twenex[The Help character is typed as Control-_.] @ITS[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(Node="Help"). @Section[Using Blank Lines Can Make Editing Faster] @WideCommands[ C-O@\Insert one or more blank lines after the cursor. C-X C-O@\Delete all but one of many consecutive blank lines. ] @index{C-O}@index{C-X C-O}@index{blank lines}@index{^R Open Line}@index{^R Delete Blank Lines} One thing you should know is that 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, it is better to make a blank line there first and then type the text into it, rather than just go to the beginning, insert the text, and then insert a line boundary. It is also clearer what is going on while you are in the middle. 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, instead of typing FOO Return to insert a line containing FOO, type C-O FOO. If you want to insert many lines, you should 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(Node="Arguments"), for how). You can then insert the lines of text, and 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. C-X C-O on a blank line among many blank lines reduces them to one. C-X C-O on a nonblank line deletes any blank lines which follow. @Node(Name="Arguments", Prev="Basic", Next="Mark") @Chapter[Giving Numeric Arguments to EMACS Commands] @index{numeric arguments} 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 one. 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. @index{meta} On terminals with Meta keys, entering an argument is easy. Simply type the digits of the argument, with the Control or Meta key held down (or both). The argument must precede the command it is intended for. To give a negative argument, type a "-", again with the Control or Meta key held down, before the digits. @index{Altmode} On other terminals, an argument can be entered by typing Altmode followed by an optional minus sign, and the digits. The next non-digit is assumed to be the command for which the argument was intended. This works only on terminals which do @xxii[not] have Meta keys, for technical reasons. @Note(Node="Losers", Name="Altmode"). @index{C-U}@index{^R Universal Argument} A way of specifying an argument that works the same on all terminals is to use the C-U (^R Universal Argument) command followed by the optional minus sign and the digits. C-U followed by a non-digit other than "-" 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. It 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". Again, 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. @Section[Autoarg Mode] @index{autoarg mode} Users of ASCII keyboards may prefer to use Autoarg mode, in which an argument can be specified for most commands merely by typing the digits. Digits preceding an ordinary inserting character are themselves inserted, but digits preceding an Altmode or Control character serve as an argument to it and are not inserted. To turn on this mode, set the variable Autoarg Mode nonzero. 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. @Node(Name="Mark", Prev="Arguments", Next="Killing") @Chapter[The Mark and the Region] @index{mark}@index{Region} @index{C-X C-U}@index{^R Uppercase Region} In general, a command which processes an arbitrary part of the buffer must be able to be told where to start and where to stop. In EMACS, such commands start at the pointer and end at a place called the "mark". This range of text is called "the region". For example, if you wish to convert part of the buffer to all upper-case with the C-X C-U command, you can first set go to the beginning of the text to be capitalized, put the mark there, move to the end, and then issue the C-X C-U command. Or, you can set the mark at the end of the text, move to the beginning, and then issue the 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 capitalized. @WideCommands[ 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. C-M-@@@\Set mark after end of next 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 defun. C-X H@\Put region around entire buffer. C-X C-P@\Put region around current page. ] @index{C-@@}@index{C-Space}@index{^R Set/Pop Mark} 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 the pointer is. Then you can move the pointer 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 a C-@@, which is an equivalent command. A few keyboards just send a Space. If you have one of them, you suffer, or customize your EMACS. @index{C-X C-X}@index{^R Exchange Point and Mark} Since terminals have only one cursor, there is no way for EMACS to show you where the mark is located. You just have to remember. The solution to this problem is usually simply to set the mark and then use it soon before you have any chance to forget. 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. Thus, the previous location of the mark is shown, but the region specified is not changed. C-X C-X is also useful when you are satisfied with the location of point but want to move the other end of the region; just do C-X C-X to put point at that end and then you can adjust it. The end of the region which is at point can be moved, while the end which is at the mark stays fixed. If you insert or delete before the mark, the mark does not stay with the characters it was between. 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. @Section[Commands to Mark Textual Objects] @index{M-@@}@index{C-M-@@}@index{words}@index{lists}@index{C->}@index{C-<} @index{^R Mark Word}@index{^R Mark Sexp}@index{^R Mark Beginning}@index{^R Mark End} 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, sometimes. @index{paragraphs}@index{Defuns}@index{pages}@index{M-H}@index{C-M-H}@index{C-X C-P}@index{C-X H} @index{^R Mark Paragraph}@index{^R Mark Defun}@index{^R Mark Page}@index{^R Mark Whole Buffer} 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. @Section[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, 16 previous locations of the mark are remembered. 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 are still good for this purpose because they are approximately right. @index{Auto Push Point Option}@index{Auto Push Point Notification} 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-@@ later 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. @manual{ @chapter(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 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 good for special purposes.} @Node(Name="Killing", Prev="Mark", Next="Un-killing") @section(Deletion and Killing) @index{M-D}@index{M-Rubout}@index{C-M-K}@index{C-M-Rubout}@index{C-X Rubout}@index{M-K} @index{^R Delete Character}@index{^R Backward Delete Character} @index{^R Kill Line}@index{^R Kill Region}@index{^R Kill Word}@index{^R Backward Kill Word} @index{^R Kill Sexp}@index{^R Backward Kill Sexp} @index{^R Kill Sentence}@index{^R Backward Kill Sentence} @DoubleWideCommands[ C-D@\Delete next character. Rubout@\Delete previous character. C-K@\Kill rest of line or one or more lines. C-W@\Kill region (ie, from point to mark). M-D@\Kill a word. M-Rubout@\Kill a 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. ] @index{killing}@index{deletion}@index{C-D}@index{Rubout}@index{C-K}@index{C-W}@index{lines} EMACS has several commands that erase variously sized blocks of text from the buffer. Most of them save the erased text so that it can be restored if the user changes his mind, or moved or copied to other parts of the file. 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 commands which delete instead of killing are the single-character delete commands C-D and Rubout, 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(Node="Undo").). @index{blank 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 the pointer up to the end of the line, unless it is at the end of a line, in which case the line separator following the line is killed, thus merging the next line into the current one. Invisible spaces and tabs at the end of the line are ignored when making this decision, so if point appears to be at the end of the line, you can be sure the line separator will be killed. @index{numeric arguments} C-K with an argument of zero kills all the text before the pointer on the current line. 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 the pointer is spared). With a negative argument, -5 for example, all text before the pointer on the current line, and all of the five preceding lines, are killed. 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. @index{mark}@index{Region} 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 set the mark at one end of them and go to the other end, first. A function ^R Delete Region used to exist, but it was too dangerous. When it happens that you want to delete a large amount of text without saving a copy of it (perhaps because that would be too big), you can set point and mark around the text and then do MRK in the minibuffer. Other syntactic units can be killed: words, with M-Rubout and M-D (@Note(Node="Words").); s-expressions, with C-M-Rubout and C-M-K (@Note(Node="Lists", Name="S-expressions").); sentences, with C-X Rubout and M-K (@Note(Node="Sentences").). @Node(Name="Un-Killing", Prev="Killing", Next="Copying") @Section[Un-Killing] @index{killing}@index{undo}@index{moving text}@index{kill ring} Un-killing is the way to get back text which was killed. We often move or copy text by killing it and then un-killing it. @Commands[ 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. ] @index{C-Y}@index{^R Un-kill} Killed text is pushed onto a ring buffer 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. @index{mark}@index{Region}@index{M-W}@index{^R Copy Region} 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 file as "changed" and does not temporarily change the screen. Note that 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. @index{C-M-W}@index{^R Append Next Kill} 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 just as it was before it was killed. (Thus we join TV in leading people to kill thoughtlessly). 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 pushing 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. @index{M-Y}@index{^R Un-kill Pop} If you wish to recover text that was killed some time ago (was not the most recent victim), 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 and replaces it with the text from an earlier 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. @index{numeric arguments} 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 is 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 convenient way of viewing the contents of the kill ring is @example[ 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. @Node(Name="Copying", Prev="Un-killing", Next="M-X") @Section[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. @Subsection[Accumulating Text] @index{C-X A}@index{^R Append to Buffer}@index{Append to File}@index{Prepend to File} 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 its pointer. Successive uses of C-X A accumulate the text in the specified buffer in the same order as they were copied. Later on, you can retrieve the accumulated text from that buffer with M-X Insert Buffer. @Note(Node="Buffers"), for background information on buffers. To accumulate text into a file, use 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. @Subsection[Copying Text Many Times] @index{C-X X}@index{C-X G}@index{^R Put Q-reg}@index{^R Get Q-reg}@index{q-registers}@index{TECO}@index{MM} When you want to copy one piece of text into the buffer from time to time during your editing, 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 . can be a letter or a number. This actually uses the TECO q-register of the same name! An argument makes it delete the text as well. 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 a numeric argument makes it put 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 in order to know that what you save with C-X X A is what you will get with C-X G A. It is best not to use q-registers M and R in this way, if you are going to want to use the TECO commands MM and MR. @Node(Name="M-X", Prev="Copying", Next="Help") @Chapter[Extended (Meta-X) Commands and Functions] @WideCommands[ 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. ] @index{extended commands}@index{M-X}@index{functions}@index{commands} While the most often useful EMACS commands are accessible via one or two characters, the less often used commands go by long names to make them easier to remember. They are known as "extended commands" because they extend the set of two-character commands. They 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 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 @XXi[type], starting with M-X, and what the command @XXI[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. @index{Rubout}@index{C-D}@index{C-U}@index{C-G}@index{echo area} 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 to anything which reads a line in the echo area. @index{command completion}@index{Altmode}@index{Space} You can abbreviate the name of the command, as long as the abbreviation is unambiguous. If the name you specify is ambiguous or impossible, you get an error message. You can also use completion on the function name. Typing Altmode asks to complete the entire function name, or as much as is possible. Note that Altmode has the additional function of separating the function name from any string arguments. Typing Space asks to complete only the current or next word. If the first word of the command name is Edit, List, Kill, Make, View or What, you can abbreviate it with one letter and a Space. If you are not sure whether an abbreviation is long enough, typing "?" prints out a list of all functions whose names are continuations of what you have typed so far. @index{prompting}@index{MM}@index{TECO} 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 M-X command and should type the name of a function to be called. Whenever an EMACS command reads input, it prompts like this. @index{numeric 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. @index{string arguments} Some functions require "string arguments" or "suffix arguments". For those functions, the function name is terminated with a single Altmode, after which come 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. 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. @index{minibuffer}@index{C-X Altmode}@index{^R Re-execute Minibuffer} To re-execute a saved command, use the command C-X Altmode (^R Re-execute Minibuffer). It retypes the last extended command and ask 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(Node="Minibuffer").). @index{C-M-X}@index{^R Instant Extended Command} 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. This can be useful if the string argument is a filename or a command name, because the function knows that and gives the argument special treatment such as completion. 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. So C-M-X saves @xxi[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. Note: Extended commands and functions were once called "MM commands", but this term is obsolete. If you see it in any user documentation, please report it. Ordinary one or two character commands used to be known as "^R" commands, and the term may still be used in the online documentation of some functions; please report this also. @Note(Name="MM",Node="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. @Node(Name="MMArcana", Up="M-X", Prev="M-X") @Section[Arcane Information about M-X Commands] @index{M-X}@index{TECO} You can skip this section if you are not interested in customization, unless you want to know what is going on behind the scenes. @Subsection[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 @example[ 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(Node="Minibuffer"), for information on the minibuffer. "MM" actually tells TECO to run the program in q-register "M". This program takes a string argument to be 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 TECO calls "M". That's why "MM" is called that and not "Run" or "F Q". @Subsection[Arguments in TECO Code] @index{numeric arguments} 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 pointers, TECO buffer objects, etc. However, no more about that here. @index{string 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! @Subsection[Commands and Functions] @index{customization} Actually, @xxi[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. This is the basis of customization of EMACS. You can use the function Set Key to do this. 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. This can be done with the function Set Key; or you can use an init file to do it permanently. @Note(Node="Init"). @Subsection[Subroutines and Built-in Functions] @index{subroutines} @index{command completion} 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 the user is 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 the user isn't 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. @index{BARE library}@index{Help} Some function names, present as definitions of single-character commands, are known to all the Help features but don't seem to exist if you try to call them by name. The names of these functions are not always defined; they are contained in a library called BARE which is loaded temporarily by each documentation command and then flushed again. The reason for this is that these functions are really built into TECO and not part of EMACS; the EMACS "definitions" aren't necessary for actually using them, and are only there for the sake of documentation. If you load BARE permanently, then you can refer to these functions by name like all others. @Node(Name="Help", Prev="M-X", Next="Subsystems") @Chapter[Self-Documentation Commands] @index{Help}@index{C-_} 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. Just what the Help character is depends on which terminal you are using, but aside from that the same character always does the trick. @ITS{If your keyboard has a key labeled Help (above the H), type that key (together with the Top key). }@ITS{Otherwise you}@Twenex{ you} should type the character @Twenex{C-_ (Control-Underscore).}@ITS{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. If you type Help while you are using a subsystem such as INFO, it will give you a list of the commands of that subsystem. If you type Help in the middle of a multi-character command, it will often tell you about what sort of thing you should type next. For example, if you type M-X and then Help, it will tell 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 will tell 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 will tell 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 prints "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. But the most useful of them are described here. @index{Describe} 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; just 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; type the name of the function and a Return. Thus, Help D Lisp Mode tells you about M-X Lisp Mode. "D" stands for "Describe", since Help D actually uses the function Describe to do the work. @index{Apropos} 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 will tell you. 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. If you aren't sure what characters you accidentally typed to produce surprising results, you can use Help L to find out ("L" stands for "What Lossage"). When you see commands that you don't know, you can use Help C to find out what they did. 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 @ITS{EMACS;EMACS NEWS}@Twenex{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. @index{documentation} Finally, you should know about the documentation files for EMACS, which are @ITS{EMACS;EMACS GUIDE and EMACS;EMACS CHART.}@Twenex{EMACS.GUIDE and EMACS.CHART.} EMACS@ITS{ }@Twenex{.}GUIDE is a version of the manual formatted to be printed out on a terminal or line printer. EMACS@ITS{ }@Twenex{.}CHART has a brief description of all the commands, and is good to post on the wall near your terminal. @Manual{ @Chapter[Subsystems and Recursive Editing 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 to send, or looking at a documentation file with INFO.} @Node(Name="Subsystems", Prev="Help", Next="Recursive") @Section[Subsystems] A subsystem is an EMACS command which is an interactive program in and of itself: 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{INFO itself}@Manual{INFO, the documentation reading program}. Others are Backtrace and TDEBUG, used for debugging TECO programs, and @ITS{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 graph. 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(Name="Mode Line", Node="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: @DoubleWideCommands{ C-]@\aborts (exits without finishing up) Backspace@\scrolls down, like M-V in EMACS Space@\scrolls up, 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. @Node(Name="Recursive", Previous="Subsystems", Next="Exiting") @Section[Recursive Editing Levels] @Index{Recursive Editing Level}@Index{Edit Options} @Index{Mode Line} A recursive editing level is a state in which you are inside a command which has given you some text for you to edit. The text may or may not be part of the file you are editing. Recursive editing levels are indicated in the mode line by square brackets ("[" and "]"). For example, the command M-X Edit Options is for changing the settings of EMACS options by editing a list of option names and values. You use the same commands as always for making changes in this list; when you are finished, the changes take affect in your option settings. While you are editing the list of options, the mode line says "[Edit Options]". 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. @Index{Edit Picture} 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. 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 Control-Altmode or @CMC[] (^R Exit). @Note(Node="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(Name="C-]", Node="Unwedging"). @index{minibuffer}@index{C-G} 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-]. For full details on minibuffers, @Note(Node="Minibuffer"). @Node(Name="Exiting", Prev="Recursive", Next="Unwedging") @Chapter[Exiting] @WideCommands[ C-X @CC[]@\Exit from EMACS to the superior @ITS(job)@Twenex(fork). @CMC[]@\Exit from EMACS or from a recursive editing level. ] @index{@CMC[]}@index{^R Exit}@index{C-X @CC[]}@index{^R Return to Superior}@index{exiting} The general EMACS command to exit is @CMC[] (^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 @ITS[HACTRN]@Twenex[EXEC]. If your keyboard does not have a Meta key, you must type this command by means of a bit prefix character, as @CC[] @CC[] or as Altmode @CC[]. 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(Name="Aborting", Node="Unwedging"). 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 @ITS[HACTRN]@Twenex[EXEC] at any time, even within a recursive editing level, by means of the command C-X @CC[] (^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 can use C-X C-S first. Exiting does cause an auto save if auto save mode is in use. @Index{& Exit EMACS}@Index{Exit Hook} Exiting from EMACS runs the function & Exit EMACS, which executes the value of the variable Exit Hook, if it is defined. @Node(Name="Unwedging", Prev="Exiting", Next="Undo") @Chapter[Getting EMACS out of Wedged or Undesirable States] @Commands{ 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. } @index{quitting}@index{C-G}@index{C-]}@index{Abort Recursive Edit} There are four general "quitting" procedures in EMACS: C-G, C-], M-X Top Level, and restarting EMACS. The last is a drastic one for use when the others fail. The first three have specific distinct uses. C-G is the most common way of quitting. It 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 @xxii[all] still be there, or it will @xxii[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. @index{recursive editing level} However, C-G does not quit out of recursive editing levels, or out of subsystems such as INFO. This is because it is useful to be able to quit commands within the subsystem. For example, you can use C-G to flush a partially typed INFO command without worrying that it may take you all the way out of INFO. If you are editing a message to be sent, you can flush a partial command with C-G and have no fear of quitting out of editing the message. The way to quit out of such subsystems is to use the C-] command (Abort Recursive Edit), which quits out of one level of subsystem or recursive edit. Thus, it is the way to abort sending a message. C-] will either tell you how to resume the aborted command or query for confirmation before aborting. @index{Top Level} 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. Normally, you won't need to do anything else to get EMACS out of strange states. However, sometimes you will need to restart it. This is because C-G always 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 from being destroyed. However, sometimes EMACS is hung inside a TECO command. In such a case, C-G does not work, but the more drastic procedure of restarting TECO may work. Type @ITS{CALL or C-Z} @Twenex{Control-C} to stop EMACS, then @ITS{G}@Twenex{START} 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. @Section[What to Do if EMACS Acts Strangely] @index{terminal type} @Twenex{@Index[Set Terminal Type]} 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 data which is more pleasing. Think of it as getting an opinion from another doctor. 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 may not know what type of terminal you have. You should try telling the system with the @ITS{:TCTYP command.}@Twenex{TERMINAL TYPE command. If your terminal is compatible with one of the standard types but has a different size screen, you must tell the system the size with the TERMINAL LENGTH and TERMINAL WIDTH commands, because EMACS uses whatever size the system says it knows. However, the system may not even have a type code defined for your terminal. In this case, as long as EMACS knows about your type of terminal, you can do M-X Set Terminal Type where stands for the EMACS name of your type of terminal. Get a list of all types known by doing M-X List LibraryTRMTYP. EMACS will STILL get the size of the screen from the system, so you are not relieved of responsibility for using the TERMINAL WIDTH and TERMINAL LENGTH commands. Also, if you restart EMACS (as opposed to continuing it), you will have to specify the terminal type again, since EMACS will have asked the system again.} @Index{Make Space}@INDEX{URK}@Index{Kill Ring}@Index{Undo} @Index{Kill Libraries}@Index{Kill Some Buffers} 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 you can run M-X Make Space. 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(Node="Killing").), the undo memory (@Note(Node="Undo").), and buffers created by @ITS(RMAIL,) TAGS and INFO. Another way of freeing space is to kill buffers with M-X Kill Some Buffers (@Note(Node="Buffers").) or unload libraries with M-X Kill Libraries (@Note(Node="Libraries").). @index{TECO} 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. You can get back into EMACS by typing :M..L, or by restarting the job. If you ever @xxi[want] to exit back to TECO, you can do M-X Top Level with an argument greater than zero. @Node(Name="Undo", Prev="Unwedging", Next="Bugs") @Section[Undoing Changes to the Buffer] @index{Undo}@index{killing} 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. Just 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. @index{deletion} 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 @xxii[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(Node="Revert").) might be able to. @Node(Name="Bugs", Prev="Undo", Next="Display") @Section[Reporting Bugs] There will be times when you 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. @Subsection[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. Restart EMACS and type Help L to see whether the keyboard or line noise garbled the input; if the input was such that you @xxii[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 @xxi(about the documentation). It is just as important to report documentation bugs as program bugs. @Subsection[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. 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(Node="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 @xxii[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 @ITS{INFO;TECORD >}@Twenex{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). @Twenex{If you are reporting the bug from a non-Arpanet site, keep the files small, since we may have to @xxii[type them in], unless you send them on mag tape.} If you are not in Fundamental mode when the problem occurs, you should say what mode you are in. The most important principle in reporting a bug is to report @xxii[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, since the user could have reported the raw facts. Thus, instead of saying "... happens when I read in a big file", say "... happens when I type C-X C-V @Twenex{BAZ.UGH}@ITS{GLORP;BAZ UGH}". This way you @xxii[know] we will be able to cause the problem. Suppose it's not a matter of size at all, but of having a "Z" in the filename? We would try out the problem with some "big file", probably with no "Z" in its name, and not find anything wrong. Suppose that the file actually must contain between 130,000 and 150,000 characters to cause the problem? 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. Rather than saying "if I have three characters on the line", say "after I type A B C C-P". 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. @Twenex{Consult a system wizard for how to do this.}@ITS{Do this by saying :PDUMP CRASH;EMACS >.} Be sure to report exactly all the numbers printed out with the error message. @ITS{Also type .JPC/ and include DDT's response in your report.} If you restart or continue the EMACS before saving this information, the trail will be covered and it will probably be too late to find out what happened. A dump is also useful if EMACS gets into a wedged state in which commands that usually work do strange things. @Node(Name="Display", Prev="Bugs", Next="Files") @Chapter[Controlling the Display] @index{scrolling}@index{screen} @Commands[ C-L@\Clear and redisplay screen, with point at specified place. C-V@\Scroll upwards (a screen or a few lines). M-V@\Scroll downwards. M-R@\Move point to given vertical position. C-M-R@\Get this function 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 the pointer. It continues to show approximately the same portion until the pointer moves outside of it; then EMACS chooses a new portion centered around the new pointer. 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". @index{C-L}@index{minibuffer}@index{TECO}@index{clear screen}@index{^R New Window} 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 display a portion of the buffer centered around where the pointer is currently located (actually, the pointer goes 35% of the way down from the top; this percentage can be set by executing FS % CENTER in a minibuffer). If you do not use C-L, EMACS only recenters the pointer in the screen when it moves past the edge. @index{numeric arguments} 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. The pointer 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 without sending it again if the terminal allows that. C-U C-L is different from C-L with any other sort of argument. It causes the line containing the pointer to be redisplayed but not the whole screen. @index{C-V}@index{M-V}@index{^R Next Screen}@index{^R Previous Screen} If you want to see a few more lines at the bottom of the screen and don't want to guess what argument to give to C-L, you can use the C-V (^R Next Screen) command. C-V 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. Often you want to read a long file sequentially. For this, the C-V command without an argument is ideal; it takes the last two lines at the bottom of the screen and puts them at the top, followed by a whole screenful of lines not visible before. The pointer 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). @index{View File}@index{View Buffer} If @xxii[all] you want to do to a file is read it sequentially, you might want to use M-X View File. This command allows you to look at the file a screenful at a time typing a Space to see the next screenful. Backspace gets you to the previous screenful. Typing anything else exits the command. The advantage of View File is that the whole file does not need to be read in before you can begin reading it. The inability to do anything but page forward or backward is a consequence. For in-between situations, M-X View Buffer might be useful. It lets you move through the buffer a screenful at a time by typing Spaces and Backspaces. Typing a Return exits, leaving point centered in whatever part of the buffer was on the screen at the time. Typing anything else returns to the place where point was before you gave the View Buffer command. View Buffer can be given the name of a buffer to view as a string argument. This is a quick way of examining the contents of another buffer. @Note(Node="Buffers"). @index{C-M-R}@index{^R Reposition Window} 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" is delimited by blank lines except in Lisp mode, but comments before the beginning are considered part of the function. @index{M-R}@index{^R Move to Screen Edge} 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 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-0 Meta-R puts the cursor 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. @Node(Name="Files", Prev="Display", Next="Search") @Chapter[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 * Buffers:: Using multiple buffers; visiting several files at once * Locals:: The file can say what editing modes are right for it * AutoSave:: Protection from crashes * CleanDir:: Deleting old versions to clean up * DIRED:: selectively deleting files (Directory Editor) * Filadv:: advanced file commands @ITS{* DirComp:: directory comparison }} @Node(Name="Visiting", Prev="Files", Up="Files", Next="Revert") @Section[Visiting Files] @WideCommands{ C-X C-V@\Visit a file. C-X C-R@\Visit a file for reading only. C-X C-S@\Save the visited file. C-X C-D@\List part of the file directory. Meta-~@\Tell EMACS to forget that the buffer has been changed. } @index{files}@index{visiting}@index{saving} 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 and 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. The changes you make with EMACS to the text of the file you are visiting are made not in the file itself, but 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. You can do that at any time with C-X C-S. If you change one file and then try to visit another, EMACS will offer to save the first file (if it is not saved, the changes would be lost). In addition, for those who are afraid of system crashes, Auto Save mode saves the file at regular intervals automatically while you edit. @Note(Node="Auto Save"), for more information on this. @index{C-X C-V}@index{C-G}@index{C-U}@index{Return}@index{^R Visit File} 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 them. If EMACS thinks you can't see the defaults, it prints print them out. You can abort the command by typing C-G, or edit the filename with Rubout and C-U. If you do type a Return to finish the command, the new file's text will appear on the screen, and its name will show up in the mode line. @index{C-X C-S}@index{^R Save File} 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 will print "Written: " in the echo area at the bottom of the screen. @ITS{If you are visiting a file whose name is ">", this message will contain the version number actually written. }EMACS won't actually write out the file if the contents have not been changed since the last save or since the file was read in. So you don't have to try to remember that yourself; when in doubt, type a C-X C-S. If you really can't remember what changes you made in the buffer, write it out as a new version and then SRCCOM it against the previous. If you didn't make any changes you want to keep, you can then delete the new version. However, you need not do the saves yourself. If you alter one file and then visit another, EMACS may offer 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. If you are sure you only want to look at a file, and not change it, you can use the C-X C-R command to visit it, instead of C-X C-V. Then EMACS will not offer to save the file when you later visit another, since it will assume the changes were inadvertent. However, you can still save the file with C-X C-S if you want. @index{confirmation} If EMACS is about to save a file automatically 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 at your buffer. Sometimes you will change a buffer by accident. Even if you undo the change (perhaps, rub out the character you inserted), EMACS still knows that "the buffer has been changed". You can tell EMACS to forget about that 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. It is up to you not to use it unwisely. If we take "~" to mean "not", then Meta-~ is "not" metafied. @Twenex{ @index{Strip SOS Line Numbers}@Index{SOS}@Index{Line Numbers} If there are still people using SOS on your machine, you may have to visit files with SOS line numbers in them. The function Strip SOS Line Numbers removes all line numbers from the current buffer. Actually, what it does is reset the low order bit in each word and remove all nulls. An explicit argument inhibits removal of nulls unless the file actually has line numbers.} @Index{Create File} What if you want to create a file? Just visit it. EMACS print "(New File)" but otherwise acts unworried. 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), just visit the file you meant. If you didn't "change" the nonexistent file (you never inserted anything in it) it is not created. @index{file directory}@index{List Files}@index{C-X C-D}@index{View Directory} @index{numeric arguments}@index{string arguments}@index{^R Directory Display} 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. @Index{SRCCOM} If EMACS is about to save a file and sees that the latest version on disk is not the same one as EMACS last read or wrote, EMACS notifies you of this fact, and ask 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. @Node(Name="Revert", Prev="Visiting", Up="Files", Next="Buffers") @Section[How to Undo Drastic Changes to a File] @index{Undo}@index{Revert File}@index{files} @index{numeric arguments} In this situation you might want to use M-X Revert File, which reads in the last saved version of the file. If you have been using Auto Save mode, it reads in the last version of the file or the last auto save file, whichever is more recent. If you are using Auto Save mode, saving as 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. @index{confirmation} 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). @Node(Name="Buffers", Prev="Revert", Up="Files", Next="Locals") @Section[Buffers: How to Switch between Several Bodies of Text] @WideCommands{ C-X B@\Select or create a buffer. C-X C-F@\Visit a file in a new buffer. C-X C-B@\List the existing buffers. C-X K@\Kill a buffer. } @index{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. @index{mode line} 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". @index{C-X B}@index{Select Buffer} 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 select 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 that variable is the null string. Normally this 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. 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. @index{C-X C-F}@index{visiting}@index{^R Find File} You can also read a file into its own newly created buffer, all with one command: C-X C-F, followed by the filename. The first name of the file is used as the buffer name. C-F stands for "Find", because if the specified file already resides in a buffer in your EMACS, that buffer will be 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. If the buffer with the name C-X C-F wants to use already exists but with the wrong contents (a different file with a similar name, or no file), then you are asked what to do. You can type Return meaning go ahead and use the buffer for this new file, or you can type another buffer name to use instead of the normal one. 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 given a warning, and left with the version which was already in the EMACS. To get the version on disk instead, use M-X Revert File. @index{C-X C-B}@index{List 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. @index{Save All Files}@index{C-X C-S}@index{^R Save File} 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. @index{Kill Buffer}@index{Kill Some Buffers}@index{C-X K}@index{recursive editing level} After using an EMACS for a while, it may fill up with buffers holding files that you no longer need to edit. If you have enough of them, 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 @CMC[] and you will be asked the question again. If you say to kill a buffer that needs saving, you will be asked whether to save it. You can kill the buffer FOO by doing C-X K FOO. You can kill the current buffer, a common thing to do if you use C-X C-F, by doing C-X K. If you kill the current 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. There are commands C-X A (^R Append to Buffer) and M-X Insert Buffer which can be used to copy text from one buffer to another. @Note(Node="Copying"), for their descriptions. @index{local variables}@index{List Locals}@index{TECO}@index{variables} 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. 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. You can put text in a file directing the creation of local variables when the file is visited. This is done with a local modes list (@Note(Node="Locals")). To get a list of the local variables in the current buffer, do M-X List Locals. Most local variables are killed (made no longer local) if you change major modes. 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, as opposed buffer-specific customizations. @InfoNote(Name="Variables", File="CONV", Node="Variables"), for information on how local variables work, and additional related features. @index{Rename Buffer} 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 the used for the new name of the buffer. @Node(Name="Locals", Prev="Buffers", Up="Files", Next="AutoSave") @Section[Local Variables in Files] @index{local variables}@index{files}@index{major modes}@index{Auto Fill mode} @index{redefining commands}@index{customization}@index{buffers} By putting a "local modes list" 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, or it can turn on Auto Fill mode, 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.@Twenex{ The -*- can appear on the first nonblank line after the edit history, if somebody insists on putting in an edit history.} @Twenex{ Often, EMACS is able to determine the best major mode for a file by looking at the file's extension. If this works, you don't need to worry about specifying the major mode. If the extension of the file does not inform EMACS correctly, then you need an explicit local modes specification. } @index{EVARS files}@index{C-X}@index{prefix characters} To specify more that just the major mode, you must use a "local modes" list, which goes in the @@xxii[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:". Whatever precedes that string on the line is the "prefix", and whatever follows it is the "suffix" (either or both may be null). From then on, each line should start with the prefix, end with the suffix, and in between contain one local mode specification in the form :. To set a variable, make the name of the variable and the desired value. If is a numeral (which means no spaces!), the value is a number; otherwise, it is as a string. To set a command character, make the name of the character as a q-register, such as ... R, for C-M-Comma, and make be a string of TECO commands which will return the desired value (this is so you can write M.MFoo to define the character to run the function Foo). The local modes list is terminated by a line which contains "End:" instead of :. 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. @Note(Name="EVARS", Node="Init"), for more information. 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 the variable named "MM Foo". @Note(Node="MMArcana", Name="MM"). @index{Comment Column}@index{Comment Start} @Begin(noop,need 10lines) @End(noop) Here is an example of a local modes list: @example[ ;;; Local Modes: ::: ;;; Mode:Lisp ::: ;;; Comment Column:0 ::: ;;; Comment Start:;;; ::: ;;; .. R/: m.m^R My Funny Meta-Slash ::: ;;; End: ::: ] Note that the prefix is ";;; " and the suffix is " :::". Note also that the value specified for the Comment Start variable is ";;; ", which is the same as the prefix, so the local modes list looks like a lot of comments. We used a suffix in this example, but they are usually not used except in languages which require comment terminators. If you have a local modes list, the last page of the file must be no more than 10000 characters long or it 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. @Node(Name="AutoSave", Prev="Locals", Up="Files", Next="CleanDir") @Section[Auto Save Mode: Protection Against Crashes] @index{files}@index{visiting}@index{saving}@index{Auto Save mode} If you turn on 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 when the system crashes. @index{Auto Save Default} 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. @index{numeric arguments} Each time you visit a file, no matter how, auto saving will be on for that file if Auto Save Default is nonzero. However, by giving a nonzero argument to the file-visiting command, you can turn off auto saving @xxii[for that file only], without changing the default. For example, you might use C-U C-X C-V to do this. 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 will initially be 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: @quotation[ @ITS{ If you visit a file on a device other than DSK, auto saves can't go there, because it would probably be slow. } 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 visit a file with C-X C-R, then you have said you don't want to store under those names. If you haven't visited a file, there aren't any names to use. ] @index{Auto Save Filenames}@index{Auto Save Visited File} So in all those cases, auto saves are written as the filenames in Auto Save Filenames. But if none of those cases apply -- if your visited file has version numbers, and can be written quickly -- then it is possible to store auto saves under that name. This will be done, provided that you turn on the feature by setting the variable Auto Save Visited File to a nonzero value. @index{C-X C-S} 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). @index{C-X C-W}@index{Revert File}@index{Write File} 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 use 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(Node="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. @index{Auto Save Max} 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, files which were not made by auto saving (or by explicitly requested auto-saves with C-U C-X C-S) are never deleted in this way. 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. @index{Auto Save Interval} 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. @index{Buffer Creation Hook} Auto Save Filenames is usually set up by the default init file to @ITS{DSK:;_^RSV >}@Twenex{_^RSV..}. Or, if you use auto saving in multiple buffers a lot, you might want to have a Buffer Creation Hook which sets Auto Save Filenames to a filename based on the buffer name, so that different buffers don't interfere with each other. @Node(Name="CleanDir", Prev="AutoSave", Up="Files", Next="DIRED") @Section[Cleaning a File Directory] @index{file deletion}@index{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. @index{DIRED} For complete flexibility to delete precisely the files you want to delete, you can use the DIRED package. @Note(Node="DIRED"), for more details. But there is a more convenient way to do the usual thing: keep only the two (or other number) most recent versions. @index{Reap File}@index{Temp File FN2 List}@index{TECO search string} 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). In addition, if there is a file with an FN2 of MEMO, @@XGP, XGP, PRESS or UNFASL, you are asked whether it too should be deleted (this is controlled by a TECO search string in the variable Temp File FN2 List. @Note(Name="TECO search string", Node="TECOsearch").). If you give M-X Reap File a null filename argument, or no argument, then it applies to the file you are visiting. @index{Clean Directory}@index{File Versions Kept} M-X Clean Directory@ITS{;} cleans a whole directory of old versions. Each file in the directory is processed a la M-X Reap File. M-X Clean Dir with a null argument, or no argument, cleans the directory containing the file you are visiting. M-X Reap File and M-X Clean Dir 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. @Node(Name="DIRED", Prev="CleanDir", Up="Files", Next="Filadv") @Section[DIRED, the Directory Editor Subsystem] @index{DIRED}@index{file deletion} 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. @index{recursive editing level}@index{@CMC[]}@index{C-]} Invoke DIRED with M-X DIRED to edit the current default directory, or M-X DIRED@ITS{;} 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 @CMC[] and abort with C-]. 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,@ITS{ !, $, 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 just 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 @CMC[]. 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. @index{confirmation} When you have marked the files you wish to mark, you can exit DIRED with @CMC[]. If any files were marked for deletion, DIRED lists them in a concise format, several per line. @ITS{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. Anything else typed makes DIRED print a list of these responses and try again to read one of them. A few other DIRED commands are provided. @ITS{ 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. @ITS{ 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. S copies the file you are pointing at to the secondary pack. P copies the file you are pointing at to the primary pack. $ 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 another directory or device. You must say where to move it. @Index{SRCCOM} 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. } @Twenex{ C calls up SRCCOM as an inferior with the current file in its command line. When you return to EMACS, the cursor moves down a line to the next file. S allows you to change the order in which the files are listed. It reads another character, F for filename (the default), S for size, R for read date, or W for write date. R does the same sorting of S, but the list is put in reverse order } 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. @index{C-X D}@index{directory}@index{^R DIRED} There are some other ways to invoke DIRED. The Emacs command C-X D 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 "Directory;". Type a directory name @ITS{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. @index{Keep Lines} 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 @xxii[not] be deleted. Thus, M-X Keep Lines is useful if you wish to delete only files with a FOO in their names. @Note(Name="Keep Lines", Node="Replace"). @index{minibuffer} 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. @ITS{@Node(Name="Filadv", Prev="DIRED", Up="Files", Next="DirComp")} @Twenex{@Node(Name="Filadv", Prev="DIRED", Up="Files")} @Section[Miscellaneous File Operations] @index{insertion}@index{files}@index{Insert File}@index{Write File}@index{Append to File}@index{Prepend to File} EMACS has extended commands for performing many other operations on files. 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. 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. @index{mark}@index{Region} 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. @index{Set Visited Filename}@index{List Files}@index{Delete File}@index{Copy File}@index{Rename File} 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 equivalent to this command followed by a C-X C-S. M-X List Files lists just the names of all the files in , several to a line. M-X Delete File deletes the file. M-X Copy File copies the file. M-X Rename File renames the file. @index{TECO}@index{TECO default filenames} The default filenames for all of these operations are the "TECO default filenames". Most of these operations also leave the TECO default names set to the file they operated on. The TECO default is @xxii[not always] the same as the file you are visiting. When you visit a file, they start out the same, but the commands mentioned above can change the TECO default, though they certainly don't change the visited filenames (so C-X C-S knows where to save your file). Each buffer has its own TECO default filenames. @index{Visit File} 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. @index{Auto Directory Display}@index{Directory Lister} 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, in EMACS, this is the macro that displays only the files related to the current default file.@ITS{ An alternative type of directory listing can be obtained by setting Directory Lister to M.M& Rotated Directory Listing. This function always displays the whole directory, but starts with the file you are interested in, proceeding through the end of the directory around to the beginning.} @ITS{ @Node(Name="DirComp", Prev="Filadv", Up="Files") @Section[The Directory Comparison Subsystem] @index{directory}@index{Compare Directories} 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 sname 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 @CMC[]. Here is a sample of part of a directory comparison: @Verbatim[ 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. } @Node(Name="Search", Prev="Files", Next="Fixit") @Chapter[Searching] @Commands[ C-S@\Search forward. C-R@\Search backward. ] @index{searching}@index{C-S}@index{C-R}@index{^R Incremental Search}@index{^R Reverse Search} Searching moves the cursor to the next occurrence of a string of characters which you specify. In EMACS, searching is "incremental", which means that 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. EMACS also has commands to find all or some occurrences of a string and replace them, print them, or count them. @Menu{ * Replace:: Look here for several useful replacement commands. } 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 next "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. Any command except a printing character or CR stops the searching and is then executed. Thus, if you find the word FOO you can type Meta-Rubout to exit the search and kill the FOO. Altmode is necessary only if the next command you want to type is a printing character, Rubout, Altmode or another search command, since those are the characters that would not exit 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, just 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. You can also repeat the search after exiting it, if the first thing you type after entering another search (when the argument is still empty) is a C-S. 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. @index{quitting}@index{C-G} 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. @index{String Search}@index{Character Search} A non-incremental search is also available. Just 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. @Menu( * Replace:: Search-and-replace commands. * TECOsearch:: TECO search strings are patterns used by some EMACS commands and variables. ) @Node(Name="Replace", Prev="Search", Up="Search", Next="TECOsearch") @Chapter[Replacement Commands] @index{searching}@index{replacement}@index{Replace String}@index{Query Replace}@index{Case Replace} @index{case conversion} Global search-and-replace operations are not used as often in EMACS as they are in other editors, but they are still provided. 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 with BAR, you can do M-X ReplaceFOOBAR. Replacement is done only after the pointer, so if you want to cover the whole buffer you must go to the beginning first. Unless the variable Case Replace is zero, an attempt is made 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 likewise. @index{numeric arguments} If you give Replace (or Query Replace) an argument, then it insists that the occurrences of FOO be delimited by break characters (or an end of the buffer). So you can find only the word FOO, and not FOO when it is part of FOOBAR. @index{C-X N}@index{narrowing}@index{C-X W}@index{^R Set Bounds Region}@index{^R Set Bounds Full} To restrict the replacement to a subset of the buffer, set the region around it and type C-X N ("N" for "Narrow"). This makes all of the buffer outside that region temporarily invisible (but the commands that save your file still know that it is there!). Then do the replacement. Afterward, C-X W ("Widen") to make the rest of the buffer visible again. @Note(Node="Narrowing"). If you are afraid that there may be some FOO's that should not be changed, EMACS can still help you. Use M-X Query ReplaceFOOBAR. This displays each FOO and waits for you to say whether to replace it with a BAR. The things you can type when you are shown a FOO are: @index{Space}@index{Rubout}@index{Comma}@index{Altmode}@index{.}@index{!}@index{^}@index{C-R}@index{C-W} @WideCommands{ 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 (Replace actually works by calling Query Replace and pretending that a ! was typed in). ^@\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 @CMC[]. 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 @CMC[]. } 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. @index{C-X Altmode}@index{^R Re-execute Minibuffer} The first argument of Query Replace and Replace String is not just a string; it is a kind of pattern, a TECO search string. @Note(Name="TECO search string", Node="TECOsearch"). @index{minibuffer}@index{C-]}@index{Altmode}@index{M-%}@index{^R Query Replace} Meta-% gives you a minibuffer pre-initialized with "MM Query Replace". This is the easiest way to invoke Query Replace. It also allows you to get Returns and Altmodes into the arguments. @Section[Other Search-and-loop Functions] Here are some other functions related to replacement. Their arguments are TECO search strings (@Note(Name="TECO search string", Node="TECOsearch").). They all operate from the pointer to the end of the buffer (or where C-X N stops them). @index{Occur}@index{How Many}@index{Keep Lines}@index{Flush Lines}@index{deletion}@index{replacement} @GrossCommands[ M-X OccurFOO@\ which finds all occurrences of FOO after the pointer. It prints each line containing one. With an argument, it prints that many lines before and after each occurrence. M-X How ManyFOO@\ types the number of occurrences of FOO after the pointer. M-X Keep LinesFOO@\ kills all lines after the pointer that don't contain FOO. M-X Flush LinesFOO@\ kills all lines after the pointer that contain FOO. ] @Node(Name="TECOsearch", Previous="Replace", Up="Search") @Section[TECO Search Strings] @index{TECO}@index{C-X}@index{C-B}@index{C-N}@index{C-O}@index{C-Q}@index{TECO search string} The first string argument to Replace and Query Replace is actually a TECO search string. This means that the characters C-X, C-B, C-N, C-O, and C-Q have special meanings. C-X matches any character. C-B matches any "delimiter" character (anything which the word commands consider not part of a word, according to the syntax table). C-N negates what follows, so that C-N A matches anything but A, and C-N C-B matches any non-delimiter. C-O means "or", so that XYXY C-O ZZZ matches @xxii[either] XYXY or ZZZ. C-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. When you invoke Query Replace from the minibuffer, the character C-] becomes special (because it is special in TECO programs). In order to get a C-] into the search string or the replacement string, you must use two of them. You can also use a C-] 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 C-Q C-X into the search string so as to search for a C-X, you have to type C-Q C-Q C-Q C-X. 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 C-O to match several alternatives. In the values of such variables, C-B, C-N, C-O, C-Q, C-X and C-] are special, but Altmode is not. C-B through C-X are quoted with a C-Q, and C-] is quoted with another C-]. @Node(Name="Fixit", Prev="Search", Next="Windows") @Chapter[Commands for Fixing Typos] @index{typos} In this section are described 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 when writing something on line. @DoubleWideCommands[ Rubout@\Delete last character. M-Rubout@\Kill last word. C-X Rubout@\Kill to beginning of sentence. C-T@\If typed at the end of a line, transposes last two characters. C-X C-T@\Transposes two lines. C-X T@\Transposes 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. ] @index{Rubout}@index{deletion}@index{^R Backward Delete Character} 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. @index{M-Rubout}@index{C-X Rubout}@index{words}@index{sentences}@index{killing} @index{^R Backward Kill Word}@index{^R Backward Kill Sentence} 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(Node="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 is often faster just to kill the whole word and start over again, especially if the system is heavily loaded. @index{transposition}@index{C-T}@index{^R Transpose Characters} 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. @index{C-X C-T}@index{^R Transpose Lines} 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. @Index{C-X T}@Index{^R Transpose Regions} A more general transpose command is C-X T (^R Transpose Regions). This can transpose two arbitrary blocks of text, which need not even be near 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. @index{^R Lowercase Word}@index{^R Uppercase Word}@index{^R Uppercase Initial} @index{M-- M-L}@index{M-- M-U}@index{M-- M-C}@index{case conversion}@index{words} 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, without additional commands to move the cursor either before or after the case-conversion command. @Note(Node="Case"). @index{M-'}@index{typos}@index{^R Upcase Digit} Another common error is to type a special character and miss the shift key, producing a digit instead. There is a special command just for fixing this: M-' (^R Upcase Digit), which fixes the last digit before the pointer 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 just 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 @xxii[holding down the shift key]. This tells M-' the correspondence between digits and special characters, which is remembered for the duration of the EMACS. The M-' command is used for this because it smain use is to replace "7" with "'". @Node(Name="Windows", Prev="Fixit", Next="MajorModes") @Chapter[Two Window Mode] @WideCommands[ 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. ] @index{windows}@index{two window mode} Normally, EMACS is in "one-window mode", in which a single body of text is visible on the screen and can be edited. At times, one wants to have parts of two different files visible at once. For example, while adding to a program a use of an unfamiliar feature, one might wish to see the documentation of that feature at the same time. Two-window mode makes this possible. @index{W2}@index{C-X 2}@index{^R Two Windows} 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 pointer moves to window two. If this is your first entry to two-window mode, window two will contain a new buffer named W2. Otherwise, it will contain the same text it held the last time you looked at it. The mode line will now describe the buffer and file in window two. Unfortunately, it's almost impossible to provide a mode line for each window, so making the mode line apply to the window you are in is the best we can do. @index{C-X 1}@index{^R One Window} You can now edit in window two as you wish, while window one remains visible. When you are finished editing or looking at the text in window two, C-X 1 (^R One Window) will return to one-window mode. Window one will expand to fill the whole screen, and window two will disappear until the next C-X 2. @index{C-X O}@index{^R Other Window} 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, just where it was before the first C-X O. And so on... @index{scrolling}@index{numeric arguments}@index{C-M-V}@index{^R Scroll Other Window} 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 just the 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, like an M-V. When you are finished using two windows, the C-X 1 command makes window two vanish. It doesn't matter which window the cursor is in when you do the C-X 1; either way window two vanishes and window one remains. To make window one vanish and window two remain, give C-X 1 an argument. @index{C-X 3}@index{^R View Two Windows} 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. @index{C-X ^}@index{^R Grow Window} Normally, the screen is divided evenly between the two windows. You can also redistribute the lines 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. If given a negative argument, the selected window gets smaller. The allocation of space to the windows is always remembered and changes only when you give a C-X ^ command. @index{numeric arguments}@index{buffers} You can view the same buffer in both windows. Give C-X 2 an argument as in C-U C-X 2 to go into window two viewing the same buffer as in window one. 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. However, if you have the same buffer in both windows this way, you must watch out against 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 one in @xxii[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). @index{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. When you do C-X 2 and window two appears it shows whatever buffer used to be visible in it when it was on the screen last. C-U C-X 2 enters two-window mode with the same buffer (whichever buffer was selected) in both windows. C-U C-X O switches windows when already in two-window mode but carrying the buffer from the old window to the new one so that both are viewing the same buffer. @index{C-X 4}@index{visiting}@index{files}@index{tags}@index{^R Modified Two Windows} A convenient "combination" command for viewing anything interesting in the other window is C-X 4 (^R Modified Two Windows). 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. 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. After leaving two-window mode, you can still use C-X O, but the effect is slightly 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. @Node(Name="MajorModes", Prev="Windows", Next="MinorModes") @manual{ @Chapter(Customization: Modes and Options) } @Section[Major Modes] @index{major modes}@index{Tab}@index{Rubout}@index{Linefeed}@index{comments}@index{^R CRLF}@index{^R Indent New Line} When EMACS starts up, it is in what is called "Fundamental mode", which means that the single and double character commands are defined so as to be convenient in general. More precisely, in Fundamental mode @xxi[every] EMACS option is set in its default state. For editing any specific type of text, such as Lisp code or English text, you can tell EMACS to change the meanings of a few commands to become more specifically adapted to the task. This is done by switching from Fundamental mode to one of the other major modes. 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. @index{mode line} 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). The major modes are mutually exclusive - you can be in only one major mode at a time. When at top level, EMACS always says in the mode line which major mode you are in. @Twenex{ Often EMACS enters the correct major mode for a file simply based on the file's extension, and you do not have to worry about selecting a 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-*-. Many major modes redefine the syntactical properties of characters appearing in the buffer. @Note(Node="Syntax"). Most programming language major modes specify that only blank lines separate paragraphs. This is so that the paragraph commands do not be come useless. They also cause Auto Fill mode to use the definition of Tab to indent the new lines it creates. This is because it is expected that an unindented line is the infrequent case. @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: Other Langs. PL1 mode is the archetype from which modes for all block structured languages are defined. * PASCAL: (EPASC). PASCAL, BCPL and BLISS also have modes. * BCPL: Other Langs. * BLISS: Other Langs. * FORTRAN: Other Langs. @Twenex{* FAIL: MIDAS. Fail and Macro-10 are also defined. * MACRO-10: MIDAS. }} @manual{ Major modes are standardly defined for the languages Lisp, Muddle, MIDAS, @Twenex{FAIL, MACRO-10, }Macsyma, BCPL, BLISS, PASCAL, FORTRAN, TECO, and PL1. @Note(Node="Programs"). There is also Text mode, designed for editing English text, or input to text justifier programs. @Note(Node="Text").} @Node(Name="MinorModes", Prev="MajorModes", Next="Libraries") @Section[Minor Modes] @index{minor modes} @index{numeric arguments}@index{mode line}@index{toggling} Minor modes are options which you can use or not. They are all independent of each other and of the selected major mode. Most minor modes say in the mode line when they are on (see the section about the mode line). 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 of 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. @index{Auto Fill mode}@index{C-X F}@index{Fill Column}@index{^R Set Fill Column} Auto Fill mode allows you to type text endlessly without worrying about the width or your screen. Line separators are be inserted where needed to prevent lines from becoming too long. The column at which lines are broken defaults to 70, but you can set it explicitly. C-X F (^R Set Fill Column) sets the column for breaking lines to the column point is at; or you can give it a numeric argument which is the desired column. The value is stored in the variable Fill Column. @index{Auto Save mode}@index{Auto Save Default} 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(Node="AutoSave"). @index{Atom Word mode}@index{Lisp} 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. @index{Overwrite mode}@index{Rubout} 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. @index{Word Abbrev mode} 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. @InfoNote(Name="Wordab", File="WORDAB"). @index{Indent Tabs mode} 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. Setting the minor mode with a command just changes 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(Node="Variables"). @index{local modes lists}@index{Auto Fill mode}@index{EVARS files} 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 that 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 put 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: @Example[ 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. @Node(Name="Libraries", Prev="MinorModes", Next="Variables") @Section[Libraries of Commands] @index{libraries} All EMACS functions, including the ones described in this document, reside in sharable libraries. A function is not accessible unless the library that contains it is loaded. Every EMACS starts out with @ITS{one}@Twenex{two} @ITS{library}@Twenex{libraries} loaded: the EMACS library@Twenex{, and the TWENEX library}. @ITS{This}@Twenex{These} contain all of the functions described in this document, except those explicitly stated to be elsewhere. Other libraries full of functions are provided with EMACS, and can be loaded automatically or on the user's request to make the functions available. @index{loading}@index{Load Library} To load a library permanently, 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. Thus, 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 putting functions in the search space for M-X, the library may place some of them on commands. @index{Run Library} 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. @index{List Loaded Libraries}@index{List Library} M-X List Loaded Libraries types the names and brief descriptions of all the libraries loaded, last loaded first. The last one is always the EMACS library. You can get a description of all the functions in a library with M-X List Library, whether the library is loaded or not. @index{autoloading}@index{TECO}@index{DIRED}@index{TAGS} 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. This 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 works, not by calling Run Library, but by doing M.A, which is how Run Library also works. You can make your own libraries, which you and other people can then use, if you know how to write TECO code. @InfoNote(Name="Making Libraries", File="CONV", Node="Lib"), for more details. @Node(Name="Variables", Prev="Libraries", Next="Init") @Section[Named Variables] @index{variables}@index{options}@index{Fill Column}@index{Edit Options} EMACS and TECO allow variables with arbitrary names to be defined and given numbers or strings as values. EMACS uses many variables internally, but also has several 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. @index{@CMC[]}@index{C-]}@index{^R Exit}@index{Abort Recursive Edit} 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 Help for more information on the format used. When you are finished, exit Edit Options using @CMC[] and the changes will take effect. If you screw up, C-] gets out without redefining the options. 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. @index{Set Variable}@index{numeric arguments}@index{string arguments} However, Edit Options can be used only to set a variable which already exists, and is marked as an option. Some commands may 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. You can 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 can't abbreviate it (how could EMACS know what it was an abbreviation of?), and 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 gave it. To examine the value of a single variable, the command M-X View Variable can be used. 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 someone else's. @InfoNote(Name="Init", File="CONV", Node="Init"), for details. An EVARS file is a much simpler thing which you can do yourself. @Note(Name="EVARS", Node="Init"). @index{local variables} 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, @xxi[by anyone]. Editing other files is not affected. @Note(Node="Locals"), for how to do this. @index{List Variables}@index{Describe} You can get a list of all variables, not just those you are likely to want to edit, by doing M-X List Variables. Giving List Variables a string argument show 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. @index{TECO} You can also set a variable with the TECO command U or :I. This is useful in init files. @InfoNote(Name="Variables", File="CONV", Node="Variables"), for more information on how variables are implemented, and how to manipulate them in TECO code. While we are on the subject of variables, we should also mention the syntax table. It isn't a variable, strictly speaking, but it is almost like one. @Note(Node="Syntax"). @Node(Name="Syntax", Prev="Variables", Up="Variables") @Section[The Syntax Table] @index{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 its conventions, let's talk about the syntax of the syntax table itself. @index{words} 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. @index{lists}@index{s-expressions} The second character in each group is the Lisp syntax. It has many possible values: @commands[ 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 ] Thus, several characters can each be given the syntax of parentheses. The automatic display of matching feature uses the syntax table to decide when to go into operation as well as how to balance the parentheses. The syntax of "prefix character" means that the character becomes part of whatever object follows it, or 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. @index{comments} A comment starter is taken to start a comment, which ends at the next comment ender, suppressing the normal syntax of all characters between. Not all the commands which might be expected to know about comments do know about them; there a problems more than simply a need for work. Also, the syntax table entry is not what controls the commands which deal specifically with comments. They use the variables Comment Start, Comment Begin, Comment End, etc. Only the indentation commands use the syntax table for this. 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 a close parenthesis character is matched by the wrong kind of open parenthesis character, the bell will ring. 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. @index{Edit Syntax Table}@index{Altmode}@index{C-]}@index{recursive editing level} When you call Edit Syntax Table to edit the table, it displays the syntax table broken up according to characters. 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 syntax group (of five characters). Overwrite mode is on, so you can just type the desired syntax entries. You can also do arbitrary editing, but be careful not to change the position in the buffer of anything. 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. @index{major modes} Many major modes alter the syntax table. Each 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: @Example[ 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. @index{& Alter ..D}@index{TECO} 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. @Node(Name="Init", Prev="Variables", Next="Text") @Section[Init Files and EVARS Files] @index{init files}@index{EVARS files}@index{customization} 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. @index{TECO} 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, @ITS{;EMACS}@Twenex{EMACS.INIT}. 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. @InfoNote(Name="Init:", File="CONV"), for more about init files. @Index{Home Directory}@Index{User Name} 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, are ignored. They can be used as comments. Your EVARS file is found by its filename, just as an init file is, but it should be called @ITS{; EVARS instead of EMACS.} @Twenex{EMACS.VARS instead of EMACS.INIT.} 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. @index{variables} To set a variable, just include in the EVARS file a line containing the name of the variable, a colon, and the value. If you want a string as a value, give the string; if you want a number as a value, give the digits with an optional minus sign. (If you happen to want a value which is a string of all digits, you are out of luck.) Do NOT put spaces around the colon for visual effect. Space before the colon is part of the variable name, and space after the colon is part of the value of the variable. Examples: @example[ Comment Column:70 Comment Start:; Text Mode Hook:1M.LAuto Fill Mode ] @index{Auto Fill Mode} Text Mode Hook, by the way, is supposed to hold a TECO program to be executed whenever Text mode is entered, and the TECO program supplied by this particular definition is designed to turn on Auto Fill mode at that time. The effect is that Auto Fill is always on when you are in Text mode. @index{redefining commands} 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 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. Example: @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 does not hurt in this case because it is ignored by TECO expression execution. 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. @index{C-X}@index{prefix characters} 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. @InfoNote(Name="Defining prefixes", File="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 @example[ :.X( ^ S): M.M^R Save File ] 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. To connect a command character to a function from a library which is not normally loaded, you can do @example[ . R,: MM LoadFOOW M.MBar ] This loads the library FOO and connects the command C-Comma to the function Bar, presumably found in that library. The "W" is necessary because it discards the value returned by MM Load so that it does not interfere with the M.MBar. To simply load a library you can write a definition for "*". Such a definition is ignored except that the value you specify is executed as a TECO expression. Thus, an arbitrary TECO expression can be snuck into an EVARS file. To load the library FOO, use the expression MM LoadFOO. @example[ *: MM LoadFOO ] @Node(Name="Text", Prev="Init", Next="Programs") @Chapter[Commands Good for English Text] @manual{EMACS allows the user to manipulate words, sentences, or paragraphs of his text. In addition, there are commands to fill text, and convert case. @ITS{For text-justifier input files, there are commands that may help manipulate font change commands and underlining.} @index{^R Tab to Tab Stop}@index{Edit Tab Stops}@index{Text mode}@index{Tab} @index{syntax table}@index{comments}@index{parentheses} Editing files of text in a human language ought to be done using Text mode rather than Fundamental mode. 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(Name="Tab Stops", Node="Textindent").). Comments are declared not to exist. 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. } @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) } @Node(Name="Words", Prev="Text", Up="Text", Next="Sentences") @Section[Word Commands] @index{words}@index{Meta} EMACS has commands for moving over or operating on words. By convention, they are all Meta- characters. @WideCommands[ 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-@@. @index{motion}@index{M-F}@index{M-B}@index{^R Forward Word}@index{^R Backward Word} 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, and can be made to go in the opposite direction with a negative argument. Forward motion stops right after the last letter of the word, while backward motion stops right before the first letter. @index{killing}@index{M-Rubout}@index{M-D}@index{^R Kill Word}@index{^R Backward Kill Word} 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", "FOO, " is killed. In such a situation, to avoid killing the comma and space, do a Meta-B and a Meta-D instead of a Meta-Rubout. @index{transposition}@index{numeric arguments}@index{M-T}@index{^R Transpose Words} 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. A negative argument undoes the effect of 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 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,". @index{mark}@index{M-@@}@index{^R Mark Word} 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. They can be given arguments just like Meta-F. The case conversion operations have alternative forms that apply to words, since they are particularly useful that way. @index{Atom Word mode} 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. @index{syntax table} 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(Node="Syntax"). @Node(Name="Sentences", Prev="Words", Up="Text", Next="TextIndent") @Section[Sentence and Paragraph Commands] @index{sentences}@index{paragraphs} The EMACS commands for manipulating sentences and paragraphs are all Meta- commands, so as to resemble the word-handling commands. @Commands{ M-A@\Move back to the beginning of the sentence. M-E@\Move forward to the end of the sentence. M-K@\Kill this or next 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 beginning of sentence. } @index{motion}@index{M-A}@index{M-E}@index{^R Backward Sentence}@index{^R Forward Sentence} 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, but unlike those Control characters Meta-A and Meta-E if repeated move over several 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. @index{C-A}@index{C-E}@index{C-K}@index{killing}@index{M-K}@index{C-X Rubout} @index{^R Kill Sentence}@index{^R Backward Kill 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 commands 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. @index{M-[}@index{M-]}@index{^R Backward Paragraph}@index{^R Forward Paragraph} There are similar commands for moving over 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. @index{blank lines} 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. @index{Fill Prefix} When there is a fill prefix, then paragraphs are delimited by all lines which don't start with the fill prefix. @index{Region}@index{mark}@index{C-W}@index{C-U C-@@}@index{M-H}@index{^R Mark Paragraph} When you wish to operate on a paragraph, you can use the command Meta-H (^R Mark Paragraph) to prepare. 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. @index{Paragraph Delimiter}@index{TECO}@index{Page Delimiter}@index{pages} The variable Paragraph Delimiter should be a TECO search string (@Note(Name="TECO search string", Node="TECOsearch").) composed of various characters 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 "@@", and 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. @Node(Name="TextIndent", Prev="Sentences", Up="Text", Next="Filling") @Section[Indentation Commands for Text] @index{indentation}@index{formatting} @WideCommands[ Tab@\Indents line "appropriately". M-Tab@\Inserts a tab character. Linefeed@\Is the same as Return and Tab. M-^@\Undoes a Linefeed. Merges two lines. M-M@\Moves to the line's first nonblank character. M-I@\Indent to tab stop C-M-\@\Indent several lines to same column. C-X Tab@\Shift block of lines rigidly right or left. ] @index{Tab}@index{Linefeed}@index{^R Indent New Line} 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. @index{Edit Indented Text} @index{Auto Fill Mode}@index{Space Indent Flag} For English text, usually only the first line of a paragraph is indented. When Auto Fill mode needs to break an overlong line, it usually indents the newly started line. However, in Text mode, this is inhibited by setting the variable Space Indent Flag to zero. This is so that Auto Fill can avoid indenting without denying you the use of Tab to indent. But sometimes you want to have an indented paragraph. For this, 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). @index{M-\}@index{M-^}@index{^R Delete Horizontal Space}@index{^R Delete Indentation} 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 one, do C-A, C-O, and then Tab. To make an indented line after the current one, use C-E Linefeed. @index{M-M}@index{C-M-M}@index{^R Back to Indentation} 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. 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. @Subsection[Tab Stops] @index{Edit Tab Stops}@index{Tab Stop Definitions}@index{M-I}@index{^R Tab to Tab Stop} Set the tab stops using Edit Tab Stops, which displays for you a buffer whose contents define the tab stops. The first line contains a colon or period at each tab stop. Colon indicates an ordinary tab, which you fill to 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. 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. When you are not editing the tab settings, they live in the value of the variable Tab Stop Definitions. If the second line is not needed, the variable can be just one line, with no CRLF needed. This makes the value of the variable fit in one line, which makes it more convenient to redefine local to a file (@Note(Node="Locals").) @index{numeric arguments}@index{C-M-\}@index{C-X Tab} @index{^R Indent Region}@index{^R Indent Rigidly} There are also commands for changing the indentation of several lines at once. Control-Meta-\ (^R Indent Region) gives each line whose first character is between point and mark the "usual" indentation (as determined by Tab). With a numeric argument, it gives each line precisely that much indentation. C-X Tab (^R Indent Rigidly) moves all of the lines in the region right by its argument (left, for negative arguments). @index{Indent Tabs Mode}@index{minor modes}@index{Tabify}@index{Untabify} Usually, EMACS uses both tabs and spaces to indent. If you don't want that, you can use M-X Indent Tabs Mode to turn the use of tabs on or off. To convert all tabs in a file to spaces, you can use M-X Untabify, whose argument is the number of positions to assume between tab stops (default is 8). 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. @Node(Name="Filling", Prev="TextIndent", Up="Text", Next="Case") @Section[Text Filling] @index{filling} @Commands[ 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. ] @index{Auto Fill Mode}@index{Space} EMACS's Auto Fill mode lets you type in text that is filled (broken up into lines that just fit into 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 are usually indented, but in Text mode they are not. To leave Auto Fill mode, execute M-X Auto Fill again. @index{numeric arguments} 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 creates another blank line. @index{M-Q}@index{paragraphs}@index{M-G}@index{^R Fill Region}@index{^R Fill Paragraph} If you edit the middle of a paragraph, it may no longer be correctly filled. To re-fill 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 re-filled. All the line-breaks are removed, and then new ones are inserted where necessary. @index{M-H} If you are not happy with Meta-Q's idea of where paragraphs start and end (the same as Meta-H's. @note(Name="Paragraphs", Node="Sentences").), you can use Meta-G (^R Fill Region) which re-fills 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 not fill it in with the preceding line. The sequence space-backspace at the front of a line will prevent 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. But that's what M-G is for. Giving an argument to M-G or M-Q causes the text to be justified instead of 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. @index{M-S}@index{centering}@index{^R Center Line} 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. @index{Fill Column}@index{C-X F}@index{^R Set Fill Column} The maximum line width for filling is in the variable Fill Column. Both types of filling make sure that no line exceeds this width. The easiest way to set this variable is to use the command C-X F (^R Set Fill Column) which places the margin at the column point is on, or wherever you specify with a numeric argument. The fill column is initially column 70. @index{Fill Prefix}@index{C-X .}@index{^R Set Fill Prefix} 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 the cursor to a spot right after the special marker and give the command C-X . (^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 will insert the fill prefix at the front of each new line. Also, any line which does not start with the fill prefix will be considered to start a paragraph. To turn off the fill prefix, do C-X . with the cursor at the front of a line. @index{Space Indent Flag} The variable Space Indent Flag controls whether Auto Fill mode indents the new lines that it creates. A nonzero value means that indentation should be done. @Index{C-X =}@Index{What Cursor Position} The command C-X = (What Cursor Position) is very useful for ticklish situations in volving filling. It is the way to find out what column a character is in, among other things. @Note(Name="C-X =", Node="Modeline"). @ITS{@Node(Name="Case", Prev="Filling", Up="Text", Next="Fonts")} @Twenex{@Node(Name="Case", Prev="Filling", Up="Text")} @Section[Case Conversion Commands] @index{case conversion} EMACS has commands for converting either a single word or any arbitrary range of text to upper case or to lower case. @WideCommands[ 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. ] @index{M-L}@index{M-U}@index{M-C}@index{words}@index{^R Lowercase Word}@index{^R Uppercase Word}@index{^R Uppercase Initial} 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. @index{numeric arguments} 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. @index{C-X C-L}@index{C-X C-U}@index{Region}@index{confirmation}@index{undo} @index{^R Lowercase Region}@index{^R Uppercase Region} 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(Node="Undo").). @ITS{ @Node(Name="Fonts", Prev="Case", Up="Text", Next="Underlining") @Section[Font-Changing] @index{Fonts}@index{TJ6}@index{R}@index{text justifiers} EMACS has commands to insert and move font change commands as understood by the TJ6 and R 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. @WideCommands[ M-#@\Change previous word's font, or next word's. C-X #@\Change font of region. ] @index{M-#}@index{words}@index{numeric arguments}@index{^R Change Font Word} M-# 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 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 @xxii[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! @index{C-X #}@index{Region}@index{^R Change Font Region} You can also change the font of a whole region by putting point and the mark around it and issuing C-X #, with the font number as argument. C-X # with a negative argument removes all font changes inside or adjacent to the region. @Node(Name="Underlining", Prev="Fonts", Up="Text") @Section[Underlining] @index{underlining}@index{text justifiers}@index{R} 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. @WideCommands[ M-_@\Underline previous word or next word. C-X _@\Underline region. ] @index{M-_}@index{words}@index{^R Underline Word} 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. @index{numeric arguments} 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 @xxii[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. @index{C-X _}@index{Region}@index{^R Underline Region} 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. @index{Underline Begin}@index{Underline End} 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.} @Comment{End ITS} @Node(Name="Programs", Prev="Text", Next="Narrowing") @Chapter[Commands for Editing Programs] @manual{ 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{ * 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(Node="Words"). Moving over words is useful for editing programs as well as text. @Note(Name="Paragraphs", Node="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. @InfoNote(Name="Tags", File="TAGS"). The TAGS package can remember all the labels or functions in a multi-file program and find any one of them quickly. @Node(Name="Indenting", Prev="Programs", Up="Programs", Next="Matching") @Section[Indentation Commands for Code] @WideCommands[ 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. ] @index{Tab}@index{indentation}@index{Lisp}@index{MIDAS}@index{TECO} 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. The way to request indentation is with the Tab command. Its precise effect depends on the major mode. 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. PL1 mode (@InfoNote(Name="PL1", File="EPL1").) knows in great detail about the keywords of the language so as to indent lines according to the nesting structure. } @index{Linefeed}@index{^R Indent New Line} 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, just as Return would make an empty line. Linefeed in the middle of a line breaks the line and supplies the usual indentation in front of the new line. @index{M-^}@index{C-M-^}@index{^R Delete Indentation}@index{M-\}@index{^R Delete Horizontal Space} 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 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. @index{C-A}@index{C-O}@index{C-E}@index{M-M}@index{C-M-M} 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, 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. @Node(Name="Matching", Prev="Indenting", Up="Programs", Next="Comments") @Section[Automatic Display Of Matching Parentheses] @index{matching}@index{parentheses} The purpose of the EMACS parenthesis-matching feature is to show automatically how parentheses balance in text being 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, if you don't type any more commands during that time. If you type more commands before the second is up, EMACS won't wait the whole second. It is worth emphasizing that the real location of the cursor -- the place where your type-in will be inserted -- is not affected by the close parenthesis matching feature. It stays after the close parenthesis, where it would normally be. Only the spot on the screen moves away and back. You can type ahead freely as if the matching feature were not there. In fact, if you type fast enough, you won't see the cursor move. You must pause after typing a close parenthesis to see the open parenthesis. @index{Display Matching Paren}@index{Permit Unmatched Paren} 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 recenter the window to show the text around the open parenthesis. The default setting of the variable is -1. An additional parameter is whether EMACS should warn you if you type an unmatched close parenthesis. The default is to warn you if you are editing a language in which parentheses are essential, like 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 -1, you are warned only in Lisp mode and similar modes (this is the default). Note that these modes operate by locally setting the variable to 1 if it was -1. When it is 0, you are warned regardless of the major mode. Unmatched parens are @XXI[always] "permitted" in that EMACS will never refuse to insert them. @index{Text mode}@index{Text Mode Hook}@index{syntax table}@index{TECO} 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. @InfoNote(Name="Hooks", File="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 ")" will cause the matching character with syntax "(" to be shown. Most major modes automatically set up the syntax table (@Note(Node="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. The implementation of this feature uses the TECO flag FS ^R PAREN. @Node(Name="Comments", Prev="Matching", Up="Programs", Next="Lisp") @Section[Manipulating Comments] @index{comments}@index{C-;}@index{M-;}@index{indentation}@index{^R Indent for Comment} The comment commands insert, kill and align comments. There are also commands for moving through existing code and inserting comments. @WideCommands[ C-;@\insert or align comment M-;@\the same C-M-;@\kill comment 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 Control-; or Meta-; (^R Indent for Comment). It moves to the end of the line, indents to the comment column, and inserts whatever string EMACS believes comments are supposed to start with (normally ";"). If the line goes past the comment column, then the indentation is done to a suitable boundary (usually, a multiple of 8). If the language you are editing requires a terminator for comments (other than the end of the line), the terminator is inserted too, but point goes between the starter and the terminator. Control-; can also be used to align an existing comment. If a line already contains the string that starts comments, then C-; just moves point after it and indents it to the right place (where a comment would have been created if there had been none). Even when an existing comment is properly aligned, C-; is still useful for moving directly to the start of the comment. @index{numeric arguments} If you wish to align a large number of comments, you can give Control-; 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). @index{M-N}@index{M-P}@index{^R Down Comment Line}@index{^R Up Comment Line} 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. @index{M-J}@index{M-Linefeed}@index{blank lines}@index{Auto Fill mode} @index{^R Indent New Comment Line} 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, instead of putting the next line of the comment on the next line of code. To do that, use M-N. 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 Atsign program takes a four-semicolon comment to be a subtitle, in Lisp code. @index{Comment Column}@index{C-X ;}@index{^R Set Comment Column} 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. @index{major modes} Many major modes supply default local values for the comment column. In addition, C-X ; automatically makes the variable Comment Column local. Otherwise, it changes globally (for all buffers that don't have it as a local) unless you make it local yourself. @index{C-M-;}@index{^R Kill Comment} 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. Since killed text can be reinserted with C-Y, this command is useful for moving a comment from one line to another. @index{Comment Start}@index{Comment Begin} 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 ";; ** ". @index{Comment End} 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. @Node(Name="Lisp", Prev="Comments", Up="Programs", Next="Lists") @Section[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. @index{^R Indent for Lisp}@index{Tab}@index{Lisp mode} 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. @index{Rubout}@index{C-Rubout}@index{^R Backward Delete Character} @index{^R Backward Delete Hacking Tabs} 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. @index{Paragraphs}@index{syntax table}@index{comments}@index{auto fill}@index{blank lines} 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 ";". In Lisp mode, the action of the word-motion commands is affected by whether you are in atom word mode or not. @index{Muddle mode} 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. @Node(Name="Lists", Prev="Matching", Up="Programs", Next="Defuns") @SubSection[Moving Over and Killing Lists and S-expressions] @index{Lists}@index{s-expressions} @DoubleWideCommands[ 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 reindent ] @index{Control-Meta} 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). @index{motion}@index{C-M-F}@index{C-M-B}@index{^R Forward Sexp}@index{^R Backward Sexp} To move forward over an s-expression, use C-M-F (^R Forward Sexp). If the first non-"useless" 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 atom-break character that ends 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 the pointer after " 'FOO ", C-M-B leaves the pointer before the "'", not before the "F". @index{comments} 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 wouldn't be so bad, but handling comments and "|" both is impossible to do locally. In a line " ((FOO ; | BAR ", are the open parentheses inside of a "| ... |" atom? I do not think it would be advisable to make C-M-F handle comments without making C-M-B handle them as well. @index{C-M-N}@index{C-M-P}@index{^R Forward List}@index{^R Backward List} 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 just 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. @index{killing}@index{C-M-Rubout}@index{C-M-K}@index{^R Backward Kill Sexp}@index{^R Kill Sexp} 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. @index{C-M-U}@index{C-M-(}@index{C-M-)}@index{C-M-D}@index{^R Backward Up List} @index{^R Forward Up List}@index{^R Down Sexp} C-M-F and C-M-B stay at the same level in parentheses, when that's possible. To move @xxii[up] one (or n) levels, use C-M-( or C-M-) (^R Backward Up List and ^R Forward Up List). C-M-( moves backwards up past one containing "(". C-M-) moves forwards 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 (behave like the C-M-) command). To move @xxii[down] in list structure, use C-M-D (^R Down Sexp). It is nearly the same as searching for a "(". @index{transposition}@index{C-M-T}@index{^R Transpose Sexps} A somewhat random-sounding command which is nevertheless easy to use is C-M-T (^R Transpose Sexps), which moves the cursor forward over one s-expression, dragging the previous s-expression along. An argument serves as a repeat count, and a negative argument drags backwards (thus canceling out the effect of a positive argument). An argument of zero, rather than doing nothing, transposes the s-expressions at the point and the mark. @index{mark}@index{C-M-@@}@index{^R Mark Sexp} To perform a miscellaneous operation on 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. @Index{M-(}@Index{M-)}@Index{^R Insert ()}@Index{^R Move Over )} The commands M-( and M-) 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. @index{syntax table} 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(Node="Syntax"). @Node(Name="Defuns", Prev="Lists", Up="Programs", Next="Grinding") @SubSection[Commands for Manipulating Defuns] @index{Defuns} @DoubleWideCommands( 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. ) @index{C-M-A}@index{C-M-E}@index{C-M-H}@index{mark}@index{Region}@index{motion}@index{C-M-[}@index{C-M-]} @index{^R Beginning of Defun}@index{^R End of Defun}@index{^R Mark Defun} In EMACS, a list at the top level in the buffer is called a defun, regardless of what function is actually called, because such lists 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. @Node(Name="Grinding", Prev="Defuns", Up="Programs", Next="MIDAS") @Section[Lisp Grinding] @index{indentation}@index{formatting}@index{grinding}@index{Tab}@index{C-M-Tab} The best way to keep Lisp code indented properly 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. @WideCommands[ Tab@\In Lisp mode, reindents 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@\Reindent all the lines within one list. C-M-G@\Grind a list, moving code between lines. ] @index{^R Indent for Lisp}@index{C-M-Tab} 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 to insert a tab). When given at the beginning of a line, it leaves point after the indentation; when given inside the text on the line, point remains fixed with respect to the characters around it. @index{Linefeed}@index{^R Indent New Line} When entering a large amount of new code, it becomes useful that Linefeed (^R Indent New Line) is equivalent to a Return followed by a Tab. In Lisp mode, a Linefeed creates or moves down onto a blank line, and then give it the appropriate indentation. @index{C-M-^}@index{M-^}@index{^R Delete 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 wants to place 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. Of course, it is the wrong thing for PROG tags (if you like to un-indent them), but it's impossible to be right for both. @index{numeric arguments} 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. @index{C-M-Q}@index{^R Indent Sexp} 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. @index{C-M-\}@index{Region}@index{^R Indent Region} 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. @index{C-M-G}@index{Macsyma}@index{^R Format Code} 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. @Node(Name="MIDAS", Prev="Grinding", Up="Programs", Next="Other Langs") @Section[Editing Assembly-Language Programs] @index{MIDAS}@index{Macro-10}@index{FAIL}@index{MIDAS mode} M-X MIDAS Mode is designed for editing programs written in MIDAS or other PDP-10 or PDP-11 assemblers. @Twenex{ (MACRO mode and FAIL mode also exist but differ only in the syntax table).} 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: @index{C-M-N}@index{C-M-P}@index{C-M-A}@index{C-M-E}@index{C-M-D}@index{M-]}@index{M-[} @index{^R Go to Next Label}@index{^R Go to Previous Label} @index{^R Go to AC Field}@index{^R Go to Address Field} @index{^R Kill Terminated Word}@index{^R Forward Paragraph}@index{^R Backward Paragraph} @index{labels}@index{accumulator}@index{address}@index{paragraphs} @WideCommands{ 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. M-[@\Move up to previous paragraph boundary. M-]@\Move down to next paragraph boundary. } @index{comments} 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. @index{Paragraph Delimiter} The M-[ and M-] commands are not, strictly speaking, redefined by MIDAS mode, since they always go up or down to a paragraph boundary. However, in MIDAS mode the criterion for a paragraph boundary is changed by setting the variable Paragraph Delimiter (@Note(Name="Paragraphs", Node="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. @Node(Name="Other Langs", Prev="MIDAS", Up="Programs") @Section[Major Modes for Other Languages] @index{C-M-G}@index{Macsyma mode} 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. @Twenex{ @Index{Interlisp} Interlisp mode is similar to Lisp mode, but it tailors the syntax table to Interlisp. In particular, % quotes characters in symbols, and comments are delimited by @W["(* "] and ")". It is possible to run EMACS as an inferior of Interlisp, passing functions from Interlisp, editing them and passing them back to Interlisp. @INFONote(Name="Interlisp", File="INTER").} @index{M-'}@index{M-"}@index{TECO mode}@index{^R Indent Nested}@index{PURIFY library} @index{^R Forward TECO Conditional}@index{^R Backward TECO Conditional} TECO mode is good for editing EMACS library source files. It makes Tab be ^R Indent Nested (see its self-documentation). Comments start with @W["!* "] 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 characters to insert Control characters. 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. @InfoNote(Name="PL1", File="EPL1"). PASCAL mode is similar to PL1 mode, for PASCAL. It is in the library called PASCAL. @InfoNote(Name="PASCAL", File="EPASC"). There are also modes for BLISS and BCPL, but no documentation for them except that in the libraries themselves. Any volunteers? @Node(Name="Narrowing", Prev="Programs", Next="Paging") @Chapter[Narrowing] @index{narrowing} @WideCommands[ C-X N@\Narrow down to between point and mark. C-X W@\Widen to view the entire buffer. C-X P@\Narrow down to the page point is in. ] "Narrowing" means focusing in on some portion of the buffer, making the rest temporarily invisible and inaccessible. 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 you are editing 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. @index{C-X N}@index{Region}@index{^R Set Bounds Region} The primary narrowing command is C-X N (^R Set Bounds Region). It sets the "virtual buffer boundaries" at point and the mark, so that only what was between them remains visible. Point moves to the top of the now-visible range, and the mark is left at the end, so that the region marked is unchanged. @index{C-X W}@index{^R Set Bounds Full} The way to undo narrowing is to widen with C-X W (^R Set Bounds Full). 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 Set Bounds Page). @Note(Node="Paging"). Note that the virtual buffer boundaries are a powerful TECO mechanism used internally in EMACS in many ways. While only the commands described here set them permanently, many others set them temporarily using the TECO commands FS VB and FS VZ, and restore them before finishing. @Node(Name="Paging", Prev="Narrowing", Next="Minibuffer") @Chapter[Commands for Manipulating Pages] @index{pages} @WideCommands{ 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. } @index{C-M-L}@index{insertion} Most editors make the division of a file into pages extremely important. The page separators have fundamental effects on the editors' behavior. 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 work on them. @index{C-X [}@index{C-X ]}@index{motion}@index{^R Next Page}@index{^R Previous Page} @Note(Node="PAGE"), for a description of the PAGE library, which has extensions for making it convenient to edit viewing only one page at a time. } 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 past the next page delimiter. @index{What Page}@index{echo area} 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. @index{C-X C-P}@index{mark}@index{Region}@index{C-W}@index{^R Mark Page} 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 terminator at the end is included (the mark follows it). That 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. A numeric argument to C-X C-P is used to specify which page to go to, relative to the current one (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 the whole file for formfeeds). Zero means the current page. One means the next page, and -1 means the previous one. @index{C-X P}@index{narrowing}@index{C-X W}@index{^R Set Bounds Page} The command C-X P (^R Set Bounds Page) narrows down to just one page. Everything before and after becomes temporarily invisible and inaccessible (@Note(Node="Narrowing").). Use C-X W 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 moves you to the next page (otherwise, it would be a useless no-op). One effect of this quirk is that several C-X P's in a row get first the current page and then successive pages. @index{Page Delimiter} Just what delimits pages is controlled by the variable Page Delimiter, which should contain a TECO search string (@Note(Name="TECO search string", Node="TECOsearch").) which will match a page separator. Normally, it contains 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 _ (ie, whatever separates INFO nodes) should be a page separator. 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. @index{C-X L}@index{^R Count Lines Page} The C-X L command (^R Count Lines Page) is good for deciding where to break a page in two. It first 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 @example[ 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. @Node(Name="PAGE", Prev="Paging", Up="Paging") @Section[Editing Only One Page at a Time] @index{pages}@index{libraries}@index{PAGE}@index{mode line} The PAGE library is meant to allow the handling of pages as discrete, often independent units, letting you see only one page at a time, and providing commands to move between pages, split pages 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. @WideCommands( 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. ) @index{C-X C-P}@index{^R Goto Page} 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. @index{C-X [}@index{C-X ]}@index{^R Goto Previous Page}@index{^R Goto Next 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. @index{C-X W}@index{^R Widen Bounds} When you want to go back to viewing the whole file instead of just one page, you can use the C-X W (^R 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. @index{searching}@index{C-S}@index{C-R}@index{^R Incremental Search}@index{^R Reverse Search} The C-S (^R Incremental Search) and C-R (^R Reverse Search) 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. @index{C-X P}@index{C-X J}@index{split pages}@index{join pages} @index{^R Insert Pagemark}@index{^R Join Next Page} To split an existing page, you could insert a L, but unless you do this while seeing the whole file, PAGE might get confused for a while. A way that is less tricky is to use C-X P (^R Insert Pagemark) which inserts the right things, selects the second of the two pages formed from the old page, and guarantees that things will be consistent. To get rid of a page mark without worry, 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. @index{PAGE Flush CRLF} A pagemark is defined as L. if you set the variable PAGE Flush CRLF to 1, a pagemark is be 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; the value of Page Delimiter will be used. If Page Delimiter specifies multiple alternatives, the first alternative is the one PAGE will insert, but all will be recognized. @index{comments}@index{View Page Directory}@index{Insert Page Directory} 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. @Node(Name="Minibuffer", Prev="Paging", Next="KBDMAC") @Chapter[The Minibuffer] @WideCommands[ 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. @CC[] C-Y@\Rotate ring of recent minibuffer commands. ] @index{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. The minibuffer also allows the EMACS user to type in a TECO program and execute it. @index{mode line} 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. @index{M-%}@index{Query Replace}@index{^R Query Replace} 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. @index{Altmode} 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. @index{C-\}@index{metizer} 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 @CC[] 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 @CC[] 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. @index{C-G}@index{@CC[]} 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. @index{M-Altmode}@index{^R Execute Minibuffer} 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. @index{C-X Altmode}@index{confirmation}@index{^R Re-execute Minibuffer} 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) ref-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". @index{numeric arguments}@index{@CC[] C-Y} 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 and argument, as in C-U M-Altmode, causes the minibuffer to be loaded up with the last command in the ring, just 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 @CC[] 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 @CC[] C-Y reveals an earlier command string, until the ring has rotated all the way around and the most recent one reappears. @CC[] 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. @index{C-X ^}@index{^R Grow Window} 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. @Node(Name="KBDMAC", Prev="Minibuffer", Next="PICTURE") @Chapter[Keyboard Macros] @WideCommands[ 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. ] @index{keyboard macros} 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. @index{TECO} 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. @index{C-X (}@index{C-X )}@index{C-X E}@index{^R Start Kbd Macro}@index{^R End Kbd Macro} @index{^R Execute Kbd Macro} 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. An argument of zero means to repeat the macro indefinitely (until it gets an error). C-X ) can also be given a repeat count as an argument, in which case it re-invokes the macro, but defining the macro counts as one repetition (since it is executed as you define it). So, giving C-X ) an argument of 2 executes the macro one additional time. @index{Name Kbd Macro} If you wish to save a keyboard macro for longer than until you define the next one, you must give it a name. Do M-X Name Kbd MacroFOO and 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 redefine that character command to invoke the macro. If you don't want to redefine a command, type a Return or Rubout. Only self-inserting and undefined characters, and those that are already keyboard macros, can be redefined in this way. Prefix characters may be used in specifying the command to be redefined. @index{View Kbd Macro} 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, on the terminal when View Kbd Macro asks for it. @index{C-X Q}@index{^R Kbd Macro Query} 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 @xxii[not] become part of the macro. When you are done, exit with @CMC[] 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 @CMC[], the execution of the macro will resume. If you abort the recursive editing level with C-], you will abort the macro definition or execution. @index{Query Replace}@index{Space}@index{Rubout}@index{C-L}@index{C-R}@index{Altmode} 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. @manual{@include(word)@include(tags)@String(Filename="EMACS")} @Node(Name="PICTURE", Prev="KBDMAC", Next="Sort") @Chapter[The PICTURE Subsystem, an Editor for Text Pictures] @index{pictures}@index{Edit Picture} 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. @index{libraries} 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 @CMC[], 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. @index{Up Picture Movement}@index{Down Picture Movement} @index{Left Picture Movement}@index{Right Picture Movement} 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. @Twenex{@Node(Name="Sort", Prev="PICTURE", Next="Misc")} @ITS{@Node(Name="Sort", Prev="PICTURE")} @Chapter[Sorting Functions] @index{sorting}@index{Region}@index{pages}@index{paragraphs}@index{lines} @index{Sort Lines}@index{Sort Paragraphs}@index{Sort Pages} 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(Name="Paragraph", Node="Sentences").) and pages are defined as for the page motion commands (@Note(Node="Paging").). All of these functions can be undone by the Undo command (@Note(Node="Undo").). They take no arguments. @Twenex{ @Node(Name="Misc", Prev="Sort") @Chapter[Miscellaneous Functions] @index{Push to EXEC}@index{inferiors}@index{forks}@index{Exec Name}@index{Check Mail}@index{Mail} @index{Read Mail}@index{Mail Reader}@index{MM (mail reader)}@index{TECO} M-X Push to EXEC forks up a copy of the system command language and puts you in the new fork. You can return to EMACS via POP. The fork is maintained so that the next invocation of M-X Push to EXEC gets you the EXEC you left in the last call. The variable Exec Name contains the name of the file to run, or 0 for the ordinary EXEC. M-X Check Mail checks to see if you have any new mail. M-X Mail or M-X Read Mail runs the program specified by QMail Reader which defaults to the program "MM" (no relation to EMACS "MM" commands). On subsequent calls the fork is continued rather than restarted. A numeric argument means kill the mail reader fork instead of running it. These use the TECO command FZ, which can be used in general for running any program as an inferior fork under TECO. } @Comment(End Twenex) @manual{ @Appendix(Particular Types of Terminals) } @Node(Name="Ideal", Up="Characters", Prev="Characters") @AppendixSection[Ideal Keyboards] @index{meta}@index{SAIL characters} @ITS{@INDEX[Escape key]} An ideal EMACS keyboard can be recognized because it has a Control key and a Meta key on each side, with another key labelled Top above them. On an ideal keyboard, to type any character in the 9-bit character set just 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. @ITS{ 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 @xxi[echo] 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 echos 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 character Control-Alpha (Alpha is a SAIL character) toggles the choice. You can only type this command on a terminal with a Top key, but since only such terminals can display SAIL characters anyway this is no loss. 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. @INFO{*Note Bit Prefix: Characters.} To type numeric arguments on these keyboards, just type the digits or minus sign while holding down either Control or Meta. @Node(Name="EditKey", Up="Characters", Prev="Characters") @AppendixSection[Keyboards with an "Edit" key] @index{Edit key}@index{meta} 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@Twenex{, C-B, C-D} through C-@ITS{Y}@Twenex{Z}, C-], C-@@, C-\, and C-^. C-Z@ITS{ and C-_} can be typed on the terminal but @ITS{they are}@Twenex{it is} intercepted by the operating system and therefore unavailable as EMACS command@ITS(s). C-[ is not available because its spot in ASCII is pre-empted by Altmode. The corresponding 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 @CC[] and type @CC[] ;. 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. @ITS{ 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. } @index{numeric arguments} To type numeric arguments, it is best to type the digits or minus sign while holding down the Edit key. @Node(Name="Losers", Up="Characters", Prev="Characters") @AppendixSection[ASCII Keyboards] @index{Meta}@index{Edit key}@index{bit prefix characters}@index{metizer} 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@Twenex{, C-B, C-D} through C-@ITS{Y}@Twenex{Z}, C-], C-@@, C-\, and C-^. C-Z@ITS{ and C-_} can be typed on the terminal but @ITS{they are}@Twenex{it is} intercepted by the operating system and therefore unavailable as EMACS command@ITS(s). 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, @CC[] 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. @CC[] 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 @CC[] ;. 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. @ITS{ 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. } @index{numeric arguments}@index{autoarg mode}@index{init file} 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 even typing the Altmode is painful, you might enjoy using Autoarg mode, in which you can specify a numeric argument by just typing the digits. @Note(Name="Autoarg", Node="Arguments"), for details. @Node(Name="NoLowerCase", Up="Characters") @AppendixSection[Upper-case-only Terminals] @index{case conversion} 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 (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. @Comment(??? An accent grave character is needed here) 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$ @INFO[(dollar sign)]@LPT[(dollar sign)] and FS CASE, using M-X TECDOC, for full details. @INFO{* Note Case: Case, for commands to change the case of text already in the buffer. } @Node(Name="Printing", Up="Characters") @Appendix[Use of EMACS from Printing Terminals] @index{printing terminal} 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 @xxu(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. And so on. All forward-motion commands that move reasonably short distances echo 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 a sort of backward motion, but also prints a slash over the character rubbed out. Other backwards deletion commands also act like backward motion but are not hairy enough to print the slashes; it is up to you to remember that you did deletion and not motion. @index{C-L}@index{^R New Window} 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". @Manual{ @Include(GLOSS.MSS) @Include(COMMANDS.MSS) } @Case(Device, Dover { @Begin(Verbatim,FaceCode F) @Newpage(0) @Include(CHART.MSS) @End(Verbatim)}) @Info(@Verbatim(  Tag Table: this is just a dummy. TAGS will fill in the real stuff.  End Tag Table: )) @Comment( These are for the SCRIBE source file. Local Modes:* Paragraph Delimiter:  * Page Delimiter:@Node* End:* )