aboutsummaryrefslogtreecommitdiff
path: root/vim/doc
diff options
context:
space:
mode:
Diffstat (limited to 'vim/doc')
-rwxr-xr-xvim/doc/bufexplorer.txt513
1 files changed, 513 insertions, 0 deletions
diff --git a/vim/doc/bufexplorer.txt b/vim/doc/bufexplorer.txt
new file mode 100755
index 0000000..06e9223
--- /dev/null
+++ b/vim/doc/bufexplorer.txt
@@ -0,0 +1,513 @@
+*bufexplorer.txt* Buffer Explorer Last Change: 22 Oct 2010
+
+Buffer Explorer *buffer-explorer* *bufexplorer*
+ Version 7.2.8
+
+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.
+ - 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 <your runtime directory>/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
+To start exploring in a newly split horizontal window, use: >
+ \bs or :BufExplorerHorizontalSplit
+To start exploring in a newly split vertical window, use: >
+ \bv or :BufExplorerVerticalSplit
+
+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:
+
+ <F1> Toggle help information.
+ <enter> Opens the buffer that is under the cursor into the current
+ window.
+ <leftmouse> Opens the buffer that is under the cursor into the current
+ window.
+ <shift-enter> Opens the buffer that is under the cursor in another tab.
+ 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.
+ R Toggles relative path/absolute path.
+ T Toggles to show only buffers for this tab or not.
+ 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 Quit exploring.
+ r Reverses the order the buffers are listed in.
+ s Selects the order the buffers are listed in. Either by buffer
+ number, file name, file extension, most recently used (MRU), or
+ full path.
+ 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 <F1> 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*
+
+ *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=1 " Show directories.
+ let g:bufExplorerShowDirectories=0 " Don't show directories.
+The default is to show directories.
+
+ *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 what ever is set by the global &splitbelow
+variable.
+
+ *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.
+
+===============================================================================
+CHANGE LOG *bufexplorer-changelog*
+
+7.2.8 - Enhancements:
+ * Thanks to Charles Campbell for integrating bufexplorer with GDBMGR.
+ http://mysite.verizon.net/astronaut/vim/index.html#GDBMGR
+7.2.7 - Fix:
+ * 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 - Fix:
+ * 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 - Fix:
+ * 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 - Fix:
+ * 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 - Enhancements:
+ * Thanks to David Fishburn for helping me out with a much needed
+ code overhaul as well as some awesome performance enhancements.
+ He 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.
+ Fixes:
+ * 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 - Fixes:
+ * 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 - Fixes:
+ * 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 - Enhancements:
+ * 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.
+ Fixes:
+ * 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 - Fixes:
+ * TaCahiroy fixed several issues related to opening a buffer in a
+ tab.
+7.1.6 - Fixes:
+ * Removed ff=unix from modeline in bufexplorer.txt. Found by Bill
+ McCarthy.
+7.1.5 - Fixes:
+ * Could not open unnamed buffers. Fixed by TaCahiroy.
+7.1.4 - Fixes:
+ * 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 - Fixes:
+ * Added code to allow only one instance of the plugin to run at a
+ time. Thanks Dennis Hostetler.
+7.1.2 - Fixes:
+ * 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 just having a plugin file, no autoload file. By having
+ the autoload, WinManager was no longer working and without really
+ digging into the cause, it was easier to go back to using just a
+ plugin file.
+7.1.1 - Fixes:
+ * A problem spotted by Thomas Arendsen Hein.
+ When running Vim (7.1.94), error E493 was being thrown.
+ Enhancements:
+ * Added 'D' for 'delete' buffer as the 'd' command was a 'wipe'
+ buffer.
+7.1.0 - 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 - Fixed issue with 'drop' command.
+ Various enhancements and improvements.
+7.0.16 - 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
+ <SNR>14_StartBufExplorer..<SNR>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 - Thanks to Mark Smithfield for suggesting bufexplorer needed to handle
+ the ':args' command.
+7.0.14 - 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 - 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 - 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
+ user’s 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 <F1> to be more 'standard'.
+ - Fixed splitting of vertical bufexplorer window.
+ Hopefully I have not forgot something :)
+7.0.11 - Fixed a couple of highlighting bugs, reported by David Eggum. He also
+ changed passive voice to active on a couple of warning messages.
+7.0.10 - 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 - 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 - 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 - 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 - 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. He 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 - Thanks to Mun Johl for pointing out a bug that if a buffer was
+ modified, the '+' was not showing up correctly.
+7.0.4 - 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 - 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 - 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 - 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 - 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 - Added keepjumps so that the jumps list would not get cluttered with
+ bufexplorer related stuff.
+6.2.3 - 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 - 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 - Thanks goes out to Takashi Matsuo for added the 'fullPath' sorting
+ logic and option.
+6.2.0 - 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 - Thanks to Artem Chuprina for finding a pesky bug that has been around
+ for sometime now. The <esc> key mapping was causing the buffer
+ explored to close prematurely when vim was run in an xterm. The <esc>
+ key mapping is now removed.
+6.1.5 - Thanks to Khorev Sergey. Added option to show default help or not.
+6.1.4 - 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 - 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 - Now pressing the <esc> 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 - 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 - 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 - Srinath Avadhanulax added a patch for winmanager.vim.
+6.0.14 - 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 - 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 - Thanks to Madoka Machitani, for the tip on adding the augroup command
+ around the MRUList autocommands.
+6.0.11 - Fixed bug report by Xiangjiang Ma. '"=' was being added to the
+ search history which messed up hlsearch.
+6.0.10 - 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 - Added MRU (Most Recently Used) sort ordering.
+6.0.8 - Was not resetting the showcmd command correctly.
+ Added nifty help file.
+6.0.7 - 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 - 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 - 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 - Thanks to Charles Campbell, Jr. for making this plugin more plugin
+ *compliant*, adding default keymappings of <Leader>be and <Leader>bs
+ as well as fixing the 'w:sortDirLabel not being defined' bug.
+6.0.3 - Added sorting capabilities. Sort taken from explorer.vim.
+6.0.2 - Can't remember. (2001-07-25)
+6.0.1 - 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 <delux256-vim at yahoo dot com>
+
+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=8:ft=help:norl: