Improve documentation of 'occur'

* doc/emacs/search.texi (Other Repeating Search):
* lisp/replace.el (occur): Make the documentation of 'occur' be
more accurate when matches overlap.  (Bug#27818)

2 files changed, 9 insertions, 0 deletions

diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi
index c9e83da173f..9f7e9a12cd7 100644
--- a/doc/emacs/search.texi
+++ b/doc/emacs/search.texi
@@ -1747,6 +1747,10 @@ at the first match after such line.
 You can also run @kbd{M-s o} when an incremental search is active;
 this uses the current search string.
 
+Note that matches for the regexp you type are extended to include
+complete lines, and a match that starts before the previous match ends
+is not considered a match.
+
 @kindex RET @r{(Occur mode)}
 @kindex o @r{(Occur mode)}
 @kindex C-o @r{(Occur mode)}
diff --git a/lisp/replace.el b/lisp/replace.el
index 64dfe7da22d..a5024943e64 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -1395,6 +1395,11 @@ invoke `occur'."
   "Show all lines in the current buffer containing a match for REGEXP.
 If a match spreads across multiple lines, all those lines are shown.
 
+Each match is extended to include complete lines.  Only non-overlapping
+matches are considered.  (Note that extending matches to complete
+lines could cause some of the matches to overlap; if so, they will not
+be shown as separate matches.)
+
 Each line is displayed with NLINES lines before and after, or -NLINES
 before if NLINES is negative.
 NLINES defaults to `list-matching-lines-default-context-lines'.