diff options
Diffstat (limited to 'info/emacs-14')
| -rw-r--r-- | info/emacs-14 | 1335 |
1 files changed, 1335 insertions, 0 deletions
diff --git a/info/emacs-14 b/info/emacs-14 new file mode 100644 index 00000000000..8b28d91c4c9 --- /dev/null +++ b/info/emacs-14 @@ -0,0 +1,1335 @@ +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. + +
\ No newline at end of file |