[Emacs-diffs] emacs-24 r117160: Doc updates re filter-buffer-substring

[Glenn Morris]

------------------------------------------------------------
revno: 117160
revision-id: address@hidden
parent: address@hidden
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Mon 2014-05-26 18:53:45 -0700
message:
  Doc updates re filter-buffer-substring
  
  * lisp/simple.el (filter-buffer-substring-functions)
  (filter-buffer-substring-function, buffer-substring-filters)
  (filter-buffer-substring, buffer-substring--filter): Doc fixes.
  
  * doc/lispref/text.texi (Buffer Contents):
  Update for filter-buffer-substring changes.
  
  * doc/lispref/hooks.texi: Remove old comment.
  
  * etc/NEWS: Related markup.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/hooks.texi         hooks.texi-20091113204419-o5vbwnq5f7feedwu-6186
  doc/lispref/text.texi          text.texi-20091113204419-o5vbwnq5f7feedwu-6215
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1
  lisp/ChangeLog                 changelog-20091113204419-o5vbwnq5f7feedwu-1432
  lisp/simple.el                 simple.el-20091113204419-o5vbwnq5f7feedwu-403

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-05-27 01:09:45 +0000
+++ b/doc/lispref/ChangeLog     2014-05-27 01:53:45 +0000
@@ -1,5 +1,8 @@
 2014-05-27  Glenn Morris  <address@hidden>
 
+       * text.texi (Buffer Contents):
+       Update for filter-buffer-substring changes.
+
        * abbrevs.texi (Abbrev Expansion): Update for expand-abbrev changes.
        * functions.texi (Advising Functions): Standardize menu case.
 

=== modified file 'doc/lispref/hooks.texi'
--- a/doc/lispref/hooks.texi    2014-05-27 01:25:57 +0000
+++ b/doc/lispref/hooks.texi    2014-05-27 01:53:45 +0000
@@ -243,7 +243,6 @@
 completion-list-insert-choice-function
 deactivate-current-input-method-function
 describe-current-input-method-function
-filter-buffer-substring-functions
 font-lock-function
 menu-bar-select-buffer-function
 read-file-name-function

=== modified file 'doc/lispref/text.texi'
--- a/doc/lispref/text.texi     2014-04-21 14:50:19 +0000
+++ b/doc/lispref/text.texi     2014-05-27 01:53:45 +0000
@@ -220,15 +220,17 @@
 @end defun
 
 @defun 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 wrapper hook
address@hidden, and returns the result.  The
-obsolete variable @code{buffer-substring-filters} is also consulted.
-If both of these variables are @code{nil}, the value is the unaltered
-text from the buffer, i.e., what @code{buffer-substring} would
-return.
-
-If @var{delete} is address@hidden, this function deletes the text
+This function filters the buffer text between @var{start} and @var{end}
+using a function specified by the variable
address@hidden, and returns the result.
+
+The default filter function consults the obsolete wrapper hook
address@hidden, and the obsolete variable
address@hidden  If both of these are @code{nil}, it
+returns the unaltered text from the buffer, i.e., what
address@hidden would return.
+
+If @var{delete} is address@hidden, the function deletes the text
 between @var{start} and @var{end} after copying it, like
 @code{delete-and-extract-region}.
 
@@ -236,20 +238,29 @@
 @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.
+Major and minor modes can modify @code{filter-buffer-substring-function}
+to alter such text as it is copied out of the buffer.
 @end defun
 
address@hidden FIXME: `filter-buffer-substring-function' should be documented.
address@hidden filter-buffer-substring-function
+The value of this variable is a function that @code{filter-buffer-substring}
+will call to do the actual work.  The function receives three
+arguments, the same as those of @code{filter-buffer-substring},
+which it should treat as per the documentation of that function.  It
+should return the filtered text (and optionally delete the source text).
address@hidden defvar
+
address@hidden The following two variables are obsoleted by
address@hidden, but are still supported for
+backward compatibility.
+
 @defvar 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
+This obsolete variable is a wrapper hook, whose members should be functions
+that accept four arguments: @var{fun}, @var{start}, @var{end}, and
address@hidden  @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 @var{delete} arguments are
+the same as those of @code{filter-buffer-substring}.
 
 The first hook function is passed a @var{fun} that is equivalent to
 the default operation of @code{filter-buffer-substring}, i.e., it
@@ -263,14 +274,12 @@
 @end defvar
 
 @defvar buffer-substring-filters
-This variable is obsoleted by
address@hidden, but is still supported for
-backward compatibility.  Its value should should be a list of
-functions which accept a single string argument and return another
-string.  @code{filter-buffer-substring} 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 passed to @code{filter-buffer-substring-functions}.
+The value of this obsolete variable should be a list of functions
+that accept a single string argument and return another string.
+The default @code{filter-buffer-substring} function 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 passed to @code{filter-buffer-substring-functions}.
 @end defvar
 
 @defun current-word &optional strict really-word

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-05-25 00:31:06 +0000
+++ b/etc/NEWS  2014-05-27 01:53:45 +0000
@@ -1361,6 +1361,7 @@
 *** `generic-make-keywords-list'
 *** `get-upcase-table' (use `case-table-get-table' instead).
 
++++
 ** `with-wrapper-hook' is obsoleted by `add-function'.
 The few hooks that used with-wrapper-hook are replaced as follows:
 *** `abbrev-expand-function' obsoletes `abbrev-expand-functions'.

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2014-05-27 01:25:57 +0000
+++ b/lisp/ChangeLog    2014-05-27 01:53:45 +0000
@@ -1,5 +1,9 @@
 2014-05-27  Glenn Morris  <address@hidden>
 
+       * simple.el (filter-buffer-substring-functions)
+       (filter-buffer-substring-function, buffer-substring-filters)
+       (filter-buffer-substring, buffer-substring--filter): Doc fixes.
+
        * minibuffer.el (completion-in-region-functions, completion-in-region)
        (completion--in-region): Doc fixes.
 

=== modified file 'lisp/simple.el'
--- a/lisp/simple.el    2014-05-17 16:06:02 +0000
+++ b/lisp/simple.el    2014-05-27 01:53:45 +0000
@@ -3463,46 +3463,50 @@
 
 
 (defvar filter-buffer-substring-functions nil
-  "This variable is a wrapper hook around `filter-buffer-substring'.")
+  "This variable is a wrapper hook around `buffer-substring--filter'.")
 (make-obsolete-variable 'filter-buffer-substring-functions
                         'filter-buffer-substring-function "24.4")
 
 (defvar filter-buffer-substring-function #'buffer-substring--filter
   "Function to perform the filtering in `filter-buffer-substring'.
-The function is called with 3 arguments:
-\(BEG END DELETE).  The arguments BEG, END, and DELETE are the same
-as those of `filter-buffer-substring' in each case.
-It should return the buffer substring between BEG and END, after filtering.")
+The function is called with the same 3 arguments (BEG END DELETE)
+that `filter-buffer-substring' received.  It should return the
+buffer substring between BEG and END, after filtering.  If DELETE is
+non-nil, it should delete the text between BEG and END from the buffer.")
 
 (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.
+  "List of filter functions for `buffer-substring--filter'.
+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.
 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')
+being operated on (i.e., the first argument of `buffer-substring--filter')
 before these functions are called.")
 (make-obsolete-variable 'buffer-substring-filters
                         'filter-buffer-substring-function "24.1")
 
 (defun filter-buffer-substring (beg end &optional delete)
   "Return the buffer substring between BEG and END, after filtering.
-The hook `filter-buffer-substring-function' performs the actual filtering.
-By default, no filtering is done.
-
-If DELETE is non-nil, the text between BEG and END is deleted
-from the buffer.
-
-This function should be used instead of `buffer-substring',
-`buffer-substring-no-properties', or `delete-and-extract-region'
-when you want to allow filtering to take place.  For example,
-major or minor modes can use `filter-buffer-substring-function' to
-extract characters that are special to a buffer, and should not
-be copied into other buffers."
+If DELETE is non-nil, delete the text between BEG and END from the buffer.
+
+This calls the function that `filter-buffer-substring-function' specifies
+\(passing the same three arguments that it received) to do the work,
+and returns whatever it does.  The default function does no filtering,
+unless a hook has been set.
+
+Use `filter-buffer-substring' instead of `buffer-substring',
+`buffer-substring-no-properties', or `delete-and-extract-region' when
+you want to allow filtering to take place.  For example, major or minor
+modes can use `filter-buffer-substring-function' to extract characters
+that are special to a buffer, and should not be copied into other buffers."
   (funcall filter-buffer-substring-function beg end delete))
 
 (defun buffer-substring--filter (beg end &optional delete)
+  "Default function to use for `filter-buffer-substring-function'.
+Its arguments and return value are as specified for `filter-buffer-substring'.
+This respects the wrapper hook `filter-buffer-substring-functions',
+and the abnormal hook `buffer-substring-filters'.
+No filtering is done unless a hook says to."
   (with-wrapper-hook filter-buffer-substring-functions (beg end delete)
     (cond
      ((or delete buffer-substring-filters)