.\" Man page generated from reStructuredText.
.
.TH CTAGS-UNIVERSAL 7 "" "0.0.0" "Universal-ctags"
.SH NAME
ctags-universal \- Incompatibilities between Universal-ctags and Exuberant-ctags
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.nf
\fBctags\-universal\fP [options] [file(s)]
\fBetags\fP [options] [file(s)]
.fi
.sp
.SH DESCRIPTION
.sp
This page describes major incompatible changes introduced to
Universal\-ctags forked from Exuberant\-ctags.
.SH INCOMPATIBILITIES IN COMMAND LINE INTERFACE
.SS The order of application of patterns and extensions in \fB\-\-langmap\fP
.sp
When applying mappings for a name of given source file,
Exuberant\-ctags tests file name patterns AFTER file extensions
(\fBe\-map\-order\fP). Universal\-ctags does this differently; it tests file
name patterns BEFORE file extensions (\fBu\-map\-order\fP).
.sp
This incompatible change is introduced to deal with the following
situation:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
"build.xml" as a source file,
.IP \(bu 2
The "Ant" parser declares it handles a file name pattern "build.xml", and
.IP \(bu 2
The "XML" parser declares it handles a file extension "xml".
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Which parser should be used for parsing "build.xml"?  The assumption
of Universal\-ctags is the user may want to use the "Ant" parser; the
file name pattern it declares is more specific than the file extension
that the "XML" parser declares. However, e\-map\-order chooses the "XML"
parser.
.sp
So Universal\-ctags uses the u\-map\-order even though it introduces an
incompatibility.
.sp
\fB\-\-list\-map\-extensions=language\fP and \fB\-\-list\-map\-patterns=language\fP
options are helpful to verify and the file extensions and the file
name patterns of given \fIlanguage\fP\&.
.SS Unexpected synchronization between \fB\-\-file\-scope\fP option and "F/fileScope" extra
.sp
Universal\-ctags introduces "F/fileScope" extra as the alternative to
\fB\-\-file\-scope\fP option.
.sp
Providing the two way to control the same thing in Universal\-ctags
internal can cause a trouble.
.sp
A user, expecting "\-\-file\-scope=yes" is enabled by default, gives
"\-\-extras=q". The intention of the user may be just enabling
"q/qualified". However, "\-\-extras=q" is evaluated as "disabling all
extras including F/fileScope, then enabling only
q/qualified". Unexpectedly the command line becomes as if
"\-\-file\-scope=no" is set.
.sp
In this case, the user should set "\-\-extras=+q" instead of "\-\-extras=q".
.SS Obsoleting \fB\-\-<LANG>\-kinds\fP option
.sp
Some options have \fI<LANG>\fP as parameterized parts in their name like
\fB\-\-foo\-<LANG>=...\fP or \fB\-\-<LANG>\-foo=...\fP\&. The most of all such
options in Exuberant\-ctags have the former form, \fB\-\-foo\-<LANG>=...\fP\&.
The exception is \fB\-\-<LANG>\-kinds\fP\&.
.sp
Universal\-ctags uses the former form for all \fI<LANG>\fP parameterized
option. Use \fB\-\-kinds\-<LANG>\fP instead of \fB\-\-<LANG>\-kinds\fP in
Universal\-ctags. \fB\-\-<LANG>\-kinds\fP still works but it will be
removed in the future.
.sp
The former form may be friendly to shell completion engines.
.SS Disallowing to define a kind with "file" as name
.sp
The kind name "file" is reserved.  Using it as part of kind spec in
\fB\-\-regex\-<LANG>\fP option is now disallowed.
.SH INCOMPATIBILITIES IN TAGS FILE FORMAT
.SH OPTION FILES LOADING AT STARTING UP TIME (PRELOAD FILES)
.sp
File paths for preload files are changed.
Universal\-ctags doesn\(aqt load "~/.ctags" at starting up time.
See "FILES" section of ctags(1).
.SH KIND LETTERS AND NAMES
.sp
A kind letter "F" and a kind name "file" are reserved in the
main part. A parser cannot have a kind conflicting with
these reserved ones. Some incompatible changes are introduced
to follow the above rule.
.INDENT 0.0
.IP \(bu 2
Cobol\(aqs "file" kind is renamed to "fileDesc" because the
kind name "file" is reserved.
.IP \(bu 2
Ruby\(aqs "F" (singletonMethod) is changed to "S".
.IP \(bu 2
SQL\(aqs "F" (field) is changed to "E".
.UNINDENT
.\" Generated by docutils manpage writer.
.