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