annotate man/maintaining.texi @ 47120:16d24d1d0e99

(font-lock-defaults): Fix typo.
author Juanma Barranquero <lekktu@gmail.com>
date Fri, 30 Aug 2002 11:00:46 +0000
parents a881d14145d0
children 3e1dde9764c0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c This is part of the Emacs manual.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 Free Software Foundation, Inc.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
3 @c See file emacs.texi for copying conditions.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4 @node Maintaining, Abbrevs, Building, Top
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @chapter Maintaining Programs
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @cindex Lisp editing
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @cindex C editing
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @cindex program editing
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10 This chapter describes Emacs features for maintaining programs. The
38952
c2f31ad2923b Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38860
diff changeset
11 version control features (@pxref{Version Control}) are also
c2f31ad2923b Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38860
diff changeset
12 particularly useful for this purpose.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 @menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 * Change Log:: Maintaining a change history for your program.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16 * Tags:: Go direct to any function in your program in one
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 command. Tags remembers which file it is in.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 * Emerge:: A convenient way of merging two versions of a program.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 @end menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 @node Change Log
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22 @section Change Logs
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
23
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
24 @cindex change log
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
25 @kindex C-x 4 a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 @findex add-change-log-entry-other-window
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28 file for the file you are editing
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 (@code{add-change-log-entry-other-window}). If that file is actually
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 a backup file, it makes an entry appropriate for the file's
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 parent---that is useful for making log entries for functions that
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 have been deleted in the current version.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 A change log file contains a chronological record of when and why you
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 have changed a program, consisting of a sequence of entries describing
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 individual changes. Normally it is kept in a file called
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 @file{ChangeLog} in the same directory as the file you are editing, or
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 one of its parent directories. A single @file{ChangeLog} file can
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 record changes for all the files in its directory and all its
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 subdirectories.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41
39623
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
42 You should put a copyright notice and permission notice at the
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
43 end of the change log file. Here is an example:
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
44
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
45 @example
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
46 Copyright 1997, 1998 Free Software Foundation, Inc.
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
47 Copying and distribution of this file, with or without modification, are
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
48 permitted provided the copyright notice and this notice are preserved.
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
49 @end example
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
50
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
51 @noindent
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
52 Of course, you should substitute the proper years and copyright holder.
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
53
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 A change log entry starts with a header line that contains the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 current date, your name, and your email address (taken from the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 variable @code{user-mail-address}). Aside from these header lines,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 every line in the change log starts with a space or a tab. The bulk
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 of the entry consists of @dfn{items}, each of which starts with a line
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 starting with whitespace and a star. Here are two entries, both dated
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 in May 1993, each with two items:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 @iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 @medbreak
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 @end iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 1993-05-25 Richard Stallman <rms@@gnu.org>
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 * man.el: Rename symbols `man-*' to `Man-*'.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 (manual-entry): Make prompt string clearer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 * simple.el (blink-matching-paren-distance):
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 Change default to 12,000.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 1993-05-24 Richard Stallman <rms@@gnu.org>
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 * vc.el (minor-mode-map-alist): Don't use it if it's void.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 (vc-cancel-version): Doc fix.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 One entry can describe several changes; each change should have its
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81 own item. Normally there should be a blank line between items. When
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 items are related (parts of the same change, in different places), group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 them by leaving no blank line between them. The second entry above
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 contains two items grouped in this way.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 @kbd{C-x 4 a} visits the change log file and creates a new entry
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87 unless the most recent entry is for today's date and your name. It
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
88 also creates a new item for the current file. For many languages, it
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89 can even guess the name of the function or other object that was
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
90 changed.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
91
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 @vindex add-log-keep-changes-together
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 When the option @code{add-log-keep-changes-together} is
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 non-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the file
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 rather than starting a new entry.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 @vindex change-log-version-info-enabled
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 @vindex change-log-version-number-regexp-list
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 @cindex file version in change log entries
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 If the value of the variable @code{change-log-version-info-enabled}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 change log entry. It finds the version number by searching the first
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 ten percent of the file, using regular expressions from the variable
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 @code{change-log-version-number-regexp-list}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
106 @vindex add-log-always-start-new-record
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
107 If @code{add-log-always-start-new-record} is non-@code{nil},
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
108 @kbd{C-x 4 a} always makes a new entry, even if the last entry
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
109 was made by you and on the same date.
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
110
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 @cindex Change Log mode
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 @findex change-log-mode
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 The change log file is visited in Change Log mode. In this major
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 mode, each bunch of grouped items counts as one paragraph, and each
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 entry is considered a page. This facilitates editing the entries.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 @kbd{C-j} and auto-fill indent each new line like the previous line;
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 this is convenient for entering the contents of an entry.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 @findex change-log-merge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 You can use the command @kbd{M-x change-log-merge} to merge other
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 log files into a buffer in Change Log Mode, preserving the date
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 ordering of entries.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124 @findex change-log-redate
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 @cindex converting change log date style
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 Versions of Emacs before 20.1 used a different format for the time of
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 the change log entry:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 The @kbd{M-x change-log-redate} command converts all the old-style
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 date entries in the change log file visited in the current buffer to
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136 the new format, to make the file uniform in style. This is handy when
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 entries are contributed by many different people, some of whom use old
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 versions of Emacs.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 Version control systems are another way to keep track of changes in your
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 program and keep a change log. @xref{Log Buffer}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142
40792
7ea12eee7004 Comment out the Authors node.
Richard M. Stallman <rms@gnu.org>
parents: 39623
diff changeset
143 @ignore
7ea12eee7004 Comment out the Authors node.
Richard M. Stallman <rms@gnu.org>
parents: 39623
diff changeset
144 @c This is commented out because the command is specific
7ea12eee7004 Comment out the Authors node.
Richard M. Stallman <rms@gnu.org>
parents: 39623
diff changeset
145 @c to maintenance of Emacs itself.
7ea12eee7004 Comment out the Authors node.
Richard M. Stallman <rms@gnu.org>
parents: 39623
diff changeset
146
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147 @node Authors
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 @section @file{AUTHORS} files
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 @cindex @file{AUTHORS} file
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 Programs which have many contributors usually include a file named
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152 @file{AUTHORS} in their distribution, which lists the individual
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153 contributions. Emacs has a special command for maintaining the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 @file{AUTHORS} file that is part of the Emacs distribution.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 @findex authors
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 The @kbd{M-x authors} command prompts for the name of the root of the
38860
cc3f1ee23db9 Fix a typo.
Gerd Moellmann <gerd@gnu.org>
parents: 38264
diff changeset
158 Emacs source directory. It then scans @file{ChangeLog} files and Lisp
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 source files under that directory for information about authors of
38952
c2f31ad2923b Minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38860
diff changeset
160 individual packages, and people who made changes in source files, and
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 puts the information it gleans into a buffer named @samp{*Authors*}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 You can then edit the contents of that buffer and merge it with the
38261
daf29e9ae9ed Fix a typo.
Eli Zaretskii <eliz@gnu.org>
parents: 38211
diff changeset
163 existing @file{AUTHORS} file.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 Do not assume that this command finds all the contributors; don't
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 assume that a person not listed in the output was not a contributor.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 If you merged in someone's contribution and did not put his name
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 in the change log, he won't show up in @kbd{M-x authors} either.
40792
7ea12eee7004 Comment out the Authors node.
Richard M. Stallman <rms@gnu.org>
parents: 39623
diff changeset
169 @end ignore
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 @node Tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 @section Tags Tables
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @cindex tags table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 A @dfn{tags table} is a description of how a multi-file program is
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 broken up into files. It lists the names of the component files and the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 names and positions of the functions (or other named subunits) in each
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 file. Grouping the related files makes it possible to search or replace
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 through all the files with one command. Recording the function names
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 and positions makes possible the @kbd{M-.} command which finds the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 definition of a function by looking up which of the files it is in.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 Tags tables are stored in files called @dfn{tags table files}. The
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 conventional name for a tags table file is @file{TAGS}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 Each entry in the tags table records the name of one tag, the name of the
43724
16affaf7292b etags honours #line directives.
Francesco Potortì <pot@gnu.org>
parents: 42342
diff changeset
187 file that the tag is defined in (implicitly), and the position in that
16affaf7292b etags honours #line directives.
Francesco Potortì <pot@gnu.org>
parents: 42342
diff changeset
188 file of the tag's definition. When a file parsed by @code{etags} is
43856
7d0cb2cc5e60 Use Cweb, not bison as an example of etags using #line.
Francesco Potortì <pot@gnu.org>
parents: 43724
diff changeset
189 generated from a different source file, like a C file generated from a
7d0cb2cc5e60 Use Cweb, not bison as an example of etags using #line.
Francesco Potortì <pot@gnu.org>
parents: 43724
diff changeset
190 Cweb source file, the tags of the parsed file reference the source
7d0cb2cc5e60 Use Cweb, not bison as an example of etags using #line.
Francesco Potortì <pot@gnu.org>
parents: 43724
diff changeset
191 file.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 Just what names from the described files are recorded in the tags table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 depends on the programming language of the described file. They
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 normally include all file names, functions and subroutines, and may
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196 also include global variables, data types, and anything else
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
197 convenient. Each name recorded is called a @dfn{tag}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
199 @cindex C++ class browser, tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
200 @cindex tags, C++
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 @cindex class browser, C++
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 @cindex Ebrowse
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 See also the Ebrowse facility, which is tailored for C++.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 @xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 @menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 * Tag Syntax:: Tag syntax for various types of code and text files.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 * Create Tags Table:: Creating a tags table with @code{etags}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 * Etags Regexps:: Create arbitrary tags using regular expressions.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 * Select Tags Table:: How to visit a tags table.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 * Find Tag:: Commands to find the definition of a specific tag.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 * Tags Search:: Using a tags table for searching and replacing.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 * List Tags:: Listing and finding tags defined in a file.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 @end menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 @node Tag Syntax
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 @subsection Source File Tag Syntax
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 Here is how tag syntax is defined for the most popular languages:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 @itemize @bullet
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 In C code, any C function or typedef is a tag, and so are definitions of
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 @code{struct}, @code{union} and @code{enum}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 @code{#define} macro definitions and @code{enum} constants are also
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 tags, unless you specify @samp{--no-defines} when making the tags table.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 Similarly, global variables are tags, unless you specify
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 @samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 can make the tags table file much smaller.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 You can tag function declarations and external variables in addition
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 to function definitions by giving the @samp{--declarations} option to
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 @code{etags}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 In C++ code, in addition to all the tag constructs of C code, member
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 functions are also recognized, and optionally member variables if you
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 use the @samp{--members} option. Tags for variables and functions in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 classes are named @samp{@var{class}::@var{variable}} and
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 @samp{@var{class}::@var{function}}. @code{operator} definitions have
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 tag names like @samp{operator+}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 In Java code, tags include all the constructs recognized in C++, plus
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 the @code{interface}, @code{extends} and @code{implements} constructs.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 Tags for variables and functions in classes are named
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 In La@TeX{} text, the argument of any of the commands @code{\chapter},
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 @code{\section}, @code{\subsection}, @code{\subsubsection},
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
252 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
253 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
46918
82d113655734 Minor spelling and grammar corrections.
Paul Eggert <eggert@twinsun.com>
parents: 46239
diff changeset
254 @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
255 @code{\newenvironment} or @code{\renewenvironment} is a tag.@refill
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 Other commands can make tags as well, if you specify them in the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 environment variable @env{TEXTAGS} before invoking @code{etags}. The
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 value of this environment variable should be a colon-separated list of
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 command names. For example,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 @example
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
263 TEXTAGS="mycommand:myothercommand"
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 export TEXTAGS
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 @noindent
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
268 specifies (using Bourne shell syntax) that the commands
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
269 @samp{\mycommand} and @samp{\myothercommand} also define tags.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 In Lisp code, any function defined with @code{defun}, any variable
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 defined with @code{defvar} or @code{defconst}, and in general the first
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274 argument of any expression that starts with @samp{(def} in column zero, is
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 a tag.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 In Scheme code, tags include anything defined with @code{def} or with a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 construct whose name starts with @samp{def}. They also include variables
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280 set with @code{set!} at top level in the file.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @end itemize
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 Several other languages are also supported:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 @itemize @bullet
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 In Ada code, functions, procedures, packages, tasks, and types are
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289 tags. Use the @samp{--packages-only} option to create tags for
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 packages only.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
292 In Ada, the same name can be used for different kinds of entity
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 (e.g.@:, for a procedure and for a function). Also, for things like
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 packages, procedures and functions, there is the spec (i.e.@: the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 interface) and the body (i.e.@: the implementation). To make it
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 easier to pick the definition you want, Ada tag name have suffixes
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 indicating the type of entity:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 @table @samp
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 @item /b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 package body.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 @item /f
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303 function.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @item /k
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 task.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 @item /p
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 procedure.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 @item /s
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 package spec.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @item /t
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 type.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 directly to the body of the package @code{bidule}, while @kbd{M-x
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 find-tag @key{RET} bidule @key{RET}} will just search for any tag
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 @code{bidule}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 In assembler code, labels appearing at the beginning of a line,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 followed by a colon, are tags.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 In Bison or Yacc input files, each rule defines as a tag the nonterminal
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 it constructs. The portions of the file that contain C code are parsed
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 as C code.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 In Cobol code, tags are paragraph names; that is, any word starting in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 column 8 and followed by a period.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 In Erlang code, the tags are the functions, records, and macros defined
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 in the file.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 @item
39267
a8c0a02f6129 Spelling corrections.
Richard M. Stallman <rms@gnu.org>
parents: 39082
diff changeset
337 In Fortran code, functions, subroutines and block data are tags.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 @item
47085
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
340 In HTML input files, the tags are the @code{title} and the @code{h1},
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
341 @code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
342 and all occurrences of @code{id=}.
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
343
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
344 @item
45919
Francesco Potortì <pot@gnu.org>
parents: 45887
diff changeset
345 In makefiles, targets are tags; additionally, variables are tags
Francesco Potortì <pot@gnu.org>
parents: 45887
diff changeset
346 unless you specify @samp{--no-globals}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 In Objective C code, tags include Objective C definitions for classes,
42342
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
350 class categories, methods, and protocols. Tags for variables and
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
351 functions in classes are named @samp{@var{class}::@var{variable}} and
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
352 @samp{@var{class}::@var{function}}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 In Pascal code, the tags are the functions and procedures defined in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 the file.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 @item
42342
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
359 In Perl code, the tags are the packages, subroutines and variables
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
360 defined by the @code{package}, @code{sub}, @code{my} and @code{local}
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
361 keywords. Use @samp{--globals} if you want to tag global variables.
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
362 Tags for subroutines are named @samp{@var{package}::@var{sub}}. The
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
363 name for subroutines defined in the default package is
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
364 @samp{main::@var{sub}}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 @item
42043
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
367 In PHP code, tags are functions, classes and defines. When using the
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
368 @samp{--members} option, vars are tags too.
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
369
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
370 @item
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371 In PostScript code, the tags are the functions.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
372
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 @item
42043
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
374 In Prolog code, tags are predicates and rules at the beginning of
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
375 line.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 In Python code, @code{def} or @code{class} at the beginning of a line
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 generate a tag.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 @end itemize
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 You can also generate tags based on regexp matching (@pxref{Etags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383 Regexps}) to handle other formats and languages.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
384
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
385 @node Create Tags Table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386 @subsection Creating Tags Tables
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
387 @cindex @code{etags} program
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
388
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 The @code{etags} program is used to create a tags table file. It knows
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390 the syntax of several languages, as described in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 @iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 the previous section.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 @end iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 @ifinfo
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 @ref{Tag Syntax}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
396 @end ifinfo
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
397 Here is how to run @code{etags}:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 etags @var{inputfiles}@dots{}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
403 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
404 The @code{etags} program reads the specified files, and writes a tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 table named @file{TAGS} in the current working directory.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
406
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
407 If the specified files don't exist, @code{etags} looks for
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
408 compressed versions of them and uncompresses them to read them. Under
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 does not exist.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 @code{etags} recognizes the language used in an input file based on
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 its file name and contents. You can specify the language with the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @samp{--language=@var{name}} option, described below.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 If the tags table data become outdated due to changes in the files
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 described in the table, the way to update the tags table is the same
38264
e781108d8f69 Clarify when it's good to update a tags table and why.
Richard M. Stallman <rms@gnu.org>
parents: 38261
diff changeset
419 way it was made in the first place. If the tags table fails to record
e781108d8f69 Clarify when it's good to update a tags table and why.
Richard M. Stallman <rms@gnu.org>
parents: 38261
diff changeset
420 a tag, or records it for the wrong file, then Emacs cannot possibly
e781108d8f69 Clarify when it's good to update a tags table and why.
Richard M. Stallman <rms@gnu.org>
parents: 38261
diff changeset
421 find its definition until you update the tags table. However, if the
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 position recorded in the tags table becomes a little bit wrong (due to
38264
e781108d8f69 Clarify when it's good to update a tags table and why.
Richard M. Stallman <rms@gnu.org>
parents: 38261
diff changeset
423 other editing), the only consequence is a slight delay in finding the
e781108d8f69 Clarify when it's good to update a tags table and why.
Richard M. Stallman <rms@gnu.org>
parents: 38261
diff changeset
424 tag. Even if the stored position is very far wrong, Emacs will still
e781108d8f69 Clarify when it's good to update a tags table and why.
Richard M. Stallman <rms@gnu.org>
parents: 38261
diff changeset
425 find the tag, after searching most of the file for it. Even that
e781108d8f69 Clarify when it's good to update a tags table and why.
Richard M. Stallman <rms@gnu.org>
parents: 38261
diff changeset
426 delay is hardly noticeable with today's computers.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428 So you should update a tags table when you define new tags that you want
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
429 to have listed, or when you move tag definitions from one file to another,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 or when changes become substantial. Normally there is no need to update
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431 the tags table after each edit, or even every day.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433 One tags table can virtually include another. Specify the included
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 tags file name with the @samp{--include=@var{file}} option when
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435 creating the file that is to include it. The latter file then acts as
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 if it covered all the source files specified in the included file, as
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 well as the files it directly contains.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 If you specify the source files with relative file names when you run
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 @code{etags}, the tags file will contain file names relative to the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 directory where the tags file was initially written. This way, you can
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 move an entire directory tree containing both the tags file and the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 source files, and the tags file will still refer correctly to the source
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 files.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 If you specify absolute file names as arguments to @code{etags}, then
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 the tags file will contain absolute file names. This way, the tags file
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 will still refer to the same files even if you move it, as long as the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 source files remain in the same place. Absolute file names start with
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452 When you want to make a tags table from a great number of files, you
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 may have problems listing them on the command line, because some systems
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 have a limit on its length. The simplest way to circumvent this limit
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 is to tell @code{etags} to read the file names from its standard input,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 by typing a dash in place of the file names, like this:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 find . -name "*.[chCH]" -print | etags -
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 Use the option @samp{--language=@var{name}} to specify the language
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
463 explicitly. You can intermix these options with file names; each one
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 applies to the file names that follow it. Specify
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @samp{--language=auto} to tell @code{etags} to resume guessing the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 language from the file names and file contents. Specify
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @samp{--language=none} to turn off language-specific processing
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 entirely; then @code{etags} recognizes tags by regexp matching alone
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 (@pxref{Etags Regexps}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
471 The option @samp{--parse-stdin=@var{file}} is mostly useful when
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
472 calling @code{etags} from programs. It can be used (only once) in
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
473 place of a file name on the command line. @code{Etags} will read from
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
474 standard input and mark the produced tags as belonging to the file
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
475 @var{file}.
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
476
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 @samp{etags --help} prints the list of the languages @code{etags}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 knows, and the file name rules for guessing the language. It also prints
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 a list of all the available @code{etags} options, together with a short
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480 explanation.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 @node Etags Regexps
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 @subsection Etags Regexps
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 The @samp{--regex} option provides a general way of recognizing tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 based on regexp matching. You can freely intermix it with file names.
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
487 If you specify multiple @samp{--regex} options, all of them are used
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
488 in parallel, but each one applies only to the source files that follow
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
489 it. The syntax is:
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @smallexample
45801
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
492 --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
493 @end smallexample
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
494
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
495 The essential part of the option value is @var{tagregexp}, the
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
496 regexp for matching tags. It is always used anchored, that is, it
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
497 only matches at the beginning of a line. If you want to allow
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
498 indented tags, use a regexp that matches initial whitespace; start it
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
499 with @samp{[ \t]*}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
501 In these regular expressions, @samp{\} quotes the next character, and
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
502 all the GCC character escape sequences are supported (@samp{\a} for
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
503 bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
504 escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
505 carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
45666
621742dde467 Document Etags regexp char escape sequences.
Francesco Potortì <pot@gnu.org>
parents: 45659
diff changeset
506
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
507 Ideally, @var{tagregexp} should not match more characters than are
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
508 needed to recognize what you want to tag. If the syntax requires you
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
509 to write @var{tagregexp} so it matches more characters beyond the tag
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
510 itself, you should add a @var{nameregexp}, to pick out just the tag.
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
511 This will enable Emacs to find tags more accurately and to do
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
512 completion on tag names more reliably. You can find some examples
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
513 below.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
515 The @var{modifiers} are a sequence of zero or more characters that
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
516 modify the way @code{etags} does the matching. A regexp with no
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
517 modifiers is applied sequentially to each line of the input file, in a
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
518 case-sensitive way. The modifiers and their meanings are:
45801
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
519
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
520 @table @samp
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
521 @item i
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
522 Ignore case when matching this regexp.
45801
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
523 @item m
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
524 Match this regular expression against the whole file, so that
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
525 multi-line matches are possible.
45801
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
526 @item s
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
527 Match this regular expression against the whole file, and allow
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
528 @samp{.} in @var{tagregexp} to match newlines.
45801
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
529 @end table
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
530
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
531 The @samp{-R} option cancels all the regexps defined by preceding
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 @samp{--regex} options. It applies to the file names following it, as
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 you can see from the following example:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 @smallexample
45886
22138a27a5f3 Specify that the separator character can be different from a slash.
Francesco Potortì <pot@gnu.org>
parents: 45801
diff changeset
536 etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 bar.ber -R --lang=lisp los.er
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541 Here @code{etags} chooses the parsing language for @file{voo.doo} and
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 @file{bar.ber} according to their contents. @code{etags} also uses
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 @var{reg1} and @var{reg2} to recognize additional tags in
45886
22138a27a5f3 Specify that the separator character can be different from a slash.
Francesco Potortì <pot@gnu.org>
parents: 45801
diff changeset
545 @file{bar.ber}. @var{reg1} is checked against each line of
22138a27a5f3 Specify that the separator character can be different from a slash.
Francesco Potortì <pot@gnu.org>
parents: 45801
diff changeset
546 @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
22138a27a5f3 Specify that the separator character can be different from a slash.
Francesco Potortì <pot@gnu.org>
parents: 45801
diff changeset
547 @var{reg2} is checked against the whole @file{bar.ber} file,
22138a27a5f3 Specify that the separator character can be different from a slash.
Francesco Potortì <pot@gnu.org>
parents: 45801
diff changeset
548 permitting multi-line matches, in a case-sensitive way. @code{etags}
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
549 uses only the Lisp tags rules, with no user-specified regexp matching,
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
550 to recognize tags in @file{los.er}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551
45887
8aa6e4d588ce some passive forms to active
Francesco Potortì <pot@gnu.org>
parents: 45886
diff changeset
552 You can restrict a @samp{--regex} option to match only files of a
8aa6e4d588ce some passive forms to active
Francesco Potortì <pot@gnu.org>
parents: 45886
diff changeset
553 given language by using the optional prefix @var{@{language@}}.
45886
22138a27a5f3 Specify that the separator character can be different from a slash.
Francesco Potortì <pot@gnu.org>
parents: 45801
diff changeset
554 (@samp{etags --help} prints the list of languages recognized by
22138a27a5f3 Specify that the separator character can be different from a slash.
Francesco Potortì <pot@gnu.org>
parents: 45801
diff changeset
555 @code{etags}.) This is particularly useful when storing many
22138a27a5f3 Specify that the separator character can be different from a slash.
Francesco Potortì <pot@gnu.org>
parents: 45801
diff changeset
556 predefined regular expressions for @code{etags} in a file. The
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 following example tags the @code{DEFVAR} macros in the Emacs source
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 files, for the C language only:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 @noindent
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
565 When you have complex regular expressions, you can store the list of
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
566 them in a file. The following option syntax instructs @code{etags} to
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
567 read two files of regular expressions. The regular expressions
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
568 contained in the second file are matched without regard to case.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 @smallexample
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
571 --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 @noindent
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
575 A regex file for @code{etags} contains one regular expression per
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
576 line. Empty lines, and lines beginning with space or tab are ignored.
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
577 When the first character in a line is @samp{@@}, @code{etags} assumes
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
578 that the rest of the line is the name of another file of regular
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
579 expressions; thus, one such file can include another file. All the
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
580 other lines are taken to be regular expressions. If the first
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
581 non-whitespace text on the line is @samp{--}, that line is a comment.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
583 For example, we can create a file called @samp{emacs.tags} with the
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 following contents:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 -- This is for GNU Emacs C source files
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 and then use it like this:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 etags --regex=@@emacs.tags *.[ch] */*.[ch]
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
598 Here are some more examples. The regexps are quoted to protect them
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
599 from shell interpretation.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 @itemize @bullet
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 Tag Octave files:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607 etags --language=none \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 --regex='/###key \(.*\)/\1/' \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 --regex='/[ \t]*global[ \t].*/' \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 *.m
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 Note that tags are not generated for scripts, so that you have to add
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 a line by yourself of the form @samp{###key @var{scriptname}} if you
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617 want to jump to it.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 Tag Tcl files:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
622 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
623 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 Tag VHDL files:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 etags --language=none \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 @end itemize
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @node Select Tags Table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 @subsection Selecting a Tags Table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 @vindex tags-file-name
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 @findex visit-tags-table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
642 Emacs has at any time one @dfn{selected} tags table, and all the commands
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 for working with tags tables use the selected one. To select a tags table,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 argument. The name @file{TAGS} in the default directory is used as the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 default file name.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 All this command does is store the file name in the variable
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 @code{tags-file-name}. Emacs does not actually read in the tags table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 contents until you try to use them. Setting this variable yourself is just
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 as good as using @code{visit-tags-table}. The variable's initial value is
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652 @code{nil}; that value tells all the commands for working with tags tables
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 that they must ask for a tags table file name to use.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 Using @code{visit-tags-table} when a tags table is already loaded
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
656 gives you a choice: you can add the new tags table to the current list
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 of tags tables, or start a new list. The tags commands use all the tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 tables in the current list. If you start a new list, the new tags table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 is used @emph{instead} of others. If you add the new table to the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 current list, it is used @emph{as well as} the others. When the tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661 commands scan the list of tags tables, they don't always start at the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
662 beginning of the list; they start with the first tags table (if any)
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663 that describes the current file, proceed from there to the end of the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664 list, and then scan from the beginning of the list until they have
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 covered all the tables in the list.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 @vindex tags-table-list
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 You can specify a precise list of tags tables by setting the variable
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 @code{tags-table-list} to a list of strings, like this:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 @c keep this on two lines for formatting in smallbook
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673 @group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 (setq tags-table-list
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 '("~/emacs" "/usr/local/lib/emacs/src"))
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 @end group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 This tells the tags commands to look at the @file{TAGS} files in your
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682 directory. The order depends on which file you are in and which tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 table mentions that file, as explained above.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 Do not set both @code{tags-file-name} and @code{tags-table-list}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 @node Find Tag
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 @subsection Finding a Tag
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 The most important thing that a tags table enables you to do is to find
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691 the definition of a specific tag.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 @item M-.@: @var{tag} @key{RET}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 Find first definition of @var{tag} (@code{find-tag}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696 @item C-u M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697 Find next alternate definition of last tag specified.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 @item C-u - M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 Go back to previous tag found.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700 @item C-M-. @var{pattern} @key{RET}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 @item C-u C-M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703 Find the next tag whose name matches the last pattern used.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 @item C-x 4 .@: @var{tag} @key{RET}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 Find first definition of @var{tag}, but display it in another window
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 (@code{find-tag-other-window}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 @item C-x 5 .@: @var{tag} @key{RET}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 Find first definition of @var{tag}, and create a new frame to select the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 buffer (@code{find-tag-other-frame}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710 @item M-*
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 Pop back to where you previously invoked @kbd{M-.} and friends.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714 @kindex M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 @findex find-tag
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 a specified tag. It searches through the tags table for that tag, as a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 string, and then uses the tags table info to determine the file that the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 definition is in and the approximate character position in the file of
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 the definition. Then @code{find-tag} visits that file, moves point to
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 the approximate character position, and searches ever-increasing
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 distances away to find the tag definition.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
724 If an empty argument is given (just type @key{RET}), the balanced
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 expression in the buffer before or around point is used as the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 @var{tag} argument. @xref{Expressions}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 You don't need to give @kbd{M-.} the full name of the tag; a part
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 will do. This is because @kbd{M-.} finds tags in the table which
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 contain @var{tag} as a substring. However, it prefers an exact match
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 to a substring match. To find other tags that match the same
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 M-.}; this does not read a tag name, but continues searching the tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 table's text for another tag containing the same substring last used.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736 alternative to @kbd{C-u M-.}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 @kindex C-x 4 .
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 @findex find-tag-other-window
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740 @kindex C-x 5 .
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 @findex find-tag-other-frame
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 Like most commands that can switch buffers, @code{find-tag} has a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 variant that displays the new buffer in another window, and one that
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 which invokes @code{find-tag-other-frame}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 To move back to places you've found tags recently, use @kbd{C-u -
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 command can take you to another buffer. @kbd{C-x 4 .} with a negative
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 argument finds the previous tag location in another window.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 @kindex M-*
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 @findex pop-tag-mark
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 @vindex find-tag-marker-ring-length
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 As well as going back to places you've found tags recently, you can go
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 back to places @emph{from where} you found them. Use @kbd{M-*}, which
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 invokes the command @code{pop-tag-mark}, for this. Typically you would
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759 find and study the definition of something with @kbd{M-.} and then
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
760 return to where you were with @kbd{M-*}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 a depth determined by the variable @code{find-tag-marker-ring-length}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 @findex find-tag-regexp
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 @kindex C-M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
767 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
768 match a specified regular expression. It is just like @kbd{M-.} except
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 that it does regexp matching instead of substring matching.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 @node Tags Search
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772 @subsection Searching and Replacing with Tags Tables
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 @cindex search and replace in multiple files
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774 @cindex multiple-file search and replace
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776 The commands in this section visit and search all the files listed in the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 selected tags table, one by one. For these commands, the tags table serves
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 only to specify a sequence of files to search.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782 Search for @var{regexp} through the files in the selected tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783 table.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 Perform a @code{query-replace-regexp} on each file in the selected tags table.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 @item M-,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787 Restart one of the commands above, from the current location of point
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 (@code{tags-loop-continue}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 @findex tags-search
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 searches for matches in all the files in the selected tags table, one
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 file at a time. It displays the name of the file being searched so you
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 can follow its progress. As soon as it finds an occurrence,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 @code{tags-search} returns.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 @kindex M-,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 @findex tags-loop-continue
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 Having found one match, you probably want to find all the rest. To find
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 @code{tags-search}. This searches the rest of the current buffer, followed
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 by the remaining files of the tags table.@refill
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 @findex tags-query-replace
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806 @kbd{M-x tags-query-replace} performs a single
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807 @code{query-replace-regexp} through all the files in the tags table. It
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 reads a regexp to search for and a string to replace with, just like
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 tags-search}, but repeatedly, processing matches according to your
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 input. @xref{Replace}, for more information on query replace.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 @vindex tags-case-fold-search
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814 @cindex case-sensitivity and tags search
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
815 You can control the case-sensitivity of tags search commands by
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 customizing the value of the variable @code{tags-case-fold-search}. The
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 default is to use the same setting as the value of
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 @code{case-fold-search} (@pxref{Search Case}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 It is possible to get through all the files in the tags table with a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821 single invocation of @kbd{M-x tags-query-replace}. But often it is
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 useful to exit temporarily, which you can do with any input event that
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823 has no special query replace meaning. You can resume the query replace
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 subsequently by typing @kbd{M-,}; this command resumes the last tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 search or replace command that you did.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 The commands in this section carry out much broader searches than the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 @code{find-tag} family. The @code{find-tag} commands search only for
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 definitions of tags that match your substring or regexp. The commands
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 @code{tags-search} and @code{tags-query-replace} find every occurrence
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 of the regexp, as ordinary search commands and replace commands do in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 the current buffer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 These commands create buffers only temporarily for the files that they
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 have to search (those which are not already visited in Emacs buffers).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 Buffers in which no match is found are quickly killed; the others
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 continue to exist.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 It may have struck you that @code{tags-search} is a lot like
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 @code{grep}. You can also run @code{grep} itself as an inferior of
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841 Emacs and have Emacs show you the matching lines one by one. This works
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 much like running a compilation; finding the source locations of the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 @code{grep} matches works like finding the compilation errors.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844 @xref{Compilation}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 @node List Tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 @subsection Tags Table Inquiries
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850 @item M-x list-tags @key{RET} @var{file} @key{RET}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 Display a list of the tags defined in the program file @var{file}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 Display a list of all tags matching @var{regexp}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 @findex list-tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 @kbd{M-x list-tags} reads the name of one of the files described by
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858 the selected tags table, and displays a list of all the tags defined in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 that file. The ``file name'' argument is really just a string to
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 compare against the file names recorded in the tags table; it is read as
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 a string rather than as a file name. Therefore, completion and
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 defaulting are not available, and you must enter the file name the same
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
863 way it appears in the tags table. Do not include a directory as part of
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 the file name unless the file name recorded in the tags table includes a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865 directory.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 @findex tags-apropos
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
868 @vindex tags-apropos-verbose
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
869 @kbd{M-x tags-apropos} is like @code{apropos} for tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
870 (@pxref{Apropos}). It finds all the tags in the selected tags table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
871 whose entries match @var{regexp}, and displays them. If the variable
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 of the tags files together with the tag names.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875 @vindex tags-tag-face
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876 @vindex tags-apropos-additional-actions
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877 You can customize the appearance of the output with the face
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878 @code{tags-tag-face}. You can display additional output with @kbd{M-x
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
879 tags-apropos} by customizing the variable
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
880 @code{tags-apropos-additional-actions}---see its documentation for
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
881 details.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
882
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883 You can also use the collection of tag names to complete a symbol
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 name in the buffer. @xref{Symbol Completion}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885
38211
5ef494421061 Fix mistakes in @node Emerge.
Richard M. Stallman <rms@gnu.org>
parents: 38198
diff changeset
886 @node Emerge
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 @section Merging Files with Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888 @cindex Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889 @cindex merging files
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 It's not unusual for programmers to get their signals crossed and modify
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 the same program in two different directions. To recover from this
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893 confusion, you need to merge the two versions. Emerge makes this
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894 easier. See also @ref{Comparing Files}, for commands to compare
41864
16dc446b245f Don't omit first argument of @ref.
Andreas Schwab <schwab@suse.de>
parents: 40792
diff changeset
895 in a more manual fashion, and @ref{Top, Ediff,, ediff, The Ediff Manual}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 @menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 * Overview of Emerge:: How to start Emerge. Basic concepts.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899 * Submodes of Emerge:: Fast mode vs. Edit mode.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 Skip Prefers mode and Auto Advance mode.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 * State of Difference:: You do the merge by specifying state A or B
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902 for each difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 * Merge Commands:: Commands for selecting a difference,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 changing states of differences, etc.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 * Exiting Emerge:: What to do when you've finished the merge.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 * Combining in Emerge:: How to keep both alternatives for a difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 * Fine Points of Emerge:: Misc.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 @end menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 @node Overview of Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 @subsection Overview of Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 To start Emerge, run one of these four commands:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 @item M-x emerge-files
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 @findex emerge-files
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918 Merge two specified files.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 @item M-x emerge-files-with-ancestor
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
921 @findex emerge-files-with-ancestor
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
922 Merge two specified files, with reference to a common ancestor.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924 @item M-x emerge-buffers
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 @findex emerge-buffers
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926 Merge two buffers.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928 @item M-x emerge-buffers-with-ancestor
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929 @findex emerge-buffers-with-ancestor
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
930 Merge two buffers with reference to a common ancestor in a third
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
931 buffer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 @cindex merge buffer (Emerge)
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 @cindex A and B buffers (Emerge)
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936 The Emerge commands compare two files or buffers, and display the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 comparison in three buffers: one for each input text (the @dfn{A buffer}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 takes place. The merge buffer shows the full merged text, not just the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 differences. Wherever the two input texts differ, you can choose which
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941 one of them to include in the merge buffer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 The Emerge commands that take input from existing buffers use only the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 accessible portions of those buffers, if they are narrowed
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 (@pxref{Narrowing}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 If a common ancestor version is available, from which the two texts to
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
948 be merged were both derived, Emerge can use it to guess which
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949 alternative is right. Wherever one current version agrees with the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 ancestor, Emerge presumes that the other current version is a deliberate
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951 change which should be kept in the merged version. Use the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 @samp{with-ancestor} commands if you want to specify a common ancestor
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953 text. These commands read three file or buffer names---variant A,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954 variant B, and the common ancestor.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956 After the comparison is done and the buffers are prepared, the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957 interactive merging starts. You control the merging by typing special
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
958 @dfn{merge commands} in the merge buffer. The merge buffer shows you a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
959 full merged text, not just differences. For each run of differences
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
960 between the input texts, you can choose which one of them to keep, or
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 edit them both together.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
962
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
963 The merge buffer uses a special major mode, Emerge mode, with commands
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964 for making these choices. But you can also edit the buffer with
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 ordinary Emacs commands.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 At any given time, the attention of Emerge is focused on one
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 particular difference, called the @dfn{selected} difference. This
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 difference is marked off in the three buffers like this:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 vvvvvvvvvvvvvvvvvvvv
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973 @var{text that differs}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 ^^^^^^^^^^^^^^^^^^^^
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978 Emerge numbers all the differences sequentially and the mode
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 line always shows the number of the selected difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981 Normally, the merge buffer starts out with the A version of the text.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 But when the A version of a difference agrees with the common ancestor,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 then the B version is initially preferred for that difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 Emerge leaves the merged text in the merge buffer when you exit. At
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 that point, you can save it in a file with @kbd{C-x C-w}. If you give a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 numeric argument to @code{emerge-files} or
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 @code{emerge-files-with-ancestor}, it reads the name of the output file
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989 using the minibuffer. (This is the last file name those commands read.)
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990 Then exiting from Emerge saves the merged text in the output file.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992 Normally, Emerge commands save the output buffer in its file when you
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993 exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 save the output buffer, but you can save it yourself if you wish.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996 @node Submodes of Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 @subsection Submodes of Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 You can choose between two modes for giving merge commands: Fast mode
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 and Edit mode. In Fast mode, basic merge commands are single
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 characters, but ordinary Emacs commands are disabled. This is
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 convenient if you use only merge commands. In Edit mode, all merge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003 commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004 commands are also available. This allows editing the merge buffer, but
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1005 slows down Emerge operations.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007 Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008 Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009 and @samp{F}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011 Emerge has two additional submodes that affect how particular merge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012 commands work: Auto Advance mode and Skip Prefers mode.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014 If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 advance to the next difference. This lets you go through the merge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016 faster as long as you simply choose one of the alternatives from the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 input. The mode line indicates Auto Advance mode with @samp{A}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019 If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020 skip over differences in states prefer-A and prefer-B (@pxref{State of
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1021 Difference}). Thus you see only differences for which neither version
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 is presumed ``correct.'' The mode line indicates Skip Prefers mode with
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023 @samp{S}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1024
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 @findex emerge-auto-advance-mode
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026 @findex emerge-skip-prefers-mode
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027 Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 clear Auto Advance mode. Use @kbd{s s}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029 (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 These commands turn on the mode with a positive argument, turns it off
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031 with a negative or zero argument, and toggle the mode with no argument.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 @node State of Difference
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 @subsection State of a Difference
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1035
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036 In the merge buffer, a difference is marked with lines of @samp{v} and
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 @samp{^} characters. Each difference has one of these seven states:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039 @table @asis
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040 @item A
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 The difference is showing the A version. The @kbd{a} command always
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 produces this state; the mode line indicates it with @samp{A}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044 @item B
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1045 The difference is showing the B version. The @kbd{b} command always
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 produces this state; the mode line indicates it with @samp{B}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048 @item default-A
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 @itemx default-B
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050 The difference is showing the A or the B state by default, because you
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051 haven't made a choice. All differences start in the default-A state
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052 (and thus the merge buffer is a copy of the A buffer), except those for
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 which one alternative is ``preferred'' (see below).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055 When you select a difference, its state changes from default-A or
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 default-B to plain A or B. Thus, the selected difference never has
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 state default-A or default-B, and these states are never displayed in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 the mode line.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 The command @kbd{d a} chooses default-A as the default state, and @kbd{d
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 b} chooses default-B. This chosen default applies to all differences
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 which you haven't ever selected and for which no alternative is preferred.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 If you are moving through the merge sequentially, the differences you
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 haven't selected are those following the selected one. Thus, while
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 moving sequentially, you can effectively make the A version the default
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 for some sections of the merge buffer and the B version the default for
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067 others by using @kbd{d a} and @kbd{d b} between sections.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 @item prefer-A
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070 @itemx prefer-B
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071 The difference is showing the A or B state because it is
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1072 @dfn{preferred}. This means that you haven't made an explicit choice,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1073 but one alternative seems likely to be right because the other
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 alternative agrees with the common ancestor. Thus, where the A buffer
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 agrees with the common ancestor, the B version is preferred, because
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076 chances are it is the one that was actually changed.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1078 These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080 @item combined
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081 The difference is showing a combination of the A and B states, as a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 result of the @kbd{x c} or @kbd{x C} commands.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084 Once a difference is in this state, the @kbd{a} and @kbd{b} commands
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 don't do anything to it unless you give them a numeric argument.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087 The mode line displays this state as @samp{comb}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1089
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090 @node Merge Commands
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091 @subsection Merge Commands
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1092
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 Here are the Merge commands for Fast mode; in Edit mode, precede them
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094 with @kbd{C-c C-c}:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1097 @item p
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1098 Select the previous difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100 @item n
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 Select the next difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 @item a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 Choose the A version of this difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106 @item b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107 Choose the B version of this difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1108
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109 @item C-u @var{n} j
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110 Select difference number @var{n}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1112 @item .
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 Select the difference containing point. You can use this command in the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114 merge buffer or in the A or B buffer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116 @item q
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117 Quit---finish the merge.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1118
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119 @item C-]
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 Abort---exit merging and do not save the output.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1121
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 @item f
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125 @item e
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126 Go into Edit mode.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 @item l
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129 Recenter (like @kbd{C-l}) all three windows.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 @item -
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 Specify part of a prefix numeric argument.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 @item @var{digit}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 Also specify part of a prefix numeric argument.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 @item d a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 Choose the A version as the default from here down in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139 the merge buffer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1141 @item d b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142 Choose the B version as the default from here down in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1143 the merge buffer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1144
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 @item c a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 Copy the A version of this difference into the kill ring.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148 @item c b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149 Copy the B version of this difference into the kill ring.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1150
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151 @item i a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152 Insert the A version of this difference at point.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154 @item i b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 Insert the B version of this difference at point.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157 @item m
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 Put point and mark around the difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1160 @item ^
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161 Scroll all three windows down (like @kbd{M-v}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 @item v
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 Scroll all three windows up (like @kbd{C-v}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166 @item <
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 Scroll all three windows left (like @kbd{C-x <}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1169 @item >
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1170 Scroll all three windows right (like @kbd{C-x >}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1171
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1172 @item |
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 Reset horizontal scroll on all three windows.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 @item x 1
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177 to full size.)
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 @item x c
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1180 Combine the two versions of this difference (@pxref{Combining in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 Emerge}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183 @item x f
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1184 Show the names of the files/buffers Emerge is operating on, in a Help
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185 window. (Use @kbd{C-u l} to restore windows.)
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1186
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187 @item x j
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188 Join this difference with the following one.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 (@kbd{C-u x j} joins this difference with the previous one.)
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191 @item x s
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192 Split this difference into two differences. Before you use this
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193 command, position point in each of the three buffers at the place where
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194 you want to split the difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196 @item x t
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 Trim identical lines off the top and bottom of the difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198 Such lines occur when the A and B versions are
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1199 identical but differ from the ancestor version.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1200 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1202 @node Exiting Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1203 @subsection Exiting Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205 The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1206 the results into the output file if you specified one. It restores the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207 A and B buffers to their proper contents, or kills them if they were
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1208 created by Emerge and you haven't changed them. It also disables the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1209 Emerge commands in the merge buffer, since executing them later could
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 damage the contents of the various buffers.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212 @kbd{C-]} aborts the merge. This means exiting without writing the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1213 output file. If you didn't specify an output file, then there is no
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214 real difference between aborting and finishing the merge.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1216 If the Emerge command was called from another Lisp program, then its
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 return value is @code{t} for successful completion, or @code{nil} if you
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1218 abort.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220 @node Combining in Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221 @subsection Combining the Two Versions
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1222
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223 Sometimes you want to keep @emph{both} alternatives for a particular
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1224 difference. To do this, use @kbd{x c}, which edits the merge buffer
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225 like this:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1227 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1228 @group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229 #ifdef NEW
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 @var{version from A buffer}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 #else /* not NEW */
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232 @var{version from B buffer}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 #endif /* not NEW */
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234 @end group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1235 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1237 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238 @vindex emerge-combine-versions-template
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 While this example shows C preprocessor conditionals delimiting the two
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240 alternative versions, you can specify the strings to use by setting
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241 the variable @code{emerge-combine-versions-template} to a string of your
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242 choice. In the string, @samp{%a} says where to put version A, and
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 @samp{%b} says where to put version B. The default setting, which
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 produces the results shown above, looks like this:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 @group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249 @end group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 @node Fine Points of Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253 @subsection Fine Points of Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 During the merge, you mustn't try to edit the A and B buffers yourself.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 Emerge modifies them temporarily, but ultimately puts them back the way
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257 they were.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1258
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1259 You can have any number of merges going at once---just don't use any one
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1260 buffer as input to more than one merge at once, since the temporary
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1261 changes made in these buffers would get in each other's way.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263 Starting Emerge can take a long time because it needs to compare the
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 files fully. Emacs can't do anything else until @code{diff} finishes.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 Perhaps in the future someone will change Emerge to do the comparison in
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 the background when the input files are large---then you could keep on
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267 doing other things with Emacs until Emerge is ready to accept
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268 commands.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270 @vindex emerge-startup-hook
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271 After setting up the merge, Emerge runs the hook
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272 @code{emerge-startup-hook} (@pxref{Hooks}).