Skip to content
This repository
Browse code

Add documentation in vimdoc format

This is a generated file which I normally wouldn't commit but
Pathogen users like to check out the git repository directly.
  • Loading branch information...
commit 6de3e062202e249f9c46d273b8dc577657497893 1 parent 0a49b11
Peter Odding authored March 19, 2011

Showing 1 changed file with 374 additions and 0 deletions. Show diff stats Hide diff stats

  1. 374  doc/easytags.txt
374  doc/easytags.txt
... ...
@@ -0,0 +1,374 @@
  1
+*easytags.txt*  Automated tag generation and syntax highlighting in Vim
  2
+
  3
+Vim has long been my favorite text editor and combined with Exuberant Ctags
  4
+[1] it has the potential to provide most of what I expect from an integrated
  5
+development environment [2]. Exuberant Ctags is the latest incarnation of a
  6
+family of computer programs [3] that scan source code files to create an index
  7
+of identifiers (tags) and where they are defined. Vim uses this index (a
  8
+so-called tags file) to enable you to jump to the definition of any identifier
  9
+using the Control-] (see |CTRL-]|) mapping.
  10
+
  11
+When you're familiar with integrated development environments you may
  12
+recognize this feature as "Go-to definition". One advantage of the combination
  13
+of Vim and Exuberant Ctags over integrated development environments is that
  14
+Vim supports syntax highlighting for over 500 file types [4] (!) and Exuberant
  15
+Ctags can generate tags for over 40 file types [5] as well...
  16
+
  17
+There's just one problem: You have to manually keep your tags files up-to-date
  18
+and this turns out to be a royal pain in the ass! So I set out to write a Vim
  19
+plug-in that would do this boring work for me. When I finished the plug-in's
  20
+basic functionality (one automatic command and a call to |system()| later) I
  21
+became interested in dynamic syntax highlighting, so I added that as well to
  22
+see if it would work -- surprisingly well I'm happy to report!
  23
+
  24
+==============================================================================
  25
+Install & usage ~
  26
+
  27
+Unzip the most recent ZIP archive [6] file inside your Vim profile directory
  28
+(usually this is '~/.vim' on UNIX and '%USERPROFILE%\vimfiles' on Windows),
  29
+restart Vim and execute the command ':helptags ~/.vim/doc' (use ':helptags
  30
+~\vimfiles\doc' instead on Windows). Now try it out: Edit any file type
  31
+supported by Exuberant Ctags and within ten seconds the plug-in should
  32
+create/update your tags file ('~/.vimtags' on UNIX, '~/_vimtags' on Windows)
  33
+with the tags defined in the file you just edited! This means that whatever
  34
+file you're editing in Vim (as long as it's on the local file system), tags
  35
+will always be available by the time you need them!
  36
+
  37
+Additionally if the file you just opened is a C, C++, Objective-C, Java, Lua,
  38
+Python, PHP or Vim source file you should also notice that the function and
  39
+type names defined in the file have been syntax highlighted.
  40
+
  41
+The 'easytags.vim' plug-in is intended to work automatically once it's
  42
+installed, but if you want to change how it works there are several options
  43
+you can change and commands you can execute from your own mappings and/or
  44
+automatic commands. These are all documented below.
  45
+
  46
+Note that if the plug-in warns you 'ctags' isn't installed you'll have to
  47
+download it from its homepage [1], or if you're running Debian/Ubuntu you can
  48
+install it by executing the following shell command:
  49
+>
  50
+    $ sudo apt-get install exuberant-ctags
  51
+
  52
+------------------------------------------------------------------------------
  53
+If you're using Windows ~
  54
+
  55
+On Windows the |system()| function used by 'easytags.vim' causes a command
  56
+prompt window to pop up while Exuberant Ctags is executing. If this bothers
  57
+you then you can install my shell.vim [7] plug-in which includes a DLL [8]
  58
+that works around this issue. Once you've installed both plug-ins it should
  59
+work out of the box! Please let me know if this doesn't work for you.
  60
+
  61
+------------------------------------------------------------------------------
  62
+The *:UpdateTags* command
  63
+
  64
+This command executes Exuberant Ctags [1] from inside Vim to update the global
  65
+tags file defined by |g:easytags_file|. When no arguments are given the tags for
  66
+the current file are updated, otherwise the arguments are passed on to
  67
+'ctags'. For example when you execute the Vim command ':UpdateTags -R ~/.vim'
  68
+(or ':UpdateTags -R ~\vimfiles' on Windows) the plug-in will execute 'ctags -R
  69
+~/.vim' for you (with some additional arguments, see the troubleshooting
  70
+section ":HighlightTags only works for the tags file created by |:UpdateTags|"
  71
+for more information).
  72
+
  73
+When you execute this command like |:UpdateTags|! (including the bang!) then all
  74
+tags whose files are missing will be filtered from the global tags file.
  75
+
  76
+Note that this command will be executed automatically every once in a while,
  77
+assuming you haven't changed |g:easytags_on_cursorhold|.
  78
+
  79
+------------------------------------------------------------------------------
  80
+The *:HighlightTags* command
  81
+
  82
+When you execute this command while editing one of the supported file types
  83
+(see above) the relevant tags in the current file are highlighted. The tags to
  84
+highlight are gathered from all tags files known to Vim (through the |'tags'|
  85
+option).
  86
+
  87
+Note that this command will be executed automatically every once in a while,
  88
+assuming you haven't changed |g:easytags_on_cursorhold|.
  89
+
  90
+------------------------------------------------------------------------------
  91
+The *g:easytags_cmd* option
  92
+
  93
+The plug-in will try to determine the location where Exuberant Ctags is
  94
+installed on its own but this might not always work because any given
  95
+executable named 'ctags' in your '$PATH' might not in fact be Exuberant Ctags
  96
+but some older, more primitive 'ctags' implementation which doesn't support
  97
+the same command line options and thus breaks the 'easytags.vim' plug-in. If
  98
+this is the case you can set the global variable |g:easytags_cmd| to the
  99
+location where you've installed Exuberant Ctags, e.g.:
  100
+>
  101
+    :let g:easytags_cmd = '/usr/local/bin/ctags'
  102
+
  103
+------------------------------------------------------------------------------
  104
+The *g:easytags_file* option
  105
+
  106
+As mentioned above the plug-in will store your tags in '~/.vimtags' on UNIX
  107
+and '~/_vimtags' on Windows. To change the location of this file, set the
  108
+global variable |g:easytags_file|, e.g.:
  109
+>
  110
+    :let g:easytags_file = '~/.vim/tags'
  111
+
  112
+A leading '~' in the |g:easytags_file| variable is expanded to your current home
  113
+directory ('$HOME' on UNIX, '%USERPROFILE%' on Windows).
  114
+
  115
+------------------------------------------------------------------------------
  116
+The *g:easytags_always_enabled* option
  117
+
  118
+By default the plug-in automatically generates and highlights tags when you
  119
+stop typing for a few seconds (this works using the |CursorHold| automatic
  120
+command). This means that when you edit a file, the dynamic highlighting won't
  121
+appear until you pause for a moment. If you don't like this you can configure
  122
+the plug-in to always enable dynamic highlighting:
  123
+>
  124
+    :let g:easytags_always_enabled = 1
  125
+
  126
+Be warned that after setting this option you'll probably notice why it's
  127
+disabled by default: Every time you edit a file in Vim, the plug-in will first
  128
+run Exuberant Ctags and then highlight the tags, and this slows Vim down quite
  129
+a lot. I have some ideas on how to improve this latency by running Exuberant
  130
+Ctags in the background so stay tuned!
  131
+
  132
+Note: If you change this option it won't apply until you restart Vim, so
  133
+you'll have to set this option in your |vimrc| script.
  134
+
  135
+------------------------------------------------------------------------------
  136
+The *g:easytags_on_cursorhold* option
  137
+
  138
+As I explained above the plug-in by default doesn't update or highlight your
  139
+tags until you stop typing for a moment. The plug-in tries hard to do the
  140
+least amount of work possible in this break but it might still interrupt your
  141
+workflow. If it does you can disable the periodic update:
  142
+>
  143
+    :let g:easytags_on_cursorhold = 0
  144
+
  145
+Note: Like the |g:easytags_always_enabled| option, if you change this option it
  146
+won't apply until you restart Vim, so you'll have to set this option in your
  147
+|vimrc| script.
  148
+
  149
+------------------------------------------------------------------------------
  150
+The *g:easytags_autorecurse* option
  151
+
  152
+When the |:UpdateTags| command is executed automatically or without arguments,
  153
+it defaults to updating just the tags for the current file. If you'd rather
  154
+have it recursively scan everything below the directory of the current file
  155
+then set this option to true (1):
  156
+>
  157
+    :let g:easytags_autorecurse = 1
  158
+
  159
+You have to explicitly enable this option because it should only be used while
  160
+navigating around small directory trees. Imagine always having this option
  161
+enabled and then having to edit a file in e.g. the root of your home
  162
+directory: The 'easytags.vim' plug-in would freeze Vim for a long time while
  163
+you'd have to wait for Exuberant Cags to scan thousands of files...
  164
+
  165
+Note that when you enable this option the 'easytags.vim' plug-in might ignore
  166
+other options like |g:easytags_resolve_links|. This is an implementation detail
  167
+which I intend to fix.
  168
+
  169
+------------------------------------------------------------------------------
  170
+The *g:easytags_include_members* option
  171
+
  172
+Exuberant Ctags knows how to generate tags for struct/class members in C++ and
  173
+Java source code but doesn't do so by default because it can more than double
  174
+the size of your tags files, thus taking much longer to read/write the tags
  175
+file. When you enable the |g:easytags_include_members| option from your |vimrc|
  176
+script (before the 'easytags.vim' plug-in is loaded):
  177
+>
  178
+    :let g:easytags_include_members = 1
  179
+
  180
+Exuberant Ctags will be instructed to include struct/class members using the
  181
+'--extra=+q' command line argument and the 'easytags.vim' plug-in will
  182
+highlight them using the 'cMember' highlighting group. Because most color
  183
+schemes don't distinguish the Identifier and Type (see |group-name|)
  184
+highlighting groups all members will now probably look like type definitions.
  185
+You can change that by executing either of the following Vim commands (from
  186
+your vimrc script, a file type plug-in, etc.):
  187
+>
  188
+    " If you like one of the existing styles you can link them:
  189
+    highlight link cMember Special
  190
+>
  191
+    " You can also define your own style if you want:
  192
+    highlight cMember gui=italic
  193
+
  194
+------------------------------------------------------------------------------
  195
+The *g:easytags_resolve_links* option
  196
+
  197
+UNIX has symbolic links [9] and hard links [10], both of which conflict with
  198
+the concept of having one unique location for every identifier. With regards
  199
+to hard links there's not much anyone can do, but because I use symbolic links
  200
+quite a lot I've added this option. It's disabled by default since it has a
  201
+small performance impact and might not do what unknowing users expect it to:
  202
+When you enable this option the plug-in will resolve symbolic links in
  203
+pathnames, which means your tags file will only contain entries with canonical
  204
+pathnames [11]. To enable this option (which I strongly suggest doing when you
  205
+run UNIX and use symbolic links) execute the following Vim command:
  206
+>
  207
+    :let g:easytags_resolve_links = 1
  208
+
  209
+------------------------------------------------------------------------------
  210
+The *g:easytags_suppress_ctags_warning* option
  211
+
  212
+If this is set and not false, it will suppress the warning on startup if ctags
  213
+is not found or not recent enough.
  214
+>
  215
+    :let g:easytags_suppress_ctags_warning = 1
  216
+
  217
+------------------------------------------------------------------------------
  218
+How to customize the highlighting colors? ~
  219
+
  220
+The easytags plug-in defines new highlighting groups for dynamically
  221
+highlighted tags. These groups are linked to Vim's default groups so that
  222
+they're colored out of the box, but if you want you can change the styles. To
  223
+do so use a 'highlight' command such as the ones given a few paragraphs back.
  224
+Of course you'll need to change the group name. Here are the group names used
  225
+by the easytags plug-in:
  226
+
  227
+ * Lua: 'luaFuncTag'
  228
+ * C: 'cTypeTag', 'cEnumTag', 'cPreProcTag', 'cFunctionTag', 'cMemberTag'
  229
+ * PHP: 'phpFunctionsTag', 'phpClassesTag'
  230
+ * Vim: 'vimAutoGroupTag', 'vimCommandTag', 'vimFuncNameTag',
  231
+   'vimScriptFuncNameTag'
  232
+ * Python: 'pythonFunctionTag', 'pythonMethodTag', 'pythonClassTag'
  233
+ * Java: 'javaClassTag', 'javaMethodTag'
  234
+ * C#: 'csClassOrStructTag', 'csMethodTag'
  235
+
  236
+As you can see each of these names ends in 'Tag' to avoid conflicts with the
  237
+syntax modes shipped with Vim. And about the singular/plural confusion: I've
  238
+tried to match the existing highlighting groups defined by popular syntax
  239
+modes (except of course for the 'Tag' suffix).
  240
+
  241
+==============================================================================
  242
+Troubleshooting ~
  243
+
  244
+------------------------------------------------------------------------------
  245
+:HighlightTags only works for the tags file created by :UpdateTags ~
  246
+
  247
+If you want to create tags files and have their tags highlighted by the
  248
+'easytags.vim' plug-in then you'll have to create the tags file with certain
  249
+arguments to Exuberant Ctags:
  250
+>
  251
+    $ ctags --fields=+l --c-kinds=+p --c++-kinds=+p ...
  252
+
  253
+The '--fields=+l' argument makes sure that Exuberant Ctags includes a
  254
+'language:...' property with each entry in the tags file. This is required by
  255
+the |:HighlightTags| command so it can filter tags by their file type. The other
  256
+two arguments make sure Exuberant Ctags generates tags for function prototypes
  257
+in C/C++ source code.
  258
+
  259
+If you have the |g:easytags_include_members| option enabled (its off by default)
  260
+then you'll also need to add the '--extra=+q' argument so that Exuberant Ctags
  261
+generates tags for structure/class members.
  262
+
  263
+------------------------------------------------------------------------------
  264
+The plug-in complains that Exuberant Ctags isn't installed ~
  265
+
  266
+After a Mac OS X user found out the hard way that the 'ctags' executable isn't
  267
+always Exuberant Ctags and we spend a few hours debugging the problem I added
  268
+proper version detection: The plug-in executes 'ctags --version' when Vim is
  269
+started to verify that Exuberant Ctags 5.5 or newer is installed. If it isn't
  270
+Vim will show the following message on startup:
  271
+>
  272
+    easytags.vim: Plug-in not loaded because Exuberant Ctags isn't installed!
  273
+    Please download & install Exuberant Ctags from http://ctags.sf.net
  274
+
  275
+If the installed Exuberant Ctags version is too old the plug-in will complain:
  276
+>
  277
+    easytags.vim: Plug-in not loaded because Exuberant Ctags 5.5
  278
+    or newer is required while you have version %s installed!
  279
+
  280
+If you have the right version of Exuberant Ctags installed but the plug-in
  281
+still complains, try executing the following command from inside Vim:
  282
+>
  283
+    :!which ctags
  284
+
  285
+If this doesn't print the location where you installed Exuberant Ctags it
  286
+means your system already had a 'ctags' executable but it isn't compatible
  287
+with Exuberant Ctags 5.5 and you'll need to set the |g:easytags_cmd| option (see
  288
+above) so the plug-in knows which 'ctags' to run.
  289
+
  290
+------------------------------------------------------------------------------
  291
+Vim locks up while the plug-in is running ~
  292
+
  293
+Once or twice now in several years I've experienced Exuberant Ctags getting
  294
+into an infinite loop when given garbage input. In my case this happened by
  295
+accident a few days ago :-|. Because my plug-in executes 'ctags' in the
  296
+foreground this will block Vim indefinitely! If this happens you might be able
  297
+to kill 'ctags' by pressing Control-C (see |CTRL-C|) but if that doesn't work
  298
+you can also kill it without stopping Vim using a task manager or the 'pkill'
  299
+command (available on most UNIX systems):
  300
+>
  301
+    $ pkill -KILL ctags
  302
+
  303
+If Vim seems very slow and you suspect this plug-in might be the one to blame,
  304
+increase Vim's verbosity level:
  305
+>
  306
+    :set vbs=1
  307
+
  308
+Every time the plug-in executes it will time how long the execution takes and
  309
+add the results to Vim's message history, which you can view by executing the
  310
+|:messages| command.
  311
+
  312
+------------------------------------------------------------------------------
  313
+Failed to highlight tags because pattern is too big! ~
  314
+
  315
+If the 'easytags.vim' plug-in fails to highlight your tags and the error
  316
+message mentions that the pattern is too big, your tags file has grown too
  317
+large for Vim to be able to highlight all tagged identifiers! I've had this
  318
+happen to me with 50 KB patterns because I added most of the headers in
  319
+'/usr/include/' to my tags file. Internally Vim raises the error |E339|: Pattern
  320
+too long and unfortunately the only way to avoid this problem once it occurs
  321
+is to reduce the number of tagged identifiers...
  322
+
  323
+In my case the solution was to move most of the tags from '/usr/include/' over
  324
+to project specific tags files which are automatically loaded by Vim when I
  325
+edit files in different projects because I've set the |'tags'| option as
  326
+follows:
  327
+>
  328
+    :set tags=./.tags;,~/.vimtags
  329
+
  330
+Once you've executed the above command, Vim will automatically look for a file
  331
+named '.tags' in the directory of the current file. Because of the ';' Vim
  332
+also recurses upwards so that you can nest files arbitrarily deep under your
  333
+project directories.
  334
+
  335
+------------------------------------------------------------------------------
  336
+The plug-in doesn't seem to work in Cygwin [12] ~
  337
+
  338
+If you want to use the plug-in with Vim under Cygwin, you need to have the
  339
+Cygwin version of Ctags installed instead of the Windows version (thanks to
  340
+Alex Zuroff for reporting this!).
  341
+
  342
+==============================================================================
  343
+Contact ~
  344
+
  345
+If you have questions, bug reports, suggestions, etc. the author can be
  346
+contacted at peter@peterodding.com. The latest version is available at
  347
+http://peterodding.com/code/vim/easytags/ and http://github.com/xolox/vim-easytags.
  348
+If you like this plug-in please vote for it on Vim Online [13].
  349
+
  350
+==============================================================================
  351
+License ~
  352
+
  353
+This software is licensed under the MIT license [14].
  354
+Copyright 2010 Peter Odding <peter@peterodding.com>.
  355
+
  356
+==============================================================================
  357
+References ~
  358
+
  359
+[1] http://ctags.sourceforge.net/
  360
+[2] http://en.wikipedia.org/wiki/Integrated_development_environment
  361
+[3] http://en.wikipedia.org/wiki/Ctags
  362
+[4] http://ftp.vim.org/vim/runtime/syntax/
  363
+[5] http://ctags.sourceforge.net/languages.html
  364
+[6] http://peterodding.com/code/vim/downloads/easytags
  365
+[7] http://peterodding.com/code/vim/shell/
  366
+[8] http://en.wikipedia.org/wiki/Dynamic-link_library
  367
+[9] http://en.wikipedia.org/wiki/Symbolic_link
  368
+[10] http://en.wikipedia.org/wiki/Hard_link
  369
+[11] http://en.wikipedia.org/wiki/Canonicalization
  370
+[12] http://en.wikipedia.org/wiki/Cygwin
  371
+[13] http://www.vim.org/scripts/script.php?script_id=3114
  372
+[14] http://en.wikipedia.org/wiki/MIT_License
  373
+
  374
+vim: syntax=help nospell

0 notes on commit 6de3e06

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