vim-scripts-20130814/0000755000000000000000000000000012203050723011116 5ustar vim-scripts-20130814/doc/0000755000000000000000000000000012203050723011663 5ustar vim-scripts-20130814/doc/bufexplorer.txt0000644000000000000000000007761312203050723014777 0ustar *bufexplorer.txt* Buffer Explorer Last Change: 06 May 2013 Buffer Explorer *buffer-explorer* *bufexplorer* Version 7.3.6 Plugin for easily exploring (or browsing) Vim|:buffers|. |bufexplorer-installation| Installation |bufexplorer-usage| Usage |bufexplorer-windowlayout| Window Layout |bufexplorer-customization| Customization |bufexplorer-changelog| Change Log |bufexplorer-todo| Todo |bufexplorer-credits| Credits For Vim version 7.0 and above. This plugin is only available if 'compatible' is not set. {Vi does not have any of this} ============================================================================== INSTALLATION *bufexplorer-installation* To install: - Download the bufexplorer.zip from: http://www.vim.org/scripts/script.php?script_id=42 - Extract the zip archive into your runtime directory. The archive contains plugin/bufexplorer.vim, and doc/bufexplorer.txt. - Start Vim or goto an existing instance of Vim. - Execute the following command: > :helptag /doc < This will generate all the help tags for any file located in the doc directory. ============================================================================== USAGE *bufexplorer-usage* To start exploring in the current window, use: > \be or :BufExplorer or Your custom key mapping To start exploring in a newly split horizontal window, use: > \bs or :BufExplorerHorizontalSplit or Your custom key mapping To start exploring in a newly split vertical window, use: > \bv or :BufExplorerVerticalSplit or Your custom key mapping If you would like to use something other than '\', you may simply change the leader (see |mapleader|). Note: If the current buffer is modified when bufexplorer started, the current window is always split and the new bufexplorer is displayed in that new window. Commands to use once exploring: Toggle help information. Opens the buffer that is under the cursor into the current window. Opens the buffer that is under the cursor into the current window. Opens the buffer that is under the cursor in another tab. B Works in association with the|ShowTabBuffer|option. If |ShowTabBuffer|is set to 1, this toggles if BufExplorer is to only store the most recent tab for this buffer or not. d |:delete|the buffer under the cursor from the list. The buffer's 'buflisted' is cleared. This allows for the buffer to be displayed again using the 'show unlisted' command. D |:wipeout|the buffer under the cursor from the list. When a buffers is wiped, it will not be shown when unlisted buffer are displayed. f Toggles whether you are taken to the active window when selecting a buffer or not. o Opens the buffer that is under the cursor into the current window. p Toggles the showing of a split filename/pathname. q Exit/Close bufexplorer. r Reverses the order the buffers are listed in. R Toggles relative path/absolute path. s Cycle thru how the buffers are listed. Either by buffer number, file name, file extension, most recently used (MRU), or full path. S Cycle thru how the buffers are listed, in reverse order. Either by buffer number, file name, file extension, most recently used (MRU), or full path. T Toggles to show only buffers for this tab or not. t Opens the buffer that is under the cursor in another tab. u Toggles the showing of "unlisted" buffers. Once invoked, Buffer Explorer displays a sorted list (MRU is the default sort method) of all the buffers that are currently opened. You are then able to move the cursor to the line containing the buffer's name you are wanting to act upon. Once you have selected the buffer you would like, you can then either open it, close it(delete), resort the list, reverse the sort, quit exploring and so on... =============================================================================== WINDOW LAYOUT *bufexplorer-windowlayout* ------------------------------------------------------------------------------- " Press for Help " Sorted by mru | Locate buffer | Absolute Split path "= 01 %a bufexplorer.txt C:\Vim\vimfiles\doc line 87 02 # bufexplorer.vim c:\Vim\vimfiles\plugin line 1 ------------------------------------------------------------------------------- | | | | | | | | | +-- Current Line #. | | | +-- Relative/Full Path | | +-- Buffer Name. | +-- Buffer Attributes. See|:buffers|for more information. +-- Buffer Number. See|:buffers|for more information. =============================================================================== CUSTOMIZATION *bufexplorer-customization* If you do not like the default key mappings of \be, \bs, and \bv, you can override bufexplorer's default mappings by setting up something like the following in your vimrc file: noremap :BufExplorer noremap :BufExplorerHorizontalSplit noremap :BufExplorerVerticalSplit *g:bufExplorerChgWin* If set, bufexplorer will bring up the selected buffer in the window specified by g:bufExplorerChgWin. *g:bufExplorerDefaultHelp* To control whether the default help is displayed or not, use: > let g:bufExplorerDefaultHelp=0 " Do not show default help. let g:bufExplorerDefaultHelp=1 " Show default help. The default is to show the default help. *g:bufExplorerDetailedHelp* To control whether detailed help is display by, use: > let g:bufExplorerDetailedHelp=0 " Do not show detailed help. let g:bufExplorerDetailedHelp=1 " Show detailed help. The default is NOT to show detailed help. *g:bufExplorerFindActive* To control whether you are taken to the active window when selecting a buffer, use: > let g:bufExplorerFindActive=0 " Do not go to active window. let g:bufExplorerFindActive=1 " Go to active window. The default is to be taken to the active window. *g:bufExplorerFuncRef* When a buffer is selected, the functions specified either singly or as a list will be called. *g:bufExplorerReverseSort* To control whether to sort the buffer in reverse order or not, use: > let g:bufExplorerReverseSort=0 " Do not sort in reverse order. let g:bufExplorerReverseSort=1 " Sort in reverse order. The default is NOT to sort in reverse order. *g:bufExplorerShowDirectories* Directories usually show up in the list from using a command like ":e .". To control whether to show directories in the buffer list or not, use: > let g:bufExplorerShowDirectories=0 " Do not show directories. let g:bufExplorerShowDirectories=1 " Show directories. The default is to show directories. *g:bufExplorerShowNoName* To control whether to show "No Name" buffers or not, use: > let g:bufExplorerShowNoName=0 " Do not "No Name" buffers. let g:bufExplorerShowNoName=1 " Show "No Name" buffers. The default is to NOT show "No Name buffers. *g:bufExplorerShowRelativePath* To control whether to show absolute paths or relative to the current directory, use: > let g:bufExplorerShowRelativePath=0 " Show absolute paths. let g:bufExplorerShowRelativePath=1 " Show relative paths. The default is to show absolute paths. *g:bufExplorerShowTabBuffer* To control weither or not to show buffers on for the specific tab or not, use: > let g:bufExplorerShowTabBuffer=0 " No. let g:bufExplorerShowTabBuffer=1 " Yes. The default is not to show. *g:bufExplorerShowUnlisted* To control whether to show unlisted buffer or not, use: > let g:bufExplorerShowUnlisted=0 " Do not show unlisted buffers. let g:bufExplorerShowUnlisted=1 " Show unlisted buffers. The default is to NOT show unlisted buffers. *g:bufExplorerSortBy* To control what field the buffers are sorted by, use: > let g:bufExplorerSortBy='extension' " Sort by file extension. let g:bufExplorerSortBy='fullpath' " Sort by full file path name. let g:bufExplorerSortBy='mru' " Sort by most recently used. let g:bufExplorerSortBy='name' " Sort by the buffer's name. let g:bufExplorerSortBy='number' " Sort by the buffer's number. The default is to sort by mru. *g:bufExplorerSplitBelow* To control where the new split window will be placed above or below the current window, use: > let g:bufExplorerSplitBelow=1 " Split new window below current. let g:bufExplorerSplitBelow=0 " Split new window above current. The default is to use whatever is set by the global &splitbelow variable. *g:bufExplorerSplitHorzSize* To control the size of the new horizontal split window. use: > let g:bufExplorerHorzSize=n " New split window is n rows high. let g:bufExplorerHorzSize=0 " New split window size set by Vim. The default is 0, so that the size is set by Vim. *g:bufExplorerSplitOutPathName* To control whether to split out the path and file name or not, use: > let g:bufExplorerSplitOutPathName=1 " Split the path and file name. let g:bufExplorerSplitOutPathName=0 " Don't split the path and file " name. The default is to split the path and file name. *g:bufExplorerSplitRight* To control where the new vsplit window will be placed to the left or right of current window, use: > let g:bufExplorerSplitRight=0 " Split left. let g:bufExplorerSplitRight=1 " Split right. The default is to use the global &splitright. *g:bufExplorerSplitVertSize* To control the size of the new vertical split window. use: > let g:bufExplorerVertSize=n " New split window is n columns wide. let g:bufExplorerVertSize=0 " New split windows size set by Vim. The default is 0, so that the size is set by Vim. =============================================================================== CHANGE LOG *bufexplorer-changelog* 7.3.6 May, 06, 2013 * Removed the 'drop' window command that was causing issue with the argument-list being modified after the BufExplorer windows was displayed. 7.3.5 February 08, 2013 * Michael Henry added the ability to view "No Name" buffers. This functionality was lost since version 7.3.0. He also did some removal of "dead" code and cleaned up the code to handle filenames with embedded '"'. 7.3.4 January 28, 2013 * Thanks go out to John Szakmeister for finding and fixing a bug in the RebuildBufferList method. The keepjumps line that clears the list could potentially reference a backwards range. 7.3.3 January 14, 2013 * Major cleanup and reorganization of the change log. * We welcome the return of g:bufExplorerSplitHorzSize and g:bufExplorerSplitVertSize. When setting these values, anything less than or equal to 0 causes the split windows size to be determined by Vim. If for example you want your new horizontal split window 10 rows high, set g:bufExplorerSplitHorzSize = 10 in your .vimrc. Similar would be done if wanting a vertical split except you would use the g:bufExplorerSplitVertSize variable instead. 7.3.2 December 24, 2012 * Thanks go out to Michael Henry for pointing out that I completely missed yet another function, ReverseSortSelect(), during the refactoring. This function has now returned. 7.3.1 December 06, 2012 * Thanks go out to Brett Rasmussen for pointing out that the feature added way back in version 7.2.3 by Yuriy Ershov to automatically reposition the cursor to the line containing the active buffer, was no longer in the plugin. That bit of code has been re-added and all is well. 7.3.0 October 09, 2012 * It has been quite a while since I published a new version and this is the first version since Vim 7.3 was released. I have put some time into reworking and cleaning up the code as well as various bug fixes. Overall, I am hopeful that I not forgotten or lost a feature. * Thanks to Tim Johnson for testing out this new version. * I have hopefully allowed for better mapping of the main public methods as is explained in the|bufexplorer-customization|section of the documentation. * Add new 'B', 'o', and 'S' key mappings. 7.2.8 November 08, 2010 * Thanks to Charles Campbell for integrating bufexplorer with GDBMGR. http://mysite.verizon.net/astronaut/vim/index.html#GDBMGR 7.2.7 April 26, 2010 * My 1st attempt to fix the "cache" issue where buffers information has changed but the cache/display does not reflect those changes. More work still needs to be done. 7.2.6 February 12, 2010 * Thanks to Michael Henry for pointing out that I totally forgot to update the inline help to reflect the previous change to the 'd' and 'D' keys. Opps! 7.2.5 February 10, 2010 * Philip Morant suggested switching the command (bwipe) associated with the 'd' key with the command (bdelete) associated with the 'D' key. This made sense since the 'd' key is more likely to be used compared to the 'D' key. 7.2.4 January 14, 2010 * I did not implement the patch provided by Godefroid Chapelle correctly. I missed one line which happened to be the most important one :) 7.2.3 December 15, 2009 * Hopefully I have not left anyone or anything out :) * Thanks to David Fishburn for helping me out with a much needed code overhaul as well as some awesome performance enhancements. * David also reworked the handling of tabs. * Thanks to Vladimir Dobriakov for making the suggestions on enhancing the documentation to include a better explaination of what is contained in the main bufexplorer window. * Thanks to Yuriy Ershov for added code that when the bufexplorer window is opened, the cursor is now positioned at the line with the active buffer (useful in non-MRU sort modes). * Yuriy also added the abiltiy to cycle through the sort fields in reverse order. * Thanks to Michael Henry for supplying a patch that allows bufexplorer to be opened even when there is one buffer or less. * Thanks to Godefroid Chapelle for supplying a patch that fixed MRU sort order after loading a session. 7.2.2 November 19, 2008 * Thanks to David L. Dight for spotting and fixing an issue when using ctrl^. bufexplorer would incorrectly handle the previous buffer so that when ctrl^ was pressed the incorrect file was opened. 7.2.1 September 03, 2008 * Thanks to Dimitar for spotting and fixing a feature that was inadvertently left out of the previous version. The feature was when bufexplorer was used together with WinManager, you could use the tab key to open a buffer in a split window. 7.2.0 August 15, 2008 * For all those missing the \bs and \bv commands, these have now returned. Thanks to Phil O'Connell for asking for the return of these missing features and helping test out this version. * Fixed problem with the bufExplorerFindActive code not working correctly. * Fixed an incompatibility between bufexplorer and netrw that caused buffers to be incorrectly removed from the MRU list. 7.1.7 December 21, 2007 * TaCahiroy fixed several issues related to opening a buffer in a tab. 7.1.6 December 01, 2007 * Removed ff=unix from modeline in bufexplorer.txt. Found by Bill McCarthy. 7.1.5 November 30, 2007 * Could not open unnamed buffers. Fixed by TaCahiroy. 7.1.4 November 16, 2007 * Sometimes when a file's path has 'white space' in it, extra buffers would be created containing each piece of the path. i.e: opening c:\document and settings\test.txt would create a buffer named "and" and a buffer named "Documents". This was reported and fixed by TaCa Yoss. 7.1.3 November 15, 2007 * Added code to allow only one instance of the plugin to run at a time. Thanks Dennis Hostetler. 7.1.2 November 07, 2007 * Dave Larson added handling of tabs. * Dave Larson removed \bs and \bv commands because these are easier for the used to create horizontal and vertical windows. * Fixed a jumplist issue spotted by JiangJun. I overlooked the 'jumplist' and with a couple calls to 'keepjumps', everything is fine again. * Went back to using just a plugin file, instead of both an autoload and plugin file. The splitting of the file caused issues with other plugins. So if you have a prior version of bufexplorer that has an autoload file, please remove autoload\bufexplorer and plugin\bufexplorer before installing this new version. * Fixed E493 error spotted by Thomas Arendsen Hein. * Minor cosmetic changes. * Minor help file changes. 7.1.1 August 02, 2007 * A problem spotted by Thomas Arendsen Hein. When running Vim (7.1.94), error E493 was being thrown. * Added 'D' for 'delete' buffer as the 'd' command was a 'wipe' buffer. 7.1.0 August 01, 2007 * Another 'major' update, some by Dave Larson, some by me. * Making use of 'autoload' now to make the plugin load quicker. * Removed '\bs' and '\bv'. These are now controlled by the user. The user can issue a ':sp' or ':vs' to create a horizontal or vertical split window and then issue a '\be' * Added handling of tabs. 7.0.17 July 24, 2007 * Fixed issue with 'drop' command. * Various enhancements and improvements. 7.0.16 May 15, 2007 * Fixed issue reported by Liu Jiaping on non Windows systems, which was ... Open file1, open file2, modify file1, open bufexplorer, you get the following error: --------8<-------- Error detected while processing function 14_StartBufExplorer..14_SplitOpen: line 4: E37: No write since last change (add ! to override) But the worse thing is, when I want to save the current buffer and type ':w', I get another error message: E382: Cannot write, 'buftype' option is set --------8<-------- 7.0.15 April 27, 2007 * Thanks to Mark Smithfield for suggesting bufexplorer needed to handle the ':args' command. 7.0.14 March 23, 2007 * Thanks to Randall Hansen for removing the requirement of terminal versions to be recompiled with 'gui' support so the 'drop' command would work. The 'drop' command is really not needed in terminal versions. 7.0.13 February 23, 2007 * Fixed integration with WinManager. * Thanks to Dave Eggum for another update. - Fix: The detailed help didn't display the mapping for toggling the split type, even though the split type is displayed. - Fixed incorrect description in the detailed help for toggling relative or full paths. - Deprecated s:ExtractBufferNbr(). Vim's str2nr() does the same thing. - Created a s:Set() function that sets a variable only if it hasn't already been defined. It's useful for initializing all those default settings. - Removed checks for repetitive command definitions. They were unnecessary. - Made the help highlighting a little more fancy. - Minor reverse compatibility issue: Changed ambiguous setting names to be more descriptive of what they do (also makes the code easier to follow): Changed bufExplorerSortDirection to bufExplorerReverseSort Changed bufExplorerSplitType to bufExplorerSplitVertical Changed bufExplorerOpenMode to bufExplorerUseCurrentWindow - When the BufExplorer window closes, all the file-local marks are now deleted. This may have the benefit of cleaning up some of the jumplist. - Changed the name of the parameter for StartBufExplorer from "split" to "open". The parameter is a string which specifies how the buffer will be open, not if it is split or not. - Deprecated DoAnyMoreBuffersExist() - it is a one line function only used in one spot. - Created four functions (SplitOpen(), RebuildBufferList(), UpdateHelpStatus() and ReSortListing()) all with one purpose - to reduce repeated code. - Changed the name of AddHeader() to CreateHelp() to be more descriptive of what it does. It now returns an array instead of updating the window directly. This has the benefit of making the code more efficient since the text the function returns is used a little differently in the two places the function is called. - Other minor simplifications. 7.0.12 November 30, 2006 * MAJOR Update. This version will ONLY run with Vim version 7.0 or greater. * Dave Eggum has made some 'significant' updates to this latest version: - Added BufExplorerGetAltBuf() global function to be used in the users rulerformat. - Added g:bufExplorerSplitRight option. - Added g:bufExplorerShowRelativePath option with mapping. - Added current line highlighting. - The split type can now be changed whether bufexplorer is opened in split mode or not. - Various major and minor bug fixes and speed improvements. - Sort by extension. * Other improvements/changes: - Changed the help key from '?' to to be more 'standard'. - Fixed splitting of vertical bufexplorer window. * Hopefully I have not forgot something :) 7.0.11 March 10, 2006 * Fixed a couple of highlighting bugs, reported by David Eggum. * Dave Eggum also changed passive voice to active on a couple of warning messages. 7.0.10 March 02, 2006 * Fixed bug report by Xiangjiang Ma. If the 'ssl' option is set, the slash character used when displaying the path was incorrect. 7.0.9 February 28, 2006 * Martin Grenfell found and eliminated an annoying bug in the bufexplorer/winmanager integration. The bug was were an annoying message would be displayed when a window was split or a new file was opened in a new window. Thanks Martin! 7.0.8 January 18, 2006 * Thanks to Mike Li for catching a bug in the WinManager integration. The bug was related to the incorrect displaying of the buffer explorer's window title. 7.0.7 December 19, 2005 * Thanks to Jeremy Cowgar for adding a new enhancement. This enhancement allows the user to press 'S', that is capital S, which will open the buffer under the cursor in a newly created split window. 7.0.6 November 18, 2005 * Thanks to Larry Zhang for finding a bug in the "split" buffer code. If you force set g:bufExplorerSplitType='v' in your vimrc, and if you tried to do a \bs to split the bufexplorer window, it would always split horizontal, not vertical. * Larry Zhang also found that I had a typeo in that the variable g:bufExplorerSplitVertSize was all lower case in the documentation which was incorrect. 7.0.5 October 18, 2005 * Thanks to Mun Johl for pointing out a bug that if a buffer was modified, the '+' was not showing up correctly. 7.0.4 October 03, 2005 * Fixed a problem discovered first by Xiangjiang Ma. Well since I've been using vim 7.0 and not 6.3, I started using a function (getftype) that is not in 6.3. So for backward compatibility, I conditionaly use this function now. Thus, the g:bufExplorerShowDirectories feature is only available when using vim 7.0 and above. 7.0.3 September 30, 2005 * Thanks to Erwin Waterlander for finding a problem when the last buffer was deleted. This issue got me to rewrite the buffer display logic (which I've wanted to do for sometime now). * Also great thanks to Dave Eggum for coming up with idea for g:bufExplorerShowDirectories. Read the above information about this feature. 7.0.2 March 25, 2005 * Thanks to Thomas Arendsen Hein for finding a problem when a user has the default help turned off and then brought up the explorer. An E493 would be displayed. 7.0.1 March 10, 2005 * Thanks to Erwin Waterlander for finding a couple problems. The first problem allowed a modified buffer to be deleted. Opps! The second problem occurred when several files were opened, BufExplorer was started, the current buffer was deleted using the 'd' option, and then BufExplorer was exited. The deleted buffer was still visible while it is not in the buffers list. Opps again! 7.0.0 March 10, 205 * Thanks to Shankar R. for suggesting to add the ability to set the fixed width (g:bufExplorerSplitVertSize) of a new window when opening bufexplorer vertically and fixed height (g:bufExplorerSplitHorzSize) of a new window when opening bufexplorer horizontally. By default, the windows are normally split to use half the existing width or height. 6.3.0 July 23, 2004 * Added keepjumps so that the jumps list would not get cluttered with bufexplorer related stuff. 6.2.3 April 15, 2004 * Thanks to Jay Logan for finding a bug in the vertical split position of the code. When selecting that the window was to be split vertically by doing a '\bv', from then on, all splits, i.e. '\bs', were split vertically, even though g:bufExplorerSplitType was not set to 'v'. 6.2.2 January 09, 2004 * Thanks to Patrik Modesto for adding a small improvement. For some reason his bufexplorer window was always showing up folded. He added 'setlocal nofoldenable' and it was fixed. 6.2.1 October 09, 2003 * Thanks goes out to Takashi Matsuo for added the 'fullPath' sorting logic and option. 6.2.0 June 13, 2003 * Thanks goes out to Simon Johann-Ganter for spotting and fixing a problem in that the last search pattern is overridden by the search pattern for blank lines. 6.1.6 May 05, 2003 * Thanks to Artem Chuprina for finding a pesky bug that has been around for sometime now. The key mapping was causing the buffer explored to close prematurely when vim was run in an xterm. The key mapping is now removed. 6.1.5 April 28, 2003 * Thanks to Khorev Sergey. Added option to show default help or not. 6.1.4 March 18, 2003 * Thanks goes out to Valery Kondakoff for suggesting the addition of setlocal nonumber and foldcolumn=0. This allows for line numbering and folding to be turned off temporarily while in the explorer. 6.1.3 March 11, 2003 * Added folding. * Did some code cleanup. * Added the ability to force the newly split window to be temporarily vertical, which was suggested by Thomas Glanzmann. 6.1.2 November 05, 2002 * Now pressing the key will quit, just like 'q'. * Added folds to hide winmanager configuration. * If anyone had the 'C' option in their cpoptions they would receive a E10 error on startup of BufExplorer. cpo is now saved, updated and restored. Thanks to Charles E Campbell, Jr. * Attempted to make sure there can only be one BufExplorer window open at a time. 6.1.1 March 28, 2002 * Thanks to Brian D. Goodwin for adding toupper to FileNameCmp. This way buffers sorted by name will be in the correct order regardless of case. 6.0.16 March 14, 2002 * Thanks to Andre Pang for the original patch/idea to get bufexplorer to work in insertmode/modeless mode (evim). * Added Initialize and Cleanup autocommands to handle commands that need to be performed when starting or leaving bufexplorer. 6.0.15 February 20, 2002 * Srinath Avadhanulax added a patch for winmanager.vim. 6.0.14 February 19, 2002 * Fix a few more bug that I thought I already had fixed. * Thanks to Eric Bloodworth for adding 'Open Mode/Edit in Place'. * Added vertical splitting. 6.0.13 February 05, 2002 * Thanks to Charles E Campbell, Jr. for pointing out some embarrassing typos that I had in the documentation. I guess I need to run the spell checker more :o) 6.0.12 February 04, 2002 * Thanks to Madoka Machitani, for the tip on adding the augroup command around the MRUList autocommands. 6.0.11 January 26, 2002 * Fixed bug report by Xiangjiang Ma. '"=' was being added to the search history which messed up hlsearch. 6.0.10 January 14, 2002 * Added the necessary hooks so that the Srinath Avadhanula's winmanager.vim script could more easily integrate with this script. * Tried to improve performance. 6.0.9 December 17, 2001 * Added MRU (Most Recently Used) sort ordering. 6.0.8 December 03, 2001 * Was not resetting the showcmd command correctly. * Added nifty help file. 6.0.7 November 19, 2001 * Thanks to Brett Carlane for some great enhancements. Some are added, some are not, yet. Added highlighting of current and alternate filenames. Added splitting of path/filename toggle. Reworked ShowBuffers(). * Changed my email address. 6.0.6 September 05, 2001 * Copyright notice added. Needed this so that it could be distributed with Debian Linux. Fixed problem with the SortListing() function failing when there was only one buffer to display. 6.0.5 August 10, 2001 * Fixed problems reported by David Pascoe, in that you where unable to hit 'd' on a buffer that belonged to a files that no longer existed and that the 'yank' buffer was being overridden by the help text when the bufexplorer was opened. 6.0.4 July, 31, 2001 * Thanks to Charles Campbell, Jr. for making this plugin more plugin *compliant*, adding default keymappings of be and bs as well as fixing the 'w:sortDirLabel not being defined' bug. 6.0.3 July 30, 2001 * Added sorting capabilities. Sort taken from explorer.vim. 6.0.2 July 25, 2001 * Can't remember. 6.0.1 Sometime before July 25, 2001 * Initial release. =============================================================================== TODO *bufexplorer-todo* - Nothing as of now, buf if you have any suggestions, drop me an email. =============================================================================== CREDITS *bufexplorer-credits* Author: Jeff Lanzarotta Credit must go out to Bram Moolenaar and all the Vim developers for making the world's best editor (IMHO). I also want to thank everyone who helped and gave me suggestions. I wouldn't want to leave anyone out so I won't list names. =============================================================================== vim:tw=78:noet:wrap:ts=4:ft=help:norl: vim-scripts-20130814/doc/surround.txt0000644000000000000000000002247612203050723014320 0ustar *surround.txt* Plugin for deleting, changing, and adding "surroundings" Author: Tim Pope License: Same terms as Vim itself (see |license|) This plugin is only available if 'compatible' is not set. INTRODUCTION *surround* This plugin is a tool for dealing with pairs of "surroundings." Examples of surroundings include parentheses, quotes, and HTML tags. They are closely related to what Vim refers to as |text-objects|. Provided are mappings to allow for removing, changing, and adding surroundings. Details follow on the exact semantics, but first, consider the following examples. An asterisk (*) is used to denote the cursor position. Old text Command New text ~ "Hello *world!" ds" Hello world! [123+4*56]/2 cs]) (123+456)/2 "Look ma, I'm *HTML!" cs" Look ma, I'm HTML! if *x>3 { ysW( if ( x>3 ) { my $str = *whee!; vllllS' my $str = 'whee!'; While a few features of this plugin will work in older versions of Vim, Vim 7 is recommended for full functionality. MAPPINGS *surround-mappings* Delete surroundings is *ds* . The next character given determines the target to delete. The exact nature of the target is explained in |surround-targets| but essentially it is the last character of a |text-object|. This mapping deletes the difference between the "i"nner object and "a"n object. This is easiest to understand with some examples: Old text Command New text ~ "Hello *world!" ds" Hello world! (123+4*56)/2 ds) 123+456/2
Yo!*
dst Yo! Change surroundings is *cs* . It takes two arguments, a target like with |ds|, and a replacement. Details about the second argument can be found below in |surround-replacements|. Once again, examples are in order. Old text Command New text ~ "Hello *world!" cs"' 'Hello world!' "Hello *world!" cs" Hello world! (123+4*56)/2 cs)] [123+456]/2 (123+4*56)/2 cs)[ [ 123+456 ]/2
Yo!*
cst

Yo!

*ys* takes a valid Vim motion or text object as the first object, and wraps it using the second argument as with |cs|. (It's a stretch, but a good mnemonic for "ys" is "you surround".) Old text Command New text ~ Hello w*orld! ysiw) Hello (world)! As a special case, *yss* operates on the current line, ignoring leading whitespace. Old text Command New text ~ Hello w*orld! yssB {Hello world!} There is also *yS* and *ySS* which indent the surrounded text and place it on a line of its own. In visual mode, a simple "S" with an argument wraps the selection. This is referred to as the *vS* mapping, although ordinarily there will be additional keystrokes between the v and S. In linewise visual mode, the surroundings are placed on separate lines and indented. In blockwise visual mode, each line is surrounded. A "gS" in visual mode, known as *vgS* , behaves similarly. In linewise visual mode, the automatic indenting is suppressed. In blockwise visual mode, this enables surrounding past the end of the line with 'virtualedit' set (there seems to be no way in Vim Script to differentiate between a jagged end of line selection and a virtual block selected past the end of the line, so two maps were needed). *i_CTRL-G_s* *i_CTRL-G_S* Finally, there is an experimental insert mode mapping on s and . Beware that the latter won't work on terminals with flow control (if you accidentally freeze your terminal, use to unfreeze it). The mapping inserts the specified surroundings and puts the cursor between them. If, immediately after the mapping and before the replacement, a second or carriage return is pressed, the prefix, cursor, and suffix will be placed on three separate lines. S (not s) also exhibits this behavior. TARGETS *surround-targets* The |ds| and |cs| commands both take a target as their first argument. The possible targets are based closely on the |text-objects| provided by Vim. All targets are currently just one character. Eight punctuation marks, (, ), {, }, [, ], <, and >, represent themselves and their counterparts. If the opening mark is used, contained whitespace is also trimmed. The targets b, B, r, and a are aliases for ), }, ], and > (the first two mirror Vim; the second two are completely arbitrary and subject to change). Three quote marks, ', ", `, represent themselves, in pairs. They are only searched for on the current line. A t is a pair of HTML or XML tags. See |tag-blocks| for details. Remember that you can specify a numerical argument if you want to get to a tag other than the innermost one. The letters w, W, and s correspond to a |word|, a |WORD|, and a |sentence|, respectively. These are special in that they have nothing to delete, and used with |ds| they are a no-op. With |cs|, one could consider them a slight shortcut for ysi (cswb == ysiwb, more or less). A p represents a |paragraph|. This behaves similarly to w, W, and s above; however, newlines are sometimes added and/or removed. REPLACEMENTS *surround-replacements* A replacement argument is a single character, and is required by |cs|, |ys|, and |vS|. Undefined replacement characters (with the exception of alphabetic characters) default to placing themselves at the beginning and end of the destination, which can be useful for characters like / and |. If either ), }, ], or > is used, the text is wrapped in the appropriate pair of characters. Similar behavior can be found with (, {, and [ (but not <), which append an additional space to the inside. Like with the targets above, b, B, r, and a are aliases for ), }, ], and >. To fulfill the common need for code blocks in C-style languages, (which is really ) adds braces on lines separate from the content. If t or < is used, Vim prompts for an HTML/XML tag to insert. You may specify attributes here and they will be stripped from the closing tag. End your input by pressing or >. If is used, the tags will appear on lines by themselves. If s is used, a leading but not trailing space is added. This is useful for removing parentheses from a function call with csbs. CUSTOMIZING *surround-customizing* The following adds a potential replacement on "-" (ASCII 45) in PHP files. (To determine the ASCII code to use, :echo char2nr("-")). The carriage return will be replaced by the original text. > autocmd FileType php let b:surround_45 = "" < This can be used in a PHP file as in the following example. Old text Command New text ~ print "Hello *world!" yss- Additionally, one can use a global variable for globally available replacements. > let g:surround_45 = "<% \r %>" let g:surround_61 = "<%= \r %>" < Advanced, experimental, and subject to change: One can also prompt for replacement text. The syntax for this is to surround the replacement in pairs of low numbered control characters. If this sounds confusing, that's because it is (but it makes the parsing easy). Consider the following example for a LaTeX environment on the "l" replacement. > let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\1}" < When this replacement is used, the user is prompted with an "environment: " prompt for input. This input is inserted between each set of \1's. Additional inputs up to \7 can be used. Furthermore, one can specify a regular expression substitution to apply. > let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\r}.*\r\1}" < This will remove anything after the first } in the input when the text is placed within the \end{} slot. The first \r marks where the pattern begins, and the second where the replacement text begins. Here's a second example for creating an HTML
. The substitution cleverly prompts for an id, but only adds id="" if it is non-blank. You may have to read this one a few times slowly before you understand it. > let g:surround_{char2nr("d")} = "\r
" < Inputting text replacements is a proof of concept at this point. The ugly, unintuitive interface and the brevity of the documentation reflect this. Finally, It is possible to always append a string to surroundings in insert mode (and only insert mode). This is useful with certain plugins and mappings that allow you to jump to such markings. > let g:surround_insert_tail = "<++>" < ISSUES *surround-issues* Vim could potentially get confused when deleting/changing occurs at the very end of the line. Please report any repeatable instances of this. Do we need to use |inputsave()|/|inputrestore()| with the tag replacement? Indenting is handled haphazardly. Need to decide the most appropriate behavior and implement it. Right now one can do :let b:surround_indent = 1 (or the global equivalent) to enable automatic re-indenting by Vim via |=|; should this be the default? vim:tw=78:ts=8:ft=help:norl: vim-scripts-20130814/doc/supertab.txt0000644000000000000000000003632312203050723014260 0ustar *supertab.txt* Author: Eric Van Dewoestine Original concept and versions up to 0.32 written by Gergely Kontra This plugin is licensed under the terms of the BSD License. Please see supertab.vim for the license in its entirety. ============================================================================== Supertab *supertab* 1. Introduction |supertab-intro| 2. Supertab Usage |supertab-usage| 3. Supertab Options |supertab-options| Default completion type |supertab-defaultcompletion| Secondary default completion type |supertab-contextdefault| Completion contexts |supertab-completioncontexts| Context text |supertab-contexttext| Context Discover |supertab-contextdiscover| Example |supertab-contextexample| Completion Duration |supertab-duration| Preventing Completion After/Before... |supertab-preventcomplete| Changing default mapping |supertab-forwardbackward| Inserting true tabs |supertab-mappingtabliteral| Enhanced longest match support |supertab-longestenhanced| Preselecting the first entry |supertab-longesthighlight| Mapping to end completion |supertab-crmapping| Auto close the preview window |supertab-closepreviewonpopupclose| Completion Chaining |supertab-completionchaining| ============================================================================== 1. Introduction *supertab-intro* Supertab is a plugin which allows you to perform all your insert completion (|ins-completion|) using the tab key. Supertab requires Vim version 7.0 or above. ============================================================================== 2. Supertab usage *supertab-usage* Using Supertab is as easy as hitting or (shift+tab) while in insert mode, with at least one non whitespace character before the cursor, to start the completion and then or again to cycle forwards or backwards through the available completions. Example ('|' denotes the cursor location): bar baz b| Hitting here will start the completion, allowing you to then cycle through the suggested words ('bar' and 'baz'). ============================================================================== 3. Supertab Options *supertab-options* Supertab is configured via several global variables that you can set in your |vimrc| file according to your needs. Below is a comprehensive list of the variables available. Default Completion Type *supertab-defaultcompletion* *g:SuperTabDefaultCompletionType* g:SuperTabDefaultCompletionType (default value: "") Used to set the default completion type. There is no need to escape this value as that will be done for you when the type is set. Example: setting the default completion to 'user' completion: let g:SuperTabDefaultCompletionType = "" Note: a special value of 'context' is supported which will result in super tab attempting to use the text preceding the cursor to decide which type of completion to attempt. Currently super tab can recognize method calls or attribute references via '.', '::' or '->', and file path references containing '/'. let g:SuperTabDefaultCompletionType = "context" /usr/l # will use filename completion myvar.t # will use user completion if completefunc set, # or omni completion if omnifunc set. myvar-> # same as above When using context completion, super tab will fall back to a secondary default completion type set by |g:SuperTabContextDefaultCompletionType|. Note: once the buffer has been initialized, changing the value of this setting will not change the default complete type used. If you want to change the default completion type for the current buffer after it has been set, perhaps in an ftplugin, you'll need to call SuperTabSetDefaultCompletionType like so, supplying the completion type you wish to switch to: call SuperTabSetDefaultCompletionType("") Secondary default completion type *supertab-contextdefault* *g:SuperTabContextDefaultCompletionType* g:SuperTabContextDefaultCompletionType (default value: "") Sets the default completion type used when g:SuperTabDefaultCompletionType is set to 'context' and no completion type is returned by any of the configured contexts. Completion contexts *supertab-completioncontexts* *g:SuperTabCompletionContexts* g:SuperTabCompletionContexts (default value: ['s:ContextText']) Sets the list of contexts used for context completion. This value should be a list of function names which provide the context implementation. When supertab starts the default completion, each of these contexts will be consulted, in the order they were supplied, to determine the completion type to use. If a context returns a completion type, that type will be used, otherwise the next context in the list will be consulted. If after executing all the context functions, no completion type has been determined, then the value of g:SuperTabContextDefaultCompletionType will be used. Built in completion contexts: s:ContextText *supertab-contexttext* The text context will examine the text near the cursor to decide which type of completion to attempt. Currently the text context can recognize method calls or attribute references via '.', '::' or '->', and file path references containing '/'. /usr/l # will use filename completion myvar.t # will use user completion if completefunc set, or # omni completion if omnifunc set. myvar-> # same as above Supported configuration attributes: g:SuperTabContextTextFileTypeExclusions List of file types for which the text context will be skipped. g:SuperTabContextTextOmniPrecedence List of omni completion option names in the order of precedence that they should be used if available. By default, user completion will be given precedence over omni completion, but you can use this variable to give omni completion higher precedence by placing it first in the list. s:ContextDiscover *supertab-contextdiscover* This context will use the 'g:SuperTabContextDiscoverDiscovery' variable to determine the completion type to use. It will evaluate each value, in the order they were defined, until a variable evaluates to a non-zero or non-empty value, then the associated completion type is used. Supported configuration properties: g:SuperTabContextDiscoverDiscovery List of variable:completionType mappings. Example context configuration: *supertab-contextexample* let g:SuperTabCompletionContexts = ['s:ContextText', 's:ContextDiscover'] let g:SuperTabContextTextOmniPrecedence = ['&omnifunc', '&completefunc'] let g:SuperTabContextDiscoverDiscovery = \ ["&completefunc:", "&omnifunc:"] In addition to the default completion contexts, you can plug in your own implementation by creating a globally accessible function that returns the completion type to use (eg. "\\"). function MyTagContext() if filereadable(expand('%:p:h') . '/tags') return "\\" endif " no return will result in the evaluation of the next " configured context endfunction let g:SuperTabCompletionContexts = \ ['MyTagContext', 's:ContextText', 's:ContextDiscover'] Note: supertab also supports the b:SuperTabCompletionContexts variable allowing you to set the list of contexts separately for the current buffer, like from an ftplugin for example. Completion Duration *supertab-duration* *g:SuperTabRetainCompletionDuration* g:SuperTabRetainCompletionDuration (default value: 'insert') Determines if, and for how long, the current completion type is retained. The possible values include: 'completion' - The current completion type is only retained for the current completion. Once you have chosen a completion result or exited the completion mode, the default completion type is restored. 'insert' - The current completion type is saved until you exit insert mode (via ESC). Once you exit insert mode the default completion type is restored. (supertab default) 'session' - The current completion type is saved for the duration of your vim session or until you enter a different completion mode. Preventing completion after... *supertab-preventcomplete* *g:SuperTabNoCompleteBefore* *g:SuperTabNoCompleteAfter* g:SuperTabNoCompleteBefore (default value: []) g:SuperTabNoCompleteAfter (default value: ['\s']) These two variables are used to control when supertab will attempt completion or instead fall back to inserting a literal , by specifying a list of patterns which are tested against the text before and after the current cursor position that when matched, prevent completion. So if you don't want supertab to start completion after a comma or space, you can set g:SuperTabNoCompleteAfter to [',', '\s']. Note: That a buffer local version of these variables (b:SuperTabNoCompleteBefore, b:SuperTabNoCompleteAfter) is also supported should you wish to have different values depending on the file type for instance. Changing the default mapping *supertab-forwardbackward* *g:SuperTabMappingForward* *g:SuperTabMappingBackward* g:SuperTabMappingForward (default value: '') g:SuperTabMappingBackward (default value: '') These two variables allow you to set the keys used to kick off the current completion. By default this is and . To change to something like and , you can add the following to your |vimrc|. let g:SuperTabMappingForward = '' let g:SuperTabMappingBackward = '' Note: if the above does not have the desired effect (which may happen in console version of vim), you can try the following mappings. Although the backwards mapping still doesn't seem to work in the console for me, your milage may vary. let g:SuperTabMappingForward = '' let g:SuperTabMappingBackward = '' Inserting true tabs *supertab-mappingtabliteral* *g:SuperTabMappingTabLiteral* g:SuperTabMappingTabLiteral (default value: '') Sets the key mapping used to insert a literal tab where supertab would otherwise attempt to kick off insert completion. The default is '' (ctrl-tab) which unfortunately might not work at the console. So if you are using a console vim and want this functionality, you may have to change it to something that is supported. Alternatively, you can escape the with (see |i_CTRL-V| for more infos). Enhanced longest match support *supertab-longestenhanced* *g:SuperTabLongestEnhanced* g:SuperTabLongestEnhanced (default value: 0) When enabled and 'longest' is in your |completeopt| setting, supertab will provide an enhanced longest match support where typing one or more letters and hitting tab again while in a completion mode will complete the longest common match using the new text in the buffer. For example, say you have a buffer with the following contents: FooBarFoo FooBar Foo FooBarBaz And you then type F. Vim's builtin longest support will complete the longest common text 'Foo' and offer 'FooBarFoo', 'FooBar', 'Foo', and 'FooBarBaz' as possible completions. With supertab's longest match enhancement disabled, typing B while still in the completion mode will end up completing 'FooBarBaz' or 'FooBarFoo' depending your settings, instead of the next longest common match of 'FooBar'. With supertab's enhanced longest match feature enabled, the typing of B will result in the next longest text being completed. Preselecting the first entry *supertab-longesthighlight* *g:SuperTabLongestHighlight* g:SuperTabLongestHighlight (default value: 0) Sets whether or not to pre-highlight the first match when completeopt has the popup menu enabled and the 'longest' option as well. When enabled, will kick off completion and pre-select the first entry in the popup menu, allowing you to simply hit to use it. Mapping to end completion *supertab-crmapping* *g:SuperTabCrMapping* g:SuperTabCrMapping (default value: 1) When enabled, will cancel completion mode preserving the current text. Compatibility with other plugins: - endwise: compatible - delimitMate: not compatible (disabled if the delimitMate mapping is detected.) Auto close the preview window *supertab-closepreviewonpopupclose* *g:SuperTabClosePreviewOnPopupClose* g:SuperTabClosePreviewOnPopupClose (default value: 0) When enabled, supertab will attempt to close vim's completion preview window when the completion popup closes (completion is finished or canceled). Completion Chaining *supertab-completionchaining* SuperTab provides the ability to chain one of the completion functions (|completefunc| or |omnifunc|) together with a one of the default vim completion key sequences (|ins-completion|), giving you the ability to attempt completion with the first, and upon no results, fall back to the second. To utilize this feature you need to call the SuperTabChain function where the first argument is the name of a vim compatible |complete-function| and the second is one of vim's insert completion (|ins-completion|) key bindings (, , , etc). Calling this function will set the current buffer's |completefunc| option to a supertab provided implementation which utilizes the supplied arguments to perform the completion. Since the |completefunc| option is being set, this feature works best when also setting |g:SuperTabDefaultCompletionType| to either "context" or "". Here is an example that can be added to your .vimrc which will setup the supertab chaining for any filetype that has a provided |omnifunc| to first try that, then fall back to supertab's default, , completion: autocmd FileType * \ if &omnifunc != '' | \ call SuperTabChain(&omnifunc, "") | \ call SuperTabSetDefaultCompletionType("") | \ endif Note: This feature does not support chaining any other combination of completions (2 or more completion functions, 2 or more key bindings, etc.). It can only support 1 completion function followed by 1 key binding. This is due to limitations imposed by vim's code completion implementation. vim:tw=78:ts=8:ft=help:norl: vim-scripts-20130814/doc/vcscommand.txt0000644000000000000000000007407412203050723014572 0ustar *vcscommand.txt* vcscommand Copyright (c) 2007 Bob Hiestand Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. For instructions on installing this file, type :help add-local-help inside Vim. Author: Bob Hiestand Credits: Benji Fisher's excellent MatchIt documentation ============================================================================== 1. Contents *vcscommand-contents* Installation : |vcscommand-install| vcscommand Intro : |vcscommand| vcscommand Manual : |vcscommand-manual| Customization : |vcscommand-customize| SSH "integration" : |vcscommand-ssh| Changes from cvscommand : |cvscommand-changes| Bugs : |vcscommand-bugs| ============================================================================== 2. vcscommand Installation *vcscommand-install* The vcscommand plugin comprises five files: vcscommand.vim, vcssvn.vim, vcscvs.vim, vcssvk.vim and vcscommand.txt (this file). In order to install the plugin, place the vcscommand.vim, vcssvn.vim, vcssvk.vim, and vcscvs.vim files into a plugin directory in your runtime path (please see |add-global-plugin| and |'runtimepath'|. This help file can be included in the VIM help system by copying it into a 'doc' directory in your runtime path and then executing the |:helptags| command, specifying the full path of the 'doc' directory. Please see |add-local-help| for more details. vcscommand may be customized by setting variables, creating maps, and specifying event handlers. Please see |vcscommand-customize| for more details. ============================================================================== 3. vcscommand Intro *vcscommand* *vcscommand-intro* The vcscommand plugin provides global ex commands for manipulating version-controlled source files, currently those controlled either by CVS or Subversion. In general, each command operates on the current buffer and accomplishes a separate source control function, such as update, commit, log, and others (please see |vcscommand-commands| for a list of all available commands). The results of each operation are displayed in a scratch buffer. Several buffer variables are defined for those scratch buffers (please see |vcscommand-buffer-variables|). The notion of "current file" means either the current buffer, or, in the case of a directory buffer (such as Explorer or netrw buffers), the directory (and all subdirectories) represented by the the buffer. For convenience, any vcscommand invoked on a vcscommand scratch buffer acts as though it was invoked on the original file and splits the screen so that the output appears in a new window. Many of the commands accept revisions as arguments. By default, most operate on the most recent revision on the current branch if no revision is specified. Each vcscommand is mapped to a key sequence starting with the || keystroke. The default mappings may be overridden by supplying different mappings before the plugin is loaded, such as in the vimrc, in the standard fashion for plugin mappings. For examples, please see |vcscommand-mappings-override|. The vcscommand plugin may be configured in several ways. For more details, please see |vcscommand-customize|. ============================================================================== 4. vcscommand Manual *vcscommand-manual* 4.1 vcscommand commands *vcscommand-commands* vcscommand defines the following commands: |:VCSAdd| |:VCSAnnotate| |:VCSBlame| |:VCSCommit| |:VCSDelete| |:VCSDiff| |:VCSGotoOriginal| |:VCSLog| |:VCSRemove| |:VCSRevert| |:VCSReview| |:VCSStatus| |:VCSUpdate| |:VCSVimDiff| The following commands are specific to CVS files: |:CVSEdit| |:CVSEditors| |:CVSUnedit| |:CVSWatch| |:CVSWatchAdd| |:CVSWatchOn| |:CVSWatchOff| |:CVSWatchRemove| |:CVSWatchers| :VCSAdd *:VCSAdd* This command adds the current file to source control. Please note, this does not commit the newly-added file. All parameters to the command are passed to the underlying VCS. :VCSAnnotate[!] *:VCSAnnotate* This command displays the current file with each line annotated with the version in which it was most recently changed. If an argument is given, the argument is used as a revision number to display. If not given an argument, it uses the most recent version of the file (on the current branch, if under CVS control). Additionally, if the current buffer is a VCSAnnotate buffer already, the version number on the current line is used. If '!' is used, the view of the annotated buffer is split so that the annotation is in a separate window from the content, and each is highlighted separately. For CVS buffers, the 'VCSCommandCVSAnnotateParent' option, if set to non-zero, will cause the above behavior to change. Instead of annotating the version on the current line, the parent revision is used instead, crossing branches if necessary. The filetype of the vcscommand scratch buffer is set to one of 'CVSAnnotate', 'SVNAnnotate', 'SVKAnnotate' or 'gitAnnotate' as appropriate, to take advantage of the bundled syntax files. :VCSBlame[!] *:VCSBlame* Alias for |:VCSAnnotate|. :VCSCommit[!] *:VCSCommit* This command commits changes to the current file to source control. If called with arguments, the arguments are the log message. If '!' is used, an empty log message is committed. If called with no arguments, this is a two-step command. The first step opens a buffer to accept a log message. When that buffer is written, it is automatically closed and the file is committed using the information from that log message. The commit can be abandoned if the log message buffer is deleted or wiped before being written. Alternatively, the mapping that is used to invoke :VCSCommit (by default ||cc, please see |vcscommand-mappings|) can be used in the log message buffer in Normal mode to immediately commit. This is useful if the |VCSCommandCommitOnWrite| variable is set to 0 to disable the normal commit-on-write behavior. :VCSDelete *:VCSDelete* Deletes the current file and removes it from source control. All parameters to the command are passed to the underlying VCS. :VCSDiff *:VCSDiff* With no arguments, this displays the differences between the current file and its parent version under source control in a new scratch buffer. With one argument, the diff is performed on the current file against the specified revision. With two arguments, the diff is performed between the specified revisions of the current file. For CVS, this command uses the |VCSCommandCVSDiffOpt| variable to specify diff options. If that variable does not exist, a plugin-specific default is used. If you wish to have no options, then set it to the empty string. For SVN, this command uses the |VCSCommandSVNDiffOpt| variable to specify diff options. If that variable does not exist, the SVN default is used. Additionally, |VCSCommandSVNDiffExt| can be used to select an external diff application. :VCSGotoOriginal *:VCSGotoOriginal* This command jumps to the source buffer if the current buffer is a VCS scratch buffer. :VCSGotoOriginal! Like ":VCSGotoOriginal" but also executes :bufwipeout on all VCS scrach buffers associated with the original file. :VCSInfo *:VCSInfo* This command displays extended information about the current file in a new scratch buffer. :VCSLock *:VCSLock* This command locks the current file in order to prevent other users from concurrently modifying it. The exact semantics of this command depend on the underlying VCS. This does nothing in CVS. All parameters are passed to the underlying VCS. :VCSLog *:VCSLog* Displays the version history of the current file in a new scratch buffer. If there is one parameter supplied, it is taken as as a revision parameters to be passed through to the underlying VCS. Otherwise, all parameters are passed to the underlying VCS. :VCSRemove *:VCSRemove* Alias for |:VCSDelete|. :VCSRevert *:VCSRevert* This command replaces the current file with the most recent version from the repository in order to wipe out any undesired changes. :VCSReview *:VCSReview* Displays a particular version of the current file in a new scratch buffer. If no argument is given, the most recent version of the file on the current branch is retrieved. :VCSStatus *:VCSStatus* Displays versioning information about the current file in a new scratch buffer. All parameters are passed to the underlying VCS. :VCSUnlock *:VCSUnlock* Unlocks the current file in order to allow other users from concurrently modifying it. The exact semantics of this command depend on the underlying VCS. All parameters are passed to the underlying VCS. :VCSUpdate *:VCSUpdate* Updates the current file with any relevant changes from the repository. This intentionally does not automatically reload the current buffer, though vim should prompt the user to do so if the underlying file is altered by this command. :VCSVimDiff *:VCSVimDiff* Uses vimdiff to display differences between versions of the current file. If no revision is specified, the most recent version of the file on the current branch is used. With one argument, that argument is used as the revision as above. With two arguments, the differences between the two revisions is displayed using vimdiff. With either zero or one argument, the original buffer is used to perform the vimdiff. When the scratch buffer is closed, the original buffer will be returned to normal mode. Once vimdiff mode is started using the above methods, additional vimdiff buffers may be added by passing a single version argument to the command. There may be up to 4 vimdiff buffers total. Using the 2-argument form of the command resets the vimdiff to only those 2 versions. Additionally, invoking the command on a different file will close the previous vimdiff buffers. :CVSEdit *:CVSEdit* This command performs "cvs edit" on the current file. Yes, the output buffer in this case is almost completely useless. :CVSEditors *:CVSEditors* This command performs "cvs edit" on the current file. :CVSUnedit *:CVSUnedit* Performs "cvs unedit" on the current file. Again, yes, the output buffer here is basically useless. :CVSWatch *:CVSWatch* This command takes an argument which must be one of [on|off|add|remove]. The command performs "cvs watch" with the given argument on the current file. :CVSWatchAdd *:CVSWatchAdd* This command is an alias for ":CVSWatch add" :CVSWatchOn *:CVSWatchOn* This command is an alias for ":CVSWatch on" :CVSWatchOff *:CVSWatchOff* This command is an alias for ":CVSWatch off" :CVSWatchRemove *:CVSWatchRemove* This command is an alias for ":CVSWatch remove" :CVSWatchers *:CVSWatchers* This command performs "cvs watchers" on the current file. 4.2 Mappings *vcscommand-mappings* By default, a mapping is defined for each command. These mappings execute the default (no-argument) form of each command. ||ca VCSAdd ||cn VCSAnnotate ||cN VCSAnnotate! ||cc VCSCommit ||cD VCSDelete ||cd VCSDiff ||cg VCSGotoOriginal ||cG VCSGotoOriginal! ||ci VCSInfo ||cl VCSLog ||cL VCSLock ||cr VCSReview ||cs VCSStatus ||cu VCSUpdate ||cU VCSUnlock ||cv VCSVimDiff Only for CVS buffers: ||ce CVSEdit ||cE CVSEditors ||ct CVSUnedit ||cwv CVSWatchers ||cwa CVSWatchAdd ||cwn CVSWatchOn ||cwf CVSWatchOff ||cwf CVSWatchRemove *vcscommand-mappings-override* The default mappings can be overridden by user-provided instead by mapping to CommandName. This is especially useful when these mappings collide with other existing mappings (vim will warn of this during plugin initialization, but will not clobber the existing mappings). There are three methods for controlling mapping: First, maps can be overriden for individual commands. For instance, to override the default mapping for :VCSAdd to set it to '\add', add the following to the vimrc: nmap \add VCSAdd Second, the default map prefix ('c') can be overridden by defining the |VCSCommandMapPrefix| variable. Third, the entire set of default maps can be overridden by defining the |VCSCommandMappings| variable. 4.3 Automatic buffer variables *vcscommand-buffer-variables* Several buffer variables are defined in each vcscommand result buffer. These may be useful for additional customization in callbacks defined in the event handlers (please see |vcscommand-events|). The following variables are automatically defined: b:VCSCommandOriginalBuffer *b:VCSCommandOriginalBuffer* This variable is set to the buffer number of the source file. b:VCSCommandCommand *b:VCSCommandCommand* This variable is set to the name of the vcscommand that created the result buffer. b:VCSCommandSourceFile *b:VCSCommandSourceFile* This variable is set to the name of the original file under source control. b:VCSCommandVCSType *b:VCSCommandVCSType* This variable is set to the type of the source control. This variable is also set on the original file itself. ============================================================================== 5. Configuration and customization *vcscommand-customize* *vcscommand-config* The vcscommand plugin can be configured in several ways: by setting configuration variables (see |vcscommand-options|) or by defining vcscommand event handlers (see |vcscommand-events|). Additionally, the vcscommand plugin supports a customized status line (see |vcscommand-statusline| and |vcscommand-buffer-management|). 5.1 vcscommand configuration variables *vcscommand-options* Several variables affect the plugin's behavior. These variables are checked at time of execution, and may be defined at the window, buffer, or global level and are checked in that order of precedence. The following variables are available: |VCSCommandCommitOnWrite| |VCSCommandCVSDiffOpt| |VCSCommandCVSExec| |VCSCommandDeleteOnHide| |VCSCommandDiffSplit| |VCSCommandDisableAll| |VCSCommandDisableMappings| |VCSCommandDisableExtensionMappings| |VCSCommandEdit| |VCSCommandEnableBufferSetup| |VCSCommandMappings| |VCSCommandMapPrefix| |VCSCommandResultBufferNameExtension| |VCSCommandResultBufferNameFunction| |VCSCommandSplit| |VCSCommandSVKExec| |VCSCommandSVNDiffExt| |VCSCommandSVNDiffOpt| |VCSCommandSVNExec| |VCSCommandVCSTypeOverride| VCSCommandCommitOnWrite *VCSCommandCommitOnWrite* This variable, if set to a non-zero value, causes the pending commit to take place immediately as soon as the log message buffer is written. If set to zero, only the VCSCommit mapping will cause the pending commit to occur. If not set, it defaults to 1. VCSCommandCVSExec *VCSCommandCVSExec* This variable controls the executable used for all CVS commands If not set, it defaults to "cvs". VCSCommandDeleteOnHide *VCSCommandDeleteOnHide* This variable, if set to a non-zero value, causes the temporary result buffers to automatically delete themselves when hidden. VCSCommandCVSDiffOpt *VCSCommandCVSDiffOpt* This variable, if set, determines the options passed to the diff command of CVS. If not set, it defaults to 'u'. VCSCommandDiffSplit *VCSCommandDiffSplit* This variable overrides the |VCSCommandSplit| variable, but only for buffers created with |:VCSVimDiff|. VCSCommandDisableAll *VCSCommandDisableAll* This variable, if set, prevents the plugin or any extensions from loading at all. This is useful when a single runtime distribution is used on multiple systems with varying versions. VCSCommandDisableMappings *VCSCommandDisableMappings* This variable, if set to a non-zero value, prevents the default command mappings from being set. This supercedes |VCSCommandDisableExtensionMappings|. VCSCommandDisableExtensionMappings *VCSCommandDisableExtensionMappings* This variable, if set to a non-zero value, prevents the default command mappings from being set for commands specific to an individual VCS. VCSCommandEdit *VCSCommandEdit* This variable controls whether the original buffer is replaced ('edit') or split ('split'). If not set, it defaults to 'split'. VCSCommandEnableBufferSetup *VCSCommandEnableBufferSetup* This variable, if set to a non-zero value, activates VCS buffer management mode see (|vcscommand-buffer-management|). This mode means that the 'VCSCommandBufferInfo' variable is filled with version information if the file is VCS-controlled. This is useful for displaying version information in the status bar. VCSCommandMappings *VCSCommandMappings* This variable, if set, overrides the default mappings used for shortcuts. It should be a List of 2-element Lists, each containing a shortcut and function name pair. The value of the '|VCSCommandMapPrefix|' variable will be added to each shortcut. VCSCommandMapPrefix *VCSCommandMapPrefix* This variable, if set, overrides the default mapping prefix ('c'). This allows customization of the mapping space used by the vcscommand shortcuts. VCSCommandResultBufferNameExtension *VCSCommandResultBufferNameExtension* This variable, if set to a non-blank value, is appended to the name of the VCS command output buffers. For example, '.vcs'. Using this option may help avoid problems caused by autocommands dependent on file extension. VCSCommandResultBufferNameFunction *VCSCommandResultBufferNameFunction* This variable, if set, specifies a custom function for naming VCS command output buffers. This function is expected to return the new buffer name, and will be passed the following arguments: command - name of the VCS command being executed (such as 'Log' or 'Diff'). originalBuffer - buffer number of the source file. vcsType - type of VCS controlling this file (such as 'CVS' or 'SVN'). statusText - extra text associated with the VCS action (such as version numbers). VCSCommandSplit *VCSCommandSplit* This variable controls the orientation of the various window splits that may occur. If set to 'horizontal', the resulting windows will be on stacked on top of one another. If set to 'vertical', the resulting windows will be side-by-side. If not set, it defaults to 'horizontal' for all but VCSVimDiff windows. VCSVimDiff windows default to the user's 'diffopt' setting, if set, otherwise 'vertical'. VCSCommandSVKExec *VCSCommandSVKExec* This variable controls the executable used for all SVK commands If not set, it defaults to "svk". VCSCommandSVNDiffExt *VCSCommandSVNDiffExt* This variable, if set, is passed to SVN via the --diff-cmd command to select an external application for performing the diff. VCSCommandSVNDiffOpt *VCSCommandSVNDiffOpt* This variable, if set, determines the options passed with the '-x' parameter to the SVN diff command. If not set, no options are passed. VCSCommandSVNExec *VCSCommandSVNExec* This variable controls the executable used for all SVN commands If not set, it defaults to "svn". VCSCommandVCSTypeOverride *VCSCommandVCSTypeOverride* This variable allows the VCS type detection to be overridden on a path-by-path basis. The value of this variable is expected to be a List of Lists. Each item in the high-level List is a List containing two elements. The first element is a regular expression that will be matched against the full file name of a given buffer. If it matches, the second element will be used as the VCS type. 5.2 VCSCommand events *vcscommand-events* For additional customization, vcscommand can trigger user-defined events. Event handlers are provided by defining User event autocommands (see |autocommand|, |User|) in the vcscommand group with patterns matching the event name. For instance, the following could be added to the vimrc to provide a 'q' mapping to quit a vcscommand scratch buffer: augroup VCSCommand au User VCSBufferCreated silent! nmap q :bwipeout augroup END The following hooks are available: VCSBufferCreated This event is fired just after a vcscommand result buffer is created and populated. It is executed within the context of the vcscommand buffer. The vcscommand buffer variables may be useful for handlers of this event (please see |vcscommand-buffer-variables|). VCSBufferSetup This event is fired just after vcscommand buffer setup occurs, if enabled. VCSPluginInit This event is fired when the vcscommand plugin first loads. VCSPluginFinish This event is fired just after the vcscommand plugin loads. VCSVimDiffFinish This event is fired just after the VCSVimDiff command executes to allow customization of, for instance, window placement and focus. Additionally, there is another hook which is used internally to handle loading the multiple scripts in order. This hook should probably not be used by an end user without a good idea of how it works. Among other things, any events associated with this hook are cleared after they are executed (during vcscommand.vim script initialization). VCSLoadExtensions This event is fired just before the VCSPluginFinish. It is used internally to execute any commands from the VCS implementation plugins that needs to be deferred until the primary plugin is initialized. 5.3 vcscommand buffer naming *vcscommand-naming* vcscommand result buffers use the following naming convention: [{VCS type} {VCS command} {Source file name}] If additional buffers are created that would otherwise conflict, a distinguishing number is added: [{VCS type} {VCS command} {Source file name}] (1,2, etc) 5.4 vcscommand status line support *vcscommand-statusline* It is intended that the user will customize the |'statusline'| option to include vcscommand result buffer attributes. A sample function that may be used in the |'statusline'| option is provided by the plugin, VCSCommandGetStatusLine(). In order to use that function in the status line, do something like the following: set statusline=%<%f\ %{VCSCommandGetStatusLine()}\ %h%m%r%=%l,%c%V\ %P of which %{VCSCommandGetStatusLine()} is the relevant portion. The sample VCSCommandGetStatusLine() function handles both vcscommand result buffers and VCS-managed files if vcscommand buffer management is enabled (please see |vcscommand-buffer-management|). 5.5 vcscommand buffer management *vcscommand-buffer-management* The vcscommand plugin can operate in buffer management mode, which means that it attempts to set a buffer variable ('VCSCommandBufferInfo') upon entry into a buffer. This is rather slow because it means that the VCS will be invoked at each entry into a buffer (during the |BufEnter| autocommand). This mode is disabled by default. In order to enable it, set the |VCSCommandEnableBufferSetup| variable to a true (non-zero) value. Enabling this mode simply provides the buffer variable mentioned above. The user must explicitly include information from the variable in the |'statusline'| option if they are to appear in the status line (but see |vcscommand-statusline| for a simple way to do that). The 'VCSCommandBufferInfo' variable is a list which contains, in order, the revision of the current file, the latest revision of the file in the repository, and (for CVS) the name of the branch. If those values cannot be determined, the list is a single element: 'Unknown'. ============================================================================== 6. SSH "integration" *vcscommand-ssh* The following instructions are intended for use in integrating the vcscommand.vim plugin with an SSH-based CVS environment. Familiarity with SSH and CVS are assumed. These instructions assume that the intent is to have a message box pop up in order to allow the user to enter a passphrase. If, instead, the user is comfortable using certificate-based authentication, then only instructions 6.1.1 and 6.1.2 (and optionally 6.1.4) need to be followed; ssh should then work transparently. 6.1 Environment settings *vcscommand-ssh-env* 6.1.1 CVSROOT should be set to something like: :ext:user@host:/path_to_repository 6.1.2 CVS_RSH should be set to: ssh Together, those settings tell CVS to use ssh as the transport when performing CVS calls. 6.1.3 SSH_ASKPASS should be set to the password-dialog program. In my case, running gnome, it's set to: /usr/libexec/openssh/gnome-ssh-askpass This tells SSH how to get passwords if no input is available. 6.1.4 OPTIONAL. You may need to set SSH_SERVER to the location of the cvs executable on the remote (server) machine. 6.2 CVS wrapper program *vcscommand-ssh-wrapper* Now you need to convince SSH to use the password-dialog program. This means you need to execute SSH (and therefore CVS) without standard input. The following script is a simple perl wrapper that dissasociates the CVS command from the current terminal. Specific steps to do this may vary from system to system; the following example works for me on linux. #!/usr/bin/perl -w use strict; use POSIX qw(setsid); open STDIN, '/dev/null'; fork and do {wait; exit;}; setsid; exec('cvs', @ARGV); 6.3 Configuring vcscommand.vim *vcscommand-ssh-config* At this point, you should be able to use your wrapper script to invoke CVS with various commands, and get the password dialog. All that's left is to make CVS use your newly-created wrapper script. 6.3.1 Tell vcscommand.vim what CVS executable to use. The easiest way to do this is globally, by putting the following in your .vimrc: let VCSCommandCVSExec=/path/to/cvs/wrapper/script 6.4 Where to go from here *vcscommand-ssh-other* The script given above works even when non-SSH CVS connections are used, except possibly when interactively entering the message for CVS commit log (depending on the editor you use... VIM works fine). Since the vcscommand.vim plugin handles that message without a terminal, the wrapper script can be used all the time. This allows mixed-mode operation, where some work is done with SSH-based CVS repositories, and others with pserver or local access. It is possible, though beyond the scope of the plugin, to dynamically set the CVS executable based on the CVSROOT for the file being edited. The user events provided (such as VCSBufferCreated and VCSBufferSetup) can be used to set a buffer-local value (b:VCSCommandCVSExec) to override the CVS executable on a file-by-file basis. Alternatively, much the same can be done (less automatically) by the various project-oriented plugins out there. It is highly recommended for ease-of-use that certificates with no passphrase or ssh-agent are employed so that the user is not given the password prompt too often. ============================================================================== 7. Changes from cvscommand *cvscommand-changes* 1. Require Vim 7 in order to leverage several convenient features; also because I wanted to play with Vim 7. 2. Renamed commands to start with 'VCS' instead of 'CVS'. The exceptions are the 'CVSEdit' and 'CVSWatch' family of commands, which are specific to CVS. 3. Renamed options, events to start with 'VCSCommand'. 4. Removed option to jump to the parent version of the current line in an annotated buffer, as opposed to the version on the current line. This made little sense in the branching scheme used by subversion, where jumping to a parent branch required finding a different location in the repository. It didn't work consistently in CVS anyway. 5. Removed option to have nameless scratch buffers. 6. Changed default behavior of scratch buffers to split the window instead of displaying in the current window. This may still be overridden using the 'VCSCommandEdit' option. 7. Split plugin into multiple plugins. 8. Added 'VCSLock' and 'VCSUnlock' commands. These are implemented for subversion but not for CVS. These were not kept specific to subversion as they seemed more general in nature and more likely to be supported by any future VCS supported by this plugin. 9. Changed name of buffer variables set by commands. 'b:cvsOrigBuffNR' became 'b:VCSCommandOriginalBuffer' 'b:cvscmd' became 'b:VCSCommandCommand' 10. Added new automatic variables to command result buffers. 'b:VCSCommandSourceFile' 'b:VCSCommandVCSType' ============================================================================== 8. Known bugs *vcscommand-bugs* Please let me know if you run across any. CVSUnedit may, if a file is changed from the repository, provide prompt text to determine whether the changes should be thrown away. Currently, that text shows up in the CVS result buffer as information; there is no way for the user to actually respond to the prompt and the CVS unedit command does nothing. If this really bothers anyone, please let me know. VCSVimDiff, when using the original (real) source buffer as one of the diff buffers, uses some hacks to try to restore the state of the original buffer when the scratch buffer containing the other version is destroyed. There may still be bugs in here, depending on many configuration details. vim:tw=78:ts=8:ft=help vim-scripts-20130814/doc/project.txt0000644000000000000000000006267012203050723014105 0ustar *project.txt* Plugin for managing multiple projects with multiple sources For Vim version 6.x and Vim version 7.x. Last Change: Fri 13 Oct 2006 10:20:13 AM EDT By Aric Blumer aricvim email-at-sign charter.net *project* *project-plugin* Contents: Commands...................|project-invoking| Inheritance.............|project-inheritance| Mappings...................|project-mappings| Adding Mappings.....|project-adding-mappings| Settings...................|project-settings| Example File................|project-example| Tips...........................|project-tips| You can use this plugin's basic functionality to set up a list of frequently-accessed files for easy navigation. The list of files will be displayed in a window on the left side of the Vim window, and you can press or double-click on filenames in the list to open the files. I find this easier to use than having to navigate a directory hierarchy with the |file-explorer|. You can also instruct the Plugin to change to a directory and to run Vim scripts when you select a file. These scripts can, for example, modify the environment to include compilers in $PATH. This makes it very easy to use quickfix with multiple projects that use different environments. Other features include: o Loading/Unloading all the files in a Project (\l, \L, \w, and \W) o Grepping all the files in a Project (\g and \G) o Running a user-specified script on a file (can be used to launch an external program on the file) (\1 through \9) o Running a user-specified script on all the files in a Project (\f1-\f9 and \F1-\F9) o High degree of user-configurability o Also works with |netrw| using the XXXX://... notation where XXXX is ftp, rcp, scp, or http. All of this is specified within a simple text file and a few global variables in your vimrc file. You must set 'nocompatible' in your |vimrc| file to use this plugin. You can stop the plugin from being loaded by setting the "loaded_project" variable: > :let loaded_project = 1 ============================================================================== COMMANDS *project-invoking* You can use the plugin by placing it in your plugin directory (e.g., ~/.vim/plugin). See |add-global-plugin|. When you start vim the next time, you then enter the command > :Project or > :Project {file} If you do not specify the filename, $HOME/.vimprojects is used. To have Vim come up with the Project Window enabled automatically (say, from a GUI launcher), run Vim like this: [g]vim +Project Note that you can invoke :Project on only one file at a time. If you wish to change the Project File, do a :bwipe in the Project Buffer, then re-invoke the Plugin as described above. Several Projects can be kept and displayed in the same file, each in a fold delimited by { and } (see |fold.txt|). There can be any number of nested folds to provide you with a Project hierarchy. Any line without a { or a } in the file is considered to be a filename. Blank lines are ignored, and any text after a # is ignored. Because the plugin uses standard Vim folds, you can use any of the |fold-commands|. You can double-click on the first line of a fold to open and close it. You can select a file to open by putting the cursor on its name and pressing or by double-clicking on it. The plugin will create a new window to the right or use the |CTRL-W_p| equivalent if it exists. *project-syntax* Each Project Entry has this form: project_entry ::= ={projpath} [{options}] { [ filename ] [ project_entry ] } {options} is one or more of the following (on the same line): CD={path} in={filename} out={filename} filter="{pat}" flags={flag} Note that a project_entry can reside within a project_entry. This allows you to set up a hierarchy within your Project. The will be displayed in the foldtext and cannot contain "=". There can be no space character directly on either side of the =. The {projpath} is the path in which the files listed in the Project's fold will be found, and it may contain environment variables. If the path is a relative path, then the plugin constructs the whole path from the Project's parent, grandparent, etc., all the way up the hierarchy. An outermost project_entry must have an absolute path. See the |project-inheritance| example below. {projpath} may contain spaces, but they must be escaped like normal Vim escapes. Here are two examples of the same directory: > Example=/my/directory/with\ spaces { } Example="/my/directory/with spaces" { } I recommend this for Windows: > Example="c:\My Documents" { } But Vim is smart enough to do this, too: > Example=c:\My\ Documents { } CD= provides the directory that Vim will change to when you select a file in that fold (using |:cd|). This allows you, for example, to enter |:make| to use the local Makefile. A CD=. means that Vim will make {projpath} or its inherited equivalent the current working directory. When CD is omitted, the directory is not changed. There can be no space on either side of the =. The value of CD can also be a relative path from a parent's CD. See the |project-inheritance| example below. This directive is ignored for |netrw| projects. Spaces are allowed in the path as for {projpath}. in= and out= provide the means to run arbitrary Vim scripts whenever you enter or leave a file's buffer (see the |BufEnter| and |BufLeave| autocommand events). The idea is to have a Vim script that sets up or tears down the environment for the Project like this: in.vim: > let $PROJECT_HOME='~/my_project' " Put the compiler in $PATH if $PATH !~ '/path/to/my/compiler' let $PATH=$PATH.':/path/to/my/compiler' endif out.vim: > " Remove compiler from $PATH if $PATH =~ '/path/to/my/compiler' let $PATH=substitute($PATH, ':/path/to/my/compiler', '', 'g') endif Then you can use :make with the proper environment depending on what file you are currently editing. If the path to the script is relative, then it is relative from {projpath}. These directives are inherited by Subprojects unless the Subproject specifies its own. For use with |netrw| projects, the paths specified for in= and out= must be absolute and local. filter= specifies a |glob()| file pattern. It is used to regenerate the list of files in a Project fold when using the \r (r) map in the Project Window. The filter value must be in quotes because it can contain multiple file patterns. If filter is omitted, then the * pattern is used. There can be no space on either side of the =. A Subproject will inherit the filter of its parent unless it specifies its own filter. flags= provides the means to enable/disable features for a particular fold. The general mnemonic scheme is for lower case to turn something off and upper case to turn something on. {flag} can contain any of the following characters: flag Description ~ l Turn off recursion for this fold for \L. Subfolds are also blocked from the recursion. r Turn off refresh. When present, do not refresh this fold when \r or \R is used. This does not affect subfold recursion. S Turn on sorting for refresh and create. s Turn off sorting for refresh and create. T Turn on top gravity. Forces folds to the top of the current fold when refreshing. It has the same affect as the 'T' flag in g:proj_flags, but controls the feature on a per-fold basis. t Turn off top gravity. Forces folds to the bottom of the current fold when refreshing. w Turn off recursion for this fold for \W. Subfolds are also blocked from the recursion. Flags are not inherited by Subprojects. Any text outside a fold is ignored. ============================================================================== INHERITANCE *project-inheritance* It's best to show inheritance by comparing these two Project Files: > Parent=~/my_project CD=. filter="Make* *.mk" flags=r { Child1=c_code { } Child2=include CD=. filter="*.h" { } } Child1's path is "~/my_project/c_code" because ~/my_project is inherited. It also inherits the CD from Parent. Since Parent has CD=., the Parent's cwd is "~/my_project". Child1 therefore inherits a CD of "~/my_project". Finally, Child1 inherits the filter from Parent. The flags are not inherited. Child2 only inherits the "~/my_project" from Parent. Thus, the example above is exactly equivalent to this: > Parent=~/my_project CD=. filter="Make* *.mk" flags=r { Child1=~/my_project/c_code CD=~/my_project filter="Make* *.mk" { } Child2=~/my_project/include CD=~/my_project/include filter="*.h" { } } (For a real Project, Child1 would not want to inherit its parent's filter, but this example shows the concept.) You can always enter \i to display what the cursor's project inherits. ============================================================================== MAPPINGS *project-mappings* Map Action ~ \r Refreshes the Project fold that the cursor is in by placing in the fold all the files that match the filter. The Project is refreshed using an indent of one space for every foldlevel in the hierarchy. You may place a "# pragma keep" (without the quotes) at the end of a line, and the file entry on that line will not be removed when you refresh. This is useful, for example, when you have . as an entry so you can easily browse the directory. Note that this mapping is actually r, and the default of || is \. This does not work for Projects using |netrw|. \R Executes \r recursively in the current fold and all folds below. This does not work for Projects using |netrw|. \c Creates a Project fold entry. It asks for the description, the path to the files, the CD parameter, and the filename |glob()| pattern. From this information, it will create the Project Entry below the cursor. This does not work for Projects using |netrw|. \C Creates a Project fold entry like \c, but recursively includes all the subdirectories. Select a file to open in the |CTRL-W_p| window or in a new window. If the cursor is on a fold, open or close it. \s Same as but horizontally split the target window. s is provided for those terminals that don't recognize . \S Load all files in a project by doing horizontal splits. \o Same as but ensure that the opened file is the only other window. o is provided for those terminals that don't recognize . \v Same as but only display the file--the cursor stays in the Project Window. <2-LeftMouse> (Double-click) If on a closed fold, open it. If on an open fold boundary, close it. If on a filename, open the file in the |CTRL-W_p| window or in a new window. Same as . Same as . Increase the width of the Project Window by g:proj_window_increment or toggle between a width of g:proj_window_width + g:proj_window_increment and g:proj_window_width. Whether you toggle or monotonically increase the width is determined by the 't' flag of the g:proj_flags variable (see |project-flags|). Note that a Right Mouse click will not automatically place the cursor in the Project Window if it is in a different window. The window will go back to the g:proj_window_width width when you leave the window. Same as \ Move the text or fold under the cursor up one row. This may not work in a terminal because the terminal is unaware of this key combination. is provided for those terminals that don't recognize . \ Move the text or fold under the cursor down one row. This may not work in a terminal because the terminal is unaware of this key combination. is provided for those terminals that don't recognize . \i Show in the status line the completely resolved and inherited parameters for the fold the cursor is in. This is intended for debugging your relative path and inherited parameters for manually entered Projects. \I Show in the status line the completely resolved filename. Uses the Project_GetFname(line('.')) function. \1 - \9 Run the command specified in g:proj_run{x} where {x} is the number of the key. See the documentation of g:proj_run1 below. \f1-\f9 Run the command specified in g:proj_run_fold{x} where {x} is the number of the key. The command is run on the files at the current Project level. See the |project-settings| below. \F1-\F9 Run the command specified in g:proj_run_fold{x} where {x} is the number of the key. The command is run on the files at the current Project level and all Subprojects. See the |project-settings| below. \0 Display the commands that are defined for \1 through \9. \f0 Display the commands that are defined for \f1 through \f9 and \F1 through \F0. Same as \F0. \l Load all the files in the current Project level into Vim. While files are being loaded, you may press any key to stop. \L Load all the files in the current Project and all Subprojects into Vim. Use this mapping with caution--I wouldn't suggest using \L to load a Project with thousands of files. (BTW, my Project file has more than 5,300 files in it!) While files are being loaded, you may press any key to stop. \w Wipe all the files in the current Project level from Vim. (If files are modified, they will be saved first.) While files are being wiped, you may press any key to stop. \W Wipe all the files in the current Project and all Subprojects from Vim. (If files are modified, they will be saved first.) While files are being wiped, you may press any key to stop. \g Grep all the files in the current Project level. \G Grep all the files in the current Project level and all Subprojects. \e Set up the Environment for the Project File as though you had selected it with . This allows you to do a \e and a :make without having to open any files in the project. \E Explore (using |file-explorer|) the directory of the project the cursor is in. Does not work with netrw. When the 'g' flag is present in g:proj_flags (see |project-flags|) this key toggles the Project Window open and closed. You may remap this toggle function by putting the following in your vimrc and replacing P with whatever key combination you wish: nmap P ToggleProject Note that the Project Plugin remaps :help because the Help Window and the Project Window get into a fight over placement. The mapping avoids the problem. ============================================================================== ADDING MAPPINGS *project-adding-mappings* You can add your own mappings or change the mappings of the plugin by placing them in the file $HOME/.vimproject_mappings. This file, if it exists, will be sourced when the plugin in loaded. Here is an example that will count the number of entries in a project when you press \K (Kount, C is taken :-): > function! s:Wc() let b:loadcount=0 function! SpawnExec(infoline, fname, lineno, data) let b:loadcount = b:loadcount + 1 if getchar(0) != 0 | let b:stop_everything=1 | endif endfunction call Project_ForEach(1, line('.'), "*SpawnExec", 0, '') delfunction SpawnExec echon b:loadcount." Files\r" unlet b:loadcount if exists("b:stop_everything") unlet b:stop_everything echon "Aborted.\r" endif endfunction nnoremap K :call Wc() Here's another example of how I integrated the use of perforce with the plugin in my $HOME/.vimproject_mappings: > function! s:DoP4(cmd) let name=Project_GetFname(line('.')) let dir=substitute(name, '\(.*\)/.*', '\1', 'g') exec 'cd '.dir exec "!".a:cmd.' '.Project_GetFname(line('.')) cd - endfunction nmap \pa :call DoP4("p4add") nmap \pe :call DoP4("p4edit") < (Note that I CD to the directory the file is in so I can pick of the $P4CONFIG file. See the perforce documentation.) This creates the mappings \pe to check out the file for edit and \pa to add the file to the depot. Here is another example where I remap the mapping to use an external program to launch a special kind of file (in this case, it launches ee to view a jpg file). It is a bit contrived, but it works. > let s:sid = substitute(maparg('', 'n'), '.*\(.\{-}\)_.*', '\1', '') function! s:LaunchOrWhat() let fname=Project_GetFname(line('.')) if fname =~ '\.jpg$' exec 'silent! !ee "'.fname.'"&' else call {s:sid}_DoFoldOrOpenEntry('', 'e') endif endfunction nnoremap \|:call LaunchOrWhat() < If the file ends in .jpg, the external program is launched, otherwise the original mapping of is run. ============================================================================== SETTINGS *project-settings* You can set these variables in your vimrc file before the plugin is loaded to change its default behavior g:proj_window_width The width of the Project Window that the plugin attempts to maintain. Default: 24 The Project Plugin is not always successful in keeping the window where I want it with the size specified here, but it does a decent job. g:proj_window_increment The increment by which to increase the width of the Project Window when pressing or clicking the . Default: 100 (See |project-mappings|.) *project-flags* g:proj_flags Default: "imst" Various flags to control the behavior of the Project Plugin. This variable can contain any of the following character flags. flag Description ~ b When present, use the |browse()| when selecting directories for \c and \C. This is off by default for Windows, because the windows browser does not allow you to select directories. c When present, the Project Window will automatically close when you select a file. F Float the Project Window. That is, turn off automatic resizing and placement. This allows placement between other windows that wish to share similar placement at the side of the screen. It is also particularly helpful for external window managers. g When present, the mapping for will be created to toggle the Project Window open and closed. i When present, display the filename and the current working directory in the command line when a file is selected for opening. l When present, the Project Plugin will use the |:lcd| command rather than |:cd| to change directories when you select a file to open. This flag is really obsolete and not of much use because of L below. L Similar to l, but install a BufEnter/Leave |:autocommand| to ensure that the current working directory is changed to the one specified in the fold CD specification whenever that buffer is active. (|:lcd| only changes the CWD for a window, not a buffer.) m Turn on mapping of the |CTRL-W_o| and |CTRL-W_CTRL_O| normal mode commands to make the current buffer the only visible buffer, but keep the Project Window visible, too. n When present, numbers will be turned on for the project window. s When present, the Project Plugin will use syntax highlighting in the Project Window. S Turn on sorting for refresh and create. t When present, toggle the size of the window rather than just increase the size when pressing or right-clicking. See the entry for in |project-mappings|. T When present, put Subproject folds at the top of the fold when refreshing. v When present, use :vimgrep rather than :grep when using \G. g:proj_run1 ... g:proj_run9 Contains a Vim command to execute on the file. See the mappings of \1 to \9 above. %f is replaced with the full path and filename %F is replaced with the full path and filename with spaces quoted %n is replaced with the filename alone %N is replaced with the filename alone with spaces quoted %h is replaced with the home directory %H is replaced with the home directory with spaces quoted %r is replaced with the directory relative to the CD path %R is replaced with the directory relative to the CD path with spaces quoted %d is replaced with the CD directory. %D is replaced with the CD directory.with spaces quoted %% is replaced with a single % that is not used in expansion. (Deprecated: %s is also replaced with the full path and filename for backward compatibility.) For example, gvim will be launched on the file under the cursor when you enter \3 if the following is in your vimrc file: > let g:proj_run3='silent !gvim %f' < Here are a few other examples: > let g:proj_run1='!p4 edit %f' let g:proj_run2='!p4 add %f' let g:proj_run4="echo 'Viewing %f'|sil !xterm -e less %f &" < On Windows systems you will want to put the %f, %h, and %d in single quotes to avoid \ escaping. g:proj_run_fold1 ... g:proj_run_fold9 Contains a Vim command to execute on the files in a fold. See the mappings of \f1 to \f9 and \F1 to \F9 above. %f is the filename, %h is replaced with the project home directory, and %d is replaced with the CD directory. Multiple filenames can be handled in two ways: The first (default) way is to have %f replaced with all the absolute filenames, and the command is run once. The second is to have the command run for each of the non-absolute filenames (%f is replaced with one filename at a time). To select the second behavior, put an '*' character at the beginning of the g:proj_run_fold{x} variable. (The '*' is stripped before the command is run.) For example, note the difference between the following: > let g:proj_run_fold3="*echo '%h/%f'" let g:proj_run_fold4="echo '%f'" < Note that on Windows systems, you will want the %f, %h, and %c within single quotes, or the \ in the paths will cause problems. The alternative is to put them in |escape()|. ============================================================================== PROJECT EXAMPLE FILE *project-example* Here is an example ~/.vimprojects file: > 1 My Project=~/c/project CD=. in=in.vim out=out.vim flags=r { 2 Makefile 3 in.vim 4 out.vim 5 GUI Files=. filter="gui*.c gui*.h" { 6 gui_window.c 7 gui_dialog.c 8 gui_list.c 9 gui.h # Header file 10 } 11 Database Files=. filter="data*.c data*.h" { 12 data_read.c 13 data_write.c 14 data.h 15 } 16 OS-Specific Files { 17 Win32=. filter="os_win32*.c os_win32*.h" { 18 os_win32_gui.c 19 os_win32_io.c 20 } 21 Unix=. filter="os_unix*.c os_unix*.h" { 22 os_unix_gui.c 23 os_unix_io.c 24 } 25 } 26 } (Don't type in the line numbers, of course.) ============================================================================== TIPS ON USING PROJECT PLUGIN *project-tips* 1. You can create a Project Entry by entering this: > Label=~/wherever CD=. filter="*.c *.h" { } < Then you can put the cursor in the fold and press \r. The script will fill in the files (C files in this case) from this directory for you. This is equivalent to \c without any dialogs. 2. You can edit the Project File at any time to add, remove, or reorder files in the Project list. 3. If the Project Window ever gets closed, you can just enter > :Project < to bring it back again. (You don't need to give it the filename; the plugin remembers.) If you have the 'm' flag set in g:proj_flags, then you get the Project Window to show up again by pressing |CTRL-W_o|. This, of course, will close any other windows that may be open that the cursor is not in. 4. Adding files to a Project is very easy. To add, for example, the 'more.c' file to the Project, just insert the filename in the Project Entry then hit on it. 5. When |quickfix| loads files, it is not equivalent to pressing on a filename, so the directory will not be changed and the scripts will not be run. (If I could make this otherwise, I would.) The solution is to use the \L key to load all of the files in the Project before running quickfix. 6. If the Project window gets a bit cluttered with folds partially open/closed, you can press |zM| to close everything and tidy it up. 7. For advanced users, I am exporting the function Project_GetAllFnames() which returns all the filenames within a fold and optionally all its Subprojects. Also, I export Project_ForEach() for running a function for each filename in the project. See the code for examples on how to use these. Finally, I export Project_GetFname(line_number) so that you can write your own mappings and get the filename for it. 8. Some people have asked how to do a global mapping to take the cursor to the Project window. One of my goals for the plugin is for it to be as self-contained as possible, so I'm not going to add it by default. But you can put this in your vimrc: > nmap P :Project < 9. You can put the . entry in a project, and it will launch the |file-explorer| plugin on the directory. To avoid removal when you refresh, make the entry look like this: > . # pragma keep < ============================================================================== THANKS The following people have sent me patches to help with the Project Plugin development: Tomas Zellerin Lawrence Kesteloot Dave Eggum A Harrison Thomas Link Richard Bair Eric Arnold Peter Jones Eric Van Dewoestine vim:ts=8 sw=8 noexpandtab tw=78 ft=help: vim-scripts-20130814/doc/alternate.txt0000644000000000000000000002130112203050723014400 0ustar *alternate.txt* Alternate Plugin Sat May 13 15:35:38 CDT 2006 Author: Michael Sharpe Copyright: (c) 2000-2006 Michael Sharpe We grant permission to use, copy modify, distribute, and sell this software for any purpose without fee, provided that the above copyright notice and this text are not removed. We make no guarantee about the suitability of this software for any purpose and we are not liable for any damages resulting from its use. Further, we are under no obligation to maintain or extend this software. It is provided on an "as is" basis without any expressed or implied warranty. ============================================================================== 1. Contents *AS* *AV* *AT* *AN* *IH* *IHS* *IHV* *IHT* *IHN* *alternate* 1. Contents...........................: |alternate| 2. Purpose............................: |alternate-purpose| 3. Commands...........................: |alternate-commands| 4. Configuration......................: |alternate-config| 5. Installation.......................: |alternate-installation| 6. Bugs/Enhancements..................: |alternate-support| 7. Acknowledgments....................: |alternate-acknowledgments| ============================================================================== 2. Purpose *alternate-purpose* The purpose of a.vim is to allow quick and easy switching between source files and corresponding header files. Many languages (C, C++, ada, ocaml, lex/yacc) have the concept of source/header files or the like. It is quite common during development or review to need to edit both files together. This plugin attempts to simplify that process. There are commands which while editing a source file allow for the quick switching to the corresponding header and vice versa. The only difference between the commands is how the switch occurs. More recent functionality allow the switching to a file under the cursor too. In the following sections the commands, configuration and installation procedures are described. ============================================================================== 3. Commands *alternate-commands* There are 4 commands provided by this plugin. They are :A switches to the header file corresponding to the source file in the current buffer (or vice versa). :AS similar to :A except the current buffer is split horizontally such that the source file is on one split and the header is in the other. :AV similar to :AS except that the split is vertical :AT similar to :AS and :AV except a new tab is opened instead of a split :IH switches to the file under cursor (or the file specified with the command). This command uses the builtin a.vim search path support and the &path variable in conjunction. :IHS similar to :IH execpt the current buffer is split horizontally first :IHS similar to :IH execpt the current buffer is split vertically first :IHS similar to :IH execpt a new tab is created for the file being switched to :IHN switches to the next matching file for the original selection In all cases if the corresponding alternate file is already loaded that buffer is preferred. That is this plugin will never load the same file twice. Some maps are also provided for the IH command (mainly for example purposes) ih - switches to the file under the cursor using the :IHS command is - switches to the source file of the header file under the cursor using the :IHS command and the :A command ihn - switches to the next match in the sequence. ============================================================================== 4. Configuration *alternate-config* It is possible to configure three separate pieces of behaviour of this plugin. a) Extensions: Each language has different extensions for identifying the source and header files. Many languages support multiple different but related extensions. As such this plugin allow for the complete specification of how source and header files correspond to each other via extension maps. There are a number of maps built in. For example, the following variable setting g:alternateExtensions_CPP = "inc,h,H,HPP,hpp" indicates that any file with a .CPP exetension can have a corresponding file with any of the .inc, .h, .H, .HPP, .hpp extension. The inverse is not specified by this map though. Typically each extension will have a mapping. So there would exist maps for .h, .inc, .H, .HPP, .hpp too. Extension maps should be specified before loading this plugin. Some of the builtin extension maps are as follows, C and C++ g:alternateExtensions_h = "c,cpp,cxx,cc,CC" g:alternateExtensions_H' = "C,CPP,CXX,CC" g:alternateExtensions_cpp' = "h,hpp" g:alternateExtensions_CPP' = "H,HPP" g:alternateExtensions_c' = "h" g:alternateExtensions_C' = "H" g:alternateExtensions_cxx' = "h" Ada g:alternateExtensions_adb' = "ads" g:alternateExtensions_ads' = "adb" Lex/Yacc g:alternateExtensions_l' = "y,yacc,ypp" g:alternateExtensions_lex' = "yacc,y,ypp" g:alternateExtensions_lpp' = "ypp,y,yacc" g:alternateExtensions_y' = "l,lex,lpp" g:alternateExtensions_yacc' = "lex,l,lpp" g:alternateExtensions_ypp' = "lpp,l,lex" b) Search Paths: In many projects the location of the source files and the corresponding header files is not always the same directory. This plugin allows the search path it uses to locate source and header files to be configured. The search path is specified by setting the g:alternateSearchPath variable. The default setting is as follows, g:alternateSearchPath = 'sfr:../source,sfr:../src,sfr:../include,sfr:../inc' This indicates that the corresponding file will be searched for in ../source, ../src. ../include and ../inc all relative to the current file being switched from. The value of the g:alternateSearchPath variable is simply a comma separated list of prefixes and directories. The "sfr:" prefix indicates that the path is relative to the file. Other prefixes are "wdr:" which indicates that the directory is relative to the current working directory and "abs:" which indicates the path is absolute. If no prefix is specified "sfr:" is assumed. c) Regex Paths: Another type of prefix which can appear in the g:alternateSearchPath variable is that of "reg:". It is used to apply a regex to the path of the file in the buffer being switched from to locate the alternate file. E.g. 'reg:/inc/src/g/' will replace every instance of 'inc' with 'src' in the source file path. It is possible to use match variables so you could do something like: 'reg:|src/\([^/]*\)|inc/\1||' (see |substitute|, |help pattern| and |sub-replace-special| for more details. The exact syntax of a "reg:" specification is reg: seperator character, we often use one of [/|%#] is what you are looking for is the output pattern can be g for global replace or empty d) No Alternate Behaviour: When attempting to alternate/switch from a source/header to its corresponding file it is possible that the corresponding file does not exist. In this case this plugin will create the missing alternate file in the same directory as the current file. Some users find this behaviour irritating. This behaviour can be disabled by setting g:alternateNoDefaultAlternate to 1. When this variable is not 0 a message will be displayed indicating that no alternate file exists. ============================================================================== 5. Installation *alternate-installation* To install this plugin simply drop the a.vim file in to $VIMRUNTIME/plugin (global or local) or simply source the file from the vimrc file. Ensure that any configuration occurs before the plugin is loaded/sourced. ============================================================================== 6. Bugs/Enhancements *alternate-support* Whilst no formal support is provided for this plugin the author is always happy to receive bug reports and enhancement requests. Please email all such reports/requests to feline@irendi.com. ============================================================================== 7. Acknowledgments *alternate-acknowledgments* The author would like to thank everyone who has submitted bug reports and feature enhancement requests in the past. In particular Bindu Wavell provided much of the original code implementing the search path and regex functionality. vim:tw=78:ts=8:ft=help vim-scripts-20130814/doc/taglist.txt0000644000000000000000000021053312203050723014077 0ustar *taglist.txt* Plugin for browsing source code Author: Yegappan Lakshmanan (yegappan AT yahoo DOT com) For Vim version 6.0 and above Last change: 2013 Feburary 26 1. 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. License |taglist-license| 12. 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. * 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 or suggestions for improvement or to send bug reports. Visit the following page for subscribing to the mailing list: > http://groups.yahoo.com/group/taglist < ============================================================================== *taglist-requirements* 3. Requirements~ The taglist plugin requires the following: * Vim version 6.0 and above * Exuberant ctags 5.0 and above 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 relies on the exuberant ctags utility to dynamically generate the tag listing. The exuberant ctags utility must be installed in your system to use this plugin. The exuberant ctags utility is shipped with most of the Linux distributions. 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 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|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 and doc/taglist.txt files from the $HOME/.vim or $HOME/vimfiles directory. ============================================================================== *taglist-using* 5. Usage~ The taglist plugin can be used in several different ways. 1. You can keep the taglist window open during the entire editing session. 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 only the tags defined in the current file. 4. In GUI Vim, 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 the cursor remains in the current window. If the 'Tlist_GainFocus_On_ToggleOpen' variable is set to 1, then the ":TlistToggle" command opens the taglist window and moves the cursor to the taglist window. You can map a key to invoke these commands. For example, the following command creates a normal mode mapping for the key to toggle the taglist window. > nnoremap :TlistToggle < Add the above mapping to your ~/.vimrc or $HOME/_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 on startup using the following command line: > $ vim +TlistOpen < 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 ":TlistToggle" command when the taglist window 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, you can set the 'Tlist_Close_On_Select' variable to 1. To exit Vim when only the taglist 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 key or by double clicking the tag name using the mouse. To jump to a tag on a single mouse click set the 'Tlist_Use_SingleClick' variable to 1. If the selected file is already opened in a window, then the cursor is moved to that window. If the file is not currently opened in a window then the file is opened in the window used by the taglist plugin to show the previously selected file. If there are no usable windows, then the file is opened in a new window. The file is not opened in special windows like the quickfix window, preview window and windows containing buffer with the 'buftype' option set. To jump to the tag in a new window, press the 'o' key. To open the file in the previous window (Ctrl-W_p) use the 'P' key. You can press the 'p' key to jump to the tag but still keep the cursor in the taglist window (preview). To open the selected file in a tab, use the 't' key. If the file is already present in a tab then the cursor is moved to that tab otherwise the file is opened in a new tab. To jump to a tag in a new tab press Ctrl-t. The taglist window is automatically opened in the newly created tab. Instead of jumping to a tag, you can open a file by pressing the key or by double clicking the file name using the mouse. In the taglist window, you can use the [[ or key to jump to the beginning of the previous file. You can use the ]] or key to jump to the beginning of the next file. When you reach the first or last file, the search wraps 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 the taglist window. The Vim |CursorHold| autocmd event is used for this. If the current tag name is not visible in the taglist window, then the taglist window contents 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 avoid unexpected problems, you should not set the |'updatetime'| option to a very low value. To disable the automatic highlighting of the current tag name in the taglist window, set the 'Tlist_Auto_Highlight_Tag' variable to zero. When entering a Vim buffer/window, the taglist plugin automatically highlights the current tag in that buffer/window. If you like to disable the automatic highlighting 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 are processed and the supported files are added to the taglist. When you edit a file in Vim, the taglist plugin automatically processes this file and adds it to the taglist. If you close the taglist window, the tag information in the taglist 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 using the ":TlistAddFiles" and the ":TlistAddFilesRecursive" commands. For example, to add all the C files in the /my/project/dir directory to the taglist, 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 large number of files, it will take several seconds to several minutes for the taglist plugin to process all the files. You should not interrupt the taglist plugin by pressing . 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 directory from which to recursively add the files. The second optional argument specifies the wildcard matching pattern for selecting the files to add. The default 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 list and all the manually added files. To display the tags for only the current active buffer, set the 'Tlist_Show_One_File' variable to 1. Removing files from the taglist~ You can remove a file from the taglist window, 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 will no longer be displayed in the taglist window in the current Vim session. To again display the tags for the file, open the file in a Vim window and then use the ":TlistUpdate" command or use ":TlistAddFiles" command to add the file to the taglist. When a buffer is removed from the Vim buffer list using the ":bdelete" or the ":bwipeout" command, the taglist is updated to remove the stored information for this buffer. Updating the tags displayed for a file~ The taglist plugin keeps track of the modification time of a file. When the modification time changes (the file is modified), the taglist plugin automatically updates the tags listed for that file. The modification time of a file is checked when you enter a window containing that file or when you load that file. You can also 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 automatically updates 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. Controlling the taglist updates~ To disable the automatic processing of new files or modified files, you can set the 'Tlist_Auto_Update' variable to zero. When this variable is set to zero, the taglist is updated only when you use the ":TlistUpdate" command or the ":TlistAddFiles" or the ":TlistAddFilesRecursive" commands. You can use this option to control which files are added to the taglist. You can use the ":TlistLock" command to lock the taglist contents. After this command is executed, new files are not automatically added to the taglist. When the taglist is locked, you can use the ":TlistUpdate" command to add the current file or the ":TlistAddFiles" or ":TlistAddFilesRecursive" commands to add new files to the taglist. To unlock the taglist, use the ":TlistUnlock" command. Displaying the tag prototype~ To display the prototype of the tag under the cursor in the taglist window, press the space bar. If you place the cursor on a tag name in the taglist window, then the tag prototype is displayed at the Vim status line after |'updatetime'| milliseconds. The default value for the |'updatetime'| Vim option is 4 seconds. You can get the name and prototype of a tag without opening the taglist window and the taglist menu using the ":TlistShowTag" and the ":TlistShowPrototype" commands. These commands will work only if the current file is already present in the taglist. To use these commands without opening the taglist window, set the 'Tlist_Process_File_Always' variable to 1. You can use the ":TlistShowTag" command to display the name of the tag at or before the specified line number in the specified file. If the file name and line number are not supplied, then this command will display the name of the current tag. For example, > :TlistShowTag :TlistShowTag myfile.java 100 < You can use the ":TlistShowPrototype" command to display the prototype of the tag at or before the specified line number in the specified file. If the file name and the line number are not supplied, then this command will display the prototype of the current tag. For example, > :TlistShowPrototype :TlistShowPrototype myfile.c 50 < In the taglist window, when the mouse is moved over a tag name, the tag prototype is displayed in a balloon. This works only in GUI versions where balloon evaluation is supported. Taglist window contents~ The taglist window contains the tags defined in various files in the taglist grouped by the filename and by the tag type (variable, function, class, etc.). For tags with scope information (like class members, structures inside structures, etc.), the scope information is displayed in square brackets "[]" after the tag name. The contents of the taglist buffer/window are managed by the taglist plugin. The |'filetype'| for the taglist buffer is set to 'taglist'. 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, close the taglist window and reopen it. Opening and closing the tag and file tree~ In the taglist window, the tag names are 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. You should not manually create or delete the folds in the taglist window. To automatically close the fold for the inactive files/buffers and open only the fold for the current buffer in the taglist window, set the 'Tlist_File_Fold_Auto_Close' variable to 1. Sorting the tags for a file~ The tags displayed in the taglist window can be sorted either by their name or by their chronological order. The default sorting method is by the order in which the tags appear in a file. You can change the default sort method by setting the 'Tlist_Sort_Type' variable to either "name" or "order". 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. 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. *taglist-session* Taglist Session~ A taglist session refers to the group of files and their tags stored in the taglist 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 the information about the tags and files in the taglist to a file, use the ":TlistSessionSave" command and specify the filename: > :TlistSessionSave < To load a saved taglist session, use the ":TlistSessionLoad" command: > :TlistSessionLoad < When you load a taglist session file, the tags stored in the file will be added to the tags already stored in the taglist. 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 for multiple files. You can create more than one taglist session file for multiple groups of files. Displaying the 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 Vim |'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 TagListFileName - Used for filenames By default, these highlight groups are linked to the standard Vim highlight groups. If you want to change the colors used for these highlight groups, prefix the highlight group name with 'My' and define it in your .vimrc or .gvimrc file: MyTagListTagName, MyTagListTagScope, MyTagListTitle, MyTagListComment and MyTagListFileName. For example, to change the colors used for tag names, you can use the following command: > :highlight MyTagListTagName guifg=blue ctermfg=blue < Controlling the taglist window~ To use a horizontally split taglist window, instead of a vertically split window, set the 'Tlist_Use_Horiz_Window' variable to 1. To use a vertically split taglist window on the rightmost side of the Vim window, set the 'Tlist_Use_Right_Window' variable to 1. You can specify the width of the vertically split taglist window, by setting the 'Tlist_WinWidth' variable. You can specify the height of the horizontally split taglist window, by setting the 'Tlist_WinHeight' variable. When opening a vertically split taglist window, the Vim window width is increased to accommodate the new taglist window. When the taglist window is closed, the Vim window is reduced. To disable this, set the 'Tlist_Inc_Winwidth' variable to zero. To reduce the number of empty lines in the taglist window, set the 'Tlist_Compact_Format' variable to 1. To not display the Vim fold column in the taglist window, set the 'Tlist_Enable_Fold_Column' variable to zero. To display the tag prototypes instead of the tag names in the taglist window, set the 'Tlist_Display_Prototype' variable to 1. To not display the scope of the tags next to the tag names, set the 'Tlist_Display_Tag_Scope' variable to zero. *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~ 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 Jump to the tag in the previous (Ctrl-W_p) window. p Display the tag definition in the file window and keep the cursor in the taglist window itself. t Jump to the tag in a new tab. If the file is already opened in a tab, move to that tab. Ctrl-t Jump to the tag in a new tab. Display the prototype of the tag under the cursor. For file names, display the full path to the file, file type and the number of tags. For tag types, display the tag type and the number of tags. 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 Jump to the beginning of the previous file ]] Jump to the beginning of the next file 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 all the tags defined in a file are of the same type (e.g. functions), then the sub-menu is not used. 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' < Getting help~ If you have installed the taglist help file (this file), then you can use the Vim ":help taglist-" command to get help on the various taglist topics. 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 is removed from the taglist window. *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. You can specify a file name to the ":TlistDebug" command to log the debug messages to a file. Otherwise, the debug messages are stored in a script-local variable. In the later case, to minimize memory usage, only the last 3000 characters from the debug messages are stored. ============================================================================== *taglist-options* 6. Options~ 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 below this table. |'Tlist_Auto_Highlight_Tag'| Automatically highlight the current tag in the taglist. |'Tlist_Auto_Open'| Open the taglist window when Vim starts. |'Tlist_Auto_Update'| Automatically update the taglist to include newly edited files. |'Tlist_Close_On_Select'| Close the taglist window when a file or tag is selected. |'Tlist_Compact_Format'| Remove extra information and blank lines from the taglist window. |'Tlist_Ctags_Cmd'| Specifies the path to the ctags utility. |'Tlist_Display_Prototype'| Show prototypes and not tags in the taglist window. |'Tlist_Display_Tag_Scope'| Show tag scope next to the tag name. |'Tlist_Enable_Fold_Column'| Show the fold indicator column in the taglist window. |'Tlist_Exit_OnlyWindow'| Close Vim if the taglist is the only window. |'Tlist_File_Fold_Auto_Close'| Close tag folds for inactive buffers. |'Tlist_GainFocus_On_ToggleOpen'| Jump to taglist window on open. |'Tlist_Highlight_Tag_On_BufEnter'| On entering a buffer, automatically highlight the current tag. |'Tlist_Inc_Winwidth'| Increase the Vim window width to accommodate the taglist window. |'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_Process_File_Always'| Process files even when the taglist window is closed. |'Tlist_Show_Menu'| Display the tags menu. |'Tlist_Show_One_File'| Show tags for the current buffer only. |'Tlist_Sort_Type'| Sort method used for arranging the tags. |'Tlist_Use_Horiz_Window'| Use a horizontally split window for the taglist window. |'Tlist_Use_Right_Window'| Place the taglist window on the right side. |'Tlist_Use_SingleClick'| Single click on a tag jumps to it. |'Tlist_WinHeight'| Horizontally split taglist window height. |'Tlist_WinWidth'| Vertically split taglist window width. *'Tlist_Auto_Highlight_Tag'* Tlist_Auto_Highlight_Tag~ The taglist plugin will automatically highlight the current tag in the taglist window. If you want to disable this, 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 < With the above variable set to 1, you can use the ":TlistHighlightTag" command to highlight the current tag. *'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 zero and the taglist window will not be opened automatically on Vim startup. > let Tlist_Auto_Open = 1 < The taglist window is opened only when a supported type of file is opened on Vim startup. For example, if you open text files, then the taglist window will not be opened. *'Tlist_Auto_Update'* Tlist_Auto_Update~ When a new file is edited, the tags defined in the file are automatically processed and added to the taglist. To stop adding new files to the taglist, set the 'Tlist_Auto_Update' variable to zero. By default, this variable is set to 1. > let Tlist_Auto_Update = 0 < With the above variable set to 1, you can use the ":TlistUpdate" command to add the tags defined in the current file to the taglist. *'Tlist_Close_On_Select'* Tlist_Close_On_Select~ If you want to close the taglist window when a file or tag is selected, then set the 'Tlist_Close_On_Select' variable to 1. By default, this variable is set zero and when you select a tag or file from the taglist window, the window is not closed. > let Tlist_Close_On_Select = 1 < *'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 1 to get a compact display. > let Tlist_Compact_Format = 1 < *'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, exctags, 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. Examples: > let Tlist_Ctags_Cmd = 'd:\tools\ctags.exe' let Tlist_Ctags_Cmd = '/usr/local/bin/ctags' < On Microsoft Windows, if ctags.exe is installed in a directory with space characters in the name (e.g. C:\Program Files\ctags\ctags.exe), then you need to set the Tlist_Ctags_Cmd variable like this: > let Tlist_Ctags_Cmd = '"C:\Program Files\ctags\ctags.exe"' < *'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 zero 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 zero. By default, this variable is set to 1 and the tag scopes will be displayed. > let Tlist_Display_Tag_Scope = 0 < *'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 zero. > let Tlist_Enable_Fold_Column = 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 1. 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, the tags tree for the current buffer is automatically opened and for all the other buffers is closed. > let Tlist_File_Fold_Auto_Close = 1 < *'Tlist_GainFocus_On_ToggleOpen'* Tlist_GainFocus_On_ToggleOpen~ When the taglist window is opened using the ':TlistToggle' command, this option controls whether the cursor is moved to the taglist window or remains in the current window. By default, this option is set to 0 and the cursor remains in the current window. When this variable is set to 1, the cursor moves to the taglist window after opening the taglist window. > let Tlist_GainFocus_On_ToggleOpen = 1 < *'Tlist_Highlight_Tag_On_BufEnter'* Tlist_Highlight_Tag_On_BufEnter~ When you enter a Vim buffer/window, the current tag in that buffer/window is automatically highlighted in the taglist window. If the current tag name is not visible in the taglist window, then the taglist window contents are scrolled to make that tag name visible. If you like to disable the automatic highlighting of the current tag when entering a buffer, you can set the 'Tlist_Highlight_Tag_On_BufEnter' variable to zero. The default setting for this variable is 1. > let Tlist_Highlight_Tag_On_BufEnter = 0 < *'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 is 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 zero. If you are using GNU Screen, you may want to set this variable to zero. CAUTION: If you are using the MS-Windows version of Vim in a MS-DOS command window then you must set this variable to zero, otherwise the system may hang due to a Vim limitation (explained in :help win32-problems) > let Tlist_Inc_Winwidth = 0 < *'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. The default value for this variable is 10. Change the 'Tlist_Max_Tag_Length' setting if you want to include more or less characters: > let Tlist_Max_Tag_Length = 10 < *'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 < To use the ":TlistShowTag" and the ":TlistShowPrototype" commands without the taglist window and the taglist menu, you should set this variable to 1. *'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 1: > let Tlist_Show_Menu = 1 < *'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_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 1: > let Tlist_Use_Right_Window = 1 < *'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 1 and try to resize the taglist window using the mouse, then Vim will crash. This problem is fixed 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_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 < The |'winfixheight'| option is set for the taglist window, to maintain the height of the taglist window, when new Vim windows are opened and existing windows are closed. *'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. When new Vim windows are opened and existing windows are closed, the taglist plugin will try to maintain the width of the taglist window to the size specified by the 'Tlist_WinWidth' variable. ============================================================================== *taglist-commands* 7. Commands~ The taglist plugin provides the following ex-mode commands: |:TlistAddFiles| Add multiple files to the taglist. |:TlistAddFilesRecursive| Add files recursively to the taglist. |:TlistClose| Close the taglist window. |:TlistDebug| Start logging of taglist debug messages. |:TlistLock| Stop adding new files to the taglist. |:TlistMessages| Display the logged taglist plugin debug messages. |:TlistOpen| Open and jump to the taglist window. |:TlistSessionSave| Save the information about files and tags in the taglist to a session file. |:TlistSessionLoad| Load the information about files and tags stored in a session file to taglist. |:TlistShowPrototype| Display the prototype of the tag at or before the specified line number. |:TlistShowTag| Display the name of the tag defined at or before the specified line number. |:TlistHighlightTag| Highlight the current tag in the taglist window. |:TlistToggle| Open or close (toggle) the taglist window. |:TlistUndebug| Stop logging of taglist debug messages. |:TlistUnlock| Start adding new files to the taglist. |:TlistUpdate| Update the tags for the current buffer. *:TlistAddFiles* :TlistAddFiles {file(s)} [file(s) ...] Add one or more specified files to the taglist. You can specify multiple filenames using wildcards. To specify a file name with space character, you should escape the space character with a backslash. Examples: > :TlistAddFiles *.c *.cpp :TlistAddFiles file1.html file2.html < If you specify a large number of files, then it will take some time for the taglist plugin to process all of them. The specified files will not be edited in a Vim window and will not be added to the Vim buffer list. *:TlistAddFilesRecursive* :TlistAddFilesRecursive {directory} [ {pattern} ] Add files matching {pattern} recursively from the specified {directory} to the taglist. If {pattern} is not specified, then '*' is assumed. To specify the current directory, use "." for {directory}. To specify a directory name with space character, you should escape the space character with a backslash. Examples: > :TlistAddFilesRecursive myproject *.java :TlistAddFilesRecursive smallproject < If large number of files are present in the specified directory tree, then it will take some time for the taglist plugin to process all of them. *:TlistClose* :TlistClose Close the taglist window. This command can be used from any one of the Vim windows. *:TlistDebug* :TlistDebug [filename] Start logging of debug messages from the taglist plugin. If {filename} is specified, then the debug messages are stored in the specified file. Otherwise, the debug messages are stored in a script local variable. If the file {filename} is already present, then it is overwritten. *:TlistLock* :TlistLock Lock the taglist and don't process new files. After this command is executed, newly edited files will not be added to the taglist. *:TlistMessages* :TlistMessages Display the logged debug messages from the taglist plugin in a window. This command works only when logging to a script-local variable. *:TlistOpen* :TlistOpen Open and jump to the taglist window. Creates the taglist window, if the window is not opened currently. After executing this command, the cursor is moved to the taglist window. When the taglist window is opened for the first time, all the files in the buffer list are processed and the tags defined in them are displayed in the taglist window. *:TlistSessionSave* :TlistSessionSave {filename} Saves the information about files and tags in the taglist to the specified file. This command can be used to save and restore the taglist contents across Vim sessions. *:TlistSessionLoad* :TlistSessionLoad {filename} Load the information about files and tags stored in the specified session file to the taglist. *:TlistShowPrototype* :TlistShowPrototype [filename] [linenumber] Display the prototype of the tag at or before 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 before 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. *:TlistHighlightTag* :TlistHighlightTag 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. *:TlistToggle* :TlistToggle 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. After executing this command, the cursor is not moved from the current window to the taglist window. *:TlistUndebug* :TlistUndebug Stop logging of debug messages from the taglist plugin. *:TlistUnlock* :TlistUnlock Unlock the taglist and start processing newly edited files. *:TlistUpdate* :TlistUpdate Update the tags information for the current buffer. This command can be used to re-process the current file/buffer and get the tags information. As the taglist plugin uses the file saved in the disk (instead of the file displayed in a Vim buffer), you should save a modified buffer before you update the taglist. Otherwise the listed tags will not include the new tags created in the buffer. You can use this command even when the taglist window is not opened. ============================================================================== *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_Get_Filenames()| Return filenames in the taglist |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 before the specified line number in the specified file. |Tlist_Get_Tagname_By_Line()| Return the name of the tag at or before the specified line number in the specified file. |Tlist_Set_App()| Set the name of the application controlling the taglist window. *Tlist_Get_Filenames()* Tlist_Get_Filenames() Returns a list of filenames in the taglist. Each filename is separated by a newline (\n) character. If the taglist is empty an empty string is returned. *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 before 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 before 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 extend the taglist plugin to add support for new languages and also modify the support for the above listed languages. You should NOT make modifications to the taglist plugin script file to add support for new languages. You will lose these changes when you upgrade to the next version of the taglist plugin. Instead you should follow the below described instructions to extend the taglist plugin. You can extend the taglist plugin by setting variables in the .vimrc or _vimrc file. The name of these variables depends on the language name and is described below. Modifying support for an existing language~ To modify the support for an already supported language, you have to set the tlist_xxx_settings variable in the ~/.vimrc or $HOME/_vimrc file. Replace xxx with the Vim filetype name for the language file. For example, to modify the support for the perl language files, you have to set the tlist_perl_settings variable. To modify the support for java files, you have to set the tlist_java_settings variable. To determine the filetype name used by Vim for a file, use the following command in the buffer containing the file: :set filetype The above command will display the Vim filetype for the current buffer. The format of the value set in the tlist_xxx_settings variable is ;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 file. 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'. To get the list of language names supported by exuberant ctags, use the following command: $ ctags --list-maps=all 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. To get the list of flags supported by exuberant ctags for the various languages use the following command: $ ctags --list-kinds=all 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 line 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 to the options used by the taglist plugin for a language, copy the option values from the taglist plugin file to your .vimrc file and modify it. Adding support for a new language~ 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 the following page: http://ctags.sourceforge.net/EXTENDING.html To add support for a new language, set the tlist_xxx_settings variable in the ~/.vimrc file 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. 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 < The output of the above command should contain "filetype detection:ON". 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 options 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 prompt and check whether the tags defined in your file are listed in the output from exuberant ctags: > ctags -f - --format=2 --excmd=pattern --fields=nks < 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. Q. 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 ... A. 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. 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 use 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-license* 11. License~ Permission is hereby granted to use and distribute the taglist plugin, with or without modifications, provided that this copyright notice is copied with it. Like anything else that's free, taglist.vim is provided *as is* and comes with no warranty of any kind, either expressed or implied. In no event will the copyright holder be liable for any damamges resulting from the use of this software. ============================================================================== *taglist-todo* 12. Todo~ 1. Group tags according to the scope and display them. For example, group all the tags belonging to a C++/Java class 2. Support for displaying tags in a modified (not-yet-saved) file. 3. Automatically open the taglist window only for selected filetypes. For other filetypes, close the taglist window. 4. When using the shell from the MKS toolkit, the taglist plugin doesn't work. 5. 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: vim-scripts-20130814/doc/NERD_commenter.txt0000644000000000000000000011416012203050723015230 0ustar *NERD_commenter.txt* Plugin for commenting code NERD COMMENTER REFERENCE MANUAL~ ============================================================================== CONTENTS *NERDCommenterContents* 1.Intro...................................|NERDCommenter| 2.Installation............................|NERDComInstallation| 3.Functionality provided..................|NERDComFunctionality| 3.1 Functionality Summary.............|NERDComFunctionalitySummary| 3.2 Functionality Details.............|NERDComFunctionalityDetails| 3.2.1 Comment map.................|NERDComComment| 3.2.2 Nested comment map..........|NERDComNestedComment| 3.2.3 Toggle comment map..........|NERDComToggleComment| 3.2.4 Minimal comment map.........|NERDComMinimalComment| 3.2.5 Invert comment map..........|NERDComInvertComment| 3.2.6 Sexy comment map............|NERDComSexyComment| 3.2.7 Yank comment map............|NERDComYankComment| 3.2.8 Comment to EOL map..........|NERDComEOLComment| 3.2.9 Append com to line map......|NERDComAppendComment| 3.2.10 Insert comment map.........|NERDComInsertComment| 3.2.11 Use alternate delims map...|NERDComAltDelim| 3.2.12 Comment aligned maps.......|NERDComAlignedComment| 3.2.13 Uncomment line map.........|NERDComUncommentLine| 3.4 Sexy Comments.....................|NERDComSexyComments| 3.5 The NERDComment function..........|NERDComNERDComment| 4.Options.................................|NERDComOptions| 4.1 Options summary...................|NERDComOptionsSummary| 4.2 Options details...................|NERDComOptionsDetails| 4.3 Default delimiter Options.........|NERDComDefaultDelims| 5. Customising key mappings...............|NERDComMappings| 6. Issues with the script.................|NERDComIssues| 6.1 Delimiter detection heuristics....|NERDComHeuristics| 6.2 Nesting issues....................|NERDComNesting| 7.About.. ............................|NERDComAbout| 8.Changelog...............................|NERDComChangelog| 9.Credits.................................|NERDComCredits| 10.License................................|NERDComLicense| ============================================================================== 1. Intro *NERDCommenter* The NERD commenter provides many different commenting operations and styles which are invoked via key mappings and a menu. These operations are available for most filetypes. There are also options that allow to tweak the commenting engine to your taste. ============================================================================== 2. Installation *NERDComInstallation* The NERD Commenter requires Vim 7 or higher. Extract the plugin files in your ~/.vim (*nix) or ~/vimfiles (Windows). You should have 2 files: > plugin/NERD_commenter.vim doc/NERD_commenter.txt < Next, to finish installing the help file run: > :helptags ~/.vim/doc < See |add-local-help| for more details. Make sure that you have filetype plugins enabled, as the script makes use of |'commentstring'| where possible (which is usually set in a filetype plugin). See |filetype-plugin-on| for details, but basically, stick this in your vimrc > filetype plugin on < ============================================================================== 3. Functionality provided *NERDComFunctionality* ------------------------------------------------------------------------------ 3.1 Functionality summary *NERDComFunctionalitySummary* The following key mappings are provided by default (there is also a menu with items corresponding to all the mappings below): [count]cc |NERDComComment| Comment out the current line or text selected in visual mode. [count]cn |NERDComNestedComment| Same as cc but forces nesting. [count]c |NERDComToggleComment| Toggles the comment state of the selected line(s). If the topmost selected line is commented, all selected lines are uncommented and vice versa. [count]cm |NERDComMinimalComment| Comments the given lines using only one set of multipart delimiters. [count]ci |NERDComInvertComment| Toggles the comment state of the selected line(s) individually. [count]cs |NERDComSexyComment| Comments out the selected lines ``sexily'' [count]cy |NERDComYankComment| Same as cc except that the commented line(s) are yanked first. c$ |NERDComEOLComment| Comments the current line from the cursor to the end of line. cA |NERDComAppendComment| Adds comment delimiters to the end of line and goes into insert mode between them. |NERDComInsertComment| Adds comment delimiters at the current cursor position and inserts between. Disabled by default. ca |NERDComAltDelim| Switches to the alternative set of delimiters. [count]cl [count]cb |NERDComAlignedComment| Same as |NERDComComment| except that the delimiters are aligned down the left side (cl) or both sides (cb). [count]cu |NERDComUncommentLine| Uncomments the selected line(s). ------------------------------------------------------------------------------ 3.2 Functionality details *NERDComFunctionalityDetails* ------------------------------------------------------------------------------ 3.2.1 Comment map *NERDComComment* Default mapping: [count]cc Mapped to: NERDCommenterComment Applicable modes: normal visual visual-line visual-block. Comments out the current line. If multiple lines are selected in visual-line mode, they are all commented out. If some text is selected in visual or visual-block mode then the script will try to comment out the exact text that is selected using multi-part delimiters if they are available. If a [count] is given in normal mode, the mapping works as though that many lines were selected in visual-line mode. ------------------------------------------------------------------------------ 3.2.2 Nested comment map *NERDComNestedComment* Default mapping: [count]cn Mapped to: NERDCommenterNest Applicable modes: normal visual visual-line visual-block. Performs nested commenting. Works the same as cc except that if a line is already commented then it will be commented again. If |'NERDUsePlaceHolders'| is set then the previous comment delimiters will be replaced by place-holder delimiters if needed. Otherwise the nested comment will only be added if the current commenting delimiters have no right delimiter (to avoid syntax errors) If a [count] is given in normal mode, the mapping works as though that many lines were selected in visual-line mode. Related options: |'NERDDefaultNesting'| ------------------------------------------------------------------------------ 3.2.3 Toggle comment map *NERDComToggleComment* Default mapping: [count]c Mapped to: NERDCommenterToggle Applicable modes: normal visual-line. Toggles commenting of the lines selected. The behaviour of this mapping depends on whether the first line selected is commented or not. If so, all selected lines are uncommented and vice versa. With this mapping, a line is only considered to be commented if it starts with a left delimiter. If a [count] is given in normal mode, the mapping works as though that many lines were selected in visual-line mode. ------------------------------------------------------------------------------ 3.2.4 Minimal comment map *NERDComMinimalComment* Default mapping: [count]cm Mapped to: NERDCommenterMinimal Applicable modes: normal visual-line. Comments the selected lines using one set of multipart delimiters if possible. For example: if you are programming in c and you select 5 lines and press cm then a '/*' will be placed at the start of the top line and a '*/' will be placed at the end of the last line. Sets of multipart comment delimiters that are between the top and bottom selected lines are replaced with place holders (see |'NERDLPlace'|) if |'NERDUsePlaceHolders'| is set for the current filetype. If it is not, then the comment will be aborted if place holders are required to prevent illegal syntax. If a [count] is given in normal mode, the mapping works as though that many lines were selected in visual-line mode. ------------------------------------------------------------------------------ 3.2.5 Invert comment map *NERDComInvertComment* Default mapping: ci Mapped to: NERDCommenterInvert Applicable modes: normal visual-line. Inverts the commented state of each selected line. If the a selected line is commented then it is uncommented and vice versa. Each line is examined and commented/uncommented individually. With this mapping, a line is only considered to be commented if it starts with a left delimiter. If a [count] is given in normal mode, the mapping works as though that many lines were selected in visual-line mode. ------------------------------------------------------------------------------ 3.2.6 Sexy comment map *NERDComSexyComment* Default mapping: [count]cs Mapped to: NERDCommenterSexy Applicable modes: normal, visual-line. Comments the selected line(s) ``sexily''... see |NERDComSexyComments| for a description of what sexy comments are. Can only be done on filetypes for which there is at least one set of multipart comment delimiters specified. Sexy comments cannot be nested and lines inside a sexy comment cannot be commented again. If a [count] is given in normal mode, the mapping works as though that many lines were selected in visual-line mode. Related options: |'NERDCompactSexyComs'| ------------------------------------------------------------------------------ 3.2.7 Yank comment map *NERDComYankComment* Default mapping: [count]cy Mapped to: NERDCommenterYank Applicable modes: normal visual visual-line visual-block. Same as cc except that it yanks the line(s) that are commented first. ------------------------------------------------------------------------------ 3.2.8 Comment to EOL map *NERDComEOLComment* Default mapping: c$ Mapped to: NERDCommenterToEOL Applicable modes: normal. Comments the current line from the current cursor position up to the end of the line. ------------------------------------------------------------------------------ 3.2.9 Append com to line map *NERDComAppendComment* Default mapping: cA Mapped to: NERDCommenterAppend Applicable modes: normal. Appends comment delimiters to the end of the current line and goes to insert mode between the new delimiters. ------------------------------------------------------------------------------ 3.2.10 Insert comment map *NERDComInsertComment* Default mapping: disabled by default. Map it to: NERDCommenterInInsert Applicable modes: insert. Adds comment delimiters at the current cursor position and inserts between them. NOTE: prior to version 2.1.17 this was mapped to ctrl-c. To restore this mapping add > let NERDComInsertMap='' < to your vimrc. ------------------------------------------------------------------------------ 3.2.11 Use alternate delims map *NERDComAltDelim* Default mapping: ca Mapped to: NERDCommenterAltDelims Applicable modes: normal. Changes to the alternative commenting style if one is available. For example, if the user is editing a c++ file using // comments and they hit ca then they will be switched over to /**/ comments. See also |NERDComDefaultDelims| ------------------------------------------------------------------------------ 3.2.12 Comment aligned maps *NERDComAlignedComment* Default mappings: [count]cl [count]cb Mapped to: NERDCommenterAlignLeft NERDCommenterAlignBoth Applicable modes: normal visual-line. Same as cc except that the comment delimiters are aligned on the left side or both sides respectively. These comments are always nested if the line(s) are already commented. If a [count] is given in normal mode, the mapping works as though that many lines were selected in visual-line mode. ------------------------------------------------------------------------------ 3.2.13 Uncomment line map *NERDComUncommentLine* Default mapping: [count]cu Mapped to: NERDCommenterUncomment Applicable modes: normal visual visual-line visual-block. Uncomments the current line. If multiple lines are selected in visual mode then they are all uncommented. When uncommenting, if the line contains multiple sets of delimiters then the ``outtermost'' pair of delimiters will be removed. The script uses a set of heurisics to distinguish ``real'' delimiters from ``fake'' ones when uncommenting. See |NERDComIssues| for details. If a [count] is given in normal mode, the mapping works as though that many lines were selected in visual-line mode. Related options: |'NERDRemoveAltComs'| |'NERDRemoveExtraSpaces'| ------------------------------------------------------------------------------ 3.3 Sexy Comments *NERDComSexyComments* These are comments that use one set of multipart comment delimiters as well as one other marker symbol. For example: > /* * This is a c style sexy comment * So there! */ /* This is a c style sexy comment * So there! * But this one is ``compact'' style */ < Here the multipart delimiters are /* and */ and the marker is *. ------------------------------------------------------------------------------ 3.4 The NERDComment function *NERDComNERDComment* All of the NERD commenter mappings and menu items invoke a single function which delegates the commenting work to other functions. This function is public and has the prototype: > function! NERDComment(isVisual, type) < The arguments to this function are simple: - isVisual: if you wish to do any kind of visual comment then set this to 1 and the function will use the '< and '> marks to find the comment boundries. If set to 0 then the function will operate on the current line. - type: is used to specify what type of commenting operation is to be performed, and it can be one of the following: "sexy", "invert", "minimal", "toggle", "alignLeft", "alignBoth", "norm", "nested", "toEOL", "append", "insert", "uncomment", "yank" For example, if you typed > :call NERDComment(1, 'sexy') < then the script would do a sexy comment on the last visual selection. ============================================================================== 4. Options *NERDComOptions* ------------------------------------------------------------------------------ 4.1 Options summary *NERDComOptionsSummary* |'loaded_nerd_comments'| Turns off the script. |'NERDAllowAnyVisualDelims'| Allows multipart alternative delims to be used when commenting in visual/visual-block mode. |'NERDBlockComIgnoreEmpty'| Forces right delims to be placed when doing visual-block comments. |'NERDCommentWholeLinesInVMode'| Changes behaviour of visual comments. |'NERDCreateDefaultMappings'| Turn the default mappings on/off. |'NERDDefaultNesting'| Tells the script to use nested comments by default. |'NERDMenuMode'| Specifies how the NERD commenter menu will appear (if at all). |'NERDLPlace'| Specifies what to use as the left delimiter placeholder when nesting comments. |'NERDUsePlaceHolders'| Specifies which filetypes may use placeholders when nesting comments. |'NERDRemoveAltComs'| Tells the script whether to remove alternative comment delimiters when uncommenting. |'NERDRemoveExtraSpaces'| Tells the script to always remove the extra spaces when uncommenting (regardless of whether NERDSpaceDelims is set) |'NERDRPlace'| Specifies what to use as the right delimiter placeholder when nesting comments. |'NERDSpaceDelims'| Specifies whether to add extra spaces around delimiters when commenting, and whether to remove them when uncommenting. |'NERDCompactSexyComs'| Specifies whether to use the compact style sexy comments. ------------------------------------------------------------------------------ 4.3 Options details *NERDComOptionsDetails* To enable any of the below options you should put the given line in your ~/.vimrc *'loaded_nerd_comments'* If this script is driving you insane you can turn it off by setting this option > let loaded_nerd_comments=1 < ------------------------------------------------------------------------------ *'NERDAllowAnyVisualDelims'* Values: 0 or 1. Default: 1. If set to 1 then, when doing a visual or visual-block comment (but not a visual-line comment), the script will choose the right delimiters to use for the comment. This means either using the current delimiters if they are multipart or using the alternative delimiters if THEY are multipart. For example if we are editing the following java code: > float foo = 1221; float bar = 324; System.out.println(foo * bar); < If we are using // comments and select the "foo" and "bar" in visual-block mode, as shown left below (where '|'s are used to represent the visual-block boundary), and comment it then the script will use the alternative delims as shown on the right: > float |foo| = 1221; float /*foo*/ = 1221; float |bar| = 324; float /*bar*/ = 324; System.out.println(foo * bar); System.out.println(foo * bar); < ------------------------------------------------------------------------------ *'NERDBlockComIgnoreEmpty'* Values: 0 or 1. Default: 1. This option affects visual-block mode commenting. If this option is turned on, lines that begin outside the right boundary of the selection block will be ignored. For example, if you are commenting this chunk of c code in visual-block mode (where the '|'s are used to represent the visual-block boundary) > #include #include #include |int| main(){ | | printf("SUCK THIS\n"); | | while(1){ | | fork(); | | } |} | < If NERDBlockComIgnoreEmpty=0 then this code will become: > #include #include #include /*int*/ main(){ /* */ printf("SUCK THIS\n"); /* */ while(1){ /* */ fork(); /* */ } /*} */ < Otherwise, the code block would become: > #include #include #include /*int*/ main(){ printf("SUCK THIS\n"); while(1){ fork(); } /*} */ < ------------------------------------------------------------------------------ *'NERDCommentWholeLinesInVMode'* Values: 0, 1 or 2. Default: 0. By default the script tries to comment out exactly what is selected in visual mode (v). For example if you select and comment the following c code (using | to represent the visual boundary): > in|t foo = 3; int bar =| 9; int baz = foo + bar; < This will result in: > in/*t foo = 3;*/ /*int bar =*/ 9; int baz = foo + bar; < But some people prefer it if the whole lines are commented like: > /*int foo = 3;*/ /*int bar = 9;*/ int baz = foo + bar; < If you prefer the second option then stick this line in your vimrc: > let NERDCommentWholeLinesInVMode=1 < If the filetype you are editing only has no multipart delimiters (for example a shell script) and you hadnt set this option then the above would become > in#t foo = 3; #int bar = 9; < (where # is the comment delimiter) as this is the closest the script can come to commenting out exactly what was selected. If you prefer for whole lines to be commented out when there is no multipart delimiters but the EXACT text that was selected to be commented out if there IS multipart delimiters then stick the following line in your vimrc: > let NERDCommentWholeLinesInVMode=2 < Note that this option does not affect the behaviour of commenting in |visual-block| mode. ------------------------------------------------------------------------------ *'NERDCreateDefaultMappings'* Values: 0 or 1. Default: 1. If set to 0, none of the default mappings will be created. See also |NERDComMappings|. ------------------------------------------------------------------------------ *'NERDRemoveAltComs'* Values: 0 or 1. Default: 1. When uncommenting a line (for a filetype with an alternative commenting style) this option tells the script whether to look for, and remove, comment delimiters of the alternative style. For example, if you are editing a c++ file using // style comments and you go cu on this line: > /* This is a c++ comment baby! */ < It will not be uncommented if the NERDRemoveAltComs is set to 0. ------------------------------------------------------------------------------ *'NERDRemoveExtraSpaces'* Values: 0 or 1. Default: 1. By default, the NERD commenter will remove spaces around comment delimiters if either: 1. |'NERDSpaceDelims'| is set to 1. 2. NERDRemoveExtraSpaces is set to 1. This means that if we have the following lines in a c code file: > /* int foo = 5; */ /* int bar = 10; */ int baz = foo + bar < If either of the above conditions hold then if these lines are uncommented they will become: > int foo = 5; int bar = 10; int baz = foo + bar < Otherwise they would become: > int foo = 5; int bar = 10; int baz = foo + bar < If you want the spaces to be removed only if |'NERDSpaceDelims'| is set then set NERDRemoveExtraSpaces to 0. ------------------------------------------------------------------------------ *'NERDLPlace'* *'NERDRPlace'* Values: arbitrary string. Default: NERDLPlace: "[>" NERDRPlace: "<]" These options are used to control the strings used as place-holder delimiters. Place holder delimiters are used when performing nested commenting when the filetype supports commenting styles with both left and right delimiters. To set these options use lines like: > let NERDLPlace="FOO" let NERDRPlace="BAR" < Following the above example, if we have line of c code: > /* int horse */ < and we comment it with cn it will be changed to: > /*FOO int horse BAR*/ < When we uncomment this line it will go back to what it was. ------------------------------------------------------------------------------ *'NERDMenuMode'* Values: 0, 1, 2, 3. Default: 3 This option can take 4 values: "0": Turns the menu off. "1": Turns the 'comment' menu on with no menu shortcut. "2": Turns the 'comment 'menu on with -c as the shortcut. "3": Turns the 'Plugin -> comment' menu on with -c as the shortcut. ------------------------------------------------------------------------------ *'NERDUsePlaceHolders'* Values: 0 or 1. Default 1. This option is used to specify whether place-holder delimiters should be used when creating a nested comment. ------------------------------------------------------------------------------ *'NERDSpaceDelims'* Values: 0 or 1. Default 0. Some people prefer a space after the left delimiter and before the right delimiter like this: > /* int foo=2; */ < as opposed to this: > /*int foo=2;*/ < If you want spaces to be added then set NERDSpaceDelims to 1 in your vimrc. See also |'NERDRemoveExtraSpaces'|. ------------------------------------------------------------------------------ *'NERDCompactSexyComs'* Values: 0 or 1. Default 0. Some people may want their sexy comments to be like this: > /* Hi There! * This is a sexy comment * in c */ < As opposed to like this: > /* * Hi There! * This is a sexy comment * in c */ < If this option is set to 1 then the top style will be used. ------------------------------------------------------------------------------ *'NERDDefaultNesting'* Values: 0 or 1. Default 1. When this option is set to 1, comments are nested automatically. That is, if you hit cc on a line that is already commented it will be commented again. ------------------------------------------------------------------------------ 3.3 Default delimiter customisation *NERDComDefaultDelims* If you want the NERD commenter to use the alternative delimiters for a specific filetype by default then put a line of this form into your vimrc: > let NERD__alt_style=1 < Example: java uses // style comments by default, but you want it to default to /* */ style comments instead. You would put this line in your vimrc: > let NERD_java_alt_style=1 < See |NERDComAltDelim| for switching commenting styles at runtime. ============================================================================== 5. Key mapping customisation *NERDComMappings* To change a mapping just map another key combo to the internal mapping. For example, to remap the |NERDComComment| mapping to ",omg" you would put this line in your vimrc: > map ,omg NERDCommenterComment < This will stop the corresponding default mappings from being created. See the help for the mapping in question to see which mapping to map to. See also |'NERDCreateDefaultMappings'|. ============================================================================== 6. Issues with the script *NERDComIssues* ------------------------------------------------------------------------------ 6.1 Delimiter detection heuristics *NERDComHeuristics* Heuristics are used to distinguish the real comment delimiters Because we have comment mappings that place delimiters in the middle of lines, removing comment delimiters is a bit tricky. This is because if comment delimiters appear in a line doesnt mean they really ARE delimiters. For example, Java uses // comments but the line > System.out.println("//"); < clearly contains no real comment delimiters. To distinguish between ``real'' comment delimiters and ``fake'' ones we use a set of heuristics. For example, one such heuristic states that any comment delimiter that has an odd number of non-escaped " characters both preceding and following it on the line is not a comment because it is probably part of a string. These heuristics, while usually pretty accurate, will not work for all cases. ------------------------------------------------------------------------------ 6.2 Nesting issues *NERDComNesting* If we have some line of code like this: > /*int foo */ = /*5 + 9;*/ < This will not be uncommented legally. The NERD commenter will remove the "outter most" delimiters so the line will become: > int foo */ = /*5 + 9; < which almost certainly will not be what you want. Nested sets of comments will uncomment fine though. Eg: > /*int/* foo =*/ 5 + 9;*/ < will become: > int/* foo =*/ 5 + 9; < (Note that in the above examples I have deliberately not used place holders for simplicity) ============================================================================== 7. About *NERDComAbout* The author of the NERD commenter is Martyzillatron --- the half robot, half dinosaur bastard son of Megatron and Godzilla. He enjoys destroying metropolises and eating tourist busses. Drop him a line at martin_grenfell at msn.com. He would love to hear from you. its a lonely life being the worlds premier terror machine. How would you feel if your face looked like a toaster and a t-rex put together? :( The latest stable versions can be found at http://www.vim.org/scripts/script.php?script_id=1218 The latest dev versions are on github http://github.com/scrooloose/nerdcommenter ============================================================================== 8. Changelog *NERDComChangelog* 2.3.0 - remove all filetypes which have a &commentstring in the standard vim runtime for vim > 7.0 unless the script stores an alternate set of delimiters - make the script complain if the user doesnt have filetype plugins enabled - use instead of comma to start the default mappings - fix a couple of bugs with sexy comments - thanks to Tim Smart - lots of refactoring 2.2.2 - remove the NERDShutup option and the message is suppresses, this makes the plugin silently rely on &commentstring for unknown filetypes. - add support for dhcpd, limits, ntp, resolv, rgb, sysctl, udevconf and udevrules. Thanks to Thilo Six. - match filetypes case insensitively - add support for mp (metapost), thanks to Andrey Skvortsov. - add support for htmlcheetah, thanks to Simon Hengel. - add support for javacc, thanks to Matt Tolton. - make <%# %> the default delims for eruby, thanks to tpope. - add support for javascript.jquery, thanks to Ivan Devat. - add support for cucumber and pdf. Fix sass and railslog delims, thanks to tpope 2.2.1 - add support for newlisp and clojure, thanks to Matthew Lee Hinman. - fix automake comments, thanks to Elias Pipping - make haml comments default to -# with / as the alternative delimiter, thanks to tpope - add support for actionscript and processing thanks to Edwin Benavides - add support for ps1 (powershell), thanks to Jason Mills - add support for hostsaccess, thanks to Thomas Rowe - add support for CVScommit - add support for asciidoc, git and gitrebase. Thanks to Simon Ruderich. - use # for gitcommit comments, thanks to Simon Ruderich. - add support for mako and genshi, thanks to Keitheis. - add support for conkyrc, thanks to David - add support for SVNannotate, thanks to Miguel Jaque Barbero. - add support for sieve, thanks to Stefan Walk - add support for objj, thanks to Adam Thorsen. 2.2.0 - rewrote the mappings system to be more "standard". - removed all the mapping options. Now, mappings to mappings are used - see :help NERDComMappings, and :help NERDCreateDefaultMappings for more info - remove "prepend comments" and "right aligned comments". - add support for applescript, calbire, man, SVNcommit, potwiki, txt2tags and SVNinfo. Thanks to nicothakis, timberke, sgronblo, mntnoe, Bernhard Grotz, John O'Shea, François and Giacomo Mariani respectively. - bugfix for haskell delimiters. Thanks to mntnoe. 2.1.18 - add support for llvm. Thanks to nicothakis. - add support for xquery. Thanks to Phillip Kovalev. 2.1.17 - fixed haskell delimiters (hackily). Thanks to Elias Pipping. - add support for mailcap. Thanks to Pascal Brueckner. - add support for stata. Thanks to Jerónimo Carballo. - applied a patch from ewfalor to fix an error in the help file with the NERDMapleader doc - disable the insert mode ctrl-c mapping by default, see :help NERDComInsertComment if you wish to restore it ============================================================================== 9. Credits *NERDComCredits* Thanks to the follow people for suggestions and patches: Nick Brettell Matthew Hawkins Mathieu Clabaut Greg Searle Nguyen Litchi Jorge Scandaliaris Shufeng Zheng Martin Stubenschrott Markus Erlmann Brent Rice Richard Willis Igor Prischepoff Harry David Bourgeois Eike Von Seggern Torsten Blix Alexander Bosecke Stefano Zacchiroli Norick Chen Joseph Barker Gary Church Tim Carey-Smith Markus Klinik Anders Seth Mason James Hales Heptite Cheng Fang Yongwei Wu David Miani Jeremy Hinegardner Marco Ingo Karkat Zhang Shuhan tpope Ben Schmidt David Fishburn Erik Falor JaGoTerr Elias Pipping mntnoe Mark S. Thanks to the following people for sending me new filetypes to support: The hackers The filetypes~ Sam R verilog Jonathan Derque context, plaintext and mail Vigil fetchmail Michael Brunner kconfig Antono Vasiljev netdict Melissa Reid omlet Ilia N Ternovich quickfix John O'Shea RTF, SVNcommitlog and vcscommit, SVNCommit Anders occam Mark Woodward csv fREW gentoo-package-mask, gentoo-package-keywords, gentoo-package-use, and vo_base Alexey verilog_systemverilog, systemverilog Lizendir fstab Michael Böhler autoit, autohotkey and docbk Aaron Small cmake Ramiro htmldjango and django Stefano Zacchiroli debcontrol, debchangelog, mkd Alex Tarkovsky ebuild and eclass Jorge Rodrigues gams Rainer Müller Objective C Jason Mills Groovy, ps1 Normandie Azucena vera Florian Apolloner ldif David Fishburn lookupfile Niels Aan de Brugh rst Don Hatlestad ahk Christophe Benz Desktop and xsd Eyolf Østrem lilypond, bbx and lytex Ingo Karkat dosbatch Nicolas Weber markdown, objcpp tinoucas gentoo-conf-d Greg Weber D, haml Bruce Sherrod velocity timberke cobol, calibre Aaron Schaefer factor Mr X asterisk, mplayerconf Kuchma Michael plsql Brett Warneke spectre Pipp lhaskell Renald Buter scala Vladimir Lomov asymptote Marco mrxvtrc, aap nicothakis SVNAnnotate, CVSAnnotate, SVKAnnotate, SVNdiff, gitAnnotate, gitdiff, dtrace llvm, applescript Chen Xing Wikipedia Jacobo Diaz dakota, patran Li Jin gentoo-env-d, gentoo-init-d, gentoo-make-conf, grub, modconf, sudoers SpookeyPeanut rib Greg Jandl pyrex/cython Christophe Benz services, gitcommit A Pontus vimperator Stromnov slice, bzr Martin Kustermann pamconf Indriði Einarsson mason Chris map Krzysztof A. Adamski group Pascal Brueckner mailcap Jerónimo Carballo stata Phillip Kovalev xquery Bernhard Grotz potwiki sgronblo man François txt2tags Giacomo Mariani SVNinfo Matthew Lee Hinman newlisp, clojure Elias Pipping automake Edwin Benavides actionscript, processing Thomas Rowe hostsaccess Simon Ruderich asciidoc, git, gitcommit, gitrebase Keitheis mako, genshi David conkyrc Miguel Jaque Barbero SVNannotate Stefan Walk sieve Adam Thorsen objj Thilo Six dhcpd, limits, ntp, resolv, rgb, sysctl, udevconf, udevrules Andrey Skvortsov mp Simon Hengel htmlcheetah Matt Tolton javacc Ivan Devat javascript.jquery tpope cucumber,pdf ============================================================================== 10. License *NERDComLicense* The NERD commenter is released under the wtfpl. See http://sam.zoy.org/wtfpl/COPYING. vim-scripts-20130814/doc/detectindent.txt0000644000000000000000000000342712203050723015104 0ustar *detectindent.txt* The Detect Indent Plugin 1.0, Jan 04, 2005 Author: Ciaran McCreesh ============================================================================== 1. Contents *detectindent* *detectindent-contents* 1. Contents |detectindent-contents| 2. :DetectIndent Command |:DetectIndent| Settings |detectindent-settings| 3. Uptime ChangeLog |uptime-changelog| ============================================================================== 2. :DetectIndent Command *:DetectIndent* The :DetectIndent command tries to intelligently set the 'shiftwidth', 'expandtab' and 'tabstop' options based upon the existing settings in use in the active file. Settings *detectindent-settings* When the correct value for 'expandtab' cannot be determined, it will usually retain its existing value. To specify that 'expandtab' should be used where autodetection is impossible, set: > :let g:detectindent_preferred_expandtab = 1 < in your |vimrc| file. To set a preferred value for 'shiftwidth' and 'tabstop' when they cannot be automatically detected, set: > :let g:detectindent_preferred_indent = 4 < in your |vimrc| file. To set limit for number of lines that will be analysed set: > :let g:detectindent_max_lines_to_analyse = 1024 < in your |vimrc| file. ============================================================================== 3. DetectIndent ChangeLog *detectindent-changelog* v1.0 (20050105) * initial release after discussion on irc.freenode.net:#vim ============================================================================== vim:tw=78:ts=8:ft=help vim-scripts-20130814/doc/winmanager.txt0000644000000000000000000006522012203050723014561 0ustar *winmanager* Plugin for a classical Windows style IDE for Vim 6.0 For Vim version 6.0. Last Change: Sun Mar 31 11:00 PM 2002 PST By Srinath Avadhanula (srinath@fastmail.fm) *winmanager-plugin* winmanager.vim is a plugin which implements a classical windows type IDE in Vim-6.0, where the directory and buffer browsers are displayed in 2 windows on the left and the current editing is done on the right. When you open up a new vim window, simply type in :WMToggle. This will start up winmanager. Note This plugin is available only if 'compatible' is not set You can avoid loading this plugin by setting the "loaded_winmanager" variable > :let loaded_winmanager = 1 {Vi does not have any of this} =========================================================================== OVERVIEW *winmanager-overview* |winmanager-installing| Please follow these instructions for installing winmanager. |winmanager-customizing| Describes ways of customizing the window layout, i.e how to club various explorers into groups, how to change their relative position, etc. |winmanager-details| details of using winmanager. keyboard shortcuts and other usage details. |winmanager-commands| commands provided to the user. its useful to set keyboard shortcuts to these commands. |winmanager-settings| settings (typically made in ~/.vimrc) which affect the behavior of winmanager. |winmanager-adding| one of the most important new features of this version is the creation of a framework whereby adding other plugins like explorer.vim or bufexplorer.vim to winmanager. This section describes briefly the implementation of winmanager and then describes how to add a new plugin to winmanager |add-local-help| how to use this text file as a vim help file. |winmanager-bug| bug reports are welcome. |winmanager-thanks| thanks to the many people who helped! =========================================================================== UPDATES *winmanager-updates* The official releases can be found at: > http://vim.sourceforge.net/scripts/script.php?script_id=95 However, I will only update the vim.sf.net version of winmanager.zip in case of a major bug or new feature. For small (and not so bothersome) bug-fixes, I will put the latest version at: > http://robotics.eecs.berkeley.edu/~srinath/vim/winmanager-2.0.htm and also announce it in vim@vim.org when an update occurs. Therefore if you want to keep to be kept abreast of updates, you could check occassionally at vim@vim.org. (you can also use your mail server's filtering capability to effectively subscribe to the announcement). ============================================================================ INSTALLING *winmanager-installing* winmanager.vim should start working as soon as you restart vim after unzipping the .zip file you got this from into ~/.vim (unix) or ~\vimfiles (dos) winmanager only recognizes plugins whose name appears in the global variable > g:winManagerWindowLayout < By default this global variable has the value > g:winManagerWindowLayout = 'FileExplorer,TagsExplorer|BufExplorer' < (which is the value which winmanager uses if its not set in the user's .vimrc) This global variable is responsible for making winmanager recognize the existence of the explorers and simultaneously custome the window layout. See the next section for how to set this variable for various custom layouts of winmanager. ============================================================================ CUSTOMIZING *winmanager-customizing* The layout of winmanager is controlled by changing the value of the "g:winManagerWindowLayout" variable. The general form of this variable is > g:winManagerWindowLayout = 'Group1_Member1,Group1_Member2|Group2_Member_1,Group2_Member_2' < i.e, explorer "groups" are seperated by the '|' character. Within each group, individual explorer plugin names are seperated by the comma (',') character. What winmanager does is display only 1 member from each group in a window. The user can go to a window and press to display the next explorer belonging to that group. This ability to "group" windows is valuable to preserve screen real-estate by using them only as needed. Thus for the default value of 'g:winManagerWindowLayout', winmanager will split the vim window as follows: +-----------+-------------------+ | | | | File | | | explorer | File being | | | edited | | | | +-----------+ | | Buffer | | | explorer | | | | | +-----------+-------------------+ The user can go the [File List] window and press to goto the 'TagsExplorer' view. Removing a plugin name from the 'g:winManagerWindowLayout' variable means winmanager no longer sees that variable. ============================================================================ COMMANDS *winmanager-commands* :WMToggle :toggles the visibility of winmanager. This can also be used to start winmanager for the first time. A handy mapping is: > :map :WMToggle < mnemonic: window-toggle : :FirstExplorerWindow :directly takes you to the first explorer window from the top left corner which is visible. > :map :FirstExplorerWindow < mnemonic: window-first : :BottomExplorerWindow :directly takes you to the last explorere window from the top-left which is visible. > :map :BottomExplorerWindow < mnemonic: window-last : NOTE: winmanager does not provide any mappings by default. These have to set in the user's .vimrc if you want to use mappings. ============================================================================ SETTINGS *winmanager-settings* The values of the following global variables should be set in your .vimrc file if you want a different value than the default: g:persistentBehaviour: if set to 0, then as soon as you quit all the files and only the explorer windows are the ones left, vim will quit. the default is 1, which means that the explorer windows persist even if they are the only ones visible. g:winManagerWidth: the width of the explorer areas. (default 25) g:defaultExplorer: If you want winmanager to assume the functioning of the default explorer.vim which ships with vim, set this variable to 0. (default 1). If this variable is set to 1, then winmanager will behave as follows: . if the user starts off vim with a command such as ":vim some/dir/" then winmanager starts off the window layout with FileExplorer at the top left window. as of now it changes the g:windowLayout variable so that file explorer appears in the top left window. . if on the other hand the user does ":e some/dir/" while _inside_ vim, then the behavior is consistent with the original behavior of the explorer.vim plugin which ships with vim, i.e, the directory is opened in a buffer and the user can use that to open a file in that window. Note that the commands ":Explore" and ":Sexplore" are still available if you set this variable to 1. winfileexplorer.vim, the modification of explorer.vim which ships with this version is different from the standard explorer.vim in that it has display caching. i.e, the directory is read and sorted only the first time. From the second time on, the directory list is cached in a script variable so display is faster. *winmanager-fileexplorer-settings* See |explorer| for details. NOTE: Some of the settings used in explorer.vim are not utlized in winmanager. *winmanager-bufexplorer-settings* g:bufExplorerMaxHeight: the buffer list window dynamicall rescales itself to occupy only the minimum space required to display all the windows. you can set a maximum number of lines for this window. (defualt 15) See |bufexplorer| for details on additional options. NOTE: Some of the settings used in bufexplorer.vim are not utlized in winmanager. ============================================================================= DETAILED HELP *winmanager-details* When winmanager starts up, it divides up the whole vim window into 2 "regions". The region on the left is the "explorer area" where the various explorer plugins are displayed. The region on the right is the "file editing area", where the user works on his current editing session. +--------+-------------------+ | | | | | 2(i) | | 1(i) | | | +-------------------+ | | | +--------+ 2(ii) | | 1(ii) | | +--------+-------------------+ The explorer area (area 1) might contain multiple windows each of which might contain multiple explorers. In the default configuration (for g:winManagerWindowLayout = 'FileExplorer,TagsExplorer|BufExplorer'), the first window can be thought of as containing 2 explorers, the file explorer plugin and the tags explorer plugin, while the bottom window contains bufexplorer by itself. When a window contains multiple explorers, then the user can cycle between them by pressing (mnemonic: next) or (mnemonic: previous). This section describes the various keyboard shortcuts for the 3 plugins which are used with winmanager by default. NOTE: Other plugins might be distributed as add-ins to winmanager. In that case, please refer to the help which ships with that plugin. 1. File Explorer plugin This plugin displays the current directory. Its a modification of the standard explorer.vim which ships with vim6.0. The following keyboard shortcuts are available with this plugin: if on a directory, enters it and displays it in the same area. If on a file, then opens it in the File Editing Area. Attempts to open in the same window as the one visited before, otherwise split open a new window horizontally. if this sounds a bit confusing, it isnt. its the most intuitive behaviour that one expects. <2-leftmouse> (doubleclick) the same as open the file or directory in a new window in the FileEditing area. c change the pwd to the directory currently displayed C change the currently displayed directory to pwd (converse of c) this helps in changing to different drives in windows. i.e, if you are currently on the c: drive and you want to change to the d: drive, you will have to do cd d:\ and then press 'C' in the file explorer area. s select sort field (size, date, name) r reverse direction of sort f add current directory to list of favorites. R rename file D delete file (or range of files in visual mode) - move up one level refresh the file list 2. Buffer Explorer plugin See |bufexplorer-usage| for details. NOTE: In addition to those shortcuts, winmanager adds the following: Opens the buffer under the cursor in a split window even if the current buffer is not modified. This window is dynamically rescaled and re-displayed. i.e, when a new window opens somehwere, the buffer list is automatically updated. also, it tries to occupy the minimum possible space required to display the files. 3. File Editing Area The area where normal editing takes place. The commands in the File Explorer and Buffer Explorer shouldnt affect the layout of the windows here. Some mappings which I find useful (which should be placed in your .vimrc if you plan on using WManager often) is > map :BottomExplorerWindow map :FirstExplorerWindow map :WMToggle Pressing CTRL-W-B should then take you directly to the last explorer window Similarly pressing CTRL-W-F should take you to the first explorer window. CTRL-W-T will toggle between the winmanager visible and invisible. ============================================================================= ADDING NEW PLUGINS *winmanager-adding* This section is of interest only to people who might want to extend winmanager by adding other plugins to it. The casual user can skip it. One of the most important new features of winmanager2.x is the ability to let other users add IDE type plugins to winmanager.vim with a minimum of effort. The way winmanager ships, it usually contains the following plugins: > (FileExplorer, TagsExplorer) (BufExplorer) i.e, FileExplorer and TagsExplorer occupy one window as a single group, while BufExplorer occupies another window. "Adding" a plugin means that you will be able to add a seperate IDE plugin, (call it "YourPlugin" henceforth) either to one of these groups or seperately by itself. This section describes how to accomplish this. Although the section is somewhat lengthy, please rest assured that its really quite simple to do. Have a look at |wintagexplorer|.vim for a small plugin which accomplishes this. To better understand the process, its helpful to give a short description of the workings of winmanager. When a user wants to use your plugin, he "registers" it with winmanager, i.e he adds the "name" of the plugin to the variable g:winManagerWindowLayout in his .vimrc as: " this line goes in the user's .vimrc let g:winManagerWindowLayout = "FileExplorer,TagsExplorer|YourPlugin" When winmanager starts up, it remembers the string "YourPlugin" internally as the plugins "name". (The reason for making this a part of the user's .vimrc is that that way, he can customize the window layout according to his preferences). In addition to registering, the plugin itself initializes a variable called the "title" which starts with the name, such as: > " this line goes in your script file. let g:YourPlugin_title = "[My Plugin Title]" < NOTE: Just like the rest of the hooks provided by your plugin, this global variable name is formed according the rule: g:_title. When winmanager starts up, it performs the following 2 actions: 1. It opens a new file with the "title" provided by the plugin. This automatically ensures that the same buffer is opened for multiple invokations of the plugin. NOTE: It is very important for this reason that the plugin's name be distinct so that there is a low (ideally zero) probability of a file with the same name existing on a user's system. 2. It modifies the "name" string (in this case "YourPlugin") to form "call YourPlugin_Start()" and then |exec|s this string. Thus winmanager communicates with your plugin by using a number of such "hooks" or global functions which all start with the string "YourPlugin" which are defined in the script file you create. In order to enable the dynamic nature of winmanager, where you can have your plugin change its display every time a |BufEnter| or |BufDelete| event occurs, it is necessary to provide a few other hooks. Every time a BufEnter or BufDelete event occurs, winmanager makes a loop over all the visible buffers. Then it "refreshes" the display of that plugin if it is "invalid". The following paragraphs describe the hooks that have to be provided to enable this. *winmanager-hooks* The following is a list of hooks which should be provided. A few of them are optional. Consider the case where you want to add a plugin which you have named "YourPlugin". In the following discussion, a "hook" simply refers to a globally visible function which is formed according to the rule that it start with the string "YourPlugin_", where "YourPlugin" is the name of your plugin. *winmanager-hook-start* YourPlugin_Start() This function is called during initialization. It {Mandatory} can be assumed (and _should_ be) that the focus is already in the buffer where stuff needs to be displayed. i.e, the plugin shouldnt open some other buffer during this function. (i.e, commands such as ":e", ":vsplit", ":wincmd h" etc in this stage are bad. If however, you absolutely need to switch buffers or something which will cause |BufEnter| or |BufDelete| events, then you need to temporarily switch winmanager off by using |WinManagerSuspendAUs|) *winmanager-hook-isvalid* YourPlugin_IsValid() winmanager is dynamic in the sense that it allows the {Mandatory} plugins to change their displays when a BufEnter event occurs. At each BufEnter event, winmanager will cycle through all the visible explorers asking them if their display is "valid". If it isn't, then they will be redrawn by calling the next function. For plugins such as bufexplorer which change with every BufEnter, it is sufficient to make this always return 1. For plugins such as fileexplorer, the display never changes with the BufEnter even. hence in its case, it will always return 0. *winmanager-hook-refresh* YourPlugin_Refresh() If the YourPlugin_IsValid() function returns 0, then {Optional} this function is called to update the display. if the first function always returns 1, then this function need not be defined. NOTE: It is not clear at this time whether this function is really necessary. It might be obsoleted in the future. Future versions might call the _Start() function instead. NOTE: It has been obsoleted as of version 2.1 *winmanager-hook-resize* YourPlugin_ReSize() The plugins can also be dynamically resizable. (the {Optional} current bufexplorer which ships with the winmanager exhibits this behavior). If a plugin creates such a function, then it will be called after its Refresh() function. The reason for not letting the plugin make this a part of its Refresh() function is that sometimes resizing is not allowed, such as in instances where there is no window above or below the plugin to take the slack of a resize. In addition, the plugin should also initialize the following global variable *winmanager-hook-title* g:YourPlugin_title This is the name of the buffer associated with this plugin. The reason for a title in addition to a name is that the name should be such that a global function of that name can be defined. However, the title can be more descriptive and contain spaces etc. For example, the present distribution of FileExplorer has the title "[File List]". Also, winmanager opens a file with this name (using an equivalent of ":e g:YourPlugin_title"), which automatically ensures that new buffers are not eaten up in multiple invokations of winmanager, toggling visibility of buffers, etc. NOTE: It is very important for this reason that the plugin's name be distinct so that there is a low (ideally zero) probability of a file with the same name existing on a user's system. In addition to YourPlugin providing winmanager with hooks, winmanager also provides the following hooks for use by YourPlugin: *WinManagerFileEdit* WinManagerFileEdit({filename}, {split}) This function _must_ be used when the plugin wants to open a new file in the file editing area for editing. Its not sufficient to do something like ":wincmd p" and then ":e filename", because first of all the ":wincmd p" command gets screwed (unfortunately) in the presence of winmanager because of the (sometimes) large movement winmanager does over all visible windows to maintain the dynamic nature. Secondly, doing a simple ":e filename" will not preserve the @# and the @% registers properly, causing handy commands such as |CTRL-^| to totally mis-behave. The first argument should be (preferably) the (complete) name of the file to be opened (including the full path to it if possible). The second argument decides whether winmanager should attempt to open the file in the same window as the last window or to split a new window to open the file. *WinManagerSuspendAUs* WinManagerSuspendAUs() This makes winmanager stop responding to the |BufEnter| or |BufDelete| autocommands like it normally does. Please use this function with care. You will need to use this when you are performing some action which causes these events but you dont want to have winmanager go through the whole isvalid/refresh cycle. NOTE: Take care to definitely reset the behavior by using the next function. *WinManagerResumeAUs* WinManagerResumeAUs() This is the converse of |WinManagerSuspendAUs()|. It makes winmanager start responding to events with the usual isvalid/refresh cycle. *WinManagerForceReSize* WinManagerForceReSize() Normally, winmanager calls the YourPlugin_ReSize() function after the YourPlugin_Refresh(). However, this happens only every |BufEnter| event. When the plugin performs some function which requires it to resize even when there was no |BufEnter| or |BufDelete| event, use this function. Please avoid making a call to YourPlugin_ReSize() because a number of safety checks have to be performed before a resizing is "legal". Finally, if you do plan on making an addin to winmanager, feel free to contact me for help/comments/suggestions. You might also want to take a look at: > http://robotics.eecs.berkeley.edu/~srinath/vim/explorerSample.vim for a simple template of an add-in plugin. ============================================================================= BUGS *winmanager-bug* Please send any comments for improvements or bug-reports to > srinath@fastmail.fm If the bug is repeatable, then it will be of great help if a short description of the events leading to the bug are also given. Note "I dont like winmanager" is not a bug report, only an opinion ;-) ============================================================================= THANKS *winmanager-thanks* I am really grateful to all those who emailed me with bug-reports and comments for improvement. Most of all, a huge thanks to Xiangjiang Ma for his enormous support and extremeley helpful QA. Other people who helped greatly: Madoka Machitani: fixed a couple of typos and gave some ideas for making things more robust. Colin Dearing: gave many useful suggestions for improvement which lead to the fast redraw capability of winmanager Jeff Lanzarotta: for agreeing to make changes to bufexplorer.vim so that bufexplorer.vim would be compatible with the latest version of winmanager.vim and finally all the great support I got from vim@vim.org and comp.editors helped a lot. vim:tw=78:et:ts=4:ft=help:norl: vim-scripts-20130814/doc/EnhancedCommentify.txt0000644000000000000000000004113512203050723016170 0ustar ENHANCED COMMENTIFY *EnhancedCommentify* This is the online help to EnhancedCommentify-script for Vim. It provides a convenient way to comment/decomment lines of code in source files. Currently several languages are supported (eg. Vim, C(++), Ada, Perl, Python and many more), but it is really easy to add other languages. (see 'Adding new languages') ============================================================================== CONTENTS 1. The main function |EnhComm-EnhCommentify| 2. Changing behaviour (options) |EnhComm-Options| 3. Adding new languages |EnhComm-NewLanguages| 4. Changing the keybindings |EnhComm-Keybindings| 5. Adding fallbacks |EnhComm-Fallbacks| 6. Support |EnhComm-Support| 7. Credits |EnhComm-Credits| 8. Known problems |EnhComm-Bugs| ============================================================================== 1. The main function *EnhComm-EnhCommentify* *EnhancedCommentify()* The function which does the main work is called EnhancedCommentify(). It may also be called from outside the script. It takes two to four arguments. EnhancedCommentify(overrideEL, mode [, startBlock, endBlock]) overrideEL -- may be 'yes', 'no' or ''. With UseSyntax option this value is guessed for every invocation of the function. However, if the passed value is not '', the given value will ocerride any checks. mode -- may be 'comment', 'decomment', 'guess' or 'first'. Specifies in what mode the script is run. comment => region gets commented decomment => region gets decommented guess => every line is checked wether it should be commented or decommented. This is the traditional mode. first => blocks is commented or decommented based on the very first line of the block. For single lines, this is identical to 'guess' startBlock -- number of line, where block starts (optional) endBlock -- number of line, where block ends (optional) If startBlock and endBlock are omitted, the function operates on the current line. Examples: > EnhancedCommentify('yes', 'guess') EnhancedCommentify('no', 'decomment', 55, 137) < The first call operates on the current line in the traditional way. Empty lines are also processed. The second call ignores empty lines and decomments all lines from line 55 up to line 137 inclusive. ============================================================================== 2. Changing behaviour (options) *EnhComm-Options* All options are boolean except those marked with a (*). Boolean variables may hold 'yes' or 'no' in any case or abbreviation. So in some sense the variables aren't really of boolean type: they are always strings. So don't forget the quotation marks! Examples: > let g:EnhCommentifyUseAltKeys = 'yes' let g:EnhCommentifyTraditionalMode = 'N' < 'g:EnhCommentifyAltOpen' string (default '|+') (*) Defines the alternative placeholder for the opening string of multipart comments. 'g:EnhCommentifyAltClose' string (default '+|') (*) Same for closing string. Example: > /* This is a problem in C. */ < If the above line would be commented again, it would produce this wrong code: > /*/* This is a problem in C. */*/ < The script recognises this problem and removes the inner comment strings replacing them with the given alternative "escape" strings. In the default configuration you get > /*|+ This is a problem in C. +|*/ < which is fine. When decommenting the line, the alternative strings are replaced with the original comment strings. These two options have no meaning for languages, which have only singlepart comment strings (like Perl or Scheme). 'g:EnhCommentifyIdentString' string (default '') (*) Add this identity string to every comment made by the script. This looks ugly and introduces non-standard comments, but solves several problems (see |EnhComm-Bugs|). Setting this option makes only sense in combination with 'g:EnhCommentifyTraditionalMode'. Examples: The default setting would comment lines like this one > /*foo();*/ < Setting g:EnhCommentifyIdentString to '+' would result in > /*+foo();+*/ < 'g:EnhCommentifyRespectIndent' string (default 'No') Respect the indent of a line. The comment leader is inserted correctly indented, not at the beginning of the line. Examples: g:EnhCommentifyRespectIndent = 'No' > if (bar) { /* foo();*/ } < g:EnhCommentifyRespectIndent = 'Yes' > if (bar) { /*foo();*/ } < 'g:EnhCommentifyIgnoreWS' string (default: 'Yes') Ignore whitespace at the beginning of the line. This decomments indented lines. This option has no effect when setting g:EnhCommentifyRespectIndent to 'Yes'. 'g:EnhCommentifyPretty' string (default: 'No') Add a whitespace between comment strings and code. Mainly for readability. Comments without this space may still be decommented. Examples: g:EnhCommentifyPretty = 'No' > /*foo();*/ < g:EnhCommentifyPretty = 'Yes' > /* foo(); */ < 'g:EnhCommentifyBindPerBuffer' string (default: 'No') Make keybindings local to buffer. 'g:EnhCommentifyBindUnknown' string (default: 'Yes') If the filetype is not known, don't add keybindings. This option has no meaning, when g:EnhCommentifyBindPerBuffer is set to 'No'. 'g:EnhCommentifyBindInNormal' string (default: 'Yes') 'g:EnhCommentifyBindInInsert' 'g:EnhCommentifyBindInVisual' Add keybindings in normal/insert/visual mode. 'g:EnhCommentifyUseAltKeys' string (default: 'No') Use alternative keybindings. instead of X. This may cause trouble on some terminals. Eg. aterm has to be used with 'meta8: true' in the Xresources. This option has no meaning, when g:EnhCommentifyUserBindings is set to 'Yes'. 'g:EnhCommentifyTraditionalMode' string (default: 'Yes') The traditional commentify mode. Check for every line what action should be performed. This option has no meaning, when g:EnhCommentifyUserBindings is set to 'Yes'. 'g:EnhCommentifyFirstLineMode' string (default: 'No') The decision, which action (commenting/decommenting) is performed for a visual block, is based on the first line of this block. This option has no meaning, when one of g:EnhCommentifyUserBindings or g:EnhCommentifyTraditionalMode is set to 'Yes'. 'g:EnhCommentifyUserMode' string (default: 'No') If this option is set to yes, the scripts lets you decide what to do. Then there are several two different keybindings active, one for commenting, one for decommenting. (see |EnhComm-Keybindings|) This option has no effect if any of these options is set to 'yes': - g:EnhCommentifyTraditionalMode - g:EnhCommentifyFirstLineMode - g:EnhCommentifyUserBindings 'g:EnhCommentifyUserBindings' string (default: 'No') This option allows you to choose your own keybindings, without much trouble. Please see below (|EnhComm-Keybindings|) for more details. 'g:EnhCommentifyUseBlockIndent' string (default: 'No') It's a bit difficult to explain, what this option does, so here are some examples (The numbers are just line numbers!): > 1if (foo) { 2 bar(); 3 baz(); 4} else { 5 bar(); 6 baz(); 7} < Commenting lines 1 to 7 in a visual block will give: > /*if (foo) {*/ /* bar();*/ /* baz();*/ /*} else {*/ /* bar();*/ /* baz();*/ /*}*/ < Or commenting lines 3 to 5 will give: > if (foo) { bar(); /* baz();*/ /*} else {*/ /* bar();*/ baz(); } < lines 2 to 3: > if (foo) { /*bar();*/ /*baz();*/ } else { bar(); baz(); } < However you should think about activating g:EnhCommentifyIgnoreWS, if you do not use g:EnhCommentifyRespectIndent or you won't be able to decomment lines, which are commented with this method, if they have leading whitespace! 'g:EnhCommentifyMultiPartBlocks'string (default: 'No') When using a language with multipart-comments commenting a visual block will result in the whole block commented in unit, not line by line. let g:EnhCommentifyMultiPartBlocks = 'yes' > /*if (foo) { frobnicate(baz); }*/ < 'g:EnhCommentifyCommentsOp' string (default: 'No') !!! EXPERIMENTAL !!! When set the comments option is parsed. This is currently only used for the above option in order to set the middle part of the comment. let g:EnhCommentifyCommentsOp = 'yes' > /*if (foo) { * frobnicate(baz); *}*/ < 'g:EnhCommentifyAlignRight' string (default: 'No') When commenting a visual block align the right hand side comment strings. Examples: let g:EnhCommentifyAlignRight = 'no' > /*if (foo) {*/ /* frobnicate(baz);*/ /*}*/ < let g:EnhCommentifyAlignRight = 'yes' > /*if (foo) { */ /* frobnicate(baz);*/ /*} */ < 'g:EnhCommentifyUseSyntax' string (default: 'No') With this option set, the script tries to figure out which filetype to use for every block by using the synID of the block. This improves handling of embedded languages eg. CSS in HTML, Perl in VimL... But be aware, that this feature currently relies on a special form of the names of the syntax items. So it might not work with every syntax file (see |EnhComm-Bugs|). It also calls synID only once for every block! So the first line is significant. Be aware, that "cross" commenting might cause problems. Examples: > 1

a header

2 7link < Commenting line 1 will give: > link < Commenting line 4 will give: >

a header

link < You don't have to change anything. The filetype is still 'html'. However marking the whole paragraph in one visual block and commenting it, will result in the following: > < BTW: Don't expect any sense or correctness of code in these examples. ============================================================================== 3. Adding new languages *EnhComm-NewLanguages* Since 2.3 there is the possibility to use some callback function to handle unrecognised filetypes. This is a substitute to steps a)-d) below. Just add a function called "EnhCommentifyCallback" and set "g:EnhCommentifyCallbackExists" to some value. > function EnhCommentifyCallback(ft) if a:ft == 'foo' let b:ECcommentOpen = 'bar' let b:ECcommentClose = 'baz' endif endfunction let g:EnhCommentifyCallbackExists = 'Yes' < Optionally the steps e) and f) still apply. Of course the old way still works: a) Open the script. b) Go to the GetFileTypeSettings() function. c) Now you should see the large "if"-tree. > if fileType =~ '^\(c\|css\|...' let b:ECcommentOpen = '/*' let b:ECcommentClose = '*/' elseif ... < d) There are two buffer-local variables, which hold the different comment strings. > if fileType =~ '^\(c\|css\|...' let b:ECcommentOpen = '/*' let b:ECcommentClose = '*/' elseif fileType == 'foo' let b:ECcommentOpen = 'bar' let b:ECcommentClose = 'baz' elseif ... < If the new language has only one comment string (like '#' in Perl), we simply leave the CommentClose variable empty (''). That's it! Optionally you can also take step e) and f) in order to complete the setup, but this is not necessary. e) Go to the CommentEmptyLines() function and add the new language to the apropriate "if"-clause. The first will cause empty lines to be processed also. The second make the script ignore empty lines for this filetype. (My rule of thumb: single part comment strings => "yes", multi part comment strings => "no") The default is to ignore empty lines. f) Some syntax-files are "broken". "Broken" in the sense, that the syntax items are not named with xxxFoo or xxxBar, where xxx is the filetype. This scheme seems to be used by ninety percent of all syntax files I saw. This is currently the only way to get the filetype from the synID. If your language may have other languages embedded, you should add the filetype to "if"-clause in CheckPossibleEmbedding(). ============================================================================== 4. Changing the keybindings *EnhComm-Keybindings* The script defines several 's, which can be used to bind the different actions to different keys: - Comment / DeComment - Traditional - FirstLine I don't think, that there's much, what needs to be explained. The 's names are descriptive enough. For every there is also its visual counterpart (eg. VisualComment), which may be used to bind the actions for visual mode. Here an example from the standard bindings: > imap Traditionalji < Clearly this definition binds in insert mode to the traditional Commentify-functionality. Step-by-Step: 1) : leave insert mode 2) Traditional: execute the Commentify-function for this line 3) j: go one line down 4) i: go back to insert mode Another example, which adds a binding for visual mode with the new first- line-mode: > vmap c VisualFirstLine < If you absolutely don't like the standards you can specify your own. Search for '***' in the script. Insert your bindings at this place and add > let g:EnhCommentifyUserBindings = 'yes' < to your .vimrc. That should do the trick. 4.1 Standard keybindings: Meta-Keys: Keys: Traditional-mode: Traditionial x Traditionial + one line down c FirstLine-mode: FirstLine x FirstLine + one line down c User-mode: Comment x Comment + one line down c DeComment X DeComment + one line down C ============================================================================== 5. Fallbacks *EnhComm-Fallbacks* Problems showed up with the php syntax file. In general it worked, but when there was simple text in a line it had an empty synID-name. Then the default kicked in using '&ft', which caused the php comments to be used, instead of the correct HTML comments. So it seemed necessary to provide a possibility to override the standard fallback. The solution looks like the following: 1st step: Create a .vim/ftplugin/foo_enhcomm.vim. 2nd step: Add the fallback-setting function call: call EnhCommentifyFallback4Embedded('synFiletype == "bar"', "baz") 3rd step: Have fun! :) So the general idea is: You specify a test and a fallback filetype. In the test 'synFiletype' can be used to reference the name tag of the current synID. For PHP this looks like: > call EnhCommentifyFallback4Embedded('synFiletype == ""', "html") < ============================================================================== 6. Support *EnhComm-Support* Suggestions, feature requests and bugreports are always welcome! You can contact me with . ============================================================================== 7. Credits *EnhComm-Credits* The following people contributed to EnhancedCommentify resp. reported bugs: (in temporal order) - Vincent Nijs (this script is based on his ToggleCommentify) - Mary Ellen Foster - Scott Stirling - Zak Beck - Xiangjiang Ma - Steve Butts - Preben Randhol - John Orr - Luc Hermite - Brett Calcott - Ben Kibbey - Brian Neu - Steve Hall - Zhang Le - Pieter Naaijkens - Thomas Link - Stefano Zacchiroli Thanks to John Orr and Xiangjiang Ma for their rich feedback and to Luc Hermite for some good improvement suggestions. ============================================================================== 8. Known Problems *EnhComm-Bugs* If g:EnhCommentifyFirstLineMode is used, the following block produces wrong code: > /* This is a comment and not programm code. */ foo = bar; baz(); < With indent string, the script recognises, that the comment is not created by the script and correctly comments the block. Lines like the following will not be correctly decommented. > /*|+ foo +| bar |+ baz +|*/ < The script currently relies on the assumption, that the names of syntax items are of the form '', eg. "phpXy" or "htmlFooBar". This seems to be true except for some rare, esoteric cases. ============================================================================== vim: ft=help:norl:ts=8:tw=78 vim-scripts-20130814/doc/vimplate.txt0000644000000000000000000002526012203050723014252 0ustar *vimplate* vimplate - vim template (example for C++, Perl, LaTeX and make) Author: Urs Stotz Last change: 2005 August 20 ============================================================================== 1. Contents *vimplate-contents* =========== 1. Contents.................: |vimplate-contents| 2. Description..............: |vimplate-description| 3. Usage....................: |vimplate-usage| 4. Subroutines..............: |vimplate-subroutines| 5. Example..................: |vimplate-example| 6. Requirements.............: |vimplate-requirements| 7. Documentation............: |vimplate-documentation| ============================================================================== 2. Description *vimplate-description* ============== Vimplate provides an extensible and powerful template processing system. It is based on Perl and Template-Toolkit. You can create templates for program code, makefiles, letters, html pages, latex etc. As example vimplate contains templates for C++, LaTeX, Perl and Makefile. With vimplate you can write templates which interact with the user. For themes are the functions choice() and input(). You can choose different locale for the function date() and locale(). You can write your own perl code directly in the templates. In case you find my template useful, or have suggestions for improvements, please let me know. If you write a new template, and would like me to add it to the vimplate package please send it to: stotz@gmx.ch ============================================================================== 3. Usage *vimplate-usage* ======== Usage: :Vimplate