comparison man/maintaining.texi @ 68693:f06d0aec15a7

(Format of ChangeLog): New node, split out from ChangeLog. (ChangeLog): Clarifications in the remaining text. (Create Tags Table, Etags Regexps, Select Tags Table): Cleanups. (Find Tag): Add @w. (Tags Search): Explain tag table order here. Simplify grep ref. (List Tags): tags-tag-face is a variable, not a face. (Emerge): Cleanups.

68692:06780217e0ec

version control features (@pxref{Version Control}) are also particularly
useful for this purpose.

@menu
* Change Log::	        Maintaining a change history for your program.
* 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

(@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.

  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
can even guess the name of the function or other object that was
changed.

@vindex add-log-keep-changes-together
  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
@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}.

@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
mode, each bunch of grouped items counts as one paragraph, and each
entry is considered a page.  This facilitates editing the entries.

@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}.

@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

@node Tags
@section Tags Tables
@cindex tags table

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 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,
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

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.  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.
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{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
@end smallexample

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}/i voo.doo --regex=/@var{reg2}/m \
    bar.ber -R --lang=lisp los.er
@end smallexample

@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:

@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

@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.

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{Grep Searching}.

@node List Tags
@subsection Tags Table Inquiries

@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
@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{Top, 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.

@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.

68693:f06d0aec15a7

version control features (@pxref{Version Control}) are also particularly
useful for this purpose.

@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.
@end menu

@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
  The Emacs command @kbd{C-x 4 a} adds a new entry to the change log

(@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.

@vindex add-log-keep-changes-together
  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 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
  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.

@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.

  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
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.

  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.

@node Tags
@section Tags Tables
@cindex tags table

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 @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

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} 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, 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 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:

@smallexample
--regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
@end smallexample

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 too applies to the file names following
it.  Here's an example:

@smallexample
etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
    bar.ber -R --lang=lisp los.er
@end smallexample

@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, 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.

@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:

@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 @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.  @w{@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

@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.  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}
Search for @var{regexp} through the files in the selected tags
table.

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.
@xref{Grep Searching}.

@node List Tags
@subsection Tags Table Inquiries

@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 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.

  You can also use the collection of tag names to complete a symbol
name in the buffer.  @xref{Symbol Completion}.

@node Emerge
@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 other ways to compare
files, and @ref{Top, 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.

@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.