Update to bash-4.1

1 files changed, 176 insertions, 19 deletions

diff --git a/lib/readline/doc/rluser.texi b/lib/readline/doc/rluser.texi
index 5c6467a..519c0de 100644
--- a/lib/readline/doc/rluser.texi
+++ b/lib/readline/doc/rluser.texi
@@ -1,7 +1,6 @@
 @comment %**start of header (This is for running Texinfo on a region.)
 @setfilename rluser.info
 @comment %**end of header (This is for running Texinfo on a region.)
-@setchapternewpage odd
 
 @ignore
 This file documents the end user interface to the GNU command line
@@ -10,7 +9,7 @@ use these features.  There is a document entitled "readline.texinfo"
 which contains both end-user and programmer documentation for the
 GNU Readline Library.
 
-Copyright (C) 1988-2006 Free Software Foundation, Inc.
+Copyright (C) 1988--2009 Free Software Foundation, Inc.
 
 Authored by Brian Fox and Chet Ramey.
 
@@ -48,6 +47,16 @@ command line editing interface.
 @ifset BashFeatures
 Command line editing is provided by the Readline library, which is
 used by several different programs, including Bash.
+Command line editing is enabled by default when using an interactive shell,
+unless the @option{--noediting} option is supplied at shell invocation.
+Line editing is also used when using the @option{-e} option to the
+@code{read} builtin command (@pxref{Bash Builtins}).
+By default, the line editing commands are similar to those of emacs.
+A vi-style line editing interface is also available.
+Line editing can be enabled at any time using the @option{-o emacs} or
+@option{-o vi} options to the @code{set} builtin command
+(@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or 
+@option{+o vi} options to @code{set}.
 @end ifset
 
 @menu
@@ -427,6 +436,13 @@ If set to @samp{on}, Readline performs filename matching and completion
 in a case-insensitive fashion.
 The default value is @samp{off}.
 
+@item completion-prefix-display-length
+@vindex completion-prefix-display-length
+The length in characters of the common prefix of a list of possible
+completions that is displayed without modification.  When set to a
+value greater than zero, common prefixes longer than this value are
+replaced with an ellipsis when displaying possible completions.
+
 @item completion-query-items
 @vindex completion-query-items
 The number of possible completions that determines when the user is
@@ -458,12 +474,23 @@ key bindings is used.  By default, Readline starts up in Emacs editing
 mode, where the keystrokes are most similar to Emacs.  This variable can be
 set to either @samp{emacs} or @samp{vi}.
 
+@item echo-control-characters
+When set to @samp{on}, on operating systems that indicate they support it,
+readline echoes a character corresponding to a signal generated from the
+keyboard.  The default is @samp{on}.
+
 @item enable-keypad
 @vindex enable-keypad
 When set to @samp{on}, Readline will try to enable the application
 keypad when it is called.  Some systems need this to enable the
 arrow keys.  The default is @samp{off}.
 
+@item enable-meta-key
+When set to @samp{on}, Readline will try to enable any meta modifier
+key the terminal claims to support when it is called.  On many terminals,
+the meta key is used to send eight-bit characters.
+The default is @samp{on}.
+
 @item expand-tilde
 @vindex expand-tilde
 If set to @samp{on}, tilde expansion is performed when Readline
@@ -471,10 +498,16 @@ attempts word completion.  The default is @samp{off}.
 
 @item history-preserve-point
 @vindex history-preserve-point
-If set to @samp{on}, the history code attempts to place point at the
+If set to @samp{on}, the history code attempts to place the point (the
+current cursor position) at the
 same location on each history line retrieved with @code{previous-history}
 or @code{next-history}.  The default is @samp{off}.
 
+@item history-size
+@vindex history-size
+Set the maximum number of history entries saved in the history list.  If
+set to zero, the number of entries in the history list is not limited.
+
 @item horizontal-scroll-mode
 @vindex horizontal-scroll-mode
 This variable can be set to either @samp{on} or @samp{off}.  Setting it
@@ -558,6 +591,13 @@ If set to @samp{on}, Readline will display completions with matches
 sorted horizontally in alphabetical order, rather than down the screen.
 The default is @samp{off}.
 
+@item revert-all-at-newline
+@vindex revert-all-at-newline
+If set to @samp{on}, Readline will undo all changes to history lines
+before returning when @code{accept-line} is executed.  By default,
+history lines may be modified and retain individual undo lists across
+calls to @code{readline}.  The default is @samp{off}.
+
 @item show-all-if-ambiguous
 @vindex show-all-if-ambiguous
 This alters the default behavior of the completion functions.  If
@@ -577,6 +617,20 @@ a common prefix) cause the matches to be listed immediately instead
 of ringing the bell.
 The default value is @samp{off}.
 
+@item skip-completed-text
+@vindex skip-completed-text
+If set to @samp{on}, this alters the default completion behavior when
+inserting a single match into the line.  It's only active when
+performing completion in the middle of a word.  If enabled, readline
+does not insert characters from the completion that match characters
+after point in the word being completed, so portions of the word
+following the cursor are not duplicated.
+For instance, if this is enabled, attempting completion when the cursor
+is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile}
+rather than @samp{Makefilefile}, assuming there is a single possible
+completion.
+The default value is @samp{off}.
+
 @item visible-stats
 @vindex visible-stats
 If set to @samp{on}, a character denoting a file's type
@@ -941,12 +995,22 @@ Move forward a character.
 Move back a character.
 
 @item forward-word (M-f)
-Move forward to the end of the next word.  Words are composed of
-letters and digits.
+Move forward to the end of the next word.
+Words are composed of letters and digits.
 
 @item backward-word (M-b)
-Move back to the start of the current or previous word.  Words are
-composed of letters and digits.
+Move back to the start of the current or previous word.
+Words are composed of letters and digits.
+
+@ifset BashFeatures
+@item shell-forward-word ()
+Move forward to the end of the next word.
+Words are delimited by non-quoted shell metacharacters.
+
+@item shell-backward-word ()
+Move back to the start of the current or previous word.
+Words are delimited by non-quoted shell metacharacters.
+@end ifset
 
 @item clear-screen (C-l)
 Clear the screen and redraw the current line,
@@ -1142,6 +1206,17 @@ Word boundaries are the same as @code{forward-word}.
 Kill the word behind point.
 Word boundaries are the same as @code{backward-word}.
 
+@ifset BashFeatures
+@item shell-kill-word ()
+Kill from point to the end of the current word, or if between
+words, to the end of the next word.
+Word boundaries are the same as @code{shell-forward-word}.
+
+@item backward-kill-word ()
+Kill the word behind point.
+Word boundaries are the same as @code{shell-backward-word}.
+@end ifset
+
 @item unix-word-rubout (C-w)
 Kill the word behind point, using white space as a word boundary.
 The killed text is saved on the kill-ring.
@@ -1242,6 +1317,11 @@ through the list.
 This command is intended to be bound to @key{TAB}, but is unbound
 by default.
 
+@item menu-complete-backward ()
+Identical to @code{menu-complete}, but moves backward through the list
+of possible completions, as if @code{menu-complete} had been given a
+negative argument.
+
 @item delete-char-or-list ()
 Deletes the character under the cursor if not at the beginning or
 end of the line (like @code{delete-char}).
@@ -1297,6 +1377,11 @@ Attempt completion on the text before point, comparing
 the text against lines from the history list for possible
 completion matches.
 
+@item dabbrev-expand ()
+Attempt menu completion on the text before point, comparing
+the text against lines from the history list for possible
+completion matches.
+
 @item complete-into-braces (M-@{)
 Perform filename completion and insert the list of possible completions
 enclosed within braces so the list is available to the shell
@@ -1376,6 +1461,15 @@ A character is read and point is moved to the previous occurrence
 of that character.  A negative count searches for subsequent
 occurrences.
 
+@item skip-csi-sequence ()
+Read enough characters to consume a multi-key sequence such as those
+defined for keys like Home and End.  Such sequences begin with a
+Control Sequence Indicator (CSI), usually ESC-[.  If this sequence is
+bound to "\e[", keys producing such sequences will have no effect
+unless explicitly bound to a readline command, instead of inserting
+stray characters into the editing buffer.  This is unbound by default,
+but usually bound to ESC-[.
+
 @item insert-comment (M-#)
 Without a numeric argument, the value of the @code{comment-begin}
 variable is inserted at the beginning of the current line.
@@ -1519,10 +1613,15 @@ the programmable completion facilities are invoked.
 First, the command name is identified.
 If a compspec has been defined for that command, the
 compspec is used to generate the list of possible completions for the word.
+If the command word is the empty string (completion attempted at the
+beginning of an empty line), any compspec defined with
+the @option{-E} option to @code{complete} is used.
 If the command word is a full pathname, a compspec for the full
 pathname is searched for first.
 If no compspec is found for the full pathname, an attempt is made to
 find a compspec for the portion following the final slash.
+If those searches do not result in a compspec, any compspec defined with
+the @option{-D} option to @code{complete} is used as the default.
 
 Once a compspec has been found, it is used to generate the list of
 matching words.
@@ -1559,9 +1658,9 @@ completed, and the matching words become the possible completions.
 
 After these matches have been generated, any shell function or command
 specified with the @option{-F} and @option{-C} options is invoked.
-When the command or function is invoked, the @env{COMP_LINE} and
-@env{COMP_POINT} variables are assigned values as described above
-(@pxref{Bash Variables}).
+When the command or function is invoked, the @env{COMP_LINE},
+@env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are
+assigned values as described above (@pxref{Bash Variables}).
 If a shell function is being invoked, the @env{COMP_WORDS} and
 @env{COMP_CWORD} variables are also set.
 When the function or command is invoked, the first argument is the
@@ -1574,7 +1673,7 @@ the matches.
 
 Any function specified with @option{-F} is invoked first.
 The function may use any of the shell facilities, including the
-@code{compgen} builtin described below
+@code{compgen} and @code{compopt} builtins described below
 (@pxref{Programmable Completion Builtins}), to generate the matches.
 It must put the possible completions in the @env{COMPREPLY} array
 variable.
@@ -1626,6 +1725,30 @@ to completed names which are symbolic links to directories, subject to
 the value of the @var{mark-directories} Readline variable, regardless
 of the setting of the @var{mark-symlinked-directories} Readline variable.
 
+There is some support for dynamically modifying completions.  This is
+most useful when used in combination with a default completion specified
+with @option{-D}.  It's possible for shell functions executed as completion
+handlers to indicate that completion should be retried by returning an
+exit status of 124.  If a shell function returns 124, and changes
+the compspec associated with the command on which completion is being
+attempted (supplied as the first argument when the function is executed),
+programmable completion restarts from the beginning, with an
+attempt to find a compspec for that command.  This allows a set of
+completions to be built dynamically as completion is attempted, rather than
+being loaded all at once.
+
+For instance, assuming that there is a library of compspecs, each kept in a
+file corresponding to the name of the command, the following default
+completion function would load completions dynamically:
+
+@example
+_completion_loader()
+@{
+	. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
+@}
+complete -D -F _completion_loader
+@end example
+
 @node Programmable Completion Builtins
 @section Programmable Completion Builtins
 @cindex completion builtins
@@ -1661,10 +1784,10 @@ matches were generated.
 @item complete
 @btindex complete
 @example
-@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
-[-P @var{prefix}] [-S @var{suffix}] [-X @var{filterpat}] [-F @var{function}]
-[-C @var{command}] @var{name} [@var{name} @dots{}]}
-@code{complete -pr [@var{name} @dots{}]}
+@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DE] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
+[-F @var{function}] [-C @var{command}] [-X @var{filterpat}]
+[-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]}
+@code{complete -pr [-DE] [@var{name} @dots{}]}
 @end example
 
 Specify how arguments to each @var{name} should be completed.
@@ -1674,9 +1797,16 @@ reused as input.
 The @option{-r} option removes a completion specification for
 each @var{name}, or, if no @var{name}s are supplied, all
 completion specifications.
+The @option{-D} option indicates that the remaining options and actions should
+apply to the ``default'' command completion; that is, completion attempted
+on a command for which no completion has previously been defined.
+The @option{-E} option indicates that the remaining options and actions should
+apply to ``empty'' command completion; that is, completion attempted on a 
+blank line.
 
 The process of applying these completion specifications when word completion
-is attempted is described above (@pxref{Programmable Completion}).
+is attempted is described above (@pxref{Programmable Completion}).  The
+@option{-D} option takes precedence over @option{-E}.
 
 Other options, if specified, have the following meanings.
 The arguments to the @option{-G}, @option{-W}, and @option{-X} options
@@ -1706,9 +1836,10 @@ Perform directory name completion if the compspec generates no matches.
 
 @item filenames
 Tell Readline that the compspec generates filenames, so it can perform any
-filename-specific processing (like adding a slash to directory names or
-suppressing trailing spaces).  This option is intended to be used with
-shell functions specified with @option{-F}.
+filename-specific processing (like adding a slash to directory names
+quoting special characters, or suppressing trailing spaces).
+This option is intended to be used with shell functions specified
+with @option{-F}.
 
 @item nospace
 Tell Readline not to append a space (the default) to words completed at
@@ -1846,5 +1977,31 @@ argument, an attempt is made to remove a completion specification for
 a @var{name} for which no specification exists, or
 an error occurs adding a completion specification.
 
+@item compopt
+@btindex compopt
+@example
+@code{compopt} [-o @var{option}] [-DE] [+o @var{option}] [@var{name}]
+@end example
+Modify completion options for each @var{name} according to the
+@var{option}s, or for the currently-execution completion if no @var{name}s
+are supplied.
+If no @var{option}s are given, display the completion options for each
+@var{name} or the current completion.
+The possible values of @var{option} are those valid for the @code{complete}
+builtin described above.
+The @option{-D} option indicates that the remaining options should
+apply to the ``default'' command completion; that is, completion attempted
+on a command for which no completion has previously been defined.
+The @option{-E} option indicates that the remaining options should
+apply to ``empty'' command completion; that is, completion attempted on a 
+blank line.
+
+The @option{-D} option takes precedence over @option{-E}.
+
+The return value is true unless an invalid option is supplied, an attempt
+is made to modify the options for a @var{name} for which no completion
+specification exists, or an output error occurs.
+
 @end table
+
 @end ifset