3 files changed, 23 insertions, 5 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index fa5aac6e9ec..345e69e6989 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,10 @@
+2011-10-13  Chong Yidong  <cyd@stupidchicken.com>
+
+        * text.texi (Yanking): Document yank-excluded-properties.
+
+        * package.texi (Packaging Basics): The commentary should say how
+        to begin using the package.
+
 2011-10-11  Martin Rudalics  <rudalics@gmx.at>
 
         * windows.texi (Deleting Windows): Mention which window gets
diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi
index 62fbc2a9a07..5533f8ab5fa 100644
--- a/doc/lispref/package.texi
+++ b/doc/lispref/package.texi
@@ -63,7 +63,8 @@ should occupy a single line, ideally in 36 characters or less.
 This is shown in the buffer created by @kbd{C-h P}
 (@code{describe-package}), following the package's brief description
 and installation status.  It normally spans multiple lines, and should
-fully describe the package and its capabilities.
+fully describe the package's capabilities and how to begin using it
+once it is installed.
 
 @item Dependencies
 A list of other packages (possibly including minimal acceptable
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 2348e3706dc..3a081dddc61 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -907,10 +907,11 @@ text that they copy into the buffer.
 
 @defun insert-for-yank string
 This function normally works like @code{insert} except that it doesn't
-insert the text properties in the @code{yank-excluded-properties}
-list.  However, if any part of @var{string} has a non-@code{nil}
-@code{yank-handler} text property, that property can do various
-special processing on that part of the text being inserted.
+insert the text properties (@pxref{Text Properties}) in the list
+variable @code{yank-excluded-properties}.  However, if any part of
+@var{string} has a non-@code{nil} @code{yank-handler} text property,
+that property can do various special processing on that part of the
+text being inserted.
 @end defun
 
 @defun insert-buffer-substring-as-yank buf &optional start end
@@ -958,6 +959,15 @@ region.  @var{function} can set @code{yank-undo-function} to override
 the @var{undo} value.
 @end table
 
+@cindex yanking and text properties
+@defopt yank-excluded-properties
+Yanking discards certain text properties from the yanked text, as
+described above.  The value of this variable is the list of properties
+to discard.  Its default value contains properties that might lead to
+annoying results, such as causing the text to respond to the mouse or
+specifying key bindings.
+@end defopt
+
 @node Yank Commands
 @comment  node-name,  next,  previous,  up
 @subsection Functions for Yanking