Commit | Line | Data |
---|---|---|
f9f999d9 | 1 | .\" Copyright (c) 1992, 2001 Free Software Foundation |
a933dad1 | 2 | .\" See section COPYING for conditions for redistribution |
544b00c1 | 3 | .TH etags 1 "23nov2001" "GNU Tools" "GNU Tools" |
a933dad1 DL |
4 | .de BP |
5 | .sp | |
6 | .ti -.2i | |
7 | \(** | |
8 | .. | |
9 | ||
10 | .SH NAME | |
11 | etags, ctags \- generate tag file for Emacs, vi | |
12 | .SH SYNOPSIS | |
13 | .hy 0 | |
14 | .na | |
e6dd1a49 | 15 | \fBetags\fP [\|\-aCDGImRVh\|] [\|\-i \fIfile\fP\|] [\|\-l \fIlanguage\fP\|] |
8dc78b52 | 16 | .if n .br |
e6dd1a49 | 17 | [\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|] |
0f374b8b | 18 | [\|\-\-parse\-stdin=\fIfile\fP\|] |
8dc78b52 | 19 | .br |
e6dd1a49 | 20 | [\|\-\-append\|] [\|\-\-no\-defines\|] |
8dc78b52 FP |
21 | [\|\-\-no\-globals\|] [\|\-\-include=\fIfile\fP\|] |
22 | [\|\-\-ignore\-indentation\|] [\|\-\-language=\fIlanguage\fP\|] | |
23 | [\|\-\-members\|] [\|\-\-output=\fItagfile\fP\|] | |
24 | [\|\-\-regex=\fIregexp\fP\|] [\|\-\-no\-regex\|] | |
25 | [\|\-\-help\|] [\|\-\-version\|] | |
26 | \fIfile\fP .\|.\|. | |
a933dad1 | 27 | |
e6dd1a49 | 28 | \fBctags\fP [\|\-aCdgImRVh\|] [\|\-BtTuvwx\|] [\|\-l \fIlanguage\fP\|] |
8dc78b52 | 29 | .if n .br |
e6dd1a49 | 30 | [\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|] |
0f374b8b | 31 | [\|\-\-parse\-stdin=\fIfile\fP\|] |
8dc78b52 | 32 | .br |
e6dd1a49 | 33 | [\|\-\-append\|] [\|\-\-backward\-search\|] |
8dc78b52 FP |
34 | [\|\-\-cxref\|] [\|\-\-defines\|] [\|\-\-forward\-search\|] |
35 | [\|\-\-globals\|] [\|\-\-ignore\-indentation\|] | |
36 | [\|\-\-language=\fIlanguage\fP\|] [\|\-\-members\|] | |
37 | [\|\-\-output=\fItagfile\fP\|] [\|\-\-regex=\fIregexp\fP\|] | |
38 | [\|\-\-typedefs\|] [\|\-\-typedefs\-and\-c++\|] | |
39 | [\|\-\-update\|] [\|\-\-no\-warn\|] | |
a933dad1 | 40 | [\|\-\-help\|] [\|\-\-version\|] |
8dc78b52 | 41 | \fIfile\fP .\|.\|. |
a933dad1 DL |
42 | .ad b |
43 | .hy 1 | |
44 | .SH DESCRIPTION | |
f9f999d9 | 45 | The \|\fBetags\fP\| program is used to create a tag table file, in a format |
a933dad1 DL |
46 | understood by |
47 | .BR emacs ( 1 )\c | |
f9f999d9 | 48 | \&; the \|\fBctags\fP\| program is used to create a similar table in a |
a933dad1 DL |
49 | format understood by |
50 | .BR vi ( 1 )\c | |
51 | \&. Both forms of the program understand | |
2c37653c | 52 | the syntax of C, Objective C, C++, Java, Fortran, Ada, Cobol, Erlang, HTML, |
e94a3679 | 53 | LaTeX, Emacs Lisp/Common Lisp, makefiles, Pascal, Perl, PHP, Postscript, |
e6dd1a49 | 54 | Python, Prolog, Scheme and |
8dc78b52 | 55 | most assembler\-like syntaxes. |
a933dad1 | 56 | Both forms read the files specified on the command line, and write a tag |
f9f999d9 | 57 | table (defaults: \fBTAGS\fP for \fBetags\fP, \fBtags\fP for |
a933dad1 DL |
58 | \fBctags\fP) in the current working directory. |
59 | Files specified with relative file names will be recorded in the tag | |
60 | table with file names relative to the directory where the tag table | |
61 | resides. Files specified with absolute file names will be recorded | |
0eaa5fcc FP |
62 | with absolute file names. Files generated from a source file\-\-like |
63 | a C file generated from a source Cweb file\-\-will be recorded with | |
64 | the name of the source file. | |
a933dad1 | 65 | The programs recognize the language used in an input file based on its |
f9f999d9 | 66 | file name and contents. The \fB\-\-language\fP switch can be used to force |
a933dad1 DL |
67 | parsing of the file names following the switch according to the given |
68 | language, overriding guesses based on filename extensions. | |
69 | .SH OPTIONS | |
70 | Some options make sense only for the \fBvi\fP style tag files produced | |
71 | by ctags; | |
72 | \fBetags\fP does not recognize them. | |
73 | The programs accept unambiguous abbreviations for long option names. | |
74 | .TP | |
75 | .B \-a, \-\-append | |
f9f999d9 | 76 | Append to existing tag file. (For \fBvi\fP-format tag files, see also |
a933dad1 DL |
77 | \fB\-\-update\fP.) |
78 | .TP | |
79 | .B \-B, \-\-backward\-search | |
80 | Tag files written in the format expected by \fBvi\fP contain regular | |
81 | expression search instructions; the \fB\-B\fP option writes them using | |
82 | the delimiter `\|\fB?\fP\|', to search \fIbackwards\fP through files. | |
83 | The default is to use the delimiter `\|\fB/\fP\|', to search \fIforwards\fP | |
84 | through files. | |
85 | Only \fBctags\fP accepts this option. | |
86 | .TP | |
8dc78b52 FP |
87 | .B \-\-declarations |
88 | In C and derived languages, create tags for function declarations, | |
89 | and create tags for extern variables unless \-\-no\-globals is used. | |
90 | .TP | |
a933dad1 | 91 | .B \-d, \-\-defines |
8dc78b52 FP |
92 | Create tag entries for C preprocessor constant definitions |
93 | and enum constants, too. This is the | |
94 | default behavior for \fBetags\fP. | |
a933dad1 DL |
95 | .TP |
96 | .B \-D, \-\-no\-defines | |
8dc78b52 FP |
97 | Do not create tag entries for C preprocessor constant definitions |
98 | and enum constants. | |
a933dad1 | 99 | This may make the tags file much smaller if many header files are tagged. |
8dc78b52 FP |
100 | This is the default behavior for \fBctags\fP. |
101 | .TP | |
102 | .B \-g, \-\-globals | |
103 | Create tag entries for global variables in C, C++, Objective C, Java, | |
104 | and Perl. | |
105 | This is the default behavior for \fBetags\fP. | |
106 | .TP | |
107 | .B \-G, \-\-no\-globals | |
108 | Do not tag global variables. Typically this reduces the file size by | |
109 | one fourth. This is the default behavior for \fBctags\fP. | |
110 | .TP | |
111 | \fB\-i\fP \fIfile\fP, \fB\-\-include=\fIfile\fP | |
112 | Include a note in the tag file indicating that, when searching for a | |
113 | tag, one should also consult the tags file \fIfile\fP after checking the | |
114 | current file. This options is only accepted by \fBetags\fP. | |
115 | .TP | |
116 | .B \-I, \-\-ignore\-indentation | |
117 | Don't rely on indentation as much as we normally do. Currently, this | |
118 | means not to assume that a closing brace in the first column is the | |
119 | final brace of a function or structure definition in C and C++. | |
a933dad1 DL |
120 | .TP |
121 | \fB\-l\fP \fIlanguage\fP, \fB\-\-language=\fIlanguage\fP | |
122 | Parse the following files according to the given language. More than | |
123 | one such options may be intermixed with filenames. Use \fB\-\-help\fP | |
124 | to get a list of the available languages and their default filename | |
125 | extensions. The `auto' language can be used to restore automatic | |
e6dd1a49 | 126 | detection of language based on the file name. The `none' |
a933dad1 DL |
127 | language may be used to disable language parsing altogether; only |
128 | regexp matching is done in this case (see the \fB\-\-regex\fP option). | |
129 | .TP | |
8dc78b52 FP |
130 | .B \-m, \-\-members |
131 | Create tag entries for variables that are members of structure-like | |
132 | constructs in C++, Objective C, Java. | |
133 | .TP | |
134 | .B \-M, \-\-no\-members | |
135 | Do not tag member variables. This is the default behavior. | |
136 | .TP | |
137 | .B \-\-packages\-only | |
138 | Only tag packages in Ada files. | |
139 | .TP | |
0f374b8b FP |
140 | \fB\-\-parse\-stdin=\fIfile\fP |
141 | May be used (only once) in place of a file name on the command line. | |
5cc4f104 | 142 | \fBetags\fP will read from standard input and mark the produced tags |
0f374b8b FP |
143 | as belonging to the file \fBFILE\fP. |
144 | .TP | |
a933dad1 | 145 | \fB\-o\fP \fItagfile\fP, \fB\-\-output=\fItagfile\fP |
f9f999d9 EZ |
146 | Explicit name of file for tag table; overrides default \fBTAGS\fP or |
147 | \fBtags\fP. (But ignored with \fB\-v\fP or \fB\-x\fP.) | |
a933dad1 DL |
148 | .TP |
149 | \fB\-r\fP \fIregexp\fP, \fB\-\-regex=\fIregexp\fP | |
6861f0e3 FP |
150 | |
151 | Make tags based on regexp matching for the files following this option, | |
152 | in addition to the tags made with the standard parsing based on | |
153 | language. May be freely intermixed with filenames and the \fB\-R\fP | |
154 | option. The regexps are cumulative, i.e. each such option will add to | |
df3eebcb | 155 | the previous ones. The regexps are of one of the forms: |
a933dad1 | 156 | .br |
df3eebcb FP |
157 | [\fB{\fP\fIlanguage\fP\fB}\fP]\fB/\fP\fItagregexp/\fP[\fInameregexp\fP\fB/\fP]\fImodifiers\fP |
158 | .br | |
159 | \fB@\fP\fIregexfile\fP | |
a933dad1 DL |
160 | .br |
161 | ||
6861f0e3 FP |
162 | where \fItagregexp\fP is used to match the tag. It should not match |
163 | useless characters. If the match is such that more characters than | |
164 | needed are unavoidably matched by \fItagregexp\fP, it may be useful to | |
165 | add a \fInameregexp\fP, to narrow down the tag scope. \fBctags\fP | |
166 | ignores regexps without a \fInameregexp\fP. The syntax of regexps is | |
167 | the same as in emacs. The following character escape sequences are | |
168 | supported: \\a, \\b, \\d, \\e, \\f, \\n, \\r, \\t, \\v, which | |
169 | respectively stand for the ASCII characters BEL, BS, DEL, ESC, FF, NL, | |
170 | CR, TAB, VT. | |
171 | .br | |
172 | The \fImodifiers\fP are a sequence of 0 or more characters among | |
173 | \fIi\fP, which means to ignore case when matching; \fIm\fP, which means | |
174 | that the \fItagregexp\fP will be matched against the whole file contents | |
175 | at once, rather than line by line, and the matching sequence can match | |
176 | multiple lines; and \fIs\fP, which implies \fIm\fP and means that the | |
177 | dot character in \fItagregexp\fP matches the newline char as well. | |
df3eebcb | 178 | .br |
3bc04ecc FP |
179 | The separator, which is \fB/\fP in the examples, can be any character |
180 | different from space, tab, braces and \fB@\fP. If the separator | |
181 | character is needed inside the regular expression, it must be quoted | |
182 | by preceding it with \fB\\\fP. | |
183 | .br | |
184 | The optional \fB{\fP\fIlanguage\fP\fB}\fP prefix means that the tag | |
185 | should be | |
df3eebcb FP |
186 | created only for files of language \fIlanguage\fP, and ignored |
187 | otherwise. This is particularly useful when storing many predefined | |
188 | regexps in a file. | |
189 | .br | |
3bc04ecc FP |
190 | In its second form, \fIregexfile\fP is the name of a file that contains |
191 | a number of arguments to the \fI\-\-regex\=\fP option, | |
192 | one per line. Lines beginning with a space or tab are assumed | |
df3eebcb | 193 | to be comments, and ignored. |
b4b39c67 | 194 | |
a933dad1 DL |
195 | .br |
196 | Here are some examples. All the regexps are quoted to protect them | |
197 | from shell interpretation. | |
198 | .br | |
199 | ||
200 | Tag the DEFVAR macros in the emacs source files: | |
201 | .br | |
202 | \fI\-\-regex\='/[ \\t]*DEFVAR_[A-Z_ \\t(]+"\\([^"]+\\)"\/'\fP | |
e94a3679 | 203 | .\"" This comment is to avoid confusion to Emacs syntax highlighting |
a933dad1 DL |
204 | .br |
205 | ||
206 | Tag VHDL files (this example is a single long line, broken here for | |
207 | formatting reasons): | |
208 | .br | |
209 | \fI\-\-language\=none\ \-\-regex='/[\ \\t]*\\(ARCHITECTURE\\|\\ | |
210 | CONFIGURATION\\)\ +[^\ ]*\ +OF/'\ \-\-regex\='/[\ \\t]*\\ | |
211 | \\(ATTRIBUTE\\|ENTITY\\|FUNCTION\\|PACKAGE\\(\ BODY\\)?\\ | |
212 | \\|PROCEDURE\\|PROCESS\\|TYPE\\)[\ \\t]+\\([^\ \\t(]+\\)/\\3/'\fP | |
213 | .br | |
214 | ||
a933dad1 DL |
215 | Tag TCL files (this last example shows the usage of a \fItagregexp\fP): |
216 | .br | |
217 | \fI\-\-lang\=none \-\-regex\='/proc[\ \\t]+\\([^\ \\t]+\\)/\\1/'\fP | |
218 | ||
caac7f2c | 219 | .br |
e6dd1a49 | 220 | A regexp can be preceded by {\fIlang\fP}, thus restricting it to match |
f9f999d9 EZ |
221 | lines of files of the specified language. Use \fBetags --help\fP to obtain |
222 | a list of the recognised languages. This feature is particularly useful inside | |
223 | \fBregex files\fP. A regex file contains one regex per line. Empty lines, | |
caac7f2c FP |
224 | and those lines beginning with space or tab are ignored. Lines beginning |
225 | with @ are references to regex files whose name follows the @ sign. Other | |
f9f999d9 | 226 | lines are considered regular expressions like those following \fB\-\-regex\fP. |
caac7f2c FP |
227 | .br |
228 | For example, the command | |
229 | .br | |
f9f999d9 | 230 | \fIetags \-\-regex=@regex.file *.c\fP |
caac7f2c FP |
231 | .br |
232 | reads the regexes contained in the file regex.file. | |
a933dad1 DL |
233 | .TP |
234 | .B \-R, \-\-no\-regex | |
235 | Don't do any more regexp matching on the following files. May be | |
236 | freely intermixed with filenames and the \fB\-\-regex\fP option. | |
237 | .TP | |
a933dad1 | 238 | .B \-t, \-\-typedefs |
f76041d5 | 239 | Record typedefs in C code as tags. Since this is the default behavior |
a933dad1 DL |
240 | of \fBetags\fP, only \fBctags\fP accepts this option. |
241 | .TP | |
242 | .B \-T, \-\-typedefs\-and\-c++ | |
243 | Generate tag entries for typedefs, struct, enum, and union tags, and | |
f76041d5 | 244 | C++ member functions. Since this is the default behavior |
a933dad1 DL |
245 | of \fBetags\fP, only \fBctags\fP accepts this option. |
246 | .TP | |
247 | .B \-u, \-\-update | |
248 | Update tag entries for \fIfiles\fP specified on command line, leaving | |
249 | tag entries for other files in place. Currently, this is implemented | |
250 | by deleting the existing entries for the given files and then | |
251 | rewriting the new entries at the end of the tags file. It is often | |
252 | faster to simply rebuild the entire tag file than to use this. | |
253 | Only \fBctags\fP accepts this option. | |
254 | .TP | |
255 | .B \-v, \-\-vgrind | |
256 | Instead of generating a tag file, write index (in \fBvgrind\fP format) | |
257 | to standard output. Only \fBctags\fP accepts this option. | |
258 | .TP | |
259 | .B \-w, \-\-no\-warn | |
260 | Suppress warning messages about duplicate entries. The \fBetags\fP | |
261 | program does not check for duplicate entries, so this option is not | |
262 | allowed with it. | |
263 | .TP | |
264 | .B \-x, \-\-cxref | |
265 | Instead of generating a tag file, write a cross reference (in | |
266 | \fBcxref\fP format) to standard output. Only \fBctags\fP accepts this option. | |
267 | .TP | |
8dc78b52 | 268 | .B \-h, \-H, \-\-help |
a933dad1 DL |
269 | Print usage information. |
270 | .TP | |
271 | .B \-V, \-\-version | |
272 | Print the current version of the program (same as the version of the | |
273 | emacs \fBetags\fP is shipped with). | |
274 | ||
275 | .SH "SEE ALSO" | |
276 | `\|\fBemacs\fP\|' entry in \fBinfo\fP; \fIGNU Emacs Manual\fP, Richard | |
277 | Stallman. | |
278 | .br | |
279 | .BR cxref ( 1 ), | |
280 | .BR emacs ( 1 ), | |
281 | .BR vgrind ( 1 ), | |
282 | .BR vi ( 1 ). | |
283 | ||
284 | .SH COPYING | |
e6dd1a49 | 285 | Copyright |
8cd13fd1 EZ |
286 | .if t \(co |
287 | .if n (c) | |
288 | 1999, 2001 Free Software Foundation, Inc. | |
a933dad1 | 289 | .PP |
544b00c1 EZ |
290 | Permission is granted to make and distribute verbatim copies of this |
291 | document provided the copyright notice and this permission notice are | |
292 | preserved on all copies. | |
a933dad1 | 293 | .PP |
544b00c1 EZ |
294 | Permission is granted to copy and distribute modified versions of |
295 | this document under the conditions for verbatim copying, provided that | |
296 | the entire resulting derived work is distributed under the terms of | |
297 | a permission notice identical to this one. | |
298 | .PP | |
299 | Permission is granted to copy and distribute translations of this | |
300 | document into another language, under the above conditions for | |
301 | modified versions, except that this permission notice may be stated | |
302 | in a translation approved by the Free Software Foundation. |