all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Drew Adams <drew.adams@oracle.com>
To: Karl Fogel <kfogel@red-bean.com>, Eli Zaretskii <eliz@gnu.org>
Cc: emacs-devel@gnu.org
Subject: RE: Question about intended behavior of 'insert-for-yank-1'.
Date: Mon, 12 Sep 2016 15:54:36 -0700 (PDT)	[thread overview]
Message-ID: <7abf7a00-3f17-4ef6-bfbd-0f5df4e7acd6@default> (raw)
In-Reply-To: <87poo8g2zi.fsf@red-bean.com>

> >> 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



  reply	other threads:[~2016-09-12 22:54 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 [this message]
2016-09-12 23:08           ` Karl Fogel
2016-10-03  0:53           ` Karl Fogel
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=7abf7a00-3f17-4ef6-bfbd-0f5df4e7acd6@default \
    --to=drew.adams@oracle.com \
    --cc=eliz@gnu.org \
    --cc=emacs-devel@gnu.org \
    --cc=kfogel@red-bean.com \
    /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.