bug#3098: 23.0.92; improving documentation of process filter functions

bug#3098: 23.0.92; improving documentation of process filter functions

[Markus Triska]

The documentation of process filter functions states:

   The expression `(buffer-name (process-buffer PROCESS))' returns
   `nil' if the buffer is dead.

Instead of `buffer-name', it seems better to use `buffer-live-p' here:
For one thing, it will also work when process-buffer is `nil', whereas
`buffer-name' would then evaluate to the name of the current buffer.

And, although the documentation also says:

   A filter function that writes the output into the buffer of the
   process should check whether the buffer is still alive.

the `ordinary-insertion-filter' example does not heed this advice.

Suggestion:

2009-04-24  Markus Triska  <markus.triska@gmx.at>

	* processes.texi (Filter Functions): Use `buffer-live-p' instead
	of `buffer-name' in the main text as well as in the example.

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 64d2d7d..6f54eb6 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -1249,25 +1249,28 @@ filter function.  @xref{Debugger}.
 
   Many filter functions sometimes or always insert the text in the
 process's buffer, mimicking the actions of Emacs when there is no
-filter.  Such filter functions need to use @code{set-buffer} in order to
-be sure to insert in that buffer.  To avoid setting the current buffer
-semipermanently, these filter functions must save and restore the
-current buffer.  They should also update the process marker, and in some
-cases update the value of point.  Here is how to do these things:
+filter.  Such filter functions need to use @code{set-buffer} in order
+to be sure to insert in that buffer.  To avoid setting the current
+buffer semipermanently, these filter functions must save and restore
+the current buffer.  Such filter functions should also check whether
+the buffer is still alive, since inserting into a dead buffer will
+raise an error. They should also update the process marker, and in
+some cases update the value of point.  Here is how to do these things:
 
 @smallexample
 @group
 (defun ordinary-insertion-filter (proc string)
-  (with-current-buffer (process-buffer proc)
-    (let ((moving (= (point) (process-mark proc))))
+  (when (buffer-live-p (process-buffer proc))
+    (with-current-buffer (process-buffer proc)
+      (let ((moving (= (point) (process-mark proc))))
 @end group
 @group
-      (save-excursion
-        ;; @r{Insert the text, advancing the process marker.}
-        (goto-char (process-mark proc))
-        (insert string)
-        (set-marker (process-mark proc) (point)))
-      (if moving (goto-char (process-mark proc))))))
+        (save-excursion
+          ;; @r{Insert the text, advancing the process marker.}
+          (goto-char (process-mark proc))
+          (insert string)
+          (set-marker (process-mark proc) (point)))
+        (if moving (goto-char (process-mark proc)))))))
 @end group
 @end smallexample
 
@@ -1294,12 +1297,6 @@ expression searching or matching had to explicitly save and restore the
 match data.  Now Emacs does this automatically for filter functions;
 they never need to do it explicitly.  @xref{Match Data}.
 
-  A filter function that writes the output into the buffer of the
-process should check whether the buffer is still alive.  If it tries to
-insert into a dead buffer, it will get an error.  The expression
-@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
-if the buffer is dead.
-
   The output to the function may come in chunks of any size.  A program
 that produces the same output twice in a row may send it as one batch of
 200 characters one time, and five batches of 40 characters the next.  If


In GNU Emacs 23.0.92.2 (i386-apple-darwin9.6.1, GTK+ Version 2.14.7)
 of 2009-04-05 on mt-imac.local
Windowing system distributor `The X.Org Foundation', version 11.0.10402000
configured using `configure  '--with-tiff=no''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en.UTF-8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default-enable-multibyte-characters: t

bug#3098: 23.0.92; improving documentation of process filter functions

[Chong Yidong]

> 2009-04-24  Markus Triska  <markus.triska <at> gmx.at>
>
> * processes.texi (Filter Functions): Use `buffer-live-p' instead
> of `buffer-name' in the main text as well as in the example.

Thanks, committed.