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: Sun, 02 Oct 2016 19:53:45 -0500 Message-ID: <87twcutfqe.fsf@red-bean.com> References: <874m5lr92d.fsf@red-bean.com> <83eg4p9hqk.fsf@gnu.org> <87inu1ghud.fsf@red-bean.com> <83y42x7yud.fsf@gnu.org> <87poo8g2zi.fsf@red-bean.com> <7abf7a00-3f17-4ef6-bfbd-0f5df4e7acd6@default> Reply-To: Karl Fogel NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1475456089 10521 195.159.176.226 (3 Oct 2016 00:54:49 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 3 Oct 2016 00:54:49 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.50 (gnu/linux) Cc: Eli Zaretskii , emacs-devel@gnu.org To: Drew Adams Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 03 02:54:45 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 1bqrWf-00018c-GS for ged-emacs-devel@m.gmane.org; Mon, 03 Oct 2016 02:54:37 +0200 Original-Received: from localhost ([::1]:33201 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bqrWe-0003N7-1F for ged-emacs-devel@m.gmane.org; Sun, 02 Oct 2016 20:54:36 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34477) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bqrWW-0003Mz-Ja for emacs-devel@gnu.org; Sun, 02 Oct 2016 20:54:29 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bqrWS-00010w-DH for emacs-devel@gnu.org; Sun, 02 Oct 2016 20:54:27 -0400 Original-Received: from mail-it0-x22c.google.com ([2607:f8b0:4001:c0b::22c]:35001) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bqrWS-00010N-6C; Sun, 02 Oct 2016 20:54:24 -0400 Original-Received: by mail-it0-x22c.google.com with SMTP id r192so103199835ita.0; Sun, 02 Oct 2016 17:54:23 -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=8J+oPmQK9np54IZG60DJb39MF2DMZZLJCyGoUIFuJGM=; b=AvoEa1BeM8LqOobvEDdwZlVdZnENVg+6xInv9tw961B3Hf1EtTWjVX0wSXJTk6ujtN 2OsW12aFDlJn/gKOlIuhqDO6jXWSu/2mPCKVrR2GR3+GZHWmxW9OkfkDY2vOtgAayG6c R1aRwxAT2Hbaba6AOBF4fCOe5zcCgA2MOqfBoDatG1HJmOkhCG6gyMi7LSYDVsxoH1Cz D42SnMx2UfJoGGMS/qXGJRNu+szWULTA5FqTzitYJlTnNqKM0Ivazyr07Yhfac1CV3lw wMZzrVxWh6xx4nlsRx4q1r56vx0MSOdqHLF+mCVh6dvQkN7L9BfYNDeZhI2TqZQ53sXC 8HJA== 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=8J+oPmQK9np54IZG60DJb39MF2DMZZLJCyGoUIFuJGM=; b=IFRtCmeUd4ZS9nvl9wXL8/XXqnA+XXDcdqPlUOAvIPM5fScnLZfcUSsvL1el0tnpWW CRhpCP4vLLKu3oph33Q5fTfAbK/Q6bqibYrxWMVRAg1bgkNH2WunKY9iDBLTJI/uxW6A 87VvZUBWKJwZ6jaw+3dMG0KMw605zJicxr81RS+MjGbcqidY84wPLLuWkugoAYm8qJMW 3uLJ3DgkVgtg3NYf8SC8F0A2oSYwjREgyO9b0soI7sG6K/4ETrHVJFFSAtbL0hkyq1tu 0BSl82gqIAcqribIK4eAFFayr6nLdP9b7xuRNHuEDQcqfeXMJdxSyqx90sQeVQLAqjBB Th+Q== X-Gm-Message-State: AA6/9RkYQSLUnVubFC04og73goCHcj7WKE0hCXGTkhTjuo6kbfiQVoTCAj5g5s4qaSygOQ== X-Received: by 10.36.48.149 with SMTP id q143mr14259937itq.48.1475456030527; Sun, 02 Oct 2016 17:53:50 -0700 (PDT) Original-Received: from klen ([166.175.190.180]) by smtp.gmail.com with ESMTPSA id 66sm6691809itz.9.2016.10.02.17.53.48 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sun, 02 Oct 2016 17:53:49 -0700 (PDT) In-Reply-To: <7abf7a00-3f17-4ef6-bfbd-0f5df4e7acd6@default> (Drew Adams's message of "Mon, 12 Sep 2016 15:54:36 -0700 (PDT)") X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2607:f8b0:4001:c0b::22c 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:207944 Archived-At: This is done now (commit 8cd975ceb). Drew, thanks for pointing out bug #286; I took care of that doc issue in the same commit. I can't (re)close the bug, because it was closed earlier as "wontfix" and it now says "Bug is archived. No further changes may be made." However, I agree with your reasoning in the bug report, and infer similar agreement from others' responses in this mailing list thread. Best regards, -Karl Drew Adams 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. > >Bell ringing... > >http://debbugs.gnu.org/cgi/bugreport.cgi?bug=286