[Emacs-diffs] /srv/bzr/emacs/trunk r107633: Update doc to reflect new non-nil value of redisplay-dont-pause.

[Chong Yidong]

------------------------------------------------------------
revno: 107633
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Tue 2012-03-20 16:52:11 +0800
message:
  Update doc to reflect new non-nil value of redisplay-dont-pause.
  
  * doc/lispref/display.texi (Forcing Redisplay): Various rewrites to reflect
  new value of redisplay-dont-pause.
  (Truncation): Copyedits.
  
  * src/dispnew.c (Fredisplay, Vredisplay_preemption_period): Update doc
  to reflect default non-nil value of redisplay-dont-pause.
modified:
  doc/lispref/ChangeLog
  doc/lispref/display.texi
  src/ChangeLog
  src/dispnew.c

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-03-20 07:44:03 +0000
+++ b/doc/lispref/ChangeLog     2012-03-20 08:52:11 +0000
@@ -1,3 +1,9 @@
+2012-03-20  Chong Yidong  <address@hidden>
+
+       * display.texi (Forcing Redisplay): Various rewrites to reflect
+       new value of redisplay-dont-pause.
+       (Truncation): Copyedits.
+
 2012-03-20  Glenn Morris  <address@hidden>
 
        * os.texi (Startup Summary): Don't mention initial-buffer-choice = t.

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2012-03-11 16:10:07 +0000
+++ b/doc/lispref/display.texi  2012-03-20 08:52:11 +0000
@@ -86,60 +86,58 @@
 waiting for input.
 
 @defun redisplay &optional force
-This function tries immediately to redisplay, provided there are no
-pending input events.
-
-If the optional argument @var{force} is address@hidden, it does all
-pending redisplay work even if input is available, with no
-pre-emption.
+This function tries immediately to redisplay.  The optional argument
address@hidden, if address@hidden, forces the redisplay to be performed,
+instead of being preempted, even if input is pending and the variable
address@hidden is @code{nil} (see below).  If
address@hidden is address@hidden (the default), this
+function redisplays in any case, i.e.@: @var{force} does nothing.
 
 The function returns @code{t} if it actually tried to redisplay, and
 @code{nil} otherwise.  A value of @code{t} does not mean that
-redisplay proceeded to completion; it could have been pre-empted by
-newly arriving terminal input.
address@hidden defun
-
-  @code{redisplay} with no argument tries immediately to redisplay,
-but has no effect on the usual rules for what parts of the screen to
-redisplay.  By contrast, the following function adds certain windows
-to the pending redisplay work (as if their contents had completely
-changed), but doesn't immediately try to do any redisplay work.
-
address@hidden force-window-update &optional object
-This function forces some or all windows to be updated on next
-redisplay.  If @var{object} is a window, it requires eventual
-redisplay of that window.  If @var{object} is a buffer or buffer name,
-it requires eventual redisplay of all windows displaying that buffer.
-If @var{object} is @code{nil} (or omitted), it requires eventual
-redisplay of all windows.
address@hidden defun
-
-  @code{force-window-update} does not do a redisplay immediately.
-(Emacs will do that when it waits for input.)  Rather, its effect is
-to put more work on the queue to be done by redisplay whenever there
-is a chance.
+redisplay proceeded to completion; it could have been preempted by
+newly arriving input.
address@hidden defun
 
 @defvar redisplay-dont-pause
-If this variable is address@hidden, pending input does not prevent or
-halt redisplay; redisplay occurs, and finishes, regardless of whether
-input is available.  If it is @code{nil}, Emacs redisplay stops if
-input arrives, and does not happen at all if input is available before
-it starts.  The default is @code{t}.
+If this variable is @code{nil}, arriving input events preempt
+redisplay; Emacs avoids starting a redisplay, and stops any redisplay
+that is in progress, until the input has been processed.  In
+particular, @code{(redisplay)} returns @code{nil} without actually
+redisplaying, if there is pending input.
+
+The default value is @code{t}, which means that pending input does not
+preempt redisplay.
 @end defvar
 
 @defvar redisplay-preemption-period
-This variable specifies how many seconds Emacs waits between checks
-for new input during redisplay.  (The default is 0.1 seconds.)  If
-input has arrived when Emacs checks, it pre-empts redisplay and
-processes the available input before trying again to redisplay.
-
-If this variable is @code{nil}, Emacs does not check for input during
-redisplay, and redisplay cannot be preempted by input.
-
-This variable is only obeyed on graphical terminals.  For
-text terminals, see @ref{Terminal Output}.
+If @code{redisplay-dont-pause} is @code{nil}, this variable specifies
+how many seconds Emacs waits between checks for new input during
+redisplay; if input arrives during this interval, redisplay stops and
+the input is processed.  The default value is 0.1; if the value is
address@hidden, Emacs does not check for input during redisplay.
+
+This variable has no effect when @code{redisplay-dont-pause} is
address@hidden (the default).
 @end defvar
 
+  Although @code{redisplay} tries immediately to redisplay, it does
+not change how Emacs decides which parts of its frame(s) to redisplay.
+By contrast, the following function adds certain windows to the
+pending redisplay work (as if their contents had completely changed),
+but does not immediately try to perform redisplay.
+
address@hidden force-window-update &optional object
+This function forces some or all windows to be updated the next time
+Emacs does a redisplay.  If @var{object} is a window, that window is
+to be updated.  If @var{object} is a buffer or buffer name, all
+windows displaying that buffer are to be updated.  If @var{object} is
address@hidden (or omitted), all windows are to be updated.
+
+This function does not do a redisplay immediately; Emacs does that as
+it waits for input, or when the function @code{redisplay} is called.
address@hidden defun
+
 @node Truncation
 @section Truncation
 @cindex line wrapping
@@ -169,7 +167,7 @@
 beyond the right edge of the window are truncated; otherwise, they are
 continued.  As a special exception, the variable
 @code{truncate-partial-width-windows} takes precedence in
address@hidden windows (i.e., windows that do not occupy the
address@hidden windows (i.e.@: windows that do not occupy the
 entire frame width).
 @end defopt
 
@@ -192,37 +190,37 @@
 
 @defvar wrap-prefix
 If this buffer-local variable is address@hidden, it defines a
-``prefix'' that is prepended to every continuation line at
-display time.  (If lines are truncated, the wrap-prefix is never
-used.)  It may be a string or an image (@pxref{Other Display Specs}),
-or a stretch of whitespace such as specified by the @code{:width} or
address@hidden:align-to} display properties (@pxref{Specified Space}).  The
-value is interpreted in the same way as a @code{display} text
-property.  @xref{Display Property}.
address@hidden prefix} which Emacs displays at the start of every
+continuation line.  (If lines are truncated, @code{wrap-prefix} is
+never used.)  Its value may be a string or an image (@pxref{Other
+Display Specs}), or a stretch of whitespace such as specified by the
address@hidden:width} or @code{:align-to} display properties (@pxref{Specified
+Space}).  The value is interpreted in the same way as a @code{display}
+text property.  @xref{Display Property}.
 
-A wrap-prefix may also be specified for regions of text, using the
+A wrap prefix may also be specified for regions of text, using the
 @code{wrap-prefix} text or overlay property.  This takes precedence
 over the @code{wrap-prefix} variable.  @xref{Special Properties}.
 @end defvar
 
 @defvar line-prefix
 If this buffer-local variable is address@hidden, it defines a
-``prefix'' that is prepended to every non-continuation line at
-display time.  It may be a string or an image (@pxref{Other Display
-Specs}), or a stretch of whitespace such as specified by the
address@hidden:width} or @code{:align-to} display properties (@pxref{Specified
-Space}).  The value is interpreted in the same way as a @code{display}
-text property.  @xref{Display Property}.
address@hidden prefix} which Emacs displays at the start of every
+non-continuation line.  Its value may be a string or an image
+(@pxref{Other Display Specs}), or a stretch of whitespace such as
+specified by the @code{:width} or @code{:align-to} display properties
+(@pxref{Specified Space}).  The value is interpreted in the same way
+as a @code{display} text property.  @xref{Display Property}.
 
-A line-prefix may also be specified for regions of text using the
+A line prefix may also be specified for regions of text using the
 @code{line-prefix} text or overlay property.  This takes precedence
 over the @code{line-prefix} variable.  @xref{Special Properties}.
 @end defvar
 
   If your buffer contains @emph{very} long lines, and you use
 continuation to display them, computing the continuation lines can
-make Emacs redisplay slow.  The column computation and indentation
-functions also become slow.  Then you might find it advisable to set
+make redisplay slow.  The column computation and indentation functions
+also become slow.  Then you might find it advisable to set
 @code{cache-long-line-scans} to @code{t}.
 
 @defvar cache-long-line-scans

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-03-19 04:17:50 +0000
+++ b/src/ChangeLog     2012-03-20 08:52:11 +0000
@@ -1,3 +1,8 @@
+2012-03-20  Chong Yidong  <address@hidden>
+
+       * dispnew.c (Fredisplay, Vredisplay_preemption_period): Update doc
+       to reflect default non-nil value of redisplay-dont-pause.
+
 2012-03-19  Kenichi Handa  <address@hidden>
 
        * ftfont.c (ftfont_drive_otf): Mask bits of character code to make

=== modified file 'src/dispnew.c'
--- a/src/dispnew.c     2012-02-04 11:29:29 +0000
+++ b/src/dispnew.c     2012-03-20 08:52:11 +0000
@@ -6068,10 +6068,14 @@
 
 
 DEFUN ("redisplay", Fredisplay, Sredisplay, 0, 1, 0,
-       doc: /* Perform redisplay if no input is available.
-If optional arg FORCE is non-nil or `redisplay-dont-pause' is non-nil,
-perform a full redisplay even if input is available.
-Return t if redisplay was performed, nil otherwise.  */)
+       doc: /* Perform redisplay.
+Optional arg FORCE, if non-nil, prevents redisplay from being
+preempted by arriving input, even if `redisplay-dont-pause' is nil.
+If `redisplay-dont-pause' is non-nil (the default), redisplay is never
+preempted by arriving input, so FORCE does nothing.
+
+Return t if redisplay was performed, nil if redisplay was preempted
+immediately by pending input.  */)
   (Lisp_Object force)
 {
   int count;
@@ -6521,21 +6525,21 @@
   DEFSYM (Qredisplay_dont_pause, "redisplay-dont-pause");
 
   DEFVAR_INT ("baud-rate", baud_rate,
-             doc: /* *The output baud rate of the terminal.
+             doc: /* The output baud rate of the terminal.
 On most systems, changing this value will affect the amount of padding
 and the other strategic decisions made during redisplay.  */);
 
   DEFVAR_BOOL ("inverse-video", inverse_video,
-              doc: /* *Non-nil means invert the entire frame display.
+              doc: /* Non-nil means invert the entire frame display.
 This means everything is in inverse video which otherwise would not be.  */);
 
   DEFVAR_BOOL ("visible-bell", visible_bell,
-              doc: /* *Non-nil means try to flash the frame to represent a 
bell.
+              doc: /* Non-nil means try to flash the frame to represent a bell.
 
 See also `ring-bell-function'.  */);
 
   DEFVAR_BOOL ("no-redraw-on-reenter", no_redraw_on_reenter,
-              doc: /* *Non-nil means no need to redraw entire frame after 
suspending.
+              doc: /* Non-nil means no need to redraw entire frame after 
suspending.
 A non-nil value is useful if the terminal can automatically preserve
 Emacs's frame display when you reenter Emacs.
 It is up to you to set this variable if your terminal can do that.  */);
@@ -6590,14 +6594,15 @@
   Vstandard_display_table = Qnil;
 
   DEFVAR_BOOL ("redisplay-dont-pause", redisplay_dont_pause,
-              doc: /* *Non-nil means display update isn't paused when input is 
detected.  */);
+              doc: /* Non-nil means display update isn't paused when input is 
detected.  */);
   redisplay_dont_pause = 1;
 
 #if PERIODIC_PREEMPTION_CHECKING
   DEFVAR_LISP ("redisplay-preemption-period", Vredisplay_preemption_period,
-              doc: /* *The period in seconds between checking for input during 
redisplay.
-If input is detected, redisplay is pre-empted, and the input is processed.
-If nil, never pre-empt redisplay.  */);
+              doc: /* Period in seconds between checking for input during 
redisplay.
+This has an effect only if `redisplay-dont-pause' is nil; in that
+case, arriving input preempts redisplay until the input is processed.
+If the value is nil, redisplay is never preempted.  */);
   Vredisplay_preemption_period = make_float (0.10);
 #endif