@menu
* 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.
* Emerge:: A convenient way of merging two versions of a program.
@node Change Log
@section 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
+@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.
+
@cindex change log
@kindex C-x 4 a
@findex add-change-log-entry-other-window
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.
-
- 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 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, 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
also creates a new item for the current file. For many languages, it
non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
rather than starting a new item.
+@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.
+
@vindex change-log-version-info-enabled
@vindex change-log-version-number-regexp-list
@cindex file version in change log entries
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
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:
+ Version control systems are another way to keep track of changes in your
+program and keep a change log. @xref{Log Buffer}.
+
+@node Format of ChangeLog
+@section 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
+@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 iftex
@smallexample
-Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>
+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
-@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.
+ 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.
- Version control systems are another way to keep track of changes in your
-program and keep a change log. @xref{Log Buffer}.
+ You should put a copyright notice and permission notice at the
+end of the change log file. Here is an example:
-@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
-
- 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{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
-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.
-
- 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
+@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.
@node Tags
@section Tags Tables
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 only consequence is a slight delay in finding the
+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. Even that
-delay is hardly noticeable with today's computers.
+find the tag, after searching most of the file for it. 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,
-or when changes become substantial. Normally there is no need to update
-the tags table after each edit, or even every day.
+ 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 @samp{--include=@var{file}} option when
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}
+ @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 @samp{--language=@var{lang}}
-options, prints detailed information about how tags are generated for
+options, it outputs 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.
+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, but each one applies only to the source files that follow
-it. The syntax is:
+in parallel. The syntax is:
@smallexample
--regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
@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:
+@samp{--regex} options. It too applies to the file names following
+it. Here's an example:
@smallexample
etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
@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.
+ 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. 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.
+current list, it is used @emph{as well as} the others.
@vindex tags-table-list
You can specify a precise list of tags tables by setting the variable
@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 .},
+makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes
+the command @code{find-tag-other-window}. The latter is @w{@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
+command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative
argument finds the previous tag location in another window.
@kindex M-*
@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.
+ 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.
@table @kbd
@item M-x tags-search @key{RET} @var{regexp} @key{RET}
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.
+Emacs and have Emacs show you the matching lines one by one.
@xref{Grep Searching}.
@node List Tags
@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
+ 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
@code{tags-apropos-additional-actions}---see its documentation for
details.
@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{Top, Ediff,, ediff, The Ediff Manual}.
+ 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 other ways to compare
+files, and @ref{Top, Ediff,, ediff, The Ediff Manual}.
@menu
* Overview of Emerge:: How to start Emerge. Basic concepts.
@node Overview of Emerge
@subsection Overview of Emerge
-To start Emerge, run one of these four commands:
+ To start Emerge, run one of these four commands:
@table @kbd
@item M-x emerge-files
projects / emacs.git / commitdiff