[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to maintaining.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to maintaining.texi |
|
Date: |
Thu, 06 Sep 2007 04:47:09 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:47:09
Index: maintaining.texi
===================================================================
RCS file: maintaining.texi
diff -N maintaining.texi
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ maintaining.texi 6 Sep 2007 04:47:09 -0000 1.1
@@ -0,0 +1,862 @@
address@hidden This is part of the Emacs manual.
address@hidden Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999,
2000,
address@hidden 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software
Foundation, Inc.
address@hidden See file emacs.texi for copying conditions.
address@hidden Maintaining, Abbrevs, Building, Top
address@hidden Maintaining Large Programs
+
+ This chapter describes Emacs features for maintaining large
+programs. The version control features (@pxref{Version Control}) are
+also particularly useful for this purpose.
+
address@hidden
+* Change Log:: Maintaining a change history for your program.
+* Format of ChangeLog:: What the change log file looks like.
+* Tags:: Go direct to any function in your program in one
+ command. Tags remembers which file it is in.
address@hidden
+* Emerge:: A convenient way of merging two versions of a program.
address@hidden ifnottex
address@hidden menu
+
address@hidden Change Log
address@hidden Change Logs
+
+ 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
address@hidden 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.
+
address@hidden change log
address@hidden C-x 4 a
address@hidden 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.
+
+ @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.
+
address@hidden add-log-keep-changes-together
+ When the variable @code{add-log-keep-changes-together} is
address@hidden, @kbd{C-x 4 a} adds to any existing item for the file
+rather than starting a new item.
+
address@hidden add-log-always-start-new-record
+ If @code{add-log-always-start-new-record} is address@hidden,
address@hidden 4 a} always makes a new entry, even if the last entry
+was made by you and on the same date.
+
address@hidden change-log-version-info-enabled
address@hidden change-log-version-number-regexp-list
address@hidden file version in change log entries
+ If the value of the variable @code{change-log-version-info-enabled}
+is address@hidden, @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
address@hidden
+
address@hidden Change Log mode
address@hidden 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.
address@hidden and auto-fill indent each new line like the previous line;
+this is convenient for entering the contents of an entry.
+
address@hidden 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.
+
+ Version control systems are another way to keep track of changes in your
+program and keep a change log. @xref{Log Buffer}.
+
address@hidden Format of ChangeLog
address@hidden Format of ChangeLog
+
+ A change log entry starts with a header line that contains the current
+date, your name, and your email address (taken from the variable
address@hidden). 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, with two items and one item respectively.
+
address@hidden
address@hidden
address@hidden iftex
address@hidden
+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.
address@hidden smallexample
+
+ One entry can describe several changes; each change should have its
+own item, or its own line in an 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.
+
+ You should put a copyright notice and permission notice at the
+end of the change log file. Here is an example:
+
address@hidden
+Copyright 1997, 1998 Free Software Foundation, Inc.
+Copying and distribution of this file, with or without modification, are
+permitted provided the copyright notice and this notice are preserved.
address@hidden smallexample
+
address@hidden
+Of course, you should substitute the proper years and copyright holder.
+
address@hidden Tags
address@hidden Tags Tables
address@hidden 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. When a file parsed by @code{etags} is
+generated from a different source file, like a C file generated from a
+Cweb source file, the tags of the parsed file reference the source
+file.
+
+ 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}.
+
address@hidden C++ class browser, tags
address@hidden tags, C++
address@hidden class browser, C++
address@hidden Ebrowse
+ See also the Ebrowse facility, which is tailored for C++.
address@hidden,, Ebrowse, ebrowse, Ebrowse User's Manual}.
+
address@hidden
+* 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.
address@hidden menu
+
address@hidden Tag Syntax
address@hidden Source File Tag Syntax
+
+ Here is how tag syntax is defined for the most popular languages:
+
address@hidden @bullet
address@hidden
+In C code, any C function or typedef is a tag, and so are definitions of
address@hidden, @code{union} and @code{enum}.
address@hidden macro definitions, @code{#undef} 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
address@hidden, and so are struct members, unless you specify
address@hidden Use of @samp{--no-globals}, @samp{--no-defines}
+and @samp{--no-members} 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
address@hidden
+
address@hidden
+In C++ code, in addition to all the tag constructs of C code, member
+functions are also recognized; member variables are also recognized,
+unless you use the @samp{--no-members} option. Tags for variables and
+functions in classes are named @address@hidden::@var{variable}} and
address@hidden@var{class}::@var{function}}. @code{operator} definitions have
+tag names like @samp{operator+}.
+
address@hidden
+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
address@hidden@address@hidden and @address@hidden@var{function}}.
+
address@hidden
+In address@hidden text, the argument of any of the commands @code{\chapter},
address@hidden, @code{\subsection}, @code{\subsubsection},
address@hidden, @code{\label}, @code{\ref}, @code{\cite},
address@hidden, @code{\part}, @code{\appendix}, @code{\entry},
address@hidden, @code{\def}, @code{\newcommand}, @code{\renewcommand},
address@hidden or @code{\renewenvironment} is a address@hidden
+
+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,
+
address@hidden
+TEXTAGS="mycommand:myothercommand"
+export TEXTAGS
address@hidden example
+
address@hidden
+specifies (using Bourne shell syntax) that the commands
address@hidden and @samp{\myothercommand} also define tags.
+
address@hidden
+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.
+
address@hidden
+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.
address@hidden itemize
+
+ Several other languages are also supported:
+
address@hidden @bullet
+
address@hidden
+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:
+
address@hidden @samp
address@hidden /b
+package body.
address@hidden /f
+function.
address@hidden /k
+task.
address@hidden /p
+procedure.
address@hidden /s
+package spec.
address@hidden /t
+type.
address@hidden 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
address@hidden
+
address@hidden
+In assembler code, labels appearing at the beginning of a line,
+followed by a colon, are tags.
+
address@hidden
+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.
+
address@hidden
+In Cobol code, tags are paragraph names; that is, any word starting in
+column 8 and followed by a period.
+
address@hidden
+In Erlang code, the tags are the functions, records and macros defined
+in the file.
+
address@hidden
+In Fortran code, functions, subroutines and block data are tags.
+
address@hidden
+In HTML input files, the tags are the @code{title} and the @code{h1},
address@hidden, @code{h3} headers. Also, tags are @code{name=} in anchors
+and all occurrences of @code{id=}.
+
address@hidden
+In Lua input files, all functions are tags.
+
address@hidden
+In makefiles, targets are tags; additionally, variables are tags
+unless you specify @samp{--no-globals}.
+
address@hidden
+In Objective C code, tags include Objective C definitions for classes,
+class categories, methods and protocols. Tags for variables and
+functions in classes are named @address@hidden::@var{variable}} and
address@hidden@var{class}::@var{function}}.
+
address@hidden
+In Pascal code, the tags are the functions and procedures defined in
+the file.
+
address@hidden
+In Perl code, the tags are the packages, subroutines and variables
+defined by the @code{package}, @code{sub}, @code{my} and @code{local}
+keywords. Use @samp{--globals} if you want to tag global variables.
+Tags for subroutines are named @address@hidden::@var{sub}}. The
+name for subroutines defined in the default package is
address@hidden::@var{sub}}.
+
address@hidden
+In PHP code, tags are functions, classes and defines. Vars are tags
+too, unless you use the @samp{--no-members} option.
+
address@hidden
+In PostScript code, the tags are the functions.
+
address@hidden
+In Prolog code, tags are predicates and rules at the beginning of
+line.
+
address@hidden
+In Python code, @code{def} or @code{class} at the beginning of a line
+generate a tag.
address@hidden itemize
+
+ You can also generate tags based on regexp matching (@pxref{Etags
+Regexps}) to handle other formats and languages.
+
address@hidden Create Tags Table
address@hidden Creating Tags Tables
address@hidden @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
address@hidden
+the previous section.
address@hidden iftex
address@hidden
address@hidden Syntax}.
address@hidden ifnottex
+Here is how to run @code{etags}:
+
address@hidden
+etags @address@hidden
address@hidden example
+
address@hidden
+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
address@hidden@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. If the tags table fails to record
+a tag, or records it for the wrong file, then Emacs cannot possibly
+find its definition until you update the tags table. However, if the
+position recorded in the tags table becomes a little bit wrong (due to
+other editing), the worst consequence is a slight delay in finding the
+tag. Even if the stored position is very far wrong, Emacs will still
+find the tag, after searching most of the file for it. That delay is
+hardly noticeable with today's computers.
+
+ Thus, there is no need to update the tags table after each edit.
+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.
+
+ One tags table can virtually include another. Specify the included
+tags file name with the @address@hidden 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
address@hidden, 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 the tags file is in @file{/dev}, however, the file names are
+made relative to the current working directory. This is useful, for
+example, when writing the tags to @file{/dev/stdout}.
+
+ When using a relative file name, it should not be a symbolic link
+pointing to a tags file in a different directory, because this would
+generally render the file names invalid.
+
+ 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
address@hidden/}, or with @address@hidden:/} 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:
+
address@hidden
+find . -name "*.[chCH]" -print | etags -
address@hidden smallexample
+
+ Use the option @address@hidden to specify the language
+explicitly. You can intermix these options with file names; each one
+applies to the file names that follow it. Specify
address@hidden to tell @code{etags} to resume guessing the
+language from the file names and file contents. Specify
address@hidden to turn off language-specific processing
+entirely; then @code{etags} recognizes tags by regexp matching alone
+(@pxref{Etags Regexps}).
+
+ The option @address@hidden is mostly useful when
+calling @code{etags} from programs. It can be used (only once) in
+place of a file name on the command line. @code{Etags} will read from
+standard input and mark the produced tags as belonging to the file
address@hidden
+
+ @samp{etags --help} outputs 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. If followed by one or more @address@hidden
+options, it outputs detailed information about how tags are generated for
address@hidden
+
address@hidden Etags Regexps
address@hidden Etags Regexps
+
+ The @samp{--regex} option provides a general way of recognizing tags
+based on regexp matching. You can freely intermix this option with
+file names, and each one applies to the source files that follow it.
+If you specify multiple @samp{--regex} options, all of them are used
+in parallel. The syntax is:
+
address@hidden
address@hidden@address@hidden/@var{tagregexp}/address@hidden/address@hidden
address@hidden smallexample
+
+ The essential part of the option value is @var{tagregexp}, the
+regexp for matching tags. It is always used anchored, that is, it
+only matches at the beginning of a line. If you want to allow
+indented tags, use a regexp that matches initial whitespace; start it
+with @samp{[ \t]*}.
+
+ In these regular expressions, @samp{\} quotes the next character, and
+all the GCC character escape sequences are supported (@samp{\a} for
+bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
+escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
+carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
+
+ Ideally, @var{tagregexp} should not match more characters than are
+needed to recognize what you want to tag. If the syntax requires you
+to write @var{tagregexp} so it matches more characters beyond the tag
+itself, 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 @var{modifiers} are a sequence of zero or more characters that
+modify the way @code{etags} does the matching. A regexp with no
+modifiers is applied sequentially to each line of the input file, in a
+case-sensitive way. The modifiers and their meanings are:
+
address@hidden @samp
address@hidden i
+Ignore case when matching this regexp.
address@hidden m
+Match this regular expression against the whole file, so that
+multi-line matches are possible.
address@hidden s
+Match this regular expression against the whole file, and allow
address@hidden in @var{tagregexp} to match newlines.
address@hidden table
+
+ The @samp{-R} option cancels all the regexps defined by preceding
address@hidden options. It too applies to the file names following
+it. Here's an example:
+
address@hidden
+etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
+ bar.ber -R --lang=lisp los.er
address@hidden smallexample
+
address@hidden
+Here @code{etags} chooses the parsing language for @file{voo.doo} and
address@hidden according to their contents. @code{etags} also uses
address@hidden to recognize additional tags in @file{voo.doo}, and both
address@hidden and @var{reg2} to recognize additional tags in
address@hidden @var{reg1} is checked against each line of
address@hidden and @file{bar.ber}, in a case-insensitive way, while
address@hidden is checked against the whole @file{bar.ber} file,
+permitting multi-line matches, in a case-sensitive way. @code{etags}
+uses only the Lisp tags rules, with no user-specified regexp matching,
+to recognize tags in @file{los.er}.
+
+ You can restrict a @samp{--regex} option to match only files of a
+given language by using the optional prefix @address@hidden@}}.
+(@samp{etags --help} prints the list of languages recognized by
address@hidden) This is particularly useful when storing many
+predefined regular expressions for @code{etags} in a file. The
+following example tags the @code{DEFVAR} macros in the Emacs source
+files, for the C language only:
+
address@hidden
+--regex='@address@hidden/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
address@hidden smallexample
+
address@hidden
+When you have complex regular expressions, you can store the list of
+them 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.
+
address@hidden
+--regex=@@@var{case-sensitive-file}
--ignore-case-regex=@@@var{ignore-case-file}
address@hidden smallexample
+
address@hidden
+A regex file for @code{etags} contains one regular expression 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 another 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, we can create a file called @samp{emacs.tags} with the
+following contents:
+
address@hidden
+ -- This is for GNU Emacs C source files
address@hidden@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
address@hidden smallexample
+
address@hidden
+and then use it like this:
+
address@hidden
+etags --regex=@@emacs.tags *.[ch] */*.[ch]
address@hidden smallexample
+
+ Here are some more examples. The regexps are quoted to protect them
+from shell interpretation.
+
address@hidden @bullet
+
address@hidden
+Tag Octave files:
+
address@hidden
+etags --language=none \
+ --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
+ --regex='/###key \(.*\)/\1/' \
+ --regex='/[ \t]*global[ \t].*/' \
+ *.m
address@hidden smallexample
+
address@hidden
+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.
+
address@hidden
+Tag Tcl files:
+
address@hidden
+etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
address@hidden smallexample
+
address@hidden
+Tag VHDL files:
+
address@hidden
+etags --language=none \
+ --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
+ --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
+ \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
address@hidden smallexample
address@hidden itemize
+
address@hidden Select Tags Table
address@hidden Selecting a Tags Table
+
address@hidden tags-file-name
address@hidden 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, with @file{TAGS} in the default
+directory as the default.
+
+ Emacs does not actually read in the tags table contents until you
+try to use them; all @code{visit-tags-table} does is store the file
+name in the variable @code{tags-file-name}, and setting the variable
+yourself is just as good. 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.
+
address@hidden tags-table-list
+ You can specify a precise list of tags tables by setting the variable
address@hidden to a list of strings, like this:
+
address@hidden keep this on two lines for formatting in smallbook
address@hidden
address@hidden
+(setq tags-table-list
+ '("~/emacs" "/usr/local/lib/emacs/src"))
address@hidden group
address@hidden example
+
address@hidden
+This tells the tags commands to look at the @file{TAGS} files in your
address@hidden/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}.
+
address@hidden Find Tag
address@hidden Finding a Tag
+
+ The most important thing that a tags table enables you to do is to find
+the definition of a specific tag.
+
address@hidden @kbd
address@hidden M-.@: @var{tag} @key{RET}
+Find first definition of @var{tag} (@code{find-tag}).
address@hidden C-u M-.
+Find next alternate definition of last tag specified.
address@hidden C-u - M-.
+Go back to previous tag found.
address@hidden C-M-. @var{pattern} @key{RET}
+Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
address@hidden C-u C-M-.
+Find the next tag whose name matches the last pattern used.
address@hidden C-x 4 .@: @var{tag} @key{RET}
+Find first definition of @var{tag}, but display it in another window
+(@code{find-tag-other-window}).
address@hidden 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}).
address@hidden M-*
+Pop back to where you previously invoked @kbd{M-.} and friends.
address@hidden table
+
address@hidden M-.
address@hidden 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
address@hidden 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-.}.
+
address@hidden C-x 4 .
address@hidden find-tag-other-window
address@hidden C-x 5 .
address@hidden 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 @address@hidden 4 .}}, which invokes
+the command @code{find-tag-other-window}. The latter is @address@hidden 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. @address@hidden 4 .}} with a negative
+argument finds the previous tag location in another window.
+
address@hidden M-*
address@hidden pop-tag-mark
address@hidden 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}.
+
address@hidden find-tag-regexp
address@hidden 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.
+
address@hidden Tags Search
address@hidden Searching and Replacing with Tags Tables
address@hidden search and replace in multiple files
address@hidden 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. These
+commands scan the list of tags tables starting 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.
+
address@hidden @kbd
address@hidden M-x tags-search @key{RET} @var{regexp} @key{RET}
+Search for @var{regexp} through the files in the selected tags
+table.
address@hidden 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.
address@hidden M-,
+Restart one of the commands above, from the current location of point
+(@code{tags-loop-continue}).
address@hidden table
+
address@hidden 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,
address@hidden returns.
+
address@hidden M-,
address@hidden 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
address@hidden This searches the rest of the current buffer, followed
+by the remaining files of the tags address@hidden
+
address@hidden tags-query-replace
+ @kbd{M-x tags-query-replace} performs a single
address@hidden 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.
+
address@hidden tags-case-fold-search
address@hidden 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
address@hidden (@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
address@hidden family. The @code{find-tag} commands search only for
+definitions of tags that match your substring or regexp. The commands
address@hidden 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
address@hidden You can also run @code{grep} itself as an inferior of
+Emacs and have Emacs show you the matching lines one by one.
address@hidden Searching}.
+
address@hidden List Tags
address@hidden Tags Table Inquiries
+
address@hidden @kbd
address@hidden M-x list-tags @key{RET} @var{file} @key{RET}
+Display a list of the tags defined in the program file @var{file}.
address@hidden M-x tags-apropos @key{RET} @var{regexp} @key{RET}
+Display a list of all tags matching @var{regexp}.
address@hidden table
+
address@hidden 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.
+
address@hidden tags-apropos
address@hidden 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
address@hidden is address@hidden, it displays the names
+of the tags files together with the tag names.
+
address@hidden tags-tag-face
address@hidden tags-apropos-additional-actions
+ You can customize the appearance of the output by setting the
+variable @code{tags-tag-face} to a face. You can display additional
+output with @kbd{M-x tags-apropos} by customizing the variable
address@hidden its documentation for
+details.
+
+ You can also use the collection of tag names to complete a symbol
+name in the buffer. @xref{Symbol Completion}.
+
address@hidden
address@hidden emerge-xtra.texi
address@hidden ifnottex
+
address@hidden
+ arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb
address@hidden ignore