From: Karl Fogel <kfogel@red-bean.com>
To: Drew Adams <drew.adams@oracle.com>
Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
Subject: Re: Question about intended behavior of 'insert-for-yank-1'.
Date: Sun, 02 Oct 2016 19:53:45 -0500 [thread overview]
Message-ID: <87twcutfqe.fsf@red-bean.com> (raw)
In-Reply-To: <7abf7a00-3f17-4ef6-bfbd-0f5df4e7acd6@default> (Drew Adams's message of "Mon, 12 Sep 2016 15:54:36 -0700 (PDT)")
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 <drew.adams@oracle.com> 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
next prev parent reply other threads:[~2016-10-03 0:53 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-09-12 5:17 Question about intended behavior of 'insert-for-yank-1' Karl Fogel
2016-09-12 16:59 ` Eli Zaretskii
2016-09-12 17:15 ` Karl Fogel
2016-09-12 18:32 ` Eli Zaretskii
2016-09-12 22:36 ` Karl Fogel
2016-09-12 22:54 ` Drew Adams
2016-09-12 23:08 ` Karl Fogel
2016-10-03 0:53 ` Karl Fogel [this message]
2016-10-03 3:17 ` Noam Postavsky
2016-10-03 6:53 ` Eli Zaretskii
2016-10-03 19:21 ` Karl Fogel
2016-10-03 6:44 ` Eli Zaretskii
2016-10-03 19:17 ` Karl Fogel
2016-10-04 6:03 ` Eli Zaretskii
2016-10-04 17:40 ` Karl Fogel
2016-10-04 18:19 ` Eli Zaretskii
2016-10-04 20:16 ` Davis Herring
2016-10-04 21:04 ` Karl Fogel
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87twcutfqe.fsf@red-bean.com \
--to=kfogel@red-bean.com \
--cc=drew.adams@oracle.com \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.