| blob | 86d6ba4776e7dea9884e9b884df6fd646c1ea85f |
1 *mark.txt* Highlight several words in different colors simultaneously.
3 MARK by Ingo Karkat
4 (original version by Yuheng Xie)
5 *mark.vim*
6 description |mark-description|
7 usage |mark-usage|
8 installation |mark-installation|
9 configuration |mark-configuration|
10 integration |mark-integration|
11 limitations |mark-limitations|
12 known problems |mark-known-problems|
13 todo |mark-todo|
14 history |mark-history|
16 ==============================================================================
17 DESCRIPTION *mark-description*
19 This script adds mappings and a :Mark command to highlight several words in
20 different colors simultaneously, similar to the built-in 'hlsearch'
21 highlighting of search results and the * |star| command. For example, when you
22 are browsing a big program file, you could highlight multiple identifiers in
23 parallel. This will make it easier to trace the source code.
25 This is a continuation of vimscript #1238 by Yuheng Xie, who apparently
26 doesn't maintain his original version anymore and cannot be reached via the
27 email address in his profile. This script offers the following advantages over
28 the original:
29 - Much faster, all colored words can now be highlighted, no more clashes with
30 syntax highlighting (due to use of matchadd()).
31 - Many bug fixes.
32 - Jumps behave like the built-in search, including wrap and error messages.
33 - Like the built-in commands, jumps take an optional [count] to quickly skip
34 over some marks.
36 RELATED WORKS *
37 - MultipleSearch (vimscript #479) can highlight in a single window and in all
38 buffers, but still relies on the :syntax highlighting method, which is
39 slower and less reliable.
40 - http://vim.wikia.com/wiki/Highlight_multiple_words offers control over the
41 color used by mapping the 1-9 keys on the numeric keypad, persistence, and
42 highlights only a single window.
44 ==============================================================================
45 USAGE *mark-usage*
47 HIGHLIGHTING *mark-highlighting*
49 <Leader>m Mark or unmark the word under the cursor, similar to
50 the |star| command.
51 {Visual}<Leader>m Mark or unmark the visual selection.
52 <Leader>r Manually input a regular expression to highlight.
53 {Visual}<Leader>r (Based on the visual selection.)
54 In accordance with the built-in |star| command,
55 all these mappings use 'ignorecase', but not
56 'smartcase'.
57 <Leader>n Clear the mark under the cursor / all marks.
58 *:Mark*
59 :Mark {pattern} Mark or unmark {pattern}.
60 For implementation reasons, {pattern} cannot use the
61 'smartcase' setting, only 'ignorecase'.
62 :Mark Clear all marks.
65 SEARCHING *mark-searching*
67 [count]* [count]#
68 [count]<Leader>* [count]<Leader>#
69 [count]<Leader>/ [count]<Leader>?
70 Use these six keys to jump to the [count]'th next /
71 previous occurrence of a mark.
72 You could also use Vim's / and ? to search, since the
73 mark patterns are (optionally, see configuration)
74 added to the search history, too.
76 Cursor over mark Cursor not over mark
77 ---------------------------------------------------------------------------
78 <Leader>* Jump to the next occurrence of Jump to the next occurrence of
79 current mark, and remember it "last mark".
80 as "last mark".
82 <Leader>/ Jump to the next occurrence of Same as left.
83 ANY mark.
85 * If <Leader>* is the most recently Do Vim's original * command.
86 used, do a <Leader>*; otherwise
87 (<Leader>/ is the most recently
88 used), do a <Leader>/.
90 Note: When the cursor is on a mark, the backwards
91 search does not jump to the beginning of the current
92 mark (like the built-in search), but to the previous
93 mark. The entire mark text is treated as one entity.
95 You can use Vim's |jumplist| to go back to previous
96 mark matches and the position before a mark search.
98 ==============================================================================
99 INSTALLATION *mark-installation*
101 This script is packaged as a|vimball|. If you have the "gunzip" decompressor
102 in your PATH, simply edit the *.vba.gz package in Vim; otherwise, decompress
103 the archive first, e.g. using WinZip. Inside Vim, install by sourcing the
104 vimball or via the|:UseVimball|command. >
105 vim mark.vba.gz
106 :so %
107 To uninstall, use the|:RmVimball|command.
109 DEPENDENCIES *mark-dependencies*
111 - Requires Vim 7.1 with "matchadd()", or Vim 7.2 or higher.
113 ==============================================================================
114 CONFIGURATION *mark-configuration*
116 You may define your own colors or more than the default 6 highlightings in
117 your vimrc file (or anywhere before this plugin is sourced), in the following
118 form (where N = 1..): >
119 highlight MarkWordN ctermbg=Cyan ctermfg=Black guibg=#8CCBEA guifg=Black
120 <
121 The search type highlighting (in the search message) can be changed via: >
122 highlight link SearchSpecialSearchType MoreMsg
123 <
124 By default, any marked words are also added to the search (/) and input (@)
125 history; if you don't want that, remove the corresponding symbols from: >
126 let g:mwHistAdd = "/@"
127 <
128 You can use different mappings by mapping to the <Plug>Mark... mappings before
129 this plugin is sourced. To remove the default overriding of * and #, use: >
130 nmap <Plug>IgnoreMarkSearchNext <Plug>MarkSearchNext
131 nmap <Plug>IgnoreMarkSearchPrev <Plug>MarkSearchPrev
132 <
133 ==============================================================================
134 INTEGRATION *mark-integration*
136 ==============================================================================
137 LIMITATIONS *mark-limitations*
139 - If the 'ignorecase' setting is changed, there will be discrepancies between
140 the highlighted marks and subsequent jumps to marks.
141 - If {pattern} in a :Mark command contains atoms that change the semantics of
142 the entire (|/\c|, |/\C|) or following (|/\v|,|/\V|, |/\M|) regular
143 expression, there may be discrepancies between the highlighted marks and
144 subsequent jumps to marks.
146 KNOWN PROBLEMS *mark-known-problems*
148 TODO *mark-todo*
150 IDEAS *mark-ideas*
152 Taken from an alternative implementation at
153 http://vim.wikia.com/wiki/Highlight_multiple_words:
154 - Allow to specify the highlight group number via :Mark [n] {regexp}
155 - Use keys 1-9 on the numeric keypad to toggle a highlight group number.
156 - Persist the patterns in a uppercase global variable across Vim sessions.
157 (Request from Mun Johl, 16-Apr-2010.)
158 Can be somewhat emulated by placing something like this in |vimrc|: >
159 runtime plugin/mark.vim
160 Mark foo
161 Mark bar
162 < or defining a custom command a la: >
163 command -bar MyMarks execute "Mark foo" | execute "Mark bar"
165 ==============================================================================
166 HISTORY *mark-history*
168 2.4.0 13-Jul-2010
169 - ENH: The MarkSearch mappings (<Leader>[*#/?]) add the original cursor
170 position to the jump list, like the built-in [/?*#nN] commands. This allows
171 to use the regular jump commands for mark matches, like with regular search
172 matches.
174 2.3.3 19-Feb-2010
175 - BUG: Clearing of an accidental zero-width match (e.g. via :Mark \zs) results
176 in endless loop. Thanks to Andy Wokula for the patch.
178 2.3.2 17-Nov-2009
179 - BUG: Creation of literal pattern via '\V' in {Visual}<Leader>m mapping
180 collided with individual escaping done in <Leader>m mapping so that an
181 escaped '\*' would be interpreted as a multi item when both modes are used
182 for marking. Thanks to Andy Wokula for the patch.
184 2.3.1 06-Jul-2009
185 - Now working correctly when 'smartcase' is set. All mappings and the :Mark
186 command use 'ignorecase', but not 'smartcase'.
188 2.3.0 04-Jul-2009
189 - All jump commands now take an optional [count], so you can quickly skip over
190 some marks, as with the built-in */# and n/N commands. For this, the entire
191 core search algorithm has been rewritten. The script's logic has been
192 simplified through the use of Vim 7 features like Lists.
193 - Now also printing a Vim-alike search error message when 'nowrapscan' is set.
195 2.2.0 02-Jul-2009
196 - Split off functions into autoload script.
197 - Initialization of global variables and autocommands is now done lazily on
198 the first use, not during loading of the plugin. This reduces Vim startup
199 time and footprint as long as the functionality isn't yet used.
200 - Split off documentation into separate help file. Now packaging as VimBall.
203 2.1.0 06-Jun-2009
204 - Replaced highlighting via :syntax with matchadd() / matchdelete(). This
205 requires Vim 7.2 / 7.1 with patches. This method is faster, there are no
206 more clashes with syntax highlighting (:match always has preference), and
207 the background highlighting does not disappear under 'cursorline'.
208 - Using winrestcmd() to fix effects of :windo: By entering a window, its
209 height is potentially increased from 0 to 1.
210 - Handling multiple tabs by calling s:UpdateScope() on the TabEnter event.
212 2.0.0 01-Jun-2009
213 - Now using Vim List for g:mwWord and thus requiring Vim 7. g:mwCycle is now
214 zero-based, but the syntax groups "MarkWordx" are still one-based.
215 - Factored :syntax operations out of s:DoMark() and s:UpdateMark() so that
216 they can all be done in a single :windo.
217 - Normal mode <Plug>MarkSet now has the same semantics as its visual mode
218 cousin: If the cursor is on an existing mark, the mark is removed.
219 Beforehand, one could only remove a visually selected mark via again
220 selecting it. Now, one simply can invoke the mapping when on such a mark.
222 1.6.1 31-May-2009
223 Publication of improved version by Ingo Karkat.
224 - Now prepending search type ("any-mark", "same-mark", "new-mark") for better
225 identification.
226 - Retired the algorithm in s:PrevWord in favor of simply using <cword>, which
227 makes mark.vim work like the * command. At the end of a line, non-keyword
228 characters may now be marked; the previous algorithm preferred any preceding
229 word.
230 - BF: If 'iskeyword' contains characters that have a special meaning in a
231 regexp (e.g. [.*]), these are now escaped properly.
232 - Highlighting can now actually be overridden in the vimrc (anywhere _before_
233 sourcing this script) by using ':hi def'.
234 - Added missing setter for re-inclusion guard.
236 1.5.0 01-Sep-2008
237 Bug fixes and enhancements by Ingo Karkat.
238 - Added <Plug>MarkAllClear (without a default mapping), which clears all
239 marks, even when the cursor is on a mark.
240 - Added <Plug>... mappings for hard-coded \*, \#, \/, \?, * and #, to allow
241 re-mapping and disabling. Beforehand, there were some <Plug>... mappings
242 and hard-coded ones; now, everything can be customized.
243 - BF: Using :autocmd without <bang> to avoid removing _all_ autocmds for the
244 BufWinEnter event. (Using a custom :augroup would be even better.)
245 - BF: Explicitly defining s:current_mark_position; some execution paths left
246 it undefined, causing errors.
247 - ENH: Make the match according to the 'ignorecase' setting, like the star
248 command.
249 - ENH: The jumps to the next/prev occurrence now print 'search hit BOTTOM,
250 continuing at TOP" and "Pattern not found:..." messages, like the * and n/N
251 Vim search commands.
252 - ENH: Jumps now open folds if the occurrence is inside a closed fold, just
253 like n/N do.
255 1.1.8-g 25-Apr-2008
256 Last version published by Yuheng Xie on vim.org.
258 1.1.2 22-Mar-2005
259 Initial version published by Yuheng Xie on vim.org.
261 ==============================================================================
262 Copyright: (C) 2005-2008 by Yuheng Xie
263 (C) 2008-2010 by Ingo Karkat
264 The VIM LICENSE applies to this script; see|copyright|.
266 Maintainer: Ingo Karkat <ingo@karkat.de>
267 ==============================================================================
268 vim:tw=78:ts=8:ft=help:norl: