Skip to content

Commit 0841477

Browse files
justinmkjustinmk
committed
doc: how to "disable" mappings #248 
1 parent 7afd63b commit 0841477

File tree

1 file changed

+54
-52
lines changed

1 file changed

+54
-52
lines changed

‎doc/sneak.txt‎

Lines changed: 54 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Sneak - the missing motion for Vim
44

55
==============================================================================
6-
OVERVIEW *sneak*
6+
OVERVIEW *sneak*
77

88
Sneak provides a way to move quickly and precisely to locations that would be
99
awkward to reach with built-in Vim motions.
@@ -22,7 +22,7 @@ a quick-start, and |sneak-features| for full description.
2222
Sneak works with Vim 7.2+ (|sneak-label-mode| requires Vim 7.3+).
2323

2424
==============================================================================
25-
USAGE *sneak-usage*
25+
USAGE *sneak-usage*
2626

2727
Example (cursor position indicated with brackets []): >
2828
[L]orem ipsum dolor sit amet, consectetur adipisicing elit
@@ -40,9 +40,9 @@ Type dzad to delete from the cursor to the first instance of "ad": >
4040
Lorem ipsum [a]dipisicing elit
4141
<
4242
------------------------------------------------------------------------------
43-
DEFAULT MAPPINGS *sneak-mappings*
43+
DEFAULT MAPPINGS *sneak-mappings*
4444

45-
Note: See |sneak-custom-mappings| to change these defaults.
45+
Full list of default mappings (see |sneak-custom-mappings| to change them):
4646

4747
NORMAL-MODE~
4848
Key Sequence | Description
@@ -81,8 +81,7 @@ VISUAL-MODE~
8181
s | Go to the [count]th next match (NOTE above)
8282
S | Go to the [count]th previous match (NOTE above)
8383

84-
NOTE: Z goes backwards in visual-mode, because S is taken by the
85-
|surround| plugin).
84+
NOTE: Z goes backwards in visual-mode because S is used by |surround|.
8685

8786
LABEL-MODE~
8887
Key Sequence | Description
@@ -92,11 +91,15 @@ LABEL-MODE~
9291
<BS> or <S-Tab> | Label the previous set of matches.
9392

9493
------------------------------------------------------------------------------
95-
CUSTOM MAPPINGS *sneak-custom-mappings*
94+
CUSTOM MAPPINGS *sneak-custom-mappings*
9695

97-
Sneak provides <Plug> keys for you to specify alternative mappings. But
98-
keep in mind that motion mappings should be the least-friction mappings in
99-
your editor, because motion is the most common editor task.
96+
Sneak defines <Plug> keys so you can choose alternative mappings. But keep in
97+
mind that motions should be the least-friction mappings, because motion is the
98+
most common editor task.
99+
*sneak-disable-mappings*
100+
To "disable" Sneak default mappings, simply define any other mapping to the
101+
relevant <Plug> key. For example to prevent Sneak from remapping "s" and "S",
102+
just map to <Plug>Sneak_s and <Plug>Sneak_S as shown below.
100103

101104
Available <Plug> keys: >
102105
@@ -137,9 +140,9 @@ Available <Plug> keys: >
137140
" label-mode
138141
nmap ? <Plug>SneakLabel_s
139142
nmap ? <Plug>SneakLabel_S
140-
<
143+
141144
==============================================================================
142-
FEATURES *sneak-features*
145+
FEATURES *sneak-features*
143146

144147
------------------------------------------------------------------------------
145148
NORMAL-MODE
@@ -160,11 +163,12 @@ your preferred 'keymap'.
160163
[count]; and [count], skip to the [count]th match, similar to the
161164
behavior of [count]f and [count]t.
162165

163-
Note: If your mapleader is |,| then Sneak maps |\| instead of |,|.
164-
You can override this by specifying some other mapping, e.g.: >
166+
Note: If your mapleader is |,| then Sneak maps |\| instead of |,|. You can
167+
override this by specifying some other mapping, e.g.: >
168+
165169
map gS <Plug>Sneak_,
166170
<
167-
*sneak-clever-s*
171+
*sneak-clever-s*
168172
Similar to clever-f[3], immediately after invoking Sneak you can move to the
169173
next match by hitting `s` (or `S`) again. If you instead move the cursor or do
170174
something else, then `s` starts a new Sneak. In that case, you can repeat the
@@ -213,48 +217,46 @@ Use-cases:
213217
------------------------------------------------------------------------------
214218
LABEL-MODE *sneak-label-mode* *sneak-streak-mode*
215219

220+
*g:sneak#label*
216221
Label-mode minimizes the steps to jump to a location, using a clever interface
217-
similar to vim-easymotion (but Sneak is faster and more predictable than
218-
vim-easymotion).
222+
similar to EasyMotion. If enabled, Sneak overlays text with "labels" which can
223+
be jumped-to by typing the label character. To enable label-mode: >
219224
220-
To enable label-mode: *g:sneak#label*
221-
>
222225
let g:sneak#label = 1
223-
<
224-
<Tab> skips to the next set of matches (<BS> or <S-Tab> go the other way).
225-
These actions are preserved when repeating!
226-
227-
<Space> or <Esc> exits label-mode. |g:sneak#label_esc|
228226
229-
|folds| are skipped (not labeled). (Use |;| and |,| to reach folded or
230-
off-screen matches.)
231-
232-
Compared to vim-easymotion:
233-
- Never modifies your data. vim-easymotion uses edit-and-undo hacks.
234-
- Never adds extra "stages" or "groups", so it is predictable. The _common_
235-
case is the highest priority.
236-
- Target labels are always visually separated.
237-
*sneak-fallthrough*
227+
Label-mode features:
228+
- Jump to a label by typing its character. *sneak-fallthrough*
238229
- Non-label keys "fall through" to normal-mode, so you don't need to
239230
explicitly exit label-mode if the first match is correct.
240-
241-
As always, you can:
231+
- <Tab> skips to the next set of matches (<BS>, <S-Tab> go the other way).
232+
These actions are preserved with dot-repeat.
233+
- <Space> or <Esc> exits label-mode. |g:sneak#label_esc|
234+
- |folds| are skipped (not labeled). Use |;| and |,| to reach folded or
235+
off-screen matches.
236+
237+
Standard features behave as usual:
238+
- If `s` is prefixed with [count] then |sneak-vertical-scope| is invoked, not
239+
label-mode.
242240
- Skip to the next or previous match with |;| or |,|
243241
- Return to your original location via |CTRL-O| or |``|
244242
- Use any |operator|, including |surround|.
245243
- Repeat operations with |.| (dot).
246244

247-
Note: If `s` is prefixed with a [count] then |sneak-vertical-scope| is
248-
invoked.
245+
Sneak compared to EasyMotion:
246+
- is faster and more predictable
247+
- never modifies your data (EasyMotion uses edit-and-undo hacks)
248+
- never adds extra "stages" or "groups", so it is predictable (common case is
249+
the highest priority)
250+
- always visually separates target labels
249251

250252
==============================================================================
251-
CONFIGURATION *sneak-configuration*
253+
CONFIGURATION *sneak-config*
252254

253255
Sneak is designed with sane, effective defaults, to avoid configuration as
254-
much as possible; but you can change them as follows.
256+
much as possible. But you can change them as follows.
255257

256258
------------------------------------------------------------------------------
257-
OPTIONS *sneak-options*
259+
OPTIONS *sneak-options*
258260

259261
To change an option, add a |let| statement in your |vimrc|. Example: >
260262
let g:sneak#use_ic_scs = 0
@@ -317,12 +319,12 @@ g:sneak#label = 0
317319

318320
1: Enable |sneak-label-mode| if the Vim |+conceal| feature is available.
319321

320-
g:sneak#label_esc = "\<Space>" *g:sneak#label_esc*
322+
g:sneak#label_esc = "\<Space>" *g:sneak#label_esc*
321323

322324
Exit |sneak-label-mode| as if <Esc> were pressed.
323325
https://github.com/justinmk/vim-sneak/issues/122
324326

325-
g:sneak#target_labels = ";sftunq/SFGHLTUNRMQZ?0" *g:sneak#target_labels*
327+
g:sneak#target_labels = ";sftunq/SFGHLTUNRMQZ?0" *g:sneak#target_labels*
326328

327329
List of characters used to label the target locations. |sneak-label-mode|
328330

@@ -344,7 +346,7 @@ g:sneak#prompt = '>'
344346
Message displayed at the Sneak input prompt.
345347

346348
------------------------------------------------------------------------------
347-
HIGHLIGHTING *sneak-highlight*
349+
HIGHLIGHTING *sneak-highlight*
348350

349351
Sneak uses these highlight groups:
350352

@@ -370,11 +372,11 @@ To disable highlighting: >
370372
autocmd User SneakLeave highlight clear Sneak
371373
372374
------------------------------------------------------------------------------
373-
FUNCTIONS *sneak-functions*
375+
FUNCTIONS *sneak-functions*
374376

375377
These functions are provided if you want more control.
376378

377-
sneak#wrap(op, inputlen, reverse, inclusive, label) *sneak#wrap()*
379+
sneak#wrap(op, inputlen, reverse, inclusive, label) *sneak#wrap()*
378380
Sneaks with exactly {inputlen} characters. For example with {inputlen}
379381
of 2 the search is performed when the second character is typed,
380382
without waiting for <Enter>.
@@ -408,7 +410,7 @@ sneak#wrap(op, inputlen, reverse, inclusive, label) *sneak#wrap()*
408410
onoremap <silent> s :<C-U>call sneak#wrap(v:operator, 3, 0, 2, 1)<CR>
409411
onoremap <silent> S :<C-U>call sneak#wrap(v:operator, 3, 1, 2, 1)<CR>
410412
<
411-
sneak#is_sneaking() *sneak#is_sneaking()*
413+
sneak#is_sneaking() *sneak#is_sneaking()*
412414
Returns 1 if Sneak is active, else 0. Sneak deactivates when the user
413415
chooses a target or moves the cursor. Useful for changing the behavior
414416
of a mapping.
@@ -421,12 +423,12 @@ sneak#is_sneaking() *sneak#is_sneaking()*
421423
<
422424
https://github.com/justinmk/vim-sneak/pull/93
423425

424-
sneak#cancel() *sneak#cancel()*
426+
sneak#cancel() *sneak#cancel()*
425427
Deactivates Sneak: removes autocmds/highlighting and causes
426428
|sneak#is_sneaking()| to return 0.
427429
https://github.com/justinmk/vim-sneak/issues/106
428430

429-
sneak#reset(key) *sneak#reset()*
431+
sneak#reset(key) *sneak#reset()*
430432
Prevents Sneak from hijacking |;| and |,| until the next invocation of
431433
Sneak. This is useful if you have remapped the Vim built-in |f| or
432434
|t| to another key and you still want to use |;| and |,| for both Sneak
@@ -444,7 +446,7 @@ sneak#reset(key) *sneak#reset()*
444446
<
445447
Note: The <expr> modifier is required!
446448

447-
sneak#state() *sneak#state()*
449+
sneak#state() *sneak#state()*
448450
Returns a read-only dictionary representing the current behavior.
449451

450452
Values set at invocation (_not_ for repeat):
@@ -474,7 +476,7 @@ sneak#state() *sneak#state()*
474476
\ : '<Plug>Sneak_s'
475477
<
476478
==============================================================================
477-
EVENTS *sneak-events*
479+
EVENTS *sneak-events*
478480

479481
The |User| *SneakEnter* event is triggered when Sneak is invoked (including
480482
dot-repeat invocations, but not motion-repeat).
@@ -489,7 +491,7 @@ Example: >
489491
autocmd User SneakLeave set cursorcolumn cursorline
490492
491493
==============================================================================
492-
CONTRIBUTING *sneak-contributing*
494+
CONTRIBUTING *sneak-contributing*
493495

494496
Bug reports, feature requests, and patches are welcome:
495497
https://github.com/justinmk/vim-sneak
@@ -501,7 +503,7 @@ or Nvim: >
501503
nvim -u NORC +"let g:sneak#label=1" +":set runtimepath+=~/.local/share/nvim/bundle/vim-sneak/" +":runtime plugin/sneak.vim"
502504
503505
==============================================================================
504-
CREDITS *sneak-credits*
506+
CREDITS *sneak-credits*
505507

506508
Author: Justin M. Keyes <[email protected]>
507509

0 commit comments

Comments
 (0)