Don't recommend insert-before-markers in process filters

See <https://lists.gnu.org/r/emacs-devel/2019-05/msg00062.html> and
Bug#35334.
* doc/lispref/processes.texi (Filter Functions): Go back to using
plain insert in the example filter.  Add note about updating window
point.

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 38ad9076a0c38638d83840e5fe3572f082cab584..a93f4db42827b5c4ed8fac820c71f730e44f1f69 100644 (file)
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -1643,7 +1643,7 @@ how to do these things:
         (save-excursion
           ;; @r{Insert the text, advancing the process marker.}
           (goto-char (process-mark proc))
-          (insert-before-markers string)
+          (insert string)
           (set-marker (process-mark proc) (point)))
         (if moving (goto-char (process-mark proc)))))))
 @end group
@@ -1659,7 +1659,12 @@ text arrives, you could insert a line like the following just before the
 
   To force point to the end of the new output, no matter where it was
 previously, eliminate the variable @code{moving} from the example and
-call @code{goto-char} unconditionally.
+call @code{goto-char} unconditionally.  Note that this doesn't
+necessarily move the window point.  The default filter actually uses
+@code{insert-before-markers} which moves all markers, including the
+window point.  This may move unrelated markers, so it's generally
+better to move the window point explicitly, or set its insertion type
+to @code{t} (@pxref{Window Point}).
 
 @ignore
   In earlier Emacs versions, every filter function that did regular