*glimpse.txt* Last change: $Id$

                VIM REFERENCE MANUAL    by Mahlon E. Smith

                                  VimGlimpse

A basic Glimpse interface for Vim                                     *glimpse*

==============================================================================

CONTENTS                                                      *GlimpseContents*

    1) Intro........................................|GlimpseIntro|

    2) Functionality................................|GlimpseFunctionality|

    3) Adjusting Behavior...........................|GlimpseVimrcExample|

    4) Configuration................................|GlimpseOptions|

        4.1) Glimpse keybinding.....................|g:glimpseKey|

        4.2) GlimpseIndex keybinding................|g:glimpseindexKey|

		4.3) Changing the results window size.......|g:glimpseWindowResultSize|

		4.4) Altering default flags to glimpse......|g:glimpseFlags|

		4.5) Altering flags to glimpseindex.........|g:glimpseindexFlags|

    5) Author.......................................|GlimpseAuthor|

    6) License......................................|GlimpseLicense|

==============================================================================

1. INTRO                                                         *GlimpseIntro*

Glimpse is a powerful indexing and query system, free for personal use.

	http://www.webglimpse.net

VimGlimpse is a basic Glimpse interface within Vim, based on a Vim Tip from

Jean-Rene David. 

	http://vim.wikia.com/wiki/Use_glimpse_from_within_Vim

VimGlimpse retains normal Vim |:grep| functionality, and provides

additional Glimpse features outside of what |grepprg| can allow.  By

default, VimGlimpse only searches within your current working directory,

making it ideal for near instantaneous searches across a project.

==============================================================================

2. FUNCTIONALITY                                         *GlimpseFunctionality*

Glimpse installs two new global commands, *Glimpse* and *GlimpseIndex* .

SEARCHING ~

------------------------------------------------------------------------------

If you set the |g:glimpseKey|variable to something, you can search for

the word under the cursor with a keystroke.  Otherwise, just execute the

|:Glimpse| command.  Here are some examples (shamelessly stolen from the

glimpse man page):

    :Glimpse needle haystack.h$~

		Finds all needles in all haystack.h's files.

	:let g:glimpseFlags = "-iny -2"	~

	:Glimpse Anestesiology html ~

		Outputs all occurrences of  Anestesiology  with  two  errors  in

		files with html somewhere in their full name.

	:Glimpse windsurfing;Arizona mail;1993 ~

		Finds  all lines containing windsurfing and Arizona in all files

		having `mail' and '1993' somewhere in their full name.

Results are placed into the |quickfix| window.  Additionally, the 'q' key is

bound to the window so you can close it again quickly. 

INDEXING ~

------------------------------------------------------------------------------

If you set the |g:glimpseindexKey|variable to something, you can reindex

your current working directory with a keystroke.  Otherwise, just

you can just manually execute the |:GlimpseIndex| command.

Results from an index are placed into the location window.  You can view them

via |:lopen|.

If you are reindexing a large directory, this could take a few moments.

The defaults are to produce an incremental merge -- so it should be

fairly fast, but it's a good idea to ensure your indexes exist prior to

running this command.

If you've just installed glimpse, a great way to start playing with it

immediately is to let it index your entire home directory (from the shell):

	% glimpseindex -M 10 -B -o ~ ~

If you've deleted a lot of files, re-running this command will free up space

in your indexes.  I just run it nightly from cron.

==============================================================================

3. ADJUSTING-BEHAVIOR                                     *GlimpseVimrcExample*

Here's what my config looks like. >

	let g:glimpseFlags = "-winy1"

	let g:glimpseKey = "<Leader>g"

	let g:glimpseindexKey = "<Leader>G"

With these settings, I can find the full word under the cursor with

<Leader>g, in a case insensitive 1 character fuzzy match search.

With <Leader>G, I can quickly re-index my current working directory, so

changes to my files are reflected in search results.

==============================================================================

4. CONFIGURATION-OPTIONS                                       *GlimpseOptions*

Here are all of the available configuration options.

------------------------------------------------------------------------------

4.1                                                              *g:glimpseKey*

Setting this binding enables immediate searching for the |word| that is

currently under the cursor.  There is no default. >

	let g:glimpseKey = "<Leader>g"

------------------------------------------------------------------------------

4.2                                                         *g:glimpseindexKey*

Setting this enables reindexing with a keystroke, rather than running the

|GlimpseIndex| command manually.  There is no default. >

	let g:glimpseindexKey = "<Leader>G"

------------------------------------------------------------------------------

4.3                                                 *g:glimpseWindowResultSize*

Change the height of the results window.  The default is 15 lines. >

	let g:glimpseWindowResultSize = 15

------------------------------------------------------------------------------

4.4                                                            *g:glimpseFlags*

Alter the command line flags used when executing glimpse.  If you alter

this, you should retain the '-n' flag, as the |quickfix| window relies

on that for line positioning.  The default is: >

	let g:glimpseFlags = "-iny"

See the glimpse man page for all available options.  (I find -w, -i, and

-# to be the most immediately useful.)

------------------------------------------------------------------------------

4.5                                                       *g:glimpseindexFlags*

Alter the command line flags used when executing glimpseindex.

The default is: >

	let g:glimpseindexFlags = '-M 10 -B -o'

The '-f' flag with the current working directory is always appended to this

flag list.

==============================================================================

5. AUTHOR                                                       *GlimpseAuthor*

VimGlimpse was written by Mahlon E. Smith.

    mahlon@martini.nu ~

    http://www.martini.nu/ 

==============================================================================

6. LICENSE                                                     *GlimpseLicense*

This Glimpse VIM plugin is distributed under the BSD license.

    http://www.opensource.org/licenses/bsd-license.php

>

    Copyright (c) 2009, Mahlon E. Smith <mahlon@martini.nu>

    All rights reserved.

    Redistribution and use in source and binary forms, with or without

    modification, are permitted provided that the following conditions are

    met:

        * Redistributions of source code must retain the above copyright

          notice, this list of conditions and the following disclaimer.

        * Redistributions in binary form must reproduce the above copyright

          notice, this list of conditions and the following disclaimer in the

          documentation and/or other materials provided with the distribution.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED

    TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

vim: set noet nosta sw=4 ts=4 ft=help :