emacs-31 7a9c0049249: ; Clarify documentation of 'filter-buffer-substring'

branch: emacs-31
commit 7a9c0049249c0a3eac8ca698ec504502a737dea8
Author: Eli Zaretskii <[email protected]>
Commit: Eli Zaretskii <[email protected]>

    ; Clarify documentation of 'filter-buffer-substring'
    
    * doc/lispref/text.texi (Buffer Contents): Clarify that the order
    of buffer positions in arguments of 'filter-buffer-substring'
    should not matter.
    
    * lisp/simple.el (filter-buffer-substring-function):
    (filter-buffer-substring): Doc fix.
---
 doc/lispref/text.texi | 8 +++++++-
 lisp/simple.el        | 6 ++++--
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 6fcc1b0a078..b7e494c985f 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -238,7 +238,10 @@ reordering of bidirectional text, use the
 @defun filter-buffer-substring start end &optional delete
 This function filters the buffer text between @var{start} and @var{end}
 using a function specified by the variable
-@code{filter-buffer-substring-function}, and returns the result.
+@code{filter-buffer-substring-function}, and returns the result.  The
+order of buffer positions specified by @var{start} and @var{end} should
+not matter, since this function is frequently used for extracting text
+passed to kill functions (@pxref{Kill Functions}).
 
 The default filter function consults the obsolete wrapper hook
 @code{filter-buffer-substring-functions} (see the documentation string
@@ -264,6 +267,9 @@ 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).
+Note that it must process the @var{start} and @var{end} arguments
+regardless of the order of the buffer positions they specify, to comply
+with the protocol of extracting text for the purposes of killing it.
 @end defvar
 
 @noindent The following two variables are obsoleted by
diff --git a/lisp/simple.el b/lisp/simple.el
index fd9ba28c762..7ea287fd6ff 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -5579,12 +5579,14 @@ These commands include \\[set-mark-command] and \\[start-kbd-macro]."
   "Function to perform the filtering in `filter-buffer-substring'.
 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.")
+buffer substring between BEG and END, regardless of the order of
+BEG and END, after filtering.  If DELETE is non-nil, it should
+delete the text between BEG and END from the buffer.")
 
 (defun filter-buffer-substring (beg end &optional delete)
   "Return the buffer substring between BEG and END, after filtering.
 If DELETE is non-nil, delete the text between BEG and END from the buffer.
+The order of BEG and END does not matter.
 
 This calls the function that `filter-buffer-substring-function' specifies
 \(passing the same three arguments that it received) to do the work,