Mercurial > emacs

--- a/lispref/display.texi	Sun Jul 03 19:02:02 2005 +0000
+++ b/lispref/display.texi	Sun Jul 03 19:05:09 2005 +0000
@@ -14,9 +14,8 @@
 * 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.
+* The Echo Area::       Displaying messages at the bottom of the screen.
 * 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.
@@ -184,7 +183,7 @@
 @cindex error display
 @cindex echo area

-The @dfn{echo area} is used for displaying error messages
+  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,9 +192,22 @@
 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:
+  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,12 +228,6 @@
 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 non-@code{nil}, 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."
@@ -241,12 +247,6 @@
 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
@@ -303,6 +303,170 @@
 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*}
+buffer.  The value @code{t} means there is no limit on how many lines to
+keep.  The value @code{nil} disables message logging entirely.  Here's
+how to display a message and prevent it from being logged:
+
+@example
+(let (message-log-max)
+  (message @dots{}))
+@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 @samp{@var{question}},
+and the second is @samp{@var{question}...@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
+@samp{@var{base}...@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 non-@code{nil}, then the cursor
@@ -318,21 +482,6 @@
 @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*}
-buffer.  The value @code{t} means there is no limit on how many lines to
-keep.  The value @code{nil} disables message logging entirely.  Here's
-how to display a message and prevent it from being logged:
-
-@example
-(let (message-log-max)
-  (message @dots{}))
-@end example
-@end defopt
-
 @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,6 +495,19 @@
 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 non-@code{nil}, 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,122 +697,6 @@
 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