From 384ebf413dac9739d15857bf5a51c05e9c91d514 Mon Sep 17 00:00:00 2001
From: Peter Odding <peter@peterodding.com>
Date: Sun, 19 May 2013 13:51:34 +0200
Subject: Add g:easytags_updatetime_warn option, improve documentation (issue
#47)
Issue #47 on GitHub:
https://github.com/xolox/vim-easytags/issues/47
---
README.md | 17 ++++++++++--
autoload/xolox/easytags.vim | 8 +++---
doc/easytags.txt | 63 ++++++++++++++++++++++++++++++++-------------
3 files changed, 65 insertions(+), 23 deletions(-)
diff --git a/README.md b/README.md
index 51b0ab4..d29492d 100644
--- a/README.md
+++ b/README.md
@@ -125,9 +125,21 @@ Note: Like the `g:easytags_always_enabled` option, if you change this option it
### The `g:easytags_updatetime_min` option
-Vim has a setting which influences how often the plug-in is automatically executed. When this setting is too low, the plug-in can break. For this reason the plug-in compensates by keeping track of when it was last executed. You'll get one warning when the plug-in first notices the low value, after that it will shut up. The default value of this option is 4000 milliseconds (4 seconds).
+Vim's ['updatetime'] [updatetime] option controls how often the easytags plug-in is automatically executed. A lot of popular Vim plug-ins manipulate this option to control how often they are called. Unfortunately some of those plug-ins set ['updatetime'] [updatetime] to a very low value (less than a second) and this can break the easytags plug-in.
-If you really want the plug-in to be executed more than once every 4 seconds you can lower the minimum acceptable updatetime by setting this option (as the number of milliseconds) however note that subsecond granularity is not supported.
+Because of this the easytags plug-in compensates by keeping track of when it was last executed. You'll get one warning when the plug-in first notices a very low value of ['updatetime'] [updatetime], after that the plug-in will shut up (until you restart Vim) and simply compensate by not executing until its time has come. If you want to silence the warning message forever, see the `g:easytags_updatetime_warn` option.
+
+The default value of Vim's ['updatetime] [updatetime] option *and* the `g:easytags_updatetime_min` option is 4000 milliseconds (4 seconds).
+
+If you know what you're doing and you really want the easytags plug-in to be executed more than once every 4 seconds you can lower the minimum acceptable updatetime by setting `g:easytags_updatetime_min` to the number of milliseconds (an integer).
+
+Note that although `g:easytags_updatetime_min` counts in milliseconds, the easytags plug-in does not support subsecond granularity because it is limited by Vim's [localtime()] [localtime] function which has one-second resolution.
+
+### The `g:easytags_updatetime_warn` option
+
+Since the easytags plug-in now compensates for low ['updatetime'] [updatetime] values (see the `g:easytags_updatetime_min` option above) the warning message shown by the easytags plug-in has become kind of redundant (and probably annoying?). For now it can be completely disabled by setting `g:easytags_updatetime_warn` to 0 (false).
+
+When the feature that compensates for low ['updatetime'] [updatetime] values has proven to be a reliable workaround I will probably remove the warning message and the `g:easytags_updatetime_warn` option.
### The `g:easytags_auto_update` option
@@ -297,6 +309,7 @@ This software is licensed under the [MIT license](http://en.wikipedia.org/wiki/M
[hlinks]: http://en.wikipedia.org/wiki/Hard_link
[ide]: http://en.wikipedia.org/wiki/Integrated_development_environment
[jsctags]: https://npmjs.org/package/jsctags
+[localtime]: http://vimdoc.sourceforge.net/htmldoc/eval.html#localtime()
[messages]: http://vimdoc.sourceforge.net/htmldoc/message.html#:messages
[neocomplcache]: http://www.vim.org/scripts/script.php?script_id=2620
[shell]: http://peterodding.com/code/vim/shell/
diff --git a/autoload/xolox/easytags.vim b/autoload/xolox/easytags.vim
index 034cdca..192f7c0 100644
--- a/autoload/xolox/easytags.vim
+++ b/autoload/xolox/easytags.vim
@@ -3,7 +3,7 @@
" Last Change: May 19, 2013
" URL: http://peterodding.com/code/vim/easytags/
-let g:xolox#easytags#version = '3.3.1'
+let g:xolox#easytags#version = '3.3.2'
call xolox#misc#compat#check('easytags', 3)
@@ -53,8 +53,10 @@ function! xolox#easytags#autoload(event) " {{{2
let updatetime_min = xolox#misc#option#get('easytags_updatetime_min', 4000)
if &updatetime < updatetime_min
if s:last_automatic_run == 0
- " Warn once about the low &updatetime value.
- call xolox#misc#msg#warn("easytags.vim %s: The 'updatetime' option has an unreasonably low value, so I'll start compensating (see the easytags_updatetime_min option).", g:xolox#easytags#version)
+ " Warn once about the low &updatetime value?
+ if xolox#misc#option#get('easytags_updatetime_warn', 1)
+ call xolox#misc#msg#warn("easytags.vim %s: The 'updatetime' option has an unreasonably low value, so I'll start compensating (see the easytags_updatetime_min option).", g:xolox#easytags#version)
+ endif
let s:last_automatic_run = localtime()
else
let next_scheduled_run = s:last_automatic_run + max([1, updatetime_min / 1000])
diff --git a/doc/easytags.txt b/doc/easytags.txt
index 4d38908..2aba0dc 100644
--- a/doc/easytags.txt
+++ b/doc/easytags.txt
@@ -19,13 +19,14 @@ Contents ~
6. The |g:easytags_always_enabled| option
7. The |g:easytags_on_cursorhold| option
8. The |g:easytags_updatetime_min| option
- 9. The |g:easytags_auto_update| option
- 10. The |g:easytags_auto_highlight| option
- 11. The |g:easytags_autorecurse| option
- 12. The |g:easytags_include_members| option
- 13. The |g:easytags_resolve_links| option
- 14. The |g:easytags_suppress_ctags_warning| option
- 15. The |g:easytags_ignored_syntax_groups| option
+ 9. The |g:easytags_updatetime_warn| option
+ 10. The |g:easytags_auto_update| option
+ 11. The |g:easytags_auto_highlight| option
+ 12. The |g:easytags_autorecurse| option
+ 13. The |g:easytags_include_members| option
+ 14. The |g:easytags_resolve_links| option
+ 15. The |g:easytags_suppress_ctags_warning| option
+ 16. The |g:easytags_ignored_syntax_groups| option
5. Faster syntax highlighting using Python |easytags-faster-syntax-highlighting-using-python|
1. The |g:easytags_python_enabled| option
2. The |g:easytags_python_script| option
@@ -291,17 +292,43 @@ your |vimrc| script.
-------------------------------------------------------------------------------
The *g:easytags_updatetime_min* option
-Vim has a setting which influences how often the plug-in is automatically
-executed. When this setting is too low, the plug-in can break. For this reason
-the plug-in compensates by keeping track of when it was last executed. You'll
-get one warning when the plug-in first notices the low value, after that it
-will shut up. The default value of this option is 4000 milliseconds (4
-seconds).
-
-If you really want the plug-in to be executed more than once every 4 seconds
-you can lower the minimum acceptable updatetime by setting this option (as the
-number of milliseconds) however note that subsecond granularity is not
-supported.
+Vim's |'updatetime'| option controls how often the easytags plug-in is
+automatically executed. A lot of popular Vim plug-ins manipulate this option
+to control how often they are called. Unfortunately some of those plug-ins set
+|'updatetime'| to a very low value (less than a second) and this can break the
+easytags plug-in.
+
+Because of this the easytags plug-in compensates by keeping track of when it
+was last executed. You'll get one warning when the plug-in first notices a
+very low value of |'updatetime'|, after that the plug-in will shut up (until you
+restart Vim) and simply compensate by not executing until its time has come.
+If you want to silence the warning message forever, see the |g:easytags_updatetime_warn|
+option.
+
+The default value of Vim's 'updatetime (see |'updatetime'|) option and the
+|g:easytags_updatetime_min| option is 4000 milliseconds (4 seconds).
+
+If you know what you're doing and you really want the easytags plug-in to be
+executed more than once every 4 seconds you can lower the minimum acceptable
+updatetime by setting |g:easytags_updatetime_min| to the number of
+milliseconds (an integer).
+
+Note that although |g:easytags_updatetime_min| counts in milliseconds, the
+easytags plug-in does not support subsecond granularity because it is limited
+by Vim's |localtime()| function which has one-second resolution.
+
+-------------------------------------------------------------------------------
+The *g:easytags_updatetime_warn* option
+
+Since the easytags plug-in now compensates for low |'updatetime'| values (see
+the |g:easytags_updatetime_min| option above) the warning message shown by the
+easytags plug-in has become kind of redundant (and probably annoying?). For
+now it can be completely disabled by setting |g:easytags_updatetime_warn| to 0
+(false).
+
+When the feature that compensates for low |'updatetime'| values has proven to be
+a reliable workaround I will probably remove the warning message and the
+|g:easytags_updatetime_warn| option.
-------------------------------------------------------------------------------
The *g:easytags_auto_update* option
--
cgit v1.2.3