Return to emacs-14 CVS log

Up to [Apple XNU] / GNUtools / emacs / info

Annotation of GNUtools/emacs/info/emacs-14, revision 1.1

1.1     ! root        1: This is Info file ../info/emacs, produced by Makeinfo-1.49 from the
        !             2: input file emacs.texi.
        !             3: 
        !             4:    This file documents the GNU Emacs editor.
        !             5: 
        !             6:    Copyright (C) 1985, 1986, 1988, 1992 Richard M. Stallman.
        !             7: 
        !             8:    Permission is granted to make and distribute verbatim copies of this
        !             9: manual provided the copyright notice and this permission notice are
        !            10: preserved on all copies.
        !            11: 
        !            12:    Permission is granted to copy and distribute modified versions of
        !            13: this manual under the conditions for verbatim copying, provided also
        !            14: that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
        !            15: General Public License" are included exactly as in the original, and
        !            16: provided that the entire resulting derived work is distributed under the
        !            17: terms of a permission notice identical to this one.
        !            18: 
        !            19:    Permission is granted to copy and distribute translations of this
        !            20: manual into another language, under the above conditions for modified
        !            21: versions, except that the sections entitled "The GNU Manifesto",
        !            22: "Distribution" and "GNU General Public License" may be included in a
        !            23: translation approved by the author instead of in the original English.
        !            24: 
        !            25: 
        !            26: File: emacs,  Node: Concepts of VC,  Next: Editing with VC,  Up: Version Control
        !            27: 
        !            28: Concepts of Version Control
        !            29: ---------------------------
        !            30: 
        !            31:    When a file is under version control, we also say that it is
        !            32: "registered" in the version control system.  Each registered file has a
        !            33: corresponding "master file" which represents the file's present state
        !            34: plus its change history, so that you can reconstruct from it either the
        !            35: current version or any specified earlier version.  Usually the master
        !            36: file also records a change comment for each version.
        !            37: 
        !            38:    The file that is maintained under version control is sometimes called
        !            39: the "work file" corresponding to its master file.
        !            40: 
        !            41:    To examine a file, you "check it out".  This extracts a version of
        !            42: the file (typically, the most recent) from the master.  If you want to
        !            43: edit the file, you must check it out "locked".  Only one user can do
        !            44: this at a time for any given source file.  When you are done with your
        !            45: editing, you must "check in" the new version.  This records the new
        !            46: version in the master file, and unlocks the source file so that other
        !            47: people can lock it and thus modify it.
        !            48: 
        !            49:    These are the basic operations of version control. Checking in and
        !            50: checking out both use the single Emacs command `C-x C-q'
        !            51: (`vc-toggle-read-only').
        !            52: 
        !            53: 
        !            54: File: emacs,  Node: Editing with VC,  Next: Variables for Check-in/out,  Prev: Concepts of VC,  Up: Version Control
        !            55: 
        !            56: Editing with Version Control
        !            57: ----------------------------
        !            58: 
        !            59:    When you visit a file that is maintained using version control, the
        !            60: mode line displays `RCS' or `SCCS' to inform you that version control
        !            61: is in use, and also (in case you care) which low-level system the file
        !            62: is actually stored in.  Normally, such a source file is read-only, and
        !            63: the mode line indicates this with `%%'.)
        !            64: 
        !            65:    These are the commands that you use to edit a file maintained with
        !            66: version control:
        !            67: 
        !            68: `C-x C-q'
        !            69:      Check the visited file in or out.
        !            70: 
        !            71: `C-x v u'
        !            72:      Revert the buffer and the file to the last checked in version.
        !            73: 
        !            74: `C-x v c'
        !            75:      Remove the last-entered change from the master for the visited
        !            76:      file. This undoes your last check-in.
        !            77: 
        !            78: `C-x v i'
        !            79:      Register the visited file in version control.
        !            80: 
        !            81: (`C-x v' is the prefix key for version control commands; all of these
        !            82: commands except for `C-x C-q' start with `C-x v'.)
        !            83: 
        !            84:    If you want to edit the file, type `C-x C-q'
        !            85: (`vc-toggle-read-only').  This "checks out" and locks the file, so that
        !            86: you can edit it.  The file is writable after check-out, but only for
        !            87: you, not for anyone else.
        !            88: 
        !            89:    Emacs does not save backup files for source files that are maintained
        !            90: with version control.  If you want to make backup files despite version
        !            91: control, set the variable `vc-make-backups' to a non-`nil' value.
        !            92: 
        !            93:    When you are finished editing the file, type `C-x C-q' again. When
        !            94: used on a file that is checked out, this command checks the file in. 
        !            95: But check-in does not start immediately; first, you must enter a "log
        !            96: entry"--a description of the changes in the new version. `C-x C-q' pops
        !            97: up a buffer for you to enter this in.  When you are finished typing in
        !            98: the log entry, type `C-c C-c' to terminate it; this is when actual
        !            99: check-in takes place.
        !           100: 
        !           101:    Once you have checked in your changes, the file is unlocked, so that
        !           102: other users can lock it and modify it.
        !           103: 
        !           104:    Normally the work file exists all the time, whether it is locked or
        !           105: not.  If you set `vc-keep-workfiles' to `nil', then checking in a new
        !           106: version with `C-x C-q' deletes the work file; but any attempt to visit
        !           107: the file with Emacs creates it again.
        !           108: 
        !           109:    Actually, it is not impossible to lock a file that someone else has
        !           110: locked.  If you try to check out a file that is locked, `C-x C-q' asks
        !           111: you whether you want to "steal the lock."  If you say yes, the file
        !           112: becomes locked by you, but a message is sent to the person who had
        !           113: formerly locked the file, to inform him or her of what has happened.
        !           114: 
        !           115:    If you want to discard your current set of changes and revert to the
        !           116: last version checked in, use `C-x v u' (`vc-revert-buffer'). This
        !           117: cancels your last check-out, leaving the file unlocked.  If you want to
        !           118: make a different set of changes, you must first check the file out
        !           119: again.  `C-x v u' requies confirmation, unless it sees that you haven't
        !           120: made any changes since the last checked-in version.
        !           121: 
        !           122:    `C-x v u' is also the command to use if you lock a file and then
        !           123: don't actually change it.
        !           124: 
        !           125:    You can even cancel a change after checking it in, with `C-x v c'
        !           126: (`vc-cancel-version').  Normally, `C-x v c' reverts your workfile and
        !           127: buffer to the previous version (the one that precedes the version that
        !           128: is deleted), but you can prevent the reversion by giving the command a
        !           129: prefix argument.  Then the buffer does not change.
        !           130: 
        !           131:    This command with a prefix argument is useful when you have checked
        !           132: in a change and then discover a trivial error in it; you can cancel the
        !           133: erroneous check-in, fix the error, and repeat the check-in.
        !           134: 
        !           135:    Be careful when invoking `C-x v c', as it is easy to throw away a
        !           136: lot of work with it.  To help you be careful, this command always asks
        !           137: for confirmation with `yes'.
        !           138: 
        !           139:    You can register the visited file for version control using
        !           140: `C-x v i' (`vc-register').  This uses RCS if RCS is installed on your
        !           141: system; otherwise, it uses SCCS.
        !           142: 
        !           143:    By default, the initial version number is 1.1.  If you want to use a
        !           144: different number, give `C-x v i' a prefix argument; then it reads the
        !           145: initial version number using the minibuffer.
        !           146: 
        !           147:    After `C-x v i', the file is unlocked and read-only.  Type `C-x C-q'
        !           148: if you wish to edit it.
        !           149: 
        !           150:    If `vc-initial-comment' is non-`nil', `C-x v i' reads an initial
        !           151: comment (much like a log entry) to describe the purpose of this source
        !           152: file.
        !           153: 
        !           154: 
        !           155: File: emacs,  Node: Variables for Check-in/out,  Next: Comparing Versions,  Prev: Editing with VC,  Up: Version Control
        !           156: 
        !           157: Variables Affecting Check-in and Check-out
        !           158: ------------------------------------------
        !           159: 
        !           160:    If `vc-suppress-confirm' is non-`nil', then `C-x C-q' and `C-x v i'
        !           161: can save the current buffer without asking, and `C-x v u' also operates
        !           162: without asking for confirmation. (This variable does not affect `C-x v
        !           163: c'; that is so drastic that it should always ask for confirmation.)
        !           164: 
        !           165:    VC mode does much of its work by running the shell commands for RCS
        !           166: and SCCS.  If `vc-command-messages' is non-`nil', VC displays messages
        !           167: to indicate which shell commands it runs, and additional messages when
        !           168: the commands finish.
        !           169: 
        !           170:    Normally, VC assumes that it can deduce the locked/unlocked state of
        !           171: files by looking at the file permissions of the work file; this is
        !           172: fast.  However, if the `RCS' or `SCCS' subdirectory is actually a
        !           173: symbolic link, then VC does not trust the file permissions to reflect
        !           174: this status.
        !           175: 
        !           176:    You can specify the criterion for whether to trust the file
        !           177: permissions by setting the variable `vc-mistrust-permissions'.  Its
        !           178: value may be `t' (always mistrust the file permissions and check the
        !           179: master file), `nil' (always trust the file permissions), or a function
        !           180: of one argument which makes the decision.  The argument is the directory
        !           181: name of the `RCS' or `SCCS' subdirectory.  A non-`nil' value from the
        !           182: function says to mistrust the file permissions.
        !           183: 
        !           184:    If you find that the file permissions of work files are changed
        !           185: erroneously, then you can set `vc-mistrust-permissions' to `t' so that
        !           186: VC always checks the master file.
        !           187: 
        !           188: 
        !           189: File: emacs,  Node: Log Entries,  Next: Change Logs and VC,  Prev: Snapshots,  Up: Version Control
        !           190: 
        !           191: Log Entries
        !           192: -----------
        !           193: 
        !           194:    When you're editing an initial or change comment for inclusion in a
        !           195: master file, finish your entry by typing `C-c C-c'.
        !           196: 
        !           197: `C-c C-c'
        !           198:      Finish the comment edit normally (`vc-finish-logentry'). This
        !           199:      finishes check-in.
        !           200: 
        !           201:    To abort check-in, just don't type `C-c C-c' in that buffer.  You
        !           202: can switch buffers and do other editing.  As long as you don't try to
        !           203: check in another file, the comment you were editing remains in its
        !           204: buffer, and you can go back to that buffer at any time to complete the
        !           205: check-in.
        !           206: 
        !           207:    If you change several source files for the same reason, it is often
        !           208: convenient to specify the same log entry for many of the files.  To do
        !           209: this, use the history of previous log entries.  The commands `M-n',
        !           210: `M-p', `M-s' and `M-r' for doing this work just like the minibuffer
        !           211: history commands (except that they don't use the minibuffer).
        !           212: 
        !           213:    The history of previous log entries is actually stored in previous
        !           214: pages of the log entry editing buffer; they are normally hidden by
        !           215: narrowing.
        !           216: 
        !           217:    Each time you check in a file, the log entry buffer is put into VC
        !           218: Log mode, which involves running two hook variables: `text-mode-hook'
        !           219: and `vc-log-mode-hook'.
        !           220: 
        !           221: 
        !           222: File: emacs,  Node: Change Logs and VC,  Next: Version Headers,  Prev: Log Entries,  Up: Version Control
        !           223: 
        !           224: Change Logs and VC
        !           225: ------------------
        !           226: 
        !           227:    Emacs users often record brief summaries of program changes in a file
        !           228: called `ChangeLog', which is kept in the same directory as the source
        !           229: files, and is usually meant to be distributed along with the source
        !           230: files.  You can maintain `ChangeLog' from the version control logs with
        !           231: the following command.
        !           232: 
        !           233: `C-x v a'
        !           234:      Visit the current directory's change log file and create new
        !           235:      entries for versions checked in since the most recent entry in the
        !           236:      change log file (`vc-update-change-log').
        !           237: 
        !           238:      This command works with RCS only; it does not work with SCCS.
        !           239: 
        !           240:    For example, suppose the first line of `ChangeLog' is dated 10 April
        !           241: 1992, and suppose the only check-in since then was by Nathaniel
        !           242: Bowditch to `rcs2log' on 8 May 1992 with log text `Ignore log messages
        !           243: that start with `#'.'.  Then `C-x v a' visits `ChangeLog' and inserts
        !           244: text like this:
        !           245: 
        !           246:      Fri May  8 21:45:00 1992  Nathaniel Bowditch  ([email protected])
        !           247:      
        !           248:              * rcs2log: Ignore log messages that start with `#'.
        !           249: 
        !           250: You can then further edit as you wish.
        !           251: 
        !           252:    A log entry whose text begins with `#' is not copied to `ChangeLog'.
        !           253:  For example, if you merely fix some misspellings in comments, you can
        !           254: log the change with an entry beginning with `#' to avoid putting such
        !           255: trivia into `ChangeLog'.
        !           256: 
        !           257:    When `C-x v a' adds several change log entries at once, it groups
        !           258: related log entries together if they all are checked in by the same
        !           259: author at nearly the same time.  If the log entries for several such
        !           260: files all have the same text, it coalesces them into a single entry.
        !           261: For example, suppose the most recent check-ins have the following log
        !           262: entries:
        !           263: 
        !           264: For `vc.texinfo':
        !           265:      Fix expansion typos.
        !           266: For `vc.el':
        !           267:      Don't call expand-file-name.
        !           268: For `vc-hooks.el':
        !           269:      Don't call expand-file-name.
        !           270: 
        !           271:    They appear like this in `ChangeLog':
        !           272: 
        !           273:      Wed Apr  1 08:57:59 1992  Nathaniel Bowditch  ([email protected])
        !           274:      
        !           275:              * vc.texinfo: Fix expansion typos.
        !           276:      
        !           277:              * vc.el, vc-hooks.el: Don't call expand-file-name.
        !           278: 
        !           279:    Normally, `C-x v a' separates log entries by a blank line, but you
        !           280: can mark several related log entries to be clumped together (without an
        !           281: intervening blank line) by starting the text of each related log entry
        !           282: with a label of the form `{CLUMPNAME} '.  The label itself is not
        !           283: copied to `ChangeLog'.  For example, suppose the log entries are:
        !           284: 
        !           285: For `vc.texinfo':
        !           286:      {expand} Fix expansion typos.
        !           287: For `vc.el':
        !           288:      {expand} Don't call expand-file-name.
        !           289: For `vc-hooks.el':
        !           290:      {expand} Don't call expand-file-name.
        !           291: 
        !           292:    Then the text in `ChangeLog' looks like this:
        !           293: 
        !           294:      Wed Apr  1 08:57:59 1992  Nathaniel Bowditch  ([email protected])
        !           295:      
        !           296:              * vc.texinfo: Fix expansion typos.
        !           297:              * vc.el, vc-hooks.el: Don't call expand-file-name.
        !           298: 
        !           299:    Normally, the log entry for file `foo' is displayed as `* foo: TEXT
        !           300: OF LOG ENTRY'.  But by convention, the `:' after `foo' is omitted if
        !           301: the text of the log entry starts with `(FUNCTIONNAME): '.  For example,
        !           302: if the log entry for `vc.el' is `(vc-do-command): Check call-process
        !           303: status.', then the text in `ChangeLog' looks like this:
        !           304: 
        !           305:      Wed May  6 10:53:00 1992  Nathaniel Bowditch  ([email protected])
        !           306:      
        !           307:              * vc.el (vc-do-command): Check call-process status.
        !           308: 
        !           309: 
        !           310: File: emacs,  Node: Comparing Versions,  Next: VC Status,  Prev: Variables for Check-in/out,  Up: Version Control
        !           311: 
        !           312: Comparing Versions
        !           313: ------------------
        !           314: 
        !           315:    To compare two versions of a file, use `C-x v =' (`vc-diff').
        !           316: 
        !           317:    Plain `C-x v =' compares the current buffer contents (saving them in
        !           318: the file if necessary) with the last checked-in version of the file.
        !           319: With a prefix argument, `C-x v =' reads a filename and two version
        !           320: numbers, and compares those versions of the file you specify.
        !           321: 
        !           322:    If you supply a directory name instead of the name of a work file,
        !           323: this command compares the two specified versions of all registered files
        !           324: in that directory and its subdirectories.  You can also specify a
        !           325: snapshot name (*note Snapshots::.) instead of one or both version
        !           326: numbers.
        !           327: 
        !           328:    You can specify a checked-in version by its number; you can specify
        !           329: the most recent checked-in version with `-'; and you can specify the
        !           330: current buffer contents with `+'.  Thus, you can compare two checked-in
        !           331: versions, or compare a checked-in version with the text you are editing.
        !           332: 
        !           333:    This command works by running the `diff' utility, getting the
        !           334: options from the variable `diff-switches'.  It displays the output in a
        !           335: special buffer in another window.
        !           336: 
        !           337: 
        !           338: File: emacs,  Node: VC Status,  Next: Renaming and VC,  Prev: Comparing Versions,  Up: Version Control
        !           339: 
        !           340: VC Status Commands
        !           341: ------------------
        !           342: 
        !           343:    To get the detailed version control status of one file, type `C-x v
        !           344: l' (`vc-print-log').  It displays the history of changes to the current
        !           345: file, including the text of the log entries.  The output appears in a
        !           346: separate window.
        !           347: 
        !           348:    When you are working on a large program, it's often useful to find
        !           349: all the files that are currently locked, or all the files maintained in
        !           350: version control at all.  You can do so using these commands, both of
        !           351: which operate on the branch of the file system starting at the current
        !           352: directory.
        !           353: 
        !           354:    You can use `C-x v d' (`vc-directory') to show all the locked files
        !           355: in or beneath the current directory.  This includes all files that are
        !           356: locked by any user.
        !           357: 
        !           358:    With a prefix argument, `C-x v d' shows all the version control
        !           359: activity in the current directory--it lists all files in or beneath the
        !           360: current directory that are maintained with version control.
        !           361: 
        !           362: 
        !           363: File: emacs,  Node: Renaming and VC,  Next: Snapshots,  Prev: VC Status,  Up: Version Control
        !           364: 
        !           365: Renaming VC Work Files and Master Files
        !           366: ---------------------------------------
        !           367: 
        !           368:    When you rename a registered file, you must also rename its master
        !           369: file correspondingly to get proper results.  Use `vc-rename-file' to
        !           370: rename the source file as you specify, and rename its master file
        !           371: accordingly.  It also updates any snapshots (*note Snapshots::.) that
        !           372: mention the file, so that they use the new name; despite this, the
        !           373: snapshot thus modified may not completely work (*note Snapshot
        !           374: Caveats::.).
        !           375: 
        !           376:    You cannot use `vc-rename-file' on a file that is locked by someone
        !           377: else.
        !           378: 
        !           379:    `vc-rename-file' is not bound to a key because it's not likely to be
        !           380: used frequently.
        !           381: 
        !           382: 
        !           383: File: emacs,  Node: Snapshots,  Next: Log Entries,  Prev: Renaming and VC,  Up: Version Control
        !           384: 
        !           385: Snapshots
        !           386: ---------
        !           387: 
        !           388:    A "snapshot" is a named set of file versions (one for each
        !           389: registered file) that you can treat as a unit.  One important kind of
        !           390: snapshot is a "release", a (theoretically) stable version of the system
        !           391: that is ready for distribution to users.
        !           392: 
        !           393: * Menu:
        !           394: 
        !           395: * Making Snapshots::           The snapshot facilities.
        !           396: * Snapshot Caveats::           Things to be careful of, when using snapshots.
        !           397: 
        !           398: 
        !           399: File: emacs,  Node: Making Snapshots,  Next: Snapshot Caveats,  Up: Snapshots
        !           400: 
        !           401: Making and Using Snapshots
        !           402: ..........................
        !           403: 
        !           404:    There are two basic commands for snapshots; one makes a snapshot
        !           405: with a given name, the other retrieves a named snapshot.
        !           406: 
        !           407: `C-x v s NAME RET'
        !           408:      Define the last saved versions of every registered file in or
        !           409:      under the current directory as a snapshot named NAME
        !           410:      (`vc-create-snapshot').
        !           411: 
        !           412: `C-x v r NAME RET'
        !           413:      Check out all registered files at or below the current directory
        !           414:      level using whatever versions correspond to the snapshot NAME
        !           415:      (`vc-retrieve-snapshot').
        !           416: 
        !           417:      This function reports an error if any files are locked at or below
        !           418:      the current directory, without changing anything; this is to avoid
        !           419:      overwriting work in progress.
        !           420: 
        !           421:    You shouldn't need to use `vc-retrieve-snapshot' very often; you can
        !           422: get difference reports between two snapshots without retrieving either
        !           423: one, using `C-x =' (*note Comparing Versions::.).  Thus, retrieving a
        !           424: snapshot is only necessary if you need to study or compile portions of
        !           425: the snapshot.
        !           426: 
        !           427:    A snapshot uses a very small amount of resources--just enough to
        !           428: record the list of file names and which version belongs to the
        !           429: snapshot.  Thus, you need not hesitate to create snapshots whenever
        !           430: they are useful.
        !           431: 
        !           432:    You can give a snapshot name as an argument to `C-x v =' (*note
        !           433: Comparing Versions::.).  Thus, you can use it to compare a snapshot
        !           434: against the current files, or two snapshots against each other, or a
        !           435: snapshot against a named version.
        !           436: 
        !           437: 
        !           438: File: emacs,  Node: Snapshot Caveats,  Prev: Making Snapshots,  Up: Snapshots
        !           439: 
        !           440: Snapshot Caveats
        !           441: ................
        !           442: 
        !           443:    VC's snapshot facilities are modeled on RCS's named-configuration
        !           444: support.  They use RCS's native facilities for this, so under VC
        !           445: snapshots made using RCS are visible even when you bypass VC.
        !           446: 
        !           447:    For SCCS, VC implements snapshots itself.  The files it uses contain
        !           448: name/file/version-number triples.  These snapshots are visible only
        !           449: through VC.
        !           450: 
        !           451:    File renaming and deletion can create some difficulties with
        !           452: snapshots. This is not a VC-specific problem, but a general design
        !           453: issue in version control systems that no one has solved very well yet.
        !           454: 
        !           455:    If you rename a registered file, you need to rename its master along
        !           456: with it (the function `vc-rename-file' does this automatically). If you
        !           457: are using SCCS, you must also update the records of the snapshot, to
        !           458: mention the file by its new name (`vc-rename-file' does this, too). 
        !           459: This makes the snapshot remain valid for retrieval, but it does not
        !           460: solve all problems.
        !           461: 
        !           462:    For example, some of the files in the program probably refer to
        !           463: others by name.  At the very least, the makefile probably mentions the
        !           464: file that you renamed.  If you retrieve an old snapshot, the renamed
        !           465: file is retrieved under its new name, which is not the name that the
        !           466: makefile expects.  So the program won't really work.
        !           467: 
        !           468:    If you use snapshots, don't rename either work files or master files
        !           469: except by means of `vc-rename-file'.  It knows how to update snapshots
        !           470: so that you can still retrieve them.  An old snapshot that refers to a
        !           471: master file that no longer exists under the recorded name is invalid;
        !           472: VC can no longer retrieve it.  It would be beyond the scope of this
        !           473: manual to explain enough about RCS and SCCS to teach the reader how to
        !           474: update the snapshots by hand.
        !           475: 
        !           476: 
        !           477: File: emacs,  Node: Version Headers,  Prev: Change Logs and VC,  Up: Version Control
        !           478: 
        !           479: Inserting Version Control Headers
        !           480: ---------------------------------
        !           481: 
        !           482:    Sometimes it is convenient to put version identification strings
        !           483: directly into working files.  Certain special strings called "version
        !           484: headers" are replaced in each successive version by the number of that
        !           485: version.
        !           486: 
        !           487:    You can use the `C-x v h' command (`vc-insert-headers') to insert a
        !           488: suitable header string.
        !           489: 
        !           490: `C-x v h'
        !           491:      Insert headers in a file for use with your version-control system.
        !           492: 
        !           493:    The default header string is `$ld$' for RCS and `%W%' for SCCS.  You
        !           494: can specify other headers to insert by setting the variable
        !           495: `vc-header-string'.  Its value (if non-`nil') should be the string to
        !           496: be inserted.  You can also specify a list of strings; then each string
        !           497: in the list is inserted as a separate header on a line of its own.  (It
        !           498: is often important to use "superfluous" backslashes when writing a Lisp
        !           499: string constant for this use, to prevent the string in the constant
        !           500: from being interpreted as a header itself if the Emacs Lisp file
        !           501: containing it is maintained with version control.)
        !           502: 
        !           503:    Each header is inserted surrounded by tabs, inside comment
        !           504: delimiters, on a new line at the start of the buffer.  Normally the
        !           505: ordinary comment start and comment end strings of the current mode are
        !           506: used, but for certain modes, there are special comment delimiters for
        !           507: this purpose; the variable `vc-comment-alist' specifies them.  Each
        !           508: element of this list has the form `(MODE STARTER ENDER)'.
        !           509: 
        !           510:    `vc-static-header-alist' is consulted to add further strings based
        !           511: on the name of the buffer.  Its value should be a list of dotted pairs;
        !           512: the CAR of each pair is a regular expression that should match the
        !           513: buffer name, and the CDR is the format to use on each header.  A string
        !           514: is inserted for each file name pattern that matches the buffer name,
        !           515: and for each header taken from `vc-header-string'.  The default value
        !           516: for `vc-static-header-alist' is:
        !           517: 
        !           518:      (("\\.c$" .
        !           519:        "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
        !           520:      #endif /* lint */\n"))
        !           521: 
        !           522: which specifies insertion of a string of this form:
        !           523: 
        !           524: 
        !           525:      #ifndef lint
        !           526:      static char vcid[] = "HEADER-STRING";
        !           527:      #endif /* lint */
        !           528: 
        !           529: 
        !           530: File: emacs,  Node: Emerge,  Next: Debuggers,  Prev: Version Control,  Up: Version 19
        !           531: 
        !           532: Emerge
        !           533: ======
        !           534: 
        !           535:    It's not unusual for programmers to get their signals crossed and
        !           536: modify the same program in two different directions.  To recover from
        !           537: this confusion, you need to merge the two versions.  Emerge makes this
        !           538: easier.
        !           539: 
        !           540: * Menu:
        !           541: 
        !           542: * Overview of Emerge::
        !           543: * Submodes of Emerge::
        !           544: * State of Difference::
        !           545: * Merge Commands::
        !           546: * Exiting Emerge::
        !           547: * Combining in Emerge::
        !           548: * Fine Points of Emerge::
        !           549: 
        !           550: 
        !           551: File: emacs,  Node: Overview of Emerge,  Next: Submodes of Emerge,  Up: Emerge
        !           552: 
        !           553: Overview of Emerge
        !           554: ------------------
        !           555: 
        !           556:    To start Emerge, run one of these four commands:
        !           557: 
        !           558: `M-x emerge-files'
        !           559:      Merge two specified files.
        !           560: 
        !           561: `M-x emerge-files-with-ancestor'
        !           562:      Merge two specified files, with reference to a common ancestor.
        !           563: 
        !           564: `M-x emerge-buffers'
        !           565:      Merge two buffers (the currently accessible portions).
        !           566: 
        !           567: `M-x emerge-buffers-with-ancestor'
        !           568:      Merge two buffers (the currently accessible portions) with
        !           569:      reference to a common ancestor in another buffer.
        !           570: 
        !           571:    The Emerge commands compare two texts, and display the results in
        !           572: three buffers: one for each input text (the "A buffer" and the "B
        !           573: buffer"), and one (the "merge buffer") where merging takes place. The
        !           574: merge buffer does not show just the differences.  Rather, it shows you
        !           575: the full text, but wherever the input texts differ, you can choose
        !           576: which one of them to include in the merge buffer.
        !           577: 
        !           578:    If a common ancestor version is available, from which the two texts
        !           579: to be merged were both derived, Emerge can use it to guess which
        !           580: alternative is right.  Wherever one current version agrees with the
        !           581: ancestor, Emerge presumes that the other current version is a deliberate
        !           582: change which should be kept in the merged version.  Use the
        !           583: "with-ancestor" commands if you want to specify a common ancestor text.
        !           584:  These commands read three file or buffer names--variant A, variant B,
        !           585: and the common ancestor.
        !           586: 
        !           587:    After the comparison is done and the buffers are prepared, the actual
        !           588: merging starts.  You control the merging interactively by editing the
        !           589: merge buffer.  The merge buffer shows you a full merged text, not just
        !           590: differences.  For each point where the input texts differ, you can
        !           591: choose which one of them to include in the merge buffer.
        !           592: 
        !           593:    The merge buffer has a special major mode, Emerge mode, with commands
        !           594: for making these choices.  But you can also edit the buffer with
        !           595: ordinary Emacs commands.
        !           596: 
        !           597:    At any given time, the attention of Emerge is focused on one
        !           598: particular difference, called the "selected" difference.  This
        !           599: difference is marked off in the three buffers by
        !           600: 
        !           601:      vvvvvvvvvvvvvvvvvvvv
        !           602: 
        !           603: above and
        !           604: 
        !           605:      ^^^^^^^^^^^^^^^^^^^^
        !           606: 
        !           607: below.  Emerge numbers all the differences sequentially and the mode
        !           608: line always shows the number of the selected difference.
        !           609: 
        !           610:    Normally, the merge buffer starts out with the A version of the text.
        !           611: But when the A version of a part of the buffer agrees with the common
        !           612: ancestor, then the B version is preferred for that part.
        !           613: 
        !           614:    Normally, Emerge stores the merged output in place of the first input
        !           615: text (the A file or buffer).  If you give a prefix argument to
        !           616: `emerge-files' or `emerge-files-with-ancestor', it reads the name of
        !           617: the output file using the minibuffer.  (This is the last file name
        !           618: those commands read.)
        !           619: 
        !           620:    If you abort Emerge with `C-u q', the output is not saved.
        !           621: 
        !           622: 
        !           623: File: emacs,  Node: Submodes of Emerge,  Next: State of Difference,  Prev: Overview of Emerge,  Up: Emerge
        !           624: 
        !           625: Submodes of Emerge
        !           626: ------------------
        !           627: 
        !           628:    You can choose between two modes for giving merge commands: Fast mode
        !           629: and Edit mode.  In Fast mode, basic Emerge commands are single
        !           630: characters, but ordinary Emacs commands are disabled.  This is
        !           631: convenient if you use only Emerge commands.
        !           632: 
        !           633:    In Edit mode, all Emerge commands start with the prefix character
        !           634: `C-c', and the normal Emacs commands are also available.  This allows
        !           635: editing the merge buffer, but slows down Emerge operations.
        !           636: 
        !           637:    Use `e' to switch to Edit mode, and `f' to switch to Fast mode. The
        !           638: mode line indicates Edit and Fast modes with `E' and `F'.
        !           639: 
        !           640:    Emerge has two additional submodes that affect how particular merge
        !           641: commands work: Auto Advance mode and Skip Prefers mode.
        !           642: 
        !           643:    If Auto Advance mode is in effect, the `a' and `b' commands advance
        !           644: to the next difference.  This lets you go through the merge faster
        !           645: doing ordinary things.  The mode line indicates Auto Advance mode with
        !           646: `A'.
        !           647: 
        !           648:    If Skip Prefers mode is in effect, the `n' and `p' commands skip
        !           649: over differences in states prefer-A and prefer-B.  Thus you will only
        !           650: see differences for which neither version is presumed "correct".  The
        !           651: mode line indicates Skip Prefers mode with `S'.
        !           652: 
        !           653:    Use the command `emerge-auto-advance-mode' to set or clear Auto
        !           654: Advance mode.  Use `emerge-skip-prefers-mode' to set or clear Skip
        !           655: Prefers mode.  A positive argument turns the mode on, a nonpositive
        !           656: argument turns it off, and no argument toggles it.
        !           657: 
        !           658: 
        !           659: File: emacs,  Node: State of Difference,  Next: Merge Commands,  Prev: Submodes of Emerge,  Up: Emerge
        !           660: 
        !           661: State of a Difference
        !           662: ---------------------
        !           663: 
        !           664:    In the merge buffer, a difference is marked `vvvvvvvvvvvvvvvvvvvv'
        !           665: above and `^^^^^^^^^^^^^^^^^^^^' below.  Such a difference can have one
        !           666: of seven states:
        !           667: 
        !           668: A
        !           669:      The difference is showing the A version.  The `a' command always
        !           670:      produces this state; the mode line indicates it with `A'.
        !           671: 
        !           672: B
        !           673:      The difference is showing the B version.  The `b' command always
        !           674:      produces this state; the mode line indicates it with `B'.
        !           675: 
        !           676: default-A
        !           677: default-B
        !           678:      The difference is showing the A or the B state by default, because
        !           679:      you haven't made a choice.  All differences start in the default-A
        !           680:      state (and thus the merge buffer is a copy of the A buffer),
        !           681:      except those for which one alternative is "preferred" (see below).
        !           682: 
        !           683:      When you select a difference, its state changes from default-A or
        !           684:      default-B to plain A or B.  Thus, the selected difference never has
        !           685:      state default-A or default-B, and these states are never displayed
        !           686:      in the mode line.
        !           687: 
        !           688:      The command `d a' chooses default-A as the default state, and `d
        !           689:      b' chooses default-B.  This chosen default applies to all
        !           690:      differences which you haven't selected and for which no
        !           691:      alternative is preferred. If you are moving through the merge
        !           692:      sequentially, the differences you haven't selected are those
        !           693:      following the selected one.  Thus, while moving sequentially, you
        !           694:      can effectively make the A version the default for some sections
        !           695:      of the merge buffer and the B version the default for others by
        !           696:      using `d a' and `d b' at the end of each section.
        !           697: 
        !           698: prefer-A
        !           699: prefer-B
        !           700:      The difference is showing the A or B state because it is
        !           701:      "preferred".  This means that you haven't made an explicit choice,
        !           702:      but one alternative seems likely to be right because the other
        !           703:      alternative agrees with the common ancestor.  Thus, where the A
        !           704:      buffer agrees with the common ancestor, the B version is
        !           705:      preferred, because chances are it is the one that was actually
        !           706:      changed.
        !           707: 
        !           708:      These two states are displayed in the mode line as `A*' and `B*'.
        !           709: 
        !           710: combined
        !           711:      The difference is showing a combination of the A and B states, as a
        !           712:      result of the `x c' or `x C' commands.
        !           713: 
        !           714:      Once a difference is in this state, the `a' and `b' commands don't
        !           715:      do anything to it unless you give them a prefix argument.
        !           716: 
        !           717:      The mode line displays this state as `comb'.
        !           718: 
        !           719: 
        !           720: File: emacs,  Node: Merge Commands,  Next: Exiting Emerge,  Prev: State of Difference,  Up: Emerge
        !           721: 
        !           722: Merge Commands
        !           723: --------------
        !           724: 
        !           725:    Here are the Merge commands for Fast mode; in Edit mode, precede
        !           726: these with `C-c' and turn all the letters into control characters.
        !           727: 
        !           728: `p'
        !           729:      Select the previous difference.
        !           730: 
        !           731: `n'
        !           732:      Select the next difference.
        !           733: 
        !           734: `a'
        !           735:      Choose the A version of this difference.
        !           736: 
        !           737: `b'
        !           738:      Choose the B version of this difference.
        !           739: 
        !           740: `j'
        !           741:      Select a particular difference; specify the sequence number of that
        !           742:      difference as a prefix argument.
        !           743: 
        !           744: `M-x emerge-select-difference'
        !           745:      Select the run of differences containing the current location. 
        !           746:      You can use this command in the merge buffer or in the A or B
        !           747:      buffer.
        !           748: 
        !           749: `q'
        !           750:      Quit--finish the merge.  With an argument, abort the merge.
        !           751: 
        !           752: `f'
        !           753:      Go into fast mode.
        !           754: 
        !           755: `e'
        !           756:      Go into edit mode.
        !           757: 
        !           758: `l'
        !           759:      Recenter (like `C-l') all three windows.
        !           760: 
        !           761: `-'
        !           762:      Specify part of a prefix numeric argument.
        !           763: 
        !           764: `DIGIT'
        !           765:      Also specify part of a prefix numeric argument.
        !           766: 
        !           767: `d a'
        !           768:      Choose the A version as the default from here down in the merge
        !           769:      buffer.
        !           770: 
        !           771: `d b'
        !           772:      Choose the B version as the default from here down in the merge
        !           773:      buffer.
        !           774: 
        !           775: `c a'
        !           776:      Copy the A version of this difference into the kill ring.
        !           777: 
        !           778: `c b'
        !           779:      Copy the B version of this difference into the kill ring.
        !           780: 
        !           781: `i a'
        !           782:      Insert the A version of this difference at the point.
        !           783: 
        !           784: `i b'
        !           785:      Insert the B version of this difference at the point.
        !           786: 
        !           787: `m'
        !           788:      Put the point and mark around the difference region.
        !           789: 
        !           790: `^'
        !           791:      Scroll all three windows down (like `M-v').
        !           792: 
        !           793: `v'
        !           794:      Scroll all three windows up (like `C-v').
        !           795: 
        !           796: `<'
        !           797:      Scroll all three windows left (like `C-x <').
        !           798: 
        !           799: `>'
        !           800:      Scroll all three windows right (like `C-x >').
        !           801: 
        !           802: `|'
        !           803:      Reset horizontal scroll on all three windows.
        !           804: 
        !           805: `x 1'
        !           806:      Shrink the merge window to one line.  (Use `C-u l' to restore it
        !           807:      to full size.)
        !           808: 
        !           809: `x c'
        !           810:      Combine the two versions of this difference.
        !           811: 
        !           812: `x f'
        !           813:      Show the files/buffers Emerge is operating on in Help window. (Use
        !           814:      `C-u l' to restore windows.)
        !           815: 
        !           816: `x j'
        !           817:      Join this difference with the following one. (`C-u x j' joins this
        !           818:      difference with the previous one.)
        !           819: 
        !           820: `x s'
        !           821:      Split this difference into two differences.  Before you use this
        !           822:      command, position point in each of the three buffers to the place
        !           823:      where you want to split the difference.
        !           824: 
        !           825: `x t'
        !           826:      Trim identical lines off top and bottom of the difference. Such
        !           827:      lines occur when the A and B versions are identical but differ
        !           828:      from the ancestor version.
        !           829: 
        !           830: 
        !           831: File: emacs,  Node: Exiting Emerge,  Next: Combining in Emerge,  Prev: Merge Commands,  Up: Emerge
        !           832: 
        !           833: Exiting Emerge
        !           834: --------------
        !           835: 
        !           836:    The `q' (`emerge-quit') command finishes the merge, storing the
        !           837: results into the output file.  It restores the A and B buffers to their
        !           838: proper contents, or kills them if they were created by Emerge.  It also
        !           839: disables the Emerge commands in the merge buffer, since executing them
        !           840: later could damage the contents of the various buffers.
        !           841: 
        !           842:    `C-u q' aborts the merge.  Aborting means that Emerge does not write
        !           843: the output file.
        !           844: 
        !           845:    If Emerge was called from another Lisp program, then its return value
        !           846: is `t' or `nil' to indicate success or failure.
        !           847: 
        !           848: 
        !           849: File: emacs,  Node: Combining in Emerge,  Next: Fine Points of Emerge,  Prev: Exiting Emerge,  Up: Emerge
        !           850: 
        !           851: Combining the Two Versions
        !           852: --------------------------
        !           853: 
        !           854:    Sometimes you want to keep *both* alternatives for a particular
        !           855: locus.  To do this, use `x c', which edits the merge buffer like this:
        !           856: 
        !           857:      #ifdef NEW
        !           858:      VERSION FROM A FILE
        !           859:      #else /* NEW */
        !           860:      VERSION FROM B FILE
        !           861:      #endif /* NEW */
        !           862: 
        !           863:    While this example shows C preprocessor conditionals delimiting the
        !           864: two alternative versions, you can specify the strings you want by
        !           865: setting the variable `emerge-combine-template' to a list of three
        !           866: strings. The default setting, which produces the results shown above,
        !           867: looks like this:
        !           868: 
        !           869:      ("#ifdef NEW\n"
        !           870:       "#else /* NEW */\n"
        !           871:       "#endif /* NEW */\n")
        !           872: 
        !           873: 
        !           874: File: emacs,  Node: Fine Points of Emerge,  Prev: Combining in Emerge,  Up: Emerge
        !           875: 
        !           876: Fine Points of Emerge
        !           877: ---------------------
        !           878: 
        !           879:    You can have any number of merges going at once--just don't use any
        !           880: one buffer as input to more than one merge at once, since that will
        !           881: cause the read-only/modified/auto-save status save-and-restore to screw
        !           882: up.
        !           883: 
        !           884:    Starting Emerge can take a long time because it needs to compare the
        !           885: files.  Emacs can't do anything else until `diff' finishes.  Perhaps in
        !           886: the future someone will change Emerge to do the comparison in the
        !           887: background when the input files are large--then you could keep on doing
        !           888: other things with Emacs until Emerge gets ready to accept commands.
        !           889: 
        !           890:    After the merge has been set up, Emerge runs the hooks in
        !           891: `emerge-startup-hook'.
        !           892: 
        !           893:    During the merge, you musn't try to edit the A and B buffers
        !           894: yourself. Emerge modifies them temporarily, but ultimately puts them
        !           895: back the way they were.
        !           896: 
        !           897: 
        !           898: File: emacs,  Node: Debuggers,  Next: Other New Modes,  Prev: Emerge,  Up: Version 19
        !           899: 
        !           900: Running Debuggers Under Emacs
        !           901: =============================
        !           902: 
        !           903:    The GUD (Grand Unified Debugger) library provides an interface to
        !           904: various symbolic debuggers from within Emacs.  We recommend the
        !           905: debugger GDB, which is free software, but you can also run DBX or SDB
        !           906: if you have them.
        !           907: 
        !           908: * Menu:
        !           909: 
        !           910: * Starting GUD::       How to start a debugger subprocess.
        !           911: * Debugger Operation:: Connection between the debugger and source buffers.
        !           912: * Commands of GUD::    Keybindings for common commands.
        !           913: * GUD Customization::  Defining your own commands for GUD.
        !           914: 
        !           915: 
        !           916: File: emacs,  Node: Starting GUD,  Next: Debugger Operation,  Up: Debuggers
        !           917: 
        !           918: Starting GUD
        !           919: ------------
        !           920: 
        !           921:    There are three commands for starting a debugger.  Each corresponds
        !           922: to a particular debugger program.
        !           923: 
        !           924: `M-x gdb RET FILE RET'
        !           925: `M-x dbx RET FILE RET'
        !           926:      Run GDB or DBX in a subprocess of Emacs.  Both of these commands
        !           927:      select the buffer used for input and output to the debugger.
        !           928: 
        !           929: `M-x sdb RET FILE RET'
        !           930:      Run SDB in a subprocess of Emacs.  SDB's messages do not mention
        !           931:      file names, so the Emacs interface to SDB depends on having a tags
        !           932:      table (*note Tags::.) to find which file each function is in.  If
        !           933:      you have not visited a tags table or the tags table doesn't list
        !           934:      one of the functions, you get a message saying `The sdb support
        !           935:      requires a valid tags table to work'.  If this happens, generate a
        !           936:      valid tags table in the working directory and try again.
        !           937: 
        !           938:    You can only run one debugger process at a time.
        !           939: 
        !           940: 
        !           941: File: emacs,  Node: Debugger Operation,  Next: Commands of GUD,  Prev: Starting GUD,  Up: Debuggers
        !           942: 
        !           943: Debugger Operation
        !           944: ------------------
        !           945: 
        !           946:    When you run a debugger with GUD, the debugger displays source files
        !           947: via Emacs--Emacs finds the source file and moves point to the line
        !           948: where the program is executing.  An arrow (`=>') indicates the current
        !           949: execution line, and it stays put even if you move the cursor.
        !           950: 
        !           951:    You can start editing the file at any time.  The arrow is not part of
        !           952: the file's text; it appears only on the screen.  If you do modify a
        !           953: source file, keep in mind that inserting or deleting lines will throw
        !           954: off the arrow's positioning; GUD has no way of figuring out which line
        !           955: corresponded before your changes to the line number in a debugger
        !           956: message.  Also, you'll typically have to recompile and restart the
        !           957: program for your changes to be reflected in the debugger's tables.
        !           958: 
        !           959:    If you wish, you can control your debugger process entirely through
        !           960: the debugger buffer, which uses a variant of Shell mode.  All the usual
        !           961: commands for your debugger are available, and you can use the Shell mode
        !           962: history commands to repeat them.
        !           963: 
        !           964: 
        !           965: File: emacs,  Node: Commands of GUD,  Next: GUD Customization,  Prev: Debugger Operation,  Up: Debuggers
        !           966: 
        !           967: Commands of GUD
        !           968: ---------------
        !           969: 
        !           970:    GUD provides a command available in all buffers for setting
        !           971: breakpoints.  This command is defined globally because you need to use
        !           972: it in the source files' buffers.
        !           973: 
        !           974: `C-x SPC'
        !           975:      Set a breakpoint on the line that point is on.
        !           976: 
        !           977:    The debugger buffer has a number of keybindings for invoking common
        !           978: debugging commands quickly:
        !           979: 
        !           980: `C-c C-l'
        !           981:      Display in another window the last line referred to in the GUD
        !           982:      buffer (that is, the line indicated in the last location message).
        !           983:      This runs the command `gud-refresh'.
        !           984: 
        !           985: `C-c C-s'
        !           986:      Execute a single line of code (`gud-step').  If the code contains
        !           987:      a function call, execution stops after entering the called
        !           988:      function.
        !           989: 
        !           990: `C-c C-n'
        !           991:      Execute a single line of code, stepping across entire function
        !           992:      calls at full speed (`gud-next').
        !           993: 
        !           994: `C-c C-i'
        !           995:      Execute a single machine instruction (`gud-stepi').
        !           996: 
        !           997: `C-c C-c'
        !           998:      Continue execution until the next breakpoint, or other event that
        !           999:      would normally stop the program (`gud-cont').
        !          1000: 
        !          1001:    The above commands are common to all supported debuggers.  If you are
        !          1002: using GDB or (some versions of) DBX, these additional commands are
        !          1003: available:
        !          1004: 
        !          1005: `C-c <'
        !          1006:      Select the next enclosing stack frame (`gud-up').  This is
        !          1007:      equivalent to the `up' command.
        !          1008: 
        !          1009: `C-c >'
        !          1010:      Select the next inner stack frame (`gud-down').  This is
        !          1011:      equivalent to the `down' command.
        !          1012: 
        !          1013:    If you are using GDB, two additional keybindings are available:
        !          1014: 
        !          1015: `C-c C-f'
        !          1016:      Run the program until the selected stack frame returns (or until it
        !          1017:      stops for some other reason).
        !          1018: 
        !          1019: `TAB'
        !          1020:      Complete the symbol in the buffer before point, using the set of
        !          1021:      all symbols known to GDB.
        !          1022: 
        !          1023:    These commands interpret a prefix argument as a repeat count, when
        !          1024: that makes sense.
        !          1025: 
        !          1026:    After each command that changes the program counter, GUD displays the
        !          1027: new current source line, and updates the location of the arrow.
        !          1028: 
        !          1029: 
        !          1030: File: emacs,  Node: GUD Customization,  Prev: Commands of GUD,  Up: Debuggers
        !          1031: 
        !          1032: GUD Customization
        !          1033: -----------------
        !          1034: 
        !          1035:    On startup, GUD executes one of the following hooks:
        !          1036: `gdb-mode-hook', if you are using GDB; `dbx-mode-hook', if you are
        !          1037: using DBX; and `sdb-mode-hook', if you are using SDB.  You can use
        !          1038: these hooks to define custom keybindings for the debugger interaction
        !          1039: buffer.
        !          1040: 
        !          1041:    Here is a convenient way to define a command that sends a particular
        !          1042: command string to the debugger, and set up a key binding for it in the
        !          1043: debugger interaction buffer:
        !          1044: 
        !          1045:      (gud-def FUNCTION CMDSTRING BINDING DOCSTRING)
        !          1046: 
        !          1047:    This defines a command named FUNCTION which sends CMDSTRING to the
        !          1048: debugger process, with documentation string DOCSTRING, and binds it to
        !          1049: BINDING in the debugger buffer's mode.  (If BINDING is `nil', this
        !          1050: defines the command but does not make a binding for it; you can make a
        !          1051: binding explicitly, perhaps using one of the above hooks.)
        !          1052: 
        !          1053:    Commands defined with `gud-def' handle prefix arguments by passing
        !          1054: them to the debugger, appended to end of CMDSTRING with a space in
        !          1055: between.  (This use of prefix arguments works with GDB and DBX, but not
        !          1056: with SDB.)
        !          1057: 
        !          1058:    You can also set up commands that you can send to the debugger while
        !          1059: in another buffer, such as a source file.  Set the variable
        !          1060: `gud-commands' to a list of strings containing debugger commands you
        !          1061: might want to send.
        !          1062: 
        !          1063: `C-x &'
        !          1064:      Send a custom command to the debugger process
        !          1065:      (`send-gud-command').  Normally, send the CAR of the
        !          1066:      `gud-commands' list; a prefix argument specifies which element of
        !          1067:      that list to use (counting from 0).
        !          1068: 
        !          1069:      If the string contains `%s', `C-x &' substitutes a numeric value
        !          1070:      found in the buffer at or near point.  It looks for decimal,
        !          1071:      octal, or hexadecimal numbers, with `0x' allowed.  This lets you
        !          1072:      define commands to chase pointers whose numeric values have been
        !          1073:      displayed.
        !          1074: 
        !          1075: 
        !          1076: File: emacs,  Node: Other New Modes,  Next: Key Sequence Changes,  Prev: Debuggers,  Up: Version 19
        !          1077: 
        !          1078: Other New Modes
        !          1079: ===============
        !          1080: 
        !          1081:    There is now a Perl mode for editing Perl programs and an Icon mode
        !          1082: for editing Icon programs.
        !          1083: 
        !          1084:    C++ mode is like C mode, except that it understands C++ comment
        !          1085: syntax and certain other differences between C and C++.  It also has a
        !          1086: command `fill-c++-comment' which fills a paragraph made of comment
        !          1087: lines. The command `comment-region' is useful in C++ mode for commenting
        !          1088: out several consecutive lines, or removing the commenting out of such
        !          1089: lines.
        !          1090: 
        !          1091:    WordStar emulation is available--type `M-x wordstar-mode'. For more
        !          1092: information, type `C-h f wordstar-mode RET'.
        !          1093: 
        !          1094:    The command `C-o' in Buffer Menu mode now displays the current
        !          1095: line's buffer in another window but does not select it.  This is like
        !          1096: the existing command `o' which selects the current line's buffer in
        !          1097: another window.
        !          1098: 
        !          1099: * Menu:
        !          1100: 
        !          1101: * Asm Mode::           A major mode for editing assembler files.
        !          1102: * Edebug Mode::                A new Lisp debugger.
        !          1103: * Editing Binary Files::Hexl mode lets you edit a binary file as numbers.
        !          1104: 
        !          1105: 
        !          1106: File: emacs,  Node: Asm Mode,  Next: Edebug Mode,  Up: Other New Modes
        !          1107: 
        !          1108: Asm Mode
        !          1109: --------
        !          1110: 
        !          1111:    Asm mode is a new major mode for editing files of assembler code. It
        !          1112: defines these commands:
        !          1113: 
        !          1114: `TAB'
        !          1115:      `tab-to-tab-stop'.
        !          1116: 
        !          1117: `LFD'
        !          1118:      Insert a newline and then indent using `tab-to-tab-stop'.
        !          1119: 
        !          1120: `:'
        !          1121:      Insert a colon and then remove the indentation from before the
        !          1122:      label preceding colon.  Then do `tab-to-tab-stop'.
        !          1123: 
        !          1124: `;'
        !          1125:      Insert or align a comment.
        !          1126: 
        !          1127: 
        !          1128: File: emacs,  Node: Edebug Mode,  Next: Editing Binary Files,  Prev: Asm Mode,  Up: Other New Modes
        !          1129: 
        !          1130: Edebug Mode
        !          1131: -----------
        !          1132: 
        !          1133:    Edebug is a new source-level debugger for Emacs Lisp programs.
        !          1134: 
        !          1135:    To use Edebug, use the command `M-x edebug-defun' to "evaluate" a
        !          1136: function definition in an Emacs Lisp file.  We put "evaluate" in
        !          1137: quotation marks because it doesn't just evaluate the function, it also
        !          1138: inserts additional information to support source-level debugging.
        !          1139: 
        !          1140:    You must also do this:
        !          1141: 
        !          1142:      (setq debugger 'edebug-debug)
        !          1143: 
        !          1144: to cause errors and single-stepping to use Edebug instead of the usual
        !          1145: Emacs Lisp debugger.
        !          1146: 
        !          1147:    For more information, see `The Emacs Extensions Manual', which
        !          1148: should be included in the Emacs 19 distribution.
        !          1149: 
        !          1150: 
        !          1151: File: emacs,  Node: Editing Binary Files,  Prev: Edebug Mode,  Up: Other New Modes
        !          1152: 
        !          1153: Editing Binary Files
        !          1154: --------------------
        !          1155: 
        !          1156:    There is a new major mode for editing binary files: Hexl mode.  To
        !          1157: use it, use `M-x hexl-find-file' instead of `C-x C-f' to visit the
        !          1158: file.  This command converts the file's contents to hexadecimal and lets
        !          1159: you edit the translation.  When you save the file, it is converted
        !          1160: automatically back to binary.
        !          1161: 
        !          1162:    You can also use `M-x hexl-mode' to translate an existing buffer
        !          1163: into hex.  This is useful if you visit a file normally and discover it
        !          1164: is a binary file.
        !          1165: 
        !          1166:    Hexl mode has a few other commands:
        !          1167: 
        !          1168: `C-M-d'
        !          1169:      Insert a byte with a code typed in decimal.
        !          1170: 
        !          1171: `C-M-o'
        !          1172:      Insert a byte with a code typed in octal.
        !          1173: 
        !          1174: `C-M-x'
        !          1175:      Insert a byte with a code typed in hex.
        !          1176: 
        !          1177: `C-x ['
        !          1178:      Move to the beginning of a 1k-byte "page".
        !          1179: 
        !          1180: `C-x ]'
        !          1181:      Move to the end of a 1k-byte "page".
        !          1182: 
        !          1183: `M-g'
        !          1184:      Move to an address specified in hex.
        !          1185: 
        !          1186: `M-j'
        !          1187:      Move to an address specified in decimal.
        !          1188: 
        !          1189: `C-c C-c'
        !          1190:      Leave Hexl mode, going back to the major mode this buffer had
        !          1191:      before you invoked `hexl-mode'.
        !          1192: 
        !          1193: 
        !          1194: File: emacs,  Node: Key Sequence Changes,  Next: Hook Changes,  Prev: Other New Modes,  Up: Version 19
        !          1195: 
        !          1196: Changes in Key Sequences
        !          1197: ========================
        !          1198: 
        !          1199:    In Emacs 18, a key sequence was a sequence of characters, which
        !          1200: represented keyboard input.
        !          1201: 
        !          1202:    In Emacs 19, you can still use a sequence of characters as a key
        !          1203: sequence, but you aren't limited to characters.  You can also use Lisp
        !          1204: symbols which represent terminal function keys or mouse buttons.  If the
        !          1205: function key has a word as its label, then that word is also the name of
        !          1206: the symbol which represents the function key.  Other function keys are
        !          1207: assigned Lisp names as follows:
        !          1208: 
        !          1209: `kp-add', `kp-decimal', `kp-divide', ...
        !          1210:      Keypad keys (to the right of the regular keyboard), with names or
        !          1211:      punctuation
        !          1212: 
        !          1213: `kp-0', `kp-1', ...
        !          1214:      Keypad keys with digits
        !          1215: 
        !          1216: `kp-f1', `kp-f2', `kp-f3', `kp-f4'
        !          1217:      Keypad PF keys
        !          1218: 
        !          1219: `left', `up', `right', `down'
        !          1220:      Cursor arrow keys
        !          1221: 
        !          1222:    A key sequence which contains non-characters must be a vector rather
        !          1223: than a string.
        !          1224: 
        !          1225:    Thus, to bind function key `f1' to `rmail', write the following:
        !          1226: 
        !          1227:      (global-set-key [f1] 'rmail)
        !          1228: 
        !          1229: (To find the name of a key, type `C-h k' and then the key.)
        !          1230: 
        !          1231:    To bind the right-arrow key to the command `forward-char', you can
        !          1232: use this expression:
        !          1233: 
        !          1234:      (global-set-key [right] 'forward-char)
        !          1235: 
        !          1236: using the Lisp syntax for a vector containing the symbol `right'.
        !          1237: 
        !          1238:    And this is how to make `C-x RIGHTARROW' move forward a page:
        !          1239: 
        !          1240:      (global-set-key [?\C-x right] 'forward-page)
        !          1241: 
        !          1242: where `?\C-x' is the Lisp syntax for an integer whose value is the code
        !          1243: for the character `C-x'.
        !          1244: 
        !          1245:    You can use modifier keys such as CTRL, META and SHIFT with function
        !          1246: keys.  To represent these modifiers, prepend the strings `C-', `M-' and
        !          1247: `S-' to the symbol name.  Thus, here is how to make `M-RIGHTARROW' move
        !          1248: forward a word:
        !          1249: 
        !          1250:      (global-set-key [M-right] 'forward-word)
        !          1251: 
        !          1252:    Emacs uses symbols to designate mouse buttons, too. The ordinary
        !          1253: mouse events in Emacs are "click" events; these happen when you press a
        !          1254: button and release it without moving the mouse. You can also get "drag"
        !          1255: events, when you move the mouse while holding the button down.  Drag
        !          1256: events happen when you finally let go of the button.
        !          1257: 
        !          1258:    The symbols for basic click events are `mouse-1' for the leftmost
        !          1259: button, `mouse-2' for the next, and so on.  Here is how you can
        !          1260: redefine the second mouse button to split the current window:
        !          1261: 
        !          1262:      (global-set-key [mouse-2] 'split-window-vertically)
        !          1263: 
        !          1264:    The symbols for drag events are similar, but have the prefix `drag-'
        !          1265: before the word `mouse'.  For example, dragging the left button
        !          1266: generates a `drag-mouse-1' event.
        !          1267: 
        !          1268:    You can also request events when the mouse button is pressed down.
        !          1269: These events start with `down-' instead of `drag-'.  Such events are
        !          1270: generated only if they have key bindings.  When you get a button-down
        !          1271: event, a corresponding click or drag event will always follow.
        !          1272: 
        !          1273:    The symbols for mouse events also indicate the status of the modifier
        !          1274: keys, with the usual prefixes `C-', `M-' and `S-'. These always follow
        !          1275: `drag-' or `down-'.
        !          1276: 
        !          1277:    When mouse events occur in special parts of a frame or window, such
        !          1278: as a mode line or a scroll bar, the event symbol shows nothing special.
        !          1279:  The information about the special part is implicit in other data (the
        !          1280: screen location of the event).  But `read-key-sequence' figures out this
        !          1281: aspect of the event, and encodes it with make-believe prefix keys, all
        !          1282: of which are symbols: `mode-line', `vertical-line',
        !          1283: `horizontal-scrollbar' and `vertical-scrollbar'.  Thus, to define the
        !          1284: command for clicking the left button in a mode line, you could use this
        !          1285: key sequence:
        !          1286: 
        !          1287:      [mode-line mouse-1]
        !          1288: 
        !          1289:    You are not limited to defining individual function keys or mouse
        !          1290: buttons; these can appear anywhere in a key sequence, just as characters
        !          1291: can.  You can even mix together all three kinds of inputs in one key
        !          1292: sequence--but mixing mouse buttons with keyboard inputs is probably not
        !          1293: convenient for actual use.
        !          1294: 
        !          1295: 
        !          1296: File: emacs,  Node: Hook Changes,  Prev: Key Sequence Changes,  Up: Version 19
        !          1297: 
        !          1298: Changes Regarding Hooks
        !          1299: =======================
        !          1300: 
        !          1301:    A "hook variable" is a variable that exists so that you can store in
        !          1302: it functions for Emacs to call on certain occasions.  (The functions
        !          1303: that you put in hook variables are called "hook functions".)  Emacs 19
        !          1304: has a new convention for naming hook variables that indicates more
        !          1305: reliably how to use them.
        !          1306: 
        !          1307:    All the variables whose names end in `-hook' are "normal hooks";
        !          1308: their values are lists of functions to be called with no arguments. 
        !          1309: You can use `add-hook' (see below) to install hook functions in these
        !          1310: hooks.  We have made all Emacs hooks into normal hooks except when
        !          1311: there is some reason this won't work.
        !          1312: 
        !          1313:    A few hook-like variables are "abnormal"--they don't use the normal
        !          1314: convention.  This is either because the user-supplied functions receive
        !          1315: arguments, or because their return values matter.  These variables have
        !          1316: names that end in `-function' (if the value is a single function) or
        !          1317: `-functions' (if the value is a list of functions).
        !          1318: 
        !          1319:    Thus, you can always tell from the variable's name precisely how to
        !          1320: install a new hook function in the variable.  If the name indicates a
        !          1321: normal hook, then you also know how to write your hook function.
        !          1322: 
        !          1323:    To add a hook function to a normal hook, use `add-hook'.  It takes
        !          1324: care of adding a new hook function to any functions already installed in
        !          1325: a given hook.  It takes two arguments, the hook symbol and the function
        !          1326: to add.  For example,
        !          1327: 
        !          1328:      (add-hook 'text-mode-hook 'my-text-hook-function)
        !          1329: 
        !          1330: is how to arrange to call `my-text-hook-function' when entering Text
        !          1331: mode or related modes. Two new hooks are worth noting here.  Expansion
        !          1332: of an abbrev first runs the hook `pre-abbrev-expand-hook'.
        !          1333: `kill-buffer-hook' now runs whenever a buffer is killed.
        !          1334: 
        !          1335: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.