tlist.txt (69364B)
1 *tlist.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: