focal (7) ctags-incompatibilities.7.gz

Provided by: universal-ctags_0+git20181215-2_amd64 bug

NAME
       ctags-universal - Incompatibilities between Universal-ctags and Exuberant-ctags


SYNOPSIS
       ctags-universal [options] [file(s)]
       etags [options] [file(s)]


DESCRIPTION
       This page describes major incompatible changes introduced to Universal-ctags forked from Exuberant-ctags.


INCOMPATIBILITIES IN COMMAND LINE INTERFACE
   The order of application of patterns and extensions in --langmap
       When  applying  mappings  for a name of given source file, Exuberant-ctags tests file name patterns AFTER
       file extensions (e-map-order). Universal-ctags does this differently; it tests file name patterns  BEFORE
       file extensions (u-map-order).

       This incompatible change is introduced to deal with the following situation:

          • "build.xml" as a source file,

          • The "Ant" parser declares it handles a file name pattern "build.xml", and

          • The "XML" parser declares it handles a file extension "xml".

       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.

       So Universal-ctags uses the u-map-order even though it introduces an incompatibility.

       --list-map-extensions=language  and  --list-map-patterns=language  options  are helpful to verify and the
       file extensions and the file name patterns of given language.

   Unexpected synchronization between --file-scope option and F/fileScope extra
       Universal-ctags introduces "F/fileScope" extra as the alternative to --file-scope option.

       Providing the two way to control the same thing in Universal-ctags internal can cause a trouble.

       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.

       In this case, the user should set "--extras=+q" instead of "--extras=q".

   Obsoleting --<LANG>-kinds option
       Some  options have <LANG> as parameterized parts in their name like --foo-<LANG>=... or --<LANG>-foo=....
       The most of all such options in Exuberant-ctags have the former form, --foo-<LANG>=....  The exception is
       --<LANG>-kinds.

       Universal-ctags  uses  the former form for all <LANG> parameterized option. Use --kinds-<LANG> instead of
       --<LANG>-kinds in Universal-ctags. --<LANG>-kinds still works but it will be removed in the future.

       The former form may be friendly to shell completion engines.

   Disallowing to define a kind with file as name
       The kind name "file" is reserved.  Using it as  part  of  kind  spec  in  --regex-<LANG>  option  is  now
       disallowed.


INCOMPATIBILITIES IN TAGS FILE FORMAT
OPTION FILES LOADING AT STARTING UP TIME (PRELOAD FILES)
       File  paths  for preload files are changed.  Universal-ctags doesn't load "~/.ctags" at starting up time.
       See "FILES" section of ctags(1).


KIND LETTERS AND NAMES
       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.

       • Cobol's "file" kind is renamed to "fileDesc" because the kind name "file" is reserved.

       • Ruby's "F" (singletonMethod) is changed to "S".

       • SQL's "F" (field) is changed to "E".