*taglist.txt*	Plugin for browsing source codeAuthor: Yegappan Lakshmanan  (yegappan AT yahoo DOT com)For Vim version 6.0 and aboveLast change: 2006 November 141. Overview 					|taglist-intro|2. Taglist on the internet			|taglist-internet|3. Requirements					|taglist-requirements|4. Installation 				|taglist-install|5. Usage 					|taglist-using|6. Options 					|taglist-options|7. Commands 					|taglist-commands|8. Global functions 				|taglist-functions|9. Extending 					|taglist-extend|10. FAQ 					|taglist-faq|11. Todo					|taglist-todo|==============================================================================						*taglist-intro*1. Overview~The "Tag List" plugin is a source code browser plugin for Vim. This pluginallows you to efficiently browse through source code files for differentprogramming languages. The "Tag List" plugin provides the following features:    * Displays the tags (functions, classes, structures, variables, etc.)       defined in a file in a vertically or horizontally split Vim window.    * In GUI Vim, optionally displays the tags in the Tags drop-down menu and      in the popup menu.    * Automatically updates the taglist window as you switch between      files/buffers. As you open new files, the tags defined in the new files      are added to the existing file list and the tags defined in all the      files are displayed grouped by the filename.    * When a tag name is selected from the taglist window, positions the      cursor at the definition of the tag in the source file.    * Automatically highlights the current tag name.    * Groups the tags by their type and displays them in a foldable tree.    * Can display the prototype and scope of a tag.    * Can optionally display the tag prototype instead of the tag name in the      taglist window.    * The tag list can be sorted either by name or by chronological order.    * Supports the following language files: Assembly, ASP, Awk, Beta, C,      C++, C#, Cobol, Eiffel, Erlang, Fortran, HTML, Java, Javascript, Lisp,      Lua, Make, Pascal, Perl, PHP, Python, Rexx, Ruby, Scheme, Shell, Slang,      SML, Sql, TCL, Verilog, Vim and Yacc.    * Can be easily extended to support new languages. Support for      existing languages can be modified easily.    * Provides functions to display the current tag name in the Vim status      line or the window title bar.    * The list of tags and files in the taglist can be saved and      restored across Vim sessions.    * Provides commands to get the name and prototype of the current tag.    * Runs in both console/terminal and GUI versions of Vim.    * Works with the winmanager plugin. Using the winmanager plugin, you      can use Vim plugins like the file explorer, buffer explorer and the      taglist plugin at the same time like an IDE.    * Can be used in both Unix and MS-Windows systems.==============================================================================						*taglist-internet*2. Taglist on the internet~The home page of the taglist plugin is at:>	http://vim-taglist.sourceforge.net/<You can subscribe to the taglist mailing list to post your questions orsuggestions for improvement or to send bug reports. Visit the following pagefor subscribing to the mailing list:>	http://groups.yahoo.com/group/taglist<==============================================================================						*taglist-requirements*3. Requirements~The taglist plugin will work on all the platforms where the exuberant ctagsutility and Vim are supported (this includes MS-Windows and Unix basedsystems).The taglist plugin will work with Vim version 6.0 and above.The taglist plugin relies on the exuberant ctags utility to dynamicallygenerate the tag listing.  The exuberant ctags utility must be installed inyour system to use this plugin. You should use exuberant ctags version 5.0 andabove. The exuberant ctags utility is shipped with most of the Linuxdistributions.  You can download the exuberant ctags utility from>	http://ctags.sourceforge.net<The taglist plugin doesn't use or create a tags file and there is no need tocreate a tags file to use this plugin. The taglist plugin will not work withthe GNU ctags or the Unix ctags utility.This plugin relies on the Vim "filetype" detection mechanism to determine thetype of the current file. You have to turn on the Vim filetype detection byadding the following line to your .vimrc file:>	filetype on<The taglist plugin will not work if you run Vim in the restricted mode (usingthe -Z command-line argument).The taglist plugin uses the Vim system() function to invoke the exuberantctags utility. If Vim is compiled without the system() function then youcannot use the taglist plugin. Some of the Linux distributions (Suse) compileVim without the system() function for security reasons.==============================================================================						*taglist-install*4. Installation~1. Download the taglist.zip file and unzip the files to the $HOME/.vim or the   $HOME/vimfiles or the $VIM/vimfiles directory. After this step, you should   have the following two files (the directory structure should be preserved):	plugin/taglist.vim - main taglist plugin file	doc/taglist.txt    - documentation (help) file   Refer to the |add-plugin|, |add-global-plugin| and |'runtimepath'| Vim   help pages for more details about installing Vim plugins.2. Change to the $HOME/.vim/doc or $HOME/vimfiles/doc or $VIM/vimfiles/doc   directory, start Vim and run the ":helptags ." command to process the   taglist help file. Without this step, you cannot jump to the taglist help   topics.3. If the exuberant ctags utility is not present in one of the directories in   the PATH environment variable, then set the 'Tlist_Ctags_Cmd' variable to   point to the location of the exuberant ctags utility (not to the directory)   in the .vimrc file.4. If you are running a terminal/console version of Vim and the terminal   doesn't support changing the window width then set the   'Tlist_Inc_Winwidth' variable to 0 in the .vimrc file.5. Restart Vim.6. You can now use the ":TlistToggle" command to open/close the taglist   window. You can use the ":help taglist" command to get more information   about using the taglist plugin.To uninstall the taglist plugin, remove the plugin/taglist.vim anddoc/taglist.txt files.==============================================================================						*taglist-using*5. Usage~The taglist plugin can be used in several different ways.1. You can open the taglist window and keep it open. On opening the taglist   window, the tags defined in all the files in the Vim buffer list will be   displayed in the taglist window. As you edit files, the tags defined in   them will be added to the taglist window. You can select a tag from the   taglist window and jump to it. The current tag will be highlighted in the   taglist window. You can close the taglist window when you no longer need   the window.2. You can configure the taglist plugin to process the tags defined in all the   edited files always. In this configuration, even if the taglist window is   closed and the taglist menu is not displayed, the taglist plugin will   processes the tags defined in newly edited files. You can then open the   taglist window only when you need to select a tag and then automatically   close the taglist window after selecting the tag.3. You can configure the taglist plugin to display only the tags defined in   the current file in the taglist window. By default, the taglist plugin   displays the tags defined in all the files in the Vim buffer list. As you   switch between files, the taglist window will be refreshed to display the   tags defined only in the current file.4. You can use the Tags pull-down and popup menu created by the taglist plugin   to display the tags defined in the current file and select a tag to jump to   it. You can use the menu without opening the taglist window. By default,   the Tags menu is disabled.5. You can configure the taglist plugin to display the name of the current tag   in the Vim window status line or in the Vim window title bar. For this to   work without the taglist window or menu, you need to configure the taglist   plugin to process the tags defined in a file always.6. You can save the tags defined in multiple files to a taglist session file   and load it when needed. You can also configure the taglist plugin to not   update the taglist window when editing new files. You can then manually add   files to the taglist window.Opening the taglist window~You can open the taglist window using the ":TlistOpen" or the ":TlistToggle"commands. The ":TlistOpen" command opens the taglist window and jumps to it.The ":TlistToggle" command opens or closes (toggle) the taglist window and thecursor remains in the current window. If the 'Tlist_GainFocus_On_ToggleOpen'variable is set to 1, then the ":TlistToggle" command opens the taglist windowand moves the cursor to the taglist window.You can map a key to invoke these commands. For example, the following commandcreates a normal mode mapping for the <F8> key to toggle the taglist window.>	nnoremap <silent> <F8> :TlistToggle<CR><Add the above mapping to your ~/.vimrc file.To automatically open the taglist window on Vim startup, set the'Tlist_Auto_Open' variable to 1.  You can also open the taglist window onstartup using the following command line:>	$ vim +TlistOpen<Closing the taglist window~You can close the taglist window from the taglist window by pressing 'q' orusing the Vim ":q" command. You can also use any of the Vim window commands toclose the taglist window. Invoking the ":TlistToggle" command when the taglistwindow is opened, closes the taglist window. You can also use the":TlistClose" command to close the taglist window.To automatically close the taglist window when a tag or file is selected, youcan set the 'Tlist_Close_On_Select' variable to 1.  To exit Vim when only thetaglist window is present, set the 'Tlist_Exit_OnlyWindow' variable to 1.Jumping to a tag or a file~You can select a tag in the taglist window either by pressing the <Enter> keyor by double clicking the tag name using the mouse. To jump to a tag on asingle mouse click set the 'Tlist_Use_SingleClick' variable to 1. To jump tothe tag in a new window, press the 'o' key. You can press the 'p' key to jumpto the tag but still keep the cursor in the taglist window itself (preview).You can open a file by pressing the <Enter> key or by double clicking the filename using the mouse.In the taglist window, you can use the [[ or <Backspace> key to jump to thebeginning of the previous file. You can use the ]] or <Tab> key to jump to thebeginning of the next file. When you reach the first or last file, the searchwraps around and the jumps to the next/previous file.Highlighting the current tag~The taglist plugin automatically highlights the name of the current tag in thetaglist window. The Vim |CursorHold| autocmd event is used for this. If thecurrent tag name is not visible in the taglist window, then the taglist windowcontents are scrolled to make that tag name visible. You can also use the":TlistHighlightTag" command to force the highlighting of the current tag.The tag name is highlighted if no activity is performed for |'updatetime'|milliseconds. The default value for this Vim option is 4 seconds. To avoidunexpected problems, you should not set the |'updatetime'| option to a verylow value.To disable the automatic highlighting of the current tag name in the taglistwindow, set the 'Tlist_Auto_Highlight_Tag' variable to zero.When entering a Vim buffer/window, the taglist plugin automatically highlightsthe current tag in that buffer/window.  If you like to disable the automatichighlighting of the current tag when entering a buffer, set the'Tlist_Highlight_Tag_On_BufEnter' variable to zero.Adding files to the taglist~When the taglist window is opened, all the files in the Vim buffer list areprocessed and the supported files are added to the taglist.  When you edit afile in Vim, the taglist plugin automatically processes this file and adds itto the taglist. If you close the taglist window, the tag information in thetaglist is retained.To process files even when the taglist window is not open, set the'Tlist_Process_File_Always' variable to 1.You can manually add multiple files to the taglist without opening them usingthe ":TlistAddFiles" and the ":TlistAddFilesRecursive" commands.For example, to add all the C files in the /my/project/dir directory to thetaglist, you can use the following command:>	:TlistAddFiles /my/project/dir/*.c<Note that when adding several files with a large number of tags or a largenumber of files, it will take several seconds to several minutes for thetaglist plugin to process all the files. You should not interrupt the taglistplugin by pressing <CTRL-C>.You can recursively add multiple files from a directory tree using the":TlistAddFilesRecursive" command:>	:TlistAddFilesRecursive /my/project/dir *.c<This command takes two arguments. The first argument specifies the directoryfrom which to recursively add the files. The second optional argumentspecifies the wildcard matching pattern for selecting the files to add. Thedefault pattern is * and all the files are added.Displaying tags for only one file~The taglist window displays the tags for all the files in the Vim buffer listand all the manually added files. To display the tags for only the currentactive buffer, set the 'Tlist_Show_One_File' variable to 1.Removing files from the taglist~