This is ../info/emacs, produced by makeinfo version 4.8 from emacs.texi.  File: emacs, Node: Check-In, Next: Version Control Undo, Prev: Check-Out, Up: Editing with VC 12.7.3.2 Check-In ................. When you are finished editing the file, type `C-x C-q' again. When used on a file that is checked out, this command checks the file in. But check-in does not start immediately; first, you must enter the "log entry"--a description of the changes in the new version. `C-x C-q' pops up a buffer for you to enter this in. When you are finished typing in the log entry, type `C-c C-c' to terminate it; this is when actual check-in takes place. *Note Log Entries::. With RCS and SCCS, a checked-out file is also "locked", which means it is writable for you, but not for anyone else. As long as you own the lock on the file, nobody else can modify it, and nobody can check in any changes to that particular version. Checking in your changes unlocks the file, so that other users can lock it and modify it. CVS, on the contrary, doesn't have a concept of locking. The working files are always modifiable, allowing concurrent development, with possible conflicts being resolved at check-in time. *Note CVS and VC::. To specify the version number for the new version, type `C-u C-x C-q' to check in a file. Then Emacs asks you for the new version number in the minibuffer. This can be used to create a new "branch" of the file (*note Branches::), or to increment the file's major version number. It is not impossible to lock a file that someone else has locked. If you try to check out a file that is locked, `C-x C-q' asks you whether you want to "steal the lock." If you say yes, the file becomes locked by you, but a message is sent to the person who had formerly locked the file, to inform him of what has happened. The mode line indicates that a file is locked by someone else by displaying the login name of that person, before the version number.  File: emacs, Node: Registering, Next: VC Mode Line, Prev: Version Control Undo, Up: Editing with VC 12.7.3.3 Registering a File for Version Control ............................................... `C-x v i' Register the visited file for version control. You can put any file under version control by simply visiting it, and then typing `C-x v i' (`vc-register'). After `C-x v i', the file is unlocked and read-only. Type `C-x C-q' if you wish to start editing it. When you register the file, Emacs must choose which version control system to use for it. You can specify your choice explicitly by setting `vc-default-back-end' to `RCS', `CVS' or `SCCS'. Otherwise, if there is a subdirectory named `RCS', `SCCS', or `CVS', Emacs uses the corresponding version control system. In the absence of any specification, the default choice is RCS if RCS is installed, otherwise SCCS. After registering a file with CVS, you must subsequently commit the initial version by typing `C-x C-q'. *Note CVS and VC::. The initial version number for a newly registered file is 1.1, by default. To specify a different number, give `C-x v i' a numeric argument; then it reads the initial version number using the minibuffer. If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial comment (much like a log entry) to describe the purpose of this source file.  File: emacs, Node: Version Control Undo, Next: Registering, Prev: Check-In, Up: Editing with VC 12.7.3.4 Undoing Version Control Actions ........................................ `C-x v u' Revert the buffer and the file to the last checked in version. `C-x v c' Remove the last-entered change from the master for the visited file. This undoes your last checkin. If you want to discard your current set of changes and revert to the last version checked in, use `C-x v u' (`vc-revert-buffer'). This cancels your last check-out, leaving the file unlocked. If you want to make a different set of changes, you must first check the file out again. `C-x v u' requires confirmation, unless it sees that you haven't made any changes since the last checked-in version. `C-x v u' is also the command to use to unlock a file if you lock it and then decide not to change it. You can cancel a change after checking it in, with `C-x v c' (`vc-cancel-version'). This command discards all record of the most recent checked in version. `C-x v c' also offers to revert your work file and buffer to the previous version (the one that precedes the version that is deleted). If you say `no', then VC keeps your changes in the buffer and locks the file. The no-revert option is useful when you have checked in a change and then discover a trivial error in it; you can cancel the erroneous check-in, fix the error, and check the file in again. When `C-x v c' does not revert the buffer, it unexpands all version control headers in the buffer instead (*note Version Headers::). This is because the buffer no longer corresponds to any existing version. If you check it in again, the checkin process will expand the headers properly for the new version number. However, it is impossible to unexpand the RCS `$Log$' header automatically. If you use that header feature, you have to unexpand it by hand--by deleting the entry for the version that you just canceled. Be careful when invoking `C-x v c', as it is easy to throw away a lot of work with it. To help you be careful, this command always requires confirmation with `yes'. Note also that this command is disabled under CVS, because canceling versions is very dangerous and discouraged with this back end.  File: emacs, Node: VC Mode Line, Next: CVS and VC, Prev: Registering, Up: Editing with VC 12.7.3.5 The VC Mode Line ......................... When you visit a file that is under version control, the mode line indicates the current status of the file: the name of the version control back end system, the locking state, and the version. The locking state is displayed as a single character, which can be either `-' or `:'. `-' means the file is not locked or not modified by you. Once you lock the file, the state indicator changes to `:'. If the file is locked by someone else, that user's name appears after the version number. For example, `RCS-1.3' means you are looking at RCS version 1.3, which is not locked. `RCS:1.3' means that you have locked the file, and possibly already changed it. `RCS:jim:1.3' means that the file is locked by jim.  File: emacs, Node: CVS and VC, Prev: VC Mode Line, Up: Editing with VC 12.7.3.6 Using VC with CVS .......................... In CVS, files are never locked. Two users can check out the same file at the same time; each user has a separate copy and can edit it. Work files are always writable; once you have one, you need not type a VC command to start editing the file. You can edit it at any time. When using RCS and SCCS, you normally use `C-x C-q' twice for each change; once before the change, for checkout, and once after, for checkin. With CVS, it's different: you normally use `C-x C-q' just once for each change, to commit the change when it is done. The work file remains writable, so you can begin editing again with no special commands. One way to understand this is that VC does an "implicit" check-out when you save the modified file for the first time. VC indicates this on the mode line: the status indicator changes from `-' to `:' as soon as you save a modified version, telling you that you are not in sync with the repository anymore (*note VC Mode Line::). The file stays "checked out" until you check it back in, even if you kill the buffer and visit the file again. If, instead, you would like to use explicit check-out with CVS, set the `CVSREAD' environment variable to some value. (It does not matter what value you use.) CVS then makes your work files read-only by default, and VC requires you to check them out explicitly with `C-x C-q'. When setting `CVSREAD' for the first time, make sure to check out all your modules anew, so that the file protections are set correctly. VC does not provide a way to check out a working copy of an existing file in the repository. You have to use the CVS shell commands to do that. Once you have a work file, you can start using VC for that file. CVS terminology speaks of "committing" a change rather than checking it in. But in practical terms they work the same way: Emacs asks you to type in a log entry, and you finish it with `C-c C-c'. When you try to commit a change in a file, but someone else has committed another change in the meanwhile, that creates a "conflict". VC detects this situation and offers to "merge" your changes and those of the other user, creating a new local version of the file, which you can then commit to the repository. This works smoothly if the changes are in different parts of the file, although it is wise to check the resulting file for semantic consistency. However, if you and the other user changed the same parts of the file, the conflict cannot be resolved automatically. In this case, CVS inserts both variants of the conflicting regions into your working file, and puts so-called "conflict markers" around them. They indicate how the region looks in the respective user's version. You must resolve the conflict manually, for example by choosing one of the two variants and deleting the other one (and the conflict markers). Then you can commit the resulting file into the repository. The example below shows how a conflict region looks; the file is called `name' and the current repository version with user B's changes in it is 1.11. <<<<<<< name USER A'S VERSION ======= USER B'S VERSION >>>>>>> 1.11 You can turn off use of VC for CVS-managed files by setting the variable `vc-handle-cvs' to `nil'. If you do this, Emacs treats these files as if they were not managed, and the VC commands are not available for them. You must do all CVS operations manually.  File: emacs, Node: Log Entries, Next: Change Logs and VC, Prev: Editing with VC, Up: Version Control 12.7.4 Log Entries ------------------ When you're editing an initial comment or log entry for inclusion in a master file, finish your entry by typing `C-c C-c'. `C-c C-c' Finish the comment edit normally (`vc-finish-logentry'). This finishes check-in. To abort check-in, just *don't* type `C-c C-c' in that buffer. You can switch buffers and do other editing. As long as you don't try to check in another file, the entry you were editing remains in its buffer, and you can go back to that buffer at any time to complete the check-in. If you change several source files for the same reason, it is often convenient to specify the same log entry for many of the files. To do this, use the history of previous log entries. The commands `M-n', `M-p', `M-s' and `M-r' for doing this work just like the minibuffer history commands (except that these versions are used outside the minibuffer). Each time you check in a file, the log entry buffer is put into VC Log mode, which involves running two hooks: `text-mode-hook' and `vc-log-mode-hook'. *Note Hooks::.  File: emacs, Node: Change Logs and VC, Next: Old Versions, Prev: Log Entries, Up: Version Control 12.7.5 Change Logs and VC ------------------------- If you use RCS for a program and also maintain a change log file for it (*note Change Log::), you can generate change log entries automatically from the version control log entries: `C-x v a' Visit the current directory's change log file and create new entries for versions checked in since the most recent entry in the change log file (`vc-update-change-log'). This command works with RCS only; it does not work with CVS or SCCS. For example, suppose the first line of `ChangeLog' is dated 10 April 1992, and that the only check-in since then was by Nathaniel Bowditch to `rcs2log' on 8 May 1992 with log text `Ignore log messages that start with `#'.'. Then `C-x v a' visits `ChangeLog' and inserts text like this: Fri May 8 21:45:00 1992 Nathaniel Bowditch * rcs2log: Ignore log messages that start with `#'. You can then edit the new change log entry further as you wish. Normally, the log entry for file `foo' is displayed as `* foo: TEXT OF LOG ENTRY'. The `:' after `foo' is omitted if the text of the log entry starts with `(FUNCTIONNAME): '. For example, if the log entry for `vc.el' is `(vc-do-command): Check call-process status.', then the text in `ChangeLog' looks like this: Wed May 6 10:53:00 1992 Nathaniel Bowditch * vc.el (vc-do-command): Check call-process status. When `C-x v a' adds several change log entries at once, it groups related log entries together if they all are checked in by the same author at nearly the same time. If the log entries for several such files all have the same text, it coalesces them into a single entry. For example, suppose the most recent checkins have the following log entries: * For `vc.texinfo': `Fix expansion typos.' * For `vc.el': `Don't call expand-file-name.' * For `vc-hooks.el': `Don't call expand-file-name.' They appear like this in `ChangeLog': Wed Apr 1 08:57:59 1992 Nathaniel Bowditch * vc.texinfo: Fix expansion typos. * vc.el, vc-hooks.el: Don't call expand-file-name. Normally, `C-x v a' separates log entries by a blank line, but you can mark several related log entries to be clumped together (without an intervening blank line) by starting the text of each related log entry with a label of the form `{CLUMPNAME} '. The label itself is not copied to `ChangeLog'. For example, suppose the log entries are: * For `vc.texinfo': `{expand} Fix expansion typos.' * For `vc.el': `{expand} Don't call expand-file-name.' * For `vc-hooks.el': `{expand} Don't call expand-file-name.' Then the text in `ChangeLog' looks like this: Wed Apr 1 08:57:59 1992 Nathaniel Bowditch * vc.texinfo: Fix expansion typos. * vc.el, vc-hooks.el: Don't call expand-file-name. A log entry whose text begins with `#' is not copied to `ChangeLog'. For example, if you merely fix some misspellings in comments, you can log the change with an entry beginning with `#' to avoid putting such trivia into `ChangeLog'.  File: emacs, Node: Old Versions, Next: Branches, Prev: Change Logs and VC, Up: Version Control 12.7.6 Examining And Comparing Old Versions ------------------------------------------- `C-u C-x C-q VERSION ' Select version VERSION as the current work file version. `C-x v ~ VERSION ' Examine version VERSION of the visited file, in a buffer of its own. `C-x v =' Compare the current buffer contents with the latest checked-in version of the file. `C-u C-x v = FILE OLDVERS NEWVERS ' Compare the specified two versions of FILE. There are two ways to work with an old version of a file. You can make the old version your current work file, for example if you want to reproduce a former stage of development, or if you want to create a branch from the old version (*note Branches::). To do this, visit the file and type `C-u C-x C-q VERSION '. (This works only with RCS.) If you want only to examine an old version, without changing your work file, visit the file and then type `C-x v ~ VERSION ' (`vc-version-other-window'). This puts the text of version VERSION in a file named `FILENAME.~VERSION~', and visits it in its own buffer in a separate window. To compare two versions of a file, use the command `C-x v =' (`vc-diff'). Plain `C-x v =' compares the current buffer contents (saving them in the file if necessary) with the last checked-in version of the file. `C-u C-x v =', with a numeric argument, reads a file name and two version numbers, then compares those versions of the specified file. If you supply a directory name instead of the name of a work file, this command compares the two specified versions of all registered files in that directory and its subdirectories. You can also specify a snapshot name (*note Snapshots::) instead of one or both version numbers. You can specify a checked-in version by its number; an empty input specifies the current contents of the work file (which may be different from all the checked-in versions). This command works by running the `diff' utility, getting the options from the variable `diff-switches'. It displays the output in a special buffer in another window. Unlike the `M-x diff' command, `C-x v =' does not try to locate the changes in the old and new versions. This is because normally one or both versions do not exist as files when you compare them; they exist only in the records of the master file. *Note Comparing Files::, for more information about `M-x diff'.  File: emacs, Node: Branches, Next: Status in VC, Prev: Old Versions, Up: Version Control 12.7.7 Multiple Branches of a File ---------------------------------- One use of version control is to maintain multiple "current" versions of a file. For example, you might have different versions of a program in which you are gradually adding various unfinished new features. Each such independent line of development is called a "branch". VC allows you to create branches, and switch between existing branches. Note, however, that branches are supported only with RCS. A file's main line of development is usually called the "trunk". The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At any such version, you may start an independent branch. A branch starting at version 1.2 would have version number 1.2.1.1. Consecutive versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is a second branch also starting at version 1.2; it would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, and so on. If you omit the final component of a version number, that is called a "branch number". It refers to the highest existing version on that branch. The branches in the example above have branch numbers 1.2.1 and 1.2.2. A version which is the last in its branch is called a "head" version. * Menu: * Switching Branches:: How to get to another existing branch. * Creating Branches:: How to start a new branch. * Multi-User Branching:: Multiple users working at multiple branches in parallel.  File: emacs, Node: Switching Branches, Next: Creating Branches, Up: Branches 12.7.7.1 Switching between Branches ................................... To switch between branches, type `C-u C-x C-q' and specify the version number you want to select. This version is then checked out _unlocked_ (write-protected), so you can examine it before really checking it out. Switching branches in this way is allowed only when the file is not locked. You may omit the minor version number, thus giving only the branch number; this takes you to the highest version on the indicated branch. If you only type `RET', Emacs goes to the highest version on the trunk. After you have switched to any branch (including the main branch), you stay on it for subsequent VC commands, until you explicitly select some other branch.  File: emacs, Node: Creating Branches, Next: Multi-User Branching, Prev: Switching Branches, Up: Branches 12.7.7.2 Creating New Branches .............................. To create a new branch from a head version (one that is the latest in the branch that contains it), first select that version if necessary, lock it with `C-x C-q', and make whatever changes you want. Then, when you check in the changes, use `C-u C-x C-q'. This lets you specify the version number for the new version. You should specify a suitable branch number for a branch starting at the current version. For example, if the current version is 2.5, the branch number should be 2.5.1, 2.5.2, and so on, depending on the number of existing branches at that point. To create a new branch at an older version (one that is no longer the head of a branch), first select that version, then lock it with `C-x C-q'. You'll be asked to confirm, when you lock the old version, that you really mean to create a new branch--if you say no, you'll be offered a chance to lock the latest version instead. Then make your changes and type `C-x C-q' again to check in a new version. This automatically creates a new branch starting from the selected version. You need not specially request a new branch, because that's the only way to add a new version at a point that is not the head of a branch. After the branch is created, you "stay" on it. That means that subsequent checkouts and checkins create new versions on that branch. To leave the branch, you must explicitly select a different version with `C-u C-x C-q' for checkout.  File: emacs, Node: Multi-User Branching, Prev: Creating Branches, Up: Branches 12.7.7.3 Multi-User Branching ............................. It is sometimes useful for multiple developers to work simultaneously on different branches of a file. This is possible if you create multiple source directories. Each source directory should have a link named `RCS' which points to a common directory of RCS master files. Then each source directory can have its own choice of versions checked out, but all share the same common RCS records. This technique works reliably and automatically, provided that the source files contain RCS version headers (*note Version Headers::). The headers enable Emacs to be sure, at all times, which version number is present in the work file. If the files do not have version headers, you must instead tell Emacs explicitly in each session which branch you are working on. To do this, first find the file, then type `C-u C-x C-q' and specify the correct branch number. This ensures that Emacs knows which branch it is using during this particular editing session.  File: emacs, Node: Status in VC, Next: Renaming and VC, Prev: Branches, Up: Version Control 12.7.8 VC Status Commands ------------------------- To view the detailed version control status and history of a file, type `C-x v l' (`vc-print-log'). It displays the history of changes to the current file, including the text of the log entries. The output appears in a separate window. When you are working on a large program, it's often useful to find all the files that are currently locked, or all the files maintained in version control at all. You can use `C-x v d' (`vc-directory') to show all the locked files in or beneath a certain directory. This includes all files that are locked by any user. `C-u C-x v d' lists all files in or beneath the specified directory that are maintained with version control. The list of files is displayed as a buffer that uses an augmented Dired mode. The names of the users locking various files are shown (in parentheses) in place of the owner and group. (With CVS, a more detailed status is shown for each file.) All the normal Dired commands work in this buffer. Most interactive VC commands work also, and apply to the file name on the current line. The `C-x v v' command (`vc-next-action'), when used in the augmented Dired buffer, operates on all the marked files (or the file on the current line). If it operates on more than one file, it handles each file according to its current state; thus, it may check out one file and check in another (because it is already checked out). If it has to check in any files, it reads a single log entry, then uses that text for all the files being checked in. This can be convenient for registering or checking in several files at once, as part of the same change.  File: emacs, Node: Renaming and VC, Next: Snapshots, Prev: Status in VC, Up: Version Control 12.7.9 Renaming VC Work Files and Master Files ---------------------------------------------- When you rename a registered file, you must also rename its master file correspondingly to get proper results. Use `vc-rename-file' to rename the source file as you specify, and rename its master file accordingly. It also updates any snapshots (*note Snapshots::) that mention the file, so that they use the new name; despite this, the snapshot thus modified may not completely work (*note Snapshot Caveats::). You cannot use `vc-rename-file' on a file that is locked by someone else.  File: emacs, Node: Snapshots, Next: Version Headers, Prev: Renaming and VC, Up: Version Control 12.7.10 Snapshots ----------------- A "snapshot" is a named set of file versions (one for each registered file) that you can treat as a unit. One important kind of snapshot is a "release", a (theoretically) stable version of the system that is ready for distribution to users. * Menu: * Making Snapshots:: The snapshot facilities. * Snapshot Caveats:: Things to be careful of when using snapshots.  File: emacs, Node: Making Snapshots, Next: Snapshot Caveats, Up: Snapshots 12.7.10.1 Making and Using Snapshots .................................... There are two basic commands for snapshots; one makes a snapshot with a given name, the other retrieves a named snapshot. `C-x v s NAME ' Define the last saved versions of every registered file in or under the current directory as a snapshot named NAME (`vc-create-snapshot'). `C-x v r NAME ' Check out all registered files at or below the current directory level using whatever versions correspond to the snapshot NAME (`vc-retrieve-snapshot'). This command reports an error if any files are locked at or below the current directory, without changing anything; this is to avoid overwriting work in progress. A snapshot uses a very small amount of resources--just enough to record the list of file names and which version belongs to the snapshot. Thus, you need not hesitate to create snapshots whenever they are useful. You can give a snapshot name as an argument to `C-x v =' or `C-x v ~' (*note Old Versions::). Thus, you can use it to compare a snapshot against the current files, or two snapshots against each other, or a snapshot against a named version.  File: emacs, Node: Snapshot Caveats, Prev: Making Snapshots, Up: Snapshots 12.7.10.2 Snapshot Caveats .......................... VC's snapshot facilities are modeled on RCS's named-configuration support. They use RCS's native facilities for this, so under VC snapshots made using RCS are visible even when you bypass VC. For SCCS, VC implements snapshots itself. The files it uses contain name/file/version-number triples. These snapshots are visible only through VC. A snapshot is a set of checked-in versions. So make sure that all the files are checked in and not locked when you make a snapshot. File renaming and deletion can create some difficulties with snapshots. This is not a VC-specific problem, but a general design issue in version control systems that no one has solved very well yet. If you rename a registered file, you need to rename its master along with it (the command `vc-rename-file' does this automatically). If you are using SCCS, you must also update the records of the snapshot, to mention the file by its new name (`vc-rename-file' does this, too). An old snapshot that refers to a master file that no longer exists under the recorded name is invalid; VC can no longer retrieve it. It would be beyond the scope of this manual to explain enough about RCS and SCCS to explain how to update the snapshots by hand. Using `vc-rename-file' makes the snapshot remain valid for retrieval, but it does not solve all problems. For example, some of the files in the program probably refer to others by name. At the very least, the makefile probably mentions the file that you renamed. If you retrieve an old snapshot, the renamed file is retrieved under its new name, which is not the name that the makefile expects. So the program won't really work as retrieved.  File: emacs, Node: Version Headers, Next: Customizing VC, Prev: Snapshots, Up: Version Control 12.7.11 Inserting Version Control Headers ----------------------------------------- Sometimes it is convenient to put version identification strings directly into working files. Certain special strings called "version headers" are replaced in each successive version by the number of that version. If you are using RCS, and version headers are present in your working files, Emacs can use them to determine the current version and the locking state of the files. This is more reliable than referring to the master files, which is done when there are no version headers. Note that in a multi-branch environment, version headers are necessary to make VC behave correctly (*note Multi-User Branching::). Searching for version headers is controlled by the variable `vc-consult-headers'. If it is non-`nil', Emacs searches for headers to determine the version number you are editing. Setting it to `nil' disables this feature. You can use the `C-x v h' command (`vc-insert-headers') to insert a suitable header string. `C-x v h' Insert headers in a file for use with your version-control system. The default header string is `$Id$' for RCS and `%W%' for SCCS. You can specify other headers to insert by setting the variable `vc-header-alist'. Its value is a list of elements of the form `(PROGRAM . STRING)' where PROGRAM is `RCS' or `SCCS' and STRING is the string to use. Instead of a single string, you can specify a list of strings; then each string in the list is inserted as a separate header on a line of its own. It is often necessary to use "superfluous" backslashes when writing the strings that you put in this variable. This is to prevent the string in the constant from being interpreted as a header itself if the Emacs Lisp file containing it is maintained with version control. Each header is inserted surrounded by tabs, inside comment delimiters, on a new line at the start of the buffer. Normally the ordinary comment start and comment end strings of the current mode are used, but for certain modes, there are special comment delimiters for this purpose; the variable `vc-comment-alist' specifies them. Each element of this list has the form `(MODE STARTER ENDER)'. The variable `vc-static-header-alist' specifies further strings to add based on the name of the buffer. Its value should be a list of elements of the form `(REGEXP . FORMAT)'. Whenever REGEXP matches the buffer name, FORMAT is inserted as part of the header. A header line is inserted for each element that matches the buffer name, and for each string specified by `vc-header-alist'. The header line is made by processing the string from `vc-header-alist' with the format taken from the element. The default value for `vc-static-header-alist' is as follows: (("\\.c$" . "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ #endif /* lint */\n")) It specifies insertion of text of this form: #ifndef lint static char vcid[] = "STRING"; #endif /* lint */ Note that the text above starts with a blank line. If you use more than one version header in a file, put them close together in the file. The mechanism in `revert-buffer' that preserves markers may not handle markers positioned between two version headers.  File: emacs, Node: Customizing VC, Prev: Version Headers, Up: Version Control 12.7.12 Customizing VC ---------------------- There are many ways of customizing VC. The variables that control its behavior fall into three categories, described in the following sections. * Menu: * VC Workfile Handling:: Various options concerning working files. * VC Status Retrieval:: How VC finds the version control status of a file, and how to customize this. * VC Command Execution:: Which commands VC should run, and how.  File: emacs, Node: VC Workfile Handling, Next: VC Status Retrieval, Up: Customizing VC 12.7.12.1 VC Workfile Handling .............................. Emacs normally does not save backup files for source files that are maintained with version control. If you want to make backup files even for files that use version control, set the variable `vc-make-backup-files' to a non-`nil' value. Normally the work file exists all the time, whether it is locked or not. If you set `vc-keep-workfiles' to `nil', then checking in a new version with `C-x C-q' deletes the work file; but any attempt to visit the file with Emacs creates it again. (With CVS, work files are always kept.) Editing a version-controlled file through a symbolic link can be dangerous. It bypasses the version control system--you can edit the file without checking it out, and fail to check your changes in. Also, your changes might overwrite those of another user. To protect against this, VC checks each symbolic link that you visit, to see if it points to a file under version control. The variable `vc-follow-symlinks' controls what to do when a symbolic link points to a version-controlled file. If it is `nil', VC only displays a warning message. If it is `t', VC automatically follows the link, and visits the real file instead, telling you about this in the echo area. If the value is `ask' (the default), VC asks you each time whether to follow the link.  File: emacs, Node: VC Status Retrieval, Next: VC Command Execution, Prev: VC Workfile Handling, Up: Customizing VC 12.7.12.2 VC Status Retrieval ............................. When deducing the locked/unlocked state of a file, VC first looks for an RCS version header string in the file (*note Version Headers::). If there is no header string (or if the backend system is SCCS), VC normally looks at the file permissions of the work file; this is fast. But there might be situations when the file permissions cannot be trusted. In this case the master file has to be consulted, which is rather expensive. Also the master file can only tell you _if_ there's any lock on the file, but not whether your work file really contains that locked version. You can tell VC not to use version headers to determine lock status by setting `vc-consult-headers' to `nil'. VC then always uses the file permissions (if it can trust them), or else checks the master file. You can specify the criterion for whether to trust the file permissions by setting the variable `vc-mistrust-permissions'. Its value may be `t' (always mistrust the file permissions and check the master file), `nil' (always trust the file permissions), or a function of one argument which makes the decision. The argument is the directory name of the `RCS', `CVS' or `SCCS' subdirectory. A non-`nil' value from the function says to mistrust the file permissions. If you find that the file permissions of work files are changed erroneously, set `vc-mistrust-permissions' to `t'. Then VC always checks the master file to determine the file's status.  File: emacs, Node: VC Command Execution, Prev: VC Status Retrieval, Up: Customizing VC 12.7.12.3 VC Command Execution .............................. If `vc-suppress-confirm' is non-`nil', then `C-x C-q' and `C-x v i' can save the current buffer without asking, and `C-x v u' also operates without asking for confirmation. (This variable does not affect `C-x v c'; that operation is so drastic that it should always ask for confirmation.) VC mode does much of its work by running the shell commands for RCS, CVS and SCCS. If `vc-command-messages' is non-`nil', VC displays messages to indicate which shell commands it runs, and additional messages when the commands finish. You can specify additional directories to search for version control programs by setting the variable `vc-path'. These directories are searched before the usual search path. But the proper files are usually found automatically.  File: emacs, Node: Directories, Next: Comparing Files, Prev: Version Control, Up: Files 12.8 File Directories ===================== The file system groups files into "directories". A "directory listing" is a list of all the files in a directory. Emacs provides commands to create and delete directories, and to make directory listings in brief format (file names only) and verbose format (sizes, dates, and authors included). There is also a directory browser called Dired; see *Note Dired::. `C-x C-d DIR-OR-PATTERN ' Display a brief directory listing (`list-directory'). `C-u C-x C-d DIR-OR-PATTERN ' Display a verbose directory listing. `M-x make-directory DIRNAME ' Create a new directory named DIRNAME. `M-x delete-directory DIRNAME ' Delete the directory named DIRNAME. It must be empty, or you get an error. The command to display a directory listing is `C-x C-d' (`list-directory'). It reads using the minibuffer a file name which is either a directory to be listed or a wildcard-containing pattern for the files to be listed. For example, C-x C-d /u2/emacs/etc lists all the files in directory `/u2/emacs/etc'. Here is an example of specifying a file name pattern: C-x C-d /u2/emacs/src/*.c Normally, `C-x C-d' prints a brief directory listing containing just file names. A numeric argument (regardless of value) tells it to make a verbose listing including sizes, dates, and authors (like `ls -l'). The text of a directory listing is obtained by running `ls' in an inferior process. Two Emacs variables control the switches passed to `ls': `list-directory-brief-switches' is a string giving the switches to use in brief listings (`"-CF"' by default), and `list-directory-verbose-switches' is a string giving the switches to use in a verbose listing (`"-l"' by default).  File: emacs, Node: Comparing Files, Next: Misc File Ops, Prev: Directories, Up: Files 12.9 Comparing Files ==================== The command `M-x diff' compares two files, displaying the differences in an Emacs buffer named `*Diff*'. It works by running the `diff' program, using options taken from the variable `diff-switches', whose value should be a string. The buffer `*Diff*' has Compilation mode as its major mode, so you can use `C-x `' to visit successive changed locations in the two source files. You can also move to a particular hunk of changes and type or `C-c C-c', or click `Mouse-2' on it, to move to the corresponding source location. You can also use the other special commands of Compilation mode: and for scrolling, and `M-p' and `M-n' for cursor motion. *Note Compilation::. The command `M-x diff-backup' compares a specified file with its most recent backup. If you specify the name of a backup file, `diff-backup' compares it with the source file that it is a backup of. The command `M-x compare-windows' compares the text in the current window with that in the next window. Comparison starts at point in each window, and each starting position is pushed on the mark ring in its respective buffer. Then point moves forward in each window, a character at a time, until a mismatch between the two windows is reached. Then the command is finished. For more information about windows in Emacs, *Note Windows::. With a numeric argument, `compare-windows' ignores changes in whitespace. If the variable `compare-ignore-case' is non-`nil', it ignores differences in case as well. See also *Note Emerge::, for convenient facilities for merging two similar files.  File: emacs, Node: Misc File Ops, Next: Compressed Files, Prev: Comparing Files, Up: Files 12.10 Miscellaneous File Operations =================================== Emacs has commands for performing many other operations on files. All operate on one file; they do not accept wild card file names. `M-x view-file' allows you to scan or read a file by sequential screenfuls. It reads a file name argument using the minibuffer. After reading the file into an Emacs buffer, `view-file' displays the beginning. You can then type to scroll forward one windowful, or to scroll backward. Various other commands are provided for moving around in the file, but none for changing it; type `?' while viewing for a list of them. They are mostly the same as normal Emacs cursor motion commands. To exit from viewing, type `q'. The commands for viewing are defined by a special major mode called View mode. A related command, `M-x view-buffer', views a buffer already present in Emacs. *Note Misc Buffer::. `M-x insert-file' inserts a copy of the contents of the specified file into the current buffer at point, leaving point unchanged before the contents and the mark after them. `M-x write-region' is the inverse of `M-x insert-file'; it copies the contents of the region into the specified file. `M-x append-to-file' adds the text of the region to the end of the specified file. *Note Accumulating Text::. `M-x delete-file' deletes the specified file, like the `rm' command in the shell. If you are deleting many files in one directory, it may be more convenient to use Dired (*note Dired::). `M-x rename-file' reads two file names OLD and NEW using the minibuffer, then renames file OLD as NEW. If a file named NEW already exists, you must confirm with `yes' or renaming is not done; this is because renaming causes the old meaning of the name NEW to be lost. If OLD and NEW are on different file systems, the file OLD is copied and deleted. The similar command `M-x add-name-to-file' is used to add an additional name to an existing file without removing its old name. The new name must belong on the same file system that the file is on. `M-x copy-file' reads the file OLD and writes a new file named NEW with the same contents. Confirmation is required if a file named NEW already exists, because copying has the consequence of overwriting the old contents of the file NEW. `M-x make-symbolic-link' reads two file names OLD and LINKNAME, then creates a symbolic link named LINKNAME and pointing at OLD. The effect is that future attempts to open file LINKNAME will refer to whatever file is named OLD at the time the opening is done, or will get an error if the name OLD is not in use at that time. This command does not expand the argument FILENAME, so that it allows you to specify a relative name as the target of the link. Confirmation is required when creating the link if LINKNAME is in use. Note that not all systems support symbolic links.  File: emacs, Node: Compressed Files, Prev: Misc File Ops, Up: Files 12.11 Accessing Compressed Files ================================ Emacs comes with a library that can automatically uncompress compressed files when you visit them, and automatically recompress them if you alter them and save them. To enable this feature, type the command `M-x auto-compression-mode'. When automatic compression (which implies automatic uncompression as well) is enabled, Emacs recognizes compressed files by their file names. File names ending in `.gz' indicate a file compressed with `gzip'. Other endings indicate other compression programs. Automatic uncompression and compression apply to all the operations in which Emacs uses the contents of a file. This includes visiting it, saving it, inserting its contents into a buffer, loading it, and byte compiling it.  File: emacs, Node: Buffers, Next: Windows, Prev: Files, Up: Top 13 Using Multiple Buffers ************************* The text you are editing in Emacs resides in an object called a "buffer". Each time you visit a file, a buffer is created to hold the file's text. Each time you invoke Dired, a buffer is created to hold the directory listing. If you send a message with `C-x m', a buffer named `*mail*' is used to hold the text of the message. When you ask for a command's documentation, that appears in a buffer called `*Help*'. At any time, one and only one buffer is "selected". It is also called the "current buffer". Often we say that a command operates on "the buffer" as if there were only one; but really this means that the command operates on the selected buffer (most commands do). When Emacs has multiple windows, each window has a chosen buffer which is displayed there, but at any time only one of the windows is selected and its chosen buffer is the selected buffer. Each window's mode line displays the name of the buffer that the window is displaying (*note Windows::). Each buffer has a name, which can be of any length, and you can select any buffer by giving its name. Most buffers are made by visiting files, and their names are derived from the files' names. But you can also create an empty buffer with any name you want. A newly started Emacs has a buffer named `*scratch*' which can be used for evaluating Lisp expressions in Emacs. The distinction between upper and lower case matters in buffer names. Each buffer records individually what file it is visiting, whether it is modified, and what major mode and minor modes are in effect in it (*note Major Modes::). Any Emacs variable can be made "local to" a particular buffer, meaning its value in that buffer can be different from the value in other buffers. *Note Locals::. * Menu: * Select Buffer:: Creating a new buffer or reselecting an old one. * List Buffers:: Getting a list of buffers that exist. * Misc Buffer:: Renaming; changing read-onliness; copying text. * Kill Buffer:: Killing buffers you no longer need. * Several Buffers:: How to go through the list of all buffers and operate variously on several of them. * Indirect Buffers:: An indirect buffer shares the text of another buffer.  File: emacs, Node: Select Buffer, Next: List Buffers, Up: Buffers 13.1 Creating and Selecting Buffers =================================== `C-x b BUFFER ' Select or create a buffer named BUFFER (`switch-to-buffer'). `C-x 4 b BUFFER ' Similar, but select BUFFER in another window (`switch-to-buffer-other-window'). `C-x 5 b BUFFER ' Similar, but select BUFFER in a separate frame (`switch-to-buffer-other-frame'). To select the buffer named BUFNAME, type `C-x b BUFNAME '. This runs the command `switch-to-buffer' with argument BUFNAME. You can use completion on an abbreviation for the buffer name you want (*note Completion::). An empty argument to `C-x b' specifies the most recently selected buffer that is not displayed in any window. Most buffers are created by visiting files, or by Emacs commands that want to display some text, but you can also create a buffer explicitly by typing `C-x b BUFNAME '. This makes a new, empty buffer which is not visiting any file, and selects it for editing. Such buffers are used for making notes to yourself. If you try to save one, you are asked for the file name to use. The new buffer's major mode is determined by the value of `default-major-mode' (*note Major Modes::). Note that `C-x C-f', and any other command for visiting a file, can also be used to switch to an existing file-visiting buffer. *Note Visiting::. Emacs uses buffer names that start with a space for internal purposes. It treats these buffers specially in minor ways--for example, by default they do not record undo information. It is best to avoid using such buffer names yourself.  File: emacs, Node: List Buffers, Next: Misc Buffer, Prev: Select Buffer, Up: Buffers 13.2 Listing Existing Buffers ============================= `C-x C-b' List the existing buffers (`list-buffers'). To display a list of all the buffers that exist, type `C-x C-b'. Each line in the list shows one buffer's name, major mode and visited file. The buffers are listed in the order, most recently visited first. `*' at the beginning of a line indicates the buffer is "modified". If several buffers are modified, it may be time to save some with `C-x s' (*note Saving::). `%' indicates a read-only buffer. `.' marks the selected buffer. Here is an example of a buffer list: MR Buffer Size Mode File -- ------ ---- ---- ---- .* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex *Help* 1287 Fundamental files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el % RMAIL 64042 RMAIL /u/rms/RMAIL *% man 747 Dired /u2/emacs/man/ net.emacs 343885 Fundamental /u/rms/net.emacs fileio.c 27691 C /u2/emacs/src/fileio.c NEWS 67340 Text /u2/emacs/etc/NEWS *scratch* 0 Lisp Interaction Note that the buffer `*Help*' was made by a help request; it is not visiting any file. The buffer `man' was made by Dired on the directory `/u2/emacs/man/'.  File: emacs, Node: Misc Buffer, Next: Kill Buffer, Prev: List Buffers, Up: Buffers 13.3 Miscellaneous Buffer Operations ==================================== `C-x C-q' Toggle read-only status of buffer (`vc-toggle-read-only'). `M-x rename-buffer NAME ' Change the name of the current buffer. `M-x rename-uniquely' Rename the current buffer by adding `' to the end. `M-x view-buffer BUFFER ' Scroll through buffer BUFFER. A buffer can be "read-only", which means that commands to change its contents are not allowed. The mode line indicates read-only buffers with `%%' or `%*' near the left margin. Read-only buffers are usually made by subsystems such as Dired and Rmail that have special commands to operate on the text; also by visiting a file whose access control says you cannot write it. If you wish to make changes in a read-only buffer, use the command `C-x C-q' (`vc-toggle-read-only'). It makes a read-only buffer writable, and makes a writable buffer read-only. In most cases, this works by setting the variable `buffer-read-only', which has a local value in each buffer and makes the buffer read-only if its value is non-`nil'. If the file is maintained with version control, `C-x C-q' works through the version control system to change the read-only status of the file as well as the buffer. *Note Version Control::. `M-x rename-buffer' changes the name of the current buffer. Specify the new name as a minibuffer argument. There is no default. If you specify a name that is in use for some other buffer, an error happens and no renaming is done. `M-x rename-uniquely' renames the current buffer to a similar name with a numeric suffix added to make it both different and unique. This command does not need an argument. It is useful for creating multiple shell buffers: if you rename the `*Shell*' buffer, then do `M-x shell' again, it makes a new shell buffer named `*Shell*'; meanwhile, the old shell buffer continues to exist under its new name. This method is also good for mail buffers, compilation buffers, and most Emacs features that create special buffers with particular names. `M-x view-buffer' is much like `M-x view-file' (*note Misc File Ops::) except that it examines an already existing Emacs buffer. View mode provides commands for scrolling through the buffer conveniently but not for changing it. When you exit View mode, the value of point that resulted from your perusal remains in effect. The commands `M-x append-to-buffer' and `M-x insert-buffer' can be used to copy text from one buffer to another. *Note Accumulating Text::.  File: emacs, Node: Kill Buffer, Next: Several Buffers, Prev: Misc Buffer, Up: Buffers 13.4 Killing Buffers ==================== If you continue an Emacs session for a while, you may accumulate a large number of buffers. You may then find it convenient to "kill" the buffers you no longer need. On most operating systems, killing a buffer releases its space back to the operating system so that other programs can use it. Here are some commands for killing buffers: `C-x k BUFNAME ' Kill buffer BUFNAME (`kill-buffer'). `M-x kill-some-buffers' Offer to kill each buffer, one by one. `C-x k' (`kill-buffer') kills one buffer, whose name you specify in the minibuffer. The default, used if you type just in the minibuffer, is to kill the current buffer. If you kill the current buffer, another buffer is selected; one that has been selected recently but does not appear in any window now. If you ask to kill a file-visiting buffer that is modified (has unsaved editing), then you must confirm with `yes' before the buffer is killed. The command `M-x kill-some-buffers' asks about each buffer, one by one. An answer of `y' means to kill the buffer. Killing the current buffer or a buffer containing unsaved changes selects a new buffer or asks for confirmation just like `kill-buffer'. The buffer menu feature (*note Several Buffers::) is also convenient for killing various buffers. If you want to do something special every time a buffer is killed, you can add hook functions to the hook `kill-buffer-hook' (*note Hooks::).  File: emacs, Node: Several Buffers, Next: Indirect Buffers, Prev: Kill Buffer, Up: Buffers 13.5 Operating on Several Buffers ================================= The "buffer-menu" facility is like a "Dired for buffers"; it allows you to request operations on various Emacs buffers by editing an Emacs buffer containing a list of them. You can save buffers, kill them (here called "deleting" them, for consistency with Dired), or display them. `M-x buffer-menu' Begin editing a buffer listing all Emacs buffers. The command `buffer-menu' writes a list of all Emacs buffers into the buffer `*Buffer List*', and selects that buffer in Buffer Menu mode. The buffer is read-only, and can be changed only through the special commands described in this section. The usual Emacs cursor motion commands can be used in the `*Buffer List*' buffer. The following commands apply to the buffer described on the current line. `d' Request to delete (kill) the buffer, then move down. The request shows as a `D' on the line, before the buffer name. Requested deletions take place when you type the `x' command. `C-d' Like `d' but move up afterwards instead of down. `s' Request to save the buffer. The request shows as an `S' on the line. Requested saves take place when you type the `x' command. You may request both saving and deletion for the same buffer. `x' Perform previously requested deletions and saves. `u' Remove any request made for the current line, and move down. `' Move to previous line and remove any request made for that line. The `d', `C-d', `s' and `u' commands to add or remove flags also move down (or up) one line. They accept a numeric argument as a repeat count. These commands operate immediately on the buffer listed on the current line: `~' Mark the buffer "unmodified". The command `~' does this immediately when you type it. `%' Toggle the buffer's read-only flag. The command `%' does this immediately when you type it. `t' Visit the buffer as a tags table. *Note Select Tags Table::. There are also commands to select another buffer or buffers: `q' Quit the buffer menu--immediately display the most recent formerly visible buffer in its place. `' `f' Immediately select this line's buffer in place of the `*Buffer List*' buffer. `o' Immediately select this line's buffer in another window as if by `C-x 4 b', leaving `*Buffer List*' visible. `C-o' Immediately display this line's buffer in another window, but don't select the window. `1' Immediately select this line's buffer in a full-screen window. `2' Immediately set up two windows, with this line's buffer in one, and the previously selected buffer (aside from the buffer `*Buffer List*') in the other. `m' Mark this line's buffer to be displayed in another window if you exit with the `v' command. The request shows as a `>' at the beginning of the line. (A single buffer may not have both a delete request and a display request.) `v' Immediately select this line's buffer, and also display in other windows any buffers previously marked with the `m' command. If you have not marked any buffers, this command is equivalent to `1'. All that `buffer-menu' does directly is create and switch to a suitable buffer, and turn on Buffer Menu mode. Everything else described above is implemented by the special commands provided in Buffer Menu mode. One consequence of this is that you can switch from the `*Buffer List*' buffer to another Emacs buffer, and edit there. You can reselect the `*Buffer List*' buffer later, to perform the operations already requested, or you can kill it, or pay no further attention to it. The only difference between `buffer-menu' and `list-buffers' is that `buffer-menu' switches to the `*Buffer List*' buffer in the selected window; `list-buffers' displays it in another window. If you run `list-buffers' (that is, type `C-x C-b') and select the buffer list manually, you can use all of the commands described here. The buffer `*Buffer List*' is not updated automatically when buffers are created and killed; its contents are just text. If you have created, deleted or renamed buffers, the way to update `*Buffer List*' to show what you have done is to type `g' (`revert-buffer') or repeat the `buffer-menu' command.  File: emacs, Node: Indirect Buffers, Prev: Several Buffers, Up: Buffers 13.6 Indirect Buffers ===================== An "indirect buffer" shares the text of some other buffer, which is called the "base buffer" of the indirect buffer. In some ways it is the analogue, for buffers, of a symbolic link between files. `M-x make-indirect-buffer BASE-BUFFER INDIRECT-NAME ' Create an indirect buffer named INDIRECT-NAME whose base buffer is BASE-BUFFER. The text of the indirect buffer is always identical to the text of its base buffer; changes made by editing either one are visible immediately in the other. But in all other respects, the indirect buffer and its base buffer are completely separate. They have different names, different values of point, different narrowing, different markers, different major modes, and different local variables. An indirect buffer cannot visit a file, but its base buffer can. If you try to save the indirect buffer, that actually works by saving the base buffer. Killing the base buffer effectively kills the indirect buffer, but killing an indirect buffer has no effect on its base buffer. One way to use indirect buffers is to display multiple views of an outline. *Note Outline Views::.  File: emacs, Node: Windows, Next: Frames, Prev: Buffers, Up: Top 14 Multiple Windows ******************* Emacs can split a frame into two or many windows. Multiple windows can display parts of different buffers, or different parts of one buffer. Multiple frames always imply multiple windows, because each frame has its own set of windows. Each window belongs to one and only one frame. * Menu: * Basic Window:: Introduction to Emacs windows. * Split Window:: New windows are made by splitting existing windows. * Other Window:: Moving to another window or doing something to it. * Pop Up Window:: Finding a file or buffer in another window. * Force Same Window:: Forcing certain buffers to appear in the selected window rather than in another window. * Change Window:: Deleting windows and changing their sizes.  File: emacs, Node: Basic Window, Next: Split Window, Up: Windows 14.1 Concepts of Emacs Windows ============================== Each Emacs window displays one Emacs buffer at any time. A single buffer may appear in more than one window; if it does, any changes in its text are displayed in all the windows where it appears. But the windows showing the same buffer can show different parts of it, because each window has its own value of point. At any time, one of the windows is the "selected window"; the buffer this window is displaying is the current buffer. The terminal's cursor shows the location of point in this window. Each other window has a location of point as well, but since the terminal has only one cursor there is no way to show where those locations are. When multiple frames are visible in X Windows, each frame has a cursor which appears in the frame's selected window. The cursor in the selected frame is solid; the cursor in other frames is a hollow box. Commands to move point affect the value of point for the selected Emacs window only. They do not change the value of point in any other Emacs window, even one showing the same buffer. The same is true for commands such as `C-x b' to change the selected buffer in the selected window; they do not affect other windows at all. However, there are other commands such as `C-x 4 b' that select a different window and switch buffers in it. Also, all commands that display information in a window, including (for example) `C-h f' (`describe-function') and `C-x C-b' (`list-buffers'), work by switching buffers in a nonselected window without affecting the selected window. When multiple windows show the same buffer, they can have different regions, because they can have different values of point. This means that in Transient Mark mode, each window highlights a different part of the buffer. The part that is highlighted in the selected window is the region that editing commands use. Each window has its own mode line, which displays the buffer name, modification status and major and minor modes of the buffer that is displayed in the window. *Note Mode Line::, for full details on the mode line.  File: emacs, Node: Split Window, Next: Other Window, Prev: Basic Window, Up: Windows 14.2 Splitting Windows ====================== `C-x 2' Split the selected window into two windows, one above the other (`split-window-vertically'). `C-x 3' Split the selected window into two windows positioned side by side (`split-window-horizontally'). `C-Mouse-2' In the mode line or scroll bar of a window, split that window. The command `C-x 2' (`split-window-vertically') breaks the selected window into two windows, one above the other. Both windows start out displaying the same buffer, with the same value of point. By default the two windows each get half the height of the window that was split; a numeric argument specifies how many lines to give to the top window. `C-x 3' (`split-window-horizontally') breaks the selected window into two side-by-side windows. A numeric argument specifies how many columns to give the one on the left. A line of vertical bars separates the two windows. Windows that are not the full width of the screen have mode lines, but they are truncated; also, they do not always appear in inverse video, because the Emacs display routines have not been taught how to display a region of inverse video that is only part of a line on the screen. You can split a window horizontally or vertically by clicking `C-Mouse-2' in the mode line or the scroll bar. The line of splitting goes through the place where you click: if you click on the mode line, the new scroll bar goes above the spot; if you click in the scroll bar, the mode line of the split window is side by side with your click. When a window is less than the full width, text lines too long to fit are frequent. Continuing all those lines might be confusing. The variable `truncate-partial-width-windows' can be set non-`nil' to force truncation in all windows less than the full width of the screen, independent of the buffer being displayed and its value for `truncate-lines'. *Note Continuation Lines::. Horizontal scrolling is often used in side-by-side windows. *Note Display::. If `split-window-keep-point' is non-nil, `C-x 2' tries to avoid shifting any text on the screen by putting point in whichever window happens to contain the screen line the cursor is already on. The default is that `split-window-keep-point' is non-nil on slow terminals.  File: emacs, Node: Other Window, Next: Pop Up Window, Prev: Split Window, Up: Windows 14.3 Using Other Windows ======================== `C-x o' Select another window (`other-window'). That is `o', not zero. `C-M-v' Scroll the next window (`scroll-other-window'). `M-x compare-windows' Find next place where the text in the selected window does not match the text in the next window. `Mouse-1' `Mouse-1', in a window's mode line, selects that window but does not move point in it (`mouse-select-region'). To select a different window, click with `Mouse-1' on its mode line. With the keyboard, you can switch windows by typing `C-x o' (`other-window'). That is an `o', for `other', not a zero. When there are more than two windows, this command moves through all the windows in a cyclic order, generally top to bottom and left to right. After the rightmost and bottommost window, it goes back to the one at the upper left corner. A numeric argument means to move several steps in the cyclic order of windows. A negative argument moves around the cycle in the opposite order. When the minibuffer is active, the minibuffer is the last window in the cycle; you can switch from the minibuffer window to one of the other windows, and later switch back and finish supplying the minibuffer argument that is requested. *Note Minibuffer Edit::. The usual scrolling commands (*note Display::) apply to the selected window only, but there is one command to scroll the next window. `C-M-v' (`scroll-other-window') scrolls the window that `C-x o' would select. It takes arguments, positive and negative, like `C-v'. (In the minibuffer, `C-M-v' scrolls the window that contains the minibuffer help display, if any, rather than the next window in the standard cyclic order.) The command `M-x compare-windows' lets you compare two files or buffers visible in two windows, by moving through them to the next mismatch. *Note Comparing Files::, for details.  File: emacs, Node: Pop Up Window, Next: Force Same Window, Prev: Other Window, Up: Windows 14.4 Displaying in Another Window ================================= `C-x 4' is a prefix key for commands that select another window (splitting the window if there is only one) and select a buffer in that window. Different `C-x 4' commands have different ways of finding the buffer to select. `C-x 4 b BUFNAME ' Select buffer BUFNAME in another window. This runs `switch-to-buffer-other-window'. `C-x 4 C-o BUFNAME ' Display buffer BUFNAME in another window, but don't select that buffer or that window. This runs `display-buffer'. `C-x 4 f FILENAME ' Visit file FILENAME and select its buffer in another window. This runs `find-file-other-window'. *Note Visiting::. `C-x 4 d DIRECTORY ' Select a Dired buffer for directory DIRECTORY in another window. This runs `dired-other-window'. *Note Dired::. `C-x 4 m' Start composing a mail message in another window. This runs `mail-other-window'; its same-window analogue is `C-x m' (*note Sending Mail::). `C-x 4 .' Find a tag in the current tags table, in another window. This runs `find-tag-other-window', the multiple-window variant of `M-.' (*note Tags::). `C-x 4 r FILENAME ' Visit file FILENAME read-only, and select its buffer in another window. This runs `find-file-read-only-other-window'. *Note Visiting::.  File: emacs, Node: Force Same Window, Next: Change Window, Prev: Pop Up Window, Up: Windows 14.5 Forcing Display in the Same Window ======================================= Certain Emacs commands switch to a specific buffer with special contents. For example, `M-x shell' switches to a buffer named `*Shell*'. By convention, all these commands are written to pop up the buffer in a separate window. But you can specify that certain of these buffers should appear in the selected window. If you add a buffer name to the list `same-window-buffer-names', the effect is that such commands display that particular buffer by switching to it in the selected window. For example, if you add the element `"*grep*"' to the list, the `grep' command will display its output buffer in the selected window. The default value of `same-window-buffer-names' is not `nil'. It specifies the buffers `*info*', `*mail*' and `*shell*'. This is why `M-x shell' normally switches to the `*shell*' buffer in the selected window. If you delete this element from the value of `same-window-buffer-names', the behavior of `M-x shell' will change--it will pop up the buffer in another window instead. You can specify these buffers more generally with the variable `same-window-regexps'. Set it to a list of regular expressions; then any buffer whose name matches one of those regular expressions is displayed by switching to it in the selected window. (Once again, this applies only to buffers that normally get displayed for you in a separate window.) The default value of this variable specifies Telnet and rlogin buffers. An analogous feature lets you specify buffers which should be displayed in their own individual frames. *Note Special Buffer Frames::.  File: emacs, Node: Change Window, Prev: Force Same Window, Up: Windows 14.6 Deleting and Rearranging Windows ===================================== `C-x 0' Delete the selected window (`delete-window'). That is a zero. `C-x 1' Delete all windows in the selected frame except the selected window (`delete-other-windows'). `C-x ^' Make selected window taller (`enlarge-window'). `C-x }' Make selected window wider (`enlarge-window-horizontally'). `Drag-Mouse-1' Dragging a window's mode line up or down with `Mouse-1' changes window heights. `Mouse-2' `Mouse-2' in a window's mode line deletes all other windows in the frame (`mouse-delete-other-windows'). `Mouse-3' `Mouse-3' in a window's mode line deletes that window (`mouse-delete-window'). To delete a window, type `C-x 0' (`delete-window'). (That is a zero.) The space occupied by the deleted window is given to an adjacent window (but not the minibuffer window, even if that is active at the time). Once a window is deleted, its attributes are forgotten; only restoring a window configuration can bring it back. Deleting the window has no effect on the buffer it used to display; the buffer continues to exist, and you can select it in any window with `C-x b'. `C-x 1' (`delete-other-windows') is more powerful than `C-x 0'; it deletes all the windows except the selected one (and the minibuffer); the selected window expands to use the whole frame except for the echo area. You can also delete a window by clicking on its mode line with `Mouse-2', and expand a window to fill its frame by clicking on its mode line with `Mouse-3'. The easiest way to adjust window heights is with a mouse. If you press `Mouse-1' on a mode line, you can drag that mode line up or down, changing the heights of the windows above and below it. To readjust the division of space among vertically adjacent windows, use `C-x ^' (`enlarge-window'). It makes the currently selected window get one line bigger, or as many lines as is specified with a numeric argument. With a negative argument, it makes the selected window smaller. `C-x }' (`enlarge-window-horizontally') makes the selected window wider by the specified number of columns. The extra screen space given to a window comes from one of its neighbors, if that is possible. If this makes any window too small, it is deleted and its space is given to an adjacent window. The minimum size is specified by the variables `window-min-height' and `window-min-width'. *Note Minibuffer Edit::, for information about the Resize-Minibuffer mode, which automatically changes the size of the minibuffer window to fit the text in the minibuffer.  File: emacs, Node: Frames, Next: Major Modes, Prev: Windows, Up: Top 15 Frames and X Windows *********************** When using the X Window System, you can create multiple windows at the X level in a single Emacs session. Each X window that belongs to Emacs displays a "frame" which can contain one or several Emacs windows. A frame initially contains a single general-purpose Emacs window which you can subdivide vertically or horizontally into smaller windows. A frame normally contains its own echo area and minibuffer, but you can make frames that don't have these--they use the echo area and minibuffer of another frame. Editing you do in one frame also affects the other frames. For instance, if you put text in the kill ring in one frame, you can yank it in another frame. If you exit Emacs through `C-x C-c' in one frame, it terminates all the frames. To delete just one frame, use `C-x 5 0'. To avoid confusion, we reserve the word "window" for the subdivisions that Emacs implements, and never use it to refer to a frame. * Menu: * Mouse Commands:: Moving, cutting, and pasting, with the mouse. * Secondary Selection::Cutting without altering point and mark. * Mouse References:: Using the mouse to select an item from a list. * Menu Mouse Clicks:: Mouse clicks that bring up menus. * Mode Line Mouse:: Mouse clicks on the mode line. * Creating Frames:: Creating additional Emacs frames with various contents. * Multiple Displays:: How one Emacs job can talk to several displays. * Special Buffer Frames:: You can make certain buffers have their own frames. * Frame Parameters:: Changing the colors and other modes of frames. * Scroll Bars:: How to enable and disable scroll bars; how to use them. * Menu Bars:: Enabling and disabling the menu bar. * Faces:: How to change the display style using faces. * Modifying Faces:: How to change what a particular face looks like. * Font Lock:: Minor mode for syntactic highlighting using faces. * Support Modes:: Font Lock support modes make Font Lock faster. * Misc X:: Iconifying and deleting frames. Region highlighting. * Non-Window Terminals:: Multiple frames on terminals that only show one.  File: emacs, Node: Mouse Commands, Next: Secondary Selection, Up: Frames 15.1 Mouse Commands for Editing =============================== The mouse commands for selecting and copying a region are mostly compatible with the `xterm' program. You can use the same mouse commands for copying between Emacs and other X client programs. `Mouse-1' Move point to where you click (`mouse-set-point'). This is normally the left button. `Drag-Mouse-1' Set the region to the text you select by dragging, and copy it to the kill ring (`mouse-set-region'). You can specify both ends of the region with this single command. If you move the mouse off the top or bottom of the window while dragging, the window scrolls at a steady rate until you move the mouse back into the window. This way, you can select regions that don't fit entirely on the screen. The number of lines scrolled per step depends on how far away from the window edge the mouse has gone; the variable `mouse-scroll-min-lines' specifies a minimum step size. `Mouse-2' Yank the last killed text, where you click (`mouse-yank-at-click'). This is normally the middle button. `Mouse-3' This command, `mouse-save-then-kill', has several functions depending on where you click and the status of the region. The most basic case is when you click `Mouse-1' in one place and then `Mouse-3' in another. This selects the text between those two positions as the region. It also copies the new region to the kill ring, so that you can copy it to someplace else. If you click `Mouse-1', scroll with the scroll bar, and then click `Mouse-3', it remembers where point was before scrolling (where you put it with `Mouse-1'), and uses that position as the other end of the region. This is so that you can select a region that doesn't fit entirely on the screen. More generally, if you do not have a highlighted region, `Mouse-3' selects the text between point and the click position as the region. It does this by setting the mark where point was, and moving point to where you click. If you have a highlighted region, or if the region was set just before by dragging button 1, `Mouse-3' adjusts the nearer end of the region by moving it to where you click. The adjusted region's text also replaces the old region's text in the kill ring. If you originally specified the region using a double or triple `Mouse-1', so that the region is defined to consist of entire words or lines, then adjusting the region with `Mouse-3' also proceeds by entire words or lines. If you use `Mouse-3' a second time consecutively, at the same place, that kills the region already selected. `Double-Mouse-1' This key sets the region around the word which you click on. If you click on a character with "symbol" syntax (such as underscore, in C mode), it sets the region around the symbol surrounding that character. If you click on a character with open-parenthesis or close-parenthesis syntax, it sets the region around the parenthetical grouping (sexp) which that character starts or ends. If you click on a character with string-delimiter syntax (such as a singlequote or doublequote in C), it sets the region around the string constant (using heuristics to figure out whether that character is the beginning or the end of it). `Double-Drag-Mouse-1' This key selects a region made up of the words that you drag across. `Triple-Mouse-1' This key sets the region around the line which you click on. `Triple-Drag-Mouse-1' This key selects a region made up of the lines that you drag across. The simplest way to kill text with the mouse is to press `Mouse-1' at one end, then press `Mouse-3' twice at the other end. *Note Killing::. To copy the text into the kill ring without deleting it from the buffer, press `Mouse-3' just once--or just drag across the text with `Mouse-1'. Then you can copy it elsewhere by yanking it. To yank the killed or copied text somewhere else, move the mouse there and press `Mouse-2'. *Note Yanking::. However, if `mouse-yank-at-point' is non-`nil', `Mouse-2' yanks at point. Then it does not matter precisely where you click; all that matters is which window you click on. The default value is `nil'. This variable also effects yanking the secondary selection. To copy text to another X window, kill it or save it in the kill ring. Under X, this also sets the "primary selection". Then use the "paste" or "yank" command of the program operating the other window to insert the text from the selection. To copy text from another X window, use the "cut" or "copy" command of the program operating the other window, to select the text you want. Then yank it in Emacs with `C-y' or `Mouse-2'. When Emacs puts text into the kill ring, or rotates text to the front of the kill ring, it sets the "primary selection" in the X server. This is how other X clients can access the text. Emacs also stores the text in the cut buffer, but only if the text is short enough (`x-cut-buffer-max' specifies the maximum number of characters); putting long strings in the cut buffer can be slow. The commands to yank the first entry in the kill ring actually check first for a primary selection in another program; after that, they check for text in the cut buffer. If neither of those sources provides text to yank, the kill ring contents are used.  File: emacs, Node: Secondary Selection, Next: Mouse References, Prev: Mouse Commands, Up: Frames 15.2 Secondary Selection ======================== The "secondary selection" is another way of selecting text using X. It does not use point or the mark, so you can use it to kill text without setting point or the mark. `M-Drag-Mouse-1' Set the secondary selection, with one end at the place where you press down the button, and the other end at the place where you release it (`mouse-set-secondary'). The highlighting appears and changes as you drag. If you move the mouse off the top or bottom of the window while dragging, the window scrolls at a steady rate until you move the mouse back into the window. This way, you can mark regions that don't fit entirely on the screen. `M-Mouse-1' Set one endpoint for the "secondary selection" (`mouse-start-secondary'). `M-Mouse-3' Make a secondary selection, using the place specified with `M-Mouse-1' as the other end (`mouse-secondary-save-then-kill'). A second click at the same place kills the secondary selection just made. `M-Mouse-2' Insert the secondary selection where you click (`mouse-kill-secondary'). This places point at the end of the yanked text. Double or triple clicking of `M-Mouse-1' operates on words and lines, much like `Mouse-1'. If `mouse-yank-at-point' is non-`nil', `M-Mouse-2' yanks at point. Then it does not matter precisely where you click; all that matters is which window you click on. *Note Mouse Commands::.  File: emacs, Node: Mouse References, Next: Menu Mouse Clicks, Prev: Secondary Selection, Up: Frames 15.3 Following References with the Mouse ======================================== Some Emacs buffers display lists of various sorts. These include lists of files, of buffers, of possible completions, of matches for a pattern, and so on. Since yanking text into these buffers is not very useful, most of them define `Mouse-2' specially, as a command to use or view the item you click on. For example, if you click `Mouse-2' on a file name in a Dired buffer, you visit the that file. If you click `Mouse-2' on an error message in the `*Compilation*' buffer, you go to the source code for that error message. If you click `Mouse-2' on a completion in the `*Completions*' buffer, you choose that completion. You can usually tell when `Mouse-2' has this special sort of meaning because the sensitive text highlights when you move the mouse over it.  File: emacs, Node: Menu Mouse Clicks, Next: Mode Line Mouse, Prev: Mouse References, Up: Frames 15.4 Mouse Clicks for Menus =========================== Mouse clicks modified with the and keys bring up menus. `C-Mouse-1' This menu is for selecting a buffer. `C-Mouse-2' This menu is for specifying faces and other text properties for editing formatted text. *Note Formatted Text::. `C-Mouse-3' This menu is mode-specific. For most modes, this menu has the same items as all the mode-specific menu bar menus put together. Some modes may specify a different menu for this button.(1) `S-mouse-1' This menu is for specifying the frame's default font. ---------- Footnotes ---------- (1) Some systems use `Mouse-3' for a mode-specific menu. We took a survey of users, and found they preferred to keep `Mouse-3' for selecting and killing regions. Hence the decision to use `C-Mouse-3' for this menu.  File: emacs, Node: Mode Line Mouse, Next: Creating Frames, Prev: Menu Mouse Clicks, Up: Frames 15.5 Mode Line Mouse Commands ============================= You can use mouse clicks on window mode lines to select and manipulate windows. `Mouse-1' `Mouse-1' on a mode line selects the window above. By dragging `Mouse-1' on the mode line, you can move it, thus changing the height of the windows above and below. `Mouse-2' `Mouse-2' on a mode line expands that window to fill its frame. `Mouse-3' `Mouse-3' on a mode line deletes the window above. `C-Mouse-2' `C-Mouse-2' on a mode line splits the window above horizontally, above the place in the mode line where you click. `C-Mouse-2' on a scroll bar splits the corresponding window vertically. *Note Split Window::.  File: emacs, Node: Creating Frames, Next: Multiple Displays, Prev: Mode Line Mouse, Up: Frames 15.6 Creating Frames ==================== The prefix key `C-x 5' is analogous to `C-x 4', with parallel subcommands. The difference is that `C-x 5' commands create a new frame rather than just a new window in the selected frame (*Note Pop Up Window::). If an existing visible or iconified frame already displays the requested material, these commands use the existing frame, after raising or deiconifying as necessary. The various `C-x 5' commands differ in how they find or create the buffer to select: `C-x 5 2' Create a new frame (`make-frame'). `C-x 5 b BUFNAME ' Select buffer BUFNAME in another window. This runs `switch-to-buffer-other-frame'. `C-x 5 f FILENAME ' Visit file FILENAME and select its buffer in another frame. This runs `find-file-other-frame'. *Note Visiting::. `C-x 5 d DIRECTORY ' Select a Dired buffer for directory DIRECTORY in another frame. This runs `dired-other-frame'. *Note Dired::. `C-x 5 m' Start composing a mail message in another frame. This runs `mail-other-frame'. It is the other-frame variant of `C-x m'. *Note Sending Mail::. `C-x 5 .' Find a tag in the current tag table in another frame. This runs `find-tag-other-frame', the multiple-frame variant of `M-.'. *Note Tags::. `C-x 5 r FILENAME ' Visit file FILENAME read-only, and select its buffer in another frame. This runs `find-file-read-only-other-frame'. *Note Visiting::. You can control the appearance of new frames you create by setting the frame parameters in `default-frame-alist'. You can use the variable `initial-frame-alist' to specify parameters that affect only the initial frame. *Note Initial Parameters: (elisp)Initial Parameters, for more information.  File: emacs, Node: Multiple Displays, Next: Special Buffer Frames, Prev: Creating Frames, Up: Frames 15.7 Multiple Displays ====================== A single Emacs can talk to more than one X Windows display. Initially, Emacs uses just one display--the one specified with the `DISPLAY' environment variable or with the `--display' option (*note Initial Options::). To connect to another display, use the command `make-frame-on-display': `M-x make-frame-on-display DISPLAY ' Create a new frame on display DISPLAY. A single X server can handle more than one screen. When you open frames on two screens belonging to one server, Emacs knows they share a single keyboard, and it treats all the commands arriving from these screens as a single stream of input. When you open frames on different X servers, Emacs makes a separate input stream for each server. This way, two users can type simultaneously on the two displays, and Emacs will not garble their input. Each server also has its own selected frame. The commands you enter with a particular X server apply to that server's selected frame. Despite these features, people using the same Emacs job from different displays can still interfere with each other if they are not careful. For example, if any one types `C-x C-c', that exits the Emacs job for all of them!  File: emacs, Node: Special Buffer Frames, Next: Frame Parameters, Prev: Multiple Displays, Up: Frames 15.8 Special Buffer Frames ========================== You can make certain chosen buffers, for which Emacs normally creates a second window when you have just one window, appear in special frames of their own. To do this, set the variable `special-display-buffer-names' to a list of buffer names; any buffer whose name is in that list automatically gets a special frame, when an Emacs command wants to display it "in another window." For example, if you set the variable this way, (setq special-display-buffer-names '("*Completions*" "*grep*" "*tex-shell*")) then completion lists, `grep' output and the TeX mode shell buffer get individual frames of their own. These frames, and the windows in them, are never automatically split or reused for any other buffers. They continue to show the buffers they were created for, unless you alter them by hand. Killing the special buffer deletes its frame automatically. More generally, you can set `special-display-regexps' to a list of regular expressions; then a buffer gets its own frame if its name matches any of those regular expressions. (Once again, this applies only to buffers that normally get displayed for you in a separate window.) The variable `special-display-frame-alist' specifies the frame parameters for these frames. It has a default value, so you don't need to set it. For those who know Lisp, an element of `special-display-buffer-names' or `special-display-regexps' can also be a list. Then the first element is the buffer name or regular expression; the rest of the list specifies how to create the frame. It can be an association list specifying frame parameter values; these values take precedence over parameter values specified in `special-display-frame-alist'. Alternatively, it can have this form: (FUNCTION ARGS...) where FUNCTION is a symbol. Then the frame is constructed by calling FUNCTION; its first argument is the buffer, and its remaining arguments are ARGS.  File: emacs, Node: Frame Parameters, Next: Scroll Bars, Prev: Special Buffer Frames, Up: Frames 15.9 Setting Frame Parameters ============================= This section describes commands for altering the display style and window management behavior of the selected frame. `M-x set-foreground-color COLOR ' Specify color COLOR for the foreground of the selected frame. `M-x set-background-color COLOR ' Specify color COLOR for the background of the selected frame. This changes the foreground color of the `modeline' face also, so that it remains in inverse video compared with the default. `M-x set-cursor-color COLOR ' Specify color COLOR for the cursor of the selected frame. `M-x set-mouse-color COLOR ' Specify color COLOR for the mouse cursor when it is over the selected frame. `M-x set-border-color COLOR ' Specify color COLOR for the border of the selected frame. `M-x list-colors-display' Display the defined color names and show what the colors look like. This command is somewhat slow. `M-x auto-raise-mode' Toggle whether or not the selected frame should auto-raise. Auto-raise means that every time you move the mouse onto the frame, it raises the frame. Note that this auto-raise feature is implemented by Emacs itself. Some window managers also implement auto-raise. If you enable auto-raise for Emacs frames in your X window manager, it should work, but it is beyond Emacs's control and therefore `auto-raise-mode' has no effect on it. `M-x auto-lower-mode' Toggle whether or not the selected frame should auto-lower. Auto-lower means that every time you move the mouse off of the frame, the frame moves to the bottom of the stack of X windows. The command `auto-lower-mode' has no effect on auto-lower implemented by the X window manager. To control that, you must use the appropriate window manager features. `M-x set-default-font FONT ' Specify font FONT as the default for the selected frame. *Note Font X::, for ways to list the available fonts on your system. You can also set a frame's default font through a pop-up menu. Press `S-Mouse-1' to activate this menu. In Emacs versions that use an X toolkit, the color-setting and font-setting functions don't affect menus and the menu bar, since they are displayed by their own widget classes. To change the appearance of the menus and menu bar, you must use X resources (*note Resources X::). *Note Colors X::, regarding colors. *Note Font X::, regarding choice of font. For information on frame parameters and customization, see *Note Frame Parameters: (elisp)Frame Parameters.  File: emacs, Node: Scroll Bars, Next: Menu Bars, Prev: Frame Parameters, Up: Frames 15.10 Scroll Bars ================= When using X, Emacs normally makes a "scroll bar" at the right of each Emacs window. The scroll bar runs the height of the window, and shows a moving rectangular inner box which represents the portion of the buffer currently displayed. The entire height of the scroll bar represents the entire length of the buffer. You can use `Mouse-2' (normally, the middle button) in the scroll bar to move or drag the inner box up and down. If you move it to the top of the scroll bar, you see the top of the buffer. If you move it to the bottom of the scroll bar, you see the bottom of the buffer. The left and right buttons in the scroll bar scroll by controlled increments. `Mouse-1' (normally, the left button) moves the line at the level where you click up to the top of the window. `Mouse-3' (normally, the right button) moves the line at the top of the window down to the level where you click. By clicking repeatedly in the same place, you can scroll by the same distance over and over. Aside from scrolling, you can also click `C-Mouse-2' in the scroll bar to split a window vertically. The split occurs on the line where you click. You can enable or disable Scroll Bar mode with the command `M-x scroll-bar-mode'. With no argument, it toggles the use of scroll bars. With an argument, it turns use of scroll bars on if and only if the argument is positive. This command applies to all frames, including frames yet to be created. You can use the X resource `verticalScrollBars' to control the initial setting of Scroll Bar mode. *Note Resources X::. To enable or disable scroll bars for just the selected frame, use the `M-x toggle-scroll-bar' command.  File: emacs, Node: Menu Bars, Next: Faces, Prev: Scroll Bars, Up: Frames 15.11 Menu Bars =============== By default, each Emacs frame has a menu bar at the top which you can use to perform certain common operations. There's no need to describe them in detail here, as you can more easily see for yourself; also, we may change them and add to them in subsequent Emacs versions. When you are using a window system, you can use the mouse to choose a command from the menu bar. On text-only terminals, you can use the menu bar by typing `M-`' (`tmm-menubar'). This enters a mode in which you can select a menu item from the keyboard. Either type the initial of the item you want, or use the left and right arrow keys to choose an item and use to finalize the choice. Each of the operations in the menu bar is bound to an ordinary Emacs command which you can invoke equally well with `M-x' or with its own key bindings. The menu lists one equivalent key binding (if the command has any) at the right margin. To see the command's name and documentation, type `C-h k' and then select the menu bar item you are interested in. You can turn display of menu bars on or off with `M-x menu-bar-mode'. With no argument, this command toggles Menu Bar mode, a minor mode. With an argument, the command turns Menu Bar mode on if the argument is positive, off if the argument is not positive. You can use the X resource `menuBarLines' to control the initial setting of Menu Bar mode. *Note Resources X::. Expert users often turn off the menu bar, especially on text-only terminals where this makes one additional line available for text.  File: emacs, Node: Faces, Next: Modifying Faces, Prev: Menu Bars, Up: Frames 15.12 Using Multiple Typefaces ============================== When using Emacs with X, you can set up multiple styles of displaying characters. The aspects of style that you can control are the type font, the foreground color, the background color, and whether to underline. Emacs on MS-DOS supports faces partially by letting you control the foreground and background colors of each face (*note MS-DOS::). The way you control display style is by defining named "faces". Each face can specify a type font, a foreground color, a background color, and an underline flag; but it does not have to specify all of them. The style of display used for a given character in the text is determined by combining several faces. Any aspect of the display style that isn't specified by overlays or text properties comes from the frame itself. Enriched mode, the mode for editing formatted text, includes several commands and menus for specifying faces. *Note Format Faces::, for how to specify the font for text in the buffer. *Note Format Colors::, for how to specify the foreground and background color. To see what faces are currently defined, and what they look like, type `M-x list-faces-display'. It's possible for a given face to look different in different frames; this command shows the appearance in the frame in which you type it. Here's a list of the standardly defined faces: `default' This face is used for ordinary text that doesn't specify any other face. `modeline' This face is used for mode lines. By default, it's set up as the inverse of the default face. *Note Display Vars::. `highlight' This face is used for highlighting portions of text, in various modes. `region' This face is used for displaying a selected region (when Transient Mark mode is enabled--see below). `secondary-selection' This face is used for displaying a secondary selection (*note Secondary Selection::). `bold' This face uses a bold variant of the default font, if it has one. `italic' This face uses an italic variant of the default font, if it has one. `bold-italic' This face uses a bold italic variant of the default font, if it has one. `underline' This face underlines text. When Transient Mark mode is enabled, the text of the region is highlighted when the mark is active. This uses the face named `region'; you can control the style of highlighting by changing the style of this face (*note Modifying Faces::). *Note Transient Mark::, for more information about Transient Mark mode and activation and deactivation of the mark. One easy way to use faces is to turn on Font Lock mode. This minor mode, which is always local to a particular buffer, arranges to choose faces according to the syntax of the text you are editing. It can recognize comments and strings in most languages; in several languages, it can also recognize and properly highlight various other important constructs. *Note Font Lock::, for more information about Font Lock mode and syntactic highlighting. You can print out the buffer with the highlighting that appears on your screen using the command `ps-print-buffer-with-faces'. *Note Postscript::.  File: emacs, Node: Modifying Faces, Next: Font Lock, Prev: Faces, Up: Frames 15.13 Modifying Faces ===================== Here are the commands for changing the font of a face: `M-x set-face-font FACE FONT ' Change face FACE to use font FONT. *Note Font X::, for more information about font naming under X. `M-x make-face-bold FACE ' Convert face FACE to use a bold version of its current font. `M-x make-face-italic FACE ' Convert face FACE to use a italic version of its current font. `M-x make-face-bold-italic FACE ' Convert face FACE to use a bold-italic version of its current font. `M-x make-face-unbold FACE ' Convert face FACE to use a non-bold version of its current font. `M-x make-face-unitalic FACE ' Convert face FACE to use a non-italic version of its current font. Here are the commands for setting the colors and underline flag of a face: `M-x set-face-foreground FACE COLOR ' Use color COLOR for the foreground of characters in face FACE. `M-x set-face-background FACE COLOR ' Use color COLOR for the background of characters in face FACE. On a black-and-white display, the colors you can use for the background are `black', `white', `gray', `gray1' and `gray3'. Emacs supports the gray colors by using background stipple patterns instead of a color. `M-x set-face-stipple FACE PATTERN ' Use stipple pattern PATTERN for the background of characters in face FACE. `M-x list-colors-display' Display the defined color names and show what the colors look like. `M-x set-face-underline-p FACE FLAG ' Specify whether to underline characters in face FACE. `M-x invert-face FACE ' Swap the foreground and background colors of face FACE. `M-x modify-face FACE ATTRIBUTES...' Change various attributes of face FACE. This command prompts for all the attribute of the face, one attribute at a time. For the color and stipple attributes, the attribute's current value is the default--type just if you don't want to change that attribute. Type `none' if you want to clear out the attribute. You can also use X resources to specify attributes of particular faces. *Note Resources X::.  File: emacs, Node: Font Lock, Next: Support Modes, Prev: Modifying Faces, Up: Frames 15.14 Font Lock mode ==================== Font Lock mode is a minor mode, always local to a particular buffer, which highlights (or "fontifies") using various faces according to the syntax of the text you are editing. It can recognize comments and strings in most languages; in several languages, it can also recognize and properly highlight various other important constructs--for example, names of functions being defined or reserved keywords. The command `M-x font-lock-mode' turns Font Lock mode on or off according to the argument, and toggles the mode when it has no argument. The function `turn-on-font-lock' unconditionally enables Font Lock mode. This is useful in mode-hook functions. For example, to enable Font Lock mode whenever you edit a C file, you can do this: (add-hook 'c-mode-hook 'turn-on-font-lock) To turn on Font Lock mode automatically in all modes which support it, use the function `global-font-lock-mode', like this: (global-font-lock-mode t) In Font Lock mode, when you edit the text, the highlighting updates automatically in the line that you changed. Most changes don't affect the highlighting of subsequent lines, but occasionally they do. To rehighlight a range of lines, use the command `C-M-g' (`font-lock-fontify-block'). In certain major modes, `C-M-g' refontifies the entire current function. (The variable `font-lock-mark-block-function' controls how to find the current function.) In other major modes, `C-M-g' refontifies 16 lines above and below point. With a prefix argument N, `C-M-g' refontifies N lines above and below point, regardless of the mode. To get the full benefit of Font Lock mode, you need to choose a default font which has bold, italic, and bold-italic variants; or else you need to have a color or grayscale screen. The variable `font-lock-display-type' specifies whether Font Lock mode should use font styles, colors, or shades of gray to distinguish the various kinds of text. Emacs chooses the default value according to the characteristics of your display. The variable `font-lock-maximum-decoration' specifies the preferred level of fontification for modes that provide multiple levels. The normal default is 1; larger numbers request more fontification, and some modes support levels as high as 3. These variables can also specify different numbers for particular major modes; for example, to use level 3 for C/C++ modes, and the default level otherwise, use this: (setq font-lock-maximum-decoration '((c-mode . 3) (c++-mode . 3))) Fontification can be too slow for large buffers, so you can suppress it. The variable `font-lock-maximum-size' specifies a buffer size, beyond which buffer fontification is suppressed.  File: emacs, Node: Support Modes, Next: Misc X, Prev: Font Lock, Up: Frames 15.15 Font Lock Support Modes ============================= Font Lock support modes make Font Lock mode faster for large buffers. There are two support modes: Fast Lock mode and Lazy Lock mode. They use two different methods of speeding up Font Lock mode. * Menu: * Fast Lock Mode:: Saving font information in files. * Lazy Lock Mode:: Fontifying only text that is actually displayed. * Fast or Lazy:: Which support mode is best for you?  File: emacs, Node: Fast Lock Mode, Next: Lazy Lock Mode, Up: Support Modes 15.15.1 Fast Lock Mode ---------------------- To make Font Lock mode faster for buffers visiting large files, you can use Fast Lock mode. Fast Lock mode saves the font information for each file in a separate cache file; each time you visit the file, it rereads the font information from the cache file instead of refontifying the text from scratch. The command `M-x fast-lock-mode' turns Fast Lock mode on or off, according to the argument (with no argument, it toggles). You can also arrange to enable Fast Lock mode whenever you use Font Lock mode, like this: (setq font-lock-support-mode 'fast-lock-mode) It is not worth writing a cache file for small buffers. Therefore, the variable `fast-lock-minimum-size' specifies a minimum file size for caching font information. The variable `fast-lock-cache-directories' specifies where to put the cache files. Its value is a list of directories to try; `"."' means the same directory as the file being edited. The default value is `("." "~/.emacs-flc")', which means to use the same directory if possible, and otherwise the directory `~/.emacs-flc'. The variable `fast-lock-save-others' specifies whether Fast Lock mode should save cache files for files that you do not own. A non-`nil' value means yes (and that is the default).  File: emacs, Node: Lazy Lock Mode, Next: Fast or Lazy, Prev: Fast Lock Mode, Up: Support Modes 15.15.2 Lazy Lock Mode ---------------------- To make Font Lock mode faster for large buffers, you can use Lazy Lock mode to reduce the amount of text that is fontified. In Lazy Lock mode, buffer fontification is demand-driven; it happens to portions of the buffer that are about to be displayed. And fontification of your changes is deferred; it happens only when Emacs has been idle for a certain short period of time. The command `M-x lazy-lock-mode' turns Lazy Lock mode on or off, according to the argument (with no argument, it toggles). You can also arrange to enable Lazy Lock mode whenever you use Font Lock mode, like this: (setq font-lock-support-mode 'lazy-lock-mode) It is not worth avoiding buffer fontification for small buffers. Therefore, the variable `lazy-lock-minimum-size' specifies a minimum buffer size for demand-driven buffer fontification. Buffers smaller than that are fontified all at once, as in plain Font Lock mode. When you alter the buffer, Lazy Lock mode defers fontification of the text you changed. The variable `lazy-lock-defer-time' specifies how many seconds Emacs must be idle before it starts fontifying your changes. If the value is `nil', then changes are fontified immediately, as in plain Font Lock mode. Lazy Lock mode normally fontifies newly visible portions of the buffer before they are first displayed. However, if the value of `lazy-lock-defer-driven' is non-`nil', newly visible text is fontified only when Emacs is idle for `lazy-lock-defer-time' seconds. When Emacs is idle for a long time, Lazy Lock fontifies additional portions of the buffer, not yet displayed, in case you will display them later. This is called "stealth fontification". The variable `lazy-lock-stealth-time' specifies how many seconds Emacs has to be idle before stealth fontification starts. A value of `nil' means no stealth fontification. The variables `lazy-lock-stealth-lines' and `lazy-lock-stealth-verbose' specify the granularity and verbosity of stealth fontification.  File: emacs, Node: Fast or Lazy, Prev: Lazy Lock Mode, Up: Support Modes 15.15.3 Fast Lock or Lazy Lock? ------------------------------- Here is a simple guide to help you choose one of the Font Lock support modes. * Fast Lock mode only intervenes during file visiting and buffer killing (and related events); therefore buffer editing and window scrolling are no faster or slower than plain Font Lock mode. * Fast Lock mode is slower at reading a cache file than Lazy Lock mode is at fontifying a window; therefore Fast Lock mode is slower at visiting a file than Lazy Lock mode. * Lazy Lock mode intervenes during window scrolling to fontify text that scrolls onto the screen; therefore, scrolling is slower than in plain Font Lock mode. * Lazy Lock mode doesn't fontify during buffer editing (it defers fontification of changes); therefore, editing is faster than in plain Font Lock mode. * Fast Lock mode can be fooled by a file that is kept under version control software; therefore buffer fontification may occur even when a cache file exists for the file. * Fast Lock mode only works with a buffer visiting a file; Lazy Lock mode works with any buffer. * Fast Lock mode generates cache files; Lazy Lock mode does not. The variable `font-lock-support-mode' specifies which of these support modes to use; for example, to specify that Fast Lock mode is used for C/C++ modes, and Lazy Lock mode otherwise, set the variable like this: (setq font-lock-support-mode '((c-mode . fast-lock-mode) (c++-mode . fast-lock-mode) (t . lazy-lock-mode)))  File: emacs, Node: Misc X, Next: Non-Window Terminals, Prev: Support Modes, Up: Frames 15.16 Miscellaneous X Window Features ===================================== The following commands let you create, delete and operate on frames: `C-z' To iconify the selected Emacs frame, type `C-z' (`iconify-or-deiconify-frame'). The normal meaning of `C-z', to suspend Emacs, is not useful under a window system, so it has a different binding in that case. If you type this command on an Emacs frame's icon, it deiconifies the frame. `C-x 5 0' To delete the selected frame, type `C-x 5 0' (`delete-frame'). This is not allowed if there is only one frame. `C-x 5 o' Select another frame, raise it, and warp the mouse to it so that it stays selected. If you repeat this command, it cycles through all the frames on your terminal. `M-x transient-mark-mode' Under X Windows, when Transient Mark mode is enabled, Emacs highlights the region when the mark is active. This feature is the main motive for using Transient Mark mode. To toggle the state of this mode, use the command `M-x transient-mark-mode'. *Note Mark::.  File: emacs, Node: Non-Window Terminals, Prev: Misc X, Up: Frames 15.17 Non-Window Terminals ========================== If your terminal does not have a window system that Emacs supports, then it can display only one Emacs frame at a time. However, you can still create multiple Emacs frames, and switch between them. Switching frames on these terminals is much like switching between different window configurations. Use `C-x 5 2' to create a new frame and switch to it; use `C-x 5 o' to cycle through the existing frames; use `C-x 5 0' to delete the current frame. Each frame has a number to distinguish it. The selected frame's number appears in the mode line after `Emacs', except when frame 1 is selected.  File: emacs, Node: Major Modes, Next: Indentation, Prev: Frames, Up: Top 16 Major Modes ************** Emacs provides many alternative "major modes", each of which customizes Emacs for editing text of a particular sort. The major modes are mutually exclusive, and each buffer has one major mode at any time. The mode line normally shows the name of the current major mode, in parentheses (*note Mode Line::). The least specialized major mode is called "Fundamental mode". This mode has no mode-specific redefinitions or variable settings, so that each Emacs command behaves in its most general manner, and each option is in its default state. For editing text of a specific type that Emacs knows about, such as Lisp code or English text, you should switch to the appropriate major mode, such as Lisp mode or Text mode. Selecting a major mode changes the meanings of a few keys to become more specifically adapted to the language being edited. The ones which are changed frequently are , , and . The prefix key `C-c' normally contains mode-specific commands. In addition, the commands which handle comments use the mode to determine how comments are to be delimited. Many major modes redefine the syntactical properties of characters appearing in the buffer. *Note Syntax::. The major modes fall into three major groups. Lisp mode (which has several variants), C mode, Fortran mode and others are for specific programming languages. Text mode, Nroff mode, TeX mode and Outline mode are for editing English text. The remaining major modes are not intended for use on users' files; they are used in buffers created for specific purposes by Emacs, such as Dired mode for buffers made by Dired (*note Dired::), and Mail mode for buffers made by `C-x m' (*note Sending Mail::), and Shell mode for buffers used for communicating with an inferior shell process (*note Interactive Shell::). Most programming language major modes specify that only blank lines separate paragraphs. This is to make the paragraph commands useful. (*Note Paragraphs::.) They also cause Auto Fill mode to use the definition of to indent the new lines it creates. This is because most lines in a program are usually indented. (*Note Indentation::.) * Menu: * Choosing Modes:: How major modes are specified or chosen.  File: emacs, Node: Choosing Modes, Prev: Major Modes, Up: Major Modes 16.1 How Major Modes are Chosen =============================== You can select a major mode explicitly for the current buffer, but most of the time Emacs determines which mode to use based on the file name or on special text in the file. Explicit selection of a new major mode is done with a `M-x' command. From the name of a major mode, add `-mode' to get the name of a command to select that mode. Thus, you can enter Lisp mode by executing `M-x lisp-mode'. When you visit a file, Emacs usually chooses the right major mode based on the file's name. For example, files whose names end in `.c' are edited in C mode. The correspondence between file names and major modes is controlled by the variable `auto-mode-alist'. Its value is a list in which each element has this form, (REGEXP . MODE-FUNCTION) or this form, (REGEXP MODE-FUNCTION FLAG) For example, one element normally found in the list has the form `("\\.c\\'" . c-mode)', and it is responsible for selecting C mode for files whose names end in `.c'. (Note that `\\' is needed in Lisp syntax to include a `\' in the string, which is needed to suppress the special meaning of `.' in regexps.) If the element has the form `(REGEXP MODE-FUNCTION FLAG)' and FLAG is non-nil, then after calling FUNCTION, the suffix that matched REGEXP is deleted and the list is searched again for another match. You can specify which major mode should be used for editing a certain file by a special sort of text in the first nonblank line of the file. The mode name should appear in this line both preceded and followed by `-*-'. Other text may appear on the line as well. For example, ;-*-Lisp-*- tells Emacs to use Lisp mode. Such an explicit specification overrides any defaulting based on the file name. Note how the semicolon is used to make Lisp treat this line as a comment. Another format of mode specification is -*-Mode: MODENAME;-*- which allows you to specify local variables as well, like this: -*- mode: MODENAME; VAR: VALUE; ... -*- *Note File Variables::, for more information about this. When a file's contents begin with `#!', it can serve as an executable shell command, which works by running an interpreter named on the file's first line. The rest of the file is used as input to the interpreter. When you visit such a file in Emacs, if the file's name does not specify a major mode, Emacs uses the interpreter name on the first line to choose a mode. If the first line is the name of a recognized interpreter program, such as `perl' or `tcl', Emacs uses a mode appropriate for programs for that interpreter. The variable `interpreter-mode-alist' specifies the correspondence between interpreter program names and major modes. When you visit a file that does not specify a major mode to use, or when you create a new buffer with `C-x b', the variable `default-major-mode' specifies which major mode to use. Normally its value is the symbol `fundamental-mode', which specifies Fundamental mode. If `default-major-mode' is `nil', the major mode is taken from the previously selected buffer. If you change the major mode of a buffer, you can go back to the major mode Emacs would choose automatically: use the command `M-x normal-mode' to do this. This is the same function that `find-file' calls to choose the major mode. It also processes the file's local variables list if any.  File: emacs, Node: Indentation, Next: Text, Prev: Major Modes, Up: Top 17 Indentation ************** This chapter describes the Emacs commands that add, remove, or adjust indentation. `' Indent current line "appropriately" in a mode-dependent fashion. `' Perform followed by (`newline-and-indent'). `M-^' Merge two lines (`delete-indentation'). This would cancel out the effect of . `C-M-o' Split line at point; text on the line after point becomes a new line indented to the same column that it now starts in (`split-line'). `M-m' Move (forward or back) to the first nonblank character on the current line (`back-to-indentation'). `C-M-\' Indent several lines to same column (`indent-region'). `C-x ' Shift block of lines rigidly right or left (`indent-rigidly'). `M-i' Indent from point to the next prespecified tab stop column (`tab-to-tab-stop'). `M-x indent-relative' Indent from point to under an indentation point in the previous line. Most programming languages have some indentation convention. For Lisp code, lines are indented according to their nesting in parentheses. The same general idea is used for C code, though many details are different. Whatever the language, to indent a line, use the command. Each major mode defines this command to perform the sort of indentation appropriate for the particular language. In Lisp mode, aligns the line according to its depth in parentheses. No matter where in the line you are when you type , it aligns the line as a whole. In C mode, implements a subtle and sophisticated indentation style that knows about many aspects of C syntax. In Text mode, runs the command `tab-to-tab-stop', which indents to the next tab stop column. You can set the tab stops with `M-x edit-tab-stops'. * Menu: * Indentation Commands:: Various commands and techniques for indentation. * Tab Stops:: You can set arbitrary "tab stops" and then indent to the next tab stop when you want to. * Just Spaces:: You can request indentation using just spaces.  File: emacs, Node: Indentation Commands, Next: Tab Stops, Prev: Indentation, Up: Indentation 17.1 Indentation Commands and Techniques ======================================== To move over the indentation on a line, do `M-m' (`back-to-indentation'). This command, given anywhere on a line, positions point at the first nonblank character on the line. To insert an indented line before the current line, do `C-a C-o '. To make an indented line after the current line, use `C-e '. If you just want to insert a tab character in the buffer, you can type `C-q '. `C-M-o' (`split-line') moves the text from point to the end of the line vertically down, so that the current line becomes two lines. `C-M-o' first moves point forward over any spaces and tabs. Then it inserts after point a newline and enough indentation to reach the same column point is on. Point remains before the inserted newline; in this regard, `C-M-o' resembles `C-o'. To join two lines cleanly, use the `M-^' (`delete-indentation') command. It deletes the indentation at the front of the current line, and the line boundary as well, replacing them with a single space. As a special case (useful for Lisp code) the single space is omitted if the characters to be joined are consecutive open parentheses or closing parentheses, or if the junction follows another newline. To delete just the indentation of a line, go to the beginning of the line and use `M-\' (`delete-horizontal-space'), which deletes all spaces and tabs around the cursor. If you have a fill prefix, `M-^' deletes the fill prefix if it appears after the newline that is deleted. *Note Fill Prefix::. There are also commands for changing the indentation of several lines at once. `C-M-\' (`indent-region') applies to all the lines that begin in the region; it indents each line in the "usual" way, as if you had typed at the beginning of the line. A numeric argument specifies the column to indent to, and each line is shifted left or right so that its first nonblank character appears in that column. `C-x ' (`indent-rigidly') moves all of the lines in the region right by its argument (left, for negative arguments). The whole group of lines moves rigidly sideways, which is how the command gets its name. `M-x indent-relative' indents at point based on the previous line (actually, the last nonempty line). It inserts whitespace at point, moving point, until it is underneath an indentation point in the previous line. An indentation point is the end of a sequence of whitespace or the end of the line. If point is farther right than any indentation point in the previous line, the whitespace before point is deleted and the first indentation point then applicable is used. If no indentation point is applicable even then, `indent-relative' runs `tab-to-tab-stop' (*note Tab Stops::). `indent-relative' is the definition of in Indented Text mode. *Note Text::. *Note Format Indentation::, for another way of specifying the indentation for part of your text.  File: emacs, Node: Tab Stops, Next: Just Spaces, Prev: Indentation Commands, Up: Indentation 17.2 Tab Stops ============== For typing in tables, you can use Text mode's definition of , `tab-to-tab-stop'. This command inserts indentation before point, enough to reach the next tab stop column. If you are not in Text mode, this command can be found on the key `M-i'. You can specify the tab stops used by `M-i'. They are stored in a variable called `tab-stop-list', as a list of column-numbers in increasing order. The convenient way to set the tab stops is with `M-x edit-tab-stops', which creates and selects a buffer containing a description of the tab stop settings. You can edit this buffer to specify different tab stops, and then type `C-c C-c' to make those new tab stops take effect. In the tab stop buffer, `C-c C-c' runs the function `edit-tab-stops-note-changes' rather than its usual definition `save-buffer'. `edit-tab-stops' records which buffer was current when you invoked it, and stores the tab stops back in that buffer; normally all buffers share the same tab stops and changing them in one buffer affects all, but if you happen to make `tab-stop-list' local in one buffer then `edit-tab-stops' in that buffer will edit the local settings. Here is what the text representing the tab stops looks like for ordinary tab stops every eight columns. : : : : : : 0 1 2 3 4 0123456789012345678901234567890123456789012345678 To install changes, type C-c C-c The first line contains a colon at each tab stop. The remaining lines are present just to help you see where the colons are and know what to do. Note that the tab stops that control `tab-to-tab-stop' have nothing to do with displaying tab characters in the buffer. *Note Display Vars::, for more information on that.  File: emacs, Node: Just Spaces, Prev: Tab Stops, Up: Indentation 17.3 Tabs vs. Spaces ==================== Emacs normally uses both tabs and spaces to indent lines. If you prefer, all indentation can be made from spaces only. To request this, set `indent-tabs-mode' to `nil'. This is a per-buffer variable; altering the variable affects only the current buffer, but there is a default value which you can change as well. *Note Locals::. There are also commands to convert tabs to spaces or vice versa, always preserving the columns of all nonblank text. `M-x tabify' scans the region for sequences of spaces, and converts sequences of at least three spaces to tabs if that can be done without changing indentation. `M-x untabify' changes all tabs in the region to appropriate numbers of spaces.  File: emacs, Node: Text, Next: Programs, Prev: Indentation, Up: Top 18 Commands for Human Languages ******************************* The term "text" has two widespread meanings in our area of the computer field. One is data that is a sequence of characters. Any file that you edit with Emacs is text, in this sense of the word. The other meaning is more restrictive: a sequence of characters in a human language for humans to read (possibly after processing by a text formatter), as opposed to a program or commands for a program. Human languages have syntactic/stylistic conventions that can be supported or used to advantage by editor commands: conventions involving words, sentences, paragraphs, and capital letters. This chapter describes Emacs commands for all of these things. There are also commands for "filling", which means rearranging the lines of a paragraph to be approximately equal in length. The commands for moving over and killing words, sentences and paragraphs, while intended primarily for editing text, are also often useful for editing programs. Emacs has several major modes for editing human language text. If the file contains text pure and simple, use Text mode, which customizes Emacs in small ways for the syntactic conventions of text. Outline mode provides special commands for operating on text with an outline structure. For text which contains embedded commands for text formatters, Emacs has other major modes, each for a particular text formatter. Thus, for input to TeX, you would use TeX mode. For input to nroff, use Nroff mode. Instead of using a text formatter, you can edit formatted text in WYSIWYG style ("what you see is what you get"), with Enriched mode. Then the formatting appears on the screen in Emacs while you edit. * Menu: * Words:: Moving over and killing words. * Sentences:: Moving over and killing sentences. * Paragraphs:: Moving over paragraphs. * Pages:: Moving over pages. * Filling:: Filling or justifying text. * Case:: Changing the case of text. * Text Mode:: The major modes for editing text files. * Outline Mode:: The major mode for editing outlines. * TeX Mode:: The major modes for editing input to the formatter TeX. * Nroff Mode:: The major mode for editing input to the formatter nroff. * Formatted Text::Editing formatted text directly in WYSIWYG fashion.  File: emacs, Node: Words, Next: Sentences, Up: Text 18.1 Words ========== Emacs has commands for moving over or operating on words. By convention, the keys for them are all Meta characters. `M-f' Move forward over a word (`forward-word'). `M-b' Move backward over a word (`backward-word'). `M-d' Kill up to the end of a word (`kill-word'). `M-' Kill back to the beginning of a word (`backward-kill-word'). `M-@' Mark the end of the next word (`mark-word'). `M-t' Transpose two words or drag a word across other words (`transpose-words'). Notice how these keys form a series that parallels the character-based `C-f', `C-b', `C-d', `C-t' and . `M-@' is cognate to `C-@', which is an alias for `C-'. The commands `M-f' (`forward-word') and `M-b' (`backward-word') move forward and backward over words. These Meta characters are thus analogous to the corresponding control characters, `C-f' and `C-b', which move over single characters in the text. The analogy extends to numeric arguments, which serve as repeat counts. `M-f' with a negative argument moves backward, and `M-b' with a negative argument moves forward. Forward motion stops right after the last letter of the word, while backward motion stops right before the first letter. `M-d' (`kill-word') kills the word after point. To be precise, it kills everything from point to the place `M-f' would move to. Thus, if point is in the middle of a word, `M-d' kills just the part after point. If some punctuation comes between point and the next word, it is killed along with the word. (If you wish to kill only the next word but not the punctuation before it, simply do `M-f' to get the end, and kill the word backwards with `M-'.) `M-d' takes arguments just like `M-f'. `M-' (`backward-kill-word') kills the word before point. It kills everything from point back to where `M-b' would move to. If point is after the space in `FOO, BAR', then `FOO, ' is killed. (If you wish to kill just `FOO', do `M-b M-d' instead of `M-'.) `M-t' (`transpose-words') exchanges the word before or containing point with the following word. The delimiter characters between the words do not move. For example, `FOO, BAR' transposes into `BAR, FOO' rather than `BAR FOO,'. *Note Transpose::, for more on transposition and on arguments to transposition commands. To operate on the next N words with an operation which applies between point and mark, you can either set the mark at point and then move over the words, or you can use the command `M-@' (`mark-word') which does not move point, but sets the mark where `M-f' would move to. `M-@' accepts a numeric argument that says how many words to scan for the place to put the mark. In Transient Mark mode, this command activates the mark. The word commands' understanding of syntax is completely controlled by the syntax table. Any character can, for example, be declared to be a word delimiter. *Note Syntax::.  File: emacs, Node: Sentences, Next: Paragraphs, Prev: Words, Up: Text 18.2 Sentences ============== The Emacs commands for manipulating sentences and paragraphs are mostly on Meta keys, so as to be like the word-handling commands. `M-a' Move back to the beginning of the sentence (`backward-sentence'). `M-e' Move forward to the end of the sentence (`forward-sentence'). `M-k' Kill forward to the end of the sentence (`kill-sentence'). `C-x ' Kill back to the beginning of the sentence (`backward-kill-sentence'). The commands `M-a' and `M-e' (`backward-sentence' and `forward-sentence') move to the beginning and end of the current sentence, respectively. They were chosen to resemble `C-a' and `C-e', which move to the beginning and end of a line. Unlike them, `M-a' and `M-e' if repeated or given numeric arguments move over successive sentences. Moving backward over a sentence places point just before the first character of the sentence; moving forward places point right after the punctuation that ends the sentence. Neither one moves over the whitespace at the sentence boundary. Just as `C-a' and `C-e' have a kill command, `C-k', to go with them, so `M-a' and `M-e' have a corresponding kill command `M-k' (`kill-sentence') which kills from point to the end of the sentence. With minus one as an argument it kills back to the beginning of the sentence. Larger arguments serve as a repeat count. There is also a command, `C-x ' (`backward-kill-sentence'), for killing back to the beginning of a sentence. This command is useful when you change your mind in the middle of composing text. The sentence commands assume that you follow the American typist's convention of putting two spaces at the end of a sentence; they consider a sentence to end wherever there is a `.', `?' or `!' followed by the end of a line or two spaces, with any number of `)', `]', `'', or `"' characters allowed in between. A sentence also begins or ends wherever a paragraph begins or ends. The variable `sentence-end' controls recognition of the end of a sentence. It is a regexp that matches the last few characters of a sentence, together with the whitespace following the sentence. Its normal value is "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" This example is explained in the section on regexps. *Note Regexps::. If you want to use just one space between sentences, you should set `sentence-end' to this value: "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" You should also set the variable `sentence-end-double-space' to `nil' so that the fill commands expect and leave just one space at the end of a sentence. Note that this makes it impossible to distinguish between periods that end sentences and those that indicate abbreviations.  File: emacs, Node: Paragraphs, Next: Pages, Prev: Sentences, Up: Text 18.3 Paragraphs =============== The Emacs commands for manipulating paragraphs are also Meta keys. `M-{' Move back to previous paragraph beginning (`backward-paragraph'). `M-}' Move forward to next paragraph end (`forward-paragraph'). `M-h' Put point and mark around this or next paragraph (`mark-paragraph'). `M-{' moves to the beginning of the current or previous paragraph, while `M-}' moves to the end of the current or next paragraph. Blank lines and text formatter command lines separate paragraphs and are not considered part of any paragraph. Also, an indented line starts a new paragraph. In major modes for programs (as opposed to Text mode), paragraphs begin and end only at blank lines. This makes the paragraph commands continue to be useful even though there are no paragraphs per se. When there is a fill prefix, then paragraphs are delimited by all lines which don't start with the fill prefix. *Note Filling::. When you wish to operate on a paragraph, you can use the command `M-h' (`mark-paragraph') to set the region around it. Thus, for example, `M-h C-w' kills the paragraph around or after point. The `M-h' command puts point at the beginning and mark at the end of the paragraph point was in. In Transient Mark mode, it activates the mark. If point is between paragraphs (in a run of blank lines, or at a boundary), the paragraph following point is surrounded by point and mark. If there are blank lines preceding the first line of the paragraph, one of these blank lines is included in the region. The precise definition of a paragraph boundary is controlled by the variables `paragraph-separate' and `paragraph-start'. The value of `paragraph-start' is a regexp that should match any line that either starts or separates paragraphs. The value of `paragraph-separate' is another regexp that should match only lines that separate paragraphs without being part of any paragraph. Lines that start a new paragraph and are contained in it must match only `paragraph-start', not `paragraph-separate'. For example, normally `paragraph-start' is `"[ \t\n\f]"' and `paragraph-separate' is `"[ \t\f]*$"'. Normally it is desirable for page boundaries to separate paragraphs. The default values of these variables recognize the usual separator for pages.  File: emacs, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text 18.4 Pages ========== Files are often thought of as divided into "pages" by the "formfeed" character (ASCII control-L, octal code 014). When you print hardcopy for a file, this character forces a page break; thus, each page of the file goes on a separate page on paper. Most Emacs commands treat the page-separator character just like any other character: you can insert it with `C-q C-l', and delete it with . Thus, you are free to paginate your file or not. However, since pages are often meaningful divisions of the file, Emacs provides commands to move over them and operate on them. `C-x [' Move point to previous page boundary (`backward-page'). `C-x ]' Move point to next page boundary (`forward-page'). `C-x C-p' Put point and mark around this page (or another page) (`mark-page'). `C-x l' Count the lines in this page (`count-lines-page'). The `C-x [' (`backward-page') command moves point to immediately after the previous page delimiter. If point is already right after a page delimiter, it skips that one and stops at the previous one. A numeric argument serves as a repeat count. The `C-x ]' (`forward-page') command moves forward past the next page delimiter. The `C-x C-p' command (`mark-page') puts point at the beginning of the current page and the mark at the end. The page delimiter at the end is included (the mark follows it). The page delimiter at the front is excluded (point follows it). `C-x C-p C-w' is a handy way to kill a page to move it elsewhere. If you move to another page delimiter with `C-x [' and `C-x ]', then yank the killed page, all the pages will be properly delimited once again. The reason `C-x C-p' includes only the following page delimiter in the region is to ensure that. A numeric argument to `C-x C-p' is used to specify which page to go to, relative to the current one. Zero means the current page. One means the next page, and -1 means the previous one. The `C-x l' command (`count-lines-page') is good for deciding where to break a page in two. It prints in the echo area the total number of lines in the current page, and then divides it up into those preceding the current line and those following, as in Page has 96 (72+25) lines Notice that the sum is off by one; this is correct if point is not at the beginning of a line. The variable `page-delimiter' controls where pages begin. Its value is a regexp that matches the beginning of a line that separates pages. The normal value of this variable is `"^\f"', which matches a formfeed character at the beginning of a line.  File: emacs, Node: Filling, Next: Case, Prev: Pages, Up: Text 18.5 Filling Text ================= "Filling" text means breaking it up into lines that fit a specified width. Emacs does filling in two ways. In Auto Fill mode, inserting text with self-inserting characters also automatically fills it. There are also explicit fill commands that you can use when editing text leaves it unfilled. When you edit formatted text, you can specify a style of filling for each portion of the text (*note Formatted Text::). * Menu: * Auto Fill:: Auto Fill mode breaks long lines automatically. * Fill Commands:: Commands to refill paragraphs and center lines. * Fill Prefix:: Filling when every line is indented or in a comment, etc.  File: emacs, Node: Auto Fill, Next: Fill Commands, Up: Filling 18.5.1 Auto Fill Mode --------------------- "Auto Fill" mode is a minor mode in which lines are broken automatically when they become too wide. Breaking happens only when you type a or . `M-x auto-fill-mode' Enable or disable Auto Fill mode. `' `' In Auto Fill mode, break lines when appropriate. `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off if it was on. With a positive numeric argument it always turns Auto Fill mode on, and with a negative argument always turns it off. You can see when Auto Fill mode is in effect by the presence of the word `Fill' in the mode line, inside the parentheses. Auto Fill mode is a minor mode which is enabled or disabled for each buffer individually. *Note Minor Modes::. In Auto Fill mode, lines are broken automatically at spaces when they get longer than the desired width. Line breaking and rearrangement takes place only when you type or . If you wish to insert a space or newline without permitting line-breaking, type `C-q ' or `C-q ' (recall that a newline is really a linefeed). Also, `C-o' inserts a newline without line breaking. Auto Fill mode works well with Lisp mode, because when it makes a new line in Lisp mode it indents that line with . If a line ending in a comment gets too long, the text of the comment is split into two comment lines. Optionally new comment delimiters are inserted at the end of the first line and the beginning of the second so that each line is a separate comment; the variable `comment-multi-line' controls the choice (*note Comments::). Adaptive filling (see the following section) works for Auto Filling as well as for explicit fill commands. It takes a fill prefix automatically from the second or first line of a paragraph. Auto Fill mode does not refill entire paragraphs; it can break lines but cannot merge lines. So editing in the middle of a paragraph can result in a paragraph that is not correctly filled. The easiest way to make the paragraph properly filled again is usually with the explicit fill commands. *Note Fill Commands::. Many users like Auto Fill mode and want to use it in all text files. The section on init files says how to arrange this permanently for yourself. *Note Init File::.  File: emacs, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling 18.5.2 Explicit Fill Commands ----------------------------- `M-q' Fill current paragraph (`fill-paragraph'). `C-x f' Set the fill column (`set-fill-column'). `M-x fill-region' Fill each paragraph in the region (`fill-region'). `M-x fill-region-as-paragraph.' Fill the region, considering it as one paragraph. `M-s' Center a line. To refill a paragraph, use the command `M-q' (`fill-paragraph'). This operates on the paragraph that point is inside, or the one after point if point is between paragraphs. Refilling works by removing all the line-breaks, then inserting new ones where necessary. To refill many paragraphs, use `M-x fill-region', which divides the region into paragraphs and fills each of them. `M-q' and `fill-region' use the same criteria as `M-h' for finding paragraph boundaries (*note Paragraphs::). For more control, you can use `M-x fill-region-as-paragraph', which refills everything between point and mark. This command deletes any blank lines within the region, so separate blocks of text end up combined into one block. A numeric argument to `M-q' causes it to "justify" the text as well as filling it. This means that extra spaces are inserted to make the right margin line up exactly at the fill column. To remove the extra spaces, use `M-q' with no argument. (Likewise for `fill-region'.) Another way to control justification, and choose other styles of filling, is with the `justification' text property; see *Note Format Justification::. The fill commands can deduce the proper fill prefix for a paragraph automatically in certain cases: either whitespace or certain punctuation characters at the beginning of a line are treated as a fill prefix. They take the fill prefix from the paragraph's second line, unless the paragraph has just one line. You can turn off this feature by setting `adaptive-fill-mode' to `nil'. Some major modes, including Text mode, treat whitespace at the beginning of a line as a signal that this line starts a new paragraph. It would be a mistake to copy text which implies the start of a paragraph onto each line of the paragraph when filling it. Therefore, adaptive filling does not accept a fill prefix from a line which is a paragraph-starter. In particular, adaptive filling in Text mode does not accept a fill prefix consisting of just whitespace. However, other modes including Indented Text mode (*note Text Mode::) do not consider whitespace as a signal to start a new paragraph. In these modes, adaptive filling does accept a fill prefix consisting of just whitespace, if the first or second line of a paragraph begins with whitespace. The variable `adaptive-fill-regexp' determines what kinds of line beginnings can serve as a fill prefix: any characters at the start of the line which match this regular expression are used. You can specify more complex ways of choosing a fill prefix automatically by setting the variable `adaptive-fill-function' to a function. This function is called with point after the left margin of a line, and it should return the appropriate fill prefix based on that line. If it returns `nil', that means it sees no fill prefix in that line. The command `M-s' (`center-line') centers the current line within the current fill column. With an argument N, it centers N lines individually and moves past them. The maximum line width for filling is in the variable `fill-column'. Altering the value of `fill-column' makes it local to the current buffer; until that time, the default value is in effect. The default is initially 70. *Note Locals::. The easiest way to set `fill-column' is to use the command `C-x f' (`set-fill-column'). With a numeric argument, it uses that as the new fill column. With just `C-u' as argument, it sets `fill-column' to the current horizontal position of point. Emacs commands normally consider a period followed by two spaces or by a newline as the end of a sentence; a period followed by just one space indicates an abbreviation and not the end of a sentence. To preserve the distinction between these two ways of using a period, the fill commands do not break a line after a period followed by just one space. If the variable `sentence-end-double-space' is `nil', the fill commands expect and leave just one space at the end of a sentence. Ordinarily this variable is `t', so the fill commands insist on two spaces for the end of a sentence, as explained above. *Note Sentences::. If the variable `colon-double-space' is non-`nil', the fill commands put two spaces after a colon.  File: emacs, Node: Fill Prefix, Prev: Fill Commands, Up: Filling 18.5.3 The Fill Prefix ---------------------- To fill a paragraph in which each line starts with a special marker (which might be a few spaces, giving an indented paragraph), use the "fill prefix" feature. The fill prefix is a string which Emacs expects every line to start with, and which is not included in filling. `C-x .' Set the fill prefix (`set-fill-prefix'). `M-q' Fill a paragraph using current fill prefix (`fill-paragraph'). `M-x fill-individual-paragraphs' Fill the region, considering each change of indentation as starting a new paragraph. `M-x fill-nonuniform-paragraphs' Fill the region, considering only paragraph-separator lines as starting a new paragraph. To specify a fill prefix, move to a line that starts with the desired prefix, put point at the end of the prefix, and give the command `C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn off the fill prefix, specify an empty prefix: type `C-x .' with point at the beginning of a line. When a fill prefix is in effect, the fill commands remove the fill prefix from each line before filling and insert it on each line after filling. Auto Fill mode also inserts the fill prefix automatically when it makes a new line. The `C-o' command inserts the fill prefix on new lines it creates, when you use it at the beginning of a line (*note Blank Lines::). Conversely, the command `M-^' deletes the prefix (if it occurs) after the newline that it deletes (*note Indentation::). For example, if `fill-column' is 40 and you set the fill prefix to `;; ', then `M-q' in the following text ;; This is an ;; example of a paragraph ;; inside a Lisp-style comment. produces this: ;; This is an example of a paragraph ;; inside a Lisp-style comment. Lines that do not start with the fill prefix are considered to start paragraphs, both in `M-q' and the paragraph commands; this gives good results for paragraphs with hanging indentation (every line indented except the first one). Lines which are blank or indented once the prefix is removed also separate or start paragraphs; this is what you want if you are writing multi-paragraph comments with a comment delimiter on each line. You can use `M-x fill-individual-paragraphs' to set the fill prefix for each paragraph automatically. This command divides the region into paragraphs, treating every change in the amount of indentation as the start of a new paragraph, and fills each of these paragraphs. Thus, all the lines in one "paragraph" have the same amount of indentation. That indentation serves as the fill prefix for that paragraph. `M-x fill-nonuniform-paragraphs' is a similar command that divides the region into paragraphs in a different way. It considers only paragraph-separating lines (as defined by `paragraph-separate') as starting a new paragraph. Since this means that the lines of one paragraph may have different amounts of indentation, the fill prefix used is the smallest amount of indentation of any of the lines of the paragraph. This gives good results with styles that indent a paragraph's first line more or less that the rest of the paragraph. The fill prefix is stored in the variable `fill-prefix'. Its value is a string, or `nil' when there is no fill prefix. This is a per-buffer variable; altering the variable affects only the current buffer, but there is a default value which you can change as well. *Note Locals::. The `indentation' text property provides another way to control the amount of indentation paragraphs receive. *Note Format Indentation::.  File: emacs, Node: Case, Next: Text Mode, Prev: Filling, Up: Text 18.6 Case Conversion Commands ============================= Emacs has commands for converting either a single word or any arbitrary range of text to upper case or to lower case. `M-l' Convert following word to lower case (`downcase-word'). `M-u' Convert following word to upper case (`upcase-word'). `M-c' Capitalize the following word (`capitalize-word'). `C-x C-l' Convert region to lower case (`downcase-region'). `C-x C-u' Convert region to upper case (`upcase-region'). The word conversion commands are the most useful. `M-l' (`downcase-word') converts the word after point to lower case, moving past it. Thus, repeating `M-l' converts successive words. `M-u' (`upcase-word') converts to all capitals instead, while `M-c' (`capitalize-word') puts the first letter of the word into upper case and the rest into lower case. All these commands convert several words at once if given an argument. They are especially convenient for converting a large amount of text from all upper case to mixed case, because you can move through the text using `M-l', `M-u' or `M-c' on each word as appropriate, occasionally using `M-f' instead to skip a word. When given a negative argument, the word case conversion commands apply to the appropriate number of words before point, but do not move point. This is convenient when you have just typed a word in the wrong case: you can give the case conversion command and continue typing. If a word case conversion command is given in the middle of a word, it applies only to the part of the word which follows point. This is just like what `M-d' (`kill-word') does. With a negative argument, case conversion applies only to the part of the word before point. The other case conversion commands are `C-x C-u' (`upcase-region') and `C-x C-l' (`downcase-region'), which convert everything between point and mark to the specified case. Point and mark do not move. The region case conversion commands `upcase-region' and `downcase-region' are normally disabled. This means that they ask for confirmation if you try to use them. When you confirm, you may enable the command, which means it will not ask for confirmation again. *Note Disabling::.  File: emacs, Node: Text Mode, Next: Outline Mode, Prev: Case, Up: Text 18.7 Text Mode ============== When you edit files of text in a human language, it's more convenient to use Text mode rather than Fundamental mode. Invoke `M-x text-mode' to enter Text mode. In Text mode, runs the function `tab-to-tab-stop', which allows you to use arbitrary tab stops set with `M-x edit-tab-stops' (*note Tab Stops::). Features concerned with comments in programs are turned off in Text mode except when explicitly invoked. The syntax table is changed so that periods are not considered part of a word, while apostrophes, backspaces and underlines are part of words. A similar variant mode is Indented Text mode, intended for editing text in which most lines are indented. This mode defines to run `indent-relative' (*note Indentation::), and makes Auto Fill indent the lines it creates. The result is that normally a line made by Auto Filling, or by , is indented just like the previous line. In Indented Text mode, only blank lines separate paragraphs--indented lines continue the current paragraph. Use `M-x indented-text-mode' to select this mode. Text mode, and all the modes based on it, define `M-' as the command `ispell-complete-word', which performs completion of the partial word in the buffer before point, using the spelling dictionary as the space of possible words. *Note Spelling::. Entering Text mode or Indented Text mode runs the hook `text-mode-hook'. Other major modes related to Text mode also run this hook, followed by hooks of their own; this includes Nroff mode, TeX mode, Outline mode and Mail mode. Hook functions on `text-mode-hook' can look at the value of `major-mode' to see which of these modes is actually being entered. *Note Hooks::. Emacs provides two other modes for editing text that is to be passed through a text formatter to produce fancy formatted printed output. *Note Nroff Mode::, for editing input to the formatter nroff. *Note TeX Mode::, for editing input to the formatter TeX. Another mode is used for editing outlines. It allows you to view the text at various levels of detail. You can view either the outline headings alone or both headings and text; you can also hide some of the headings at lower levels from view to make the high level structure more visible. *Note Outline Mode::.  File: emacs, Node: Outline Mode, Next: TeX Mode, Prev: Text Mode, Up: Text 18.8 Outline Mode ================= Outline mode is a major mode much like Text mode but intended for editing outlines. It allows you to make parts of the text temporarily invisible so that you can see the outline structure. Type `M-x outline-mode' to switch to Outline mode as the major mode of the current buffer. When Outline mode makes a line invisible, the line does not appear on the screen. The screen appears exactly as if the invisible line were deleted, except that an ellipsis (three periods in a row) appears at the end of the previous visible line (only one ellipsis no matter how many invisible lines follow). All editing commands treat the text of the invisible line as part of the previous visible line. For example, `C-n' moves onto the next visible line. Killing an entire visible line, including its terminating newline, really kills all the following invisible lines along with it; yanking it all back yanks the invisible lines and they remain invisible. Outline minor mode provides the same commands as the major mode, Outline mode, but you can use it in conjunction with other major modes. Type `M-x outline-minor-mode' to enable the Outline minor mode in the current buffer. You can also specify this in the text of a file, with a file local variable of the form `mode: outline-minor' (*note File Variables::). The major mode, Outline mode, provides special key bindings on the `C-c' prefix. Outline minor mode provides similar bindings with `C-c @' as the prefix; this is to reduce the conflicts with the major mode's special commands. (The variable `outline-minor-mode-prefix' controls the prefix used.) Entering Outline mode runs the hook `text-mode-hook' followed by the hook `outline-mode-hook' (*note Hooks::). * Menu: * Format: Outline Format. What the text of an outline looks like. * Motion: Outline Motion. Special commands for moving through outlines. * Visibility: Outline Visibility. Commands to control what is visible. * Views: Outline Views. Outlines and multiple views.  File: emacs, Node: Outline Format, Next: Outline Motion, Up: Outline Mode 18.8.1 Format of Outlines ------------------------- Outline mode assumes that the lines in the buffer are of two types: "heading lines" and "body lines". A heading line represents a topic in the outline. Heading lines start with one or more stars; the number of stars determines the depth of the heading in the outline structure. Thus, a heading line with one star is a major topic; all the heading lines with two stars between it and the next one-star heading are its subtopics; and so on. Any line that is not a heading line is a body line. Body lines belong with the preceding heading line. Here is an example: * Food This is the body, which says something about the topic of food. ** Delicious Food This is the body of the second-level header. ** Distasteful Food This could have a body too, with several lines. *** Dormitory Food * Shelter Another first-level topic with its header line. A heading line together with all following body lines is called collectively an "entry". A heading line together with all following deeper heading lines and their body lines is called a "subtree". You can customize the criterion for distinguishing heading lines by setting the variable `outline-regexp'. Any line whose beginning has a match for this regexp is considered a heading line. Matches that start within a line (not at the left margin) do not count. The length of the matching text determines the level of the heading; longer matches make a more deeply nested level. Thus, for example, if a text formatter has commands `@chapter', `@section' and `@subsection' to divide the document into chapters and sections, you could make those lines count as heading lines by setting `outline-regexp' to `"@chap\\|@\\(sub\\)*section"'. Note the trick: the two words `chapter' and `section' are equally long, but by defining the regexp to match only `chap' we ensure that the length of the text matched on a chapter heading is shorter, so that Outline mode will know that sections are contained in chapters. This works as long as no other command starts with `@chap'. It is possible to change the rule for calculating the level of a heading line by setting the variable `outline-level'. The value of `outline-level' should be a function that takes no arguments and returns the level of the current heading. Some major modes such as C, Nroff, and Emacs Lisp mode set this variable in order to work with Outline minor mode. Outline mode makes a line invisible by changing the newline before it into an ASCII control-M (code 015). Most editing commands that work on lines treat an invisible line as part of the previous line because, strictly speaking, it _is_ part of that line, since there is no longer a newline in between. When you save the file in Outline mode, control-M characters are saved as newlines, so the invisible lines become ordinary lines in the file. But saving does not change the visibility status of a line inside Emacs.  File: emacs, Node: Outline Motion, Next: Outline Visibility, Prev: Outline Format, Up: Outline Mode 18.8.2 Outline Motion Commands ------------------------------ Outline mode provides special motion commands that move backward and forward to heading lines. `C-c C-n' Move point to the next visible heading line (`outline-next-visible-heading'). `C-c C-p' Move point to the previous visible heading line (`outline-previous-visible-heading'). `C-c C-f' Move point to the next visible heading line at the same level as the one point is on (`outline-forward-same-level'). `C-c C-b' Move point to the previous visible heading line at the same level (`outline-backward-same-level'). `C-c C-u' Move point up to a lower-level (more inclusive) visible heading line (`outline-up-heading'). `C-c C-n' (`outline-next-visible-heading') moves down to the next heading line. `C-c C-p' (`outline-previous-visible-heading') moves similarly backward. Both accept numeric arguments as repeat counts. The names emphasize that invisible headings are skipped, but this is not really a special feature. All editing commands that look for lines ignore the invisible lines automatically. More powerful motion commands understand the level structure of headings. `C-c C-f' (`outline-forward-same-level') and `C-c C-b' (`outline-backward-same-level') move from one heading line to another visible heading at the same depth in the outline. `C-c C-u' (`outline-up-heading') moves backward to another heading that is less deeply nested.  File: emacs, Node: Outline Visibility, Next: Outline Views, Prev: Outline Motion, Up: Outline Mode 18.8.3 Outline Visibility Commands ---------------------------------- The other special commands of outline mode are used to make lines visible or invisible. Their names all start with `hide' or `show'. Most of them fall into pairs of opposites. They are not undoable; instead, you can undo right past them. Making lines visible or invisible is simply not recorded by the undo mechanism. `C-c C-t' Make all body lines in the buffer invisible (`hide-body'). `C-c C-a' Make all lines in the buffer visible (`show-all'). `C-c C-d' Make everything under this heading invisible, not including this heading itself (`hide-subtree'). `C-c C-s' Make everything under this heading visible, including body, subheadings, and their bodies (`show-subtree'). `C-c C-l' Make the body of this heading line, and of all its subheadings, invisible (`hide-leaves'). `C-c C-k' Make all subheadings of this heading line, at all levels, visible (`show-branches'). `C-c C-i' Make immediate subheadings (one level down) of this heading line visible (`show-children'). `C-c C-c' Make this heading line's body invisible (`hide-entry'). `C-c C-e' Make this heading line's body visible (`show-entry'). `C-c C-q' Hide everything except the top N levels of heading lines (`hide-sublevels'). `C-c C-o' Hide everything except for the heading or body that point is in, plus the headings leading up from there to the top level of the outline (`hide-other'). Two commands that are exact opposites are `C-c C-c' (`hide-entry') and `C-c C-e' (`show-entry'). They are used with point on a heading line, and apply only to the body lines of that heading. Subheadings and their bodies are not affected. Two more powerful opposites are `C-c C-d' (`hide-subtree') and `C-c C-s' (`show-subtree'). Both expect to be used when point is on a heading line, and both apply to all the lines of that heading's "subtree": its body, all its subheadings, both direct and indirect, and all of their bodies. In other words, the subtree contains everything following this heading line, up to and not including the next heading of the same or higher rank. Intermediate between a visible subtree and an invisible one is having all the subheadings visible but none of the body. There are two commands for doing this, depending on whether you want to hide the bodies or make the subheadings visible. They are `C-c C-l' (`hide-leaves') and `C-c C-k' (`show-branches'). A little weaker than `show-branches' is `C-c C-i' (`show-children'). It makes just the direct subheadings visible--those one level down. Deeper subheadings remain invisible, if they were invisible. Two commands have a blanket effect on the whole file. `C-c C-t' (`hide-body') makes all body lines invisible, so that you see just the outline structure. `C-c C-a' (`show-all') makes all lines visible. These commands can be thought of as a pair of opposites even though `C-c C-a' applies to more than just body lines. The command `C-c C-q' (`hide-sublevels') hides all but the top level headings. With a numeric argument N, it hides everything except the top N levels of heading lines. The command `C-c C-o' (`hide-other') hides everything except the heading or body text that point is in, plus its parents (the headers leading up from there to top level in the outline). You can turn off the use of ellipses at the ends of visible lines by setting `selective-display-ellipses' to `nil'. Then there is no visible indication of the presence of invisible lines.  File: emacs, Node: Outline Views, Prev: Outline Visibility, Up: Outline Mode 18.8.4 Viewing One Outline in Multiple Views -------------------------------------------- You can display two views of a single outline at the same time, in different windows, by means of an alternative implementation of Outline mode called `noutline'. To do this, first load the library `noutline' with `M-x load-library noutline '. This loads the alternative implementation of Outline mode. It provides the same command names and key bindings as regular Outline mode, but it implements them differently. Then, to display a second view of an outline buffer, you must create an indirect buffer using `M-x make-indirect-buffer'. The first argument of this command is the existing outline buffer name, and its second argument is the name to use for the new indirect buffer. *Note Indirect Buffers::. Once the indirect buffer exists, you can display it in a window in the normal fashion, with `C-x 4 b' or other Emacs commands. The Outline mode commands to show and hide parts of the text operate on each buffer independently; as a result, each buffer can have its own view. If you want more than two views on the same outline, create additional indirect buffers. In a future Emacs version, the alternative `noutline' implementation will probably become the principal implementation.  File: emacs, Node: TeX Mode, Next: Nroff Mode, Prev: Outline Mode, Up: Text 18.9 TeX Mode ============= TeX is a powerful text formatter written by Donald Knuth; it is also free, like GNU Emacs. LaTeX is a simplified input format for TeX, implemented by TeX macros; it comes with TeX. SliTeX is a special form of LaTeX. Emacs has a special TeX mode for editing TeX input files. It provides facilities for checking the balance of delimiters and for invoking TeX on all or part of the file. TeX mode has three variants, Plain TeX mode, LaTeX mode, and SliTeX mode (these three distinct major modes differ only slightly). They are designed for editing the three different formats. The command `M-x tex-mode' looks at the contents of the buffer to determine whether the contents appear to be either LaTeX input or SliTeX input; if so, it selects the appropriate mode. If the file contents do not appear to be LaTeX or SliTeX, it selects Plain TeX mode. If the contents are insufficient to determine this, the variable `tex-default-mode' controls which mode is used. When `M-x tex-mode' does not guess right, you can use the commands `M-x plain-tex-mode', `M-x latex-mode', and `M-x slitex-mode' to select explicitly the particular variants of TeX mode. * Menu: * Editing: TeX Editing. Special commands for editing in TeX mode. * LaTeX: LaTeX Editing. Additional commands for LaTeX input files. * Printing: TeX Print. Commands for printing part of a file with TeX. * Getting: TeX Distrib. Getting the latest Unix TeX distribution.  File: emacs, Node: TeX Editing, Next: LaTeX Editing, Up: TeX Mode 18.9.1 TeX Editing Commands --------------------------- Here are the special commands provided in TeX mode for editing the text of the file. `"' Insert, according to context, either ```' or `"' or `''' (`tex-insert-quote'). `' Insert a paragraph break (two newlines) and check the previous paragraph for unbalanced braces or dollar signs (`tex-terminate-paragraph'). `M-x validate-tex-region' Check each paragraph in the region for unbalanced braces or dollar signs. `C-c {' Insert `{}' and position point between them (`tex-insert-braces'). `C-c }' Move forward past the next unmatched close brace (`up-list'). In TeX, the character `"' is not normally used; we use ```' to start a quotation and `''' to end one. To make editing easier under this formatting convention, TeX mode overrides the normal meaning of the key `"' with a command that inserts a pair of single-quotes or backquotes (`tex-insert-quote'). To be precise, this command inserts ```' after whitespace or an open brace, `"' after a backslash, and `''' after any other character. If you need the character `"' itself in unusual contexts, use `C-q' to insert it. Also, `"' with a numeric argument always inserts that number of `"' characters. In TeX mode, `$' has a special syntax code which attempts to understand the way TeX math mode delimiters match. When you insert a `$' that is meant to exit math mode, the position of the matching `$' that entered math mode is displayed for a second. This is the same feature that displays the open brace that matches a close brace that is inserted. However, there is no way to tell whether a `$' enters math mode or leaves it; so when you insert a `$' that enters math mode, the previous `$' position is shown as if it were a match, even though they are actually unrelated. TeX uses braces as delimiters that must match. Some users prefer to keep braces balanced at all times, rather than inserting them singly. Use `C-c {' (`tex-insert-braces') to insert a pair of braces. It leaves point between the two braces so you can insert the text that belongs inside. Afterward, use the command `C-c }' (`up-list') to move forward past the close brace. There are two commands for checking the matching of braces. (`tex-terminate-paragraph') checks the paragraph before point, and inserts two newlines to start a new paragraph. It prints a message in the echo area if any mismatch is found. `M-x validate-tex-region' checks a region, paragraph by paragraph. When it finds a paragraph that contains a mismatch, it displays point at the beginning of the paragraph for a few seconds and sets the mark at that spot. Scanning continues until the whole buffer has been checked or until you type another key. Afterward, you can use the mark ring to find the last several paragraphs that had mismatches (*note Mark Ring::). Note that Emacs commands count square brackets and parentheses in TeX mode, not just braces. This is not strictly correct for the purpose of checking TeX syntax. However, parentheses and square brackets are likely to be used in text as matching delimiters and it is useful for the various motion commands and automatic match display to work with them.  File: emacs, Node: LaTeX Editing, Next: TeX Print, Prev: TeX Editing, Up: TeX Mode 18.9.2 LaTeX Editing Commands ----------------------------- LaTeX mode, and its variant, SliTeX mode, provide a few extra features not applicable to plain TeX. `C-c C-o' Insert `\begin' and `\end' for LaTeX block and position point on a line between them. (`tex-latex-block'). `C-c C-e' Close the last unended block for LaTeX (`tex-close-latex-block'). In LaTeX input, `\begin' and `\end' commands are used to group blocks of text. To insert a `\begin' and a matching `\end' (on a new line following the `\begin'), use `C-c C-o' (`tex-latex-block'). A blank line is inserted between the two, and point is left there. You can use completion when you enter the block type; to specify additional block type names beyond the standard list, set the variable `latex-block-names'. For example, here's how to add `theorem', `corollary', and `proof': (setq latex-block-names '("theorem" "corollary" "proof")) In LaTeX input, `\begin' and `\end' commands must balance. You can use `C-c C-e' (`tex-close-latex-block') to insert automatically a matching `\end' to match the last unmatched `\begin'. It indents the `\end' to match the corresponding `\begin'. It inserts a newline after `\end' if point is at the beginning of a line.  File: emacs, Node: TeX Print, Next: TeX Distrib, Prev: LaTeX Editing, Up: TeX Mode 18.9.3 TeX Printing Commands ---------------------------- You can invoke TeX as an inferior of Emacs on either the entire contents of the buffer or just a region at a time. Running TeX in this way on just one chapter is a good way to see what your changes look like without taking the time to format the entire file. `C-c C-r' Invoke TeX on the current region, together with the buffer's header (`tex-region'). `C-c C-b' Invoke TeX on the entire current buffer (`tex-buffer'). `C-c TAB' Invoke BibTeX on the current file (`tex-bibtex-file'). `C-c C-f' Invoke TeX on the current file (`tex-file'). `C-c C-l' Recenter the window showing output from the inferior TeX so that the last line can be seen (`tex-recenter-output-buffer'). `C-c C-k' Kill the TeX subprocess (`tex-kill-job'). `C-c C-p' Print the output from the last `C-c C-r', `C-c C-b', or `C-c C-f' command (`tex-print'). `C-c C-v' Preview the output from the last `C-c C-r', `C-c C-b', or `C-c C-f' command (`tex-view'). `C-c C-q' Show the printer queue (`tex-show-print-queue'). You can pass the current buffer through an inferior TeX by means of `C-c C-b' (`tex-buffer'). The formatted output appears in a temporary file; to print it, type `C-c C-p' (`tex-print'). Afterward, you can use `C-c C-q' (`tex-show-print-queue') to view the progress of your output towards being printed. If your terminal has the ability to display TeX output files, you can preview the output on the terminal with `C-c C-v' (`tex-view'). You can specify the directory to use for running TeX by setting the variable `tex-directory'. `"."' is the default value. If your environment variable `TEXINPUTS' contains relative directory names, or if your files contains `\input' commands with relative file names, then `tex-directory' _must_ be `"."' or you will get the wrong results. Otherwise, it is safe to specify some other directory, such as `"/tmp"'. If you want to specify which shell commands are used in the inferior TeX, you can do so by setting the values of the variables `tex-run-command', `latex-run-command', `slitex-run-command', `tex-dvi-print-command', `tex-dvi-view-command', and `tex-show-queue-command'. You _must_ set the value of `tex-dvi-view-command' for your particular terminal; this variable has no default value. The other variables have default values that may (or may not) be appropriate for your system. Normally, the file name given to these commands comes at the end of the command string; for example, `latex FILENAME'. In some cases, however, the file name needs to be embedded in the command; an example is when you need to provide the file name as an argument to one command whose output is piped to another. You can specify where to put the file name with `*' in the command string. For example, (setq tex-dvi-print-command "dvips -f * | lpr") The terminal output from TeX, including any error messages, appears in a buffer called `*tex-shell*'. If TeX gets an error, you can switch to this buffer and feed it input (this works as in Shell mode; *note Interactive Shell::). Without switching to this buffer you can scroll it so that its last line is visible by typing `C-c C-l'. Type `C-c C-k' (`tex-kill-job') to kill the TeX process if you see that its output is no longer useful. Using `C-c C-b' or `C-c C-r' also kills any TeX process still running. You can also pass an arbitrary region through an inferior TeX by typing `C-c C-r' (`tex-region'). This is tricky, however, because most files of TeX input contain commands at the beginning to set parameters and define macros, without which no later part of the file will format correctly. To solve this problem, `C-c C-r' allows you to designate a part of the file as containing essential commands; it is included before the specified region as part of the input to TeX. The designated part of the file is called the "header". To indicate the bounds of the header in Plain TeX mode, you insert two special strings in the file. Insert `%**start of header' before the header, and `%**end of header' after it. Each string must appear entirely on one line, but there may be other text on the line before or after. The lines containing the two strings are included in the header. If `%**start of header' does not appear within the first 100 lines of the buffer, `C-c C-r' assumes that there is no header. In LaTeX mode, the header begins with `\documentstyle' and ends with `\begin{document}'. These are commands that LaTeX requires you to use in any case, so nothing special needs to be done to identify the header. The commands (`tex-buffer') and (`tex-region') do all of their work in a temporary directory, and do not have available any of the auxiliary files needed by TeX for cross-references; these commands are generally not suitable for running the final copy in which all of the cross-references need to be correct. When you want the auxiliary files, use `C-c C-f' (`tex-file') which runs TeX on the current buffer's file, in that file's directory. Before TeX runs, you will be asked about saving any modified buffers. Generally, you need to use (`tex-file') twice to get cross-references correct. For LaTeX files, you can use BibTeX to process the auxiliary file for the current buffer's file. BibTeX looks up bibliographic citations in a data base and prepares the cited references for the bibliography section. The command `C-c TAB' (`tex-bibtex-file') runs the shell command (`tex-bibtex-command') to produce a `.bbl' file for the current buffer's file. Generally, you need to do `C-c C-f' (`tex-file') once to generate the `.aux' file, then do `C-c TAB' (`tex-bibtex-file'), and then repeat `C-c C-f' (`tex-file') twice more to get the cross-references correct. Entering any kind of TeX mode runs the hooks `text-mode-hook' and `tex-mode-hook'. Then it runs either `plain-tex-mode-hook' or `latex-mode-hook', whichever is appropriate. For SliTeX files, it calls `slitex-mode-hook'. Starting the TeX shell runs the hook `tex-shell-hook'. *Note Hooks::.  File: emacs, Node: TeX Distrib, Prev: TeX Print, Up: TeX Mode 18.9.4 Unix TeX Distribution ---------------------------- TeX for Unix systems can be obtained from the University of Washington for a distribution fee. To order a full distribution, specify whether you prefer 1/4 inch QIC-24 or 4mm DAT tape (9-track reel-to-reel is no longer available) and send $210.00 for a (tar or cpio) cartridge, payable to the University of Washington to: Pierre MacKay Department of Classics Denny Hall, Mail Stop DH-10 University of Washington Seattle, Washington 98195 Purchase orders are acceptable, but there is an extra charge of $10.00, to pay for processing charges. For overseas orders please add $20.00 to the base cost for shipment via air parcel post, or $30.00 for shipment via courier. The normal distribution is a tar tape, blocked 20, 1600 bpi, on an industry standard 2400 foot half-inch reel. The physical format for the 1/4 inch streamer cartridges is QIC-24. System V tapes can be written in cpio format, blocked 5120 bytes, with ASCII headers.  File: emacs, Node: Nroff Mode, Next: Formatted Text, Prev: TeX Mode, Up: Text 18.10 Nroff Mode ================ Nroff mode is a mode like Text mode but modified to handle nroff commands present in the text. Invoke `M-x nroff-mode' to enter this mode. It differs from Text mode in only a few ways. All nroff command lines are considered paragraph separators, so that filling will never garble the nroff commands. Pages are separated by `.bp' commands. Comments start with backslash-doublequote. Also, three special commands are provided that are not in Text mode: `M-n' Move to the beginning of the next line that isn't an nroff command (`forward-text-line'). An argument is a repeat count. `M-p' Like `M-n' but move up (`backward-text-line'). `M-?' Prints in the echo area the number of text lines (lines that are not nroff commands) in the region (`count-text-lines'). The other feature of Nroff mode is that you can turn on Electric Nroff mode. This is a minor mode that you can turn on or off with `M-x electric-nroff-mode' (*note Minor Modes::). When the mode is on, each time you use to end a line that contains an nroff command that opens a kind of grouping, the matching nroff command to close that grouping is automatically inserted on the following line. For example, if you are at the beginning of a line and type `. ( b ', this inserts the matching command `.)b' on a new line following point. If you use Outline minor mode with Nroff mode (*note Outline Mode::), heading lines are lines of the form `.H' followed by a number (the header level). Entering Nroff mode runs the hook `text-mode-hook', followed by the hook `nroff-mode-hook' (*note Hooks::).  File: emacs, Node: Formatted Text, Prev: Nroff Mode, Up: Text 18.11 Editing Formatted Text ============================ "Enriched mode" is a minor mode for editing files that contain formatted text in WYSIWYG fashion, as in a word processor. Currently, formatted text in Enriched mode can specify fonts, colors, underlining, margins, and types of filling and justification. In the future, we plan to implement other formatting features as well. Enriched mode is a minor mode (*note Minor Modes::). Typically it is used in conjunction with Text mode (*note Text Mode::). However, you can also use it with other major modes such as Outline mode and Indented Text mode. Potentially, Emacs can store formatted text files in various file formats. Currently, only one format is implemented: "text/enriched" format, which is defined by the MIME protocol. *Note Format Conversion: (elisp)Format Conversion, for details of how Emacs recognizes and converts file formats. The Emacs distribution contains a formatted text file that can serve as an example. Its name is `etc/enriched.doc'. It contains samples illustrating all the features described in this section. It also contains a list of ideas for future enhancements. * Menu: * Requesting Formatted Text:: Entering and exiting Enriched mode. * Hard and Soft Newlines:: There are two different kinds of newlines. * Editing Format Info:: How to edit text properties. * Faces: Format Faces. Bold, italic, underline, etc. * Color: Format Colors. Changing the color of text. * Indent: Format Indentation. Changing the left and right margins. * Justification: Format Justification. Centering, setting text flush with the left or right margin, etc. * Other: Format Properties. The "special" text properties submenu. * Forcing Enriched Mode:: How to force use of Enriched mode.  File: emacs, Node: Requesting Formatted Text, Next: Hard and Soft Newlines, Up: Formatted Text 18.11.1 Requesting to Edit Formatted Text ----------------------------------------- Whenever you visit a file that Emacs saved in the text/enriched format, Emacs automatically converts the formatting information in the file into Emacs's own internal format (text properties), and turns on Enriched mode. To create a new file of formatted text, first visit the nonexistent file, then type `M-x enriched-mode' before you start inserting text. This command turns on Enriched mode. Do this before you begin inserting text, to ensure that the text you insert is handled properly. More generally, the command `enriched-mode' turns Enriched mode on if it was off, and off if it was on. With a prefix argument, this command turns Enriched mode on if the argument is positive, and turns the mode off otherwise. When you save a buffer while Enriched mode is enabled in it, Emacs automatically converts the text to text/enriched format while writing it into the file. When you visit the file again, Emacs will automatically recognize the format, reconvert the text, and turn on Enriched mode again. Normally, after reading a file in text/enriched format, Emacs refills each paragraph to fit the width of the window. You can turn off this refilling, to save time, by setting the variable `enriched-fill-after-visiting' to `nil' or to `ask'. In any case, if the window width is the same as the width with which the file was saved, Emacs trusts that the file is already properly filled. You can add annotations for saving additional text properties, which Emacs normally does not save, by adding to `enriched-translations'. Note that the text/enriched standard requires any non-standard annotations to have names starting with `x-', as in `x-read-only'. This ensures that they will not conflict with standard annotations that may be added later.  File: emacs, Node: Hard and Soft Newlines, Next: Editing Format Info, Prev: Requesting Formatted Text, Up: Formatted Text 18.11.2 Hard and Soft Newlines ------------------------------ In formatted text, Emacs distinguishes between two different kinds of newlines, "hard" newlines and "soft" newlines. Hard newlines are used to separate paragraphs, or items in a list, or anywhere that there should always be a line break regardless of the margins. The `RET' command (`newline') and `C-o' (`open-line') insert hard newlines. Soft newlines are used to make text fit between the margins. All the fill commands, including Auto Fill, insert soft newlines--and they delete only soft newlines. Although hard and soft newlines look the same, it is important to bear the difference in mind. Do not use to break lines in the middle of filled paragraphs, or else you will get hard newlines that are barriers to further filling. Instead, let Auto Fill mode break lines, so that if the text or the margins change, Emacs can refill the lines properly. *Note Auto Fill::. On the other hand, in tables and lists, where the lines should always remain as you type them, you can use to end lines. For these lines, you may also want to set the justification style to `unfilled'. *Note Format Justification::.  File: emacs, Node: Editing Format Info, Next: Format Faces, Prev: Hard and Soft Newlines, Up: Formatted Text 18.11.3 Editing Format Information ---------------------------------- There are two ways to alter the formatting information for a formatted text file: with keyboard commands, and with the mouse. The easiest way to add properties to your document is by using the Text Properties menu. You can get to this menu in two ways: from the Edit menu in the menu bar, or with `C-mouse-2' (hold the key and press the middle mouse button). Most of the items in the Text Properties menu lead to other submenus. These are described in the sections that follow. Some items run commands directly: `Remove Properties' Delete from the region all the text properties that the Text Properties menu works with (`facemenu-remove-props'). `Remove All' Delete _all_ text properties from the region (`facemenu-remove-all'). `List Properties' List all the text properties of the character following point (`list-text-properties-at'). `Display Faces' Display a list of all the defined faces. `Display Colors' Display a list of all the defined colors.  File: emacs, Node: Format Faces, Next: Format Colors, Prev: Editing Format Info, Up: Formatted Text 18.11.4 Faces in Formatted Text ------------------------------- The Faces submenu lists various Emacs faces including `bold', `italic', and `underline'. Selecting one of these adds the chosen face to the region. *Note Faces::. You can also specify a face with these keyboard commands: `M-g d' Set the region, or the next inserted character, to the `default' face (`facemenu-set-default'). `M-g b' Set the region, or the next inserted character, to the `bold' face (`facemenu-set-bold'). `M-g i' Set the region, or the next inserted character, to the `italic' face (`facemenu-set-italic'). `M-g l' Set the region, or the next inserted character, to the `bold-italic' face (`facemenu-set-bold-italic'). `M-g u' Set the region, or the next inserted character, to the `underline' face (`facemenu-set-underline'). `M-g o FACE ' Set the region, or the next inserted character, to the face FACE (`facemenu-set-face'). If you use these commands with a prefix argument--or, in Transient Mark mode, if the region is not active--then these commands specify a face to use for your next self-inserting input. *Note Transient Mark::. This applies to both the keyboard commands and the menu commands. Enriched mode defines two additional faces: `excerpt' and `fixed'. These correspond to codes used in the text/enriched file format. The `excerpt' face is intended for quotations. This face is the same as `italic' unless you customize it (*note Modifying Faces::). The `fixed' face is meant to say, "Use a fixed-width font for this part of the text." Emacs currently supports only fixed-width fonts; therefore, the `fixed' annotation is not necessary now. However, we plan to support variable width fonts in future Emacs versions, and other systems that display text/enriched format may not use a fixed-width font as the default. So if you specifically want a certain part of the text to use a fixed-width font, you should specify the `fixed' face for that part. The `fixed' face is normally defined to use a different font from the default. However, systems have different fonts installed, you may need to customize this. If your terminal cannot display different faces, you will not be able to see them, but you can still edit documents containing faces. You can even add faces and colors to documents. They will be visible when the file is viewed on a terminal that can display them.  File: emacs, Node: Format Colors, Next: Format Indentation, Prev: Format Faces, Up: Formatted Text 18.11.5 Colors in Formatted Text -------------------------------- You can specify foreground and background colors for portions of the text. There is a menu for specifying the foreground color and a menu for specifying the background color. Each color menu lists all the colors that you have used in Enriched mode in the current Emacs session. If you specify a color with a prefix argument--or, in Transient Mark mode, if the region is not active--then it applies to your next self-inserting input. *Note Transient Mark::. Otherwise, the command applies to the region. Each color menu contains one additional item: `Other'. You can use this item to specify a color that is not listed in the menu; it reads the color name with the minibuffer. To display list of available colors and their names, use the `Display Colors' menu item in the Text Properties menu (*note Editing Format Info::). Any color that you specify in this way, or that is mentioned in a formatted text file that you read in, is added to both color menus for the duration of the Emacs session. There are no key bindings for specifying colors, but you can do so with the extended commands `M-x facemenu-set-foreground' and `M-x facemenu-set-background'. Both of these commands read the name of the color with the minibuffer.  File: emacs, Node: Format Indentation, Next: Format Justification, Prev: Format Colors, Up: Formatted Text 18.11.6 Indentation in Formatted Text ------------------------------------- When editing formatted text, you can specify different amounts of indentation for the right or left margin of an entire paragraph or a part of a paragraph. The margins you specify automatically affect the Emacs fill commands (*note Filling::) and line-breaking commands. The Indentation submenu provides a convenient interface for specifying these properties. The submenu contains four items: `Indent More' Indent the region by 4 columns (`increase-left-margin'). In Enriched mode, this command is also available on `C-x '; if you supply a numeric argument, that says how many columns to add to the margin (a negative argument reduces the number of columns). `Indent Less' Remove 4 columns of indentation from the region. `Indent Right More' Make the text narrower by indenting 4 columns at the right margin. `Indent Right Less' Remove 4 columns of indentation from the right margin. You can use these commands repeatedly to increase or decrease the indentation. The most common way to use these commands is to change the indentation of an entire paragraph. However, that is not the only use. You can change the margins at any point; the new values take effect at the end of the line (for right margins) or the beginning of the next line (for left margins). This makes it possible to format paragraphs with "hanging indents", which means that the first line is indented less than subsequent lines. To set up a hanging indent, increase the indentation of the region starting after the first word of the paragraph and running until the end of the paragraph. Indenting the first line of a paragraph is easier. Set the margin for the whole paragraph where you want it to be for the body of the paragraph, then indent the first line by inserting extra spaces or tabs. Sometimes, as a result of editing, the filling of a paragraph becomes messed up--parts of the paragraph may extend past the left or right margins. When this happens, use `M-q' (`fill-paragraph') to refill the paragraph. The variable `standard-indent' specifies how many columns these commands should add to or subtract from the indentation. The default value is 4. Enriched mode automatically sets the variable `fill-column' based on the window width: it leaves a certain number of columns for the right margin. The variable `enriched-default-right-margin' says how many columns. The default value is 10.  File: emacs, Node: Format Justification, Next: Format Properties, Prev: Format Indentation, Up: Formatted Text 18.11.7 Justification in Formatted Text --------------------------------------- When editing formatted text, you can specify various styles of justification for a paragraph. The style you specify automatically affects the Emacs fill commands. The Justification submenu provides a convenient interface for specifying the style. The submenu contains five items: `Flush Left' This is the most common style of justification (at least for English). Lines are aligned at the left margin but left uneven at the right. `Flush Right' This aligns each line with the right margin. Spaces and tabs are added on the left, if necessary, to make lines line up on the right. `Full' This justifies the text, aligning both edges of each line. Justified text looks very nice in a printed book, where the spaces can all be adjusted equally, but it does not look as nice with a fixed-width font on the screen. Perhaps a future version of Emacs will be able to adjust the width of spaces in a line to achieve elegant justification. `Center' This centers every line between the current margins. `None' This turns off filling entirely. Each line will remain as you wrote it; the fill and auto-fill functions will have no effect on text which has this setting. You can, however, still indent the left margin. In unfilled regions, all newlines are treated as hard newlines (*note Hard and Soft Newlines::) . In Enriched mode, you can also specify justification from the keyboard using the `M-j' prefix character: `M-j l' Make the region left-filled (`set-justification-left'). `M-j r' Make the region right-filled (`set-justification-right'). `M-j f' Make the region fully-justified (`set-justification-full'). `M-j c' `M-S' Make the region centered (`set-justification-center'). `M-j u' Make the region unfilled (`set-justification-none'). Justification styles apply to entire paragraphs. All the justification-changing commands operate on the paragraph containing point, or, if the region is active, on all paragraphs which overlap the region. The default justification style is specified by the variable `default-justification'. Its value should be one of the symbols `left', `right', `full', `center', or `none'.  File: emacs, Node: Format Properties, Next: Forcing Enriched Mode, Prev: Format Justification, Up: Formatted Text 18.11.8 Setting Other Text Properties ------------------------------------- The Other Properties menu lets you add or remove three other useful text properties: `read-only', `invisible' and `intangible'. The `intangible' property disallows moving point within the text, the `invisible' text property hides text from display, and the `read-only' property disallows alteration of the text. Each of these special properties has a menu item to add it to the region. The last menu item, `Remove Special', removes all of these special properties from the text in the region. Currently, the `invisible' and `intangible' properties are _not_ saved in the text/enriched format. The `read-only' property is saved, but it is not a standard part of the text/enriched format, so other editors may not respect it.  File: emacs, Node: Forcing Enriched Mode, Prev: Format Properties, Up: Formatted Text 18.11.9 Forcing Enriched Mode ----------------------------- Normally, Emacs knows when you are editing formatted text because it recognizes the special annotations used in the file that you visited. However, there are situations in which you must take special actions to convert file contents or turn on Enriched mode: * When you visit a file that was created with some other editor, Emacs may not recognize the file as being in the text/enriched format. In this case, when you visit the file you will see the formatting commands rather than the formatted text. Type `M-x format-decode-buffer' to translate it. * When you _insert_ a file into a buffer, rather than visiting it. Emacs does the necessary conversions on the text which you insert, but it does not enable Enriched mode. If you wish to do that, type `M-x enriched-mode'. The command `format-decode-buffer' translates text in various formats into Emacs's internal format. It asks you to specify the format to translate from; however, normally you can type just , which tells Emacs to guess the format. If you wish to look at a file in text/enriched format in its raw form, as a sequence of characters with no formatting, use `M-x format-find-file FILENAME '. The empty second argument means, "read without format conversion."  File: emacs, Node: Programs, Next: Building, Prev: Text, Up: Top 19 Editing Programs ******************* Emacs has many commands designed to understand the syntax of programming languages such as Lisp and C. These commands can * Move over or kill balanced expressions or "sexps" (*note Lists::). * Move over or mark top-level expressions--"defuns", in Lisp; functions, in C (*note Defuns::). * Show how parentheses balance (*note Matching::). * Insert, kill or align comments (*note Comments::). * Follow the usual indentation conventions of the language (*note Program Indent::). The commands for words, sentences and paragraphs are very useful in editing code even though their canonical application is for editing human language text. Most symbols contain words (*note Words::); sentences can be found in strings and comments (*note Sentences::). Paragraphs per se don't exist in code, but the paragraph commands are useful anyway, because programming language major modes define paragraphs to begin and end at blank lines (*note Paragraphs::). Judicious use of blank lines to make the program clearer will also provide useful chunks of text for the paragraph commands to work on. The selective display feature is useful for looking at the overall structure of a function (*note Selective Display::). This feature causes only the lines that are indented less than a specified amount to appear on the screen. * Menu: * Program Modes:: Major modes for editing programs. * Lists:: Expressions with balanced parentheses. * List Commands:: The commands for working with list and sexps. * Defuns:: Each program is made up of separate functions. There are editing commands to operate on them. * Program Indent:: Adjusting indentation to show the nesting. * Matching:: Insertion of a close-delimiter flashes matching open. * Comments:: Inserting, killing, and aligning comments. * Balanced Editing:: Inserting two matching parentheses at once, etc. * Symbol Completion:: Completion on symbol names of your program or language. * Documentation:: Getting documentation of functions you plan to call. * Change Log:: Maintaining a change history for your program. * Tags:: Go direct to any function in your program in one command. Tags remembers which file it is in. * Emerge:: A convenient way of merging two versions of a program. * C Mode:: Special commands of C, C++, Objective-C and Java modes. * Fortran:: Fortran mode and its special features. * Asm Mode:: Asm mode and its special features.  File: emacs, Node: Program Modes, Next: Lists, Up: Programs 19.1 Major Modes for Programming Languages ========================================== Emacs also has major modes for the programming languages Lisp, Scheme (a variant of Lisp), Awk, C, C++, Fortran, Icon, Java, Objective-C, Pascal, Perl and Tcl. There is also a major mode for makefiles, called Makefile mode. Ideally, a major mode should be implemented for each programming language that you might want to edit with Emacs; but often the mode for one language can serve for other syntactically similar languages. The language modes that exist are those that someone decided to take the trouble to write. There are several forms of Lisp mode, which differ in the way they interface to Lisp execution. *Note Executing Lisp::. Each of the programming language modes defines the key to run an indentation function that knows the indentation conventions of that language and updates the current line's indentation accordingly. For example, in C mode is bound to `c-indent-line'. is normally defined to do followed by ; thus, it too indents in a mode-specific fashion. In most programming languages, indentation is likely to vary from line to line. So the major modes for those languages rebind to treat a tab as if it were the equivalent number of spaces (using the command `backward-delete-char-untabify'). This makes it possible to rub out indentation one column at a time without worrying whether it is made up of spaces or tabs. Use `C-b C-d' to delete a tab character before point, in these modes. Programming language modes define paragraphs to be separated only by blank lines, so that the paragraph commands remain useful. Auto Fill mode, if enabled in a programming language major mode, indents the new lines which it creates. Turning on a major mode runs a normal hook called the "mode hook", which is the value of a Lisp variable. Each major mode has a mode hook, and the hook's name is always made from the mode command's name by adding `-hook'. For example, turning on C mode runs the hook `c-mode-hook', while turning on Lisp mode runs the hook `lisp-mode-hook'. *Note Hooks::.  File: emacs, Node: Lists, Next: List Commands, Prev: Program Modes, Up: Programs 19.2 Lists and Sexps ==================== By convention, Emacs keys for dealing with balanced expressions are usually Control-Meta characters. They tend to be analogous in function to their Control and Meta equivalents. These commands are usually thought of as pertaining to expressions in programming languages, but can be useful with any language in which some sort of parentheses exist (including human languages). These commands fall into two classes. Some deal only with "lists" (parenthetical groupings). They see nothing except parentheses, brackets, braces (whichever ones must balance in the language you are working with), and escape characters that might be used to quote those. The other commands deal with expressions or "sexps". The word `sexp' is derived from "s-expression", the ancient term for an expression in Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It refers to an expression in whatever language your program is written in. Each programming language has its own major mode, which customizes the syntax tables so that expressions in that language count as sexps. Sexps typically include symbols, numbers, and string constants, as well as anything contained in parentheses, brackets or braces. In languages that use prefix and infix operators, such as C, it is not possible for all expressions to be sexps. For example, C mode does not recognize `foo + bar' as a sexp, even though it _is_ a C expression; it recognizes `foo' as one sexp and `bar' as another, with the `+' as punctuation between them. This is a fundamental ambiguity: both `foo + bar' and `foo' are legitimate choices for the sexp to move over if point is at the `f'. Note that `(foo + bar)' is a single sexp in C mode. Some languages have obscure forms of expression syntax that nobody has bothered to make Emacs understand properly.  File: emacs, Node: List Commands, Next: Defuns, Prev: Lists, Up: Programs 19.3 List And Sexp Commands =========================== `C-M-f' Move forward over a sexp (`forward-sexp'). `C-M-b' Move backward over a sexp (`backward-sexp'). `C-M-k' Kill sexp forward (`kill-sexp'). `C-M-' Kill sexp backward (`backward-kill-sexp'). `C-M-u' Move up and backward in list structure (`backward-up-list'). `C-M-d' Move down and forward in list structure (`down-list'). `C-M-n' Move forward over a list (`forward-list'). `C-M-p' Move backward over a list (`backward-list'). `C-M-t' Transpose expressions (`transpose-sexps'). `C-M-@' Put mark after following expression (`mark-sexp'). To move forward over a sexp, use `C-M-f' (`forward-sexp'). If the first significant character after point is an opening delimiter (`(' in Lisp; `(', `[' or `{' in C), `C-M-f' moves past the matching closing delimiter. If the character begins a symbol, string, or number, `C-M-f' moves over that. The command `C-M-b' (`backward-sexp') moves backward over a sexp. The detailed rules are like those above for `C-M-f', but with directions reversed. If there are any prefix characters (single-quote, backquote and comma, in Lisp) preceding the sexp, `C-M-b' moves back over them as well. The sexp commands move across comments as if they were whitespace in most modes. `C-M-f' or `C-M-b' with an argument repeats that operation the specified number of times; with a negative argument, it moves in the opposite direction. Killing a sexp at a time can be done with `C-M-k' (`kill-sexp') or `C-M-' (`backward-kill-sexp'). `C-M-k' kills the characters that `C-M-f' would move over, and `C-M-' kills the characters that `C-M-b' would move over. The "list commands" move over lists like the sexp commands but skip blithely over any number of other kinds of sexps (symbols, strings, etc). They are `C-M-n' (`forward-list') and `C-M-p' (`backward-list'). The main reason they are useful is that they usually ignore comments (since the comments usually do not contain any lists). `C-M-n' and `C-M-p' stay at the same level in parentheses, when that's possible. To move _up_ one (or N) levels, use `C-M-u' (`backward-up-list'). `C-M-u' moves backward up past one unmatched opening delimiter. A positive argument serves as a repeat count; a negative argument reverses direction of motion and also requests repetition, so it moves forward and up one or more levels. To move _down_ in list structure, use `C-M-d' (`down-list'). In Lisp mode, where `(' is the only opening delimiter, this is nearly the same as searching for a `('. An argument specifies the number of levels of parentheses to go down. A somewhat random-sounding command which is nevertheless handy is `C-M-t' (`transpose-sexps'), which drags the previous sexp across the next one. An argument serves as a repeat count, and a negative argument drags backwards (thus canceling out the effect of `C-M-t' with a positive argument). An argument of zero, rather than doing nothing, transposes the sexps ending after point and the mark. To set the region around the next sexp in the buffer, use `C-M-@' (`mark-sexp'), which sets mark at the same place that `C-M-f' would move to. `C-M-@' takes arguments like `C-M-f'. In particular, a negative argument is useful for putting the mark at the beginning of the previous sexp. The list and sexp commands' understanding of syntax is completely controlled by the syntax table. Any character can, for example, be declared to be an opening delimiter and act like an open parenthesis. *Note Syntax::.  File: emacs, Node: Defuns, Next: Program Indent, Prev: List Commands, Up: Programs 19.4 Defuns =========== In Emacs, a parenthetical grouping at the top level in the buffer is called a "defun". The name derives from the fact that most top-level lists in a Lisp file are instances of the special form `defun', but any top-level parenthetical grouping counts as a defun in Emacs parlance regardless of what its contents are, and regardless of the programming language in use. For example, in C, the body of a function definition is a defun. `C-M-a' Move to beginning of current or preceding defun (`beginning-of-defun'). `C-M-e' Move to end of current or following defun (`end-of-defun'). `C-M-h' Put region around whole current or following defun (`mark-defun'). The commands to move to the beginning and end of the current defun are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun'). If you wish to operate on the current defun, use `C-M-h' (`mark-defun') which puts point at the beginning and mark at the end of the current or next defun. For example, this is the easiest way to get ready to move the defun to a different place in the text. In C mode, `C-M-h' runs the function `mark-c-function', which is almost the same as `mark-defun'; the difference is that it backs up over the argument declarations, function name and returned data type so that the entire C function is inside the region. *Note Marking Objects::. Emacs assumes that any open-parenthesis found in the leftmost column is the start of a defun. Therefore, *never put an open-parenthesis at the left margin in a Lisp file unless it is the start of a top level list. Never put an open-brace or other opening delimiter at the beginning of a line of C code unless it starts the body of a function.* The most likely problem case is when you want an opening delimiter at the start of a line inside a string. To avoid trouble, put an escape character (`\', in C and Emacs Lisp, `/' in some other Lisp dialects) before the opening delimiter. It will not affect the contents of the string. In the remotest past, the original Emacs found defuns by moving upward a level of parentheses until there were no more levels to go up. This always required scanning all the way back to the beginning of the buffer, even for a small function. To speed up the operation, Emacs was changed to assume that any `(' (or other character assigned the syntactic class of opening-delimiter) at the left margin is the start of a defun. This heuristic is nearly always right and avoids the costly scan; however, it mandates the convention described above.  File: emacs, Node: Program Indent, Next: Matching, Prev: Defuns, Up: Programs 19.5 Indentation for Programs ============================= The best way to keep a program properly indented is to use Emacs to re-indent it as you change it. Emacs has commands to indent properly either a single line, a specified number of lines, or all of the lines inside a single parenthetical grouping. * Menu: * Basic Indent:: Indenting a single line. * Multi-line Indent:: Commands to reindent many lines at once. * Lisp Indent:: Specifying how each Lisp function should be indented. * C Indent:: Extra features for indenting C code. * Custom C Indent:: Controlling indentation style for C code. Emacs also provides a Lisp pretty-printer in the library `pp'. This program prints a Lisp object with indentation chosen to look nice.  File: emacs, Node: Basic Indent, Next: Multi-line Indent, Up: Program Indent 19.5.1 Basic Program Indentation Commands ----------------------------------------- `' Adjust indentation of current line. `' Equivalent to followed by (`newline-and-indent'). The basic indentation command is , which gives the current line the correct indentation as determined from the previous lines. The function that runs depends on the major mode; it is `lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These functions understand different syntaxes for different languages, but they all do about the same thing. in any programming language major mode inserts or deletes whitespace at the beginning of the current line, independent of where point is in the line. If point is inside the whitespace at the beginning of the line, leaves it at the end of that whitespace; otherwise, leaves point fixed with respect to the characters around it. Use `C-q ' to insert a tab at point. When entering lines of new code, use (`newline-and-indent'), which is equivalent to a followed by a . creates a blank line, and then gives it the appropriate indentation. indents the second and following lines of the body of a parenthetical grouping each under the preceding one; therefore, if you alter one line's indentation to be nonstandard, the lines below will tend to follow it. This behavior is convenient in cases where you have overridden the standard result of because you find it unaesthetic for a particular line. Remember that an open-parenthesis, open-brace or other opening delimiter at the left margin is assumed by Emacs (including the indentation routines) to be the start of a function. Therefore, you must never have an opening delimiter in column zero that is not the beginning of a function, not even inside a string. This restriction is vital for making the indentation commands fast; you must simply accept it. *Note Defuns::, for more information on this.  File: emacs, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Program Indent 19.5.2 Indenting Several Lines ------------------------------ When you wish to re-indent several lines of code which have been altered or moved to a different level in the list structure, you have several commands available. `C-M-q' Re-indent all the lines within one list (`indent-sexp'). `C-u ' Shift an entire list rigidly sideways so that its first line is properly indented. `C-M-\' Re-indent all lines in the region (`indent-region'). You can re-indent the contents of a single list by positioning point before the beginning of it and typing `C-M-q' (`indent-sexp' in Lisp mode, `indent-c-exp' in C mode; also bound to other suitable commands in other modes). The indentation of the line the sexp starts on is not changed; therefore, only the relative indentation within the list, and not its position, is changed. To correct the position as well, type a before the `C-M-q'. If the relative indentation within a list is correct but the indentation of its first line is not, go to that line and type `C-u '. with a numeric argument reindents the current line as usual, then reindents by the same amount all the lines in the grouping starting on the current line. In other words, it reindents the whole grouping rigidly as a unit. It is clever, though, and does not alter lines that start inside strings, or C preprocessor lines when in C mode. Another way to specify the range to be re-indented is with the region. The command `C-M-\' (`indent-region') applies to every line whose first character is between point and mark.  File: emacs, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Program Indent 19.5.3 Customizing Lisp Indentation ----------------------------------- The indentation pattern for a Lisp expression can depend on the function called by the expression. For each Lisp function, you can choose among several predefined patterns of indentation, or define an arbitrary one with a Lisp program. The standard pattern of indentation is as follows: the second line of the expression is indented under the first argument, if that is on the same line as the beginning of the expression; otherwise, the second line is indented underneath the function name. Each following line is indented under the previous line whose nesting depth is the same. If the variable `lisp-indent-offset' is non-`nil', it overrides the usual indentation pattern for the second line of an expression, so that such lines are always indented `lisp-indent-offset' more columns than the containing list. The standard pattern is overridden for certain functions. Functions whose names start with `def' always indent the second line by `lisp-body-indent' extra columns beyond the open-parenthesis starting the expression. The standard pattern can be overridden in various ways for individual functions, according to the `lisp-indent-function' property of the function name. There are four possibilities for this property: `nil' This is the same as no property; the standard indentation pattern is used. `defun' The pattern used for function names that start with `def' is used for this function also. a number, NUMBER The first NUMBER arguments of the function are "distinguished" arguments; the rest are considered the "body" of the expression. A line in the expression is indented according to whether the first argument on it is distinguished or not. If the argument is part of the body, the line is indented `lisp-body-indent' more columns than the open-parenthesis starting the containing expression. If the argument is distinguished and is either the first or second argument, it is indented _twice_ that many extra columns. If the argument is distinguished and not the first or second argument, the standard pattern is followed for that line. a symbol, SYMBOL SYMBOL should be a function name; that function is called to calculate the indentation of a line within this expression. The function receives two arguments: STATE The value returned by `parse-partial-sexp' (a Lisp primitive for indentation and nesting computation) when it parses up to the beginning of this line. POS The position at which the line being indented begins. It should return either a number, which is the number of columns of indentation for that line, or a list whose car is such a number. The difference between returning a number and returning a list is that a number says that all following lines at the same nesting level should be indented just like this one; a list says that following lines might call for different indentations. This makes a difference when the indentation is being computed by `C-M-q'; if the value is a number, `C-M-q' need not recalculate indentation for the following lines until the end of the list.  File: emacs, Node: C Indent, Next: Custom C Indent, Prev: Lisp Indent, Up: Program Indent 19.5.4 Commands for C Indentation --------------------------------- Here are the commands for indentation in C mode and related modes: `C-c C-q' Reindent the current top-level function definition or aggregate type declaration (`c-indent-defun'). `C-M-q' Reindent each line in the balanced expression that follows point (`c-indent-exp'). A prefix argument inhibits error checking and warning messages about invalid syntax. `' Reindent the current line, and/or in some cases insert a tab character (`c-indent-command'). If `c-tab-always-indent' is `t', this command always reindents the current line and does nothing else. This is the default. If that variable is `nil', this command reindents the current line only if point is at the left margin or in the line's indentation; otherwise, it inserts a tab. Any other value (not `nil' or `t') means always reindent the line, and also insert a tab if within a comment, a string, or a preprocessor directive. `C-u ' Reindent the current line according to its syntax; also rigidly reindent any other lines of the expression that starts on the current line. *Note Multi-line Indent::. To reindent the whole current buffer, type `C-x h C-M-\'. This first selects the whole buffer as the region, then reindents that region. To reindent the current block, use `C-M-u C-M-q'. This moves to the front of the block and then reindents it all.  File: emacs, Node: Custom C Indent, Prev: C Indent, Up: Program Indent 19.5.5 Customizing C Indentation -------------------------------- C mode and related modes use a simple yet flexible mechanism for customizing indentation. The mechanism works in two steps: first it classifies the line syntactically according to its contents and context; second, it associates each kind of syntactic construct with an indentation offset which you can customize. * Menu: * Syntactic Analysis:: * Indentation Calculation:: * Changing Indent Style:: * Syntactic Symbols:: * Variables for C Indent:: * C Indent Styles::  File: emacs, Node: Syntactic Analysis, Next: Indentation Calculation, Up: Custom C Indent 19.5.5.1 Step 1--Syntactic Analysis ................................... In the first step, the C indentation mechanism looks at the line you are currently indenting and determines the syntactic components of the construct on that line. It builds a list of these syntactic components, where each component on the list contains a "syntactic symbol" and a relative buffer position. Syntactic symbols describe grammatical elements such as STATEMENT, SUBSTATEMENT, CLASS-OPEN, CLASS-CLOSE, KNR-ARGDECL, etc. Conceptually, a line of C code is always indented relative to the indentation of some line higher up in the buffer. This is represented by the relative buffer positions in the syntactic component list. Here is an example. Suppose we have the following code in a C++ mode buffer (the line numbers don't actually appear in the buffer): 1: void swap (int& a, int& b) 2: { 3: int tmp = a; 4: a = b; 5: b = tmp; 6: } If you type `C-c C-s' (which runs the command `c-show-syntactic-information') on line 4, it shows the result of the indentation mechanism for that line: ((statement . 32)) This indicates that the line is a statement and it is indented relative to buffer position 32, which happens to be the `i' in `int' on line 3. If you move the cursor to line 3 and type `C-c C-s', it displays this: ((defun-block-intro . 28)) This indicates that the `int' line is the first statement in a block, and is indented relative to buffer position 28, which is the brace just after the function header. Here is another example: 1: int add (int val, int incr, int doit) 2: { 3: if (doit) 4: { 5: return (val + incr); 6: } 7: return (val); 8: } Typing `C-c C-s' on line 4 displays this: ((substatement-open . 43)) This says that the brace _opens_ a substatement block. By the way, a "substatement" indicates the line after an `if', `else', `while', `do', `switch', and `for' statements. After a line has been analyzed syntactically for indentation, the global variable `c-syntactic-context' contains a list that describes the results. Each element in this list is a a "syntactic component": a cons cell containing a syntactic symbol and (optionally) its corresponding buffer position. There may be several elements in a component list; typically only one element has a buffer position.  File: emacs, Node: Indentation Calculation, Next: Changing Indent Style, Prev: Syntactic Analysis, Up: Custom C Indent 19.5.5.2 Step 2--Indentation Calculation ........................................ The C indentation mechanism calculates the indentation for the current line using the list of syntactic components, `c-syntactic-context', derived from syntactic analysis. Each component is a cons cell that contains a syntactic symbol and may also contain a pointer to a location in the buffer. Each component contributes to the final total indentation of the line in two ways. First, the syntactic symbol identifies an element of `c-offsets-alist', which is an association list mapping syntactic symbols into indentation offsets. Each syntactic symbol's offset adds to the total indentation. Second, if the component includes a buffer position, the column number of that position adds to the indentation. All these offsets and column numbers, added together, give the total indentation. The following examples demonstrate the workings of the C indentation mechanism: 1: void swap (int& a, int& b) 2: { 3: int tmp = a; 4: a = b; 5: b = tmp; 6: } Suppose that point is on line 3 and you type to reindent the line. As explained above (*note Syntactic Analysis::), the syntactic component list for that line is: ((defun-block-intro . 28)) In this case, the indentation calculation first looks up `defun-block-intro' in the `c-offsets-alist' alist. Suppose that it finds the integer 2; it adds this to the running total (initialized to zero), yielding a updated total indentation of 2 spaces. The next step is to find the column number of buffer position 28. Since the brace at buffer position 28 is in column zero, this adds 0 to the running total. Since this line has only one syntactic component, the total indentation for the line is 2 spaces. 1: int add (int val, int incr, int doit) 2: { 3: if (doit) 4: { 5: return(val + incr); 6: } 7: return(val); 8: } If you type on line 4, the same process is performed, but with different data. The syntactic component list for this line is: ((substatement-open . 43)) Here, the indentation calculation's first job is to look up the symbol `substatement-open' in `c-offsets-alist'. Let's assume that the offset for this symbol is 2. At this point the running total is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43, which is the `i' in `if' on line 3. This character is in column 2 on that line. Adding this yields a total indentation of 4 spaces. If a syntactic symbol in the analysis of a line does not appear in `c-offsets-alist', it is ignored; if in addition the variable `c-strict-syntax-p' is non-`nil', it is an error.  File: emacs, Node: Changing Indent Style, Next: Syntactic Symbols, Prev: Indentation Calculation, Up: Custom C Indent 19.5.5.3 Changing Indentation Style ................................... There are two ways to customize the indentation style for the C modes. First, you can select one of several predefined styles, each of which specifies offsets for all the syntactic symbols. For more flexibility, you can customize the handling of individual syntactic symbols. *Note Syntactic Symbols::, for a list of all defined syntactic symbols. `M-x c-set-style STYLE ' Select predefined indentation style STYLE. Type `?' when entering STYLE to see a list of supported styles; to find out what a style looks like, select it and reindent some C code. `C-c C-o SYMBOL OFFSET ' Set the indentation offset for syntactic symbol SYMBOL (`c-set-offset'). The second argument OFFSET specifies the new indentation offset. The `c-offsets-alist' variable controls the amount of indentation to give to each syntactic symbol. Its value is an association list, and each element of the list has the form `(SYNTACTIC-SYMBOL . OFFSET)'. By changing the offsets for various syntactic symbols, you can customize indentation in fine detail. Each offset value in `c-offsets-alist' can be an integer, a function or variable name, or one of the following symbols: `+', `-', `++', or `--', indicating positive or negative multiples of the variable `c-basic-offset'. Thus, if you want to change the levels of indentation to be 3 spaces instead of 2 spaces, set `c-basic-offset' to 3. Using a function as the offset value provides the ultimate flexibility in customizing indentation. The function is called with a single argument containing the `cons' of the syntactic symbol and the relative indent point. The function should return an integer offset. The command `C-c C-o' (`c-set-offset') is the easiest way to set offsets, both interactively or in your `~/.emacs' file. First specify the syntactic symbol, then the offset you want. *Note Syntactic Symbols::, for a list of valid syntactic symbols and their meanings. The variable `c-offsets-alist-default' holds the default settings for the offsets of the syntactic symbols. _Do not change this value!_  File: emacs, Node: Syntactic Symbols, Next: Variables for C Indent, Prev: Changing Indent Style, Up: Custom C Indent 19.5.5.4 Syntactic Symbols .......................... Here is a table of valid syntactic symbols for C mode indentation, with their syntactic meanings. Normally, most of these symbols are assigned offsets in `c-offsets-alist'. `string' Inside a multi-line string. `c' Inside a multi-line C style block comment. `defun-open' On a brace that opens a function definition. `defun-close' On a brace that closes a function definition. `defun-block-intro' In the first line in a top-level defun. `class-open' On a brace that opens a class definition. `class-close' On a brace that closes a class definition. `inline-open' On a brace that opens an in-class inline method. `inline-close' On a brace that closes an in-class inline method. `ansi-funcdecl-cont' In the nether region between an ANSI function declaration and the defun opening brace. `knr-argdecl-intro' On the first line of a K&R C argument declaration. `knr-argdecl' In one of the subsequent lines in a K&R C argument declaration. `topmost-intro' On the first line in a topmost construct definition. `topmost-intro-cont' On the topmost definition continuation lines. `member-init-intro' On the first line in a member initialization list. `member-init-cont' On one of the subsequent member initialization list lines. `inher-intro' On the first line of a multiple inheritance list. `inher-cont' On one of the subsequent multiple inheritance lines. `block-open' On a statement block open brace. `block-close' On a statement block close brace. `brace-list-open' On the opening brace of an `enum' or `static' array list. `brace-list-close' On the closing brace of an `enum' or `static' array list. `brace-list-intro' On the first line in an `enum' or `static' array list. `brace-list-entry' On one of the subsequent lines in an `enum' or `static' array list. `statement' On an ordinary statement. `statement-cont' On a continuation line of a statement. `statement-block-intro' On the first line in a new statement block. `statement-case-intro' On the first line in a `case' "block". `statement-case-open' On the first line in a `case' block starting with brace. `substatement' On the first line after an `if', `while', `for', `do', or `else'. `substatement-open' On the brace that opens a substatement block. `case-label' On a `case' or `default' label. `access-label' On a C++ `private', `protected', or `public' access label. `label' On any ordinary label. `do-while-closure' On the `while' that ends a `do'-`while' construct. `else-clause' On the `else' of an `if'-`else' construct. `comment-intro' On a line containing only a comment introduction. `arglist-intro' On the first line in an argument list. `arglist-cont' On one of the subsequent argument list lines when no arguments follow on the same line as the the arglist opening parenthesis. `arglist-cont-nonempty' On one of the subsequent argument list lines when at least one argument follows on the same line as the arglist opening parenthesis. `arglist-close' On the closing parenthesis of an argument list. `stream-op' On one of the lines continuing a stream operator construct. `inclass' On a construct which is nested inside a class definition. `cpp-macro' On the start of a cpp macro. `friend' On a C++ `friend' declaration. `objc-method-intro' On the first line of an Objective-C method definition. `objc-method-args-cont' On one of the lines continuing an Objective-C method definition. `objc-method-call-cont' On one of the lines continuing an Objective-C method call.  File: emacs, Node: Variables for C Indent, Next: C Indent Styles, Prev: Syntactic Symbols, Up: Custom C Indent 19.5.5.5 Variables for C Indentation .................................... This section describes additional variables which control the indentation behavior of C mode and related mode. `c-offsets-alist' Association list of syntactic symbols and their indentation offsets. *Note Changing Indent Style::, for details. `c-offsets-alist-default' Default settings for the offsets of the syntactic symbols. *Note Changing Indent Style::. `c-style-alist' Variable for specifying styles of indentation; see below. `c-basic-offset' Amount of basic offset used by `+' and `-' symbols in `c-offsets-alist'. `c-recognize-knr-p' If this variable is non-`nil', C mode and Objective C mode recognize K&R constructs. This variable is needed because of ambiguities in C syntax that make recognition of K&R constructs problematic and slow. If you always use ANSI C prototype syntax, set this variable to `nil' to speed up C indentation. This variable is `nil' by default in C++ mode, and `t' by default in C mode and Objective C mode. `c-special-indent-hook' Hook for user-defined special indentation adjustments. This hook is called after a line is indented by C mode and related modes. The variable `c-style-alist' specifies the predefined indentation styles. Each element has form `(NAME VARIABLE-SETTING...)', where NAME is the name of the style. Each VARIABLE-SETTING has the form `(VARIABLE . VALUE)'; VARIABLE is one of the customization variables used by C mode, and VALUE is the value for that variable when using the selected style. When VARIABLE is `c-offsets-alist', that is a special case: VALUE is appended to the front of the value of `c-offsets-alist' instead of replacing that value outright. Therefore, it is not necessary for VALUE to specify each and every syntactic symbol--only those for which the style differs from the default. The indentation of lines containing only comments is also affected by the variable `c-comment-only-line-offset' (*note Comments in C::).  File: emacs, Node: C Indent Styles, Prev: Variables for C Indent, Up: Custom C Indent 19.5.5.6 C Indentation Styles ............................. A "C style" is a collection of indentation style customizations. Emacs comes with several predefined indentation styles for C code including `gnu', `k&r', `bsd', `stroustrup' `whitesmith', `ellemtel', and `cc-mode'. The default style is `gnu'. To choose the style you want, use the command `M-x c-set-style'. Specify a style name as an argument (case is not significant in C style names). The chosen style only affects newly visited buffers, not those you are already editing. To define a new C indentation style, call the function `c-add-style': (c-add-style NAME VALUES USE-NOW) Here NAME is the name of the new style (a string), and VALUES is an alist whose elements have the form `(VARIABLE . VALUE)'. The variables you specify should be among those documented in *Note Variables for C Indent::. If USE-NOW is non-`nil', `c-add-style' switches to the new style after defining it.  File: emacs, Node: Matching, Next: Comments, Prev: Program Indent, Up: Programs 19.6 Automatic Display Of Matching Parentheses ============================================== The Emacs parenthesis-matching feature is designed to show automatically how parentheses match in the text. Whenever you type a self-inserting character that is a closing delimiter, the cursor moves momentarily to the location of the matching opening delimiter, provided that is on the screen. If it is not on the screen, some text near it is displayed in the echo area. Either way, you can tell what grouping is being closed off. In Lisp, automatic matching applies only to parentheses. In C, it applies to braces and brackets too. Emacs knows which characters to regard as matching delimiters based on the syntax table, which is set by the major mode. *Note Syntax::. If the opening delimiter and closing delimiter are mismatched--such as in `[x)'--a warning message is displayed in the echo area. The correct matches are specified in the syntax table. Three variables control parenthesis match display. `blink-matching-paren' turns the feature on or off; `nil' turns it off, but the default is `t' to turn match display on. `blink-matching-delay' says how many seconds to wait; the default is 1, but on some systems it is useful to specify a fraction of a second. `blink-matching-paren-distance' specifies how many characters back to search to find the matching opening delimiter. If the match is not found in that far, scanning stops, and nothing is displayed. This is to prevent scanning for the matching delimiter from wasting lots of time when there is no match. The default is 12,000. When using X Windows, you can request a more powerful kind of automatic parenthesis matching by loading the `paren' library. To load it, type `M-x load-library paren '. This library turns off the usual kind of matching parenthesis display and substitutes another: whenever point is after a close parenthesis, the close parenthesis and its matching open parenthesis are both highlighted; otherwise, if point is before an open parenthesis, the matching close parenthesis is highlighted. (There is no need to highlight the open parenthesis after point because the cursor appears on top of that character.)  File: emacs, Node: Comments, Next: Balanced Editing, Prev: Matching, Up: Programs 19.7 Manipulating Comments ========================== Because comments are such an important part of programming, Emacs provides special commands for editing and inserting comments. * Menu: * Comment Commands:: * Multi-Line Comments:: * Options for Comments::  File: emacs, Node: Comment Commands, Next: Multi-Line Comments, Up: Comments 19.7.1 Comment Commands ----------------------- The comment commands insert, kill and align comments. `M-;' Insert or align comment (`indent-for-comment'). `C-x ;' Set comment column (`set-comment-column'). `C-u - C-x ;' Kill comment on current line (`kill-comment'). `M-' Like followed by inserting and aligning a comment (`indent-new-comment-line'). `M-x comment-region' Add or remove comment delimiters on all the lines in the region. The command that creates a comment is `M-;' (`indent-for-comment'). If there is no comment already on the line, a new comment is created, aligned at a specific column called the "comment column". The comment is created by inserting the string Emacs thinks comments should start with (the value of `comment-start'; see below). Point is left after that string. If the text of the line extends past the comment column, then the indentation is done to a suitable boundary (usually, at least one space is inserted). If the major mode has specified a string to terminate comments, that is inserted after point, to keep the syntax valid. `M-;' can also be used to align an existing comment. If a line already contains the string that starts comments, then `M-;' just moves point after it and re-indents it to the conventional place. Exception: comments starting in column 0 are not moved. Some major modes have special rules for indenting certain kinds of comments in certain contexts. For example, in Lisp code, comments which start with two semicolons are indented as if they were lines of code, instead of at the comment column. Comments which start with three semicolons are supposed to start at the left margin. Emacs understands these conventions by indenting a double-semicolon comment using , and by not changing the indentation of a triple-semicolon comment at all. ;; This function is just an example ;;; Here either two or three semicolons are appropriate. (defun foo (x) ;;; And now, the first part of the function: ;; The following line adds one. (1+ x)) ; This line adds one. In C code, a comment preceded on its line by nothing but whitespace is indented like a line of code. Even when an existing comment is properly aligned, `M-;' is still useful for moving directly to the start of the comment. `C-u - C-x ;' (`kill-comment') kills the comment on the current line, if there is one. The indentation before the start of the comment is killed as well. If there does not appear to be a comment in the line, nothing is done. To reinsert the comment on another line, move to the end of that line, do `C-y', and then do `M-;' to realign it. Note that `C-u - C-x ;' is not a distinct key; it is `C-x ;' (`set-comment-column') with a negative argument. That command is programmed so that when it receives a negative argument it calls `kill-comment'. However, `kill-comment' is a valid command which you could bind directly to a key if you wanted to.  File: emacs, Node: Multi-Line Comments, Next: Options for Comments, Prev: Comment Commands, Up: Comments 19.7.2 Multiple Lines of Comments --------------------------------- If you are typing a comment and wish to continue it on another line, you can use the command `M-' (`indent-new-comment-line'). This terminates the comment you are typing, creates a new blank line afterward, and begins a new comment indented under the old one. When Auto Fill mode is on, going past the fill column while typing a comment causes the comment to be continued in just this fashion. If point is not at the end of the line when `M-' is typed, the text on the rest of the line becomes part of the new comment line. To turn existing lines into comment lines, use the `M-x comment-region' command. It adds comment delimiters to the lines that start in the region, thus commenting them out. With a negative argument, it does the opposite--it deletes comment delimiters from the lines in the region. With a positive argument, `comment-region' duplicates the last character of the comment start sequence it adds; the argument specifies how many copies of the character to insert. Thus, in Lisp mode, `C-u 2 M-x comment-region' adds `;;' to each line. Duplicating the comment delimiter is a way of calling attention to the comment. It can also affect how the comment is indented. In Lisp, for proper indentation, you should use an argument of two, if between defuns, and three, if within a defun.  File: emacs, Node: Options for Comments, Prev: Multi-Line Comments, Up: Comments 19.7.3 Options Controlling Comments ----------------------------------- The comment column is stored in the variable `comment-column'. You can set it to a number explicitly. Alternatively, the command `C-x ;' (`set-comment-column') sets the comment column to the column point is at. `C-u C-x ;' sets the comment column to match the last comment before point in the buffer, and then does a `M-;' to align the current line's comment under the previous one. Note that `C-u - C-x ;' runs the function `kill-comment' as described above. The variable `comment-column' is per-buffer: setting the variable in the normal fashion affects only the current buffer, but there is a default value which you can change with `setq-default'. *Note Locals::. Many major modes initialize this variable for the current buffer. The comment commands recognize comments based on the regular expression that is the value of the variable `comment-start-skip'. Make sure this regexp does not match the null string. It may match more than the comment starting delimiter in the strictest sense of the word; for example, in C mode the value of the variable is `"/\\*+ *"', which matches extra stars and spaces after the `/*' itself. (Note that `\\' is needed in Lisp syntax to include a `\' in the string, which is needed to deny the first star its special meaning in regexp syntax. *Note Regexps::.) When a comment command makes a new comment, it inserts the value of `comment-start' to begin it. The value of `comment-end' is inserted after point, so that it will follow the text that you will insert into the comment. In C mode, `comment-start' has the value `"/* "' and `comment-end' has the value `" */"'. The variable `comment-multi-line' controls how `M-' (`indent-new-comment-line') behaves when used inside a comment. If `comment-multi-line' is `nil', as it normally is, then the comment on the starting line is terminated and a new comment is started on the new following line. If `comment-multi-line' is not `nil', then the new following line is set up as part of the same comment that was found on the starting line. This is done by not inserting a terminator on the old line, and not inserting a starter on the new line. In languages where multi-line comments work, the choice of value for this variable is a matter of taste. The variable `comment-indent-function' should contain a function that will be called to compute the indentation for a newly inserted comment or for aligning an existing comment. It is set differently by various major modes. The function is called with no arguments, but with point at the beginning of the comment, or at the end of a line if a new comment is to be inserted. It should return the column in which the comment ought to start. For example, in Lisp mode, the indent hook function bases its decision on how many semicolons begin an existing comment, and on the code in the preceding lines.  File: emacs, Node: Balanced Editing, Next: Symbol Completion, Prev: Comments, Up: Programs 19.8 Editing Without Unbalanced Parentheses =========================================== `M-(' Put parentheses around next sexp(s) (`insert-parentheses'). `M-)' Move past next close parenthesis and re-indent (`move-over-close-and-reindent'). The commands `M-(' (`insert-parentheses') and `M-)' (`move-over-close-and-reindent') are designed to facilitate a style of editing which keeps parentheses balanced at all times. `M-(' inserts a pair of parentheses, either together as in `()', or, if given an argument, around the next several sexps. It leaves point after the open parenthesis. The command `M-)' moves past the close parenthesis, deleting any indentation preceding it (in this example there is none), and indenting with after it. For example, instead of typing `( F O O )', you can type `M-( F O O', which has the same effect except for leaving the cursor before the close parenthesis. `M-(' may insert a space before the open parenthesis, depending on the syntax class of the preceding character. Set `parens-dont-require-spaces' to a non-`nil' value if you wish to inhibit this.  File: emacs, Node: Symbol Completion, Next: Documentation, Prev: Balanced Editing, Up: Programs 19.9 Completion for Symbol Names ================================ Usually completion happens in the minibuffer. But one kind of completion is available in all buffers: completion for symbol names. The character `M-' runs a command to complete the partial symbol before point against the set of meaningful symbol names. Any additional characters determined by the partial name are inserted at point. If the partial name in the buffer has more than one possible completion and they have no additional characters in common, a list of all possible completions is displayed in another window. There are two ways of determining the set of legitimate symbol names to complete against. In most major modes, this uses a tags table (*note Tags::); the legitimate symbol names are the tag names listed in the tags table file. The command which implements this is `complete-tag'. In Emacs-Lisp mode, the name space for completion normally consists of nontrivial symbols present in Emacs--those that have function definitions, values or properties. However, if there is an open-parenthesis immediately before the beginning of the partial symbol, only symbols with function definitions are considered as completions. The command which implements this is `lisp-complete-symbol'. In Text mode and related modes, `M-' completes words based on the spell-checker's dictionary. *Note Spelling::.  File: emacs, Node: Documentation, Next: Change Log, Prev: Symbol Completion, Up: Programs 19.10 Documentation Commands ============================ As you edit Lisp code to be run in Emacs, the commands `C-h f' (`describe-function') and `C-h v' (`describe-variable') can be used to print documentation of functions and variables that you want to call. These commands use the minibuffer to read the name of a function or variable to document, and display the documentation in a window. For extra convenience, these commands provide default arguments based on the code in the neighborhood of point. `C-h f' sets the default to the function called in the innermost list containing point. `C-h v' uses the symbol name around or adjacent to point as its default. Documentation on operating system commands, library functions and system calls can be obtained with the `M-x manual-entry' command. This reads a topic as an argument, and displays the "man page" on that topic. `manual-entry' starts a background process that formats the manual page, by running the `man' program. The result goes in a buffer named `*man TOPIC*'. These buffers use a special major mode, Man mode, that facilitates scrolling and examining other manual pages. For details, type `C-h m' while in a man page buffer. For a long man page, setting the faces properly can take substantial time. By default, Emacs uses faces in man pages if you are using X Windows. You can turn off use of faces in man pages by setting the variable `Man-fontify-manpage-flag' to `nil'. If you insert the text of a man page into an Emacs buffer in some other fashion, you can use the command `M-x Man-fontify-manpage' to perform the same conversions that `M-x manual-entry' does. Eventually the GNU project hopes to replace most man pages with better-organized manuals that you can browse with Info. *Note Misc Help::. Since this process is only partially completed, it is still useful to read manual pages.  File: emacs, Node: Change Log, Next: Tags, Prev: Documentation, Up: Programs 19.11 Change Logs ================= The Emacs command `C-x 4 a' adds a new entry to the change log file for the file you are editing (`add-change-log-entry-other-window'). A change log file contains a chronological record of when and why you have changed a program, consisting of a sequence of entries describing individual changes. Normally it is kept in a file called `ChangeLog' in the same directory as the file you are editing, or one of its parent directories. A single `ChangeLog' file can record changes for all the files in its directory and all its subdirectories. A change log entry starts with a header line that contains your name, your email address (taken from the variable `user-mail-address'), and the current date and time. Aside from these header lines, every line in the change log starts with a space or a tab. The bulk of the entry consists of "items", each of which starts with a line starting with whitespace and a star. Here are two entries, each with two items: Wed May 5 14:11:45 1993 Richard Stallman * man.el: Rename symbols `man-*' to `Man-*'. (manual-entry): Make prompt string clearer. * simple.el (blink-matching-paren-distance): Change default to 12,000. Tue May 4 12:42:19 1993 Richard Stallman * vc.el (minor-mode-map-alist): Don't use it if it's void. (vc-cancel-version): Doc fix. One entry can describe several changes; each change should have its own item. Normally there should be a blank line between items. When items are related (parts of the same change, in different places), group them by leaving no blank line between them. The second entry above contains two items grouped in this way. `C-x 4 a' visits the change log file and creates a new entry unless the most recent entry is for today's date and your name. It also creates a new item for the current file. For many languages, it can even guess the name of the function or other object that was changed. The change log file is visited in Change Log mode. In this major mode, each bunch of grouped items counts as one paragraph, and each entry is considered a page. This facilitates editing the entries. and auto-fill indent each new line like the previous line; this is convenient for entering the contents of an entry. Version control systems are another way to keep track of changes in your program and keep a change log. *Note Log Entries::.  File: emacs, Node: Tags, Next: Emerge, Prev: Change Log, Up: Programs 19.12 Tags Tables ================= A "tags table" is a description of how a multi-file program is broken up into files. It lists the names of the component files and the names and positions of the functions (or other named subunits) in each file. Grouping the related files makes it possible to search or replace through all the files with one command. Recording the function names and positions makes possible the `M-.' command which finds the definition of a function by looking up which of the files it is in. Tags tables are stored in files called "tags table files". The conventional name for a tags table file is `TAGS'. Each entry in the tags table records the name of one tag, the name of the file that the tag is defined in (implicitly), and the position in that file of the tag's definition. Just what names from the described files are recorded in the tags table depends on the programming language of the described file. They normally include all functions and subroutines, and may also include global variables, data types, and anything else convenient. Each name recorded is called a "tag". * Menu: * Tag Syntax:: Tag syntax for various types of code and text files. * Create Tags Table:: Creating a tags table with `etags'. * Select Tags Table:: How to visit a tags table. * Find Tag:: Commands to find the definition of a specific tag. * Tags Search:: Using a tags table for searching and replacing. * List Tags:: Listing and finding tags defined in a file.  File: emacs, Node: Tag Syntax, Next: Create Tags Table, Up: Tags 19.12.1 Source File Tag Syntax ------------------------------ * In Lisp code, any function defined with `defun', any variable defined with `defvar' or `defconst', and in general the first argument of any expression that starts with `(def' in column zero, is a tag. * In Scheme code, tags include anything defined with `def' or with a construct whose name starts with `def'. They also include variables set with `set!' at top level in the file. * In C code, any C function or typedef is a tag, and so are definitions of struct, union and enum. Any `#define' is also a tag, unless `--no-defines' is specified when the tags table is constructed, which sometimes makes the tags file much smaller. In C++ code, member functions are also recognized. * In Yacc or Bison input files, each rule defines as a tag the nonterminal it constructs. The portions of the file that contain C code are parsed as C code. * In Fortran code, functions and subroutines are tags. * In Pascal code, the tags are the functions and procedures defined in the file. * In Perl code, the tags are the procedures defined by the `sub' keyword. * In Prolog code, a tag name appears at the left margin. * In Erlang code, the tags are the functions, records, and macros defined in the file. * In assembler code, labels appearing at the beginning of a line, followed by a colon, are tags. * In LaTeX text, the argument of any of the commands `\chapter', `\section', `\subsection', `\subsubsection', `\eqno', `\label', `\ref', `\cite', `\bibitem', `\part', `\appendix', `\entry', or `\index', is a tag. Other commands can make tags as well, if you specify them in the environment variable `TEXTAGS' before invoking `etags'. The value of this environment variable should be a colon-separated list of commands names. For example, TEXTAGS="def:newcommand:newenvironment" export TEXTAGS specifies (using Bourne shell syntax) that the commands `\def', `\newcommand' and `\newenvironment' also define tags. * You can also generate tags based on regexp matching (*note Create Tags Table::) for any text file.  File: emacs, Node: Create Tags Table, Next: Select Tags Table, Prev: Tag Syntax, Up: Tags 19.12.2 Creating Tags Tables ---------------------------- The `etags' program is used to create a tags table file. It knows the syntax of several languages, as described in *Note Tag Syntax::. Here is how to run `etags': etags INPUTFILES... The `etags' program reads the specified files, and writes a tags table named `TAGS' in the current working directory. `etags' recognizes the language used in an input file based on its file name and contents. You can specify the language with the `--language=NAME' option, described below. If the tags table data become outdated due to changes in the files described in the table, the way to update the tags table is the same way it was made in the first place. It is not necessary to do this often. If the tags table fails to record a tag, or records it for the wrong file, then Emacs cannot possibly find its definition. However, if the position recorded in the tags table becomes a little bit wrong (due to some editing in the file that the tag definition is in), the only consequence is a slight delay in finding the tag. Even if the stored position is very wrong, Emacs will still find the tag, but it must search the entire file for it. So you should update a tags table when you define new tags that you want to have listed, or when you move tag definitions from one file to another, or when changes become substantial. Normally there is no need to update the tags table after each edit, or even every day. One tags table can effectively include another. Specify the included tags file name with the `--include=FILE' option when creating the file that is to include it. The latter file then acts as if it contained all the files specified in the included file, as well as the files it directly contains. If you specify the source files with relative file names when you run `etags', the tags file will contain file names relative to the directory where the tags file was initially written. This way, you can move an entire directory tree containing both the tags file and the source files, and the tags file will still refer correctly to the source files. If you specify absolute file names as arguments to `etags', then the tags file will contain absolute file names. This way, the tags file will still refer to the same files even if you move it, as long as the source files remain in the same place. Absolute file names start with `/', or with `DEVICE:/' on MS-DOS and Windows. When you want to make a tags table from a great number of files, you may have problems listing them on the command line, because some systems have a limit on its length. The simplest way to circumvent this limit is to tell `etags' to read the file names from its standard input, by typing a dash in place of the file names, like this: find . -name "*.[chCH]" -print | etags - Use the option `--language=NAME' to specify the language explicitly. You can intermix these options with file names; each one applies to the file names that follow it. Specify `--language=auto' to tell `etags' to resume guessing the language from the file names and file contents. Specify `--language=none' to turn off language-specific processing entirely; then `etags' recognizes tags by regexp matching alone. `etags --help' prints the list of the languages `etags' knows, and the file name rules for guessing the language. The `--regex' option provides a general way of recognizing tags based on regexp matching. You can freely intermix it with file names. Each `--regex' option adds to the preceding ones, and applies only to the following files. The syntax is: --regex=/TAGREGEXP[/NAMEREGEXP]/ where TAGREGEXP is used to match the lines to tag. It is always anchored, that is, it behaves as if preceded by `^'. If you want to account for indentation, just match any initial number of blanks by beginning your regular expression with `[ \t]*'. In the regular expressions, `\' quotes the next character, and `\t' stands for the tab character. Note that `etags' does not handle the other C escape sequences for special characters. You should not match more characters with TAGREGEXP than that needed to recognize what you want to tag. If the match is such that more characters than needed are unavoidably matched by TAGREGEXP, you may find useful to add a NAMEREGEXP, in order to narrow the tag scope. You can find some examples below. The `-R' option deletes all the regexps defined with `--regex' options. It applies to the file names following it, as you can see from the following example: etags --regex=/REG1/ voo.doo --regex=/REG2/ \ bar.ber -R --lang=lisp los.er Here `etags' chooses the parsing language for `voo.doo' and `bar.ber' according to their contents. `etags' also uses REG1 to recognize additional tags in `voo.doo', and both REG1 and REG2 to recognize additional tags in `bar.ber'. `etags' uses the Lisp tags rules, and no regexp matching, to recognize tags in `los.er'. Here are some more examples. The regexps are quoted to protect them from shell interpretation. Tag the `DEFVAR' macros in the emacs source files: --regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' Tag VHDL files (this example is a single long line, broken here for formatting reasons): --language=none --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' Tag Cobol files (every label starting in column seven): --language=none --regex='/.......[a-zA-Z0-9-]+\./' Tag Postscript files (every label starting in column one): --language=none --regex='#/[^ \t{]+#/' Tag TCL files (this last example shows the usage of a NAMEREGEXP): --lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' For a list of the other available `etags' options, execute `etags --help'.  File: emacs, Node: Select Tags Table, Next: Find Tag, Prev: Create Tags Table, Up: Tags 19.12.3 Selecting a Tags Table ------------------------------ Emacs has at any time one "selected" tags table, and all the commands for working with tags tables use the selected one. To select a tags table, type `M-x visit-tags-table', which reads the tags table file name as an argument. The name `TAGS' in the default directory is used as the default file name. All this command does is store the file name in the variable `tags-file-name'. Emacs does not actually read in the tags table contents until you try to use them. Setting this variable yourself is just as good as using `visit-tags-table'. The variable's initial value is `nil'; that value tells all the commands for working with tags tables that they must ask for a tags table file name to use. Using `visit-tags-table' when a tags table is already loaded gives you a choice: you can add the new tags table to the current list of tags tables, or start a new list. The tags commands use all the tags tables in the current list. If you start a new list, the new tags table is used _instead_ of others. If you add the new table to the current list, it is used _as well as_ the others. When the tags commands scan the list of tags tables, they don't always start at the beginning of the list; they start with the first tags table (if any) that describes the current file, proceed from there to the end of the list, and then scan from the beginning of the list until they have covered all the tables in the list. You can specify a precise list of tags tables by setting the variable `tags-table-list' to a list of strings, like this: (setq tags-table-list '("~/emacs" "/usr/local/lib/emacs/src")) This tells the tags commands to look at the `TAGS' files in your `~/emacs' directory and in the `/usr/local/lib/emacs/src' directory. The order depends on which file you are in and which tags table mentions that file, as explained above. Do not set both `tags-file-name' and `tags-table-list'.  File: emacs, Node: Find Tag, Next: Tags Search, Prev: Select Tags Table, Up: Tags 19.12.4 Finding a Tag --------------------- The most important thing that a tags table enables you to do is to find the definition of a specific tag. `M-. TAG ' Find first definition of TAG (`find-tag'). `C-u M-.' Find next alternate definition of last tag specified. `C-u - M-.' Go back to previous tag found. `C-M-. PATTERN ' Find a tag whose name matches PATTERN (`find-tag-regexp'). `C-u C-M-.' Find the next tag whose name matches the last pattern used. `C-x 4 . TAG ' Find first definition of TAG, but display it in another window (`find-tag-other-window'). `C-x 5 . TAG ' Find first definition of TAG, and create a new frame to select the buffer (`find-tag-other-frame'). `M-.' (`find-tag') is the command to find the definition of a specified tag. It searches through the tags table for that tag, as a string, and then uses the tags table info to determine the file that the definition is in and the approximate character position in the file of the definition. Then `find-tag' visits that file, moves point to the approximate character position, and searches ever-increasing distances away to find the tag definition. If an empty argument is given (just type ), the sexp in the buffer before or around point is used as the TAG argument. *Note Lists::, for info on sexps. You don't need to give `M-.' the full name of the tag; a part will do. This is because `M-.' finds tags in the table which contain TAG as a substring. However, it prefers an exact match to a substring match. To find other tags that match the same substring, give `find-tag' a numeric argument, as in `C-u M-.'; this does not read a tag name, but continues searching the tags table's text for another tag containing the same substring last used. If you have a real key, `M-0 M-.' is an easier alternative to `C-u M-.'. Like most commands that can switch buffers, `find-tag' has a variant that displays the new buffer in another window, and one that makes a new frame for it. The former is `C-x 4 .', which invokes the command `find-tag-other-window'. The latter is `C-x 5 .', which invokes `find-tag-other-frame'. To move back to places you've found tags recently, use `C-u - M-.'; more generally, `M-.' with a negative numeric argument. This command can take you to another buffer. `C-x 4 .' with a negative argument finds the previous tag location in another window. The command `C-M-.' (`find-tag-regexp') visits the tags that match a specified regular expression. It is just like `M-.' except that it does regexp matching instead of substring matching.  File: emacs, Node: Tags Search, Next: List Tags, Prev: Find Tag, Up: Tags 19.12.5 Searching and Replacing with Tags Tables ------------------------------------------------ The commands in this section visit and search all the files listed in the selected tags table, one by one. For these commands, the tags table serves only to specify a sequence of files to search. `M-x tags-search REGEXP ' Search for REGEXP through the files in the selected tags table. `M-x tags-query-replace REGEXP REPLACEMENT ' Perform a `query-replace-regexp' on each file in the selected tags table. `M-,' Restart one of the commands above, from the current location of point (`tags-loop-continue'). `M-x tags-search' reads a regexp using the minibuffer, then searches for matches in all the files in the selected tags table, one file at a time. It displays the name of the file being searched so you can follow its progress. As soon as it finds an occurrence, `tags-search' returns. Having found one match, you probably want to find all the rest. To find one more match, type `M-,' (`tags-loop-continue') to resume the `tags-search'. This searches the rest of the current buffer, followed by the remaining files of the tags table. `M-x tags-query-replace' performs a single `query-replace-regexp' through all the files in the tags table. It reads a regexp to search for and a string to replace with, just like ordinary `M-x query-replace-regexp'. It searches much like `M-x tags-search', but repeatedly, processing matches according to your input. *Note Replace::, for more information on query replace. It is possible to get through all the files in the tags table with a single invocation of `M-x tags-query-replace'. But often it is useful to exit temporarily, which you can do with any input event that has no special query replace meaning. You can resume the query replace subsequently by typing `M-,'; this command resumes the last tags search or replace command that you did. The commands in this section carry out much broader searches than the `find-tag' family. The `find-tag' commands search only for definitions of tags that match your substring or regexp. The commands `tags-search' and `tags-query-replace' find every occurrence of the regexp, as ordinary search commands and replace commands do in the current buffer. These commands create buffers only temporarily for the files that they have to search (those which are not already visited in Emacs buffers). Buffers in which no match is found are quickly killed; the others continue to exist. It may have struck you that `tags-search' is a lot like `grep'. You can also run `grep' itself as an inferior of Emacs and have Emacs show you the matching lines one by one. This works much like running a compilation; finding the source locations of the `grep' matches works like finding the compilation errors. *Note Compilation::.  File: emacs, Node: List Tags, Prev: Tags Search, Up: Tags 19.12.6 Tags Table Inquiries ---------------------------- `M-x list-tags FILE ' Display a list of the tags defined in the program file `file'. `M-x tags-apropos REGEXP ' Display a list of all tags matching REGEXP. `M-x list-tags' reads the name of one of the files described by the selected tags table, and displays a list of all the tags defined in that file. The "file name" argument is really just a string to compare against the file names recorded in the tags table; it is read as a string rather than as a file name. Therefore, completion and defaulting are not available, and you must enter the file name the same way it appears in the tags table. Do not include a directory as part of the file name unless the file name recorded in the tags table includes a directory. `M-x tags-apropos' is like `apropos' for tags (*note Apropos::). It reads a regexp, then finds all the tags in the selected tags table whose entries match that regexp, and displays the tag names found. You can also perform completion in the buffer on the name space of tag names in the current tags tables. *Note Symbol Completion::.  File: emacs, Node: Emerge, Next: C Mode, Prev: Tags, Up: Programs 19.13 Merging Files with Emerge =============================== It's not unusual for programmers to get their signals crossed and modify the same program in two different directions. To recover from this confusion, you need to merge the two versions. Emerge makes this easier. See also *Note Comparing Files::. * Menu: * Overview of Emerge:: How to start Emerge. Basic concepts. * Submodes of Emerge:: Fast mode vs. Edit mode. Skip Prefers mode and Auto Advance mode. * State of Difference:: You do the merge by specifying state A or B for each difference. * Merge Commands:: Commands for selecting a difference, changing states of differences, etc. * Exiting Emerge:: What to do when you've finished the merge. * Combining in Emerge:: How to keep both alternatives for a difference. * Fine Points of Emerge:: Misc.  File: emacs, Node: Overview of Emerge, Next: Submodes of Emerge, Up: Emerge 19.13.1 Overview of Emerge -------------------------- To start Emerge, run one of these four commands: `M-x emerge-files' Merge two specified files. `M-x emerge-files-with-ancestor' Merge two specified files, with reference to a common ancestor. `M-x emerge-buffers' Merge two buffers. `M-x emerge-buffers-with-ancestor' Merge two buffers with reference to a common ancestor in a third buffer. The Emerge commands compare two files or buffers, and display the comparison in three buffers: one for each input text (the "A buffer" and the "B buffer"), and one (the "merge buffer") where merging takes place. The merge buffer shows the full merged text, not just the differences. Wherever the two input texts differ, you can choose which one of them to include in the merge buffer. The Emerge commands that take input from existing buffers use only the accessible portions of those buffers, if they are narrowed (*note Narrowing::). If a common ancestor version is available, from which the two texts to be merged were both derived, Emerge can use it to guess which alternative is right. Wherever one current version agrees with the ancestor, Emerge presumes that the other current version is a deliberate change which should be kept in the merged version. Use the `with-ancestor' commands if you want to specify a common ancestor text. These commands read three file or buffer names--variant A, variant B, and the common ancestor. After the comparison is done and the buffers are prepared, the interactive merging starts. You control the merging by typing special "merge commands" in the merge buffer. The merge buffer shows you a full merged text, not just differences. For each run of differences between the input texts, you can choose which one of them to keep, or edit them both together. The merge buffer uses a special major mode, Emerge mode, with commands for making these choices. But you can also edit the buffer with ordinary Emacs commands. At any given time, the attention of Emerge is focused on one particular difference, called the "selected" difference. This difference is marked off in the three buffers like this: vvvvvvvvvvvvvvvvvvvv TEXT THAT DIFFERS ^^^^^^^^^^^^^^^^^^^^ Emerge numbers all the differences sequentially and the mode line always shows the number of the selected difference. Normally, the merge buffer starts out with the A version of the text. But when the A version of a difference agrees with the common ancestor, then the B version is initially preferred for that difference. Emerge leaves the merged text in the merge buffer when you exit. At that point, you can save it in a file with `C-x C-w'. If you give a numeric argument to `emerge-files' or `emerge-files-with-ancestor', it reads the name of the output file using the minibuffer. (This is the last file name those commands read.) Then exiting from Emerge saves the merged text in the output file. Normally, Emerge commands save the output buffer in its file when you exit. If you abort Emerge with `C-]', the Emerge command does not save the output buffer, but you can save it yourself if you wish.  File: emacs, Node: Submodes of Emerge, Next: State of Difference, Prev: Overview of Emerge, Up: Emerge 19.13.2 Submodes of Emerge -------------------------- You can choose between two modes for giving merge commands: Fast mode and Edit mode. In Fast mode, basic merge commands are single characters, but ordinary Emacs commands are disabled. This is convenient if you use only merge commands. In Edit mode, all merge commands start with the prefix key `C-c C-c', and the normal Emacs commands are also available. This allows editing the merge buffer, but slows down Emerge operations. Use `e' to switch to Edit mode, and `C-c C-c f' to switch to Fast mode. The mode line indicates Edit and Fast modes with `E' and `F'. Emerge has two additional submodes that affect how particular merge commands work: Auto Advance mode and Skip Prefers mode. If Auto Advance mode is in effect, the `a' and `b' commands advance to the next difference. This lets you go through the merge faster as long as you simply choose one of the alternatives from the input. The mode line indicates Auto Advance mode with `A'. If Skip Prefers mode is in effect, the `n' and `p' commands skip over differences in states prefer-A and prefer-B (*note State of Difference::). Thus you see only differences for which neither version is presumed "correct". The mode line indicates Skip Prefers mode with `S'. Use the command `s a' (`emerge-auto-advance-mode') to set or clear Auto Advance mode. Use `s s' (`emerge-skip-prefers-mode') to set or clear Skip Prefers mode. These commands turn on the mode with a positive argument, turns it off with a negative or zero argument, and toggle the mode with no argument.  File: emacs, Node: State of Difference, Next: Merge Commands, Prev: Submodes of Emerge, Up: Emerge 19.13.3 State of a Difference ----------------------------- In the merge buffer, a difference is marked with lines of `v' and `^' characters. Each difference has one of these seven states: A The difference is showing the A version. The `a' command always produces this state; the mode line indicates it with `A'. B The difference is showing the B version. The `b' command always produces this state; the mode line indicates it with `B'. default-A default-B The difference is showing the A or the B state by default, because you haven't made a choice. All differences start in the default-A state (and thus the merge buffer is a copy of the A buffer), except those for which one alternative is "preferred" (see below). When you select a difference, its state changes from default-A or default-B to plain A or B. Thus, the selected difference never has state default-A or default-B, and these states are never displayed in the mode line. The command `d a' chooses default-A as the default state, and `d b' chooses default-B. This chosen default applies to all differences which you haven't ever selected and for which no alternative is preferred. If you are moving through the merge sequentially, the differences you haven't selected are those following the selected one. Thus, while moving sequentially, you can effectively make the A version the default for some sections of the merge buffer and the B version the default for others by using `d a' and `d b' between sections. prefer-A prefer-B The difference is showing the A or B state because it is "preferred". This means that you haven't made an explicit choice, but one alternative seems likely to be right because the other alternative agrees with the common ancestor. Thus, where the A buffer agrees with the common ancestor, the B version is preferred, because chances are it is the one that was actually changed. These two states are displayed in the mode line as `A*' and `B*'. combined The difference is showing a combination of the A and B states, as a result of the `x c' or `x C' commands. Once a difference is in this state, the `a' and `b' commands don't do anything to it unless you give them a numeric argument. The mode line displays this state as `comb'.  File: emacs, Node: Merge Commands, Next: Exiting Emerge, Prev: State of Difference, Up: Emerge 19.13.4 Merge Commands ---------------------- Here are the Merge commands for Fast mode; in Edit mode, precede them with `C-c C-c': `p' Select the previous difference. `n' Select the next difference. `a' Choose the A version of this difference. `b' Choose the B version of this difference. `C-u N j' Select difference number N. `.' Select the difference containing point. You can use this command in the merge buffer or in the A or B buffer. `q' Quit--finish the merge. `C-]' Abort--exit merging and do not save the output. `f' Go into Fast mode. (In Edit mode, this is actually `C-c C-c f'.) `e' Go into Edit mode. `l' Recenter (like `C-l') all three windows. `-' Specify part of a prefix numeric argument. `DIGIT' Also specify part of a prefix numeric argument. `d a' Choose the A version as the default from here down in the merge buffer. `d b' Choose the B version as the default from here down in the merge buffer. `c a' Copy the A version of this difference into the kill ring. `c b' Copy the B version of this difference into the kill ring. `i a' Insert the A version of this difference at point. `i b' Insert the B version of this difference at point. `m' Put point and mark around the difference. `^' Scroll all three windows down (like `M-v'). `v' Scroll all three windows up (like `C-v'). `<' Scroll all three windows left (like `C-x <'). `>' Scroll all three windows right (like `C-x >'). `|' Reset horizontal scroll on all three windows. `x 1' Shrink the merge window to one line. (Use `C-u l' to restore it to full size.) `x c' Combine the two versions of this difference (*note Combining in Emerge::). `x f' Show the names of the files/buffers Emerge is operating on, in a Help window. (Use `C-u l' to restore windows.) `x j' Join this difference with the following one. (`C-u x j' joins this difference with the previous one.) `x s' Split this difference into two differences. Before you use this command, position point in each of the three buffers at the place where you want to split the difference. `x t' Trim identical lines off top and bottom of the difference. Such lines occur when the A and B versions are identical but differ from the ancestor version.  File: emacs, Node: Exiting Emerge, Next: Combining in Emerge, Prev: Merge Commands, Up: Emerge 19.13.5 Exiting Emerge ---------------------- The `q' command (`emerge-quit') finishes the merge, storing the results into the output file if you specified one. It restores the A and B buffers to their proper contents, or kills them if they were created by Emerge and you haven't changed them. It also disables the Emerge commands in the merge buffer, since executing them later could damage the contents of the various buffers. `C-]' aborts the merge. This means exiting without writing the output file. If you didn't specify an output file, then there is no real difference between aborting and finishing the merge. If the Emerge command was called from another Lisp program, then its return value is `t' for successful completion, or `nil' if you abort.  File: emacs, Node: Combining in Emerge, Next: Fine Points of Emerge, Prev: Exiting Emerge, Up: Emerge 19.13.6 Combining the Two Versions ---------------------------------- Sometimes you want to keep _both_ alternatives for a particular difference. To do this, use `x c', which edits the merge buffer like this: #ifdef NEW VERSION FROM A BUFFER #else /* NEW */ VERSION FROM B BUFFER #endif /* NEW */ While this example shows C preprocessor conditionals delimiting the two alternative versions, you can specify the strings to use by setting the variable `emerge-combine-versions-template' to a string of your choice. In the string, `%a' says where to put version A, and `%b' says where to put version B. The default setting, which produces the results shown above, looks like this: "#ifdef NEW\n%a#else /* NEW */\n%b#endif /* NEW */\n"  File: emacs, Node: Fine Points of Emerge, Prev: Combining in Emerge, Up: Emerge 19.13.7 Fine Points of Emerge ----------------------------- During the merge, you mustn't try to edit the A and B buffers yourself. Emerge modifies them temporarily, but ultimately puts them back the way they were. You can have any number of merges going at once--just don't use any one buffer as input to more than one merge at once, since the temporary changes made in these buffers would get in each other's way. Starting Emerge can take a long time because it needs to compare the files fully. Emacs can't do anything else until `diff' finishes. Perhaps in the future someone will change Emerge to do the comparison in the background when the input files are large--then you could keep on doing other things with Emacs until Emerge is ready to accept commands. After setting up the merge, Emerge runs the hook `emerge-startup-hook' (*note Hooks::).  File: emacs, Node: C Mode, Next: Fortran, Prev: Emerge, Up: Programs 19.14 C Mode ============ This section describes special features available in C, C++, Objective-C and Java modes. * Menu: * Motion in C:: * Electric C:: * Hungry Delete:: * Other C Commands:: * Comments in C::  File: emacs, Node: Motion in C, Next: Electric C, Up: C Mode 19.14.1 C Mode Motion Commands ------------------------------ This section commands for moving point, in C mode and related modes. `C-c C-u' Move point back to the containing preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move point forward to the end of the containing preprocessor conditional. When going backwards, `#elif' is treated like `#else' followed by `#if'. When going forwards, `#elif' is ignored. `C-c C-p' Move point back over a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move forward. `C-c C-n' Move point forward across a preprocessor conditional, leaving the mark behind. A prefix argument acts as a repeat count. With a negative argument, move backward. `M-a' Move point to the beginning of the innermost C statement. If point is already at the beginning of a statement, move to the beginning of the preceding statement. With prefix argument N, move back N - 1 statements. If point is within a string or comment, or next to a comment (only whitespace between them), this command moves by sentences instead of statements. When called from a program, this function takes two optional arguments: the numeric prefix argument, and a buffer position limit (don't move back before that place). `M-e' Move point to the end of the innermost C statement. If point is at the end of a statement, move to the end of the next statement. With prefix argument N, move forward N - 1 statements. If point is within a string or comment, or next to a comment (only whitespace between them), this command moves by sentences instead of statements. When called from a program, this function takes two optional arguments: the numeric prefix argument, and a buffer position limit (don't move past that place). `M-x c-backward-into-nomenclature' Move point backward to beginning of a C++ nomenclature section or word. With prefix argument N, move N times. If N is negative, move forward. C++ nomenclature means a symbol name in the style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter begins a section or word. In the GNU project, we recommend using underscores to separate words within an identifier in C or C++, rather than using case distinctions. `M-x c-forward-into-nomenclature' Move point forward to end of a C++ nomenclature section or word. With prefix argument N, move N times.  File: emacs, Node: Electric C, Next: Hungry Delete, Prev: Motion in C, Up: C Mode 19.14.2 Electric C Characters ----------------------------- In C mode and related modes, certain printing characters are "electric"--in addition to inserting themselves, they also reindent the current line and may insert newlines. This feature is controlled by the variable `c-auto-newline'. The "electric" characters are `{', `}', `:', `#', `;', `,', `<', `>', `/' and `*'. Electric characters insert newlines only when the "auto-newline" feature is enabled (indicated by `/a' in the mode line after the mode name). This feature is controlled by the variable `c-auto-newline'. You can turn this feature on or off with the command `C-c C-a': `C-c C-a' Toggle the auto-newline feature (`c-toggle-auto-state'). With a prefix argument, this command turns the auto-newline feature on if the argument is positive, and off if it is negative. The colon character is electric because that is appropriate for a single colon. But when you want to insert a double colon in C++, the electric behavior of colon is inconvenient. You can insert a double colon with no reindentation or newlines by typing `C-c :': `C-c :' Insert a double colon scope operator at point, without reindenting the line or adding any newlines (`c-scope-operator'). The electric `#' key reindents the line if it appears to be the beginning of a preprocessor directive. This happens when the value of `c-electric-pound-behavior' is `(alignleft)'. You can turn this feature off by setting `c-electric-pound-behavior' to `nil'. The variable `c-hanging-braces-alist' controls the insertion of newlines before and after inserted braces. It is an association list with elements of the following form: `(SYNTACTIC-SYMBOL . NL-LIST)'. Most of the syntactic symbols that appear in `c-offsets-alist' are meaningful here as well. The list NL-LIST may contain either of the symbols `before' or `after', or both; or it may be `nil'. When a brace is inserted, the syntactic context it defines is looked up in `c-hanging-braces-alist'; if it is found, the NL-LIST is used to determine where newlines are inserted: either before the brace, after, or both. If not found, the default is to insert a newline both before and after braces. The variable `c-hanging-colons-alist' controls the insertion of newlines before and after inserted colons. It is an association list with elements of the following form: `(SYNTACTIC-SYMBOL . NL-LIST)'. The list NL-LIST may contain either of the symbols `before' or `after', or both; or it may be `nil'. When a colon is inserted, the syntactic symbol it defines is looked up in this list, and if found, the NL-LIST is used to determine where newlines are inserted: either before the brace, after, or both. If the syntactic symbol is not found in this list, no newlines are inserted. Electric characters can also delete newlines automatically when the auto-newline feature is enabled. This feature makes auto-newline more acceptable, by deleting the newlines in the most common cases where you do not want them. Emacs can recognize several cases in which deleting a newline might be desirable; by setting the variable `c-cleanup-list', you can specify _which_ of these cases that should happen. The variable's value is a list of symbols, each describing one case for possible deletion of a newline. Here are the meaningful symbols, and their meanings: `brace-else-brace' Clean up `} else {' constructs by placing entire construct on a single line. The clean-up occurs when you type the `{' after the `else', but only if there is nothing but white space between the braces and the `else'. `empty-defun-braces' Clean up empty defun braces by placing the braces on the same line. Clean-up occurs when you type the closing brace. `defun-close-semi' Clean up the semicolon after a `struct' or similar type declaration, by placing the semicolon on the same line as the closing brace. Clean-up occurs when you type the semicolon. `list-close-comma' Clean up commas following braces in array and aggregate initializers. Clean-up occurs when you type the comma. `scope-operator' Clean up double colons which may designate a C++ scope operator, by placing the colons together. Clean-up occurs when you type the second colon, but only when the two colons are separated by nothing but whitespace.  File: emacs, Node: Hungry Delete, Next: Other C Commands, Prev: Electric C, Up: C Mode 19.14.3 Hungry Delete Feature in C ---------------------------------- When the "hungry-delete" feature is enabled (indicated by `/h' or `/ah' in the mode line after the mode name), a single command deletes all preceding whitespace, not just one space. To turn this feature on or off, use `C-c C-d': `C-c C-d' Toggle the hungry-delete feature (`c-toggle-hungry-state'). With a prefix argument, this command turns the hungry-delete feature on if the argument is positive, and off if it is negative. `C-c C-t' Toggle the auto-newline and hungry-delete features, both at once (`c-toggle-auto-hungry-state'). The variable `c-hungry-delete-key' controls whether the hungry-delete feature is enabled.