commit bash-20111216 snapshot

doc/bash.1

@@ -5,12 +5,12 @@
 .\"	Case Western Reserve University
 .\"	chet@po.cwru.edu
 .\"
-.\"	Last Change: Wed Dec  7 17:34:07 EST 2011
+.\"	Last Change: Wed Dec 21 20:32:29 EST 2011
 .\"
 .\" bash_builtins, strip all but Built-Ins section
 .if \n(zZ=1 .ig zZ
 .if \n(zY=1 .ig zY
-.TH BASH 1 "2011 December 7" "GNU Bash 4.2"
+.TH BASH 1 "2011 December 21" "GNU Bash 4.2"
 .\"
 .\" There's some problem with having a `@'
 .\" in a tagged paragraph with the BSD man macros.
@@ -1886,6 +1886,7 @@ upon receipt of a
 An array variable from which \fBbash\fP reads the possible completions
 generated by a shell function invoked by the programmable completion
 facility (see \fBProgrammable Completion\fP below).
+Each array element contains one possible completion.
 .TP
 .B EMACS
 If \fBbash\fP finds this variable in the environment when the shell starts
@@ -5908,6 +5909,9 @@ and store the definition.
 .B call\-last\-kbd\-macro (C\-x e)
 Re-execute the last keyboard macro defined, by making the characters
 in the macro appear as if typed at the keyboard.
+.B print\-last\-kbd\-macro ()
+Print the last keyboard macro defined in a format suitable for the
+\fIinputrc\fP file.
 .PD
 .SS Miscellaneous
 .PP
@@ -6117,10 +6121,12 @@ and
 .SM
 .B COMP_CWORD
 variables are also set.
-When the function or command is invoked, the first argument is the
-name of the command whose arguments are being completed, the
-second argument is the word being completed, and the third argument
-is the word preceding the word being completed on the current command line.
+When the function or command is invoked,
+the first argument (\fB$1\fP) is the name of the command whose arguments are
+being completed,
+the second argument (\fB$2\fP) is the word being completed,
+and the third argument (\fB$3\fP) is the word preceding the word being
+completed on the current command line.
 No filtering of the generated completions against the word being completed
 is performed; the function or command has complete freedom in generating
 the matches.
@@ -6131,7 +6137,7 @@ The function may use any of the shell facilities, including the
 It must put the possible completions in the
 .SM
 .B COMPREPLY
-array variable.
+array variable, one per array element.
 .PP
 Next, any command specified with the \fB\-C\fP option is invoked
 in an environment equivalent to command substitution.
@@ -6703,7 +6709,7 @@ returns 0 unless run when job control is disabled or, when run with
 job control enabled, any specified \fIjobspec\fP was not found
 or was started without job control.
 .TP
-\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSV\fP]
+\fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-lpsvPSVX\fP]
 .PD 0
 .TP
 \fBbind\fP [\fB\-m\fP \fIkeymap\fP] [\fB\-q\fP \fIfunction\fP] [\fB\-u\fP \fIfunction\fP] [\fB\-r\fP \fIkeyseq\fP]
@@ -6798,6 +6804,10 @@ or
 .SM
 .BR READLINE_POINT ,
 those new values will be reflected in the editing state.
+.TP
+.B \-X
+List all key sequences bound to shell commands and the associated commands
+in a format that can be reused as input.
 .PD
 .PP
 The return value is 0 unless an unrecognized option is given or an
@@ -7124,6 +7134,12 @@ used as the possible completions.
 \fB\-F\fP \fIfunction\fP
 The shell function \fIfunction\fP is executed in the current shell
 environment.
+When the function is executed,
+the first argument (\fB$1\fP) is the name of the command whose arguments are
+being completed,
+the second argument (\fB$2\fP) is the word being completed,
+and the third argument (\fB$3\fP) is the word preceding the word being
+completed on the current command line.
 When it finishes, the possible completions are retrieved from the value
 of the
 .SM
@@ -8447,8 +8463,9 @@ are supplied, the line read is assigned to the variable
 .SM
 .BR REPLY .
 The return code is zero, unless end-of-file is encountered, \fBread\fP
-times out (in which case the return code is greater than 128), or an
-invalid file descriptor is supplied as the argument to \fB\-u\fP.
+times out (in which case the return code is greater than 128),
+a variable assignment error (such as assigning to a readonly variable) occurs,
+or an invalid file descriptor is supplied as the argument to \fB\-u\fP.
 .RE
 .TP
 \fBreadonly\fP [\fB\-aAf\fP] [\fB\-p\fP] [\fIname\fP[=\fIword\fP] ...]