diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/easytags.txt | 433 |
1 files changed, 215 insertions, 218 deletions
diff --git a/doc/easytags.txt b/doc/easytags.txt index 2f354ff..6ae6516 100644 --- a/doc/easytags.txt +++ b/doc/easytags.txt @@ -1,16 +1,15 @@ *easytags.txt* Automated tag generation and syntax highlighting in Vim =============================================================================== - *easytags-contents* Contents ~ - 1. Introduction |easytags-introduction| - 2. Installation |easytags-installation| - 1. A note about Windows |easytags-a-note-about-windows| - 3. Commands |easytags-commands| + 1. Introduction |easytags-introduction| + 2. Installation |easytags-installation| + 1. A note about Windows |easytags-note-about-windows| + 3. Commands |easytags-commands| 1. The |:UpdateTags| command 2. The |:HighlightTags| command - 4. Options |easytags-options| + 4. Options |easytags-options| 1. The |g:easytags_cmd| option 2. The |g:easytags_languages| option 3. The |g:easytags_file| option @@ -28,39 +27,40 @@ Contents ~ 15. The |g:easytags_resolve_links| option 16. The |g:easytags_suppress_ctags_warning| option 17. The |g:easytags_ignored_syntax_groups| option - 5. Customizing the easytags plug-in |customizing-easytags-plug-in| - 1. Passing custom command line arguments to Exuberant Ctags - 2. Update & highlight tags immediately after save - 3. How to customize the highlighting colors? + 5. Customizing the easytags plug-in |customizing-easytags-plug-in| + 1. Passing custom command line arguments to Exuberant Ctags |easytags-passing-custom-command-line-arguments-to-exuberant-ctags| + 2. Update & highlight tags immediately after save |easytags-update-highlight-tags-immediately-after-save| + 3. How to customize the highlighting colors? |easytags-how-to-customize-highlighting-colors| 6. 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 - 7. Troubleshooting |easytags-troubleshooting| - 1. |:HighlightTags| only works for the tags file created by |:UpdateTags| - 2. The plug-in complains that Exuberant Ctags isn't installed - 3. Vim locks up while the plug-in is running - 4. Failed to highlight tags because pattern is too big! - 5. The plug-in doesn't seem to work in Cygwin - 8. Contact |easytags-contact| - 9. License |easytags-license| + 7. Troubleshooting |easytags-troubleshooting| + 1. |:HighlightTags| only works for the tags file created by |:UpdateTags| |easytags-highlighttags-only-works-for-tags-file-created-by-updatetags| + 2. The plug-in complains that Exuberant Ctags isn't installed |easytags-plug-in-complains-that-exuberant-ctags-isnt-installed| + 3. Vim locks up while the plug-in is running |easytags-vim-locks-up-while-plug-in-is-running| + 4. Failed to highlight tags because pattern is too big! |easytags-failed-to-highlight-tags-because-pattern-is-too-big| + 5. The plug-in doesn't seem to work in Cygwin |easytags-plug-in-doesnt-seem-to-work-in-cygwin| + 8. Contact |easytags-contact| + 9. License |easytags-license| + 10. References |easytags-references| =============================================================================== - *easytags-introduction* + *easytags-introduction* Introduction ~ -Vim has long been my favorite text editor and combined with Exuberant Ctags -[1] it has the potential to provide most of what I expect from an integrated +Vim has long been my favorite text editor and combined with Exuberant Ctags [1] +it has the potential to provide most of what I expect from an integrated development environment [2]. Exuberant Ctags is the latest incarnation of a family of computer programs [3] 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 +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-] (see |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 [4] (!) and Exuberant -Ctags can generate tags for over 40 file types [5] as well... +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 [4] (!) and Exuberant Ctags can +generate tags for over 40 file types [5] as well... There's just one problem: You have to manually keep your tags files up-to-date and this turns out to be a royal pain in the ass! So I set out to write a Vim @@ -70,11 +70,11 @@ 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-installation* + *easytags-installation* Installation ~ -Please note that the vim-easytags plug-in requires my vim-misc plug-in which -is separately distributed. +_Please note that the vim-easytags plug-in requires my vim-misc plug-in which +is separately distributed._ Unzip the most recent ZIP archives of the vim-easytags [6] and vim-misc [7] plug-ins inside your Vim profile directory (usually this is '~/.vim' on UNIX @@ -82,8 +82,8 @@ and '%USERPROFILE%\vimfiles' on Windows), restart Vim and execute the command ':helptags ~/.vim/doc' (use ':helptags ~\vimfiles\doc' instead on Windows). If you prefer you can also use Pathogen [8], Vundle [9] or a similar tool to -install & update the vim-easytags [10] and vim-misc [11] plug-ins using a -local clone of the git repository. +install & update the vim-easytags [10] and vim-misc [11] plug-ins using a local +clone of the git repository. Now try it out: Edit any file type supported by Exuberant Ctags and within ten seconds the plug-in should create/update your tags file ('~/.vimtags' on UNIX, @@ -97,28 +97,28 @@ notice that the function and type names defined in the file have been syntax highlighted. The 'easytags.vim' plug-in is intended to work automatically once it's -installed, but if you want to change how it works there are several options -you can change and commands you can execute from your own mappings and/or -automatic commands. These are all documented below. +installed, but if you want to change how it works there are several options you +can change and commands you can execute from your own mappings and/or automatic +commands. These are all documented below. Note that if the plug-in warns you 'ctags' isn't installed you'll have to download it from its homepage [1], or if you're running Debian/Ubuntu you can install it by executing the following shell command: > - $ sudo apt-get install exuberant-ctags - + $ sudo apt-get install exuberant-ctags +< ------------------------------------------------------------------------------- - *easytags-a-note-about-windows* + *easytags-note-about-windows* A note about Windows ~ On Windows the |system()| function used by 'easytags.vim' causes a command -prompt window to pop up while Exuberant Ctags is executing. If this bothers -you then you can install my shell.vim [12] plug-in which includes a DLL [13] -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. +prompt window to pop up while Exuberant Ctags is executing. If this bothers you +then you can install my shell.vim [12] plug-in which includes a DLL [13] 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. =============================================================================== - *easytags-commands* + *easytags-commands* Commands ~ ------------------------------------------------------------------------------- @@ -151,7 +151,7 @@ Note that this command will be executed automatically every once in a while, assuming you haven't changed |g:easytags_on_cursorhold|. =============================================================================== - *easytags-options* + *easytags-options* Options ~ The easytags plug-in should work out of the box but if you don't like the @@ -161,26 +161,26 @@ files by setting a buffer local variable instead of the global variable. For example to disable automatic highlighting (enabled by default) only in Python files you can add the following line to your |vimrc| script: > - :autocmd FileType python let b:easytags_auto_highlight = 0 - + :autocmd FileType python let b:easytags_auto_highlight = 0 +< Note that buffer local variables always override global variables, so if you want to undo this for a specific file you have to use |:unlet|: > - :unlet b:easytags_auto_highlight - + :unlet b:easytags_auto_highlight +< ------------------------------------------------------------------------------- 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 plug-in. If this is -the case you can set the global variable |g:easytags_cmd| to the location -where you've installed Exuberant Ctags, e.g.: +but some older, more primitive 'ctags' implementation which doesn't support the +same command line options and thus breaks the easytags plug-in. If 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' - + :let g:easytags_cmd = '/usr/local/bin/ctags' +< If you rely entirely on language-specific configuration and don't have a general ctags program, set this to the empty string. @@ -188,20 +188,20 @@ general ctags program, set this to the empty string. The *g:easytags_languages* option Exuberant Ctags supports many languages and can be extended via regular -expression patterns, but for some languages separate tools with -ctags-compatible output exist (e.g. jsctags [14] for Javascript). To use -these, the executable and its arguments must be configured: +expression patterns, but for some languages separate tools with ctags- +compatible output exist (e.g. jsctags [14] for Javascript). To use these, the +executable and its arguments must be configured: > - let g:easytags_languages = { - \ 'language': { - \ 'cmd': g:easytags_cmd, - \ 'args': [], - \ 'fileoutput_opt': '-f', - \ 'stdout_opt': '-f-', - \ 'recurse_flag': '-R' - \ } - \} - + let g:easytags_languages = { + \ 'language': { + \ 'cmd': g:easytags_cmd, + \ 'args': [], + \ 'fileoutput_opt': '-f', + \ 'stdout_opt': '-f-', + \ 'recurse_flag': '-R' + \ } + \} +< Each key is a special language definition. The key is in the notation of ctags in lowercase; you still need to use 'xolox#easytags#map_filetypes()' to map this to Vim's filetypes, if necessary. @@ -212,12 +212,12 @@ differ. ------------------------------------------------------------------------------- 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.: +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.: > - :let g:easytags_file = '~/.vim/tags' - + :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). @@ -228,22 +228,20 @@ By default |:UpdateTags| only writes to the global tags file, but it can be configured to look for project specific tags files by adding the following lines to your |vimrc| script: > - :set tags=./tags; - :let g:easytags_dynamic_files = 1 - + :set tags=./tags; + :let g:easytags_dynamic_files = 1 +< You can change the name of the tags file, the important thing is that it's relative to your working directory or the buffer (using a leading './'). When |g:easytags_dynamic_files| is set to 1 the easytags plug-in will write to the first existing tags file seen by Vim (based on the |'tags'| option). In other words: If a project specific tags file is found it will be used, otherwise the -plug-in falls back to the global tags file (or a file type specific tags -file). +plug-in falls back to the global tags file (or a file type specific tags file). If you set |g:easytags_dynamic_files| to 2 the easytags plug-in will automatically create project specific tags based on the first name in the -'tags' option. In this mode the the global tags file or file type specific -tags files are only used for directories where you don't have write -permissions. +'tags' option. In this mode the the global tags file or file type specific tags +files are only used for directories where you don't have write permissions. The |'tags'| option is reevaluated each time the plug-in runs, so which tags file is selected can differ depending on the buffer and working directory. @@ -270,16 +268,16 @@ files from the global tags file using the command ':TagsByFileType'. The *g:easytags_events* option This option can be used to customize the events that trigger the automatic -updating and highlighting performed by the easytags plug-in. The |g:easytags_always_enabled| -and |g:easytags_on_cursorhold| options are more user friendly but limited ways -to accomplish the same thing. +updating and highlighting performed by the easytags plug-in. The +|g:easytags_always_enabled| and |g:easytags_on_cursorhold| options are more +user friendly but limited ways to accomplish the same thing. Here's an example: Say you want the easytags plug-in to automatically update & highlight tags for the current file right after you save the file. You can accomplish this by adding the following line to your |vimrc| script: > - :let g:easytags_events = ['BufWritePost'] - + :let g:easytags_events = ['BufWritePost'] +< Note that if you set |g:easytags_events| in your |vimrc| script, the values of the options |g:easytags_always_enabled| and |g:easytags_on_cursorhold| will be ignored completely. @@ -293,54 +291,54 @@ 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: > - :let g:easytags_always_enabled = 1 - + :let g:easytags_always_enabled = 1 +< Be warned that after setting this option you'll probably notice why it's disabled by default: Every time you edit a file in Vim, the plug-in will first run Exuberant Ctags and then highlight the tags, and this slows Vim down quite a lot. I have some ideas on how to improve this latency by running Exuberant Ctags in the background so stay tuned! -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. +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 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 -least amount of work possible in this break but it might still interrupt your +tags until you stop typing for a moment. The plug-in tries hard to do the least +amount of work possible in this break but it might still interrupt your 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. + :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. ------------------------------------------------------------------------------- The *g:easytags_updatetime_min* option 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 +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. +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 +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). +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 @@ -351,12 +349,12 @@ 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 +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 +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. ------------------------------------------------------------------------------- @@ -366,8 +364,8 @@ By default the plug-in automatically updates and highlights your tags when you stop typing for a moment. If you want to disable automatic updating while keeping automatic highlighting enabled you can set this option to false: > - :let g:easytags_auto_update = 0 - + :let g:easytags_auto_update = 0 +< ------------------------------------------------------------------------------- The *g:easytags_auto_highlight* option @@ -375,8 +373,8 @@ By default the plug-in automatically updates and highlights your tags when you stop typing for a moment. If you want to disable automatic highlighting while keeping automatic updating enabled you can set this option to false: > - :let g:easytags_auto_highlight = 0 - + :let g:easytags_auto_highlight = 0 +< ------------------------------------------------------------------------------- The *g:easytags_autorecurse* option @@ -385,17 +383,17 @@ 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): > - :let g:easytags_autorecurse = 1 - + :let g:easytags_autorecurse = 1 +< You have to explicitly enable this option because it should only be used while navigating around small directory trees. Imagine always having this option -enabled and then having to edit a file in e.g. the root of your home -directory: The 'easytags.vim' plug-in would freeze Vim for a long time while -you'd have to wait for Exuberant Ctags to scan thousands of files... +enabled and then having to edit a file in e.g. the root of your home directory: +The 'easytags.vim' plug-in would freeze Vim for a long time while you'd have to +wait for Exuberant Ctags 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 @@ -406,28 +404,28 @@ 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| script (before the 'easytags.vim' plug-in is loaded): > - :let g:easytags_include_members = 1 - -Exuberant Ctags will be instructed to include struct/class members using the -'--extra=+q' command line argument and the 'easytags.vim' plug-in will -highlight them using the 'cMember' highlighting group. Because most color -schemes don't distinguish the Identifier and Type (see |group-name|) -highlighting groups all members will now probably look like type definitions. -You can change that by executing either of the following Vim commands (from -your vimrc script, a file type plug-in, etc.): + :let g:easytags_include_members = 1 +< +Exuberant Ctags will be instructed to include struct/class members using the ' +--extra=+q' command line argument and the 'easytags.vim' plug-in will highlight +them using the 'cMember' highlighting group. Because most color schemes don't +distinguish the Identifier and Type (see |group-name|) highlighting groups all +members will now probably look like type definitions. You can change that by +executing either of the following Vim commands (from 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 - + " 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 UNIX has symbolic links [15] and hard links [16], both of which conflict with -the concept of having one unique location for every identifier. With regards -to hard links there's not much anyone can do, but because I use symbolic links +the concept of having one unique location for every identifier. With regards to +hard links there's not much anyone can do, but because I use symbolic links quite a lot I've added this option. It's disabled by default since it has a small performance impact and might not do what unknowing users expect it to: When you enable this option the plug-in will resolve symbolic links in @@ -435,24 +433,25 @@ pathnames, which means your tags file will only contain entries with canonical pathnames [17]. To enable this option (which I strongly suggest doing when you run UNIX and use symbolic links) execute the following Vim command: > - :let g:easytags_resolve_links = 1 - + :let g:easytags_resolve_links = 1 +< ------------------------------------------------------------------------------- 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. > - :let g:easytags_suppress_ctags_warning = 1 - + :let g:easytags_suppress_ctags_warning = 1 +< ------------------------------------------------------------------------------- The *g:easytags_ignored_syntax_groups* option This variable is a string of comma separated names of syntax groups in which -dynamic highlighting is not applied. It defaults to '.*String.*,.*Comment.*,cIncluded'. +dynamic highlighting is not applied. It defaults to +'.*String.*,.*Comment.*,cIncluded'. =============================================================================== - *customizing-easytags-plug-in* + *customizing-easytags-plug-in* Customizing the easytags plug-in ~ Advanced users may wish to customize how the easytags plug-in works beyond the @@ -460,29 +459,32 @@ point of changing configuration defaults. This section contains some hints about this. If you have suggestions, please feel free to submit them. ------------------------------------------------------------------------------- + *easytags-passing-custom-command-line-arguments-to-exuberant-ctags* Passing custom command line arguments to Exuberant Ctags ~ You may want to run Exuberant Ctags with specific command line options, for example the code_complete [18] plug-in requires the signature field to be present. To do this you can create a configuration file for Exuberant Ctags, e.g. '~/.ctags' on UNIX or '%USERPROFILE%\ctags.cnf' on Windows. The file -should contain one command line option per line. See the Exuberant Ctags -manual [19] for details. +should contain one command line option per line. See the Exuberant Ctags manual +[19] for details. ------------------------------------------------------------------------------- + *easytags-update-highlight-tags-immediately-after-save* Update & highlight tags immediately after save ~ -By default the easytags plug-in automatically updates & highlights tags for -the current file after several seconds of inactivity. This is done to prevent -the easytags plug-in from interrupting your workflow. +By default the easytags plug-in automatically updates & highlights tags for the +current file after several seconds of inactivity. This is done to prevent the +easytags plug-in from interrupting your workflow. If you want the easytags plug-in to automatically update & highlight tags for the current file right after you save the file, you can add the following line to your |vimrc| script: > - :let g:easytags_events = ['BufWritePost'] - + :let g:easytags_events = ['BufWritePost'] +< ------------------------------------------------------------------------------- + *easytags-how-to-customize-highlighting-colors* How to customize the highlighting colors? ~ The easytags plug-in defines new highlighting groups for dynamically @@ -492,37 +494,27 @@ 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: - - AWK: 'awkFunctionTag' - - - C#: 'csClassOrStructTag', 'csMethodTag' - - - C, C++, Objective C: 'cTypeTag', 'cEnumTag', 'cPreProcTag', 'cFunctionTag', - 'cMemberTag' - - - Java: 'javaClassTag', 'javaMethodTag' - - - Lua: 'luaFuncTag' - - - PHP: 'phpFunctionsTag', 'phpClassesTag' - - - Python: 'pythonFunctionTag', 'pythonMethodTag', 'pythonClassTag' - - - Ruby: 'rubyModuleNameTag', 'rubyClassNameTag', 'rubyMethodNameTag' - - - Shell: 'shFunctionTag' - - - Tcl: 'tclCommandTag' - - - Vim: 'vimAutoGroupTag', 'vimCommandTag', 'vimFuncNameTag', - 'vimScriptFuncNameTag' +- **AWK**: 'awkFunctionTag' +- **C#:**'csClassOrStructTag', 'csMethodTag' +- **C, C++, Objective C:**'cTypeTag', 'cEnumTag', 'cPreProcTag', + 'cFunctionTag', 'cMemberTag' +- **Java:**'javaClassTag', 'javaMethodTag' +- **Lua:**'luaFuncTag' +- **PHP:**'phpFunctionsTag', 'phpClassesTag' +- **Python:**'pythonFunctionTag', 'pythonMethodTag', 'pythonClassTag' +- **Ruby:**'rubyModuleNameTag', 'rubyClassNameTag', 'rubyMethodNameTag' +- **Shell**: 'shFunctionTag' +- **Tcl**: 'tclCommandTag' +- **Vim:**'vimAutoGroupTag', 'vimCommandTag', 'vimFuncNameTag', + 'vimScriptFuncNameTag' 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 -tried to match the existing highlighting groups defined by popular syntax -modes (except of course for the 'Tag' suffix). +tried to match the existing highlighting groups defined by popular syntax modes +(except of course for the 'Tag' suffix). =============================================================================== - *easytags-faster-syntax-highlighting-using-python* + *easytags-faster-syntax-highlighting-using-python* Faster syntax highlighting using Python ~ The Vim script implementation of dynamic syntax highlighting is quite slow on @@ -534,8 +526,8 @@ following options are available to change the default configuration. ------------------------------------------------------------------------------- The *g:easytags_python_enabled* option -To disable the Python implementation of dynamic syntax highlighting you can -set this option to false (0). +To disable the Python implementation of dynamic syntax highlighting you can set +this option to false (0). ------------------------------------------------------------------------------- The *g:easytags_python_script* option @@ -544,18 +536,19 @@ This option defines the pathname of the script that contains the Python implementation of dynamic syntax highlighting. =============================================================================== - *easytags-troubleshooting* + *easytags-troubleshooting* Troubleshooting ~ ------------------------------------------------------------------------------- -|:HighlightTags| only works for the tags file created by |:UpdateTags| ~ + *easytags-highlighttags-only-works-for-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 arguments to Exuberant Ctags: > - $ ctags --fields=+l --c-kinds=+p --c++-kinds=+p ... - + $ ctags --fields=+l --c-kinds=+p --c++-kinds=+p ... +< 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 @@ -567,6 +560,7 @@ default) then you'll also need to add the '--extra=+q' argument so that Exuberant Ctags generates tags for structure/class members. ------------------------------------------------------------------------------- + *easytags-plug-in-complains-that-exuberant-ctags-isnt-installed* The plug-in complains that Exuberant Ctags isn't installed ~ After a Mac OS X user found out the hard way that the 'ctags' executable isn't @@ -575,25 +569,26 @@ 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: > - easytags.vim: Plug-in not loaded because Exuberant Ctags isn't installed! - Please download & install Exuberant Ctags from http://ctags.sf.net - + easytags.vim: Plug-in not loaded because Exuberant Ctags isn't installed! + Please download & install Exuberant Ctags from http://ctags.sf.net +< If the installed Exuberant Ctags version is too old the plug-in will complain: > - easytags.vim: Plug-in not loaded because Exuberant Ctags 5.5 - or newer is required while you have version %s installed! - + easytags.vim: Plug-in not loaded because Exuberant Ctags 5.5 + or newer is required while you have version %s installed! +< If you have the right version of Exuberant Ctags installed but the plug-in still complains, try executing the following command from inside Vim: > - :!which ctags - -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. + :!which ctags +< +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. ------------------------------------------------------------------------------- + *easytags-vim-locks-up-while-plug-in-is-running* Vim locks up while the plug-in is running ~ Once or twice now in several years I've experienced Exuberant Ctags getting @@ -604,65 +599,67 @@ to kill 'ctags' by pressing Control-C (see |CTRL-C|) but if that doesn't work you can also kill it without stopping Vim using a task manager or the 'pkill' command (available on most UNIX systems): > - $ pkill -KILL ctags - + $ pkill -KILL ctags +< If Vim seems very slow and you suspect this plug-in might be the one to blame, increase Vim's verbosity level: > - :set vbs=1 - + :set vbs=1 +< Every time the plug-in executes it will time how long the execution takes and add the results to Vim's message history, which you can view by executing the |:messages| command. ------------------------------------------------------------------------------- + *easytags-failed-to-highlight-tags-because-pattern-is-too-big* Failed to highlight tags because pattern is too big! ~ 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 and unfortunately the only way to avoid this problem once it occurs -is to reduce the number of tagged identifiers... +'/usr/include/' to my tags file. Internally Vim raises the error |E339|: +Pattern too long 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 as follows: > - :set tags=./.tags;,~/.vimtags - + :set tags=./.tags;,~/.vimtags +< Once you've executed the above command, Vim will automatically look for a file -named '.tags' in the directory of the current file. Because of the ';' Vim -also recurses upwards so that you can nest files arbitrarily deep under your -project directories. +named '.tags' in the directory of the current file. Because of the ';' Vim also +recurses upwards so that you can nest files arbitrarily deep under your project +directories. ------------------------------------------------------------------------------- + *easytags-plug-in-doesnt-seem-to-work-in-cygwin* The plug-in doesn't seem to work in Cygwin ~ -If you want to use the plug-in with Vim under Cygwin [20], you need to have -the Cygwin version of Ctags installed instead of the Windows version (thanks -to Alex Zuroff for reporting this!). +If you want to use the plug-in with Vim under Cygwin [20], you need to have the +Cygwin version of Ctags installed instead of the Windows version (thanks to +Alex Zuroff for reporting this!). =============================================================================== - *easytags-contact* + *easytags-contact* Contact ~ If you have questions, bug reports, suggestions, etc. the author can be contacted at peter@peterodding.com. The latest version is available at -http://peterodding.com/code/vim/easytags/ and http://github.com/xolox/vim-easytags. -If you like this plug-in please vote for it on Vim Online [21]. +http://peterodding.com/code/vim/easytags/ and http://github.com/xolox/vim- +easytags. If you like this plug-in please vote for it on Vim Online [21]. =============================================================================== - *easytags-license* + *easytags-license* License ~ -This software is licensed under the MIT license [22]. Copyright 2013 Peter -Odding <peter@peterodding.com>. +This software is licensed under the MIT license [22]. © 2013 Peter Odding +<peter@peterodding.com>. =============================================================================== - *easytags-references* + *easytags-references* References ~ [1] http://ctags.sourceforge.net/ |