Enable updating of project specific tags files

4 files changed, 119 insertions, 57 deletions

diff --git a/README.md b/README.md
index 6d42350..85ab460 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Automated tag generation and syntax highlighting in Vim
 
-[Vim](http://www.vim.org/) has long been my favorite text editor and combined with [Exuberant Ctags] [exuberant_ctags] it has the potential to provide most of what I expect from an [integrated development environment](http://en.wikipedia.org/wiki/Integrated_development_environment). Exuberant Ctags is the latest incarnation of a [family of computer programs](http://en.wikipedia.org/wiki/Ctags) that scan source code files to create an index of identifiers (tags) and where they are defined. Vim uses this index (a so-called tags file) to enable you to jump to the definition of any identifier using the [Control-]](http://vimdoc.sourceforge.net/htmldoc/tagsrch.html#CTRL-]) mapping.
+[Vim](http://www.vim.org/) has long been my favorite text editor and combined with [Exuberant Ctags] [exuberant_ctags] it has the potential to provide most of what I expect from an [integrated development environment](http://en.wikipedia.org/wiki/Integrated_development_environment). Exuberant Ctags is the latest incarnation of a [family of computer programs](http://en.wikipedia.org/wiki/Ctags) that scan source code files to create an index of identifiers (tags) and where they are defined. Vim uses this index (a so-called tags file) to enable you to jump to the definition of any identifier using the [Control-]](http://vimdoc.sourceforge.net/htmldoc/tagsrch.html#CTRL-]) mapping.
 
 When you're familiar with integrated development environments you may recognize this feature as "Go-to definition". One advantage of the combination of Vim and Exuberant Ctags over integrated development environments is that Vim supports syntax highlighting for [over 500 file types](http://ftp.vim.org/vim/runtime/syntax/) (!) and Exuberant Ctags can generate tags for [over 40 file types](http://ctags.sourceforge.net/languages.html) as well...
 
@@ -32,7 +32,7 @@ Note that this command will be executed automatically every once in a while, ass
 
 ### The `:HighlightTags` command
 
-When you execute this command while editing one of the supported file types (see above) the relevant tags in the current file are highlighted. The tags to highlight are gathered from all tags files known to Vim (through the ['tags' option](http://vimdoc.sourceforge.net/htmldoc/options.html#'tags')).
+When you execute this command while editing one of the supported file types (see above) the relevant tags in the current file are highlighted. The tags to highlight are gathered from all tags files known to Vim (through the ['tags' option](http://vimdoc.sourceforge.net/htmldoc/options.html#%27tags%27)).
 
 Note that this command will be executed automatically every once in a while, assuming you haven't changed `g:easytags_on_cursorhold`.
 
@@ -50,6 +50,18 @@ As mentioned above the plug-in will store your tags in `~/.vimtags` on UNIX and
 
 A leading `~` in the `g:easytags_file` variable is expanded to your current home directory (`$HOME` on UNIX, `%USERPROFILE%` on Windows).
 
+### The `g:easytags_dynamic_files` option
+
+By default `:UpdateTags` only writes to the global tags file. If you use the following setting to enable project specific tags files:
+
+    :set tags=./tags;
+
+You can enable this option so that the project specific tags files are written instead of the global tags file:
+
+    :let g:easytags_dynamic_files = 1
+
+When you enable this option, the easytags plug-in will use the first filename returned by [tagfiles()](http://vimdoc.sourceforge.net/htmldoc/eval.html#tagfiles%28%29) as the tags file to write. Note that `tagfiles()` is reevaluated every time the plug-in runs.
+
 ### The `g:easytags_always_enabled` option
 
 By default the plug-in automatically generates and highlights tags when you stop typing for a few seconds (this works using the [CursorHold](http://vimdoc.sourceforge.net/htmldoc/autocmd.html#CursorHold) automatic command). This means that when you edit a file, the dynamic highlighting won't appear until you pause for a moment. If you don't like this you can configure the plug-in to always enable dynamic highlighting:
@@ -164,7 +176,7 @@ Every time the plug-in executes it will time how long the execution takes and ad
 
 If the `easytags.vim` plug-in fails to highlight your tags and the error message mentions that the pattern is too big, your tags file has grown too large for Vim to be able to highlight all tagged identifiers! I've had this happen to me with 50 KB patterns because I added most of the headers in `/usr/include/` to my tags file. Internally Vim raises the error [E339: Pattern too long](http://vimdoc.sourceforge.net/htmldoc/message.html#E339) and unfortunately the only way to avoid this problem once it occurs is to reduce the number of tagged identifiers...
 
-In my case the solution was to move most of the tags from `/usr/include/` over to project specific tags files which are automatically loaded by Vim when I edit files in different projects because I've set the ['tags' option](http://vimdoc.sourceforge.net/htmldoc/options.html#'tags') as follows:
+In my case the solution was to move most of the tags from `/usr/include/` over to project specific tags files which are automatically loaded by Vim when I edit files in different projects because I've set the ['tags' option](http://vimdoc.sourceforge.net/htmldoc/options.html#%27tags%27) as follows:
 
     :set tags=./.tags;,~/.vimtags
 
diff --git a/autoload/xolox/easytags.vim b/autoload/xolox/easytags.vim
index 8202e8a..15d63f7 100644
--- a/autoload/xolox/easytags.vim
+++ b/autoload/xolox/easytags.vim
@@ -1,6 +1,6 @@
 " Vim script
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: March 15, 2011
+" Last Change: April 23, 2011
 " URL: http://peterodding.com/code/vim/easytags/
 
 let s:script = expand('<sfile>:p:~')
@@ -344,6 +344,12 @@ function! xolox#easytags#add_tagged_file(filename) " {{{2
 endfunction
 
 function! xolox#easytags#get_tagsfile() " {{{2
+  if g:easytags_dynamic_files
+    let files = tagfiles()
+    if len(files) > 0
+      return files[0]
+    endif
+  endif
   let tagsfile = expand(g:easytags_file)
   if filereadable(tagsfile) && filewritable(tagsfile) != 1
     let message = "The tags file %s isn't writable!"
diff --git a/doc/easytags.txt b/doc/easytags.txt
index 3694620..b9ec98c 100644
--- a/doc/easytags.txt
+++ b/doc/easytags.txt
@@ -22,6 +22,7 @@ became interested in dynamic syntax highlighting, so I added that as well to
 see if it would work -- surprisingly well I'm happy to report!
 
 ==============================================================================
+                                                        *easytags-install-usage*
 Install & usage ~
 
 Unzip the most recent ZIP archive [6] file inside your Vim profile directory
@@ -50,6 +51,7 @@ install it by executing the following shell command:
     $ sudo apt-get install exuberant-ctags
 
 ------------------------------------------------------------------------------
+                                              *easytags-if-you-re-using-windows*
 If you're using Windows ~
 
 On Windows the |system()| function used by 'easytags.vim' causes a command
@@ -59,25 +61,27 @@ that works around this issue. Once you've installed both plug-ins it should
 work out of the box! Please let me know if this doesn't work for you.
 
 ------------------------------------------------------------------------------
-The *:UpdateTags* command
+                                                  *easytags-:updatetags-command*
+The ':UpdateTags' command ~
 
 This command executes Exuberant Ctags [1] 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
+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).
+section "':HighlightTags' only works for the tags file created by
+':UpdateTags'" for more information).
 
-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.
+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.
 
 Note that this command will be executed automatically every once in a while,
-assuming you haven't changed |g:easytags_on_cursorhold|.
+assuming you haven't changed 'g:easytags_on_cursorhold'.
 
 ------------------------------------------------------------------------------
-The *:HighlightTags* command
+                                               *easytags-:highlighttags-command*
+The ':HighlightTags' command ~
 
 When you execute this command while editing one of the supported file types
 (see above) the relevant tags in the current file are highlighted. The tags to
@@ -85,35 +89,56 @@ highlight are gathered from all tags files known to Vim (through the |'tags'|
 option).
 
 Note that this command will be executed automatically every once in a while,
-assuming you haven't changed |g:easytags_on_cursorhold|.
+assuming you haven't changed 'g:easytags_on_cursorhold'.
 
 ------------------------------------------------------------------------------
-The *g:easytags_cmd* option
+                                                         *g:easytags_cmd-option*
+The 'g:easytags_cmd' option ~
 
 The plug-in will try to determine the location where Exuberant Ctags is
 installed on its own but this might not always work because any given
 executable named 'ctags' in your '$PATH' might not in fact be Exuberant Ctags
 but some older, more primitive 'ctags' implementation which doesn't support
 the same command line options and thus breaks the 'easytags.vim' plug-in. If
-this is the case you can set the global variable |g:easytags_cmd| to the
+this is the case you can set the global variable 'g:easytags_cmd' to the
 location where you've installed Exuberant Ctags, e.g.:
 >
     :let g:easytags_cmd = '/usr/local/bin/ctags'
 
 ------------------------------------------------------------------------------
-The *g:easytags_file* option
+                                                        *g:easytags_file-option*
+The 'g:easytags_file' option ~
 
 As mentioned above the plug-in will store your tags in '~/.vimtags' on UNIX
 and '~/_vimtags' on Windows. To change the location of this file, set the
-global variable |g:easytags_file|, e.g.:
+global variable 'g:easytags_file', e.g.:
 >
     :let g:easytags_file = '~/.vim/tags'
 
-A leading '~' in the |g:easytags_file| variable is expanded to your current home
-directory ('$HOME' on UNIX, '%USERPROFILE%' on Windows).
+A leading '~' in the 'g:easytags_file' variable is expanded to your current
+home directory ('$HOME' on UNIX, '%USERPROFILE%' on Windows).
 
 ------------------------------------------------------------------------------
-The *g:easytags_always_enabled* option
+                                               *g:easytags_dynamic_files-option*
+The 'g:easytags_dynamic_files' option ~
+
+By default ':UpdateTags' only writes to the global tags file. If you use the
+following setting to enable project specific tags files:
+>
+    :set tags=./tags;
+
+You can enable this option so that the project specific tags files are written
+instead of the global tags file:
+>
+    :let g:easytags_dynamic_files = 1
+
+When you enable this option, the easytags plug-in will use the first filename
+returned by |tagfiles()| as the tags file to write. Note that 'tagfiles()' is
+reevaluated every time the plug-in runs.
+
+------------------------------------------------------------------------------
+                                              *g:easytags_always_enabled-option*
+The 'g:easytags_always_enabled' option ~
 
 By default the plug-in automatically generates and highlights tags when you
 stop typing for a few seconds (this works using the |CursorHold| automatic
@@ -133,7 +158,8 @@ Note: If you change this option it won't apply until you restart Vim, so
 you'll have to set this option in your |vimrc| script.
 
 ------------------------------------------------------------------------------
-The *g:easytags_on_cursorhold* option
+                                               *g:easytags_on_cursorhold-option*
+The 'g:easytags_on_cursorhold' option ~
 
 As I explained above the plug-in by default doesn't update or highlight your
 tags until you stop typing for a moment. The plug-in tries hard to do the
@@ -142,14 +168,15 @@ workflow. If it does you can disable the periodic update:
 >
     :let g:easytags_on_cursorhold = 0
 
-Note: Like the |g:easytags_always_enabled| option, if you change this option it
-won't apply until you restart Vim, so you'll have to set this option in your
-|vimrc| script.
+Note: Like the 'g:easytags_always_enabled' option, if you change this option
+it won't apply until you restart Vim, so you'll have to set this option in
+your |vimrc| script.
 
 ------------------------------------------------------------------------------
-The *g:easytags_autorecurse* option
+                                                 *g:easytags_autorecurse-option*
+The 'g:easytags_autorecurse' option ~
 
-When the |:UpdateTags| command is executed automatically or without arguments,
+When the ':UpdateTags' command is executed automatically or without arguments,
 it defaults to updating just the tags for the current file. If you'd rather
 have it recursively scan everything below the directory of the current file
 then set this option to true (1):
@@ -163,16 +190,17 @@ directory: The 'easytags.vim' plug-in would freeze Vim for a long time while
 you'd have to wait for Exuberant Cags to scan thousands of files...
 
 Note that when you enable this option the 'easytags.vim' plug-in might ignore
-other options like |g:easytags_resolve_links|. This is an implementation detail
-which I intend to fix.
+other options like 'g:easytags_resolve_links'. This is an implementation
+detail which I intend to fix.
 
 ------------------------------------------------------------------------------
-The *g:easytags_include_members* option
+                                             *g:easytags_include_members-option*
+The 'g:easytags_include_members' option ~
 
 Exuberant Ctags knows how to generate tags for struct/class members in C++ and
 Java source code but doesn't do so by default because it can more than double
 the size of your tags files, thus taking much longer to read/write the tags
-file. When you enable the |g:easytags_include_members| option from your |vimrc|
+file. When you enable the 'g:easytags_include_members' option from your |vimrc|
 script (before the 'easytags.vim' plug-in is loaded):
 >
     :let g:easytags_include_members = 1
@@ -187,12 +215,13 @@ your vimrc script, a file type plug-in, etc.):
 >
     " If you like one of the existing styles you can link them:
     highlight link cMember Special
->
+    
     " You can also define your own style if you want:
     highlight cMember gui=italic
 
 ------------------------------------------------------------------------------
-The *g:easytags_resolve_links* option
+                                               *g:easytags_resolve_links-option*
+The 'g:easytags_resolve_links' option ~
 
 UNIX has symbolic links [9] and hard links [10], both of which conflict with
 the concept of having one unique location for every identifier. With regards
@@ -207,7 +236,8 @@ run UNIX and use symbolic links) execute the following Vim command:
     :let g:easytags_resolve_links = 1
 
 ------------------------------------------------------------------------------
-The *g:easytags_suppress_ctags_warning* option
+                                      *g:easytags_suppress_ctags_warning-option*
+The 'g:easytags_suppress_ctags_warning' option ~
 
 If this is set and not false, it will suppress the warning on startup if ctags
 is not found or not recent enough.
@@ -224,14 +254,20 @@ do so use a 'highlight' command such as the ones given a few paragraphs back.
 Of course you'll need to change the group name. Here are the group names used
 by the easytags plug-in:
 
- * Lua: 'luaFuncTag'
- * C: 'cTypeTag', 'cEnumTag', 'cPreProcTag', 'cFunctionTag', 'cMemberTag'
- * PHP: 'phpFunctionsTag', 'phpClassesTag'
- * Vim: 'vimAutoGroupTag', 'vimCommandTag', 'vimFuncNameTag',
+ - Lua: 'luaFuncTag'
+
+ - C: 'cTypeTag', 'cEnumTag', 'cPreProcTag', 'cFunctionTag', 'cMemberTag'
+
+ - PHP: 'phpFunctionsTag', 'phpClassesTag'
+
+ - Vim: 'vimAutoGroupTag', 'vimCommandTag', 'vimFuncNameTag',
    'vimScriptFuncNameTag'
- * Python: 'pythonFunctionTag', 'pythonMethodTag', 'pythonClassTag'
- * Java: 'javaClassTag', 'javaMethodTag'
- * C#: 'csClassOrStructTag', 'csMethodTag'
+
+ - Python: 'pythonFunctionTag', 'pythonMethodTag', 'pythonClassTag'
+
+ - Java: 'javaClassTag', 'javaMethodTag'
+
+ - C#: 'csClassOrStructTag', 'csMethodTag'
 
 As you can see each of these names ends in 'Tag' to avoid conflicts with the
 syntax modes shipped with Vim. And about the singular/plural confusion: I've
@@ -239,10 +275,11 @@ tried to match the existing highlighting groups defined by popular syntax
 modes (except of course for the 'Tag' suffix).
 
 ==============================================================================
+                                                      *easytags-troubleshooting*
 Troubleshooting ~
 
 ------------------------------------------------------------------------------
-:HighlightTags only works for the tags file created by :UpdateTags ~
+':HighlightTags' only works for the tags file created by ':UpdateTags' ~
 
 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
@@ -252,13 +289,13 @@ arguments to Exuberant Ctags:
 
 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.
+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.
 
-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.
+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.
 
 ------------------------------------------------------------------------------
 The plug-in complains that Exuberant Ctags isn't installed ~
@@ -284,8 +321,8 @@ still complains, try executing the following command from inside Vim:
 
 If this doesn't print the location where you installed Exuberant Ctags it
 means your system already had a 'ctags' executable but it isn't compatible
-with Exuberant Ctags 5.5 and you'll need to set the |g:easytags_cmd| option (see
-above) so the plug-in knows which 'ctags' to run.
+with Exuberant Ctags 5.5 and you'll need to set the 'g:easytags_cmd' option
+(see above) so the plug-in knows which 'ctags' to run.
 
 ------------------------------------------------------------------------------
 Vim locks up while the plug-in is running ~
@@ -340,6 +377,7 @@ Cygwin version of Ctags installed instead of the Windows version (thanks to
 Alex Zuroff for reporting this!).
 
 ==============================================================================
+                                                              *easytags-contact*
 Contact ~
 
 If you have questions, bug reports, suggestions, etc. the author can be
@@ -348,12 +386,14 @@ http://peterodding.com/code/vim/easytags/ and http://github.com/xolox/vim-easyta
 If you like this plug-in please vote for it on Vim Online [13].
 
 ==============================================================================
+                                                              *easytags-license*
 License ~
 
-This software is licensed under the MIT license [14].
-Copyright 2010 Peter Odding <peter@peterodding.com>.
+This software is licensed under the MIT license [14]. Copyright 2010 Peter
+Odding <peter@peterodding.com>.
 
 ==============================================================================
+                                                           *easytags-references*
 References ~
 
 [1] http://ctags.sourceforge.net/
@@ -371,4 +411,4 @@ References ~
 [13] http://www.vim.org/scripts/script.php?script_id=3114
 [14] http://en.wikipedia.org/wiki/MIT_License
 
-vim: syntax=help nospell
+vim: ft=help
diff --git a/plugin/easytags.vim b/plugin/easytags.vim
index 2884da6..0c0537a 100644
--- a/plugin/easytags.vim
+++ b/plugin/easytags.vim
@@ -1,10 +1,10 @@
 " Vim plug-in
 " Author: Peter Odding <peter@peterodding.com>
-" Last Change: April 23, 2011
+" Last Change: May 2, 2011
 " URL: http://peterodding.com/code/vim/easytags/
 " Requires: Exuberant Ctags (http://ctags.sf.net)
 " License: MIT
-" Version: 2.2.5
+" Version: 2.2.6
 
 " Support for automatic update using the GLVS plug-in.
 " GetLatestVimScripts: 3114 1 :AutoInstall: easytags.zip
@@ -19,13 +19,17 @@ let s:script = expand('<sfile>:p:~')
 " Configuration defaults and initialization. {{{1
 
 if !exists('g:easytags_file')
-  if has('win32') || has('win64')
+  if xolox#misc#os#is_win()
     let g:easytags_file = '~\_vimtags'
   else
     let g:easytags_file = '~/.vimtags'
   endif
 endif
 
+if !exists('g:easytags_dynamic_files')
+  let g:easytags_dynamic_files = 0
+endif
+
 if !exists('g:easytags_resolve_links')
   let g:easytags_resolve_links = 0
 endif
@@ -140,7 +144,7 @@ function! s:RegisterTagsFile()
     " this is a bug in Vim is to type :set tags= then press <Tab> followed by
     " <CR>. Now you entered the exact same value that the code below also did
     " but suddenly Vim sees the tags file and tagfiles() != [] :-S
-    call insert(tagfiles, g:easytags_file)
+    call add(tagfiles, g:easytags_file)
     let value = xolox#misc#option#join_tags(tagfiles)
     let cmd = 'set tags=' . escape(value, '\ ')
     if xolox#misc#os#is_win() && v:version < 703