Mercurial > emacs
diff man/maintaining.texi @ 38198:1381135c49a4
Initial version consists of sections moved from Editing Programs chapter.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Tue, 26 Jun 2001 13:12:29 +0000 |
parents | |
children | 5ef494421061 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/maintaining.texi Tue Jun 26 13:12:29 2001 +0000 @@ -0,0 +1,1216 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Maintaining, Abbrevs, Building, Top +@chapter Maintaining Programs +@cindex Lisp editing +@cindex C editing +@cindex program editing + + This chapter describes Emacs features for maintaining programs. The +version control features,described in the chapter on files +(@pxref{Version Control}), are also useful particularly for this +purpose. + +@menu +* Change Log:: Maintaining a change history for your program. +* Authors:: Maintaining an @file{AUTHORS} file. +* Tags:: Go direct to any function in your program in one + command. Tags remembers which file it is in. +* Emerge:: A convenient way of merging two versions of a program. +@end menu + +@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 the +current date, your name, and your email address (taken from the +variable @code{user-mail-address}). 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} adds 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 balanced +expression in the buffer before or around point is used as the +@var{tag} argument. @xref{Expressions}. + + 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 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. + +@item a +Choose the A version of this difference. + +@item b +Choose the B version of this difference. + +@item C-u @var{n} j +Select difference number @var{n}. + +@item . +Select the difference containing point. You can use this command in the +merge buffer or in the A or B buffer. + +@item q +Quit---finish the merge. + +@item C-] +Abort---exit merging and do not save the output. + +@item f +Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) + +@item e +Go into Edit mode. + +@item l +Recenter (like @kbd{C-l}) all three windows. + +@item - +Specify part of a prefix numeric argument. + +@item @var{digit} +Also specify part of a prefix numeric argument. + +@item d a +Choose the A version as the default from here down in +the merge buffer. + +@item d b +Choose the B version as the default from here down in +the merge buffer. + +@item c a +Copy the A version of this difference into the kill ring. + +@item c b +Copy the B version of this difference into the kill ring. + +@item i a +Insert the A version of this difference at point. + +@item i b +Insert the B version of this difference at point. + +@item m +Put point and mark around the difference. + +@item ^ +Scroll all three windows down (like @kbd{M-v}). + +@item v +Scroll all three windows up (like @kbd{C-v}). + +@item < +Scroll all three windows left (like @kbd{C-x <}). + +@item > +Scroll all three windows right (like @kbd{C-x >}). + +@item | +Reset horizontal scroll on all three windows. + +@item x 1 +Shrink the merge window to one line. (Use @kbd{C-u l} to restore it +to full size.) + +@item x c +Combine the two versions of this difference (@pxref{Combining in +Emerge}). + +@item x f +Show the names of the files/buffers Emerge is operating on, in a Help +window. (Use @kbd{C-u l} to restore windows.) + +@item x j +Join this difference with the following one. +(@kbd{C-u x j} joins this difference with the previous one.) + +@item x s +Split this difference into two differences. Before you use this +command, position point in each of the three buffers at the place where +you want to split the difference. + +@item x t +Trim identical lines off the top and bottom of the difference. +Such lines occur when the A and B versions are +identical but differ from the ancestor version. +@end table + +@node Exiting Emerge +@subsection Exiting Emerge + + The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing +the results into the output file if you specified one. It restores the +A and B buffers to their proper contents, or kills them if they were +created by Emerge and you haven't changed them. It also disables the +Emerge commands in the merge buffer, since executing them later could +damage the contents of the various buffers. + + @kbd{C-]} aborts the merge. This means exiting without writing the +output file. If you didn't specify an output file, then there is no +real difference between aborting and finishing the merge. + + If the Emerge command was called from another Lisp program, then its +return value is @code{t} for successful completion, or @code{nil} if you +abort. + +@node Combining in Emerge +@subsection Combining the Two Versions + + Sometimes you want to keep @emph{both} alternatives for a particular +difference. To do this, use @kbd{x c}, which edits the merge buffer +like this: + +@example +@group +#ifdef NEW +@var{version from A buffer} +#else /* not NEW */ +@var{version from B buffer} +#endif /* not NEW */ +@end group +@end example + +@noindent +@vindex emerge-combine-versions-template +While this example shows C preprocessor conditionals delimiting the two +alternative versions, you can specify the strings to use by setting +the variable @code{emerge-combine-versions-template} to a string of your +choice. In the string, @samp{%a} says where to put version A, and +@samp{%b} says where to put version B. The default setting, which +produces the results shown above, looks like this: + +@example +@group +"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" +@end group +@end example + +@node Fine Points of Emerge +@subsection Fine Points of Emerge + + During the merge, you mustn't try to edit the A and B buffers yourself. +Emerge modifies them temporarily, but ultimately puts them back the way +they were. + + You can have any number of merges going at once---just don't use any one +buffer as input to more than one merge at once, since the temporary +changes made in these buffers would get in each other's way. + + Starting Emerge can take a long time because it needs to compare the +files fully. Emacs can't do anything else until @code{diff} finishes. +Perhaps in the future someone will change Emerge to do the comparison in +the background when the input files are large---then you could keep on +doing other things with Emacs until Emerge is ready to accept +commands. + +@vindex emerge-startup-hook + After setting up the merge, Emerge runs the hook +@code{emerge-startup-hook} (@pxref{Hooks}). +