]> git.wincent.com - docvim.git/blob - tests/fixtures/integration/loupe/golden/plaintext.golden
Tweak function and command output in Vim help printer to stand out more
[docvim.git] / tests / fixtures / integration / loupe / golden / plaintext.golden
1 *loupe.txt*                      Loupe plug-in for Vim                     *loupe*
2
3 CONTENTS                                                        *loupe-contents*
4
5 1. Intro          |loupe-intro|
6 2. Installation   |loupe-installation|
7 3. Mappings       |loupe-mappings|
8 4. Options        |loupe-options|
9 5. Functions      |loupe-functions|
10 6. Overrides      |loupe-overrides|
11 7. Related        |loupe-related|
12 8. Website        |loupe-website|
13 9. License        |loupe-license|
14 10. Development   |loupe-development|
15 11. Authors       |loupe-authors|
16 12. History       |loupe-history|
17
18 INTRO                                                              *loupe-intro*
19
20     "loupe (noun)
21     a small magnifying glass used by jewelers and watchmakers."
22
23
24                                                                 *loupe-features*
25 Loupe enhances Vim's |search-commands| in four ways:
26
27 1. Makes the currently selected match easier to see ~
28
29 When searching using |/|, |?|, |star|, |#|, |n|, |N| or similar, it can be hard to see
30 the "current" match from among all the matches that 'hlsearch' highlights.
31 Loupe makes the currently selected match easier to see by:
32
33 - Applying a different |:highlight| group (by default, |hl-IncSearch|) to the
34   match under the cursor.
35 - Keeping the matching line centered within the window when jumping between
36   matches with |n| and |N|.
37
38 2. Applies sane pattern syntax by default ~
39
40 Loupe makes "very magic" (|/\v|) syntax apply by default when searching. This
41 is true even if you initiate a search via a novel means, such as from a
42 visual selection or with a complicated |:range| prefix.
43
44 This means that you can use a pattern syntax closer to the familiar regular
45 expression syntax from languages such as Perl, Ruby, JavaScript (indeed,
46 most other modern languages that support regular expressions).
47
48 3. Provides a shortcut to remove search highlighting ~
49
50 Loupe maps <leader>n to quickly remove all 'hlsearch' highlighting (although
51 you can provide an alternative mapping of your choosing or suppress the
52 feature entirely).
53
54 4. Sensible defaults for search-related features ~
55
56 Loupe provides reasonable defaults for most search-related Vim settings to
57 provide a good "out of the box" experience. For more details, or to see how
58 to override Loupe's settings, see |loupe-overrides|.
59
60 INSTALLATION                                                *loupe-installation*
61
62 To install Loupe, use your plug-in management system of choice.
63
64 If you don't have a "plug-in management system of choice", I recommend
65 Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and
66 robustness. Assuming that you have Pathogen installed and configured, and
67 that you want to install Loupe into `~/.vim/bundle`, you can do so with:
68 >
69     git clone https://github.com/wincent/loupe.git ~/.vim/bundle/loupe
70 <
71 Alternatively, if you use a Git submodule for each Vim plug-in, you could do
72 the following after `cd`-ing into the top-level of your Git superproject:
73 >
74     git submodule add https://github.com/wincent/loupe.git ~/vim/bundle/loupe
75     git submodule init
76 <
77 To generate help tags under Pathogen, you can do so from inside Vim with:
78 >
79     :call pathogen#helptags()
80 <
81 MAPPINGS                                                        *loupe-mappings*
82
83
84                                                    *<Plug>(LoupeClearHighlight)*
85 Loupe maps <leader>n to |<Plug>(LoupeClearHighlight)|, which clears all
86 visible highlights (like |:nohighlight| does). To use an alternative mapping
87 instead, create a different one in your |.vimrc| instead using |:nmap|:
88 >
89     " Instead of <leader>n, use <leader>x.
90     nmap <leader>x <Plug>(LoupeClearHighlight)
91 <
92 Note that Loupe will not try to set up its <leader>n mapping if any of the
93 following are true:
94
95 - A mapping for <leader>n already exists.
96 - An alternative mapping for |<Plug>(LoupeClearHighlight)| has already been
97   set up from a |.vimrc|.
98 - The mapping has been suppressed by setting |g:LoupeClearHighlightMap| to 1
99   in your |.vimrc|.
100
101
102                                                        *<Plug>(LoupeOctothorpe)*
103 Loupe maps |#| to |<Plug>(LoupeOctothorpe)| in order to implement custom
104 highlighting and line-centering for the current match.
105
106 To prevent this from happening, create an alternate mapping in your |.vimrc|:
107 >
108     nmap <Nop> <Plug>(LoupeOctothorpe)
109 <
110
111                                                              *<Plug>(LoupeStar)*
112 Loupe maps |star| to |<Plug>(LoupeStar)| in order to implement custom
113 highlighting and line-centering for the current match.
114
115 To prevent this from happening, create an alternate mapping in your |.vimrc|:
116 >
117     nmap <Nop> <Plug>(LoupeStar)
118 <
119
120                                                                 *<Plug>(LoupeN)*
121 Loupe maps |N| to |<Plug>(LoupeN)| in order to implement custom highlighting and
122 line-centering for the current match.
123
124 To prevent this from happening, create an alternate mapping in your |.vimrc|:
125 >
126     nmap <Nop> <Plug>(LoupeN)
127 <
128
129                                                       *<Plug>(LoupeGOctothorpe)*
130 Loupe maps |g#| to |<Plug>(LoupeGOctothorpe)| in order to implement custom
131 highlighting and line-centering for the current match.
132
133 To prevent this from happening, create an alternate mapping in your |.vimrc|:
134 >
135     nmap <Nop> <Plug>(LoupeGOctothorpe)
136 <
137
138                                                             *<Plug>(LoupeGStar)*
139 Loupe maps |gstar| to |<Plug>(LoupeGStar)| in order to implement custom
140 highlighting and line-centering for the current match.
141
142 To prevent this from happening, create an alternate mapping in your |.vimrc|:
143 >
144     nmap <Nop> <Plug>(LoupeGStar)
145 <
146
147                                                                 *<Plug>(Loupen)*
148 Loupe maps |n| to |<Plug>(Loupen)| in order to implement custom highlighting and
149 line-centering for the current match.
150
151 To prevent this from happening, create an alternate mapping in your |.vimrc|:
152 >
153     nmap <Nop> <Plug>(Loupen)
154 <
155 OPTIONS                                                          *loupe-options*
156
157
158                                                          *g:LoupeHighlightGroup*
159 |g:LoupeHighlightGroup|                              string (default: IncSearch)
160
161 Specifies the |:highlight| group used to emphasize the match currently under
162 the cursor for the current search pattern. Defaults to "IncSearch" (ie.
163 |hl-IncSearch|). For example:
164 >
165     let g:LoupeHighlightGroup='Error'
166 <
167 To prevent any special highlighting from being applied, set this option to
168 "" (ie. the empty string).
169
170
171                                                                  *g:LoupeLoaded*
172 |g:LoupeLoaded|                                              any (default: none)
173
174 To prevent Loupe from being loaded, set |g:LoupeLoaded| to any value in your
175 |.vimrc|. For example:
176 >
177     let g:LoupeLoaded=1
178 <
179
180                                                       *g:LoupeClearHighlightMap*
181 |g:LoupeClearHighlightMap|                                  boolean (default: 1)
182
183 Controls whether to set up the |<Plug>(LoupeClearHighlight)| mapping. To
184 prevent any mapping from being configured, set to 0:
185 >
186     let g:LoupeClearHighlightMap=0
187 <
188
189                                                               *g:LoupeVeryMagic*
190 |g:LoupeVeryMagic|                                          boolean (default: 1)
191
192 Controls whether "very magic" pattern syntax (|/\v|) is applied by default. To
193 disable, set to 0:
194 >
195     let g:LoupeVeryMagic=0
196 <
197
198                                                           *g:LoupeCenterResults*
199 |g:LoupeCenterResults|                                      boolean (default: 1)
200
201 Controls whether the match's line is vertically centered within the window
202 when jumping (via |n|, |N| etc). To disable, set to 0:
203 >
204     let g:LoupeCenterResults=0
205 <
206 FUNCTIONS                                                      *loupe-functions*
207
208                                                                *loupe#hlmatch()*
209 loupe#hlmatch() ~
210
211 Apply highlighting to the current search match.
212
213 OVERRIDES                                                      *loupe-overrides*
214
215 Loupe sets a number of search-related Vim settings to reasonable defaults in
216 order to provide a good "out of the box" experience. The following overrides
217 will be set unless suppressed or overridden (see |loupe-suppress-overrides|):
218
219
220                                                         *loupe-history-override*
221 'history'
222
223 Increased to 1000, to increase the number of previous searches remembered.
224 Note that Loupe only applies this setting if the current value of 'history'
225 is less than 1000.
226
227
228                                                        *loupe-hlsearch-override*
229 'hlsearch'
230
231 Turned on (when there is a previous search pattern, highlight all its
232 matches).
233
234
235                                                       *loupe-incsearch-override*
236 'incsearch'
237
238 Turned on (while typing a search command, show where the pattern matches, as
239 it was typed so far).
240
241
242                                                      *loupe-ignorecase-override*
243 'ignorecase'
244
245 Turned on (to ignore case in search patterns).
246
247
248                                                       *loupe-shortmess-override*
249 'shortmess'
250
251 Adds "s", which suppresses the display of "search hit BOTTOM, continuing at
252 TOP" and "search hit TOP, continuing at BOTTOM" messages.
253
254
255                                                       *loupe-smartcase-override*
256 'smartcase'
257
258 Turned on (overrides 'ignorecase', making the search pattern case-sensitive
259 whenever it containers uppercase characters).
260
261
262                                                       *loupe-suppress-overrides*
263 Preventing Loupe overrides from taking effect ~
264
265 To override any of these choices, you can place overrides in an
266 |after-directory| (ie. `~/.vim/after/plugin/loupe.vim`). For example:
267 >
268      " Override Loupe's 'history' setting from 1000 to 10000.
269      set history=10000
270
271      " Reset Loupe's 'incsearch' back to Vim default.
272      set incsearch&vim
273
274      " Remove unwanted 's' from 'shortmess'.
275      set shortmess-=s
276 <
277 RELATED                                                          *loupe-related*
278
279 Just as Loupe aims to improve the within-file search experience, Ferret does
280 the same for multi-file searching and replacing:
281
282 - https://github.com/wincent/ferret
283
284 WEBSITE                                                          *loupe-website*
285
286 The official Loupe source code repo is at:
287
288 - http://git.wincent.com/loupe.git
289
290 A mirror exists at:
291
292 - https://github.com/wincent/loupe
293
294 Official releases are listed at:
295
296 - http://www.vim.org/scripts/script.php?script_id=5215
297
298 LICENSE                                                          *loupe-license*
299
300 Copyright 2015-present Greg Hurrell. All rights reserved.
301
302 Redistribution and use in source and binary forms, with or without
303 modification, are permitted provided that the following conditions are met:
304
305 1. Redistributions of source code must retain the above copyright notice,
306 this list of conditions and the following disclaimer.
307
308 2. Redistributions in binary form must reproduce the above copyright notice,
309 this list of conditions and the following disclaimer in the documentation
310 and/or other materials provided with the distribution.
311
312 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
313 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
314 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
315 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
316 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
317 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
318 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
319 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
320 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
321 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
322 POSSIBILITY OF SUCH DAMAGE.
323
324 DEVELOPMENT                                                  *loupe-development*
325
326 Contributing patches ~
327
328 Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
329 at: https://github.com/wincent/loupe/pulls
330
331 Cutting a new release ~
332
333 At the moment the release process is manual:
334
335 - Perform final sanity checks and manual testing
336 - Update the |loupe-history| section of the documentation
337 - Verify clean work tree:
338 >
339     git status
340 <
341 - Tag the release:
342 >
343     git tag -s -m "$VERSION release" $VERSION
344 <
345 - Publish the code:
346 >
347     git push origin master --follow-tags
348     git push github master --follow-tags
349 <
350 - Produce the release archive:
351 >
352     git archive -o loupe-$VERSION.zip HEAD -- .
353 <
354 - Upload to http://www.vim.org/scripts/script.php?script_id=5215
355
356 AUTHORS                                                          *loupe-authors*
357
358 Loupe is written and maintained by Greg Hurrell <greg@hurrell.net>.
359
360 The original idea for the |g:LoupeHighlightGroup| feature was taken from
361 Damian Conway's Vim set-up:
362
363 -
364
365   https://github.com/thoughtstream/Damian-Conway-s-Vim-Setup/blob/master/plugin/hlnext.vim
366
367 Which he discussed in his "More Instantly Better Vim" presentation at OSCON
368 2013:
369
370 - https://www.youtube.com/watch?v=aHm36-na4-4
371
372 HISTORY                                                          *loupe-history*
373
374 1.1 (15 June 2016) ~
375
376 - Make compatible with older versions of Vim that do not have |v:hlsearch|.
377 - Add support for special delimiters with |:substitute| command.
378
379 1.0 (28 December 2015) ~
380
381 - Renamed the |<Plug>LoupeClearHighlight| mapping to
382   |<Plug>(LoupeClearHighlight)|.
383
384 0.1 (5 July 2015) ~
385
386 - Initial release, extracted from my dotfiles
387   (https://github.com/wincent/wincent).