bug#6797: documentation: `insert-for-yank-1' needs refilled

bug#6797: documentation: `insert-for-yank-1' needs refilled

[MON KEY]

`insert-for-yank-1' needs refilled

problem current through Bzr-100972



*** /ediff52068uN	2010-08-04 16:11:00.078669691 -0400
---lisp/subr.el	2010-08-04 15:50:02.478794136 -0400
***************
*** 2469,2497 ****
    (insert-for-yank-1 string))

  (defun insert-for-yank-1 (string)
!   "Insert STRING at point, stripping some text properties.

  Strip text properties from the inserted text according to
  `yank-excluded-properties'.  Otherwise just like (insert STRING).

! If STRING has a non-nil `yank-handler' property on the first character,
  the normal insert behavior is modified in various ways.  The value of
! the yank-handler property must be a list with one to four elements
! with the following format:  (FUNCTION PARAM NOEXCLUDE UNDO).
! When FUNCTION is present and non-nil, it is called instead of `insert'
!  to insert the string.  FUNCTION takes one argument--the object to insert.
! If PARAM is present and non-nil, it replaces STRING as the object
!  passed to FUNCTION (or `insert'); for example, if FUNCTION is
!  `yank-rectangle', PARAM may be a list of strings to insert as a
!  rectangle.
! If NOEXCLUDE is present and non-nil, the normal removal of the
!  yank-excluded-properties is not performed; instead FUNCTION is
!  responsible for removing those properties.  This may be necessary
!  if FUNCTION adjusts point before or after inserting the object.
! If UNDO is present and non-nil, it is a function that will be called
!  by `yank-pop' to undo the insertion of the current object.  It is
!  called with two arguments, the start and end of the current region.
!  FUNCTION may set `yank-undo-function' to override the UNDO value."
    (let* ((handler (and (stringp string)
  		       (get-text-property 0 'yank-handler string)))
  	 (param (or (nth 1 handler) string))
--- 2469,2503 ----
    (insert-for-yank-1 string))

  (defun insert-for-yank-1 (string)
! "Insert STRING at point, stripping some text properties.

  Strip text properties from the inserted text according to
  `yank-excluded-properties'.  Otherwise just like (insert STRING).

! when STRING has a non-nil `yank-handler' property on the first character,
  the normal insert behavior is modified in various ways.  The value of
! the yank-handler property is a list with one to four elements
! of the following format:  (FUNCTION PARAM NOEXCLUDE UNDO).
!
! When FUNCTION is present and non-nil, it is a function called with one
! argument -- an object to insert, and is called instead of `insert' when
! inserting STRING.
!
! When PARAM is present and non-nil, it replaces STRING as the object
! passed to FUNCTION (or `insert'). For example, if FUNCTION is
! `yank-rectangle', PARAM may be a list of strings to insert as a
! rectangle.
!
! When NOEXCLUDE is present and non-nil, normal removal of
! yank-excluded-properties is not performed; instead text-property filtering
! is deferred to FUNCTION which becomes responsible for property removal prior
! to object insertion.  This may be necessary when FUNCTION adjusts point
! either before or after object insertion.
!
! When UNDO is present and non-nil, it is a function called
! by `yank-pop' to undo the insertion of the current object.  It is
! called with two arguments, the start and end of the current region.
! FUNCTION may set `yank-undo-function' to override the UNDO value."
    (let* ((handler (and (stringp string)
  		       (get-text-property 0 'yank-handler string)))
  	 (param (or (nth 1 handler) string))

bug#6797: documentation: `insert-for-yank-1' needs refilled

[Chong Yidong]

Closing the bug; see comment in 6821.