Merge pull request #2289 from k-takata/generate-docs-man

docs,man: Commit generated man files into docs/man/
universal-ctags · Nov 1, 2019 · a6684bd · a6684bd
2 parents a1ce56a + c18e8e4
commit a6684bd
Show file tree

Hide file tree

Showing 7 changed files with 3,029 additions and 7 deletions.
diff --git a/docs/man/ctags-incompatibilities.7.rst b/docs/man/ctags-incompatibilities.7.rst
diff --git a/docs/man/ctags-incompatibilities.7.rst b/docs/man/ctags-incompatibilities.7.rst
@@ -0,0 +1,191 @@
+.. _ctags-incompatibilities(7):
+
+==============================================================
+ctags
+==============================================================
+--------------------------------------------------------------
+Incompatibilities between Universal-ctags and Exuberant-ctags
+--------------------------------------------------------------
+:Version: 0.0.0
+:Manual group: Universal-ctags
+:Manual section: 7
+
+SYNOPSIS
+--------
+|	**ctags** [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".
+
+Kind definitions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+Disallowing to define a kind with "F" as letter
+....................................................................................
+
+The kind letter "F" is reserved.  Using it as part of a kind spec in
+``--regex-<LANG>`` option is now disallowed.
+
+Disallowing to use other than alphabetical character as kind letter
+....................................................................................
+
+Exuberant-ctags accepts a character other than alphabetical character
+as kind letter in ``--regex-<LANG>=...`` option.  Universal-ctags
+accepts only an alphabetical character.
+
+Acceptable characters as parts of a kind name
+....................................................................................
+
+Exuberant-ctags accepts any character as a part of a kind name
+defined with ``--regex-<LANG>=/regex/replacement/kind-spec/``.
+
+Universal-ctags accepts only an alphabetical character as
+the initial letter of a kind name.
+Universal-ctags accepts only an alphabetical character or
+numerical character as the rest letters.
+
+An example::
+
+  --regex-Foo=/abstract +class +([a-z]+)/\1/a,abstract class/i
+
+Universal-ctags rejects this because the kind name, "abstract class",
+includes a whitespace character.
+
+This requirement is for making the output of Universal-ctags follow
+the tags file format.
+
+A combination of a kind letter and a kind name
+....................................................................................
+
+In Universal-ctags, the combination of
+a kind letter and a kind name must be unique in a language.
+
+You cannot define more than one kind reusing a kind letter with
+different kind names. You cannot define more than one kind reusing a
+kind name with different kind letters.
+
+An example::
+
+  --regex-Foo=/abstract +class +([a-z]+)/\1/a,abstractClass/i
+  --regex-Foo=/attribute +([a-z]+)/\1/a,attribute/i
+
+Universal-ctags rejects this because the kind letter, "a", used twice
+for defining a kind "abstractClass" and "attribute".
+
+
+Incompatibilities in tags file format
+-------------------------------------------------------------
+
+Using numerical character in the name part of tag tagfield
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The version 2 tags file format, the default output format of
+Exuberant-ctags, accepts only alphabetical characters in the name part
+of tag tagfield.
+
+Universal-ctags introduces an exception to this specification; it may
+use numerical characters in addition to alphabetical characters as the
+letters other than initial letter of the name part.
+
+The kinds "heading1", "heading2", and "heading3" in the HTML parser
+are the examples.
+
+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".
+
+SEE ALSO
+--------
+ctags(1) and tags(5).
diff --git a/docs/man/ctags-optlib.7.rst b/docs/man/ctags-optlib.7.rst