]> git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/taglist.txt
6a62b39635730f372e33fd9300f62f15f10d2754
[rbdr/dotfiles] / vim / doc / taglist.txt
1 *taglist.txt* Plugin for browsing source code
2
3 Author: Yegappan Lakshmanan (yegappan AT yahoo DOT com)
4 For Vim version 6.0 and above
5 Last change: 2007 May 24
6
7 1. Overview |taglist-intro|
8 2. Taglist on the internet |taglist-internet|
9 3. Requirements |taglist-requirements|
10 4. Installation |taglist-install|
11 5. Usage |taglist-using|
12 6. Options |taglist-options|
13 7. Commands |taglist-commands|
14 8. Global functions |taglist-functions|
15 9. Extending |taglist-extend|
16 10. FAQ |taglist-faq|
17 11. License |taglist-license|
18 12. Todo |taglist-todo|
19
20 ==============================================================================
21 *taglist-intro*
22 1. Overview~
23
24 The "Tag List" plugin is a source code browser plugin for Vim. This plugin
25 allows you to efficiently browse through source code files for different
26 programming languages. The "Tag List" plugin provides the following features:
27
28 * Displays the tags (functions, classes, structures, variables, etc.)
29 defined in a file in a vertically or horizontally split Vim window.
30 * In GUI Vim, optionally displays the tags in the Tags drop-down menu and
31 in the popup menu.
32 * Automatically updates the taglist window as you switch between
33 files/buffers. As you open new files, the tags defined in the new files
34 are added to the existing file list and the tags defined in all the
35 files are displayed grouped by the filename.
36 * When a tag name is selected from the taglist window, positions the
37 cursor at the definition of the tag in the source file.
38 * Automatically highlights the current tag name.
39 * Groups the tags by their type and displays them in a foldable tree.
40 * Can display the prototype and scope of a tag.
41 * Can optionally display the tag prototype instead of the tag name in the
42 taglist window.
43 * The tag list can be sorted either by name or by chronological order.
44 * Supports the following language files: Assembly, ASP, Awk, Beta, C,
45 C++, C#, Cobol, Eiffel, Erlang, Fortran, HTML, Java, Javascript, Lisp,
46 Lua, Make, Pascal, Perl, PHP, Python, Rexx, Ruby, Scheme, Shell, Slang,
47 SML, Sql, TCL, Verilog, Vim and Yacc.
48 * Can be easily extended to support new languages. Support for
49 existing languages can be modified easily.
50 * Provides functions to display the current tag name in the Vim status
51 line or the window title bar.
52 * The list of tags and files in the taglist can be saved and
53 restored across Vim sessions.
54 * Provides commands to get the name and prototype of the current tag.
55 * Runs in both console/terminal and GUI versions of Vim.
56 * Works with the winmanager plugin. Using the winmanager plugin, you
57 can use Vim plugins like the file explorer, buffer explorer and the
58 taglist plugin at the same time like an IDE.
59 * Can be used in both Unix and MS-Windows systems.
60
61 ==============================================================================
62 *taglist-internet*
63 2. Taglist on the internet~
64
65 The home page of the taglist plugin is at:
66 >
67 http://vim-taglist.sourceforge.net/
68 <
69 You can subscribe to the taglist mailing list to post your questions or
70 suggestions for improvement or to send bug reports. Visit the following page
71 for subscribing to the mailing list:
72 >
73 http://groups.yahoo.com/group/taglist
74 <
75 ==============================================================================
76 *taglist-requirements*
77 3. Requirements~
78
79 The taglist plugin requires the following:
80
81 * Vim version 6.0 and above
82 * Exuberant ctags 5.0 and above
83
84 The taglist plugin will work on all the platforms where the exuberant ctags
85 utility and Vim are supported (this includes MS-Windows and Unix based
86 systems).
87
88 The taglist plugin relies on the exuberant ctags utility to dynamically
89 generate the tag listing. The exuberant ctags utility must be installed in
90 your system to use this plugin. The exuberant ctags utility is shipped with
91 most of the Linux distributions. You can download the exuberant ctags utility
92 from
93 >
94 http://ctags.sourceforge.net
95 <
96 The taglist plugin doesn't use or create a tags file and there is no need to
97 create a tags file to use this plugin. The taglist plugin will not work with
98 the GNU ctags or the Unix ctags utility.
99
100 This plugin relies on the Vim "filetype" detection mechanism to determine the
101 type of the current file. You have to turn on the Vim filetype detection by
102 adding the following line to your .vimrc file:
103 >
104 filetype on
105 <
106 The taglist plugin will not work if you run Vim in the restricted mode (using
107 the -Z command-line argument).
108
109 The taglist plugin uses the Vim system() function to invoke the exuberant
110 ctags utility. If Vim is compiled without the system() function then you
111 cannot use the taglist plugin. Some of the Linux distributions (Suse) compile
112 Vim without the system() function for security reasons.
113
114 ==============================================================================
115 *taglist-install*
116 4. Installation~
117
118 1. Download the taglist.zip file and unzip the files to the $HOME/.vim or the
119 $HOME/vimfiles or the $VIM/vimfiles directory. After this step, you should
120 have the following two files (the directory structure should be preserved):
121
122 plugin/taglist.vim - main taglist plugin file
123 doc/taglist.txt - documentation (help) file
124
125 Refer to the |add-plugin|and |'runtimepath'| Vim help pages for more
126 details about installing Vim plugins.
127 2. Change to the $HOME/.vim/doc or $HOME/vimfiles/doc or $VIM/vimfiles/doc
128 directory, start Vim and run the ":helptags ." command to process the
129 taglist help file. Without this step, you cannot jump to the taglist help
130 topics.
131 3. If the exuberant ctags utility is not present in one of the directories in
132 the PATH environment variable, then set the 'Tlist_Ctags_Cmd' variable to
133 point to the location of the exuberant ctags utility (not to the directory)
134 in the .vimrc file.
135 4. If you are running a terminal/console version of Vim and the terminal
136 doesn't support changing the window width then set the
137 'Tlist_Inc_Winwidth' variable to 0 in the .vimrc file.
138 5. Restart Vim.
139 6. You can now use the ":TlistToggle" command to open/close the taglist
140 window. You can use the ":help taglist" command to get more information
141 about using the taglist plugin.
142
143 To uninstall the taglist plugin, remove the plugin/taglist.vim and
144 doc/taglist.txt files from the $HOME/.vim or $HOME/vimfiles directory.
145
146 ==============================================================================
147 *taglist-using*
148 5. Usage~
149
150 The taglist plugin can be used in several different ways.
151
152 1. You can keep the taglist window open during the entire editing session. On
153 opening the taglist window, the tags defined in all the files in the Vim
154 buffer list will be displayed in the taglist window. As you edit files, the
155 tags defined in them will be added to the taglist window. You can select a
156 tag from the taglist window and jump to it. The current tag will be
157 highlighted in the taglist window. You can close the taglist window when
158 you no longer need the window.
159 2. You can configure the taglist plugin to process the tags defined in all the
160 edited files always. In this configuration, even if the taglist window is
161 closed and the taglist menu is not displayed, the taglist plugin will
162 processes the tags defined in newly edited files. You can then open the
163 taglist window only when you need to select a tag and then automatically
164 close the taglist window after selecting the tag.
165 3. You can configure the taglist plugin to display only the tags defined in
166 the current file in the taglist window. By default, the taglist plugin
167 displays the tags defined in all the files in the Vim buffer list. As you
168 switch between files, the taglist window will be refreshed to display only
169 the tags defined in the current file.
170 4. In GUI Vim, you can use the Tags pull-down and popup menu created by the
171 taglist plugin to display the tags defined in the current file and select a
172 tag to jump to it. You can use the menu without opening the taglist window.
173 By default, the Tags menu is disabled.
174 5. You can configure the taglist plugin to display the name of the current tag
175 in the Vim window status line or in the Vim window title bar. For this to
176 work without the taglist window or menu, you need to configure the taglist
177 plugin to process the tags defined in a file always.
178 6. You can save the tags defined in multiple files to a taglist session file
179 and load it when needed. You can also configure the taglist plugin to not
180 update the taglist window when editing new files. You can then manually add
181 files to the taglist window.
182
183 Opening the taglist window~
184 You can open the taglist window using the ":TlistOpen" or the ":TlistToggle"
185 commands. The ":TlistOpen" command opens the taglist window and jumps to it.
186 The ":TlistToggle" command opens or closes (toggle) the taglist window and the
187 cursor remains in the current window. If the 'Tlist_GainFocus_On_ToggleOpen'
188 variable is set to 1, then the ":TlistToggle" command opens the taglist window
189 and moves the cursor to the taglist window.
190
191 You can map a key to invoke these commands. For example, the following command
192 creates a normal mode mapping for the <F8> key to toggle the taglist window.
193 >
194 nnoremap <silent> <F8> :TlistToggle<CR>
195 <
196 Add the above mapping to your ~/.vimrc or $HOME/_vimrc file.
197
198 To automatically open the taglist window on Vim startup, set the
199 'Tlist_Auto_Open' variable to 1.
200
201 You can also open the taglist window on startup using the following command
202 line:
203 >
204 $ vim +TlistOpen
205 <
206 Closing the taglist window~
207 You can close the taglist window from the taglist window by pressing 'q' or
208 using the Vim ":q" command. You can also use any of the Vim window commands to
209 close the taglist window. Invoking the ":TlistToggle" command when the taglist
210 window is opened, closes the taglist window. You can also use the
211 ":TlistClose" command to close the taglist window.
212
213 To automatically close the taglist window when a tag or file is selected, you
214 can set the 'Tlist_Close_On_Select' variable to 1. To exit Vim when only the
215 taglist window is present, set the 'Tlist_Exit_OnlyWindow' variable to 1.
216
217 Jumping to a tag or a file~
218 You can select a tag in the taglist window either by pressing the <Enter> key
219 or by double clicking the tag name using the mouse. To jump to a tag on a
220 single mouse click set the 'Tlist_Use_SingleClick' variable to 1.
221
222 If the selected file is already opened in a window, then the cursor is moved
223 to that window. If the file is not currently opened in a window then the file
224 is opened in the window used by the taglist plugin to show the previously
225 selected file. If there are no usable windows, then the file is opened in a
226 new window. The file is not opened in special windows like the quickfix
227 window, preview window and windows containing buffer with the 'buftype' option
228 set.
229
230 To jump to the tag in a new window, press the 'o' key. To open the file in the
231 previous window (Ctrl-W_p) use the 'P' key. You can press the 'p' key to jump
232 to the tag but still keep the cursor in the taglist window (preview).
233
234 To open the selected file in a tab, use the 't' key. If the file is already
235 present in a tab then the cursor is moved to that tab otherwise the file is
236 opened in a new tab. To jump to a tag in a new tab press Ctrl-t. The taglist
237 window is automatically opened in the newly created tab.
238
239 Instead of jumping to a tag, you can open a file by pressing the <Enter> key
240 or by double clicking the file name using the mouse.
241
242 In the taglist window, you can use the [[ or <Backspace> key to jump to the
243 beginning of the previous file. You can use the ]] or <Tab> key to jump to the
244 beginning of the next file. When you reach the first or last file, the search
245 wraps around and the jumps to the next/previous file.
246
247 Highlighting the current tag~
248 The taglist plugin automatically highlights the name of the current tag in the
249 taglist window. The Vim |CursorHold| autocmd event is used for this. If the
250 current tag name is not visible in the taglist window, then the taglist window
251 contents are scrolled to make that tag name visible. You can also use the
252 ":TlistHighlightTag" command to force the highlighting of the current tag.
253
254 The tag name is highlighted if no activity is performed for |'updatetime'|
255 milliseconds. The default value for this Vim option is 4 seconds. To avoid
256 unexpected problems, you should not set the |'updatetime'| option to a very
257 low value.
258
259 To disable the automatic highlighting of the current tag name in the taglist
260 window, set the 'Tlist_Auto_Highlight_Tag' variable to zero.
261
262 When entering a Vim buffer/window, the taglist plugin automatically highlights
263 the current tag in that buffer/window. If you like to disable the automatic
264 highlighting of the current tag when entering a buffer, set the
265 'Tlist_Highlight_Tag_On_BufEnter' variable to zero.
266
267 Adding files to the taglist~
268 When the taglist window is opened, all the files in the Vim buffer list are
269 processed and the supported files are added to the taglist. When you edit a
270 file in Vim, the taglist plugin automatically processes this file and adds it
271 to the taglist. If you close the taglist window, the tag information in the
272 taglist is retained.
273
274 To process files even when the taglist window is not open, set the
275 'Tlist_Process_File_Always' variable to 1.
276
277 You can manually add multiple files to the taglist without opening them using
278 the ":TlistAddFiles" and the ":TlistAddFilesRecursive" commands.
279
280 For example, to add all the C files in the /my/project/dir directory to the
281 taglist, you can use the following command:
282 >
283 :TlistAddFiles /my/project/dir/*.c
284 <
285 Note that when adding several files with a large number of tags or a large
286 number of files, it will take several seconds to several minutes for the
287 taglist plugin to process all the files. You should not interrupt the taglist
288 plugin by pressing <CTRL-C>.
289
290 You can recursively add multiple files from a directory tree using the
291 ":TlistAddFilesRecursive" command:
292 >
293 :TlistAddFilesRecursive /my/project/dir *.c
294 <
295 This command takes two arguments. The first argument specifies the directory
296 from which to recursively add the files. The second optional argument
297 specifies the wildcard matching pattern for selecting the files to add. The
298 default pattern is * and all the files are added.
299
300 Displaying tags for only one file~
301 The taglist window displays the tags for all the files in the Vim buffer list
302 and all the manually added files. To display the tags for only the current
303 active buffer, set the 'Tlist_Show_One_File' variable to 1.
304
305 Removing files from the taglist~
306 You can remove a file from the taglist window, by pressing the 'd' key when the
307 cursor is on one of the tags listed for the file in the taglist window. The
308 removed file will no longer be displayed in the taglist window in the current
309 Vim session. To again display the tags for the file, open the file in a Vim
310 window and then use the ":TlistUpdate" command or use ":TlistAddFiles" command
311 to add the file to the taglist.
312
313 When a buffer is removed from the Vim buffer list using the ":bdelete" or the
314 ":bwipeout" command, the taglist is updated to remove the stored information
315 for this buffer.
316
317 Updating the tags displayed for a file~
318 The taglist plugin keeps track of the modification time of a file. When the
319 modification time changes (the file is modified), the taglist plugin
320 automatically updates the tags listed for that file. The modification time of
321 a file is checked when you enter a window containing that file or when you
322 load that file.
323
324 You can also update or refresh the tags displayed for a file by pressing the
325 "u" key in the taglist window. If an existing file is modified, after the file
326 is saved, the taglist plugin automatically updates the tags displayed for the
327 file.
328
329 You can also use the ":TlistUpdate" command to update the tags for the current
330 buffer after you made some changes to it. You should save the modified buffer
331 before you update the taglist window. Otherwise the listed tags will not
332 include the new tags created in the buffer.
333
334 If you have deleted the tags displayed for a file in the taglist window using
335 the 'd' key, you can again display the tags for that file using the
336 ":TlistUpdate" command.
337
338 Controlling the taglist updates~
339 To disable the automatic processing of new files or modified files, you can
340 set the 'Tlist_Auto_Update' variable to zero. When this variable is set to
341 zero, the taglist is updated only when you use the ":TlistUpdate" command or
342 the ":TlistAddFiles" or the ":TlistAddFilesRecursive" commands. You can use
343 this option to control which files are added to the taglist.
344
345 You can use the ":TlistLock" command to lock the taglist contents. After this
346 command is executed, new files are not automatically added to the taglist.
347 When the taglist is locked, you can use the ":TlistUpdate" command to add the
348 current file or the ":TlistAddFiles" or ":TlistAddFilesRecursive" commands to
349 add new files to the taglist. To unlock the taglist, use the ":TlistUnlock"
350 command.
351
352 Displaying the tag prototype~
353 To display the prototype of the tag under the cursor in the taglist window,
354 press the space bar. If you place the cursor on a tag name in the taglist
355 window, then the tag prototype is displayed at the Vim status line after
356 |'updatetime'| milliseconds. The default value for the |'updatetime'| Vim
357 option is 4 seconds.
358
359 You can get the name and prototype of a tag without opening the taglist window
360 and the taglist menu using the ":TlistShowTag" and the ":TlistShowPrototype"
361 commands. These commands will work only if the current file is already present
362 in the taglist. To use these commands without opening the taglist window, set
363 the 'Tlist_Process_File_Always' variable to 1.
364
365 You can use the ":TlistShowTag" command to display the name of the tag at or
366 before the specified line number in the specified file. If the file name and
367 line number are not supplied, then this command will display the name of the
368 current tag. For example,
369 >
370 :TlistShowTag
371 :TlistShowTag myfile.java 100
372 <
373 You can use the ":TlistShowPrototype" command to display the prototype of the
374 tag at or before the specified line number in the specified file. If the file
375 name and the line number are not supplied, then this command will display the
376 prototype of the current tag. For example,
377 >
378 :TlistShowPrototype
379 :TlistShowPrototype myfile.c 50
380 <
381 In the taglist window, when the mouse is moved over a tag name, the tag
382 prototype is displayed in a balloon. This works only in GUI versions where
383 balloon evaluation is supported.
384
385 Taglist window contents~
386 The taglist window contains the tags defined in various files in the taglist
387 grouped by the filename and by the tag type (variable, function, class, etc.).
388 For tags with scope information (like class members, structures inside
389 structures, etc.), the scope information is displayed in square brackets "[]"
390 after the tag name.
391
392 The contents of the taglist buffer/window are managed by the taglist plugin.
393 The |'filetype'| for the taglist buffer is set to 'taglist'. The Vim
394 |'modifiable'| option is turned off for the taglist buffer. You should not
395 manually edit the taglist buffer, by setting the |'modifiable'| flag. If you
396 manually edit the taglist buffer contents, then the taglist plugin will be out
397 of sync with the taglist buffer contents and the plugin will no longer work
398 correctly. To redisplay the taglist buffer contents again, close the taglist
399 window and reopen it.
400
401 Opening and closing the tag and file tree~
402 In the taglist window, the tag names are displayed as a foldable tree using
403 the Vim folding support. You can collapse the tree using the '-' key or using
404 the Vim |zc| fold command. You can open the tree using the '+' key or using
405 the Vim |zo| fold command. You can open all the folds using the '*' key or
406 using the Vim |zR| fold command. You can also use the mouse to open/close the
407 folds. You can close all the folds using the '=' key. You should not manually
408 create or delete the folds in the taglist window.
409
410 To automatically close the fold for the inactive files/buffers and open only
411 the fold for the current buffer in the taglist window, set the
412 'Tlist_File_Fold_Auto_Close' variable to 1.
413
414 Sorting the tags for a file~
415 The tags displayed in the taglist window can be sorted either by their name or
416 by their chronological order. The default sorting method is by the order in
417 which the tags appear in a file. You can change the default sort method by
418 setting the 'Tlist_Sort_Type' variable to either "name" or "order". You can
419 sort the tags by their name by pressing the "s" key in the taglist window. You
420 can again sort the tags by their chronological order using the "s" key. Each
421 file in the taglist window can be sorted using different order.
422
423 Zooming in and out of the taglist window~
424 You can press the 'x' key in the taglist window to maximize the taglist
425 window width/height. The window will be maximized to the maximum possible
426 width/height without closing the other existing windows. You can again press
427 'x' to restore the taglist window to the default width/height.
428
429 *taglist-session*
430 Taglist Session~
431 A taglist session refers to the group of files and their tags stored in the
432 taglist in a Vim session.
433
434 You can save and restore a taglist session (and all the displayed tags) using
435 the ":TlistSessionSave" and ":TlistSessionLoad" commands.
436
437 To save the information about the tags and files in the taglist to a file, use
438 the ":TlistSessionSave" command and specify the filename:
439 >
440 :TlistSessionSave <file name>
441 <
442 To load a saved taglist session, use the ":TlistSessionLoad" command: >
443
444 :TlistSessionLoad <file name>
445 <
446 When you load a taglist session file, the tags stored in the file will be
447 added to the tags already stored in the taglist.
448
449 The taglist session feature can be used to save the tags for large files or a
450 group of frequently used files (like a project). By using the taglist session
451 file, you can minimize the amount to time it takes to load/refresh the taglist
452 for multiple files.
453
454 You can create more than one taglist session file for multiple groups of
455 files.
456
457 Displaying the tag name in the Vim status line or the window title bar~
458 You can use the Tlist_Get_Tagname_By_Line() function provided by the taglist
459 plugin to display the current tag name in the Vim status line or the window
460 title bar. Similarly, you can use the Tlist_Get_Tag_Prototype_By_Line()
461 function to display the current tag prototype in the Vim status line or the
462 window title bar.
463
464 For example, the following command can be used to display the current tag name
465 in the status line:
466 >
467 :set statusline=%<%f%=%([%{Tlist_Get_Tagname_By_Line()}]%)
468 <
469 The following command can be used to display the current tag name in the
470 window title bar:
471 >
472 :set title titlestring=%<%f\ %([%{Tlist_Get_Tagname_By_Line()}]%)
473 <
474 Note that the current tag name can be displayed only after the file is
475 processed by the taglist plugin. For this, you have to either set the
476 'Tlist_Process_File_Always' variable to 1 or open the taglist window or use
477 the taglist menu. For more information about configuring the Vim status line,
478 refer to the documentation for the Vim |'statusline'| option.
479
480 Changing the taglist window highlighting~
481 The following Vim highlight groups are defined and used to highlight the
482 various entities in the taglist window:
483
484 TagListTagName - Used for tag names
485 TagListTagScope - Used for tag scope
486 TagListTitle - Used for tag titles
487 TagListComment - Used for comments
488 TagListFileName - Used for filenames
489
490 By default, these highlight groups are linked to the standard Vim highlight
491 groups. If you want to change the colors used for these highlight groups,
492 prefix the highlight group name with 'My' and define it in your .vimrc or
493 .gvimrc file: MyTagListTagName, MyTagListTagScope, MyTagListTitle,
494 MyTagListComment and MyTagListFileName. For example, to change the colors
495 used for tag names, you can use the following command:
496 >
497 :highlight MyTagListTagName guifg=blue ctermfg=blue
498 <
499 Controlling the taglist window~
500 To use a horizontally split taglist window, instead of a vertically split
501 window, set the 'Tlist_Use_Horiz_Window' variable to 1.
502
503 To use a vertically split taglist window on the rightmost side of the Vim
504 window, set the 'Tlist_Use_Right_Window' variable to 1.
505
506 You can specify the width of the vertically split taglist window, by setting
507 the 'Tlist_WinWidth' variable. You can specify the height of the horizontally
508 split taglist window, by setting the 'Tlist_WinHeight' variable.
509
510 When opening a vertically split taglist window, the Vim window width is
511 increased to accommodate the new taglist window. When the taglist window is
512 closed, the Vim window is reduced. To disable this, set the
513 'Tlist_Inc_Winwidth' variable to zero.
514
515 To reduce the number of empty lines in the taglist window, set the
516 'Tlist_Compact_Format' variable to 1.
517
518 To not display the Vim fold column in the taglist window, set the
519 'Tlist_Enable_Fold_Column' variable to zero.
520
521 To display the tag prototypes instead of the tag names in the taglist window,
522 set the 'Tlist_Display_Prototype' variable to 1.
523
524 To not display the scope of the tags next to the tag names, set the
525 'Tlist_Display_Tag_Scope' variable to zero.
526
527 *taglist-keys*
528 Taglist window key list~
529 The following table lists the description of the keys that can be used
530 in the taglist window.
531
532 Key Description~
533
534 <CR> Jump to the location where the tag under cursor is
535 defined.
536 o Jump to the location where the tag under cursor is
537 defined in a new window.
538 P Jump to the tag in the previous (Ctrl-W_p) window.
539 p Display the tag definition in the file window and
540 keep the cursor in the taglist window itself.
541 t Jump to the tag in a new tab. If the file is already
542 opened in a tab, move to that tab.
543 Ctrl-t Jump to the tag in a new tab.
544 <Space> Display the prototype of the tag under the cursor.
545 For file names, display the full path to the file,
546 file type and the number of tags. For tag types, display the
547 tag type and the number of tags.
548 u Update the tags listed in the taglist window
549 s Change the sort order of the tags (by name or by order)
550 d Remove the tags for the file under the cursor
551 x Zoom-in or Zoom-out the taglist window
552 + Open a fold
553 - Close a fold
554 * Open all folds
555 = Close all folds
556 [[ Jump to the beginning of the previous file
557 <Backspace> Jump to the beginning of the previous file
558 ]] Jump to the beginning of the next file
559 <Tab> Jump to the beginning of the next file
560 q Close the taglist window
561 <F1> Display help
562
563 The above keys will work in both the normal mode and the insert mode.
564
565 *taglist-menu*
566 Taglist menu~
567 When using GUI Vim, the taglist plugin can display the tags defined in the
568 current file in the drop-down menu and the popup menu. By default, this
569 feature is turned off. To turn on this feature, set the 'Tlist_Show_Menu'
570 variable to 1.
571
572 You can jump to a tag by selecting the tag name from the menu. You can use the
573 taglist menu independent of the taglist window i.e. you don't need to open the
574 taglist window to get the taglist menu.
575
576 When you switch between files/buffers, the taglist menu is automatically
577 updated to display the tags defined in the current file/buffer.
578
579 The tags are grouped by their type (variables, functions, classes, methods,
580 etc.) and displayed as a separate sub-menu for each type. If all the tags
581 defined in a file are of the same type (e.g. functions), then the sub-menu is
582 not used.
583
584 If the number of items in a tag type submenu exceeds the value specified by
585 the 'Tlist_Max_Submenu_Items' variable, then the submenu will be split into
586 multiple submenus. The default setting for 'Tlist_Max_Submenu_Items' is 25.
587 The first and last tag names in the submenu are used to form the submenu name.
588 The menu items are prefixed by alpha-numeric characters for easy selection by
589 keyboard.
590
591 If the popup menu support is enabled (the |'mousemodel'| option contains
592 "popup"), then the tags menu is added to the popup menu. You can access
593 the popup menu by right clicking on the GUI window.
594
595 You can regenerate the tags menu by selecting the 'Tags->Refresh menu' entry.
596 You can sort the tags listed in the menu either by name or by order by
597 selecting the 'Tags->Sort menu by->Name/Order' menu entry.
598
599 You can tear-off the Tags menu and keep it on the side of the Vim window
600 for quickly locating the tags.
601
602 Using the taglist plugin with the winmanager plugin~
603 You can use the taglist plugin with the winmanager plugin. This will allow you
604 to use the file explorer, buffer explorer and the taglist plugin at the same
605 time in different windows. To use the taglist plugin with the winmanager
606 plugin, set 'TagList' in the 'winManagerWindowLayout' variable. For example,
607 to use the file explorer plugin and the taglist plugin at the same time, use
608 the following setting: >
609
610 let winManagerWindowLayout = 'FileExplorer|TagList'
611 <
612 Getting help~
613 If you have installed the taglist help file (this file), then you can use the
614 Vim ":help taglist-<keyword>" command to get help on the various taglist
615 topics.
616
617 You can press the <F1> key in the taglist window to display the help
618 information about using the taglist window. If you again press the <F1> key,
619 the help information is removed from the taglist window.
620
621 *taglist-debug*
622 Debugging the taglist plugin~
623 You can use the ":TlistDebug" command to enable logging of the debug messages
624 from the taglist plugin. To display the logged debug messages, you can use the
625 ":TlistMessages" command. To disable the logging of the debug messages, use
626 the ":TlistUndebug" command.
627
628 You can specify a file name to the ":TlistDebug" command to log the debug
629 messages to a file. Otherwise, the debug messages are stored in a script-local
630 variable. In the later case, to minimize memory usage, only the last 3000
631 characters from the debug messages are stored.
632
633 ==============================================================================
634 *taglist-options*
635 6. Options~
636
637 A number of Vim variables control the behavior of the taglist plugin. These
638 variables are initialized to a default value. By changing these variables you
639 can change the behavior of the taglist plugin. You need to change these
640 settings only if you want to change the behavior of the taglist plugin. You
641 should use the |:let| command in your .vimrc file to change the setting of any
642 of these variables.
643
644 The configurable taglist variables are listed below. For a detailed
645 description of these variables refer to the text below this table.
646
647 |'Tlist_Auto_Highlight_Tag'| Automatically highlight the current tag in the
648 taglist.
649 |'Tlist_Auto_Open'| Open the taglist window when Vim starts.
650 |'Tlist_Auto_Update'| Automatically update the taglist to include
651 newly edited files.
652 |'Tlist_Close_On_Select'| Close the taglist window when a file or tag is
653 selected.
654 |'Tlist_Compact_Format'| Remove extra information and blank lines from
655 the taglist window.
656 |'Tlist_Ctags_Cmd'| Specifies the path to the ctags utility.
657 |'Tlist_Display_Prototype'| Show prototypes and not tags in the taglist
658 window.
659 |'Tlist_Display_Tag_Scope'| Show tag scope next to the tag name.
660 |'Tlist_Enable_Fold_Column'| Show the fold indicator column in the taglist
661 window.
662 |'Tlist_Exit_OnlyWindow'| Close Vim if the taglist is the only window.
663 |'Tlist_File_Fold_Auto_Close'| Close tag folds for inactive buffers.
664 |'Tlist_GainFocus_On_ToggleOpen'|
665 Jump to taglist window on open.
666 |'Tlist_Highlight_Tag_On_BufEnter'|
667 On entering a buffer, automatically highlight
668 the current tag.
669 |'Tlist_Inc_Winwidth'| Increase the Vim window width to accommodate
670 the taglist window.
671 |'Tlist_Max_Submenu_Items'| Maximum number of items in a tags sub-menu.
672 |'Tlist_Max_Tag_Length'| Maximum tag length used in a tag menu entry.
673 |'Tlist_Process_File_Always'| Process files even when the taglist window is
674 closed.
675 |'Tlist_Show_Menu'| Display the tags menu.
676 |'Tlist_Show_One_File'| Show tags for the current buffer only.
677 |'Tlist_Sort_Type'| Sort method used for arranging the tags.
678 |'Tlist_Use_Horiz_Window'| Use a horizontally split window for the
679 taglist window.
680 |'Tlist_Use_Right_Window'| Place the taglist window on the right side.
681 |'Tlist_Use_SingleClick'| Single click on a tag jumps to it.
682 |'Tlist_WinHeight'| Horizontally split taglist window height.
683 |'Tlist_WinWidth'| Vertically split taglist window width.
684
685 *'Tlist_Auto_Highlight_Tag'*
686 Tlist_Auto_Highlight_Tag~
687 The taglist plugin will automatically highlight the current tag in the taglist
688 window. If you want to disable this, then you can set the
689 'Tlist_Auto_Highlight_Tag' variable to zero. Note that even though the current
690 tag highlighting is disabled, the tags for a new file will still be added to
691 the taglist window.
692 >
693 let Tlist_Auto_Highlight_Tag = 0
694 <
695 With the above variable set to 1, you can use the ":TlistHighlightTag" command
696 to highlight the current tag.
697
698 *'Tlist_Auto_Open'*
699 Tlist_Auto_Open~
700 To automatically open the taglist window, when you start Vim, you can set the
701 'Tlist_Auto_Open' variable to 1. By default, this variable is set to zero and
702 the taglist window will not be opened automatically on Vim startup.
703 >
704 let Tlist_Auto_Open = 1
705 <
706 The taglist window is opened only when a supported type of file is opened on
707 Vim startup. For example, if you open text files, then the taglist window will
708 not be opened.
709
710 *'Tlist_Auto_Update'*
711 Tlist_Auto_Update~
712 When a new file is edited, the tags defined in the file are automatically
713 processed and added to the taglist. To stop adding new files to the taglist,
714 set the 'Tlist_Auto_Update' variable to zero. By default, this variable is set
715 to 1.
716 >
717 let Tlist_Auto_Update = 0
718 <
719 With the above variable set to 1, you can use the ":TlistUpdate" command to
720 add the tags defined in the current file to the taglist.
721
722 *'Tlist_Close_On_Select'*
723 Tlist_Close_On_Select~
724 If you want to close the taglist window when a file or tag is selected, then
725 set the 'Tlist_Close_On_Select' variable to 1. By default, this variable is
726 set zero and when you select a tag or file from the taglist window, the window
727 is not closed.
728 >
729 let Tlist_Close_On_Select = 1
730 <
731 *'Tlist_Compact_Format'*
732 Tlist_Compact_Format~
733 By default, empty lines are used to separate different tag types displayed for
734 a file and the tags displayed for different files in the taglist window. If
735 you want to display as many tags as possible in the taglist window, you can
736 set the 'Tlist_Compact_Format' variable to 1 to get a compact display.
737 >
738 let Tlist_Compact_Format = 1
739 <
740 *'Tlist_Ctags_Cmd'*
741 Tlist_Ctags_Cmd~
742 The 'Tlist_Ctags_Cmd' variable specifies the location (path) of the exuberant
743 ctags utility. If exuberant ctags is present in any one of the directories in
744 the PATH environment variable, then there is no need to set this variable.
745
746 The exuberant ctags tool can be installed under different names. When the
747 taglist plugin starts up, if the 'Tlist_Ctags_Cmd' variable is not set, it
748 checks for the names exuberant-ctags, exctags, ctags, ctags.exe and tags in
749 the PATH environment variable. If any one of the named executable is found,
750 then the Tlist_Ctags_Cmd variable is set to that name.
751
752 If exuberant ctags is not present in one of the directories specified in the
753 PATH environment variable, then set this variable to point to the location of
754 the ctags utility in your system. Note that this variable should point to the
755 fully qualified exuberant ctags location and NOT to the directory in which
756 exuberant ctags is installed. If the exuberant ctags tool is not found in
757 either PATH or in the specified location, then the taglist plugin will not be
758 loaded. Examples:
759 >
760 let Tlist_Ctags_Cmd = 'd:\tools\ctags.exe'
761 let Tlist_Ctags_Cmd = '/usr/local/bin/ctags'
762 <
763 *'Tlist_Display_Prototype'*
764 Tlist_Display_Prototype~
765 By default, only the tag name will be displayed in the taglist window. If you
766 like to see tag prototypes instead of names, set the 'Tlist_Display_Prototype'
767 variable to 1. By default, this variable is set to zero and only tag names
768 will be displayed.
769 >
770 let Tlist_Display_Prototype = 1
771 <
772 *'Tlist_Display_Tag_Scope'*
773 Tlist_Display_Tag_Scope~
774 By default, the scope of a tag (like a C++ class) will be displayed in
775 square brackets next to the tag name. If you don't want the tag scopes
776 to be displayed, then set the 'Tlist_Display_Tag_Scope' to zero. By default,
777 this variable is set to 1 and the tag scopes will be displayed.
778 >
779 let Tlist_Display_Tag_Scope = 0
780 <
781 *'Tlist_Enable_Fold_Column'*
782 Tlist_Enable_Fold_Column~
783 By default, the Vim fold column is enabled and displayed in the taglist
784 window. If you wish to disable this (for example, when you are working with a
785 narrow Vim window or terminal), you can set the 'Tlist_Enable_Fold_Column'
786 variable to zero.
787 >
788 let Tlist_Enable_Fold_Column = 1
789 <
790 *'Tlist_Exit_OnlyWindow'*
791 Tlist_Exit_OnlyWindow~
792 If you want to exit Vim if only the taglist window is currently opened, then
793 set the 'Tlist_Exit_OnlyWindow' variable to 1. By default, this variable is
794 set to zero and the Vim instance will not be closed if only the taglist window
795 is present.
796 >
797 let Tlist_Exit_OnlyWindow = 1
798 <
799 *'Tlist_File_Fold_Auto_Close'*
800 Tlist_File_Fold_Auto_Close~
801 By default, the tags tree displayed in the taglist window for all the files is
802 opened. You can close/fold the tags tree for the files manually. To
803 automatically close the tags tree for inactive files, you can set the
804 'Tlist_File_Fold_Auto_Close' variable to 1. When this variable is set to 1,
805 the tags tree for the current buffer is automatically opened and for all the
806 other buffers is closed.
807 >
808 let Tlist_File_Fold_Auto_Close = 1
809 <
810 *'Tlist_GainFocus_On_ToggleOpen'*
811 Tlist_GainFocus_On_ToggleOpen~
812 When the taglist window is opened using the ':TlistToggle' command, this
813 option controls whether the cursor is moved to the taglist window or remains
814 in the current window. By default, this option is set to 0 and the cursor
815 remains in the current window. When this variable is set to 1, the cursor
816 moves to the taglist window after opening the taglist window.
817 >
818 let Tlist_GainFocus_On_ToggleOpen = 1
819 <
820 *'Tlist_Highlight_Tag_On_BufEnter'*
821 Tlist_Highlight_Tag_On_BufEnter~
822 When you enter a Vim buffer/window, the current tag in that buffer/window is
823 automatically highlighted in the taglist window. If the current tag name is
824 not visible in the taglist window, then the taglist window contents are
825 scrolled to make that tag name visible. If you like to disable the automatic
826 highlighting of the current tag when entering a buffer, you can set the
827 'Tlist_Highlight_Tag_On_BufEnter' variable to zero. The default setting for
828 this variable is 1.
829 >
830 let Tlist_Highlight_Tag_On_BufEnter = 0
831 <
832 *'Tlist_Inc_Winwidth'*
833 Tlist_Inc_Winwidth~
834 By default, when the width of the window is less than 100 and a new taglist
835 window is opened vertically, then the window width is increased by the value
836 set in the 'Tlist_WinWidth' variable to accommodate the new window. The value
837 of this variable is used only if you are using a vertically split taglist
838 window.
839
840 If your terminal doesn't support changing the window width from Vim (older
841 version of xterm running in a Unix system) or if you see any weird problems in
842 the screen due to the change in the window width or if you prefer not to
843 adjust the window width then set the 'Tlist_Inc_Winwidth' variable to zero.
844 CAUTION: If you are using the MS-Windows version of Vim in a MS-DOS command
845 window then you must set this variable to zero, otherwise the system may hang
846 due to a Vim limitation (explained in :help win32-problems)
847 >
848 let Tlist_Inc_Winwidth = 0
849 <
850 *'Tlist_Max_Submenu_Items'*
851 Tlist_Max_Submenu_Items~
852 If a file contains too many tags of a particular type (function, variable,
853 class, etc.), greater than that specified by the 'Tlist_Max_Submenu_Items'
854 variable, then the menu for that tag type will be split into multiple
855 sub-menus. The default setting for the 'Tlist_Max_Submenu_Items' variable is
856 25. This can be changed by setting the 'Tlist_Max_Submenu_Items' variable:
857 >
858 let Tlist_Max_Submenu_Items = 20
859 <
860 The name of the submenu is formed using the names of the first and the last
861 tag entries in that submenu.
862
863 *'Tlist_Max_Tag_Length'*
864 Tlist_Max_Tag_Length~
865 Only the first 'Tlist_Max_Tag_Length' characters from the tag names will be
866 used to form the tag type submenu name. The default value for this variable is
867 10. Change the 'Tlist_Max_Tag_Length' setting if you want to include more or
868 less characters:
869 >
870 let Tlist_Max_Tag_Length = 10
871 <
872 *'Tlist_Process_File_Always'*
873 Tlist_Process_File_Always~
874 By default, the taglist plugin will generate and process the tags defined in
875 the newly opened files only when the taglist window is opened or when the
876 taglist menu is enabled. When the taglist window is closed, the taglist plugin
877 will stop processing the tags for newly opened files.
878
879 You can set the 'Tlist_Process_File_Always' variable to 1 to generate the list
880 of tags for new files even when the taglist window is closed and the taglist
881 menu is disabled.
882 >
883 let Tlist_Process_File_Always = 1
884 <
885 To use the ":TlistShowTag" and the ":TlistShowPrototype" commands without the
886 taglist window and the taglist menu, you should set this variable to 1.
887
888 *'Tlist_Show_Menu'*
889 Tlist_Show_Menu~
890 When using GUI Vim, you can display the tags defined in the current file in a
891 menu named "Tags". By default, this feature is turned off. To turn on this
892 feature, set the 'Tlist_Show_Menu' variable to 1:
893 >
894 let Tlist_Show_Menu = 1
895 <
896 *'Tlist_Show_One_File'*
897 Tlist_Show_One_File~
898 By default, the taglist plugin will display the tags defined in all the loaded
899 buffers in the taglist window. If you prefer to display the tags defined only
900 in the current buffer, then you can set the 'Tlist_Show_One_File' to 1. When
901 this variable is set to 1, as you switch between buffers, the taglist window
902 will be refreshed to display the tags for the current buffer and the tags for
903 the previous buffer will be removed.
904 >
905 let Tlist_Show_One_File = 1
906 <
907 *'Tlist_Sort_Type'*
908 Tlist_Sort_Type~
909 The 'Tlist_Sort_Type' variable specifies the sort order for the tags in the
910 taglist window. The tags can be sorted either alphabetically by their name or
911 by the order of their appearance in the file (chronological order). By
912 default, the tag names will be listed by the order in which they are defined
913 in the file. You can change the sort type (from name to order or from order to
914 name) by pressing the "s" key in the taglist window. You can also change the
915 default sort order by setting 'Tlist_Sort_Type' to "name" or "order":
916 >
917 let Tlist_Sort_Type = "name"
918 <
919 *'Tlist_Use_Horiz_Window'*
920 Tlist_Use_Horiz_Window~
921 Be default, the tag names are displayed in a vertically split window. If you
922 prefer a horizontally split window, then set the 'Tlist_Use_Horiz_Window'
923 variable to 1. If you are running MS-Windows version of Vim in a MS-DOS
924 command window, then you should use a horizontally split window instead of a
925 vertically split window. Also, if you are using an older version of xterm in a
926 Unix system that doesn't support changing the xterm window width, you should
927 use a horizontally split window.
928 >
929 let Tlist_Use_Horiz_Window = 1
930 <
931 *'Tlist_Use_Right_Window'*
932 Tlist_Use_Right_Window~
933 By default, the vertically split taglist window will appear on the left hand
934 side. If you prefer to open the window on the right hand side, you can set the
935 'Tlist_Use_Right_Window' variable to 1:
936 >
937 let Tlist_Use_Right_Window = 1
938 <
939 *'Tlist_Use_SingleClick'*
940 Tlist_Use_SingleClick~
941 By default, when you double click on the tag name using the left mouse
942 button, the cursor will be positioned at the definition of the tag. You
943 can set the 'Tlist_Use_SingleClick' variable to 1 to jump to a tag when
944 you single click on the tag name using the mouse. By default this variable
945 is set to zero.
946 >
947 let Tlist_Use_SingleClick = 1
948 <
949 Due to a bug in Vim, if you set 'Tlist_Use_SingleClick' to 1 and try to resize
950 the taglist window using the mouse, then Vim will crash. This problem is fixed
951 in Vim 6.3 and above. In the meantime, instead of resizing the taglist window
952 using the mouse, you can use normal Vim window resizing commands to resize the
953 taglist window.
954
955 *'Tlist_WinHeight'*
956 Tlist_WinHeight~
957 The default height of the horizontally split taglist window is 10. This can be
958 changed by modifying the 'Tlist_WinHeight' variable:
959 >
960 let Tlist_WinHeight = 20
961 <
962 The |'winfixheight'| option is set for the taglist window, to maintain the
963 height of the taglist window, when new Vim windows are opened and existing
964 windows are closed.
965
966 *'Tlist_WinWidth'*
967 Tlist_WinWidth~
968 The default width of the vertically split taglist window is 30. This can be
969 changed by modifying the 'Tlist_WinWidth' variable:
970 >
971 let Tlist_WinWidth = 20
972 <
973 Note that the value of the |'winwidth'| option setting determines the minimum
974 width of the current window. If you set the 'Tlist_WinWidth' variable to a
975 value less than that of the |'winwidth'| option setting, then Vim will use the
976 value of the |'winwidth'| option.
977
978 When new Vim windows are opened and existing windows are closed, the taglist
979 plugin will try to maintain the width of the taglist window to the size
980 specified by the 'Tlist_WinWidth' variable.
981
982 ==============================================================================
983 *taglist-commands*
984 7. Commands~
985
986 The taglist plugin provides the following ex-mode commands:
987
988 |:TlistAddFiles| Add multiple files to the taglist.
989 |:TlistAddFilesRecursive|
990 Add files recursively to the taglist.
991 |:TlistClose| Close the taglist window.
992 |:TlistDebug| Start logging of taglist debug messages.
993 |:TlistLock| Stop adding new files to the taglist.
994 |:TlistMessages| Display the logged taglist plugin debug messages.
995 |:TlistOpen| Open and jump to the taglist window.
996 |:TlistSessionSave| Save the information about files and tags in the
997 taglist to a session file.
998 |:TlistSessionLoad| Load the information about files and tags stored
999 in a session file to taglist.
1000 |:TlistShowPrototype| Display the prototype of the tag at or before the
1001 specified line number.
1002 |:TlistShowTag| Display the name of the tag defined at or before the
1003 specified line number.
1004 |:TlistHighlightTag| Highlight the current tag in the taglist window.
1005 |:TlistToggle| Open or close (toggle) the taglist window.
1006 |:TlistUndebug| Stop logging of taglist debug messages.
1007 |:TlistUnlock| Start adding new files to the taglist.
1008 |:TlistUpdate| Update the tags for the current buffer.
1009
1010 *:TlistAddFiles*
1011 :TlistAddFiles {file(s)} [file(s) ...]
1012 Add one or more specified files to the taglist. You can
1013 specify multiple filenames using wildcards. To specify a
1014 file name with space character, you should escape the space
1015 character with a backslash.
1016 Examples:
1017 >
1018 :TlistAddFiles *.c *.cpp
1019 :TlistAddFiles file1.html file2.html
1020 <
1021 If you specify a large number of files, then it will take some
1022 time for the taglist plugin to process all of them. The
1023 specified files will not be edited in a Vim window and will
1024 not be added to the Vim buffer list.
1025
1026 *:TlistAddFilesRecursive*
1027 :TlistAddFilesRecursive {directory} [ {pattern} ]
1028 Add files matching {pattern} recursively from the specified
1029 {directory} to the taglist. If {pattern} is not specified,
1030 then '*' is assumed. To specify the current directory, use "."
1031 for {directory}. To specify a directory name with space
1032 character, you should escape the space character with a
1033 backslash.
1034 Examples:
1035 >
1036 :TlistAddFilesRecursive myproject *.java
1037 :TlistAddFilesRecursive smallproject
1038 <
1039 If large number of files are present in the specified
1040 directory tree, then it will take some time for the taglist
1041 plugin to process all of them.
1042
1043 *:TlistClose*
1044 :TlistClose Close the taglist window. This command can be used from any
1045 one of the Vim windows.
1046
1047 *:TlistDebug*
1048 :TlistDebug [filename]
1049 Start logging of debug messages from the taglist plugin.
1050 If {filename} is specified, then the debug messages are stored
1051 in the specified file. Otherwise, the debug messages are
1052 stored in a script local variable. If the file {filename} is
1053 already present, then it is overwritten.
1054
1055 *:TlistLock*
1056 :TlistLock
1057 Lock the taglist and don't process new files. After this
1058 command is executed, newly edited files will not be added to
1059 the taglist.
1060
1061 *:TlistMessages*
1062 :TlistMessages
1063 Display the logged debug messages from the taglist plugin
1064 in a window. This command works only when logging to a
1065 script-local variable.
1066
1067 *:TlistOpen*
1068 :TlistOpen Open and jump to the taglist window. Creates the taglist
1069 window, if the window is not opened currently. After executing
1070 this command, the cursor is moved to the taglist window. When
1071 the taglist window is opened for the first time, all the files
1072 in the buffer list are processed and the tags defined in them
1073 are displayed in the taglist window.
1074
1075 *:TlistSessionSave*
1076 :TlistSessionSave {filename}
1077 Saves the information about files and tags in the taglist to
1078 the specified file. This command can be used to save and
1079 restore the taglist contents across Vim sessions.
1080
1081 *:TlistSessionLoad*
1082 :TlistSessionLoad {filename}
1083 Load the information about files and tags stored in the
1084 specified session file to the taglist.
1085
1086 *:TlistShowPrototype*
1087 :TlistShowPrototype [filename] [linenumber]
1088 Display the prototype of the tag at or before the specified
1089 line number. If the file name and the line number are not
1090 specified, then the current file name and line number are
1091 used. A tag spans multiple lines starting from the line where
1092 it is defined to the line before the next tag. This command
1093 displays the prototype for the tag for any line number in this
1094 range.
1095
1096 *:TlistShowTag*
1097 :TlistShowTag [filename] [linenumber]
1098 Display the name of the tag defined at or before the specified
1099 line number. If the file name and the line number are not
1100 specified, then the current file name and line number are
1101 used. A tag spans multiple lines starting from the line where
1102 it is defined to the line before the next tag. This command
1103 displays the tag name for any line number in this range.
1104
1105 *:TlistHighlightTag*
1106 :TlistHighlightTag
1107 Highlight the current tag in the taglist window. By default,
1108 the taglist plugin periodically updates the taglist window to
1109 highlight the current tag. This command can be used to force
1110 the taglist plugin to highlight the current tag.
1111
1112 *:TlistToggle*
1113 :TlistToggle Open or close (toggle) the taglist window. Opens the taglist
1114 window, if the window is not opened currently. Closes the
1115 taglist window, if the taglist window is already opened. When
1116 the taglist window is opened for the first time, all the files
1117 in the buffer list are processed and the tags are displayed in
1118 the taglist window. After executing this command, the cursor
1119 is not moved from the current window to the taglist window.
1120
1121 *:TlistUndebug*
1122 :TlistUndebug
1123 Stop logging of debug messages from the taglist plugin.
1124
1125 *:TlistUnlock*
1126 :TlistUnlock
1127 Unlock the taglist and start processing newly edited files.
1128
1129 *:TlistUpdate*
1130 :TlistUpdate Update the tags information for the current buffer. This
1131 command can be used to re-process the current file/buffer and
1132 get the tags information. As the taglist plugin uses the file
1133 saved in the disk (instead of the file displayed in a Vim
1134 buffer), you should save a modified buffer before you update
1135 the taglist. Otherwise the listed tags will not include the
1136 new tags created in the buffer. You can use this command even
1137 when the taglist window is not opened.
1138
1139 ==============================================================================
1140 *taglist-functions*
1141 8. Global functions~
1142
1143 The taglist plugin provides several global functions that can be used from
1144 other Vim plugins to interact with the taglist plugin. These functions are
1145 described below.
1146
1147 |Tlist_Update_File_Tags()| Update the tags for the specified file
1148 |Tlist_Get_Tag_Prototype_By_Line()| Return the prototype of the tag at or
1149 before the specified line number in the
1150 specified file.
1151 |Tlist_Get_Tagname_By_Line()| Return the name of the tag at or
1152 before the specified line number in
1153 the specified file.
1154 |Tlist_Set_App()| Set the name of the application
1155 controlling the taglist window.
1156
1157 *Tlist_Update_File_Tags()*
1158 Tlist_Update_File_Tags({filename}, {filetype})
1159 Update the tags for the file {filename}. The second argument
1160 specifies the Vim filetype for the file. If the taglist plugin
1161 has not processed the file previously, then the exuberant
1162 ctags tool is invoked to generate the tags for the file.
1163
1164 *Tlist_Get_Tag_Prototype_By_Line()*
1165 Tlist_Get_Tag_Prototype_By_Line([{filename}, {linenumber}])
1166 Return the prototype of the tag at or before the specified
1167 line number in the specified file. If the filename and line
1168 number are not specified, then the current buffer name and the
1169 current line number are used.
1170
1171 *Tlist_Get_Tagname_By_Line()*
1172 Tlist_Get_Tagname_By_Line([{filename}, {linenumber}])
1173 Return the name of the tag at or before the specified line
1174 number in the specified file. If the filename and line number
1175 are not specified, then the current buffer name and the
1176 current line number are used.
1177
1178 *Tlist_Set_App()*
1179 Tlist_Set_App({appname})
1180 Set the name of the plugin that controls the taglist plugin
1181 window and buffer. This can be used to integrate the taglist
1182 plugin with other Vim plugins.
1183
1184 For example, the winmanager plugin and the Cream package use
1185 this function and specify the appname as "winmanager" and
1186 "cream" respectively.
1187
1188 By default, the taglist plugin is a stand-alone plugin and
1189 controls the taglist window and buffer. If the taglist window
1190 is controlled by an external plugin, then the appname should
1191 be set appropriately.
1192
1193 ==============================================================================
1194 *taglist-extend*
1195 9. Extending~
1196
1197 The taglist plugin supports all the languages supported by the exuberant ctags
1198 tool, which includes the following languages: Assembly, ASP, Awk, Beta, C,
1199 C++, C#, Cobol, Eiffel, Erlang, Fortran, HTML, Java, Javascript, Lisp, Lua,
1200 Make, Pascal, Perl, PHP, Python, Rexx, Ruby, Scheme, Shell, Slang, SML, Sql,
1201 TCL, Verilog, Vim and Yacc.
1202
1203 You can extend the taglist plugin to add support for new languages and also
1204 modify the support for the above listed languages.
1205
1206 You should NOT make modifications to the taglist plugin script file to add
1207 support for new languages. You will lose these changes when you upgrade to the
1208 next version of the taglist plugin. Instead you should follow the below
1209 described instructions to extend the taglist plugin.
1210
1211 You can extend the taglist plugin by setting variables in the .vimrc or _vimrc
1212 file. The name of these variables depends on the language name and is
1213 described below.
1214
1215 Modifying support for an existing language~
1216 To modify the support for an already supported language, you have to set the
1217 tlist_xxx_settings variable in the ~/.vimrc or $HOME/_vimrc file. Replace xxx
1218 with the Vim filetype name for the language file. For example, to modify the
1219 support for the perl language files, you have to set the tlist_perl_settings
1220 variable. To modify the support for java files, you have to set the
1221 tlist_java_settings variable.
1222
1223 To determine the filetype name used by Vim for a file, use the following
1224 command in the buffer containing the file:
1225
1226 :set filetype
1227
1228 The above command will display the Vim filetype for the current buffer.
1229
1230 The format of the value set in the tlist_xxx_settings variable is
1231
1232 <language_name>;flag1:name1;flag2:name2;flag3:name3
1233
1234 The different fields in the value are separated by the ';' character.
1235
1236 The first field 'language_name' is the name used by exuberant ctags to refer
1237 to this language file. This name can be different from the file type name used
1238 by Vim. For example, for C++, the language name used by ctags is 'c++' but the
1239 filetype name used by Vim is 'cpp'. To get the list of language names
1240 supported by exuberant ctags, use the following command:
1241
1242 $ ctags --list-maps=all
1243
1244 The remaining fields follow the format "flag:name". The sub-field 'flag' is
1245 the language specific flag used by exuberant ctags to generate the
1246 corresponding tags. For example, for the C language, to list only the
1247 functions, the 'f' flag is used. To get the list of flags supported by
1248 exuberant ctags for the various languages use the following command:
1249
1250 $ ctags --list-kinds=all
1251
1252 The sub-field 'name' specifies the title text to use for displaying the tags
1253 of a particular type. For example, 'name' can be set to 'functions'. This
1254 field can be set to any text string name.
1255
1256 For example, to list only the classes and functions defined in a C++ language
1257 file, add the following line to your .vimrc file:
1258
1259 let tlist_cpp_settings = 'c++;c:class;f:function'
1260
1261 In the above setting, 'cpp' is the Vim filetype name and 'c++' is the name
1262 used by the exuberant ctags tool. 'c' and 'f' are the flags passed to
1263 exuberant ctags to list C++ classes and functions and 'class' is the title
1264 used for the class tags and 'function' is the title used for the function tags
1265 in the taglist window.
1266
1267 For example, to display only functions defined in a C file and to use "My
1268 Functions" as the title for the function tags, use
1269
1270 let tlist_c_settings = 'c;f:My Functions'
1271
1272 When you set the tlist_xxx_settings variable, you will override the default
1273 setting used by the taglist plugin for the 'xxx' language. You cannot add to
1274 the default options used by the taglist plugin for a particular file type. To
1275 add to the options used by the taglist plugin for a language, copy the option
1276 values from the taglist plugin file to your .vimrc file and modify it.
1277
1278 Adding support for a new language~
1279 If you want to add support for a new language to the taglist plugin, you need
1280 to first extend the exuberant ctags tool. For more information about extending
1281 exuberant ctags, visit the following page:
1282
1283 http://ctags.sourceforge.net/EXTENDING.html
1284
1285 To add support for a new language, set the tlist_xxx_settings variable in the
1286 ~/.vimrc file appropriately as described above. Replace 'xxx' in the variable
1287 name with the Vim filetype name for the new language.
1288
1289 For example, to extend the taglist plugin to support the latex language, you
1290 can use the following line (assuming, you have already extended exuberant
1291 ctags to support the latex language):
1292
1293 let tlist_tex_settings='latex;b:bibitem;c:command;l:label'
1294
1295 With the above line, when you edit files of filetype "tex" in Vim, the taglist
1296 plugin will invoke the exuberant ctags tool passing the "latex" filetype and
1297 the flags b, c and l to generate the tags. The text heading 'bibitem',
1298 'command' and 'label' will be used in the taglist window for the tags which
1299 are generated for the flags b, c and l respectively.
1300
1301 ==============================================================================
1302 *taglist-faq*
1303 10. Frequently Asked Questions~
1304
1305 Q. The taglist plugin doesn't work. The taglist window is empty and the tags
1306 defined in a file are not displayed.
1307 A. Are you using Vim version 6.0 and above? The taglist plugin relies on the
1308 features supported by Vim version 6.0 and above. You can use the following
1309 command to get the Vim version:
1310 >
1311 $ vim --version
1312 <
1313 Are you using exuberant ctags version 5.0 and above? The taglist plugin
1314 relies on the features supported by exuberant ctags and will not work with
1315 GNU ctags or the Unix ctags utility. You can use the following command to
1316 determine whether the ctags installed in your system is exuberant ctags:
1317 >
1318 $ ctags --version
1319 <
1320 Is exuberant ctags present in one of the directories in your PATH? If not,
1321 you need to set the Tlist_Ctags_Cmd variable to point to the location of
1322 exuberant ctags. Use the following Vim command to verify that this is setup
1323 correctly:
1324 >
1325 :echo system(Tlist_Ctags_Cmd . ' --version')
1326 <
1327 The above command should display the version information for exuberant
1328 ctags.
1329
1330 Did you turn on the Vim filetype detection? The taglist plugin relies on
1331 the filetype detected by Vim and passes the filetype to the exuberant ctags
1332 utility to parse the tags. Check the output of the following Vim command:
1333 >
1334 :filetype
1335 <
1336 The output of the above command should contain "filetype detection:ON".
1337 To turn on the filetype detection, add the following line to the .vimrc or
1338 _vimrc file:
1339 >
1340 filetype on
1341 <
1342 Is your version of Vim compiled with the support for the system() function?
1343 The following Vim command should display 1:
1344 >
1345 :echo exists('*system')
1346 <
1347 In some Linux distributions (particularly Suse Linux), the default Vim
1348 installation is built without the support for the system() function. The
1349 taglist plugin uses the system() function to invoke the exuberant ctags
1350 utility. You need to rebuild Vim after enabling the support for the
1351 system() function. If you use the default build options, the system()
1352 function will be supported.
1353
1354 Do you have the |'shellslash'| option set? You can try disabling the
1355 |'shellslash'| option. When the taglist plugin invokes the exuberant ctags
1356 utility with the path to the file, if the incorrect slashes are used, then
1357 you will see errors.
1358
1359 Check the shell related Vim options values using the following command:
1360 >
1361 :set shell? shellcmdflag? shellpipe?
1362 :set shellquote? shellredir? shellxquote?
1363 <
1364 If these options are set in your .vimrc or _vimrc file, try removing those
1365 lines.
1366
1367 Are you using a Unix shell in a MS-Windows environment? For example,
1368 the Unix shell from the MKS-toolkit. Do you have the SHELL environment
1369 set to point to this shell? You can try resetting the SHELL environment
1370 variable.
1371
1372 If you are using a Unix shell on MS-Windows, you should try to use
1373 exuberant ctags that is compiled for Unix-like environments so that
1374 exuberant ctags will understand path names with forward slash characters.
1375
1376 Is your filetype supported by the exuberant ctags utility? The file types
1377 supported by the exuberant ctags utility are listed in the ctags help. If a
1378 file type is not supported, you have to extend exuberant ctags. You can use
1379 the following command to list the filetypes supported by exuberant ctags:
1380 >
1381 ctags --list-languages
1382 <
1383 Run the following command from the shell prompt and check whether the tags
1384 defined in your file are listed in the output from exuberant ctags:
1385 >
1386 ctags -f - --format=2 --excmd=pattern --fields=nks <filename>
1387 <
1388 If you see your tags in the output from the above command, then the
1389 exuberant ctags utility is properly parsing your file.
1390
1391 Do you have the .ctags or _ctags or the ctags.cnf file in your home
1392 directory for specifying default options or for extending exuberant ctags?
1393 If you do have this file, check the options in this file and make sure
1394 these options are not interfering with the operation of the taglist plugin.
1395
1396 If you are using MS-Windows, check the value of the TEMP and TMP
1397 environment variables. If these environment variables are set to a path
1398 with space characters in the name, then try using the DOS 8.3 short name
1399 for the path or set them to a path without the space characters in the
1400 name. For example, if the temporary directory name is "C:\Documents and
1401 Settings\xyz\Local Settings\Temp", then try setting the TEMP variable to
1402 the following:
1403 >
1404 set TEMP=C:\DOCUMEN~1\xyz\LOCALS~1\Temp
1405 <
1406 If exuberant ctags is installed in a directory with space characters in the
1407 name, then try adding the directory to the PATH environment variable or try
1408 setting the 'Tlist_Ctags_Cmd' variable to the shortest path name to ctags
1409 or try copying the exuberant ctags to a path without space characters in
1410 the name. For example, if exuberant ctags is installed in the directory
1411 "C:\Program Files\Ctags", then try setting the 'Tlist_Ctags_Cmd' variable
1412 as below:
1413 >
1414 let Tlist_Ctags_Cmd='C:\Progra~1\Ctags\ctags.exe'
1415 <
1416 If you are using a cygwin compiled version of exuberant ctags on MS-Windows,
1417 make sure that either you have the cygwin compiled sort utility installed
1418 and available in your PATH or compile exuberant ctags with internal sort
1419 support. Otherwise, when exuberant ctags sorts the tags output by invoking
1420 the sort utility, it may end up invoking the MS-Windows version of
1421 sort.exe, thereby resulting in failure.
1422
1423 Q. When I try to open the taglist window, I am seeing the following error
1424 message. How do I fix this problem?
1425
1426 Taglist: Failed to generate tags for /my/path/to/file
1427 ctags: illegal option -- -^@usage: ctags [-BFadtuwvx] [-f tagsfile] file ...
1428
1429 A. The taglist plugin will work only with the exuberant ctags tool. You
1430 cannot use the GNU ctags or the Unix ctags program with the taglist plugin.
1431 You will see an error message similar to the one shown above, if you try
1432 use a non-exuberant ctags program with Vim. To fix this problem, either add
1433 the exuberant ctags tool location to the PATH environment variable or set
1434 the 'Tlist_Ctags_Cmd' variable.
1435
1436 Q. A file has more than one tag with the same name. When I select a tag name
1437 from the taglist window, the cursor is positioned at the incorrect tag
1438 location.
1439 A. The taglist plugin uses the search pattern generated by the exuberant ctags
1440 utility to position the cursor at the location of a tag definition. If a
1441 file has more than one tag with the same name and same prototype, then the
1442 search pattern will be the same. In this case, when searching for the tag
1443 pattern, the cursor may be positioned at the incorrect location.
1444
1445 Q. I have made some modifications to my file and introduced new
1446 functions/classes/variables. I have not yet saved my file. The taglist
1447 plugin is not displaying the new tags when I update the taglist window.
1448 A. The exuberant ctags utility will process only files that are present in the
1449 disk. To list the tags defined in a file, you have to save the file and
1450 then update the taglist window.
1451
1452 Q. I have created a ctags file using the exuberant ctags utility for my source
1453 tree. How do I configure the taglist plugin to use this tags file?
1454 A. The taglist plugin doesn't use a tags file stored in disk. For every opened
1455 file, the taglist plugin invokes the exuberant ctags utility to get the
1456 list of tags dynamically. The Vim system() function is used to invoke
1457 exuberant ctags and get the ctags output. This function internally uses a
1458 temporary file to store the output. This file is deleted after the output
1459 from the command is read. So you will never see the file that contains the
1460 output of exuberant ctags.
1461
1462 Q. When I set the |'updatetime'| option to a low value (less than 1000) and if
1463 I keep pressing a key with the taglist window open, the current buffer
1464 contents are changed. Why is this?
1465 A. The taglist plugin uses the |CursorHold| autocmd to highlight the current
1466 tag. The CursorHold autocmd triggers for every |'updatetime'| milliseconds.
1467 If the |'updatetime'| option is set to a low value, then the CursorHold
1468 autocmd will be triggered frequently. As the taglist plugin changes
1469 the focus to the taglist window to highlight the current tag, this could
1470 interfere with the key movement resulting in changing the contents of
1471 the current buffer. The workaround for this problem is to not set the
1472 |'updatetime'| option to a low value.
1473
1474 ==============================================================================
1475 *taglist-license*
1476 11. License~
1477 Permission is hereby granted to use and distribute the taglist plugin, with or
1478 without modifications, provided that this copyright notice is copied with it.
1479 Like anything else that's free, taglist.vim is provided *as is* and comes with
1480 no warranty of any kind, either expressed or implied. In no event will the
1481 copyright holder be liable for any damamges resulting from the use of this
1482 software.
1483
1484 ==============================================================================
1485 *taglist-todo*
1486 12. Todo~
1487
1488 1. Group tags according to the scope and display them. For example,
1489 group all the tags belonging to a C++/Java class
1490 2. Support for displaying tags in a modified (not-yet-saved) file.
1491 3. Automatically open the taglist window only for selected filetypes.
1492 For other filetypes, close the taglist window.
1493 4. When using the shell from the MKS toolkit, the taglist plugin
1494 doesn't work.
1495 5. The taglist plugin doesn't work with files edited remotely using the
1496 netrw plugin. The exuberant ctags utility cannot process files over
1497 scp/rcp/ftp, etc.
1498
1499 ==============================================================================
1500
1501 vim:tw=78:ts=8:noet:ft=help: