vim-taglist-plus/doc/taglist.txt

*taglist.txt*	Plugin for browsing source code

Author: Yegappan Lakshmanan  (yegappan AT yahoo DOT com)
For Vim version 6.0 and above
Last change: 2005 April 4

1. Overview 					|taglist-intro|
2. Taglist on the internet			|taglist-internet|
3. Requirements					|taglist-requirement|
4. Installation 				|taglist-install|
5. Usage 					|taglist-using|
6. Configuration 				|taglist-configure|
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 plugin
allows you to efficiently browse through source code files for different
programming 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.
    * Groups the tags by their type and displays them in a foldable tree.
    * 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.
    * In GUI Vim, optionally displays the tags in the Tags drop-down menu and
      in the popup menu.
    * 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 line number.
    * 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 commands to get the name and prototype of the current tag.
    * Provides functions to display the current tag name in the Vim status
      line or the window title bar.
    * The list of tags displayed in the taglist window can be saved and
      restored across Vim sessions.
    * 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~

You can visit the taglist plugin home page for more information: >

	http://www.geocities.com/yegappan/taglist
<
You can subscribe to the taglist mailing list to post your questions
or suggestions for improvement or bug reports. Visit the following
page for subscribing to the mailing list: >

	http://groups.yahoo.com/group/taglist/
<
==============================================================================
						*taglist-requirement*
3. Requirements~

The taglist plugin will work on all the platforms where the exuberant ctags
utility and Vim are supported (this includes MS-Windows and Unix based
systems).

The taglist plugin will work with Vim version 6.0 and above.

The taglist plugin relies on the exuberant ctags utility to dynamically
generate the tag listing. You can download the exuberant ctags utility from >

	http://ctags.sourceforge.net
<
The exuberant ctags utility must be installed in your system to use this
plugin. You should use exuberant ctags version 5.0 and above. This plugin
doesn't use or create a tags file and there is no need to create a tags file
to use this plugin. The taglist plugin will not work with the GNU ctags or the
Unix ctags utility.

This plugin relies on the Vim "filetype" detection mechanism to determine the
type of the current file. You have to turn on the Vim filetype detection by
adding the following line to your .vimrc file: >

	filetype on
<
The taglist plugin will not work if you run Vim in the restricted mode (using
the -Z command-line argument).

The taglist plugin uses the Vim system() function to invoke the exuberant
ctags utility. If Vim is compiled without the system() function then you
cannot use the taglist plugin. Some of the Linux distributions (Suse) compile
Vim 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/doc/vimfiles
   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 your PATH, 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 ":Tlist" command to open/close the taglist
   window. You can use the ":help taglist" command to get more information
   about using the taglist plugin.

==============================================================================
						*taglist-using*
5. Usage~

Opening the taglist window~
You can open the taglist window using the ":Tlist" command. This command will
open or close (toggle) the taglist window. You can map a key to invoke this
command. For example, the following command creates a normal mode mapping for
the <F8> key to open or close the taglist window. >

	:nnoremap <silent> <F8> :Tlist<CR>
<
Add the above mapping to your ~/.vimrc file. You can also open the taglist
window on startup using the following command line: >

	$ vim +Tlist

When the taglist window is opened for the first time, all the files in the
buffer list are processed and the tags for those files are displayed. If you
close the taglist window, the tags information displayed in the taglist window
will not be lost. The next time you open the taglist window in the same Vim
session, the stored tags information will be displayed.

Closing the taglist window~
You can close the taglist window from the taglist window by pressing 'q' or
using the Vim ":q" command. You can also use any of the Vim window commands
to close the taglist window. Invoking the ":Tlist" command when the taglist
window is opened, will close the taglist window. You can also close the
taglist window by invoking the ":TlistClose" command.

Taglist window contents~
As you switch between source files, the taglist window will be automatically
updated with the tags defined in the current source file. The tag names will
grouped by their type (variable, function, class, etc). For tags with scope
information (like class members, structures inside structures, etc), the scope
information will be displayed in square brackets "[]" after the tagname.

Opening and closing the tag and file tree~
The tag names will be  displayed as a foldable tree using the Vim folding
support. You can collapse the tree using the '-' key or using the Vim zc
fold command. You can open the tree using the '+' key or using the Vim zo
fold command. You can open all the folds using the '*' key or using the Vim
zR fold command. You can also use the mouse to open/close the folds. You
can close all the folds using the '=' key.

Jumping to a tag or a file~
You can select a tag either by pressing the <Enter> key or by double clicking
the tag name using the mouse. You can jump to a tag using a single mouse click
by setting the 'Tlist_Use_SingleClick' variable. You can press the 'o' key to
jump to the tag in a new window. You can press the 'p' key to jump to the tag
but still keep the cursor in the taglist window itself.

You can open a file by pressing <Enter> key or by double clicking the file
name using the mouse.

In the taglist window, you can use the [[ or <Backspace> key to jump to the
beginning of the previous file. You can use the ]] or <Tab> key to jump to the
beginning of the next file.

Syncing the taglist window~
The taglist plugin will automatically highlight the name of the current tag.
The tag name will be highlighted after |updatetime| milliseconds. The default
value for this Vim option is 4 seconds. To avoid unexpected problems, you
should not set the |updatetime| option to very low values. You can also use
the ":TlistSync" command to force the highlighting of the current tag.

Displaying the tag prototype~
If you place the cursor on a tag name in the taglist window, then the tag
prototype will be displayed at the Vim status line after |updatetime|
milliseconds. The default value for the |updatetime| Vim option is 4
seconds. You can also press the space bar to display the prototype of the
tag under the cursor in the taglist window.

You can use the ":TlistShowPrototype" command to display the prototype of the
tag at or below the specified line number. For example, >

	:TlistShowPrototype myfile.c 50
<
If the file name and line number are not supplied, then this command will
display the prototype of the current tag.

You can use the ":TlistShowTag" command to display the name of the tag at or
below the specified line number. For example,
>
	:TlistShowTag myfile.java 100
<
If the file name and line number are not supplied, then this command will
display the name of the current tag.

The above two commands will work even when the taglist window is closed. To
use this command on newly opened files without the taglist window and the
taglist menu, you should set the Tlist_Process_File_Always variable to 1.

Sorting the tags for a file~
The tags displayed in the taglist window can be sorted either by name of by
their chronological order. The default sorting order is by the order in which
the tags appear in the file. You can change the default sort order by setting
the Tlist_Sort_Type variable. You can sort the tags by their name by pressing
the "s" key in the taglist window. You can again sort the tags by their
chronological order using the "s" key. Each file in the taglist window can be
sorted using different order.

Removing the tags listed for a file from the taglist window~
You can remove the tags displayed for a file, by pressing the 'd' key when the
cursor is on one of the tags listed for the file in the taglist window. The
removed file is no longer displayed in the taglist window. To again display
the tags for the file, open the file in a Vim window and then use the
:TlistUpdate command.

Zooming in and out of the taglist window~
You can press the 'x' key in the taglist window to maximize the taglist
window width/height. The window will be maximized to the maximum possible
width/height without closing the other existing windows. You can again press
'x' to restore the taglist window to the default width/height.

Updating the tags displayed for a file~
You can update or refresh the tags displayed for a file by pressing the "u"
key in the taglist window. If an existing file is modified, after the file is
saved, the taglist plugin will automatically update the tags displayed for the
file.

You can also use the ":TlistUpdate" command to update the tags for the current
buffer after you made some changes to it. You should save the modified buffer
before you update the taglist window. Otherwise the listed tags will not
include the new tags created in the buffer. 

If you have deleted the tags displayed for a file in the taglist window using
the 'd' key, you can again display the tags for that file using the
':TlistUpdate' command.

Modifying the contents of the taglist buffer/window~
The contents of the taglist buffer/window are managed by the taglist plugin.
The Vim 'modifiable' option is turned off for the taglist buffer. You should
not manually edit the taglist buffer, by setting the 'modifiable' flag. If you
manually edit the taglist buffer contents, then the taglist plugin will be out
of sync with the taglist buffer contents and the plugin will no longer work
correctly. To redisplay the taglist buffer contents again, you can close the
taglist window and reopen it.

						*taglist-session*
Taglist Session~
A taglist session refers to the group of files and their tags displayed in the
taglist window in a Vim session.

You can save and restore a taglist session (and all the displayed tags) using
the :TlistSessionSave and :TlistSessionLoad commands.

To save all the tags displayed in the taglist window to a file, use the
:TlistSessionSave command and specify the filename: >

	:TlistSessionSave <file name>
<
To load the saved taglist session, use the TlistSessionLoad command: >

	:TlistSessionLoad <file name>
<
Information about the tags displayed for the files in the taglist window will
be stored in the taglist session file. This will be used to restore the
taglist window state later. When you load a taglist session file, the tags
stored in the file will be added to the tags already displayed in the taglist
window.

The taglist session feature can be used to save the tags for large files or a
group of frequently used files (like a project). By using the taglist session
file, you can minimize the amount to time it takes to load/refresh the taglist
window for multiple files.

You can create more than one taglist session file for multiple groups of
files.

Displaying tag name in the Vim status line or the window title bar~
You can use the Tlist_Get_Tagname_By_Line() function provided by the taglist
plugin to display the current tag name in the Vim status line or the window
title bar. Similarly, you can use the Tlist_Get_Tag_Prototype_By_Line()
function to display the current tag prototype in the Vim status line or the
window title bar.

For example, the following command can be used to display the current tag name
in the status line:
>
	:set statusline=%<%f%=%([%{Tlist_Get_Tagname_By_Line()}]%)
<
The following command can be used to display the current tag name in the
window title bar:
>
	:set title titlestring=%<%f\ %([%{Tlist_Get_Tagname_By_Line()}]%)
<
Note that the current tag name can be displayed only after the file is
processed by the taglist plugin. For this, you have to either set the
'Tlist_Process_File_Always' variable to 1 or open the taglist window or use
the taglist menu. For more information about configuring the Vim status line,
refer to the documentation for the |'statusline'| option.

Changing the taglist window highlighting~
The following Vim highlight groups are defined and used to highlight the
various entities in the taglist window:

    TagListTagName  - Used for tag names
    TagListTagScope - Used for tag scope
    TagListTitle    - Used for tag titles
    TagListComment  - Used for comments in the taglist window
    TagListFileName - Used for filenames

By default, these highlight groups are linked to the standard Vim highlight
groups. If you want to change these highlight groups, you can prefix 'My'
to the above highlight group names and define them in your .vimrc file. The
taglist plugin will use the defined highlight groups instead of the default
groups. For example, to change the highlighting used for tag names, you can
use: >

	:highlight MyTagListTagName guifg=cyan
<
Getting help~
You can press the "?" key in the taglist window to display the help
information about using the taglist window. If you again press the '?' key,
the help information will be removed from the taglist window.

						*taglist-keys*
Taglist window key list~
The following table lists the description of the keys that can be used
in the taglist window.

  Key           Description~

  <CR>          Jump to the location where the tag under cursor is
                defined.
  o             Jump to the location where the tag under cursor is
                defined in a new window.
  p             Display the tag definition in the file window and
                keep the cursor in the taglist window itself.
  <Space>       Display the prototype of the tag under the cursor.
  u             Update the tags listed in the taglist window
  s             Change the sort order of the tags (by name or by order)
  d             Remove the tags for the file under the cursor
  x             Zoom-in or Zoom-out the taglist window
  +             Open a fold
  -             Close a fold
  *             Open all folds
  =             Close all folds
  [[		Jump to the beginning of the previous file
  <Backspace>	Jump to the beginning of the previous file
  ]]		Jump to the beginning of the next file
  <Tab>		Jump to the beginning of the next file
  q             Close the taglist window
  ?             Display help

The above keys will work in both the normal mode and the insert mode.

						*taglist-menu*
Taglist menu~
When using GUI Vim, the taglist plugin can display the tags defined in the
current file in the drop-down menu and the popup menu. By default, this
feature is turned off. To turn on this feature, set the 'Tlist_Show_Menu'
variable to 1.

You can jump to a tag by selecting the tag name from the menu. You can use the
taglist menu independent of the taglist window i.e. you don't need to open the
taglist window to get the taglist menu.

When you switch between files/buffers, the taglist menu is automatically
updated to display the tags defined in the current file/buffer.

The tags are grouped by their type (variables, functions, classes, methods,
etc) and displayed as a separate sub-menu for each type.

If the number of items in a tag type submenu exceeds the value specified by
the Tlist_Max_Submenu_Items variable, then the submenu will be split into
multiple submenus. The default setting for Tlist_Max_Submenu_Items is 25. The
first and last tag names in the submenu are used to form the submenu name. The
menu items are prefixed by alpha-numeric characters for easy selection by
keyboard.

If the popup menu support is enabled (the 'mousemodel' option contains
"popup"), then the tags menu is added to the popup menu. You can access
the popup menu by right clicking on the GUI window.

You can regenerate the tags menu by selecting the 'Tags->Refresh menu' entry.
You can sort the tags listed in the menu either by name or by order by
selecting the 'Tags->Sort menu by->Name/Order' menu entry.

You can tear-off the Tags menu and keep it on the side of the Vim window
for quickly locating the tags.

Using the taglist plugin with the winmanager plugin~
You can use the taglist plugin with the winmanager plugin. This will allow you
to use the file explorer, buffer explorer and the taglist plugin at the same
time in different windows. To use the taglist plugin with the winmanager
plugin, set 'TagList' in the 'winManagerWindowLayout' variable. For example,
to use the file explorer plugin and the taglist plugin at the same time, use
the following setting: >

	let winManagerWindowLayout = 'FileExplorer|TagList'
<
						*taglist-debug*
Debugging the taglist plugin~
You can use the ":TlistDebug" command to enable logging of the debug messages
from the taglist plugin. To display the logged debug messages, you can use the
":TlistMessages" command. To disable the logging of the debug messages, use
the ":TlistUndebug" command. The debug messages are stored in a script-local
variable by the taglist plugin. To minimize memory usage, only the last 3000
characters from the debug messages are stored.

==============================================================================
						*taglist-configure*
6. Configuration~

A number of Vim variables control the behavior of the taglist plugin. These
variables are initialized to a default value. By changing these variables you
can change the behavior of the taglist plugin. You need to change these
settings only if you want to change the behavior of the taglist plugin. You
should use the |let| command in your .vimrc file to change the setting of any
of these variables. 

The configurable taglist variables are listed below. For a detailed
description of these variables refer to the text after this table.

|'Tlist_Ctags_Cmd'|		Specifies the path to the ctags utility.
|'Tlist_Sort_Type'|		Sort method used for arranging the tags.
|'Tlist_Use_Horiz_Window'|	Use a horizontal split window for the taglist.
|'Tlist_Use_Right_Window'|	Put the taglist window on the right side.
|'Tlist_Auto_Open'|		Open the taglist window when VIM starts.
|'Tlist_Display_Prototype'|	Show prototypes, not just tags.
|'Tlist_Display_Tag_Scope'|	Show tag scope next to the tag name.
|'Tlist_Show_One_File'|		Show tags for the current buffer only.
|'Tlist_WinWidth'|		Set the taglist window width.
|'Tlist_Inc_Winwidth'|		Expand the current window to accommodate the
       				taglist.
|'Tlist_WinHeight'|		If horizontal is set, set the window height.
|'Tlist_Use_SingleClick'|	Single click on a tag jumps to it.
|'Tlist_Compact_Format'|	Remove extra information and blank lines from
       				the taglist.
|'Tlist_Exit_OnlyWindow'|	Close VIM if the taglist is the only window.
|'Tlist_File_Fold_Auto_Close'|	Close tag folds for all buffers not shown.
|'Tlist_Enable_Fold_Column'|	Show the fold indicator column.
|'Tlist_Auto_Highlight_Tag'|	Highlight the current tag in the taglist.
|'Tlist_Process_File_Always'|	Process tags for files when taglist is closed.
|'Tlist_Show_Menu'|		Display the tags menu.
|'Tlist_Max_Submenu_Items'|	Maximum number of items in a tags sub-menu.
|'Tlist_Max_Tag_Length'|	Maximum tag length used in a tag menu entry.

						*'Tlist_Ctags_Cmd'*
Tlist_Ctags_Cmd~
The 'Tlist_Ctags_Cmd' variable specifies the location (path) of the exuberant
ctags utility. If exuberant ctags is present in any one of the directories in
the PATH environment variable, then there is no need to set this variable.

The exuberant ctags tool can be installed under different names.  When the
taglist plugin starts up, if the Tlist_Ctags_Cmd variable is not set, it
checks for the names exuberant-ctags, ctags, ctags.exe and tags in the PATH
environment variable.  If any one of the named executable is found, then the
Tlist_Ctags_Cmd variable is set to that name.

If exuberant ctags is not present in one of the directories specified in the
PATH environment variable, then set this variable to point to the location of
the ctags utility in your system. Note that this variable should point to the
fully qualified exuberant ctags location and NOT to the directory in which
exuberant ctags is installed. If the exuberant ctags tool is not found in
either PATH or in the specified location, then the taglist plugin will not be
loaded.
>
	let Tlist_Ctags_Cmd = 'd:\tools\ctags.exe'
	let Tlist_Ctags_Cmd = '/usr/local/bin/ctags'
<
						*'Tlist_Sort_Type'*
Tlist_Sort_Type~
The 'Tlist_Sort_Type' variable specifies the sort order for the tags in the
taglist window. The tags can be sorted either alphabetically by their name or
by the order of their appearance in the file (chronological order). By
default, the tag names will be listed by the order in which they are defined
in the file. You can change the sort type (from name to order or from order to
name) by pressing the "s" key in the taglist window. You can also change the
default sort order by setting 'Tlist_Sort_Type' to "name" or "order": >

	let Tlist_Sort_Type = "name"
<
						*'Tlist_Use_Horiz_Window'*
Tlist_Use_Horiz_Window~
Be default, the tag names are displayed in a vertically split window. If you
prefer a horizontally split window, then set the 'Tlist_Use_Horiz_Window'
variable to 1. If you are running MS-Windows version of Vim in a MS-DOS
command window, then you should use a horizontally split window instead of a
vertically split window. Also, if you are using an older version of xterm in a
Unix system that doesn't support changing the xterm window width, you should
use a horizontally split window. >

	let Tlist_Use_Horiz_Window = 1
<
						*'Tlist_Use_Right_Window'*
Tlist_Use_Right_Window~
By default, the vertically split taglist window will appear on the left hand
side. If you prefer to open the window on the right hand side, you can set the
'Tlist_Use_Right_Window' variable to one: >

	let Tlist_Use_Right_Window = 1
<
						*'Tlist_Auto_Open'*
Tlist_Auto_Open~
To automatically open the taglist window, when you start Vim, you can set the
'Tlist_Auto_Open' variable to 1. By default, this variable is set to 0 and the
taglist window will not be opened automatically on Vim startup. >

	let Tlist_Auto_Open = 1
<
						*'Tlist_Display_Prototype'*
Tlist_Display_Prototype~
By default, only the tag name will be displayed in the taglist window. If you
like to see tag prototypes instead of names, set the 'Tlist_Display_Prototype'
variable to 1. By default, this variable is set to 0 and only tag names will
be displayed. >

	let Tlist_Display_Prototype = 1
<
						*'Tlist_Display_Tag_Scope'*
Tlist_Display_Tag_Scope~
By default, the scope of a tag (like a C++ class) will be displayed in
square brackets next to the tag name. If you don't want the tag scopes
to be displayed, then set the 'Tlist_Display_Tag_Scope' to 0. By default,
this variable is set to 1 and the tag scopes will be displayed. >

	let Tlist_Display_Tag_Scope = 0
<
						*'Tlist_Show_One_File'*
Tlist_Show_One_File~
By default, the taglist plugin will display the tags defined in all the loaded
buffers in the taglist window. If you prefer to display the tags defined only
in the current buffer, then you can set the 'Tlist_Show_One_File' to 1. When
this variable is set to 1, as you switch between buffers, the taglist window
will be refreshed to display the tags for the current buffer and the tags for
the previous buffer will be removed.
>
	let Tlist_Show_One_File = 1
<
						*'Tlist_WinWidth'*
Tlist_WinWidth~
The default width of the vertically split taglist window is 30. This can be
changed by modifying the 'Tlist_WinWidth' variable: >

	let Tlist_WinWidth = 20
<
Note that the value of the |winwidth| option setting determines the minimum
width of the current window. If you set the 'Tlist_WinWidth' variable to a
value less than that of the |winwidth| option setting, then Vim will use the
value of the |winwidth| option.

						*'Tlist_Inc_Winwidth'*
Tlist_Inc_Winwidth~
By default, when the width of the window is less than 100 and a new taglist
window is opened vertically, then the window width will be increased by the
value set in the Tlist_WinWidth variable to accommodate the new window. The
value of this variable is used only if you are using a vertically split
taglist window.

If your terminal doesn't support changing the window width from Vim (older
version of xterm running in a Unix system) or if you see any weird problems in
the screen due to the change in the window width or if you prefer not to
adjust the window width then set the 'Tlist_Inc_Winwidth' variable to 0.
CAUTION: If you are using the MS-Windows version of Vim in a MS-DOS command
window then you must set this variable to 0, otherwise the system may hang due
to a Vim limitation (explained in :help win32-problems) >

	let Tlist_Inc_Winwidth = 0
<
						*'Tlist_WinHeight'*
Tlist_WinHeight~
The default height of the horizontally split taglist window is 10. This can be
changed by modifying the 'Tlist_WinHeight' variable: >

	let Tlist_WinHeight = 20
<
						*'Tlist_Use_SingleClick'*
Tlist_Use_SingleClick~
By default, when you double click on the tag name using the left mouse 
button, the cursor will be positioned at the definition of the tag. You 
can set the Tlist_Use_SingleClick variable to 1 to jump to a tag when
you single click on the tag name using the mouse. By default this variable
is set to zero. >

	let Tlist_Use_SingleClick = 1
<
Due to a bug in Vim, if you set Tlist_Use_SingleClick to one and try to resize
the taglist window using the mouse, then Vim will crash. The fix for this bug
will be available in Vim 6.3 and above. In the meantime, instead of resizing
the taglist window using the mouse, you can use normal Vim window resizing
commands to resize the taglist window.

						*'Tlist_Compact_Format'*
Tlist_Compact_Format~
By default, empty lines are used to separate different tag types displayed for
a file and the tags displayed for different files in the taglist window. If
you want to display as many tags as possible in the taglist window, you can
set the Tlist_Compact_Format variable to one to get a compact display. >

	let Tlist_Compact_Format = 1
<
						*'Tlist_Exit_OnlyWindow'*
Tlist_Exit_OnlyWindow~
If you want to exit Vim if only the taglist window is currently opened, then
set the Tlist_Exit_OnlyWindow variable to one. By default, this variable is
set to zero and the Vim instance will not be closed if only the taglist window
is present. >

	let Tlist_Exit_OnlyWindow = 1
<
						*'Tlist_File_Fold_Auto_Close'*
Tlist_File_Fold_Auto_Close~
By default, the tags tree displayed in the taglist window for all the files is
opened. You can close/fold the tags tree for the files manually. To
automatically close the tags tree for inactive files, you can set the
Tlist_File_Fold_Auto_Close variable to 1. When this variable is set to 1, if a
Vim buffer is no longer displayed in a Vim window, the corresponding tags tree
in the taglist window will be collapsed/folded. When a buffer is loaded in a
Vim window, the corresponding tags tree will be opened.
>
	let Tlist_File_Fold_Auto_Close = 1
<
						*'Tlist_Enable_Fold_Column'*
Tlist_Enable_Fold_Column~
By default, the Vim fold column is enabled and displayed in the taglist
window. If you wish to disable this (for example, when you are working with a
narrow Vim window or terminal), you can set the Tlist_Enable_Fold_Column
variable to 0.
>
	let Tlist_Enable_Fold_Column = 1
<
						*'Tlist_Auto_Highlight_Tag'*
Tlist_Auto_Highlight_Tag~
By default, the taglist plugin will highlight the current tag in the taglist
window. If you want to disable the highlighting of the current tag, then you
can set the Tlist_Auto_Highlight_Tag variable to zero. Note that even though
the current tag highlighting is disabled, the tags for a new file will still
be added to the taglist window.
>
	let Tlist_Auto_Highlight_Tag = 0
<
						*'Tlist_Process_File_Always'*
Tlist_Process_File_Always~
By default, the taglist plugin will generate and process the tags defined in
the newly opened files only when the taglist window is opened or when the
taglist menu is enabled. When the taglist window is closed, the taglist plugin
will stop processing the tags for newly opened files.

You can set the Tlist_Process_File_Always variable to 1 to generate the list
of tags for new files even when the taglist window is closed and the taglist
menu is disabled.
>
	let Tlist_Process_File_Always = 1
<
You should set this variable to 1, if you want to use the :TlistShowTag and
:TlistShowPrototype commands without the taglist window and the taglist menu.

						*'Tlist_Show_Menu'*
Tlist_Show_Menu~
When using GUI Vim, you can display the tags defined in the current file in a
menu named "Tags". By default, this feature is turned off. To turn on this
feature, set the Tlist_Show_Menu variable to one:
>
	let Tlist_Show_Menu = 1
<
						*'Tlist_Max_Submenu_Items'*
Tlist_Max_Submenu_Items~
If a file contains too many tags of a particular type (function, variable,
class, etc.), greater than that specified by the Tlist_Max_Submenu_Items
variable, then the menu for that tag type will be split into multiple
sub-menus. The default setting for the Tlist_Max_Submenu_Items variable is 25.
This can be changed by setting the Tlist_Max_Submenu_Items variable:
>
	let Tlist_Max_Submenu_Items = 20
<
The name of the submenu is formed using the names of the first and the last
tag entries in that submenu.

						*'Tlist_Max_Tag_Length'*
Tlist_Max_Tag_Length~
Only the first Tlist_Max_Tag_Length characters from the tag names will be used
to form the tag type submenu name. Change the Tlist_Max_Tag_Length setting if
you want to include more or less characters:
>
	let Tlist_Max_Tag_Length = 10
<
==============================================================================
						*taglist-commands*
7. Commands~

The taglist plugin provides the following ex-mode commands:

|:Tlist|		Open or close (toggle) the taglist window.
|:TlistClose|		Close the taglist window.
|:TlistUpdate|		Update the tags for the current buffer.
|:TlistSync|		Highlight the current tag in the taglist window.
|:TlistShowPrototype|	Display the prototype of the tag at or below the
		    	specified line number.
|:TlistShowTag|		Display the name of the tag defined at or below the
		    	specified line number.
|:TlistSessionSave|	Save the information about files and tags in use.
|:TlistSessionLoad|	Load information about files and tags last saved.
|:TlistDebug|		Start logging of taglist debug messages.
|:TlistUndebug|		Stop logging of taglist debug messages.
|:TlistMessages|	Display the logged taglist plugin debug messages.

						*:Tlist*
:Tlist		Open or close (toggle) the taglist window. Opens the taglist
		window, if the window is not opened currently. Closes the
		taglist window, if the taglist window is already opened. When
		the taglist window is opened for the first time, all the files
		in the buffer list are processed and the tags are displayed in
		the taglist window.

						*:TlistClose*
:TlistClose	Close the taglist window. This command can be used from any
		one of the Vim windows.

						*:TlistUpdate*
:TlistUpdate	Update the tags displayed for the current buffer. This
		command can be used to force an update of the tags for the
		current file/buffer. As the taglist plugin uses the file saved
		in the disk (instead of the file displayed in a Vim buffer),
		you should save the modified buffer before you update the
		taglist window. Otherwise the listed tags will not include the
		new tags created in the buffer.

						*:TlistSync*
:TlistSync	Highlight the current tag in the taglist window. By default,
		the taglist plugin periodically updates the taglist window to
		highlight the current tag. This command can be used to force
		the taglist plugin to highlight the current tag.

						*:TlistShowPrototype*
:TlistShowPrototype [filename] [linenumber]
		Display the prototype of the tag at or below the specified
		line number. If the file name and the line number are not
		specified, then the current file name and line number are
		used. A tag spans multiple lines starting from the line where
		it is defined to the line before the next tag. This command
		displays the prototype for the tag for any line number in this
		range. 

						*:TlistShowTag*
:TlistShowTag [filename] [linenumber]
		Display the name of the tag defined at or below the specified
		line number. If the file name and the line number are not
		specified, then the current file name and line number are
		used. A tag spans multiple lines starting from the line where
		it is defined to the line before the next tag. This command
		displays the tag name for any line number in this range. 

						*:TlistSessionSave*
:TlistSessionSave {filename}
		Save the information about files and tags displayed in the
		taglist window to the specified file. This command can be used
		to save and restore the taglist window contents across Vim
		sessions.

						*:TlistSessionLoad*
:TlistSessionLoad {filename}
		Load the information about files and tags stored in the
		specified session file and update the taglist window with
		the tags stored in the session file.

						*:TlistDebug*
:TlistDebug
		Start logging of debug messages from the taglist plugin.
		The debug messages are stored in a script local variable by
		the taglist plugin.

						*:TlistUndebug*
:TlistUndebug
		Stop logging of debug messages from the taglist plugin.

						*:TlistMessages*
:TlistMessages
		Display the logged debug messages from the taglist plugin.

==============================================================================
						*taglist-functions*
8. Global functions~

The taglist plugin provides several global functions that can be used from
other Vim plugins to interact with the taglist plugin. These functions are
described below.

|Tlist_Update_File_Tags()|		Update the tags for the specified file
|Tlist_Get_Tag_Prototype_By_Line()|	Return the prototype of the tag at or
				    	below the specified line number in the
				    	specified file.
|Tlist_Get_Tagname_By_Line()|		Return the name of the tag at or below
				    	the specified line number in the
				    	specified file.
|Tlist_Set_App()|			Set the name of the app controlling
				    	the taglist window.

					    *Tlist_Update_File_Tags()*
Tlist_Update_File_Tags({filename}, {filetype})
		Update the tags for the file {filename}. The second argument
		specifies the Vim filetype for the file. If the taglist plugin
		has not processed the file previously, then the exuberant
		ctags tool is invoked to generate the tags for the file.

					    *Tlist_Get_Tag_Prototype_By_Line()*
Tlist_Get_Tag_Prototype_By_Line([{filename}, {linenumber}])
		Return the prototype of the tag at or below the specified
		line number in the specified file. If the filename and line
		number are not specified, then the current buffer name and the
		current line number are used.

					    *Tlist_Get_Tagname_By_Line()*
Tlist_Get_Tagname_By_Line([{filename}, {linenumber}])
		Return the name of the tag at or below the specified line
		number in the specified file. If the filename and line number
		are not specified, then the current buffer name and the
		current line number are used.

					    *Tlist_Set_App()*
Tlist_Set_App({appname})
		Set the name of the plugin that controls the taglist plugin
		window and buffer. This can be used to integrate the taglist
		plugin with other Vim plugins.
		
		For example, the winmanager plugin and the Cream package use
		this function and specify the appname as "winmanager" and
		"cream" respectively.
		
		By default, the taglist plugin is a stand-alone plugin and
		controls the taglist window and buffer. If the taglist window
		is controlled by an external plugin, then the appname should
		be set appropriately.

==============================================================================
						*taglist-extend*
9. Extending~

The taglist plugin supports all the languages supported by the exuberant ctags
tool, which includes the following languages: 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.

You can modify the taglist plugin support for the above listed languages. You
can also extend the taglist plugin to add support for new languages.

If you want to add support for a new language to the taglist plugin, you need
to first extend the exuberant ctags tool. For more information about extending
exuberant ctags, visit http://ctags.sourceforge.net/EXTENDING.html 

You can extend the taglist plugin to add support for new languages or modify
the support for an already supported language by setting the following
variables in the .vimrc file.

To modify the support for an already supported language, you have to set the
tlist_xxx_settings variable. Replace xxx with the Vim filetype name. To
determine the filetype name used by Vim for a file, use the following command
in the buffer containing the file: >

	:set filetype
<
For example, to modify the support for the perl language files, you have to
set the tlist_perl_settings variable.

The format of the value set in the tlist_xxx_settings variable is >

	<language_name>;flag1:name1;flag2:name2;flag3:name3
<
The different fields in the value are separated by the ';' character.

The first field 'language_name' is the name used by exuberant ctags to refer
to this language files. This name can be different from the file type name
used by Vim. For example, for C++, the language name used by ctags is 'c++'
but the filetype name used by Vim is 'cpp'.

The remaining fields follow the format "flag:name". The sub-field 'flag' is
the language specific flag used by exuberant ctags to generate the
corresponding tags. For example, for the C language, to list only the
functions, the 'f' flag is used. For more information about the flags
supported by exuberant ctags for a particular language, read the help text
from the 'ctags --help' command. The sub-field 'name' specifies the title text
to use for displaying the tags of a particular type. For example, 'name' can
be set to 'functions'. This field can be set to any text string name.

For example, to list only the classes and functions defined in a C++
language file, add the following lines to your .vimrc file >

	let tlist_cpp_settings = 'c++;c:class;f:function'
<
In the above setting, 'cpp' is the Vim filetype name and 'c++' is the name
used by the exuberant ctags tool. 'c' and 'f' are the flags passed to
exuberant ctags to list C++ classes and functions and 'class' is the title
used for the class tags and 'function' is the title used for the function tags
in the taglist window.

For example, to display only functions defined in a C file and to use "My
Functions" as the title for the function tags, use >

	let tlist_c_settings = 'c;f:My Functions'
<
When you set the tlist_xxx_settings variable, you will override the default
setting used by the taglist plugin for the 'xxx' language. You cannot add to
the default options used by the taglist plugin for a particular file type.

To add support for a new language, set the tlist_xxx_settings variable
appropriately as described above. Replace 'xxx' in the variable name with the
Vim filetype name for the new language.

For example, to extend the taglist plugin to support the latex language, you
can use the following line (assuming, you have already extended exuberant
ctags to support the latex language): >

	let tlist_tex_settings='latex;b:bibitem;c:command;l:label'
<
With the above line, when you edit files of filetype "tex" in Vim, the taglist
plugin will invoke the exuberant ctags tool passing the "latex" filetype and
the flags b, c and l to generate the tags. The text heading 'bibitem',
'command' and 'label' will be used in the taglist window for the tags which
are generated for the flags b, c and l respectively.

==============================================================================
						*taglist-faq*
10. Frequently Asked Questions~

Q. The taglist plugin doesn't work. The taglist window is empty and the tags
   defined in a file are not displayed. 
A. Are you using Vim version 6.0 and above? The taglist plugin relies on the
   features supported by Vim version 6.0 and above. 

   Are you using exuberant ctags version 5.0 and above? The taglist plugin
   relies on the features supported by exuberant ctags and will not work with
   GNU ctags or the Unix ctags utility. 

   Did you turn on the Vim filetype detection? The taglist plugin relies on
   the filetype detected by Vim and passes the filetype to the exuberant ctags
   utility to parse the tags. Add the following line to the .vimrc or _vimrc
   file to enable Vim filetype detection: >

	filetype on
<
   Is your version of Vim compiled with the support for the system() function?
   In some Linux distributions (particularly Suse Linux), the default Vim
   installation is built without the support for the system() function. The
   taglist plugin uses the system() function to invoke the exuberant ctags
   utility. You need to rebuild Vim after enabling the support for the
   system() function. If you use the default build options, the system()
   function will be supported. 

   Do you have the |shellslash| option set? You can try disabling the
   |shellslash| option. When the taglist plugin invokes the exuberant ctags
   utility with the path to the file, if the incorrect slashes are used, then
   you will see errors. 

   Are you using a Unix shell in a MS-Windows environment? For example,
   the Unix shell from the MKS-toolkit. Do you have the SHELL environment
   set to point to this shell? You can try resetting the SHELL environment
   variable.

   Is your filetype supported by the exuberant ctags utility? The file types
   supported by the exuberant ctags utility are listed in the ctags help. If a
   file type is not supported, you have to extend exuberant ctags.

   Run the following command from the shell and see whether you see
   your tags in the output from exuberant ctags:

	ctags  -f - --format=2 --excmd=pattern --fields=nks <filename>

   If you see your tags in the output from the above command, then the
   exuberant ctags utility is properly parsing your file.

   Do you have the .ctags or _ctags or the ctags.cnf file in your home
   directory for specifying default options or for extending exuberant ctags?
   If you do have this file, check the options in this file and make sure
   these options are not interfering with the operation of the taglist plugin.

   If you are using MS-Windows, check the value of the TEMP and TMP
   environment variables. If these environment variables are set to a path
   with space characters in the name, then try using the DOS 8.3 short name
   for the path or set them to a path without the space characters in the
   name. For example, if the temporary directory name is "C:\Documents and
   Settings\xyz\Local Settings\Temp", then try setting the TEMP variable to
   the following:

	set TEMP=C:\DOCUMEN~1\xyz\LOCALS~1\Temp

   If exuberant ctags is installed in a directory with space characters in the
   name, then try adding the directory to the PATH environment variable or try
   copying the exuberant ctags to a path without space characters in the name.

Q. A file has more than one tag with the same name. When I select a tag name
   from the taglist window, the cursor is positioned at the incorrect tag
   location. 
A. The taglist plugin uses the search pattern generated by the exuberant ctags
   utility to position the cursor at the location of a tag definition. If a
   file has more than one tag with the same name and same prototype, then the
   search pattern will be the same. In this case, when searching for the tag
   pattern, the cursor may be positioned at the incorrect location. 

Q. I have made some modifications to my file and introduced new
   functions/classes/variables. I have not yet saved my file. The taglist
   plugin is not displaying the new tags when I update the taglist window.
A. The exuberant ctags utility will process only files that are present in the
   disk. To list the tags defined in a file, you have to save the file and
   then update the taglist window. 

Q. I have created a ctags file using the exuberant ctags utility for my source
   tree. How do I configure the taglist plugin to use this tags file? 
A. The taglist plugin doesn't a tags file stored in disk. For every opened
   file, the taglist plugin invokes the exuberant ctags utility to get the
   list of tags dynamically. The Vim system() function is used to invoke
   exuberant ctags and get the ctags output. This function internally uses a
   temporary file to store the output. This file is deleted after the output
   from the command is read. So you will never see the file that contains the
   output of exuberant ctags.

Q. When I set the |updatetime| option to a low value (less than 1000) and if I
   keep pressing a key with the taglist window open, the current buffer
   contents are changed. Why is this?
A. The taglist plugin uses the |CursorHold| autocmd to highlight the current
   tag. The CursorHold autocmd triggers for every 'updatetime' milliseconds.
   If the 'updatetime' option is set to a low value, then the CursorHold
   autocmd will be triggered frequently. As the taglist plugin changes
   the focus to the taglist window to highlight the current tag, this could
   interfere with the key movement resulting in changing the contents of
   the current buffer. The workaround for this problem is to not set the
   'updatetime' option to a low value.

==============================================================================
						*taglist-todo*
11. Todo~

1. Support for displaying tags in a modified (not-yet-saved) file. 
2. Group tags according to the scope and display them. For example,
   group all the tags belonging to a C++/Java class 
3. Automatically open the taglist window only for selected filetypes.
   For other filetypes, close the taglist window. 
4. Taglist plugin doesn't work properly with the Vim session support.
   When a session with taglist window is saved and restored, the plugin
   doesn't update the window. 
5. When using the shell from the MKS toolkit, the taglist plugin 
   doesn't work.
6. The taglist plugin doesn't work with files edited remotely using the
   netrw plugin. The exuberant ctags utility cannot process files over
   scp/rcp/ftp, etc.

==============================================================================

vim:tw=78:ts=8:noet:ft=help: