.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: