Skip to content
This repository
Browse code

Improved README, added references to Vim documentation

  • Loading branch information...
commit 726c08bf946ba3cdabab23a63bb8892c19408a04 1 parent a6edd82
Peter Odding authored July 10, 2010

Showing 1 changed file with 37 additions and 28 deletions. Show diff stats Hide diff stats

  1. 65  README.md
65  README.md
Source Rendered
@@ -6,7 +6,7 @@ from an [integrated development environment] [ide]. Exuberant Ctags is the
6 6
 latest incarnation of a [family of computer programs] [ctags] that scan
7 7
 source code files to create an index of identifiers (tags) and where they are
8 8
 defined. Vim uses this index (a so-called tags file) to enable you to jump to
9  
-the definition of any identifier using the `Ctrl-]` mapping.
  9
+the definition of any identifier using the [Control-\]][jump_to_tag] mapping.
10 10
 
11 11
 When you're familiar with integrated development environments you may recognize
12 12
 this feature as "Go-to definition". One advantage of the combination of Vim and
@@ -17,9 +17,9 @@ Ctags can generate tags for [over 40 file types] [ctags_support] as well...
17 17
 There's just one problem: You have to manually keep your tags files up-to-date
18 18
 and this turns out to be a royal pain in the ass! So I set out to write a Vim
19 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()`) I became
21  
-interested in dynamic syntax highlighting, so I added that as well to see if it
22  
-would work -- surprisingly well I'm happy to report!
  20
+basic functionality (one automatic command and a call to [system()][system]
  21
+later) I became interested in dynamic syntax highlighting, so I added that as
  22
+well to see if it would work -- surprisingly well I'm happy to report!
23 23
 
24 24
 ## Install & first use
25 25
 
@@ -40,14 +40,14 @@ If the plug-in warns you that `ctags` isn't installed you can download it from
40 40
 its [homepage] [exuberant_ctags], or if you're running Debian/Ubuntu you can
41 41
 install it by executing the following shell command:
42 42
 
43  
-    sudo apt-get install exuberant-ctags
  43
+    $ sudo apt-get install exuberant-ctags
44 44
 
45 45
 ## Configuration
46 46
 
47 47
 The plug-in is intended to work without configuration but can be customized by
48 48
 changing the following options:
49 49
 
50  
-### The `easytags_cmd` option
  50
+### The `g:easytags_cmd` option
51 51
 
52 52
 The plug-in will try to determine the location where Exuberant Ctags is
53 53
 installed on its own but this might not always work because any given
@@ -59,36 +59,37 @@ where you've installed Exuberant Ctags, e.g.:
59 59
 
60 60
     :let g:easytags_cmd = '/usr/local/bin/ctags'
61 61
 
62  
-### The `easytags_file` option
  62
+### The `g:easytags_file` option
63 63
 
64 64
 As mentioned above the plug-in will store your tags in `~/.vimtags` on UNIX and
65 65
 `~/_vimtags` on Windows. To change the location of this file, set the global
66  
-variable `easytags_file`, e.g.:
  66
+variable `g:easytags_file`, e.g.:
67 67
 
68 68
     :let g:easytags_file = '~/.vim/tags'
69 69
 
70  
-A leading `~` in the `easytags_file` variable is expanded to your current home
  70
+A leading `~` in the `g:easytags_file` variable is expanded to your current home
71 71
 directory (`$HOME` on UNIX, `%USERPROFILE%` on Windows).
72 72
 
73  
-### The `easytags_always_enabled` option
  73
+### The `g:easytags_always_enabled` option
74 74
 
75 75
 By default the plug-in automatically generates and highlights tags when you
76  
-stop typing for a few seconds. This means that when you edit a file, the
77  
-dynamic highlighting won't appear until you pause for a moment. If you don't
78  
-want this you can configure the plug-in to always enable dynamic highlighting:
  76
+stop typing for a few seconds (this works using the [CursorHold][cursorhold]
  77
+automatic command). This means that when you edit a file, the dynamic
  78
+highlighting won't appear until you pause for a moment. If you don't like this
  79
+you can configure the plug-in to always enable dynamic highlighting:
79 80
 
80 81
     :let g:easytags_always_enabled = 1
81 82
 
82 83
 Be warned that after setting this option you'll probably notice why it's
83 84
 disabled by default: Every time you edit a file in Vim, the plug-in will first
84  
-run Exuberant Ctags and then highlight the tags, which slows Vim down quite a
85  
-lot. I have some ideas on how to improve this latency by executing Exuberant
86  
-Ctags in the background, so stay tuned!
  85
+run Exuberant Ctags and then highlight the tags, and this slows Vim down quite
  86
+a lot. I have some ideas on how to improve this latency by running Exuberant
  87
+Ctags in the background (see my [shell.vim][shell] plug-in) so stay tuned!
87 88
 
88 89
 Note: If you change this option it won't apply until you restart Vim, so you'll
89  
-have to set this option in your `~/.vimrc` script (`~/_vimrc` on Windows).
  90
+have to set this option in your [vimrc script][vimrc].
90 91
 
91  
-### The `easytags_on_cursorhold` option
  92
+### The `g:easytags_on_cursorhold` option
92 93
 
93 94
 As I explained above the plug-in by default doesn't update or highlight your
94 95
 tags until you stop typing for a moment. The plug-in tries hard to do the least
@@ -96,12 +97,12 @@ amount of work possible in this break but it might still interrupt your
96 97
 workflow. If it does you can disable the periodic update:
97 98
 
98 99
     :let g:easytags_on_cursorhold = 0
99  
-    
100  
-Note: Like the `easytags_always_enabled` option, if you change this option it
101  
-won't apply until you restart Vim, so you'll have to set this option in your
102  
-`~/.vimrc` script (`~/_vimrc` on Windows).
103 100
 
104  
-### The `easytags_resolve_links` option
  101
+Note: Like the `g:easytags_always_enabled` option, if you change this option it
  102
+won't apply until you restart Vim, so you'll have to set this option in
  103
+your [vimrc script][vimrc].
  104
+
  105
+### The `g:easytags_resolve_links` option
105 106
 
106 107
 UNIX has [symbolic links] [symlinks] and [hard links] [hardlinks], both of
107 108
 which conflict with the concept of having one unique location for every
@@ -150,10 +151,11 @@ Once or twice now in several years I've experienced Exuberant Ctags getting
150 151
 into an infinite loop when given garbage input. In my case this happened by
151 152
 accident a few days ago :-|. Because my plug-in executes `ctags` in the
152 153
 foreground this will block Vim indefinitely! If this happens you might be
153  
-able to kill `ctags` by pressing `Ctrl-C` but if that doesn't work you can also
154  
-kill it without stopping Vim using a task manager or the `pkill` command:
  154
+able to kill `ctags` by pressing [Control-C][control_c] but if that doesn't
  155
+work you can also kill it without stopping Vim using a task manager or the
  156
+`pkill` command:
155 157
 
156  
-    pkill -KILL ctags
  158
+    $ pkill -KILL ctags
157 159
 
158 160
 If Vim seems very slow and you suspect this plug-in might be the one to blame,
159 161
 increase Vim's verbosity level:
@@ -162,13 +164,13 @@ increase Vim's verbosity level:
162 164
 
163 165
 Every time the plug-in executes it will time how long the execution takes and
164 166
 add the results to Vim's message history, which you can view by executing the
165  
-`:messages` command.
  167
+[:messages][messages] command.
166 168
 
167 169
 ## Contact
168 170
 
169 171
 If you have questions, bug reports, suggestions, etc. the author can be
170 172
 contacted at <peter@peterodding.com>. The latest version is available at
171  
-<http://peterodding.com/code/vim/easytags> and
  173
+<http://peterodding.com/code/vim/easytags/> and
172 174
 <http://github.com/xolox/vim-easytags>. If you like this plug-in please vote
173 175
 for it on [www.vim.org] [vim_scripts_entry].
174 176
 
@@ -179,14 +181,21 @@ This software is licensed under the [MIT license] [mit_license].
179 181
 
180 182
 
181 183
 [canon]: http://en.wikipedia.org/wiki/Canonicalization
  184
+[control_c]: http://vimdoc.sourceforge.net/htmldoc/pattern.html#CTRL-C
182 185
 [ctags]: http://en.wikipedia.org/wiki/Ctags
183 186
 [ctags_support]: http://ctags.sourceforge.net/languages.html
  187
+[cursorhold]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#CursorHold
184 188
 [exuberant_ctags]: http://ctags.sourceforge.net/
185 189
 [hardlinks]: http://en.wikipedia.org/wiki/Hard_link
186 190
 [ide]: http://en.wikipedia.org/wiki/Integrated_development_environment
  191
+[jump_to_tag]: http://vimdoc.sourceforge.net/htmldoc/tagsrch.html#CTRL-]
187 192
 [latest_zip]: http://peterodding.com/code/vim/downloads/easytags
  193
+[messages]: http://vimdoc.sourceforge.net/htmldoc/message.html#:messages
188 194
 [mit_license]: http://en.wikipedia.org/wiki/MIT_License
  195
+[shell]: http://peterodding.com/code/vim/shell/
189 196
 [symlinks]: http://en.wikipedia.org/wiki/Symbolic_link
  197
+[system]: http://vimdoc.sourceforge.net/htmldoc/eval.html#system()
190 198
 [vim]: http://www.vim.org/
191 199
 [vim_scripts_entry]: http://www.vim.org/scripts/script.php?script_id=3114
192 200
 [vim_support]: http://ftp.vim.org/vim/runtime/syntax/
  201
+[vimrc]: http://vimdoc.sourceforge.net/htmldoc/starting.html#vimrc

0 notes on commit 726c08b

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