From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#33167: 26; Doc string of `region-extract-function' Date: Sat, 27 Oct 2018 19:32:45 +0300 Message-ID: <83o9bfmjte.fsf@gnu.org> References: <<2e187b74-9999-4090-96b4-bb13d1f27544@default>> <<831s8bocu3.fsf@gnu.org>> NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1540657933 29917 195.159.176.226 (27 Oct 2018 16:32:13 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sat, 27 Oct 2018 16:32:13 +0000 (UTC) Cc: 33167@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Oct 27 18:32:09 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gGRVM-0007c4-Nk for geb-bug-gnu-emacs@m.gmane.org; Sat, 27 Oct 2018 18:32:04 +0200 Original-Received: from localhost ([::1]:37165 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gGRXS-00079T-LC for geb-bug-gnu-emacs@m.gmane.org; Sat, 27 Oct 2018 12:34:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:41664) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gGRXL-00079D-RH for bug-gnu-emacs@gnu.org; Sat, 27 Oct 2018 12:34:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gGRXG-0008Aj-O0 for bug-gnu-emacs@gnu.org; Sat, 27 Oct 2018 12:34:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:41417) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gGRXG-0008Ad-Jn for bug-gnu-emacs@gnu.org; Sat, 27 Oct 2018 12:34:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1gGRXG-00011d-CW for bug-gnu-emacs@gnu.org; Sat, 27 Oct 2018 12:34:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 27 Oct 2018 16:34:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 33167 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 33167-submit@debbugs.gnu.org id=B33167.15406579863876 (code B ref 33167); Sat, 27 Oct 2018 16:34:02 +0000 Original-Received: (at 33167) by debbugs.gnu.org; 27 Oct 2018 16:33:06 +0000 Original-Received: from localhost ([127.0.0.1]:45675 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gGRWL-00010R-II for submit@debbugs.gnu.org; Sat, 27 Oct 2018 12:33:05 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:59997) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gGRWJ-0000xg-3z for 33167@debbugs.gnu.org; Sat, 27 Oct 2018 12:33:03 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gGRW8-0007cq-PZ for 33167@debbugs.gnu.org; Sat, 27 Oct 2018 12:32:57 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:59144) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gGRW6-0007c9-VS; Sat, 27 Oct 2018 12:32:51 -0400 Original-Received: from [176.228.60.248] (port=4823 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1gGRW5-0002Wj-1H; Sat, 27 Oct 2018 12:32:50 -0400 In-reply-to: (message from Drew Adams on Sat, 27 Oct 2018 08:27:41 -0700 (PDT)) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:151687 Archived-At: > Date: Sat, 27 Oct 2018 08:27:41 -0700 (PDT) > From: Drew Adams > Cc: 33167-done@debbugs.gnu.org > > > > 1. What are the BEG and END args passed to `filter-buffer-substring'? > > > Is BEG the smallest car of any of the zones in the noncontiguous > > > region, and END the largest cdr of any of the zones? > > > > They are the first and the last positions of the region for > > filter-buffer-substring to act upon. That function is not supposed to > > process non-contiguous regions. > > Yes, but where do they come from, for that call? How do they > relate to, or how are they derived from, the noncontiguous > region? Are they point and mark? Something else? That's the > question. It's entirely up to the region-extract-function that handles such regions. The default one doesn't. So I don't see why these questions need to be answered in the doc string of filter-buffer-substring, they don't belong there and would only confuse. > The only arg to the function that is the value of > `region-extract-function` is METHOD. The "region's content" > is presumably the content of the noncontiguous region. And > presumably it is that that is "the content" that is returned > as a string. How is that string derived from the noncontiguous > region? That's the question. It isn't. The region passed to filter-buffer-substring must always be contiguous. > > > 2. `filter-buffer-substring' calls the value of > > > `filter-buffer-substring-function' with the same 3 args. But what > > > can that function do with BEG and END (which are what?)? It's > > > presumably a function that expects to use a single stretch of > > > buffer text from BEG to END. But here we're talking about a > > > noncontiguous > > > > No, we are talking about contiguous regions when this function is > > concerned. > > Sorry, but I don't understand. What contiguous regions > are we talking about? How/where in this doc did you > get from a noncontiguous region to contiguous regions? That depends on the implementation of region-extract-function that supports non-contiguous regions: it must somehow call filter-buffer-substring-function in a way that this function gets only contiguous regions of text. So this question cannot be answered in the doc string of filter-buffer-substring-function. > I haven't see your update to the doc string, but so far > your description here doesn't give the impression that > these questions have been cleared up. Well, I suggest to read that first: http://git.savannah.gnu.org/cgit/emacs.git/commit/?h=emacs-26&id=df64da8eb845c9f07ee93bfbf28af41a01a2e83f > > > 3. The 3rd arg to `filter-buffer-substring' just deletes the region > > > from BEG to END if it is non-nil, so it seems like passing that > > > non-nil 3rd arg is useless, as the region gets deleted anyway, by > > > `region-extract-function'. > > > > Not sure what is the problem here. > > Not sure what you're saying. You say that passing the 3rd arg is "useless", and I don't understand why. > Are you saying that I'm wrong that a non-nil 3rd arg just deletes > the region? Or are you saying that I'm wrong that that non-nil 3rd > arg is useless because the region is deleted anyway? I'm saying that I don't understand what you wanted to say here. At all. > > > 4. The use of `filter-buffer-substring' is also unclear. It is passed > > > BEG and END (and METHOD, but see #3, above). And it filters the > > > buffer text between BEG and END. But see #1 above - are BEG and > > > END buffer positions that make sense for the whole region text? > > > Just what happens here? > > > > See above. It is not the job of filter-buffer-substring to DTRT when > > the region is non-contiguous, it is the job of its callers. See > > rect.el for one example. > > See above. See above. > What are BEG and END that get passed to it? The doc string already tells that: the beginning and the end of the region to be filtered. > The doc should be able to make clear what the behavior > is, without someone needing to investigate the code of > rect.el. It does. What it does NOT have to do is tell how one would use this function while implementing a replacement for the default region-extract-function that can handle non-contiguous regions. > Plus, noncontiguous regions are more general than rectangles. Exactly. So each such implementation has to figure out how to call filter-buffer-substring in a way that makes sense and passes only contiguous regions to filter-buffer-substring. > The doc should make clear what happens in the general case. The doc string of filter-buffer-substring needs to tell what that function does. And it does precisely that. > The doc should make clear in general terms what extracting > a noncontiguous region is about, and just what the value of > `region-extract-function' does: what its arguments are and > what its return value is (as a function of those arguments). It does now, please see the new doc string. > I did what you suggest before filing the bug report: > checked all of the existing occurrences. I felt that > the doc is wrong wrt what really happens, and I feel > that there's a need for a general description of this > variable which helps. The doc string was indeed incomplete before my changes; it is IMO complete now. > > > Or is what happens perhaps that EACH element of the noncontiguous > > > region, that is, each zone (BEG . END) of the list ((BEG1 . > > > END1) ...) gets filtered by `filter-buffer-substring', passing > > > its BEG END and METHOD > > > > Yes! > > Then please say that in the doc. NO! Because that's just one possible implementation, for one possible kind of non-contiguous regions. > > > - so that a mapcar is applied? > > > > Not literally, but the result is a list, yes. > > If you haven't already done so, please say that in the doc. If you haven't already done so, please read the new doc string. I think I covered everything that should be covered.