Provided by: elvis-common_2.2.0-11.1_all bug

NAME

       elvtags - Generates "tags" and (optionally) "refs" files

SYNOPSIS

       elvtags [-D word] [-FBNgitvshlpdxra] files...

VERSION

       This page describes the Elvis 2.2_0 version of ctags.  See elvis(1).

DESCRIPTION

       elvtags  generates  the tags and refs files from a group of C source files.  The tags file
       is used by Elvis' ":tag" command, ^] command, and -t option.  The refs file  is  sometimes
       used by the ref(1) program.

       Each C source file is scanned for #define statements and global function definitions.  The
       name of the macro or function becomes the name of a tag.  For each tag, a line is added to
       the tags file.

       The  filenames  list  will  typically  be  the  names of all C source files in the current
       directory, like this:

              $ elvtags *.c *.h

OPTIONS

       If no options are given, then elvtags acts as though the -l -i -t -v and -s  option  flags
       were  given.   If  you  want  to  omit those options, you can do so by explicitly giving a
       harmless option such as -F.

       -Dword This causes Elvis to ignore any instance of "word" in your source  code.   This  is
              handy  if  you're  using  a  macro  for  conditionally  declaring  the arguments to
              functions, in order to make your code  be  backward-compatible  with  older  K&R  C
              compilers.   elvtags  always  ignores "P_" and "__P"; the -Dword flag allows you to
              make it ignore a third word.

       -F     Enclose regular expressions in slashes (/regexp/)  which  will  cause  elvis(1)  to
              search from the top of the file.  This is the default.

       -B     Enclose  the  regular  expressions  in  question  marks (?regexp?) so elvis(1) will
              search backward from the bottom of the file.  The search direction rarely  matters;
              this option exists mostly for compatibility with earlier versions of elvtags.

       -N     This  causes elvtags to use line numbers for all tags.  Without this flag, it would
              use numbers for #define'ed macros, and regular expressions for anything else.

       -g     For static tags, generate  entries  that  look  like  global  tags.   (I.e.,  never
              generate an extra "file:" attribute.)  This implies -s and -h.

       -i     Include  inline  definitions.   A  tag will be generated for each function which is
              declared as being inline, __inline, or __inline__.

       -t     Include typedefs.  A tag will be generated for each user-defined type.   Also  tags
              will  be generated for struct and enum names.  Types are considered to be global if
              they are defined in a header file, and static if they are defined  in  a  C  source
              file.

       -v     Include  variable  declarations.  A tag will be generated for each variable, except
              for those that are declared inside the body of a function.

       -s     Include static tags.  elvtags will normally put global tags in the tags  file,  and
              silently  ignore  the static tags.  This flag causes both global and static tags to
              be added.

       -e     Include extern tags.  elvtags will normally ignore extern declarations of functions
              or variables; that's handy when generating tags for your own programs.  A tags file
              for the extern declarations in the system's standard header files  can  be  a  very
              handy resource, so this -e flag was created.

       -h     Add  hints  that  may help Elvis handle overloaded tags better.  The resulting tags
              file may be unreadable by programs other than Elvis, though.

       -l     Add "ln" line number hints.  This implies -h, since it would be pointless if  hints
              weren't  allowed.  The "ln" hints are used by elvis(1) to make its "showtag" option
              work much faster.

       -p     Write parsing information to  stdout.   This  is  intended  mainly  as  an  aid  to
              debugging  the elvtags command itself.  If elvtags doesn't generate all of the tags
              that you expect it to, then try studying the -p output  to  determine  what  syntax
              feature is tripping it up.

       -d     Warn about duplicates, on stdout.  elvtags allows tags with duplicate names, except
              for typedefs (tags with kind=t) which must be unique.   When  a  duplicate  tag  is
              detected, elvtags can either add it if neither the new tag nor the existing one has
              "kind=t", skip it if the existing one has  "kind=t",  or  add  it  and  delete  the
              existing  one if the new one has "kind=t".  Usually you won't care, but -d may help
              you understand why elvtags fails to add a tag that you expected it to add.

       -x     Generate a human-readable tag list instead of a "tags" file.  The list  is  written
              to  stdout.  Each line contains a tag name, the line number and file name where the
              tag is defined, and the text of that line.

       -r     This causes elvtags to generate both tags and refs.   Without  -r,  it  would  only
              generate tags.

       -a     Append to tags, and maybe refs.  Normally, elvtags overwrites these files each time
              it is invoked.  This flag is useful when you have too many  files  in  the  current
              directory for you to list them on a single command-line; it allows you to split the
              arguments among several invocations.  This may result in an unsorted tags file.

FORMAT OF THE TAGS FILE

       The tags file is a text file.  Each line stores the attributes of a single tag.  The basic
       format of a line is:

              · the name of the tag
              · a tab character
              · the name of the file containing the tag
              · a tab character
              · the tag's address within that file

       The  tag  address  may  be  given as either line number (a string of digits), or a regular
       expression using ex/vi's "nomagic" syntax, delimited by either slashes or question  marks.
       Regular expressions are allowed to contain tab characters.

       The  authors  of  Elvis,  Vim,  and "Exuberant" Ctags have agreed on a standard format for
       adding additional attributes to tags.  In this format, the first three fields of all  tags
       are  identical  to  the  traditional format, except that a semicolon-doublequote character
       pair is appended to the tag address field, with the extra attributes appearing after that.

       The semicolon-doublequote character pair is present because it has  the  surprising  side-
       effect  of  making  the original ex/vi ignore the remainder of the line, thus allowing the
       original ex/vi to read new-format tags files.  The original ex/vi will simply  ignore  the
       extra attributes.

       Any  additional  attributes  are  appended to the tag's line.  They may be appended in any
       order.  Each attribute will use the following format:

              · a tab character
              · the name of the attribute
              · a colon character, ':'
              · the value of the attribute.

       Note that each additional attribute has an explicit name.  Different tags  files  may  use
       totally  different  names  for  additional attributes, and even within a single file, most
       tags will use only a subset of the possible attributes.  This version of elvtags uses  the
       following names:

       file   This  attribute  is  used  to mark static tags -- i.e., tags for C/C++ functions or
              variables whose scope is limited to the function in which they  are  defined.   The
              value  is  the name of the file where it is defined, except that if the file is the
              same as field 2 (and it nearly always is) then the value may be given  as  a  zero-
              length string.

       class  This is used to mark member functions of C++ classes.  The value is the class name.
              However, currently elvtags doesn't do a  very  good  job  of  detecting  whether  a
              function is a member function or not.

       kind   This  attribute's  value  is  a  single  letter, indicating the lexical type of the
              tagged identifier: f for a function, t for a typedef, s for a struct tag, u  for  a
              union  tag,  v  for  a  variable,  d  for  a  macro  definition, or x for an extern
              declaration.

              Note that in the tags  file,  the  "kind:"  label  is  omitted,  for  the  sake  of
              compactness.

       ln     This  gives  the line number where the tag was defined.  It is redundant, but it is
              still somewhat useful because it allows elvis(1)'s "showtag" option to work faster.

       The values can only contain tabs if those tabs are converted  to  the  '\t'  (backslash-t)
       notation.   Similarly,  a  newline,  carriage return, or literal backslash can be given as
       '\n', '\r', or '\\' respectively.  For MS-DOS file names, this means the  names  must  use
       double  backslashes.   Space characters don't require any special encoding.  (This doesn't
       apply to file names in the tagfile field, where names can be  given  without  any  special
       encoding.  It only applies to file names in extra fields.)

       As  a  special  case,  if  an extra attribute contains no ':' to delimit the name from the
       value, then the attribute string is assumed to be the value of an attribute named  "kind".
       Usually  this  will be a single letter indicating what type of token the tag represents --
       'f' for function, 'v' for variable, and so on.

       Here's an example of a new-format tag:
              bar  foo.c     /^void Foo::bar(int zot)$/;"  class:Foo
       The tagname is "bar", to  match  its  function's  name.   The  tagfile  is  "foo.c".   The
       tagaddress  is  a  regular  expression  containing the whole definition line.  Note that a
       semicolon-doublequote character pair has been appended to the tagaddress.  There  is  only
       one additional attribute, with the name "class" and the value "Foo".

FILES

       tags   A  cross-reference  that  lists  each  tag  name,  the name of the source file that
              contains it, and a way to locate a particular line in the source file.

       refs   The refs file contains the definitions for each tag in  the  tags  file,  and  very
              little  else.   This  file  can be useful, for example, when licensing restrictions
              prevent you from making the source code to  the  standard  C  library  readable  by
              everybody,  but  you  still  want  everybody  to  know  what  arguments the library
              functions need.

BUGS

       elvtags is sensitive to indenting and line breaks.  Consequently, it  might  not  discover
       all of the tags in a file that is formatted in an unusual way.

       The  -a  flag  causes tag files to be appended, but not necessarily sorted.  Some programs
       expect tags files to be sorted, and will misbehave if they aren't.  Also, the  new  format
       allows  a "!_TAG_FILE_SORTED" marker near the top of the file to indicate whether the file
       is sorted, but that might not be accurate  after  new  tags  are  appended  to  the  file.
       Consequently, you should avoid the use of -a.

       The new standard doesn't specify how overloaded operators are to be labelled.  If your C++
       source contains a definition of operator+=(), then this version of elvtags  will  store  a
       tag named "operator+=".  Other versions of elvtags could simply use the name "+=".

SEE ALSO

       elvis(1), ref(1)

AUTHOR

       Steve Kirkendall
       kirkenda@cs.pdx.edu

                                                                                       ELVTAGS(1)