GNU bug report logs - #33179
26; Doc string of `filter-buffer-substring'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 33179 in the body.
You can then email your comments to 33179 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26; Doc string of `filter-buffer-substring'
Date: Sat, 27 Oct 2018 10:24:32 -0700 (PDT)

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

Message #8 received at 33179 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 33179 <at> debbugs.gnu.org
Subject: Re: bug#33179: 26; Doc string of `filter-buffer-substring'
Date: Sat, 27 Oct 2018 21:53:45 +0300

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

Message #11 received at 33179 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 33179 <at> debbugs.gnu.org
Subject: RE: bug#33179: 26; Doc string of `filter-buffer-substring'
Date: Sat, 27 Oct 2018 12:10:15 -0700 (PDT)

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

Message #14 received at 33179 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 33179 <at> debbugs.gnu.org
Subject: Re: bug#33179: 26; Doc string of `filter-buffer-substring'
Date: Sat, 27 Oct 2018 22:25:23 +0300

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

Message #17 received at 33179 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 33179 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#33179: 26; Doc string of `filter-buffer-substring'
Date: Sat, 27 Oct 2018 15:32:50 -0400

[Message part 1 (text/plain, inline)]

Drew Adams <drew.adams <at> 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.

[v1-0001-lisp-simple.el-filter-buffer-substring-Clarify-do.patch (text/x-diff, inline)]

From c0cbc1cb7d5bbb0942a76781c1ed29d1346e5644 Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs <at> 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

Message #20 received at 33179 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Noam Postavsky <npostavs <at> gmail.com>
Cc: 33179 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#33179: 26; Doc string of `filter-buffer-substring'
Date: Sat, 27 Oct 2018 22:38:32 +0300

> From: Noam Postavsky <npostavs <at> gmail.com>
> Cc: Eli Zaretskii <eliz <at> gnu.org>,  33179 <at> 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 <at> 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.

Message #23 received at 33179 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Noam Postavsky <npostavs <at> gmail.com>
Cc: 33179 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: RE: bug#33179: 26; Doc string of `filter-buffer-substring'
Date: Sat, 27 Oct 2018 14:35:36 -0700 (PDT)

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

Message #26 received at 33179 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 33179 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#33179: 26; Doc string of `filter-buffer-substring'
Date: Sat, 27 Oct 2018 17:59:03 -0400

tags 33179 fixed
close 33179 26.2
quit

Drew Adams <drew.adams <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.