*selectbuf.txt* A fast and feature rich buffer explorer.
                    Requires Vim 6.0
            Last Change: 28-Oct-2004 @ 09:01
          Since Version: 3.0
               Revision: 1.3.1
         Plugin Version: 3.4
                 Author: Hari Krishna Dara (hari_vim at yahoo dot com)

                                            *selectbuf-introduction*
                                            *selectbuf-plugin*
SelectBuf is a buffer explorer similar to the file explorer (|file-explorer|)
plugin that comes with Vim, the difference being that file explorer allows you
to view the files on the file system, where as buffer explorer limits the view
to only the files that are already opened in the current Vim session.

==============================================================================
OVERVIEW                                    *selectbuf-overview*

|selectbuf-installation|     Installing the plugin.

|selectbuf-usage|            A brief usage to get you quickly started.

|selectbuf-features|         A description of features.

|selectbuf-mappings|         Mappings created in the browser window.

|selectbuf-commands|         A description of commands that can be issued
                             on Vim command-line.

|selectbuf-settings|         An explanation of how to configure the plugin.

|selectbuf-filetype|         Making use of the "selectbuf" filetype and
                             configuring the syntax coloring in the browser
                             window.

|selectbuf-deprecations|     A list of deprecated features.

|perforce-limitations|       Current limitations of the plugin.

|selectbuf-changes|          A change list for current version from the previous
                             versions.

|selectbuf-known-issues|     A list of known issues.

|selectbuf-wishlist|         Wishlist items that may be worth doing for a future
                             version.

|selectbuf-acknowledgements| Acknowledgements.
==============================================================================

                                            *selectbuf-installation*
To install, place the plugin in one of the runtime plugin directories along
with the genutils.vim and multvals.vim scripts that it depends on. This
typically is .vim/plugin or vimfiles/plugin directory under your home
directory. To get the latest versions of these plugins, goto the following
webpages:
     selectbuf.vim: http://www.vim.org/script.php?script_id=107
     genutils.vim:  http://vim.sourceforge.net/script.php?script_id=197
     multvals.vim:  http://vim.sourceforge.net/script.php?script_id=171

The distribution contains 2 files:
    - The selectbuf plugin itself (selectbuf.vim).
        - Should go into the user plugin directory.
    - The help file (this file) (selectbuf.txt).
        - Should go into the user doc directory.

If you obtained the plugin as a zip archive,
    - Just extract it in your runtime directory.
    - Start a new instance or go to an existing instance of vim.
    - Execute:
>
        :helpt <your runtime directory>/doc
<
      This should generate the help tags for the selectbuf plugin help.

Later, if you need to temporarily disable the plugin without needing to remove
the file or move it into a different directory, you can set the loaded_selectbuf
variable in your vimrc. You can also set the no_selectbuf_maps to disable just
the mappings defined in this plugin or no_plugin_maps to disable mappings in all
the plugins (provided they honor this setting), in your vimrc.

In addition, it is recommended that you apply the following patch to Vim 6.1
to avoid flooding the |messages| with unwanted stuff.

      6.1.344  ":silent filetype" writes to the message history

                                            *selectbuf-activation-key*
                                            *selectbuf-plug-mapping*
Next, if you would like to change the activation key from the default <F3> to
something else, you need to customize it in your vimrc. Choose a function key or
a key sequence (say \sb) and add the following line to your vimrc: >

       nmap <silent> <unique> \sb <Plug>SelectBuf
<
After you restart Vim, you will be able to open the browser window by pressing
\sb in the normal mode.
==============================================================================

                                            *selectbuf-usage*
To use the plugin, first active the window by pressing the activation key
(the default <F3>, or whatever you chose during the |selectbuf-installation|
step). This opens a window titled "[Select Buf]" and displays a list of all the
regular buffers that are loaded in the current Vim session.

There are probably other buffers loaded that are used by plugins (such as the
one used by selectbuf itself) and others such as the ones loaded by help.
SelectBuf by default hides these buffers, because it is rare that you want to
edit such buffers (see |selectbuf-settings| and |selectbuf-mappings| for ways to
change this behavior)

To open a buffer, you can double-click left-mouse button on the line
corresponding to the buffer or move your cursor and press <Enter> key. You can
press the same key that you used to activate the browser to even close it
without selecting any buffer. To see other useful commands for opening buffers,
see |selectbuf-mappings|.

                                            *selectbuf-marks*
Everytime the browser window is opened, the plugin creates three marks, viz.,
a, b and c (|mark|). These marks (accessed as 'a, 'b and 'c) always points to
the next, previous and the current buffers in the order of their buffer
numbers, irrespective of how the buffers are sorted. If you want to go to the
line corresponding to the current buffer, you just have to type "'c" (without
the quotes).
==============================================================================

                                            *selectbuf-features*
Here is a brief list of important features:
    - Incremental update of the browser for speed. The browser caches the list
      of buffers and incrementally updates them as and when the new buffers
      are added and the old ones are deleted, instead of regenerating the list
      every time the browser needs an updated. This is a lot more efficient
      especially when you work with a large set of files at a time in the same
      vim session and it happens quite often, when you use quickfix through
      make, grep, id-utils etc. This makes the browser a lot more responsive
      both when used stand-alone and when used in WinManager. When you want to
      open the browser window, it is almost instantaneous, no matter you have
      just 10 files open or 1000 files.
    - Hide buffer numbers. This is useful when used under WinManager or in
      combination with the vertically-split "Always On" mode as mentioned
      below. This reduces the horizontal real-estate required for the plugin
      when all you really care about is the buffer name.
    - Block operations for buffer deletes. You can block select the list of
      buffers and delete/undelete/wipeout at once. Some of the plugins often
      produce huge number of temporary buffers with similar looking names (or
      unnamed buffers), which can be selected as a block if sorted
      by name. If you want to delete all the buffers of a particular type,
      simply sort by type so that they are all adjacent and do a block delete.

      If you have multiselect installed, you can also do multiple block
      selections. E.g., you can block select all the Java files by executing
            :MSMatchAdd \.java\>
    - Flexible configuration. Most of the significant features can be turned
      on and off and can be given a default value. The key associations for
      all the commands can be customized. The syntax coloring can be changed.
      The features can also be changed interactively.
    - "Always On" mode. You can configure the browser to be always on and switch
      between different available modes interactively. The always on mode is
      very useful if you like to use mouse and would like to have a quick
      access to the list of buffers displayed in a vertically split left
      window. If you choose to use the plugin under WinManager, you don't have
      to do any additional configuration.
    - Marks for a quick access to the next, previous and current buffers in the
      order of their buffer numbers.
    - The browser when opened remembers the existing window sizes and
      automatically restores them after the browser window is hidden. This is
      important if you work with multiple windows.
    - Other standard features found in a few of the other buffer explorers such
      as sorting, MRU access to buffers, syntax coloring, help header and
      more. There are more ways that you can sort and the sorting is also
      faster too.
    - Some limited extensibility through the "selectbuf" filetype.
==============================================================================

                                            *selectbuf-mappings*
The plugin defines a set of mappings to be used in the browser window. A brief
description of these commands can be seen right in the window by pressing the
default help toggle key, ?. Each one of the mappings has a corresponding <Plug>
mapping that can be used to change the key association from your vimrc file. As
an example the below mapping when placed in your vimrc changes the key that
activates the help header to <C-H> instead of the default ?. This leaves ? for
doing reverse searches. >

        nmap <script> <silent> <Plug>SelBufTHelpKey <C-H>
<
Note that the semantic is reversed from the usual plugin convention (as
described in the "MAPPING" section under |write-plugin|), as the <Plug> mapping
is lhs instead of rhs. This is so that the key can later be obtained for display
purposes, which can be done only if the key is the rhs (there is no vim function
to obtain the lhs of a mapping).

                                *SelBufDeleteKey*        *SelBufMSelectKey*
                                *SelBufOpenKey*          *SelBufQuitKey*
                                *SelBufRefreshKey*       *SelBufSelectKey*
                                *SelBufShowSummaryKey*   *SelBufSortRevKey*
                                *SelBufSortSelectBKey*   *SelBufSortSelectFKey*
                                *SelBufTBufNumsKey*      *SelBufTDetailsKey*
                                *SelBufTHelpKey*         *SelBufTHiddenKey*
                                *SelBufTHidePathsKey*    *SelBufWipeOutKey*
                                *SelBufWSelectKey*       *SelBufLaunchKey*


Here is a table of all the mappings and their default key associations (with the
corresponding buffer local command name in parenthesis):

    Mapping               Default       Description~
    SelBufSelectKey       <CR>          Open buffer in the previous window
                                        (which could be the current window
                                        itself if |selBufBrowserMode| is
                                        "switch"). (SBSelect)
    SelBufMSelectKey      <2-LeftMouse> Same as SelBufSelectKey, but using
                                        mouse. The default is to double click
                                        the item but you can change it to say
                                        <RightMouse> if it is more convenient.
                                        In fact there is nothing to prevent you
                                        from assigning another key to this
                                        instead of a mouse click. (SBSelect)
    SelBufOpenKey         O             Same as SelBufSelectKey, but keep
                                        browser open. (SBOpen)
    SelBufWSelectKey      <C-W><CR>     Split open the current buffer.
                                        (SBWSelect)
    SelBufQuitKey         q             Quit browser. Under WinManager, this
                                        just moves the cursor back to the
                                        previous window. (SBQuit)
    SelBufDeleteKey       d             Delete/Undelete current buffer
                                        (list/unlist), see |:delete| and
                                        'buflisted'. Works on visual selections
                                        too. See also |selectbuf-multiselect|.
                                        (SBDelete)
    SelBufWipeOutKey      D             |:wipeout| current buffer.
                                        Works on visual selections too. See also
                                        |selectbuf-multiselect|. (SBWipeout)
    SelBufRefreshKey      R             Refresh browser. (SBRefresh)
    SelBufShowSummaryKey  <C-G>         Shows summary of the current buffer.
                                        (SBSummary)
    SelBufSortSelectFKey  s             Select next sort field. (SBFSort)
    SelBufSortSelectBKey  S             Select previous sort field. (SBBSort)
    SelBufSortRevKey      r             Reverse the sort direction. (SBRSort)
    SelBufLaunchKey       A             Launch the current buffer with in an
                                        external program. On windows, this by
                                        default invokes the program that is
                                        associated based on the extension of the
                                        file (the Explorer File Associations).
                                        On non-windows platform, you will have
                                        to configure |selBufLauncher| to launch
                                        the right program yourself. Most useful
                                        for viewing html files. Also see,
                                        |SBLaunch|. (SBLaunch)
    SelBufTBufNumsKey     p             Toggle showing buffer numbers.
                                        (SBTBufNums)
    SelBufTDetailsKey     i             Toggle showing details. (SBTDetails)
    SelBufTHelpKey        ?             Toggle showing help header. (SBTHelp)
    SelBufTHiddenKey      u             Toggle showing unlisted buffers.
                                        (SBTHidden)
    SelBufTHidePathsKey   P             Toggle showing full path. (SBTPaths)


Note that indicators or path should currently be displayed to be able to sort by
that criteria. To be able to sort by MRU, the |selBufDisableMRUlisting| should
not have been enabled.

Note that SelBufDeleteKey only sets/clears the 'buflisted' option, to completely
remove a buffer from the current Vim session, use SelBufWipeOutKey.  Deleting a
buffer instead of wiping it out is useful to hide the buffer temporarily. To
undelete the buffer, first show the unlisted buffers using the SelBufTHiddenKey
and press SelBufDeleteKey again on the buffer. For more information see
|:delete| and |:wipeout|.

For convenience, <C-R><C-F> (|c_CTRL-R_CTRL-F|) is mapped to expand to the full
path name of the buffer under the cursor, no matter what the current display
mode is.

                                            *selectbuf-buffer-search*
There are a few mappings provided to search for buffers by their number quickly.
The plugin maps numbers 1 to 9 such that you can simply start typing the buffer
number to start a search for it. It also maps number 0 such that the cursor is
taken on to the header. This can be used to quickly move to the start of the
buffer list before doing a search for the buffer.
==============================================================================

                                            *selectbuf-commands*
The plugin defines some commands that can be invoked on the vim |command-line|.

                                            *SelectBuf*
SelectBuf       This command can be used instead of the
                |selectbuf-activation-key|, and it works exactly like its
                corresponding mapping. If the browser is already opened, it just
                moves the cursor to the browser window (and updates it),
                otherwise it opens a new window for the browser and takes the
                cursor to the new window.

                                            *SBSettings*
SBSettings      This command is an interactive way of temporarily modifying
                script settings without needing to remember the names of the
                global variables and to remember to run |SBInitialize| every
                time.  The command shows the list of settings in a tabular form
                to choose one from. Enter the index of the setting that you
                would like to modify or just press <Enter> to quit the dialog.
                Selecting a setting will first show you the current value of
                that setting and then give you a prompt to enter new value for
                it. Again, if you don't want to change the value just hit
                <Enter>.

                Note that the settings are modified only in the current Vim
                session. If you want the change to take place across sessions,
                lookup the global variable name corresponding to the setting and
                add an entry in your vimrc as described in |selectbuf-settings|.

                                            *SBInitialize*
SBInitialize    This command reinitializes the plugin and imports any changes
                done to the plugin settings in the global name space. If any
                plugin specific global variables are modified in the current
                Vim session, they are not imported until you run this command
                or any other command that results in a re-initialization of
                the plugin (like |SBSettings|).

                                            *SBLaunch*
This is a global command that can open the current buffer (with no arguments),
or a specified buffer/file (by path) in an external program. On MS Windows, this
works just like the Start->Run dialog, using the Explorer File Types and default
associations (which means, it opens your default browser for an HTML file and
perl interpreter on .pl files etc.), but for other systems, you need to
configure |selBufLauncher| setting for this to work.

When in the browser window, the command with no arguments defaults to the buffer
under the cursor.

Note that on windows, if you need to configure |selBufLauncher| setting, then it
is recommended that you prefix the commands with "start" such that you will not
end up seeing a dos window hanging around until you quit the external program
(See |:!start|).

On Windows, using the default launcher command, you can even start applications
(such as another gvim instance) using this command. If the application is not in
the path, you may have to specify the path to the application.
>
        :SBLaunch gvim
<
The global mapping defined for this command, if you prefer, is <Leader>sbl,
which you can change using <Plug>SelBufLaunchCmd.

                                            *SBBufToHead*
                                            *SBBufToTail*
These commands can be used to move a buffer to the head or to the tail in the
MRU order without needing to open/close the buffers. E.g., to push the current
file to the end of the MRU list (so that it will appear at the end of the list
the next time browser is updated, if the current sort order is MRU): >

        :SBBufToTail %
<
To move buffer 10 to the head of the MRU list (so that it will appear at the
start of the list the next time browser is updated, if the current sort order is
MRU): >

        :SBBufToHead 10
<
                                            *SBExec*
This command allows you to execute any built-in or user-defined command that
takes in a list of buffer/file names over a selected block of buffers in the
browser window. All that you need to do is first create a selection by using
mouse or keyboard and execute :SBExec with the ex-mode command (and its
arguments) that you would like to execute on them (the command should accept a
buffer/file name). E.g., you can sort the list by filetype and select all the
java files and execute the following command on them:
>
        :SBExec next
<
This results in Vim setting |:args| to the set of java files (you can then use
|:argdo| and related commands to manipulate the buffers as a set).

You can also execute any external command on the selected buffers by prefixing
it with a bang (|:!|). E.g., you can permanently remove the selected files from
the filesystem by using the following command:
>
    :SBExec !rm
<
In this case, you would of course want to create a custom command which would
first confirm before executing the external rm command (see
|selectbuf-extend-examples|).

You can also execute the user-defined commands that the plugins add (such as a
source control plugin) on the buffer. E.g., to execute perforce checkout command
on a set of files:
>
    :SBExec PE
<
See |selectbuf-extend| for ways to create a new mapping or custom command for
the above.

If you specify string "%s" in the command, it is replaced with the buffer names
before executing the command and otherwise, the buffer names are appended at the
end of the command. You can also specify "%b" to replace with the buffer numbers
instead of the buffer names, for those ex commands that understand only buffer
numbers. Don't use "%n" if you are executing an external command, as the
external command will not understand the Vim buffer numbers. To pass in "%"
itself, escape it by prefixing with another "%".

Note: Currently only "s" and "n" following a "%" have special meaning, so other
characters following "%" will get through without any processing, but some of
these characters might acquire special meaning in the future, so if your
intention is to pass "%" as part of the command, always prefix it with another
"%".

See |selectbuf-extend| for a way to create shortcuts to execute such commands.

To select buffers that are non-adjacent to each other, see
|selectbuf-multiselect|.
==============================================================================

                                            *selectbuf-settings*
The plugin provides support for customization through a set of global
variables, in addition to the customization of the activation key as described
in |selectbuf-activation-key| and mappings as described in |selectbuf-mappings|.
When assigned a value in the vimrc, these global variables are read in by the
plugin during the startup and are used to customize it. As an example, the below
commands when placed in vimrc make the browser stay always visible in a
vertically split left window. >

        :let g:selBufBrowserMode = "keep"
        :let g:selBufUseVerticalSplit = 1
        :let g:selBufSplitType = "topleft"
<

                        *selBufAlwaysHideBufNums*     *selBufAlwaysShowDetails*
                        *selBufAlwaysShowHelp*        *selBufAlwaysShowHidden*
                        *selBufAlwaysShowPaths*       *selBufBrowserMode*
                        *selBufDefaultSortDirection*  *selBufDefaultSortOrder*
                        *selBufDelayedDynUpdate*      *selBufDisableMRUlisting*
                        *selBufDisableSummary*        *selBufEnableDynUpdate*
                        *selBufIgnoreCaseInSort*      *selBufIgnoreNonFileBufs*
                        *selBufRestoreWindowSizes*    *selBufSplitType*
                        *selBufUseVerticalSplit*      *selBufDoFileOnClose*
                        *selBufDisplayMaxPath*        *selBufLauncher*

Here is a table that describes the names of the global variables with their
defaults.

    Setting                     Default Description ~
    selBufAlwaysHideBufNums     0       The plugin by default shows the buffer
                                        numbers, but if you always want them
                                        to be hidden, set this to 1. If the
                                        first time the plugin is activate, is
                                        through WinManager, and if this setting
                                        is not overridden in vimrc, then the
                                        buffer numbers are automatically hidden.
                                        Note that you can always toggle this
                                        using the |SelBufTBufNumsKey|,
                                        irrespective of this setting.
    selBufAlwaysShowDetails     0       The plugin by default hides extra
                                        details for the buffers (that is shown
                                        by using the |:ls| command), but if
                                        you want that to be always displayed,
                                        set this to 1. Note that you can
                                        always toggle this using the
                                        |SelBufTDetailsKey|, irrespective of
                                        this setting.
    selBufAlwaysShowHelp        0       By default, the plugin hides the help
                                        header as it occupies a lot of real
                                        estate. But, if you want this to be
                                        displayed then set this to 1. Note
                                        that you can always toggle this using
                                        the |SelBufTHelpKey| irrespective of
                                        this setting.
    selBufAlwaysShowHidden      0       The plugin by default hides the hidden
                                        buffers, but if you want them to be
                                        always shown, set this to 1. Note that
                                        you can always toggle this using the
                                        |SelBufTHiddenKey|, irrespective of
                                        this setting.
    selBufAlwaysShowPaths       2       When 0, the plugin hides the full
                                        path names of the buffers, but if you
                                        always want them to be shown, set this
                                        to 1 or 2. Setting it to 2 will make the
                                        plugin split the path component separate
                                        from the filename (gives the best of
                                        both 0 and 1). Also see,
                                        |selBufDisplayMaxPath| setting.
                                        Note that you can always toggle
                                        this using the |SelBufTHidePathsKey|,
                                        irrespective of this setting.
    selBufBrowserMode           split   The mode of operation for browser. In
                                        split mode the plugin always
                                        split-opens the browser window
                                        (resulting in a new window). In switch
                                        mode, the existing window is reused for
                                        the browser, so quitting the browser
                                        using |SelBufQuitKey| will switch back
                                        to the original buffer. In keep mode,
                                        the plugin split-opens the window, but
                                        leaves the window open until you
                                        explicitly close it. The selected buffer
                                        will be opened in the last accessed
                                        window.
    selBufDefaultSortDirection  1       Select the default sort direction. The
                                        browser will start in this sort
                                        direction, but it can later be changed
                                        by using the |SelBufSortRevKey|. The
                                        default is to sort in the ascending
                                        order. Set it to -1 to sort in the
                                        descending order.
    selBufDefaultSortOrder      mru     Select the default sort order. The
                                        browser will start with this sort order,
                                        which can always be changed by using the
                                        |SelBufSortSelectFKey| and
                                        |SelBufSortSelectBKey|. Other possible
                                        values are: number, name,
                                                             path, type,
                                                             indicators, mru.
    selBufDelayedDynUpdate      0       If you enable this, the plugin waits
                                        for the browser window to get focus
                                        before making updates for the buffers
                                        added and deleted (and when MRU order
                                        changes), even when the browser window
                                        is visible. This again is a little more
                                        efficient than making the updates
                                        immediately. If you use mouse to select
                                        the buffers and you use MRU sort
                                        ordering, then you would want to keep
                                        this setting disabled as otherwise you
                                        can end up double-clicking on a wrong
                                        buffer.
    selBufDisableMRUlisting     0       Disable generating an MRU listing of
                                        the file usage. If you don't use MRU
                                        sorting, then disabling this should
                                        improve the performance a little bit.
                                        Also, before opening a large set of
                                        files at one time (using :next */java
                                        command, e.g.), disabling this is
                                        advisable to avoid the MRU overhead.
    selBufDisableSummary        1       Setting this to a zero will enable some
                                        summary messages, but if your
                                        'cmdheight' setting is too small (1 is
                                        usually too small), you may end up
                                        seeing too many more prompts, so it is
                                        recommended to increase the 'cmdheight'
                                        value to at least 2.
    selBufEnableDynUpdate       1       By default, the plugin dynamically
                                        updates the browser as and when buffers
                                        get added and deleted. This usually is
                                        much more efficient than generating the
                                        list every time, but if you want to
                                        disable this feature, then set this to
                                        0.
    selBufIgnoreCaseInSort      0       A non-zero value for this setting makes
                                        the sort compare the buffer names and
                                        paths case-insensitively.
    selBufIgnoreNonFileBufs     1       Normally, the plugin ignores all the
                                        non-file buffers (those that have
                                        'buftype' option set) for MRU ordering
                                        and a few others. These are usually the
                                        buffers that belong to various plugin
                                        and you don't really want to see them in
                                        the list. Setting this to 0 will make
                                        the plugin treat all the buffers same.
    selBufRestoreWindowSizes    1       A non-zero value for this setting
                                        will make the plugin save the window
                                        sizes when the browser is opened and
                                        restore them while closing it. Set this
                                        to 0 to disable the feature.
    selBufSplitType             <none>
                                        If set, this is prefixed to the |split|
                                        command used for opening the browser
                                        window. See |:vertical| for possible
                                        options.
    selBufUseVerticalSplit      0       If you set this to 1, the plugin uses
                                        vertically-split window when it opens
                                        the browser window. This can always be
                                        achieved by setting "selBufSplitType" to
                                        "vertical" but it is recommended to use
                                        this setting instead, as the plugin does
                                        some additional customizations when this
                                        is on.
    selBufDoFileOnClose         1       By default, the plugin executes the
                                        |:file| command after the plugin window
                                        is closed, in case you lost track of
                                        which file you are looking at. But this
                                        will have a side effect of adding a line
                                        to your |:messages|. If you don't like
                                        this, set this to 0 to disable this
                                        feature.
    selBufDisplayMaxPath        -1      This setting specifies the width to
                                        which the paths should be trimmed to.
                                        When the path name for a buffer is too
                                        long to be fit in the current window,
                                        the more distinguishing path components
                                        will normally be pushed out of the
                                        display. Setting this value to a
                                        positive number will allow you to
                                        always see these path components instead
                                        of loosing them to the window.
    selBufLauncher              "!start rundll32 url.dll,FileProtocolHandler" (windows)
                                "" (other platforms)                       
                                        The command that should be used to
                                        launch files when |SBLaunch| command is
                                        used. On windows it is set to a value
                                        that is acceptable to most of the users
                                        and is empty on other platforms. You can
                                        set it to any Vim built-in/user-defined
                                        or external command (by prefixing it
                                        with a bang (|:!|)) that accepts a
                                        filename as an argument.


Note that these variables are required only during the startup and
consequently are removed by the plugin after the initialization is complete.
This avoids cluttering the global name space. If you want to change the values
of these settings in the current vim session, then use |SBSettings| command.

                                            *selectbuf-header*
The browser window always shows a one-line header with a brief information on
what display related settings are currently on. An example header is given
below: >

    "= Sorting=mru,showDetails=0,showHidden=0,showPaths=0,hideBufNums=0
<
==============================================================================
                                            *selectbuf-filetype*
                                            *selectbuf-syntax-coloring*
The syntax colors in the browser window can easily be customized, by following
the same procedure that you would follow for customizing any language syntax
file. All the syntax groups defined by the plugin start with the prefix "SelBuf"
and they all are linked to a default highlighting group. Here is a table with
all the defaults:

    Syntax Group            Default Highlighting Group ~
    SelBufHelpLine          Comment
    SelBufMapping           Special
    SelBufSummary           Statement
    SelBufKeyWords          Keyword
    SelBufKeyValues         Constant
    SelBufBufNumber         Constant
    SelBufBufIndicators     Label
    SelBufBufName           Directory
    SelBufPath              Identifier
    SelBufSummary           Special

To change the colors for any of the above syntax groups, simply link them to any
existing or new highlighting group as below (you can place it in your vimrc):
>
	:highlight link SelBufSummary WarningMsg
<
In addition, the plugin also sets 'filetype' of the browser window to
"selectbuf". This allows you to create a syntax/selectbuf.txt file in your
'runtimepath' to define additional syntax rules such that you can highlight
important keywords etc. that occur in the path, buffer name or indicators (or
the entire line).

All that the plugin actually does is to define four syntax clusters as place
holders and include them as part of the four different syntax matches that it
defines. The user then just needs to create additional syntax rules and add them
to the corresponding cluster. Here is a table that lists these four clusters:

        Match Group             Cluster Name ~
        SelBufBufName           SelBufBufAdd
        SelBufPath              SelBufPathAdd
        SelBufBufIndicators     SelBufIndAdd
        SelBufBufLine           SelBufLineAdd

As an example, here is a simple syntax file (named syntax/selectbuf.vim) that
will highlight the keywords "oracle" and "mssql" in different colors when they
occur in the path:
>
        syn keyword SelBufOracle oracle
        syn keyword SelBufMssql mssql
        hi link SelBufOracle Special
        hi link SelBufMssql Underlined
        syn cluster SelBufPathAdd add=SelBufOracle,SelBufMssql
<
(I actually use something like above to easily distinguish the files with the
same name that exist in oracle and mssql subdirectories, this is very useful,
especially with the new split mode (see, |selBufAlwaysShowPaths|)).

Though the above example shows defining only simple keywords, you can create
complex |syn-match|'s and include them as part of the corresponding cluster.

                                            *selectbuf-extend*
                                            *selectbuf-API*
The filetype customization is not limited to syntax coloring. It is possible to
create a filetype plugin (ftplugin/selectbuf.vim) that actually enables you to
extend the functionality with new commands and customize further in the browser
window. The plugin provides public functions to get the buffer number so that
you can create new commands that operate on the buffer list.
>
        " Buffer number of the current buffer in the list.
        " Returns -1 if not on a buffer line.
        int SBCurBufNumber()
        " Buffer number of the buffer at the given line in the list.
        " Returns -1 if not on a buffer line.
        int SBBufNumber(int line)
        " Update line for given buffer.
        int SBUpdateBuffer(int bufNr)
        " Returns the list of all the buffers in a form that can be directly
        "   used in an ex command accepting buffer names, for the given range.
        "   When multiselect is installed and there are multiple selections
        "   currently existing, the parameters are ignored.
        String SBSelectedBuffers(int firstline, int lastline)
        " Same as SBSelectedBuffers(), except that only the buffer numbers are
        "   returned.
        String SBSelectedBufNums(int firstline, int lastline)
        String SBSelectedBuffers(int firstline, int lastline)
<
It is also possible for other plugin writers to customize selectbuf such that
new commands are automatically added to the browser. For example, a CVS plugin
can add ftplugin/selectbuf_cvs.vim with commands such as the below, which get
automatically added when the browser window is opened (assume that "CVS edit
<file>" is the actual command to open a file for "edit"):
>
        " Define a CVS command to edit the current file.
        nnoremap <buffer> \cvse :SBExec CVS edit<CR>
        vnoremap <buffer> \cvse :SBExec CVS edit<CR>
<
Or a more generic command, such as:
>
        nnoremap <buffer> \cvs :SBExec CVS 
        vnoremap <buffer> \cvs :SBExec CVS 
<
                                            *selectbuf-extend-examples*
As an example, here is a simple custom command that selects the current buffer
saves it and returns back to browser window.
>
        nmap <buffer> <C-S> O:w<CR>:SelectBuf<CR>
<
which can also be written more precisely as:
>
        nnoremap <silent> <buffer> <C-S> :call <SID>SaveCurrentBuffer()<CR>

        if !exists('*s:SaveCurrentBuffer'')
          function! s:SaveCurrentBuffer()
            if SBCurBufNumber() != -1
              normal O
              w
              SelectBuf
            endif
          endfunction
        endif
<
This command will then be defined as part of the browser window (make sure you
use <buffer> option for maps and -buffer option for commands). Note that the if
!exists block is a recommended practice (and required in this case) for writing
ftplugins (see |ftplugin| for this and other guidelines for writing a new
ftplugin). 

Other examples:
    - create a command to backup the selected files to a predefined location,
      something like this:
>
        nnoremap <silent> <buffer> <Leader>b :SBExec !cp %s /backup
<
    - create a command to remove selected files from the filesystem as well as
      the corresponding buffers from Vim.
>
        vnoremap <silent> <buffer> <Leader>r :call <SID>RemoveFiles()<CR>

        if !exists('*s:RemoveFiles')
          function! s:RemoveFiles() range
            let opt = confirm('Do you want to remove selected files '.
                \ 'permanently (from filesystem and vim)?',
                \ "&Yes\n&No", 2, 'Question')
            if opt == 1
              let selBufs = SBSelectedBuffers(a:firstline, a:lastline)
              let selBufNums = SBSelectedBufNums(a:firstline, a:lastline)
              exec '!rm' selBufs
              exec 'bwipeout' selBufNums
            endif
          endfunction
        endif
<
    - If multiselect.vim is installed, you can have it automatically select
      files and do operations on them, e.g., you can creat a command to have all
      the open files under src selected and zipped (using info-zip commandline
      tool). This assumes that the path is being currently shown:
>
        command! -buffer BackupSrcChanges :call <SID>BackupSrcChanges()

        if !exists('*s:BackupSrcChanges')
          function! s:BackupSrcChanges()
            let zipFile = inputdialog('Enter zip file: ', '/tmp/src.zip')
            if zipFile != '' && search('^"= ', 'w')
              +,$MSMatchAdd /src/
              exec 'SBExec !zip' zipFile
            endif
          endfunction
        endif
<
See help on |SBExec|.

The perforce plugin for Vim that can be downloaded from www.vim.org comes with
selectbuf_perforce.vim ftplugin that adds a few commands this way to the
SelectBuf window.
==============================================================================

                                            *selectbuf-multiselect*
If multiselect.vim plugin is installed, the plugin automatically makes use of
the multiple selections, if any, for the commands that operate on visual
selections (such as buffer deletion or wipeout and the :SBExec command).

It also maps the <Space> to toggle selections, so you can press spacebar on any
buffer name and have it added to or cleared from the selection automatically.
This also works on visual blocks.
==============================================================================

                                            *selectbuf-deprecations*
- With the addition of the feature to split file paths,
  selBufHighlightOnlyFilename setting is unnecessary and so is no longer
  supported.
- Dropped selBufWindowName, selBufRemoveBrowserBuffer, selBufOpenInNewWindow,
  selBufAlwaysWrapLines, selBufAlwaysShowDirectories, selBufIntWithWinManager
  settings.

==============================================================================
                                            *selectbuf-limitations*
- When using incremental update feature of the plugin, there is no attempt made
  to keep the file paths up to date when you change the current directory. This
  however impacts only when the selBufAlwaysShowPaths has value 1, and can be
  worked-around by refreshing the browser window.
- When using incremental update feature of the plugin, there is no attempt made
  to update the '%' and '#' buffers when the active window is changed. This
  impacts only when selBufAlwaysShowDetails is enabled and can be worked around
  by reloading the current buffer using the :e command (with no arguments)

==============================================================================
                                            *selectbuf-changes*

                                            *selectbuf-changes-3.4*
- Faster sorting of buffer list.
- If multiselect is installed, you can use spacebar to toggle selection. See
  |selectbuf-multiselect|.
- Fixed a bug in case-insensitive sorting of buffer names.
- Number keys are now mapped to jump to a buffer by its number. See
  |selectbuf-buffer-search|.
- Bug fixes.
    - If SBExec created a new window, it results in a Vim error.
    - Toggle buffer numbers is broken.
    - Other misc. bug fixes.

                                            *selectbuf-changes-3.3*
- New mappings to do a quick buffer search. See |selectbuf-buffer-search|.

                                            *selectbuf-changes-3.2*
- Added a feature to split file paths, instead of the setting
  selBufHighlightOnlyFilename. See help on |selBufAlwaysShowPaths|. The browser
  by default now starts with this mode.
- The display is now more compact by the use of only required number of spaces
  than using hard tabs.
- A setting to ignore case while sorting, see |selBufIgnoreCaseInSort|.
- A new "selectbuf" filetype to further customize the syntax highlighting and
  extend the functionality, see |selectbuf-filetype|. There is now an API
  available, see |selectbuf-extend|.
- New command SBExec for selections, see |SBExec|. Extremely useful to execute
  external commands.
- Support for multiple selections through multiselect.vim plugin, see
  |selectbuf-multiselect|.
- New command (very useful, at least on MS Windows), |SBLaunch|.
- Improved |SelBufTHiddenKey| and |SelBufTDetailsKey| to avoid doing a full
  refresh. It should work much faster now.
- The :SBLaunch command doesn't anymore treat number arguments as buffer
  numbers. This is such that you can pass arbitrary arguments to the external
  command.
- When in the browser window, <C-R><C-F> at command-line now expands to the full
  path name of the current buffer.

                                            *selectbuf-changes-3.1*
- Fixed problem with disabling DelayedDynUpdate under WinManager. Also this
  setting is now by default disabled (David Fishburn).
- Now the cursor position is remember correctly for incremental update.
- If files are opened from the command-line, and if SelectBuf is opened
  before accessing all the files, those files that are not accessed don't appear
  in (David Fishburn).
- Performance improvements to reduce number of window jumps when used with
  WinManager (WinManager also had to be changed for this).
- New setting selBufDoFileOnClose to control executing :file command when the
  browser window is closed.
- Improved MRU list handling for new buffers added.
- Fixed showDetails to show '+' in front of buffers when they are modified
  (David Fishburn)
- Improved the accuracy of showing % and # markers when showDetails is enabled.
- Now the default register is not overwritten when SelectBuf is used while the
  hideBufNums is selected (David Fishburn).
- Better filename handling (for buffers with special chars in their names)

                                            *selectbuf-changes-3.0*
- Dropped selBufWindowName, selBufRemoveBrowserBuffer, selBufOpenInNewWindow,
  selBufAlwaysWrapLines, selBufAlwaysShowDirectories settings.
- Added |selBufIgnoreNonFileBufs|, |selBufEnableDynUpdate|,
  |selBufDelayDynUpdate|, |selBufDisableSummary|, |selBufIgnoreNonFileBufs|,
  |selBufEnableDynUpdate| settings.
- I have also changed some default settings to the most favored values.
- Renamed SelBufHelpKey mapping to |SelBufTHelpKey|.
- Changed the name of the browser window to "[Select Buf]" from
  "__Select_Buf__".
- Added |SBSettings| command.
- Added support to work as a WinManager plugin.

                                            *selectbuf-known-issues*
- Opening a large set of files at a time takes longer than it would usually
  take. This is because, the plugin has to generate an MRU list for each buffer
  that gets loaded into Vim. I have observed that opening 1500 files at a
  time took almost 40 to 50% longer on an old laptop. If there are other plugins
  that manage MRU lists at the same time, the impact can be even worse. You can
  temporarily disable MRU feature in selectbuf (and later enable it back) by
  using the |selBufDisableMRUlisting| setting. This should reduce the time taken
  for loading the buffers, though the MRU listing then may not show all the
  buffers.  You may have to select a different sort field and probably do a
  refresh (unless the |selBufEnableDynUpdate| is disabled) before you can see
  the complete list.
- If you perform a command from plugin window that splits the window and
  switches to a different buffer, the plugin changes the mode and the 'quit'
  behavior changes.

                                            *selectbuf-wishlist*
TBD

                                            *selectbuf-acknowledgements*
- Thomas Link (t dot link02a at gmx dot net) for his excellent idea with mapping
  number keys to begin searching for a buffer by its number.
- Many bug reports by David Fishburn (fishburn at ianywhere dot com).
- Various others for reporting bugs, ideas and feedback. Some of them are:
    - Geoff Caplan (geoff at advantae dot com)
    - Warren (musicww at WellsFargo dot COM)
    - Paul Nguyen (PNguyen at Santera dot com)
    - Barrie Stott
    - Alan Schmitt
    - Salman Halim (salman at hp dot com)
    - Todd J. Cosgrove (todd dot cosgrove at softechnics dot com)
    - Shishir Ramam (sramam at yahoo dot com)
    - Geoff Caplan (geoff at advantae dot com)
    - Tim Johnson (tim at johnsons-web dot com)
    - David Rennalls (drennalls at canada dot com)
    - Eric Winger (ewinger at keyww dot com)
    - George Reilly (georgere at windows dot microsoft dot com).

 vim6:tw=80:ts=8:ft=help:ai:sw=4:et
