From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#20395: 24.3; Documentation for `replace-regexp-in-string' Date: Tue, 21 Apr 2015 18:00:01 +0300 Message-ID: <83383t5xxq.fsf@gnu.org> References: <21814.8037.812473.636136@home.barzilay.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1429628484 20990 80.91.229.3 (21 Apr 2015 15:01:24 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 21 Apr 2015 15:01:24 +0000 (UTC) Cc: 20395@debbugs.gnu.org To: Eli Barzilay Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Apr 21 17:01:16 2015 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1YkZfn-0006Kv-Oe for geb-bug-gnu-emacs@m.gmane.org; Tue, 21 Apr 2015 17:01:15 +0200 Original-Received: from localhost ([::1]:58981 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YkZfn-0006En-5R for geb-bug-gnu-emacs@m.gmane.org; Tue, 21 Apr 2015 11:01:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:43733) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YkZfg-0006Eb-8e for bug-gnu-emacs@gnu.org; Tue, 21 Apr 2015 11:01:12 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YkZfb-0005Md-5x for bug-gnu-emacs@gnu.org; Tue, 21 Apr 2015 11:01:08 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:45635) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YkZfb-0005MT-2G for bug-gnu-emacs@gnu.org; Tue, 21 Apr 2015 11:01:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1YkZfa-0008Ml-JJ for bug-gnu-emacs@gnu.org; Tue, 21 Apr 2015 11:01: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: Tue, 21 Apr 2015 15:01:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 20395 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 20395-submit@debbugs.gnu.org id=B20395.142962841732055 (code B ref 20395); Tue, 21 Apr 2015 15:01:02 +0000 Original-Received: (at 20395) by debbugs.gnu.org; 21 Apr 2015 15:00:17 +0000 Original-Received: from localhost ([127.0.0.1]:35410 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YkZeq-0008Km-21 for submit@debbugs.gnu.org; Tue, 21 Apr 2015 11:00:16 -0400 Original-Received: from mtaout20.012.net.il ([80.179.55.166]:40287) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1YkZem-0008KO-6n for 20395@debbugs.gnu.org; Tue, 21 Apr 2015 11:00:14 -0400 Original-Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0NN500M00W6D3K00@a-mtaout20.012.net.il> for 20395@debbugs.gnu.org; Tue, 21 Apr 2015 18:00:05 +0300 (IDT) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NN500LQNWC5RSA0@a-mtaout20.012.net.il>; Tue, 21 Apr 2015 18:00:05 +0300 (IDT) In-reply-to: <21814.8037.812473.636136@home.barzilay.org> X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:101822 Archived-At: > From: Eli Barzilay > Date: Tue, 21 Apr 2015 05:59:01 -0400 > > When REP is called, the match data are the result of matching > REGEXP against a substring of STRING. > > and IMO that "a substring" is very subtle and easy to miss. I then > looked at the code, and at least in its current form, I saw that I > could do this instead: > > (let ((text "foo\nbar\nbaz\n") (r "*")) > (replace-regexp-in-string > "\n\\(.\\)" > (lambda (s) (concat "\n" r (match-string 1 s))) > text)) > > So I think that it would be really good if this was made explicit in > the documentation, better with an example. Something like > > When REP is called, the match data are the result of matching > REGEXP against only the currently matched substring of STRING. > For example, (lambda (s) (concat "<" (match-string 1 s) ">")) as > REP is equivalent to "<\\1>". Thanks. However, I wonder whether your suggested change is really enough of an improvement. AFAIU, the main problem with the existing doc string is that it doesn't explain _which_ substring is being alluded to here, it only hints on the answer. And your suggested change also leaves that part unexplained, leaving it to the reader to glean that from the fact that 'concat' is being used. So I think it would be good to come up with text that actually makes that part clear. WDYT?