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

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

[Drew Adams]

IIUC, the meaning of "extract" in this sentence is to exclude the chars
from the result.  If so, please consider using "exclude" or "remove"
(preferably the former, as nothing is removed from the buffer) instead.
"Extract" can give the impression that those chars are extracted as the
result, rather than being excluded from the result.

  "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."

Yes, if read carefully one can guess what was really meant here, because
of the "and should not..." part.  Still, the text can be misleading as
it is now.

In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.16299
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

[Eli Zaretskii]

> Date: Sat, 27 Oct 2018 10:24:32 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 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".

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

[Drew Adams]

> > 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.
> >
> This patch is fine with me, thanks.

Thanks, guys.

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

[Noam Postavsky]

tags 33179 fixed
close 33179 26.2
quit

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

>> > example usage I found was in org-indent.el, which uses it to exclude
>> > text properties, so I propose changing the docstring example
>> > accordingly.
>> >
>> This patch is fine with me, thanks.
>
> Thanks, guys.

Pushed to emacs-26.

[1: de2818432a]: 2018-10-27 17:56:28 -0400
  * lisp/simple.el (filter-buffer-substring): Clarify doc (Bug#33179).
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=de2818432acacea4eec35d5a92f240856de7b765

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

[Drew Adams]

> > 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.

By "copying into other buffers" does we mean copy+paste
here?  What kind of copying is meant?

In sum, it's not clear to me what that "For example..."
sentence is trying to describe.  I thought I had some
idea, but that was apparently the wrong idea.

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

[Eli Zaretskii]

> Date: Sat, 27 Oct 2018 12:10:15 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 33179@debbugs.gnu.org
> 
> > > 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.

It's a "for example", so not very important, IMO.

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

[Noam Postavsky]

[-- Attachment #1: Type: text/plain, Size: 882 bytes --]

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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: patch --]
[-- Type: text/x-diff, Size: 994 bytes --]

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

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

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  33179@debbugs.gnu.org
> Date: Sat, 27 Oct 2018 15:32:50 -0400
> 
> 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).

This patch is fine with me, thanks.