bug#33179: 26; Doc string of `filter-buffer-substring'

[Noam Postavsky]

Drew Adams <drew.adams@oracle.com> writes:

>> > IIUC, the meaning of "extract" in this sentence is to exclude the
>> > chars from the result.
>> 
>> No, I don't think it means that.  It means "take".
>
> Then I don't understand the "and should not be copied
> into other buffers" part.  I thought that text describes
> a situation where you want to return some parts, for
> copying to another buffer, and you want to exclude other
> parts from that copying.

For what it's worth, I read it like Drew does.  I also think giving
"characters" as an example doesn't make much sense, because I can't
really think of characters so "special to a buffer" that they "should
not be copied into other buffers".  Grepping the Emacs source, the only
example usage I found was in org-indent.el, which uses it to exclude
text properties, so I propose changing the docstring example
accordingly.

>From c0cbc1cb7d5bbb0942a76781c1ed29d1346e5644 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Sat, 27 Oct 2018 15:27:45 -0400
Subject: [PATCH v1] * lisp/simple.el (filter-buffer-substring): Clarify doc
 (Bug#33179).

---
 lisp/simple.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/simple.el b/lisp/simple.el
index 29bb9cbcfb..08f622ad8e 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -4232,7 +4232,7 @@ filter-buffer-substring
 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
+modes can use `filter-buffer-substring-function' to exclude text properties
 that are special to a buffer, and should not be copied into other buffers."
   (funcall filter-buffer-substring-function beg end delete))
 
-- 
2.11.0