--- embedaddon/readline/doc/readline.3	2014/07/30 08:16:45	1.1.1.1
+++ embedaddon/readline/doc/readline.3	2021/03/17 01:01:01	1.1.1.2
@@ -6,9 +6,9 @@
 .\"	Case Western Reserve University
 .\"	chet.ramey@case.edu
 .\"
-.\"	Last Change: Mon Jan  6 16:34:55 EST 2014
+.\"	Last Change: Tue Mar 24 09:27:30 EDT 2020
 .\"
-.TH READLINE 3 "2014 January 6" "GNU Readline 6.3"
+.TH READLINE 3 "2020 October 29" "GNU Readline 8.1"
 .\"
 .\" File Name macro.  This used to be `.PN', for Path Name,
 .\" but Sun doesn't seem to like that very much.
@@ -34,8 +34,8 @@ readline \- get a line from a user with editing
 \fBreadline\fP (\fIconst char *prompt\fP);
 .fi
 .SH COPYRIGHT
-.if n Readline is Copyright (C) 1989\-2011 Free Software Foundation,  Inc.
-.if t Readline is Copyright \(co 1989\-2011 Free Software Foundation, Inc.
+.if n Readline is Copyright (C) 1989\-2020 Free Software Foundation,  Inc.
+.if t Readline is Copyright \(co 1989\-2020 Free Software Foundation, Inc.
 .SH DESCRIPTION
 .LP
 .B readline
@@ -78,10 +78,10 @@ treated as a newline.
 .LP
 An Emacs-style notation is used to denote
 keystrokes.  Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
-means Control\-N.  Similarly, 
+means Control\-N.  Similarly,
 .I meta
 keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X.  (On keyboards
-without a 
+without a
 .I meta
 key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
 then the
@@ -98,14 +98,15 @@ Readline commands may be given numeric
 which normally act as a repeat count.  Sometimes, however, it is the
 sign of the argument that is significant.  Passing a negative argument
 to a command that acts in the forward direction (e.g., \fBkill\-line\fP)
-causes that command to act in a backward direction.  Commands whose
-behavior with arguments deviates from this are noted.
+causes that command to act in a backward direction.
+Commands whose behavior with arguments deviates from this are noted
+below.
 .PP
 When a command is described as \fIkilling\fP text, the text
 deleted is saved for possible future retrieval
 (\fIyanking\fP).  The killed text is saved in a
 \fIkill ring\fP.  Consecutive kills cause the text to be
-accumulated into one unit, which can be yanked all at once. 
+accumulated into one unit, which can be yanked all at once.
 Commands which do not kill text separate the chunks of text
 on the kill ring.
 .SH INITIALIZATION FILE
@@ -138,7 +139,7 @@ or
 C\-Meta\-u: universal\-argument
 .RE
 .sp
-into the 
+into the
 .I inputrc
 would make M\-C\-u execute the readline command
 .IR universal\-argument .
@@ -162,12 +163,11 @@ In addition to command names, readline allows keys to 
 to a string that is inserted when the key is pressed (a \fImacro\fP).
 .PP
 .SS Key Bindings
-.PP
 The syntax for controlling key bindings in the
 .I inputrc
 file is simple.  All that is required is the name of the
 command or the text of a macro and a key sequence to which
-it should be bound. The name may be specified in one of two ways:
+it should be bound.  The name may be specified in one of two ways:
 as a symbolic key name, possibly with \fIMeta\-\fP or \fIControl\-\fP
 prefixes, or as a key sequence.
 The name and key sequence are separated by a colon.  There can be no
@@ -225,7 +225,7 @@ is again bound to the function
 .I "C-x C-r"
 is bound to the function
 .BR re\-read\-init\-file ,
-and 
+and
 .I "ESC [ 1 1 ~"
 is bound to insert the text
 .if t \f(CWFunction Key 1\fP.
@@ -317,7 +317,6 @@ similar mechanisms.  The
 file may be edited and re-read if a program does not provide
 any other means to incorporate new bindings.
 .SS Variables
-.PP
 Readline has variables that can be used to further customize its
 behavior.  A variable may be set in the
 .I inputrc
@@ -347,13 +346,23 @@ If set to \fBnone\fP, readline never rings the bell.  
 If set to \fBaudible\fP, readline attempts to ring the terminal's bell.
 .TP
 .B bind\-tty\-special\-chars (On)
-If set to \fBOn\fP, readline attempts to bind the control characters  
-treated specially by the kernel's terminal driver to their readline
-equivalents.
+If set to \fBOn\fP (the default), readline attempts to bind the control
+characters   treated specially by the kernel's terminal driver to their
+readline equivalents.
 .TP
+.B blink\-matching\-paren (Off)
+If set to \fBOn\fP, readline attempts to briefly move the cursor to an
+opening parenthesis when a closing parenthesis is inserted.
+.TP
+.B colored\-completion\-prefix (Off)
+If set to \fBOn\fP, 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 \fBLS_COLORS\fP
+environment variable.
+.TP
 .B colored\-stats (Off)
 If set to \fBOn\fP, readline displays possible completions using different
-colors to indicate their file type.     
+colors to indicate their file type.
 The color definitions are taken from the value of the \fBLS_COLORS\fP
 environment variable.
 .TP
@@ -367,13 +376,13 @@ in emacs mode and to
 .B #
 in vi command mode.
 .TP
-.B completion\-display\-width (-1)
+.B completion\-display\-width (\-1)
 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.
+The default value is \-1.
 .TP 
 .B completion\-ignore\-case (Off)
 If set to \fBOn\fP, readline performs filename matching and completion
@@ -394,10 +403,11 @@ replaced with an ellipsis when displaying possible com
 This determines when the user is queried about viewing
 the number of possible completions
 generated by the \fBpossible\-completions\fP command.
-It may be set to any integer value greater than or equal to
-zero.  If the number of possible completions is greater than
-or equal to the value of this variable, the user is asked whether
-or not he wishes to view them; otherwise they are simply listed
+It may be set to any integer value greater than or equal to zero.
+If the number of possible completions is greater than
+or equal to the value of this variable,
+readline will ask whether or not the user wishes to view them;
+otherwise they are simply listed
 on the terminal.  A negative value causes readline to never ask.
 .TP
 .B convert\-meta (On)
@@ -405,12 +415,19 @@ If set to \fBOn\fP, readline will convert characters w
 eighth bit set to an ASCII key sequence
 by stripping the eighth bit and prefixing it with an
 escape character (in effect, using escape as the \fImeta prefix\fP).
+The default is \fIOn\fP, but readline will set it to \fIOff\fP if the
+locale contains eight-bit characters.
 .TP
 .B disable\-completion (Off)
 If set to \fBOn\fP, readline will inhibit word completion.  Completion 
 characters will be inserted into the line as if they had been
 mapped to \fBself-insert\fP.
 .TP
+.B echo\-control\-characters (On)
+When set to \fBOn\fP, on operating systems that indicate they support it,
+readline echoes a character corresponding to a signal generated from the
+keyboard.
+.TP
 .B editing\-mode (emacs)
 Controls whether readline begins with a set of key bindings similar
 to \fIEmacs\fP or \fIvi\fP.
@@ -420,11 +437,23 @@ can be set to either
 or
 .BR vi .
 .TP
-.B echo\-control\-characters (On)
-When set to \fBOn\fP, on operating systems that indicate they support it,
-readline echoes a character corresponding to a signal generated from the
-keyboard.
+.B emacs\-mode\-string (@)
+If the \fIshow\-mode\-in\-prompt\fP variable is enabled, 
+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 \e1 and \e2 escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control 
+sequence into the mode string.
 .TP
+.B enable\-bracketed\-paste (On)
+When set to \fBOn\fP, 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.
+.TP
 .B enable\-keypad (Off)
 When set to \fBOn\fP, readline will try to enable the application
 keypad when it is called.  Some systems need this to enable the
@@ -444,18 +473,21 @@ If set to \fBOn\fP, the history code attempts to place
 same location on each history line retrieved with \fBprevious-history\fP 
 or \fBnext-history\fP.
 .TP
-.B history\-size (0)
+.B history\-size (unset)
 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 \fIhistory\-size\fP to a non-numeric value,
+the maximum number of history entries will be set to 500.
 .TP
 .B horizontal\-scroll\-mode (Off)
 When set to \fBOn\fP, makes readline use a single line for display,
 scrolling the input horizontally on a single screen line when it
 becomes longer than the screen width rather than wrapping to a new line.
+This setting is automatically enabled for terminals of height 1.
 .TP
 .B input\-meta (Off)
 If set to \fBOn\fP, readline will enable eight-bit input (that is,
@@ -463,6 +495,8 @@ it will not clear the eighth bit in the characters it 
 regardless of what the terminal claims it can support.  The name
 .B meta\-flag
 is a synonym for this variable.
+The default is \fIOff\fP, but readline will set it to \fIOn\fP if the 
+locale contains eight-bit characters.
 .TP
 .B isearch\-terminators (``C\-[ C\-J'')
 The string of characters that should terminate an incremental
@@ -510,7 +544,7 @@ have a slash appended (subject to the value of
 .TP
 .B match\-hidden\-files (On)
 This variable, when set to \fBOn\fP, causes readline to match files whose 
-names begin with a `.' (hidden files) when performing filename     
+names begin with a `.' (hidden files) when performing filename
 completion.
 If set to \fBOff\fP, the leading `.' must be
 supplied by the user in the filename to be completed.
@@ -524,6 +558,8 @@ the list.
 If set to \fBOn\fP, readline will display characters with the
 eighth bit set directly rather than as a meta-prefixed escape
 sequence.
+The default is \fIOff\fP, but readline will set it to \fIOn\fP if the
+locale contains eight-bit characters.
 .TP
 .B page\-completions (On)
 If set to \fBOn\fP, readline uses an internal \fImore\fP-like pager
@@ -557,9 +593,9 @@ a common prefix) cause the matches to be listed immedi
 of ringing the bell.
 .TP
 .B show\-mode\-in\-prompt (Off)
-If set to \fBOn\fP, add a character to the beginning of the prompt
-indicating the editing mode: emacs (@), vi command (:) or vi      
-insertion (+).
+If set to \fBOn\fP, add a string to the beginning of the prompt
+indicating the editing mode: emacs, vi command, or vi insertion.
+The mode strings are user-settable (e.g., \fIemacs\-mode\-string\fP).
 .TP
 .B skip\-completed\-text (Off)
 If set to \fBOn\fP, this alters the default completion behavior when
@@ -569,24 +605,46 @@ does not insert characters from the completion that ma
 after point in the word being completed, so portions of the word
 following the cursor are not duplicated.
 .TP
+.B vi\-cmd\-mode\-string ((cmd))
+If the \fIshow\-mode\-in\-prompt\fP variable is enabled, 
+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 \e1 and \e2 escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control
+sequence into the mode string.
+.TP
+.B vi\-ins\-mode\-string ((ins))
+If the \fIshow\-mode\-in\-prompt\fP variable is enabled, 
+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 \e1 and \e2 escapes to begin and end sequences of
+non-printing characters, which can be used to embed a terminal control 
+sequence into the mode string.
+.TP
 .B visible\-stats (Off)
 If set to \fBOn\fP, a character denoting a file's type as reported  
 by \fIstat\fP(2) is appended to the filename when listing possible
 completions.
 .PD
 .SS Conditional Constructs
-.PP
 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.
 .IP \fB$if\fP
-The 
+The
 .B $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.
+readline.  The text of the test, after any comparison operator,
+extends to the end of the line;
+unless otherwise noted, no characters are required to isolate it.
 .RS
 .IP \fBmode\fP
 The \fBmode=\fP form of the \fB$if\fP directive is used to test
@@ -608,6 +666,26 @@ to match both
 and
 .IR sun\-cmd ,
 for instance.
+.IP \fBversion\fP
+The \fBversion\fP test may be used to perform comparisons against
+specific readline versions.
+The \fBversion\fP expands to the current readline version.
+The set of comparison operators includes
+.BR = ,
+(and
+.BR == ),
+.BR != ,
+.BR <= ,
+.BR >= ,
+.BR < ,
+and
+.BR > .
+The version number supplied on the right side of the operator consists
+of a major version number, an optional decimal point, and an optional
+minor version (e.g., \fB7.1\fP). If the minor version is omitted, it
+is assumed to be \fB0\fP.
+The operator may be separated from the string \fBversion\fP
+and from the version number argument by whitespace.
 .IP \fBapplication\fP
 The \fBapplication\fP construct is used to include
 application-specific settings.  Each program using the readline
@@ -625,6 +703,15 @@ key sequence that quotes the current or previous word 
 \fB$endif\fP
 .fi
 .RE
+.IP \fIvariable\fP
+The \fIvariable\fP construct provides simple equality tests for readline
+variables and values.
+The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP.
+The variable name must be separated from the comparison operator by
+whitespace; the operator may be separated from the value on the right hand
+side by whitespace.
+Both string and boolean variables may be tested. Boolean variables must be
+tested against the values \fIon\fP and \fIoff\fP.
 .RE
 .IP \fB$endif\fP
 This command, as seen in the previous example, terminates an
@@ -643,7 +730,6 @@ would read \fI/etc/inputrc\fP:
 .fi 
 .RE
 .SH SEARCHING
-.PP
 Readline provides commands for searching through the command history
 for lines containing a specified string.
 There are two search modes:
@@ -683,7 +769,6 @@ Non-incremental searches read the entire search string
 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.
 .SH EDITING COMMANDS
-.PP
 The following is a list of the names of the commands and the default
 key sequences to which they are bound.
 Command names without an accompanying key sequence are unbound by default.
@@ -693,7 +778,6 @@ position, and \fImark\fP refers to a cursor position s
 \fBset\-mark\fP command.
 The text between the point and mark is referred to as the \fIregion\fP.
 .SS Commands for Moving
-.PP
 .PD 0
 .TP
 .B beginning\-of\-line (C\-a)
@@ -716,8 +800,28 @@ alphanumeric characters (letters and digits).
 Move back to the start of the current or previous word.  Words are
 composed of alphanumeric characters (letters and digits).
 .TP
+.B previous\-screen\-line
+Attempt to move point to the same physical screen column on the previous
+physical screen line. This will not have the desired effect if the current
+Readline line does not take up more than one physical line or if point is not
+greater than the length of the prompt plus the screen width.
+.TP
+.B next\-screen\-line
+Attempt to move point to the same physical screen column on the next
+physical screen line. This will not have the desired effect if the current
+Readline line does not take up more than one physical line or if the length
+of the current Readline line is not greater than the length of the prompt
+plus the screen width.
+.TP
+.B clear\-display (M\-C\-l)
+Clear the screen and, if possible, the terminal's scrollback buffer,
+then redraw the current line,
+leaving the current line at the top of the screen.
+.TP
 .B clear\-screen (C\-l)
-Clear the screen leaving the current line at the top of the screen.
+Clear the screen,
+then redraw the current line,
+leaving the current line at the top of the screen.
 With an argument, refresh the current line without clearing the
 screen.
 .TP
@@ -725,7 +829,6 @@ screen.
 Refresh the current line.
 .PD
 .SS Commands for Manipulating the History
-.PP
 .PD 0
 .TP
 .B accept\-line (Newline, Return)
@@ -816,9 +919,17 @@ the direction to move through the history.  A negative
 the direction through the history (back or forward).
 The history expansion facilities are used to extract the last argument,
 as if the "!$" history expansion had been specified.
+.TP
+.B
+operate\-and\-get\-next (C\-o)
+Accept the current line for return to the calling application as if a
+newline had been entered,
+and fetch the next line relative to the current line from the history
+for editing.
+A numeric argument, if supplied, specifies the history entry to use instead
+of the current line.
 .PD
 .SS Commands for Changing Text
-.PP
 .PD 0
 .TP
 .B \fIend\-of\-file\fP (usually C\-d)
@@ -887,13 +998,12 @@ switches to overwrite mode.  With an explicit non-posi
 argument, switches to insert mode.  This command affects only
 \fBemacs\fP mode; \fBvi\fP mode does overwrite differently.
 Each call to \fIreadline()\fP starts in insert mode.
-In overwrite mode, characters bound to \fBself\-insert\fP replace   
+In overwrite mode, characters bound to \fBself\-insert\fP replace
 the text at point rather than pushing the text to the right.
 Characters bound to \fBbackward\-delete\-char\fP replace the character
 before point with a space.  By default, this command is unbound.
 .PD
 .SS Killing and Yanking
-.PP
 .PD 0
 .TP
 .B kill\-line (C\-k)
@@ -910,7 +1020,7 @@ The killed text is saved on the kill-ring.
 .B kill\-whole\-line
 Kill all characters on the current line, no matter where point is.
 .TP
-.B kill\-word  (M\-d)
+.B kill\-word (M\-d)
 Kill from point 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 \fBforward\-word\fP.
@@ -956,7 +1066,6 @@ or
 .BR yank\-pop .
 .PD
 .SS Numeric Arguments
-.PP
 .PD 0
 .TP
 .B digit\-argument (M\-0, M\-1, ..., M\-\-)
@@ -978,7 +1087,6 @@ first time makes the argument count four, a second tim
 argument count sixteen, and so on.
 .PD
 .SS Completing
-.PP
 .PD 0
 .TP
 .B complete (TAB)
@@ -1035,7 +1143,6 @@ If at the end of the line, behaves identically to
 \fBpossible-completions\fP.
 .PD
 .SS Keyboard Macros
-.PP
 .PD 0
 .TP
 .B start\-kbd\-macro (C\-x (\^)
@@ -1048,12 +1155,12 @@ and store the definition.
 .B call\-last\-kbd\-macro (C\-x e)
 Re-execute the last keyboard macro defined, by making the characters
 in the macro appear as if typed at the keyboard.
+.TP
 .B print\-last\-kbd\-macro ()
 Print the last keyboard macro defined in a format suitable for the
 \fIinputrc\fP file.
 .PD
 .SS Miscellaneous
-.PP
 .PD 0
 .TP
 .B re\-read\-init\-file (C\-x C\-r)
@@ -1065,9 +1172,10 @@ Abort the current editing command and
 ring the terminal's bell (subject to the setting of
 .BR bell\-style ).
 .TP
-.B do\-uppercase\-version (M\-a, M\-b, M\-\fIx\fP, ...)
-If the metafied character \fIx\fP is lowercase, run the command
-that is bound to the corresponding uppercase character.
+.B do\-lowercase\-version (M\-A, M\-B, M\-\fIx\fP, ...)
+If the metafied character \fIx\fP is uppercase, run the command
+that is bound to the corresponding metafied lowercase character.
+The behavior is undefined if \fIx\fP is already lowercase.
 .TP
 .B prefix\-meta (ESC)
 Metafy the next character typed.
@@ -1117,7 +1225,7 @@ but usually bound to ESC\-[.
 Without a numeric argument, the value of the readline
 .B 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
+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 \fBcomment\-begin\fP, the value is inserted, otherwise             
 the characters in \fBcomment-begin\fP are deleted from the beginning of
@@ -1228,6 +1336,7 @@ Emacs Meta bindings
 "M-C-H"  backward-kill-word
 "M-C-I"  tab-insert
 "M-C-J"  vi-editing-mode
+"M-C-L"  clear-display
 "M-C-M"  vi-editing-mode
 "M-C-R"  revert-line
 "M-C-Y"  yank-nth-arg
@@ -1432,5 +1541,4 @@ Comments and bug reports concerning
 this manual page should be directed to
 .IR chet.ramey@case.edu .
 .SH BUGS
-.PP
 It's too big and too slow.