changeset 98751:a0e705c1e7f7

(Using Interactive, Interactive Codes): Document `^'. (Interactive Examples): Show an example of `^'. (Key Sequence Input): Document this-command-keys-shift-translated.

--- a/doc/lispref/commands.texi	Wed Oct 15 15:32:21 2008 +0000
+++ b/doc/lispref/commands.texi	Wed Oct 15 16:47:35 2008 +0000
@@ -186,20 +186,31 @@
 
 @cindex @samp{*} in @code{interactive}
 @cindex read-only buffers in interactive
-If the first character in the string is @samp{*}, then an error is
+If @samp{*} appears at the beginning of the string, then an error is
 signaled if the buffer is read-only.
 
 @cindex @samp{@@} in @code{interactive}
 @c Emacs 19 feature
-If the first character in the string is @samp{@@}, and if the key
+If @samp{@@} appears at the beginning of the string, and if the key
 sequence used to invoke the command includes any mouse events, then
 the window associated with the first of those events is selected
 before the command is run.
 
-You can use @samp{*} and @samp{@@} together; the order does not matter.
-Actual reading of arguments is controlled by the rest of the prompt
-string (starting with the first character that is not @samp{*} or
-@samp{@@}).
+@cindex @samp{^} in @code{interactive}
+@cindex shift-selection, and @code{interactive} spec
+If @samp{^} appears at the beginning of the string, and if the command
+was invoked through @dfn{shift-translation}, set the mark and activate
+the region temporarily, or extend an already active region, before the
+command is run.  If the command was invoked without shift-translation,
+and the region is temporarily active, deactivate the region before the
+command is run.  Shift-translation is controlled on the user level by
+@code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU
+Emacs Manual}.
+
+You can use @samp{*}, @samp{@@}, and @code{^} together; the order does
+not matter.  Actual reading of arguments is controlled by the rest of
+the prompt string (starting with the first character that is not
+@samp{*}, @samp{@@}, or @samp{^}).
 
 @item
 It may be a Lisp expression that is not a string; then it should be a
@@ -316,6 +327,13 @@
 Select the window mentioned in the first mouse event in the key
 sequence that invoked this command.  Special.
 
+@item ^
+If the command was invoked through shift-translation, set the mark and
+activate the region temporarily, or extend an already active region,
+before the command is run.  If the command was invoked without
+shift-translation, and the region is temporarily active, deactivate
+the region before the command is run.  Special.
+
 @item a
 A function name (i.e., a symbol satisfying @code{fboundp}).  Existing,
 Completion, Prompt.
@@ -492,7 +510,9 @@
 
 @group
 (defun foo2 (n)             ; @r{@code{foo2} takes one argument,}
-    (interactive "p")       ;   @r{which is the numeric prefix.}
+    (interactive "^p")      ;   @r{which is the numeric prefix.}
+                            ; @r{under @code{shift-select-mode},}
+                            ;   @r{will activate or extend region.}
     (forward-word (* 2 n)))
      @result{} foo2
 @end group
@@ -2214,11 +2234,21 @@
 
 @cindex upper case key sequence
 @cindex downcasing in @code{lookup-key}
+@cindex shift-translation
 If an input character is upper-case (or has the shift modifier) and
 has no key binding, but its lower-case equivalent has one, then
 @code{read-key-sequence} converts the character to lower case.  Note
 that @code{lookup-key} does not perform case conversion in this way.
 
+@vindex this-command-keys-shift-translated
+When reading input results in such a @dfn{shift-translation}, Emacs
+sets the variable @code{this-command-keys-shift-translated} to a
+non-nil value.  Lisp programs can examine this variable if they need
+to modify their behavior when invoked by shift-translated keys.  For
+example, the function @code{handle-shift-selection} examines the value
+of this variable to determine how to activate or deactivate the region
+(@pxref{The Mark, handle-shift-selection}).
+
 The function @code{read-key-sequence} also transforms some mouse events.
 It converts unbound drag events into click events, and discards unbound
 button-down events entirely.  It also reshuffles focus events and