[Emacs-diffs] Changes to emacs/man/maintaining.texi

[Richard M. Stallman]

Index: emacs/man/maintaining.texi
diff -u emacs/man/maintaining.texi:1.39 emacs/man/maintaining.texi:1.40
--- emacs/man/maintaining.texi:1.39     Sun Feb  5 22:41:31 2006
+++ emacs/man/maintaining.texi  Wed Feb  8 00:00:22 2006
@@ -14,6 +14,7 @@
 
 @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.
@@ -22,6 +23,14 @@
 @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
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.
+
 @cindex change log
 @kindex C-x 4 a
 @findex add-change-log-entry-other-window
@@ -32,58 +41,6 @@
 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
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.
-
-  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 example
-
address@hidden
-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
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.
-
   @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
@@ -95,6 +52,11 @@
 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.
+
 @vindex change-log-version-info-enabled
 @vindex change-log-version-number-regexp-list
 @cindex file version in change log entries
@@ -104,11 +66,6 @@
 ten percent of the file, using regular expressions from the variable
 @code{change-log-version-number-regexp-list}.
 
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.
-
 @cindex Change Log mode
 @findex change-log-mode
   The change log file is visited in Change Log mode.  In this major
@@ -122,52 +79,55 @@
 log files into a buffer in Change Log Mode, preserving the date
 ordering of entries.
 
address@hidden change-log-redate
address@hidden 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}.
+
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
 @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
 
address@hidden
-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:
 
address@hidden
address@hidden This is commented out because the command is specific
address@hidden to maintenance of Emacs itself.
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 example
 
address@hidden Authors
address@hidden @file{AUTHORS} files
address@hidden @file{AUTHORS} file
-
-  Programs which have many contributors usually include a file named
address@hidden in their distribution, which lists the individual
-contributions.  Emacs has a special command for maintaining the
address@hidden file that is part of the Emacs distribution.
-
address@hidden 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.
address@hidden ignore
address@hidden
+Of course, you should substitute the proper years and copyright holder.
 
 @node Tags
 @section Tags Tables
@@ -425,15 +385,15 @@
 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 @address@hidden option when
@@ -480,21 +440,21 @@
 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 @address@hidden
-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
 address@hidden@address@hidden/@var{tagregexp}/address@hidden/address@hidden
@@ -537,8 +497,8 @@
 @end table
 
   The @samp{-R} option cancels all the regexps defined by preceding
address@hidden options.  It applies to the file names following it, as
-you can see from the following example:
address@hidden 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 \
@@ -647,30 +607,25 @@
 
 @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
address@hidden  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
address@hidden; 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
@@ -749,13 +704,13 @@
 @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 @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.  @kbd{C-x 4 .} with a negative
+command can take you to another buffer.  @address@hidden 4 .}} with a negative
 argument finds the previous tag location in another window.
 
 @kindex M-*
@@ -781,9 +736,13 @@
 @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}
@@ -846,9 +805,7 @@
 
   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
address@hidden 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
@@ -882,9 +839,9 @@
 
 @vindex tags-tag-face
 @vindex tags-apropos-additional-actions
-You can customize the appearance of the output with the face
address@hidden  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.
 
@@ -896,11 +853,11 @@
 @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.
@@ -918,7 +875,7 @@
 @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