[Emacs-diffs] master 8adc0e5 10/12: Improve documentation of thread list buffer

[Gemini Lasswell]

branch: master
commit 8adc0e518fe36b6251d79ac61b6de9d4766a6afd
Author: Gemini Lasswell <address@hidden>
Commit: Gemini Lasswell <address@hidden>

    Improve documentation of thread list buffer
    
    * doc/lispref/threads.texi (The Thread List): Cross-reference
    'Basic Thread Functions'.  Use defvar for thread-list-refresh-seconds.
    Improve descriptions of the backtrace and signal commands.
---
 doc/lispref/threads.texi | 32 ++++++++++++++++++--------------
 etc/NEWS                 |  6 +++++-
 2 files changed, 23 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/threads.texi b/doc/lispref/threads.texi
index a4a1af3..c9d5f79 100644
--- a/doc/lispref/threads.texi
+++ b/doc/lispref/threads.texi
@@ -281,15 +281,17 @@ mutex cannot be changed.
 @findex list-threads
 The @code{list-threads} command lists all the currently alive threads.
 In the resulting buffer, each thread is identified either by the name
-passed to @code{make-thread}, or by its unique internal identifier if
-it was not created with a name.  The status of each thread at the time
-of the creation or last update of the buffer is shown, in addition to
-the object the thread was blocked on at the time, if it was blocked.
+passed to @code{make-thread} (@pxref{Basic Thread Functions}), or by
+its unique internal identifier if it was not created with a name.  The
+status of each thread at the time of the creation or last update of
+the buffer is shown, in addition to the object the thread was blocked
+on at the time, if it was blocked.
 
address@hidden thread-list-refresh-seconds
address@hidden thread-list-refresh-seconds
 The @file{*Threads*} buffer will automatically update twice per
-second.  To make the refresh rate faster or slower, customize
address@hidden
+second.  You can make the refresh rate faster or slower by customizing
+this variable.
address@hidden defvar
 
 Here are the commands available in the thread list buffer:
 
@@ -300,9 +302,9 @@ Here are the commands available in the thread list buffer:
 @item b
 Show a backtrace of the thread at point.  This will show where in its
 code the thread had yielded or was blocked at the moment you pressed
address@hidden  Be aware that by the time you see the backtrace, the thread
-may have resumed execution, and be in a different section of code, or
-be completed.
address@hidden  Be aware that the backtrace is a snapshot; the thread could
+have meanwhile resumed execution, and be in a different state, or
+could have exited.
 
 You may use @kbd{g} in the thread's backtrace buffer to get an updated
 backtrace, as backtrace buffers do not automatically update.
@@ -310,10 +312,12 @@ backtrace, as backtrace buffers do not automatically 
update.
 commands which work on them.
 
 @item s
-Send a signal to the thread at point.  After @kbd{s}, type @kbd{q} to
-send a quit signal or @kbd{e} to send an error signal.  Only do this
-if you understand how to restart the target thread, because your Emacs
-session may behave incorrectly if necessary threads are killed.
+Signal the thread at point.  After @kbd{s}, type @kbd{q} to send a
+quit signal or @kbd{e} to send an error signal.  Threads may implement
+handling of signals, but the default behavior is to exit on any
+signal.  Therefore you should only use this command if you understand
+how to restart the target thread, because your Emacs session may
+behave incorrectly if necessary threads are killed.
 
 @item g
 Update the list of threads and their statuses.
diff --git a/etc/NEWS b/etc/NEWS
index 2e4ed5d..ff65a55 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -738,7 +738,11 @@ Instead, error messages are just printed in the main 
thread.
 *** 'thread-alive-p' is now obsolete, use 'thread-live-p' instead.
 
 +++
-*** 'list-threads' displays the live threads in a tabulated-list buffer.
+*** New command 'list-threads' shows Lisp threads.
+See the current list of live threads in a tabulated-list buffer which
+automatically updates.  In the buffer, you can use 's q' or 's e' to
+signal a thread with quit or error respectively, or get a snapshot
+backtrace with 'b'.
 
 ---
 ** thingatpt.el supports a new "thing" called 'uuid'.