-\1f
-File: xemacs.info, Node: Create Tags Table, Next: Select Tags Table, Prev: Tag Syntax, Up: Tags
-
-Creating Tags Tables
---------------------
-
- The `etags' program is used to create a tags table file. It knows
-the syntax of several languages, as described in *Note 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 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'.