annotate man/maintaining.texi @ 69355:a685fca1ccb6

(USE_POSIX_MEMALIGN): Fix last change.
author Kim F. Storm <storm@cua.dk>
date Fri, 10 Mar 2006 08:10:24 +0000
parents 1ccf0b1b5b01
children 91970b147f39 9e490faa9f6b
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.
61200
710c5be02d52 (Change Log): add-change-log-entry uses add-log-mailing-address.
Lute Kamstra <lute@gnu.org>
parents: 59798
diff changeset
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
68639
dc2d5a6655a3 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64951
diff changeset
3 @c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
4 @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
5 @node Maintaining, Abbrevs, Building, Top
68823
63d1645b9198 (Maintaining): Change title; clarify topic. Delete duplicate index entries.
Richard M. Stallman <rms@gnu.org>
parents: 68693
diff changeset
6 @chapter Maintaining Large Programs
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7
68823
63d1645b9198 (Maintaining): Change title; clarify topic. Delete duplicate index entries.
Richard M. Stallman <rms@gnu.org>
parents: 68693
diff changeset
8 This chapter describes Emacs features for maintaining large
63d1645b9198 (Maintaining): Change title; clarify topic. Delete duplicate index entries.
Richard M. Stallman <rms@gnu.org>
parents: 68693
diff changeset
9 programs. The version control features (@pxref{Version Control}) are
63d1645b9198 (Maintaining): Change title; clarify topic. Delete duplicate index entries.
Richard M. Stallman <rms@gnu.org>
parents: 68693
diff changeset
10 also 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
11
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 @menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 * Change Log:: Maintaining a change history for your program.
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
14 * Format of ChangeLog:: What the change log file looks like.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 * 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
16 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
17 * 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
18 @end menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 @node Change Log
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 @section Change Logs
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
22
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
23 A change log file contains a chronological record of when and why you
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
24 have changed a program, consisting of a sequence of entries describing
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
25 individual changes. Normally it is kept in a file called
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
26 @file{ChangeLog} in the same directory as the file you are editing, or
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
27 one of its parent directories. A single @file{ChangeLog} file can
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
28 record changes for all the files in its directory and all its
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
29 subdirectories.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
30
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 @cindex change log
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 @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
33 @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
34 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
35 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
36 (@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
37 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
38 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
39 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
40
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
41 @kbd{C-x 4 a} visits the change log file and creates a new entry
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
42 unless the most recent entry is for today's date and your name. It
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
43 also creates a new item for the current file. For many languages, it
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
44 can even guess the name of the function or other object that was
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
45 changed.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
46
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
47 @vindex add-log-keep-changes-together
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
48 When the variable @code{add-log-keep-changes-together} is
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
49 non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
50 rather than starting a new item.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
51
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
52 @vindex add-log-always-start-new-record
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
53 If @code{add-log-always-start-new-record} is non-@code{nil},
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
54 @kbd{C-x 4 a} always makes a new entry, even if the last entry
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
55 was made by you and on the same date.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
57 @vindex change-log-version-info-enabled
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
58 @vindex change-log-version-number-regexp-list
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
59 @cindex file version in change log entries
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
60 If the value of the variable @code{change-log-version-info-enabled}
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
61 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
62 change log entry. It finds the version number by searching the first
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
63 ten percent of the file, using regular expressions from the variable
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
64 @code{change-log-version-number-regexp-list}.
39623
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
65
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
66 @cindex Change Log mode
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
67 @findex change-log-mode
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
68 The change log file is visited in Change Log mode. In this major
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
69 mode, each bunch of grouped items counts as one paragraph, and each
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
70 entry is considered a page. This facilitates editing the entries.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
71 @kbd{C-j} and auto-fill indent each new line like the previous line;
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
72 this is convenient for entering the contents of an entry.
39623
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
73
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
74 @findex change-log-merge
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
75 You can use the command @kbd{M-x change-log-merge} to merge other
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
76 log files into a buffer in Change Log Mode, preserving the date
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
77 ordering of entries.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
78
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
79 Version control systems are another way to keep track of changes in your
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
80 program and keep a change log. @xref{Log Buffer}.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
81
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
82 @node Format of ChangeLog
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
83 @section Format of ChangeLog
39623
eff57c5f75db Explain where and how to put the copyright notice and permission
Richard M. Stallman <rms@gnu.org>
parents: 39267
diff changeset
84
61200
710c5be02d52 (Change Log): add-change-log-entry uses add-log-mailing-address.
Lute Kamstra <lute@gnu.org>
parents: 59798
diff changeset
85 A change log entry starts with a header line that contains the current
710c5be02d52 (Change Log): add-change-log-entry uses add-log-mailing-address.
Lute Kamstra <lute@gnu.org>
parents: 59798
diff changeset
86 date, your name, and your email address (taken from the variable
710c5be02d52 (Change Log): add-change-log-entry uses add-log-mailing-address.
Lute Kamstra <lute@gnu.org>
parents: 59798
diff changeset
87 @code{add-log-mailing-address}). Aside from these header lines, every
710c5be02d52 (Change Log): add-change-log-entry uses add-log-mailing-address.
Lute Kamstra <lute@gnu.org>
parents: 59798
diff changeset
88 line in the change log starts with a space or a tab. The bulk of the
710c5be02d52 (Change Log): add-change-log-entry uses add-log-mailing-address.
Lute Kamstra <lute@gnu.org>
parents: 59798
diff changeset
89 entry consists of @dfn{items}, each of which starts with a line starting
710c5be02d52 (Change Log): add-change-log-entry uses add-log-mailing-address.
Lute Kamstra <lute@gnu.org>
parents: 59798
diff changeset
90 with whitespace and a star. Here are two entries, both dated in May
61466
0d13c2e5baa9 (Change Log): Correct the description of the example.
Richard M. Stallman <rms@gnu.org>
parents: 61200
diff changeset
91 1993, with two items and one item respectively.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 @iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 @medbreak
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 @end iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97 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
98
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 * 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
100 (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
101
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 * 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
103 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
104
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 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
106
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107 * 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
108 (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
109 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 One entry can describe several changes; each change should have its
61466
0d13c2e5baa9 (Change Log): Correct the description of the example.
Richard M. Stallman <rms@gnu.org>
parents: 61200
diff changeset
112 own item, or its own line in an item. Normally there should be a
0d13c2e5baa9 (Change Log): Correct the description of the example.
Richard M. Stallman <rms@gnu.org>
parents: 61200
diff changeset
113 blank line between items. When items are related (parts of the same
0d13c2e5baa9 (Change Log): Correct the description of the example.
Richard M. Stallman <rms@gnu.org>
parents: 61200
diff changeset
114 change, in different places), group them by leaving no blank line
0d13c2e5baa9 (Change Log): Correct the description of the example.
Richard M. Stallman <rms@gnu.org>
parents: 61200
diff changeset
115 between them.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
117 You should put a copyright notice and permission notice at the
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
118 end of the change log file. Here is an example:
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
120 @example
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
121 Copyright 1997, 1998 Free Software Foundation, Inc.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
122 Copying and distribution of this file, with or without modification, are
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
123 permitted provided the copyright notice and this notice are preserved.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
124 @end example
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 @noindent
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
127 Of course, you should substitute the proper years and copyright holder.
38198
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 @node Tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 @section Tags Tables
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @cindex tags table
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 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
134 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
135 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
136 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
137 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
138 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
139 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
140
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 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
142 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
143
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
144 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
145 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
146 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
147 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
148 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
149 file.
38198
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 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
152 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
153 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
154 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
155 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
156
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157 @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
158 @cindex tags, C++
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @cindex class browser, C++
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 @cindex Ebrowse
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 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
162 @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
163
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 * 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
166 * 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
167 * 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
168 * 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
169 * 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
170 * 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
171 * 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
172 @end menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 @node Tag Syntax
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @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
176
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 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
178
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 @itemize @bullet
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 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
182 @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
183 @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
184 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
185 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
186 @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
187 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
188
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
189 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
190 to function definitions by giving the @samp{--declarations} option to
49123
3e1dde9764c0 Added reference to the new `etags --help --lang=LANG' option.
Francesco Potortì <pot@gnu.org>
parents: 47085
diff changeset
191 @code{etags}. You can tag struct members with the @samp{--members}
3e1dde9764c0 Added reference to the new `etags --help --lang=LANG' option.
Francesco Potortì <pot@gnu.org>
parents: 47085
diff changeset
192 option.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 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
196 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
197 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
198 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
199 @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
200 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
201
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
203 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
204 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
205 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
206 @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
207
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 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
210 @code{\section}, @code{\subsection}, @code{\subsubsection},
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
211 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
212 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
46918
82d113655734 Minor spelling and grammar corrections.
Paul Eggert <eggert@twinsun.com>
parents: 46239
diff changeset
213 @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
214 @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
215
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 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
217 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
218 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
219 command names. For example,
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 @example
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
222 TEXTAGS="mycommand:myothercommand"
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 export TEXTAGS
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 @noindent
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
227 specifies (using Bourne shell syntax) that the commands
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
228 @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
229
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
231 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
232 defined with @code{defvar} or @code{defconst}, and in general the first
49123
3e1dde9764c0 Added reference to the new `etags --help --lang=LANG' option.
Francesco Potortì <pot@gnu.org>
parents: 47085
diff changeset
233 argument of any expression that starts with @samp{(def} in column zero is
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 a tag.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 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
238 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
239 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
240 @end itemize
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 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
243
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 @itemize @bullet
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 @item
49123
3e1dde9764c0 Added reference to the new `etags --help --lang=LANG' option.
Francesco Potortì <pot@gnu.org>
parents: 47085
diff changeset
247 In Ada code, functions, procedures, packages, tasks and types are
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 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
249 packages only.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 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
252 (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
253 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
254 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
255 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
256 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
257
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 @table @samp
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 @item /b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 package body.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 @item /f
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 function.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 @item /k
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 task.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 @item /p
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 procedure.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 @item /s
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 package spec.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 @item /t
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 type.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 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
274 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
275 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
276 @code{bidule}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
279 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
280 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
281
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
283 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
284 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
285 as C code.
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 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
289 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
290
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 @item
49123
3e1dde9764c0 Added reference to the new `etags --help --lang=LANG' option.
Francesco Potortì <pot@gnu.org>
parents: 47085
diff changeset
292 In Erlang code, the tags are the functions, records and macros defined
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 in the file.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 @item
39267
a8c0a02f6129 Spelling corrections.
Richard M. Stallman <rms@gnu.org>
parents: 39082
diff changeset
296 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
297
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 @item
47085
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
299 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
300 @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
301 and all occurrences of @code{id=}.
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
302
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
303 @item
57087
be3afbddb35b Added support in etags for the Lua script language.
Francesco Potortì <pot@gnu.org>
parents: 52401
diff changeset
304 In Lua input files, all functions are tags.
be3afbddb35b Added support in etags for the Lua script language.
Francesco Potortì <pot@gnu.org>
parents: 52401
diff changeset
305
be3afbddb35b Added support in etags for the Lua script language.
Francesco Potortì <pot@gnu.org>
parents: 52401
diff changeset
306 @item
45919
Francesco Potortì <pot@gnu.org>
parents: 45887
diff changeset
307 In makefiles, targets are tags; additionally, variables are tags
Francesco Potortì <pot@gnu.org>
parents: 45887
diff changeset
308 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
309
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311 In Objective C code, tags include Objective C definitions for classes,
49123
3e1dde9764c0 Added reference to the new `etags --help --lang=LANG' option.
Francesco Potortì <pot@gnu.org>
parents: 47085
diff changeset
312 class categories, methods and protocols. Tags for variables and
42342
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
313 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
314 @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
315
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 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
318 the file.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 @item
42342
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
321 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
322 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
323 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
324 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
325 name for subroutines defined in the default package is
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
326 @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
327
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 @item
42043
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
329 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
330 @samp{--members} option, vars are tags too.
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
331
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
332 @item
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333 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
334
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
335 @item
42043
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
336 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
337 line.
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
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340 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
341 generate a tag.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342 @end itemize
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
344 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
345 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
346
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 @node Create Tags Table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 @subsection Creating Tags Tables
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349 @cindex @code{etags} program
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 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
352 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
353 @iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 the previous section.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 @end iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 @ifinfo
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 @ref{Tag Syntax}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 @end ifinfo
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 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
360
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 etags @var{inputfiles}@dots{}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 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
367 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
368
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 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
370 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
371 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
372 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
373 does not exist.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375 @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
376 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
377 @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
378
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379 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
380 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
381 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
382 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
383 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
384 position recorded in the tags table becomes a little bit wrong (due to
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
385 other editing), the worst consequence is a slight delay in finding the
38264
e781108d8f69 Clarify when it's good to update a tags table and why.
Richard M. Stallman <rms@gnu.org>
parents: 38261
diff changeset
386 tag. Even if the stored position is very far wrong, Emacs will still
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
387 find the tag, after searching most of the file for it. That delay is
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
388 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
389
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
390 Thus, there is no need to update the tags table after each edit.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
391 You should update a tags table when you define new tags that you want
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
392 to have listed, or when you move tag definitions from one file to
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
393 another, or when changes become substantial.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 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
396 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
397 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
398 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
399 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
400
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401 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
402 @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
403 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
404 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
405 source files, and the tags file will still refer correctly to the source
57102
5c078eb058f8 Put /dev into @file.
Francesco Potortì <pot@gnu.org>
parents: 57090
diff changeset
406 files. If the tags file is in @file{/dev}, however, the file names are
68927
1ccf0b1b5b01 (Create Tags Table): Explain why the exception when etags writes to
Francesco Potortì <pot@gnu.org>
parents: 68823
diff changeset
407 made relative to the current working directory. This is useful, for
1ccf0b1b5b01 (Create Tags Table): Explain why the exception when etags writes to
Francesco Potortì <pot@gnu.org>
parents: 68823
diff changeset
408 example, when writing the tags to @file{/dev/stdout}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
410 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
411 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
412 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
413 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
414 @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
415
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
416 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
417 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
418 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
419 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
420 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
421
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 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
424 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 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
427 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
428 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
429 @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
430 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
431 @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
432 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
433 (@pxref{Etags Regexps}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
435 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
436 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
437 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
438 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
439 @var{file}.
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
440
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
441 @samp{etags --help} outputs the list of the languages @code{etags}
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 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
443 a list of all the available @code{etags} options, together with a short
49123
3e1dde9764c0 Added reference to the new `etags --help --lang=LANG' option.
Francesco Potortì <pot@gnu.org>
parents: 47085
diff changeset
444 explanation. If followed by one or more @samp{--language=@var{lang}}
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
445 options, it outputs detailed information about how tags are generated for
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49123
diff changeset
446 @var{lang}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 @node Etags Regexps
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449 @subsection Etags Regexps
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 The @samp{--regex} option provides a general way of recognizing tags
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
452 based on regexp matching. You can freely intermix this option with
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
453 file names, and each one applies to the source files that follow it.
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
454 If you specify multiple @samp{--regex} options, all of them are used
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
455 in parallel. The syntax is:
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 @smallexample
45801
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
458 --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
459 @end smallexample
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
460
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
461 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
462 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
463 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
464 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
465 with @samp{[ \t]*}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
467 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
468 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
469 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
470 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
471 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
472
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
473 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
474 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
475 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
476 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
477 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
478 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
479 below.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
481 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
482 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
483 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
484 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
485
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
486 @table @samp
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
487 @item i
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
488 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
489 @item m
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
490 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
491 multi-line matches are possible.
45801
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
492 @item s
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
493 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
494 @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
495 @end table
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
496
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
497 The @samp{-R} option cancels all the regexps defined by preceding
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
498 @samp{--regex} options. It too applies to the file names following
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
499 it. Here's an example:
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
501 @smallexample
45886
22138a27a5f3 Specify that the separator character can be different from a slash.
Francesco Potortì <pot@gnu.org>
parents: 45801
diff changeset
502 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
503 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
504 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 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
508 @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
509 @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
510 @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
511 @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
512 @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
513 @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
514 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
515 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
516 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
517
45887
8aa6e4d588ce some passive forms to active
Francesco Potortì <pot@gnu.org>
parents: 45886
diff changeset
518 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
519 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
520 (@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
521 @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
522 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
523 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
524 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
525
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 --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
528 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530 @noindent
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
531 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
532 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
533 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
534 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
535
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 @smallexample
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
537 --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
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
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
541 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
542 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
543 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
544 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
545 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
546 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
547 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
548
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
549 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
550 following contents:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 -- 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
554 @{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
555 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 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
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 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
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 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
565 from shell interpretation.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567 @itemize @bullet
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 Tag Octave files:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 etags --language=none \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 --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
575 --regex='/###key \(.*\)/\1/' \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 --regex='/[ \t]*global[ \t].*/' \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 *.m
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 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
582 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
583 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
584
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 Tag Tcl files:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 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
590 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593 Tag VHDL files:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 etags --language=none \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
597 --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
598 --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
599 \( 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
600 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601 @end itemize
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 @node Select Tags Table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
604 @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
605
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 @vindex tags-file-name
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607 @findex visit-tags-table
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
608 Emacs has at any time one @dfn{selected} tags table, and all the
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
609 commands for working with tags tables use the selected one. To select
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
610 a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
611 table file name as an argument, with @file{TAGS} in the default
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
612 directory as the default.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
614 Emacs does not actually read in the tags table contents until you
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
615 try to use them; all @code{visit-tags-table} does is store the file
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
616 name in the variable @code{tags-file-name}, and setting the variable
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
617 yourself is just as good. The variable's initial value is @code{nil};
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
618 that value tells all the commands for working with tags tables that
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
619 they must ask for a tags table file name to use.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
621 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
622 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
623 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
624 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
625 is used @emph{instead} of others. If you add the new table to the
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
626 current list, it is used @emph{as well as} the others.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 @vindex tags-table-list
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
629 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
630 @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
631
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 @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
633 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 (setq tags-table-list
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 '("~/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
637 @end group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 @end example
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 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 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
642 @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
643 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
644 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
645
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 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
647
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 @node Find Tag
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 @subsection Finding a Tag
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 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
652 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
653
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
655 @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
656 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
657 @item C-u M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
658 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
659 @item C-u - M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 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
661 @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
662 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
663 @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
664 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
665 @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
666 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
667 (@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
668 @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
669 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
670 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
671 @item M-*
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 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
673 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 @kindex M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 @findex find-tag
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 @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
678 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
679 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
680 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
681 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
682 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
683 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
684
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 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
686 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
687 @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
688
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 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
690 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
691 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
692 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
693 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
694 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
695 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
696 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
697 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
698
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 @kindex C-x 4 .
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700 @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
701 @kindex C-x 5 .
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
702 @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
703 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
704 variant that displays the new buffer in another window, and one that
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
705 makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
706 the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}},
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 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
708
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 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
710 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
711 command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 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
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 pop-tag-mark
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 @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
717 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
718 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
719 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
720 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
721 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
722
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 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
724 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
725
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 @findex find-tag-regexp
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 @kindex C-M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 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
729 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
730 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
731
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @node Tags Search
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 @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
734 @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
735 @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
736
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
737 The commands in this section visit and search all the files listed
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
738 in the selected tags table, one by one. For these commands, the tags
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
739 table serves only to specify a sequence of files to search. These
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
740 commands scan the list of tags tables starting with the first tags
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
741 table (if any) that describes the current file, proceed from there to
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
742 the end of the list, and then scan from the beginning of the list
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
743 until they have covered all the tables in the list.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 @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
747 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
748 table.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 @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
750 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
751 @item M-,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 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
753 (@code{tags-loop-continue}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 @findex tags-search
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 @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
758 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
759 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
760 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
761 @code{tags-search} returns.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @kindex M-,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 @findex tags-loop-continue
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765 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
766 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
767 @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
768 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
769
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 @findex tags-query-replace
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 @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
772 @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
773 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
774 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
775 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
776 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
777
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 @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
779 @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
780 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
781 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
782 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
783 @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
784
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 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
786 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
787 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
788 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
789 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
790 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
791
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 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
793 @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
794 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
795 @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
796 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
797 the current buffer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 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
800 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
801 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
802 continue to exist.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 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
805 @code{grep}. You can also run @code{grep} itself as an inferior of
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
806 Emacs and have Emacs show you the matching lines one by one.
64951
74a593bdd0a2 (Tags Search): Replace grep xref to `Compilation' node
Juri Linkov <juri@jurta.org>
parents: 64890
diff changeset
807 @xref{Grep Searching}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 @node List Tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 @subsection Tags Table Inquiries
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 @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
814 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
815 @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
816 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
817 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 @findex list-tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820 @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
821 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
822 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
823 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
824 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
825 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
826 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
827 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
828 directory.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 @findex tags-apropos
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 @vindex tags-apropos-verbose
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 @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
833 (@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
834 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
835 @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
836 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
837
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 @vindex tags-tag-face
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 @vindex tags-apropos-additional-actions
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
840 You can customize the appearance of the output by setting the
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
841 variable @code{tags-tag-face} to a face. You can display additional
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
842 output with @kbd{M-x tags-apropos} by customizing the variable
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 @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
844 details.
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 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
847 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
848
38211
5ef494421061 Fix mistakes in @node Emerge.
Richard M. Stallman <rms@gnu.org>
parents: 38198
diff changeset
849 @node Emerge
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850 @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
851 @cindex Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 @cindex merging files
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
854 It's not unusual for programmers to get their signals crossed and
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
855 modify the same program in two different directions. To recover from
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
856 this confusion, you need to merge the two versions. Emerge makes this
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
857 easier. See also @ref{Comparing Files}, for other ways to compare
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
858 files, 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
859
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 @menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 * 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
862 * 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
863 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
864 * 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
865 for each difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866 * 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
867 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
868 * 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
869 * 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
870 * 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
871 @end menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 @node Overview of Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
874 @subsection Overview of Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
876 To start Emerge, run one of these four commands:
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
879 @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
880 @findex emerge-files
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
881 Merge two specified files.
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 @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
884 @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
885 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
886
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 @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
888 @findex emerge-buffers
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889 Merge two buffers.
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 @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
892 @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
893 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
894 buffer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895 @end table
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 @cindex merge buffer (Emerge)
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 @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
899 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
900 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
901 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
902 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
903 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
904 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
905
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 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
907 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
908 (@pxref{Narrowing}).
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 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
911 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
912 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
913 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
914 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
915 @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
916 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
917 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
918
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 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
920 interactive merging starts. You control the merging by typing special
62479
0659ac37d53c (Overview of Emerge): Add cross reference. Remove duplication.
Lute Kamstra <lute@gnu.org>
parents: 61466
diff changeset
921 @dfn{merge commands} in the merge buffer (@pxref{Merge Commands}).
0659ac37d53c (Overview of Emerge): Add cross reference. Remove duplication.
Lute Kamstra <lute@gnu.org>
parents: 61466
diff changeset
922 For each run of differences between the input texts, you can choose
0659ac37d53c (Overview of Emerge): Add cross reference. Remove duplication.
Lute Kamstra <lute@gnu.org>
parents: 61466
diff changeset
923 which one of them to keep, or edit them both together.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 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
926 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
927 ordinary Emacs commands.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
929 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
930 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
931 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
932
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 vvvvvvvvvvvvvvvvvvvv
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 @var{text that differs}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936 ^^^^^^^^^^^^^^^^^^^^
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 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
941 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
942
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 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
944 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
945 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
946
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 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
948 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
949 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
950 @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
951 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
952 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
953
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954 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
955 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
956 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
957
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
958 @node Submodes of Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
959 @subsection Submodes of Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
960
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 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
962 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
963 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
964 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
965 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
966 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
967 slows down Emerge operations.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 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
970 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
971 and @samp{F}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973 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
974 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
975
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 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
977 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
978 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
979 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
980
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981 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
982 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
983 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
984 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
985 @samp{S}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 @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
988 @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
989 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
990 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
991 (@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
992 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
993 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
994
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995 @node State of Difference
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996 @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
997
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998 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
999 @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
1000
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 @table @asis
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 @item A
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003 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
1004 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
1005
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006 @item B
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007 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
1008 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
1009
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 @item default-A
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011 @itemx default-B
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012 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
1013 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
1014 (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
1015 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
1016
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 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
1018 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
1019 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
1020 the mode line.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1021
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 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
1023 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
1024 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
1025 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
1026 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
1027 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
1028 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
1029 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
1030
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031 @item prefer-A
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 @itemx prefer-B
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 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
1034 @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
1035 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
1036 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
1037 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
1038 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
1039
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040 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
1041
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 @item combined
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043 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
1044 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
1045
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 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
1047 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
1048
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 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
1050 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052 @node Merge Commands
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 @subsection Merge Commands
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 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
1056 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
1057
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059 @item p
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 Select the previous difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 @item n
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 Select the next difference.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 @item a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 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
1067
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 @item b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 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
1070
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071 @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
1072 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
1073
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 @item .
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 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
1076 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
1077
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1078 @item q
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079 Quit---finish the merge.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081 @item C-]
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 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
1083
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084 @item f
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 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
1086
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087 @item e
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 Go into Edit mode.
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 @item l
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091 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
1092
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 @item -
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094 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
1095
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 @item @var{digit}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1097 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
1098
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099 @item d a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100 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
1101 the merge buffer.
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 d b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 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
1105 the merge buffer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107 @item c a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1108 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
1109
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110 @item c b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111 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
1112
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 @item i a
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114 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
1115
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116 @item i b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117 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
1118
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119 @item m
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1120 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
1121
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 @item ^
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 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
1124
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125 @item v
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126 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
1127
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 @item <
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129 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
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 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
1133
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 @item |
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 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
1136
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 @item x 1
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 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
1139 to full size.)
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 x c
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142 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
1143 Emerge}).
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 x f
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 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
1147 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
1148
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149 @item x j
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1150 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
1151 (@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
1152
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153 @item x s
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154 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
1155 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
1156 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
1157
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 @item x t
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 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
1160 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
1161 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
1162 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 @node Exiting Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165 @subsection Exiting Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167 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
1168 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
1169 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
1170 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
1171 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
1172 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
1173
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 @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
1175 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
1176 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
1177
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 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
1179 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
1180 abort.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 @node Combining in Emerge
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183 @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
1184
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185 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
1186 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
1187 like this:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190 @group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191 #ifdef NEW
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192 @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
1193 #else /* not NEW */
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194 @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
1195 #endif /* not NEW */
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196 @end group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1199 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1200 @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
1201 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
1202 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
1203 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
1204 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
1205 @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
1206 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
1207
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1208 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1209 @group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 "#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
1211 @end group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1213
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214 @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
1215 @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
1216
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217 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
1218 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
1219 they were.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221 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
1222 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
1223 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
1224
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225 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
1226 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
1227 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
1228 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
1229 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
1230 commands.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232 @vindex emerge-startup-hook
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 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
1234 @code{emerge-startup-hook} (@pxref{Hooks}).
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
1235
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
1236 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
1237 arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
1238 @end ignore