* bug#33179: 26; Doc string of `filter-buffer-substring'
[not found] ` <<83in1nmdae.fsf@gnu.org>
@ 2018-10-27 19:10 ` Drew Adams
2018-10-27 19:25 ` Eli Zaretskii
2018-10-27 19:32 ` Noam Postavsky
0 siblings, 2 replies; 8+ messages in thread
From: Drew Adams @ 2018-10-27 19:10 UTC (permalink / raw)
To: Eli Zaretskii, Drew Adams; +Cc: 33179
> > 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.
^ permalink raw reply [flat|nested] 8+ messages in thread* bug#33179: 26; Doc string of `filter-buffer-substring'
2018-10-27 19:10 ` bug#33179: 26; Doc string of `filter-buffer-substring' Drew Adams
@ 2018-10-27 19:25 ` Eli Zaretskii
2018-10-27 19:32 ` Noam Postavsky
1 sibling, 0 replies; 8+ messages in thread
From: Eli Zaretskii @ 2018-10-27 19:25 UTC (permalink / raw)
To: Drew Adams; +Cc: 33179
> 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.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#33179: 26; Doc string of `filter-buffer-substring'
2018-10-27 19:10 ` bug#33179: 26; Doc string of `filter-buffer-substring' Drew Adams
2018-10-27 19:25 ` Eli Zaretskii
@ 2018-10-27 19:32 ` Noam Postavsky
2018-10-27 19:38 ` Eli Zaretskii
1 sibling, 1 reply; 8+ messages in thread
From: Noam Postavsky @ 2018-10-27 19:32 UTC (permalink / raw)
To: Drew Adams; +Cc: 33179
[-- 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
^ permalink raw reply related [flat|nested] 8+ messages in thread
* bug#33179: 26; Doc string of `filter-buffer-substring'
2018-10-27 19:32 ` Noam Postavsky
@ 2018-10-27 19:38 ` Eli Zaretskii
0 siblings, 0 replies; 8+ messages in thread
From: Eli Zaretskii @ 2018-10-27 19:38 UTC (permalink / raw)
To: Noam Postavsky; +Cc: 33179
> 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.
^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#33179: 26; Doc string of `filter-buffer-substring'
@ 2018-10-27 17:24 Drew Adams
2018-10-27 18:53 ` Eli Zaretskii
0 siblings, 1 reply; 8+ messages in thread
From: Drew Adams @ 2018-10-27 17:24 UTC (permalink / raw)
To: 33179
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''
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2018-10-27 21:59 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <<08b6c241-7972-48e3-b354-95b6cb50fe52@default>
[not found] ` <<83in1nmdae.fsf@gnu.org>
2018-10-27 19:10 ` bug#33179: 26; Doc string of `filter-buffer-substring' Drew Adams
2018-10-27 19:25 ` Eli Zaretskii
2018-10-27 19:32 ` Noam Postavsky
2018-10-27 19:38 ` Eli Zaretskii
2018-10-27 17:24 Drew Adams
2018-10-27 18:53 ` Eli Zaretskii
[not found] ` <<8c1ed257-be78-4355-84a1-572cfa1d3af6@default>
[not found] ` <<87h8h7jicd.fsf@gmail.com>
[not found] ` <<83d0rvmb7r.fsf@gnu.org>
2018-10-27 21:35 ` Drew Adams
2018-10-27 21:59 ` Noam Postavsky
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).