etags(1)                    GNU Tools                    etags(1)

NAME
       etags, gctags - generate tag file for Emacs, vi

SYNOPSIS
       etags [-aCDRSVh] [-i file] [-l language] [-i regexp] [-o
       tagfile]
       [--c++] [--no-defines] [--ignore-indentation]
       [--language=language] [--regex=regexp] [--no-regexp]
       [--help] [--version] [--include=file] [--output=tagfile]
       [--append] file ...

       gctags [-aCdRSVh] [-BtTuvwx] [-l language]
       [-i regexp] [-o tagfile] [--c++] [--defines]
       [--ignore-indentation] [--no-warn] [--cxref]
       [--backward-search] [--forward-search] [--typedefs]
       [--typedefs-and-c++] [--language=language]
       [--regex=regexp] [--help] [--version]
       [--output=tagfile] [--append] [--update] file ...

DESCRIPTION
       The `etags' program is used to create a tag table file, in
       a format understood by emacs(1); the `gctags'  program  is
       used  to  create a similar table in a format understood by
       vi(1).  Both forms of the program understand the syntax of
       C,  C++, Fortran, Pascal, LaTeX, Scheme, Emacs Lisp/Common
       Lisp, Erlang, Prolog  and  most  assembler-like  syntaxes.
       Both  forms  read the files specified on the command line,
       and write a tag table (defaults: `TAGS' for etags,  `tags'
       for gctags) in the current working directory.  Files spec-
       ified with relative file names will be recorded in the tag
       table  with file names relative to the directory where the
       tag table resides.  Files  specified  with  absolute  file
       names will be recorded with absolute file names.  The pro-
       grams recognize the language used in an input  file  based
       on  its file name and contents.  The --language switch can
       be used to force parsing of the file names  following  the
       switch according to the given language, overriding guesses
       based on filename extensions.

OPTIONS
       Some options make sense only for the vi  style  tag  files
       produced  by  gctags;  etags does not recognize them.  The
       programs accept unambiguous abbreviations for long  option
       names.

       -a, --append
              Append  to  existing  tag file.  (For vi-format tag
              files, see also --update.)

       -B, --backward-search
              Tag files written in the format expected by vi con-
              tain regular expression search instructions; the -B
              option writes them  using  the  delimiter  `?',  to
              search  backwards through files.  The default is to
              use the delimiter `/', to search  forwards  through
              files.  Only gctags accepts this option.

       -C, --c++
              Treat  files  with  `.c' and `.h' extensions as C++
              code, not C code.  Files with `.C',  `.H',  `.cxx',
              `.hxx',  or  `.cc' extensions are always assumed to
              be C++ code.

       -d, --defines
              Create tag entries for C preprocessor  definitions,
              too.   This  is  the default behavior for etags, so
              this option is only accepted by gctags.

       -D, --no-defines
              Do not create tag entries for C preprocessor  defi-
              nitions.   This may make the tags file much smaller
              if many header files are tagged.  This is  the  de-
              fault  behavior  for gctags, so this option is only
              accepted by etags.

       -l language, --language=language
              Parse the following files according  to  the  given
              language.  More than one such options may be inter-
              mixed with filenames.  Use --help to get a list  of
              the  available languages and their default filename
              extensions.  The `auto' language can be used to re-
              store  automatic  detection  of  language  based on
              filename extension.  The  `none'  language  may  be
              used  to  disable language parsing altogether; only
              regexp matching is  done  in  this  case  (see  the
              --regex option).

       -o tagfile, --output=tagfile
              Explicit  name of file for tag table; overrides de-
              fault `TAGS' or `tags'.   (But ignored with  -v  or
              -x.)

       -r regexp, --regex=regexp
              Make tags based on regexp matching for each line of
              the files following this option, in addition to the
              tags  made  with the standard parsing based on lan-
              guage.  May be freely intermixed with filenames and
              the  -R  option.   The regexps are cumulative, i.e.
              each option will add to  the  previous  ones.   The
              regexps are of the form:

                        /tagregexp[/nameregexp]/

              where  tagregexp  is  used  to match the lines that
              must be tagged.  It should not match useless  char-
              acters.   If the match is such that more characters
              than needed are unavoidably matched  by  tagregexp,
              it  may  be  useful  to add a nameregexp, to narrow
              down the tag scope.  gctags ignores regexps without
              a nameregexp.
              Here are some examples.  All 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 Cobol files:
              --language=none --regex='/.......[a-zA-Z0-9-]+\./'

              Tag Postscript files:
              --language=none --regex='#/[^ \t{]+#/'

              Tag TCL files (this last example shows the usage of
              a tagregexp):
              --lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/'

       -R, --no-regex
              Don't do any more regexp matching on the  following
              files.  May be freely intermixed with filenames and
              the --regex option.

       -S, --ignore-indentation
              Don't rely on indentation as much  as  we  normally
              do.   Currently,  this  means  not to assume that a
              closing brace in the  first  column  is  the  final
              brace  of  a  function or structure definition in C
              and C++.

       -t, --typedefs
              Record typedefs in C code as tags.  Since  this  is
              the default behaviour of etags, only gctags accepts
              this option.

       -T, --typedefs-and-c++
              Generate tag entries for  typedefs,  struct,  enum,
              and  union  tags,  and C++ member functions.  Since
              this is the default behaviour of etags, only gctags
              accepts this option.

       -u, --update
              Update  tag  entries for files specified on command
              line, leaving tag entries for other files in place.
              Currently,  this is implemented by deleting the ex-
              isting entries for the given files and then rewrit-
              ing  the  new  entries at the end of the tags file.
              It is often faster to simply rebuild the entire tag
              file  than  to  use this.  Only gctags accepts this
              option.

       -v, --vgrind
              Instead of generating a tag file, write  index  (in
              vgrind format) to standard output.  Only gctags ac-
              cepts this option.

       -w, --no-warn
              Suppress warning messages about duplicate  entries.
              The  etags program does not check for duplicate en-
              tries, so this option is not allowed with it.

       -x, --cxref
              Instead of generating a tag  file,  write  a  cross
              reference  (in  cxref  format)  to standard output.
              Only gctags accepts this option.

       -H, --help
              Print usage information.

       -V, --version
              Print the current version of the program  (same  as
              the version of the emacs etags is shipped with).

SEE ALSO
       `emacs' entry in info; GNU Emacs Manual, Richard Stallman.
       cxref(1), emacs(1), vgrind(1), vi(1).

COPYING
       Copyright (c) 1992 Free Software Foundation, Inc.

       Permission is granted  to  make  and  distribute  verbatim
       copies  of  this  manual provided the copyright notice and
       this permission notice are preserved on all copies.

       Permission is granted to copy and distribute modified ver-
       sions  of  this  manual  under the conditions for verbatim
       copying, provided that the entire resulting  derived  work
       is  distributed  under  the  terms  of a permission notice
       identical to this one.

       Permission is granted to copy and distribute  translations
       of this manual into another language, under the above con-
       ditions for modified versions, except that this permission
       notice  may  be  included  in translations approved by the
       Free Software Foundation instead of in  the  original  En-
       glish.

GNU Tools                   19apr1994                           1