This is ../info/emacs, produced by makeinfo version 4.8 from emacs.texi.  File: emacs, Node: Other C Commands, Next: Comments in C, Prev: Hungry Delete, Up: C Mode 19.14.4 Other Commands for C Mode --------------------------------- `C-M-h' Put mark at the end of a function definition, and put point at the beginning (`c-mark-function'). `M-q' Fill a paragraph, handling C and C++ comments (`c-fill-paragraph'). If any part of the current line is a comment or within a comment, this command fills the comment or the paragraph of it that point is in, preserving the comment indentation and comment delimiters. `C-c C-e' Run the C preprocessor on the text in the region, and show the result, which includes the expansion of all the macro calls (`c-macro-expand'). The buffer text before the region is also included in preprocessing, for the sake of macros defined there, but the output from this part isn't shown. When you are debugging C code that uses macros, sometimes it is hard to figure out precisely how the macros expand. With this command, you don't have to figure it out; you can see the expansions. `C-c C-\' Insert or align `\' characters at the ends of the lines of the region (`c-backslash-region'). This is useful after writing or editing a C macro definition. If a line already ends in `\', this command adjusts the amount of whitespace before it. Otherwise, it inserts a new `\'. However, the last line in the region is treated specially; no `\' is inserted on that line, and any `\' there is deleted. `M-x cpp-highlight-buffer' Highlight parts of the text according to its preprocessor conditionals. This command displays another buffer named `*CPP Edit*', which serves as a graphic menu for selecting how to display particular kinds of conditionals and their contents. After changing various settings, click on `[A]pply these settings' (or go to that buffer and type `a') to rehighlight the C mode buffer accordingly. `C-c C-s' Display the syntactic information about the current source line (`c-show-syntactic-information'). This is the information that directs how the line is indented.  File: emacs, Node: Comments in C, Prev: Other C Commands, Up: C Mode 19.14.5 Comments in C Modes --------------------------- C mode and related modes use a number of variables for controlling comment format. `c-block-comments-indent-p' This variable specifies how to reindent block comments. The C modes support five styles of block comments: style 1: style 2 (GNU): style 3: style 4: style 5: /* /* Blah /* /* /* blah blah. */ * blah ** blah blah blah * blah ** blah blah */ */ */ */ For the styles 1 through 4, `c-block-comments-indent-p' should be `nil' (the default). If you want to use style 5, set `c-block-comments-indent-p' to `t'. This variable has no effect on the indentation of the comment-start itself or on insertion of asterisks when auto-filling C comments. It does not affect `M-q' either. `c-comment-only-line-offset' Extra offset for line which contains only the start of a comment. It can be either an integer or a cons cell of the form `(NON-ANCHORED-OFFSET . ANCHORED-OFFSET)', where NON-ANCHORED-OFFSET is the amount of offset given to non-column-zero anchored comment-only lines, and ANCHORED-OFFSET is the amount of offset to give column-zero anchored comment-only lines. Just an integer as value is equivalent to `(VAL . 0)'. `c-comment-start-regexp' This buffer-local variable specifies how to recognize the start of a comment. `c-hanging-comment-ender-p' If this variable is `nil', `c-fill-paragraph' leaves the comment terminator of a block comment on a line by itself. The default value is `t', which always puts the comment-end delimiter `*/' at the end of the last line of the comment text.  File: emacs, Node: Fortran, Next: Asm Mode, Prev: C Mode, Up: Programs 19.15 Fortran Mode ================== Fortran mode provides special motion commands for Fortran statements and subprograms, and indentation commands that understand Fortran conventions of nesting, line numbers and continuation statements. Fortran mode has its own Auto Fill mode that breaks long lines into proper Fortran continuation lines. Special commands for comments are provided because Fortran comments are unlike those of other languages. Built-in abbrevs optionally save typing when you insert Fortran keywords. Use `M-x fortran-mode' to switch to this major mode. This command runs the hook `fortran-mode-hook' (*note Hooks::). * Menu: * Motion: Fortran Motion. Moving point by statements or subprograms. * Indent: Fortran Indent. Indentation commands for Fortran. * Comments: Fortran Comments. Inserting and aligning comments. * Autofill: Fortran Autofill. Auto fill minor mode for Fortran. * Columns: Fortran Columns. Measuring columns for valid Fortran. * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords.  File: emacs, Node: Fortran Motion, Next: Fortran Indent, Up: Fortran 19.15.1 Motion Commands ----------------------- Fortran mode provides special commands to move by subprograms (functions and subroutines) and by statements. There is also a command to put the region around one subprogram, convenient for killing it or moving it. `C-M-a' Move to beginning of subprogram (`beginning-of-fortran-subprogram'). `C-M-e' Move to end of subprogram (`end-of-fortran-subprogram'). `C-M-h' Put point at beginning of subprogram and mark at end (`mark-fortran-subprogram'). `C-c C-n' Move to beginning of current or next statement (`fortran-next-statement'). `C-c C-p' Move to beginning of current or previous statement (`fortran-previous-statement').  File: emacs, Node: Fortran Indent, Next: Fortran Comments, Prev: Fortran Motion, Up: Fortran 19.15.2 Fortran Indentation --------------------------- Special commands and features are needed for indenting Fortran code in order to make sure various syntactic entities (line numbers, comment line indicators and continuation line flags) appear in the columns that are required for standard Fortran. * Menu: * Commands: ForIndent Commands. Commands for indenting Fortran. * Contline: ForIndent Cont. How continuation lines indent. * Numbers: ForIndent Num. How line numbers auto-indent. * Conv: ForIndent Conv. Conventions you must obey to avoid trouble. * Vars: ForIndent Vars. Variables controlling Fortran indent style.  File: emacs, Node: ForIndent Commands, Next: ForIndent Cont, Up: Fortran Indent 19.15.2.1 Fortran Indentation Commands ...................................... `' Indent the current line (`fortran-indent-line'). `' Indent the current and start a new indented line (`fortran-indent-new-line'). `M-' Break the current line and set up a continuation line. `C-M-q' Indent all the lines of the subprogram point is in (`fortran-indent-subprogram'). Fortran mode redefines to reindent the current line for Fortran (`fortran-indent-line'). This command indents Line numbers and continuation markers to their required columns, and independently indents the body of the statement based on its nesting in the program. The key `LFD' runs the command `fortran-indent-new-line', which reindents the current line then makes and indents a new line. This command is useful to reindent the closing statement of `do' loops and other blocks before starting a new line. The key `C-M-q' runs `fortran-indent-subprogram', a command to reindent all the lines of the Fortran subprogram (function or subroutine) containing point. The key `M-' runs `fortran-split-line', which splits a line in the appropriate fashion for Fortran. In a non-comment line, the second half becomes a continuation line and is indented accordingly. In a comment line, both halves become separate comment lines.  File: emacs, Node: ForIndent Cont, Next: ForIndent Num, Prev: ForIndent Commands, Up: Fortran Indent 19.15.2.2 Continuation Lines ............................ Most modern Fortran compilers allow two ways of writing continuation lines. If the first non-space character on a line is in column 5, then that line is a continuation of the previous line. We call this "fixed format". (In GNU Emacs we always count columns from 0.) The variable `fortran-continuation-string' specifies what character to put on column 5. A line that starts with a tab character followed by any digit except `0' is also a continuation line. We call this style of continuation "tab format". Fortran mode can make either style of continuation line, but you must specify which one you prefer. The value of the variable `indent-tabs-mode' controls the choice: `nil' for fixed format, and non-`nil' for tab format. You can tell which style is presently in effect by the presence or absence of the string `Tab' in the mode line. If the text on a line starts with the conventional Fortran continuation marker `$', or if it begins with any non-whitespace character in column 5, Fortran mode treats it as a continuation line. When you indent a continuation line with , it converts the line to the current continuation style. When you split a Fortran statement with `M-', the continuation marker on the newline is created according to the continuation style. The setting of continuation style affects several other aspects of editing in Fortran mode. In fixed format mode, the minimum column number for the body of a statement is 6. Lines inside of Fortran blocks that are indented to larger column numbers always use only the space character for whitespace. In tab format mode, the minimum column number for the statement body is 8, and the whitespace before column 8 must always consist of one tab character. When you enter Fortran mode for an existing file, it tries to deduce the proper continuation style automatically from the file contents. The first line that begins with either a tab character or six spaces determines the choice. The variable `fortran-analyze-depth' specifies how many lines to consider (at the beginning of the file); if none of those lines indicates a style, then the variable `fortran-tab-mode-default' specifies the style. If it is `nil', that specifies fixed format, and non-`nil' specifies tab format.  File: emacs, Node: ForIndent Num, Next: ForIndent Conv, Prev: ForIndent Cont, Up: Fortran Indent 19.15.2.3 Line Numbers ...................... If a number is the first non-whitespace in the line, Fortran indentation assumes it is a line number and moves it to columns 0 through 4. (Columns always count from 0 in GNU Emacs.) Line numbers of four digits or less are normally indented one space. The variable `fortran-line-number-indent' controls this; it specifies the maximum indentation a line number can have. Line numbers are indented to right-justify them to end in column 4 unless that would require more than this maximum indentation. The default value of the variable is 1. Simply inserting a line number is enough to indent it according to these rules. As each digit is inserted, the indentation is recomputed. To turn off this feature, set the variable `fortran-electric-line-number' to `nil'. Then inserting line numbers is like inserting anything else.  File: emacs, Node: ForIndent Conv, Next: ForIndent Vars, Prev: ForIndent Num, Up: Fortran Indent 19.15.2.4 Syntactic Conventions ............................... Fortran mode assumes that you follow certain conventions that simplify the task of understanding a Fortran program well enough to indent it properly: * Two nested `do' loops never share a `continue' statement. * Fortran keywords such as `if', `else', `then', `do' and others are written without embedded whitespace or line breaks. Fortran compilers generally ignore whitespace outside of string constants, but Fortran mode does not recognize these keywords if they are not contiguous. Constructs such as `else if' or `end do' are acceptable, but the second word should be on the same line as the first and not on a continuation line. If you fail to follow these conventions, the indentation commands may indent some lines unaesthetically. However, a correct Fortran program retains its meaning when reindented even if the conventions are not followed.  File: emacs, Node: ForIndent Vars, Prev: ForIndent Conv, Up: Fortran Indent 19.15.2.5 Variables for Fortran Indentation ........................................... Several additional variables control how Fortran indentation works: `fortran-do-indent' Extra indentation within each level of `do' statement (default 3). `fortran-if-indent' Extra indentation within each level of `if' statement (default 3). This value is also used for extra indentation within each level of the Fortran 90 `where' statement. `fortran-structure-indent' Extra indentation within each level of `structure', `union', or `map' statements (default 3). `fortran-continuation-indent' Extra indentation for bodies of continuation lines (default 5). `fortran-check-all-num-for-matching-do' If this is `nil', indentation assumes that each `do' statement ends on a `continue' statement. Therefore, when computing indentation for a statement other than `continue', it can save time by not checking for a `do' statement ending there. If this is non-`nil', indenting any numbered statement must check for a `do' that ends there. The default is `nil'. `fortran-blink-matching-if' If this is `t', indenting an `endif' statement moves the cursor momentarily to the matching `if' statement to show where it is. The default is `nil'. `fortran-minimum-statement-indent-fixed' Minimum indentation for fortran statements when using fixed format continuation line style. Statement bodies are never indented less than this much. The default is 6. `fortran-minimum-statement-indent-tab' Minimum indentation for fortran statements for tab format continuation line style. Statement bodies are never indented less than this much. The default is 8.  File: emacs, Node: Fortran Comments, Next: Fortran Autofill, Prev: Fortran Indent, Up: Fortran 19.15.3 Fortran Comments ------------------------ The usual Emacs comment commands assume that a comment can follow a line of code. In Fortran, the standard comment syntax requires an entire line to be just a comment. Therefore, Fortran mode replaces the standard Emacs comment commands and defines some new variables. Fortran mode can also handle a nonstandard comment syntax where comments start with `!' and can follow other text. Because only some Fortran compilers accept this syntax, Fortran mode will not insert such comments unless you have said in advance to do so. To do this, set the variable `comment-start' to `"!"' (*note Variables::). `M-;' Align comment or insert new comment (`fortran-comment-indent'). `C-x ;' Applies to nonstandard `!' comments only. `C-c ;' Turn all lines of the region into comments, or (with argument) turn them back into real code (`fortran-comment-region'). `M-;' in Fortran mode is redefined as the command `fortran-comment-indent'. Like the usual `M-;' command, this recognizes any kind of existing comment and aligns its text appropriately; if there is no existing comment, a comment is inserted and aligned. But inserting and aligning comments are not the same in Fortran mode as in other modes. When a new comment must be inserted, if the current line is blank, a full-line comment is inserted. On a non-blank line, a nonstandard `!' comment is inserted if you have said you want to use them. Otherwise a full-line comment is inserted on a new line before the current line. Nonstandard `!' comments are aligned like comments in other languages, but full-line comments are different. In a standard full-line comment, the comment delimiter itself must always appear in column zero. What can be aligned is the text within the comment. You can choose from three styles of alignment by setting the variable `fortran-comment-indent-style' to one of these values: `fixed' Align the text at a fixed column, which is the sum of `fortran-comment-line-extra-indent' and the minimum statement indentation. This is the default. The minimum statement indentation is `fortran-minimum-statement-indent-fixed' for fixed format continuation line style and `fortran-minimum-statement-indent-tab' for tab format style. `relative' Align the text as if it were a line of code, but with an additional `fortran-comment-line-extra-indent' columns of indentation. `nil' Don't move text in full-line columns automatically at all. In addition, you can specify the character to be used to indent within full-line comments by setting the variable `fortran-comment-indent-char' to the single-character string you want to use. Fortran mode introduces two variables `comment-line-start' and `comment-line-start-skip' which play for full-line comments the same roles played by `comment-start' and `comment-start-skip' for ordinary text-following comments. Normally these are set properly by Fortran mode so you do not need to change them. The normal Emacs comment command `C-x ;' has not been redefined. If you use `!' comments, this command can be used with them. Otherwise it is useless in Fortran mode. The command `C-c ;' (`fortran-comment-region') turns all the lines of the region into comments by inserting the string `C$$$' at the front of each one. With a numeric argument, it turns the region back into live code by deleting `C$$$' from the front of each line in it. The string used for these comments can be controlled by setting the variable `fortran-comment-region'. Note that here we have an example of a command and a variable with the same name; these two uses of the name never conflict because in Lisp and in Emacs it is always clear from the context which one is meant.  File: emacs, Node: Fortran Autofill, Next: Fortran Columns, Prev: Fortran Comments, Up: Fortran 19.15.4 Fortran Auto Fill Mode ------------------------------ Fortran Auto Fill mode is a minor mode which automatically splits Fortran statements as you insert them when they become too wide. Splitting a statement involves making continuation lines using `fortran-continuation-string' (*Note ForIndent Cont::). This splitting happens when you type , , or , and also in the Fortran indentation commands. `M-x fortran-auto-fill-mode' turns Fortran Auto Fill mode on if it was off, or off if it was on. This command works the same as `M-x auto-fill-mode' does for normal Auto Fill mode (*note Filling::). A positive numeric argument turns Fortran Auto Fill mode on, and a negative argument turns it off. You can see when Fortran Auto Fill mode is in effect by the presence of the word `Fill' in the mode line, inside the parentheses. Fortran Auto Fill mode is a minor mode, turned on or off for each buffer individually. *Note Minor Modes::. Fortran Auto Fill mode breaks lines at spaces or delimiters when the lines get longer than the desired width (the value of `fill-column'). The delimiters that Fortran Auto Fill mode may break at are `,', `'', `+', `-', `/', `*', `=', and `)'. The line break comes after the delimiter if the variable `fortran-break-before-delimiters' is `nil'. Otherwise (and by default), the break comes before the delimiter. By default, Fortran Auto Fill mode is not enabled. If you want this feature turned on permanently, add a hook function to `fortran-mode-hook' to execute `(fortran-auto-fill-mode 1)'. *Note Hooks::.  File: emacs, Node: Fortran Columns, Next: Fortran Abbrev, Prev: Fortran Autofill, Up: Fortran 19.15.5 Checking Columns in Fortran ----------------------------------- `C-c C-r' Display a "column ruler" momentarily above the current line (`fortran-column-ruler'). `C-c C-w' Split the current window horizontally temporarily so that it is 72 columns wide. This may help you avoid making lines longer than the 72 character limit that some fortran compilers impose (`fortran-window-create-momentarily'). The command `C-c C-r' (`fortran-column-ruler') shows a column ruler momentarily above the current line. The comment ruler is two lines of text that show you the locations of columns with special significance in Fortran programs. Square brackets show the limits of the columns for line numbers, and curly brackets show the limits of the columns for the statement body. Column numbers appear above them. Note that the column numbers count from zero, as always in GNU Emacs. As a result, the numbers may be one less than those you are familiar with; but the positions they indicate in the line are standard for Fortran. The text used to display the column ruler depends on the value of the variable `indent-tabs-mode'. If `indent-tabs-mode' is `nil', then the value of the variable `fortran-column-ruler-fixed' is used as the column ruler. Otherwise, the variable `fortran-column-ruler-tab' is displayed. By changing these variables, you can change the column ruler display. For even more help, use `C-c C-w' (`fortran-window-create'), a command which splits the current window horizontally, making a window 72 columns wide. By editing in this window you can immediately see when you make a line too wide to be correct Fortran.  File: emacs, Node: Fortran Abbrev, Prev: Fortran Columns, Up: Fortran 19.15.6 Fortran Keyword Abbrevs ------------------------------- Fortran mode provides many built-in abbrevs for common keywords and declarations. These are the same sort of abbrev that you can define yourself. To use them, you must turn on Abbrev mode. *Note Abbrevs::. The built-in abbrevs are unusual in one way: they all start with a semicolon. You cannot normally use semicolon in an abbrev, but Fortran mode makes this possible by changing the syntax of semicolon to "word constituent." For example, one built-in Fortran abbrev is `;c' for `continue'. If you insert `;c' and then insert a punctuation character such as a space or a newline, the `;c' expands automatically to `continue', provided Abbrev mode is enabled. Type `;?' or `;C-h' to display a list of all the built-in Fortran abbrevs and what they stand for.  File: emacs, Node: Asm Mode, Prev: Fortran, Up: Programs 19.16 Asm Mode ============== Asm mode is a major mode for editing files of assembler code. It defines these commands: `' `tab-to-tab-stop'. `' Insert a newline and then indent using `tab-to-tab-stop'. `:' Insert a colon and then remove the indentation from before the label preceding colon. Then do `tab-to-tab-stop'. `;' Insert or align a comment. The variable `asm-comment-char' specifies which character starts comments in assembler syntax.  File: emacs, Node: Building, Next: Abbrevs, Prev: Programs, Up: Top 20 Compiling and Testing Programs ********************************* The previous chapter discusses the Emacs commands that are useful for making changes in programs. This chapter deals with commands that assist in the larger process of developing and maintaining programs. * Menu: * Compilation:: Compiling programs in languages other than Lisp (C, Pascal, etc.) * Debuggers:: Running symbolic debuggers for non-Lisp programs. * Executing Lisp:: Various modes for editing Lisp programs, with different facilities for running the Lisp programs. * Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs. * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. * Eval: Lisp Eval. Executing a single Lisp expression in Emacs. * External Lisp:: Communicating through Emacs with a separate Lisp.  File: emacs, Node: Compilation, Next: Debuggers, Up: Building 20.1 Running Compilations under Emacs ===================================== Emacs can run compilers for noninteractive languages such as C and Fortran as inferior processes, feeding the error log into an Emacs buffer. It can also parse the error messages and show you the source lines where compilation errors occurred. `M-x compile' Run a compiler asynchronously under Emacs, with error messages to `*compilation*' buffer. `M-x grep' Run `grep' asynchronously under Emacs, with matching lines listed in the buffer named `*grep*'. `M-x kill-compilation' `M-x kill-grep' Kill the running compilation or `grep' subprocess. `C-x `' Visit the locus of the next compiler error message or `grep' match. `' Visit the locus of the error message that point is on. This command is used in the compilation buffer. `Mouse-2' Visit the locus of the error message that you click on. To run `make' or another compilation command, do `M-x compile'. This command reads a shell command line using the minibuffer, and then executes the command in an inferior shell, putting output in the buffer named `*compilation*'. The current buffer's default directory is used as the working directory for the execution of the command; normally, therefore, the compilation happens in this directory. When the shell command line is read, the minibuffer appears containing a default command line, which is the command you used the last time you did `M-x compile'. If you type just , the same command line is used again. For the first `M-x compile', the default is `make -k'. The default compilation command comes from the variable `compile-command'; if the appropriate compilation command for a file is something other than `make -k', it can be useful for the file to specify a local value for `compile-command' (*note File Variables::). Starting a compilation displays the buffer `*compilation*' in another window but does not select it. The buffer's mode line tells you whether compilation is finished, with the word `run' or `exit' inside the parentheses. You do not have to keep this buffer visible; compilation continues in any case. While a compilation is going on, the string `Compiling' appears in the mode lines of all windows. When this string disappears, the compilation is finished. If you want to watch the compilation transcript as it appears, switch to the `*compilation*' buffer and move point to the end of the buffer. When point is at the end, new compilation output is inserted above point, which remains at the end. If point is not at the end of the buffer, it remains fixed while more compilation output is added at the end of the buffer. To kill the compilation process, do `M-x kill-compilation'. When the compiler process terminates, the mode line of the `*compilation*' buffer changes to say `signal' instead of `run'. Starting a new compilation also kills any running compilation, as only one can exist at any time. However, `M-x compile' asks for confirmation before actually killing a compilation that is running. The `*compilation*' buffer uses a special major mode, Compilation mode. This mode provides the keys and to scroll by screenfuls, and `M-n' and `M-p' to move to the next or previous error message. You can also use `M-{' and `M-}' to move up or down to an error message for a different source file. You can visit the source for any particular error message by moving point in `*compilation*' to that error message and typing (`compile-goto-error'). Or click `Mouse-2' on the error message; you need not switch to the `*compilation*' buffer first. To parse the compiler error messages sequentially, type `C-x `' (`next-error'). The character following the `C-x' is the backquote or "grave accent," not the single-quote. This command is available in all buffers, not just in `*compilation*'; it displays the next error message at the top of one window and source location of the error in another window. The first time `C-x `' is used after the start of a compilation, it moves to the first error's location. Subsequent uses of `C-x `' advance down to subsequent errors. If you visit a specific error message with or `Mouse-2', subsequent `C-x `' commands advance from there. When `C-x `' gets to the end of the buffer and finds no more error messages to visit, it fails and signals an Emacs error. `C-u C-x `' starts scanning from the beginning of the compilation buffer. This way, you can process the same set of errors again. Just as you can run a compiler, you can also run `grep' and then visit the lines on which matches were found. To do this, type `M-x grep' with an argument line that contains the same arguments you would give `grep' when running it normally: a `grep'-style regexp (usually in single-quotes to quote the shell's special characters) followed by file names which may use wildcards. The output from `grep' goes in the `*grep*' buffer, and you can find the matching lines in the source with `C-x `' and just like compiler errors. Note: a shell is used to run the compile command, but the shell is told that it should be noninteractive. This means in particular that the shell starts up with no prompt. If you find your usual shell prompt making an unsightly appearance in the `*compilation*' buffer, it means you have made a mistake in your shell's init file by setting the prompt unconditionally. (The init file name may be `.profile', `.cshrc', `.shrc', or various other things, depending on the shell you use.) The shell init file should set the prompt only if there already is a prompt. In csh, here is how to do it: if ($?prompt) set prompt = ... And here's how to do it in bash: if [ "${PS1+set}" = set ] then prompt=... fi There may well be other things that your shell's init file ought to do only for an interactive shell. You can use the same method to conditionalize them. The features of Compilation mode are also available in a minor mode called Compilation Minor mode. This lets you parse error messages in any buffer, not just a normal compilation output buffer. Type `M-x compilation-minor-mode' to enable the minor mode. This defines the keys and `Mouse-2', as in the Compilation major mode. In an Rlogin buffer (*note Remote Host::), Compilation minor mode automatically accesses remote source files by FTP (*note File Names::). The MS-DOS "operating system" does not support asynchronous subprocesses; to work around this lack, `M-x compile' runs the compilation command synchronously on MS-DOS. As a consequence, you must wait until the command finishes before you can do anything else in Emacs. *Note MS-DOS::.  File: emacs, Node: Debuggers, Next: Executing Lisp, Prev: Compilation, Up: Building 20.2 Running Debuggers Under Emacs ================================== The GUD (Grand Unified Debugger) library provides an interface to various symbolic debuggers from within Emacs. We recommend the debugger GDB, which is free software, but you can also run DBX, SDB or XDB if you have them. GUD can also serve as an interface to the Perl's debugging mode. * Menu: * Starting GUD:: How to start a debugger subprocess. * Debugger Operation:: Connection between the debugger and source buffers. * Commands of GUD:: Key bindings for common commands. * GUD Customization:: Defining your own commands for GUD.  File: emacs, Node: Starting GUD, Next: Debugger Operation, Up: Debuggers 20.2.1 Starting GUD ------------------- There are five commands for starting a debugger, each corresponding to a particular debugger program. `M-x gdb FILE ' Run GDB as a subprocess of Emacs. This command creates a buffer for input and output to GDB, and switches to it. If a GDB buffer already exists, it just switches to that buffer. `M-x dbx FILE ' Similar, but run DBX instead of GDB. `M-x xdb FILE ' Similar, but run XDB instead of GDB. Use the variable `gud-xdb-directories' to specify directories to search for source files. `M-x sdb FILE ' Similar, but run SDB instead of GDB. Some versions of SDB do not mention source file names in their messages. When you use them, you need to have a valid tags table (*note Tags::) in order for GUD to find functions in the source code. If you have not visited a tags table or the tags table doesn't list one of the functions, you get a message saying `The sdb support requires a valid tags table to work'. If this happens, generate a valid tags table in the working directory and try again. `M-x perldb FILE ' Run the Perl interpreter in debug mode to debug FILE, a Perl program. You can only run one debugger process at a time. Each of these commands takes one argument: a command line to invoke the debugger. In the simplest case, specify just the name of the executable file you want to debug. You may also use options that the debugger supports. However, shell wild cards and variables are not allowed. GUD assumes that the first argument not preceded by a `-' is the executable file name.  File: emacs, Node: Debugger Operation, Next: Commands of GUD, Prev: Starting GUD, Up: Debuggers 20.2.2 Debugger Operation ------------------------- When you run a debugger with GUD, the debugger uses an Emacs buffer for its ordinary input and output. This is called the GUD buffer. The debugger displays the source files of the program by visiting them in Emacs buffers. An arrow (`=>') in one of these buffers indicates the current execution line. Moving point in this buffer does not move the arrow. You can start editing these source files at any time in the buffers that were made to display them. The arrow is not part of the file's text; it appears only on the screen. If you do modify a source file, keep in mind that inserting or deleting lines will throw off the arrow's positioning; GUD has no way of figuring out which line corresponded before your changes to the line number in a debugger message. Also, you'll typically have to recompile and restart the program for your changes to be reflected in the debugger's tables. If you wish, you can control your debugger process entirely through the debugger buffer, which uses a variant of Shell mode. All the usual commands for your debugger are available, and you can use the Shell mode history commands to repeat them. *Note Shell Mode::.  File: emacs, Node: Commands of GUD, Next: GUD Customization, Prev: Debugger Operation, Up: Debuggers 20.2.3 Commands of GUD ---------------------- The GUD interaction buffer uses a variant of Shell mode, so the commands of Shell mode are available (*note Shell Mode::). GUD mode also provides commands for setting and clearing breakpoints, for selecting stack frames, and for stepping through the program. These commands are available both in the GUD buffer and globally, but with different key bindings. The breakpoint commands are usually used in source file buffers, because that is the way to specify where to set or clear the breakpoint. Here's the global command to set a breakpoint: `C-x ' Set a breakpoint on the source line that point is on. Here are the other special commands provided by GUD. The keys starting with `C-c' are available only in the GUD interaction buffer. The bindings that start with `C-x C-a' are available in the GUD buffer and also in source files. `C-c C-l' `C-x C-a C-l' Display in another window the last line referred to in the GUD buffer (that is, the line indicated in the last location message). This runs the command `gud-refresh'. `C-c C-s' `C-x C-a C-s' Execute a single line of code (`gud-step'). If the line contains a function call, execution stops after entering the called function. `C-c C-n' `C-x C-a C-n' Execute a single line of code, stepping across entire function calls at full speed (`gud-next'). `C-c C-i' `C-x C-a C-i' Execute a single machine instruction (`gud-stepi'). `C-c C-r' `C-x C-a C-r' Continue execution without specifying any stopping point. The program will run until it hits a breakpoint, terminates, or gets a signal that the debugger is checking for (`gud-cont'). `C-c C-d' `C-x C-a C-d' Delete the breakpoint(s) on the current source line, if any (`gud-remove'). If you use this command in the GUD interaction buffer, it applies to the line where the program last stopped. `C-c C-t' `C-x C-a C-t' Set a temporary breakpoint on the current source line, if any. If you use this command in the GUD interaction buffer, it applies to the line where the program last stopped. The above commands are common to all supported debuggers. If you are using GDB or (some versions of) DBX, these additional commands are available: `C-c <' `C-x C-a <' Select the next enclosing stack frame (`gud-up'). This is equivalent to the `up' command. `C-c >' `C-x C-a >' Select the next inner stack frame (`gud-down'). This is equivalent to the `down' command. If you are using GDB, these additional key bindings are available: `' With GDB, complete a symbol name (`gud-gdb-complete-command'). This key is available only in the GUD interaction buffer, and requires GDB versions 4.13 and later. `C-c C-f' `C-x C-a C-f' Run the program until the selected stack frame returns (or until it stops for some other reason). These commands interpret a numeric argument as a repeat count, when that makes sense. Because serves as a completion command, you can't use it to enter a tab as input to the program you are debugging with GDB. Instead, type `C-q ' to enter a tab.  File: emacs, Node: GUD Customization, Prev: Commands of GUD, Up: Debuggers 20.2.4 GUD Customization ------------------------ On startup, GUD runs one of the following hooks: `gdb-mode-hook', if you are using GDB; `dbx-mode-hook', if you are using DBX; `sdb-mode-hook', if you are using SDB; `xdb-mode-hook', if you are using XDB; `perldb-mode-hook', for Perl debugging mode. You can use these hooks to define custom key bindings for the debugger interaction buffer. *Note Hooks::. Here is a convenient way to define a command that sends a particular command string to the debugger, and set up a key binding for it in the debugger interaction buffer: (gud-def FUNCTION CMDSTRING BINDING DOCSTRING) This defines a command named FUNCTION which sends CMDSTRING to the debugger process, and gives it the documentation string DOCSTRING. You can use the command thus defined in any buffer. If BINDING is non-`nil', `gud-def' also binds the command to `C-c BINDING' in the GUD buffer's mode and to `C-x C-a BINDING' generally. The command string CMDSTRING may contain certain `%'-sequences that stand for data to be filled in at the time FUNCTION is called: `%f' The name of the current source file. If the current buffer is the GUD buffer, then the "current source file" is the file that the program stopped in. `%l' The number of the current source line. If the current buffer is the GUD buffer, then the "current source line" is the line that the program stopped in. `%e' The text of the C lvalue or function-call expression at or adjacent to point. `%a' The text of the hexadecimal address at or adjacent to point. `%p' The numeric argument of the called function, as a decimal number. If the command is used without a numeric argument, `%p' stands for the empty string. If you don't use `%p' in the command string, the command you define ignores any numeric argument.  File: emacs, Node: Executing Lisp, Next: Lisp Libraries, Prev: Debuggers, Up: Building 20.3 Executing Lisp Expressions =============================== Emacs has several different major modes for Lisp and Scheme. They are the same in terms of editing commands, but differ in the commands for executing Lisp expressions. Each mode has its own purpose. Emacs-Lisp mode The mode for editing source files of programs to run in Emacs Lisp. This mode defines `C-M-x' to evaluate the current defun. *Note Lisp Libraries::. Lisp Interaction mode The mode for an interactive session with Emacs Lisp. It defines to evaluate the sexp before point and insert its value in the buffer. *Note Lisp Interaction::. Lisp mode The mode for editing source files of programs that run in Lisps other than Emacs Lisp. This mode defines `C-M-x' to send the current defun to an inferior Lisp process. *Note External Lisp::. Inferior Lisp mode The mode for an interactive session with an inferior Lisp process. This mode combines the special features of Lisp mode and Shell mode (*note Shell Mode::). Scheme mode Like Lisp mode but for Scheme programs. Inferior Scheme mode The mode for an interactive session with an inferior Scheme process. Most editing commands for working with Lisp programs are in fact available globally. *Note Programs::.  File: emacs, Node: Lisp Libraries, Next: Lisp Interaction, Prev: Executing Lisp, Up: Building 20.4 Libraries of Lisp Code for Emacs ===================================== Lisp code for Emacs editing commands is stored in files whose names conventionally end in `.el'. This ending tells Emacs to edit them in Emacs-Lisp mode (*note Executing Lisp::). To execute a file of Emacs Lisp code, use `M-x load-file'. This command reads a file name using the minibuffer and then executes the contents of that file as Lisp code. It is not necessary to visit the file first; in any case, this command reads the file as found on disk, not text in an Emacs buffer. Once a file of Lisp code is installed in the Emacs Lisp library directories, users can load it using `M-x load-library'. Programs can load it by calling `load-library', or with `load', a more primitive function that is similar but accepts some additional arguments. `M-x load-library' differs from `M-x load-file' in that it searches a sequence of directories and tries three file names in each directory. Suppose your argument is LIB; the three names are `LIB.elc', `LIB.el', and lastly just `LIB'. If `LIB.elc' exists, it is by convention the result of compiling `LIB.el'; it is better to load the compiled file, since it will load and run faster. If `load-library' finds that `LIB.el' is newer than `LIB.elc' file, it prints a warning, because it's likely that somebody made changes to the `.el' file and forgot to recompile it. Because the argument to `load-library' is usually not in itself a valid file name, file name completion is not available. Indeed, when using this command, you usually do not know exactly what file name will be used. The sequence of directories searched by `M-x load-library' is specified by the variable `load-path', a list of strings that are directory names. The default value of the list contains the directory where the Lisp code for Emacs itself is stored. If you have libraries of your own, put them in a single directory and add that directory to `load-path'. `nil' in this list stands for the current default directory, but it is probably not a good idea to put `nil' in the list. If you find yourself wishing that `nil' were in the list, most likely what you really want to do is use `M-x load-file' this once. Often you do not have to give any command to load a library, because the commands defined in the library are set up to "autoload" that library. Trying to run any of those commands calls `load' to load the library; this replaces the autoload definitions with the real ones from the library. Emacs Lisp code can be compiled into byte-code which loads faster, takes up less space when loaded, and executes faster. *Note Byte Compilation: (elisp)Byte Compilation. By convention, the compiled code for a library goes in a separate file whose name consists of the library source file with `c' appended. Thus, the compiled code for `foo.el' goes in `foo.elc'. That's why `load-library' searches for `.elc' files first.  File: emacs, Node: Lisp Eval, Next: External Lisp, Prev: Lisp Interaction, Up: Building 20.5 Evaluating Emacs-Lisp Expressions ====================================== Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp mode; this happens automatically for file names ending in `.el'. By contrast, Lisp mode itself is used for editing Lisp programs intended for other Lisp systems. To switch to Emacs-Lisp mode explicitly, use the command `M-x emacs-lisp-mode'. For testing of Lisp programs to run in Emacs, it is often useful 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, for invoking noninteractive functions (functions that are not commands). `M-:' Read a single Lisp expression in the minibuffer, evaluate it, and print the value in the echo area (`eval-expression'). `C-x C-e' Evaluate the Lisp expression before point, and print the value in the echo area (`eval-last-sexp'). `C-M-x' Evaluate the defun containing or after point, and print the value in the echo area (`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-:' (`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-:' was typed. `M-:' can easily confuse users who do not understand it. 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 command `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. `C-M-x' treats `defvar' expressions specially. Normally, evaluating a `defvar' expression does nothing if the variable it defines already has a value. But `C-M-x' unconditionally resets the variable to the initial value specified in the `defvar' expression. This special feature is convenient for debugging Lisp programs. The command `C-x C-e' (`eval-last-sexp') evaluates the Lisp expression preceding point in the buffer, and displays the value in the echo area. It is available in all major modes, not just Emacs-Lisp mode. It does not treat `defvar' specially. If `C-M-x' or `C-x C-e' is given a numeric argument, it inserts the value into the current buffer at point, rather than displaying it in the echo area. The argument's 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. Later, as you find bugs and change individual functions, use `C-M-x' on each function that you change. This keeps the Lisp world in step with the source file.  File: emacs, Node: Lisp Interaction, Next: Lisp Eval, Prev: Lisp Libraries, Up: Building 20.6 Lisp Interaction Buffers ============================= The buffer `*scratch*' which is selected when Emacs starts up is provided for evaluating Lisp expressions interactively inside Emacs. The simplest way to use the `*scratch*' buffer is to insert Lisp expressions and type after each expression. This command reads the Lisp expression before point, evaluates it, and inserts the value in printed representation before point. The result is a complete typescript of the expressions you have evaluated and their values. The `*scratch*' buffer's major mode is Lisp Interaction mode, which is the same as Emacs-Lisp mode except for the binding of . 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. Type `M-x lisp-interaction-mode' to put the current buffer in Lisp Interaction mode. An alternative way of evaluating Emacs Lisp expressions interactively is to use Inferior Emacs-Lisp mode, which provides an interface rather like Shell mode (*note Shell Mode::) for evaluating Emacs Lisp expressions. Type `M-x ielm' to create an `*ielm*' buffer which uses this mode.  File: emacs, Node: External Lisp, Prev: Lisp Eval, Up: Building 20.7 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. (You can change the name of the Lisp executable file by setting the variable `inferior-lisp-program'.) To give input to Lisp, go to the end of the buffer and type the input, terminated by . The `*lisp*' buffer is in Inferior Lisp mode, which combines the special characteristics of Lisp mode with most of the features of Shell mode (*note Shell Mode::). The definition of to send a line to a subprocess is one of the features of 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', `.lsp', 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-eval-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 Executing Lisp::.  File: emacs, Node: Abbrevs, Next: Picture, Prev: Building, Up: Top 21 Abbrevs ********** A defined "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'. Then you would be able to insert `find outer otter ' into the buffer by typing `f o o '. A second kind of abbreviation facility is called "dynamic abbrev expansion". You use dynamic abbrev expansion with an explicit command to expand the letters in the buffer before point by looking for other words in the buffer that start with those letters. *Note Dynamic Abbrevs::. * Menu: * Abbrev Concepts:: Fundamentals of defined abbrevs. * 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. * Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling.  File: emacs, Node: Abbrev Concepts, Next: Defining Abbrevs, Up: Abbrevs 21.1 Abbrev Concepts ==================== An "abbrev" is a word which has been defined to "expand" into a specified "expansion". When you insert a word-separator character following the abbrev, that expands the abbrev--replacing the abbrev with its expansion. For example, if `foo' is defined as an abbrev expanding to `find outer otter', then you can insert `find outer otter.' into the buffer by typing `f o o .'. 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.  File: emacs, Node: Defining Abbrevs, Next: Expanding Abbrevs, Prev: Abbrev Concepts, Up: Abbrevs 21.2 Defining Abbrevs ===================== `C-x a g' Define an abbrev, using one or more words before point as its expansion (`add-global-abbrev'). `C-x a l' Similar, but define an abbrev specific to the current major mode (`add-mode-abbrev'). `C-x a i g' Define a word in the buffer as an abbrev (`inverse-add-global-abbrev'). `C-x a i l' Define a word in the buffer as a mode-specific abbrev (`inverse-add-mode-abbrev'). `M-x kill-all-abbrevs' This command discards all abbrev definitions currently in effect, leaving a blank slate. 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 a g' (`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 a g f o o '. An argument of zero to `C-x a g' means to use the contents of the region as the expansion of the abbrev being defined. The command `C-x a l' (`add-mode-abbrev') is similar, but defines a mode-specific abbrev. Mode specific abbrevs are active only in a particular major mode. `C-x a l' defines an abbrev for the major mode in effect at the time `C-x a l' is typed. The arguments work the same as for `C-x a g'. If the text already in the buffer is the abbrev, rather than its expansion, use command `C-x a i g' (`inverse-add-global-abbrev') instead of `C-x a g', or use `C-x a i l' (`inverse-add-mode-abbrev') instead of `C-x a l'. These commands are called "inverse" because they invert the meaning of the two text strings they use (one from the buffer and one read with the minibuffer). To change the definition of an abbrev, just define a new definition. When the abbrev has a prior definition, the abbrev definition commands ask for confirmation for replacing it. To remove an abbrev definition, give a negative argument to the abbrev definition command: `C-u - C-x a g' or `C-u - C-x a l'. The former removes a global definition, while the latter removes a mode-specific definition. `M-x kill-all-abbrevs' removes all the abbrev definitions there are, both global and local.  File: emacs, Node: Expanding Abbrevs, Next: Editing Abbrevs, Prev: Defining Abbrevs, Up: Abbrevs 21.3 Controlling Abbrev Expansion ================================= An abbrev expands whenever it is present in the buffer just before point and you type a self-inserting whitespace or punctuation character (, comma, etc.). More precisely, any character that is not a word constituent expands an abbrev, and any word constituent character can be part of an abbrev. The most common way to use an abbrev is to insert it and then insert a punctuation character to expand it. 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 commands are used to control abbrev expansion: `M-'' Separate a prefix from a following abbrev to be expanded (`abbrev-prefix-mark'). `C-x a e' Expand the abbrev before point (`expand-abbrev'). This is effective even when Abbrev mode is not enabled. `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 you can do is 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 hyphen 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 non-word character to expand the abbrev `cnst' into `construction'. This expansion step also deletes the hyphen that indicated `M-'' had been used. The result 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 and bring back the abbrev itself by typing `C-_' to undo (*note Undo::). This also undoes the insertion of the non-word character that expanded the abbrev. If the result you want is the terminating non-word character plus the unexpanded abbrev, you must reinsert the terminating character, quoting it with `C-q'. `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. Expanding an abbrev runs the hook `pre-abbrev-expand-hook' (*note Hooks::).  File: emacs, Node: Editing Abbrevs, Next: Saving Abbrevs, Prev: Expanding Abbrevs, Up: Abbrevs 21.4 Examining and Editing Abbrevs ================================== `M-x list-abbrevs' Display 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 of the line is the abbrev. The number that follows is the number of times the abbrev has been expanded. Emacs keeps track of this to help you see which abbrevs you actually use, so that you can 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. Type `C-c C-c' in this buffer to install the abbrev definitions as specified in the buffer--and delete any abbrev definitions not listed. The command `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 21.5 Saving Abbrevs =================== These commands allow you to keep abbrev definitions between editing sessions. `M-x write-abbrev-file FILE ' Write a file FILE describing all defined abbrevs. `M-x read-abbrev-file FILE ' Read the file FILE and define abbrevs as specified therein. `M-x quietly-read-abbrev-file FILE ' Similar but do not display a message about what is going on. `M-x define-abbrevs' Define abbrevs from definitions in current buffer. `M-x insert-abbrevs' Insert all abbrevs and their expansions into current buffer. `M-x write-abbrev-file' reads a file name using the minibuffer and then writes a description of all current abbrev definitions into that file. This is used to save abbrev definitions for use in a later session. The text stored in the file is a series of Lisp expressions that, when executed, define the same abbrevs that you currently have. `M-x read-abbrev-file' reads a file name using the minibuffer and then 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, they use the file name specified in 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, Next: Dabbrev Customization, Prev: Saving Abbrevs, Up: Abbrevs 21.6 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'). `C-M-/' Complete the word before point as a dynamic abbrev (`dabbrev-completion'). 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 considering the entire buffer before point, it searches the text after point. The variable `dabbrev-limit', if non-`nil', specifies how far in the buffer to search for an expansion. After searching all of the current buffer, `M-/' normally searches other buffers, unless you have set `dabbrev-check-all-buffers' to `nil'. A negative argument to `M-/', as in `C-u - M-/', says to search first for expansions after point, and second for expansions before point. If you repeat the `M-/' to look for another expansion, do not specify an argument. This tries all the expansions after point and then the expansions before point. After you have expanded a dynamic abbrev, you can copy additional words that follow the expansion in its original context. Simply type ` M-/' for each word you want to copy. The spacing and punctuation between words is copied along with the words. The command `C-M-/' (`dabbrev-completion') performs completion of a dynamic abbreviation. Instead of trying the possible expansions one by one, it finds all of them, then inserts the text that they have in common. If they have nothing in common, `C-M-/' displays a list of completions, from which you can select a choice in the usual manner. *Note Completion::. 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: Dabbrev Customization, Prev: Dynamic Abbrevs, Up: Abbrevs 21.7 Customizing Dynamic Abbreviation ===================================== Normally, dynamic abbrev expansion ignores case when searching for expansions. That is, the expansion need not agree in case with the word you are expanding. If you set `dabbrev-case-fold-search' to `nil', then the word and the expansion must match in case. The value of `dabbrev-case-fold-search' may be any expression. Dynamic abbrev expansion evaluates that expression, and ignores case while searching if its value is not `nil'. The default value of `dabbrev-case-fold-search' is `case-fold-search', so normally the value of `case-fold-search' controls the decision. The reason why dynamic abbrev expansion normally ignores case when searching for expansions is that normally the value of `case-fold-search' is `t'. Normally, dynamic abbrev expansion preserves the case pattern _of the word you are expanding_, by converting the expansion to that case pattern. If you set `dabbrev-case-replace' to `nil', the expansion is copied without conversion. The variables `dabbrev-case-fold-search' and `dabbrev-case-replace' are handled in a special way. Their values are actually Lisp expressions which are evaluated each time a decision needs to be made. If the expression's value is non-`nil', then case is ignored in searching, or converted on replacement, respectively. If the expression's value is `nil', case is not ignored or not converted. The default values let the variables `case-fold-search' (*note Search Case::) and `case-replace' (*note Replacement and Case::) control what to do. The variable `dabbrev-abbrev-char-regexp', if non-`nil', controls which characters are considered part of a word, for dynamic expansion purposes. The regular expression must match just one character, never two or more. The same regular expression also determines which characters are part of an expansion. The value `nil' has a special meaning: abbreviations are made of word characters, but expansions are made of word and symbol characters. In shell scripts and makefiles, a variable name is sometimes prefixed with `$' and sometimes not. Major modes for this kind of text can customize dynamic abbreviation to handle optional prefixes by setting the variable `dabbrev-abbrev-skip-leading-regexp'. Its value should be a regular expression that matches the optional prefix that dynamic abbreviation should ignore.  File: emacs, Node: Picture, Next: Sending Mail, Prev: Abbrevs, Up: Top 22 Editing Pictures ******************* To edit 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 `M-x 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 Picture mode replaces the most frequently-used commands with variants 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 so you can use the `C-c C-c' command (`picture-mode-exit') later to go back to that mode. `C-c C-c' also deletes spaces from the ends of lines, unless given a numeric argument. The special commands of Picture mode all work in other modes (provided the `picture' library is loaded), but are not bound to keys except in Picture mode. 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 runs the hook `picture-mode-hook' (*note Hooks::). * 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 22.1 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', a command which moves point one column to the right, 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. runs `picture-newline', which just moves to the beginning of the following line so that new text will replace that line. Picture mode provides erasure instead of deletion and killing of text. (`picture-backward-clear-column') replaces the preceding character with a space rather than removing it; this moves point backwards. `C-d' (`picture-clear-column') replaces the next character or characters with spaces, but does not move point. (If you want to clear characters to spaces and move forward over them, use .) `C-k' (`picture-clear-line') really kills the contents of lines, but does not delete the newlines from the buffer. To do actual insertion, you must use special commands. `C-o' (`picture-open-line') creates a blank line after the current line; it never splits a line. `C-M-o', `split-line', makes sense in Picture mode, so it is not changed. (`picture-duplicate-line') inserts below the current line another line with the same contents. To do actual deletion in Picture mode, use `C-w', `C-c C-d' (which is defined as `delete-char', as `C-d' is in other modes), or 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 22.2 Controlling Motion after Insert ==================================== Since "self-inserting" characters in Picture mode 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 22.3 Picture Mode Tabs ====================== Two kinds of tab-like action are provided in Picture mode. Use `M-' (`picture-tab-search') for context-based tabbing. 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-', this command moves to the next such interesting character in the current line. `M-' does not change the text; it only moves point. "Interesting" characters are defined by the variable `picture-tab-chars', which should define a set of characters. The syntax for this variable is like the syntax used inside of `[...]' in a regular expression--but without the `[' and the `]'. Its default value is `"!-~"'. 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 ', `picture-set-tab-stops'. This command sets the tab stops to the positions which `M-' would consider significant in the current line. The use of this command, together with , can get the effect of context-based tabbing. But `M-' is more convenient in the cases where it is sufficient. It may be convenient to prevent use of actual tab characters in pictures. For example, this prevents `C-x ' from messing up the picture. You can do this by setting the variable `indent-tabs-mode' to `nil'. *Note Just Spaces::.  File: emacs, Node: Rectangles in Picture, Prev: Tabs in Picture, Up: Picture 22.4 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 with spaces (`picture-clear-rectangle'). With argument, delete the text. `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. `C-c C-k' either with or without a numeric argument saves the rectangle for `C-c C-y'. 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 differs 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 23 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-s' or `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-x 5 m' Likewise, but make a new frame (`mail-other-frame'). `C-c C-s' In Mail mode, send the message (`mail-send'). `C-c C-c' Send the message and bury the mail 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. `C-x 5 m' (`mail-other-frame') creates a new frame to select the `*mail*' buffer. 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-uniquely' (*note Misc Buffer::). Then you can use `C-x m' or its variants described above to make a new `*mail*' buffer. Once you've done that, you can work with each mail buffer independently. * Menu: * Format: Mail Format. Format of the mail being composed. * Headers: Mail Headers. Details of permitted mail header fields. * Aliases: Mail Aliases. Abbreviating and grouping mail addresses. * Mode: Mail Mode. Special commands for editing mail being composed. * Spook: Distracting NSA. How to distract the NSA's attention.  File: emacs, Node: Mail Format, Next: Mail Headers, Up: Sending Mail 23.1 The Format of the Mail Buffer ================================== In addition to the "text" or "body", 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 and edit 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: gnu@prep.ai.mit.edu CC: lungfish@spam.org, byob@spam.org Subject: The Emacs Manual --Text follows this line-- Please ignore this message.  File: emacs, Node: Mail Headers, Next: Mail Aliases, Prev: Mail Format, Up: Sending Mail 23.2 Mail Header Fields ======================= A header field in the mail buffer starts with a field name at the beginning of a line, terminated by a colon. Upper and lower case are equivalent in field names (and in mailing addresses also). After the colon and optional whitespace comes the contents of the field. You can use any name you like for a header field, but normally people use only standard field names with accepted meanings. Here is a table of fields commonly used in outgoing messages. `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, which should not appear in the header of the message actually sent. Copies sent this way are called "blind carbon copies". To send a blind carbon copy of every outgoing message to yourself, set the variable `mail-self-blind' to `t'. `FCC' This field contains the name of one file and directs Emacs to append a copy of the message to that file when you send the message. If the file is in Rmail format, Emacs writes the message to Rmail format; otherwise, Emacs writes the message in system mail file format. To put a fixed file name as in `FCC' field each time you start editing an outgoing message, set the variable `mail-archive-file-name' to that file name. Unless you remove the `FCC' field before sending, the message will be written into that file when it 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. If you don't specify the `From' field yourself, Emacs uses the value of `user-mail-address' as the default. `Reply-to' Use this field to direct replies to a different address. Most mail-reading programs (including Rmail) automatically send replies to the `Reply-to' address in preference to the `From' address. By adding a `Reply-to' field to your header, you can work around any problems your `From' address may cause for replies. To put a fixed `Reply-to' address into every outgoing message, set the variable `mail-default-reply-to' to that address (as a string). Then `mail' initializes the message with a `Reply-to' field as specified. You can delete or alter that header field before you send the message, if you wish. When Emacs starts up, if the environment variable `REPLYTO' is set, `mail-default-reply-to' is initialized from that environment 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 reply 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.net, this@there.net, me@gnu.cambridge.mass.usa.earth.spiral3281 When you send the message, if you didn't write a `From' field yourself, Emacs puts in one for you. The variable `mail-from-style' controls the format: `nil' Just the email address, as in `king@grassland.com'. `parens' Both email address and full name, as in `king@grassland.com (Elvis Parsley)'. `angles' Both email address and full name, as in `Elvis Parsley '.  File: emacs, Node: Mail Aliases, Next: Mail Mode, Prev: Mail Headers, Up: Sending Mail 23.3 Mail Aliases ================= You can define "mail aliases" in a file named `~/.mailrc'. These are short mnemonic names which stand for mail addresses or groups of mail addresses. Like many other mail programs, Emacs expands aliases when they occur in the `To', `From', `CC', `BCC', and `Reply-to' fields, plus their `Resent-' variants. To define an alias in `~/.mailrc', write a line in the following format: alias SHORTADDRESS FULLADDRESSES Here FULLADDRESSES stands for one or more mail addresses for SHORTADDRESS to expand into. Separate multiple addresses with spaces; if an address contains a space, quote the whole address with a pair of double-quotes. For instance, to make `maingnu' stand for `gnu@prep.ai.mit.edu' plus a local address of your own, put in this line: alias maingnu gnu@prep.ai.mit.edu local-gnu Emacs also recognizes include commands in `.mailrc' files. They look like this: source FILENAME The file `~/.mailrc' is used primarily by other mail-reading programs; it can contain various other commands. Emacs ignores everything in it except for alias definitions and include commands. Another way to define a mail alias, within Emacs alone, is with the `define-mail-alias' command. It prompts for the alias and then the full address. You can use it to define aliases in your `.emacs' file, like this: (define-mail-alias "maingnu" "gnu@prep.ai.mit.edu") `define-mail-alias' records aliases by adding them to a variable named `mail-aliases'. If you are comfortable with manipulating Lisp lists, you can set `mail-aliases' directly. The initial value of `mail-aliases' is `t', which means that Emacs should read `.mailrc' to get the proper value. You can specify a different file name to use instead of `~/.mailrc' by setting the variable `mail-personal-alias-file'. Normally, Emacs expands aliases when you send the message. If you like, you can have mail aliases expand as abbrevs, as soon as you type them in (*note Abbrevs::). To enable this feature, execute the following: (add-hook 'mail-setup-hook 'mail-abbrevs-setup) This can go in your `.emacs' file. *Note Hooks::. If you use this feature, you must use `define-mail-abbrev' instead of `define-mail-alias'; the latter does not work with this package. Note that the mail abbreviation package uses the variable `mail-abbrevs' instead of `mail-aliases', and that all alias names are converted to lower case. The mail abbreviation package also provides the `C-c C-a' (`mail-interactive-insert-alias') command, which reads an alias name (with completion) and inserts its definition at point. This is useful when editing the message text itself or a header field such as `Subject' in which Emacs does not normally expand aliases. Note that abbrevs expand only if you insert a word-separator character afterward. However, you can rebind `C-n' and `M->' to cause expansion as well. Here's how to do that: (add-hook 'mail-setup-hook '(lambda () (substitute-key-definition 'next-line 'mail-abbrev-next-line mail-mode-map global-map) (substitute-key-definition 'end-of-buffer 'mail-abbrev-end-of-buffer mail-mode-map global-map)))  File: emacs, Node: Mail Mode, Next: Distracting NSA, Prev: Mail Aliases, Up: Sending Mail 23.4 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'). `M-' Complete a mailing address (`mail-complete'). `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-f C-b' Move to the `BCC' header field, creating one if there is none (`mail-bcc'). `C-c C-f C-f' Move to the `FCC' header field, creating one if there is none (`mail-fcc'). `C-c C-t' Move to the beginning of the message body text (`mail-text'). `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'). `M-x ispell-message' Do spelling correction on the message text, but not on citations from other messages. 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 or switches to another buffer. It puts the mail buffer at the lowest priority for reselection by default, since you are finished with using it. This is the usual way to send the message. While editing a header field that contains mailing addresses, such as `To:', `CC:' and `BCC:', you can complete a mailing address by typing `M-' (`mail-complete'). For completion purposes, the valid mailing addresses are taken to be the local users' names plus your personal mail aliases. Additionally, if your site provides a mail directory or a specific host to use for any unrecognized user name, you can arrange to query that host for completion--see the variables `mail-directory-process' and `mail-directory-stream' in the source code. If you type `M-' in the body of the message, it invokes `ispell-complete-word', as in Text mode. Mail mode provides special commands for editing the headers and text of the message before you send it. There are five 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, `C-c C-f C-c' (`mail-cc') for the `CC' field, `C-c C-f C-b' (`mail-bcc') for the `BCC' field, and `C-c C-f C-f' (`mail-fcc') for the `FCC' field. If the field in question does not exist, these commands create one. We provide special motion commands for these particular fields because they are the fields users most often want to edit. `C-c C-t' (`mail-text') moves point to just after the header separator line--that is, to the beginning of the message body text. `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. To insert your signature automatically, set the variable `mail-signature' to `t'; then starting a mail message automatically inserts the contents of your `.signature' file. If you want to omit your signature from a particular message, delete it from the buffer before you send the message. You can also set `mail-signature' to a string; then that string is inserted automatically as your signature when you start editing a message to send. 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. You can specify the text for `C-c C-y' to insert at the beginning of each line: set `mail-yank-prefix' to the desired string. (A value of `nil' means to use indentation; this is the default.) However, `C-u C-c C-y' never adds anything at the beginning of the inserted lines, regardless of the value of `mail-yank-prefix'. After using `C-c C-y', you can use 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 individually. To fill a single paragraph of the quoted message, use `M-q', after first setting the fill prefix appropriately to handle the indentation. *Note Filling::. You can do spelling correction on the message text you have written with the command `M-x ispell-message'. If you have yanked an incoming message into the outgoing draft, this command skips what was yanked, but it checks the text that you yourself inserted. (It looks for indentation or `mail-yank-prefix' to distinguish the cited lines from your input.) *Note Spelling::. Mail mode defines the character `%' as a word separator; this is helpful for using the word commands to edit mail addresses. Mail mode is normally used in buffers set up automatically by the `mail' command and related commands. However, you can also switch to Mail mode in a file-visiting buffer. That is a useful thing to do if you have saved draft message text in a file. In a file-visiting buffer, `C-c C-c' does not clear the modified flag, because only saving the file should do that. As a result, you don't get a warning about trying to send the same message twice. Turning on Mail mode (which `C-x m' does automatically) runs the normal hooks `text-mode-hook' and `mail-mode-hook'. Initializing a new outgoing message runs the normal hook `mail-setup-hook'; if you want to add special fields to your mail header or make other changes to the appearance of the mail buffer, use that hook. *Note Hooks::. The main difference between these hooks is just when they are invoked. Whenever you type `M-x mail', `mail-mode-hook' runs as soon as the `*mail*' buffer is created. Then the `mail-setup' function puts in the default contents of the buffer. After these default contents are inserted, `mail-setup-hook' runs.  File: emacs, Node: Distracting NSA, Prev: Mail Mode, Up: Sending Mail 23.5 Distracting the NSA ======================== `M-x spook' adds a line of randomly chosen keywords to an outgoing mail message. The keywords are chosen from a list of words that suggest you are discussing something subversive. The idea behind this feature is the suspicion that the NSA snoops on all electronic mail messages that contain keywords suggesting they might find them interesting. (The NSA says they don't, but that's what they _would_ say.) The idea is that if lots of people add suspicious words to their messages, the NSA will get so busy with spurious input that they will have to give up reading it all. Here's how to insert spook keywords automatically whenever you start entering an outgoing message: (add-hook 'mail-setup-hook 'spook) Whether or not this confuses the NSA, it at least amuses people.  File: emacs, Node: Rmail, Next: Dired, Prev: Sending Mail, Up: Top 24 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. * Menu: * Basic: Rmail Basics. Basic concepts of Rmail, and simple use. * 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. * Reply: Rmail Reply. Sending replies to messages you are viewing. * Summary: Rmail Summary. Summaries show brief info on many messages. * Sort: Rmail Sorting. Sorting messages in Rmail. * Display: Rmail Display. How Rmail displays a message; customization. * Editing: Rmail Editing. Editing message text and headers in Rmail. * Digest: Rmail Digest. Extracting the messages from a digest message. * Out of Rmail:: Converting an Rmail file to mailbox format. * Rot13: Rmail Rot13. Reading messages encoded in the rot13 code.  File: emacs, Node: Rmail Basics, Next: Rmail Scrolling, Up: Rmail 24.1 Basic Concepts of Rmail ============================ 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 Rmail file". The command `M-x rmail' reads your primary Rmail file, merges new mail in from your inboxes, displays the first message you haven't read yet, and lets you begin reading. The variable `rmail-file-name' specifies the name of the primary Rmail file. Rmail uses narrowing to hide all but one message in the Rmail file. The message that is shown is called the "current message". Rmail mode's special commands can do such things as delete the current message, copy it into another file, send a reply, or move to another message. You can also create multiple Rmail files and use Rmail to move messages between them. Within the Rmail file, messages are normally arranged sequentially in order of receipt; you can specify other ways to sort them. Messages are 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 with 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 save it 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 also saves the Rmail file after merging 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. (The Rmail command `b', `rmail-bury', does this for you.) 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::).  File: emacs, Node: Rmail Scrolling, Next: Rmail Motion, Prev: Rmail Basics, Up: Rmail 24.2 Scrolling Within a Message =============================== When Rmail displays a message that does not fit on the screen, you must scroll through it to read the rest. You could do this with `C-v', `M-v' and `M-<', but in Rmail scrolling is so frequent that it deserves to be easier to type. `' Scroll forward (`scroll-up'). `' 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 and 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.  File: emacs, Node: Rmail Motion, Next: Rmail Deletion, Prev: Rmail Scrolling, Up: Rmail 24.3 Moving Among Messages ========================== The most basic thing to do with a message is to read it. The way to do this in Rmail is to make the message current. The usual practice is to move sequentially through the file, since this is the order of receipt of messages. When you enter Rmail, you are positioned at the first message that you have not yet made current (that is, the first one that has the `unseen' attribute; *note Rmail Labels::). Move forward to see the other new messages; move backward to reexamine old messages. `n' Move to the next nondeleted message, skipping any intervening deleted messages (`rmail-next-undeleted-message'). `p' Move to the previous nondeleted message (`rmail-previous-undeleted-message'). `M-n' Move to the next message, including deleted messages (`rmail-next-message'). `M-p' Move to the previous message, including deleted messages (`rmail-previous-message'). `j' Move to the first message. With argument N, move to message number N (`rmail-show-message'). `>' Move to the last message (`rmail-last-message'). `<' Move to the first message (`rmail-first-message'). `M-s REGEXP ' Move to the next message containing a match for REGEXP (`rmail-search'). `- M-s REGEXP ' Move to the previous message containing a match for REGEXP. `n' and `p' are the usual way of moving among messages in Rmail. They move through the messages sequentially, but skip over deleted messages, which is usually what you want to do. Their command definitions are named `rmail-next-undeleted-message' and `rmail-previous-undeleted-message'. If you do not want to skip deleted messages--for example, if you want to move to a message to undelete it--use the variants `M-n' and `M-p' (`rmail-next-message' and `rmail-previous-message'). A numeric argument to any of these commands serves as a repeat count. In Rmail, you can specify a numeric argument by typing just the digits. You don't need to type `C-u' first. The `M-s' (`rmail-search') command is Rmail's version of search. The usual incremental search command `C-s' works in Rmail, but it searches only within the current message. The purpose of `M-s' is to search for another message. It reads a regular expression (*note Regexps::) nonincrementally, then searches starting at the beginning of the following message for a match. It then selects that message. If REGEXP is empty, `M-s' reuses the regexp used the previous time. To search backward in the file for another message, give `M-s' a negative argument. In Rmail you can do this with `- M-s'. It is also possible to search for a message based on labels. *Note Rmail Labels::. To move to a message specified by absolute message number, use `j' (`rmail-show-message') with the message number as argument. With no argument, `j' selects the first message. `<' (`rmail-first-message') also selects the first message. `>' (`rmail-last-message') selects the last message.  File: emacs, Node: Rmail Deletion, Next: Rmail Inbox, Prev: Rmail Motion, Up: Rmail 24.4 Deleting Messages ====================== When you no longer need to keep a message, you can "delete" it. This flags it as ignorable, and some Rmail commands pretend it is no longer present; but it still has its place in the Rmail file, and still has its message number. "Expunging" the Rmail file actually removes the deleted messages. The remaining messages are renumbered consecutively. Expunging is the only action that changes the message number of any message, except for undigestifying (*note Rmail Digest::). `d' Delete the current message, and move to the next nondeleted message (`rmail-delete-forward'). `C-d' Delete the current message, and move to the previous nondeleted message (`rmail-delete-backward'). `u' Undelete the current message, or move back to a deleted message and undelete it (`rmail-undelete-previous-message'). `x' Expunge the Rmail file (`rmail-expunge'). There are two Rmail commands for deleting messages. Both delete the current message and select another message. `d' (`rmail-delete-forward') moves to the following message, skipping messages already deleted, while `C-d' (`rmail-delete-backward') moves to the previous nondeleted message. If there is no nondeleted message to move to in the specified direction, the message that was just deleted remains current. Whenever Rmail deletes a message, it invokes the function(s) listed in `rmail-delete-message-hook'. When the hook functions are invoked, the message has been marked deleted, but it is still the current message in the Rmail buffer. To make all the deleted messages finally vanish from the Rmail file, type `x' (`rmail-expunge'). Until you do this, you can still "undelete" the deleted messages. The undeletion command, `u' (`rmail-undelete-previous-message'), is designed to cancel the effect of a `d' command in most cases. It undeletes the current message if the current message is deleted. Otherwise it moves backward to previous messages until a deleted message is found, and undeletes that message. You can usually undo a `d' with a `u' because the `u' moves back to and undeletes the message that the `d' deleted. But this does not work when the `d' skips a few already-deleted messages that follow the message being deleted; then the `u' command undeletes the last of the messages that were skipped. There is no clean way to avoid this problem. However, by repeating the `u' command, you can eventually get back to the message that you intend to undelete. You can also select a particular deleted message with the `M-p' command, then type `u' to undelete it. A deleted message has the `deleted' attribute, and as a result `deleted' appears in the mode line when the current message is deleted. In fact, deleting or undeleting a message is nothing more than adding or removing this attribute. *Note Rmail Labels::.  File: emacs, Node: Rmail Inbox, Next: Rmail Files, Prev: Rmail Deletion, Up: Rmail 24.5 Rmail Files and Inboxes ============================ The operating system places incoming mail for you in a file that we call your "inbox". When you start up Rmail, it runs a C program called `movemail' to copy the new messages from your inbox into your primary Rmail file, which also contains other messages saved from previous Rmail sessions. It is in this file that you actually read the mail with Rmail. This operation is called "getting new mail". You can get new mail at any time in Rmail by typing `g'. The variable `rmail-primary-inbox-list' contains a list of the files which are inboxes for your primary Rmail file. If you don't set this variable explicitly, it is initialized from the `MAIL' environment variable, or, as a last resort, set to `nil', which means to use the default inbox. The default inbox is `/var/mail/USERNAME', `/usr/spool/mail/USERNAME', or `/usr/mail/USERNAME', depending on your operating system. You can specify the inbox file(s) for any Rmail file with the command `set-rmail-inbox-list'; see *Note Rmail Files::. Some sites use a method called POP for accessing users' inbox data instead of storing the data in inbox files. `movemail' can work with POP if you compile it with the macro `MAIL_USE_POP' defined, and then install it setuid to `root'. It is safe to install `movemail' in this way. Note: `movemail' only works with POP3, not with older versions of POP. Assuming you have compiled and installed `movemail' appropriately, you can specify a POP inbox with a "file name" of the form `po:USERNAME'. `movemail' handles such a name by opening a connection to the POP server. The `MAILHOST' environment variable specifies the machine to look for the server on. Accessing mail via POP may require a password. If the variable `rmail-pop-password' is non-`nil', it specifies the password to use for POP. Alternatively, if `rmail-pop-password-required' is non-`nil', then Rmail asks you for the password to use. There are two reasons for having separate Rmail files and inboxes. 1. The inbox file format varies between operating systems and according to the other mail software in use. Only one part of Rmail needs to know about the alternatives, and it need only understand how to convert all of them to Rmail's own format. 2. It is very cumbersome to access an inbox file without danger of losing mail, because it is necessary to interlock with mail delivery. Moreover, different operating systems use different interlocking techniques. The strategy of moving mail out of the inbox once and for all into a separate Rmail file avoids the need for interlocking in all the rest of Rmail, since only Rmail operates on the Rmail file. Rmail was written to use Babyl format as its internal format. Since then, we have recognized that the usual inbox format on Unix and GNU systems is adequate for the job, and we plan to change Rmail to use that as its internal format. However, the Rmail file will still be separate from the inbox file, even on systems where their format is the same. When getting new mail, Rmail first copies the new mail from the inbox file to the Rmail file; then it saves the Rmail file; then it truncates the inbox file. This way, a system crash may cause duplication of mail between the inbox and the Rmail file, but cannot lose mail. When `movemail' copies mail from an inbox in the system's mailer directory, it actually puts it in an intermediate file `~/.newmail-INBOXNAME'. Once it finishes, Rmail reads that file, merges the new mail, saves the Rmail file, and only then deletes the intermediate file. If there is a crash at the wrong time, this file continues to exist and Rmail will use it again the next time it gets new mail from that inbox.  File: emacs, Node: Rmail Files, Next: Rmail Output, Prev: Rmail Inbox, Up: Rmail 24.6 Multiple Rmail Files ========================= Rmail operates by default on your "primary Rmail file", which is named `~/RMAIL' and receives your incoming mail from your system inbox file. But you can also have other Rmail files and edit them with Rmail. These files can receive mail through their own inboxes, or you can move messages into them with explicit Rmail commands (*note Rmail Output::). `i FILE ' Read FILE into Emacs and run Rmail on it (`rmail-input'). `M-x set-rmail-inbox-list FILES ' Specify inbox file names for current Rmail file to get mail from. `g' Merge new mail from current Rmail file's inboxes (`rmail-get-new-mail'). `C-u g FILE ' Merge new mail from inbox file FILE. To run Rmail on a file other than your primary Rmail file, you may use the `i' (`rmail-input') command in Rmail. This visits the file in Rmail mode. You can use `M-x rmail-input' even when not in Rmail. The file you read with `i' should normally be a valid Rmail file. If it is not, Rmail tries to decompose it into a stream of messages in various known formats. If it succeeds, it converts the whole file to an Rmail file. If you specify a file name that doesn't exist, `i' initializes a new buffer for creating a new Rmail file. You can also select an Rmail file from a menu. Choose first the menu bar Classify item, then from the Classify menu choose the Input Rmail File item; then choose the Rmail file you want. The variables `rmail-secondary-file-directory' and `rmail-secondary-file-regexp' specify which files to offer in the menu: the first variable says which directory to find them in; the second says which files in that directory to offer (all those that match the regular expression). These variables also apply to choosing a file for output (*note Rmail Output::). Each Rmail file can contain a list of inbox file names; you can specify this list with `M-x set-rmail-inbox-list FILES '. The argument can contain any number of file names, separated by commas. It can also be empty, which specifies that this file should have no inboxes. Once a list of inboxes is specified, the Rmail file remembers it permanently until you specify a different list. As a special exception, if your primary Rmail file does not specify any inbox files, it uses your standard system inbox. The `g' command (`rmail-get-new-mail') merges mail into the current Rmail file from its specified inboxes. If the Rmail file has no inboxes, `g' does nothing. The command `M-x rmail' also merges new mail into your primary Rmail file. To merge mail from a file that is not the usual inbox, give the `g' key a numeric argument, as in `C-u g'. Then it reads a file name and merges mail from that file. The inbox file is not deleted or changed in any way when `g' with an argument is used. This is, therefore, a general way of merging one file of messages into another.  File: emacs, Node: Rmail Output, Next: Rmail Labels, Prev: Rmail Files, Up: Rmail 24.7 Copying Messages Out to Files ================================== These commands copy messages from an Rmail file into another file. `o FILE ' Append a copy of the current message to the file FILE, using Rmail file format by default (`rmail-output-to-rmail-file'). `C-o FILE ' Append a copy of the current message to the file FILE, using system inbox file format by default (`rmail-output'). The commands `o' and `C-o' copy the current message into a specified file. This file may be an Rmail file or it may be in system inbox format; the output commands ascertain the file's format and write the copied message in that format. The `o' and `C-o' commands differ in two ways: each has its own separate default file name, and each specifies a choice of format to use when the file does not already exist. The `o' command uses Rmail format when it creates a new file, while `C-o' uses system inbox format for a new file. The default file name for `o' is the file name used last with `o', and the default file name for `C-o' is the file name used last with `C-o'. If the output file is an Rmail file currently visited in an Emacs buffer, the output commands copy the message into that buffer. It is up to you to save the buffer eventually in its file. You can also output a message to an Rmail file chosen with a menu. Choose first the menu bar Classify item, then from the Classify menu choose the Output Rmail Menu item; then choose the Rmail file you want. This outputs the current message to that file, like the `o' command. The variables `rmail-secondary-file-directory' and `rmail-secondary-file-regexp' specify which files to offer in the menu: the first variable says which directory to find them in; the second says which files in that directory to offer (all those that match the regular expression). Copying a message gives the original copy of the message the `filed' attribute, so that `filed' appears in the mode line when such a message is current. If you like to keep just a single copy of every mail message, set the variable `rmail-delete-after-output' to `t'; then the `o' and `C-o' commands delete the original message after copying it. (You can undelete the original afterward if you wish.) Copying messages into files in system inbox format uses the header fields that are displayed in Rmail at the time. Thus, if you use the `t' command to view the entire header and then copy the message, the entire header is copied. *Note Rmail Display::. The variable `rmail-output-file-alist' lets you specify intelligent defaults for the output file, based on the contents of the current message. The value should be a list whose elements have this form: (REGEXP . NAME-EXP) If there's a match for REGEXP in the current message, then the default file name for output is NAME-EXP. If multiple elements match the message, the first matching element decides the default file name. The subexpression NAME-EXP may be a string constant giving the file name to use, or more generally it may be any Lisp expression that returns a file name as a string. `rmail-output-file-alist' applies to both `o' and `C-o'.  File: emacs, Node: Rmail Labels, Next: Rmail Reply, Prev: Rmail Output, Up: Rmail 24.8 Labels =========== Each message can have various "labels" assigned to it as a means of classification. Each label has a name; different names are different labels. Any given label is either present or absent on a particular message. A few label names have standard meanings and are given to messages automatically by Rmail when appropriate; these special labels are called "attributes". All other labels are assigned only by users. `a LABEL ' Assign the label LABEL to the current message (`rmail-add-label'). `k LABEL ' Remove the label LABEL from the current message (`rmail-kill-label'). `C-M-n LABELS ' Move to the next message that has one of the labels LABELS (`rmail-next-labeled-message'). `C-M-p LABELS ' Move to the previous message that has one of the labels LABELS (`rmail-previous-labeled-message'). `C-M-l LABELS ' Make a summary of all messages containing any of the labels LABELS (`rmail-summary-by-labels'). The `a' (`rmail-add-label') and `k' (`rmail-kill-label') commands allow you to assign or remove any label on the current message. If the LABEL argument is empty, it means to assign or remove the same label most recently assigned or removed. Once you have given messages labels to classify them as you wish, there are two ways to use the labels: in moving and in summaries. The command `C-M-n LABELS ' (`rmail-next-labeled-message') moves to the next message that has one of the labels LABELS. The argument LABELS specifies one or more label names, separated by commas. `C-M-p' (`rmail-previous-labeled-message') is similar, but moves backwards to previous messages. A numeric argument to either command serves as a repeat count. The command `C-M-l LABELS ' (`rmail-summary-by-labels') displays a summary containing only the messages that have at least one of a specified set of labels. The argument LABELS is one or more label names, separated by commas. *Note Rmail Summary::, for information on summaries. If the LABELS argument to `C-M-n', `C-M-p' or `C-M-l' is empty, it means to use the last set of labels specified for any of these commands. Some labels such as `deleted' and `filed' have built-in meanings and are assigned to or removed from messages automatically at appropriate times; these labels are called "attributes". Here is a list of Rmail attributes: `unseen' Means the message has never been current. Assigned to messages when they come from an inbox file, and removed when a message is made current. When you start Rmail, it initially shows the first message that has this attribute. `deleted' Means the message is deleted. Assigned by deletion commands and removed by undeletion commands (*note Rmail Deletion::). `filed' Means the message has been copied to some other file. Assigned by the file output commands (*note Rmail Files::). `answered' Means you have mailed an answer to the message. Assigned by the `r' command (`rmail-reply'). *Note Rmail Reply::. `forwarded' Means you have forwarded the message. Assigned by the `f' command (`rmail-forward'). *Note Rmail Reply::. `edited' Means you have edited the text of the message within Rmail. *Note Rmail Editing::. `resent' Means you have resent the message. Assigned by the command `M-x rmail-resend'. *Note Rmail Reply::. All other labels are assigned or removed only by the user, and have no standard meaning.  File: emacs, Node: Rmail Reply, Next: Rmail Summary, Prev: Rmail Labels, Up: Rmail 24.9 Sending Replies ==================== Rmail has several commands that use Mail mode to send outgoing mail. *Note Sending Mail::, for information on using Mail mode. What are documented here are the special commands of Rmail for entering Mail mode. Note that the usual keys for sending mail--`C-x m', `C-x 4 m', and `C-x 5 m'--are available in Rmail mode and work just as they usually do. `m' Send a message (`rmail-mail'). `c' Continue editing already started outgoing message (`rmail-continue'). `r' Send a reply to the current Rmail message (`rmail-reply'). `f' Forward current message to other users (`rmail-forward'). `C-u f' Resend the current message to other users (`rmail-resend'). `M-m' Try sending a bounced message a second time (`rmail-retry-failure'). The most common reason to send a message while in Rmail is to reply to the message you are reading. To do this, type `r' (`rmail-reply'). This displays the `*mail*' buffer in another window, much like `C-x 4 m', but preinitializes the `Subject', `To', `CC' and `In-reply-to' header fields based on the message you are replying to. The `To' field starts out as the address of the person who sent the message you received, and the `CC' field starts out with all the other recipients of that message. You can exclude certain recipients from being placed automatically in the `CC', using the variable `rmail-dont-reply-to-names'. Its value should be a regular expression (as a string); any recipient that the regular expression matches, is excluded from the `CC' field. The default value matches your own name, and any name starting with `info-'. (Those names are excluded because there is a convention of using them for large mailing lists to broadcast announcements.) To omit the `CC' field completely for a particular reply, enter the reply command with a numeric argument: `C-u r' or `1 r'. Once the `*mail*' buffer has been initialized, editing and sending the mail goes as usual (*note Sending Mail::). You can edit the presupplied header fields if they are not right for you. You can also use the commands of Mail mode (*note Mail Mode::), including `C-c C-y' which yanks in the message that you are replying to. You can switch to the Rmail buffer, select a different message there, switch back, and yank the new current message. Sometimes a message does not reach its destination. Mailers usually send the failed message back to you, enclosed in a "failure message". The Rmail command `M-m' (`rmail-retry-failure') prepares to send the same message a second time: it sets up a `*mail*' buffer with the same text and header fields as before. If you type `C-c C-c' right away, you send the message again exactly the same as the first time. Alternatively, you can edit the text or headers and then send it. The variable `rmail-retry-ignored-headers', in the same format as `rmail-ignored-headers' (*note Rmail Display::), controls which headers are stripped from the failed message when retrying it; it defaults to nil. Another frequent reason to send mail in Rmail is to "forward" the current message to other users. `f' (`rmail-forward') makes this easy by preinitializing the `*mail*' buffer with the current message as the text, and a subject designating a forwarded message. All you have to do is fill in the recipients and send. When you forward a message, recipients get a message which is "from" you, and which has the original message in its contents. Forwarding a message encloses it between two delimiter lines. It also modifies every line that starts with a dash, by inserting `- ' at the start of the line. When you receive a forwarded message, if it contains something besides ordinary text--for example, program source code--you might find it useful to undo that transformation. You can do this by selecting the forwarded message and typing `M-x unforward-rmail-message'. This command extracts the original forwarded message, deleting the inserted `- ' strings, and inserts it into the Rmail file as a separate message immediately following the current one. "Resending" is an alternative similar to forwarding; the difference is that resending sends a message that is "from" the original sender, just as it reached you--with a few added header fields `Resent-from' and `Resent-to' to indicate that it came via you. To resend a message in Rmail, use `C-u f'. (`f' runs `rmail-forward', which is programmed to invoke `rmail-resend' if you provide a numeric argument.) The `m' (`rmail-mail') command is used to start editing an outgoing message that is not a reply. It leaves the header fields empty. Its only difference from `C-x 4 m' is that it makes the Rmail buffer accessible for `C-c C-y', just as `r' does. Thus, `m' can be used to reply to or forward a message; it can do anything `r' or `f' can do. The `c' (`rmail-continue') command resumes editing the `*mail*' buffer, to finish editing an outgoing message you were already composing, or to alter a message you have sent. If you set the variable `rmail-mail-new-frame' to a non-`nil' value, then all the Rmail commands to start sending a message create a new frame to edit it in. This frame is deleted when you send the message, or when you use the `Don't Send' item in the `Mail' menu.  File: emacs, Node: Rmail Summary, Next: Rmail Sorting, Prev: Rmail Reply, Up: Rmail 24.10 Summaries =============== A "summary" is a buffer containing one line per message to give you an overview of the mail in an Rmail file. Each line shows the message number, the sender, the labels, and the subject. Almost all Rmail commands are valid in the summary buffer also; these apply to the message described by the current line of the summary. Moving point in the summary buffer selects messages as you move to their summary lines. A summary buffer applies to a single Rmail file only; if you are editing multiple Rmail files, each one can have its own summary buffer. The summary buffer name is made by appending `-summary' to the Rmail buffer's name. Normally only one summary buffer is displayed at a time. * Menu: * Rmail Make Summary:: Making various sorts of summaries. * Rmail Summary Edit:: Manipulating messages from the summary.  File: emacs, Node: Rmail Make Summary, Next: Rmail Summary Edit, Up: Rmail Summary 24.10.1 Making Summaries ------------------------ Here are the commands to create a summary for the current Rmail file. Once the Rmail file has a summary buffer, changes in the Rmail file (such as deleting or expunging messages, and getting new mail) automatically update the summary. `h' `C-M-h' Summarize all messages (`rmail-summary'). `l LABELS ' `C-M-l LABELS ' Summarize message that have one or more of the specified labels (`rmail-summary-by-labels'). `C-M-r RCPTS ' Summarize messages that have one or more of the specified recipients (`rmail-summary-by-recipients'). `C-M-t TOPIC ' Summarize messages that have a match for the specified regexp TOPIC in their subjects (`rmail-summary-by-topic'). The `h' or `C-M-h' (`rmail-summary') command fills the summary buffer for the current Rmail file with a summary of all the messages in the file. It then displays and selects the summary buffer in another window. `C-M-l LABELS ' (`rmail-summary-by-labels') makes a partial summary mentioning only the messages that have one or more of the labels LABELS. LABELS should contain label names separated by commas. `C-M-r RCPTS ' (`rmail-summary-by-recipients') makes a partial summary mentioning only the messages that have one or more of the recipients RCPTS. RCPTS should contain mailing addresses separated by commas. `C-M-t TOPIC ' (`rmail-summary-by-topic') makes a partial summary mentioning only the messages whose subjects have a match for the regular expression TOPIC. Note that there is only one summary buffer for any Rmail file; making one kind of summary discards any previously made summary. The variable `rmail-summary-window-size' says how many lines to use for the summary window.  File: emacs, Node: Rmail Summary Edit, Prev: Rmail Make Summary, Up: Rmail Summary 24.10.2 Editing in Summaries ---------------------------- You can use the Rmail summary buffer to do almost anything you can do in the Rmail buffer itself. In fact, once you have a summary buffer, there's no need to switch back to the Rmail buffer. You can select and display various messages in the Rmail buffer, from the summary buffer, just by moving point in the summary buffer to different lines. It doesn't matter what Emacs command you use to move point; whichever line point is on at the end of the command, that message is selected in the Rmail buffer. Almost all Rmail commands work in the summary buffer as well as in the Rmail buffer. Thus, `d' in the summary buffer deletes the current message, `u' undeletes, and `x' expunges. `o' and `C-o' output the current message to a file; `r' starts a reply to it. You can scroll the current message while remaining in the summary buffer using and . The Rmail commands to move between messages also work in the summary buffer, but with a twist: they move through the set of messages included in the summary. They also ensure the Rmail buffer appears on the screen (unlike cursor motion commands, which update the contents of the Rmail buffer but don't display it in a window unless it already appears). Here is a list of these commands: `n' Move to next line, skipping lines saying `deleted', and select its message. `p' Move to previous line, skipping lines saying `deleted', and select its message. `M-n' Move to next line and select its message. `M-p' Move to previous line and select its message. `>' Move to the last line, and select its message. `<' Move to the first line, and select its message. `M-s PATTERN ' Search through messages for PATTERN starting with the current message; select the message found, and move point in the summary buffer to that message's line. Deletion, undeletion, and getting new mail, and even selection of a different message all update the summary buffer when you do them in the Rmail buffer. If the variable `rmail-redisplay-summary' is non-`nil', these actions also bring the summary buffer back onto the screen. When you are finished using the summary, type `w' (`rmail-summary-wipe') to delete the summary buffer's window. You can also exit Rmail while in the summary: `q' (`rmail-summary-quit') deletes the summary window, then exits from Rmail by saving the Rmail file and switching to another buffer.  File: emacs, Node: Rmail Sorting, Next: Rmail Display, Prev: Rmail Summary, Up: Rmail 24.11 Sorting the Rmail File ============================ `M-x rmail-sort-by-date' Sort messages of current Rmail file by date. `M-x rmail-sort-by-subject' Sort messages of current Rmail file by subject. `M-x rmail-sort-by-author' Sort messages of current Rmail file by author's name. `M-x rmail-sort-by-recipient' Sort messages of current Rmail file by recipient's names. `M-x rmail-sort-by-correspondent' Sort messages of current Rmail file by the name of the other correspondent. `M-x rmail-sort-by-lines' Sort messages of current Rmail file by size (number of lines). `M-x rmail-sort-by-keywords LABELS ' Sort messages of current Rmail file by labels. The argument LABELS should be a comma-separated list of labels. The order of these labels specifies the order of messages; messages with the first label come first, messages with the second label come second, and so on. Messages which have none of these labels come last. The Rmail sort commands perform a _stable sort_: if there is no reason to prefer either one of two messages, their order remains unchanged. You can use this to sort by more than one criterion. For example, if you use `rmail-sort-by-date' and then `rmail-sort-by-author', messages from the same author appear in order by date. With a numeric argument, all these commands reverse the order of comparison. This means they sort messages from newest to oldest, from biggest to smallest, or in reverse alphabetical order.  File: emacs, Node: Rmail Display, Next: Rmail Editing, Prev: Rmail Sorting, Up: Rmail 24.12 Display of Messages ========================= Rmail reformats the header of each message before displaying it for the first time. Reformatting hides uninteresting header fields to reduce clutter. You can use the `t' command to show the entire header or to repeat the header reformatting operation. `t' Toggle display of complete header (`rmail-toggle-header'). Reformatting the header involves deleting most header fields, on the grounds that they are not interesting. The variable `rmail-ignored-headers' holds a regular expression that specifies which header fields to hide in this way--if it matches the beginning of a header field, that whole field is hidden. Rmail saves the complete original header before reformatting; to see it, use the `t' command (`rmail-toggle-header'). This discards the reformatted headers of the current message and displays it with the original header. Repeating `t' reformats the message again. Selecting the message again also reformats. One consequence of this is that if you edit the reformatted header (using `e'; *note Rmail Editing::), subsequent use of `t' will discard your edits. On the other hand, if you use `e' after `t', to edit the original (unreformatted) header, those changes are permanent. When used with a window system that supports multiple fonts, Rmail highlights certain header fields that are especially interesting--by default, the `From' and `Subject' fields. The variable `rmail-highlighted-headers' holds a regular expression that specifies the header fields to highlight; if it matches the beginning of a header field, that whole field is highlighted. If you specify unusual colors for your text foreground and background, the colors used for highlighting may not go well with them. If so, specify different colors for the `highlight' face. That is worth doing because the `highlight' face is used for other kinds of highlighting as well. *Note Faces::, for how to do this. To turn off highlighting entirely in Rmail, set `rmail-highlighted-headers' to `nil'.  File: emacs, Node: Rmail Editing, Next: Rmail Digest, Prev: Rmail Display, Up: Rmail 24.13 Editing Within a Message ============================== Most of the usual Emacs commands are available in Rmail mode, though a few, such as `C-M-n' and `C-M-h', are redefined by Rmail for other purposes. However, the Rmail buffer is normally read only, and most of the letters are redefined as Rmail commands. If you want to edit the text of a message, you must use the Rmail command `e'. `e' Edit the current message as ordinary text. The `e' command (`rmail-edit-current-message') switches from Rmail mode into Rmail Edit mode, another major mode which is nearly the same as Text mode. The mode line indicates this change. In Rmail Edit mode, letters insert themselves as usual and the Rmail commands are not available. When you are finished editing the message and are ready to go back to Rmail, type `C-c C-c', which switches back to Rmail mode. Alternatively, you can return to Rmail mode but cancel all the editing that you have done, by typing `C-c C-]'. Entering Rmail Edit mode runs the hook `text-mode-hook'; then it runs the hook `rmail-edit-mode-hook' (*note Hooks::). It adds the attribute `edited' to the message.  File: emacs, Node: Rmail Digest, Next: Out of Rmail, Prev: Rmail Editing, Up: Rmail 24.14 Digest Messages ===================== A "digest message" is a message which exists to contain and carry several other messages. Digests are used on some moderated mailing lists; all the messages that arrive for the list during a period of time such as one day are put inside a single digest which is then sent to the subscribers. Transmitting the single digest uses much less computer time than transmitting the individual messages even though the total size is the same, because the per-message overhead in network mail transmission is considerable. When you receive a digest message, the most convenient way to read it is to "undigestify" it: to turn it back into many individual messages. Then you can read and delete the individual messages as it suits you. To do this, select the digest message and type the command `M-x undigestify-rmail-message'. This extracts the submessages as separate Rmail messages, and inserts them following the digest. The digest message itself is flagged as deleted.  File: emacs, Node: Out of Rmail, Next: Rmail Rot13, Prev: Rmail Digest, Up: Rmail 24.15 Converting an Rmail File to Inbox Format ============================================== The command `M-x unrmail' converts a file in Rmail format to inbox format (also known as the system mailbox format), so that you can use it with other mail-editing tools. You must specify two arguments, the name of the Rmail file and the name to use for the converted file. `M-x unrmail' does not alter the Rmail file itself.  File: emacs, Node: Rmail Rot13, Prev: Out of Rmail, Up: Rmail 24.16 Reading Rot13 Messages ============================ Mailing list messages that might offend some readers are sometimes encoded in a simple code called "rot13"--so named because it rotates the alphabet by 13 letters. This code is not for secrecy, as it provides none; rather, it enables those who might be offended to avoid ever seeing the real text of the message. To view a buffer using the rot13 code, use the command `M-x rot13-other-window'. This displays the current buffer in another window which applies the code when displaying the text.  File: emacs, Node: Dired, Next: Calendar/Diary, Prev: Rmail, Up: Top 25 Dired, the Directory Editor ****************************** Dired makes an Emacs buffer containing a listing of a directory, and optionally some of its subdirectories as well. You can use the normal Emacs commands to move around in this buffer, and special Dired commands to operate on the files listed. * Menu: * Enter: Dired Enter. How to invoke Dired. * Commands: Dired Commands. Commands in the Dired buffer. * Deletion: Dired Deletion. Deleting files with Dired. * Flagging Many Files:: Flagging files based on their names. * Visit: Dired Visiting. Other file operations through Dired. * Marks vs Flags:: Flagging for deletion vs marking. * Operating on Files:: How to copy, rename, print, compress, etc. either one file or several files. * Shell Commands in Dired:: Running a shell command on the marked files. * Transforming File Names:: Using patterns to rename multiple files. * Comparison in Dired:: Running `diff' by way of Dired. * Subdirectories in Dired:: Adding subdirectories to the Dired buffer. * Subdirectory Motion:: Moving across subdirectories, and up and down. * Hiding Subdirectories:: Making subdirectories visible or invisible. * Updating: Dired Updating. Discarding lines for files of no interest. * Find: Dired and Find. Using `find' to choose the files for Dired.  File: emacs, Node: Dired Enter, Next: Dired Commands, Up: Dired 25.1 Entering Dired =================== To invoke Dired, do `C-x d' or `M-x dired'. The command reads a directory name or wildcard file name pattern as a minibuffer argument to specify which files to list. Where `dired' differs from `list-directory' is in putting the buffer into Dired mode so that the special commands of Dired are available. The variable `dired-listing-switches' specifies the options to give to `ls' for listing directory; this string _must_ contain `-l'. If you use a numeric prefix argument with the `dired' command, you can specify the `ls' switches with the minibuffer after you finish entering the directory specification. To display the Dired buffer in another window rather than in the selected window, use `C-x 4 d' (`dired-other-window)' instead of `C-x d'. `C-x 5 d' (`dired-other-frame') uses a separate frame to display the Dired buffer.  File: emacs, Node: Dired Commands, Next: Dired Deletion, Prev: Dired Enter, Up: Dired 25.2 Commands in the Dired Buffer ================================= The Dired buffer is "read-only", and inserting text in it is not useful, so ordinary printing characters such as `d' and `x' are used for special Dired commands. Some Dired commands "mark" or "flag" the "current file" (that is, the file on the current line); other commands operate on the marked files or on the flagged files. All the usual Emacs cursor motion commands are available in Dired buffers. Some special purpose cursor motion commands are also provided. The keys `C-n' and `C-p' are redefined to put the cursor at the beginning of the file name on the line, rather than at the beginning of the line. For extra convenience, and `n' in Dired are equivalent to `C-n'. `p' is equivalent to `C-p'. (Moving by lines is so common in Dired that it deserves to be easy to type.) (move up and unflag) is often useful simply for moving up.  File: emacs, Node: Dired Deletion, Next: Flagging Many Files, Prev: Dired Commands, Up: Dired 25.3 Deleting Files with Dired ============================== The primary use of Dired is to "flag" files for deletion and then delete the files previously flagged. `d' Flag this file for deletion. `u' Remove deletion flag on this line. `' Move point to previous line and remove the deletion flag on that line. `x' Delete the files that are flagged for deletion. You can flag a file for deletion by moving to the line describing the file and typing `d'. The deletion flag is visible as a `D' at the beginning of the line. This command moves point to the next line, so that repeated `d' commands flag successive files. A numeric argument serves as a repeat count. The files are flagged for deletion rather than deleted immediately to reduce the danger of deleting a file accidentally. Until you direct Dired to expunge the flagged files, you can remove deletion flags using the commands `u' and . `u' works just like `d', but removes flags rather than making flags. moves upward, removing flags; it is like `u' with numeric argument automatically negated. To delete the flagged files, type `x' (`dired-expunge'). This command first displays a list of all the file names flagged for deletion, and requests confirmation with `yes'. If you confirm, Dired deletes the flagged files, then deletes their lines from the text of the Dired buffer. The shortened Dired buffer remains selected. If you answer `no' or quit with `C-g' when asked to confirm, you return immediately to Dired, with the deletion flags still present in the buffer, and no files actually deleted.  File: emacs, Node: Flagging Many Files, Next: Dired Visiting, Prev: Dired Deletion, Up: Dired 25.4 Flagging Many Files ======================== `#' Flag all auto-save files (files whose names start and end with `#') for deletion (*note Auto Save::). `~' Flag all backup files (files whose names end with `~') for deletion (*note Backup::). `. (Period)' Flag excess numeric backup files for deletion. The oldest and newest few backup files of any one file are exempt; the middle ones are flagged. `% d REGEXP ' Flag for deletion all files whose names match the regular expression REGEXP (`dired-flag-files-regexp'). The `#', `~' and `.' commands flag many files for deletion, based on their file names. These commands are useful precisely because they do not actually delete any files; you can remove the deletion flags from any flagged files that you really wish to keep. `#' flags for deletion all files whose names look like auto-save files (*note Auto Save::)--that is, files whose names begin and end with `#'. `~' flags for deletion all files whose names say they are backup files (*note Backup::)--that is, whose names end in `~'. `.' (Period) flags just some of the backup files for deletion: all but the oldest few and newest few backups of any one file. Normally `dired-kept-versions' (*not* `kept-new-versions'; that applies only when saving) specifies the number of newest versions of each file to keep, and `kept-old-versions' specifies the number of oldest versions to keep. Period with a positive numeric argument, as in `C-u 3 .', specifies the number of newest versions to keep, overriding `dired-kept-versions'. A negative numeric argument overrides `kept-old-versions', using minus the value of the argument to specify the number of oldest versions of each file to keep. The `% d' command flags all files whose names match a specified regular expression (`dired-flag-files-regexp'). Only the non-directory part of the file name is used in matching. You can use `^' and `$' to anchor matches. You can exclude subdirectories by hiding them (*note Hiding Subdirectories::).  File: emacs, Node: Dired Visiting, Next: Marks vs Flags, Prev: Flagging Many Files, Up: Dired 25.5 Visiting Files in Dired ============================ There are several Dired commands for visiting or examining the files listed in the Dired buffer. All of them apply to the current line's file; if that file is really a directory, these commands invoke Dired on that subdirectory (making a separate Dired buffer). `f' Visit the file described on the current line, like typing `C-x C-f' and supplying that file name (`dired-find-file'). *Note Visiting::. `' Equivalent to `f'. `o' Like `f', but uses another window to display the file's buffer (`dired-find-file-other-window'). The Dired buffer remains visible in the first window. This is like using `C-x 4 C-f' to visit the file. *Note Windows::. `C-o' Visit the file described on the current line, and display the buffer in another window, but do not select that window (`dired-display-file'). `Mouse-2' Visit the file named by the line you click on (`dired-mouse-find-file-other-window'). This uses another window to display the file, like the `o' command. `v' View the file described on the current line, using `M-x view-file' (`dired-view-file'). Viewing a file is like visiting it, but is slanted toward moving around in the file conveniently and does not allow changing the file. *Note View File: Misc File Ops.  File: emacs, Node: Marks vs Flags, Next: Operating on Files, Prev: Dired Visiting, Up: Dired 25.6 Dired Marks vs. Flags ========================== Instead of flagging a file with `D', you can "mark" the file with some other character (usually `*'). Most Dired commands to operate on files, aside from "expunge" (`x'), look for files marked with `*'. Here are some commands for marking with `*' (and also for unmarking). (*Note Dired Deletion::, for commands to flag and unflag files.) `m' Mark the current file with `*' (`dired-mark'). With a numeric argument N, mark the next N files starting with the current file. (If N is negative, mark the previous -N files.) `*' Mark all executable files with `*' (`dired-mark-executables'). With a numeric argument, unmark all those files. `@' Mark all symbolic links with `*' (`dired-mark-symlinks'). With a numeric argument, unmark all those files. `/' Mark with `*' all files which are actually directories, except for `.' and `..' (`dired-mark-directories'). With a numeric argument, unmark all those files. `M- MARKCHAR' Remove all marks that use the character MARKCHAR (`dired-unmark-all-files'). If you specify as MARKCHAR, this command removes all marks, no matter what the marker character is. With a numeric argument, this command queries about each marked file, asking whether to remove its mark. You can answer `y' meaning yes, `n' meaning no, `!' to remove the marks from the remaining files without asking about them. `c OLD NEW' Replace all marks that use the character OLD with marks that use the character NEW (`dired-change-marks'). This command is the primary way to create or use marks other than `*' or `D'. The arguments are single characters--do not use to terminate them. You can use almost any character as a mark character by means of this command, to distinguish various classes of files. If OLD is a space (` '), then the command operates on all unmarked files; if NEW is a space, then the command unmarks the files it acts on. To illustrate the power of this command, here is how to put `*' marks on all the files that are unmarked, while unmarking all those that have `*' marks: c * t c SPC * c t SPC `% m REGEXP ' Mark (with `*') all files whose names match the regular expression REGEXP (`dired-mark-files-regexp'). `% m' is like `% d', except that it marks files with `*' instead of flagging with `D'. *Note Flagging Many Files::. Only the non-directory part of the file name is used in matching. Use `^' and `$' to anchor matches. Exclude subdirectories by hiding them (*note Hiding Subdirectories::).  File: emacs, Node: Operating on Files, Next: Shell Commands in Dired, Prev: Marks vs Flags, Up: Dired 25.7 Operating on Files ======================= This section describes the basic Dired commands to operate on one file or several files. All of these commands are capital letters; all of them use the minibuffer, either to read an argument or to ask for confirmation, before they act. All use the following convention to decide which files to manipulate: * If you give the command a numeric prefix argument N, it operates on the next N files, starting with the current file. (If N is negative, the command operates on the -N files preceding the current line.) * Otherwise, if some files are marked with `*', the command operates on all those files. * Otherwise, the command operates on the current file only. Here are the file-manipulating commands that operate on files in this way. (Some other Dired commands, such as `!' and the `%' commands, also use these conventions to decide which files to work on.) `C NEW ' Copy the specified files (`dired-do-copy'). The argument NEW is the directory to copy into, or (if copying a single file) the new name. If `dired-copy-preserve-time' is non-`nil', then copying with this command sets the modification time of the new file to be the same as that of the old file. `R NEW ' Rename the specified files (`dired-do-rename'). The argument NEW is the directory to rename into, or (if renaming a single file) the new name. Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names. `H NEW ' Make hard links to the specified files (`dired-do-hardlink'). The argument NEW is the directory to make the links in, or (if making just one link) the name to give the link. `S NEW ' Make symbolic links to the specified files (`dired-do-symlink'). The argument NEW is the directory to make the links in, or (if making just one link) the name to give the link. `M MODESPEC ' Change the mode (also called "permission bits") of the specified files (`dired-do-chmod'). This uses the `chmod' program, so MODESPEC can be any argument that `chmod' can handle. `G NEWGROUP ' Change the group of the specified files to NEWGROUP (`dired-do-chgrp'). `O NEWOWNER ' Change the owner of the specified files to NEWOWNER (`dired-do-chown'). (On most systems, only the superuser can do this.) The variable `dired-chown-program' specifies the name of the program to use to do the work (different systems put `chown' in different places). `P COMMAND ' Print the specified files (`dired-do-print'). You must specify the command to print them with, but the minibuffer starts out with a suitable guess made using the variables `lpr-command' and `lpr-switches' (the same variables that `lpr-file' uses; *note Hardcopy::). `Z' Compress or uncompress the specified files (`dired-do-compress'). If the file appears to be a compressed file, it is uncompressed; otherwise, it is compressed. `L' Load the specified Emacs Lisp files (`dired-do-load'). *Note Lisp Libraries::. `B' Byte compile the specified Emacs Lisp files (`dired-do-byte-compile'). *Note Byte Compilation: (elisp)Byte Compilation. `A REGEXP ' Search all the specified files for the regular expression REGEXP (`dired-do-search'). This command is a variant of `tags-search'. The search stops at the first match it finds; use `M-,' to resume the search and find the next match. *Note Tags Search::. `Q FROM TO ' Perform `query-replace-regexp' on each of the specified files, replacing matches for FROM (a regular expression) with the string TO (`dired-do-query-replace'). This command is a variant of `tags-query-replace'. If you exit the query replace loop, you can use `M-,' to resume the scan and replace more matches. *Note Tags Search::. One special file-operation command is `+' (`dired-create-directory'). This command reads a directory name and creates the directory if it does not already exist.  File: emacs, Node: Shell Commands in Dired, Next: Transforming File Names, Prev: Operating on Files, Up: Dired 25.8 Shell Commands in Dired ============================ The dired command `!' (`dired-do-shell-command') reads a shell command string in the minibuffer and runs that shell command on all the specified files. There are two ways of applying a shell command to multiple files: * If you use `*' in the shell command, then it runs just once, with the list of file names substituted for the `*'. The order of file names is the order of appearance in the Dired buffer. Thus, `! tar cf foo.tar * ' runs `tar' on the entire list of file names, putting them into one tar file `foo.tar'. * If the command string doesn't contain `*', then it runs once _for each file_, with the file name added at the end. For example, `! uudecode ' runs `uudecode' on each file. What if you want to run the shell command once for each file but with the file name inserted in the middle? Or if you want to use the file names in a more complicated fashion? Use a shell loop. For example, this shell command would run `uuencode' on each of the specified files, writing the output into a corresponding `.uu' file: for file in *; uuencode $file $file >$file.uu; done The working directory for the shell command is the top level directory of the Dired buffer. The `!' command does not attempt to update the Dired buffer to show new or modified files, because it doesn't really understand shell commands, and does not know what files the shell command changed. Use the `g' command to update the Dired buffer (*note Dired Updating::).  File: emacs, Node: Transforming File Names, Next: Comparison in Dired, Prev: Shell Commands in Dired, Up: Dired 25.9 Transforming File Names in Dired ===================================== Here are commands that alter file names in a systematic way: `% u' Rename each of the selected files to an upper case name (`dired-upcase'). If the old file names are `Foo' and `bar', the new names are `FOO' and `BAR'. `% l' Rename each of the selected files to a lower case name (`dired-downcase'). If the old file names are `Foo' and `bar', the new names are `foo' and `bar'. `% R FROM TO ' `% C FROM TO ' `% H FROM TO ' `% S FROM TO ' These four commands rename, copy, make hard links and make soft links, in each case computing the new name by regular expression substitution from the name of the old file. The four regular expression substitution commands effectively perform a search-and-replace on the selected file names in the Dired buffer. They read two arguments: a regular expression FROM, and a substitution pattern TO. The commands match each "old" file name against the regular expression FROM, and then replace the matching part with TO. You can use `\&' and `\DIGIT' in TO to refer to all or part of what the pattern matched in the old file name, as in `query-replace-regexp' (*note Query Replace::). If the regular expression matches more than once in a file name, only the first match is replaced. For example, `% R ^.*$ x-\& ' renames each selected file by prepending `x-' to its name. The inverse of this, removing `x-' from the front of each file name, is also possible: one method is `% R ^x-\(.*\)$ \1 '; another is `% R ^x- '. (Use `^' and `$' to anchor matches that should span the whole filename.) Normally, the replacement process does not consider the files' directory names; it operates on the file name within the directory. If you specify a numeric argument of zero, then replacement affects the entire absolute file name including directory name. Often you will want to apply the command to all files matching the same REGEXP that you use in the command. To do this, mark those files with `% m REGEXP ', then use the same regular expression in the command to operate on the files. To make this easier, the `%' commands to operate on files use the last regular expression specified in any `%' command as a default.  File: emacs, Node: Comparison in Dired, Next: Subdirectories in Dired, Prev: Transforming File Names, Up: Dired 25.10 File Comparison with Dired ================================ Here are two Dired commands that compare specified files using `diff'. `=' Compare the current file (the file at point) with another file (the file at the mark) using the `diff' program (`dired-diff'). The file at the mark is the first argument of `diff', and the file at point is the second argument. `M-=' Compare the current file with its latest backup file (`dired-backup-diff'). If the current file is itself a backup, compare it with the file it is a backup of; this way, you can compare a file with any backup version of your choice. The backup file is the first file given to `diff'.  File: emacs, Node: Subdirectories in Dired, Next: Subdirectory Motion, Prev: Comparison in Dired, Up: Dired 25.11 Subdirectories in Dired ============================= A Dired buffer displays just one directory in the normal case; but you can optionally include its subdirectories as well. The simplest way to include multiple directories in one Dired buffer is to specify the options `-lR' for running `ls'. (If you give a numeric argument when you run Dired, then you can specify these options in the minibuffer.) That produces a recursive directory listing showing all subdirectories at all levels. But usually all the subdirectories are too many; usually you will prefer to include specific subdirectories only. You can do this with the `i' command: `i' Insert the contents of a subdirectory later in the buffer. Use the `i' (`dired-maybe-insert-subdir') command on a line that describes a file which is a directory. It inserts the contents of that directory into the same Dired buffer, and moves there. Inserted subdirectory contents follow the top-level directory of the Dired buffer, just as they do in `ls -lR' output. If the subdirectory's contents are already present in the buffer, the `i' command just moves to it. In either case, `i' sets the Emacs mark before moving, so `C-u C-' takes you back to the old position in the buffer (the line describing that subdirectory). Use the `l' command (`dired-do-redisplay') to update the subdirectory's contents. Use `k' to delete the subdirectory. *Note Dired Updating::.  File: emacs, Node: Subdirectory Motion, Next: Hiding Subdirectories, Prev: Subdirectories in Dired, Up: Dired 25.12 Moving Over Subdirectories ================================ When a Dired buffer lists subdirectories, you can use the page motion commands `C-x [' and `C-x ]' to move by entire directories. The following commands move across, up and down in the tree of directories within one Dired buffer. They move to "directory header lines", which are the lines that give a directory's name, at the beginning of the directory's contents. `C-M-n' Go to next subdirectory header line, regardless of level (`dired-next-subdir'). `C-M-p' Go to previous subdirectory header line, regardless of level (`dired-prev-subdir'). `C-M-u' Go up to the parent directory's header line (`dired-tree-up'). `C-M-d' Go down in the directory tree, to the first subdirectory's header line (`dired-tree-down').  File: emacs, Node: Hiding Subdirectories, Next: Dired Updating, Prev: Subdirectory Motion, Up: Dired 25.13 Hiding Subdirectories =========================== "Hiding" a subdirectory means to make it invisible, except for its header line, via selective display (*note Selective Display::). `$' Hide or reveal the subdirectory that point is in, and move point to the next subdirectory (`dired-hide-subdir'). A numeric argument serves as a repeat count. `M-$' Hide all subdirectories in this Dired buffer, leaving only their header lines (`dired-hide-all'). Or, if any subdirectory is currently hidden, make all subdirectories visible again. You can use this command to get an overview in very deep directory trees or to move quickly to subdirectories far away. Ordinary Dired commands never consider files inside a hidden subdirectory. For example, the commands to operate on marked files ignore files in hidden directories even if they are marked. Thus you can use hiding to temporarily exclude subdirectories from operations without having to remove the markers. The subdirectory hiding commands toggle; that is, they hide what was visible, and show what was hidden.  File: emacs, Node: Dired Updating, Next: Dired and Find, Prev: Hiding Subdirectories, Up: Dired 25.14 Updating the Dired Buffer =============================== This section describes commands to update the Dired buffer to reflect outside (non-Dired) changes in the directories and files, and to delete part of the Dired buffer. `g' Update the entire contents of the Dired buffer (`revert-buffer'). `l' Update the specified files (`dired-do-redisplay'). `k' Delete the specified _file lines_--not the files, just the lines (`dired-do-kill-lines'). `s' Toggle between sorting by file name and sorting by date/time (`dired-sort-toggle-or-edit'). `C-u s SWITCHES ' Refresh the Dired buffer using SWITCHES as `dired-listing-switches'. Type `g' (`revert-buffer') to update the contents of the Dired buffer, based on changes in the files and directories listed. This preserves all marks except for those on files that have vanished. Hidden subdirectories are updated but remain hidden. To update only some of the files, type `l' (`dired-do-redisplay'). This command applies to the next N files, or to the marked files if any, or to the current file. Updating them means reading their current status from the file system and changing the buffer to reflect it properly. If you use `l' on a subdirectory header line, it updates the contents of the corresponding subdirectory. To delete the specified _file lines_--not the files, just the lines--type `k' (`dired-do-kill-lines'). This command applies to the next N files, or to the marked files if any, or to the current file. If you kill the line for a file that is a directory, the directory's contents are also deleted from the buffer. Typing `C-u k' on the header line for a subdirectory is another way to delete a subdirectory from the Dired buffer. The `g' command brings back any individual lines that you have killed in this way, but not subdirectories--you must use `i' to reinsert each subdirectory. The files in a Dired buffers are normally in listed alphabetical order by file names. Alternatively Dired can sort them by date/time. The Dired command `s' (`dired-sort-toggle-or-edit') switches between these two sorting modes. The mode line in a Dired buffer indicates which way it is currently sorted--by name, or by date. `C-u s SWITCHES ' lets you specify a new value for `dired-listing-switches'.  File: emacs, Node: Dired and Find, Prev: Dired Updating, Up: Dired 25.15 Dired and `find' ====================== You can select a set of files for display in a Dired buffer more flexibly by using the `find' utility to choose the files. To search for files with names matching a wildcard pattern use `M-x find-name-dired'. It reads arguments DIRECTORY and PATTERN, and chooses all the files in DIRECTORY or its subdirectories whose individual names match PATTERN. The files thus chosen are displayed in a Dired buffer in which the ordinary Dired commands are available. If you want to test the contents of files, rather than their names, use `M-x find-grep-dired'. This command reads two minibuffer arguments, DIRECTORY and REGEXP; it chooses all the files in DIRECTORY or its subdirectories that contain a match for REGEXP. It works by running the programs `find' and `grep'. The most general command in this series is `M-x find-dired', which lets you specify any condition that `find' can test. It takes two minibuffer arguments, DIRECTORY and FIND-ARGS; it runs `find' in DIRECTORY, passing FIND-ARGS to tell `find' what condition to test. To use this command, you need to know how to use `find'. The format of listing produced by these commands is controlled by the variable `find-ls-option', whose default value specifies using options `-ldi' for `ls'. If your listings are corrupted, you may need to change the value of this variable.  File: emacs, Node: Calendar/Diary, Next: Gnus, Prev: Dired, Up: Top 26 The Calendar and the Diary ***************************** Emacs provides the functions of a desk calendar, with a diary of planned or past events. To enter the calendar, type `M-x calendar'; this displays a three-month calendar centered on the current month, with point on the current date. With a numeric argument, as in `C-u M-x calendar', it prompts you for the month and year to be the center of the three-month calendar. The calendar uses its own buffer, whose major mode is Calendar mode. `Mouse-2' in the calendar brings up a menu of operations on a particular date; `C-Mouse-3' brings up a menu of commonly used calendar features that are independent of any particular date. To exit the calendar, type `q'. *Note Customizing the Calendar and Diary: (elisp)Calendar, for customization information about the calendar and diary. * Menu: * Calendar Motion:: Moving through the calendar; selecting a date. * Scroll Calendar:: Bringing earlier or later months onto the screen. * Counting Days:: How many days are there between two dates? * General Calendar:: Exiting or recomputing the calendar. * TeX Calendar:: Print a calendar using TeX. * Holidays:: Displaying dates of holidays. * Sunrise/Sunset:: Displaying local times of sunrise and sunset. * Lunar Phases:: Displaying phases of the moon. * Other Calendars:: Converting dates to other calendar systems. * Diary:: Displaying events from your diary. * Appointments:: Reminders when it's time to do something. * Daylight Savings:: How to specify when daylight savings time is active.  File: emacs, Node: Calendar Motion, Next: Scroll Calendar, Up: Calendar/Diary 26.1 Movement in the Calendar ============================= Calendar mode lets you move through the calendar in logical units of time such as days, weeks, months, and years. If you move outside the three months originally displayed, the calendar display "scrolls" automatically through time to make the selected date visible. Moving to a date lets you view its holidays or diary entries, convert it to other calendars; moving longer time periods is also useful simply to scroll the calendar. * Menu: * Calendar Unit Motion:: Moving by days, weeks, months, and years. * Move to Beginning or End:: Moving to start/end of weeks, months, and years. * Specified Dates:: Moving to the current date or another specific date.  File: emacs, Node: Calendar Unit Motion, Next: Move to Beginning or End, Up: Calendar Motion 26.1.1 Motion by Standard Lengths of Time ----------------------------------------- The commands for movement in the calendar buffer parallel the commands for movement in text. You can move forward and backward by days, weeks, months, and years. `C-f' Move point one day forward (`calendar-forward-day'). `C-b' Move point one day backward (`calendar-backward-day'). `C-n' Move point one week forward (`calendar-forward-week'). `C-p' Move point one week backward (`calendar-backward-week'). `M-}' Move point one month forward (`calendar-forward-month'). `M-{' Move point one month backward (`calendar-backward-month'). `C-x ]' Move point one year forward (`calendar-forward-year'). `C-x [' Move point one year backward (`calendar-forward-year'). The day and week commands are natural analogues of the usual Emacs commands for moving by characters and by lines. Just as `C-n' usually moves to the same column in the following line, in Calendar mode it moves to the same day in the following week. And `C-p' moves to the same day in the previous week. The arrow keys are equivalent to `C-f', `C-b', `C-n' and `C-p', just as they normally are in other modes. The commands for motion by months and years work like those for weeks, but move a larger distance. The month commands `M-}' and `M-{' move forward or backward by an entire month's time. The year commands `C-x ]' and `C-x [' move forward or backward a whole year. The easiest way to remember these commands is to consider months and years analogous to paragraphs and pages of text, respectively. But the commands themselves are not quite analogous. The ordinary Emacs paragraph commands move to the beginning or end of a paragraph, whereas these month and year commands move by an entire month or an entire year, which usually involves skipping across the end of a month or year. All these commands accept a numeric argument as a repeat count. For convenience, the digit keys and the minus sign specify numeric arguments in Calendar mode even without the Meta modifier. For example, `100 C-f' moves point 100 days forward from its present location.  File: emacs, Node: Move to Beginning or End, Next: Specified Dates, Prev: Calendar Unit Motion, Up: Calendar Motion 26.1.2 Beginning or End of Week, Month or Year ---------------------------------------------- A week (or month, or year) is not just a quantity of days; we think of weeks (months, years) as starting on particular dates. So Calendar mode provides commands to move to the beginning or end of a week, month or year: `C-a' Move point to start of week (`calendar-beginning-of-week'). `C-e' Move point to end of week (`calendar-end-of-week'). `M-a' Move point to start of month (`calendar-beginning-of-month'). `M-e' Move point to end of month (`calendar-end-of-month'). `M-<' Move point to start of year (`calendar-beginning-of-year'). `M->' Move point to end of year (`calendar-end-of-year'). These commands also take numeric arguments as repeat counts, with the repeat count indicating how many weeks, months, or years to move backward or forward. By default, weeks begin on Sunday. To make them begin on Monday instead, set the variable `calendar-week-start-day' to 1.  File: emacs, Node: Specified Dates, Prev: Move to Beginning or End, Up: Calendar Motion 26.1.3 Specified Dates ---------------------- Calendar mode provides commands for moving to a particular date specified in various ways. `g d' Move point to specified date (`calendar-goto-date'). `o' Center calendar around specified month (`calendar-other-month'). `.' Move point to today's date (`calendar-goto-today'). `g d' (`calendar-goto-date') prompts for a year, a month, and a day of the month, and then moves to that date. Because the calendar includes all dates from the beginning of the current era, you must type the year in its entirety; that is, type `1990', not `90'. `o' (`calendar-other-month') prompts for a month and year, then centers the three-month calendar around that month. You can return to today's date with `.' (`calendar-goto-today').  File: emacs, Node: Scroll Calendar, Next: Counting Days, Prev: Calendar Motion, Up: Calendar/Diary 26.2 Scrolling in the Calendar ============================== The calendar display scrolls automatically through time when you move out of the visible portion. You can also scroll it manually. Imagine that the calendar window contains a long strip of paper with the months on it. Scrolling it means moving the strip so that new months become visible in the window. `C-x <' Scroll calendar one month forward (`scroll-calendar-left'). `C-x >' Scroll calendar one month backward (`scroll-calendar-right'). `C-v' `' Scroll calendar three months forward (`scroll-calendar-left-three-months'). `M-v' `' Scroll calendar three months backward (`scroll-calendar-right-three-months'). The most basic calendar scroll commands scroll by one month at a time. This means that there are two months of overlap between the display before the command and the display after. `C-x <' scrolls the calendar contents one month to the left; that is, it moves the display forward in time. `C-x >' scrolls the contents to the right, which moves backwards in time. The commands `C-v' and `M-v' scroll the calendar by an entire "screenful"--three months--in analogy with the usual meaning of these commands. `C-v' makes later dates visible and `M-v' makes earlier dates visible. These commands take a numeric argument as a repeat count; in particular, since `C-u' multiplies the next command by four, typing `C-u C-v' scrolls the calendar forward by a year and typing `C-u M-v' scrolls the calendar backward by a year. The function keys and are equivalent to `C-v' and `M-v', just as they are in other modes.  File: emacs, Node: Counting Days, Next: General Calendar, Prev: Scroll Calendar, Up: Calendar/Diary 26.3 Counting Days ================== `M-=' Display the number of days in the current region (`calendar-count-days-region'). To determine the number of days in the region, type `M-=' (`calendar-count-days-region'). The numbers of days printed is _inclusive_; that is, it includes the days specified by mark and point.  File: emacs, Node: General Calendar, Next: TeX Calendar, Prev: Counting Days, Up: Calendar/Diary 26.4 Miscellaneous Calendar Commands ==================================== `p d' Display day-in-year (`calendar-print-day-of-year'). `C-c C-l' Regenerate the calendar window (`redraw-calendar'). `SPC' Scroll the next window (`scroll-other-window'). `q' Exit from calendar (`exit-calendar'). To print the number of days elapsed since the start of the year, or the number of days remaining in the year, type the `p d' command (`calendar-print-day-of-year'). This displays both of those numbers in the echo area. The number of days elapsed includes the selected date. The number of days remaining does not include that date. If the calendar window text gets corrupted, type `C-c C-l' (`redraw-calendar') to redraw it. (This can only happen if you use non-Calendar-mode editing commands.) In Calendar mode, you can use `SPC' (`scroll-other-window') to scroll the other window. This is handy when you display a list of holidays or diary entries in another window. To exit from the calendar, type `q' (`exit-calendar'). This buries all buffers related to the calendar, selecting other buffers. (If a frame contains a dedicated calendar window, exiting from the calendar iconifies that frame.)  File: emacs, Node: TeX Calendar, Next: Holidays, Prev: General Calendar, Up: Calendar/Diary 26.5 TeX Calendar ================= The Calendar TeX commands produce a buffer of LaTeX code that prints as a calendar. Depending on the command you use, the printed calendar covers the day, week, month or year that point is in. `t m' Generate a one-month calendar (`cal-tex-cursor-month'). `t M' Generate a sideways-printing one-month calendar (`cal-tex-cursor-month-landscape'). `t d' Generate a one-day calendar (`cal-tex-cursor-day'). `t w 1' Generate a one-page calendar for one week (`cal-tex-cursor-week'). `t w 2' Generate a two-page calendar for one week (`cal-tex-cursor-week2'). `t w 3' Generate an ISO-style calendar for one week (`cal-tex-cursor-week-iso'). `t w 4' Generate a calendar for one Monday-starting week (`cal-tex-cursor-week-monday'). `t f w' Generate a Filofax-style two-weeks-at-a-glance calendar (`cal-tex-cursor-filofax-2week'). `t f W' Generate a Filofax-style one-week-at-a-glance calendar (`cal-tex-cursor-filofax-week'). `t y' Generate a calendar for one year (`cal-tex-cursor-year'). `t Y' Generate a sideways-printing calendar for one year (`cal-tex-cursor-landscape-year'). `t f y' Generate a Filofax-style calendar for one year (`cal-tex-cursor-filofax-year'). Some of these commands print the calendar sideways (in "landscape mode"), so it can be wider than it is long. Some of them use Filofax paper size (3.75in x 6.75in). All of these commands accept a prefix argument which specifies how many days, weeks, months or years to print (starting always with the selected one). If the variable `cal-tex-holidays' is non-`nil' (the default), then the printed calendars show the holidays in `calendar-holidays'. If the variable `cal-tex-diary' is non-`nil' (the default is `nil'), diary entries are included also (in weekly and monthly calendars only).  File: emacs, Node: Holidays, Next: Sunrise/Sunset, Prev: TeX Calendar, Up: Calendar/Diary 26.6 Holidays ============= The Emacs calendar knows about all major and many minor holidays, and can display them. `h' Display holidays for the selected date (`calendar-cursor-holidays'). `Mouse-2 Holidays' Display any holidays for the date you click on. `x' Mark holidays in the calendar window (`mark-calendar-holidays'). `u' Unmark calendar window (`calendar-unmark'). `a' List all holidays for the displayed three months in another window (`list-calendar-holidays'). `M-x holidays' List all holidays for three months around today's date in another window. To see if any holidays fall on a given date, position point on that date in the calendar window and use the `h' command. Alternatively, click on that date with `Mouse-2' and then choose `Holidays' from the menu that appears. Either way, this displays the holidays for that date, in the echo area if they fit there, otherwise in a separate window. To view the distribution of holidays for all the dates shown in the calendar, use the `x' command. This displays the dates that are holidays in a different face (or places a `*' after these dates, if display with multiple faces is not available). The command applies both to the currently visible months and to other months that subsequently become visible by scrolling. To turn marking off and erase the current marks, type `u', which also erases any diary marks (*note Diary::). To get even more detailed information, use the `a' command, which displays a separate buffer containing a list of all holidays in the current three-month range. You can use in the calendar window to scroll that list. The command `M-x holidays' displays the list of holidays for the current month and the preceding and succeeding months; this works even if you don't have a calendar window. If you want the list of holidays centered around a different month, use `C-u M-x holidays', which prompts for the month and year. The holidays known to Emacs include American holidays and the major Christian, Jewish, and Islamic holidays; also the solstices and equinoxes. The dates used by Emacs for holidays are based on _current practice_, not historical fact. Historically, for instance, the start of daylight savings time and even its existence have varied from year to year, but present American law mandates that daylight savings time begins on the first Sunday in April. In an American locale, Emacs always uses this definition, even though it is wrong for some prior years.  File: emacs, Node: Sunrise/Sunset, Next: Lunar Phases, Prev: Holidays, Up: Calendar/Diary 26.7 Times of Sunrise and Sunset ================================ Special calendar commands can tell you, to within a minute or two, the times of sunrise and sunset for any date. `S' Display times of sunrise and sunset for the selected date (`calendar-sunrise-sunset'). `Mouse-2 Sunrise/Sunset' Display times of sunrise and sunset for the date you click on. `M-x sunrise-sunset' Display times of sunrise and sunset for today's date. `C-u M-x sunrise-sunset' Display times of sunrise and sunset for a specified date. Within the calendar, to display the _local times_ of sunrise and sunset in the echo area, move point to the date you want, and type `S'. Alternatively, click `Mouse-2' on the date, then choose `Sunrise/Sunset' from the menu that appears. The command `M-x sunrise-sunset' is available outside the calendar to display this information for today's date or a specified date. To specify a date other than today, use `C-u M-x sunrise-sunset', which prompts for the year, month, and day. You can display the times of sunrise and sunset for any location and any date with `C-u C-u M-x sunrise-sunset'. This asks you for a longitude, latitude, number of minutes difference from Coordinated Universal Time, and date, and then tells you the times of sunrise and sunset for that location on that date. Because the times of sunrise and sunset depend on the location on earth, you need to tell Emacs your latitude, longitude, and location name before using these commands. Here is an example of what to set: (setq calendar-latitude 40.1) (setq calendar-longitude -88.2) (setq calendar-location-name "Urbana, IL") Use one decimal place in the values of `calendar-latitude' and `calendar-longitude'. Your time zone also affects the local time of sunrise and sunset. Emacs usually gets time zone information from the operating system, but if these values are not what you want (or if the operating system does not supply them), you must set them yourself. Here is an example: (setq calendar-time-zone -360) (setq calendar-standard-time-zone-name "CST") (setq calendar-daylight-time-zone-name "CDT") The value of `calendar-time-zone' is the number of minutes difference between your local standard time and Coordinated Universal Time (Greenwich time). The values of `calendar-standard-time-zone-name' and `calendar-daylight-time-zone-name' are the abbreviations used in your time zone. Emacs displays the times of sunrise and sunset _corrected for daylight savings time_. *Note Daylight Savings::, for how daylight savings time is determined. As a user, you might find it convenient to set the calendar location variables for your usual physical location in your `.emacs' file. And when you install Emacs on a machine, you can create a `default.el' file which sets them properly for the typical location of most users of that machine. *Note Init File::.  File: emacs, Node: Lunar Phases, Next: Other Calendars, Prev: Sunrise/Sunset, Up: Calendar/Diary 26.8 Phases of the Moon ======================= These calendar commands display the dates and times of the phases of the moon (new moon, first quarter, full moon, last quarter). This feature is useful for debugging problems that "depend on the phase of the moon." `M' Display the dates and times for all the quarters of the moon for the three-month period shown (`calendar-phases-of-moon'). `M-x phases-of-moon' Display dates and times of the quarters of the moon for three months around today's date. Within the calendar, use the `M' command to display a separate buffer of the phases of the moon for the current three-month range. The dates and times listed are accurate to within a few minutes. Outside the calendar, use the command `M-x phases-of-moon' to display the list of the phases of the moon for the current month and the preceding and succeeding months. For information about a different month, use `C-u M-x phases-of-moon', which prompts for the month and year. The dates and times given for the phases of the moon are given in local time (corrected for daylight savings, when appropriate); but if the variable `calendar-time-zone' is void, Coordinated Universal Time (the Greenwich time zone) is used. *Note Daylight Savings::.  File: emacs, Node: Other Calendars, Next: Diary, Prev: Lunar Phases, Up: Calendar/Diary 26.9 Conversion To and From Other Calendars =========================================== The Emacs calendar displayed is _always_ the Gregorian calendar, sometimes called the "new style" calendar, which is used in most of the world today. However, this calendar did not exist before the sixteenth century and was not widely used before the eighteenth century; it did not fully displace the Julian calendar and gain universal acceptance until the early twentieth century. The Emacs calendar can display any month since January, year 1 of the current era, but the calendar displayed is the Gregorian, even for a date at which the Gregorian calendar did not exist. While Emacs cannot display other calendars, it can convert dates to and from several other calendars. * Menu: * Calendar Systems:: The calendars Emacs understands (aside from Gregorian). * To Other Calendar:: Converting the selected date to various calendars. * From Other Calendar:: Moving to a date specified in another calendar. * Mayan Calendar:: Moving to a date specified in a Mayan calendar.  File: emacs, Node: Calendar Systems, Next: To Other Calendar, Up: Other Calendars 26.9.1 Supported Calendar Systems --------------------------------- The ISO commercial calendar is used largely in Europe. The Julian calendar, named after Julius Caesar, was the one used in Europe throughout medieval times, and in many countries up until the nineteenth century. Astronomers use a simple counting of days elapsed since noon, Monday, January 1, 4713 B.C. on the Julian calendar. The number of days elapsed is called the _Julian day number_ or the _Astronomical day number_. The Hebrew calendar is used by tradition in the Jewish religion. The Emacs calendar program uses the Hebrew calendar to determine the dates of Jewish holidays. Hebrew calendar dates begin and end at sunset. The Islamic calendar is used in many predominantly Islamic countries. Emacs uses it to determine the dates of Islamic holidays. There is no universal agreement in the Islamic world about the calendar; Emacs uses a widely accepted version, but the precise dates of Islamic holidays often depend on proclamation by religious authorities, not on calculations. As a consequence, the actual dates of observance can vary slightly from the dates computed by Emacs. Islamic calendar dates begin and end at sunset. The French Revolutionary calendar was created by the Jacobins after the 1789 revolution, to represent a more secular and nature-based view of the annual cycle, and to install a 10-day week in a rationalization measure similar to the metric system. The French government officially abandoned this calendar at the end of 1805. The Maya of Central America used three separate, overlapping calendar systems, the _long count_, the _tzolkin_, and the _haab_. Emacs knows about all three of these calendars. Experts dispute the exact correlation between the Mayan calendar and our calendar; Emacs uses the Goodman-Martinez-Thompson correlation in its calculations. The Copts use a calendar based on the ancient Egyptian solar calendar. Their calendar consists of twelve 30-day months followed by an extra five day period. Once every fourth year they add a leap day to this extra period to make it six days. The Ethiopic calendar is identical in structure, but has different year numbers and month names. The Persians use a solar calendar based on a design of Omar Khayyam. Their calendar consists of twelve months of which the first six have 31 days, the next five have 30 days, and the last has 29 in ordinary years and 30 in leap years. Leap years occur in a complicated pattern every four or five years. The Chinese calendar is a complicated system of lunar months arranged into solar years. The years go in cycles of sixty, each year containing either twelve months in an ordinary year or thirteen months in a leap year; each month has either 29 or 30 days. Years, ordinary months, and days are named by combining one of ten "celestial stems" with one of twelve "terrestrial branches" for a total of sixty names that are repeated in a cycle of sixty.  File: emacs, Node: To Other Calendar, Next: From Other Calendar, Prev: Calendar Systems, Up: Other Calendars 26.9.2 Converting To Other Calendars ------------------------------------ The following commands describe the selected date (the date at point) in various other calendar systems: `Mouse-2 Other Calendars' Display the date that you click on, expressed in various other calendars. `p c' Display ISO commercial calendar equivalent for selected day (`calendar-print-iso-date'). `p j' Display Julian date for selected day (`calendar-print-julian-date'). `p a' Display astronomical (Julian) day number for selected day (`calendar-print-astro-day-number'). `p h' Display Hebrew date for selected day (`calendar-print-hebrew-date'). `p i' Display Islamic date for selected day (`calendar-print-islamic-date'). `p f' Display French Revolutionary date for selected day (`calendar-print-french-date'). `p C' Display Chinese date for selected day (`calendar-print-chinese-date'). `p k' Display Coptic date for selected day (`calendar-print-coptic-date'). `p e' Display Ethiopic date for selected day (`calendar-print-ethiopic-date'). `p p' Display Persian date for selected day (`calendar-print-persian-date'). `p m' Display Mayan date for selected day (`calendar-print-mayan-date'). If you are using X, the easiest way to translate a date into other calendars is to click on it with `Mouse-2', then choose `Other Calendars' from the menu that appears. This displays the equivalent forms of the date in all the calendars Emacs understands, in the form of a menu. (Choosing an alternative from this menu doesn't actually do anything--the menu is used only for display.) Put point on the desired date of the Gregorian calendar, then type the appropriate keys. The `p' is a mnemonic for "print" since Emacs "prints" the equivalent date in the echo area.  File: emacs, Node: From Other Calendar, Next: Mayan Calendar, Prev: To Other Calendar, Up: Other Calendars 26.9.3 Converting From Other Calendars -------------------------------------- You can use the other supported calendars to specify a date to move to. This section describes the commands for doing this using calendars other than Mayan; for the Mayan calendar, see the following section. `g c' Move to a date specified in the ISO commercial calendar (`calendar-goto-iso-date'). `g j' Move to a date specified in the Julian calendar (`calendar-goto-julian-date'). `g a' Move to a date specified in astronomical (Julian) day number (`calendar-goto-astro-day-number'). `g h' Move to a date specified in the Hebrew calendar (`calendar-goto-hebrew-date'). `g i' Move to a date specified in the Islamic calendar (`calendar-goto-islamic-date'). `g f' Move to a date specified in the French Revolutionary calendar (`calendar-goto-french-date'). `g C' Move to a date specified in the Chinese calendar (`calendar-goto-chinese-date'). `g p' Move to a date specified in the Persian calendar (`calendar-goto-persian-date'). `g k' Move to a date specified in the Coptic calendar (`calendar-goto-coptic-date'). `g e' Move to a date specified in the Ethiopic calendar (`calendar-goto-ethiopic-date'). These commands ask you for a date on the other calendar, move point to the Gregorian calendar date equivalent to that date, and display the other calendar's date in the echo area. Emacs uses strict completion (*note Completion::) whenever it asks you to type a month name, so you don't have to worry about the spelling of Hebrew, Islamic, or French names. One common question concerning the Hebrew calendar is the computation of the anniversary of a date of death, called a "yahrzeit." The Emacs calendar includes a facility for such calculations. If you are in the calendar, the command `M-x list-yahrzeit-dates' asks you for a range of years and then displays a list of the yahrzeit dates for those years for the date given by point. If you are not in the calendar, this command first asks you for the date of death and the range of years, and then displays the list of yahrzeit dates.  File: emacs, Node: Mayan Calendar, Prev: From Other Calendar, Up: Other Calendars 26.9.4 Converting from the Mayan Calendar ----------------------------------------- Here are the commands to select dates based on the Mayan calendar: `g m l' Move to a date specified by the long count calendar (`calendar-goto-mayan-long-count-date'). `g m n t' Move to the next occurrence of a place in the tzolkin calendar (`calendar-next-tzolkin-date'). `g m p t' Move to the previous occurrence of a place in the tzolkin calendar (`calendar-previous-tzolkin-date'). `g m n h' Move to the next occurrence of a place in the haab calendar (`calendar-next-haab-date'). `g m p h' Move to the previous occurrence of a place in the haab calendar (`calendar-previous-haab-date'). `g m n c' Move to the next occurrence of a place in the calendar round (`calendar-next-calendar-round-date'). `g m p c' Move to the previous occurrence of a place in the calendar round (`calendar-previous-calendar-round-date'). To understand these commands, you need to understand the Mayan calendars. The "long count" is a counting of days with these units: 1 kin = 1 day 1 uinal = 20 kin 1 tun = 18 uinal 1 katun = 20 tun 1 baktun = 20 katun Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long count dates as early as 7.17.18.13.1, but no earlier. When you use the `g m l' command, type the Mayan long count date with the baktun, katun, tun, uinal, and kin separated by periods. The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of independent cycles of 13 and 20 days. Since this cycle repeats endlessly, Emacs provides commands to move backward and forward to the previous or next point in the cycle. Type `g m p t' to go to the previous tzolkin date; Emacs asks you for a tzolkin date and moves point to the previous occurrence of that date. Similarly, type `g m n t' to go to the next occurrence of a tzolkin date. The Mayan haab calendar is a cycle of 365 days arranged as 18 months of 20 days each, followed a 5-day monthless period. Like the tzolkin cycle, this cycle repeats endlessly, and there are commands to move backward and forward to the previous or next point in the cycle. Type `g m p h' to go to the previous haab date; Emacs asks you for a haab date and moves point to the previous occurrence of that date. Similarly, type `g m n h' to go to the next occurrence of a haab date. The Maya also used the combination of the tzolkin date and the haab date. This combination is a cycle of about 52 years called a _calendar round_. If you type `g m p c', Emacs asks you for both a haab and a tzolkin date and then moves point to the previous occurrence of that combination. Use `g m n c' to move point to the next occurrence of a combination. These commands signal an error if the haab/tzolkin date combination you have typed is impossible. Emacs uses strict completion (*note Strict Completion::) whenever it asks you to type a Mayan name, so you don't have to worry about spelling.  File: emacs, Node: Diary, Next: Appointments, Prev: Other Calendars, Up: Calendar/Diary 26.10 The Diary =============== The Emacs diary keeps track of appointments or other events on a daily basis, in conjunction with the calendar. To use the diary feature, you must first create a "diary file" containing a list of events and their dates. Then Emacs can automatically pick out and display the events for today, for the immediate future, or for any specified date. By default, Emacs uses `~/diary' as the diary file. This is the same file that the `calendar' utility uses. A sample `~/diary' file is: 12/22/1988 Twentieth wedding anniversary!! &1/1. Happy New Year! 10/22 Ruth's birthday. * 21, *: Payday Tuesday--weekly meeting with grad students at 10am Supowit, Shen, Bitner, and Kapoor to attend. 1/13/89 Friday the thirteenth!! &thu 4pm squash game with Lloyd. mar 16 Dad's birthday April 15, 1989 Income tax due. &* 15 time cards due. This example uses extra spaces to align the event descriptions of most of the entries. Such formatting is purely a matter of taste. Although you probably will start by creating a diary manually, Emacs provides a number of commands to let you view, add, and change diary entries. * Menu: * Diary Commands:: Viewing diary entries and associated calendar dates. * Format of Diary File:: Entering events in your diary. * Date Formats:: Various ways you can specify dates. * Adding to Diary:: Commands to create diary entries. * Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc.  File: emacs, Node: Diary Commands, Next: Format of Diary File, Up: Diary 26.10.1 Commands Displaying Diary Entries ----------------------------------------- Once you have created a `~/diary' file, you can use the calendar to view it. You can also view today's events outside of Calendar mode. `d' Display all diary entries for the selected date (`view-diary-entries'). `Mouse-2 Diary' Display all diary entries for the date you click on. `s' Display the entire diary file (`show-all-diary-entries'). `m' Mark all visible dates that have diary entries (`mark-diary-entries'). `u' Unmark the calendar window (`calendar-unmark'). `M-x print-diary-entries' Print hard copy of the diary display as it appears. `M-x diary' Display all diary entries for today's date. Displaying the diary entries with `d' shows in a separate window the diary entries for the selected date in the calendar. The mode line of the new window shows the date of the diary entries and any holidays that fall on that date. If you specify a numeric argument with `d', it shows all the diary entries for that many successive days. Thus, `2 d' displays all the entries for the selected date and for the following day. Another way to display the diary entries for a date is to click `Mouse-2' on the date, and then choose `Diary' from the menu that appears. To get a broader view of which days are mentioned in the diary, use the `m' command. This displays the dates that have diary entries fall in a different face (or places a `+' after these dates, if display with multiple faces is not available). The command applies both to the currently visible months and to other months that subsequently become visible by scrolling. To turn marking off and erase the current marks, type `u', which also turns off holiday marks (*note Holidays::). To see the full diary file, rather than just some of the entries, use the `s' command. Display of selected diary entries uses the selective display feature to hide entries that don't apply. This is the same feature that Outline mode uses to show part of an outline (*note Outline Mode::). The diary buffer as you see it is an illusion, so simply printing the buffer does not print what you see on your screen. There is a special command to print hard copy of the diary buffer _as it appears_; this command is `M-x print-diary-entries'. It sends the data directly to the printer. You can customize it like `lpr-region' (*note Hardcopy::). The command `M-x diary' displays the diary entries for the current date, independently of the calendar display, and optionally for the next few days as well; the variable `number-of-diary-entries' specifies how many days to include. *Note Calendar/Diary Options: (elisp)Calendar/Diary Options. If you put `(diary)' in your `.emacs' file, this automatically displays a window with the day's diary entries, when you enter Emacs. The mode line of the displayed window shows the date and any holidays that fall on that date.  File: emacs, Node: Format of Diary File, Next: Date Formats, Prev: Diary Commands, Up: Diary 26.10.2 The Diary File ---------------------- Your "diary file" is a file that records events associated with particular dates. The name of the diary file is specified by the variable `diary-file'; `~/diary' is the default. The `calendar' utility program supports a subset of the format allowed by the Emacs diary facilities, so you can use that utility to view the diary file, with reasonable results aside from the entries it cannot understand. Each entry in the diary file describes one event and consists of one or more lines. An entry always begins with a date specification at the left margin. The rest of the entry is simply text to describe the event. If the entry has more than one line, then the lines after the first must begin with whitespace to indicate they continue a previous entry. Lines that do not begin with valid dates and do not continue a preceding entry are ignored. You can inhibit the marking of certain diary entries in the calendar window; to do this, insert an ampersand (`&') at the beginning of the entry, before the date. This has no effect on display of the entry in the diary window; it affects only marks on dates in the calendar window. Nonmarking entries are especially useful for generic entries that would otherwise mark many different dates. If the first line of a diary entry consists only of the date or day name with no following blanks or punctuation, then the diary window display doesn't include that line; only the continuation lines appear. For example, this entry: 02/11/1989 Bill B. visits Princeton today 2pm Cognitive Studies Committee meeting 2:30-5:30 Liz at Lawrenceville 4:00pm Dentist appt 7:30pm Dinner at George's 8:00-10:00pm concert appears in the diary window without the date line at the beginning. This style of entry looks neater when you display just a single day's entries, but can cause confusion if you ask for more than one day's entries. You can edit the diary entries as they appear in the window, but it is important to remember that the buffer displayed contains the _entire_ diary file, with portions of it concealed from view. This means, for instance, that the `C-f' (`forward-char') command can put point at what appears to be the end of the line, but what is in reality the middle of some concealed line. _Be careful when editing the diary entries!_ Inserting additional lines or adding/deleting characters in the middle of a visible line cannot cause problems, but editing at the end of a line may not do what you expect. Deleting a line may delete other invisible entries that follow it. Before editing the diary, it is best to display the entire file with `s' (`show-all-diary-entries').  File: emacs, Node: Date Formats, Next: Adding to Diary, Prev: Format of Diary File, Up: Diary 26.10.3 Date Formats -------------------- Here are some sample diary entries, illustrating different ways of formatting a date. The examples all show dates in American order (month, day, year), but Calendar mode supports European order (day, month, year) as an option. 4/20/93 Switch-over to new tabulation system apr. 25 Start tabulating annual results 4/30 Results for April are due */25 Monthly cycle finishes Friday Don't leave without backing up files The first entry appears only once, on April 20, 1993. The second and third appear every year on the specified dates, and the fourth uses a wildcard (asterisk) for the month, so it appears on the 25th of every month. The final entry appears every week on Friday. You can use just numbers to express a date, as in `MONTH/DAY' or `MONTH/DAY/YEAR'. This must be followed by a nondigit. In the date itself, MONTH and DAY are numbers of one or two digits. The optional YEAR is also a number, and may be abbreviated to the last two digits; that is, you can use `11/12/1989' or `11/12/89'. Dates can also have the form `MONTHNAME DAY' or `MONTHNAME DAY, YEAR', where the month's name can be spelled in full or abbreviated to three characters (with or without a period). Case is not significant. A date may be "generic"; that is, partially unspecified. Then the entry applies to all dates that match the specification. If the date does not contain a year, it is generic and applies to any year. Alternatively, MONTH, DAY, or YEAR can be a `*'; this matches any month, day, or year, respectively. Thus, a diary entry `3/*/*' matches any day in March of any year; so does `march *'. If you prefer the European style of writing dates--in which the day comes before the month--type `M-x european-calendar' while in the calendar, or set the variable `european-calendar-style' to `t' _before_ using any calendar or diary command. This mode interprets all dates in the diary in the European manner, and also uses European style for displaying diary dates. (Note that there is no comma after the MONTHNAME in the European style.) To go back to the (default) American style of writing dates, type `M-x american-calendar'. You can use the name of a day of the week as a generic date which applies to any date falling on that day of the week. You can abbreviate the day of the week to three letters (with or without a period) or spell it in full; case is not significant.  File: emacs, Node: Adding to Diary, Next: Special Diary Entries, Prev: Date Formats, Up: Diary 26.10.4 Commands to Add to the Diary ------------------------------------ While in the calendar, there are several commands to create diary entries: `i d' Add a diary entry for the selected date (`insert-diary-entry'). `i w' Add a diary entry for the selected day of the week (`insert-weekly-diary-entry'). `i m' Add a diary entry for the selected day of the month (`insert-monthly-diary-entry'). `i y' Add a diary entry for the selected day of the year (`insert-yearly-diary-entry'). You can make a diary entry for a specific date by selecting that date in the calendar window and typing the `i d' command. This command displays the end of your diary file in another window and inserts the date; you can then type the rest of the diary entry. If you want to make a diary entry that applies to a specific day of the week, select that day of the week (any occurrence will do) and type `i w'. This inserts the day-of-week as a generic date; you can then type the rest of the diary entry. You can make a monthly diary entry in the same fashion. Select the day of the month, use the `i m' command, and type rest of the entry. Similarly, you can insert a yearly diary entry with the `i y' command. All of the above commands make marking diary entries by default. To make a nonmarking diary entry, give a numeric argument to the command. For example, `C-u i w' makes a nonmarking weekly diary entry. When you modify the diary file, be sure to save the file before exiting Emacs.  File: emacs, Node: Special Diary Entries, Prev: Adding to Diary, Up: Diary 26.10.5 Special Diary Entries ----------------------------- In addition to entries based on calendar dates, the diary file can contain "sexp entries" for regular events such as anniversaries. These entries are based on Lisp expressions (sexps) that Emacs evaluates as it scans the diary file. Instead of a date, a sexp entry contains `%%' followed by a Lisp expression which must begin and end with parentheses. The Lisp expression determines which dates the entry applies to. Calendar mode provides commands to insert certain commonly used sexp entries: `i a' Add an anniversary diary entry for the selected date (`insert-anniversary-diary-entry'). `i b' Add a block diary entry for the current region (`insert-block-diary-entry'). `i c' Add a cyclic diary entry starting at the date (`insert-cyclic-diary-entry'). If you want to make a diary entry that applies to the anniversary of a specific date, move point to that date and use the `i a' command. This displays the end of your diary file in another window and inserts the anniversary description; you can then type the rest of the diary entry. The entry looks like this: %%(diary-anniversary 10 31 1948) Arthur's birthday This entry applies to October 31 in any year after 1948; `10 31 1948' specifies the date. (If you are using the European calendar style, the month and day are interchanged.) The reason this expression requires a beginning year is that advanced diary functions can use it to calculate the number of elapsed years. A "block" diary entry applies to a specified range of consecutive dates. Here is a block diary entry that applies to all dates from June 24, 1990 through July 10, 1990: %%(diary-block 6 24 1990 7 10 1990) Vacation The `6 24 1990' indicates the starting date and the `7 10 1990' indicates the stopping date. (Again, if you are using the European calendar style, the month and day are interchanged.) To insert a block entry, place point and the mark on the two dates that begin and end the range, and type `i b'. This command displays the end of your diary file in another window and inserts the block description; you can then type the diary entry. "Cyclic" diary entries repeat after a fixed interval of days. To create one, select the starting date and use the `i c' command. The command prompts for the length of interval, then inserts the entry, which looks like this: %%(diary-cyclic 50 3 1 1990) Renew medication This entry applies to March 1, 1990 and every 50th day following; `3 1 1990' specifies the starting date. (If you are using the European calendar style, the month and day are interchanged.) All three of these commands make marking diary entries. To insert a nonmarking entry, give a numeric argument to the command. For example, `C-u i a' makes a nonmarking anniversary diary entry. Marking sexp diary entries in the calendar is _extremely_ time-consuming, since every date visible in the calendar window must be individually checked. So it's a good idea to make sexp diary entries nonmarking (with `&') when possible. Another sophisticated kind of sexp entry, a "floating" diary entry, specifies a regularly-occurring event by offsets specified in days, weeks, and months. It is comparable to a crontab entry interpreted by the `cron' utility. Here is a nonmarking, floating diary entry that applies to the last Thursday in November: &%%(diary-float 11 4 -1) American Thanksgiving The 11 specifies November (the eleventh month), the 4 specifies Thursday (the fourth day of the week, where Sunday is numbered zero), and the -1 specifies "last" (1 would mean "first", 2 would mean "second", -2 would mean "second-to-last", and so on). The month can be a single month or a list of months. Thus you could change the 11 above to `'(1 2 3)' and have the entry apply to the last Thursday of January, February, and March. If the month is `t', the entry applies to all months of the year. Most generally, sexp diary entries can perform arbitrary computations to determine when they apply. *Note Sexp Diary Entries: (elisp)Sexp Diary Entries.  File: emacs, Node: Appointments, Next: Daylight Savings, Prev: Diary, Up: Calendar/Diary 26.11 Appointments ================== If you have a diary entry for an appointment, and that diary entry begins with a recognizable time of day, Emacs can warn you, several minutes beforehand, that that appointment is pending. Emacs alerts you to the appointment by displaying a message in the mode line. To enable appointment notification, you must enable the time display feature of Emacs, `M-x display-time' (*note Mode Line::). You must also add the function `appt-make-list' to the `diary-hook', like this: (add-hook 'diary-hook 'appt-make-list) With these preparations done, when you display the diary (either with the `d' command in the calendar window or with the `M-x diary' command), it sets up an appointment list of all the diary entries found with recognizable times of day, and reminds you just before each of them. For example, suppose the diary file contains these lines: Monday 9:30am Coffee break 12:00pm Lunch Then on Mondays, after you have displayed the diary, you will be reminded at 9:20am about your coffee break and at 11:50am about lunch. You can write times in am/pm style (with `12:00am' standing for midnight and `12:00pm' standing for noon), or 24-hour European/military style. You need not be consistent; your diary file can have a mixture of the two styles. Emacs updates the appointments list automatically just after midnight. This also displays the next day's diary entries in the diary buffer, unless you set `appt-display-diary' to `nil'. You can also use the appointment notification facility like an alarm clock. The command `M-x appt-add' adds entries to the appointment list without affecting your diary file. You delete entries from the appointment list with `M-x appt-delete'. You can turn off the appointment notification feature at any time by setting `appt-issue-message' to `nil'.  File: emacs, Node: Daylight Savings, Prev: Appointments, Up: Calendar/Diary 26.12 Daylight Savings Time =========================== Emacs understands the difference between standard time and daylight savings time--the times given for sunrise, sunset, solstices, equinoxes, and the phases of the moon take that into account. The rules for daylight savings time vary from place to place and have also varied historically from year to year. To do the job properly, Emacs needs to know which rules to use. Some operating systems keep track of the rules that apply to the place where you are; on these systems, Emacs gets the information it needs from the system automatically. If some or all of this information is missing, Emacs fills in the gaps with the rules currently used in Cambridge, Massachusetts. If the resulting rules are not what you want, you can tell Emacs the rules to use by setting certain variables. These values should be Lisp expressions that refer to the variable `year', and evaluate to the Gregorian date on which daylight savings time starts or (respectively) ends, in the form of a list `(MONTH DAY YEAR)'. The values should be `nil' if your area does not use daylight savings time. Emacs uses these expressions to determine the starting date of daylight savings time for the holiday list and for correcting times of day in the solar and lunar calculations. The values for Cambridge, Massachusetts are as follows: (calendar-nth-named-day 1 0 4 year) (calendar-nth-named-day -1 0 10 year) That is, the first 0th day (Sunday) of the fourth month (April) in the year specified by `year', and the last Sunday of the tenth month (October) of that year. If daylight savings time were changed to start on October 1, you would set `calendar-daylight-savings-starts' to this: (list 10 1 year) If there is no daylight savings time at your location, or if you want all times in standard time, set `calendar-daylight-savings-starts' and `calendar-daylight-savings-ends' to `nil'. The variable `calendar-daylight-time-offset' specifies the difference between daylight savings time and standard time, measured in minutes. The value for Cambridge, Massachusetts is 60. The two variables `calendar-daylight-savings-starts-time' and `calendar-daylight-savings-ends-time' specify the number of minutes after midnight local time when the transition to and from daylight savings time should occur. For Cambridge, Massachusetts both variables' values are 120.  File: emacs, Node: Gnus, Next: Shell, Prev: Calendar/Diary, Up: Top 26.13 Gnus ========== Gnus is an Emacs package primarily designed for reading and posting Usenet news. It can also be used to read and respond to messages from a number of other sources--mail, remote directories, digests, and so on. Here we introduce Gnus and describe several basic features. For full details, see *Note Gnus: (gnus)Top. To start Gnus, type `M-x gnus '. * Menu: * Buffers of Gnus:: The group, summary and article buffers. * Gnus Startup:: What you should know about starting Gnus. * Summary of Gnus:: A short description of the basic Gnus commands.  File: emacs, Node: Buffers of Gnus, Next: Gnus Startup, Up: Gnus 26.13.1 Gnus Buffers -------------------- As opposed to most normal Emacs packages, Gnus uses a number of different buffers to display information and to receive commands. The three buffers users spend most of their time in are the "group buffer", the "summary buffer" and the "article buffer". The "group buffer" contains a list of groups. This is the first buffer Gnus displays when it starts up. It normally displays only the groups to which you subscribe and that contain unread articles. Use this buffer to select a specific group. The "summary buffer" lists one line for each article in a single group. By default, the author, the subject and the line number are displayed for each article, but this is customizable, like most aspects of Gnus display. The summary buffer is created when you select a group in the group buffer, and is killed when you exit the group. Use this buffer to select an article. The "article buffer" displays the article. In normal Gnus usage, you don't select this buffer--all useful article-oriented commands work in the summary buffer. But you can select the article buffer, and execute all Gnus commands from that buffer, if you want to.  File: emacs, Node: Gnus Startup, Next: Summary of Gnus, Prev: Buffers of Gnus, Up: Gnus 26.13.2 When Gnus Starts Up --------------------------- At startup, Gnus reads your `.newsrc' news initialization file and attempts to communicate with the local news server, which is a repository of news articles. The news server need not be the same computer you are logged in on. If you start Gnus and connect to the server, but do not see any newsgroups listed in the group buffer, type `L' or `A k' to get a listing of all the groups. Then type `u' to toggle subscription to groups. The first time you start Gnus, Gnus subscribes you to a few selected groups. All other groups start out as "killed groups" for you; you can list them with `A k'. All new groups that subsequently come to exist at the news server become "zombie groups" for you; type `A z' to list them. You can subscribe to a group shown in these lists using the `u' command. When you quit Gnus with `q', it automatically records in your `.newsrc' and `.newsrc.eld' initialization files the subscribed or unsubscribed status of all groups. You should normally not edit these files manually, but you may if you know how.  File: emacs, Node: Summary of Gnus, Prev: Gnus Startup, Up: Gnus 26.13.3 Summary of Gnus Commands -------------------------------- Reading news is a two step process: 1. Choose a group in the group buffer. 2. Select articles from the summary buffer. Each article selected is displayed in the article buffer in a large window, below the summary buffer in its small window. Each Gnus buffer has its own special commands; however, the meanings of any given key in the various Gnus buffers are usually analogous, even if not identical. Here are commands for the group and summary buffers: `q' In the group buffer, update your `.newsrc' initialization file and quit Gnus. In the summary buffer, exit the current group and return to the group buffer. Thus, typing `q' twice quits Gnus. `L' In the group buffer, list all the groups available on your news server (except those you have killed). This may be a long list! `l' In the group buffer, list only the groups to which you subscribe and which contain unread articles. `u' In the group buffer, unsubscribe from (or subscribe to) the group listed in the line that point is on. When you quit Gnus by typing `q', Gnus lists in your `.newsrc' file which groups you have subscribed to. The next time you start Gnus, you won't see this group, because Gnus normally displays only subscribed-to groups. `C-k' In the group buffer, "kill" the current line's group--don't even list it in `.newsrc' from now on. This affects future Gnus sessions as well as the present session. When you quit Gnus by typing `q', Gnus writes information in the file `.newsrc' describing all newsgroups except those you have "killed." `' In the group buffer, select the group on the line under the cursor and display the first unread article in that group. In the summary buffer, * Select the article on the line under the cursor if none is selected. * Scroll the text of the selected article (if there is one). * Select the next unread article if at the end of the current article. Thus, you can move through all the articles by repeatedly typing . `' In the group buffer, move point to the previous group containing unread articles. In the summary buffer, scroll the text of the article backwards. `n' Move point to the next unread group, or select the next unread article. `p' Move point to the previous unread group, or select the previous unread article. `C-n' `C-p' Move point to the next or previous item, even if it is marked as read. This does not select the article or group on that line. `s' In the summary buffer, do an incremental search of the current text in the article buffer, just as if you switched to the article buffer and typed `C-s'. `M-s REGEXP RET' In the summary buffer, search forward for articles containing a match for REGEXP.  File: emacs, Node: Shell, Next: Emacs Server, Prev: Gnus, Up: Top 26.14 Running Shell Commands from Emacs ======================================= Emacs has commands for passing single command lines to inferior shell processes; it can also run a shell interactively with input and output to an Emacs buffer named `*shell*'. `M-! CMD ' Run the shell command line CMD and display the output (`shell-command'). `M-| CMD ' Run the shell command line CMD with region contents as input; optionally replace the region with the output (`shell-command-on-region'). `M-x shell' Run a subshell with input and output through an Emacs buffer. You can then give commands interactively. * Menu: * Single Shell:: How to run one shell command and return. * Interactive Shell:: Permanent shell taking input via Emacs. * Shell Mode:: Special Emacs commands used with permanent shell. * History: Shell History. Repeating previous commands in a shell buffer. * Options: Shell Options. Options for customizing Shell mode. * Remote Host:: Connecting to another computer.  File: emacs, Node: Single Shell, Next: Interactive Shell, Up: Shell 26.14.1 Single Shell Commands ----------------------------- `M-!' (`shell-command') reads a line of text using the minibuffer and executes it as a shell command in a subshell made just for that command. Standard input for the command comes from the null device. If the shell command produces any output, the output goes into an Emacs buffer named `*Shell Command Output*', which is displayed in another window but not selected. A numeric argument, as in `M-1 M-!', directs this command to insert any output into the current buffer. In that case, point is left before the output and the mark is set after the output. If the shell command line ends in `&', it runs asynchronously. `M-|' (`shell-command-on-region') is like `M-!' but passes the contents of the region as the standard input to the shell command, instead of no input. If a numeric argument is used, meaning insert the output in the current buffer, then the old region is deleted first and the output replaces it as the contents of the region. Both `M-!' and `M-|' use `shell-file-name' to specify the shell to use. This variable is initialized based on your `SHELL' environment variable when Emacs is started. If the file name does not specify a directory, the directories in the list `exec-path' are searched; this list is initialized based on the environment variable `PATH' when Emacs is started. Your `.emacs' file can override either or both of these default initializations. Both `M-!' and `M-|' wait for the shell command to complete. To stop waiting, type `C-g' to quit; that terminates the shell command with the signal `SIGINT'--the same signal that `C-c' normally generates in the shell. Emacs waits until the command actually terminates. If the shell command doesn't stop (because it ignores the `SIGINT' signal), type `C-g' again; this sends the command a `SIGKILL' signal which is impossible to ignore.  File: emacs, Node: Interactive Shell, Next: Shell Mode, Prev: Single Shell, Up: Shell 26.14.2 Interactive Inferior Shell ---------------------------------- To run a subshell interactively, putting its typescript in an Emacs buffer, use `M-x shell'. This creates (or reuses) a buffer named `*shell*' and runs a subshell with input coming from and output going to that buffer. That is to say, any "terminal output" from the subshell goes into the buffer, advancing point, and any "terminal input" for the subshell comes from text in the buffer. To give input to the subshell, go to the end of the buffer and type the input, terminated by . Emacs does not wait for the subshell to do anything. You can switch windows or buffers and edit them while the shell is waiting, or while it is running a command. Output from the subshell waits until Emacs has time to process it; this happens whenever Emacs is waiting for keyboard input or for time to elapse. To make multiple subshells, rename the buffer `*shell*' to something different using `M-x rename-uniquely'. Then type `M-x shell' again to create a new buffer `*shell*' with its own subshell. If you rename this buffer as well, you can create a third one, and so on. All the subshells run independently and in parallel. The file name used to load the subshell is the value of the variable `explicit-shell-file-name', if that is non-`nil'. Otherwise, the environment variable `ESHELL' is used, or the environment variable `SHELL' if there is no `ESHELL'. If the file name specified is relative, the directories in the list `exec-path' are searched; this list is initialized based on the environment variable `PATH' when Emacs is started. Your `.emacs' file can override either or both of these default initializations. As soon as the subshell is started, it is sent as input the contents of the file `~/.emacs_SHELLNAME', if that file exists, where SHELLNAME is the name of the file that the shell was loaded from. For example, if you use bash, the file sent to it is `~/.emacs_bash'. `cd', `pushd' and `popd' commands given to the inferior shell are watched by Emacs so it can keep the `*shell*' buffer's default directory the same as the shell's working directory. These commands are recognized syntactically by examining lines of input that are sent. If you use aliases for these commands, you can tell Emacs to recognize them also. For example, if the value of the variable `shell-pushd-regexp' matches the beginning of a shell command line, that line is regarded as a `pushd' command. Change this variable when you add aliases for `pushd'. Likewise, `shell-popd-regexp' and `shell-cd-regexp' are used to recognize commands with the meaning of `popd' and `cd'. These commands are recognized only at the beginning of a shell command line. If Emacs gets an error while trying to handle what it believes is a `cd', `pushd' or `popd' command, it runs the hook `shell-set-directory-error-hook' (*note Hooks::). If Emacs does not properly track changes in the current directory of the subshell, use the command `M-x dirs' to ask the shell what its current directory is. This command works for shells that support the most common command syntax; it may not work for unusual shells.  File: emacs, Node: Shell Mode, Next: Shell History, Prev: Interactive Shell, Up: Shell 26.14.3 Shell Mode ------------------ Shell buffers use Shell mode, which defines several special keys attached to the `C-c' prefix. They are chosen to resemble the usual editing and job control characters present in shells that are not under Emacs, except that you must type `C-c' first. Here is a complete list of the special key bindings of Shell mode: `' At end of buffer send line as input; otherwise, copy current line to end of buffer and send it (`comint-send-input'). When a line is copied, any text at the beginning of the line that matches the variable `shell-prompt-pattern' is left out; this variable's value should be a regexp string that matches the prompts that your shell uses. `' Complete the command name or file name before point in the shell buffer (`comint-dynamic-complete'). also completes history references (*note History References::) and environment variable names. The variable `shell-completion-fignore' specifies a list of file name extensions to ignore in Shell mode completion. The default setting ignores file names ending in `~', `#' or `%'. Other related Comint modes use the variable `comint-completion-fignore' instead. `M-?' Display temporarily a list of the possible completions of the file name before point in the shell buffer (`comint-dynamic-list-filename-completions'). `C-d' Either delete a character or send EOF (`comint-delchar-or-maybe-eof'). Typed at the end of the shell buffer, `C-d' sends EOF to the subshell. Typed at any other position in the buffer, `C-d' deletes a character as usual. `C-c C-a' Move to the beginning of the line, but after the prompt if any (`comint-bol'). `C-c C-u' Kill all text pending at end of buffer to be sent as input (`comint-kill-input'). `C-c C-w' Kill a word before point (`backward-kill-word'). `C-c C-c' Interrupt the shell or its current subjob if any (`comint-interrupt-subjob'). `C-c C-z' Stop the shell or its current subjob if any (`comint-stop-subjob'). `C-c C-\' Send quit signal to the shell or its current subjob if any (`comint-quit-subjob'). `C-c C-o' Kill the last batch of output from a shell command (`comint-kill-output'). This is useful if a shell command spews out lots of output that just gets in the way. `C-c C-r' `C-M-l' Scroll to display the beginning of the last batch of output at the top of the window; also move the cursor there (`comint-show-output'). `C-c C-e' Scroll to put the end of the buffer at the bottom of the window (`comint-show-maximum-output'). `C-c C-f' Move forward across one shell command, but not beyond the current line (`shell-forward-command'). The variable `shell-command-regexp' specifies how to recognize the end of a command. `C-c C-b' Move backward across one shell command, but not beyond the current line (`shell-backward-command'). `C-c C-l' Display the buffer's history of shell commands in another window (`comint-dynamic-list-input-ring'). `M-x dirs' Ask the shell what its current directory is, so that Emacs can agree with the shell. `M-x send-invisible TEXT ' Send TEXT as input to the shell, after reading it without echoing. This is useful when a shell command runs a program that asks for a password. Alternatively, you can arrange for Emacs to notice password prompts and turn off echoing for them, as follows: (add-hook 'comint-output-filter-functions 'comint-watch-for-password-prompt) `M-x comint-continue-subjob' Continue the shell process. This is useful if you accidentally suspend the shell process.(1) `M-x comint-strip-ctrl-m' Discard all control-m characters from the current group of shell output. The most convenient way to use this command is to make it run automatically when you get output from the subshell. To do that, evaluate this Lisp expression: (add-hook 'comint-output-filter-functions 'comint-strip-ctrl-m) `M-x comint-truncate-buffer' This command truncates the shell buffer to a certain maximum number of lines, specified by the variable `comint-buffer-maximum-size'. Here's how to do this automatically each time you get output from the subshell: (add-hook 'comint-output-filter-functions 'comint-truncate-buffer) Shell mode also customizes the paragraph commands so that only shell prompts start new paragraphs. Thus, a paragraph consists of an input command plus the output that follows it in the buffer. Shell mode is a derivative of Comint mode, a general purpose mode for communicating with interactive subprocesses. Most of the features of Shell mode actually come from Comint mode, as you can see from the command names listed above. The special features of Shell mode in particular include the choice of regular expression for detecting prompts, the directory tracking feature, and a few user commands. Other Emacs features that use variants of Comint mode include GUD (*note Debuggers::) and `M-x run-lisp' (*note External Lisp::). You can use `M-x comint-run' to execute any program of your choice in a subprocess using unmodified Comint mode--without the specializations of Shell mode. ---------- Footnotes ---------- (1) You should not suspend the shell process. Suspending a subjob of the shell is a completely different matter--that is normal practice, but you must use the shell to continue the subjob; this command won't do it.  File: emacs, Node: Shell History, Next: Shell Options, Prev: Shell Mode, Up: Shell 26.14.4 Shell Command History ----------------------------- Shell buffers support three ways of repeating earlier commands. You can use the same keys used in the minibuffer; these work much as they do in the minibuffer, inserting text from prior commands while point remains always at the end of the buffer. You can move through the buffer to previous inputs in their original place, then resubmit them or copy them to the end. Or you can use a `!'-style history reference. * Menu: * Ring: Shell Ring. Fetching commands from the history list. * Copy: Shell History Copying. Moving to a command and then copying it. * History References:: Expanding `!'-style history references.  File: emacs, Node: Shell Ring, Next: Shell History Copying, Up: Shell History 26.14.4.1 Shell History Ring ............................ `M-p' Fetch the next earlier old shell command. `M-n' Fetch the next later old shell command. `M-r REGEXP ' `M-s REGEXP ' Search backwards or forwards for old shell commands that match REGEXP. Shell buffers provide a history of previously entered shell commands. To reuse shell commands from the history, use the editing commands `M-p', `M-n', `M-r' and `M-s'. These work just like the minibuffer history commands except that they operate on the text at the end of the shell buffer, where you would normally insert text to send to the shell. `M-p' fetches an earlier shell command to the end of the shell buffer. Successive use of `M-p' fetches successively earlier shell commands, each replacing any text that was already present as potential shell input. `M-n' does likewise except that it finds successively more recent shell commands from the buffer. The history search commands `M-r' and `M-s' read a regular expression and search through the history for a matching command. Aside from the choice of which command to fetch, they work just like `M-p' and `M-r'. If you enter an empty regexp, these commands reuse the same regexp used last time. When you find the previous input you want, you can resubmit it by typing , or you can edit it first and then resubmit it if you wish. These commands get the text of previous shell commands from a special history list, not from the shell buffer itself. Thus, editing the shell buffer, or even killing large parts of it, does not affect the history that these commands access. Some shells store their command histories in files so that you can refer to previous commands from previous shell sessions. Emacs reads the command history file for your chosen shell, to initialize its own command history. The file name is `~/.bash_history' for bash, `~/.sh_history' for ksh, and `~/.history' for other shells.  File: emacs, Node: Shell History Copying, Next: History References, Prev: Shell Ring, Up: Shell History 26.14.4.2 Shell History Copying ............................... `C-c C-p' Move point to the previous prompt (`comint-previous-prompt'). `C-c C-n' Move point to the following prompt (`comint-next-prompt'). `C-c ' Copy the input command which point is in, inserting the copy at the end of the buffer (`comint-copy-old-input'). This is useful if you move point back to a previous command. After you copy the command, you can submit the copy as input with . If you wish, you can edit the copy before resubmitting it. Moving to a previous input and then copying it with `C-c ' produces the same results--the same buffer contents--that you would get by using `M-p' enough times to fetch that previous input from the history list. However, `C-c ' copies the text from the buffer, which can be different from what is in the history list if you edit the input text in the buffer after it has been sent.  File: emacs, Node: History References, Prev: Shell History Copying, Up: Shell History 26.14.4.3 Shell History References .................................. Various shells including csh and bash support "history references" that begin with `!' and `^'. Shell mode can understand these constructs and perform the history substitution for you. If you insert a history reference and type , this searches the input history for a matching command, performs substitution if necessary, and places the result in the buffer in place of the history reference. For example, you can fetch the most recent command beginning with `mv' with `! m v '. You can edit the command if you wish, and then resubmit the command to the shell by typing . History references take effect only following a shell prompt. The variable `shell-prompt-pattern' specifies how to recognize a shell prompt. Comint modes in general use the variable `comint-prompt-regexp' to specify how to find a prompt; Shell mode uses `shell-prompt-pattern' to set up the local value of `comint-prompt-regexp'. Shell mode can optionally expand history references in the buffer when you send them to the shell. To request this, set the variable `comint-input-autoexpand' to `input'. You can make perform history expansion by binding to the command `comint-magic-space'.  File: emacs, Node: Shell Options, Next: Remote Host, Prev: Shell History, Up: Shell 26.14.5 Shell Mode Options -------------------------- If the variable `comint-scroll-to-bottom-on-input' is non-`nil', insertion and yank commands scroll the selected window to the bottom before inserting. If `comint-scroll-show-maximum-output' is non-`nil', then scrolling due to arrival of output tries to place the last line of text at the bottom line of the window, so as to show as much useful text as possible. (This mimics the scrolling behavior of many terminals.) The default is `nil'. By setting `comint-scroll-to-bottom-on-output', you can opt for having point jump to the end of the buffer whenever output arrives--no matter where in the buffer point was before. If the value is `this', point jumps in the selected window. If the value is `all', point jumps in each window that shows the comint buffer. If the value is `other', point jumps in all nonselected windows that show the current buffer. The default value is `nil', which means point does not jump to the end. The variable `comint-input-ignoredups' controls whether successive identical inputs are stored in the input history. A non-`nil' value means to omit an input that is the same as the previous input. The default is `nil', which means to store each input even if it is equal to the previous input. Three variables customize file name completion. The variable `comint-completion-addsuffix' controls whether completion inserts a space or a slash to indicate a fully completed file or directory name (non-`nil' means do insert a space or slash). `comint-completion-recexact', if non-`nil', directs to choose the shortest possible completion if the usual Emacs completion algorithm cannot add even a single character. `comint-completion-autolist', if non-`nil', says to list all the possible completions whenever completion is not exact. The command `comint-dynamic-complete-variable' does variable name completion using the environment variables as set within Emacs. The variables controlling file name completion apply to variable name completion too. This command is normally available through the menu bar. Command completion normally considers only executable files. If you set `shell-command-execonly' to `nil', it considers nonexecutable files as well. You can configure the behavior of `pushd'. Variables control whether `pushd' behaves like `cd' if no argument is given (`shell-pushd-tohome'), pop rather than rotate with a numeric argument (`shell-pushd-dextract'), and only add directories to the directory stack if they are not already on it (`shell-pushd-dunique'). The values you choose should match the underlying shell, of course.  File: emacs, Node: Remote Host, Prev: Shell Options, Up: Shell 26.14.6 Remote Host Shell ------------------------- Emacs provides two commands for logging in to another computer and communicating with it through an Emacs buffer. `M-x telnet HOSTNAME ' Set up a Telnet connection to the computer named HOSTNAME. `M-x rlogin HOSTNAME ' Set up an Rlogin connection to the computer named HOSTNAME. Use `M-x telnet' to set up a Telnet connection to another computer. (Telnet is the standard Internet protocol for remote login.) It reads the host name of the other computer as an argument with the minibuffer. Once the connection is established, talking to the other computer works like talking to a subshell: you can edit input with the usual Emacs commands, and send it a line at a time by typing . The output is inserted in the Telnet buffer interspersed with the input. Use `M-x rlogin' to set up an Rlogin connection. Rlogin is another remote login communication protocol, essentially much like the Telnet protocol but incompatible with it, and supported only by certain systems. Rlogin's advantages are that you can arrange not to have to give your user name and password when communicating between two machines you frequently use, and that you can make an 8-bit-clean connection. (To do that in Emacs, set `rlogin-explicit-args' to `("-8")' before you run Rlogin.) `M-x rlogin' sets up the default file directory of the Emacs buffer to access the remote host via FTP (*note File Names::), and it tracks the shell commands that change the current directory just like Shell mode. There are two ways of doing directory tracking in an Rlogin buffer--either with remote directory names `/HOST:DIR/' or with local names (that works if the "remote" machine shares file systems with your machine of origin). You can use the command `rlogin-directory-tracking-mode' to switch modes. No argument means use remote directory names, a positive argument means use local names, and a negative argument means turn off directory tracking.  File: emacs, Node: Emacs Server, Next: Hardcopy, Prev: Shell, Up: Top 26.15 Using Emacs as a Server ============================= Various programs such as `mail' can invoke your choice of editor to edit a particular piece of text, such as a message that you are sending. By convention, most of these programs use the environment variable `EDITOR' to specify which editor to run. If you set `EDITOR' to `emacs', they invoke Emacs--but in an inconvenient fashion, by starting a new, separate Emacs process. This is inconvenient because it takes time and because the new Emacs process doesn't share the buffers in the existing Emacs process. You can arrange to use your existing Emacs process as the editor for programs like `mail' by using the Emacs client and Emacs server programs. Here is how. First, the preparation. Within Emacs, call the function `server-start'. (Your `.emacs' file can do this automatically if you add the expression `(server-start)' to it.) Then, outside Emacs, set the `EDITOR' environment variable to `emacsclient'. (Note that some programs use a different environment variable; for example, to make TeX use `emacsclient', you should set the `TEXEDIT' environment variable to `emacsclient +%d %s'.) Then, whenever any program invokes your specified `EDITOR' program, the effect is to send a message to your principal Emacs telling it to visit a file. (That's what the program `emacsclient' does.) Emacs displays the buffer immediately and you can immediately begin editing it. When you've finished editing that buffer, type `C-x #' (`server-edit'). This saves the file and sends a message back to the `emacsclient' program telling it to exit. The programs that use `EDITOR' wait for the "editor" (actually, `emacsclient') to exit. `C-x #' also checks for other pending external requests to edit various files, and selects the next such file. You can switch to a server buffer manually if you wish; you don't have to arrive at it with `C-x #'. But `C-x #' is the only way to say that you are "finished" with one. If you set the variable `server-window' to a window or a frame, `C-x #' displays the server buffer in that window or in that frame. While `mail' or another application is waiting for `emacsclient' to finish, `emacsclient' does not read terminal input. So the terminal that `mail' was using is effectively blocked for the duration. In order to edit with your principal Emacs, you need to be able to use it without using that terminal. There are two ways to do this: * Using a window system, run `mail' and the principal Emacs in two separate windows. While `mail' is waiting for `emacsclient', the window where it was running is blocked, but you can use Emacs by switching windows. * Use Shell mode in Emacs to run the other program such as `mail'; then, `emacsclient' blocks only the subshell under Emacs, and you can still use Emacs to edit the file. Some programs write temporary files for you to edit. After you edit the temporary file, the program reads it back and deletes it. If the Emacs server is later asked to edit the same file name, it should assume this has nothing to do with the previous occasion for that file name. The server accomplishes this by killing the temporary file's buffer when you finish with the file. Use the variable `server-temp-file-regexp' to specify which files are temporary in this sense; its value should be a regular expression that matches file names that are temporary.  File: emacs, Node: Hardcopy, Next: Postscript, Prev: Emacs Server, Up: Top 26.16 Hardcopy Output ===================== The Emacs commands for making hardcopy let you print either an entire buffer or just part of one, either with or without page headers. See also the hardcopy commands of Dired (*note Misc File Ops::) and the diary (*note Diary Commands::). `M-x print-buffer' Print hardcopy of current buffer with page headings containing the file name and page number. `M-x lpr-buffer' Print hardcopy of current buffer without page headings. `M-x print-region' Like `print-buffer' but print only the current region. `M-x lpr-region' Like `lpr-buffer' but print only the current region. The hardcopy commands (aside from the Postscript commands) pass extra switches to the `lpr' program based on the value of the variable `lpr-switches'. Its value should be a list of strings, each string an option starting with `-'. For example, to use a printer named `nearme', set `lpr-switches' like this: (setq lpr-switches '("-Pnearme")) The variable `lpr-command' specifies the name of the printer program to run; the default value depends on your operating system type. On most systems, the default is `"lpr"'. The variable `lpr-headers-switches' similarly specifies the extra switches to use to make page headers. The variable `lpr-add-switches' controls whether to supply `-T' and `-J' options (suitable for `lpr') to the printer program: `nil' means don't add them. `lpr-add-switches' should be `nil' if your printer program is not compatible with `lpr'.  File: emacs, Node: Postscript, Next: Sorting, Prev: Hardcopy, Up: Top 26.17 Postscript Hardcopy ========================= These commands convert buffer contents to Postscript, either printing it or leaving it in another Emacs buffer. `M-x ps-print-buffer' Print hardcopy of the current buffer in Postscript form. `M-x ps-print-region' Print hardcopy of the current region in Postscript form. `M-x ps-print-buffer-with-faces' Print hardcopy of the current buffer in Postscript form, showing the faces used in the text by means of Postscript features. `M-x ps-print-region-with-faces' Print hardcopy of the current region in Postscript form, showing the faces used in the text. `M-x ps-spool-buffer' Generate Postscript for the current buffer text. `M-x ps-spool-region' Generate Postscript for the current region. `M-x ps-spool-buffer-with-faces' Generate Postscript for the current buffer, showing the faces used. `M-x ps-spool-region-with-faces' Generate Postscript for the current region, showing the faces used. The Postscript commands, `ps-print-buffer' and `ps-print-region', print buffer contents in Postscript form. One command prints the entire buffer; the other, just the region. The corresponding `-with-faces' commands, `ps-print-buffer-with-faces' and `ps-print-region-with-faces', use Postscript features to show the faces (fonts and colors) in the text properties of the text being printed. If you are using a color display, you can print a buffer of program code with color highlighting by turning on Font-Lock mode in that buffer, and using `ps-print-buffer-with-faces'. All four of the commands above use the variables `ps-lpr-command' and `ps-lpr-switches' to specify how to print the output. `ps-lpr-command' specifies the command name to run, and `ps-lpr-switches' specifies command line options to use. If you don't set these variables yourself, they take their initial values from `lpr-command' and `lpr-switches'. The variable `ps-print-header' controls whether these commands add header lines to each page--set it to `nil' to turn headers off. You can turn off color processing by setting `ps-print-color-p' to `nil'. Many other customization variables for these commands are defined and described in the Lisp file `ps-print.el'. The commands whose names have `spool' instead of `print' generate the Postscript output in an Emacs buffer instead of sending it to the printer.  File: emacs, Node: Sorting, Next: Narrowing, Prev: Postscript, Up: Top 26.18 Sorting Text ================== Emacs provides several commands for sorting text in the buffer. All operate on the contents of the region (the text between point and the mark). They divide the text of the region into many "sort records", identify a "sort key" for each record, and then reorder the records into the order determined by the sort keys. The records are ordered so that their keys are in alphabetical order, or, for numeric sorting, in numeric order. In alphabetic sorting, all upper case letters `A' through `Z' come before lower case `a', in accord with the ASCII character sequence. The various sort commands differ in how they divide the text into sort records and in which part of each record is used as the sort key. Most of the commands make each line a separate sort record, but some commands use paragraphs or pages as sort records. Most of the sort commands use each entire sort record as its own sort key, but some use only a portion of the record as the sort key. `M-x sort-lines' Divide the region into lines, and sort by comparing the entire text of a line. A numeric argument means sort into descending order. `M-x sort-paragraphs' Divide the region into paragraphs, and sort by comparing the entire text of a paragraph (except for leading blank lines). A numeric argument means sort into descending order. `M-x sort-pages' Divide the region into pages, and sort by comparing the entire text of a page (except for leading blank lines). A numeric argument means sort into descending order. `M-x sort-fields' Divide the region into lines, and sort by comparing the contents of one field in each line. Fields are defined as separated by whitespace, so the first run of consecutive non-whitespace characters in a line constitutes field 1, the second such run constitutes field 2, etc. Specify which field to sort by with a numeric argument: 1 to sort by field 1, etc. A negative argument means count fields from the right instead of from the left; thus, minus 1 means sort by the last field. If several lines have identical contents in the field being sorted, they keep same relative order that they had in the original buffer. A negative argument means count fields from the right (from the end of the line). `M-x sort-numeric-fields' Like `M-x sort-fields' except the specified field is converted to an integer for each line, and the numbers are compared. `10' comes before `2' when considered as text, but after it when considered as a number. `M-x sort-columns' Like `M-x sort-fields' except that the text within each line used for comparison comes from a fixed range of columns. See below for an explanation. `M-x reverse-region' Reverse the order of the lines in the region. This is useful for sorting into descending order by fields or columns, since those sort commands do not have a feature for doing that. For example, if the buffer contains this: On systems where clash detection (locking of files being edited) is implemented, Emacs also checks the first time you modify a buffer whether the file has changed on disk since it was last visited or saved. If it has, you are asked to confirm that you want to change the buffer. applying `M-x sort-lines' to the entire buffer produces this: On systems where clash detection (locking of files being edited) is implemented, Emacs also checks the first time you modify a buffer saved. If it has, you are asked to confirm that you want to change the buffer. whether the file has changed on disk since it was last visited or where the upper case `O' sorts before all lower case letters. If you use `C-u 2 M-x sort-fields' instead, you get this: implemented, Emacs also checks the first time you modify a buffer saved. If it has, you are asked to confirm that you want to change the buffer. On systems where clash detection (locking of files being edited) is whether the file has changed on disk since it was last visited or where the sort keys were `Emacs', `If', `buffer', `systems' and `the'. `M-x sort-columns' requires more explanation. You specify the columns by putting point at one of the columns and the mark at the other column. Because this means you cannot put point or the mark at the beginning of the first line to sort, this command uses an unusual definition of `region': all of the line point is in is considered part of the region, and so is all of the line the mark is in, as well as all the lines in between. For example, to sort a table by information found in columns 10 to 15, you could put the mark on column 10 in the first line of the table, and point on column 15 in the last line of the table, and then run `sort-columns'. Equivalently, you could run it with the mark on column 15 in the first line and point on column 10 in the last line. This can be thought of as sorting the rectangle specified by point and the mark, except that the text on each line to the left or right of the rectangle moves along with the text inside the rectangle. *Note Rectangles::. Many of the sort commands ignore case differences when comparing, if `sort-fold-case' is non-`nil'.  File: emacs, Node: Narrowing, Next: Two-Column, Prev: Sorting, Up: Top 26.19 Narrowing =============== "Narrowing" means focusing in on some portion of the buffer, making the rest temporarily inaccessible. The portion which you can still get to is called the "accessible portion". Canceling the narrowing, which makes the entire buffer once again accessible, is called "widening". The amount of narrowing in effect in a buffer at any time is called the buffer's "restriction". Narrowing can make it easier to concentrate on a single subroutine or paragraph by eliminating clutter. It can also be used to restrict the range of operation of a replace command or repeating keyboard macro. `C-x n n' Narrow down to between point and mark (`narrow-to-region'). `C-x n w' Widen to make the entire buffer accessible again (`widen'). `C-x n p' Narrow down to the current page (`narrow-to-page'). 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 accessible part), you can't change it in any way. However, it is not gone, and if you save the file all the inaccessible text will be saved. The word `Narrow' appears in the mode line whenever narrowing is in effect. The primary narrowing command is `C-x n n' (`narrow-to-region'). It sets the current buffer's restrictions so that the text in the current region remains accessible but all text before the region or after the region is inaccessible. Point and mark do not change. Alternatively, use `C-x n p' (`narrow-to-page') to narrow down to the current page. *Note Pages::, for the definition of a page. The way to cancel narrowing is to widen with `C-x n w' (`widen'). This makes all text in the buffer accessible again. You can get information on what part of the buffer you are narrowed down to using the `C-x =' command. *Note Position Info::. Because narrowing can easily confuse users who do not understand it, `narrow-to-region' is normally a disabled command. Attempting to use this command asks for confirmation and gives you the option of enabling it; if you enable the command, confirmation will no longer be required for it. *Note Disabling::.  File: emacs, Node: Two-Column, Next: Editing Binary Files, Prev: Narrowing, Up: Top 26.20 Two-Column Editing ======================== Two-column mode lets you conveniently edit two side-by-side columns of text. It uses two side-by-side windows, each showing its own buffer. There are three ways to enter two-column mode: `f2 2' or `C-x 6 2' Enter two-column mode with the current buffer on the left, and on the right, a buffer whose name is based on the current buffer's name (`2C-two-columns'). If the right-hand buffer doesn't already exist, it starts out empty; the current buffer's contents are not changed. This command is appropriate when the current buffer is empty or contains just one column and you want to add another column. `f2 s' or `C-x 6 s' Split the current buffer, which contains two-column text, into two buffers, and display them side by side (`2C-split'). The current buffer becomes the left-hand buffer, but the text in the right-hand column is moved into the right-hand buffer. The current column specifies the split point. Splitting starts with the current line and continues to the end of the buffer. This command is appropriate when you have a buffer that already contains two-column text, and you wish to separate the columns temporarily. `f2 b BUFFER ' `C-x 6 b BUFFER ' Enter two-column mode using the current buffer as the left-hand buffer, and using buffer BUFFER as the right-hand buffer (`2C-associate-buffer'). `f2 s' or `C-x 6 s' looks for a column separator which is a string that appears on each line between the two columns. You can specify the width of the separator with a numeric argument to `f2 s'; that many characters, before point, constitute the separator string. By default, the width is 1, so the column separator is the character before point. When a line has the separator at the proper place, `f2 s' puts the text after the separator into the right-hand buffer, and deletes the separator. Lines that don't have the column separator at the proper place remain unsplit; they stay in the left-hand buffer, and the right-hand buffer gets an empty line to correspond. (This is the way to write a line which "spans both columns while in two-column mode": write it in the left-hand buffer, and put an empty line in the right-hand buffer.) The command `C-x 6 ' or `f2 ' (`2C-newline') inserts a newline in each of the two buffers at corresponding positions. This is the easiest way to add a new line to the two-column text while editing it in split buffers. When you have edited both buffers as you wish, merge them with `f2 1' or `C-x 6 1' (`2C-merge'). This copies the text from the right-hand buffer as a second column in the other buffer. To go back to two-column editing, use `f2 s'. Use `f2 d' or `C-x 6 d' to disassociate the two buffers, leaving each as it stands (`2C-dissociate'). If the other buffer, the one not current when you type `f2 d', is empty, `f2 d' kills it.  File: emacs, Node: Editing Binary Files, Next: Saving Emacs Sessions, Prev: Two-Column, Up: Top 26.21 Editing Binary Files ========================== There is a special major mode for editing binary files: Hexl mode. To use it, use `M-x hexl-find-file' instead of `C-x C-f' to visit the file. This command converts the file's contents to hexadecimal and lets you edit the translation. When you save the file, it is converted automatically back to binary. You can also use `M-x hexl-mode' to translate an existing buffer into hex. This is useful if you visit a file normally and then discover it is a binary file. Ordinary text characters overwrite in Hexl mode. This is to reduce the risk of accidentally spoiling the alignment of data in the file. There are special commands for insertion. Here is a list of the commands of Hexl mode: `C-M-d' Insert a byte with a code typed in decimal. `C-M-o' Insert a byte with a code typed in octal. `C-M-x' Insert a byte with a code typed in hex. `C-x [' Move to the beginning of a 1k-byte "page". `C-x ]' Move to the end of a 1k-byte "page". `M-g' Move to an address specified in hex. `M-j' Move to an address specified in decimal. `C-c C-c' Leave Hexl mode, going back to the major mode this buffer had before you invoked `hexl-mode'.  File: emacs, Node: Saving Emacs Sessions, Next: Recursive Edit, Prev: Editing Binary Files, Up: Top 26.22 Saving Emacs Sessions =========================== You can use the Desktop library to save the state of Emacs from one session to another. Saving the state means that Emacs starts up with the same set of buffers, major modes, buffer positions, and so on that the previous Emacs session had. To use Desktop, you should first add these lines at the end of your `.emacs' file: (load "desktop") (desktop-load-default) (desktop-read) The first time you save the state of the Emacs session, you must do it manually, with the command `M-x desktop-save'. Once you have done that, exiting Emacs will save the state again--not only the present Emacs session, but also subsequent sessions. You can also save the state at any time, without exiting Emacs, by typing `M-x desktop-save' again. In order for Emacs to recover the state from a previous session, you must start it with the same current directory as you used when you started the previous session. The variable `desktop-files-not-to-save' controls which files are excluded from state saving. Its value is a regular expression that matches the files to exclude. By default, remote (ftp-accessed) files are excluded; this is because visiting them again in the subsequent session would be slow. If you want to include these files in state saving, set `desktop-files-not-to-save' to `"^$"'.  File: emacs, Node: Recursive Edit, Next: Emulation, Prev: Saving Emacs Sessions, Up: Top 26.23 Recursive Editing Levels ============================== A "recursive edit" is a situation in which you are using Emacs commands to perform arbitrary editing while in the middle of another Emacs command. For example, when you type `C-r' inside of a `query-replace', you enter a recursive edit in which you can change the current buffer. On exiting from the recursive edit, you go back to the `query-replace'. "Exiting" the recursive edit means returning to the unfinished command, which continues execution. The command to exit is `C-M-c' (`exit-recursive-edit'). You can also "abort" the recursive edit. This is like exiting, but also quits the unfinished command immediately. Use the command `C-]' (`abort-recursive-edit') to do this. *Note Quitting::. The mode line shows you when you are in a recursive edit by displaying square brackets around the parentheses that always surround the major and minor mode names. Every window's mode line shows this, in the same way, since being in a recursive edit is true of Emacs as a whole rather than any particular window or buffer. It is possible to be in recursive edits within recursive edits. For example, after typing `C-r' in a `query-replace', you may type a command that enters the debugger. This begins a recursive editing level for the debugger, within the recursive editing level for `C-r'. Mode lines display a pair of square brackets for each recursive editing level currently in progress. Exiting the inner recursive edit (such as, with the debugger `c' command) resumes the command running in the next level up. When that command finishes, you can then use `C-M-c' to exit another recursive editing level, and so on. Exiting applies to the innermost level only. Aborting also gets out of only one level of recursive edit; it returns immediately to the command level of the previous recursive edit. If you wish, you can then abort the next recursive editing level. Alternatively, the command `M-x top-level' aborts all levels of recursive edits, returning immediately to the top level command reader. The text being edited inside the recursive edit need not be the same text that you were editing at top level. It depends on what the recursive edit is for. If the command that invokes the recursive edit selects a different buffer first, that is the buffer you will edit recursively. In any case, you can switch buffers within the recursive edit in the normal manner (as long as the buffer-switching keys have not been rebound). You could probably do all the rest of your editing inside the recursive edit, visiting files and all. But this could have surprising effects (such as stack overflow) from time to time. So remember to exit or abort the recursive edit when you no longer need it. In general, we try to minimize the use of recursive editing levels in GNU Emacs. This is because they constrain you to "go back" in a particular order-from the innermost level toward the top level. When possible, we present different activities in separate buffers so that you can switch between them as you please. Some commands switch to a new major mode which provides a command to switch back. These approaches give you more flexibility to go back to unfinished tasks in the order you choose.  File: emacs, Node: Emulation, Next: Dissociated Press, Prev: Recursive Edit, Up: Top 26.24 Emulation =============== GNU Emacs can be programmed to emulate (more or less) most other editors. Standard facilities can emulate these: EDT (DEC VMS editor) Turn on EDT emulation with `M-x edt-emulation-on'. `M-x edt-emulation-off' restores normal Emacs command bindings. Most of the EDT emulation commands are keypad keys, and most standard Emacs key bindings are still available. The EDT emulation rebindings are done in the global keymap, so there is no problem switching buffers or major modes while in EDT emulation. vi (Berkeley editor) Viper is the newest emulator for vi. It implements several levels of emulation; level 1 is closest to vi itself, while level 5 departs somewhat from strict emulation to take advantage of the capabilities of Emacs. To invoke Viper, type `M-x viper-mode'; it will guide you the rest of the way and ask for the emulation level. vi (another emulator) `M-x vi-mode' enters a major mode that replaces the previously established major mode. All of the vi commands that, in real vi, enter "input" mode are programmed instead to return to the previous major mode. Thus, ordinary Emacs serves as vi's "input" mode. Because vi emulation works through major modes, it does not work to switch buffers during emulation. Return to normal Emacs first. If you plan to use vi emulation much, you probably want to bind a key to the `vi-mode' command. vi (alternate emulator) `M-x vip-mode' invokes another vi emulator, said to resemble real vi more thoroughly than `M-x vi-mode'. "Input" mode in this emulator is changed from ordinary Emacs so you can use to go back to emulated vi command mode. To get from emulated vi command mode back to ordinary Emacs, type `C-z'. This emulation does not work through major modes, and it is possible to switch buffers in various ways within the emulator. It is not so necessary to assign a key to the command `vip-mode' as it is with `vi-mode' because terminating insert mode does not use it. For full information, see the long comment at the beginning of the source file, which is `lisp/vip.el' in the Emacs distribution.  File: emacs, Node: Dissociated Press, Next: Amusements, Prev: Emulation, Up: Top 26.25 Dissociated Press ======================= `M-x dissociated-press' is a command for scrambling a file of text either word by word or character by character. Starting from a buffer of straight English, it produces extremely amusing output. The input comes from the current Emacs buffer. Dissociated Press writes its output in a buffer named `*Dissociation*', and redisplays that buffer after every couple of lines (approximately) so you can read the output as it comes out. Dissociated Press asks every so often whether to continue generating output. Answer `n' to stop it. You can also stop at any time by typing `C-g'. The dissociation output remains in the `*Dissociation*' buffer for you to copy elsewhere if you wish. Dissociated Press operates by jumping at random from one point in the buffer to another. In order to produce plausible output rather than gibberish, it insists on a certain amount of overlap between the end of one run of consecutive words or characters and the start of the next. That is, if it has just printed out `president' and then decides to jump to a different point in the file, it might spot the `ent' in `pentagon' and continue from there, producing `presidentagon'.(1) Long sample texts produce the best results. A positive argument to `M-x dissociated-press' tells it to operate character by character, and specifies the number of overlap characters. A negative argument tells it to operate word by word and specifies the number of overlap words. In this mode, whole words are treated as the elements to be permuted, rather than characters. No argument is equivalent to an argument of two. For your againformation, the output goes only into the buffer `*Dissociation*'. The buffer you start with is not changed. Dissociated Press produces nearly the same results as a Markov chain based on a frequency table constructed from the sample text. It is, however, an independent, ignoriginal invention. Dissociated Press techniquitously copies several consecutive characters from the sample between random choices, whereas a Markov chain would choose randomly for each word or character. This makes for more plausible sounding results, and runs faster. It is a mustatement that too much use of Dissociated Press can be a developediment to your real work. Sometimes to the point of outragedy. And keep dissociwords out of your documentation, if you want it to be well userenced and properbose. Have fun. Your buggestions are welcome. ---------- Footnotes ---------- (1) This dissociword actually appeared during the Vietnam War, when it was very appropriate.  File: emacs, Node: Amusements, Next: Customization, Prev: Dissociated Press, Up: Top 26.26 Other Amusements ====================== If you are a little bit bored, you can try `M-x hanoi'. If you are considerably bored, give it a numeric argument. If you are very very bored, try an argument of 9. Sit back and watch. If you want a little more personal involvement, try `M-x gomoku', which plays the game Go Moku with you. `M-x blackbox' and `M-x mpuz' are two kinds of puzzles. `blackbox' challenges you to determine the location of objects inside a box by tomography. `mpuz' displays a multiplication puzzle with letters standing for digits in a code that you must guess--to guess a value, type a letter and then the digit you think it stands for. `M-x dunnet' runs an adventure-style exploration game, which is a bigger sort of puzzle. When you are frustrated, try the famous Eliza program. Just do `M-x doctor'. End each input by typing `RET' twice. When you are feeling strange, type `M-x yow'.  File: emacs, Node: Customization, Next: Quitting, Prev: Amusements, Up: Top 27 Customization **************** This chapter talks about various topics relevant to adapting the behavior of Emacs in minor ways. See `The Emacs Lisp Reference Manual' for how to make more far-reaching changes. All kinds of customization affect only the particular Emacs session that you do them in. They are completely lost when you kill the Emacs session, and have no effect on other Emacs sessions you may run at the same time or later. The only way an Emacs session can affect anything outside of it is by writing a file; in particular, the only way to make a customization `permanent' is to put something in your `.emacs' file or other appropriate file to do the customization in each session. *Note Init File::. * Menu: * Minor Modes:: Each minor mode is one feature you can turn on independently of any others. * Variables:: Many Emacs commands examine Emacs variables to decide what to do; by setting variables, you can control their functioning. * Keyboard Macros:: A keyboard macro records a sequence of keystrokes to be replayed with a single command. * Key Bindings:: The keymaps say what command each key runs. By changing them, you can "redefine keys". * Keyboard Translations:: If your keyboard passes an undesired code for a key, you can tell Emacs to substitute another code. * Syntax:: The syntax table controls how words and expressions are parsed. * Init File:: How to write common customizations in the `.emacs' file.  File: emacs, Node: Minor Modes, Next: Variables, Up: Customization 27.1 Minor Modes ================ Minor modes are optional features which you can turn on or off. For example, Auto Fill mode is a minor mode in which breaks lines between words as you type. All the minor modes are independent of each other and of the selected major mode. Most minor modes say in the mode line when they are on; for example, `Fill' in the mode line means that Auto Fill mode is on. Append `-mode' to the name of a minor mode to get the name of a command function that turns the mode on or off. Thus, the command to enable or disable Auto Fill mode is called `M-x auto-fill-mode'. These commands are usually invoked with `M-x', but you can bind keys to them if you wish. With no argument, the function turns the mode on if it was off and off if it was on. This is known as "toggling". A positive argument always turns the mode on, and an explicit zero argument or a negative argument always turns it off. Enabling or disabling some minor modes applies only to the current buffer; each buffer is independent of the other buffers. Therefore, you can enable the mode in particular buffers and disable it in others. The per-buffer minor modes include Auto Fill mode, Auto Save mode, Font-Lock mode, ISO Accents mode, Outline minor mode, Overwrite mode, and Binary Overwrite mode. Auto Fill mode allows you to enter filled text without breaking lines explicitly. Emacs inserts newlines as necessary to prevent lines from becoming too long. *Note Filling::. Auto Save mode causes the contents of a buffer to be saved periodically to reduce the amount of work you can lose in case of a system crash. *Note Auto Save::. Enriched mode enables editing and saving of formatted text. *Note Formatted Text::. Font-Lock mode automatically highlights certain textual units found in programs, such as comments, strings, and function names being defined. This requires a window system that can display multiple fonts. *Note Faces::. ISO Accents mode makes the characters ``', `'', `"', `^', `/' and `~' combine with the following letter, to produce an accented letter in the ISO Latin-1 character set. *Note European Display::. Outline minor mode provides the same facilities as the major mode called Outline mode; but since it is a minor mode instead, you can combine it with any major mode. *Note Outline Mode::. Overwrite mode causes ordinary printing characters to replace existing text instead of shoving it to the right. For example, if point is in front of the `B' in `FOOBAR', then in Overwrite mode typing a `G' changes it to `FOOGAR', instead of producing it `FOOGBAR' as usual. Binary Overwrite mode is a variant of Overwrite mode for editing binary files; it treats newlines and tabs like other characters, so that they overwrite other characters and can be overwritten by them. The following minor modes normally apply to all buffers at once. Since each is enabled or disabled by the value of a variable, you _can_ set them differently for particular buffers, by explicitly making the corresponding variables local in those buffers. *Note Locals::. Abbrev mode allows you to define abbreviations that automatically expand as you type them. For example, `amd' might expand to `abbrev mode'. *Note Abbrevs::, for full information. Icomplete mode displays an indication of available completions when you are in the minibuffer and completion is active. *Note Completion Options::. Line Number mode enables continuous display in the mode line of the line number of point. *Note Mode Line::. Resize-Minibuffer mode makes the minibuffer expand as necessary to hold the text that you put in it. *Note Minibuffer Edit::. Scroll Bar mode gives each window a scroll bar (*note Scroll Bars::). Menu Bar mode gives each frame a menu bar (*note Menu Bars::). Both of these modes are enabled by default when you use the X Window System. In Transient Mark mode, every change in the buffer contents "deactivates" the mark, so that commands that operate on the region will get an error. This means you must either set the mark, or explicitly "reactivate" it, before each command that uses the region. The advantage of Transient Mark mode is that Emacs can display the region highlighted (currently only when using X). *Note Setting Mark::. For most minor modes, the command name is also the name of a variable which directly controls the mode. The mode is enabled whenever this variable's value is non-`nil', and the minor mode command works by setting the variable. For example, the command `outline-minor-mode' works by setting the value of `outline-minor-mode' as a variable; it is this variable that directly turns Outline minor mode on and off. To check whether a given minor mode works this way, use `C-h v' to ask for documentation on the variable name. These minor mode variables provide a good way for Lisp programs to turn minor modes on and off; they are also useful in a file's local variables list. But please think twice before setting minor modes with a local variables list, because most minor modes are matter of user preference--other users editing the same file might not want the same minor modes you prefer.  File: emacs, Node: Variables, Next: Keyboard Macros, Prev: Minor Modes, Up: Customization 27.2 Variables ============== A "variable" is a Lisp symbol which has a value. The symbol's name is also called the name of the variable. A variable name can contain any characters that can appear in a file, but conventionally variable names consist of words separated by hyphens. A variable can have a documentation string which describes what kind of value it should have and how the value will be used. Lisp allows any variable to have any kind of value, but most variables that Emacs uses require a value of a certain type. Often the value should always be a string, or should always be a number. Sometimes we say that a certain feature is turned on if a variable is "non-`nil'," meaning that if the variable's value is `nil', the feature is off, but the feature is on for _any_ other value. The conventional value to use to turn on the feature--since you have to pick one particular value when you set the variable--is `t'. Emacs uses many Lisp variables for internal record keeping, as any Lisp program must, but the most interesting variables for you are the ones that exist for the sake of customization. Emacs does not (usually) change the values of these variables; instead, you set the values, and thereby alter and control the behavior of certain Emacs commands. These variables are called "user options". Most user options are documented in this manual, and appear in the Variable Index (*note Variable Index::). One example of a variable which is a user option is `fill-column', which specifies the position of the right margin (as a number of characters from the left margin) to be used by the fill commands (*note Filling::). * Menu: * Examining:: Examining or setting one variable's value. * Edit Options:: Examining or editing list of all user options' values. * Hooks:: Hook variables let you specify programs for parts of Emacs to run on particular occasions. * Locals:: Per-buffer values of variables. * File Variables:: How files can specify variable values.  File: emacs, Node: Examining, Next: Edit Options, Up: Variables 27.2.1 Examining and Setting Variables -------------------------------------- `C-h v VAR ' Display the value and documentation of variable VAR (`describe-variable'). `M-x set-variable VAR VALUE ' Change the value of variable VAR to VALUE. To examine the value of a single variable, use `C-h v' (`describe-variable'), which reads a variable name using the minibuffer, with completion. It displays both the value and the documentation of the variable. For example, C-h v fill-column displays something like this: fill-column's value is 75 Documentation: *Column beyond which automatic line-wrapping should happen. Automatically becomes buffer-local when set in any fashion. The star at the beginning of the documentation indicates that this variable is a user option. `C-h v' is not restricted to user options; it allows any variable name. The most convenient way to set a specific user option is with `M-x set-variable'. This reads the variable name with the minibuffer (with completion), and then reads a Lisp expression for the new value using the minibuffer a second time. For example, M-x set-variable fill-column 75 sets `fill-column' to 75. `M-x set-variable' is limited to user option variables. You can set any variable with a Lisp expression using the function `setq'. Here's how to use it to set `fill-column': (setq fill-column 75) Setting variables, like all means of customizing Emacs except where otherwise stated, affects only the current Emacs session.  File: emacs, Node: Edit Options, Next: Hooks, Prev: Examining, Up: Variables 27.2.2 Editing Variable Values ------------------------------ These two functions make it easy to display all the Emacs user option variables, and to change some of them if you wish. `M-x list-options' Display a buffer listing names, values and documentation of all options. `M-x edit-options' Change user option values by editing a list of user option variables. `M-x list-options' displays a list of all Emacs option variables, in an Emacs buffer named `*List Options*'. Each user option is shown with its documentation and its current value. Here is what a portion of it might look like: ;; exec-path: ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc") *List of directories to search programs to run in subprocesses. Each element is a string (directory name) or nil (try the default directory). ;; ;; fill-column: 75 *Column beyond which automatic line-wrapping should happen. Automatically becomes buffer-local when set in any fashion. ;; `M-x edit-options' goes one step further and immediately selects the `*List Options*' buffer; this buffer uses the major mode Options mode, which provides commands that allow you to point at a user option variable and change its value: `s' Set the variable point is in or near to a new value read using the minibuffer. `x' Toggle the variable point is in or near: if the value was `nil', it becomes `t'; otherwise it becomes `nil'. `1' Set the variable point is in or near to `t'. `0' Set the variable point is in or near to `nil'. `n' `p' Move to the next or previous user option. Any changes take effect immediately, and last until you exit from Emacs.  File: emacs, Node: Hooks, Next: Locals, Prev: Edit Options, Up: Variables 27.2.3 Hooks ------------ A "hook" is a variable where you can store a function or functions to be called on a particular occasion by an existing program. Emacs provides a number of hooks for the sake of customization. Most of the hooks in Emacs are "normal hooks". These variables contain lists of functions to be called with no arguments. The reason most hooks are normal hooks is so that you can use them in a uniform way. Every variable in Emacs whose name ends in `-hook' is a normal hook. Most major modes run hooks as the last step of initialization. This makes it easy for a user to customize the behavior of the mode, by overriding the local variable assignments already made by the mode. But hooks may also be used in other contexts. For example, the hook `suspend-hook' runs just before Emacs suspends itself (*note Exiting::). The recommended way to add a hook function to a normal hook is by calling `add-hook'. You can use any valid Lisp function as the hook function. For example, here's how to set up a hook to turn on Auto Fill mode when entering Text mode and other modes based on Text mode: (add-hook 'text-mode-hook 'turn-on-auto-fill) The next example shows how to use a hook to customize the indentation of C code. (People often have strong personal preferences for one format compared to another.) Here the hook function is an anonymous lambda expression. (setq my-c-style '((c-comment-only-line-offset . 4) (c-cleanup-list . (scope-operator empty-defun-braces defun-close-semi)) (c-offsets-alist . ((arglist-close . c-lineup-arglist) (substatement-open . 0))))) (add-hook 'c-mode-common-hook (function (lambda () (c-add-style "my-style" my-c-style t)))) It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is "asking for trouble." However, the order is predictable: the most recently added hook functions are executed first.