4 files changed, 147 insertions, 25 deletions

diff --git a/lispref/ChangeLog b/lispref/ChangeLog
index b568e99fb58..c33e49ca773 100644
--- a/lispref/ChangeLog
+++ b/lispref/ChangeLog
@@ -1,3 +1,21 @@
+2004-10-09  Luc Teirlinck  <teirllm@auburn.edu>
+
+        * text.texi (Filling): Add anchor for definition of
+        `sentence-end-double-space'.
+
+        * searching.texi (Regexp Example): Update description of how
+        Emacs currently recognizes the end of a sentence.
+        (Standard Regexps): Update definition of the variable
+        `sentence-end'.  Add definition of the function `sentence-end'.
+
+2004-10-08  Paul Pogonyshev  <pogonyshev@gmx.net>
+
+        * display.texi (Progress): New node.
+
+2004-10-05  Kim F. Storm  <storm@cua.dk>
+
+        * display.texi (Fringe Bitmaps): Update fringe-bitmaps-at-pos.
+
 2004-09-29  Kim F. Storm  <storm@cua.dk>
 
         * display.texi (Fringe Bitmaps): Use symbols rather than numbers
diff --git a/lispref/display.texi b/lispref/display.texi
index 00b91fe1fd8..d7e1303abad 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -16,6 +16,7 @@ that Emacs presents to the user.
 * 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).
 * Overlay Arrow::       Display of an arrow to indicate position.
@@ -533,6 +534,104 @@ symbols.  If it matches the first few elements in a warning type, then
 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:
+
+@example
+(let ((progress-reporter
+       (make-progress-reporter "Collecting some mana for Emacs..."
+                               0  500)))
+  (dotimes (k 500)
+    (sit-for 0.01)
+    (progress-reporter-update progress-reporter k))
+  (progress-reporter-done progress-reporter))
+@end example
+
+@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
+This function creates a progress reporter---the 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.
+
+The @var{message} will be displayed 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 print the message of @var{reporter} followed by
+progress percentage determined by @var{value}.  If percentage is zero,
+then it is not printed at all.
+
+@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
+
 @node Invisible Text
 @section Invisible Text
 
@@ -2655,9 +2754,10 @@ symbols have their own name space.
 @defun fringe-bitmaps-at-pos &optional pos window
 This function returns the fringe bitmaps of the display line
 containing position @var{pos} in window @var{window}.  The return
-value has the form @code{(@var{left} . @var{right})}, where @var{left}
+value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
 is the symbol for the fringe bitmap in the left fringe (or @code{nil}
-if no bitmap), and @var{right} is similar for the right fringe.
+if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
+is non-@code{nil} if there is an overlay arrow in the left fringe.
 
 The value is @code{nil} if @var{pos} is not visible in @var{window}.
 If @var{window} is @code{nil}, that stands for the selected window.
diff --git a/lispref/searching.texi b/lispref/searching.texi
index 93a152fbbe1..ee6cb06b1e1 100644
--- a/lispref/searching.texi
+++ b/lispref/searching.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/searching
@@ -694,9 +694,9 @@ an @code{invalid-regexp} error is signaled.
 
   Here is a complicated regexp which was formerly used by Emacs to
 recognize the end of a sentence together with any whitespace that
-follows.  It was used as the variable @code{sentence-end}.  (Its value
-nowadays contains alternatives for @samp{.}, @samp{?} and @samp{!} in
-other character sets.)
+follows.  (Nowadays Emacs uses a similar but more complex default
+regexp constructed by the function @code{sentence-end}.
+@xref{Standard Regexps}.)
 
   First, we show the regexp as a string in Lisp syntax to distinguish
 spaces from tab characters.  The string constant begins and ends with a
@@ -730,9 +730,9 @@ deciphered as follows:
 The first part of the pattern is a character alternative that matches
 any one of three characters: period, question mark, and exclamation
 mark.  The match must begin with one of these three characters.  (This
-is the one point where the new value of @code{sentence-end} differs
-from the old.  The new value also lists sentence ending
-non-@acronym{ASCII} characters.)
+is one point where the new default regexp used by Emacs differs from
+the old.  The new value also allows some non-@acronym{ASCII}
+characters that end a sentence without any following whitespace.)
 
 @item []\"')@}]*
 The second part of the pattern matches any closing braces and quotation
@@ -1698,23 +1698,25 @@ whitespace or starting with a form feed (after its left margin).
 @end defvar
 
 @defvar sentence-end
-This is the regular expression describing the end of a sentence.  (All
-paragraph boundaries also end sentences, regardless.)  The (slightly
-simplified) default value is:
-
-@example
-"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
-@end example
-
-This means a period, question mark or exclamation mark (the actual
-default value also lists their alternatives in other character sets),
-followed optionally by closing parenthetical characters, followed by
-tabs, spaces or new lines.
-
-For a detailed explanation of this regular expression, see @ref{Regexp
-Example}.
+If non-@code{nil}, the value should be a regular expression describing
+the end of a sentence, including the whitespace following the
+sentence.  (All paragraph boundaries also end sentences, regardless.)
+
+If the value is @code{nil}, the default, then the function
+@code{sentence-end} has to construct the regexp.  That is why you
+should always call the function @code{sentence-end} to obtain the
+regexp to be used to recognize the end of a sentence.
 @end defvar
 
+@defun sentence-end
+This function returns the value of the variable @code{sentence-end},
+if non-@code{nil}.  Otherwise it returns a default value based on the
+values of the variables @code{sentence-end-double-space}
+(@pxref{Definition of sentence-end-double-space}),
+@code{sentence-end-without-period} and
+@code{sentence-end-without-space}.
+@end defun
+
 @ignore
    arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f
 @end ignore
diff --git a/lispref/text.texi b/lispref/text.texi
index caa3f21b7b1..00aa235f513 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -1,6 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
+@c 2000, 2001, 2004
 @c   Free Software Foundation, Inc.
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/text
@@ -1448,6 +1449,7 @@ the text around point.
 @end defun
 
 @defopt sentence-end-double-space
+@anchor{Definition of sentence-end-double-space}
 If this variable is non-@code{nil}, a period followed by just one space
 does not count as the end of a sentence, and the filling functions
 avoid breaking the line at such a place.