*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~

s                   Cycle through sort regimes.
i                   Cycle through display regimes (alternate).
u                   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~

<CR>                Switch focus to the previous window and go to the current
                    entry. If "g:buffergator_autodismiss_on_select" is True,
                    then the catalog viewer is closed; otherwise it is kept
                    open.

-------------------------------------------------------------------------------
Preview Selected Buffer Without Leaving the Catalog Viewer~

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

po, .               Preview the currently-selected buffer in the previous
                    window, keeping focus on the catalog.
ps                  Preview the currently-selected buffer is a new split,
                    keeping focus on the catalog.
pv                  Preview the currently-selected buffer is a new vertical
                    split, keeping focus on the catalog.
pt                  Preview the currently-selected buffer is a new tab
                    page, keeping focus on the catalog.
<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.

-------------------------------------------------------------------------------
Open Selected Buffer Without Closing the Catalog Viewer~

The following keys all open the currently-selected buffer and switch focus to
it, but keep the catalog viewer open.

o                   Keeping the catalog viewer open, switch focus to the
                    previous window and go to the currently-selected buffer
                    (as <CR> if "g:buffergator_autodismiss_on_select" is 0).
ws                  Keeping the catalog viewer open, split the previous window,
                    switch focus, and go to the currently-selected buffer.
wv                  Keeping the catalog viewer open, split the previous window
                    vertically, switch focus, and go to the currently-selected
                    buffer.
t                   Keeping the catalog viewer open, open the current selected
                    in a new tab page.

-------------------------------------------------------------------------------
Open Selected Buffer and Close the Catalog Viewer~

The following keys all open the currently-selected buffer and switch focus to
it, closing the catalog viewer at the same time.

O                   Close catalog viewer and go to the currently-selected
                    buffer (as <CR> if "g:buffergator_autodismiss_on_select"
                    is 1).
wS                  Close the catalog viewer, split the previous window
                    and go to the currently-selected buffer.
wV                  Close the catalog viewer, split the previous window
                    vertically and go to the currently-selected buffer.
T                   Close the catalog viewer and open the currently-selected
                    buffer in a new tab page.

-------------------------------------------------------------------------------
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
        "filepath": sort by full buffer 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:
