[Emacs-diffs] /srv/bzr/emacs/trunk r107095: Try to document filter-buffer-substring changes

[Glenn Morris]

------------------------------------------------------------
revno: 107095
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sat 2012-02-04 11:48:06 -0800
message:
  Try to document filter-buffer-substring changes
  
  * doc/lispref/text.texi (Buffer Contents):
  Update filter-buffer-substring description.
  
  * lisp/simple.el (filter-buffer-substring-functions)
  (buffer-substring-filters, filter-buffer-substring): Doc fixes.
  
  * etc/NEWS: Related edits.
modified:
  doc/lispref/ChangeLog
  doc/lispref/text.texi
  etc/NEWS
  lisp/ChangeLog
  lisp/simple.el

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-04 14:56:32 +0000
+++ b/doc/lispref/ChangeLog     2012-02-04 19:48:06 +0000
@@ -1,3 +1,8 @@
+2012-02-04  Glenn Morris  <address@hidden>
+
+       * text.texi (Buffer Contents):
+       Update filter-buffer-substring description.
+
 2012-02-04  Chong Yidong  <address@hidden>
 
        * functions.texi (What Is a Function): Add closures.  Mention

=== modified file 'doc/lispref/text.texi'
--- a/doc/lispref/text.texi     2012-02-02 04:37:05 +0000
+++ b/doc/lispref/text.texi     2012-02-04 19:48:06 +0000
@@ -218,44 +218,46 @@
 properties, just the characters themselves.  @xref{Text Properties}.
 @end defun
 
address@hidden filter-buffer-substring start end &optional delete noprops
address@hidden filter-buffer-substring start end &optional delete
 This function passes the buffer text between @var{start} and @var{end}
-through the filter functions specified by the variable
address@hidden, and returns the value from the last
-filter function.  If @code{buffer-substring-filters} is @code{nil},
-the value is the unaltered text from the buffer, what
address@hidden would return.
+through the filter functions specified by the wrapper hook
address@hidden, and returns the final
+result of applying all filters.  The obsolete variable
address@hidden is also consulted.  If both of these
+variables are @code{nil}, the value is the unaltered text from the
+buffer, as @code{buffer-substring} would return.
 
 If @var{delete} is address@hidden, this function deletes the text
 between @var{start} and @var{end} after copying it, like
 @code{delete-and-extract-region}.
 
-If @var{noprops} is address@hidden, the final string returned does not
-include text properties, while the string passed through the filters
-still includes text properties from the buffer text.
-
 Lisp code should use this function instead of @code{buffer-substring},
 @code{buffer-substring-no-properties},
 or @code{delete-and-extract-region} when copying into user-accessible
 data structures such as the kill-ring, X clipboard, and registers.
 Major and minor modes can add functions to
address@hidden to alter such text as it is copied out
-of the buffer.
address@hidden to alter such text as it is
+copied out of the buffer.
 @end defun
 
address@hidden buffer-substring-filters
-This variable should be a list of functions that accept a single
-argument, a string, and return a string.
address@hidden passes the buffer substring to the
-first function in this list, and the return value of each function is
-passed to the next function.  The return value of the last function is
-used as the return value of @code{filter-buffer-substring}.
-
-As a special convention, point is set to the start of the buffer text
-being operated on (i.e., the @var{start} argument for
address@hidden) before these functions are called.
-
-If this variable is @code{nil}, no filtering is performed.
address@hidden filter-buffer-substring-functions
+This variable is a wrapper hook (@pxref{Running Hooks}), whose members
+should be functions that accept four arguments: @var{fun},
address@hidden, @var{end}, and @var{delete}.  @var{fun} is a function
+that takes three arguments (@var{start}, @var{end}, and @var{delete}),
+and returns a string.  In both cases, the @var{start}, @var{end}, and
address@hidden arguments are the same as those of
address@hidden
+
+The first hook function is passed a @var{fun} that is equivalent to
+the default operation of @code{filter-buffer-substring}, i.e. it
+returns the buffer-substring between @var{start} and @var{end}
+(processed by any @code{buffer-substring-filters}) and optionally
+deletes the original text from the buffer.  In most cases, the hook
+function will call @var{fun} once, and then do its own processing of
+the result.  The next hook function receives a @var{fun} equivalent to
+this, and so on.  The actual return value is the result of all the
+hook functions acting in sequence.
 @end defvar
 
 @defun buffer-string

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2012-02-04 14:56:32 +0000
+++ b/etc/NEWS  2012-02-04 19:48:06 +0000
@@ -1019,6 +1019,11 @@
 versions, these regions were delineated by `mouse-drag-overlay', which
 has now been removed.
 
++++
+** The fourth argument of filter-buffer-substring, which says to remove
+text properties from the final result, has been removed.
+Eg simply pass the result through substring-no-properties if you need this.
+
 ---
 ** cl.el no longer provides `cl-19'.
 
@@ -1415,6 +1420,7 @@
 *** `tooltip-use-echo-area' is obsolete.
 Rather than setting this to t, disable Tooltip mode instead.
 
++++
 *** buffer-substring-filters is obsolete.
 Use `filter-buffer-substring-functions' instead.
 

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-02-04 09:57:09 +0000
+++ b/lisp/ChangeLog    2012-02-04 19:48:06 +0000
@@ -1,3 +1,8 @@
+2012-02-04  Glenn Morris  <address@hidden>
+
+       * simple.el (filter-buffer-substring-functions)
+       (buffer-substring-filters, filter-buffer-substring): Doc fixes.
+
 2012-02-04  Lars Ljung  <address@hidden>  (tiny change)
 
        * eshell/esh-ext.el (eshell-windows-shell-file): Match "cmdproxy"

=== modified file 'lisp/simple.el'
--- a/lisp/simple.el    2012-01-28 14:29:29 +0000
+++ b/lisp/simple.el    2012-02-04 19:48:06 +0000
@@ -2914,28 +2914,46 @@
 
 
 (defvar filter-buffer-substring-functions nil
-  "Wrapper hook around `filter-buffer-substring'.
-The functions on this special hook are called with four arguments:
-  NEXT-FUN BEG END DELETE
-NEXT-FUN is a function of three arguments (BEG END DELETE)
-that performs the default operation.  The other three arguments
-are like the ones passed to `filter-buffer-substring'.")
+  "This variable is a wrapper hook around `filter-buffer-substring'.
+Each member of the hook should be a function accepting four arguments:
+\(FUN BEG END DELETE), where FUN is itself a function of three arguments
+\(BEG END DELETE).  The arguments BEG, END, and DELETE are the same
+as those of `filter-buffer-substring' in each case.
+
+The first hook function to be called receives a FUN equivalent
+to the default operation of `filter-buffer-substring',
+i.e. one that returns the buffer-substring between BEG and
+END (processed by any `buffer-substring-filters').  Normally,
+the hook function will call FUN and then do its own processing
+of the result.  The next hook function receives a FUN equivalent
+to the previous hook function, calls it, and does its own
+processing, and so on.  The overall result is that of all hook
+functions acting in sequence.
+
+Any hook may choose not to call FUN though, in which case it
+effectively replaces the default behavior with whatever it chooses.
+Of course, a later hook function may do the same thing.")
 
 (defvar buffer-substring-filters nil
   "List of filter functions for `filter-buffer-substring'.
 Each function must accept a single argument, a string, and return
 a string.  The buffer substring is passed to the first function
 in the list, and the return value of each function is passed to
-the next.  The return value of the last function is used as the
-return value of `filter-buffer-substring'.
+the next.  The final result (if `buffer-substring-filters' is
+nil, this is the unfiltered buffer-substring) is passed to the
+first function on `filter-buffer-substring-functions'.
 
-If this variable is nil, no filtering is performed.")
+As a special convention, point is set to the start of the buffer text
+being operated on (i.e., the first argument of `filter-buffer-substring')
+before these functions are called.")
 (make-obsolete-variable 'buffer-substring-filters
                         'filter-buffer-substring-functions "24.1")
 
 (defun filter-buffer-substring (beg end &optional delete)
   "Return the buffer substring between BEG and END, after filtering.
-The filtering is performed by `filter-buffer-substring-functions'.
+The wrapper hook `filter-buffer-substring-functions' performs
+the actual filtering.  The obsolete variable `buffer-substring-filters'
+is also consulted.  If both of these are nil, no filtering is done.
 
 If DELETE is non-nil, the text between BEG and END is deleted
 from the buffer.