Ctags options files changes

* Remove the `g:gutentags_ctags_options_file` setting since it's mostly useless.
* Use the script's `-o` option to pass a `.ctags` file in the project root if it exists.
* Add documentation.

autoload/gutentags/ctags.vim

@@ -6,10 +6,6 @@ if !exists('g:gutentags_ctags_executable')
     let g:gutentags_executable = 'ctags'
 endif
 
-if !exists('g:gutentags_ctags_options_file')
-    let g:gutentags_ctags_options_file = ''
-endif
-
 if !exists('g:gutentags_tagfile')
     let g:gutentags_tagfile = 'tags'
 endif
@@ -61,8 +57,9 @@ function! gutentags#ctags#generate(proj_dir, tags_file, write_mode) abort
         if g:gutentags_pause_after_update
             let l:cmd .= ' -c'
         endif
-        if len(g:gutentags_ctags_options_file)
-            let l:cmd .= ' -o "' . g:gutentags_ctags_options_file . '"'
+        let l:proj_options_file = a:proj_dir . '/.ctags'
+        if filereadable(l:proj_options_file)
+            let l:cmd .= ' -o "' . l:proj_options_file . '"'
         endif
         if g:gutentags_trace
             if has('win32')

doc/gutentags.txt

@@ -32,6 +32,7 @@
 2. Commands                 |gutentags-commands|
 3. Status Line              |gutentags-status-line|
 4. Global Settings          |gutentags-settings|
+5. Project Settings         |gutentags-project-settings|
 
 =============================================================================
 1. Introduction                                 *gutentags-intro*
@@ -175,6 +176,7 @@ Some debugging/troubleshooting commands are also available if the
                         Gutentags, or something otherwise wrong or unexpected
                         with your system. Please file a bug.
 
+
 =============================================================================
 3.  Status Line                                 *gutentags-status-line*
 
@@ -253,14 +255,6 @@ g:gutentags_exclude
                         Patterns defined in 'wildignore' will also be given as
                         exclude patterns to the `ctags` executable.
 
-                                                *gutentags_ctags_options_file*
-g:gutentags_ctags_options_file
-                        The path to an options file that will be passed to
-                        the `ctags` executable with the `--options` option.
-                        In general you can put options in a `$HOME/.ctags`
-                        file, but this lets you specify a custom file
-                        specifically for Vim/Gutentags.
-
                                                 *gutentags_auto_set_tags*
 g:gutentags_auto_set_tags
                         If set to 1, Gutentags will automatically prepend
@@ -318,4 +312,24 @@ g:gutentags_define_advanced_commands
                         |GutentagsToggleEnabled| and |GutentagsUnlock|.
 
 
+=============================================================================
+5. Project Settings                             *gutentags-project-settings*
+
+Gutentags can be customized to some extent on a per-project basis with the
+following files present in the project root directory:
+
+                                                *gutentags-.ctags*
+`.ctags`: if this file exists, Ctags will be told to load additional
+command-line parameters by reading it line by line (see the Ctags
+documentation for more information).
+
+Note that for complex reasons, Gutentags can't always run `ctags` from the
+project root, so if the `.ctags` file exists, its path will actually be passed
+through the `--options=` parameter.
+
+                                                *gutentags-.notags*
+`.notags`: if this file exists, Gutentags will be disabled completely for that
+project.
+
+
  vim:tw=78:et:ft=help:norl: