From 191f7d865ef7d75d675b7f2ad35075f5320e96e8 Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Wed, 8 Feb 2006 00:00:22 +0000 Subject: [PATCH] (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. --- man/maintaining.texi | 251 ++++++++++++++++++------------------------- 1 file changed, 104 insertions(+), 147 deletions(-) diff --git a/man/maintaining.texi b/man/maintaining.texi index b885c8b7580..66a235ae119 100644 --- a/man/maintaining.texi +++ b/man/maintaining.texi @@ -14,6 +14,7 @@ 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. @@ -22,6 +23,14 @@ useful for this purpose. @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 @@ -32,58 +41,6 @@ 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 - - * 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 - - * 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 @@ -95,6 +52,11 @@ changed. 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 @@ -104,11 +66,6 @@ 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 @@ -122,52 +79,55 @@ this is convenient for entering the contents of an entry. 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 +1993-05-25 Richard Stallman + + * 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 + + * 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 @@ -425,15 +385,15 @@ 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 +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 @@ -480,21 +440,21 @@ 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} + @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} @@ -537,8 +497,8 @@ Match this regular expression against the whole file, and allow @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 \ @@ -647,30 +607,25 @@ etags --language=none \ @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 @@ -749,13 +704,13 @@ alternative to @kbd{C-u M-.}. @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-* @@ -781,9 +736,13 @@ that it does regexp matching instead of substring matching. @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 @@ 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. +Emacs and have Emacs show you the matching lines one by one. @xref{Grep Searching}. @node List Tags @@ -882,9 +839,9 @@ 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 + 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 @@ name in the buffer. @xref{Symbol Completion}. @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 @@ in a more manual fashion, and @ref{Top, Ediff,, ediff, The Ediff Manual}. @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 -- 2.39.2