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

[Drew Adams <drew.adams@oracle.com>]

> > >   "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.

I should have said "a more typical approach".

> 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.

Yes, both of those variants are also clear.

In any case, the fact that nil is the default should
be stated clearly, and the nil and non-nil cases should
 be stated up front.  That different non-nil cases exist
comes afterward, so it is clear that they have a common
non-nil behavior.

I think it's can sometimes be clearer to put all of the
description(s) of non-nil behavior together, but it's
not a requirement for a clear description.

Describing the general nil vs non-nil together is
usually helpful, I think, before mentioning any
particular non-nil behavior (unless it is the default).