Fresh Fish 6

home *** CD-ROM | disk | FTP | other *** search

/ Fresh Fish 6 / FreshFish_September1994.bin / bbs / gnu / emacs-18.59-src.lha / GNU / src / amiga / emacs-18.59 / info / emacs-14 < prev next >

Wrap

GNU Info File | 1992-10-31 | 49.6 KB | 1,335 lines

This is Info file ../info/emacs, produced by Makeinfo-1.49 from the input file emacs.texi. This file documents the GNU Emacs editor. Copyright (C) 1985, 1986, 1988, 1992 Richard M. Stallman. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled "The GNU Manifesto", "Distribution" and "GNU General Public License" are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the sections entitled "The GNU Manifesto", "Distribution" and "GNU General Public License" may be included in a translation approved by the author instead of in the original English. File: emacs, Node: Concepts of VC, Next: Editing with VC, Up: Version Control Concepts of Version Control --------------------------- When a file is under version control, we also say that it is "registered" in the version control system. Each registered file has a corresponding "master file" which represents the file's present state plus its change history, so that you can reconstruct from it either the current version or any specified earlier version. Usually the master file also records a change comment for each version. The file that is maintained under version control is sometimes called the "work file" corresponding to its master file. To examine a file, you "check it out". This extracts a version of the file (typically, the most recent) from the master. If you want to edit the file, you must check it out "locked". Only one user can do this at a time for any given source file. When you are done with your editing, you must "check in" the new version. This records the new version in the master file, and unlocks the source file so that other people can lock it and thus modify it. These are the basic operations of version control. Checking in and checking out both use the single Emacs command `C-x C-q' (`vc-toggle-read-only'). File: emacs, Node: Editing with VC, Next: Variables for Check-in/out, Prev: Concepts of VC, Up: Version Control Editing with Version Control ---------------------------- When you visit a file that is maintained using version control, the mode line displays `RCS' or `SCCS' to inform you that version control is in use, and also (in case you care) which low-level system the file is actually stored in. Normally, such a source file is read-only, and the mode line indicates this with `%%'.) These are the commands that you use to edit a file maintained with version control: `C-x C-q' Check the visited file in or out. `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 check-in. `C-x v i' Register the visited file in version control. (`C-x v' is the prefix key for version control commands; all of these commands except for `C-x C-q' start with `C-x v'.) If you want to edit the file, type `C-x C-q' (`vc-toggle-read-only'). This "checks out" and locks the file, so that you can edit it. The file is writable after check-out, but only for you, not for anyone else. Emacs does not save backup files for source files that are maintained with version control. If you want to make backup files despite version control, set the variable `vc-make-backups' to a non-`nil' value. 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 a "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. Once you have checked in your changes, the file is unlocked, so that other users can lock it and modify it. 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. Actually, 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 or her of what has happened. 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' requies 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 if you lock a file and then don't actually change it. You can even cancel a change after checking it in, with `C-x v c' (`vc-cancel-version'). Normally, `C-x v c' reverts your workfile and buffer to the previous version (the one that precedes the version that is deleted), but you can prevent the reversion by giving the command a prefix argument. Then the buffer does not change. This command with a prefix argument 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 repeat the check-in. 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 asks for confirmation with `yes'. You can register the visited file for version control using `C-x v i' (`vc-register'). This uses RCS if RCS is installed on your system; otherwise, it uses SCCS. By default, the initial version number is 1.1. If you want to use a different number, give `C-x v i' a prefix argument; then it reads the initial version number using the minibuffer. After `C-x v i', the file is unlocked and read-only. Type `C-x C-q' if you wish to edit it. 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: Variables for Check-in/out, Next: Comparing Versions, Prev: Editing with VC, Up: Version Control Variables Affecting Check-in and Check-out ------------------------------------------ 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 is so drastic that it should always ask for confirmation.) VC mode does much of its work by running the shell commands for RCS 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. Normally, VC assumes that it can deduce the locked/unlocked state of files by looking at the file permissions of the work file; this is fast. However, if the `RCS' or `SCCS' subdirectory is actually a symbolic link, then VC does not trust the file permissions to reflect this status. 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' 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, then you can set `vc-mistrust-permissions' to `t' so that VC always checks the master file. File: emacs, Node: Log Entries, Next: Change Logs and VC, Prev: Snapshots, Up: Version Control Log Entries ----------- When you're editing an initial or change comment 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 comment 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 they don't use the minibuffer). The history of previous log entries is actually stored in previous pages of the log entry editing buffer; they are normally hidden by narrowing. Each time you check in a file, the log entry buffer is put into VC Log mode, which involves running two hook variables: `text-mode-hook' and `vc-log-mode-hook'. File: emacs, Node: Change Logs and VC, Next: Version Headers, Prev: Log Entries, Up: Version Control Change Logs and VC ------------------ Emacs users often record brief summaries of program changes in a file called `ChangeLog', which is kept in the same directory as the source files, and is usually meant to be distributed along with the source files. You can maintain `ChangeLog' from the version control logs with the following command. `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 SCCS. For example, suppose the first line of `ChangeLog' is dated 10 April 1992, and suppose 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 (nat@apn.org) * rcs2log: Ignore log messages that start with `#'. You can then further edit as you wish. 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'. 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 check-ins 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 (nat@apn.org) * 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 (nat@apn.org) * vc.texinfo: Fix expansion typos. * vc.el, vc-hooks.el: Don't call expand-file-name. Normally, the log entry for file `foo' is displayed as `* foo: TEXT OF LOG ENTRY'. But by convention, 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 (nat@apn.org) * vc.el (vc-do-command): Check call-process status. File: emacs, Node: Comparing Versions, Next: VC Status, Prev: Variables for Check-in/out, Up: Version Control Comparing Versions ------------------ To compare two versions of a file, use `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. With a prefix argument, `C-x v =' reads a filename and two version numbers, and compares those versions of the file you specify. 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; you can specify the most recent checked-in version with `-'; and you can specify the current buffer contents with `+'. Thus, you can compare two checked-in versions, or compare a checked-in version with the text you are editing. 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. File: emacs, Node: VC Status, Next: Renaming and VC, Prev: Comparing Versions, Up: Version Control VC Status Commands ------------------ To get the detailed version control status of one 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 do so using these commands, both of which operate on the branch of the file system starting at the current directory. You can use `C-x v d' (`vc-directory') to show all the locked files in or beneath the current directory. This includes all files that are locked by any user. With a prefix argument, `C-x v d' shows all the version control activity in the current directory--it lists all files in or beneath the current directory that are maintained with version control. File: emacs, Node: Renaming and VC, Next: Snapshots, Prev: VC Status, Up: Version Control 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. `vc-rename-file' is not bound to a key because it's not likely to be used frequently. File: emacs, Node: Snapshots, Next: Log Entries, Prev: Renaming and VC, Up: Version Control 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 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 RET' 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 RET' Check out all registered files at or below the current directory level using whatever versions correspond to the snapshot NAME (`vc-retrieve-snapshot'). This function 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. You shouldn't need to use `vc-retrieve-snapshot' very often; you can get difference reports between two snapshots without retrieving either one, using `C-x =' (*note Comparing Versions::.). Thus, retrieving a snapshot is only necessary if you need to study or compile portions of the snapshot. 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 =' (*note Comparing 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 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. 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 function `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). This 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. If you use snapshots, don't rename either work files or master files except by means of `vc-rename-file'. It knows how to update snapshots so that you can still retrieve them. 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 teach the reader how to update the snapshots by hand. File: emacs, Node: Version Headers, Prev: Change Logs and VC, Up: Version Control 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. 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 `$ld$' for RCS and `%W%' for SCCS. You can specify other headers to insert by setting the variable `vc-header-string'. Its value (if non-`nil') should be the string to be inserted. You can also 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 important to use "superfluous" backslashes when writing a Lisp string constant for this use, 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)'. `vc-static-header-alist' is consulted to add further strings based on the name of the buffer. Its value should be a list of dotted pairs; the CAR of each pair is a regular expression that should match the buffer name, and the CDR is the format to use on each header. A string is inserted for each file name pattern that matches the buffer name, and for each header taken from `vc-header-string'. The default value for `vc-static-header-alist' is: (("\\.c$" . "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ #endif /* lint */\n")) which specifies insertion of a string of this form: #ifndef lint static char vcid[] = "HEADER-STRING"; #endif /* lint */ File: emacs, Node: Emerge, Next: Debuggers, Prev: Version Control, Up: Version 19 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. * Menu: * Overview of Emerge:: * Submodes of Emerge:: * State of Difference:: * Merge Commands:: * Exiting Emerge:: * Combining in Emerge:: * Fine Points of Emerge:: File: emacs, Node: Overview of Emerge, Next: Submodes of Emerge, Up: Emerge 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 (the currently accessible portions). `M-x emerge-buffers-with-ancestor' Merge two buffers (the currently accessible portions) with reference to a common ancestor in another buffer. The Emerge commands compare two texts, and display the results 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 does not show just the differences. Rather, it shows you the full text, but wherever the input texts differ, you can choose which one of them to include in the merge buffer. 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 actual merging starts. You control the merging interactively by editing the merge buffer. The merge buffer shows you a full merged text, not just differences. For each point where the input texts differ, you can choose which one of them to include in the merge buffer. The merge buffer has 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 by vvvvvvvvvvvvvvvvvvvv above and ^^^^^^^^^^^^^^^^^^^^ below. 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 part of the buffer agrees with the common ancestor, then the B version is preferred for that part. Normally, Emerge stores the merged output in place of the first input text (the A file or buffer). If you give a prefix 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.) If you abort Emerge with `C-u q', the output is not saved. File: emacs, Node: Submodes of Emerge, Next: State of Difference, Prev: Overview of Emerge, Up: Emerge Submodes of Emerge ------------------ You can choose between two modes for giving merge commands: Fast mode and Edit mode. In Fast mode, basic Emerge commands are single characters, but ordinary Emacs commands are disabled. This is convenient if you use only Emerge commands. In Edit mode, all Emerge commands start with the prefix character `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 `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 doing ordinary things. 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. Thus you will only see differences for which neither version is presumed "correct". The mode line indicates Skip Prefers mode with `S'. Use the command `emerge-auto-advance-mode' to set or clear Auto Advance mode. Use `emerge-skip-prefers-mode' to set or clear Skip Prefers mode. A positive argument turns the mode on, a nonpositive argument turns it off, and no argument toggles it. File: emacs, Node: State of Difference, Next: Merge Commands, Prev: Submodes of Emerge, Up: Emerge State of a Difference --------------------- In the merge buffer, a difference is marked `vvvvvvvvvvvvvvvvvvvv' above and `^^^^^^^^^^^^^^^^^^^^' below. Such a difference can have one of 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 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' at the end of each section. 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 prefix argument. The mode line displays this state as `comb'. File: emacs, Node: Merge Commands, Next: Exiting Emerge, Prev: State of Difference, Up: Emerge Merge Commands -------------- Here are the Merge commands for Fast mode; in Edit mode, precede these with `C-c' and turn all the letters into control characters. `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. `j' Select a particular difference; specify the sequence number of that difference as a prefix argument. `M-x emerge-select-difference' Select the run of differences containing the current location. You can use this command in the merge buffer or in the A or B buffer. `q' Quit--finish the merge. With an argument, abort the merge. `f' Go into fast mode. `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 the point. `i b' Insert the B version of this difference at the point. `m' Put the point and mark around the difference region. `^' 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. `x f' Show the files/buffers Emerge is operating on in 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 to 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 Exiting Emerge -------------- The `q' (`emerge-quit') command finishes the merge, storing the results into the output file. It restores the A and B buffers to their proper contents, or kills them if they were created by Emerge. It also disables the Emerge commands in the merge buffer, since executing them later could damage the contents of the various buffers. `C-u q' aborts the merge. Aborting means that Emerge does not write the output file. If Emerge was called from another Lisp program, then its return value is `t' or `nil' to indicate success or failure. File: emacs, Node: Combining in Emerge, Next: Fine Points of Emerge, Prev: Exiting Emerge, Up: Emerge Combining the Two Versions -------------------------- Sometimes you want to keep *both* alternatives for a particular locus. To do this, use `x c', which edits the merge buffer like this: #ifdef NEW VERSION FROM A FILE #else /* NEW */ VERSION FROM B FILE #endif /* NEW */ While this example shows C preprocessor conditionals delimiting the two alternative versions, you can specify the strings you want by setting the variable `emerge-combine-template' to a list of three strings. The default setting, which produces the results shown above, looks like this: ("#ifdef NEW\n" "#else /* NEW */\n" "#endif /* NEW */\n") File: emacs, Node: Fine Points of Emerge, Prev: Combining in Emerge, Up: Emerge Fine Points of Emerge --------------------- 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 that will cause the read-only/modified/auto-save status save-and-restore to screw up. Starting Emerge can take a long time because it needs to compare the files. 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 gets ready to accept commands. After the merge has been set up, Emerge runs the hooks in `emerge-startup-hook'. During the merge, you musn't try to edit the A and B buffers yourself. Emerge modifies them temporarily, but ultimately puts them back the way they were. File: emacs, Node: Debuggers, Next: Other New Modes, Prev: Emerge, Up: Version 19 Running Debuggers Under Emacs ============================= The GUD (Grand Unified Debugger) library provides an interface to various symbolic debuggers from within Emacs. We recommend the debugger GDB, which is free software, but you can also run DBX or SDB if you have them. * Menu: * Starting GUD:: How to start a debugger subprocess. * Debugger Operation:: Connection between the debugger and source buffers. * Commands of GUD:: Keybindings for common commands. * GUD Customization:: Defining your own commands for GUD. File: emacs, Node: Starting GUD, Next: Debugger Operation, Up: Debuggers Starting GUD ------------ There are three commands for starting a debugger. Each corresponds to a particular debugger program. `M-x gdb RET FILE RET' `M-x dbx RET FILE RET' Run GDB or DBX in a subprocess of Emacs. Both of these commands select the buffer used for input and output to the debugger. `M-x sdb RET FILE RET' Run SDB in a subprocess of Emacs. SDB's messages do not mention file names, so the Emacs interface to SDB depends on having a tags table (*note Tags::.) to find which file each function is in. If you have not visited a tags table or the tags table doesn't list one of the functions, you get a message saying `The sdb support requires a valid tags table to work'. If this happens, generate a valid tags table in the working directory and try again. You can only run one debugger process at a time. File: emacs, Node: Debugger Operation, Next: Commands of GUD, Prev: Starting GUD, Up: Debuggers Debugger Operation ------------------ When you run a debugger with GUD, the debugger displays source files via Emacs--Emacs finds the source file and moves point to the line where the program is executing. An arrow (`=>') indicates the current execution line, and it stays put even if you move the cursor. You can start editing the file at any time. The arrow is not part of the file's text; it appears only on the screen. If you do modify a source file, keep in mind that inserting or deleting lines will throw off the arrow's positioning; GUD has no way of figuring out which line corresponded before your changes to the line number in a debugger message. Also, you'll typically have to recompile and restart the program for your changes to be reflected in the debugger's tables. If you wish, you can control your debugger process entirely through the debugger buffer, which uses a variant of Shell mode. All the usual commands for your debugger are available, and you can use the Shell mode history commands to repeat them. File: emacs, Node: Commands of GUD, Next: GUD Customization, Prev: Debugger Operation, Up: Debuggers Commands of GUD --------------- GUD provides a command available in all buffers for setting breakpoints. This command is defined globally because you need to use it in the source files' buffers. `C-x SPC' Set a breakpoint on the line that point is on. The debugger buffer has a number of keybindings for invoking common debugging commands quickly: `C-c C-l' Display in another window the last line referred to in the GUD buffer (that is, the line indicated in the last location message). This runs the command `gud-refresh'. `C-c C-s' Execute a single line of code (`gud-step'). If the code contains a function call, execution stops after entering the called function. `C-c C-n' Execute a single line of code, stepping across entire function calls at full speed (`gud-next'). `C-c C-i' Execute a single machine instruction (`gud-stepi'). `C-c C-c' Continue execution until the next breakpoint, or other event that would normally stop the program (`gud-cont'). The above commands are common to all supported debuggers. If you are using GDB or (some versions of) DBX, these additional commands are available: `C-c <' Select the next enclosing stack frame (`gud-up'). This is equivalent to the `up' command. `C-c >' Select the next inner stack frame (`gud-down'). This is equivalent to the `down' command. If you are using GDB, two additional keybindings are available: `C-c C-f' Run the program until the selected stack frame returns (or until it stops for some other reason). `TAB' Complete the symbol in the buffer before point, using the set of all symbols known to GDB. These commands interpret a prefix argument as a repeat count, when that makes sense. After each command that changes the program counter, GUD displays the new current source line, and updates the location of the arrow. File: emacs, Node: GUD Customization, Prev: Commands of GUD, Up: Debuggers GUD Customization ----------------- On startup, GUD executes one of the following hooks: `gdb-mode-hook', if you are using GDB; `dbx-mode-hook', if you are using DBX; and `sdb-mode-hook', if you are using SDB. You can use these hooks to define custom keybindings for the debugger interaction buffer. Here is a convenient way to define a command that sends a particular command string to the debugger, and set up a key binding for it in the debugger interaction buffer: (gud-def FUNCTION CMDSTRING BINDING DOCSTRING) This defines a command named FUNCTION which sends CMDSTRING to the debugger process, with documentation string DOCSTRING, and binds it to BINDING in the debugger buffer's mode. (If BINDING is `nil', this defines the command but does not make a binding for it; you can make a binding explicitly, perhaps using one of the above hooks.) Commands defined with `gud-def' handle prefix arguments by passing them to the debugger, appended to end of CMDSTRING with a space in between. (This use of prefix arguments works with GDB and DBX, but not with SDB.) You can also set up commands that you can send to the debugger while in another buffer, such as a source file. Set the variable `gud-commands' to a list of strings containing debugger commands you might want to send. `C-x &' Send a custom command to the debugger process (`send-gud-command'). Normally, send the CAR of the `gud-commands' list; a prefix argument specifies which element of that list to use (counting from 0). If the string contains `%s', `C-x &' substitutes a numeric value found in the buffer at or near point. It looks for decimal, octal, or hexadecimal numbers, with `0x' allowed. This lets you define commands to chase pointers whose numeric values have been displayed. File: emacs, Node: Other New Modes, Next: Key Sequence Changes, Prev: Debuggers, Up: Version 19 Other New Modes =============== There is now a Perl mode for editing Perl programs and an Icon mode for editing Icon programs. C++ mode is like C mode, except that it understands C++ comment syntax and certain other differences between C and C++. It also has a command `fill-c++-comment' which fills a paragraph made of comment lines. The command `comment-region' is useful in C++ mode for commenting out several consecutive lines, or removing the commenting out of such lines. WordStar emulation is available--type `M-x wordstar-mode'. For more information, type `C-h f wordstar-mode RET'. The command `C-o' in Buffer Menu mode now displays the current line's buffer in another window but does not select it. This is like the existing command `o' which selects the current line's buffer in another window. * Menu: * Asm Mode:: A major mode for editing assembler files. * Edebug Mode:: A new Lisp debugger. * Editing Binary Files::Hexl mode lets you edit a binary file as numbers. File: emacs, Node: Asm Mode, Next: Edebug Mode, Up: Other New Modes Asm Mode -------- Asm mode is a new major mode for editing files of assembler code. It defines these commands: `TAB' `tab-to-tab-stop'. `LFD' Insert a newline and then indent using `tab-to-tab-stop'. `:' Insert a colon and then remove the indentation from before the label preceding colon. Then do `tab-to-tab-stop'. `;' Insert or align a comment. File: emacs, Node: Edebug Mode, Next: Editing Binary Files, Prev: Asm Mode, Up: Other New Modes Edebug Mode ----------- Edebug is a new source-level debugger for Emacs Lisp programs. To use Edebug, use the command `M-x edebug-defun' to "evaluate" a function definition in an Emacs Lisp file. We put "evaluate" in quotation marks because it doesn't just evaluate the function, it also inserts additional information to support source-level debugging. You must also do this: (setq debugger 'edebug-debug) to cause errors and single-stepping to use Edebug instead of the usual Emacs Lisp debugger. For more information, see `The Emacs Extensions Manual', which should be included in the Emacs 19 distribution. File: emacs, Node: Editing Binary Files, Prev: Edebug Mode, Up: Other New Modes Editing Binary Files -------------------- There is a new major mode for editing binary files: Hexl mode. To use it, use `M-x hexl-find-file' instead of `C-x C-f' to visit the file. This command converts the file's contents to hexadecimal and lets you edit the translation. When you save the file, it is converted automatically back to binary. You can also use `M-x hexl-mode' to translate an existing buffer into hex. This is useful if you visit a file normally and discover it is a binary file. Hexl mode has a few other commands: `C-M-d' Insert a byte with a code typed in decimal. `C-M-o' Insert a byte with a code typed in octal. `C-M-x' Insert a byte with a code typed in hex. `C-x [' Move to the beginning of a 1k-byte "page". `C-x ]' Move to the end of a 1k-byte "page". `M-g' Move to an address specified in hex. `M-j' Move to an address specified in decimal. `C-c C-c' Leave Hexl mode, going back to the major mode this buffer had before you invoked `hexl-mode'. File: emacs, Node: Key Sequence Changes, Next: Hook Changes, Prev: Other New Modes, Up: Version 19 Changes in Key Sequences ======================== In Emacs 18, a key sequence was a sequence of characters, which represented keyboard input. In Emacs 19, you can still use a sequence of characters as a key sequence, but you aren't limited to characters. You can also use Lisp symbols which represent terminal function keys or mouse buttons. If the function key has a word as its label, then that word is also the name of the symbol which represents the function key. Other function keys are assigned Lisp names as follows: `kp-add', `kp-decimal', `kp-divide', ... Keypad keys (to the right of the regular keyboard), with names or punctuation `kp-0', `kp-1', ... Keypad keys with digits `kp-f1', `kp-f2', `kp-f3', `kp-f4' Keypad PF keys `left', `up', `right', `down' Cursor arrow keys A key sequence which contains non-characters must be a vector rather than a string. Thus, to bind function key `f1' to `rmail', write the following: (global-set-key [f1] 'rmail) (To find the name of a key, type `C-h k' and then the key.) To bind the right-arrow key to the command `forward-char', you can use this expression: (global-set-key [right] 'forward-char) using the Lisp syntax for a vector containing the symbol `right'. And this is how to make `C-x RIGHTARROW' move forward a page: (global-set-key [?\C-x right] 'forward-page) where `?\C-x' is the Lisp syntax for an integer whose value is the code for the character `C-x'. You can use modifier keys such as CTRL, META and SHIFT with function keys. To represent these modifiers, prepend the strings `C-', `M-' and `S-' to the symbol name. Thus, here is how to make `M-RIGHTARROW' move forward a word: (global-set-key [M-right] 'forward-word) Emacs uses symbols to designate mouse buttons, too. The ordinary mouse events in Emacs are "click" events; these happen when you press a button and release it without moving the mouse. You can also get "drag" events, when you move the mouse while holding the button down. Drag events happen when you finally let go of the button. The symbols for basic click events are `mouse-1' for the leftmost button, `mouse-2' for the next, and so on. Here is how you can redefine the second mouse button to split the current window: (global-set-key [mouse-2] 'split-window-vertically) The symbols for drag events are similar, but have the prefix `drag-' before the word `mouse'. For example, dragging the left button generates a `drag-mouse-1' event. You can also request events when the mouse button is pressed down. These events start with `down-' instead of `drag-'. Such events are generated only if they have key bindings. When you get a button-down event, a corresponding click or drag event will always follow. The symbols for mouse events also indicate the status of the modifier keys, with the usual prefixes `C-', `M-' and `S-'. These always follow `drag-' or `down-'. When mouse events occur in special parts of a frame or window, such as a mode line or a scroll bar, the event symbol shows nothing special. The information about the special part is implicit in other data (the screen location of the event). But `read-key-sequence' figures out this aspect of the event, and encodes it with make-believe prefix keys, all of which are symbols: `mode-line', `vertical-line', `horizontal-scrollbar' and `vertical-scrollbar'. Thus, to define the command for clicking the left button in a mode line, you could use this key sequence: [mode-line mouse-1] You are not limited to defining individual function keys or mouse buttons; these can appear anywhere in a key sequence, just as characters can. You can even mix together all three kinds of inputs in one key sequence--but mixing mouse buttons with keyboard inputs is probably not convenient for actual use. File: emacs, Node: Hook Changes, Prev: Key Sequence Changes, Up: Version 19 Changes Regarding Hooks ======================= A "hook variable" is a variable that exists so that you can store in it functions for Emacs to call on certain occasions. (The functions that you put in hook variables are called "hook functions".) Emacs 19 has a new convention for naming hook variables that indicates more reliably how to use them. All the variables whose names end in `-hook' are "normal hooks"; their values are lists of functions to be called with no arguments. You can use `add-hook' (see below) to install hook functions in these hooks. We have made all Emacs hooks into normal hooks except when there is some reason this won't work. A few hook-like variables are "abnormal"--they don't use the normal convention. This is either because the user-supplied functions receive arguments, or because their return values matter. These variables have names that end in `-function' (if the value is a single function) or `-functions' (if the value is a list of functions). Thus, you can always tell from the variable's name precisely how to install a new hook function in the variable. If the name indicates a normal hook, then you also know how to write your hook function. To add a hook function to a normal hook, use `add-hook'. It takes care of adding a new hook function to any functions already installed in a given hook. It takes two arguments, the hook symbol and the function to add. For example, (add-hook 'text-mode-hook 'my-text-hook-function) is how to arrange to call `my-text-hook-function' when entering Text mode or related modes. Two new hooks are worth noting here. Expansion of an abbrev first runs the hook `pre-abbrev-expand-hook'. `kill-buffer-hook' now runs whenever a buffer is killed.