doc/mark.txt

   1 *mark.txt*              Highlight several words in different colors simultaneously.
   2
   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|
  15
  16 ==============================================================================
  17 DESCRIPTION                                                 *mark-description*
  18
  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.
  24
  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.
  35
  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.
  43
  44 ==============================================================================
  45 USAGE                                                             *mark-usage*
  46
  47 HIGHLIGHTING                                               *mark-highlighting*
  48
  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.
  63
  64
  65 SEARCHING                                                     *mark-searching*
  66
  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.
  75
  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".
  81
  82   <Leader>/ Jump to the next occurrence of      Same as left.
  83             ANY mark.
  84
  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>/.
  89
  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.
  94
  95                         You can use Vim's |jumplist| to go back to previous
  96                         mark matches and the position before a mark search.
  97
  98 ==============================================================================
  99 INSTALLATION                                               *mark-installation*
 100
 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.
 108
 109 DEPENDENCIES                                               *mark-dependencies*
 110
 111 - Requires Vim 7.1 with "matchadd()", or Vim 7.2 or higher.
 112
 113 ==============================================================================
 114 CONFIGURATION                                             *mark-configuration*
 115
 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*
 135
 136 ==============================================================================
 137 LIMITATIONS                                                 *mark-limitations*
 138
 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.
 145
 146 KNOWN PROBLEMS                                           *mark-known-problems*
 147
 148 TODO                                                               *mark-todo*
 149
 150 IDEAS                                                             *mark-ideas*
 151
 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"
 164
 165 ==============================================================================
 166 HISTORY                                                         *mark-history*
 167
 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.
 173
 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.
 177
 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.
 183
 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'.
 187
 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.
 194
 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.
 201
 202
 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.
 211
 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.
 221
 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.
 235
 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.
 254
 255 1.1.8-g 25-Apr-2008
 256 Last version published by Yuheng Xie on vim.org.
 257
 258 1.1.2   22-Mar-2005
 259 Initial version published by Yuheng Xie on vim.org.
 260
 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|.
 265
 266 Maintainer:     Ingo Karkat <ingo@karkat.de>
 267 ==============================================================================
 268  vim:tw=78:ts=8:ft=help:norl: