bug#15839: 24.3.50; `isearch-allow-scroll': be able to scroll point off screen temporarily

[Eli Zaretskii]

> Date: Thu, 29 Nov 2018 16:27:13 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 15839@debbugs.gnu.org
> 
> >   "If non-nil, scrolling commands can be used in Isearch mode.
> >   However, the current match can't scroll offscreen if the value is t.
> >   But if it's `unlimited', the current match can scroll offscreen.
> >   You may want to enable `lazy-highlight-buffer' in this case.
> >   If nil, scrolling commands will cancel Isearch mode."
> >
> > If you don't agree, please suggest a better wording.
> 
> I prefer the standard approach: say first what the default
> (nil) does.  Then say what non-nil does.

I disagree that this should be a guideline.  The following two
variants are equivalently good documentation, IMO:

Variant 1:

  "If non-nil, scrolling commands can be used in Isearch mode.
  If nil, the default, scrolling commands will cancel Isearch mode.

  If the value is t, the current match cannot be scrolled off-screen,
  but that limitation is removed if the value is `unlimited'.
  You may want to enable `lazy-highlight-buffer' in this case."

Variant 2:

  "If nil, the default, scrolling commands will cancel Isearch mode.
  If non-nil, scrolling commands can be used in Isearch mode.
  
  If the value is t, the current match cannot be scrolled off-screen,
  but that limitation is removed if the value is `unlimited'.
  You may want to enable `lazy-highlight-buffer' in this case."

And I think I slightly prefer the first one.  Note that I rephrased
the last part.