.\" Copyright (c) 1992, 2001 Free Software Foundation.\" See section COPYING for conditions for redistribution.TH etags 1 "23nov2001" "GNU Tools" "GNU Tools".de BP.sp.ti -.2i\(**...SH NAMEetags, ctags \- generate tag file for Emacs, vi.SH SYNOPSIS.hy 0.na\fBetags\fP [\|\-aCDGImRVh\|] [\|\-i \fIfile\fP\|] [\|\-l \fIlanguage\fP\|].if n .br[\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|][\|\-\-parse\-stdin=\fIfile\fP\|].br[\|\-\-append\|] [\|\-\-no\-defines\|][\|\-\-no\-globals\|] [\|\-\-include=\fIfile\fP\|][\|\-\-ignore\-indentation\|] [\|\-\-language=\fIlanguage\fP\|][\|\-\-members\|] [\|\-\-output=\fItagfile\fP\|][\|\-\-regex=\fIregexp\fP\|] [\|\-\-no\-regex\|][\|\-\-help\|] [\|\-\-version\|]\fIfile\fP .\|.\|.\fBctags\fP [\|\-aCdgImRVh\|] [\|\-BtTuvwx\|] [\|\-l \fIlanguage\fP\|].if n .br[\|\-o \fItagfile\fP\|] [\|\-r \fIregexp\fP\|][\|\-\-parse\-stdin=\fIfile\fP\|].br[\|\-\-append\|] [\|\-\-backward\-search\|][\|\-\-cxref\|] [\|\-\-defines\|] [\|\-\-forward\-search\|][\|\-\-globals\|] [\|\-\-ignore\-indentation\|][\|\-\-language=\fIlanguage\fP\|] [\|\-\-members\|][\|\-\-output=\fItagfile\fP\|] [\|\-\-regex=\fIregexp\fP\|][\|\-\-typedefs\|] [\|\-\-typedefs\-and\-c++\|][\|\-\-update\|] [\|\-\-no\-warn\|][\|\-\-help\|] [\|\-\-version\|]\fIfile\fP .\|.\|..ad b.hy 1.SH DESCRIPTIONThe \|\fBetags\fP\| program is used to create a tag table file, in a formatunderstood by.BR emacs ( 1 )\c\&; the \|\fBctags\fP\| program is used to create a similar table in aformat understood by.BR vi ( 1 )\c\&. Both forms of the program understandthe syntax of C, Objective C, C++, Java, Fortran, Ada, Cobol, Erlang, HTML,LaTeX, Emacs Lisp/Common Lisp, makefiles, Pascal, Perl, PHP, Postscript,Python, Prolog, Scheme andmost assembler\-like syntaxes.Both forms read the files specified on the command line, and write a tagtable (defaults: \fBTAGS\fP for \fBetags\fP, \fBtags\fP for\fBctags\fP) in the current working directory.Files specified with relative file names will be recorded in the tagtable with file names relative to the directory where the tag tableresides. Files specified with absolute file names will be recordedwith absolute file names. Files generated from a source file\-\-likea C file generated from a source Cweb file\-\-will be recorded withthe name of the source file.The programs recognize the language used in an input file based on itsfile name and contents. The \fB\-\-language\fP switch can be used to forceparsing of the file names following the switch according to the givenlanguage, overriding guesses based on filename extensions..SH OPTIONSSome options make sense only for the \fBvi\fP style tag files producedby ctags;\fBetags\fP does not recognize them.The programs accept unambiguous abbreviations for long option names..TP.B \-a, \-\-appendAppend to existing tag file. (For \fBvi\fP-format tag files, see also\fB\-\-update\fP.).TP.B \-B, \-\-backward\-searchTag files written in the format expected by \fBvi\fP contain regularexpression search instructions; the \fB\-B\fP option writes them usingthe delimiter `\|\fB?\fP\|', to search \fIbackwards\fP through files.The default is to use the delimiter `\|\fB/\fP\|', to search \fIforwards\fPthrough files.Only \fBctags\fP accepts this option..TP.B \-\-declarationsIn C and derived languages, create tags for function declarations,and create tags for extern variables unless \-\-no\-globals is used..TP.B \-d, \-\-definesCreate tag entries for C preprocessor constant definitionsand enum constants, too. This is thedefault behavior for \fBetags\fP..TP.B \-D, \-\-no\-definesDo not create tag entries for C preprocessor constant definitionsand enum constants.This may make the tags file much smaller if many header files are tagged.This is the default behavior for \fBctags\fP..TP.B \-g, \-\-globalsCreate tag entries for global variables in C, C++, Objective C, Java,and Perl.This is the default behavior for \fBetags\fP..TP.B \-G, \-\-no\-globalsDo not tag global variables. Typically this reduces the file size byone fourth. This is the default behavior for \fBctags\fP..TP\fB\-i\fP \fIfile\fP, \fB\-\-include=\fIfile\fPInclude a note in the tag file indicating that, when searching for atag, one should also consult the tags file \fIfile\fP after checking thecurrent file. This options is only accepted by \fBetags\fP..TP.B \-I, \-\-ignore\-indentationDon't rely on indentation as much as we normally do. Currently, thismeans not to assume that a closing brace in the first column is thefinal brace of a function or structure definition in C and C++..TP\fB\-l\fP \fIlanguage\fP, \fB\-\-language=\fIlanguage\fPParse the following files according to the given language. More thanone such options may be intermixed with filenames. Use \fB\-\-help\fPto get a list of the available languages and their default filenameextensions. The `auto' language can be used to restore automaticdetection of language based on the file name. The `none'language may be used to disable language parsing altogether; onlyregexp matching is done in this case (see the \fB\-\-regex\fP option)..TP.B \-m, \-\-membersCreate tag entries for variables that are members of structure-likeconstructs in C++, Objective C, Java..TP.B \-M, \-\-no\-membersDo not tag member variables. This is the default behavior..TP.B \-\-packages\-onlyOnly tag packages in Ada files..TP\fB\-\-parse\-stdin=\fIfile\fPMay be used (only once) in place of a file name on the command line.\fBetags\fP will read from standard input and mark the produced tagsas belonging to the file \fBFILE\fP..TP\fB\-o\fP \fItagfile\fP, \fB\-\-output=\fItagfile\fPExplicit name of file for tag table; overrides default \fBTAGS\fP or\fBtags\fP. (But ignored with \fB\-v\fP or \fB\-x\fP.).TP\fB\-r\fP \fIregexp\fP, \fB\-\-regex=\fIregexp\fPMake tags based on regexp matching for the files following this option,in addition to the tags made with the standard parsing based onlanguage. May be freely intermixed with filenames and the \fB\-R\fPoption. The regexps are cumulative, i.e. each such option will add tothe previous ones. The regexps are of one of the forms:.br [\fB{\fP\fIlanguage\fP\fB}\fP]\fB/\fP\fItagregexp/\fP[\fInameregexp\fP\fB/\fP]\fImodifiers\fP.br \fB@\fP\fIregexfile\fP.brwhere \fItagregexp\fP is used to match the tag. It should not matchuseless characters. If the match is such that more characters thanneeded are unavoidably matched by \fItagregexp\fP, it may be useful toadd a \fInameregexp\fP, to narrow down the tag scope. \fBctags\fPignores regexps without a \fInameregexp\fP. The syntax of regexps isthe same as in emacs. The following character escape sequences aresupported: \\a, \\b, \\d, \\e, \\f, \\n, \\r, \\t, \\v, whichrespectively stand for the ASCII characters BEL, BS, DEL, ESC, FF, NL,CR, TAB, VT..brThe \fImodifiers\fP are a sequence of 0 or more characters among\fIi\fP, which means to ignore case when matching; \fIm\fP, which meansthat the \fItagregexp\fP will be matched against the whole file contentsat once, rather than line by line, and the matching sequence can matchmultiple lines; and \fIs\fP, which implies \fIm\fP and means that thedot character in \fItagregexp\fP matches the newline char as well..brThe separator, which is \fB/\fP in the examples, can be any characterdifferent from space, tab, braces and \fB@\fP. If the separatorcharacter is needed inside the regular expression, it must be quotedby preceding it with \fB\\\fP..brThe optional \fB{\fP\fIlanguage\fP\fB}\fP prefix means that the tagshould becreated only for files of language \fIlanguage\fP, and ignoredotherwise. This is particularly useful when storing many predefinedregexps in a file..brIn its second form, \fIregexfile\fP is the name of a file that containsa number of arguments to the \fI\-\-regex\=\fP option,one per line. Lines beginning with a space or tab are assumedto be comments, and ignored..brHere are some examples. All the regexps are quoted to protect themfrom shell interpretation..brTag the DEFVAR macros in the emacs source files:.br\fI\-\-regex\='/[ \\t]*DEFVAR_[A-Z_ \\t(]+"\\([^"]+\\)"\/'\fP.\"" This comment is to avoid confusion to Emacs syntax highlighting.brTag VHDL files (this example is a single long line, broken here forformatting reasons):.br\fI\-\-language\=none\ \-\-regex='/[\ \\t]*\\(ARCHITECTURE\\|\\CONFIGURATION\\)\ +[^\ ]*\ +OF/'\ \-\-regex\='/[\ \\t]*\\\\(ATTRIBUTE\\|ENTITY\\|FUNCTION\\|PACKAGE\\(\ BODY\\)?\\\\|PROCEDURE\\|PROCESS\\|TYPE\\)[\ \\t]+\\([^\ \\t(]+\\)/\\3/'\fP.brTag TCL files (this last example shows the usage of a \fItagregexp\fP):.br\fI\-\-lang\=none \-\-regex\='/proc[\ \\t]+\\([^\ \\t]+\\)/\\1/'\fP.brA regexp can be preceded by {\fIlang\fP}, thus restricting it to matchlines of files of the specified language. Use \fBetags --help\fP to obtaina list of the recognised languages. This feature is particularly useful inside\fBregex files\fP. A regex file contains one regex per line. Empty lines,and those lines beginning with space or tab are ignored. Lines beginningwith @ are references to regex files whose name follows the @ sign. Otherlines are considered regular expressions like those following \fB\-\-regex\fP..brFor example, the command.br\fIetags \-\-regex=@regex.file *.c\fP.brreads the regexes contained in the file regex.file..TP.B \-R, \-\-no\-regexDon't do any more regexp matching on the following files. May befreely intermixed with filenames and the \fB\-\-regex\fP option..TP.B \-t, \-\-typedefsRecord typedefs in C code as tags. Since this is the default behaviorof \fBetags\fP, only \fBctags\fP accepts this option..TP.B \-T, \-\-typedefs\-and\-c++Generate tag entries for typedefs, struct, enum, and union tags, andC++ member functions. Since this is the default behaviorof \fBetags\fP, only \fBctags\fP accepts this option..TP.B \-u, \-\-updateUpdate tag entries for \fIfiles\fP specified on command line, leavingtag entries for other files in place. Currently, this is implementedby deleting the existing entries for the given files and thenrewriting the new entries at the end of the tags file. It is oftenfaster to simply rebuild the entire tag file than to use this.Only \fBctags\fP accepts this option..TP.B \-v, \-\-vgrindInstead of generating a tag file, write index (in \fBvgrind\fP format)to standard output. Only \fBctags\fP accepts this option..TP.B \-w, \-\-no\-warnSuppress warning messages about duplicate entries. The \fBetags\fPprogram does not check for duplicate entries, so this option is notallowed with it..TP.B \-x, \-\-cxrefInstead of generating a tag file, write a cross reference (in\fBcxref\fP format) to standard output. Only \fBctags\fP accepts this option..TP.B \-h, \-H, \-\-helpPrint usage information..TP.B \-V, \-\-versionPrint the current version of the program (same as the version of theemacs \fBetags\fP is shipped with)..SH "SEE ALSO"`\|\fBemacs\fP\|' entry in \fBinfo\fP; \fIGNU Emacs Manual\fP, RichardStallman..br.BR cxref ( 1 ),.BR emacs ( 1 ),.BR vgrind ( 1 ),.BR vi ( 1 )..SH COPYINGCopyright.if t \(co.if n (c)1999, 2001 Free Software Foundation, Inc..PPPermission is granted to make and distribute verbatim copies of thisdocument provided the copyright notice and this permission notice arepreserved on all copies..PPPermission is granted to copy and distribute modified versions ofthis document under the conditions for verbatim copying, provided thatthe entire resulting derived work is distributed under the terms ofa permission notice identical to this one..PPPermission is granted to copy and distribute translations of thisdocument into another language, under the above conditions formodified versions, except that this permission notice may be statedin a translation approved by the Free Software Foundation.