diff options
Diffstat (limited to 'info/emacs-9')
| -rw-r--r-- | info/emacs-9 | 1136 |
1 files changed, 1136 insertions, 0 deletions
diff --git a/info/emacs-9 b/info/emacs-9 new file mode 100644 index 00000000000..95456103ba1 --- /dev/null +++ b/info/emacs-9 @@ -0,0 +1,1136 @@ +This is Info file ../info/emacs, produced by Makeinfo-1.49 from the +input file emacs.texi. + + This file documents the GNU Emacs editor. + + Copyright (C) 1985, 1986, 1988, 1992 Richard M. Stallman. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the sections entitled "The GNU Manifesto", "Distribution" and "GNU +General Public License" are included exactly as in the original, and +provided that the entire resulting derived work is distributed under the +terms of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that the sections entitled "The GNU Manifesto", +"Distribution" and "GNU General Public License" may be included in a +translation approved by the author instead of in the original English. + + +File: emacs, Node: Lisp Eval, Next: Lisp Debug, Prev: Lisp Libraries, Up: Compiling/Testing + +Evaluating Emacs-Lisp Expressions +================================= + + Lisp programs intended to be run in Emacs should be edited in +Emacs-Lisp mode; this will happen automatically for file names ending +in `.el'. By contrast, Lisp mode itself is used for editing Lisp +programs intended for other Lisp systems. Emacs-Lisp mode can be +selected with the command `M-x emacs-lisp-mode'. + + For testing of Lisp programs to run in Emacs, it is useful to be +able to evaluate part of the program as it is found in the Emacs +buffer. For example, after changing the text of a Lisp function +definition, evaluating the definition installs the change for future +calls to the function. Evaluation of Lisp expressions is also useful in +any kind of editing task for invoking noninteractive functions +(functions that are not commands). + +`M-ESC' + Read a Lisp expression in the minibuffer, evaluate it, and print + the value in the minibuffer (`eval-expression'). + +`C-x C-e' + Evaluate the Lisp expression before point, and print the value in + the minibuffer (`eval-last-sexp'). + +`C-M-x' + Evaluate the defun containing or after point, and print the value + in the minibuffer (`eval-defun'). + +`M-x eval-region' + Evaluate all the Lisp expressions in the region. + +`M-x eval-current-buffer' + Evaluate all the Lisp expressions in the buffer. + + `M-ESC' (`eval-expression') is the most basic command for evaluating +a Lisp expression interactively. It reads the expression using the +minibuffer, so you can execute any expression on a buffer regardless of +what the buffer contains. When the expression is evaluated, the current +buffer is once again the buffer that was current when `M-ESC' was typed. + + `M-ESC' can easily confuse users who do not understand it, +especially on keyboards with autorepeat where it can result from holding +down the ESC key for too long. Therefore, `eval-expression' is +normally a disabled command. Attempting to use this command asks for +confirmation and gives you the option of enabling it; once you enable +the command, confirmation will no longer be required for it. *Note +Disabling::. + + In Emacs-Lisp mode, the key `C-M-x' is bound to the function +`eval-defun', which parses the defun containing or following point as a +Lisp expression and evaluates it. The value is printed in the echo +area. This command is convenient for installing in the Lisp +environment changes that you have just made in the text of a function +definition. + + The command `C-x C-e' (`eval-last-sexp') performs a similar job but +is available in all major modes, not just Emacs-Lisp mode. It finds +the sexp before point, reads it as a Lisp expression, evaluates it, and +prints the value in the echo area. It is sometimes useful to type in an +expression and then, with point still after it, type `C-x C-e'. + + If `C-M-x' or `C-x C-e' is given a numeric argument, it prints the +value by insertion into the current buffer at point, rather than in the +echo area. The argument value does not matter. + + The most general command for evaluating Lisp expressions from a +buffer is `eval-region'. `M-x eval-region' parses the text of the +region as one or more Lisp expressions, evaluating them one by one. +`M-x eval-current-buffer' is similar but evaluates the entire buffer. +This is a reasonable way to install the contents of a file of Lisp code +that you are just ready to test. After finding and fixing a bug, use +`C-M-x' on each function that you change, to keep the Lisp world in +step with the source file. + + +File: emacs, Node: Lisp Debug, Next: Lisp Interaction, Prev: Lisp Eval, Up: Compiling/Testing + +The Emacs-Lisp Debugger +======================= + + GNU Emacs contains a debugger for Lisp programs executing inside it. +This debugger is normally not used; many commands frequently get Lisp +errors when invoked in inappropriate contexts (such as `C-f' at the end +of the buffer) and it would be very unpleasant for that to enter a +special debugging mode. When you want to make Lisp errors invoke the +debugger, you must set the variable `debug-on-error' to non-`nil'. +Quitting with `C-g' is not considered an error, and `debug-on-error' +has no effect on the handling of `C-g'. However, if you set +`debug-on-quit' non-`nil', `C-g' will invoke the debugger. This can be +useful for debugging an infinite loop; type `C-g' once the loop has had +time to reach its steady state. `debug-on-quit' has no effect on +errors. + + You can also cause the debugger to be entered when a specified +function is called, or at a particular place in Lisp code. Use `M-x +debug-on-entry' with argument FUN-NAME to cause function FUN-NAME to +enter the debugger as soon as it is called. Use `M-x +cancel-debug-on-entry' to make the function stop entering the debugger +when called. (Redefining the function also does this.) To enter the +debugger from some other place in Lisp code, you must insert the +expression `(debug)' there and install the changed code with `C-M-x'. +*Note Lisp Eval::. + + When the debugger is entered, it displays the previously selected +buffer in one window and a buffer named `*Backtrace*' in another +window. The backtrace buffer contains one line for each level of Lisp +function execution currently going on. At the beginning of this buffer +is a message describing the reason that the debugger was invoked (such +as, what error message if it was invoked due to an error). + + The backtrace buffer is read-only, and is in a special major mode, +Backtrace mode, in which letters are defined as debugger commands. The +usual Emacs editing commands are available; you can switch windows to +examine the buffer that was being edited at the time of the error, and +you can also switch buffers, visit files, and do any other sort of +editing. However, the debugger is a recursive editing level (*note +Recursive Edit::.) and it is wise to go back to the backtrace buffer +and exit the debugger officially when you don't want to use it any +more. Exiting the debugger kills the backtrace buffer. + + The contents of the backtrace buffer show you the functions that are +executing and the arguments that were given to them. It has the +additional purpose of allowing you to specify a stack frame by moving +point to the line describing that frame. The frame whose line point is +on is considered the "current frame". Some of the debugger commands +operate on the current frame. Debugger commands are mainly used for +stepping through code an expression at a time. Here is a list of them. + +`c' + Exit the debugger and continue execution. In most cases, + execution of the program continues as if the debugger had never + been entered (aside from the effect of any variables or data + structures you may have changed while inside the debugger). This + includes entry to the debugger due to function entry or exit, + explicit invocation, quitting or certain errors. Most errors + cannot be continued; trying to continue one of them causes the + same error to occur again. + +`d' + Continue execution, but enter the debugger the next time a Lisp + function is called. This allows you to step through the + subexpressions of an expression, seeing what values the + subexpressions compute and what else they do. + + The stack frame made for the function call which enters the + debugger in this way will be flagged automatically for the + debugger to be called when the frame is exited. You can use the + `u' command to cancel this flag. + +`b' + Set up to enter the debugger when the current frame is exited. + Frames that will invoke the debugger on exit are flagged with + stars. + +`u' + Don't enter the debugger when the current frame is exited. This + cancels a `b' command on that frame. + +`e' + Read a Lisp expression in the minibuffer, evaluate it, and print + the value in the echo area. This is the same as the command + `M-ESC', except that `e' is not normally disabled like `M-ESC'. + +`q' + Terminate the program being debugged; return to top-level Emacs + command execution. + + If the debugger was entered due to a `C-g' but you really want to + quit, not to debug, use the `q' command. + +`r' + Return a value from the debugger. The value is computed by + reading an expression with the minibuffer and evaluating it. + + The value returned by the debugger makes a difference when the + debugger was invoked due to exit from a Lisp call frame (as + requested with `b'); then the value specified in the `r' command + is used as the value of that frame. + + The debugger's return value also matters with many errors. For + example, `wrong-type-argument' errors will use the debugger's + return value instead of the invalid argument; `no-catch' errors + will use the debugger value as a throw tag instead of the tag that + was not found. If an error was signaled by calling the Lisp + function `signal', the debugger's return value is returned as the + value of `signal'. + + +File: emacs, Node: Lisp Interaction, Next: External Lisp, Prev: Lisp Debug, Up: Compiling/Testing + +Lisp Interaction Buffers +======================== + + The buffer `*scratch*' which is selected when Emacs starts up is +provided for evaluating Lisp expressions interactively inside Emacs. +Both the expressions you evaluate and their output goes in the buffer. + + The `*scratch*' buffer's major mode is Lisp Interaction mode, which +is the same as Emacs-Lisp mode except for one command, LFD. In +Emacs-Lisp mode, LFD is an indentation command, as usual. In Lisp +Interaction mode, LFD is bound to `eval-print-last-sexp'. This +function reads the Lisp expression before point, evaluates it, and +inserts the value in printed representation before point. + + Thus, the way to use the `*scratch*' buffer is to insert Lisp +expressions at the end, ending each one with LFD so that it will be +evaluated. The result is a complete typescript of the expressions you +have evaluated and their values. + + The rationale for this feature is that Emacs must have a buffer when +it starts up, but that buffer is not useful for editing files since a +new buffer is made for every file that you visit. The Lisp interpreter +typescript is the most useful thing I can think of for the initial +buffer to do. `M-x lisp-interaction-mode' will put any buffer in Lisp +Interaction mode. + + +File: emacs, Node: External Lisp, Prev: Lisp Interaction, Up: Compiling/Testing + +Running an External Lisp +======================== + + Emacs has facilities for running programs in other Lisp systems. +You can run a Lisp process as an inferior of Emacs, and pass +expressions to it to be evaluated. You can also pass changed function +definitions directly from the Emacs buffers in which you edit the Lisp +programs to the inferior Lisp process. + + To run an inferior Lisp process, type `M-x run-lisp'. This runs the +program named `lisp', the same program you would run by typing `lisp' +as a shell command, with both input and output going through an Emacs +buffer named `*lisp*'. That is to say, any "terminal output" from Lisp +will go into the buffer, advancing point, and any "terminal input" for +Lisp comes from text in the buffer. To give input to Lisp, go to the +end of the buffer and type the input, terminated by RET. The `*lisp*' +buffer is in Inferior Lisp mode, a mode which has all the special +characteristics of Lisp mode and Shell mode (*note Shell Mode::.). + + For the source files of programs to run in external Lisps, use Lisp +mode. This mode can be selected with `M-x lisp-mode', and is used +automatically for files whose names end in `.l' or `.lisp', as most Lisp +systems usually expect. + + When you edit a function in a Lisp program you are running, the +easiest way to send the changed definition to the inferior Lisp process +is the key `C-M-x'. In Lisp mode, this runs the function +`lisp-send-defun', which finds the defun around or following point and +sends it as input to the Lisp process. (Emacs can send input to any +inferior process regardless of what buffer is current.) + + Contrast the meanings of `C-M-x' in Lisp mode (for editing programs +to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp +programs to be run in Emacs): in both modes it has the effect of +installing the function definition that point is in, but the way of +doing so is different according to where the relevant Lisp environment +is found. *Note Lisp Modes::. + + +File: emacs, Node: Abbrevs, Next: Picture, Prev: Compiling/Testing, Up: Top + +Abbrevs +******* + + An "abbrev" is a word which "expands", if you insert it, into some +different text. Abbrevs are defined by the user to expand in specific +ways. For example, you might define `foo' as an abbrev expanding to +`find outer otter'. With this abbrev defined, you would be able to get +`find outer otter ' into the buffer by typing `f o o SPC'. + + Abbrevs expand only when Abbrev mode (a minor mode) is enabled. +Disabling Abbrev mode does not cause abbrev definitions to be forgotten, +but they do not expand until Abbrev mode is enabled again. The command +`M-x abbrev-mode' toggles Abbrev mode; with a numeric argument, it +turns Abbrev mode on if the argument is positive, off otherwise. *Note +Minor Modes::. `abbrev-mode' is also a variable; Abbrev mode is on +when the variable is non-`nil'. The variable `abbrev-mode' +automatically becomes local to the current buffer when it is set. + + Abbrev definitions can be "mode-specific"--active only in one major +mode. Abbrevs can also have "global" definitions that are active in +all major modes. The same abbrev can have a global definition and +various mode-specific definitions for different major modes. A mode +specific definition for the current major mode overrides a global +definition. + + Abbrevs can be defined interactively during the editing session. +Lists of abbrev definitions can also be saved in files and reloaded in +later sessions. Some users keep extensive lists of abbrevs that they +load in every session. + + A second kind of abbreviation facility is called the "dynamic +expansion". Dynamic abbrev expansion happens only when you give an +explicit command and the result of the expansion depends only on the +current contents of the buffer. *Note Dynamic Abbrevs::. + +* Menu: + +* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. +* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. +* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. +* Saving Abbrevs:: Saving the entire list of abbrevs for another session. +* Dynamic Abbrevs:: Abbreviations for words already in the buffer. + + +File: emacs, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrevs, Up: Abbrevs + +Defining Abbrevs +================ + +`C-x +' + Define an abbrev to expand into some text before point + (`add-global-abbrev'). + +`C-x C-a' + Similar, but define an abbrev available only in the current major + mode (`add-mode-abbrev'). + +`C-x -' + Define a word in the buffer as an abbrev + (`inverse-add-global-abbrev'). + +`C-x C-h' + Define a word in the buffer as a mode-specific abbrev + (`inverse-add-mode-abbrev'). + +`M-x kill-all-abbrevs' + After this command, there are no abbrev definitions in effect. + + The usual way to define an abbrev is to enter the text you want the +abbrev to expand to, position point after it, and type `C-x +' +(`add-global-abbrev'). This reads the abbrev itself using the +minibuffer, and then defines it as an abbrev for one or more words +before point. Use a numeric argument to say how many words before +point should be taken as the expansion. For example, to define the +abbrev `foo' as mentioned above, insert the text `find outer otter' and +then type `C-u 3 C-x + f o o RET'. + + An argument of zero to `C-x +' means to use the contents of the +region as the expansion of the abbrev being defined. + + The command `C-x C-a' (`add-mode-abbrev') is similar, but defines a +mode-specific abbrev. Mode specific abbrevs are active only in a +particular major mode. `C-x C-a' defines an abbrev for the major mode +in effect at the time `C-x C-a' is typed. The arguments work the same +as for `C-x +'. + + If the text of the abbrev you want is already in the buffer instead +of the expansion, use command `C-x -' (`inverse-add-global-abbrev') +instead of `C-x +', or use `C-x C-h' (`inverse-add-mode-abbrev') +instead of `C-x C-a'. These commands are called "inverse" because they +invert the meaning of the argument found in the buffer and the argument +read using the minibuffer. + + To change the definition of an abbrev, just add the new definition. +You will be asked to confirm if the abbrev has a prior definition. To +remove an abbrev definition, give a negative argument to `C-x +' or `C-x +C-a'. You must choose the command to specify whether to kill a global +definition or a mode-specific definition for the current mode, since +those two definitions are independent for one abbrev. + + `M-x kill-all-abbrevs' removes all the abbrev definitions there are. + + +File: emacs, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs + +Controlling Abbrev Expansion +============================ + + An abbrev expands whenever it is present in the buffer just before +point and a self-inserting punctuation character (SPC, comma, etc.) is +typed. Most often the way an abbrev is used is to insert the abbrev +followed by punctuation. + + Abbrev expansion preserves case; thus, `foo' expands into `find +outer otter'; `Foo' into `Find outer otter', and `FOO' into `FIND OUTER +OTTER' or `Find Outer Otter' according to the variable +`abbrev-all-caps' (a non-`nil' value chooses the first of the two +expansions). + + These two commands are used to control abbrev expansion: + +`M-'' + Separate a prefix from a following abbrev to be expanded + (`abbrev-prefix-mark'). + +`C-x '' + Expand the abbrev before point (`expand-abbrev'). This is + effective even when Abbrev mode is not enabled. + +`M-x unexpand-abbrev' + Undo last abbrev expansion. + +`M-x expand-region-abbrevs' + Expand some or all abbrevs found in the region. + + You may wish to expand an abbrev with a prefix attached; for +example, if `cnst' expands into `construction', you might want to use +it to enter `reconstruction'. It does not work to type `recnst', +because that is not necessarily a defined abbrev. What does work is to +use the command `M-'' (`abbrev-prefix-mark') in between the prefix `re' +and the abbrev `cnst'. First, insert `re'. Then type `M-''; this +inserts a minus sign in the buffer to indicate that it has done its +work. Then insert the abbrev `cnst'; the buffer now contains +`re-cnst'. Now insert a punctuation character to expand the abbrev +`cnst' into `construction'. The minus sign is deleted at this point, +because `M-'' left word for this to be done. The resulting text is the +desired `reconstruction'. + + If you actually want the text of the abbrev in the buffer, rather +than its expansion, you can accomplish this by inserting the following +punctuation with `C-q'. Thus, `foo C-q -' leaves `foo-' in the buffer. + + If you expand an abbrev by mistake, you can undo the expansion +(replace the expansion by the original abbrev text) with `M-x +unexpand-abbrev'. `C-_' (`undo') can also be used to undo the +expansion; but first it will undo the insertion of the following +punctuation character! + + `M-x expand-region-abbrevs' searches through the region for defined +abbrevs, and for each one found offers to replace it with its expansion. +This command is useful if you have typed in text using abbrevs but +forgot to turn on Abbrev mode first. It may also be useful together +with a special set of abbrev definitions for making several global +replacements at once. This command is effective even if Abbrev mode is +not enabled. + + +File: emacs, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs + +Examining and Editing Abbrevs +============================= + +`M-x list-abbrevs' + Print a list of all abbrev definitions. + +`M-x edit-abbrevs' + Edit a list of abbrevs; you can add, alter or remove definitions. + + The output from `M-x list-abbrevs' looks like this: + + (lisp-mode-abbrev-table) + "dk" 0 "define-key" + (global-abbrev-table) + "dfn" 0 "definition" + +(Some blank lines of no semantic significance, and some other abbrev +tables, have been omitted.) + + A line containing a name in parentheses is the header for abbrevs in +a particular abbrev table; `global-abbrev-table' contains all the global +abbrevs, and the other abbrev tables that are named after major modes +contain the mode-specific abbrevs. + + Within each abbrev table, each nonblank line defines one abbrev. The +word at the beginning is the abbrev. The number that appears is the +number of times the abbrev has been expanded. Emacs keeps track of +this to help you see which abbrevs you actually use, in case you decide +to eliminate those that you don't use often. The string at the end of +the line is the expansion. + + `M-x edit-abbrevs' allows you to add, change or kill abbrev +definitions by editing a list of them in an Emacs buffer. The list has +the same format described above. The buffer of abbrevs is called +`*Abbrevs*', and is in Edit-Abbrevs mode. This mode redefines the key +`C-c C-c' to install the abbrev definitions as specified in the buffer. + The command that does this is `edit-abbrevs-redefine'. Any abbrevs +not described in the buffer are eliminated when this is done. + + `edit-abbrevs' is actually the same as `list-abbrevs' except that it +selects the buffer `*Abbrevs*' whereas `list-abbrevs' merely displays +it in another window. + + +File: emacs, Node: Saving Abbrevs, Next: Dynamic Abbrevs, Prev: Editing Abbrevs, Up: Abbrevs + +Saving Abbrevs +============== + + These commands allow you to keep abbrev definitions between editing +sessions. + +`M-x write-abbrev-file' + Write a file describing all defined abbrevs. + +`M-x read-abbrev-file' + Read such a file and define abbrevs as specified there. + +`M-x quietly-read-abbrev-file' + Similar but do not display a message about what is going on. + +`M-x define-abbrevs' + Define abbrevs from buffer. + +`M-x insert-abbrevs' + Insert all abbrevs and their expansions into the buffer. + + `M-x write-abbrev-file' reads a file name using the minibuffer and +writes a description of all current abbrev definitions into that file. +The text stored in the file looks like the output of `M-x list-abbrevs'. +This is used to save abbrev definitions for use in a later session. + + `M-x read-abbrev-file' reads a file name using the minibuffer and +reads the file, defining abbrevs according to the contents of the file. +`M-x quietly-read-abbrev-file' is the same except that it does not +display a message in the echo area saying that it is doing its work; it +is actually useful primarily in the `.emacs' file. If an empty +argument is given to either of these functions, the file name used is +the value of the variable `abbrev-file-name', which is by default +`"~/.abbrev_defs"'. + + Emacs will offer to save abbrevs automatically if you have changed +any of them, whenever it offers to save all files (for `C-x s' or `C-x +C-c'). This feature can be inhibited by setting the variable +`save-abbrevs' to `nil'. + + The commands `M-x insert-abbrevs' and `M-x define-abbrevs' are +similar to the previous commands but work on text in an Emacs buffer. +`M-x insert-abbrevs' inserts text into the current buffer before point, +describing all current abbrev definitions; `M-x define-abbrevs' parses +the entire current buffer and defines abbrevs accordingly. + + +File: emacs, Node: Dynamic Abbrevs, Prev: Saving Abbrevs, Up: Abbrevs + +Dynamic Abbrev Expansion +======================== + + The abbrev facility described above operates automatically as you +insert text, but all abbrevs must be defined explicitly. By contrast, +"dynamic abbrevs" allow the meanings of abbrevs to be determined +automatically from the contents of the buffer, but dynamic abbrev +expansion happens only when you request it explicitly. + +`M-/' + Expand the word in the buffer before point as a "dynamic abbrev", + by searching in the buffer for words starting with that + abbreviation (`dabbrev-expand'). + + For example, if the buffer contains `does this follow ' and you type +`f o M-/', the effect is to insert `follow' because that is the last +word in the buffer that starts with `fo'. A numeric argument to `M-/' +says to take the second, third, etc. distinct expansion found looking +backward from point. Repeating `M-/' searches for an alternative +expansion by looking farther back. After the part of the buffer +preceding point has been considered, the part of the buffer after point +is searched. + + Dynamic abbrev expansion is completely independent of Abbrev mode; +the expansion of a word with `M-/' is completely independent of whether +it has a definition as an ordinary abbrev. + + +File: emacs, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top + +Editing Pictures +**************** + + If you want to create a picture made out of text characters (for +example, a picture of the division of a register into fields, as a +comment in a program), use the command `edit-picture' to enter Picture +mode. + + In Picture mode, editing is based on the "quarter-plane" model of +text, according to which the text characters lie studded on an area that +stretches infinitely far to the right and downward. The concept of the +end of a line does not exist in this model; the most you can say is +where the last nonblank character on the line is found. + + Of course, Emacs really always considers text as a sequence of +characters, and lines really do have ends. But in Picture mode most +frequently-used keys are rebound to commands that simulate the +quarter-plane model of text. They do this by inserting spaces or by +converting tabs to spaces. + + Most of the basic editing commands of Emacs are redefined by Picture +mode to do essentially the same thing but in a quarter-plane way. In +addition, Picture mode defines various keys starting with the `C-c' +prefix to run special picture editing commands. + + One of these keys, `C-c C-c', is pretty important. Often a picture +is part of a larger file that is usually edited in some other major +mode. `M-x edit-picture' records the name of the previous major mode, +and then you can use the `C-c C-c' command (`picture-mode-exit') to +restore that mode. `C-c C-c' also deletes spaces from the ends of +lines, unless given a numeric argument. + + The commands used in Picture mode all work in other modes (provided +the `picture' library is loaded), but are not bound to keys except in +Picture mode. Note that the descriptions below talk of moving "one +column" and so on, but all the picture mode commands handle numeric +arguments as their normal equivalents do. + + Turning on Picture mode calls the value of the variable +`picture-mode-hook' as a function, with no arguments, if that value +exists and is non-`nil'. + +* Menu: + +* Basic Picture:: Basic concepts and simple commands of Picture Mode. +* Insert in Picture:: Controlling direction of cursor motion + after "self-inserting" characters. +* Tabs in Picture:: Various features for tab stops and indentation. +* Rectangles in Picture:: Clearing and superimposing rectangles. + + +File: emacs, Node: Basic Picture, Next: Insert in Picture, Prev: Picture, Up: Picture + +Basic Editing in Picture Mode +============================= + + Most keys do the same thing in Picture mode that they usually do, +but do it in a quarter-plane style. For example, `C-f' is rebound to +run `picture-forward-column', which is defined to move point one column +to the right, by inserting a space if necessary, so that the actual end +of the line makes no difference. `C-b' is rebound to run +`picture-backward-column', which always moves point left one column, +converting a tab to multiple spaces if necessary. `C-n' and `C-p' are +rebound to run `picture-move-down' and `picture-move-up', which can +either insert spaces or convert tabs as necessary to make sure that +point stays in exactly the same column. `C-e' runs +`picture-end-of-line', which moves to after the last nonblank character +on the line. There is no need to change `C-a', as the choice of screen +model does not affect beginnings of lines. + + Insertion of text is adapted to the quarter-plane screen model +through the use of Overwrite mode (*note Minor Modes::.). +Self-inserting characters replace existing text, column by column, +rather than pushing existing text to the right. RET runs +`picture-newline', which just moves to the beginning of the following +line so that new text will replace that line. + + Deletion and killing of text are replaced with erasure. DEL +(`picture-backward-clear-column') replaces the preceding character with +a space rather than removing it. `C-d' (`picture-clear-column') does +the same thing in a forward direction. `C-k' (`picture-clear-line') +really kills the contents of lines, but does not ever remove the +newlines from the buffer. + + To do actual insertion, you must use special commands. `C-o' +(`picture-open-line') still creates a blank line, but does so after the +current line; it never splits a line. `C-M-o', `split-line', makes +sense in Picture mode, so it is not changed. LFD +(`picture-duplicate-line') inserts below the current line another line +with the same contents. + + Real deletion can be done with `C-w', or with `C-c C-d' (which is +defined as `delete-char', as `C-d' is in other modes), or with one of +the picture rectangle commands (*note Rectangles in Picture::.). + + +File: emacs, Node: Insert in Picture, Next: Tabs in Picture, Prev: Basic Picture, Up: Picture + +Controlling Motion after Insert +=============================== + + Since "self-inserting" characters in Picture mode just overwrite and +move point, there is no essential restriction on how point should be +moved. Normally point moves right, but you can specify any of the eight +orthogonal or diagonal directions for motion after a "self-inserting" +character. This is useful for drawing lines in the buffer. + +`C-c <' + Move left after insertion (`picture-movement-left'). + +`C-c >' + Move right after insertion (`picture-movement-right'). + +`C-c ^' + Move up after insertion (`picture-movement-up'). + +`C-c .' + Move down after insertion (`picture-movement-down'). + +`C-c `' + Move up and left ("northwest") after insertion + (`picture-movement-nw'). + +`C-c '' + Move up and right ("northeast") after insertion + (`picture-movement-ne'). + +`C-c /' + Move down and left ("southwest") after insertion + (`picture-movement-sw'). + +`C-c \' + Move down and right ("southeast") after insertion + (`picture-movement-se'). + + Two motion commands move based on the current Picture insertion +direction. The command `C-c C-f' (`picture-motion') moves in the same +direction as motion after "insertion" currently does, while `C-c C-b' +(`picture-motion-reverse') moves in the opposite direction. + + +File: emacs, Node: Tabs in Picture, Next: Rectangles in Picture, Prev: Insert in Picture, Up: Picture + +Picture Mode Tabs +================= + + Two kinds of tab-like action are provided in Picture mode. +Context-based tabbing is done with `M-TAB' (`picture-tab-search'). +With no argument, it moves to a point underneath the next "interesting" +character that follows whitespace in the previous nonblank line. +"Next" here means "appearing at a horizontal position greater than the +one point starts out at". With an argument, as in `C-u M-TAB', this +command moves to the next such interesting character in the current +line. `M-TAB' does not change the text; it only moves point. +"Interesting" characters are defined by the variable +`picture-tab-chars', which contains a string whose characters are all +considered interesting. Its default value is `"!-~"'. + + TAB itself runs `picture-tab', which operates based on the current +tab stop settings; it is the Picture mode equivalent of +`tab-to-tab-stop'. Normally it just moves point, but with a numeric +argument it clears the text that it moves over. + + The context-based and tab-stop-based forms of tabbing are brought +together by the command `C-c TAB', `picture-set-tab-stops'. This +command sets the tab stops to the positions which `M-TAB' would +consider significant in the current line. The use of this command, +together with TAB, can get the effect of context-based tabbing. But +`M-TAB' is more convenient in the cases where it is sufficient. + + +File: emacs, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture + +Picture Mode Rectangle Commands +=============================== + + Picture mode defines commands for working on rectangular pieces of +the text in ways that fit with the quarter-plane model. The standard +rectangle commands may also be useful (*note Rectangles::.). + +`C-c C-k' + Clear out the region-rectangle (`picture-clear-rectangle'). With + argument, kill it. + +`C-c C-w R' + Similar but save rectangle contents in register R first + (`picture-clear-rectangle-to-register'). + +`C-c C-y' + Copy last killed rectangle into the buffer by overwriting, with + upper left corner at point (`picture-yank-rectangle'). With + argument, insert instead. + +`C-c C-x R' + Similar, but use the rectangle in register R + (`picture-yank-rectangle-from-register'). + + The picture rectangle commands `C-c C-k' (`picture-clear-rectangle') +and `C-c C-w' (`picture-clear-rectangle-to-register') differ from the +standard rectangle commands in that they normally clear the rectangle +instead of deleting it; this is analogous with the way `C-d' is changed +in Picture mode. + + However, deletion of rectangles can be useful in Picture mode, so +these commands delete the rectangle if given a numeric argument. + + The Picture mode commands for yanking rectangles differ from the +standard ones in overwriting instead of inserting. This is the same +way that Picture mode insertion of other text is different from other +modes. `C-c C-y' (`picture-yank-rectangle') inserts (by overwriting) the +rectangle that was most recently killed, while `C-c C-x' +(`picture-yank-rectangle-from-register') does likewise for the +rectangle found in a specified register. + + +File: emacs, Node: Sending Mail, Next: Rmail, Prev: Picture, Up: Top + +Sending Mail +************ + + To send a message in Emacs, you start by typing a command (`C-x m') +to select and initialize the `*mail*' buffer. Then you edit the text +and headers of the message in this buffer, and type another command +(`C-c C-c') to send the message. + +`C-x m' + Begin composing a message to send (`mail'). + +`C-x 4 m' + Likewise, but display the message in another window + (`mail-other-window'). + +`C-c C-c' + In Mail mode, send the message and switch to another buffer + (`mail-send-and-exit'). + + The command `C-x m' (`mail') selects a buffer named `*mail*' and +initializes it with the skeleton of an outgoing message. `C-x 4 m' +(`mail-other-window') selects the `*mail*' buffer in a different +window, leaving the previous current buffer visible. + + Because the mail composition buffer is an ordinary Emacs buffer, you +can switch to other buffers while in the middle of composing mail, and +switch back later (or never). If you use the `C-x m' command again +when you have been composing another message but have not sent it, you +are asked to confirm before the old message is erased. If you answer +`n', the `*mail*' buffer is left selected with its old contents, so you +can finish the old message and send it. `C-u C-x m' is another way to +do this. Sending the message marks the `*mail*' buffer "unmodified", +which avoids the need for confirmation when `C-x m' is next used. + + If you are composing a message in the `*mail*' buffer and want to +send another message before finishing the first, rename the `*mail*' +buffer using `M-x rename-buffer' (*note Misc Buffer::.). + +* Menu: + +* Format: Mail Format. Format of the mail being composed. +* Headers: Mail Headers. Details of allowed mail header fields. +* Mode: Mail Mode. Special commands for editing mail being composed. + + +File: emacs, Node: Mail Format, Next: Mail Headers, Prev: Sending Mail, Up: Sending Mail + +The Format of the Mail Buffer +============================= + + In addition to the "text" or contents, a message has "header fields" +which say who sent it, when, to whom, why, and so on. Some header +fields such as the date and sender are created automatically after the +message is sent. Others, such as the recipient names, must be +specified by you in order to send the message properly. + + Mail mode provides a few commands to help you edit some header +fields, and some are preinitialized in the buffer automatically at +times. You can insert or edit any header fields using ordinary editing +commands. + + The line in the buffer that says + + --text follows this line-- + +is a special delimiter that separates the headers you have specified +from the text. Whatever follows this line is the text of the message; +the headers precede it. The delimiter line itself does not appear in +the message actually sent. The text used for the delimiter line is +controlled by the variable `mail-header-separator'. + + Here is an example of what the headers and text in the `*mail*' +buffer might look like. + + To: rms@mc + CC: mly@mc, rg@oz + Subject: The Emacs Manual + --Text follows this line-- + Please ignore this message. + + +File: emacs, Node: Mail Headers, Next: Mail Mode, Prev: Mail Format, Up: Sending Mail + +Mail Header Fields +================== + + There are several header fields you can use in the `*mail*' buffer. +Each header field starts with a field name at the beginning of a line, +terminated by a colon. It does not matter whether you use upper or +lower case in the field name. After the colon and optional whitespace +comes the contents of the field. + +`To' + This field contains the mailing addresses to which the message is + addressed. + +`Subject' + The contents of the `Subject' field should be a piece of text that + says what the message is about. The reason `Subject' fields are + useful is that most mail-reading programs can provide a summary of + messages, listing the subject of each message but not its text. + +`CC' + This field contains additional mailing addresses to send the + message to, but whose readers should not regard the message as + addressed to them. + +`BCC' + This field contains additional mailing addresses to send the + message to, but which should not appear in the header of the + message actually sent. + +`FCC' + This field contains the name of one file (in Unix mail file + format) to which a copy of the message should be appended when the + message is sent. + +`From' + Use the `From' field to say who you are, when the account you are + using to send the mail is not your own. The contents of the + `From' field should be a valid mailing address, since replies will + normally go there. + +`Reply-To' + Use the `Reply-to' field to direct replies to a different address, + not your own. There is no difference between `From' and + `Reply-to' in their effect on where replies go, but they convey a + different meaning to the human who reads the message. + + If you set the variable `mail-default-reply-to' to a non-`nil' + value, then every message you begin to edit will have a `Reply-to' + field whose contents are the value of the variable. + +`In-Reply-To' + This field contains a piece of text describing a message you are + replying to. Some mail systems can use this information to + correlate related pieces of mail. Normally this field is filled + in by Rmail when you are replying to a message in Rmail, and you + never need to think about it (*note Rmail::.). + + The `To', `CC', `BCC' and `FCC' fields can appear any number of +times, to specify many places to send the message. + + The `To', `CC', and `BCC' fields can have continuation lines. All +the lines starting with whitespace, following the line on which the +field starts, are considered part of the field. For example, + + To: foo@here, this@there, + me@gnu.cambridge.mass.usa.earth.spiral3281 + + If you have a `~/.mailrc' file, Emacs will scan it for mail aliases +the first time you try to send mail in an Emacs session. Aliases found +in the `To', `CC', and `BCC' fields will be expanded where appropriate. + + If the variable `mail-archive-file-name' is non-`nil', it should be a +string naming a file; every time you start to edit a message to send, +an `FCC' field will be put in for that file. Unless you remove the +`FCC' field, every message will be written into that file when it is +sent. + + +File: emacs, Node: Mail Mode, Prev: Mail Headers, Up: Sending Mail + +Mail Mode +========= + + The major mode used in the `*mail*' buffer is Mail mode, which is +much like Text mode except that various special commands are provided on +the `C-c' prefix. These commands all have to do specifically with +editing or sending the message. + +`C-c C-s' + Send the message, and leave the `*mail*' buffer selected + (`mail-send'). + +`C-c C-c' + Send the message, and select some other buffer + (`mail-send-and-exit'). + +`C-c C-f C-t' + Move to the `To' header field, creating one if there is none + (`mail-to'). + +`C-c C-f C-s' + Move to the `Subject' header field, creating one if there is none + (`mail-subject'). + +`C-c C-f C-c' + Move to the `CC' header field, creating one if there is none + (`mail-cc'). + +`C-c C-w' + Insert the file `~/.signature' at the end of the message text + (`mail-signature'). + +`C-c C-y' + Yank the selected message from Rmail (`mail-yank-original'). This + command does nothing unless your command to start sending a + message was issued with Rmail. + +`C-c C-q' + Fill all paragraphs of yanked old messages, each individually + (`mail-fill-yanked-message'). + + There are two ways to send the message. `C-c C-s' (`mail-send') +sends the message and marks the `*mail*' buffer unmodified, but leaves +that buffer selected so that you can modify the message (perhaps with +new recipients) and send it again. `C-c C-c' (`mail-send-and-exit') +sends and then deletes the window (if there is another window) or +switches to another buffer. It puts the `*mail*' buffer at the lowest +priority for automatic reselection, since you are finished with using +it. This is the usual way to send the message. + + Mail mode provides some other special commands that are useful for +editing the headers and text of the message before you send it. There +are three commands defined to move point to particular header fields, +all based on the prefix `C-c C-f' (`C-f' is for "field"). They are +`C-c C-f C-t' (`mail-to') to move to the `To' field, `C-c C-f C-s' +(`mail-subject') for the `Subject' field, and `C-c C-f C-c' (`mail-cc') +for the `CC' field. These fields have special motion commands because +they are the most common fields for the user to want to edit. + + `C-c C-w' (`mail-signature') adds a standard piece text at the end +of the message to say more about who you are. The text comes from the +file `.signature' in your home directory. + + When mail sending is invoked from the Rmail mail reader using an +Rmail command, `C-c C-y' can be used inside the `*mail*' buffer to +insert the text of the message you are replying to. Normally it +indents each line of that message four spaces and eliminates most +header fields. A numeric argument specifies the number of spaces to +indent. An argument of just `C-u' says not to indent at all and not to +eliminate anything. `C-c C-y' always uses the current message from the +`RMAIL' buffer, so you can insert several old messages by selecting one +in `RMAIL', switching to `*mail*' and yanking it, then switching back to +`RMAIL' to select another. + + After using `C-c C-y', you can type the command `C-c C-q' +(`mail-fill-yanked-message') to fill the paragraphs of the yanked old +message or messages. One use of `C-c C-q' fills all such paragraphs, +each one separately. + + Turning on Mail mode (which `C-x m' does automatically) calls the +value of `text-mode-hook', if it is not void or `nil', and then calls +the value of `mail-mode-hook' if that is not void or `nil'. Aside from +these, the `mail' command runs `mail-setup-hook' whenever it +initializes the `*mail*' buffer for editing a message. + + +File: emacs, Node: Rmail, Next: Recursive Edit, Prev: Sending Mail, Up: Top + +Reading Mail with Rmail +*********************** + + Rmail is an Emacs subsystem for reading and disposing of mail that +you receive. Rmail stores mail messages in files called "Rmail files". + Reading the message in an Rmail file is done in a special major mode, +Rmail mode, which redefines most letters to run commands for managing +mail. To enter Rmail, type `M-x rmail'. This reads your primary mail +file, merges new mail in from your inboxes, displays the first new +message, and lets you begin reading. + + Using Rmail in the simplest fashion, you have one Rmail file, +`~/RMAIL', in which all of your mail is saved. It is called your +"primary mail file". In more sophisticated usage, you can copy +messages into other Rmail files and then edit those files with Rmail. + + Rmail displays only one message at a time. It is called the "current +message". Rmail mode's special commands can do such things as move to +another message, delete the message, copy the message into another +file, or send a reply. + + Within the Rmail file, messages are arranged sequentially in order +of receipt. They are also assigned consecutive integers as their +"message numbers". The number of the current message is displayed in +Rmail's mode line, followed by the total number of messages in the +file. You can move to a message by specifying its message number using +the `j' key (*note Rmail Motion::.). + + Following the usual conventions of Emacs, changes in an Rmail file +become permanent only when the file is saved. You can do this with `s' +(`rmail-save'), which also expunges deleted messages from the file +first (*note Rmail Deletion::.). To save the file without expunging, +use `C-x C-s'. Rmail saves the Rmail file spontaneously when moving new +mail from an inbox file (*note Rmail Inbox::.). + + You can exit Rmail with `q' (`rmail-quit'); this expunges and saves +the Rmail file and then switches to another buffer. But there is no +need to `exit' formally. If you switch from Rmail to editing in other +buffers, and never happen to switch back, you have exited. Just make +sure to save the Rmail file eventually (like any other file you have +changed). `C-x s' is a good enough way to do this (*note Saving::.). + +* Menu: + +* Scroll: Rmail Scrolling. Scrolling through a message. +* Motion: Rmail Motion. Moving to another message. +* Deletion: Rmail Deletion. Deleting and expunging messages. +* Inbox: Rmail Inbox. How mail gets into the Rmail file. +* Files: Rmail Files. Using multiple Rmail files. +* Output: Rmail Output. Copying message out to files. +* Labels: Rmail Labels. Classifying messages by labeling them. +* Summary: Rmail Summary. Summaries show brief info on many messages. +* Reply: Rmail Reply. Sending replies to messages you are viewing. +* Editing: Rmail Editing. Editing message text and headers in Rmail. +* Digest: Rmail Digest. Extracting the messages from a digest message. + + +File: emacs, Node: Rmail Scrolling, Next: Rmail Motion, Prev: Rmail, Up: Rmail + +Scrolling Within a Message +========================== + + When Rmail displays a message that does not fit on the screen, it is +necessary to scroll through it. This could be done with `C-v', `M-v' +and `M-<', but in Rmail scrolling is so frequent that it deserves to be +easier to type. + +`SPC' + Scroll forward (`scroll-up'). + +`DEL' + Scroll backward (`scroll-down'). + +`.' + Scroll to start of message (`rmail-beginning-of-message'). + + Since the most common thing to do while reading a message is to +scroll through it by screenfuls, Rmail makes SPC and DEL synonyms of +`C-v' (`scroll-up') and `M-v' (`scroll-down'). + + The command `.' (`rmail-beginning-of-message') scrolls back to the +beginning of the selected message. This is not quite the same as `M-<': +for one thing, it does not set the mark; for another, it resets the +buffer boundaries to the current message if you have changed them. + +
\ No newline at end of file |