-than the comment starting delimiter in the strictest sense of the word;
-for example, in C mode the value of the variable is
-@c This stops M-q from breaking the line inside that @code.
-@code{@w{"/\\*+ *\\|//+ *""}}, which matches extra stars and spaces
-after the @samp{/*} itself, and accepts C++ style comments also.
-(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
-the string, which is needed to deny the first star its special meaning
-in regexp syntax. @xref{Regexps}.)
-
-@vindex comment-start
-@vindex comment-end
- When a comment command makes a new comment, it inserts the value of
-@code{comment-start} to begin it. The value of @code{comment-end} is
-inserted after point, so that it will follow the text that you will insert
-into the comment. In C mode, @code{comment-start} has the value
-@w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
-
-@vindex comment-padding
- The variable @code{comment-padding} specifies how many spaces
-@code{comment-region} should insert on each line between the
-comment delimiter and the line's original text. The default is 1,
-to insert one space.
-
-@vindex comment-multi-line
- The variable @code{comment-multi-line} controls how @kbd{C-M-j}
-(@code{indent-new-comment-line}) behaves when used inside a comment. If
-@code{comment-multi-line} is @code{nil}, as it normally is, then the
-comment on the starting line is terminated and a new comment is started
-on the new following line. If @code{comment-multi-line} is not
-@code{nil}, then the new following line is set up as part of the same
-comment that was found on the starting line. This is done by not
-inserting a terminator on the old line, and not inserting a starter on
-the new line. In languages where multi-line comments work, the choice
-of value for this variable is a matter of taste.
-
-@vindex comment-indent-function
- The variable @code{comment-indent-function} should contain a function
-that will be called to compute the indentation for a newly inserted
-comment or for aligning an existing comment. It is set differently by
-various major modes. The function is called with no arguments, but with
-point at the beginning of the comment, or at the end of a line if a new
-comment is to be inserted. It should return the column in which the
-comment ought to start. For example, in Lisp mode, the indent hook
-function bases its decision on how many semicolons begin an existing
-comment, and on the code in the preceding lines.
-
-@node Balanced Editing
-@section Editing Without Unbalanced Parentheses
-
-@table @kbd
-@item M-(
-Put parentheses around next sexp(s) (@code{insert-parentheses}).
-@item M-)
-Move past next close parenthesis and reindent
-(@code{move-past-close-and-reindent}).
-@end table
-
-@kindex M-(
-@kindex M-)
-@findex insert-parentheses
-@findex move-past-close-and-reindent
- The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
-(@code{move-past-close-and-reindent}) are designed to facilitate a style
-of editing which keeps parentheses balanced at all times. @kbd{M-(}
-inserts a pair of parentheses, either together as in @samp{()}, or, if
-given an argument, around the next several sexps. It leaves point after
-the open parenthesis. The command @kbd{M-)} moves past the close
-parenthesis, deleting any indentation preceding it, and indenting with
-@kbd{C-j} after it.
-
- For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-(
-F O O}, which has the same effect except for leaving the cursor before
-the close parenthesis.
-
-@vindex parens-require-spaces
- @kbd{M-(} may insert a space before the open parenthesis, depending on
-the syntax class of the preceding character. Set
-@code{parens-require-spaces} to @code{nil} value if you wish to inhibit
-this.
-
-@findex check-parens
-@cindex unbalanced parentheses and quotes
- You can use @kbd{M-x check-parens} to find any unbalanced
-parentheses and unbalanced string quotes in a buffer.
-
-@node Symbol Completion
-@section Completion for Symbol Names
-@cindex completion (symbol names)
-
- Usually completion happens in the minibuffer. But one kind of completion
-is available in all buffers: completion for symbol names.
-
-@kindex M-TAB
- The character @kbd{M-@key{TAB}} runs a command to complete the partial
-symbol before point against the set of meaningful symbol names. Any
-additional characters determined by the partial name are inserted at
-point.
-
- If the partial name in the buffer has more than one possible completion
-and they have no additional characters in common, a list of all possible
-completions is displayed in another window.
-
-@cindex tags-based completion
-@cindex Info index completion
-@findex complete-symbol
- In most programming language major modes, @kbd{M-@key{TAB}} runs the
-command @code{complete-symbol}, which provides two kinds of completion.
-Normally it does completion based on a tags table (@pxref{Tags}); with a
-numeric argument (regardless of the value), it does completion based on
-the names listed in the Info file indexes for your language. Thus, to
-complete the name of a symbol defined in your own program, use
-@kbd{M-@key{TAB}} with no argument; to complete the name of a standard
-library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
-completion works only if there is an Info file for the standard library
-functions of your language, and only if it is installed at your site.
-
-@cindex Lisp symbol completion
-@cindex completion (Lisp symbols)
-@findex lisp-complete-symbol
- In Emacs-Lisp mode, the name space for completion normally consists of
-nontrivial symbols present in Emacs---those that have function
-definitions, values or properties. However, if there is an
-open-parenthesis immediately before the beginning of the partial symbol,
-only symbols with function definitions are considered as completions.
-The command which implements this is @code{lisp-complete-symbol}.
-
- In Text mode and related modes, @kbd{M-@key{TAB}} completes words
-based on the spell-checker's dictionary. @xref{Spelling}.
-
-@node Which Function
-@section Which Function Mode
-
- Which Function mode is a minor mode that displays the current function
-name in the mode line, as you move around in a buffer.
-
-@findex which-function-mode
-@vindex which-func-modes
- To enable (or disable) Which Function mode, use the command @kbd{M-x
-which-function-mode}. This command is global; it applies to all
-buffers, both existing ones and those yet to be created. However, this
-only affects certain major modes, those listed in the value of
-@code{which-func-modes}. (If the value is @code{t}, then Which Function
-mode applies to all major modes that know how to support it---which are
-the major modes that support Imenu.)
-
-@node Hideshow
-@section Hideshow minor mode
-
-@findex hs-minor-mode
- Hideshow minor mode provides selective display of portions of a
-file, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} to
-enable or disable this mode, or add @code{hs-minor-mode} to the mode
-hook for certain major modes in order to enable it automatically for
-those modes.
-
- Just what constitutes a block depends on the major mode. In C mode
-or C++ mode, they are delimited by braces, while in Lisp mode and
-similar modes they are delimited by parentheses. Multi-line comments
-also count as blocks.
-
-@findex hs-hide-all
-@findex hs-hide-block
-@findex hs-show-all
-@findex hs-show-block
-@findex hs-show-region
-@findex hs-hide-level
-@findex hs-minor-mode
-@kindex C-c @@ C-h
-@kindex C-c @@ C-s
-@kindex C-c @@ C-M-h
-@kindex C-c @@ C-M-s
-@kindex C-c @@ C-r
-@kindex C-c @@ C-l
-@kindex S-Mouse-2
-@table @kbd
-@item C-c @@ C-h
-Hide the current block (@code{hs-hide-block}).
-@item C-c @@ C-s
-Show the current block (@code{hs-show-block}).
-@item C-c @@ C-c
-Either hide or show the current block (@code{hs-toggle-hiding})
-@item S-Mouse-2
-Either hide or show the block you click on (@code{hs-mouse-toggle-hiding})
-@item C-c @@ C-M-h
-Hide all top-level blocks (@code{hs-hide-all}).
-@item C-c @@ C-M-s
-Show everything in the buffer (@code{hs-show-all}).
-@item C-c @@ C-l
-Hide all blocks @var{n} levels below this block
-(@code{hs-hide-level}).
-@end table
-
-@vindex hs-hide-comments-when-hiding-all
-@vindex hs-isearch-open
-@vindex hs-special-modes-alist
- These user options exist for customizing Hideshow mode.
-
-@table @code
-@item hs-hide-comments-when-hiding-all
-Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
-@item hs-isearch-open
-Specifies what kind of hidden blocks to open in Isearch mode.
-@item hs-special-modes-alist
-Specifies
-Initializes Hideshow variables for different modes.
-@end table
-
-@node Glasses
-@section Glasses minor mode
-@cindex Glasses mode
-@cindex identifiers, making long ones readable
-@cindex StudlyCaps, making them readable
-@findex glasses-mode
-
- Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}
-readable by altering the display. It can do this in two different
-ways: by displaying underscores between an lower-case letter and the
-following capital letter, or by emboldening the capital letters. It
-does not alter the buffer text, only the way they display, so you can
-use it even on read-only buffers. You can use the command @kbd{M-x
-glasses-mode} to enable or disable the mode; you can also add
-@code{glasses-mode} to the mode hook of appropriate programming
-language major modes.
-
-@node Documentation
-@section Documentation Commands
-
- As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
-(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
-be used to print documentation of functions and variables that you want to
-call. These commands use the minibuffer to read the name of a function or
-variable to document, and display the documentation in a window.
-
- For extra convenience, these commands provide default arguments based on
-the code in the neighborhood of point. @kbd{C-h f} sets the default to the
-function called in the innermost list containing point. @kbd{C-h v} uses
-the symbol name around or adjacent to point as its default.
-
-@cindex Eldoc mode
-@findex eldoc-mode
- For Emacs Lisp code, you can also use Eldoc mode. This minor mode
-constantly displays in the echo area the argument list for the function
-being called at point. (In other words, it finds the function call that
-point is contained in, and displays the argument list of that function.)
-Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use
-the command @kbd{M-x eldoc-mode} to enable or disable this feature.
-
-@findex info-lookup-symbol
-@findex info-lookup-file
-@kindex C-h C-i
- For C, Lisp, and other languages, you can use @kbd{C-h C-i}
-(@code{info-lookup-symbol}) to view the Info documentation for a symbol.
-You specify the symbol with the minibuffer; by default, it uses the
-symbol that appears in the buffer at point. The major mode determines
-where to look for documentation for the symbol---which Info files and
-which indices. You can also use @kbd{M-x info-lookup-file} to look for
-documentation for a file name. Currently this supports the following
-modes: Awk, Autoconf, Bison, C, Emacs Lisp, LaTeX, M4,
-Makefile, Octave, Perl, Scheme and Texinfo, provided you have installed
-the relevant Info files, which are typically available with the appropriate GNU
-package.
-
-@findex manual-entry
-@cindex manual pages
- You can read the ``man page'' for an operating system command, library
-function, or system call, with the @kbd{M-x manual-entry} command. It
-runs the @code{man} program to format the man page, and runs it
-asynchronously if your system permits, so that you can keep on editing
-while the page is being formatted. (MS-DOS and MS-Windows 3 do not
-permit asynchronous subprocesses, so on these systems you cannot edit
-while Emacs waits for @code{man} to exit.) The result goes in a buffer
-named @samp{*Man @var{topic}*}. These buffers use a special major mode,
-Man mode, that facilitates scrolling and examining other manual pages.
-For details, type @kbd{C-h m} while in a man page buffer.
-
-@cindex sections of manual pages
- Man pages are classified into @dfn{sections}; sometimes there are
-man pages with the same name in different sections. To read a man
-page from a specific section, type @samp{@var{topic}(@var{section})} or
-@samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts
-for the topic. For example, to read the man page for the C library
-function @code{chmod} (as opposed to a command by the same name), type
-@kbd{M-x manual-entry @key{RET} chmod(2v) @key{RET}} (assuming
-@code{chmod} is in section @samp{2v}).
-
- If you do not specify a section, the results depend on how the
-@code{man} command works on your system. Some of them display only
-the first man page they find. Others display all man pages that have
-the specified name, so you can page between them with the @kbd{M-n}
-and @kbd{M-p} keys. The mode line shows how many manual pages are
-available in the Man buffer.
-
-@vindex Man-fontify-manpage-flag
- For a long man page, setting the faces properly can take substantial
-time. By default, Emacs uses faces in man pages if Emacs can display
-different fonts or colors. You can turn off use of faces in man pages
-by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}.
-
-@findex Man-fontify-manpage
- If you insert the text of a man page into an Emacs buffer in some
-other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
-perform the same conversions that @kbd{M-x manual-entry} does.
-
-@findex woman
-@cindex manual pages, on MS-DOS/MS-Windows
- An alternative way of reading manual pages is the @kbd{M-x woman}
-command@footnote{The name of the command, @code{woman}, is an acronym
-for ``w/o (without) man,'' since it doesn't use the @code{man}
-program.}. Unlike @kbd{M-x man}, it does not run any external
-programs to format and display the man pages; instead it does the job
-in Emacs Lisp, so it works on systems such as MS-Windows, where the
-@code{man} program and other the programs it needs are not readily
-available. @kbd{M-x woman} prompts for a name of a manual page, and
-provides completion based on the list of manual pages that are
-installed on your machine; the list of available manual pages is
-computed automatically the first time you invoke @code{woman}. The
-word at point in the current buffer is used to suggest the default
-name of the manual page.
-
- With a numeric argument, @kbd{M-x woman} recomputes the list of the
-manual pages used for completion. This is useful if you add or delete
-manual pages.
-
- If you type a name of a manual page and @kbd{M-x woman} finds that
-several manual pages by the same name exist in different sections, it
-pops up a window with possible candidates asking you to choose one of
-them.
-
-@vindex woman-manpath
- By default, @kbd{M-x woman} looks up the manual pages in directories
-listed by the @code{MANPATH} environment variable. (If @code{MANPATH}
-is not set, @code{woman} uses a suitable default value, which can be
-customized.) More precisely, @code{woman} looks for subdirectories that
-match the shell wildcard @file{man*} in each one of these directories,
-and tries to find the manual pages in those subdirectories. When first
-invoked, @kbd{M-x woman} converts the value of @code{MANPATH} to a list
-of directory names and stores that list in the @code{woman-manpath}
-variable. By changing the value of this variable, you can customize the
-list of directories where @code{woman} looks for manual pages.
-
-@vindex woman-path
- In addition, you can augment the list of directories searched by
-@code{woman} by setting the value of the @code{woman-path} variable.
-This variable should hold a list of specific directories which
-@code{woman} should search, in addition to those in
-@code{woman-manpath}. Unlike @code{woman-manpath}, the directories in
-@code{woman-path} are searched for the manual pages, not for @file{man*}
-subdirectories.
-
-@findex woman-find-file
- Occasionally, you might need to display manual pages that are not in
-any of the directories listed by @code{woman-manpath} and
-@code{woman-path}. The @kbd{M-x woman-find-file} command prompts for a
-name of a manual page file, with completion, and then formats and
-displays that file like @kbd{M-x woman} does.
-
-@vindex woman-dired-keys
- First time you invoke @kbd{M-x woman}, it defines the Dired @kbd{W}
-key to run the @code{woman-find-file} command on the current line's
-file. You can disable this by setting the variable
-@code{woman-dired-keys} to @code{nil}. @xref{Dired}. In addition, the
-Tar-mode @kbd{w} key is bound to @code{woman-find-file} on the current
-line's archive member.
-
- For more information about setting up and using @kbd{M-x woman}, see
-@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
-Manual}.
-
- Eventually the GNU project hopes to replace most man pages with
-better-organized manuals that you can browse with Info. @xref{Misc
-Help}. Since this process is only partially completed, it is still
-useful to read manual pages.
-
-@node Change Log
-@section Change Logs
-
-@cindex change log
-@kindex C-x 4 a
-@findex add-change-log-entry-other-window
- The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
-file for the file you are editing
-(@code{add-change-log-entry-other-window}). If that file is actually
-a backup file, it makes an entry appropriate for the file's
-parent---that is useful for making log entries for functions that
-have been deleted in the current version.
-
- A change log file contains a chronological record of when and why you
-have changed a program, consisting of a sequence of entries describing
-individual changes. Normally it is kept in a file called
-@file{ChangeLog} in the same directory as the file you are editing, or
-one of its parent directories. A single @file{ChangeLog} file can
-record changes for all the files in its directory and all its
-subdirectories.
-
- A change log entry starts with a header line that contains your name,
-your email address (taken from the variable @code{user-mail-address}),
-and the current date and time. Aside from these header lines, every
-line in the change log starts with a space or a tab. The bulk of the
-entry consists of @dfn{items}, each of which starts with a line starting
-with whitespace and a star. Here are two entries, both dated in May
-1993, each with two items:
-
-@iftex
-@medbreak
-@end iftex
-@smallexample
-1993-05-25 Richard Stallman <rms@@gnu.org>
-
- * man.el: Rename symbols `man-*' to `Man-*'.
- (manual-entry): Make prompt string clearer.
-
- * simple.el (blink-matching-paren-distance):
- Change default to 12,000.
-
-1993-05-24 Richard Stallman <rms@@gnu.org>
-
- * vc.el (minor-mode-map-alist): Don't use it if it's void.
- (vc-cancel-version): Doc fix.
-@end smallexample
-
- One entry can describe several changes; each change should have its
-own item. Normally there should be a blank line between items. When
-items are related (parts of the same change, in different places), group
-them by leaving no blank line between them. The second entry above
-contains two items grouped in this way.
-
- @kbd{C-x 4 a} visits the change log file and creates a new entry
-unless the most recent entry is for today's date and your name. It
-also creates a new item for the current file. For many languages, it
-can even guess the name of the function or other object that was
-changed.
-
-@vindex add-log-keep-changes-together
- When the option @code{add-log-keep-changes-together} is
-non-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the file
-rather than starting a new entry.
-
-@vindex change-log-version-info-enabled
-@vindex change-log-version-number-regexp-list
-@cindex file version in change log entries
- If the value of the variable @code{change-log-version-info-enabled}
-is non-@code{nil}, @kbd{C-x 4 a} ads the file's version number to the
-change log entry. It finds the version number by searching the first
-ten percent of the file, using regular expressions from the variable
-@code{change-log-version-number-regexp-list}.
-
-@cindex Change Log mode
-@findex change-log-mode
- The change log file is visited in Change Log mode. In this major
-mode, each bunch of grouped items counts as one paragraph, and each
-entry is considered a page. This facilitates editing the entries.
-@kbd{C-j} and auto-fill indent each new line like the previous line;
-this is convenient for entering the contents of an entry.
-
-@findex change-log-merge
- You can use the command @kbd{M-x change-log-merge} to merge other
-log files into a buffer in Change Log Mode, preserving the date
-ordering of entries.
-
-@findex change-log-redate
-@cindex converting change log date style
- Versions of Emacs before 20.1 used a different format for the time of
-the change log entry:
-
-@smallexample
-Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>
-@end smallexample
-
-@noindent
-The @kbd{M-x change-log-redate} command converts all the old-style
-date entries in the change log file visited in the current buffer to
-the new format, to make the file uniform in style. This is handy when
-entries are contributed by many different people, some of whom use old
-versions of Emacs.
-
- Version control systems are another way to keep track of changes in your
-program and keep a change log. @xref{Log Buffer}.
-
-@node Authors
-@section @file{AUTHORS} files
-@cindex @file{AUTHORS} file
-
- Programs which have many contributors usually include a file named
-@file{AUTHORS} in their distribution, which lists the individual
-contributions. Emacs has a special command for maintaining the
-@file{AUTHORS} file that is part of the Emacs distribution.
-
-@findex authors
- The @kbd{M-x authors} command prompts for the name of the root of the
-Emacs source directory. It then scans @file{ChageLog} files and Lisp
-source files under that directory for information about authors of
-individual packages and people who made changes in source files, and
-puts the information it gleans into a buffer named @samp{*Authors*}.
-You can then edit the contents of that buffer and merge it with the
-exisiting @file{AUTHORS} file.
-
- Do not assume that this command finds all the contributors; don't
-assume that a person not listed in the output was not a contributor.
-If you merged in someone's contribution and did not put his name
-in the change log, he won't show up in @kbd{M-x authors} either.
-
-@node Tags
-@section Tags Tables
-@cindex tags table
-
- A @dfn{tags table} is a description of how a multi-file program is
-broken up into files. It lists the names of the component files and the
-names and positions of the functions (or other named subunits) in each
-file. Grouping the related files makes it possible to search or replace
-through all the files with one command. Recording the function names
-and positions makes possible the @kbd{M-.} command which finds the
-definition of a function by looking up which of the files it is in.
-
- Tags tables are stored in files called @dfn{tags table files}. The
-conventional name for a tags table file is @file{TAGS}.
-
- Each entry in the tags table records the name of one tag, the name of the
-file that the tag is defined in (implicitly), and the position in that file
-of the tag's definition.
-
- Just what names from the described files are recorded in the tags table
-depends on the programming language of the described file. They
-normally include all file names, functions and subroutines, and may
-also include global variables, data types, and anything else
-convenient. Each name recorded is called a @dfn{tag}.
-
-@cindex C++ class browser, tags
-@cindex tags, C++
-@cindex class browser, C++
-@cindex Ebrowse
- See also the Ebrowse facility, which is tailored for C++.
-@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
-
-@menu
-* Tag Syntax:: Tag syntax for various types of code and text files.
-* Create Tags Table:: Creating a tags table with @code{etags}.
-* Etags Regexps:: Create arbitrary tags using regular expressions.
-* Select Tags Table:: How to visit a tags table.
-* Find Tag:: Commands to find the definition of a specific tag.
-* Tags Search:: Using a tags table for searching and replacing.
-* List Tags:: Listing and finding tags defined in a file.
-@end menu
-
-@node Tag Syntax
-@subsection Source File Tag Syntax
-
- Here is how tag syntax is defined for the most popular languages:
-
-@itemize @bullet
-@item
-In C code, any C function or typedef is a tag, and so are definitions of
-@code{struct}, @code{union} and @code{enum}.
-@code{#define} macro definitions and @code{enum} constants are also
-tags, unless you specify @samp{--no-defines} when making the tags table.
-Similarly, global variables are tags, unless you specify
-@samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
-can make the tags table file much smaller.
-
-You can tag function declarations and external variables in addition
-to function definitions by giving the @samp{--declarations} option to
-@code{etags}.
-
-@item
-In C++ code, in addition to all the tag constructs of C code, member
-functions are also recognized, and optionally member variables if you
-use the @samp{--members} option. Tags for variables and functions in
-classes are named @samp{@var{class}::@var{variable}} and
-@samp{@var{class}::@var{function}}. @code{operator} definitions have
-tag names like @samp{operator+}.
-
-@item
-In Java code, tags include all the constructs recognized in C++, plus
-the @code{interface}, @code{extends} and @code{implements} constructs.
-Tags for variables and functions in classes are named
-@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
-
-@item
-In La@TeX{} text, the argument of any of the commands @code{\chapter},
-@code{\section}, @code{\subsection}, @code{\subsubsection},
-@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
-@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
-tag.@refill
-
-Other commands can make tags as well, if you specify them in the
-environment variable @env{TEXTAGS} before invoking @code{etags}. The
-value of this environment variable should be a colon-separated list of
-command names. For example,
-
-@example
-TEXTAGS="def:newcommand:newenvironment"
-export TEXTAGS
-@end example
-
-@noindent
-specifies (using Bourne shell syntax) that the commands @samp{\def},
-@samp{\newcommand} and @samp{\newenvironment} also define tags.
-
-@item
-In Lisp code, any function defined with @code{defun}, any variable
-defined with @code{defvar} or @code{defconst}, and in general the first
-argument of any expression that starts with @samp{(def} in column zero, is
-a tag.
-
-@item
-In Scheme code, tags include anything defined with @code{def} or with a
-construct whose name starts with @samp{def}. They also include variables
-set with @code{set!} at top level in the file.
-@end itemize
-
- Several other languages are also supported:
-
-@itemize @bullet
-
-@item
-In Ada code, functions, procedures, packages, tasks, and types are
-tags. Use the @samp{--packages-only} option to create tags for
-packages only.
-
-In Ada, the same name can be used for different kinds of entity
-(e.g.@:, for a procedure and for a function). Also, for things like
-packages, procedures and functions, there is the spec (i.e.@: the
-interface) and the body (i.e.@: the implementation). To make it
-easier to pick the definition you want, Ada tag name have suffixes
-indicating the type of entity:
-
-@table @samp
-@item /b
-package body.
-@item /f
-function.
-@item /k
-task.
-@item /p
-procedure.
-@item /s
-package spec.
-@item /t
-type.
-@end table
-
- Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
-directly to the body of the package @code{bidule}, while @kbd{M-x
-find-tag @key{RET} bidule @key{RET}} will just search for any tag
-@code{bidule}.
-
-@item
-In assembler code, labels appearing at the beginning of a line,
-followed by a colon, are tags.
-
-@item
-In Bison or Yacc input files, each rule defines as a tag the nonterminal
-it constructs. The portions of the file that contain C code are parsed
-as C code.
-
-@item
-In Cobol code, tags are paragraph names; that is, any word starting in
-column 8 and followed by a period.
-
-@item
-In Erlang code, the tags are the functions, records, and macros defined
-in the file.
-
-@item
-In Fortran code, functions, subroutines and blockdata are tags.
-
-@item
-In makefiles, targets are tags.
-
-@item
-In Objective C code, tags include Objective C definitions for classes,
-class categories, methods, and protocols.
-
-@item
-In Pascal code, the tags are the functions and procedures defined in
-the file.
-
-@item
-In Perl code, the tags are the procedures defined by the @code{sub},
-@code{my} and @code{local} keywords. Use @samp{--globals} if you want
-to tag global variables.
-
-@item
-In PostScript code, the tags are the functions.
-
-@item
-In Prolog code, a tag name appears at the left margin.
-
-@item
-In Python code, @code{def} or @code{class} at the beginning of a line
-generate a tag.
-@end itemize
-
- You can also generate tags based on regexp matching (@pxref{Etags
-Regexps}) to handle other formats and languages.
-
-@node Create Tags Table
-@subsection Creating Tags Tables
-@cindex @code{etags} program
-
- The @code{etags} program is used to create a tags table file. It knows
-the syntax of several languages, as described in
-@iftex
-the previous section.
-@end iftex
-@ifinfo
-@ref{Tag Syntax}.
-@end ifinfo
-Here is how to run @code{etags}:
-
-@example
-etags @var{inputfiles}@dots{}
-@end example
-
-@noindent
-The @code{etags} program reads the specified files, and writes a tags
-table named @file{TAGS} in the current working directory.
-
- If the specified files don't exist, @code{etags} looks for
-compressed versions of them and uncompresses them to read them. Under
-MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
-if it is given @samp{mycode.c} on the command line and @file{mycode.c}
-does not exist.
-
- @code{etags} recognizes the language used in an input file based on
-its file name and contents. You can specify the language with the
-@samp{--language=@var{name}} option, described below.
-
- If the tags table data become outdated due to changes in the files
-described in the table, the way to update the tags table is the same
-way it was made in the first place. But it is not necessary to do
-this very often.
-
- If the tags table fails to record a tag, or records it for the wrong
-file, then Emacs cannot possibly find its definition. However, if the
-position recorded in the tags table becomes a little bit wrong (due to
-some editing in the file that the tag definition is in), the only
-consequence is a slight delay in finding the tag. Even if the stored
-position is very wrong, Emacs will still find the tag, but it must
-search the entire file for it.
-
- So you should update a tags table when you define new tags that you want
-to have listed, or when you move tag definitions from one file to another,
-or when changes become substantial. Normally there is no need to update
-the tags table after each edit, or even every day.
-
- One tags table can virtually include another. Specify the included
-tags file name with the @samp{--include=@var{file}} option when
-creating the file that is to include it. The latter file then acts as
-if it covered all the source files specified in the included file, as
-well as the files it directly contains.
-
- If you specify the source files with relative file names when you run
-@code{etags}, the tags file will contain file names relative to the
-directory where the tags file was initially written. This way, you can
-move an entire directory tree containing both the tags file and the
-source files, and the tags file will still refer correctly to the source
-files.
-
- If you specify absolute file names as arguments to @code{etags}, then
-the tags file will contain absolute file names. This way, the tags file
-will still refer to the same files even if you move it, as long as the
-source files remain in the same place. Absolute file names start with
-@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
-
- When you want to make a tags table from a great number of files, you
-may have problems listing them on the command line, because some systems
-have a limit on its length. The simplest way to circumvent this limit
-is to tell @code{etags} to read the file names from its standard input,
-by typing a dash in place of the file names, like this:
-
-@smallexample
-find . -name "*.[chCH]" -print | etags -
-@end smallexample
-
- Use the option @samp{--language=@var{name}} to specify the language
-explicitly. You can intermix these options with file names; each one
-applies to the file names that follow it. Specify
-@samp{--language=auto} to tell @code{etags} to resume guessing the
-language from the file names and file contents. Specify
-@samp{--language=none} to turn off language-specific processing
-entirely; then @code{etags} recognizes tags by regexp matching alone
-(@pxref{Etags Regexps}).
-
- @samp{etags --help} prints the list of the languages @code{etags}
-knows, and the file name rules for guessing the language. It also prints
-a list of all the available @code{etags} options, together with a short
-explanation.
-
-@node Etags Regexps
-@subsection Etags Regexps
-
- The @samp{--regex} option provides a general way of recognizing tags
-based on regexp matching. You can freely intermix it with file names.
-Each @samp{--regex} option adds to the preceding ones, and applies only
-to the following files. The syntax is:
-
-@smallexample
---regex=/@var{tagregexp}[/@var{nameregexp}]/
-@end smallexample
-
-@noindent
-where @var{tagregexp} is used to match the lines to tag. It is always
-anchored, that is, it behaves as if preceded by @samp{^}. If you want
-to account for indentation, just match any initial number of blanks by
-beginning your regular expression with @samp{[ \t]*}. In the regular
-expressions, @samp{\} quotes the next character, and @samp{\t} stands
-for the tab character. Note that @code{etags} does not handle the other
-C escape sequences for special characters.
-
-@cindex interval operator (in regexps)
- The syntax of regular expressions in @code{etags} is the same as in
-Emacs, augmented with the @dfn{interval operator}, which works as in
-@code{grep} and @code{ed}. The syntax of an interval operator is
-@samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
-expression at least @var{m} times and up to @var{n} times.
-
- You should not match more characters with @var{tagregexp} than that
-needed to recognize what you want to tag. If the match is such that
-more characters than needed are unavoidably matched by @var{tagregexp}
-(as will usually be the case), you should add a @var{nameregexp}, to
-pick out just the tag. This will enable Emacs to find tags more
-accurately and to do completion on tag names more reliably. You can
-find some examples below.
-
- The option @samp{--ignore-case-regex} (or @samp{-c}) works like
-@samp{--regex}, except that matching ignores case. This is
-appropriate for certain programming languages.
-
- The @samp{-R} option deletes all the regexps defined with
-@samp{--regex} options. It applies to the file names following it, as
-you can see from the following example:
-
-@smallexample
-etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
- bar.ber -R --lang=lisp los.er
-@end smallexample
-
-@noindent
-Here @code{etags} chooses the parsing language for @file{voo.doo} and
-@file{bar.ber} according to their contents. @code{etags} also uses
-@var{reg1} to recognize additional tags in @file{voo.doo}, and both
-@var{reg1} and @var{reg2} to recognize additional tags in
-@file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
-matching, to recognize tags in @file{los.er}.
-
- You can specify a regular expression for a particular language, by
-writing @samp{@{lang@}} in front of it. Then @code{etags} will use
-the regular expression only for files of that language. (@samp{etags
---help} prints the list of languages recognised by @code{etags}.) The
-following example tags the @code{DEFVAR} macros in the Emacs source
-files, for the C language only:
-
-@smallexample
---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
-@end smallexample
-
-@noindent
-This feature is particularly useful when you store a list of regular
-expressions in a file. The following option syntax instructs
-@code{etags} to read two files of regular expressions. The regular
-expressions contained in the second file are matched without regard to
-case.
-
-@smallexample
---regex=@@first-file --ignore-case-regex=@@second-file
-@end smallexample
-
-@noindent
-A regex file contains one regular expressions per line. Empty lines,
-and lines beginning with space or tab are ignored. When the first
-character in a line is @samp{@@}, @code{etags} assumes that the rest
-of the line is the name of a file of regular expressions; thus, one
-such file can include another file. All the other lines are taken to
-be regular expressions. If the first non-whitespace text on the line
-is @samp{--}, that line is a comment.
-
- For example, one can create a file called @samp{emacs.tags} with the
-following contents:
-
-@smallexample
- -- This is for GNU Emacs C source files
-@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
-@end smallexample
-
-@noindent
-and then use it like this:
-
-@smallexample
-etags --regex=@@emacs.tags *.[ch] */*.[ch]
-@end smallexample
-
- Here are some more examples. The regexps are quoted to protect them
-from shell interpretation.
-
-@itemize @bullet
-
-@item
-Tag Octave files:
-
-@smallexample
-etags --language=none \
- --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
- --regex='/###key \(.*\)/\1/' \
- --regex='/[ \t]*global[ \t].*/' \
- *.m
-@end smallexample
-
-@noindent
-Note that tags are not generated for scripts, so that you have to add
-a line by yourself of the form @samp{###key @var{scriptname}} if you
-want to jump to it.
-
-@item
-Tag Tcl files:
-
-@smallexample
-etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
-@end smallexample
-
-@item
-Tag VHDL files:
-
-@smallexample
-etags --language=none \
- --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
- --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
- \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
-@end smallexample
-@end itemize
-
-@node Select Tags Table
-@subsection Selecting a Tags Table
-
-@vindex tags-file-name
-@findex visit-tags-table
- Emacs has at any time one @dfn{selected} tags table, and all the commands
-for working with tags tables use the selected one. To select a tags table,
-type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
-argument. The name @file{TAGS} in the default directory is used as the
-default file name.
-
- All this command does is store the file name in the variable
-@code{tags-file-name}. Emacs does not actually read in the tags table
-contents until you try to use them. Setting this variable yourself is just
-as good as using @code{visit-tags-table}. The variable's initial value is
-@code{nil}; that value tells all the commands for working with tags tables
-that they must ask for a tags table file name to use.
-
- Using @code{visit-tags-table} when a tags table is already loaded
-gives you a choice: you can add the new tags table to the current list
-of tags tables, or start a new list. The tags commands use all the tags
-tables in the current list. If you start a new list, the new tags table
-is used @emph{instead} of others. If you add the new table to the
-current list, it is used @emph{as well as} the others. When the tags
-commands scan the list of tags tables, they don't always start at the
-beginning of the list; they start with the first tags table (if any)
-that describes the current file, proceed from there to the end of the
-list, and then scan from the beginning of the list until they have
-covered all the tables in the list.
-
-@vindex tags-table-list
- You can specify a precise list of tags tables by setting the variable
-@code{tags-table-list} to a list of strings, like this:
-
-@c keep this on two lines for formatting in smallbook
-@example
-@group
-(setq tags-table-list
- '("~/emacs" "/usr/local/lib/emacs/src"))
-@end group
-@end example
-
-@noindent
-This tells the tags commands to look at the @file{TAGS} files in your
-@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
-directory. The order depends on which file you are in and which tags
-table mentions that file, as explained above.
-
- Do not set both @code{tags-file-name} and @code{tags-table-list}.
-
-@node Find Tag
-@subsection Finding a Tag
-
- The most important thing that a tags table enables you to do is to find
-the definition of a specific tag.
-
-@table @kbd
-@item M-.@: @var{tag} @key{RET}
-Find first definition of @var{tag} (@code{find-tag}).
-@item C-u M-.
-Find next alternate definition of last tag specified.
-@item C-u - M-.
-Go back to previous tag found.
-@item C-M-. @var{pattern} @key{RET}
-Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
-@item C-u C-M-.
-Find the next tag whose name matches the last pattern used.
-@item C-x 4 .@: @var{tag} @key{RET}
-Find first definition of @var{tag}, but display it in another window
-(@code{find-tag-other-window}).
-@item C-x 5 .@: @var{tag} @key{RET}
-Find first definition of @var{tag}, and create a new frame to select the
-buffer (@code{find-tag-other-frame}).
-@item M-*
-Pop back to where you previously invoked @kbd{M-.} and friends.
-@end table
-
-@kindex M-.
-@findex find-tag
- @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
-a specified tag. It searches through the tags table for that tag, as a
-string, and then uses the tags table info to determine the file that the
-definition is in and the approximate character position in the file of
-the definition. Then @code{find-tag} visits that file, moves point to
-the approximate character position, and searches ever-increasing
-distances away to find the tag definition.
-
- If an empty argument is given (just type @key{RET}), the sexp in the
-buffer before or around point is used as the @var{tag} argument.
-@xref{Lists}, for info on sexps.
-
- You don't need to give @kbd{M-.} the full name of the tag; a part
-will do. This is because @kbd{M-.} finds tags in the table which
-contain @var{tag} as a substring. However, it prefers an exact match
-to a substring match. To find other tags that match the same
-substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
-M-.}; this does not read a tag name, but continues searching the tags
-table's text for another tag containing the same substring last used.
-If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
-alternative to @kbd{C-u M-.}.
-
-@kindex C-x 4 .
-@findex find-tag-other-window
-@kindex C-x 5 .
-@findex find-tag-other-frame
- Like most commands that can switch buffers, @code{find-tag} has a
-variant that displays the new buffer in another window, and one that
-makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
-the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
-which invokes @code{find-tag-other-frame}.
-
- To move back to places you've found tags recently, use @kbd{C-u -
-M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
-command can take you to another buffer. @kbd{C-x 4 .} with a negative
-argument finds the previous tag location in another window.
-
-@kindex M-*
-@findex pop-tag-mark
-@vindex find-tag-marker-ring-length
- As well as going back to places you've found tags recently, you can go
-back to places @emph{from where} you found them. Use @kbd{M-*}, which
-invokes the command @code{pop-tag-mark}, for this. Typically you would
-find and study the definition of something with @kbd{M-.} and then
-return to where you were with @kbd{M-*}.
-
- Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
-a depth determined by the variable @code{find-tag-marker-ring-length}.
-
-@findex find-tag-regexp
-@kindex C-M-.
- The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
-match a specified regular expression. It is just like @kbd{M-.} except
-that it does regexp matching instead of substring matching.
-
-@node Tags Search
-@subsection Searching and Replacing with Tags Tables
-@cindex search and replace in multiple files
-@cindex multiple-file search and replace
-
- The commands in this section visit and search all the files listed in the
-selected tags table, one by one. For these commands, the tags table serves
-only to specify a sequence of files to search.
-
-@table @kbd
-@item M-x tags-search @key{RET} @var{regexp} @key{RET}
-Search for @var{regexp} through the files in the selected tags
-table.
-@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
-Perform a @code{query-replace-regexp} on each file in the selected tags table.
-@item M-,
-Restart one of the commands above, from the current location of point
-(@code{tags-loop-continue}).
-@end table
-
-@findex tags-search
- @kbd{M-x tags-search} reads a regexp using the minibuffer, then
-searches for matches in all the files in the selected tags table, one
-file at a time. It displays the name of the file being searched so you
-can follow its progress. As soon as it finds an occurrence,
-@code{tags-search} returns.
-
-@kindex M-,
-@findex tags-loop-continue
- Having found one match, you probably want to find all the rest. To find
-one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
-@code{tags-search}. This searches the rest of the current buffer, followed
-by the remaining files of the tags table.@refill
-
-@findex tags-query-replace
- @kbd{M-x tags-query-replace} performs a single
-@code{query-replace-regexp} through all the files in the tags table. It
-reads a regexp to search for and a string to replace with, just like
-ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
-tags-search}, but repeatedly, processing matches according to your
-input. @xref{Replace}, for more information on query replace.
-
-@vindex tags-case-fold-search
-@cindex case-sensitivity and tags search
- You can control the case-sensitivity of tags search commands by
-customizing the value of the variable @code{tags-case-fold-search}. The
-default is to use the same setting as the value of
-@code{case-fold-search} (@pxref{Search Case}).
-
- It is possible to get through all the files in the tags table with a
-single invocation of @kbd{M-x tags-query-replace}. But often it is
-useful to exit temporarily, which you can do with any input event that
-has no special query replace meaning. You can resume the query replace
-subsequently by typing @kbd{M-,}; this command resumes the last tags
-search or replace command that you did.
-
- The commands in this section carry out much broader searches than the
-@code{find-tag} family. The @code{find-tag} commands search only for
-definitions of tags that match your substring or regexp. The commands
-@code{tags-search} and @code{tags-query-replace} find every occurrence
-of the regexp, as ordinary search commands and replace commands do in
-the current buffer.
-
- These commands create buffers only temporarily for the files that they
-have to search (those which are not already visited in Emacs buffers).
-Buffers in which no match is found are quickly killed; the others
-continue to exist.
-
- It may have struck you that @code{tags-search} is a lot like
-@code{grep}. You can also run @code{grep} itself as an inferior of
-Emacs and have Emacs show you the matching lines one by one. This works
-much like running a compilation; finding the source locations of the
-@code{grep} matches works like finding the compilation errors.
-@xref{Compilation}.
-
-@node List Tags
-@subsection Tags Table Inquiries
-
-@table @kbd
-@item M-x list-tags @key{RET} @var{file} @key{RET}
-Display a list of the tags defined in the program file @var{file}.
-@item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
-Display a list of all tags matching @var{regexp}.
-@end table
-
-@findex list-tags
- @kbd{M-x list-tags} reads the name of one of the files described by
-the selected tags table, and displays a list of all the tags defined in
-that file. The ``file name'' argument is really just a string to
-compare against the file names recorded in the tags table; it is read as
-a string rather than as a file name. Therefore, completion and
-defaulting are not available, and you must enter the file name the same
-way it appears in the tags table. Do not include a directory as part of
-the file name unless the file name recorded in the tags table includes a
-directory.
-
-@findex tags-apropos
-@vindex tags-apropos-verbose
- @kbd{M-x tags-apropos} is like @code{apropos} for tags
-(@pxref{Apropos}). It finds all the tags in the selected tags table
-whose entries match @var{regexp}, and displays them. If the variable
-@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
-of the tags files together with the tag names.
-
-@vindex tags-tag-face
-@vindex tags-apropos-additional-actions
-You can customize the appearance of the output with the face
-@code{tags-tag-face}. You can display additional output with @kbd{M-x
-tags-apropos} by customizing the variable
-@code{tags-apropos-additional-actions}---see its documentation for
-details.
-
- You can also use the collection of tag names to complete a symbol
-name in the buffer. @xref{Symbol Completion}.
-
-@node Imenu
-@section Imenu
-@cindex indexes of buffer contents
-@cindex buffer content indexes
-@cindex tags
-
- The Imenu facility is another way to find definitions or sections
-in a file. It is similar in spirit to Tags, but operates on a single
-buffer only, and works entirely within Emacs with no need for a separate
-tags table.
-
-@findex imenu
-@findex imenu-add-menu-bar-index
- If you type @kbd{M-x imenu}, it reads the name of a section or
-definition in the current buffer, then goes to that section or
-definition. You can use completion to specify the name, and a
-complete list of possible names is always displayed.
-
- Alternatively you can bind the command @code{imenu} to a mouse
-click. Then it displays mouse menus for you to select the section or
-definition you want. You can also add the buffer's index to the menu
-bar by calling @code{imenu-add-menu-bar-index}. If you want to have
-this menu bar item available for all buffers in a certain major mode,
-you can do this by adding @code{imenu-add-menu-bar-index} to its mode
-hook. But then you will have to wait for the buffer to be searched
-for sections and definitions, each time you visit a file which uses
-that mode.
-
-@vindex imenu-auto-rescan
- When you change the contents of a buffer, if you add or delete
-definitions or sections, you can update the buffer's index to
-correspond to the new contents by invoking the @samp{*Rescan*} item in
-the menu. Rescanning happens automatically if
-@code{imenu-auto-rescan} is non-@code{nil}. There is no need to
-rescan because of small changes in the text.
-
-@vindex imenu-sort-function
- You can customize the way the menus are sorted via the variable
-@code{imenu-sort-function}. By default names are ordered as they
-occur in the buffer; alphabetic sorting is provided as an alternative.
-
- Imenu provides the information to guide Which Function mode
-(@pxref{Which Function}). The Speedbar can also use it
-(@pxref{Speedbar}).
-
-@node Emerge, C Modes, Imenu, Programs
-@section Merging Files with Emerge
-@cindex Emerge
-@cindex merging files
-
-It's not unusual for programmers to get their signals crossed and modify
-the same program in two different directions. To recover from this
-confusion, you need to merge the two versions. Emerge makes this
-easier. See also @ref{Comparing Files}, for commands to compare
-in a more manual fashion, and @ref{,Ediff,, ediff, The Ediff Manual}.
-
-@menu
-* Overview of Emerge:: How to start Emerge. Basic concepts.
-* Submodes of Emerge:: Fast mode vs. Edit mode.
- Skip Prefers mode and Auto Advance mode.
-* State of Difference:: You do the merge by specifying state A or B
- for each difference.
-* Merge Commands:: Commands for selecting a difference,
- changing states of differences, etc.
-* Exiting Emerge:: What to do when you've finished the merge.
-* Combining in Emerge:: How to keep both alternatives for a difference.
-* Fine Points of Emerge:: Misc.
-@end menu
-
-@node Overview of Emerge
-@subsection Overview of Emerge
-
-To start Emerge, run one of these four commands:
-
-@table @kbd
-@item M-x emerge-files
-@findex emerge-files
-Merge two specified files.
-
-@item M-x emerge-files-with-ancestor
-@findex emerge-files-with-ancestor
-Merge two specified files, with reference to a common ancestor.
-
-@item M-x emerge-buffers
-@findex emerge-buffers
-Merge two buffers.
-
-@item M-x emerge-buffers-with-ancestor
-@findex emerge-buffers-with-ancestor
-Merge two buffers with reference to a common ancestor in a third
-buffer.
-@end table
-
-@cindex merge buffer (Emerge)
-@cindex A and B buffers (Emerge)
- The Emerge commands compare two files or buffers, and display the
-comparison in three buffers: one for each input text (the @dfn{A buffer}
-and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
-takes place. The merge buffer shows the full merged text, not just the
-differences. Wherever the two input texts differ, you can choose which
-one of them to include in the merge buffer.
-
- The Emerge commands that take input from existing buffers use only the
-accessible portions of those buffers, if they are narrowed
-(@pxref{Narrowing}).
-
- If a common ancestor version is available, from which the two texts to
-be merged were both derived, Emerge can use it to guess which
-alternative is right. Wherever one current version agrees with the
-ancestor, Emerge presumes that the other current version is a deliberate
-change which should be kept in the merged version. Use the
-@samp{with-ancestor} commands if you want to specify a common ancestor
-text. These commands read three file or buffer names---variant A,
-variant B, and the common ancestor.
-
- After the comparison is done and the buffers are prepared, the
-interactive merging starts. You control the merging by typing special
-@dfn{merge commands} in the merge buffer. The merge buffer shows you a
-full merged text, not just differences. For each run of differences
-between the input texts, you can choose which one of them to keep, or
-edit them both together.
-
- The merge buffer uses a special major mode, Emerge mode, with commands
-for making these choices. But you can also edit the buffer with
-ordinary Emacs commands.
-
- At any given time, the attention of Emerge is focused on one
-particular difference, called the @dfn{selected} difference. This
-difference is marked off in the three buffers like this:
-
-@example
-vvvvvvvvvvvvvvvvvvvv
-@var{text that differs}
-^^^^^^^^^^^^^^^^^^^^
-@end example
-
-@noindent
-Emerge numbers all the differences sequentially and the mode
-line always shows the number of the selected difference.
-
- Normally, the merge buffer starts out with the A version of the text.
-But when the A version of a difference agrees with the common ancestor,
-then the B version is initially preferred for that difference.
-
- Emerge leaves the merged text in the merge buffer when you exit. At
-that point, you can save it in a file with @kbd{C-x C-w}. If you give a
-numeric argument to @code{emerge-files} or
-@code{emerge-files-with-ancestor}, it reads the name of the output file
-using the minibuffer. (This is the last file name those commands read.)
-Then exiting from Emerge saves the merged text in the output file.
-
- Normally, Emerge commands save the output buffer in its file when you
-exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
-save the output buffer, but you can save it yourself if you wish.
-
-@node Submodes of Emerge
-@subsection Submodes of Emerge
-
- You can choose between two modes for giving merge commands: Fast mode
-and Edit mode. In Fast mode, basic merge commands are single
-characters, but ordinary Emacs commands are disabled. This is
-convenient if you use only merge commands. In Edit mode, all merge
-commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
-commands are also available. This allows editing the merge buffer, but
-slows down Emerge operations.
-
- Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
-Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
-and @samp{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 @kbd{a} and @kbd{b} commands
-advance to the next difference. This lets you go through the merge
-faster as long as you simply choose one of the alternatives from the
-input. The mode line indicates Auto Advance mode with @samp{A}.
-
- If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
-skip over differences in states prefer-A and prefer-B (@pxref{State of
-Difference}). Thus you see only differences for which neither version
-is presumed ``correct.'' The mode line indicates Skip Prefers mode with
-@samp{S}.
-
-@findex emerge-auto-advance-mode
-@findex emerge-skip-prefers-mode
- Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
-clear Auto Advance mode. Use @kbd{s s}
-(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
-These commands turn on the mode with a positive argument, turns it off
-with a negative or zero argument, and toggle the mode with no argument.
-
-@node State of Difference
-@subsection State of a Difference
-
- In the merge buffer, a difference is marked with lines of @samp{v} and
-@samp{^} characters. Each difference has one of these seven states:
-
-@table @asis
-@item A
-The difference is showing the A version. The @kbd{a} command always
-produces this state; the mode line indicates it with @samp{A}.
-
-@item B
-The difference is showing the B version. The @kbd{b} command always
-produces this state; the mode line indicates it with @samp{B}.
-
-@item default-A
-@itemx 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 @kbd{d a} chooses default-A as the default state, and @kbd{d
-b} chooses default-B. This chosen default applies to all differences
-which you haven't ever selected and for which no alternative is preferred.
-If you are moving through the merge sequentially, the differences you
-haven't selected are those following the selected one. Thus, while
-moving sequentially, you can effectively make the A version the default
-for some sections of the merge buffer and the B version the default for
-others by using @kbd{d a} and @kbd{d b} between sections.
-
-@item prefer-A
-@itemx prefer-B
-The difference is showing the A or B state because it is
-@dfn{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 @samp{A*} and @samp{B*}.
-
-@item combined
-The difference is showing a combination of the A and B states, as a
-result of the @kbd{x c} or @kbd{x C} commands.
-
-Once a difference is in this state, the @kbd{a} and @kbd{b} commands
-don't do anything to it unless you give them a numeric argument.
-
-The mode line displays this state as @samp{comb}.
-@end table
-
-@node Merge Commands
-@subsection Merge Commands
-
- Here are the Merge commands for Fast mode; in Edit mode, precede them
-with @kbd{C-c C-c}:
-
-@table @kbd
-@item p
-Select the previous difference.
-
-@item n
-Select the next difference.