> 1. I'm still puzzled about this:
>
>   However, the current match will never scroll offscreen.
>   If `unlimited', the current match can scroll offscreen.
>
> Those two sentences don't make sense together.
> If the current match never scrolls offscreen then
> it can't be true that the current match can scroll
> offscreen.  Something different needs to be said
> here.

Do you think this is better?

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

> 2. And the term "offscreen" doesn't seem like a
> good choice.  Don't we mean just off the window,
> i.e., out of view?  So this too bothers/confuses me:
>
>   "Allow scrolling within screen"
>
> I don't know what is meant by "screen" here.
> What are the limits of the "screen" within
> which I can scroll with this option value?

I guess a screen is part of the buffer visible in the window.
We use the word "screen" in other docstrings as well.

> 3. I'm also puzzled by this:
>
>   You may want to enable `lazy-highlight-buffer'
>   as well.
>
> Why say that?  I think it confuses people, by
> suggesting that for some reason you might need
> to do that, in order to see such highlighting
> if you scroll (e.g. "offscreen").
>
> That's not the case, is it?  (I hope not.)  I
> thought that the implementation of `unlimited'
> automatically lazy-highlights everything that
> you scroll to.  Is that not the case?

No, this is not the case.  This is very difficult
to implement, and not worth the effort because this feature
is already available by customizing lazy-highlight-buffer.

Moreover, even if implemented, it still makes no sense
because it can't highlight as quick as you scroll
thru the buffer.

The problem is that you haven't tried my patch
with lazy-highlight-buffer enabled.  If you tried
you wouldn't want any other implementation.

> 4. I think it would be better for the :tag
> "Disable scrolling" to say something like this:
> "Scrolling exits Isearch".

Thanks, fixed.

> 5. Doc string of `*-allow-shift-selection':
>
>   Whether motion is allowed to select text during
>   incremental search.
>
> That will possibly make users think that this is
> about activating the region (selecting text).
>
> The first doc-string line should kind of stand on
> its own, to give an overall idea.  I'd say
> something more like this:
>
>   Motion keys yank text to the search string.

Thanks, fixed.

> 6. `*-allow-shift-selection' behavior:
>
> Why is the value `move'?  Is that the best word?
>
> What happens with `move' if you use a shifted
> motion key?  If it acts the same as `t' then what
> you call "shifted" is really "-only_ when shifted".
> What you call just "motion" seems like just both
> shifted and unshifted.
>
> Why do we even have two such choices?  Why would
> someone who wants to yank chars by moving over
> them want to have to use Shift, ever?  Is it so
> that they can use unshifted to exit Isearch and
> move the cursor?  I guess so.  Maybe that could
> be made clearer (dunno).
>
> 7. OK, no, `move' is apparently more complicated
> than that (all the more reason why it shouldn't
> be called `move'.)  This text is a mouthful:
>
>   by motion commands that have the `isearch-move'
>   property on their symbols equal to `enabled',
>   or [for which] the shift-translated command is
>   not disabled by the value `disabled' of the same
>   property.
>
> That sounds a bit like a legal text. You can just
> repeat "property `isearch-move'" instead of saying
> "the same property" - that would be clearer.  But
> the sentence probably needs to be split.  And it
> may be a sign that the behavior is too complicated.
>
> Why do we have this complicated behavior?  Why
> not just have a `move' value that lets you yank
> text without having to use Shift (i.e. using Shift
> or not)?  What's the point of having to put such a
> property on some command symbols?
>
> And if there really is a use case for doing that
> to certain commands, so that _only they_ manifest
> a difference between `t' and `move' behavior,
> then why not have only the `move' behavior (no `t'
> behavior)?

Sorry, I don't understand what do you suggest here.

> 8.This option should not be called `*-shift-selection'
> if it is not necessarily about Shift selection.
> The option is apparently about yanking text you
> move the cursor over.

So I renamed it to `isearch-allow-yank-on-move',
and its options to `no-shift' and `shift'.

> 9. Again, I'm not crazy about this :tag, for the
> same reason as above:
>
>   Disable shift selection
>
> A nil option value doesn't disable anything.  It
> just means that cursor motion ends Isearch, so you
> just move over the buffer text.

Thanks for the suggestion, I changed it to
"Motion keys exits Isearch".