Improve documentation of blink-cursor-mode and its customization variables.

 lisp/frame.el (blink-cursor-blinks, blink-cursor-blinks-done): Doc fixes.
 (blink-cursor-mode): Mention customization variables and the
 effect of 'blink-cursor-blinks'.

 doc/emacs/display.texi (Cursor Display): Explain better how to customize
 'blink-cursor-blinks'.

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 56daee101014ae9d166ca1b5b9b4d88a9fafc17c..0b2359458ec5df149e43ecb1427de4999b4c099f 100644 (file)
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,8 @@
+2014-04-13  Eli Zaretskii  <eliz@gnu.org>
+
+       * display.texi (Cursor Display): Explain better how to customize
+       'blink-cursor-blinks'.
+
 2014-04-05  Glenn Morris  <rgm@gnu.org>
 
        * trouble.texi (Checklist): Dribble files may contain passwords.

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index d53c80acafd4d557d9bdcfd97762406bda36be55..03de755aff30433eb8817a286b9b922dae946d62 100644 (file)
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1482,18 +1482,27 @@ pixels tall), or @code{nil} (no cursor at all).
 @vindex blink-cursor-mode
 @vindex blink-cursor-blinks
 @vindex blink-cursor-alist
-  By default, the cursor stops blinking after 10 blinks.  This can be
-changed by customizing the variable @code{blink-cursor-blinks}.  To
-disable cursor blinking altogether, change the variable
-@code{blink-cursor-mode} to @code{nil} (@pxref{Easy Customization}),
-or add the line @code{(blink-cursor-mode 0)} to your init file.
-Alternatively, you can change how the cursor looks when it ``blinks
-off'' by customizing the list variable @code{blink-cursor-alist}.
-Each element in the list should have the form @code{(@var{on-type}
-. @var{off-type})}; this means that if the cursor is displayed as
-@var{on-type} when it blinks on (where @var{on-type} is one of the
-cursor types described above), then it is displayed as @var{off-type}
-when it blinks off.
+  By default, the cursor stops blinking after 10 blinks, if Emacs does
+not get any input during that time; any input event restarts the
+count.  You can customize the variable @code{blink-cursor-blinks} to
+control that: its value says how many times to blink without input
+before stopping.  Setting that variable to a zero or negative value
+will make the cursor blink forever.  To disable cursor blinking
+altogether, change the variable @code{blink-cursor-mode} to @code{nil}
+(@pxref{Easy Customization}), or add the line
+
+@lisp
+  (blink-cursor-mode 0)
+@end lisp
+
+@noindent
+to your init file.  Alternatively, you can change how the cursor
+looks when it ``blinks off'' by customizing the list variable
+@code{blink-cursor-alist}.  Each element in the list should have the
+form @code{(@var{on-type} . @var{off-type})}; this means that if the
+cursor is displayed as @var{on-type} when it blinks on (where
+@var{on-type} is one of the cursor types described above), then it is
+displayed as @var{off-type} when it blinks off.
 
 @vindex x-stretch-cursor
 @cindex wide block cursor

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index f5f3208256e9debf9c4531efb9e4e8be4c84fd80..704f7a6d8d83eb746d6f5c8fdc2eb62996ad2a15 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,9 @@
+2014-04-13  Eli Zaretskii  <eliz@gnu.org>
+
+       * frame.el (blink-cursor-blinks, blink-cursor-blinks-done): Doc fixes.
+       (blink-cursor-mode): Mention customization variables and the
+       effect of 'blink-cursor-blinks'.
+
 2014-04-12  Barry O'Reilly  <gundaetiapo@gmail.com>
 
        * simple.el (undo): Prevent insertion of identity mapping into

diff --git a/lisp/frame.el b/lisp/frame.el
index 7b0a0a80082ddd79e2795f308cf1a1358a5d07fc..f081df788ecadc3a5247059731a0515300d709c6 100644 (file)
--- a/lisp/frame.el
+++ b/lisp/frame.el
@@ -1722,14 +1722,14 @@ left untouched.  FRAME nil or omitted means use the selected frame."
   :group 'cursor)
 
 (defcustom blink-cursor-blinks 10
-  "How many times to blink before using a solid cursor on NS and X.
+  "How many times to blink before using a solid cursor on NS, X, and MS-Windows.
 Use 0 or negative value to blink forever."
   :version "24.4"
   :type 'integer
   :group 'cursor)
 
 (defvar blink-cursor-blinks-done 1
-  "Number of blinks done since we started blinking on NS and X")
+  "Number of blinks done since we started blinking on NS, X, and MS-Windows.")
 
 (defvar blink-cursor-idle-timer nil
   "Timer started after `blink-cursor-delay' seconds of Emacs idle time.
@@ -1807,6 +1807,12 @@ With a prefix argument ARG, enable Blink Cursor mode if ARG is
 positive, and disable it otherwise.  If called from Lisp, enable
 the mode if ARG is omitted or nil.
 
+If the value of `blink-cursor-blinks' is positive (10 by default),
+the cursor stops blinking after that number of blinks, if Emacs
+gets no input during that time.
+
+See also `blink-cursor-interval' and `blink-cursor-delay'.
+
 This command is effective only on graphical frames.  On text-only
 terminals, cursor blinking is controlled by the terminal."
   :init-value (not (or noninteractive