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