X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/55d3737db5916a3091e27feddbff9a3103a4336f..2470aebd1094b54047f8d9852cb6c8d81e7c3a7d:/man/maintaining.texi diff --git a/man/maintaining.texi b/man/maintaining.texi index 3ffd6dd5e7..347a15d3c9 100644 --- a/man/maintaining.texi +++ b/man/maintaining.texi @@ -1,5 +1,6 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 Free Software Foundation, Inc. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, +@c 2001, 2005 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Maintaining, Abbrevs, Building, Top @chapter Maintaining Programs @@ -8,13 +9,11 @@ @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. @@ -41,13 +40,25 @@ one of its parent directories. A single @file{ChangeLog} file can record changes for all the files in its directory and all its subdirectories. - 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, -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, each with two items: + 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 @@ -68,10 +79,10 @@ in May 1993, each with two items: @end smallexample One entry can describe several changes; each change should have its -own 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. The second entry above -contains two items grouped in this way. +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 @@ -80,9 +91,9 @@ can even guess the name of the function or other object that was changed. @vindex add-log-keep-changes-together - When the option @code{add-log-keep-changes-together} is -non-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the file -rather than starting a new entry. + 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 @@ -93,6 +104,11 @@ 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 @@ -125,6 +141,10 @@ 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 @@ -136,9 +156,9 @@ contributions. Emacs has a special command for maintaining the @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 existing @file{AUTHORS} file. @@ -147,6 +167,7 @@ existing @file{AUTHORS} file. 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 @@ -164,8 +185,11 @@ definition of a function by looking up which of the files it is in. conventional name for a tags table file is @file{TAGS}. Each entry in the tags table records the name of one tag, the name of the -file that the tag is defined in (implicitly), and the position in that file -of the tag's definition. +file that the tag is defined in (implicitly), and the position in that +file of the tag's definition. When a file parsed by @code{etags} is +generated from a different source file, like a C file generated from a +Cweb source file, the tags of the parsed file reference the source +file. Just what names from the described files are recorded in the tags table depends on the programming language of the described file. They @@ -207,7 +231,8 @@ can make the tags table file much smaller. You can tag function declarations and external variables in addition to function definitions by giving the @samp{--declarations} option to -@code{etags}. +@code{etags}. You can tag struct members with the @samp{--members} +option. @item In C++ code, in addition to all the tag constructs of C code, member @@ -226,9 +251,10 @@ Tags for variables and functions in classes are named @item In La@TeX{} text, the argument of any of the commands @code{\chapter}, @code{\section}, @code{\subsection}, @code{\subsubsection}, -@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, -@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a -tag.@refill +@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, +@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry}, +@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand}, +@code{\newenvironment} or @code{\renewenvironment} is a tag.@refill Other commands can make tags as well, if you specify them in the environment variable @env{TEXTAGS} before invoking @code{etags}. The @@ -236,18 +262,18 @@ value of this environment variable should be a colon-separated list of command names. For example, @example -TEXTAGS="def:newcommand:newenvironment" +TEXTAGS="mycommand:myothercommand" export TEXTAGS @end example @noindent -specifies (using Bourne shell syntax) that the commands @samp{\def}, -@samp{\newcommand} and @samp{\newenvironment} also define tags. +specifies (using Bourne shell syntax) that the commands +@samp{\mycommand} and @samp{\myothercommand} also define tags. @item In Lisp code, any function defined with @code{defun}, any variable defined with @code{defvar} or @code{defconst}, and in general the first -argument of any expression that starts with @samp{(def} in column zero, is +argument of any expression that starts with @samp{(def} in column zero is a tag. @item @@ -261,7 +287,7 @@ set with @code{set!} at top level in the file. @itemize @bullet @item -In Ada code, functions, procedures, packages, tasks, and types are +In Ada code, functions, procedures, packages, tasks and types are tags. Use the @samp{--packages-only} option to create tags for packages only. @@ -306,33 +332,52 @@ In Cobol code, tags are paragraph names; that is, any word starting in column 8 and followed by a period. @item -In Erlang code, the tags are the functions, records, and macros defined +In Erlang code, the tags are the functions, records and macros defined 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 HTML input files, the tags are the @code{title} and the @code{h1}, +@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors +and all occurrences of @code{id=}. + +@item +In Lua input files, all functions are tags. @item -In makefiles, targets are tags. +In makefiles, targets are tags; additionally, variables are tags +unless you specify @samp{--no-globals}. @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 @@ -401,7 +446,8 @@ well as the files it directly contains. directory where the tags file was initially written. This way, you can move an entire directory tree containing both the tags file and the source files, and the tags file will still refer correctly to the source -files. +files. If the tags file is in @file{/dev}, however, the file names are +made relative to the current working directory. If you specify absolute file names as arguments to @code{etags}, then the tags file will contain absolute file names. This way, the tags file @@ -428,57 +474,74 @@ language from the file names and file contents. Specify entirely; then @code{etags} recognizes tags by regexp matching alone (@pxref{Etags Regexps}). + The option @samp{--parse-stdin=@var{file}} is mostly useful when +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. +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. -Each @samp{--regex} option adds to the preceding ones, and applies only -to the following files. The syntax is: +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{tagregexp}[/@var{nameregexp}]/ +--regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers} @end smallexample -@noindent -where @var{tagregexp} is used to match the lines to tag. It is always -anchored, that is, it behaves as if preceded by @samp{^}. If you want -to account for indentation, just match any initial number of blanks by -beginning your regular expression with @samp{[ \t]*}. In the regular -expressions, @samp{\} quotes the next character, and @samp{\t} stands -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. - - 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 -more characters than needed are unavoidably matched by @var{tagregexp} -(as will usually be the case), you should add a @var{nameregexp}, to -pick out just the tag. This will enable Emacs to find tags more -accurately and to do completion on tag names more reliably. You can -find some examples below. - - The option @samp{--ignore-case-regex} (or @samp{-c}) works like -@samp{--regex}, except that matching ignores case. This is -appropriate for certain programming languages. - - The @samp{-R} option deletes all the regexps defined with + The essential part of the option value is @var{tagregexp}, the +regexp for matching tags. It is always used anchored, that is, it +only matches at the beginning of a line. If you want to allow +indented tags, use a regexp that matches initial whitespace; start it +with @samp{[ \t]*}. + + In these regular expressions, @samp{\} quotes the next character, and +all the GCC character escape sequences are supported (@samp{\a} for +bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for +escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for +carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab). + + Ideally, @var{tagregexp} should not match more characters than are +needed to recognize what you want to tag. If the syntax requires you +to write @var{tagregexp} so it matches more characters beyond the tag +itself, you should add a @var{nameregexp}, to pick out just the tag. +This will enable Emacs to find tags more accurately and to do +completion on tag names more reliably. You can find some examples +below. + + The @var{modifiers} are a sequence of zero or more characters that +modify the way @code{etags} does the matching. A regexp with no +modifiers is applied sequentially to each line of the input file, in a +case-sensitive way. The modifiers and their meanings are: + +@table @samp +@item i +Ignore case when matching this regexp. +@item m +Match this regular expression against the whole file, so that +multi-line matches are possible. +@item s +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}/ voo.doo --regex=/@var{reg2}/ \ +etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \ bar.ber -R --lang=lisp los.er @end smallexample @@ -487,13 +550,18 @@ Here @code{etags} chooses the parsing language for @file{voo.doo} and @file{bar.ber} according to their contents. @code{etags} also uses @var{reg1} to recognize additional tags in @file{voo.doo}, and both @var{reg1} and @var{reg2} to recognize additional tags in -@file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp -matching, to recognize tags in @file{los.er}. - - 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 +@file{bar.ber}. @var{reg1} is checked against each line of +@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while +@var{reg2} is checked against the whole @file{bar.ber} file, +permitting multi-line matches, in a case-sensitive way. @code{etags} +uses only the Lisp tags rules, with no user-specified regexp matching, +to recognize tags in @file{los.er}. + + You can restrict a @samp{--regex} option to match only files of a +given language by using the optional prefix @var{@{language@}}. +(@samp{etags --help} prints the list of languages recognized by +@code{etags}.) This is particularly useful when storing many +predefined regular expressions for @code{etags} in a file. The following example tags the @code{DEFVAR} macros in the Emacs source files, for the C language only: @@ -502,26 +570,25 @@ files, for the C language only: @end smallexample @noindent -This feature is particularly useful when you store a list of regular -expressions in a file. The following option syntax instructs -@code{etags} to read two files of regular expressions. The regular -expressions contained in the second file are matched without regard to -case. +When you have complex regular expressions, you can store the list of +them in a file. The following option syntax instructs @code{etags} to +read two files of regular expressions. The regular expressions +contained in the second file are matched without regard to case. @smallexample ---regex=@@first-file --ignore-case-regex=@@second-file +--regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file} @end smallexample @noindent -A regex file contains one regular expressions per line. Empty lines, -and lines beginning with space or tab are ignored. When the first -character in a line is @samp{@@}, @code{etags} assumes that the rest -of the line is the name of a file of regular expressions; thus, one -such file can include another file. All the other lines are taken to -be regular expressions. If the first non-whitespace text on the line -is @samp{--}, that line is a comment. - - For example, one can create a file called @samp{emacs.tags} with the +A regex file for @code{etags} contains one regular expression per +line. Empty lines, and lines beginning with space or tab are ignored. +When the first character in a line is @samp{@@}, @code{etags} assumes +that the rest of the line is the name of another file of regular +expressions; thus, one such file can include another file. All the +other lines are taken to be regular expressions. If the first +non-whitespace text on the line is @samp{--}, that line is a comment. + + For example, we can create a file called @samp{emacs.tags} with the following contents: @smallexample @@ -833,7 +900,7 @@ 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{,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. @@ -1212,3 +1279,6 @@ commands. After setting up the merge, Emerge runs the hook @code{emerge-startup-hook} (@pxref{Hooks}). +@ignore + arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb +@end ignore