annotate man/maintaining.texi @ 70148:a2348b30cc21

(restore_menu_items, save_menu_items): New functions from xmenu.c. (set_frame_menubar, digest_single_submenu): Apply 2006-04-18 changes for xmenu.c.
author YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp>
date Fri, 21 Apr 2006 07:56:47 +0000
parents 91970b147f39
children 4b75ae0fccd3 e3bacb89536a
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 @end menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
19 @node Change Log
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 @section Change Logs
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
22 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
23 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
24 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
25 @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
26 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
27 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
28 subdirectories.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
29
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 @cindex change log
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 @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
32 @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
33 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
34 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
35 (@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
36 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
37 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
38 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
39
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
40 @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
41 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
42 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
43 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
44 changed.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
45
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
46 @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
47 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
48 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
49 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
50
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
51 @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
52 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
53 @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
54 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
55
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
56 @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
57 @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
58 @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
59 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
60 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
61 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
62 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
63 @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
64
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
65 @cindex Change Log mode
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
66 @findex change-log-mode
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
67 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
68 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
69 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
70 @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
71 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
72
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
73 @findex change-log-merge
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
74 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
75 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
76 ordering of entries.
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
77
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
78 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
79 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
80
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
81 @node Format of ChangeLog
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
82 @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
83
61200
710c5be02d52 (Change Log): add-change-log-entry uses add-log-mailing-address.
Lute Kamstra <lute@gnu.org>
parents: 59798
diff changeset
84 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
85 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
86 @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
87 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
88 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
89 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
90 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
91
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
92 @iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
93 @medbreak
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 @end iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
95 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 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
97
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 * 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
99 (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
100
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 * 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
102 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
103
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 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
105
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 * 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
107 (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
108 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 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
111 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
112 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
113 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
114 between them.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
116 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
117 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
118
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
119 @example
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
120 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
121 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
122 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
123 @end example
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 @noindent
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
126 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
127
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 @node Tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 @section Tags Tables
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 @cindex tags table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132 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
133 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
134 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
135 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
136 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
137 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
138 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
139
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 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
141 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
142
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143 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
144 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
145 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
146 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
147 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
148 file.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 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
151 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
152 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
153 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
154 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
155
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 @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
157 @cindex tags, C++
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @cindex class browser, C++
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @cindex Ebrowse
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 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
161 @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
162
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 @menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 * 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
165 * 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
166 * 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
167 * 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
168 * 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
169 * 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
170 * 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
171 @end menu
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @node Tag Syntax
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 @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
175
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 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
177
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 @itemize @bullet
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 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
181 @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
182 @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
183 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
184 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
185 @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
186 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
187
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
188 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
189 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
190 @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
191 option.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 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
195 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
196 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
197 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
198 @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
199 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
200
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
201 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
202 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
203 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
204 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
205 @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
206
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208 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
209 @code{\section}, @code{\subsection}, @code{\subsubsection},
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
210 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
211 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
46918
82d113655734 Minor spelling and grammar corrections.
Paul Eggert <eggert@twinsun.com>
parents: 46239
diff changeset
212 @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
213 @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
214
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 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
216 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
217 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
218 command names. For example,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 @example
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
221 TEXTAGS="mycommand:myothercommand"
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222 export TEXTAGS
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 @noindent
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
226 specifies (using Bourne shell syntax) that the commands
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
227 @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
228
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230 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
231 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
232 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
233 a tag.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 In 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
237 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
238 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
239 @end itemize
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 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
242
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 @itemize @bullet
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 @item
49123
3e1dde9764c0 Added reference to the new `etags --help --lang=LANG' option.
Francesco Potortì <pot@gnu.org>
parents: 47085
diff changeset
246 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
247 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
248 packages only.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 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
251 (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
252 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
253 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
254 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
255 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
256
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 @table @samp
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 @item /b
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 package body.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 @item /f
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 function.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 @item /k
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 task.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 @item /p
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 procedure.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 @item /s
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 package spec.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 @item /t
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 type.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
272 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
273 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
274 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
275 @code{bidule}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
278 In 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
279 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
280
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
281 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
282 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
283 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
284 as C code.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 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
288 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
289
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
290 @item
49123
3e1dde9764c0 Added reference to the new `etags --help --lang=LANG' option.
Francesco Potortì <pot@gnu.org>
parents: 47085
diff changeset
291 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
292 in the file.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294 @item
39267
a8c0a02f6129 Spelling corrections.
Richard M. Stallman <rms@gnu.org>
parents: 39082
diff changeset
295 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
296
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 @item
47085
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
298 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
299 @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
300 and all occurrences of @code{id=}.
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
301
a881d14145d0 etags now parses HTML.
Francesco Potortì <pot@gnu.org>
parents: 46918
diff changeset
302 @item
57087
be3afbddb35b Added support in etags for the Lua script language.
Francesco Potortì <pot@gnu.org>
parents: 52401
diff changeset
303 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
304
be3afbddb35b Added support in etags for the Lua script language.
Francesco Potortì <pot@gnu.org>
parents: 52401
diff changeset
305 @item
45919
Francesco Potortì <pot@gnu.org>
parents: 45887
diff changeset
306 In makefiles, targets are tags; additionally, variables are tags
Francesco Potortì <pot@gnu.org>
parents: 45887
diff changeset
307 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
308
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 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
311 class categories, methods and protocols. Tags for variables and
42342
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
312 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
313 @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
314
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 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
317 the file.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 @item
42342
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
320 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
321 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
322 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
323 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
324 name for subroutines defined in the default package is
edeb3d66b7e0 Perl changes for etags.
Francesco Potortì <pot@gnu.org>
parents: 42201
diff changeset
325 @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
326
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 @item
42043
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
328 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
329 @samp{--members} option, vars are tags too.
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
330
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
331 @item
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 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
333
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
334 @item
42043
0fe5fe39786c Etags changes for Prolog and PHP.
Francesco Potortì <pot@gnu.org>
parents: 41864
diff changeset
335 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
336 line.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
338 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 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
340 generate a tag.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
341 @end itemize
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
342
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
343 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
344 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
345
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
346 @node Create Tags Table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 @subsection Creating Tags Tables
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348 @cindex @code{etags} program
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
349
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 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
351 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
352 @iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 the previous section.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
354 @end iftex
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
355 @ifinfo
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356 @ref{Tag Syntax}.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357 @end ifinfo
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
358 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
359
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
361 etags @var{inputfiles}@dots{}
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
363
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
364 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
365 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
366 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
367
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 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
369 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
370 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
371 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
372 does not exist.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 @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
375 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
376 @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
377
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 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
379 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
380 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
381 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
382 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
383 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
384 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
385 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
386 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
387 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
388
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
389 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
390 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
391 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
392 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
393
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394 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
395 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
396 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
397 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
398 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
399
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 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
401 @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
402 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
403 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
404 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
405 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
406 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
407 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
408
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
409 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
410 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
411 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
412 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
413 @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
414
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 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
416 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
417 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
418 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
419 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
420
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 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
423 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 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
426 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
427 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
428 @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
429 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
430 @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
431 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
432 (@pxref{Etags Regexps}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433
45659
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
434 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
435 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
436 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
437 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
438 @var{file}.
c1e620d6140c Document --parse-stdin=FILE for Etags.
Francesco Potortì <pot@gnu.org>
parents: 43856
diff changeset
439
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
440 @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
441 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
442 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
443 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
444 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
445 @var{lang}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 @node Etags Regexps
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 @subsection Etags Regexps
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 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
451 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
452 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
453 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
454 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
455
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456 @smallexample
45801
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
457 --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
458 @end smallexample
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
459
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
460 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
461 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
462 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
463 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
464 with @samp{[ \t]*}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
466 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
467 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
468 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
469 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
470 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
471
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
472 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
473 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
474 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
475 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
476 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
477 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
478 below.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
480 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
481 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
482 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
483 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
484
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
485 @table @samp
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
486 @item i
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
487 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
488 @item m
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
489 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
490 multi-line matches are possible.
45801
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
491 @item s
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
492 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
493 @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
494 @end table
0cbd872ef18b New multi-line regexp and new regexp syntax.
Francesco Potortì <pot@gnu.org>
parents: 45669
diff changeset
495
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
496 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
497 @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
498 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
499
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
500 @smallexample
45886
22138a27a5f3 Specify that the separator character can be different from a slash.
Francesco Potortì <pot@gnu.org>
parents: 45801
diff changeset
501 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
502 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
503 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
504
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 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
507 @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
508 @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
509 @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
510 @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
511 @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
512 @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
513 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
514 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
515 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
516
45887
8aa6e4d588ce some passive forms to active
Francesco Potortì <pot@gnu.org>
parents: 45886
diff changeset
517 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
518 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
519 (@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
520 @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
521 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
522 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
523 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
524
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 --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
527 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 @noindent
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
530 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
531 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
532 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
533 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
534
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
535 @smallexample
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
536 --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
537 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @noindent
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
540 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
541 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
542 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
543 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
544 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
545 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
546 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
547
46239
6d4eadedbff1 Describe add-log-always-start-new-record.
Richard M. Stallman <rms@gnu.org>
parents: 45919
diff changeset
548 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
549 following contents:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
552 -- 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
553 @{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
554 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 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
558
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
560 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
561 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 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
564 from shell interpretation.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 @itemize @bullet
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 Tag Octave files:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 etags --language=none \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 --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
574 --regex='/###key \(.*\)/\1/' \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 --regex='/[ \t]*global[ \t].*/' \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 *.m
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 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
581 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
582 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
583
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585 Tag Tcl files:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 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
589 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 @item
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592 Tag VHDL files:
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
594 @smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
595 etags --language=none \
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
596 --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
597 --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
598 \( 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
599 @end smallexample
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
600 @end itemize
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
601
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 @node Select Tags Table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 @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
604
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
605 @vindex tags-file-name
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 @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
607 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
608 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
609 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
610 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
611 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
612
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
613 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
614 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
615 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
616 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
617 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
618 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
619
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 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
621 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
622 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
623 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
624 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
625 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
626
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @vindex tags-table-list
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 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
629 @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
630
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 @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
632 @example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 @group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 (setq tags-table-list
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 '("~/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
636 @end group
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @end example
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 @noindent
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640 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
641 @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
642 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
643 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
644
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 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
646
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647 @node Find Tag
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 @subsection Finding a Tag
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 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
651 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
652
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654 @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
655 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
656 @item C-u M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
657 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
658 @item C-u - M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 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
660 @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
661 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
662 @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
663 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
664 @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
665 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
666 (@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
667 @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
668 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
669 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
670 @item M-*
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 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
672 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @kindex M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 @findex find-tag
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 @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
677 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
678 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
679 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
680 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
681 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
682 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
683
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684 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
685 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
686 @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
687
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 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
689 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
690 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
691 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
692 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
693 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
694 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
695 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
696 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
697
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 @kindex C-x 4 .
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 @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
700 @kindex C-x 5 .
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 @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
702 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
703 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
704 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
705 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
706 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
707
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 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
709 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
710 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
711 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
712
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713 @kindex M-*
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714 @findex pop-tag-mark
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 @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
716 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
717 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
718 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
719 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
720 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
721
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 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
723 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
724
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 @findex find-tag-regexp
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726 @kindex C-M-.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 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
728 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
729 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
730
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 @node Tags Search
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @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
733 @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
734 @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
735
68693
f06d0aec15a7 (Format of ChangeLog): New node, split out from ChangeLog.
Richard M. Stallman <rms@gnu.org>
parents: 68639
diff changeset
736 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
737 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
738 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
739 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
740 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
741 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
742 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
743
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 @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
746 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
747 table.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 @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
749 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
750 @item M-,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 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
752 (@code{tags-loop-continue}).
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 @findex tags-search
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 @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
757 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
758 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
759 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
760 @code{tags-search} returns.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 @kindex M-,
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @findex tags-loop-continue
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 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
765 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
766 @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
767 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
768
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
769 @findex tags-query-replace
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770 @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
771 @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
772 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
773 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
774 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
775 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
776
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 @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
778 @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
779 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
780 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
781 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
782 @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
783
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 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
785 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
786 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
787 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
788 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
789 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
790
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 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
792 @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
793 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
794 @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
795 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
796 the current buffer.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 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
799 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
800 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
801 continue to exist.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 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
804 @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
805 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
806 @xref{Grep Searching}.
38198
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 @node List Tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 @subsection Tags Table Inquiries
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 @table @kbd
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812 @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
813 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
814 @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
815 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
816 @end table
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 @findex list-tags
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 @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
820 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
821 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
822 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
823 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
824 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
825 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
826 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
827 directory.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 @findex tags-apropos
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 @vindex tags-apropos-verbose
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 @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
832 (@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
833 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
834 @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
835 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
836
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 @vindex tags-tag-face
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 @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
839 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
840 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
841 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
842 @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
843 details.
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844
1381135c49a4 Initial version consists of sections moved from Editing Programs chapter.
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 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
846 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
847
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
848 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
849 arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49600
diff changeset
850 @end ignore