@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 Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
+@c 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Maintaining, Abbrevs, Building, Top
@chapter Maintaining Programs
@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.
+version control features (@pxref{Version Control}) are also particularly
+useful 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.
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:
+ You should put a copyright notice and permission notice at the
+end of the change log file. Here is an example:
+
+@example
+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.
+@end example
+
+@noindent
+Of course, you should substitute the proper years and copyright holder.
+
+ 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{add-log-mailing-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, with two items and one item respectively.
@iftex
@medbreak
@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.
+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.
@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
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.
+ When the variable @code{add-log-keep-changes-together} is
+non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
+rather than starting a new item.
@vindex change-log-version-info-enabled
@vindex change-log-version-number-regexp-list
ten percent of the file, using regular expressions from the variable
@code{change-log-version-number-regexp-list}.
+@vindex add-log-always-start-new-record
+ If @code{add-log-always-start-new-record} is non-@code{nil},
+@kbd{C-x 4 a} always makes a new entry, even if the last entry
+was made by you and on the same date.
+
@cindex Change Log mode
@findex change-log-mode
The change log file is visited in Change Log mode. In this major
Version control systems are another way to keep track of changes in your
program and keep a change log. @xref{Log Buffer}.
+@ignore
+@c This is commented out because the command is specific
+@c to maintenance of Emacs itself.
+
@node Authors
@section @file{AUTHORS} files
@cindex @file{AUTHORS} file
@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
+Emacs source directory. It then scans @file{ChangeLog} files and Lisp
source files under that directory for information about authors of
-individual packages and people who made changes in source files, and
+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
existing @file{AUTHORS} file.
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.
+@end ignore
@node Tags
@section Tags Tables
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.
+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
You can tag function declarations and external variables in addition
to function definitions by giving the @samp{--declarations} option to
-@code{etags}.
+@code{etags}. You can tag struct members with the @samp{--members}
+option.
@item
In C++ code, in addition to all the tag constructs of C code, member
@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
+@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
+@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
+@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
+@code{\newenvironment} or @code{\renewenvironment} 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
command names. For example,
@example
-TEXTAGS="def:newcommand:newenvironment"
+TEXTAGS="mycommand:myothercommand"
export TEXTAGS
@end example
@noindent
-specifies (using Bourne shell syntax) that the commands @samp{\def},
-@samp{\newcommand} and @samp{\newenvironment} also define tags.
+specifies (using Bourne shell syntax) that the commands
+@samp{\mycommand} and @samp{\myothercommand} 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
+argument of any expression that starts with @samp{(def} in column zero is
a tag.
@item
@itemize @bullet
@item
-In Ada code, functions, procedures, packages, tasks, and types are
+In Ada code, functions, procedures, packages, tasks and types are
tags. Use the @samp{--packages-only} option to create tags for
packages only.
column 8 and followed by a period.
@item
-In Erlang code, the tags are the functions, records, and macros defined
+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.
+In Fortran code, functions, subroutines and block data are tags.
+
+@item
+In HTML input files, the tags are the @code{title} and the @code{h1},
+@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
+and all occurrences of @code{id=}.
+
+@item
+In Lua input files, all functions are tags.
@item
-In makefiles, targets are tags.
+In makefiles, targets are tags; additionally, variables are tags
+unless you specify @samp{--no-globals}.
@item
In Objective C code, tags include Objective C definitions for classes,
-class categories, methods, and protocols.
+class categories, methods and protocols. Tags for variables and
+functions in classes are named @samp{@var{class}::@var{variable}} and
+@samp{@var{class}::@var{function}}.
@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.
+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 @samp{@var{package}::@var{sub}}. The
+name for subroutines defined in the default package is
+@samp{main::@var{sub}}.
+
+@item
+In PHP code, tags are functions, classes and defines. When using the
+@samp{--members} option, vars are tags too.
@item
In PostScript code, the tags are the functions.
@item
-In Prolog code, a tag name appears at the left margin.
+In Prolog code, tags are predicates and rules at the beginning of
+line.
@item
In Python code, @code{def} or @code{class} at the beginning of a line
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
+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
-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.
+other editing), the only 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. Even that
+delay is hardly noticeable with today's computers.
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,
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.
+files. If the tags file is in @file{/dev}, however, the file names are
+made relative to the current working directory.
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
entirely; then @code{etags} recognizes tags by regexp matching alone
(@pxref{Etags Regexps}).
+ The option @samp{--parse-stdin=@var{file}} 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
+@var{file}.
+
@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.
+explanation. If followed by one or more @samp{--language=@var{lang}}
+options, prints detailed information about how tags are generated for
+@var{lang}.
@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:
+If you specify multiple @samp{--regex} options, all of them are used
+in parallel, but each one applies only to the source files that follow
+it. The syntax is:
@smallexample
---regex=/@var{tagregexp}[/@var{nameregexp}]/
+--regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
@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
+ 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:
+
+@table @samp
+@item i
+Ignore case when matching this regexp.
+@item m
+Match this regular expression against the whole file, so that
+multi-line matches are possible.
+@item s
+Match this regular expression against the whole file, and allow
+@samp{.} in @var{tagregexp} to match newlines.
+@end table
+
+ The @samp{-R} option cancels all the regexps defined by preceding
@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}/ \
+etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
bar.ber -R --lang=lisp los.er
@end smallexample
@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
+@file{bar.ber}. @var{reg1} is checked against each line of
+@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
+@var{reg2} 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 @var{@{language@}}.
+(@samp{etags --help} prints the list of languages recognized by
+@code{etags}.) 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:
@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.
+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.
@smallexample
---regex=@@first-file --ignore-case-regex=@@second-file
+--regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-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
+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:
@smallexample
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}.
+@xref{Grep Searching}.
@node List Tags
@subsection Tags Table Inquiries
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}.
+in a more manual fashion, and @ref{Top, Ediff,, ediff, The Ediff Manual}.
@menu
* Overview of Emerge:: How to start Emerge. Basic concepts.
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.
+@dfn{merge commands} in the merge buffer (@pxref{Merge Commands}).
+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
After setting up the merge, Emerge runs the hook
@code{emerge-startup-hook} (@pxref{Hooks}).
+@ignore
+ arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb
+@end ignore