glimpse/doc/glimpse.txt
branchvim-stuff
changeset 1 fd505fd00e63
equal deleted inserted replaced
0:b5f3c688fb68 1:fd505fd00e63
       
     1 *glimpse.txt* Last change: $Id$
       
     2 
       
     3                 VIM REFERENCE MANUAL    by Mahlon E. Smith
       
     4 
       
     5 
       
     6                                   VimGlimpse
       
     7 
       
     8 A basic Glimpse interface for Vim                                     *glimpse*
       
     9 ==============================================================================
       
    10 CONTENTS                                                      *GlimpseContents*
       
    11 
       
    12 
       
    13     1) Intro........................................|GlimpseIntro|
       
    14     2) Functionality................................|GlimpseFunctionality|
       
    15     3) Adjusting Behavior...........................|GlimpseVimrcExample|
       
    16     4) Configuration................................|GlimpseOptions|
       
    17         4.1) Glimpse keybinding.....................|g:glimpseKey|
       
    18         4.2) GlimpseIndex keybinding................|g:glimpseindexKey|
       
    19 		4.3) Changing the results window size.......|g:glimpseWindowResultSize|
       
    20 		4.4) Altering default flags to glimpse......|g:glimpseFlags|
       
    21 		4.5) Altering flags to glimpseindex.........|g:glimpseindexFlags|
       
    22     5) Author.......................................|GlimpseAuthor|
       
    23     6) License......................................|GlimpseLicense|
       
    24 
       
    25 
       
    26 ==============================================================================
       
    27 1. INTRO                                                         *GlimpseIntro*
       
    28 
       
    29 Glimpse is a powerful indexing and query system, free for personal use.
       
    30 	http://www.webglimpse.net
       
    31 
       
    32 VimGlimpse is a basic Glimpse interface within Vim, based on a Vim Tip from
       
    33 Jean-Rene David. 
       
    34 	http://vim.wikia.com/wiki/Use_glimpse_from_within_Vim
       
    35 
       
    36 VimGlimpse retains normal Vim |:grep| functionality, and provides
       
    37 additional Glimpse features outside of what |grepprg| can allow.  By
       
    38 default, VimGlimpse only searches within your current working directory,
       
    39 making it ideal for near instantaneous searches across a project.
       
    40 
       
    41 
       
    42 ==============================================================================
       
    43 2. FUNCTIONALITY                                         *GlimpseFunctionality*
       
    44 
       
    45 Glimpse installs two new global commands, *Glimpse* and *GlimpseIndex* .
       
    46 
       
    47 
       
    48 SEARCHING ~
       
    49 ------------------------------------------------------------------------------
       
    50 
       
    51 If you set the |g:glimpseKey|variable to something, you can search for
       
    52 the word under the cursor with a keystroke.  Otherwise, just execute the
       
    53 |:Glimpse| command.  Here are some examples (shamelessly stolen from the
       
    54 glimpse man page):
       
    55 
       
    56     :Glimpse needle haystack.h$~
       
    57 
       
    58 		Finds all needles in all haystack.h's files.
       
    59 
       
    60 	:let g:glimpseFlags = "-iny -2"	~
       
    61 	:Glimpse Anestesiology html ~
       
    62 
       
    63 		Outputs all occurrences of  Anestesiology  with  two  errors  in
       
    64 		files with html somewhere in their full name.
       
    65 
       
    66 	:Glimpse windsurfing;Arizona mail;1993 ~
       
    67 
       
    68 		Finds  all lines containing windsurfing and Arizona in all files
       
    69 		having `mail' and '1993' somewhere in their full name.
       
    70 
       
    71 Results are placed into the |quickfix| window.  Additionally, the 'q' key is
       
    72 bound to the window so you can close it again quickly. 
       
    73 
       
    74 
       
    75 INDEXING ~
       
    76 ------------------------------------------------------------------------------
       
    77 
       
    78 If you set the |g:glimpseindexKey|variable to something, you can reindex
       
    79 your current working directory with a keystroke.  Otherwise, just
       
    80 you can just manually execute the |:GlimpseIndex| command.
       
    81 
       
    82 Results from an index are placed into the location window.  You can view them
       
    83 via |:lopen|.
       
    84 
       
    85 If you are reindexing a large directory, this could take a few moments.
       
    86 The defaults are to produce an incremental merge -- so it should be
       
    87 fairly fast, but it's a good idea to ensure your indexes exist prior to
       
    88 running this command.
       
    89 
       
    90 If you've just installed glimpse, a great way to start playing with it
       
    91 immediately is to let it index your entire home directory (from the shell):
       
    92 
       
    93 	% glimpseindex -M 10 -B -o ~ ~
       
    94 
       
    95 If you've deleted a lot of files, re-running this command will free up space
       
    96 in your indexes.  I just run it nightly from cron.
       
    97 
       
    98 
       
    99 ==============================================================================
       
   100 3. ADJUSTING-BEHAVIOR                                     *GlimpseVimrcExample*
       
   101 
       
   102 
       
   103 Here's what my config looks like. >
       
   104 
       
   105 	let g:glimpseFlags = "-winy1"
       
   106 	let g:glimpseKey = "<Leader>g"
       
   107 	let g:glimpseindexKey = "<Leader>G"
       
   108 
       
   109 
       
   110 With these settings, I can find the full word under the cursor with
       
   111 <Leader>g, in a case insensitive 1 character fuzzy match search.
       
   112 
       
   113 With <Leader>G, I can quickly re-index my current working directory, so
       
   114 changes to my files are reflected in search results.
       
   115 
       
   116 
       
   117 ==============================================================================
       
   118 4. CONFIGURATION-OPTIONS                                       *GlimpseOptions*
       
   119 
       
   120 Here are all of the available configuration options.
       
   121 
       
   122 ------------------------------------------------------------------------------
       
   123 4.1                                                              *g:glimpseKey*
       
   124 
       
   125 Setting this binding enables immediate searching for the |word| that is
       
   126 currently under the cursor.  There is no default. >
       
   127 
       
   128 	let g:glimpseKey = "<Leader>g"
       
   129 
       
   130 ------------------------------------------------------------------------------
       
   131 4.2                                                         *g:glimpseindexKey*
       
   132 
       
   133 
       
   134 Setting this enables reindexing with a keystroke, rather than running the
       
   135 |GlimpseIndex| command manually.  There is no default. >
       
   136 
       
   137 	let g:glimpseindexKey = "<Leader>G"
       
   138 
       
   139 ------------------------------------------------------------------------------
       
   140 4.3                                                 *g:glimpseWindowResultSize*
       
   141 
       
   142 Change the height of the results window.  The default is 15 lines. >
       
   143 
       
   144 	let g:glimpseWindowResultSize = 15
       
   145 
       
   146 ------------------------------------------------------------------------------
       
   147 4.4                                                            *g:glimpseFlags*
       
   148 
       
   149 Alter the command line flags used when executing glimpse.  If you alter
       
   150 this, you should retain the '-n' flag, as the |quickfix| window relies
       
   151 on that for line positioning.  The default is: >
       
   152 
       
   153 	let g:glimpseFlags = "-iny"
       
   154 
       
   155 See the glimpse man page for all available options.  (I find -w, -i, and
       
   156 -# to be the most immediately useful.)
       
   157 
       
   158 ------------------------------------------------------------------------------
       
   159 4.5                                                       *g:glimpseindexFlags*
       
   160 
       
   161 Alter the command line flags used when executing glimpseindex.
       
   162 The default is: >
       
   163 
       
   164 	let g:glimpseindexFlags = '-M 10 -B -o'
       
   165 
       
   166 The '-f' flag with the current working directory is always appended to this
       
   167 flag list.
       
   168 
       
   169 ==============================================================================
       
   170 5. AUTHOR                                                       *GlimpseAuthor*
       
   171 
       
   172 
       
   173 VimGlimpse was written by Mahlon E. Smith.
       
   174 
       
   175     mahlon@martini.nu ~
       
   176     http://www.martini.nu/ 
       
   177 
       
   178 
       
   179 
       
   180 ==============================================================================
       
   181 6. LICENSE                                                     *GlimpseLicense*
       
   182 
       
   183 
       
   184 This Glimpse VIM plugin is distributed under the BSD license.
       
   185     http://www.opensource.org/licenses/bsd-license.php
       
   186 
       
   187 >
       
   188     Copyright (c) 2009, Mahlon E. Smith <mahlon@martini.nu>
       
   189     All rights reserved.
       
   190 
       
   191     Redistribution and use in source and binary forms, with or without
       
   192     modification, are permitted provided that the following conditions are
       
   193     met:
       
   194 
       
   195         * Redistributions of source code must retain the above copyright
       
   196           notice, this list of conditions and the following disclaimer.
       
   197 
       
   198         * Redistributions in binary form must reproduce the above copyright
       
   199           notice, this list of conditions and the following disclaimer in the
       
   200           documentation and/or other materials provided with the distribution.
       
   201 
       
   202     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
       
   203     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
       
   204     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
       
   205     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
       
   206     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
       
   207     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
       
   208     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
       
   209     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
       
   210     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
       
   211     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
       
   212     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
       
   213 
       
   214 
       
   215 
       
   216 
       
   217 vim: set noet nosta sw=4 ts=4 ft=help :
       
   218