Adding upstream version 7.0.upstream/7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 2312 insertions, 0 deletions

diff --git a/doc/rluser.texi b/doc/rluser.texi
new file mode 100644
index 0000000..4c094c8
--- /dev/null
+++ b/doc/rluser.texi
@@ -0,0 +1,2312 @@
+@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.)
+
+@ignore
+This file documents the end user interface to the GNU command line
+editing features.  It is to be an appendix to manuals for programs which
+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--2016 Free Software Foundation, Inc.
+
+Authored by Brian Fox and Chet Ramey.
+
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+Permission is granted to make and distribute verbatim copies of this manual
+provided the copyright notice and this permission notice are preserved on
+all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that the
+GNU Copyright statement is available to the distributee, and provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ignore
+
+@comment If you are including this manual as an appendix, then set the
+@comment variable readline-appendix.
+
+@ifclear BashFeatures
+@defcodeindex bt
+@end ifclear
+
+@node Command Line Editing
+@chapter Command Line Editing
+
+This chapter describes the basic features of the @sc{gnu}
+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
+* Introduction and Notation::	Notation used in this text.
+* Readline Interaction::	The minimum set of commands for editing a line.
+* Readline Init File::		Customizing Readline from a user's view.
+* Bindable Readline Commands::	A description of most of the Readline commands
+				available for binding
+* Readline vi Mode::		A short description of how to make Readline
+				behave like the vi editor.
+@ifset BashFeatures
+* Programmable Completion::	How to specify the possible completions for
+				a specific command.
+* Programmable Completion Builtins::	Builtin commands to specify how to
+				complete arguments for a particular command.
+* A Programmable Completion Example::	An example shell function for
+				generating possible completions.
+@end ifset
+@end menu
+
+@node Introduction and Notation
+@section Introduction to Line Editing
+
+The following paragraphs describe the notation used to represent
+keystrokes.
+
+The text @kbd{C-k} is read as `Control-K' and describes the character
+produced when the @key{k} key is pressed while the Control key
+is depressed.
+
+The text @kbd{M-k} is read as `Meta-K' and describes the character
+produced when the Meta key (if you have one) is depressed, and the @key{k}
+key is pressed.
+The Meta key is labeled @key{ALT} on many keyboards.
+On keyboards with two keys labeled @key{ALT} (usually to either side of
+the space bar), the @key{ALT} on the left side is generally set to
+work as a Meta key.
+The @key{ALT} key on the right may also be configured to work as a
+Meta key or may be configured as some other modifier, such as a
+Compose key for typing accented characters.
+
+If you do not have a Meta or @key{ALT} key, or another key working as
+a Meta key, the identical keystroke can be generated by typing @key{ESC}
+@emph{first}, and then typing @key{k}.
+Either process is known as @dfn{metafying} the @key{k} key.
+
+The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the
+character produced by @dfn{metafying} @kbd{C-k}.
+
+In addition, several keys have their own names.  Specifically,
+@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all
+stand for themselves when seen in this text, or in an init file
+(@pxref{Readline Init File}).
+If your keyboard lacks a @key{LFD} key, typing @key{C-j} will
+produce the desired character.
+The @key{RET} key may be labeled @key{Return} or @key{Enter} on
+some keyboards.
+
+@node Readline Interaction
+@section Readline Interaction
+@cindex interaction, readline
+
+Often during an interactive session you type in a long line of text,
+only to notice that the first word on the line is misspelled.  The
+Readline library gives you a set of commands for manipulating the text
+as you type it in, allowing you to just fix your typo, and not forcing
+you to retype the majority of the line.  Using these editing commands,
+you move the cursor to the place that needs correction, and delete or
+insert the text of the corrections.  Then, when you are satisfied with
+the line, you simply press @key{RET}.  You do not have to be at the
+end of the line to press @key{RET}; the entire line is accepted
+regardless of the location of the cursor within the line.
+
+@menu
+* Readline Bare Essentials::	The least you need to know about Readline.
+* Readline Movement Commands::	Moving about the input line.
+* Readline Killing Commands::	How to delete text, and how to get it back!
+* Readline Arguments::		Giving numeric arguments to commands.
+* Searching::			Searching through previous lines.
+@end menu
+
+@node Readline Bare Essentials
+@subsection Readline Bare Essentials
+@cindex notation, readline
+@cindex command editing
+@cindex editing command lines
+
+In order to enter characters into the line, simply type them.  The typed
+character appears where the cursor was, and then the cursor moves one
+space to the right.  If you mistype a character, you can use your
+erase character to back up and delete the mistyped character.
+
+Sometimes you may mistype a character, and
+not notice the error until you have typed several other characters.  In
+that case, you can type @kbd{C-b} to move the cursor to the left, and then
+correct your mistake.  Afterwards, you can move the cursor to the right
+with @kbd{C-f}.
+
+When you add text in the middle of a line, you will notice that characters
+to the right of the cursor are `pushed over' to make room for the text
+that you have inserted.  Likewise, when you delete text behind the cursor,
+characters to the right of the cursor are `pulled back' to fill in the
+blank space created by the removal of the text.  A list of the bare
+essentials for editing the text of an input line follows.
+
+@table @asis
+@item @kbd{C-b}
+Move back one character.
+@item @kbd{C-f}
+Move forward one character.
+@item @key{DEL} or @key{Backspace}
+Delete the character to the left of the cursor.
+@item @kbd{C-d}
+Delete the character underneath the cursor.
+@item @w{Printing characters}
+Insert the character into the line at the cursor.
+@item @kbd{C-_} or @kbd{C-x C-u}
+Undo the last editing command.  You can undo all the way back to an
+empty line.
+@end table
+
+@noindent
+(Depending on your configuration, the @key{Backspace} key be set to
+delete the character to the left of the cursor and the @key{DEL} key set
+to delete the character underneath the cursor, like @kbd{C-d}, rather
+than the character to the left of the cursor.)
+
+@node Readline Movement Commands
+@subsection Readline Movement Commands
+
+
+The above table describes the most basic keystrokes that you need
+in order to do editing of the input line.  For your convenience, many
+other commands have been added in addition to @kbd{C-b}, @kbd{C-f},
+@kbd{C-d}, and @key{DEL}.  Here are some commands for moving more rapidly
+about the line.
+
+@table @kbd
+@item C-a
+Move to the start of the line.
+@item C-e
+Move to the end of the line.
+@item M-f
+Move forward a word, where a word is composed of letters and digits.
+@item M-b
+Move backward a word.
+@item C-l
+Clear the screen, reprinting the current line at the top.
+@end table
+
+Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves
+forward a word.  It is a loose convention that control keystrokes
+operate on characters while meta keystrokes operate on words.
+
+@node Readline Killing Commands
+@subsection Readline Killing Commands
+
+@cindex killing text
+@cindex yanking text
+
+@dfn{Killing} text means to delete the text from the line, but to save
+it away for later use, usually by @dfn{yanking} (re-inserting)
+it back into the line.
+(`Cut' and `paste' are more recent jargon for `kill' and `yank'.)
+
+If the description for a command says that it `kills' text, then you can
+be sure that you can get the text back in a different (or the same)
+place later.
+
+When you use a kill command, the text is saved in a @dfn{kill-ring}.
+Any number of consecutive kills save all of the killed text together, so
+that when you yank it back, you get it all.  The kill
+ring is not line specific; the text that you killed on a previously
+typed line is available to be yanked back later, when you are typing
+another line.
+@cindex kill ring
+
+Here is the list of commands for killing text.
+
+@table @kbd
+@item C-k
+Kill the text from the current cursor position to the end of the line.
+
+@item M-d
+Kill from the cursor to the end of the current word, or, if between
+words, to the end of the next word.
+Word boundaries are the same as those used by @kbd{M-f}.
+
+@item M-@key{DEL}
+Kill from the cursor the start of the current word, or, if between
+words, to the start of the previous word.
+Word boundaries are the same as those used by @kbd{M-b}.
+
+@item C-w
+Kill from the cursor to the previous whitespace.  This is different than
+@kbd{M-@key{DEL}} because the word boundaries differ.
+
+@end table
+
+Here is how to @dfn{yank} the text back into the line.  Yanking
+means to copy the most-recently-killed text from the kill buffer.
+
+@table @kbd
+@item C-y
+Yank the most recently killed text back into the buffer at the cursor.
+
+@item M-y
+Rotate the kill-ring, and yank the new top.  You can only do this if
+the prior command is @kbd{C-y} or @kbd{M-y}.
+@end table
+
+@node Readline Arguments
+@subsection Readline Arguments
+
+You can pass numeric arguments to Readline commands.  Sometimes the
+argument acts as a repeat count, other times it is the @i{sign} of the
+argument that is significant.  If you pass a negative argument to a
+command which normally acts in a forward direction, that command will
+act in a backward direction.  For example, to kill text back to the
+start of the line, you might type @samp{M-- C-k}.
+
+The general way to pass numeric arguments to a command is to type meta
+digits before the command.  If the first `digit' typed is a minus
+sign (@samp{-}), then the sign of the argument will be negative.  Once
+you have typed one meta digit to get the argument started, you can type
+the remainder of the digits, and then the command.  For example, to give
+the @kbd{C-d} command an argument of 10, you could type @samp{M-1 0 C-d},
+which will delete the next ten characters on the input line.
+
+@node Searching
+@subsection Searching for Commands in the History
+
+Readline provides commands for searching through the command history
+@ifset BashFeatures
+(@pxref{Bash History Facilities})
+@end ifset
+for lines containing a specified string.
+There are two search modes:  @dfn{incremental} and @dfn{non-incremental}.
+
+Incremental searches begin before the user has finished typing the
+search string.
+As each character of the search string is typed, Readline displays
+the next entry from the history matching the string typed so far.
+An incremental search requires only as many characters as needed to
+find the desired history entry.
+To search backward in the history for a particular string, type
+@kbd{C-r}.  Typing @kbd{C-s} searches forward through the history.
+The characters present in the value of the @code{isearch-terminators} variable
+are used to terminate an incremental search.
+If that variable has not been assigned a value, the @key{ESC} and
+@kbd{C-J} characters will terminate an incremental search.
+@kbd{C-g} will abort an incremental search and restore the original line.
+When the search is terminated, the history entry containing the
+search string becomes the current line.
+
+To find other matching entries in the history list, type @kbd{C-r} or
+@kbd{C-s} as appropriate.
+This will search backward or forward in the history for the next
+entry matching the search string typed so far.
+Any other key sequence bound to a Readline command will terminate
+the search and execute that command.
+For instance, a @key{RET} will terminate the search and accept
+the line, thereby executing the command from the history list.
+A movement command will terminate the search, make the last line found
+the current line, and begin editing.
+
+Readline remembers the last incremental search string.  If two
+@kbd{C-r}s are typed without any intervening characters defining a new
+search string, any remembered search string is used.
+
+Non-incremental searches read the entire search string before starting
+to search for matching history lines.  The search string may be
+typed by the user or be part of the contents of the current line.
+
+@node Readline Init File
+@section Readline Init File
+@cindex initialization file, readline
+
+Although the Readline library comes with a set of Emacs-like
+keybindings installed by default, it is possible to use a different set
+of keybindings.
+Any user can customize programs that use Readline by putting
+commands in an @dfn{inputrc} file, conventionally in his home directory.
+The name of this
+@ifset BashFeatures
+file is taken from the value of the shell variable @env{INPUTRC}.  If
+@end ifset
+@ifclear BashFeatures
+file is taken from the value of the environment variable @env{INPUTRC}.  If
+@end ifclear
+that variable is unset, the default is @file{~/.inputrc}.  If that
+file does not exist or cannot be read, the ultimate default is
+@file{/etc/inputrc}.
+
+When a program which uses the Readline library starts up, the
+init file is read, and the key bindings are set.
+
+In addition, the @code{C-x C-r} command re-reads this init file, thus
+incorporating any changes that you might have made to it.
+
+@menu
+* Readline Init File Syntax::	Syntax for the commands in the inputrc file.
+
+* Conditional Init Constructs::	Conditional key bindings in the inputrc file.
+
+* Sample Init File::		An example inputrc file.
+@end menu
+
+@node Readline Init File Syntax
+@subsection Readline Init File Syntax
+
+There are only a few basic constructs allowed in the
+Readline init file.  Blank lines are ignored.
+Lines beginning with a @samp{#} are comments.
+Lines beginning with a @samp{$} indicate conditional
+constructs (@pxref{Conditional Init Constructs}).  Other lines
+denote variable settings and key bindings.
+
+@table @asis
+@item Variable Settings
+You can modify the run-time behavior of Readline by
+altering the values of variables in Readline
+using the @code{set} command within the init file.
+The syntax is simple:
+
+@example
+set @var{variable} @var{value}
+@end example
+
+@noindent
+Here, for example, is how to
+change from the default Emacs-like key binding to use
+@code{vi} line editing commands:
+
+@example
+set editing-mode vi
+@end example
+
+Variable names and values, where appropriate, are recognized without regard
+to case.  Unrecognized variable names are ignored.
+
+Boolean variables (those that can be set to on or off) are set to on if
+the value is null or empty, @var{on} (case-insensitive), or 1.  Any other
+value results in the variable being set to off.
+
+@ifset BashFeatures
+The @w{@code{bind -V}} command lists the current Readline variable names
+and values.  @xref{Bash Builtins}.
+@end ifset
+
+A great deal of run-time behavior is changeable with the following
+variables.
+
+@cindex variables, readline
+@table @code
+
+@item bell-style
+@vindex bell-style
+Controls what happens when Readline wants to ring the terminal bell.
+If set to @samp{none}, Readline never rings the bell.  If set to
+@samp{visible}, Readline uses a visible bell if one is available.
+If set to @samp{audible} (the default), Readline attempts to ring
+the terminal's bell.
+
+@item bind-tty-special-chars
+@vindex bind-tty-special-chars
+If set to @samp{on} (the default), Readline attempts to bind the control
+characters   treated specially by the kernel's terminal driver to their
+Readline equivalents.
+
+@item blink-matching-paren
+@vindex blink-matching-paren
+If set to @samp{on}, Readline attempts to briefly move the cursor to an
+opening parenthesis when a closing parenthesis is inserted.  The default
+is @samp{off}.
+
+@item colored-completion-prefix
+@vindex colored-completion-prefix
+If set to @samp{on}, when listing completions, Readline displays the
+common prefix of the set of possible completions using a different color.
+The color definitions are taken from the value of the @env{LS_COLORS}
+environment variable.
+The default is @samp{off}.
+
+@item colored-stats
+@vindex colored-stats
+If set to @samp{on}, Readline displays possible completions using different
+colors to indicate their file type.
+The color definitions are taken from the value of the @env{LS_COLORS}
+environment variable.
+The default is @samp{off}.
+
+@item comment-begin
+@vindex comment-begin
+The string to insert at the beginning of the line when the
+@code{insert-comment} command is executed.  The default value
+is @code{"#"}.
+
+@item completion-display-width
+@vindex completion-display-width
+The number of screen columns used to display possible matches
+when performing completion.
+The value is ignored if it is less than 0 or greater than the terminal
+screen width.
+A value of 0 will cause matches to be displayed one per line.
+The default value is -1.
+
+@item completion-ignore-case
+@vindex completion-ignore-case
+If set to @samp{on}, Readline performs filename matching and completion
+in a case-insensitive fashion.
+The default value is @samp{off}.
+
+@item completion-map-case
+@vindex completion-map-case
+If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline
+treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when
+performing case-insensitive filename matching and completion.
+
+@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
+asked whether the list of possibilities should be displayed.
+If the number of possible completions is greater than this value,
+Readline will ask the user whether or not he wishes to view
+them; otherwise, they are simply listed.
+This variable must be set to an integer value greater than or equal to 0.
+A negative value means Readline should never ask.
+The default limit is @code{100}.
+
+@item convert-meta
+@vindex convert-meta
+If set to @samp{on}, Readline will convert characters with the
+eighth bit set to an @sc{ascii} key sequence by stripping the eighth
+bit and prefixing an @key{ESC} character, converting them to a
+meta-prefixed key sequence.  The default value is @samp{on}, but
+will be set to @samp{off} if the locale is one that contains
+eight-bit characters.
+
+@item disable-completion
+@vindex disable-completion
+If set to @samp{On}, Readline will inhibit word completion.
+Completion  characters will be inserted into the line as if they had
+been mapped to @code{self-insert}.  The default is @samp{off}.
+
+@item echo-control-characters
+@vindex 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 editing-mode
+@vindex editing-mode
+The @code{editing-mode} variable controls which default set of
+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 emacs-mode-string
+@vindex emacs-mode-string
+This string is displayed immediately before the last line of the primary
+prompt when emacs editing mode is active.  The value is expanded like a
+key binding, so the standard set of meta- and control prefixes and
+backslash escape sequences is available.
+Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
+The default is @samp{@@}.
+
+@item enable-bracketed-paste
+@vindex enable-bracketed-paste
+When set to @samp{On}, Readline will configure the terminal in a way
+that will enable it to insert each paste into the editing buffer as a
+single string of characters, instead of treating each character as if
+it had been read from the keyboard.  This can prevent pasted characters
+from being interpreted as editing commands.  The default is @samp{off}.
+
+@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
+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 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, any existing history entries are deleted and no new entries
+are saved.
+If set to a value less than zero, the number of history entries is not
+limited.
+By default, the number of history entries is not limited.
+If an attempt is made to set @var{history-size} to a non-numeric value,
+the maximum number of history entries will be set to 500.
+
+@item horizontal-scroll-mode
+@vindex horizontal-scroll-mode
+This variable can be set to either @samp{on} or @samp{off}.  Setting it
+to @samp{on} means that the text of the lines being edited will scroll
+horizontally on a single screen line when they are longer than the width
+of the screen, instead of wrapping onto a new screen line.  By default,
+this variable is set to @samp{off}.
+
+@item input-meta
+@vindex input-meta
+@vindex meta-flag
+If set to @samp{on}, Readline will enable eight-bit input (it
+will not clear the eighth bit in the characters it reads),
+regardless of what the terminal claims it can support.  The
+default value is @samp{off}, but Readline will set it to @samp{on} if the 
+locale contains eight-bit characters.
+The name @code{meta-flag} is a synonym for this variable.
+
+@item isearch-terminators
+@vindex isearch-terminators
+The string of characters that should terminate an incremental search without
+subsequently executing the character as a command (@pxref{Searching}).
+If this variable has not been given a value, the characters @key{ESC} and
+@kbd{C-J} will terminate an incremental search.
+
+@item keymap
+@vindex keymap
+Sets Readline's idea of the current keymap for key binding commands.
+Acceptable @code{keymap} names are
+@code{emacs},
+@code{emacs-standard},
+@code{emacs-meta},
+@code{emacs-ctlx},
+@code{vi},
+@code{vi-move},
+@code{vi-command}, and
+@code{vi-insert}.
+@code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a
+synonym); @code{emacs} is equivalent to @code{emacs-standard}.
+The default value is @code{emacs}.
+The value of the @code{editing-mode} variable also affects the
+default keymap.
+
+@item keyseq-timeout
+Specifies the duration Readline will wait for a character when reading an
+ambiguous key sequence (one that can form a complete key sequence using
+the input read so far, or can take additional input to complete a longer
+key sequence).
+If no input is received within the timeout, Readline will use the shorter
+but complete key sequence.
+Readline uses this value to determine whether or not input is
+available on the current input source (@code{rl_instream} by default).
+The value is specified in milliseconds, so a value of 1000 means that
+Readline will wait one second for additional input.
+If this variable is set to a value less than or equal to zero, or to a
+non-numeric value, Readline will wait until another key is pressed to
+decide which key sequence to complete.
+The default value is @code{500}.
+
+@item mark-directories
+If set to @samp{on}, completed directory names have a slash
+appended.  The default is @samp{on}.
+
+@item mark-modified-lines
+@vindex mark-modified-lines
+This variable, when set to @samp{on}, causes Readline to display an
+asterisk (@samp{*}) at the start of history lines which have been modified.
+This variable is @samp{off} by default.
+
+@item mark-symlinked-directories
+@vindex mark-symlinked-directories
+If set to @samp{on}, completed names which are symbolic links
+to directories have a slash appended (subject to the value of
+@code{mark-directories}).
+The default is @samp{off}.
+
+@item match-hidden-files
+@vindex match-hidden-files
+This variable, when set to @samp{on}, causes Readline to match files whose
+names begin with a @samp{.} (hidden files) when performing filename
+completion.
+If set to @samp{off}, the leading @samp{.} must be
+supplied by the user in the filename to be completed.
+This variable is @samp{on} by default.
+
+@item menu-complete-display-prefix
+@vindex menu-complete-display-prefix
+If set to @samp{on}, menu completion displays the common prefix of the
+list of possible completions (which may be empty) before cycling through
+the list.  The default is @samp{off}.
+
+@item output-meta
+@vindex output-meta
+If set to @samp{on}, Readline will display characters with the
+eighth bit set directly rather than as a meta-prefixed escape
+sequence.
+The default is @samp{off}, but Readline will set it to @samp{on} if the
+locale contains eight-bit characters.
+
+@item page-completions
+@vindex page-completions
+If set to @samp{on}, Readline uses an internal @code{more}-like pager
+to display a screenful of possible completions at a time.
+This variable is @samp{on} by default.
+
+@item print-completions-horizontally
+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
+set to @samp{on}, 
+words which have more than one possible completion cause the
+matches to be listed immediately instead of ringing the bell.
+The default value is @samp{off}.
+
+@item show-all-if-unmodified
+@vindex show-all-if-unmodified
+This alters the default behavior of the completion functions in
+a fashion similar to @var{show-all-if-ambiguous}.
+If set to @samp{on}, 
+words which have more than one possible completion without any
+possible partial completion (the possible completions don't share
+a common prefix) cause the matches to be listed immediately instead
+of ringing the bell.
+The default value is @samp{off}.
+
+@item show-mode-in-prompt
+@vindex show-mode-in-prompt
+If set to @samp{on}, add a character to the beginning of the prompt
+indicating the editing mode: emacs, vi command, or vi insertion.
+The mode strings are user-settable.
+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 vi-cmd-mode-string
+@vindex vi-cmd-mode-string
+This string is displayed immediately before the last line of the primary
+prompt when vi editing mode is active and in command mode.
+The value is expanded like a
+key binding, so the standard set of meta- and control prefixes and
+backslash escape sequences is available.
+Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
+The default is @samp{(cmd)}.
+
+@item vi-ins-mode-string
+@vindex vi-ins-mode-string
+This string is displayed immediately before the last line of the primary
+prompt when vi editing mode is active and in insertion mode.
+The value is expanded like a
+key binding, so the standard set of meta- and control prefixes and
+backslash escape sequences is available.
+Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
+The default is @samp{(ins)}.
+
+@item visible-stats
+@vindex visible-stats
+If set to @samp{on}, a character denoting a file's type
+is appended to the filename when listing possible
+completions.  The default is @samp{off}.
+
+@end table
+
+@item Key Bindings
+The syntax for controlling key bindings in the init file is
+simple.  First you need to find the name of the command that you
+want to change.  The following sections contain tables of the command
+name, the default keybinding, if any, and a short description of what
+the command does.
+
+Once you know the name of the command, simply place on a line
+in the init file the name of the key
+you wish to bind the command to, a colon, and then the name of the
+command.
+There can be no space between the key name and the colon -- that will be
+interpreted as part of the key name.
+The name of the key can be expressed in different ways, depending on
+what you find most comfortable.
+
+In addition to command names, readline allows keys to be bound
+to a string that is inserted when the key is pressed (a @var{macro}).
+
+@ifset BashFeatures
+The @w{@code{bind -p}} command displays Readline function names and
+bindings in a format that can put directly into an initialization file.
+@xref{Bash Builtins}.
+@end ifset
+
+@table @asis
+@item @w{@var{keyname}: @var{function-name} or @var{macro}}
+@var{keyname} is the name of a key spelled out in English.  For example:
+@example
+Control-u: universal-argument
+Meta-Rubout: backward-kill-word
+Control-o: "> output"
+@end example
+
+In the above example, @kbd{C-u} is bound to the function
+@code{universal-argument},
+@kbd{M-DEL} is bound to the function @code{backward-kill-word}, and
+@kbd{C-o} is bound to run the macro
+expressed on the right hand side (that is, to insert the text
+@samp{> output} into the line).
+
+A number of symbolic character names are recognized while
+processing this key binding syntax:
+@var{DEL},
+@var{ESC},
+@var{ESCAPE},
+@var{LFD},
+@var{NEWLINE},
+@var{RET},
+@var{RETURN},
+@var{RUBOUT},
+@var{SPACE},
+@var{SPC},
+and
+@var{TAB}.
+
+@item @w{"@var{keyseq}": @var{function-name} or @var{macro}}
+@var{keyseq} differs from @var{keyname} above in that strings
+denoting an entire key sequence can be specified, by placing
+the key sequence in double quotes.  Some @sc{gnu} Emacs style key
+escapes can be used, as in the following example, but the
+special character names are not recognized.
+
+@example
+"\C-u": universal-argument
+"\C-x\C-r": re-read-init-file
+"\e[11~": "Function Key 1"
+@end example
+
+In the above example, @kbd{C-u} is again bound to the function
+@code{universal-argument} (just as it was in the first example),
+@samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file},
+and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert
+the text @samp{Function Key 1}.
+
+@end table
+
+The following @sc{gnu} Emacs style escape sequences are available when
+specifying key sequences:
+
+@table @code
+@item @kbd{\C-}
+control prefix
+@item @kbd{\M-}
+meta prefix
+@item @kbd{\e}
+an escape character
+@item @kbd{\\}
+backslash
+@item @kbd{\"}
+@key{"}, a double quotation mark
+@item @kbd{\'}
+@key{'}, a single quote or apostrophe
+@end table
+
+In addition to the @sc{gnu} Emacs style escape sequences, a second
+set of backslash escapes is available:
+
+@table @code
+@item \a
+alert (bell)
+@item \b
+backspace
+@item \d
+delete
+@item \f
+form feed
+@item \n
+newline
+@item \r
+carriage return
+@item \t
+horizontal tab
+@item \v
+vertical tab
+@item \@var{nnn}
+the eight-bit character whose value is the octal value @var{nnn}
+(one to three digits)
+@item \x@var{HH}
+the eight-bit character whose value is the hexadecimal value @var{HH}
+(one or two hex digits)
+@end table
+
+When entering the text of a macro, single or double quotes must
+be used to indicate a macro definition.
+Unquoted text is assumed to be a function name.
+In the macro body, the backslash escapes described above are expanded.
+Backslash will quote any other character in the macro text,
+including @samp{"} and @samp{'}.
+For example, the following binding will make @samp{@kbd{C-x} \}
+insert a single @samp{\} into the line:
+@example
+"\C-x\\": "\\"
+@end example
+
+@end table
+
+@node Conditional Init Constructs
+@subsection Conditional Init Constructs
+
+Readline implements a facility similar in spirit to the conditional
+compilation features of the C preprocessor which allows key
+bindings and variable settings to be performed as the result
+of tests.  There are four parser directives used.
+
+@table @code
+@item $if
+The @code{$if} construct allows bindings to be made based on the
+editing mode, the terminal being used, or the application using
+Readline.  The text of the test extends to the end of the line;
+no characters are required to isolate it.
+
+@table @code
+@item mode
+The @code{mode=} form of the @code{$if} directive is used to test
+whether Readline is in @code{emacs} or @code{vi} mode.
+This may be used in conjunction
+with the @samp{set keymap} command, for instance, to set bindings in
+the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if
+Readline is starting out in @code{emacs} mode.
+
+@item term
+The @code{term=} form may be used to include terminal-specific
+key bindings, perhaps to bind the key sequences output by the
+terminal's function keys.  The word on the right side of the
+@samp{=} is tested against both the full name of the terminal and
+the portion of the terminal name before the first @samp{-}.  This
+allows @code{sun} to match both @code{sun} and @code{sun-cmd},
+for instance.
+
+@item application
+The @var{application} construct is used to include
+application-specific settings.  Each program using the Readline
+library sets the @var{application name}, and you can test for
+a particular value. 
+This could be used to bind key sequences to functions useful for
+a specific program.  For instance, the following command adds a
+key sequence that quotes the current or previous word in Bash:
+@example
+$if Bash
+# Quote the current or previous word
+"\C-xq": "\eb\"\ef\""
+$endif
+@end example
+@end table
+
+@item $endif
+This command, as seen in the previous example, terminates an
+@code{$if} command.
+
+@item $else
+Commands in this branch of the @code{$if} directive are executed if
+the test fails.
+
+@item $include
+This directive takes a single filename as an argument and reads commands
+and bindings from that file.
+For example, the following directive reads from @file{/etc/inputrc}:
+@example
+$include /etc/inputrc
+@end example
+@end table
+
+@node Sample Init File
+@subsection Sample Init File
+
+Here is an example of an @var{inputrc} file.  This illustrates key
+binding, variable assignment, and conditional syntax.
+
+@example
+@page
+# This file controls the behaviour of line input editing for
+# programs that use the GNU Readline library.  Existing
+# programs include FTP, Bash, and GDB.
+#
+# You can re-read the inputrc file with C-x C-r.
+# Lines beginning with '#' are comments.
+#
+# First, include any system-wide bindings and variable
+# assignments from /etc/Inputrc
+$include /etc/Inputrc
+
+#
+# Set various bindings for emacs mode.
+
+set editing-mode emacs 
+
+$if mode=emacs
+
+Meta-Control-h:	backward-kill-word	Text after the function name is ignored
+
+#
+# Arrow keys in keypad mode
+#
+#"\M-OD":        backward-char
+#"\M-OC":        forward-char
+#"\M-OA":        previous-history
+#"\M-OB":        next-history
+#
+# Arrow keys in ANSI mode
+#
+"\M-[D":        backward-char
+"\M-[C":        forward-char
+"\M-[A":        previous-history
+"\M-[B":        next-history
+#
+# Arrow keys in 8 bit keypad mode
+#
+#"\M-\C-OD":       backward-char
+#"\M-\C-OC":       forward-char
+#"\M-\C-OA":       previous-history
+#"\M-\C-OB":       next-history
+#
+# Arrow keys in 8 bit ANSI mode
+#
+#"\M-\C-[D":       backward-char
+#"\M-\C-[C":       forward-char
+#"\M-\C-[A":       previous-history
+#"\M-\C-[B":       next-history
+
+C-q: quoted-insert
+
+$endif
+
+# An old-style binding.  This happens to be the default.
+TAB: complete
+
+# Macros that are convenient for shell interaction
+$if Bash
+# edit the path
+"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f"
+# prepare to type a quoted word --
+# insert open and close double quotes
+# and move to just after the open quote
+"\C-x\"": "\"\"\C-b"
+# insert a backslash (testing backslash escapes
+# in sequences and macros)
+"\C-x\\": "\\"
+# Quote the current or previous word
+"\C-xq": "\eb\"\ef\""
+# Add a binding to refresh the line, which is unbound
+"\C-xr": redraw-current-line
+# Edit variable on current line.
+"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
+$endif
+
+# use a visible bell if one is available
+set bell-style visible
+
+# don't strip characters to 7 bits when reading
+set input-meta on
+
+# allow iso-latin1 characters to be inserted rather
+# than converted to prefix-meta sequences
+set convert-meta off
+
+# display characters with the eighth bit set directly
+# rather than as meta-prefixed characters
+set output-meta on
+
+# if there are more than 150 possible completions for
+# a word, ask the user if he wants to see all of them
+set completion-query-items 150
+
+# For FTP
+$if Ftp
+"\C-xg": "get \M-?"
+"\C-xt": "put \M-?"
+"\M-.": yank-last-arg
+$endif
+@end example
+
+@node Bindable Readline Commands
+@section Bindable Readline Commands
+
+@menu
+* Commands For Moving::		Moving about the line.
+* Commands For History::	Getting at previous lines.
+* Commands For Text::		Commands for changing text.
+* Commands For Killing::	Commands for killing and yanking.
+* Numeric Arguments::		Specifying numeric arguments, repeat counts.
+* Commands For Completion::	Getting Readline to do the typing for you.
+* Keyboard Macros::		Saving and re-executing typed characters
+* Miscellaneous Commands::	Other miscellaneous commands.
+@end menu
+
+This section describes Readline commands that may be bound to key
+sequences.
+@ifset BashFeatures
+You can list your key bindings by executing
+@w{@code{bind -P}} or, for a more terse format, suitable for an
+@var{inputrc} file, @w{@code{bind -p}}.  (@xref{Bash Builtins}.)
+@end ifset
+Command names without an accompanying key sequence are unbound by default.
+
+In the following descriptions, @dfn{point} refers to the current cursor
+position, and @dfn{mark} refers to a cursor position saved by the
+@code{set-mark} command.
+The text between the point and mark is referred to as the @dfn{region}.
+
+@node Commands For Moving
+@subsection Commands For Moving
+@ftable @code
+@item beginning-of-line (C-a)
+Move to the start of the current line.
+
+@item end-of-line (C-e)
+Move to the end of the line.
+
+@item forward-char (C-f)
+Move forward a character.
+
+@item backward-char (C-b)
+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.
+
+@item backward-word (M-b)
+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,
+leaving the current line at the top of the screen.
+
+@item redraw-current-line ()
+Refresh the current line.  By default, this is unbound.
+
+@end ftable
+
+@node Commands For History
+@subsection Commands For Manipulating The History
+
+@ftable @code
+@item accept-line (Newline or Return)
+@ifset BashFeatures
+Accept the line regardless of where the cursor is.
+If this line is
+non-empty, add it to the history list according to the setting of
+the @env{HISTCONTROL} and @env{HISTIGNORE} variables.
+If this line is a modified history line, then restore the history line
+to its original state.
+@end ifset
+@ifclear BashFeatures
+Accept the line regardless of where the cursor is.
+If this line is
+non-empty, it may be added to the history list for future recall with
+@code{add_history()}.
+If this line is a modified history line, the history line is restored
+to its original state.
+@end ifclear
+
+@item previous-history (C-p)
+Move `back' through the history list, fetching the previous command.
+
+@item next-history (C-n)
+Move `forward' through the history list, fetching the next command.
+
+@item beginning-of-history (M-<)
+Move to the first line in the history.
+
+@item end-of-history (M->)
+Move to the end of the input history, i.e., the line currently
+being entered.
+
+@item reverse-search-history (C-r)
+Search backward starting at the current line and moving `up' through
+the history as necessary.  This is an incremental search.
+
+@item forward-search-history (C-s)
+Search forward starting at the current line and moving `down' through
+the history as necessary.  This is an incremental search.
+
+@item non-incremental-reverse-search-history (M-p)
+Search backward starting at the current line and moving `up'
+through the history as necessary using a non-incremental search
+for a string supplied by the user.
+The search string may match anywhere in a history line.
+
+@item non-incremental-forward-search-history (M-n)
+Search forward starting at the current line and moving `down'
+through the history as necessary using a non-incremental search
+for a string supplied by the user.
+The search string may match anywhere in a history line.
+
+@item history-search-forward ()
+Search forward through the history for the string of characters
+between the start of the current line and the point.
+The search string must match at the beginning of a history line.
+This is a non-incremental search.
+By default, this command is unbound.
+
+@item history-search-backward ()
+Search backward through the history for the string of characters
+between the start of the current line and the point.
+The search string must match at the beginning of a history line.
+This is a non-incremental search.
+By default, this command is unbound.
+
+@item history-substr-search-forward ()
+Search forward through the history for the string of characters
+between the start of the current line and the point.
+The search string may match anywhere in a history line.
+This is a non-incremental search.
+By default, this command is unbound.
+
+@item history-substr-search-backward ()
+Search backward through the history for the string of characters
+between the start of the current line and the point.
+The search string may match anywhere in a history line.
+This is a non-incremental search.
+By default, this command is unbound.
+
+@item yank-nth-arg (M-C-y)
+Insert the first argument to the previous command (usually
+the second word on the previous line) at point.
+With an argument @var{n},
+insert the @var{n}th word from the previous command (the words
+in the previous command begin with word 0).  A negative argument
+inserts the @var{n}th word from the end of the previous command.
+Once the argument @var{n} is computed, the argument is extracted
+as if the @samp{!@var{n}} history expansion had been specified.
+
+@item yank-last-arg (M-. or M-_)
+Insert last argument to the previous command (the last word of the
+previous history entry).
+With a numeric argument, behave exactly like @code{yank-nth-arg}.
+Successive calls to @code{yank-last-arg} move back through the history
+list, inserting the last word (or the word specified by the argument to
+the first call) of each line in turn.
+Any numeric argument supplied to these successive calls determines
+the direction to move through the history.  A negative argument switches
+the direction through the history (back or forward).
+The history expansion facilities are used to extract the last argument,
+as if the @samp{!$} history expansion had been specified.
+
+@end ftable
+
+@node Commands For Text
+@subsection Commands For Changing Text
+
+@ftable @code
+
+@item @i{end-of-file} (usually C-d)
+The character indicating end-of-file as set, for example, by
+@code{stty}.  If this character is read when there are no characters
+on the line, and point is at the beginning of the line, Readline
+interprets it as the end of input and returns @sc{eof}.
+
+@item delete-char (C-d)
+Delete the character at point.  If this function is bound to the
+same character as the tty @sc{eof} character, as @kbd{C-d}
+commonly is, see above for the effects.
+
+@item backward-delete-char (Rubout)
+Delete the character behind the cursor.  A numeric argument means
+to kill the characters instead of deleting them.
+
+@item forward-backward-delete-char ()
+Delete the character under the cursor, unless the cursor is at the
+end of the line, in which case the character behind the cursor is
+deleted.  By default, this is not bound to a key.
+
+@item quoted-insert (C-q or C-v)
+Add the next character typed to the line verbatim.  This is
+how to insert key sequences like @kbd{C-q}, for example.
+
+@ifclear BashFeatures
+@item tab-insert (M-@key{TAB})
+Insert a tab character.
+@end ifclear
+
+@item self-insert (a, b, A, 1, !, @dots{})
+Insert yourself.
+
+@item bracketed-paste-begin ()
+This function is intended to be bound to the "bracketed paste" escape
+sequence sent by some terminals, and such a binding is assigned by default.
+It allows Readline to insert the pasted text as a single unit without treating
+each character as if it had been read from the keyboard.  The characters
+are inserted as if each one was bound to @code{self-insert}) instead of
+executing any editing commands.
+
+@item transpose-chars (C-t)
+Drag the character before the cursor forward over
+the character at the cursor, moving the
+cursor forward as well.  If the insertion point
+is at the end of the line, then this
+transposes the last two characters of the line.
+Negative arguments have no effect.
+
+@item transpose-words (M-t)
+Drag the word before point past the word after point,
+moving point past that word as well.
+If the insertion point is at the end of the line, this transposes
+the last two words on the line.
+
+@item upcase-word (M-u)
+Uppercase the current (or following) word.  With a negative argument,
+uppercase the previous word, but do not move the cursor.
+
+@item downcase-word (M-l)
+Lowercase the current (or following) word.  With a negative argument,
+lowercase the previous word, but do not move the cursor.
+
+@item capitalize-word (M-c)
+Capitalize the current (or following) word.  With a negative argument,
+capitalize the previous word, but do not move the cursor.
+
+@item overwrite-mode ()
+Toggle overwrite mode.  With an explicit positive numeric argument,
+switches to overwrite mode.  With an explicit non-positive numeric
+argument, switches to insert mode.  This command affects only
+@code{emacs} mode; @code{vi} mode does overwrite differently.
+Each call to @code{readline()} starts in insert mode.
+
+In overwrite mode, characters bound to @code{self-insert} replace
+the text at point rather than pushing the text to the right.
+Characters bound to @code{backward-delete-char} replace the character
+before point with a space.
+
+By default, this command is unbound.
+
+@end ftable
+
+@node Commands For Killing
+@subsection Killing And Yanking
+
+@ftable @code
+
+@item kill-line (C-k)
+Kill the text from point to the end of the line.
+
+@item backward-kill-line (C-x Rubout)
+Kill backward from the cursor to the beginning of the current line.
+
+@item unix-line-discard (C-u)
+Kill backward from the cursor to the beginning of the current line.
+
+@item kill-whole-line ()
+Kill all characters on the current line, no matter where point is.
+By default, this is unbound.
+
+@item kill-word (M-d)
+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{forward-word}.
+
+@item backward-kill-word (M-@key{DEL})
+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 shell-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.
+
+@item unix-filename-rubout ()
+Kill the word behind point, using white space and the slash character
+as the word boundaries.
+The killed text is saved on the kill-ring.
+
+@item delete-horizontal-space ()
+Delete all spaces and tabs around point.  By default, this is unbound.
+
+@item kill-region ()
+Kill the text in the current region.
+By default, this command is unbound.
+
+@item copy-region-as-kill ()
+Copy the text in the region to the kill buffer, so it can be yanked
+right away.  By default, this command is unbound.
+
+@item copy-backward-word ()
+Copy the word before point to the kill buffer.
+The word boundaries are the same as @code{backward-word}.
+By default, this command is unbound.
+
+@item copy-forward-word ()
+Copy the word following point to the kill buffer.
+The word boundaries are the same as @code{forward-word}.
+By default, this command is unbound.
+
+@item yank (C-y)
+Yank the top of the kill ring into the buffer at point.
+
+@item yank-pop (M-y)
+Rotate the kill-ring, and yank the new top.  You can only do this if
+the prior command is @code{yank} or @code{yank-pop}.
+@end ftable
+
+@node Numeric Arguments
+@subsection Specifying Numeric Arguments
+@ftable @code
+
+@item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--})
+Add this digit to the argument already accumulating, or start a new
+argument.  @kbd{M--} starts a negative argument.
+
+@item universal-argument ()
+This is another way to specify an argument.
+If this command is followed by one or more digits, optionally with a
+leading minus sign, those digits define the argument.
+If the command is followed by digits, executing @code{universal-argument}
+again ends the numeric argument, but is otherwise ignored.
+As a special case, if this command is immediately followed by a
+character that is neither a digit nor minus sign, the argument count
+for the next command is multiplied by four.
+The argument count is initially one, so executing this function the
+first time makes the argument count four, a second time makes the
+argument count sixteen, and so on.
+By default, this is not bound to a key.
+@end ftable
+
+@node Commands For Completion
+@subsection Letting Readline Type For You
+
+@ftable @code
+@item complete (@key{TAB})
+Attempt to perform completion on the text before point.
+The actual completion performed is application-specific.
+@ifset BashFeatures
+Bash attempts completion treating the text as a variable (if the
+text begins with @samp{$}), username (if the text begins with
+@samp{~}), hostname (if the text begins with @samp{@@}), or
+command (including aliases and functions) in turn.  If none 
+of these produces a match, filename completion is attempted.
+@end ifset
+@ifclear BashFeatures
+The default is filename completion.
+@end ifclear
+
+@item possible-completions (M-?)
+List the possible completions of the text before point.
+When displaying completions, Readline sets the number of columns used
+for display to the value of @code{completion-display-width}, the value of
+the environment variable @env{COLUMNS}, or the screen width, in that order.
+
+@item insert-completions (M-*)
+Insert all completions of the text before point that would have
+been generated by @code{possible-completions}.
+
+@item menu-complete ()
+Similar to @code{complete}, but replaces the word to be completed
+with a single match from the list of possible completions.
+Repeated execution of @code{menu-complete} steps through the list
+of possible completions, inserting each match in turn.
+At the end of the list of completions, the bell is rung
+(subject to the setting of @code{bell-style})
+and the original text is restored.
+An argument of @var{n} moves @var{n} positions forward in the list
+of matches; a negative argument may be used to move backward
+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}).
+If at the end of the line, behaves identically to
+@code{possible-completions}.
+This command is unbound by default.
+
+@ifset BashFeatures
+@item complete-filename (M-/)
+Attempt filename completion on the text before point.
+
+@item possible-filename-completions (C-x /)
+List the possible completions of the text before point,
+treating it as a filename.
+
+@item complete-username (M-~)
+Attempt completion on the text before point, treating
+it as a username.
+
+@item possible-username-completions (C-x ~)
+List the possible completions of the text before point,
+treating it as a username.
+
+@item complete-variable (M-$)
+Attempt completion on the text before point, treating
+it as a shell variable.
+
+@item possible-variable-completions (C-x $)
+List the possible completions of the text before point,
+treating it as a shell variable.
+
+@item complete-hostname (M-@@)
+Attempt completion on the text before point, treating
+it as a hostname.
+
+@item possible-hostname-completions (C-x @@)
+List the possible completions of the text before point,
+treating it as a hostname.
+
+@item complete-command (M-!)
+Attempt completion on the text before point, treating
+it as a command name.  Command completion attempts to
+match the text against aliases, reserved words, shell
+functions, shell builtins, and finally executable filenames,
+in that order.
+
+@item possible-command-completions (C-x !)
+List the possible completions of the text before point,
+treating it as a command name.
+
+@item dynamic-complete-history (M-@key{TAB})
+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
+(@pxref{Brace Expansion}).
+
+@end ifset
+@end ftable
+
+@node Keyboard Macros
+@subsection Keyboard Macros
+@ftable @code
+
+@item start-kbd-macro (C-x ()
+Begin saving the characters typed into the current keyboard macro.
+
+@item end-kbd-macro (C-x ))
+Stop saving the characters typed into the current keyboard macro
+and save the definition.
+
+@item 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.
+
+@item print-last-kbd-macro ()
+Print the last keboard macro defined in a format suitable for the
+@var{inputrc} file.
+
+@end ftable
+
+@node Miscellaneous Commands
+@subsection Some Miscellaneous Commands
+@ftable @code
+
+@item re-read-init-file (C-x C-r)
+Read in the contents of the @var{inputrc} file, and incorporate
+any bindings or variable assignments found there.
+
+@item abort (C-g)
+Abort the current editing command and
+ring the terminal's bell (subject to the setting of
+@code{bell-style}).
+
+@item do-uppercase-version (M-a, M-b, M-@var{x}, @dots{})
+If the metafied character @var{x} is lowercase, run the command
+that is bound to the corresponding uppercase character.
+
+@item prefix-meta (@key{ESC})
+Metafy the next character typed.  This is for keyboards
+without a meta key.  Typing @samp{@key{ESC} f} is equivalent to typing
+@kbd{M-f}.
+
+@item undo (C-_ or C-x C-u)
+Incremental undo, separately remembered for each line.
+
+@item revert-line (M-r)
+Undo all changes made to this line.  This is like executing the @code{undo}
+command enough times to get back to the beginning.
+
+@ifset BashFeatures
+@item tilde-expand (M-&)
+@end ifset
+@ifclear BashFeatures
+@item tilde-expand (M-~)
+@end ifclear
+Perform tilde expansion on the current word.
+
+@item set-mark (C-@@)
+Set the mark to the point.  If a
+numeric argument is supplied, the mark is set to that position.
+
+@item exchange-point-and-mark (C-x C-x)
+Swap the point with the mark.  The current cursor position is set to
+the saved position, and the old cursor position is saved as the mark.
+
+@item character-search (C-])
+A character is read and point is moved to the next occurrence of that
+character.  A negative count searches for previous occurrences.
+
+@item character-search-backward (M-C-])
+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.
+If a numeric argument is supplied, this command acts as a toggle:  if
+the characters at the beginning of the line do not match the value
+of @code{comment-begin}, the value is inserted, otherwise
+the characters in @code{comment-begin} are deleted from the beginning of
+the line.
+In either case, the line is accepted as if a newline had been typed.
+@ifset BashFeatures
+The default value of @code{comment-begin} causes this command
+to make the current line a shell comment.
+If a numeric argument causes the comment character to be removed, the line
+will be executed by the shell.
+@end ifset
+
+@item dump-functions ()
+Print all of the functions and their key bindings to the
+Readline output stream.  If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an @var{inputrc} file.  This command is unbound by default.
+
+@item dump-variables ()
+Print all of the settable variables and their values to the
+Readline output stream.  If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an @var{inputrc} file.  This command is unbound by default.
+
+@item dump-macros ()
+Print all of the Readline key sequences bound to macros and the
+strings they output.  If a numeric argument is supplied,
+the output is formatted in such a way that it can be made part
+of an @var{inputrc} file.  This command is unbound by default.
+
+@ifset BashFeatures
+@item glob-complete-word (M-g)
+The word before point is treated as a pattern for pathname expansion,
+with an asterisk implicitly appended.  This pattern is used to
+generate a list of matching file names for possible completions.
+
+@item glob-expand-word (C-x *)
+The word before point is treated as a pattern for pathname expansion,
+and the list of matching file names is inserted, replacing the word.
+If a numeric argument is supplied, a @samp{*} is appended before
+pathname expansion.
+
+@item glob-list-expansions (C-x g)
+The list of expansions that would have been generated by
+@code{glob-expand-word} is displayed, and the line is redrawn.
+If a numeric argument is supplied, a @samp{*} is appended before
+pathname expansion.
+
+@item display-shell-version (C-x C-v)
+Display version information about the current instance of Bash.
+
+@item shell-expand-line (M-C-e)
+Expand the line as the shell does.
+This performs alias and history expansion as well as all of the shell
+word expansions (@pxref{Shell Expansions}).
+
+@item history-expand-line (M-^)
+Perform history expansion on the current line.
+
+@item magic-space ()
+Perform history expansion on the current line and insert a space
+(@pxref{History Interaction}).
+
+@item alias-expand-line ()
+Perform alias expansion on the current line (@pxref{Aliases}).
+
+@item history-and-alias-expand-line ()
+Perform history and alias expansion on the current line.
+
+@item insert-last-argument (M-. or M-_)
+A synonym for @code{yank-last-arg}.
+
+@item operate-and-get-next (C-o)
+Accept the current line for execution and fetch the next line
+relative to the current line from the history for editing.  Any
+argument is ignored.
+
+@item edit-and-execute-command (C-xC-e)
+Invoke an editor on the current command line, and execute the result as shell
+commands.
+Bash attempts to invoke
+@code{$VISUAL}, @code{$EDITOR}, and @code{emacs}
+as the editor, in that order.
+
+@end ifset
+
+@ifclear BashFeatures
+@item emacs-editing-mode (C-e)
+When in @code{vi} command mode, this causes a switch to @code{emacs}
+editing mode.
+
+@item vi-editing-mode (M-C-j)
+When in @code{emacs} editing mode, this causes a switch to @code{vi}
+editing mode.
+
+@end ifclear
+
+@end ftable
+
+@node Readline vi Mode
+@section Readline vi Mode
+
+While the Readline library does not have a full set of @code{vi}
+editing functions, it does contain enough to allow simple editing
+of the line.  The Readline @code{vi} mode behaves as specified in
+the @sc{posix} standard.
+
+@ifset BashFeatures
+In order to switch interactively between @code{emacs} and @code{vi}
+editing modes, use the @samp{set -o emacs} and @samp{set -o vi}
+commands (@pxref{The Set Builtin}).
+@end ifset
+@ifclear BashFeatures
+In order to switch interactively between @code{emacs} and @code{vi}
+editing modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode
+when in @code{vi} mode and to vi-editing-mode in @code{emacs} mode).
+@end ifclear
+The Readline default is @code{emacs} mode.
+
+When you enter a line in @code{vi} mode, you are already placed in
+`insertion' mode, as if you had typed an @samp{i}.  Pressing @key{ESC}
+switches you into `command' mode, where you can edit the text of the
+line with the standard @code{vi} movement keys, move to previous
+history lines with @samp{k} and subsequent lines with @samp{j}, and
+so forth.
+
+@ifset BashFeatures
+@node Programmable Completion
+@section Programmable Completion
+@cindex programmable completion
+
+When word completion is attempted for an argument to a command for
+which a completion specification (a @var{compspec}) has been defined
+using the @code{complete} builtin (@pxref{Programmable Completion Builtins}),
+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.
+If a compspec is not found, the default Bash completion
+described above (@pxref{Commands For Completion}) is performed.
+
+First, the actions specified by the compspec are used.
+Only matches which are prefixed by the word being completed are
+returned.
+When the @option{-f} or @option{-d} option is used for filename or
+directory name completion, the shell variable @env{FIGNORE} is
+used to filter the matches.
+@xref{Bash Variables}, for a description of @env{FIGNORE}.
+
+Any completions specified by a filename expansion pattern to the
+@option{-G} option are generated next.
+The words generated by the pattern need not match the word being completed.
+The @env{GLOBIGNORE} shell variable is not used to filter the matches,
+but the @env{FIGNORE} shell variable is used.
+
+Next, the string specified as the argument to the @option{-W} option
+is considered.
+The string is first split using the characters in the @env{IFS}
+special variable as delimiters.
+Shell quoting is honored.
+Each word is then expanded using
+brace expansion, tilde expansion, parameter and variable expansion,
+command substitution, and arithmetic expansion,
+as described above (@pxref{Shell Expansions}).
+The results are split using the rules described above
+(@pxref{Word Splitting}).
+The results of the expansion are prefix-matched against the word being
+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},
+@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 ($1) is the
+name of the command whose arguments are being completed, the
+second argument ($2) is the word being completed, and the third argument
+($3) 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.
+
+Any function specified with @option{-F} is invoked first.
+The function may use any of the shell facilities, including the
+@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, one per array element.
+
+Next, any command specified with the @option{-C} option is invoked
+in an environment equivalent to command substitution.
+It should print a list of completions, one per line, to
+the standard output.
+Backslash may be used to escape a newline, if necessary.
+
+After all of the possible completions are generated, any filter
+specified with the @option{-X} option is applied to the list.
+The filter is a pattern as used for pathname expansion; a @samp{&}
+in the pattern is replaced with the text of the word being completed.
+A literal @samp{&} may be escaped with a backslash; the backslash
+is removed before attempting a match.
+Any completion that matches the pattern will be removed from the list.
+A leading @samp{!} negates the pattern; in this case any completion
+not matching the pattern will be removed.
+If the @code{nocasematch} shell option
+(see the description of @code{shopt} in @ref{The Shopt Builtin})
+is enabled, the match is performed without regard to the case
+of alphabetic characters.
+
+Finally, any prefix and suffix specified with the @option{-P} and @option{-S}
+options are added to each member of the completion list, and the result is
+returned to the Readline completion code as the list of possible
+completions.
+
+If the previously-applied actions do not generate any matches, and the
+@option{-o dirnames} option was supplied to @code{complete} when the
+compspec was defined, directory name completion is attempted. 
+
+If the @option{-o plusdirs} option was supplied to @code{complete} when
+the compspec was defined, directory name completion is attempted and any
+matches are added to the results of the other actions.
+
+By default, if a compspec is found, whatever it generates is returned to
+the completion code as the full set of possible completions.
+The default Bash completions are not attempted, and the Readline default
+of filename completion is disabled.
+If the @option{-o bashdefault} option was supplied to @code{complete} when
+the compspec was defined, the default Bash completions are attempted
+if the compspec generates no matches.
+If the @option{-o default} option was supplied to @code{complete} when the
+compspec was defined, Readline's default completion will be performed
+if the compspec (and, if attempted, the default Bash completions)
+generate no matches.
+
+When a compspec indicates that directory name completion is desired,
+the programmable completion functions force Readline to append a slash
+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 new 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 -o bashdefault -o default
+@end example
+
+@node Programmable Completion Builtins
+@section Programmable Completion Builtins
+@cindex completion builtins
+
+Three builtin commands are available to manipulate the programmable completion
+facilities: one to specify how the arguments to a particular command are to
+be completed, and two to modify the completion as it is happening.
+
+@table @code
+@item compgen
+@btindex compgen
+@example
+@code{compgen [@var{option}] [@var{word}]}
+@end example
+
+Generate possible completion matches for @var{word} according to
+the @var{option}s, which may be any option accepted by the
+@code{complete}
+builtin with the exception of @option{-p} and @option{-r}, and write
+the matches to the standard output.
+When using the @option{-F} or @option{-C} options, the various shell variables
+set by the programmable completion facilities, while available, will not
+have useful values.
+
+The matches will be generated in the same way as if the programmable
+completion code had generated them directly from a completion specification
+with the same flags.
+If @var{word} is specified, only those completions matching @var{word}
+will be displayed.
+
+The return value is true unless an invalid option is supplied, or no
+matches were generated.
+
+@item complete
+@btindex complete
+@example
+@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.
+If the @option{-p} option is supplied, or if no options are supplied, existing
+completion specifications are printed in a way that allows them to be
+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}).  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
+(and, if necessary, the @option{-P} and @option{-S} options)
+should be quoted to protect them from expansion before the
+@code{complete} builtin is invoked.
+
+
+@table @code
+@item -o @var{comp-option}
+The @var{comp-option} controls several aspects of the compspec's behavior
+beyond the simple generation of completions.
+@var{comp-option} may be one of: 
+
+@table @code
+
+@item bashdefault
+Perform the rest of the default Bash completions if the compspec
+generates no matches.
+
+@item default
+Use Readline's default filename completion if the compspec generates
+no matches.
+
+@item dirnames
+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
+quoting special characters, or suppressing trailing spaces).
+This option is intended to be used with shell functions specified
+with @option{-F}.
+
+@item noquote
+Tell Readline not to quote the completed words if they are filenames
+(quoting filenames is the default).
+
+@item nosort
+Tell Readline not to sort the list of possible completions alphabetically.
+
+@item nospace
+Tell Readline not to append a space (the default) to words completed at
+the end of the line.
+
+@item plusdirs
+After any matches defined by the compspec are generated, 
+directory name completion is attempted and any
+matches are added to the results of the other actions.
+
+@end table
+
+@item -A @var{action}
+The @var{action} may be one of the following to generate a list of possible
+completions:
+
+@table @code
+@item alias
+Alias names.  May also be specified as @option{-a}.
+
+@item arrayvar
+Array variable names.
+
+@item binding
+Readline key binding names (@pxref{Bindable Readline Commands}).
+
+@item builtin
+Names of shell builtin commands.  May also be specified as @option{-b}.
+
+@item command
+Command names.  May also be specified as @option{-c}.
+
+@item directory
+Directory names.  May also be specified as @option{-d}.
+
+@item disabled
+Names of disabled shell builtins.
+
+@item enabled
+Names of enabled shell builtins.
+
+@item export
+Names of exported shell variables.  May also be specified as @option{-e}.
+
+@item file
+File names.  May also be specified as @option{-f}.
+
+@item function
+Names of shell functions.
+
+@item group
+Group names.  May also be specified as @option{-g}.
+
+@item helptopic
+Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}).
+
+@item hostname
+Hostnames, as taken from the file specified by the
+@env{HOSTFILE} shell variable (@pxref{Bash Variables}).
+
+@item job
+Job names, if job control is active.  May also be specified as @option{-j}.
+
+@item keyword
+Shell reserved words.  May also be specified as @option{-k}.
+
+@item running
+Names of running jobs, if job control is active.
+
+@item service
+Service names.  May also be specified as @option{-s}.
+
+@item setopt
+Valid arguments for the @option{-o} option to the @code{set} builtin
+(@pxref{The Set Builtin}).
+
+@item shopt
+Shell option names as accepted by the @code{shopt} builtin
+(@pxref{Bash Builtins}).
+
+@item signal
+Signal names.
+
+@item stopped
+Names of stopped jobs, if job control is active.
+
+@item user
+User names.  May also be specified as @option{-u}.
+
+@item variable
+Names of all shell variables.  May also be specified as @option{-v}.
+@end table
+
+@item -C @var{command}
+@var{command} is executed in a subshell environment, and its output is
+used as the possible completions.
+
+@item -F @var{function}
+The shell function @var{function} is executed in the current shell
+environment.
+When it is executed, $1 is the name of the command whose arguments are
+being completed, $2 is the word being completed, and $3 is the word
+preceding the word being completed, as described above
+(@pxref{Programmable Completion}).
+When it finishes, the possible completions are retrieved from the value
+of the @env{COMPREPLY} array variable.
+
+@item -G @var{globpat}
+The filename expansion pattern @var{globpat} is expanded to generate
+the possible completions.
+
+@item -P @var{prefix}
+@var{prefix} is added at the beginning of each possible completion
+after all other options have been applied.
+
+@item -S @var{suffix}
+@var{suffix} is appended to each possible completion
+after all other options have been applied.
+
+@item -W @var{wordlist}
+The @var{wordlist} is split using the characters in the
+@env{IFS} special variable as delimiters, and each resultant word
+is expanded.
+The possible completions are the members of the resultant list which
+match the word being completed.
+
+@item -X @var{filterpat}
+@var{filterpat} is a pattern as used for filename expansion.
+It is applied to the list of possible completions generated by the
+preceding options and arguments, and each completion matching
+@var{filterpat} is removed from the list.
+A leading @samp{!} in @var{filterpat} negates the pattern; in this
+case, any completion not matching @var{filterpat} is removed.
+@end table
+
+The return value is true unless an invalid option is supplied, an option
+other than @option{-p} or @option{-r} is supplied without a @var{name}
+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-executing 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
+
+@node A Programmable Completion Example
+@section A Programmable Completion Example
+
+The most common way to obtain additional completion functionality beyond
+the default actions @code{complete} and @code{compgen} provide is to use
+a shell function and bind it to a particular command using @code{complete -F}.
+
+The following function provides completions for the @code{cd} builtin.
+It is a reasonably good example of what shell functions must do when
+used for completion.  This function uses the word passsed as @code{$2}
+to determine the directory name to complete.  You can also use the
+@code{COMP_WORDS} array variable; the current word is indexed by the
+@code{COMP_CWORD} variable.
+
+The function relies on the @code{complete} and @code{compgen} builtins
+to do much of the work, adding only the things that the Bash @code{cd}
+does beyond accepting basic directory names:
+tilde expansion (@pxref{Tilde Expansion}),
+searching directories in @var{$CDPATH}, which is described above
+(@pxref{Bourne Shell Builtins}),
+and basic support for the @code{cdable_vars} shell option
+(@pxref{The Shopt Builtin}).
+@code{_comp_cd} modifies the value of @var{IFS} so that it contains only
+a newline to accommodate file names containing spaces and tabs --
+@code{compgen} prints the possible completions it generates one per line.
+
+Possible completions go into the @var{COMPREPLY} array variable, one
+completion per array element.  The programmable completion system retrieves
+the completions from there when the function returns.
+
+@example
+# A completion function for the cd builtin
+# based on the cd completion function from the bash_completion package
+_comp_cd()
+@{
+    local IFS=$' \t\n'    # normalize IFS
+    local cur _skipdot _cdpath
+    local i j k
+
+    # Tilde expansion, with side effect of expanding tilde to full pathname
+    case "$2" in
+    \~*)    eval cur="$2" ;;
+    *)      cur=$2 ;;
+    esac
+
+    # no cdpath or absolute pathname -- straight directory completion
+    if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then
+        # compgen prints paths one per line; could also use while loop
+        IFS=$'\n'
+        COMPREPLY=( $(compgen -d -- "$cur") )
+        IFS=$' \t\n'
+    # CDPATH+directories in the current directory if not in CDPATH
+    else
+        IFS=$'\n'
+        _skipdot=false
+        # preprocess CDPATH to convert null directory names to .
+        _cdpath=$@{CDPATH/#:/.:@}
+        _cdpath=$@{_cdpath//::/:.:@}
+        _cdpath=$@{_cdpath/%:/:.@}
+        for i in $@{_cdpath//:/$'\n'@}; do
+            if [[ $i -ef . ]]; then _skipdot=true; fi
+            k="$@{#COMPREPLY[@@]@}"
+            for j in $( compgen -d -- "$i/$cur" ); do
+                COMPREPLY[k++]=$@{j#$i/@}        # cut off directory
+            done
+        done
+        $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") )
+        IFS=$' \t\n'
+    fi
+
+    # variable names if appropriate shell option set and no completions
+    if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then
+        COMPREPLY=( $(compgen -v -- "$cur") )
+    fi
+
+    return 0
+@}
+@end example
+
+We install the completion function using the @option{-F} option to
+@code{complete}:
+
+@example
+# Tell readline to quote appropriate and append slashes to directories;
+# use the bash default completion for other arguments
+complete -o filenames -o nospace -o bashdefault -F _comp_cd cd
+@end example
+
+@noindent
+Since we'd like Bash and Readline to take care of some
+of the other details for us, we use several other options to tell Bash
+and Readline what to do.  The @option{-o filenames} option tells Readline
+that the possible completions should be treated as filenames, and quoted
+appropriately.  That option will also cause Readline to append a slash to
+filenames it can determine are directories (which is why we might want to
+extend @code{_comp_cd} to append a slash if we're using directories found
+via @var{CDPATH}: Readline can't tell those completions are directories).
+The @option{-o nospace} option tells Readline to not append a space
+character to the directory name, in case we want to append to it.
+The @option{-o bashdefault} option brings in the rest of the "Bash default"
+completions -- possible completion that Bash adds to the default Readline
+set.  These include things like command name completion, variable completion
+for words beginning with @samp{@{}, completions containing pathname
+expansion patterns (@pxref{Filename Expansion}), and so on.
+
+Once installed using @code{complete}, @code{_comp_cd} will be called every
+time we attempt word completion for a @code{cd} command.
+
+Many more examples -- an extensive collection of completions for most of
+the common GNU, Unix, and Linux commands -- are available as part of the
+bash_completion project.  This is installed by default on many GNU/Linux
+distributions.  Originally written by Ian Macdonald, the project now lives
+at @url{http://bash-completion.alioth.debian.org/}.  There are ports for
+other systems such as Solaris and Mac OS X.
+
+An older version of the bash_completion package is distributed with bash
+in the @file{examples/complete} subdirectory.
+
+@end ifset