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