*buffergator.txt*	Buffer indexing and navigation plugin.

===============================================================================
                                             *buffergator* *buffergator-contents*
CONTENTS~

    1. Introduction ....................... |buffergator-introduction|
    2. Commands ........................... |buffergator-commands|
    3. Key Mappings (Global) .............. |buffergator-global-keys|
    4. Key Mappings (Catalog Viewer) ...... |buffergator-keys|
    5. Options and Settings ............... |buffergator-options|

===============================================================================
                                                      *buffergator-introduction*
INTRODUCTION~

Buffergator is a plugin for listing, navigating between, and selecting buffers
to edit. Upon invocation, a "catalog" of listed buffers are displayed in a
separate new window split (vertical or horizontal, based on user options;
default = vertical).  From this "buffer catalog", a buffer can be selected and
opened in an existing window, a new window split (vertical or horizontal), or
a new tab page.

Selected buffers can be "previewed", i.e. opened in a window or tab page, but
with focus remaining in the buffer catalog. Even better, you can "walk" up and
down the list of buffers shown in the catalog by using <C-N> (or <SPACE>) /
<C-P> (or <C-SPACE>). These keys select the next/previous buffer in succession,
respectively, opening it for preview without leaving the buffer catalog
viewer.

By default, Buffergator provides global key maps that invoke its main
commands: "<Leader>b" to open, "<Leader>B" to close. If you prefer to map
other keys, or do not want any keys mapped at all, set
"g:buffergator_suppress_keymaps" to 1 in your $VIMRUNTIME.

===============================================================================
                                                          *buffergator-commands*
COMMANDS~

These following commands are provided globally by Buffergator:

:BuffergatorOpen
                    Open the buffer catalog, or go to it if it is already open.

:BuffergatorClose
                    Close the buffer catalog if it is already open.

:BuffergatorToggle
                    Open the buffer catalog if it is closed, or close it if
                    it is already open.

===============================================================================
                                                      *buffergator-global-keys*
KEY MAPPINGS (GLOBAL)~

Unless "g:buffergator_suppress_keymaps" is set to 1, then the following
key mappings are defined:

<Leader>b           Invokes ":BuffergatorOpen": open the buffer catalog, or go
                    to it if it is already open.

<Leader>B           Invokes ":BuffergatorClose": close the buffer catalog.

===============================================================================
                                                             *buffergator-keys*
KEY MAPPINGS (CATALOG VIEWER)~

Invoking Buffergator results in the listed buffers being displayed in a
special Buffergator window, which is referred to as a "buffer catalog viewer".
The following key mappings are available when in the viewer.

-------------------------------------------------------------------------------
Catalog Management~

cs                  Cycle through sort regimes.
cd                  Cycle through display regimes (alternate).
r                   Update (rebuild/refresh) index.
d                   Delete the selected buffer.
D                   Unconditionally delete the selected buffer.
x                   Wipe the selected buffer.
X                   Unconditionally wipe the selected buffer.
q                   Quit the index/catalog window.

-------------------------------------------------------------------------------
Open Selected Buffer~

The following keys all open the currently-selected buffer and switch focus to
it. The catalog buffer will be closed if 'g:buffergator_autodismiss_on_select'
evaluates to true; otherwise it will be kept open.

<CR>, o             Open the currently-selected buffer in previous window.
s                   Open the currently-selected buffer in a new vertical
                    split.
i                   Open the currently-selected buffer in a new split.
t                   Open the currently-selected buffer in a new tab page.

-------------------------------------------------------------------------------
Preview Selected Buffer~

The following keys all open the currently-selected buffer, but retain focus on
the catalog viewer.

O, go               Preview the currently-selected buffer in the previous
                    window.
S, gs               Preview the currently-selected buffer is a new vertical
                    split.
I, gi               Preview the currently-selected buffer is a new split
T                   Preview the currently-selected buffer is a new tab
                    page.
<SPACE>, <C-N>      Go to the next buffer entry and preview it in the previous
                    window.
<C-SPACE>, <C-P>    Go to the previous buffer entry and preview it in the
                    previous window.

-------------------------------------------------------------------------------
Go to Existing Viewport Showing Buffer~

The following keys will try to find the selected buffer in an existing
viewport (whether on the current tab page or another).

eo                  If currently-selected buffer is showing in an existing
                    viewport on this or any other tab page, go it it;
                    otherwise show it in the previous window.
es                  If currently-selected buffer is showing in an existing
                    viewport on this or any other tab page, go it it;
                    otherwise show it in a new vertical split.
ei                  If currently-selected buffer is showing in an existing
                    viewport on this or any other tab page, go it it;
                    otherwise show it in a new horizontal split.
et                  If currently-selected buffer is showing in an existing
                    viewport on this or any other tab page, go it it;
                    otherwise show it in a new tab page.
E                   If currently-selected buffer is showing in an existing
                    viewport on this or any other tab page, go it it;
                    otherwise do nothing.

-------------------------------------------------------------------------------
Window Control~

A                   Zoom/unzoom window, expanding to full height (if
                    horizontally split) or full width (if vertically split)

===============================================================================
                                                          *buffergator-options*
OPTIONS AND SETTINGS~

The following options can be used to customize the behavior of this plugin:

g:buffergator_viewport_split_policy~
    Default: "L"
    Determines how a new Buffergator window will be opened. Can be one of the
    following values:
        "L"   : vertical left (full screen height)
        "R"   : vertical right (full screen height)
        "T"   : horizontal top (full screen width)
        "B"   : horizontal bottom (full screen width)

g:buffergator_autodismiss_on_select~
    Default: 1
    If true, then selection an entry with <CR> will close the catalog. Otherwise,
    catalog stays open. Default is 1.

g:buffergator_autoexpand_on_split~
    Default: 1
    If true and running in GUI mode, then the application screen will be expanded
    to accommodate the Buffergator window.

g:buffergator_split_size~
    Default: 40
    If greater than 0, this will be the width of the Buffergator window in any
    vertical splitting mode, or its height in any horizontal splitting mode.

g:buffergator_sort_regime~
    Default: "bufnum"
    Sets the default sort regime for buffer listing:
        "bufnum" : sort by buffer number [default]
        "basename": sort by buffer file basename (followed by directory)
        "filepath": sort by full buffer filepath
        "extension": sort by buffer filename extension (followed by full
                    filepath)

g:buffergator_display_regime~
    Default: "basename"
    Sets the default sort regime for buffer listing:
        "basename": display buffer basename first,
                    followed by directory [default]
        "filepath": display full buffer filepath
        "bufname": display buffer name

g:buffergator_suppress_keymaps~
    Default: 0
    If true, then Buffergator will not automatically map "<Leader>b" to
    open the Buffergator catalog and "<Leader>B" to close it.

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