From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Karl Fogel Newsgroups: gmane.emacs.devel Subject: Re: Question about intended behavior of 'insert-for-yank-1'. Date: Mon, 12 Sep 2016 17:36:17 -0500 Message-ID: <87poo8g2zi.fsf@red-bean.com> References: <874m5lr92d.fsf@red-bean.com> <83eg4p9hqk.fsf@gnu.org> <87inu1ghud.fsf@red-bean.com> <83y42x7yud.fsf@gnu.org> Reply-To: Karl Fogel NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1473719804 6564 195.159.176.226 (12 Sep 2016 22:36:44 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 12 Sep 2016 22:36:44 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.50 (gnu/linux) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Sep 13 00:36:40 2016 Return-path: Envelope-to: ged-emacs-devel@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 1bjZq4-0000WB-ER for ged-emacs-devel@m.gmane.org; Tue, 13 Sep 2016 00:36:32 +0200 Original-Received: from localhost ([::1]:45492 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bjZq2-0004Kd-A2 for ged-emacs-devel@m.gmane.org; Mon, 12 Sep 2016 18:36:30 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42063) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bjZpw-0004KW-E7 for emacs-devel@gnu.org; Mon, 12 Sep 2016 18:36:25 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bjZps-0002gs-7K for emacs-devel@gnu.org; Mon, 12 Sep 2016 18:36:24 -0400 Original-Received: from mail-it0-x22e.google.com ([2607:f8b0:4001:c0b::22e]:36022) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bjZps-0002gW-2G; Mon, 12 Sep 2016 18:36:20 -0400 Original-Received: by mail-it0-x22e.google.com with SMTP id o3so26679975ita.1; Mon, 12 Sep 2016 15:36:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:from:to:cc:subject:references:reply-to:date:in-reply-to :message-id:user-agent:mime-version; bh=Ggidr8NHxck+knvP+dQEB5ilHPL4aq8aB7kf2iEzIWY=; b=yq2XIjLPKS300SJ7eP0FZXFGA+MVi7viQp6PKFzGsbPOn9JInmBEGWYFLH6iH6VO+v C3LgqfpQG9QBaOIhbyptQDv6jPj4A+AUDlWcWJsEr8lBzOujbg1RcXfe+Fzl5piZCvdO H+EA14t+7G+FGVk1OesYeM8tyr4NZHOP2GXjU+N6x3LzfqASqyeakDUS9kamzvXDbzqu ALEfOWeTlf/3GpTvGizsyenRFwKyfjitx/VrnytFjKzOBatKdtJn48ltuCJTwziPasRs W+WscvbVHAjcJBNh+XCk9CGJZic5zXcZOHpQAY2aQKAtBrw22yhlDF2NN3i0v/TeKceQ d09g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:sender:from:to:cc:subject:references:reply-to :date:in-reply-to:message-id:user-agent:mime-version; bh=Ggidr8NHxck+knvP+dQEB5ilHPL4aq8aB7kf2iEzIWY=; b=gjAXajCJNn3K4tvogXcpCg8/mncOFNaKDR/ug51VtnBxnJ4+eaFEiIJQPnfm45zyEZ m+Di8tEqvILRrfD4HJulDOu8mjMUrvIGvVw3rBwhVmb7OlS8VyOSnzUcgNn6m71ZczY9 kRDOzYOfcLNIrcoU8027wpSdof6+Z1BDabEmJBgWfmewOo+bmRtT963Hih/M4dg5/+Zs 0MDkJ5YEId9VQr4rZPTqRf036p9OLikhc4jfg2s//9G9favzONaytiwc4AyxOe5Mwryn 6i3WwCiCouyT5BdspIXAETgzjbg4uT1TEBZ+9NjAuP2EOV+aSGxKFWccllNiULgDHk+v L8Tg== X-Gm-Message-State: AE9vXwNrsuMDiNF7nNjC2/vY1zEdJyrOdFew8QUJimgaBAFshXFedOoYkjv7tnr9xK9vwQ== X-Received: by 10.157.50.203 with SMTP id u69mr25604507otb.157.1473719779197; Mon, 12 Sep 2016 15:36:19 -0700 (PDT) Original-Received: from kwork (74-92-190-114-Illinois.hfc.comcastbusiness.net. [74.92.190.114]) by smtp.gmail.com with ESMTPSA id r94sm2276340ioi.2.2016.09.12.15.36.17 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Mon, 12 Sep 2016 15:36:17 -0700 (PDT) In-Reply-To: <83y42x7yud.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 12 Sep 2016 21:32:58 +0300") X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2607:f8b0:4001:c0b::22e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:207403 Archived-At: Eli Zaretskii writes: >> Thanks, Eli. Yes, that's true, but note that the doc string for >> `insert-for-yank' just refers the reader to `insert-for-yank-1' for >> details. The only doc string where the STRING-passing behavior is >> discussed is the doc string of `insert-for-yank-1', and that doc >> string indicates, or strongly implies, that the entirety of STRING >> is passed (which it isn't). > >Ah, so this is about the doc string of insert-for-yank, not its >subroutine. I think that's fair, yes. It's about the combination of the two doc strings: right now, the `insert-for-yank' doc string just refers the reader to `insert-for-yank-1' for all the interesting stuff. If your point is that solving this documentation bug involves changing the documentation of `insert-for-yank' more than that of `insert-for-yank-1' (and that the latter might not changing at all), that makes sense, and I thank you for pointing out the real source of the problem. >I agree that the doc string of insert-for-yank should describe what it >does. What it says now hardly qualifies as documentation, and >referring to an internal subroutine for that is, shall we say, >suboptimal ;-) Really, stepping back from the trees to see the forest, that should have been my first reaction :-). >Feel free to improve the doc string of insert-for-yank. Will do. While I don't see any outright errors in the doc string of `insert-for-yank-1', IMHO it should more clearly document that STRING is the default argument to FUNCTION, so I may also fix that. Thanks, Eli. -Karl