@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.
+ 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{user-mail-address}). Aside from these header lines,
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
-exisiting @file{AUTHORS} file.
+existing @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.
+@end ignore
@node Tags
@section Tags Tables
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 makefiles, targets are tags.
@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,
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.
+Emacs. However, non-greedy operators and shy groups are not
+available.
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
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
+--help} prints the list of languages recognized by @code{etags}.) The
following example tags the @code{DEFVAR} macros in the Emacs source
files, for the C language only:
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.
@vindex emerge-startup-hook
After setting up the merge, Emerge runs the hook
@code{emerge-startup-hook} (@pxref{Hooks}).
-