bug#21957: 24.5; Make occur search within regions when there is one

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

> > 1. If the selected region has multiple lines, it would search only
> >    inside the region.
> > 2. If the selected region has one line or less, it would use the
> >    region as the search string.
> > 3. If there's no selection it do the usual occur.
> 
> This is a useful heuristic, not sure how intuitive it is.
> 
> BTW, I recall Drew asked how to do the same in Isearch, but I see no way
> because in Isearch it's useful to mark the beginning of the region, and
> extend it using Isearch commands by putting the end of the region where
> Isearch ends.

No, I don't think that was me.  Or not quite, if by that you
mean something I might have said about searching the region.

I'm not in favor of things such as the automatic switching
among #1, #2, and #3, above.  I prefer to let users pick
whether to search the region, regardless of its size or
whether it contains a newline char.  The combination of 1,2,3
above is _not_ a useful heuristic, IMO.  It can be useful to
do any of those things, but I don't think it is useful to
couple them together in a "dwimish" way.

I'm also not in favor of Isearch just picking up the region as
the search string (regardless of whether it contains newlines).
I prefer that users yank the region into the search string if
they want to search with it.  (I also give them another command
('C-M-y') to yank the secondary selection, which is typically
not at point, and which doesn't change until you change it
explicitly.)

IOW, I think it is better to have users explicitly say what
behavior they want, instead of dwimming them around.

FWIW, in Isearch+ these features are related to the region:

1. Option 'isearchp-restrict-to-region-flag' restricts
   searching to the active region (regardless of its size or
   the presence of a newline).  You can toggle this during
   Isearch using 'C-x n'.

2. Option 'isearchp-deactivate-region-flag' causes the active
   region to be deactivated (removing highlighting).  That
   makes it easier to see what is being searched.

3. If you also use library `modeline-posn.el' then when you
   search the active region you can keep that restriction for
   query-replacement invoked from Isearch.

4. Non-nil option 'isearchp-set-region-flag' selects the
   last search target as the region when you exit Isearch.
   You can toggle this during Isearch using 'C-SPC'.  If you
   also use library `replace+.el' then you can similarly
   select the last replacement as the region when you
   query-replace etc.

5. You can put a text or overlay property on the text in the
   region, and then later search the zones of text that have
   that property (they need not be contiguous).

6. If you also use library `zones.el' then you can search
   multiple zones defined by their limits (buffer positions
   or markers in any buffers), instead of by properties.
   You can add the active region to a set of such zones,
   using 'C-x n a'.  You can coalesce such zones, uniting
   their overlaps.  (That happens anyway when you search a
   set of zones.)

7. When you search zones of any kind, non-nil option
   'isearchp-dim-non-prop-zones-flag' dims the pieces of
   text that are not being searched.  You can toggle this
   during Isearch using 'C-M-D' (aka 'C-M-S-d').

8. You can search zones defined by text/overlays/buffer
   limits as described above, or you can search the
   complement.  You can toggle searching the complement
   using 'C-M-~' during Isearch.

http://www.emacswiki.org/emacs/IsearchPlus
http://www.emacswiki.org/emacs/Zones
http://www.emacswiki.org/emacs/ReplacePlus
http://www.emacswiki.org/emacs/ModeLinePosition