Skip to content
This repository
Browse code

Documented :HighlightTags tags file format requirements

  • Loading branch information...
commit 738d7508181423e1633e4d5d6014e8ad2acb4595 1 parent eea8f41
Peter Odding authored August 12, 2010

Showing 2 changed files with 14 additions and 2 deletions. Show diff stats Hide diff stats

  1. 12  README.md
  2. 4  TODO.md
12  README.md
Source Rendered
@@ -24,7 +24,7 @@ On Windows the [system()] [system] function used by `easytags.vim` causes a comm
24 24
 
25 25
 ### The `:UpdateTags` command
26 26
 
27  
-This command executes [Exuberant Ctags] [exuberant_ctags] from inside Vim to update the global tags file defined by `g:easytags_file`. When no arguments are given the tags for the current file are updated, otherwise the arguments are passed on to `ctags`. For example when you execute the Vim command `:UpdateTags -R ~/.vim` (or `:UpdateTags -R ~\vimfiles` on Windows) the plug-in will execute `ctags -R ~/.vim` for you (with some additional arguments).
  27
+This command executes [Exuberant Ctags] [exuberant_ctags] from inside Vim to update the global tags file defined by `g:easytags_file`. When no arguments are given the tags for the current file are updated, otherwise the arguments are passed on to `ctags`. For example when you execute the Vim command `:UpdateTags -R ~/.vim` (or `:UpdateTags -R ~\vimfiles` on Windows) the plug-in will execute `ctags -R ~/.vim` for you (with some additional arguments, see the troubleshooting section "`:HighlightTags` only works for the tags file created by `:UpdateTags`" for more information).
28 28
 
29 29
 When you execute this command like `:UpdateTags!` (including the bang!) then all tags whose files are missing will be filtered from the global tags file.
30 30
 
@@ -100,6 +100,16 @@ UNIX has [symbolic links](http://en.wikipedia.org/wiki/Symbolic_link) and [hard
100 100
 
101 101
 ## Troubleshooting
102 102
 
  103
+### `:HighlightTags` only works for the tags file created by `:UpdateTags`
  104
+
  105
+If you want to create tags files and have their tags highlighted by the `easytags.vim` plug-in then you'll have to create the tags file with certain arguments to Exuberant Ctags:
  106
+
  107
+    $ ctags --fields=+l --c-kinds=+p --c++-kinds=+p ...
  108
+
  109
+The `--fields=+l` argument makes sure that Exuberant Ctags includes a `language:...` property with each entry in the tags file. This is required by the `:HighlightTags` command so it can filter tags by their file type. The other two arguments make sure Exuberant Ctags generates tags for function prototypes in C/C++ source code.
  110
+
  111
+If you have the `g:easytags_include_members` option enabled (its off by default) then you'll also need to add the `--extra=+q` argument so that Exuberant Ctags generates tags for structure/class members.
  112
+
103 113
 ### The plug-in complains that Exuberant Ctags isn't installed
104 114
 
105 115
 After a Mac OS X user found out the hard way that the `ctags` executable isn't always Exuberant Ctags and we spend a few hours debugging the problem I added proper version detection: The plug-in executes `ctags --version` when Vim is started to verify that Exuberant Ctags 5.5 or newer is installed. If it isn't Vim will show the following message on startup:
4  TODO.md
Source Rendered
@@ -8,7 +8,9 @@
8 8
 
9 9
  * Use separate tags files for each language stored in ~/.vim/tags/ to increase performance because a single, global tags file quickly grows to a megabyte?
10 10
 
11  
- * On Microsoft Windows (tested on XP) GVim loses focus while `ctags` is running because Vim opens a command prompt window. Also the CursorHold event seems to fire repeatedly, contradicting my understanding of the autocmd and its behavior on UNIX?!
  11
+ * Make `g:easytags_autorecurse` accept the following values: 0 (only scan the current file), 1 (always scan all files in the same directory) and 2 (always recurse down the current directory)?
  12
+
  13
+ * On Microsoft Windows (tested on XP) GVim loses focus while `ctags` is running because Vim opens a command prompt window. Also the CursorHold event seems to fire repeatedly, contradicting my understanding of the automatic command and its behavior on UNIX?! This behavior doesn't occur when I use the integration with my `shell.vim` plug-in.
12 14
 
13 15
  * I might have found a bug in Vim: The tag `easytags#highlight_cmd` was correctly being highlighted by my plug-in (and was indeed included in my tags file) even though I couldn't jump to it using `Ctrl-]`, which caused:
14 16
 

0 notes on commit 738d750

Please sign in to comment.
Something went wrong with that request. Please try again.