Separate stopline for highlighting, documentation

Now g:matchup_matchparen_stopline and g:matchup_delim_stopline.
Closes #21.

README.md

@@ -363,6 +363,14 @@ let g:matchup_transmute_enabled = 1
 ```
 default: 0
 
+To configure the number of lines to search in either direction while using
+motions and text objects.  Does not apply to match highlighting
+(see `g:matchup_matchparen_stopline` instead).
+```vim
+let g:matchup_delim_stopline = 1500
+```
+default: 1500
+
 ### Variables
 
 match-up understands the following variables from matchit.
@@ -411,8 +419,24 @@ Whether to replace the statusline for off-screen matches:
 ```vim
 let g:matchup_matchparen_status_offscreen = 0
 ```
+
+If a match is off of the screen, the line belonging to that match will be
+displayed syntax-highlighted in the status line along with the line number
+(if line numbers are enabled).  If the match is above the screen border,
+an additional Δ symbol will be shown to indicate that the matching line is
+really above the cursor line.
+
 default: 1
 
+The number of lines to search in either direction while highlighting
+matches.  Set this conservatively since high values may cause performance
+issues.
+```vim
+let g:matchup_matchparen_stopline = 400  " for match highlighting only
+```
+
+default: 400
+
 #### highlighting timeouts
 
 Adjust timeouts in milliseconds for matchparen highlighting:
@@ -524,6 +548,25 @@ _Options planned_.
   If are having any other performance issues, please open a new issue and
   report `g:matchup#perf#times`.
 
+- Why is there a weird entry on the status line?
+
+  This is a feature which helps you see matches that are outside of the
+  vim screen, similar to some IDEs.  If you wish to disable it, use
+
+  ```vim
+  let g:matchup_matchparen_status_offscreen = 0
+  ```
+
+- Matching does not work when lines are too far apart.
+
+  The number of search lines is limited for performance reasons.  You may
+  increase the limits with the following options:
+
+  ```vim
+  let g:matchup_delim_stopline      = 1500 " generally
+  let g:matchup_matchparen_stopline = 400  " for match highlighting only
+  ```
+
 - How can I contribute?
 
   Read the [contribution guidelines](CONTRIBUTING.md) and [issue

autoload/matchup.vim

@@ -21,6 +21,7 @@ function! s:init_options()
   call s:init_option('matchup_matchparen_deferred', 0)
   call s:init_option('matchup_matchparen_deferred_show_delay', 50)
   call s:init_option('matchup_matchparen_deferred_hide_delay', 700)
+  call s:init_option('matchup_matchparen_stopline', 400)
 
   call s:init_option('matchup_matchparen_timeout',
     \ get(g:, 'matchparen_timeout', 300))

autoload/matchup/delim.vim

@@ -104,6 +104,9 @@ endfunction
 function! matchup#delim#get_matching(delim, ...) " {{{1
   if empty(a:delim) || !has_key(a:delim, 'lnum') | return {} | endif
 
+  let l:opts = a:0 && type(a:1) == type({}) ? a:1 : {}
+  let l:stopline = get(l:opts, 'stopline', s:stopline)
+
   " get all the matching position(s)
   " *important*: in the case of mid, we search up before searching down
   " this gives us a context object which we use for the other side
@@ -118,7 +121,7 @@ function! matchup#delim#get_matching(delim, ...) " {{{1
       call add(l:matches, [])
     endif
 
-    let l:res = a:delim.get_matching(l:down)
+    let l:res = a:delim.get_matching(l:down, l:stopline)
     if l:res[0][1] > 0
       call extend(l:matches, l:res)
     endif
@@ -358,6 +361,9 @@ function! s:get_delim(opts) " {{{1
     let l:need_restore_cursor = 1
   endif
 
+  " stopline may depend on the current action
+  let l:stopline = get(a:opts, 'stopline', s:stopline)
+
   " in the first pass, we get matching line and column numbers
   " this is intended to be as fast as possible, with no capture groups
   " we look for a match on this line (if direction == current)
@@ -365,9 +371,9 @@ function! s:get_delim(opts) " {{{1
   " for current, we actually search leftwards from the cursor
   while 1
     let [l:lnum, l:cnum] = a:opts.direction ==# 'next'
-          \ ? searchpos(l:re, 'cnW', line('.') + s:stopline)
+          \ ? searchpos(l:re, 'cnW', line('.') + l:stopline)
           \ : a:opts.direction ==# 'prev'
-          \   ? searchpos(l:re, 'bcnW', max([line('.') - s:stopline, 1]))
+          \   ? searchpos(l:re, 'bcnW', max([line('.') - l:stopline, 1]))
           \   : searchpos(l:re, 'bcnW', line('.'))
     if l:lnum == 0 | break | endif
 
@@ -602,7 +608,7 @@ function! s:parser_delim_new(lnum, cnum, opts) " {{{1
 endfunction
 " }}}1
 
-function! s:get_matching_delims(down) dict " {{{1
+function! s:get_matching_delims(down, stopline) dict " {{{1
   " called as:   a:delim.get_matching(...)
   " called from: matchup#delim#get_matching <- matchparen, motion
   "   from: matchup#delim#get_surrounding <- matchparen, motion, text_obj
@@ -613,8 +619,8 @@ function! s:get_matching_delims(down) dict " {{{1
   " first, we figure out what the furthest match is, which will be
   " either the open or close depending on the direction
   let [l:re, l:flags, l:stopline] = a:down
-      \ ? [self.regextwo.close, 'W', line('.') + s:stopline]
-      \ : [self.regextwo.open, 'bW', max([line('.') - s:stopline, 1])]
+      \ ? [self.regextwo.close, 'W', line('.') + a:stopline]
+      \ : [self.regextwo.open, 'bW', max([line('.') - a:stopline, 1])]
 
   " these are the anchors for searchpairpos
   let l:open = self.regexone.open     " TODO is this right? BADLOGIC
@@ -1293,7 +1299,7 @@ endfunction
 " }}}1
 
 " initialize script variables
-let s:stopline = get(g:, 'matchup_delim_stopline', 400)
+let s:stopline = get(g:, 'matchup_delim_stopline', 1500)
 
 let s:sidedict = {
       \ 'open'     : ['open'],

autoload/matchup/matchparen.vim

@@ -202,11 +202,13 @@ function! s:matchparen.highlight(...) abort dict " {{{1
   call matchup#perf#timeout_start(l:timeout)
 
   let l:current = matchup#delim#get_current('all', 'both_all',
-        \ { 'insertmode': l:insertmode })
+        \ { 'insertmode': l:insertmode,
+        \   'stopline': g:matchup_matchparen_stopline, })
   call matchup#perf#toc('matchparen.highlight', 'get_current')
   if empty(l:current) | return | endif
 
-  let l:corrlist = matchup#delim#get_matching(l:current, 1)
+  let l:corrlist = matchup#delim#get_matching(l:current,
+        \ { 'stopline': g:matchup_matchparen_stopline, })
   call matchup#perf#toc('matchparen.highlight', 'get_matching')
   if empty(l:corrlist) | return | endif
 

doc/matchup.txt

@@ -404,6 +404,14 @@ Options~
 
   Default: 0
 
+*g:matchup_delim_stopline*
+
+  Configures the number of lines to search in either direction while using
+  motions and text objects.  Does not apply to match highlighting
+  (see |g:matchup_matchparen_stopline| instead).
+
+  Default: 1500
+
 Variables~
 
 *b:match_words*
@@ -451,8 +459,22 @@ Module matchparen~
 
   Whether to replace the |statusline| for off-screen matches.
 
+  If a match is off of the screen, the line belonging to that match will be
+  displayed syntax-highlighted in the status line along with the line number
+  (if line numbers are enabled).  If the match is above the screen border, an
+  additional Δ symbol will be shown to indicate that the matching line is
+  really above the cursor line.
+
   Default: 1
 
+*g:matchup_matchparen_stopline*
+
+  The number of lines to search in either direction while highlighting
+  matches.  Set this conservatively since high values may cause performance
+  issues.
+
+  Default: 400
+
 *g:matchup_matchparen_timeout*
 *g:matchup_matchparen_insert_timeout*
 
@@ -503,6 +525,13 @@ Module motion~
 
   Default: 1
 
+*g:matchup_motion_count_fail*
+
+  When enabled, giving an invalid count to the |[%| and |]%| motions will
+  cause the motion to fail.  Otherwise they will move as far as possible.
+
+  Default: 1
+
 Module text_obj~
 
 *g:matchup_text_obj_linewise_operators*
@@ -614,6 +643,21 @@ A match-up aims to be as fast as possible, but highlighting matching words can
   If are having any other performance issues, please open a new issue and
   report g:matchup#perf#times.
 
+Q Why is there a weird entry on the status line?
+
+A This is a feature which helps you see matches that are outside of the
+  vim screen, similar to some IDEs.  If you wish to disable it, use >
+
+  let g:matchup_matchparen_status_offscreen = 0
+<
+Q Matching does not work when lines are too far apart.
+
+A The number of search lines is limited for performance reasons.  You may
+  increase the limits with the following options: >
+
+  let g:matchup_delim_stopline      = 1500 " generally
+  let g:matchup_matchparen_stopline = 400  " for match highlighting only
+<
 Q How can I contribute?
 
 A Read the contribution guidelines (CONTRIBUTING.md) and issue template