ctags.rb 1.0.0

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

@@ -0,0 +1,1186 @@
+.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.