(emacs.info) Create Tags Table

 
 Creating Tags Tables
 --------------------
 
    The `etags' program is used to create a tags table file.  It knows
 the syntax of several languages, as described in  Tag Syntax.
 Here is how to run `etags':
 
      etags INPUTFILES...
 
 The `etags' program reads the specified files, and writes a tags table
 named `TAGS' in the current working directory.  `etags' recognizes the
 language used in an input file based on its file name and contents.
 You can specify the language with the `--language=NAME' option,
 described below.
 
    If the tags table data become outdated due to changes in the files
 described in the table, the way to update the tags table is the same
 way it was made in the first place.  It is not necessary to do this
 often.
 
    If the tags table fails to record a tag, or records it for the wrong
 file, then Emacs cannot possibly find its definition.  However, if the
 position recorded in the tags table becomes a little bit wrong (due to
 some editing in the file that the tag definition is in), the only
 consequence is a slight delay in finding the tag.  Even if the stored
 position is very wrong, Emacs will still find the tag, but it must
 search the entire file for it.
 
    So you should update a tags table when you define new tags that you
 want to have listed, or when you move tag definitions from one file to
 another, or when changes become substantial.  Normally there is no need
 to update the tags table after each edit, or even every day.
 
    One tags table can effectively include another.  Specify the included
 tags file name with the `--include=FILE' option when creating the file
 that is to include it.  The latter file then acts as if it contained
 all the files specified in the included file, as well as the files it
 directly contains.
 
    If you specify the source files with relative file names when you run
 `etags', the tags file will contain file names relative to the
 directory where the tags file was initially written.  This way, you can
 move an entire directory tree containing both the tags file and the
 source files, and the tags file will still refer correctly to the source
 files.
 
    If you specify absolute file names as arguments to `etags', then the
 tags file will contain absolute file names.  This way, the tags file
 will still refer to the same files even if you move it, as long as the
 source files remain in the same place.  Absolute file names start with
 `/', or with `DEVICE:/' on MS-DOS and MS-Windows.
 
    When you want to make a tags table from a great number of files, you
 may have problems listing them on the command line, because some systems
 have a limit on its length.  The simplest way to circumvent this limit
 is to tell `etags' to read the file names from its standard input, by
 typing a dash in place of the file names, like this:
 
      find . -name "*.[chCH]" -print | etags -
 
    Use the option `--language=NAME' to specify the language explicitly.
 You can intermix these options with file names; each one applies to
 the file names that follow it.  Specify `--language=auto' to tell
 `etags' to resume guessing the language from the file names and file
 contents.  Specify `--language=none' to turn off language-specific
 processing entirely; then `etags' recognizes tags by regexp matching
 alone.  `etags --help' prints the list of the languages `etags' knows,
 and the file name rules for guessing the language.
 
    The `--regex' option provides a general way of recognizing tags
 based on regexp matching.  You can freely intermix it with file names.
 Each `--regex' option adds to the preceding ones, and applies only to
 the following files.  The syntax is:
 
      --regex=/TAGREGEXP[/NAMEREGEXP]/
 
 where TAGREGEXP is used to match the lines to tag.  It is always
 anchored, that is, it behaves as if preceded by `^'.  If you want to
 account for indentation, just match any initial number of blanks by
 beginning your regular expression with `[ \t]*'.  In the regular
 expressions, `\' quotes the next character, and `\t' stands for the tab
 character.  Note that `etags' does not handle the other C escape
 sequences for special characters.
 
    The syntax of regular expressions in `etags' is the same as in
 Emacs, augmented with the "interval operator", which works as in `grep'
 and `ed'.  The syntax of an interval operator is `\{M,N\}', and its
 meaning is to match the preceding expression at least M times and up to
 N times.
 
    You should not match more characters with TAGREGEXP than that needed
 to recognize what you want to tag.  If the match is such that more
 characters than needed are unavoidably matched by TAGREGEXP, you may
 find useful to add a NAMEREGEXP, in order to narrow the tag scope.  You
 can find some examples below.
 
    The `-R' option deletes all the regexps defined with `--regex'
 options.  It applies to the file names following it, as you can see
 from the following example:
 
      etags --regex=/REG1/ voo.doo --regex=/REG2/ \
          bar.ber -R --lang=lisp los.er
 
 Here `etags' chooses the parsing language for `voo.doo' and `bar.ber'
 according to their contents.  `etags' also uses REG1 to recognize
 additional tags in `voo.doo', and both REG1 and REG2 to recognize
 additional tags in `bar.ber'.  `etags' uses the Lisp tags rules, and no
 regexp matching, to recognize tags in `los.er'.
 
    Here are some more examples.  The regexps are quoted to protect them
 from shell interpretation.
 
    * Tag the `DEFVAR' macros in the emacs source files:
 
           --regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
 
    * Tag VHDL files (this example is a single long line, broken here for
      formatting reasons):
 
           --language=none
           --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/'
           --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
           \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
 
    * Tag Tcl files (this last example shows the usage of a NAMEREGEXP):
 
           --lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'
 
    For a list of the other available `etags' options, execute `etags
 --help'.
Info Catalog
(emacs.info) Tag Syntax
(emacs.info) Tags
(emacs.info) Select Tags Table
automatically generated by info2html