RubyGems - ctags.rb - Versions diffs - 1.0.19 → 1.1.3 - Mend

ctags.rb 1.0.19 → 1.1.3

Files changed (2961) hide show

data/ext/vendor/exuberant-ctags/ctags.1 DELETED Viewed

@@ -1,1186 +0,0 @@
-.TH CTAGS 1 "Version 5.8" "Darren Hiebert" "Exuberant Ctags"
-.SH "NAME"
-ctags \- Generate tag files for source code
-.SH SYNOPSIS
-.TP 6
-\fBctags\fP [\fBoptions\fP] [\fIfile(s)\fP]
-.TP 6
-\fBetags\fP [\fBoptions\fP] [\fIfile(s)\fP]
-.SH "DESCRIPTION"
-The \fBctags\fP and \fBetags\fP programs (hereinafter collectively referred to
-as \fBctags\fP, except where distinguished) generate an index (or "tag") file
-for a variety of language objects found in \fIfile(s)\fP.
-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, \fBctags\fP 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:
-.RS 4
-\fBVi\fP(1) and its derivatives (e.g. Elvis, Vim, Vile, Lemmy),
-\fBCRiSP\fP,
-\fBEmacs\fP,
-\fBFTE\fP (Folding Text Editor),
-\fBJED\fP,
-\fBjEdit\fP,
-\fBMined\fP,
-\fBNEdit\fP (Nirvana Edit),
-\fBTSE\fP (The SemWare Editor),
-\fBUltraEdit\fP,
-\fBWorkSpace\fP,
-\fBX2\fP,
-\fBZeus\fP
-.RE
-\fBCtags\fP 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 \fB\-\-list\-languages\fP and \fB\-\-list\-kinds\fP options.
-.SH "SOURCE FILES"
-Unless the \fB\-\-language\-force\fP 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 language may be display using the
-\fB\-\-list\-maps\fP option and may be changed using the \fB\-\-langmap\fP 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 running
-\fBctags\fP 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.]
-.SH "OPTIONS"
-Despite the wealth of available options, defaults are set so that \fBctags\fP
-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 special 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 "\fI[=yes\fP|\fIno]\fP" parameter) may
-be omitted, in which case "\fB=\fP\fIyes\fP" is implied. (e.g. \fB\-\-sort\fP
-is equivalent to \fB\-\-sort\fP=\fIyes\fP). Note further that "=\fI1\fP" and
-"=\fIon\fP" are considered synonyms for "=\fIyes\fP", and that "=\fI0\fP"
-and "=\fIoff\fP" are considered synonyms for "=\fIno\fP".
-Some options are either ignored or useful only when used while running in
-etags mode (see \fB\-e\fP 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 \fB\-\-list\-languages\fP option for a complete list of the
-built-in language names.
-.TP 5
-.B \-a
-Equivalent to \fB\-\-append\fP.
-.TP 5
-.B \-B
-Use backward searching patterns (e.g. ?pattern?). [Ignored in etags mode]
-.TP 5
-.B \-e
-Enable etags mode, which will create a tag file for use with the Emacs editor.
-Alternatively, if \fBctags\fP is invoked by a name containing the string
-"etags" (either by renaming, or creating a link to, the executable), etags
-mode will be enabled. This option must appear before the first file name.
-.TP 5
-.BI \-f " tagfile"
-Use the name specified by \fItagfile\fP for the tag file (default is "tags",
-or "TAGS" when running in etags mode). If \fItagfile\fP is specified as
-"\-", then the tag file is written to standard output instead. \fBCtags\fP
-will stubbornly refuse to take orders if \fItagfile\fP exists and its first
-line contains something 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.
-.TP 5
-.B \-F
-Use forward searching patterns (e.g. /pattern/) (default).
-[Ignored in etags mode]
-.TP 5
-.BI \-h  " list"
-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 followed 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 extension 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 \fB\-\-file\-scope\fP option. The default list is
-".h.H.hh.hpp.hxx.h++.inc.def". To restore the default list, specify \fB\-h\fP
-\fIdefault\fP. Note that if an extension supplied to this option is not
-already mapped to a particular language (see \fBSOURCE FILES\fP, above), you
-will also need to use either the \fB\-\-langmap\fP or \fB\-\-language\-force\fP
-option.
-.TP 5
-.BI \-I " identifier\-list"
-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 ignored
-during parsing of the source files. If an identifier is suffixed with a '+'
-character, \fBctags\fP will also ignore any parenthesis-enclosed argument list
-which may immediately follow the identifier in the source files. If two
-identifiers are separated with the '=' character, the first identifiers 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 \fIidentifier\-list\fP is '@', '.' or
-a pathname separator ('/' or '\\'), or the first two characters specify a
-drive letter (e.g. "C:"), the parameter \fIidentifier\-list\fP will be
-interpreted as a filename from which to read a list of identifiers, one per
-input line. Otherwise, \fIidentifier\-list\fP 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 \fB\-I\fP options may be supplied.
-To clear the list of ignore identifiers, supply a single dash ("\-") for
-\fIidentifier\-list\fP.
-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 \fBCAVEATS\fP, below). Some
-examples will illustrate this point.
-.RS 8
-int foo ARGDECL4(void *, ptr, long int, nbytes)
-.RE
-.IP
-In the above example, the macro "ARGDECL4" would be mistakenly interpreted to
-be the name of the function instead of the correct name of "foo". Specifying
-\fB\-I\fP \fIARGDECL4\fP results in the correct behavior.
-.RS 8
-/* creates an RCS version string in module */
-.br
-MODULE_VERSION("$Revision: 690 $")
-.RE
-.IP
-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 function definition
-could possibly even cause the rest of the file to be skipped over while trying
-to complete the definition. Specifying \fB\-I\fP \fIMODULE_VERSION+\fP would
-avoid such a problem.
-.RS 8
-CLASS Example {
-.br
-    // your content here
-.br
-};
-.RE
-.IP
-The example above uses "CLASS" as a preprocessor macro which expands to
-something different for each platform. For instance 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
-\fB\-I\fP \fICLASS=class\fP.
-.TP 5
-.BI \-L " file"
-Read from \fIfile\fP a list of file names for which tags should be generated.
-If \fIfile\fP 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 option is specified more than once, only the last will apply. \fBNote:\fP
-\fIfile\fP is read in line-oriented mode, where a new line is the only
-delimiter and non-trailing white space is considered 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.
-.TP 5
-.B \-n
-Equivalent to \fB\-\-excmd\fP=\fInumber\fP.
-.TP 5
-.B \-N
-Equivalent to \fB\-\-excmd\fP=\fIpattern\fP.
-.TP 5
-.BI \-o " tagfile"
-Equivalent to \fB\-f\fP \fItagfile\fP.
-.TP 5
-.B \-R
-Equivalent to \fB\-\-recurse\fP.
-.TP 5
-.B \-u
-Equivalent to \fB\-\-sort\fP=\fIno\fP (i.e. "unsorted").
-.TP 5
-.B \-V
-Equivalent to \fB\-\-verbose\fP.
-.TP 5
-.B \-w
-This option is silently ignored for backward-compatibility with the ctags
-of SVR4 Unix.
-.TP 5
-.B \-x
-Print a tabular, human-readable cross reference (xref) file to standard output
-instead of generating a tag file. The information 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 located in a source file (e.g. \fBctags \-x \-\-c\-kinds\fP=\fIf\fP
-\fIfile\fP), or generating a list of all externally visible global variables
-located in a source file (e.g. \fBctags \-x \-\-c\-kinds\fP=\fIv\fP
-\fB\-\-file\-scope\fP=\fIno file\fP). This option must appear before the first
-file name.
-.TP 5
-\fB\-\-append\fP[=\fIyes\fP|\fIno\fP]
-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.
-.TP 5
-\fB\-\-etags\-include\fP=\fIfile\fP
-Include a reference to \fIfile\fP 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]
-.TP 5
-\fB\-\-exclude\fP=[\fIpattern\fP]
-Add \fIpattern\fP to a list of excluded files and directories. This option
-may be specified as many times as desired. For each file name considered by
-\fBctags\fP, each \fIpattern\fP 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
-\fIpattern\fP 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 \fBctags\fP; 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
-\fB\-\-version\fP option, which will include "+wildcards" in the compiled
-feature list; otherwise, \fIpattern\fP is matched against file names using a
-simple textual comparison.
-If \fIpattern\fP 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 \fIpattern\fP 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 \fB\-\-recurse\fP
-option.
-.TP 5
-\fB\-\-excmd\fP=\fItype\fP
-Determines the type of EX command used to locate tags in the source file.
-[Ignored in etags mode]
-The valid values for \fItype\fP (either the entire word or the first letter is
-accepted) are:
-.RS 5
-.TP 9
-.I number
-Use only line numbers in the tag file for locating tags. This has four
-advantages:
-.PD 0
-.RS 9
-.TP 4
-1.
-Significantly reduces the size of the resulting tag file.
-.TP 4
-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
-\fBvim\fP, are able to recover in many such instances).
-.TP 4
-3.
-Eliminates finding identical matching, but incorrect, source lines (see
-\fBBUGS\fP, below).
-.TP 4
-4.
-Retains separate entries in the tag file for lines which are identical in
-content. In \fIpattern\fP mode, duplicate entries are dropped because the
-search patterns they generate are identical, making the duplicate entries
-useless.
-.RE
-.PD 1
-.IP
-However, this option has one significant drawback: changes to the source files
-can cause the line numbers recorded in the tag file to no longer correspond
-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: \fB\-BF\fP.
-.TP 9
-.I pattern
-Use only search patterns for all tags, rather than the line numbers usually
-used for macro definitions. This has the advantage of not referencing obsolete
-line numbers when lines have been added or removed since the tag file was
-generated.
-.TP 9
-.I mixed
-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 \fBctags\fP and is, therefore, retained as the
-default for this option. For Fortran, line numbers are used for common blocks
-because their corresponding source lines are generally identical, making
-pattern searches useless for finding all matches.
-.RE
-.TP 5
-\fB\-\-extra\fP=\fI[+|\-]flags\fP
-Specifies whether to include extra tag entries for certain kinds of
-information. The parameter \fIflags\fP is a set of one-letter flags, each
-representing one kind of extra tag entry to include in the tag file. If
-\fIflags\fP is preceded by 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:
-.PP
-.RS 8
-.TP 4
-.I 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.
-.TP 4
-.I 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 multiple 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.
-.RE
-.TP 5
-\fB\-\-fields\fP=\fI[+|\-]flags\fP
-Specifies the available extension fields which are to be included in the
-entries of the tag file (see \fBTAG FILE FORMAT\fP, below, for more
-information). The parameter \fIflags\fP 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):
-.PP
-.PD 0
-.RS 8
-.TP 4
-.I a
-Access (or export) of class members
-.TP 4
-.I f
-File-restricted scoping [enabled]
-.TP 4
-.I i
-Inheritance information
-.TP 4
-.I k
-Kind of tag as a single letter [enabled]
-.TP 4
-.I K
-Kind of tag as full name
-.TP 4
-.I l
-Language of source file containing tag
-.TP 4
-.I m
-Implementation information
-.TP 4
-.I n
-Line number of tag definition
-.TP 4
-.I s
-Scope of tag definition [enabled]
-.TP 4
-.I S
-Signature of routine (e.g. prototype or parameter list)
-.TP 4
-.I z
-Include the "kind:" key in kind field
-.TP 4
-.I t
-Type and name of a variable or typedef as "typeref:" field [enabled]
-.PD 1
-.RE
-.RS 5
-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 \fIflags\fP will be included in
-the output (i.e. overriding the default set). This option is ignored if the
-option \fB\-\-format\fP=\fI1\fP has been specified. The default value
-of this option is \fIfkst\fP.
-.RE
-.TP 5
-\fB\-\-file\-scope\fP[=\fIyes\fP|\fIno\fP]
-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 \fB\-h\fP option. This option
-is enabled by default.
-.TP 5
-\fB\-\-filter\fP[=\fIyes\fP|\fIno\fP]
-Causes \fBctags\fP to behave as a filter, reading source file names from
-standard input and printing their tags to standard output on a file-by-file
-basis. If \fB\-\-sorted\fP 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 \fB\-L\fP option) and only after file
-names listed on the command line or from any file supplied using the \fB\-L\fP
-option. When this option is enabled, the options \fB\-f\fP, \fB\-o\fP,
-and \fB\-\-totals\fP are ignored. This option is quite esoteric and is disabled
-by default. This option must appear before the first file name.
-.TP 5
-\fB\-\-filter\-terminator\fP=\fIstring\fP
-Specifies a string to print to standard output following the tags for each
-file name parsed when the \fB\-\-filter\fP option is enabled. This may permit an
-application reading the output of ctags to determine when the output for each
-file is finished. Note that if the file name read is a directory and
-\fB\-\-recurse\fP is enabled, this string will be printed only one once at the
-end of all tags found for by descending the directory. 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.
-.TP 5
-\fB\-\-format\fP=\fIlevel\fP
-Change the format of the output tag file. Currently the only valid values for
-\fIlevel\fP are \fI1\fP or \fI2\fP. Level 1 specifies the original tag file
-format and level 2 specifies a new extended format containing extension fields
-(but in a manner which retains backward-compatibility with original
-\fBvi\fP(1) implementations). The default level is 2. This option must appear
-before the first file name. [Ignored in etags mode]
-.TP 5
-.B \-\-help
-Prints to standard output a detailed usage description, and then exits.
-.TP 5
-\fB\-\-if0\fP[=\fIyes\fP|\fIno\fP]
-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 \fIno\fP. Note that this indicates a
-preference only and does not guarantee skipping code within an "#if 0" branch,
-since the fall-back algorithm used to generate tags when preprocessor
-conditionals are too complex follows all branches of a conditional. This
-option is disabled by default.
-.TP 5
-\fB\-\-<LANG>\-kinds\fP=\fI[+|\-]kinds\fP
-Specifies a list of language-specific kinds of tags (or kinds) to include in
-the output file for a particular language, where \fB<LANG>\fP is
-case-insensitive and is one of the built-in language names (see the
-\fB\-\-list\-languages\fP option for a complete list). The parameter \fIkinds\fP
-is a group of one-letter flags designating kinds of tags (particular to the
-language) 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 \fB\-\-list\-kinds\fP option. Each letter or group of letters may be
-preceded by either '+' 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 \fIkinds\fP 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 \fB\-\-c\-kinds\fP=\fI+px\-d\fP; to include only tags for functions, use
-\fB\-\-c\-kinds\fP=\fIf\fP.
-.TP 5
-\fB\-\-langdef\fP=\fIname\fP
-Defines a new user-defined language, \fIname\fP, to be parsed with regular
-expressions. Once defined, \fIname\fP may be used in other options taking
-language names. The typical use of this option is to first define the
-language, then map file names to it using \fI\-\-langmap\fP, then specify
-regular expressions using \fI\-\-regex\-<LANG>\fP to define how its tags are
-found.
-.TP 5
-\fB\-\-langmap\fP=\fImap[,map[...]]\fP
-Controls how file names are mapped to languages (see the \fB\-\-list\-maps\fP
-option). Each comma-separated \fImap\fP consists of the language name (either
-a built-in or user-defined language), 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 wildcards from being
-expanded by the shell before being passed to \fBctags\fP). You can determine
-if shell wildcards are available on your platform by examining the output of
-the \fB\-\-version\fP 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 extensions 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 "\fB\-\-langmap\fP=\fIc:.c.x\fP"; to also add files with
-extensions of .j as Java language files, specify
-"\fB\-\-langmap\fP=\fIc:.c.x,java:+.j\fP". To map makefiles (e.g. files
-named either "Makefile", "makefile", or having the extension ".mak") to a
-language called "make", specify "\fB\-\-langmap\fP=\fImake:([Mm]akefile).mak\fP".
-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.
-"\fB\-\-langmap\fP=\fIfortran:\fP"). To restore the default language mappings
-for all a particular language, supply the keyword "default" for the mapping.
-To specify restore the default language mappings for all languages, specify
-"\fB\-\-langmap\fP=\fIdefault\fP". Note that file extensions are tested before
-file name patterns when inferring the language of a file.
-.TP 5
-\fB\-\-language\-force\fP=\fIlanguage\fP
-By default, \fBctags\fP automatically selects the language of a source file,
-ignoring those files whose language cannot be determined (see
-\fBSOURCE FILES\fP, above). This option forces the specified \fIlanguage\fP
-(case-insensitive; either built-in or user-defined) to be used for every
-supplied file instead of automatically selecting the language based upon its
-extension. In addition, the special value \fIauto\fP indicates that the
-language should be automatically selected (which effectively disables this
-option).
-.TP 5
-\fB\-\-languages\fP=\fI[+|\-]list\fP
-Specifies the languages for which tag generation is enabled, with \fIlist\fP
-containing a comma-separated list of language names (case-insensitive; either
-built-in or user-defined). If the first language of \fIlist\fP is not preceded
-by either a '+' or '\-', the current list will be cleared before adding or
-removing the languages in \fIlist\fP. Until a '\-' is encountered, each
-language in the list will be added to the current 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 \fB\-\-langmap\fP
-option). Note that all languages, including user-defined languages are enabled
-unless explicitly disabled using this option. Language names included in
-\fIlist\fP may be any built-in language or one previously defined with
-\fB\-\-langdef\fP. The default is "all", which is also accepted as a valid
-argument. See the \fB\-\-list\-languages\fP option for a complete list of the
-built-in language names.
-.TP 5
-\fB\-\-license\fP
-Prints a summary of the software license to standard output, and then exits.
-.TP 5
-\fB\-\-line\-directives\fP[=\fIyes\fP|\fIno\fP]
-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 \fBctags\fP 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. \fBNote:\fP This option is
-generally only useful when used together with the \fB\-\-excmd\fP=\fInumber\fP
-(\fB\-n\fP) option. Also, you may have to use either the \fB\-\-langmap\fP or
-\fB\-\-language\-force\fP option if the extension of the preprocessor output file
-is not known to \fBctags\fP.
-.TP 5
-\fB\-\-links\fP[=\fIyes\fP|\fIno\fP]
-Indicates whether symbolic links (if supported) should be followed. When
-disabled, symbolic links are ignored. This option is on by default.
-.TP 5
-\fB\-\-list\-kinds\fP[=\fIlanguage\fP|\fIall\fP]
-Lists the tag kinds recognized for either the specified language 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 \fB\-\-<LANG>\-kinds\fP option. Note that some
-languages and/or tag kinds may be implemented using regular expressions and
-may not be available if regex support is not compiled into \fBctags\fP (see
-the \fB\-\-regex\-<LANG>\fP option). Each kind listed is enabled unless followed
-by "[off]".
-.TP 5
-\fB\-\-list\-maps\fP[=\fIlanguage\fP|\fIall\fP]
-Lists the file extensions and file name patterns which associate a file name
-with a language for either the specified language or all languages, and then
-exits. See the \fB\-\-langmap\fP option, and \fBSOURCE FILES\fP, above.
-.TP 5
-\fB\-\-list\-languages\fP
-Lists the names of the languages understood by \fBctags\fP, and then exits.
-These language names are case insensitive and may be used in the
-\fB\-\-language\-force\fP, \fB\-\-languages\fP, \fB\-\-<LANG>\-kinds\fP, and
-\fB\-\-regex\-<LANG>\fP options.
-.TP 5
-\fB\-\-options\fP=\fIfile\fP
-Read additional options from \fIfile\fP. The file should contain one option
-per line. As a special case, if
-\fB\-\-options\fP=\fINONE\fP 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 \fBFILES\fP).
-.TP 5
-\fB\-\-recurse\fP[=\fIyes\fP|\fIno\fP]
-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
-\fB\-L\fP option, then the current directory (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 \fBfind\fP(1) into \fBctags \-L\-\fP
-instead. \fBNote:\fP This option is not supported on all platforms at present.
-It is available if the output of the \fB\-\-help\fP option includes this option.
-See, also, the \fB\-\-exclude\fP to limit recursion.
-.TP 5
-\fB\-\-regex\-<LANG>\fP=\fI/regexp/replacement/[kind\-spec/][flags]\fP
-The \fI/regexp/replacement/\fP pair define a regular expression replacement
-pattern, similar in style to \fBsed\fP substitution commands, with which to
-generate tags from source files mapped to the named language, \fB<LANG>\fP,
-(case-insensitive; either a built-in or user-defined language). The regular
-expression, \fIregexp\fP, defines an extended regular expression (roughly that
-used by \fBegrep\fP(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
-\fIreplacement\fP, which generally will contain the special back-references
-\\1 through \\9 to refer to matching sub-expression groups within
-\fIregexp\fP. 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 \fIflags\fP, \fIregexp\fP is interpreted as a Posix
-extended regular expression. The \fIreplacement\fP 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 \fIregexp\fP may
-follow \fIreplacement\fP, which will determine what kind of tag is reported in
-the "kind" extension field (see \fBTAG FILE FORMAT\fP, below). The full form
-of \fIkind\-spec\fP is in the form of a single letter, a comma, a name (without
-spaces), a comma, a description, followed by a separator, which specify
-the short and long forms of the kind value and its textual description
-(displayed using \fB\-\-list\-kinds\fP). Either the kind name and/or the
-description may be omitted. If \fIkind\-spec\fP is omitted, it defaults to
-"\fIr,regex\fP". Finally, \fIflags\fP are one or more single-letter characters
-having the following effect upon the interpretation of \fIregexp\fP:
-.PP
-.RS 8
-.TP 4
-.I b
-The pattern is interpreted as a Posix basic regular expression.
-.TP 4
-.I e
-The pattern is interpreted as a Posix extended regular expression (default).
-.TP 4
-.I i
-The regular expression is to be applied in a case-insensitive manner.
-.RE
-.RS 5
-Note that this option is available only if \fBctags\fP was compiled 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 \fB\-\-version\fP option, which will include "+regex" in the
-compiled feature list.
-For more information on the regular expressions used by \fBctags\fP, see
-either the \fBregex(5,7)\fP man page, or the GNU info documentation for regex
-(e.g. "info regex").
-.RE
-.TP 5
-\fB\-\-sort\fP[=\fIyes\fP|\fIno\fP|\fIfoldcase\fP]
-Indicates whether the tag file should be sorted on the tag name (default is
-\fIyes\fP). Note that the original \fBvi\fP(1) required sorted tags.
-The \fIfoldcase\fP 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
-readtags library, or Vim version 6.2 or higher (using "set ignorecase"). This
-option must appear before the first file name. [Ignored in etags mode]
-.TP 5
-\fB\-\-tag\-relative\fP[=\fIyes\fP|\fIno\fP]
-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
-absolute paths. This option must appear before the first file name. The
-default is \fIyes\fP when running in etags mode (see the \fB\-e\fP
-option), \fIno\fP otherwise.
-.TP 5
-\fB\-\-totals\fP[=\fIyes\fP|\fIno\fP]
-Prints statistics about the source files read and the tag file written during
-the current invocation of \fBctags\fP. This option is off by default.
-This option must appear before the first file name.
-.TP 5
-\fB\-\-verbose\fP[=\fIyes\fP|\fIno\fP]
-Enable verbose mode. This prints out information on option processing and a
-brief message describing what action is being taken for each file considered
-by \fBctags\fP. Normally, \fBctags\fP does not read command line arguments
-until after options are read from the configuration files (see \fBFILES\fP,
-below) and the \fBCTAGS\fP environment variable. However, if this option is
-the first argument on the command line, it will take effect before any options
-are read from these sources. The default is \fIno\fP.
-.TP 5
-\fB\-\-version\fP
-Prints a version identifier for \fBctags\fP to standard output, and then
-exits. This is guaranteed to always contain the string "Exuberant Ctags".
-.SH "OPERATIONAL DETAILS"
-As \fBctags\fP 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 operate 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
-\fBTAG FILE FORMAT\fP, below, for details on these entries.
-This implementation of \fBctags\fP 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 conditionals.
-In general, \fBctags\fP tries to be smart about conditional preprocessor
-directives. If a preprocessor conditional is encountered within a statement
-which defines a tag, \fBctags\fP 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 reason for this is that failing to pursue only one
-branch can result in ambiguous syntax, as in the following example:
-.RS
-#ifdef TWO_ALTERNATIVES
-.br
-struct {
-.br
-#else
-.br
-union {
-.br
-#endif
-.RS 4
-short a;
-.br
-long b;
-.RE
-}
-.RE
-Both branches cannot be followed, or braces become unbalanced and \fBctags\fP
-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,
-\fBctags\fP will retry the file using a different 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.
-\fBCtags\fP will also try to specially handle arguments lists enclosed in
-double sets of parentheses in order to accept the following conditional
-construct:
-.RS
-extern void foo __ARGS((int one, char two));
-.RE
-Any name immediately preceding the "((" will be automatically ignored and
-the previous name will be used.
-C++ operator definitions are specially handled. In order for consistency 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.
-.SH "TAG FILE FORMAT"
-When not running in etags mode, each entry in the tag file consists of a
-separate line, each looking like this in the most general case:
-.RS 1
-tag_name<TAB>file_name<TAB>ex_cmd;"<TAB>extension_fields
-.RE
-The fields and separators of these lines are specified as follows:
-.PD 0
-.RS 4
-.TP 4
-1.
-tag name
-.TP 4
-2.
-single tab character
-.TP 4
-3.
-name of the file in which the object associated with the tag is located
-.TP 4
-4.
-single tab character
-.TP 4
-5.
-EX command used to locate the tag within the file; generally a search pattern
-(either /pattern/ or ?pattern?) or line number (see \fB\-\-excmd\fP). Tag file
-format 2 (see \fB\-\-format\fP) 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 original \fBvi\fP(1) implementations.
-.RE
-.PD 1
-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 overwritten 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
-\fB\-\-tag\-relative\fP 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 "\fIkey\fP:\fIvalue\fP". Their presence in the lines of the
-tag file are controlled by the \fB\-\-fields\fP option. The possible keys and
-the meaning of their values are as follows:
-.TP 12
-.I access
-Indicates the visibility of this class member, where \fIvalue\fP is specific
-to the language.
-.TP 12
-.I file
-Indicates that the tag has file-limited visibility. This key has no
-corresponding value.
-.TP 12
-.I kind
-Indicates the type, or kind, of tag. Its value is either one of the
-corresponding one-letter flags described under the various
-\fB\-\-<LANG>\-kinds\fP 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 \fB\-\-fields\fP option.
-.TP 12
-.I implementation
-When present, this indicates a limited implementation (abstract vs. concrete)
-of a routine or class, where \fIvalue\fP is specific to the language
-("virtual" or "pure virtual" for C++; "abstract" for Java).
-.TP 12
-.I inherits
-When present, \fIvalue\fP. is a comma-separated list of classes from which
-this class is derived (i.e. inherits from).
-.TP 12
-.I signature
-When present, \fIvalue\fP is a language-dependent representation of the
-signature of a routine. A routine signature in its complete form specifies the
-return type of a routine and its formal argument list. This extension field is
-presently supported only for C-based languages and does not include the return
-type.
-.PP
-In addition, information on the scope of the tag definition may be available,
-with the key portion equal to some language-dependent construct name and its
-value the name declared for that construct 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:myStruct".
-.SH "HOW TO USE WITH VI"
-Vi 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:
-.TP 12
-.B vi \-t tag
-Start vi and position the cursor at the file and line where "tag" is defined.
-.TP 12
-.B :ta tag
-Find a tag.
-.TP 12
-.B Ctrl-]
-Find the tag under the cursor.
-.TP 12
-.B Ctrl-T
-Return to previous location before jump to tag (not widely implemented).
-.SH "HOW TO USE WITH GNU EMACS"
-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:
-.TP 10
-.B "M-x visit\-tags\-table <RET> FILE <RET>"
-Select the tag file, "FILE", to use.
-.TP 10
-.B "M-. [TAG] <RET>"
-Find the first definition of TAG. The default tag is the identifier under the
-cursor.
-.TP 10
-.B "M-*"
-Pop back to where you previously invoked "M-.".
-.TP 10
-.B "C-u M-."
-Find the next definition for the last tag.
-.PP
-For more commands, see the \fITags\fP topic in the Emacs info document.
-.SH "HOW TO USE WITH NEDIT"
-NEdit version 5.1 and later can handle the new extended tag file format (see
-\fB\-\-format\fP). To make NEdit use the tag file, select "File\->Load Tags
-File". To jump to the definition for a tag, highlight the word, the press
-Ctrl-D. NEdit 5.1 can can read multiple tag files from different directories.
-Setting the X resource nedit.tagFile to the name of a tag file instructs NEdit
-to automatically load that tag file at startup time.
-.SH "CAVEATS"
-Because \fBctags\fP is neither a preprocessor nor a compiler, use of
-preprocessor macros can fool \fBctags\fP into either missing tags or
-improperly generating inappropriate tags. Although \fBctags\fP has been
-designed to handle certain common cases, this is the single biggest cause of
-reported problems. In particular, the use of preprocessor constructs which
-alter the textual syntax of C can fool \fBctags\fP. You can work around many
-such problems by using the \fB\-I\fP option.
-Note that since \fBctags\fP generates patterns for locating tags (see
-the \fB\-\-excmd\fP 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:
-.RS
-int variable;
-/* ... */
-.br
-void foo(variable)
-.br
-int variable;
-.br
-{
-.RS 4
-/* ... */
-.RE
-}
-.RE
-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 actual global variable definition, since the
-lines (and therefore their search patterns are identical). This can be avoided
-by use of the \fB\-\-excmd\fP=\fIn\fP option.
-.SH "BUGS"
-\fBCtags\fP has more options than \fBls\fP(1).
-When parsing a C++ member function definition (e.g. "className::function"),
-\fBctags\fP cannot determine whether the scope specifier 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 declaration (the usual case), the access specification (i.e. public,
-protected, or private) and implementation information (e.g. virtual, 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 \fB\-\-c++\-kinds\fP=\fI+p\fP).
-No qualified tags are generated for language objects inherited into a class.
-.SH "ENVIRONMENT VARIABLES"
-.TP 8
-.B CTAGS
-If this environment variable exists, it will be expected to contain a set of
-default options which are read when \fBctags\fP starts, after the
-configuration files listed in \fBFILES\fP, below, are read, but before any
-command line options 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 containing an
-embedded space. If this is a problem, use a configuration file instead.
-.TP 8
-.B ETAGS
-Similar to the \fBCTAGS\fP variable above, this variable, if found, will be
-read when \fBetags\fP starts. If this variable is not found, \fBetags\fP will
-try to use \fBCTAGS\fP instead.
-.TP 8
-.B TMPDIR
-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 partition
-holding the default temporary directory defined at compilation time.
-\fBctags\fP 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 algorithm to sort the tag
-files instead of the the sort utility 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 \fBctags\fP is setuid, the value of TMPDIR will be
-ignored.
-.SH "FILES"
-.PD 0
-.I /ctags.cnf (on MSDOS, MSWindows only)
-.br
-.I /etc/ctags.conf
-.br
-.I /usr/local/etc/ctags.conf
-.br
-.I $HOME/.ctags
-.br
-.I $HOME/ctags.cnf (on MSDOS, MSWindows only)
-.br
-.I .ctags
-.br
-.I ctags.cnf (on MSDOS, MSWindows only)
-.IP
-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 \fBctags\fP
-starts, but before the \fBCTAGS\fP environment variable is read or any command
-line options are read. This makes it possible to set up site-wide, personal
-or project-level defaults. It is possible to compile \fBctags\fP to read an
-additional configuration file before any of those shown above, which will be
-indicated if the output produced by the \fB\-\-version\fP option lists the
-"custom-conf" feature. Options appearing in the \fBCTAGS\fP environment
-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.
-.PD 1
-.TP
-.I tags
-The default tag file created by \fBctags\fP.
-.TP
-.I TAGS
-The default tag file created by \fBetags\fP.
-.SH "SEE ALSO"
-The official Exuberant Ctags web site at:
-.RS
-http://ctags.sourceforge.net
-.RE
-Also \fBex\fP(1), \fBvi\fP(1), \fBelvis\fP, or, better yet, \fBvim\fP, the
-official editor of \fBctags\fP. For more information on \fBvim\fP, see the VIM
-Pages web site at:
-.RS
-http://www.vim.org/
-.RE
-.SH "AUTHOR"
-Darren Hiebert <dhiebert at users.sourceforge.net>
-.br
-http://DarrenHiebert.com/
-.SH "MOTIVATION"
-"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."
-.RS
-\-\- From the Baha'i Writings
-.RE
-.SH "CREDITS"
-This version of \fBctags\fP 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 original code remains).
-Credit is also due Bram Moolenaar <Bram@vim.org>, the author of \fBvim\fP, who
-has devoted so much of his time and energy both to developing 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 \fBetags\fP.