Update ctags.1

[cweagans]

@masatake Can you please clarify what you need done here? Any specific topics that should be covered? Are these already documented elsewhere (issues, PRs, .rst files in the docs directory, etc)?

[masatake]

@cweagans, sorry to be late.

There are four big area we have to update in ctags.1.

1. newly introduced options,
2. incompatible changes in options, and
3. changes in tags file format
4. known bugs

2, 3, and 4 I'm still working on ctags program code side. So I would
like to focus on 1. here.

I wrote many of newly introduced options in docs/*.rst
or --help message.

Could you given me "feed back" about them?

Here "feed back" means:

A. the documentation of an option FOO is understandable or not.
B. the feature introduced by an option FOO is acceptable as
part of 1.0(or 0.1).

If an option FOO satisfies both A and B, I would like you to move the
documentation in docs/*rst for FOO to somewhere ctags.1.in.

If an option FOO doesn't satisfy A, I will update or add the
explanation for FOO to docs/*.rst. So tell me the name of option.

Let's take a diff between universal-ctags and exuberant-ctags:

$ diff -ruN <(ctags --help) <(./ctags --help)
--- /proc/self/fd/11    2015-11-10 02:41:51.272399358 +0900
+++ /proc/self/fd/12    2015-11-10 02:41:51.274399338 +0900
@@ -1,7 +1,9 @@
...
@@ -12,6 +14,7 @@
        Write tags to specified file. Value of "-" writes tags to stdout
        ["tags"; or "TAGS" when -e supplied].
   -F   Use forward searching patterns (/.../) (default).
+  -G   Equivalent to --guess-language-eagerly.
   -h <list>
        Specify list of file extensions to be treated as include files.
        [".h.H.hh.hpp.hxx.h++"].
@@ -28,8 +31,14 @@
   -u   Equivalent to --sort=no.
   -V   Equivalent to --verbose.
   -x   Print a tabular cross reference file to standard output.
+  --alias-<LANG>=[+|-]aliasPattern
+      Add a pattern detecting a name can be used as an alternative name for LANG.
   --append=[yes|no]
        Should tags should be appended to existing tag file [no]?
+  --config-filename=fileName
+      Use 'fileName' instead of 'ctags' in option file names.
+  --data-dir=[+]DIR
+      Add or set DIR to data directory search path.
   --etags-include=file
       Include reference to 'file' in Emacs-style tag file (requires -e).
   --exclude=pattern
@@ -37,9 +46,9 @@
   --excmd=number|pattern|mix
        Uses the specified type of EX command to locate tags [mix].
   --extra=[+|-]flags
-      Include extra tag entries for selected information (flags: "fq").
+      Include extra tag entries for selected information (flags: "fq.").
   --fields=[+|-]flags
-      Include selected extension fields (flags: "afmikKlnsStz") [fks].
+      Include selected extension fields (flags: "afmikKlnsStzZ") [fks].
   --file-scope=[yes|no]
        Should tags scoped only for a single file (e.g. "static" tags
        be included in the output [yes]?
@@ -51,10 +60,17 @@
        parsed when --filter is enabled.
   --format=level
        Force output of specified tag file format [2].
+  --guess-language-eagerly
+       Guess the language of input file more eagerly: 
+       (but taking longer time for guessing)
+       o shebang even the input file is not executable,
+       o emacs mode specification at the beginning and end of input file, and
+       o vim syntax specification at the end of input file.
   --help
        Print this option summary.
   --if0=[yes|no]
-       Should C code within #if 0 conditional branches be parsed [no]?
+       Should code within #if 0 conditional branches be parsed [no]?
+  --kinds-<LANG>=[+|-]kinds, or
   --<LANG>-kinds=[+|-]kinds
        Enable/disable tag kinds for language <LANG>.
   --langdef=name
@@ -64,23 +80,42 @@
   --language-force=language
        Force all files to be interpreted using specified language.
   --languages=[+|-]list
-       Restrict files scanned for tags to those mapped to langauges
+       Restrict files scanned for tags to those mapped to languages
        specified in the comma-separated 'list'. The list can contain any
        built-in or user-defined language [all].
+  --libexec-dir=[+]DIR
+      Add or set DIR to libexec directory search path.
   --license
        Print details of software license.
   --line-directives=[yes|no]
        Should #line directives be processed [no]?
   --links=[yes|no]
        Indicate whether symbolic links should be followed [yes].
+  --list-aliases=[language|all]
+       Output list of alias patterns.
+  --list-features
+       Output list of features.
+  --list-fields
+       Output list of fiedls.
+  --list-file-kind
+       List kind letter for file.
   --list-kinds=[language|all]
        Output a list of all tag kinds for specified language or all.
   --list-languages
        Output list of supported languages.
   --list-maps=[language|all]
        Output list of language mappings.
+  --list-regex-flags
+       Output list of flags which can be used in a regex parser definition.
+  --map-<LANG>=[+]map
+       Set or add(+) a map for <LANG>.
+       Unlike --langmap a pattern or an extension can be specified at once.
   --options=file
        Specify file from which command line options should be read.
+  --print-language
+       Don't make tags file but just print the guessed language name for input file.
+  --quiet=[yes|no]
+       Don't print NOTICE class messages [no].
   --recurse=[yes|no]
        Recurse into directories supplied on command line [no].
   --regex-<LANG>=/line_pattern/name_pattern/[flags]
@@ -91,7 +126,34 @@
        Should paths be relative to location of tag file [no; yes when -e]?
   --totals=[yes|no]
        Print statistics about source and tag files [no].
+  --undef=[yes|no]
+       Should #undef directives generate a macro tag [yes]?
   --verbose=[yes|no]
        Enable verbose messages describing actions on each source file.
   --version
        Print version identifier to standard output.
+  --xcmd-<LANG>=parser_command_path|parser_command_name
+       Define external parser command path or name for specific language.
+  --_allow-xcmd-in-homedir
+       Allow specifying --xcmd-<LANG> option in ~/.ctags and/or ~/.ctags/*.
+       By default it is not allow. This option itself can be specified only 
+       in /etc or /usr/local/etc.
+  --_echo=msg
+       Echo MSG to standard error. Useful to debug the chain
+       of loading option files.
+  --_fatal-warnings
+       Make all warnings fatal.
+  --_force-quit=[num]
+       Quit when the option is processed. Useful to debug the chain
+       of loading option files.
+  --_list-kinds-full=[language|all]
+       Output a list of quadruplet of all tag kinds for specified language or all.
+       The elements of a quadruplet are "letter", "name", "description" and "disabled".
+       Elements are separated with tab characters. 
+       If a kind is disabled, its "disabled" element is printed as "off".
+       If it is enabled, "on" is printed.
+       For each line, associated language name is printed when "all" is specified as language.
+  --_xformat=field_format
+       Specify custom format for tabular cross reference (-x).
+       Fields can be specified with letter listed in --list-fields.
+       e.g. --_xformat=%10N %10l:%K @ %-20F:%-20n

Too many. Some options start with _ like --_xformat are
experimental or debug purpose.

My idea: -G(--guess-language-eagerly), --print-language,
--quiet, --undef, --list-features, and --list-fields
are documented and acceptable.

--alias- and --list-aliases is acceptable but not
understandable. --list-file-kind is acceptable but not
understandable. --list-regex-flags may be acceptable but not
understandable.

--data-dir, --libexec-dir, --xcmd- and _allow-xcmd-in-homedir
--are not acceptable because they don't have stable meaning. So they
--should be renamed to --_data-dir, --_libexec-dir and --_xcmd-.

--map- is buggy but I would like to accept after
fixing the bug.

I would like to include --_xformat to 1.0.
How do you think about thie feature?

I would like to include --_list-kinds-full to 1.0.
However, I would like to rename this to
--list-kinds --machine.

--totals=[yes|no] may have bugs.

How do you think name --kinds- option.
I wanted to introduce new convention for per language
option name: --VERB-. Only --kinds- option
in exuberant-ctags violates this convention. So
I introduced --kinds- as alternative.
How do think this name convention and name?

One more. I introduced wildcard in some options
like --kinds-=*. They are already written
in ctags.1.in. But I would like to review the
explanation.

[masatake]

Of course I can/should write draft. However, I would like to hear about acceptability of each options.

[masatake]

Please, forget what I wrote here abut --undef. I will replace it with --extra=+r.

[ffes]

I have completed the basic conversion of ctags.1.in (and EXTENDING.html) to rst. (See #353)

Still need to figure out what is the best way to comply with the man standards like all the highlighting. When that is done, I will open a PR for this. After that we have a document that we can extend as described above.

[masatake]

Most of all things other than writing FAQ about C/C++ parsers are done.
Thank you for people updating ctags(1).