[Emacs-diffs] Changes to emacs/lispref/display.texi

[Richard M . Stallman]

Index: emacs/lispref/display.texi
diff -c emacs/lispref/display.texi:1.171 emacs/lispref/display.texi:1.172
*** emacs/lispref/display.texi:1.171    Sun Jun 26 13:51:11 2005
--- emacs/lispref/display.texi  Sun Jul  3 19:05:09 2005
***************
*** 14,22 ****
  * Refresh Screen::      Clearing the screen and redrawing everything on it.
  * Forcing Redisplay::   Forcing redisplay.
  * Truncation::          Folding or wrapping long text lines.
! * The Echo Area::       Where messages are displayed.
  * Warnings::            Displaying warning messages for the user.
- * Progress::            Informing user about progress of a long operation.
  * Invisible Text::      Hiding part of the buffer text.
  * Selective Display::   Hiding part of the buffer text (the old way).
  * Temporary Displays::  Displays that go away automatically.
--- 14,21 ----
  * Refresh Screen::      Clearing the screen and redrawing everything on it.
  * Forcing Redisplay::   Forcing redisplay.
  * Truncation::          Folding or wrapping long text lines.
! * The Echo Area::       Displaying messages at the bottom of the screen.
  * Warnings::            Displaying warning messages for the user.
  * Invisible Text::      Hiding part of the buffer text.
  * Selective Display::   Hiding part of the buffer text (the old way).
  * Temporary Displays::  Displays that go away automatically.
***************
*** 184,190 ****
  @cindex error display
  @cindex echo area
  
! The @dfn{echo area} is used for displaying error messages
  (@pxref{Errors}), for messages made with the @code{message} primitive,
  and for echoing keystrokes.  It is not the same as the minibuffer,
  despite the fact that the minibuffer appears (when active) in the same
--- 183,189 ----
  @cindex error display
  @cindex echo area
  
!   The @dfn{echo area} is used for displaying error messages
  (@pxref{Errors}), for messages made with the @code{message} primitive,
  and for echoing keystrokes.  It is not the same as the minibuffer,
  despite the fact that the minibuffer appears (when active) in the same
***************
*** 193,201 ****
  the minibuffer for use of that screen space (@pxref{Minibuffer,, The
  Minibuffer, emacs, The GNU Emacs Manual}).
  
! You can write output in the echo area by using the Lisp printing
! functions with @code{t} as the stream (@pxref{Output Functions}), or as
! follows:
  
  @defun message string &rest arguments
  This function displays a message in the echo area.  The
--- 192,213 ----
  the minibuffer for use of that screen space (@pxref{Minibuffer,, The
  Minibuffer, emacs, The GNU Emacs Manual}).
  
!   You can write output in the echo area by using the Lisp printing
! functions with @code{t} as the stream (@pxref{Output Functions}), or
! explicitly.
! 
! @menu
! * Displaying Messages:: Explicitly displaying text in the echo area.
! * Progress Reports::    Informing user about progress of a long operation.
! * Logging Messages::    Echo area messages are logged for the user.
! * Echo Area Customization:: Controlling the echo area.
! @end menu
! 
! @node Displaying Messages
! @subsection Displaying Messages in the Echo Area
! 
!   This section describes the functions for explicitly producing echo
! area messages.  Many other Emacs features display messages there, too.
  
  @defun message string &rest arguments
  This function displays a message in the echo area.  The
***************
*** 216,227 ****
  its normal size.  If the minibuffer is active, this brings the
  minibuffer contents back onto the screen immediately.
  
- @vindex message-truncate-lines
- Normally, displaying a long message resizes the echo area to display
- the entire message.  But if the variable @code{message-truncate-lines}
- is address@hidden, the echo area does not resize, and the message is
- truncated to fit it, as in Emacs 20 and before.
- 
  @example
  @group
  (message "Minibuffer depth is %d."
--- 228,233 ----
***************
*** 241,252 ****
  depending on its size, use @code{display-message-or-buffer} (see below).
  @end defun
  
- @defopt max-mini-window-height
- This variable specifies the maximum height for resizing minibuffer
- windows.  If a float, it specifies a fraction of the height of the
- frame.  If an integer, it specifies a number of lines.
- @end defopt
- 
  @tindex with-temp-message
  @defmac with-temp-message message &rest body
  This construct displays a message in the echo area temporarily, during
--- 247,252 ----
***************
*** 303,325 ****
  echo area, or @code{nil} if there is none.
  @end defun
  
! @defvar cursor-in-echo-area
! This variable controls where the cursor appears when a message is
! displayed in the echo area.  If it is address@hidden, then the cursor
! appears at the end of the message.  Otherwise, the cursor appears at
! point---not in the echo area at all.
  
! The value is normally @code{nil}; Lisp programs bind it to @code{t}
! for brief periods of time.
! @end defvar
  
! @defvar echo-area-clear-hook
! This normal hook is run whenever the echo area is cleared---either by
! @code{(message nil)} or for any other reason.
! @end defvar
  
! Almost all the messages displayed in the echo area are also recorded
! in the @samp{*Messages*} buffer.
  
  @defopt message-log-max
  This variable specifies how many lines to keep in the @samp{*Messages*}
--- 303,432 ----
  echo area, or @code{nil} if there is none.
  @end defun
  
! @node Progress
! @subsection Reporting Operation Progress
! @cindex progress reporting
  
!   When an operation can take a while to finish, you should inform the
! user about the progress it makes.  This way the user can estimate
! remaining time and clearly see that Emacs is busy working, not hung.
  
!   Functions listed in this section provide simple and efficient way of
! reporting operation progress.  Here is a working example that does
! nothing useful:
  
! @smallexample
! (let ((progress-reporter
!        (make-progress-reporter "Collecting mana for Emacs..."
!                                0  500)))
!   (dotimes (k 500)
!     (sit-for 0.01)
!     (progress-reporter-update progress-reporter k))
!   (progress-reporter-done progress-reporter))
! @end smallexample
! 
! @defun make-progress-reporter message min-value max-value &optional 
current-value min-change min-time
! This function creates and returns a @dfn{progress reporter}---an
! object you will use as an argument for all other functions listed
! here.  The idea is to precompute as much data as possible to make
! progress reporting very fast.
! 
! When this progress reporter is subsequently used, it will display
! @var{message} in the echo area, followed by progress percentage.
! @var{message} is treated as a simple string.  If you need it to depend
! on a filename, for instance, use @code{format} before calling this
! function.
! 
! @var{min-value} and @var{max-value} arguments stand for starting and
! final states of your operation.  For instance, if you scan a buffer,
! they should be the results of @code{point-min} and @code{point-max}
! correspondingly.  It is required that @var{max-value} is greater than
! @var{min-value}.  If you create progress reporter when some part of
! the operation has already been completed, then specify
! @var{current-value} argument.  But normally you should omit it or set
! it to @code{nil}---it will default to @var{min-value} then.
! 
! Remaining arguments control the rate of echo area updates.  Progress
! reporter will wait for at least @var{min-change} more percents of the
! operation to be completed before printing next message.
! @var{min-time} specifies the minimum time in seconds to pass between
! successive prints.  It can be fractional.  Depending on Emacs and
! system capabilities, progress reporter may or may not respect this
! last argument or do it with varying precision.  Default value for
! @var{min-change} is 1 (one percent), for @var{min-time}---0.2
! (seconds.)
! 
! This function calls @code{progress-reporter-update}, so the first
! message is printed immediately.
! @end defun
! 
! @defun progress-reporter-update reporter value
! This function does the main work of reporting progress of your
! operation.  It displays the message of @var{reporter}, followed by
! progress percentage determined by @var{value}.  If percentage is zero,
! or close enough according to the @var{min-change} and @var{min-time}
! arguments, then it is omitted from the output.
! 
! @var{reporter} must be the result of a call to
! @code{make-progress-reporter}.  @var{value} specifies the current
! state of your operation and must be between @var{min-value} and
! @var{max-value} (inclusive) as passed to
! @code{make-progress-reporter}.  For instance, if you scan a buffer,
! then @var{value} should be the result of a call to @code{point}.
! 
! This function respects @var{min-change} and @var{min-time} as passed
! to @code{make-progress-reporter} and so does not output new messages
! on every invocation.  It is thus very fast and normally you should not
! try to reduce the number of calls to it: resulting overhead will most
! likely negate your effort.
! @end defun
! 
! @defun progress-reporter-force-update reporter value &optional new-message
! This function is similar to @code{progress-reporter-update} except
! that it prints a message in the echo area unconditionally.
! 
! The first two arguments have the same meaning as for
! @code{progress-reporter-update}.  Optional @var{new-message} allows
! you to change the message of the @var{reporter}.  Since this functions
! always updates the echo area, such a change will be immediately
! presented to the user.
! @end defun
! 
! @defun progress-reporter-done reporter
! This function should be called when the operation is finished.  It
! prints the message of @var{reporter} followed by word ``done'' in the
! echo area.
! 
! You should always call this function and not hope for
! @code{progress-reporter-update} to print ``100%.''  Firstly, it may
! never print it, there are many good reasons for this not to happen.
! Secondly, ``done'' is more explicit.
! @end defun
! 
! @defmac dotimes-with-progress-reporter (var count [result]) message body...
! This is a convenience macro that works the same way as @code{dotimes}
! does, but also reports loop progress using the functions described
! above.  It allows you to save some typing.
! 
! You can rewrite the example in the beginning of this node using
! this macro this way:
! 
! @example
! (dotimes-with-progress-reporter
!     (k 500)
!     "Collecting some mana for Emacs..."
!   (sit-for 0.01))
! @end example
! @end defmac
! 
! @node Logging Messages
! @subsection Logging Messages in @samp{*Messages*}
! @cindex logging echo-area messages
! 
!   Almost all the messages displayed in the echo area are also recorded
! in the @samp{*Messages*} buffer so that the user can refer back to
! them.  This includes all the messages that are output with
! @code{message}.
  
  @defopt message-log-max
  This variable specifies how many lines to keep in the @samp{*Messages*}
***************
*** 333,338 ****
--- 440,487 ----
  @end example
  @end defopt
  
+   To make @samp{*Messages*} more convenient for the user, the logging
+ facility combines successive identical messages.  It also combines
+ successive related messages for the sake of two cases: question
+ followed by answer, and a series of progress messages.
+ 
+   A ``question followed by an answer'' means two messages like the
+ ones produced by @code{y-or-n-p}: the first is @address@hidden,
+ and the second is @address@hidden@var{answer}}.  The first
+ message conveys no additional information beyond what's in the second,
+ so logging the second message discards the first from the log.
+ 
+   A ``series of progress messages'' means successive messages like
+ those produced by @code{make-progress-reporter}.  They have the form
+ @address@hidden@var{how-far}}, where @var{base} is the same each
+ time, while @var{how-far} varies.  Logging each message in the series
+ discards the previous one, provided they are consecutive.
+ 
+   The functions @code{make-progress-reporter} and @code{y-or-n-p}
+ don't have to do anything special to activate the message log
+ combination feature.  It operates whenever two consecutive messages
+ are logged that share a common prefix ending in @samp{...}.
+ 
+ @node Echo Area Customization
+ @subsection Echo Area Customization
+ 
+   These variables control details of how the echo area works.
+ 
+ @defvar cursor-in-echo-area
+ This variable controls where the cursor appears when a message is
+ displayed in the echo area.  If it is address@hidden, then the cursor
+ appears at the end of the message.  Otherwise, the cursor appears at
+ point---not in the echo area at all.
+ 
+ The value is normally @code{nil}; Lisp programs bind it to @code{t}
+ for brief periods of time.
+ @end defvar
+ 
+ @defvar echo-area-clear-hook
+ This normal hook is run whenever the echo area is cleared---either by
+ @code{(message nil)} or for any other reason.
+ @end defvar
+ 
  @defvar echo-keystrokes
  This variable determines how much time should elapse before command
  characters echo.  Its value must be an integer or floating point number,
***************
*** 346,351 ****
--- 495,513 ----
  If the value is zero, then command input is not echoed.
  @end defvar
  
+ @defopt max-mini-window-height
+ This variable specifies the maximum height for resizing minibuffer
+ windows.  If a float, it specifies a fraction of the height of the
+ frame.  If an integer, it specifies a number of lines.
+ @end defopt
+ 
+ @defvar message-truncate-lines
+ Normally, displaying a long message resizes the echo area to display
+ the entire message.  But if the variable @code{message-truncate-lines}
+ is address@hidden, the echo area does not resize, and the message is
+ truncated to fit it, as in Emacs 20 and before.
+ @end defvar
+ 
  @node Warnings
  @section Reporting Warnings
  @cindex warnings
***************
*** 535,656 ****
  that warning is not logged.
  @end defopt
  
- @node Progress
- @section Reporting Operation Progress
- @cindex progress reporting
- 
-   When an operation can take a while to finish, you should inform the
- user about the progress it makes.  This way the user can estimate
- remaining time and clearly see that Emacs is busy working, not hung.
- 
-   Functions listed in this section provide simple and efficient way of
- reporting operation progress.  Here is a working example that does
- nothing useful:
- 
- @smallexample
- (let ((progress-reporter
-        (make-progress-reporter "Collecting mana for Emacs..."
-                                0  500)))
-   (dotimes (k 500)
-     (sit-for 0.01)
-     (progress-reporter-update progress-reporter k))
-   (progress-reporter-done progress-reporter))
- @end smallexample
- 
- @defun make-progress-reporter message min-value max-value &optional 
current-value min-change min-time
- This function creates and returns a @dfn{progress reporter}---an
- object you will use as an argument for all other functions listed
- here.  The idea is to precompute as much data as possible to make
- progress reporting very fast.
- 
- When this progress reporter is subsequently used, it will display
- @var{message} in the echo area, followed by progress percentage.
- @var{message} is treated as a simple string.  If you need it to depend
- on a filename, for instance, use @code{format} before calling this
- function.
- 
- @var{min-value} and @var{max-value} arguments stand for starting and
- final states of your operation.  For instance, if you scan a buffer,
- they should be the results of @code{point-min} and @code{point-max}
- correspondingly.  It is required that @var{max-value} is greater than
- @var{min-value}.  If you create progress reporter when some part of
- the operation has already been completed, then specify
- @var{current-value} argument.  But normally you should omit it or set
- it to @code{nil}---it will default to @var{min-value} then.
- 
- Remaining arguments control the rate of echo area updates.  Progress
- reporter will wait for at least @var{min-change} more percents of the
- operation to be completed before printing next message.
- @var{min-time} specifies the minimum time in seconds to pass between
- successive prints.  It can be fractional.  Depending on Emacs and
- system capabilities, progress reporter may or may not respect this
- last argument or do it with varying precision.  Default value for
- @var{min-change} is 1 (one percent), for @var{min-time}---0.2
- (seconds.)
- 
- This function calls @code{progress-reporter-update}, so the first
- message is printed immediately.
- @end defun
- 
- @defun progress-reporter-update reporter value
- This function does the main work of reporting progress of your
- operation.  It displays the message of @var{reporter}, followed by
- progress percentage determined by @var{value}.  If percentage is zero,
- or close enough according to the @var{min-change} and @var{min-time}
- arguments, then it is omitted from the output.
- 
- @var{reporter} must be the result of a call to
- @code{make-progress-reporter}.  @var{value} specifies the current
- state of your operation and must be between @var{min-value} and
- @var{max-value} (inclusive) as passed to
- @code{make-progress-reporter}.  For instance, if you scan a buffer,
- then @var{value} should be the result of a call to @code{point}.
- 
- This function respects @var{min-change} and @var{min-time} as passed
- to @code{make-progress-reporter} and so does not output new messages
- on every invocation.  It is thus very fast and normally you should not
- try to reduce the number of calls to it: resulting overhead will most
- likely negate your effort.
- @end defun
- 
- @defun progress-reporter-force-update reporter value &optional new-message
- This function is similar to @code{progress-reporter-update} except
- that it prints a message in the echo area unconditionally.
- 
- The first two arguments have the same meaning as for
- @code{progress-reporter-update}.  Optional @var{new-message} allows
- you to change the message of the @var{reporter}.  Since this functions
- always updates the echo area, such a change will be immediately
- presented to the user.
- @end defun
- 
- @defun progress-reporter-done reporter
- This function should be called when the operation is finished.  It
- prints the message of @var{reporter} followed by word ``done'' in the
- echo area.
- 
- You should always call this function and not hope for
- @code{progress-reporter-update} to print ``100%.''  Firstly, it may
- never print it, there are many good reasons for this not to happen.
- Secondly, ``done'' is more explicit.
- @end defun
- 
- @defmac dotimes-with-progress-reporter (var count [result]) message body...
- This is a convenience macro that works the same way as @code{dotimes}
- does, but also reports loop progress using the functions described
- above.  It allows you to save some typing.
- 
- You can rewrite the example in the beginning of this node using
- this macro this way:
- 
- @example
- (dotimes-with-progress-reporter
-     (k 500)
-     "Collecting some mana for Emacs..."
-   (sit-for 0.01))
- @end example
- @end defmac
- 
  @node Invisible Text
  @section Invisible Text
  
--- 697,702 ----