Frequently asked questions about the taglist plugin

1. The taglist plugin doesn't work. The taglist window is empty and the tags defined in a file are not displayed.
   
   • Are you using Vim version 6.0 and above?
     The taglist plugin relies on the features supported by Vim version 6.0 and above. You can use the following command to get the Vim version:

             $ vim --version
     

   • 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. You can use the following command to determine whether the ctags installed in your system is exuberant ctags:

             $ ctags --version
     

   • Is exuberant ctags present in one of the directories in your PATH?
     If not, you need to set the Tlist_Ctags_Cmd variable to point to the location of exuberant ctags. Use the following Vim command to verify that this is setup correctly:

             :echo system(Tlist_Ctags_Cmd . ' --version') 
     

     The above command should display the version information for exuberant ctags.
   • 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. Check the output of the following Vim command:

             :filetype
     

     To turn on the filetype detection, add the following line to the .vimrc or _vimrc file:

             filetype on
     

   • Is your version of Vim compiled with the support for the system() function?
     The following Vim command should display 1:

             :echo exists('*system')
     

     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.
   • Check the shell related Vim option values using the following command:

             :set shell? shellcmdflag? shellpipe?
             :set shellquote? shellredir? shellxquote?
     

     If these options are set in your .vimrc or _vimrc file, try removing those lines.
   • 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.

     If you are using a Unix shell on MS-Windows, you should try to use exuberant ctags that is compiled for Unix-like environments so that exuberant ctags will understand path names with forward slash characters.

   • 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. You can use the following command to list the filetypes supported by exuberant ctags:

         ctags --list-languages
     

   • 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 setting the 'Tlist_Ctags_Cmd' variable to the shortest path name to ctags or try copying the exuberant ctags to a path without space characters in the name. For example, if exuberant ctags is installed in the directory "C:\Program Files\Ctags", then try setting the 'Tlist_Ctags_Cmd' variable as below:

             let Tlist_Ctags_Cmd='C:\Progra~1\Ctags\ctags.exe'
     

   • If you are using a cygwin compiled version of exuberant ctags on MS-Windows, make sure that either you have the cygwin compiled sort utility installed and available in your PATH or compile exuberant ctags with internal sort support. Otherwise, when exuberant ctags sorts the tags output by invoking the sort utility, it may end up invoking the MS-Windows version of sort.exe, thereby resulting in failure.
2. When I try to open the taglist window, I am seeing the following error message. How do I fix this problem?

      Taglist: Failed to generate tags for /my/path/to/file
      ctags: illegal option -- -^@usage: ctags [-BFadtuwvx] [-f tagsfile] file ...
   

   The taglist plugin will work only with the exuberant ctags tool. You cannot use the GNU ctags or the Unix ctags program with the taglist plugin. You will see an error message similar to the one shown above, if you try use a non-exuberant ctags program with Vim. To fix this problem, either add the exuberant ctags tool location to the PATH environment variable or set the Tlist_Ctags_Cmd variable.
3. 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.
   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.
4. 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.
   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.
5. 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?
   The taglist plugin doesn't use the tags file generated by exuberant ctags. For every opened file, the taglist plugin invokes the exuberant ctags utility to get the list of tags.
6. 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?
   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.