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