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