cosmopolitan/third_party/ctags/README.txt

CTAGS(1)                        Exuberant Ctags                       CTAGS(1)



𝐍𝐀𝐌𝐄
       ctags - Generate tag files for source code



𝐒𝐘𝐍𝐎𝐏𝐒𝐈𝐒
       𝗰𝘁𝗮𝗴𝘀 [𝗼𝗽𝘁𝗶𝗼𝗻𝘀] [f̲i̲l̲e̲(̲s̲)̲]

       𝗲𝘁𝗮𝗴𝘀 [𝗼𝗽𝘁𝗶𝗼𝗻𝘀] [f̲i̲l̲e̲(̲s̲)̲]



𝐃𝐄𝐒𝐂𝐑𝐈𝐏𝐓𝐈𝐎𝐍
       The  𝗰𝘁𝗮𝗴𝘀  and 𝗲𝘁𝗮𝗴𝘀 programs (hereinafter collectively referred
       to as 𝗰𝘁𝗮𝗴𝘀, except where distinguished) generate  an  index  (or
       "tag")  file  for a variety of language objects found in f̲i̲l̲e̲(̲s̲)̲.
       This tag file allows these items to be quickly and easily located
       by  a  text editor or other utility. A "tag" signifies a language
       object for which an index entry is available (or,  alternatively,
       the index entry created for that object).

       Alternatively,  𝗰𝘁𝗮𝗴𝘀  can  generate a cross reference file which
       lists, in human readable  form,  information  about  the  various
       source objects found in a set of language files.

       Tag  index  files  are supported by numerous editors, which allow
       the user to locate the object associated with a name appearing in
       a  source  file  and  jump to the file and line which defines the
       name. Those known about at the time of this release are:

           𝐕𝗶(1) and its derivatives (e.g.  Elvis,  Vim,  Vile,  Lemmy),
           𝐂𝐑𝗶𝐒𝐏,  𝐄𝗺𝗮𝗰𝘀,  𝐅𝐓𝐄 (Folding Text Editor), 𝐉𝐄𝐃, 𝗷𝐄𝗱𝗶𝘁, 𝐌𝗶𝗻𝗲𝗱,
           𝐍𝐄𝗱𝗶𝘁 (Nirvana Edit), 𝐓𝐒𝐄 (The  SemWare  Editor),  𝐔𝗹𝘁𝗿𝗮𝐄𝗱𝗶𝘁,
           𝐖𝗼𝗿𝗸𝐒𝗽𝗮𝗰𝗲, 𝐗𝟮, 𝐙𝗲𝘂𝘀

       𝐂𝘁𝗮𝗴𝘀  is  capable of generating different kinds of tags for each
       of many different languages. For a  complete  list  of  supported
       languages,  the names by which they are recognized, and the kinds
       of tags which are generated for each,  see  the  --𝗹𝗶𝘀𝘁-𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲𝘀
       and --𝗹𝗶𝘀𝘁-𝗸𝗶𝗻𝗱𝘀 options.



𝐒𝐎𝐔𝐑𝐂𝐄 𝐅𝐈𝐋𝐄𝐒
       Unless  the --𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲-𝗳𝗼𝗿𝗰𝗲 option is specified, the language of
       each source file is automatically selected based upon  a  mapping
       of  file names to languages. The mappings in effect for each lan‐
       guage may be display using the  --𝗹𝗶𝘀𝘁-𝗺𝗮𝗽𝘀  option  and  may  be
       changed  using  the --𝗹𝗮𝗻𝗴𝗺𝗮𝗽 option.  On platforms which support
       it, if the name of a file is not mapped to  a  language  and  the
       file  is executable, the first line of the file is checked to see
       if the file is a "#!" script for a recognized language.

       By default, all other files names are ignored. This permits  run‐
       ning 𝗰𝘁𝗮𝗴𝘀 on all files in either a single directory (e.g. "ctags
       *"), or on all files in an entire  source  directory  tree  (e.g.
       "ctags  -R"),  since  only  those files whose names are mapped to
       languages will be scanned.

       [The reason that .h extensions are mapped  to  C++  files  rather
       than C files is because it is common to use .h extensions in C++,
       and no harm results in treating them as C++ files.]



𝐎𝐏𝐓𝐈𝐎𝐍𝐒
       Despite the wealth of available options, defaults are set so that
       𝗰𝘁𝗮𝗴𝘀  is most commonly executed without any options (e.g. "ctags
       *", or "ctags -R"), which will create a tag file in  the  current
       directory  for all recognized source files. The options described
       below are provided merely to allow custom tailoring to meet  spe‐
       cial needs.

       Note  that spaces separating the single-letter options from their
       parameters are optional.

       Note also that the boolean parameters to the  long  form  options
       (those beginning with "--" and that take a "[̲=̲y̲e̲s̲|n̲o̲]̲" parameter)
       may be omitted, in which case "=y̲e̲s̲" is implied. (e.g. --𝘀𝗼𝗿𝘁  is
       equivalent  to  --𝘀𝗼𝗿𝘁=y̲e̲s̲). Note further that "=1̲" and "=o̲n̲" are
       considered synonyms for "=y̲e̲s̲", and that "=0̲" and "=o̲f̲f̲" are con‐
       sidered synonyms for "=n̲o̲".

       Some  options  are  either ignored or useful only when used while
       running in etags mode (see  -𝗲  option).  Such  options  will  be
       noted.

       Most  options  may appear anywhere on the command line, affecting
       only those files which follow the option. A few options, however,
       must appear before the first file name and will be noted as such.

       Options  taking  language names will accept those names in either
       upper or lower case. See the --𝗹𝗶𝘀𝘁-𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲𝘀 option for  a  com‐
       plete list of the built-in language names.


       -𝗮   Equivalent to --𝗮𝗽𝗽𝗲𝗻𝗱.


       -𝐁   Use  backward  searching patterns (e.g. ?pattern?). [Ignored
            in etags mode]


       -𝗲   Enable etags mode, which will create a tag file for use with
            the  Emacs  editor.  Alternatively, if 𝗰𝘁𝗮𝗴𝘀 is invoked by a
            name containing the string "etags" (either by  renaming,  or
            creating  a link to, the executable), etags mode will be en‐
            abled. This option must appear before the first file name.


       -𝗳 t̲a̲g̲f̲i̲l̲e̲
            Use the name specified by t̲a̲g̲f̲i̲l̲e̲ for the tag file  (default
            is "tags", or "TAGS" when running in etags mode). If t̲a̲g̲f̲i̲l̲e̲
            is specified as "-", then the tag file is written  to  stan‐
            dard  output  instead.  𝐂𝘁𝗮𝗴𝘀 will stubbornly refuse to take
            orders if t̲a̲g̲f̲i̲l̲e̲ exists and its first line  contains  some‐
            thing other than a valid tags line. This will save your neck
            if you mistakenly type "ctags -f *.c", which would otherwise
            overwrite  your  first C file with the tags generated by the
            rest! It will also refuse to accept a  multi-character  file
            name  which  begins  with a '-' (dash) character, since this
            most likely means that you left out the tag  file  name  and
            this  option tried to grab the next option as the file name.
            If you really want to name your  output  tag  file  "-ugly",
            specify  it as "./-ugly". This option must appear before the
            first file name. If this option is specified more than once,
            only the last will apply.


       -𝐅   Use  forward  searching patterns (e.g. /pattern/) (default).
            [Ignored in etags mode]


       -𝗵 l̲i̲s̲t̲
            Specifies a list of file extensions, separated  by  periods,
            which are to be interpreted as include (or header) files. To
            indicate files having no extension, use a  period  not  fol‐
            lowed  by  a  non-period character (e.g. ".", "..x", ".x.").
            This option only affects how the  scoping  of  a  particular
            kinds  of  tags is interpreted (i.e. whether or not they are
            considered as globally visible or visible  only  within  the
            file  in which they are defined); it does not map the exten‐
            sion to any particular language. Any tag which is located in
            a  non-include file and cannot be seen (e.g. linked to) from
            another  file  is  considered  to  have  file-limited  (e.g.
            static)  scope.  No kind of tag appearing in an include file
            will be considered to have file-limited scope. If the  first
            character in the list is a plus sign, then the extensions in
            the list will be appended to the  current  list;  otherwise,
            the  list  will  replace  the  current  list. See, also, the
            --𝗳𝗶𝗹𝗲-𝘀𝗰𝗼𝗽𝗲     option.     The     default     list     is
            ".h.H.hh.hpp.hxx.h++.inc.def".  To restore the default list,
            specify -𝗵 d̲e̲f̲a̲u̲l̲t̲. Note that if an  extension  supplied  to
            this  option  is not already mapped to a particular language
            (see 𝐒𝐎𝐔𝐑𝐂𝐄 𝐅𝐈𝐋𝐄𝐒, above), you will also need to use  either
            the --𝗹𝗮𝗻𝗴𝗺𝗮𝗽 or --𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲-𝗳𝗼𝗿𝗰𝗲 option.


       -𝐈 i̲d̲e̲n̲t̲i̲f̲i̲e̲r̲-̲l̲i̲s̲t̲
            Specifies  a  list  of identifiers which are to be specially
            handled while parsing C and C++ source files. This option is
            specifically   provided  to  handle  special  cases  arising
            through the use of preprocessor macros. When the identifiers
            listed are simple identifiers, these identifiers will be ig‐
            nored during parsing of the source files. If  an  identifier
            is suffixed with a '+' character, 𝗰𝘁𝗮𝗴𝘀 will also ignore any
            parenthesis-enclosed argument  list  which  may  immediately
            follow  the  identifier  in the source files. If two identi‐
            fiers are separated with the '=' character, the first  iden‐
            tifiers  is  replaced  by the second identifiers for parsing
            purposes. The list of identifiers may be  supplied  directly
            on  the command line or read in from a separate file. If the
            first character of i̲d̲e̲n̲t̲i̲f̲i̲e̲r̲-̲l̲i̲s̲t̲ is '@', '.' or a pathname
            separator  ('/' or '\'), or the first two characters specify
            a drive letter (e.g. "C:"),  the  parameter  i̲d̲e̲n̲t̲i̲f̲i̲e̲r̲-̲l̲i̲s̲t̲
            will  be interpreted as a filename from which to read a list
            of identifiers,  one  per  input  line.  Otherwise,  i̲d̲e̲n̲t̲i̲‐̲
            f̲i̲e̲r̲-̲l̲i̲s̲t̲  is a list of identifiers (or identifier pairs) to
            be specially handled, each delimited by a either a comma  or
            by  white  space (in which case the list should be quoted to
            keep the entire list as one command line argument). Multiple
            -𝐈  options  may  be  supplied.  To clear the list of ignore
            identifiers, supply a single dash ("-") for i̲d̲e̲n̲t̲i̲f̲i̲e̲r̲-̲l̲i̲s̲t̲.

            This feature is useful when preprocessor macros are used  in
            such  a way that they cause syntactic confusion due to their
            presence. Indeed, this is the best way of working  around  a
            number  of problems caused by the presence of syntax-busting
            macros in source files (see 𝐂𝐀𝐕𝐄𝐀𝐓𝐒, below).  Some  examples
            will illustrate this point.

               int foo ARGDECL4(void *, ptr, long int, nbytes)


            In  the above example, the macro "ARGDECL4" would be mistak‐
            enly interpreted to be the name of the function  instead  of
            the correct name of "foo". Specifying -𝐈 A̲R̲G̲D̲E̲C̲L̲4̲ results in
            the correct behavior.

               /* creates an RCS version string in module */
               MODULE_VERSION("$Revision: 750 $")


            In the above example the macro  invocation  looks  too  much
            like  a  function definition because it is not followed by a
            semicolon (indeed, it could even be  followed  by  a  global
            variable  definition  that  would look much like a K&R style
            function parameter declaration). In fact, this seeming func‐
            tion  definition  could  possibly even cause the rest of the
            file to be skipped over while trying to complete the defini‐
            tion. Specifying -𝐈 M̲O̲D̲U̲L̲E̲_V̲E̲R̲S̲I̲O̲N̲+̲ would avoid such a prob‐
            lem.

               CLASS Example {
                   // your content here
               };


            The example above uses "CLASS" as a preprocessor macro which
            expands  to  something  different for each platform. For in‐
            stance CLASS may be defined as "class __declspec(dllexport)"
            on  Win32  platforms  and simply "class" on UNIX.  Normally,
            the absence of the  C++  keyword  "class"  would  cause  the
            source  file  to be incorrectly parsed. Correct behavior can
            be restored by specifying -𝐈 C̲L̲A̲S̲S̲=̲c̲l̲a̲s̲s̲.


       -𝐋 f̲i̲l̲e̲
            Read from f̲i̲l̲e̲ a list of file names for which tags should be
            generated.  If f̲i̲l̲e̲ is specified as "-", then file names are
            read from standard input. File names read using this  option
            are  processed following file names appearing on the command
            line. Options are also accepted in this input. If  this  op‐
            tion  is specified more than once, only the last will apply.
            𝐍𝗼𝘁𝗲: f̲i̲l̲e̲ is read in line-oriented mode, where a  new  line
            is  the  only delimiter and non-trailing white space is con‐
            sidered significant, in order  that  file  names  containing
            spaces  may  be  supplied  (however, trailing white space is
            stripped from lines); this can affect how options are parsed
            if included in the input.


       -𝗻   Equivalent to --𝗲𝘅𝗰𝗺𝗱=n̲u̲m̲b̲e̲r̲.


       -𝐍   Equivalent to --𝗲𝘅𝗰𝗺𝗱=p̲a̲t̲t̲e̲r̲n̲.


       -𝗼 t̲a̲g̲f̲i̲l̲e̲
            Equivalent to -𝗳 t̲a̲g̲f̲i̲l̲e̲.


       -𝐑   Equivalent to --𝗿𝗲𝗰𝘂𝗿𝘀𝗲.


       -𝘂   Equivalent to --𝘀𝗼𝗿𝘁=n̲o̲ (i.e. "unsorted").


       -𝐕   Equivalent to --𝘃𝗲𝗿𝗯𝗼𝘀𝗲.


       -𝘄   This  option  is silently ignored for backward-compatibility
            with the ctags of SVR4 Unix.


       -𝘅   Print a tabular, human-readable cross reference (xref)  file
            to standard output instead of generating a tag file. The in‐
            formation contained in the output includes:  the  tag  name;
            the kind of tag; the line number, file name, and source line
            (with extra white space condensed) of the file which defines
            the  tag.  No  tag file is written and all options affecting
            tag file output will be ignored.  Example  applications  for
            this  feature  are generating a listing of all functions lo‐
            cated in a source file (e.g. 𝗰𝘁𝗮𝗴𝘀 -𝘅 --𝗰-𝗸𝗶𝗻𝗱𝘀=f̲ f̲i̲l̲e̲),  or
            generating a list of all externally visible global variables
            located  in  a  source  file  (e.g.  𝗰𝘁𝗮𝗴𝘀  -𝘅   --𝗰-𝗸𝗶𝗻𝗱𝘀=v̲
            --𝗳𝗶𝗹𝗲-𝘀𝗰𝗼𝗽𝗲=n̲o̲  f̲i̲l̲e̲).  This  option must appear before the
            first file name.


       --𝗮𝗽𝗽𝗲𝗻𝗱[=y̲e̲s̲|n̲o̲]
            Indicates whether tags generated from  the  specified  files
            should  be appended to those already present in the tag file
            or should replace them. This option is off by default.  This
            option must appear before the first file name.


       --𝗲𝘁𝗮𝗴𝘀-𝗶𝗻𝗰𝗹𝘂𝗱𝗲=f̲i̲l̲e̲
            Include a reference to f̲i̲l̲e̲ in the tag file. This option may
            be specified as many times as desired. This supports  Emacs'
            capability  to  use  a  tag  file which "includes" other tag
            files. [Available only in etags mode]


       --𝗲𝘅𝗰𝗹𝘂𝗱𝗲=[p̲a̲t̲t̲e̲r̲n̲]
            Add p̲a̲t̲t̲e̲r̲n̲ to a list of  excluded  files  and  directories.
            This  option  may be specified as many times as desired. For
            each file name considered by 𝗰𝘁𝗮𝗴𝘀, each  p̲a̲t̲t̲e̲r̲n̲  specified
            using this option will be compared against both the complete
            path (e.g.  some/path/base.ext)  and  the  base  name  (e.g.
            base.ext)  of the file, thus allowing patterns which match a
            given file name irrespective of its path, or  match  only  a
            specific  path. If appropriate support is available from the
            runtime library of your C compiler, then p̲a̲t̲t̲e̲r̲n̲ may contain
            the  usual  shell wildcards (not regular expressions) common
            on Unix (be sure to quote the option  parameter  to  protect
            the  wildcards from being expanded by the shell before being
            passed to 𝗰𝘁𝗮𝗴𝘀; also be aware that wildcards can match  the
            slash  character, '/'). You can determine if shell wildcards
            are available on your platform by examining  the  output  of
            the --𝘃𝗲𝗿𝘀𝗶𝗼𝗻 option, which will include "+wildcards" in the
            compiled feature list; otherwise, p̲a̲t̲t̲e̲r̲n̲ is matched against
            file names using a simple textual comparison.

            If  p̲a̲t̲t̲e̲r̲n̲  begins with the character '@', then the rest of
            the string is interpreted as a file name from which to  read
            exclusion  patterns,  one per line. If p̲a̲t̲t̲e̲r̲n̲ is empty, the
            list of excluded patterns is cleared.  Note that at  program
            startup, the default exclude list contains "EIFGEN", "SCCS",
            "RCS", and "CVS", which are names of directories  for  which
            it  is  generally  not desirable to descend while processing
            the --𝗿𝗲𝗰𝘂𝗿𝘀𝗲 option.


       --𝗲𝘅𝗰𝗺𝗱=t̲y̲p̲e̲
            Determines the type of EX command used to locate tags in the
            source file.  [Ignored in etags mode]

            The  valid  values  for  t̲y̲p̲e̲ (either the entire word or the
            first letter is accepted) are:


            n̲u̲m̲b̲e̲r̲   Use only line numbers in the tag file for  locating
                     tags. This has four advantages:
                     1.  Significantly reduces the size of the resulting
                         tag file.
                     2.  Eliminates failures to find  tags  because  the
                         line  defining the tag has changed, causing the
                         pattern match to fail (note that some  editors,
                         such  as  𝘃𝗶𝗺, are able to recover in many such
                         instances).
                     3.  Eliminates finding identical matching, but  in‐
                         correct, source lines (see 𝐁𝐔𝐆𝐒, below).
                     4.  Retains  separate  entries  in the tag file for
                         lines which are identical in content.  In  p̲a̲t̲‐̲
                         t̲e̲r̲n̲  mode,  duplicate  entries are dropped be‐
                         cause the search  patterns  they  generate  are
                         identical,  making  the  duplicate entries use‐
                         less.


                     However, this option has one significant  drawback:
                     changes to the source files can cause the line num‐
                     bers recorded in the tag file to no  longer  corre‐
                     spond  to  the  lines  in  the source file, causing
                     jumps to some tags to miss the target definition by
                     one  or  more lines. Basically, this option is best
                     used when the source code to which it is applied is
                     not  subject  to change. Selecting this option type
                     causes the following options to be ignored: -𝐁𝐅.


            p̲a̲t̲t̲e̲r̲n̲  Use only search patterns for all tags, rather  than
                     the  line  numbers  usually  used for macro defini‐
                     tions. This has the advantage  of  not  referencing
                     obsolete line numbers when lines have been added or
                     removed since the tag file was generated.


            m̲i̲x̲e̲d̲    In this mode, patterns are generally  used  with  a
                     few  exceptions.  For  C, line numbers are used for
                     macro definition tags. This was the default  format
                     generated  by the original 𝗰𝘁𝗮𝗴𝘀 and is, therefore,
                     retained as the default for this option.  For  For‐
                     tran,  line  numbers are used for common blocks be‐
                     cause their corresponding source lines  are  gener‐
                     ally identical, making pattern searches useless for
                     finding all matches.


       --𝗲𝘅𝘁𝗿𝗮=[̲+̲|̲-̲]̲f̲l̲a̲g̲s̲
            Specifies whether to include extra tag entries  for  certain
            kinds  of  information. The parameter f̲l̲a̲g̲s̲ is a set of one-
            letter flags, each representing one kind of extra tag  entry
            to  include  in the tag file. If f̲l̲a̲g̲s̲ is preceded by either
            the '+' or '-' character, the effect of each flag  is  added
            to,  or removed from, those currently enabled; otherwise the
            flags replace any current settings. The meaning of each flag
            is as follows:


               f̲   Include  an  entry  for  the  base file name of every
                   source file (e.g.  "example.c"), which addresses  the
                   first line of the file.

               q̲   Include  an  extra class-qualified tag entry for each
                   tag which is a member of a class (for  languages  for
                   which  this  information is extracted; currently C++,
                   Eiffel, and Java). The actual form of  the  qualified
                   tag  depends upon the language from which the tag was
                   derived (using a form that is most  natural  for  how
                   qualified  calls  are specified in the language). For
                   C++, it is in the form  "class::member";  for  Eiffel
                   and  Java, it is in the form "class.member". This may
                   allow easier location of a specific tags when  multi‐
                   ple  occurrences of a tag name occur in the tag file.
                   Note, however, that this could potentially more  than
                   double the size of the tag file.


       --𝗳𝗶𝗲𝗹𝗱𝘀=[̲+̲|̲-̲]̲f̲l̲a̲g̲s̲
            Specifies the available extension fields which are to be in‐
            cluded in the entries of the tag file (see 𝐓𝐀𝐆 𝐅𝐈𝐋𝐄  𝐅𝐎𝐑𝐌𝐀𝐓,
            below,  for  more information). The parameter f̲l̲a̲g̲s̲ is a set
            of one-letter flags, each representing one type of extension
            field  to  include, with the following meanings (disabled by
            default unless indicated):


               a̲   Access (or export) of class members
               f̲   File-restricted scoping [enabled]
               i̲   Inheritance information
               k̲   Kind of tag as a single letter [enabled]
               K̲   Kind of tag as full name
               l̲   Language of source file containing tag
               m̲   Implementation information
               n̲   Line number of tag definition
               s̲   Scope of tag definition [enabled]
               S̲   Signature of routine  (e.g.  prototype  or  parameter
                   list)
               z̲   Include the "kind:" key in kind field
               t̲   Type  and name of a variable or typedef as "typeref:"
                   field [enabled]

            Each letter or group of letters may be  preceded  by  either
            '+'  to  add it to the default set, or '-' to exclude it. In
            the absence of any preceding '+' or  '-'  sign,  only  those
            kinds  explicitly  listed  in  f̲l̲a̲g̲s̲ will be included in the
            output (i.e. overriding the default set). This option is ig‐
            nored  if  the option --𝗳𝗼𝗿𝗺𝗮𝘁=1̲ has been specified. The de‐
            fault value of this option is f̲k̲s̲t̲.


       --𝗳𝗶𝗹𝗲-𝘀𝗰𝗼𝗽𝗲[=y̲e̲s̲|n̲o̲]
            Indicates whether tags scoped only for a single  file  (i.e.
            tags  which cannot be seen outside of the file in which they
            are defined, such as "static" tags) should  be  included  in
            the output. See, also, the -𝗵 option. This option is enabled
            by default.


       --𝗳𝗶𝗹𝘁𝗲𝗿[=y̲e̲s̲|n̲o̲]
            Causes 𝗰𝘁𝗮𝗴𝘀 to behave as  a  filter,  reading  source  file
            names  from  standard input and printing their tags to stan‐
            dard output on a file-by-file basis. If --𝘀𝗼𝗿𝘁𝗲𝗱 is enabled,
            tags  are  sorted  only within the source file in which they
            are defined. File names are  read  from  standard  input  in
            line-oriented  input  mode (see note for -𝐋 option) and only
            after file names listed on the command line or from any file
            supplied  using  the -𝐋 option. When this option is enabled,
            the options -𝗳, -𝗼, and --𝘁𝗼𝘁𝗮𝗹𝘀 are ignored. This option is
            quite  esoteric and is disabled by default. This option must
            appear before the first file name.


       --𝗳𝗶𝗹𝘁𝗲𝗿-𝘁𝗲𝗿𝗺𝗶𝗻𝗮𝘁𝗼𝗿=s̲t̲r̲i̲n̲g̲
            Specifies a string to print to standard output following the
            tags  for  each file name parsed when the --𝗳𝗶𝗹𝘁𝗲𝗿 option is
            enabled. This may permit an application reading  the  output
            of  ctags to determine when the output for each file is fin‐
            ished. Note that if the file name read is  a  directory  and
            --𝗿𝗲𝗰𝘂𝗿𝘀𝗲  is enabled, this string will be printed only once
            at the end of all tags found for by  descending  the  direc‐
            tory. This string will always be separated from the last tag
            line for the file by its terminating newline.   This  option
            is  quite esoteric and is empty by default. This option must
            appear before the first file name.


       --𝗳𝗼𝗿𝗺𝗮𝘁=l̲e̲v̲e̲l̲
            Change the format of the output tag file. Currently the only
            valid  values  for  l̲e̲v̲e̲l̲  are 1̲ or 2̲. Level 1 specifies the
            original tag file format and level 2  specifies  a  new  ex‐
            tended  format  containing extension fields (but in a manner
            which retains backward-compatibility with original 𝘃𝗶(1) im‐
            plementations). The default level is 2. This option must ap‐
            pear before the first file name. [Ignored in etags mode]


       --𝗵𝗲𝗹𝗽
            Prints to standard output a detailed usage description,  and
            then exits.


       --𝗶𝗳𝟬[=y̲e̲s̲|n̲o̲]
            Indicates  a preference as to whether code within an "#if 0"
            branch of a preprocessor conditional should be examined  for
            non-macro tags (macro tags are always included). Because the
            intent of this construct is to  disable  code,  the  default
            value of this option is n̲o̲. Note that this indicates a pref‐
            erence only and does not guarantee skipping code  within  an
            "#if 0" branch, since the fall-back algorithm used to gener‐
            ate tags when preprocessor conditionals are too complex fol‐
            lows  all branches of a conditional. This option is disabled
            by default.


       --<𝐋𝐀𝐍𝐆>-𝗸𝗶𝗻𝗱𝘀=[̲+̲|̲-̲]̲k̲i̲n̲d̲s̲
            Specifies a list of  language-specific  kinds  of  tags  (or
            kinds)  to  include in the output file for a particular lan‐
            guage, where <𝐋𝐀𝐍𝐆> is case-insensitive and is  one  of  the
            built-in language names (see the --𝗹𝗶𝘀𝘁-𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲𝘀 option for
            a complete list). The parameter k̲i̲n̲d̲s̲ is a group of one-let‐
            ter  flags designating kinds of tags (particular to the lan‐
            guage) to either include or exclude  from  the  output.  The
            specific  sets  of flags recognized for each language, their
            meanings and defaults may be list using the --𝗹𝗶𝘀𝘁-𝗸𝗶𝗻𝗱𝘀 op‐
            tion. Each letter or group of letters may be preceded by ei‐
            ther '+' to add it to, or '-' to remove it from, the default
            set.  In  the absence of any preceding '+' or '-' sign, only
            those kinds explicitly listed in k̲i̲n̲d̲s̲ will be  included  in
            the  output  (i.e.  overriding the default for the specified
            language).

            As an example for the C language, in order to add prototypes
            and external variable declarations to the default set of tag
            kinds, but exclude macros, use --𝗰-𝗸𝗶𝗻𝗱𝘀=+̲p̲x̲-̲d̲;  to  include
            only tags for functions, use --𝗰-𝗸𝗶𝗻𝗱𝘀=f̲.


       --𝗹𝗮𝗻𝗴𝗱𝗲𝗳=n̲a̲m̲e̲
            Defines a new user-defined language, n̲a̲m̲e̲, to be parsed with
            regular expressions. Once defined, n̲a̲m̲e̲ may be used in other
            options  taking  language names. The typical use of this op‐
            tion is to first define the language, then map file names to
            it  using  -̲-̲l̲a̲n̲g̲m̲a̲p̲, then specify regular expressions using
            -̲-̲r̲e̲g̲e̲x̲-̲<̲L̲A̲N̲G̲>̲ to define how its tags are found.


       --𝗹𝗮𝗻𝗴𝗺𝗮𝗽=m̲a̲p̲[̲,̲m̲a̲p̲[̲.̲.̲.̲]̲]̲
            Controls how file names are mapped  to  languages  (see  the
            --𝗹𝗶𝘀𝘁-𝗺𝗮𝗽𝘀  option).  Each  comma-separated m̲a̲p̲ consists of
            the language name (either a built-in  or  user-defined  lan‐
            guage),  a  colon, and a list of file extensions and/or file
            name patterns. A file extension is  specified  by  preceding
            the extension with a period (e.g. ".c"). A file name pattern
            is specified by enclosing the pattern in  parentheses  (e.g.
            "([Mm]akefile)").  If  appropriate support is available from
            the runtime library of your C compiler, then the  file  name
            pattern may contain the usual shell wildcards common on Unix
            (be sure to quote the option parameter to protect the  wild‐
            cards  from  being expanded by the shell before being passed
            to 𝗰𝘁𝗮𝗴𝘀). You can determine if shell wildcards  are  avail‐
            able  on your platform by examining the output of the --𝘃𝗲𝗿‐
            𝘀𝗶𝗼𝗻 option, which will include "+wildcards" in the compiled
            feature  list; otherwise, the file name patterns are matched
            against file names using a simple textual  comparison.  When
            mapping a file extension, it will first be unmapped from any
            other languages.

            If the first character in a map is a plus sign, then the ex‐
            tensions and file name patterns in that map will be appended
            to the current map for that  language;  otherwise,  the  map
            will  replace  the current map. For example, to specify that
            only files with extensions of .c and .x are to be treated as
            C  language files, use "--𝗹𝗮𝗻𝗴𝗺𝗮𝗽=c̲:̲.̲c̲.̲x̲"; to also add files
            with extensions  of  .j  as  Java  language  files,  specify
            "--𝗹𝗮𝗻𝗴𝗺𝗮𝗽=c̲:̲.̲c̲.̲x̲,̲j̲a̲v̲a̲:̲+̲.̲j̲".  To  map  makefiles (e.g. files
            named either "Makefile", "makefile", or having the extension
            ".mak")    to    a    language    called   "make",   specify
            "--𝗹𝗮𝗻𝗴𝗺𝗮𝗽=m̲a̲k̲e̲:̲(̲[̲M̲m̲]̲a̲k̲e̲f̲i̲l̲e̲)̲.̲m̲a̲k̲".  To map files having  no
            extension,  specify  a  period  not followed by a non-period
            character (e.g. ".", "..x", ".x."). To clear the mapping for
            a  particular language (thus inhibiting automatic generation
            of tags for that language), specify an empty extension  list
            (e.g.   "--𝗹𝗮𝗻𝗴𝗺𝗮𝗽=f̲o̲r̲t̲r̲a̲n̲:̲").  To  restore the default lan‐
            guage mappings for all a  particular  language,  supply  the
            keyword  "default"  for the mapping.  To specify restore the
            default  language  mappings  for  all   languages,   specify
            "--𝗹𝗮𝗻𝗴𝗺𝗮𝗽=d̲e̲f̲a̲u̲l̲t̲".  Note  that  file extensions are tested
            before file name patterns when inferring the language  of  a
            file.


       --𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲-𝗳𝗼𝗿𝗰𝗲=l̲a̲n̲g̲u̲a̲g̲e̲
            By  default,  𝗰𝘁𝗮𝗴𝘀  automatically selects the language of a
            source file, ignoring those files whose language  cannot  be
            determined (see 𝐒𝐎𝐔𝐑𝐂𝐄 𝐅𝐈𝐋𝐄𝐒, above). This option forces the
            specified l̲a̲n̲g̲u̲a̲g̲e̲  (case-insensitive;  either  built-in  or
            user-defined)  to be used for every supplied file instead of
            automatically selecting the language based upon  its  exten‐
            sion. In addition, the special value a̲u̲t̲o̲ indicates that the
            language should be automatically selected (which effectively
            disables this option).


       --𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲𝘀=[̲+̲|̲-̲]̲l̲i̲s̲t̲
            Specifies the languages for which tag generation is enabled,
            with l̲i̲s̲t̲ containing  a  comma-separated  list  of  language
            names  (case-insensitive;  either built-in or user-defined).
            If the first language of l̲i̲s̲t̲ is not preceded  by  either  a
            '+'  or  '-', the current list will be cleared before adding
            or removing the languages in l̲i̲s̲t̲. Until a  '-'  is  encoun‐
            tered,  each  language in the list will be added to the cur‐
            rent list. As either the '+' or '-' is  encountered  in  the
            list,  the  languages following it are added or removed from
            the current list, respectively. Thus, it becomes  simple  to
            replace the current list with a new one, or to add or remove
            languages from the current list. The actual  list  of  files
            for  which  tags will be generated depends upon the language
            extension mapping in effect (see the --𝗹𝗮𝗻𝗴𝗺𝗮𝗽 option). Note
            that all languages, including user-defined languages are en‐
            abled unless explicitly disabled using this option. Language
            names  included  in l̲i̲s̲t̲ may be any built-in language or one
            previously defined with --𝗹𝗮𝗻𝗴𝗱𝗲𝗳.  The  default  is  "all",
            which  is  also  accepted  as  a  valid  argument.  See  the
            --𝗹𝗶𝘀𝘁-𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲𝘀 option for a complete list of the  built-in
            language names.


       --𝗹𝗶𝗰𝗲𝗻𝘀𝗲
            Prints a summary of the software license to standard output,
            and then exits.


       --𝗹𝗶𝗻𝗲-𝗱𝗶𝗿𝗲𝗰𝘁𝗶𝘃𝗲𝘀[=y̲e̲s̲|n̲o̲]
            Specifies whether "#line" directives should  be  recognized.
            These are present in the output of preprocessors and contain
            the line number, and possibly the file name, of the original
            source  file(s)  from which the preprocessor output file was
            generated. When enabled, this option  will  cause  𝗰𝘁𝗮𝗴𝘀  to
            generate  tag  entries  marked  with the file names and line
            numbers of their locations original source file(s),  instead
            of  their  actual  locations in the preprocessor output. The
            actual file names placed into the tag  file  will  have  the
            same  leading  path  components  as  the preprocessor output
            file, since it is assumed that the original source files are
            located relative to the preprocessor output file (unless, of
            course, the #line directive  specifies  an  absolute  path).
            This  option  is off by default. 𝐍𝗼𝘁𝗲: This option is gener‐
            ally only useful when used together with the  --𝗲𝘅𝗰𝗺𝗱=n̲u̲m̲b̲e̲r̲
            (-𝗻)  option. Also, you may have to use either the --𝗹𝗮𝗻𝗴𝗺𝗮𝗽
            or --𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲-𝗳𝗼𝗿𝗰𝗲 option if  the  extension  of  the  pre‐
            processor output file is not known to 𝗰𝘁𝗮𝗴𝘀.


       --𝗹𝗶𝗻𝗸𝘀[=y̲e̲s̲|n̲o̲]
            Indicates  whether  symbolic  links (if supported) should be
            followed. When disabled, symbolic links  are  ignored.  This
            option is on by default.


       --𝗹𝗶𝘀𝘁-𝗸𝗶𝗻𝗱𝘀[=l̲a̲n̲g̲u̲a̲g̲e̲|a̲l̲l̲]
            Lists the tag kinds recognized for either the specified lan‐
            guage or all languages, and then exits.  Each  kind  of  tag
            recorded  in  the  tag  file  is represented by a one-letter
            flag, which is also used to filter the tags placed into  the
            output  through  use of the --<𝐋𝐀𝐍𝐆>-𝗸𝗶𝗻𝗱𝘀 option. Note that
            some languages and/or tag kinds  may  be  implemented  using
            regular  expressions  and may not be available if regex sup‐
            port is not compiled into 𝗰𝘁𝗮𝗴𝘀 (see the --𝗿𝗲𝗴𝗲𝘅-<𝐋𝐀𝐍𝐆>  op‐
            tion).  Each  kind  listed  is  enabled  unless  followed by
            "[off]".


       --𝗹𝗶𝘀𝘁-𝗺𝗮𝗽𝘀[=l̲a̲n̲g̲u̲a̲g̲e̲|a̲l̲l̲]
            Lists the file extensions and file name patterns which asso‐
            ciate  a  file name with a language for either the specified
            language or all languages, and then exits. See the --𝗹𝗮𝗻𝗴𝗺𝗮𝗽
            option, and 𝐒𝐎𝐔𝐑𝐂𝐄 𝐅𝐈𝐋𝐄𝐒, above.


       --𝗹𝗶𝘀𝘁-𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲𝘀
            Lists  the  names  of the languages understood by 𝗰𝘁𝗮𝗴𝘀, and
            then exits.  These language names are case  insensitive  and
            may   be   used   in   the   --𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲-𝗳𝗼𝗿𝗰𝗲,  --𝗹𝗮𝗻𝗴𝘂𝗮𝗴𝗲𝘀,
            --<𝐋𝐀𝐍𝐆>-𝗸𝗶𝗻𝗱𝘀, and --𝗿𝗲𝗴𝗲𝘅-<𝐋𝐀𝐍𝐆> options.


       --𝗼𝗽𝘁𝗶𝗼𝗻𝘀=f̲i̲l̲e̲
            Read additional options from f̲i̲l̲e̲. The file  should  contain
            one option per line. As a special case, if --𝗼𝗽𝘁𝗶𝗼𝗻𝘀=N̲O̲N̲E̲ is
            specified as the first option on the command line,  it  will
            disable  the  automatic reading of any configuration options
            from either a file or the environment (see 𝐅𝐈𝐋𝐄𝐒).


       --𝗿𝗲𝗰𝘂𝗿𝘀𝗲[=y̲e̲s̲|n̲o̲]
            Recurse into directories encountered in the list of supplied
            files.  If  the  list of supplied files is empty and no file
            list is specified with the -𝐋 option, then the  current  di‐
            rectory  (i.e. ".") is assumed. Symbolic links are followed.
            If you don't like these behaviors, either explicitly specify
            the  files  or pipe the output of 𝗳𝗶𝗻𝗱(1) into 𝗰𝘁𝗮𝗴𝘀 -𝐋- in‐
            stead. 𝐍𝗼𝘁𝗲: This option is not supported on  all  platforms
            at present.  It is available if the output of the --𝗵𝗲𝗹𝗽 op‐
            tion includes this option.   See,  also,  the  --𝗲𝘅𝗰𝗹𝘂𝗱𝗲  to
            limit recursion.


       --𝗿𝗲𝗴𝗲𝘅-<𝐋𝐀𝐍𝐆>=/̲r̲e̲g̲e̲x̲p̲/̲r̲e̲p̲l̲a̲c̲e̲m̲e̲n̲t̲/̲[̲k̲i̲n̲d̲-̲s̲p̲e̲c̲/̲]̲[̲f̲l̲a̲g̲s̲]̲
            The  /̲r̲e̲g̲e̲x̲p̲/̲r̲e̲p̲l̲a̲c̲e̲m̲e̲n̲t̲/̲  pair  define a regular expression
            replacement pattern, similar in style  to  𝘀𝗲𝗱  substitution
            commands,  with  which  to  generate  tags from source files
            mapped to the named language, <𝐋𝐀𝐍𝐆>, (case-insensitive; ei‐
            ther  a  built-in or user-defined language). The regular ex‐
            pression, r̲e̲g̲e̲x̲p̲, defines  an  extended  regular  expression
            (roughly  that  used by 𝗲𝗴𝗿𝗲𝗽(1)), which is used to locate a
            single source line containing a  tag  and  may  specify  tab
            characters  using  \t.  When a matching line is found, a tag
            will be generated for the name defined by r̲e̲p̲l̲a̲c̲e̲m̲e̲n̲t̲, which
            generally   will  contain  the  special  back-references  \1
            through \9 to refer to matching sub-expression groups within
            r̲e̲g̲e̲x̲p̲.  The '/' separator characters shown in the parameter
            to the option can actually be  replaced  by  any  character.
            Note that whichever separator character is used will have to
            be escaped with a backslash ('\') character wherever  it  is
            used  in  the parameter as something other than a separator.
            The regular expression defined by this option  is  added  to
            the  current  list  of regular expressions for the specified
            language unless the parameter is omitted, in which case  the
            current list is cleared.

            Unless  modified  by f̲l̲a̲g̲s̲, r̲e̲g̲e̲x̲p̲ is interpreted as a Posix
            extended regular expression. The r̲e̲p̲l̲a̲c̲e̲m̲e̲n̲t̲  should  expand
            for  all matching lines to a non-empty string of characters,
            or a warning message will  be  reported.  An  optional  kind
            specifier  for  tags matching r̲e̲g̲e̲x̲p̲ may follow r̲e̲p̲l̲a̲c̲e̲m̲e̲n̲t̲,
            which will determine what kind of tag  is  reported  in  the
            "kind"  extension  field  (see  𝐓𝐀𝐆 𝐅𝐈𝐋𝐄 𝐅𝐎𝐑𝐌𝐀𝐓, below). The
            full form of k̲i̲n̲d̲-̲s̲p̲e̲c̲ is in the form of a single letter,  a
            comma, a name (without spaces), a comma, a description, fol‐
            lowed by a separator, which specify the short and long forms
            of the kind value and its textual description (displayed us‐
            ing --𝗹𝗶𝘀𝘁-𝗸𝗶𝗻𝗱𝘀). Either the kind name and/or the  descrip‐
            tion may be omitted. If k̲i̲n̲d̲-̲s̲p̲e̲c̲ is omitted, it defaults to
            "r̲,̲r̲e̲g̲e̲x̲". Finally, f̲l̲a̲g̲s̲  are  one  or  more  single-letter
            characters  having the following effect upon the interpreta‐
            tion of r̲e̲g̲e̲x̲p̲:


               b̲   The pattern is interpreted as a Posix  basic  regular
                   expression.

               e̲   The  pattern is interpreted as a Posix extended regu‐
                   lar expression (default).

               i̲   The regular expression is to be applied in a case-in‐
                   sensitive manner.

            Note  that  this  option is available only if 𝗰𝘁𝗮𝗴𝘀 was com‐
            piled with support for regular  expressions,  which  depends
            upon your platform. You can determine if support for regular
            expressions is compiled in by examining the  output  of  the
            --𝘃𝗲𝗿𝘀𝗶𝗼𝗻  option,  which  will include "+regex" in the com‐
            piled feature list.

            For more information on  the  regular  expressions  used  by
            𝗰𝘁𝗮𝗴𝘀,  see  either the 𝗿𝗲𝗴𝗲𝘅(𝟱,𝟳) man page, or the GNU info
            documentation for regex (e.g. "info regex").


       --𝘀𝗼𝗿𝘁[=y̲e̲s̲|n̲o̲|f̲o̲l̲d̲c̲a̲s̲e̲]
            Indicates whether the tag file should be sorted on  the  tag
            name (default is y̲e̲s̲). Note that the original 𝘃𝗶(1) required
            sorted tags.  The f̲o̲l̲d̲c̲a̲s̲e̲ value specifies case  insensitive
            (or case-folded) sorting.  Fast binary searches of tag files
            sorted with case-folding will require special  support  from
            tools using tag files, such as that found in the ctags read‐
            tags library, or Vim version 6.2 or higher (using  "set  ig‐
            norecase").  This  option  must appear before the first file
            name. [Ignored in etags mode]


       --𝘁𝗮𝗴-𝗿𝗲𝗹𝗮𝘁𝗶𝘃𝗲[=y̲e̲s̲|n̲o̲]
            Indicates that the file  paths  recorded  in  the  tag  file
            should be relative to the directory containing the tag file,
            rather than relative to the current  directory,  unless  the
            files  supplied on the command line are specified with abso‐
            lute paths. This option must appear before  the  first  file
            name. The default is y̲e̲s̲ when running in etags mode (see the
            -𝗲 option), n̲o̲ otherwise.


       --𝘁𝗼𝘁𝗮𝗹𝘀[=y̲e̲s̲|n̲o̲]
            Prints statistics about the source files read  and  the  tag
            file  written  during  the current invocation of 𝗰𝘁𝗮𝗴𝘀. This
            option is off by default.  This option  must  appear  before
            the first file name.


       --𝘃𝗲𝗿𝗯𝗼𝘀𝗲[=y̲e̲s̲|n̲o̲]
            Enable  verbose  mode. This prints out information on option
            processing and a brief message describing what action is be‐
            ing taken for each file considered by 𝗰𝘁𝗮𝗴𝘀. Normally, 𝗰𝘁𝗮𝗴𝘀
            does not read command line arguments until after options are
            read from the configuration files (see 𝐅𝐈𝐋𝐄𝐒, below) and the
            𝐂𝐓𝐀𝐆𝐒 environment variable. However, if this option  is  the
            first  argument on the command line, it will take effect be‐
            fore any options are read from these sources. The default is
            n̲o̲.


       --𝘃𝗲𝗿𝘀𝗶𝗼𝗻
            Prints  a  version  identifier for 𝗰𝘁𝗮𝗴𝘀 to standard output,
            and then exits. This is guaranteed  to  always  contain  the
            string "Exuberant Ctags".



𝐎𝐏𝐄𝐑𝐀𝐓𝐈𝐎𝐍𝐀𝐋 𝐃𝐄𝐓𝐀𝐈𝐋𝐒
       As  𝗰𝘁𝗮𝗴𝘀 considers each file name in turn, it tries to determine
       the language of the file by applying the following three tests in
       order:  if  the  file extension has been mapped to a language, if
       the file name matches a shell pattern mapped to a  language,  and
       finally if the file is executable and its first line specifies an
       interpreter using the Unix-style "#!" specification (if supported
       on  the  platform).  If  a  language  was identified, the file is
       opened and then the appropriate language parser is called to  op‐
       erate  on  the currently open file. The parser parses through the
       file and adds an entry to the tag file for each  language  object
       it  is written to handle. See 𝐓𝐀𝐆 𝐅𝐈𝐋𝐄 𝐅𝐎𝐑𝐌𝐀𝐓, below, for details
       on these entries.

       This implementation of 𝗰𝘁𝗮𝗴𝘀 imposes no  formatting  requirements
       on  C code as do legacy implementations. Older implementations of
       ctags tended to rely upon certain formatting assumptions in order
       to  help it resolve coding dilemmas caused by preprocessor condi‐
       tionals.

       In general, 𝗰𝘁𝗮𝗴𝘀 tries to be smart about conditional  preproces‐
       sor  directives.  If  a  preprocessor  conditional is encountered
       within a statement which defines a tag, 𝗰𝘁𝗮𝗴𝘀  follows  only  the
       first  branch  of that conditional (except in the special case of
       "#if 0", in which case it follows only the last branch). The rea‐
       son for this is that failing to pursue only one branch can result
       in ambiguous syntax, as in the following example:

              #ifdef TWO_ALTERNATIVES
              struct {
              #else
              union {
              #endif
                  short a;
                  long b;
              }

       Both branches cannot be followed, or braces become unbalanced and
       𝗰𝘁𝗮𝗴𝘀 would be unable to make sense of the syntax.

       If  the  application  of this heuristic fails to properly parse a
       file, generally  due  to  complicated  and  inconsistent  pairing
       within  the  conditionals, 𝗰𝘁𝗮𝗴𝘀 will retry the file using a dif‐
       ferent heuristic which does not  selectively  follow  conditional
       preprocessor  branches,  but instead falls back to relying upon a
       closing brace ("}") in column 1 as indicating the end of a  block
       once any brace imbalance results from following a #if conditional
       branch.

       𝐂𝘁𝗮𝗴𝘀 will also try to specially handle arguments lists  enclosed
       in  double  sets  of parentheses in order to accept the following
       conditional construct:

              extern void foo __ARGS((int one, char two));

       Any name immediately preceding the "((" will be automatically ig‐
       nored and the previous name will be used.

       C++ operator definitions are specially handled. In order for con‐
       sistency with all types of operators (overloaded and conversion),
       the  operator name in the tag file will always be preceded by the
       string "operator " (i.e. even if the actual  operator  definition
       was written as "operator<<").

       After  creating or appending to the tag file, it is sorted by the
       tag name, removing identical tag lines.



𝐓𝐀𝐆 𝐅𝐈𝐋𝐄 𝐅𝐎𝐑𝐌𝐀𝐓
       When not running in etags mode, each entry in the tag  file  con‐
       sists of a separate line, each looking like this in the most gen‐
       eral case:

        tag_name<TAB>file_name<TAB>ex_cmd;"<TAB>extension_fields

       The fields and separators of these lines are  specified  as  fol‐
       lows:

           1.  tag name
           2.  single tab character
           3.  name  of the file in which the object associated with the
               tag is located
           4.  single tab character
           5.  EX command used to locate the tag within the file; gener‐
               ally  a search pattern (either /pattern/ or ?pattern?) or
               line number (see --𝗲𝘅𝗰𝗺𝗱). Tag file format 2 (see  --𝗳𝗼𝗿‐
               𝗺𝗮𝘁)  extends this EX command under certain circumstances
               to include a set of extension  fields  (described  below)
               embedded  in an EX comment immediately appended to the EX
               command, which leaves it backward-compatible with  origi‐
               nal 𝘃𝗶(1) implementations.

       A  few  special  tags  are written into the tag file for internal
       purposes. These tags are composed in such a way that they  always
       sort to the top of the file.  Therefore, the first two characters
       of these tags are used a magic number to detect a  tag  file  for
       purposes  of  determining whether a valid tag file is being over‐
       written rather than a source file.

       Note that the name of each source file will be  recorded  in  the
       tag file exactly as it appears on the command line. Therefore, if
       the path you specified on the command line was  relative  to  the
       current  directory,  then it will be recorded in that same manner
       in the tag file. See, however, the --𝘁𝗮𝗴-𝗿𝗲𝗹𝗮𝘁𝗶𝘃𝗲 option for  how
       this behavior can be modified.

       Extension  fields  are  tab-separated key-value pairs appended to
       the end of the EX command as a comment, as described above. These
       key  value  pairs  appear  in the general form "k̲e̲y̲:v̲a̲l̲u̲e̲". Their
       presence in the lines of the  tag  file  are  controlled  by  the
       --𝗳𝗶𝗲𝗹𝗱𝘀  option. The possible keys and the meaning of their val‐
       ues are as follows:


       a̲c̲c̲e̲s̲s̲      Indicates the visibility of this class member,  where
                   v̲a̲l̲u̲e̲ is specific to the language.


       f̲i̲l̲e̲        Indicates  that  the tag has file-limited visibility.
                   This key has no corresponding value.


       k̲i̲n̲d̲        Indicates the type, or kind, of tag. Its value is ei‐
                   ther  one  of  the corresponding one-letter flags de‐
                   scribed  under  the  various  --<𝐋𝐀𝐍𝐆>-𝗸𝗶𝗻𝗱𝘀  options
                   above,  or  a  full name. It is permitted (and is, in
                   fact, the default) for the key portion of this  field
                   to  be omitted. The optional behaviors are controlled
                   with the --𝗳𝗶𝗲𝗹𝗱𝘀 option.


       i̲m̲p̲l̲e̲m̲e̲n̲t̲a̲t̲i̲o̲n̲
                   When present, this indicates a limited implementation
                   (abstract  vs. concrete) of a routine or class, where
                   v̲a̲l̲u̲e̲ is specific to the language ("virtual" or "pure
                   virtual" for C++; "abstract" for Java).


       i̲n̲h̲e̲r̲i̲t̲s̲    When  present,  v̲a̲l̲u̲e̲.  is  a comma-separated list of
                   classes from which this class is derived (i.e. inher‐
                   its from).


       s̲i̲g̲n̲a̲t̲u̲r̲e̲   When present, v̲a̲l̲u̲e̲ is a language-dependent represen‐
                   tation of the signature of a routine. A routine  sig‐
                   nature in its complete form specifies the return type
                   of a routine and its formal argument list.  This  ex‐
                   tension field is presently supported only for C-based
                   languages and does not include the return type.


       In addition, information on the scope of the tag  definition  may
       be  available, with the key portion equal to some language-depen‐
       dent construct name and its value the name declared for that con‐
       struct  in  the  program. This scope entry indicates the scope in
       which the tag was found. For example, a tag  generated  for  a  C
       structure  member  would  have  a scope looking like "struct:myS‐
       truct".



𝐇𝐎𝐖 𝐓𝐎 𝐔𝐒𝐄 𝐖𝐈𝐓𝐇 𝐕𝐈
       Vi will, by default, expect a tag file by the name "tags" in  the
       current directory. Once the tag file is built, the following com‐
       mands exercise the tag indexing feature:

       𝘃𝗶 -𝘁 𝘁𝗮𝗴   Start vi and position the cursor at the file and line
                   where "tag" is defined.

       :𝘁𝗮 𝘁𝗮𝗴     Find a tag.

       𝐂𝘁𝗿𝗹-]      Find the tag under the cursor.

       𝐂𝘁𝗿𝗹-𝐓      Return  to  previous location before jump to tag (not
                   widely implemented).



𝐇𝐎𝐖 𝐓𝐎 𝐔𝐒𝐄 𝐖𝐈𝐓𝐇 𝐆𝐍𝐔 𝐄𝐌𝐀𝐂𝐒
       Emacs will, by default, expect a tag file by the name  "TAGS"  in
       the  current directory. Once the tag file is built, the following
       commands exercise the tag indexing feature:

       𝐌-𝘅 𝘃𝗶𝘀𝗶𝘁-𝘁𝗮𝗴𝘀-𝘁𝗮𝗯𝗹𝗲 <𝐑𝐄𝐓> 𝐅𝐈𝐋𝐄 <𝐑𝐄𝐓>
                 Select the tag file, "FILE", to use.

       𝐌-. [𝐓𝐀𝐆] <𝐑𝐄𝐓>
                 Find the first definition of TAG. The  default  tag  is
                 the identifier under the cursor.

       𝐌-*       Pop back to where you previously invoked "M-.".

       𝐂-𝘂 𝐌-.   Find the next definition for the last tag.


       For more commands, see the T̲a̲g̲s̲ topic in the Emacs info document.



𝐇𝐎𝐖 𝐓𝐎 𝐔𝐒𝐄 𝐖𝐈𝐓𝐇 𝐍𝐄𝐃𝐈𝐓
       NEdit  version 5.1 and later can handle the new extended tag file
       format (see --𝗳𝗼𝗿𝗺𝗮𝘁). To make NEdit use  the  tag  file,  select
       "File->Load  Tags  File".  To  jump  to the definition for a tag,
       highlight the word, then press Ctrl-D. NEdit  5.1  can  can  read
       multiple tag files from different directories.  Setting the X re‐
       source nedit.tagFile to the name of a tag file instructs NEdit to
       automatically load that tag file at startup time.



𝐂𝐀𝐕𝐄𝐀𝐓𝐒
       Because  𝗰𝘁𝗮𝗴𝘀  is  neither a preprocessor nor a compiler, use of
       preprocessor macros can fool 𝗰𝘁𝗮𝗴𝘀 into either  missing  tags  or
       improperly generating inappropriate tags. Although 𝗰𝘁𝗮𝗴𝘀 has been
       designed to handle certain common cases, this is the single  big‐
       gest  cause  of reported problems. In particular, the use of pre‐
       processor constructs which alter the textual syntax of C can fool
       𝗰𝘁𝗮𝗴𝘀. You can work around many such problems by using the -𝐈 op‐
       tion.

       Note that since 𝗰𝘁𝗮𝗴𝘀 generates patterns for locating  tags  (see
       the  --𝗲𝘅𝗰𝗺𝗱 option), it is entirely possible that the wrong line
       may be found by your editor if there exists another  source  line
       which  is identical to the line containing the tag. The following
       example demonstrates this condition:

              int variable;

              /* ... */
              void foo(variable)
              int variable;
              {
                  /* ... */
              }

       Depending upon which editor you use and where  in  the  code  you
       happen  to  be, it is possible that the search pattern may locate
       the local parameter declaration in foo() before it finds the  ac‐
       tual  global  variable definition, since the lines (and therefore
       their search patterns are identical). This can be avoided by  use
       of the --𝗲𝘅𝗰𝗺𝗱=n̲ option.



𝐁𝐔𝐆𝐒
       𝐂𝘁𝗮𝗴𝘀 has more options than 𝗹𝘀(1).

       When  parsing  a  C++  member  function  definition (e.g. "class‐
       Name::function"), 𝗰𝘁𝗮𝗴𝘀 cannot determine whether the scope speci‐
       fier is a class name or a namespace specifier and always lists it
       as a class name in the scope portion  of  the  extension  fields.
       Also,  if a C++ function is defined outside of the class declara‐
       tion (the usual case), the  access  specification  (i.e.  public,
       protected,  or private) and implementation information (e.g. vir‐
       tual, pure virtual) contained in the function declaration are not
       known  when  the tag is generated for the function definition. It
       will, however be available for prototypes (e.g --𝗰++-𝗸𝗶𝗻𝗱𝘀=+̲p̲).

       No qualified tags are generated for  language  objects  inherited
       into a class.



𝐄𝐍𝐕𝐈𝐑𝐎𝐍𝐌𝐄𝐍𝐓 𝐕𝐀𝐑𝐈𝐀𝐁𝐋𝐄𝐒
       𝐂𝐓𝐀𝐆𝐒   If  this environment variable exists, it will be expected
               to contain a set of default options which are  read  when
               𝗰𝘁𝗮𝗴𝘀  starts,  after  the  configuration files listed in
               𝐅𝐈𝐋𝐄𝐒, below, are read, but before any command  line  op‐
               tions  are  read.  Options  appearing on the command line
               will override options specified in  this  variable.  Only
               options  will  be  read from this variable. Note that all
               white space in this variable is considered  a  separator,
               making it impossible to pass an option parameter contain‐
               ing an embedded space. If this is a problem, use  a  con‐
               figuration file instead.


       𝐄𝐓𝐀𝐆𝐒   Similar  to  the  𝐂𝐓𝐀𝐆𝐒 variable above, this variable, if
               found, will be read when 𝗲𝘁𝗮𝗴𝘀 starts. If  this  variable
               is not found, 𝗲𝘁𝗮𝗴𝘀 will try to use 𝐂𝐓𝐀𝐆𝐒 instead.


       𝐓𝐌𝐏𝐃𝐈𝐑  On  Unix-like  hosts  where  mkstemp()  is available, the
               value of this variable specifies the directory  in  which
               to  place temporary files. This can be useful if the size
               of a temporary file becomes too large to fit on the  par‐
               tition holding the default temporary directory defined at
               compilation time.  𝗰𝘁𝗮𝗴𝘀 creates temporary files only  if
               either  (1)  an  emacs-style tag file is being generated,
               (2) the tag file is being sent to standard output, or (3)
               the  program  was  compiled to use an internal sort algo‐
               rithm to sort the tag files instead of the the sort util‐
               ity  of  the operating system. If the sort utility of the
               operating system is being used, it will generally observe
               this  variable  also.  Note  that if 𝗰𝘁𝗮𝗴𝘀 is setuid, the
               value of TMPDIR will be ignored.



𝐅𝐈𝐋𝐄𝐒
       /̲c̲t̲a̲g̲s̲.̲c̲n̲f̲ (̲o̲n̲ M̲S̲D̲O̲S̲,̲ M̲S̲W̲i̲n̲d̲o̲w̲s̲ o̲n̲l̲y̲)̲
       /̲e̲t̲c̲/̲c̲t̲a̲g̲s̲.̲c̲o̲n̲f̲
       /̲u̲s̲r̲/̲l̲o̲c̲a̲l̲/̲e̲t̲c̲/̲c̲t̲a̲g̲s̲.̲c̲o̲n̲f̲
       $̲H̲O̲M̲E̲/̲.̲c̲t̲a̲g̲s̲
       $̲H̲O̲M̲E̲/̲c̲t̲a̲g̲s̲.̲c̲n̲f̲ (̲o̲n̲ M̲S̲D̲O̲S̲,̲ M̲S̲W̲i̲n̲d̲o̲w̲s̲ o̲n̲l̲y̲)̲
       .̲c̲t̲a̲g̲s̲
       c̲t̲a̲g̲s̲.̲c̲n̲f̲ (̲o̲n̲ M̲S̲D̲O̲S̲,̲ M̲S̲W̲i̲n̲d̲o̲w̲s̲ o̲n̲l̲y̲)̲
              If any of these configuration files exist,  each  will  be
              expected  to  contain  a  set of default options which are
              read in the order listed when 𝗰𝘁𝗮𝗴𝘀 starts, but before the
              𝐂𝐓𝐀𝐆𝐒 environment variable is read or any command line op‐
              tions are read. This makes it possible  to  set  up  site-
              wide,  personal  or project-level defaults. It is possible
              to compile 𝗰𝘁𝗮𝗴𝘀 to read an additional configuration  file
              before  any  of those shown above, which will be indicated
              if the output produced by the --𝘃𝗲𝗿𝘀𝗶𝗼𝗻 option  lists  the
              "custom-conf"  feature. Options appearing in the 𝐂𝐓𝐀𝐆𝐒 en‐
              vironment variable or on the command  line  will  override
              options  specified  in  these  files. Only options will be
              read from these files. Note that the option files are read
              in  line-oriented  mode  in  which  spaces are significant
              (since shell quoting is not possible). Each  line  of  the
              file  is read as one command line parameter (as if it were
              quoted with single quotes). Therefore, use  new  lines  to
              indicate separate command-line arguments.


       t̲a̲g̲s̲   The default tag file created by 𝗰𝘁𝗮𝗴𝘀.

       T̲A̲G̲S̲   The default tag file created by 𝗲𝘁𝗮𝗴𝘀.


𝐒𝐄𝐄 𝐀𝐋𝐒𝐎
       The official Exuberant Ctags web site at:

              http://ctags.sourceforge.net

       Also  𝗲𝘅(1), 𝘃𝗶(1), 𝗲𝗹𝘃𝗶𝘀, or, better yet, 𝘃𝗶𝗺, the official edi‐
       tor of 𝗰𝘁𝗮𝗴𝘀. For more information on 𝘃𝗶𝗺, see the VIM Pages  web
       site at:

              http://www.vim.org/



𝐀𝐔𝐓𝐇𝐎𝐑
       Darren Hiebert <dhiebert at users.sourceforge.net>
       http://DarrenHiebert.com/



𝐌𝐎𝐓𝐈𝐕𝐀𝐓𝐈𝐎𝐍
       "Think  ye at all times of rendering some service to every member
       of the human race."

       "All effort and exertion put forth by man from  the  fullness  of
       his  heart  is  worship, if it is prompted by the highest motives
       and the will to do service to humanity."

              -- From the Baha'i Writings



𝐂𝐑𝐄𝐃𝐈𝐓𝐒
       This version of 𝗰𝘁𝗮𝗴𝘀 was originally derived from and inspired by
       the  ctags program by Steve Kirkendall <kirkenda@cs.pdx.edu> that
       comes with the Elvis vi clone (though virtually none of the orig‐
       inal code remains).

       Credit  is  also due Bram Moolenaar <Bram@vim.org>, the author of
       𝘃𝗶𝗺, who has devoted so much of his time and energy both  to  de‐
       veloping  the  editor  as a service to others, and to helping the
       orphans of Uganda.

       The section entitled "HOW TO USE WITH GNU EMACS" was  shamelessly
       stolen from the info page for GNU 𝗲𝘁𝗮𝗴𝘀.



Darren Hiebert              Version 5.9~svn20110310                   CTAGS(1)