1 files changed, 161 insertions, 92 deletions

diff --git a/gnu/lib/libreadline/doc/rluser.texinfo b/gnu/lib/libreadline/doc/rluser.texinfo
index ea2020503515..67fe64e57dd3 100644
--- a/gnu/lib/libreadline/doc/rluser.texinfo
+++ b/gnu/lib/libreadline/doc/rluser.texinfo
@@ -1,9 +1,3 @@
-@comment %**start of header (This is for running Texinfo on a region.)
-@setfilename rluser.info
-@synindex fn vr
-@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
 editing feautres.  It is to be an appendix to manuals for programs which
@@ -35,7 +29,7 @@ into another language, under the above conditions for modified versions.
 @end ignore
 
 @node Command Line Editing
-@chapter Command Line Editing
+@appendix Command Line Editing
 
 This text describes GNU's command line editing interface.
 
@@ -48,7 +42,8 @@ This text describes GNU's command line editing interface.
 @node Introduction and Notation
 @section Introduction to Line Editing
 
-In this tex a the following notation is used to describe keystrokes.
+The following paragraphs describe the notation we use to represent
+keystrokes.
 
 The text @key{C-k} is read as `Control-K' and describes the character
 produced when the Control key is depressed and the @key{k} key is struck.
@@ -156,10 +151,6 @@ operate on characters while meta keystrokes operate on words.
 @node Readline Killing Commands
 @subsection Readline Killing Commands
 
-The act of @dfn{cutting} text means to delete the text from the line, and
-to save away the deleted text for later use, just as if you had cut the
-text out of the line with a pair of scissors.  There is a
-
 @dfn{Killing} text means to delete the text from the line, but to save
 it away for later use, usually by @dfn{yanking} it back into the line.
 If the description for a command says that it `kills' text, then you can
@@ -177,7 +168,8 @@ Kill from the cursor to the end of the current word, or if between
 words, to the end of the next word.
 
 @item M-DEL
-Kill fromthe cursor the start ofthe previous word, or if between words, to the start of the previous word.
+Kill from the cursor to the start of the previous word, or if between
+words, to the start of the previous word. 
 
 @item C-w
 Kill from the cursor to the previous whitespace.  This is different than
@@ -234,6 +226,9 @@ file is @file{~/.inputrc}.
 When a program which uses the Readline library starts up, the
 @file{~/.inputrc} file is read, and the keybindings are set.
 
+In addition, the @key{C-x C-r} command re-reads this init file, thus
+incorporating any changes that you might have made to it.
+
 @menu
 * Readline Init Syntax::	Syntax for the commands in @file{~/.inputrc}.
 * Readline Vi Mode::		Switching to @code{vi} mode in Readline.
@@ -242,38 +237,99 @@ When a program which uses the Readline library starts up, the
 @node Readline Init Syntax
 @subsection Readline Init Syntax
 
-You can start up with a vi-like editing mode by placing
+There are only four constructs allowed in the @file{~/.inputrc}
+file:
+
+@table @asis
+@item Variable Settings
+You can change the state of a few variables in Readline.  You do this by
+using the @code{set} command within the init file.  Here is how you
+would specify that you wish to use Vi line editing commands:
 
 @example
-@code{set editing-mode vi}
+set editing-mode vi
 @end example
 
-in your @file{~/.inputrc} file.
+Right now, there are only a few variables which can be set; so few in
+fact, that we just iterate them here:
 
-You can have Readline use a single line for display, scrolling the input
-between the two edges of the screen by placing
+@table @code
 
-@example
-@code{set horizontal-scroll-mode On}
-@end example
+@item editing-mode
+@vindex editing-mode
+The @code{editing-mode} variable controls which editing mode you are
+using.  By default, GNU Readline starts up in Emacs editing mode, where
+the keystrokes are most similar to Emacs.  This variable can either be
+set to @code{emacs} or @code{vi}.
+
+@item horizontal-scroll-mode
+@vindex horizontal-scroll-mode
+This variable can either be set to @code{On} or @code{Off}.  Setting it
+to @code{On} means that the text of the lines that you edit will scroll
+horizontally on a single screen line when they are larger than the width
+of the screen, instead of wrapping onto a new screen line.  By default,
+this variable is set to @code{Off}.
+
+@item mark-modified-lines
+@vindex mark-modified-lines
+This variable when set to @code{On}, says to display an asterisk
+(@samp{*}) at the starts of history lines which have been modified.
+This variable is off by default.
 
-in your @file{~/.inputrc} file.
+@item prefer-visible-bell
+@vindex prefer-visible-bell
+If this variable is set to @code{On} it means to use a visible bell if
+one is available, rather than simply ringing the terminal bell.  By
+default, the value is @code{Off}.
+@end table
 
+@item Key Bindings
 The syntax for controlling keybindings in the @file{~/.inputrc} file is
 simple.  First you have to know the @i{name} of the command that you
-want to change.  The following pages contain tables of the command name, the
-default keybinding, and a short description of what the command does.
+want to change.  The following pages contain tables of the command name,
+the default keybinding, and a short description of what the command
+does.
 
 Once you know the name of the command, simply place the name of the key
 you wish to bind the command to, a colon, and then the name of the
-command on a line in the @file{~/.inputrc} file.  Here is an example:
+command on a line in the @file{~/.inputrc} file.  The name of the key
+can be expressed in different ways, depending on which is most
+comfortable for you.
+
+@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, @key{C-u} is bound to the function
+@code{universal-argument}, and @key{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).
+
+@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.  Simply place the key sequence
+in double quotes.  GNU Emacs style key escapes can be used, as in the
+following example:
 
 @example
-# This is a comment line.
-Meta-Rubout:	backward-kill-word
-Control-u:	universal-argument
+"\C-u": universal-argument
+"\C-x\C-r": re-read-init-file
+"\e[11~": "Function Key 1"
 @end example
 
+In the above example, @key{C-u} is bound to the function
+@code{universal-argument} (just as it was in the first example),
+@key{C-x C-r} is bound to the function @code{re-read-init-file}, and
+@key{ESC [ 1 1 ~} is bound to insert the text @samp{Function Key 1}.
+
+@end table
+@end table
+
 @menu
 * Commands For Moving::		Moving about the line.
 * Commands For History::	Getting at previous lines.
@@ -286,159 +342,159 @@ Control-u:	universal-argument
 
 @node Commands For Moving
 @subsubsection Commands For Moving
-@table @code
-@item beginning-of-line (C-a)
+@ftable @code
+@item beginning-of-line (@key{C-a})
 Move to the start of the current line.
 
-@item end-of-line (C-e)
+@item end-of-line (@key{C-e})
 Move to the end of the line.
 
-@item forward-char (C-f)
+@item forward-char (@key{C-f})
 Move forward a character.
 
-@item backward-char (C-b)
+@item backward-char (@key{C-b})
 Move back a character.
 
-@item forward-word (M-f)
+@item forward-word (@key{M-f})
 Move forward to the end of the next word.
 
-@item backward-word (M-b)
+@item backward-word (@key{M-b})
 Move back to the start of this, or the previous, word.
 
-@item clear-screen (C-l)
+@item clear-screen (@key{C-l})
 Clear the screen leaving the current line at the top of the screen.
 
-@end table
+@end ftable
 
 @node Commands For History
 @subsubsection Commands For Manipulating The History
 
-@table @code
+@ftable @code
 @item accept-line (Newline, Return)
 Accept the line regardless of where the cursor is.  If this line is
-non-empty, add it too the history list.  If this line was a history
+non-empty, add it to the history list.  If this line was a history
 line, then restore the history line to its original state.
 
-@item previous-history (C-p)
+@item previous-history (@key{C-p})
 Move `up' through the history list.
 
-@item next-history (C-n)
+@item next-history (@key{C-n})
 Move `down' through the history list.
 
-@item beginning-of-history (M-<)
+@item beginning-of-history (@key{M-<})
 Move to the first line in the history.
 
-@item end-of-history (M->)
+@item end-of-history (@key{M->})
 Move to the end of the input history, i.e., the line you are entering!
 
-@item reverse-search-history (C-r)
+@item reverse-search-history (@key{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)
+@item forward-search-history (@key{C-s})
 Search forward starting at the current line and moving `down' through
 the the history as neccessary.
 
-@end table
+@end ftable
 
 @node Commands For Text
 @subsubsection Commands For Changing Text
 
-@table @code
-@item delete-char (C-d)
+@ftable @code
+@item delete-char (@key{C-d})
 Delete the character under the cursor.  If the cursor is at the
 beginning of the line, and there are no characters in the line, and
-the last character typed was not C-d, then return EOF.
+the last character typed was not @key{C-d}, then return EOF.
 
 @item backward-delete-char (Rubout)
 Delete the character behind the cursor.  A numeric arg says to kill
 the characters instead of deleting them.
 
-@item quoted-insert (C-q, C-v)
+@item quoted-insert (@key{C-q}, @key{C-v})
 Add the next character that you type to the line verbatim.  This is
-how to insert things like C-q for example.
+how to insert things like @key{C-q} for example.
 
-@item tab-insert (M-TAB)
+@item tab-insert (@key{M-TAB})
 Insert a tab character.
 
 @item self-insert (a, b, A, 1, !, ...)
 Insert yourself.
 
-@item transpose-chars (C-t)
+@item transpose-chars (@key{C-t})
 Drag the character before point forward over the character at point.
 Point moves forward as well.  If point is at the end of the line, then
 transpose the two characters before point.  Negative args don't work.
 
-@item transpose-words (M-t)
+@item transpose-words (@key{M-t})
 Drag the word behind the cursor past the word in front of the cursor
 moving the cursor over that word as well.
 
-@item upcase-word (M-u)
-Uppercase the current (or following) word.  With a negative argument,
-do the previous word, but do not move point.
+@item upcase-word (@key{M-u})
+Uppercase all letters in the current (or following) word.  With a
+negative argument, do the previous word, but do not move point.
 
-@item downcase-word (M-l)
-Lowercase the current (or following) word.  With a negative argument,
-do the previous word, but do not move point.
+@item downcase-word (@key{M-l})
+Lowercase all letters in the current (or following) word.  With a
+negative argument, do the previous word, but do not move point.
 
-@item capitalize-word (M-c)
-Uppercase the current (or following) word.  With a negative argument,
-do the previous word, but do not move point.
+@item capitalize-word (@key{M-c})
+Uppercase the first letter in the current (or following) word.  With a
+negative argument, do the previous word, but do not move point.
 
-@end table
+@end ftable
 
 @node Commands For Killing
 @subsubsection Killing And Yanking
 
-@table @code
+@ftable @code
 
-@item kill-line (C-k)
+@item kill-line (@key{C-k})
 Kill the text from the current cursor position to the end of the line.
 
 @item backward-kill-line ()
 Kill backward to the beginning of the line.  This is normally unbound.
 
-@item kill-word (M-d)
+@item kill-word (@key{M-d})
 Kill from the cursor to the end of the current word, or if between
 words, to the end of the next word.
 
-@item backward-kill-word (M-DEL)
+@item backward-kill-word (@key{M-DEL})
 Kill the word behind the cursor.
 
-@item unix-line-discard (C-u)
-Do what C-u used to do in Unix line input.  We save the killed text on
+@item unix-line-discard (@key{C-u})
+Do what @key{C-u} used to do in Unix line input.  We save the killed text on
 the kill-ring, though.
 
-@item unix-word-rubout (C-w)
-Do what C-w used to do in Unix line input.  The killed text is saved
+@item unix-word-rubout (@key{C-w})
+Do what @key{C-w} used to do in Unix line input.  The killed text is saved
 on the kill-ring.  This is different than backward-kill-word because
 the word boundaries differ.
 
-@item yank (C-y)
+@item yank (@key{C-y})
 Yank the top of the kill ring into the buffer at point.
 
-@item yank-pop (M-y)
+@item yank-pop (@key{M-y})
 Rotate the kill-ring, and yank the new top.  You can only do this if
 the prior command is yank or yank-pop.
-@end table
+@end ftable
 
 @node Numeric Arguments
 @subsubsection Specifying Numeric Arguments
-@table @code
+@ftable @code
 
-@item digit-argument (M-0, M-1, ... M--)
+@item digit-argument (@key{M-0}, @key{M-1}, ... @key{M--})
 Add this digit to the argument already accumulating, or start a new
-argument.  M-- starts a negative argument.
+argument.  @key{M--} starts a negative argument.
 
 @item universal-argument ()
-Do what C-u does in emacs.  By default, this is not bound.
-@end table
+Do what @key{C-u} does in emacs.  By default, this is not bound.
+@end ftable
 
 
 @node Commands For Completion
 @subsubsection Letting Readline Type For You
 
-@table @code
+@ftable @code
 @item complete (TAB)
 Attempt to do completion on the text before point.  This is
 implementation defined.  Generally, if you are typing a filename
@@ -449,41 +505,54 @@ you can do variable name completion...
 
 @item possible-completions (M-?)
 List the possible completions of the text before point.
-@end table
+@end ftable
 
 @node Miscellaneous Commands
 @subsubsection Some Miscellaneous Commands
-@table @code
+@ftable @code
+
+@item re-read-init-file (@key{C-x} @key{C-r})
+Read in the contents of your @file{~/.inputrc} file, and incorporate
+any bindings found there.
 
-@item abort (C-g)
-Ding!  Stops things.
+@item abort (@key{C-g})
+Stop running the current editing command.
 
-@item do-uppercase-version (M-a, M-b, ...)
+@ignore
+@c I have no idea what this means, and can't figure it out by
+@c experiment, and can't find it in the readline source.
+@c pesch@cygnus.com, 20may1993.
+@item do-uppercase-version (@key{M-a}, @key{M-b}, ...)
 Run the command that is bound to your uppercase brother.
+@end ignore
 
 @item prefix-meta (ESC)
-Make the next character that you type be metafied.  This is for
-people without a meta key.  @key{ESC-f} is equivalent to @key{M-f}.
+Make the next character that you type be metafied.  This is for people
+without a meta key.  Typing @key{ESC f} is equivalent to typing
+@key{M-f}.
 
-@item undo (C-_)
+@item undo (@key{C-_})
 Incremental undo, separately remembered for each line.
 
-@item revert-line (M-r)
+@item revert-line (@key{M-r})
 Undo all changes made to this line.  This is like typing the `undo'
 command enough times to get back to the beginning.
-@end table
+@end ftable
 
 @node Readline Vi Mode
 @subsection Readline Vi Mode
 
+@cindex @code{vi} style command editing
+@kindex toggle-editing-mode
 While the Readline library does not have a full set of Vi editing
 functions, it does contain enough to allow simple editing of the line.
 
 In order to switch interactively between Emacs and Vi editing modes, use
-the command M-C-j (toggle-editing-mode).
+the command @key{M-C-j} (toggle-editing-mode).
 
 When you enter a line in Vi mode, you are already placed in `insertion'
 mode, as if you had typed an `i'.  Pressing @key{ESC} switches you into
 `edit' mode, where you can edit the text of the line with the standard
 Vi movement keys, move to previous history lines with `k', and following
 lines with `j', and so forth.
+