Next:Command Line Editing [Contents]
This document describes the end user interface of the GNU Readline Library,a utility which aids in the consistency of user interface across discreteprograms which provide a command line interface.The Readline home page ishttp://www.gnu.org/software/readline/.
Next:GNU Free Documentation License, Previous:GNU Readline Library, Up:GNU Readline Library [Contents]
This chapter describes the basic features of theGNUcommand line editing interface.
Next:Readline Interaction, Up:Command Line Editing [Contents]
The following paragraphs use Emacs style todescribe the notation used to represent keystrokes.
The textC-k is read as ‘Control-K’ and describes the characterproduced when thek key is pressed while the Control keyis depressed.
The textM-k is read as ‘Meta-K’ and describes the characterproduced when the Meta key (if you have one) is depressed, and thekkey is pressed (ameta character), then both are released.The Meta key is labeledALT orOption on many keyboards.On keyboards with two keys labeledALT (usually to either side ofthe space bar), theALT on the left side is generally set towork as a Meta key.One of theALT keys may also be configuredas some other modifier, such as aCompose key for typing accented characters.
On some keyboards, the Meta key modifier produces characters withthe eighth bit (0200) set.You can use theenable-meta-key variableto control whether or not it does this, if the keyboard allows it.On many others, the terminal or terminal emulator converts the metafiedkey to a key sequence beginning withESC as described in thenext paragraph.
If you do not have a Meta orALT key, or another key working asa Meta key, you can generally achieve the latter effect by typingESCfirst, and then typingk.TheESC character is known as themeta prefix).
Either process is known asmetafying thek key.
If your Meta key produces a key sequence with theESC meta prefix,you can makeM-key key bindings you specify(seeKey Bindings inReadline Init File Syntax)do the same thing by setting theforce-meta-prefix variable.
The textM-C-k is read as ‘Meta-Control-k’ and describes thecharacter produced by metafyingC-k.
In addition, several keys have their own names.Specifically,DEL,ESC,LFD,SPC,RET, andTAB allstand for themselves when seen in this text, or in an init file(seeReadline Init File).If your keyboard lacks aLFD key, typingC-j willoutput the appropriate character.TheRET key may be labeledReturn orEnter onsome keyboards.
Next:Readline Init File, Previous:Introduction to Line Editing, Up:Command Line Editing [Contents]
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 textas you type it in, allowing you to just fix your typo, and not forcingyou to retype the majority of the line.Using these editing commands,you move the cursor to the place that needs correction, and delete orinsert the text of the corrections.Then, when you are satisfied with the line, you simply pressRET.You do not have to be at theend of the line to pressRET; the entire line is acceptedregardless of the location of the cursor within the line.
In order to enter characters into the line, simply type them.The typedcharacter appears where the cursor was, and then the cursor moves onespace to the right.If you mistype a character, you can use yourerase character to back up and delete the mistyped character.
Sometimes you may mistype a character, andnot notice the error until you have typed several other characters.In that case, you can typeC-b to move the cursor to the left,and then correct your mistake.Afterwards, you can move the cursor to the right withC-f.
When you add text in the middle of a line, you will notice that charactersto the right of the cursor are ‘pushed over’ to make room for the textthat you have inserted.Likewise, when you delete text behind the cursor,characters to the right of the cursor are ‘pulled back’ to fill in theblank space created by the removal of the text.These are the bareessentials for editing the text of an input line:
Move back one character.
Move forward one character.
Delete the character to the left of the cursor.
Delete the character underneath the cursor.
Insert the character into the line at the cursor.
Undo the last editing command.You can undo all the way back to an empty line.
Depending on your configuration, theBackspace key might be set todelete the character to the left of the cursor and theDEL key setto delete the character underneath the cursor, likeC-d, ratherthan the character to the left of the cursor.
Next:Readline Killing Commands, Previous:Readline Bare Essentials, Up:Readline Interaction [Contents]
The above table describes the most basic keystrokes that you needin order to do editing of the input line.For your convenience, many other commands are available inaddition toC-b,C-f,C-d, andDEL.Here are some commands for moving more rapidly within the line.
Move to the start of the line.
Move to the end of the line.
Move forward a word, where a word is composed of letters and digits.
Move backward a word.
Clear the screen, reprinting the current line at the top.
Notice howC-f moves forward a character, whileM-f movesforward a word.It is a loose convention that control keystrokesoperate on characters while meta keystrokes operate on words.
Next:Readline Arguments, Previous:Readline Movement Commands, Up:Readline Interaction [Contents]
Killing text means to delete the text from the line, but to saveit away for later use, usually byyanking (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 canbe 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 akill-ring.Any number of consecutive kills save all of the killed text together, sothat when you yank it back, you get it all.The kill ring is not line specific; the text that you killed on a previouslytyped line is available to be yanked back later, when you are typinganother line.
Here is the list of commands for killing text.
Kill the text from the current cursor position to the end of the line.
Kill from the cursor to the end of the current word, or, if betweenwords, to the end of the next word.Word boundaries are the same as those used byM-f.
Kill from the cursor to the start of the current word, or, if betweenwords, to the start of the previous word.Word boundaries are the same as those used byM-b.
Kill from the cursor to the previous whitespace.This is different thanM-DEL because the word boundaries differ.
Here is how toyank the text back into the line. Yankingmeans to copy the most-recently-killed text from the kill bufferinto the line at the current cursor position.
Yank the most recently killed text back into the buffer at the cursor.
Rotate the kill-ring, and yank the new top.You can only do this if the prior command isC-y orM-y.
Next:Searching for Commands in the History, Previous:Readline Killing Commands, Up:Readline Interaction [Contents]
You can pass numeric arguments to Readline commands.Sometimes theargument acts as a repeat count, other times it is thesign of theargument that is significant.If you pass a negative argument to acommand which normally acts in a forward direction, that command willact in a backward direction.For example, to kill text back to thestart of the line, you might type ‘M-- C-k’.
The general way to pass numeric arguments to a command is to type metadigits before the command.If the first ‘digit’ typed is a minussign (‘-’), then the sign of the argument will be negative.Once you have typed one meta digit to get the argument started, you cantype the remainder of the digits, and then the command.For example, to givetheC-d command an argument of 10, you could type ‘M-1 0 C-d’,which will delete the next ten characters on the input line.
Previous:Readline Arguments, Up:Readline Interaction [Contents]
Readline provides commands for searching through the command historyfor lines containing a specified string.There are two search modes:incremental andnon-incremental.
Incremental searches begin before the user has finished typing thesearch string.As each character of the search string is typed, Readline displaysthe next entry from the history matching the string typed so far.An incremental search requires only as many characters as needed tofind the desired history entry.When using emacs editing mode, typeC-rto search backward in the history for a particular string.TypingC-s searches forward through the history.The characters present in the value of theisearch-terminators variableare used to terminate an incremental search.If that variable has not been assigned a value, theESC andC-j characters terminate an incremental search.C-g aborts an incremental search and restores the original line.When the search is terminated, the history entry containing thesearch string becomes the current line.
To find other matching entries in the history list, typeC-r orC-s as appropriate.This searches backward or forward in the history for the nextentry matching the search string typed so far.Any other key sequence bound to a Readline command terminatesthe search and executes that command.For instance, aRET terminates the search and acceptsthe line, thereby executing the command from the history list.A movement command will terminate the search, make the last line foundthe current line, and begin editing.
Readline remembers the last incremental search string.If twoC-rs are typed without any intervening characters defininga new search string, Readline uses any remembered search string.
Non-incremental searches read the entire search string before startingto search for matching history entries.The search string may be typed by the user or be part of the contents ofthe current line.
Next:Bindable Readline Commands, Previous:Readline Interaction, Up:Command Line Editing [Contents]
Although the Readline library comes with a set of Emacs-likekeybindings installed by default, it is possible to use a different setof keybindings.Any user can customize programs that use Readline by puttingcommands in aninputrc file, conventionally in their home directory.The name of this file is taken from the value of theenvironment variableINPUTRC.If that variable is unset, the default is~/.inputrc.If that file does not exist or cannot be read, Readline looks for/etc/inputrc.
When a program that uses the Readline library starts up, Readline readsthe init file and sets any variables and key bindings it contains.
In addition, theC-x C-r command re-reads this init file, thusincorporating any changes that you might have made to it.
There are only a few basic constructs allowed in theReadline init file.Blank lines are ignored.Lines beginning with a ‘#’ are comments.Lines beginning with a ‘$’ indicate conditionalconstructs (seeConditional Init Constructs).Other lines denote variable settings and key bindings.
You can modify the run-time behavior of Readline byaltering the values of variables in Readlineusing theset command within the init file.The syntax is simple:
setvariablevalue
Here, for example, is how tochange from the default Emacs-like key binding to usevi line editing commands:
set editing-mode vi
Variable names and values, where appropriate, are recognized withoutregard to case.Unrecognized variable names are ignored.
Boolean variables (those that can be set to on or off) are set to on ifthe value is null or empty,on (case-insensitive), or 1.Any other value results in the variable being set to off.
A great deal of run-time behavior is changeable with the followingvariables.
active-region-start-color ¶A string variable that controls the text color and background when displayingthe text in the active region (see the description ofenable-active-region below).This string must not take up any physical character positions on the display,so it should consist only of terminal escape sequences.It is output to the terminal before displaying the text in the active region.This variable is reset to the default value whenever the terminal type changes.The default value is the string that puts the terminal in standout mode,as obtained from the terminal’s terminfo description.A sample value might be ‘\e[01;33m’.
active-region-end-color ¶A string variable that “undoes”the effects ofactive-region-start-colorand restores “normal”terminal display appearance after displaying text in the active region.This string must not take up any physical character positions on the display,so it should consist only of terminal escape sequences.It is output to the terminal after displaying the text in the active region.This variable is reset to the default value whenever the terminal type changes.The default value is the string that restores the terminal from standout mode,as obtained from the terminal’s terminfo description.A sample value might be ‘\e[0m’.
bell-style ¶Controls what happens when Readline wants to ring the terminal bell.If set to ‘none’, Readline never rings the bell.If set to ‘visible’, Readline uses a visible bell if one is available.If set to ‘audible’ (the default), Readline attempts to ringthe terminal’s bell.
bind-tty-special-chars ¶If set to ‘on’ (the default), Readline attempts to bind the controlcharacters that aretreated specially by the kernel’s terminal driver to theirReadline equivalents.These override the default Readline bindings described here.Type ‘stty -a’ at a Bash prompt to see your current terminal settings,including the special control characters (usuallycchars).
blink-matching-paren ¶If set to ‘on’, Readline attempts to briefly move the cursor to anopening parenthesis when a closing parenthesis is inserted.The default is ‘off’.
colored-completion-prefix ¶If set to ‘on’, when listing completions, Readline displays thecommon prefix of the set of possible completions using a different color.The color definitions are taken from the value of theLS_COLORSenvironment variable.If there is a color definition inLS_COLORS for the custom suffix‘readline-colored-completion-prefix’, Readline uses this color forthe common prefix instead of its default.The default is ‘off’.
colored-stats ¶If set to ‘on’, Readline displays possible completions using differentcolors to indicate their file type.The color definitions are taken from the value of theLS_COLORSenvironment variable.The default is ‘off’.
comment-begin ¶The string to insert at the beginning of the line by theinsert-comment command.The default value is"#".
completion-display-width ¶The number of screen columns used to display possible matcheswhen performing completion.The value is ignored if it is less than 0 or greater than the terminalscreen width.A value of 0 causes matches to be displayed one per line.The default value is -1.
completion-ignore-case ¶If set to ‘on’, Readline performs filename matching and completionin a case-insensitive fashion.The default value is ‘off’.
completion-map-case ¶If set to ‘on’, andcompletion-ignore-case is enabled, Readlinetreats hyphens (‘-’) and underscores (‘_’) as equivalent whenperforming case-insensitive filename matching and completion.The default value is ‘off’.
completion-prefix-display-length ¶The maximumlength in characters of the common prefix of a list of possiblecompletions that is displayed without modification.When set to a value greater than zero, Readlinereplaces common prefixes longer than this valuewith an ellipsis when displaying possible completions.If a completion begins with a period,and Readline is completing filenames,it uses three underscores instead of an ellipsis.
completion-query-items ¶The number of possible completions that determines when the user is askedwhether the list of possibilities should be displayed.If the number of possible completions is greater thanor equal to this value,Readline asks whether or not the user wishes to view them;otherwise, Readline simply lists the completions.This variable must be set to an integer value greater than or equal to zero.A zero value means Readline should never ask; negativevalues are treated as zero.The default limit is100.
convert-meta ¶If set to ‘on’, Readline converts characters it readsthat have the eighth bit set to anASCII key sequence byclearing the eighth bit and prefixing anESC character,converting them to a meta-prefixed key sequence.The default value is ‘on’, but Readline sets it to ‘off’if the locale containscharacters whose encodings may include bytes with the eighth bit set.This variable is dependent on theLC_CTYPE locale category, andmay change if the locale changes.This variable also affects key bindings;see the description offorce-meta-prefix below.
disable-completion ¶If set to ‘On’, Readline inhibits word completion.Completion characters are inserted into the line as if theyhad been mapped toself-insert.The default is ‘off’.
echo-control-characters ¶When set to ‘on’, on operating systems that indicate they support it,Readline echoes a character corresponding to a signal generated from thekeyboard.The default is ‘on’.
editing-mode ¶Theediting-mode variable controls the default set ofkey bindings.By default, Readline starts up in emacs editing mode, wherethe keystrokes are most similar to Emacs.This variable can be set to either ‘emacs’ or ‘vi’.
emacs-mode-string ¶If theshow-mode-in-prompt variable is enabled,this string is displayed immediately before the last line of the primaryprompt when emacs editing mode is active.The value is expanded like akey binding, so the standard set of meta- and control- prefixes andbackslash escape sequences is available.The ‘\1’ and ‘\2’ escapes begin and end sequences ofnon-printing characters, which can be used to embed a terminal controlsequence into the mode string.The default is ‘@’.
enable-active-region ¶point is the current cursor position, andmark refers to asaved cursor position (seeCommands For Moving).The text between the point and mark is referred to as theregion.When this variable is set to ‘On’, Readline allows certain commandsto designate the region asactive.When the region is active, Readline highlights the text in the region usingthe value of theactive-region-start-color, which defaults to thestring that enables the terminal’s standout mode. The active region shows the text inserted by bracketed-paste and anymatching text found by incremental and non-incremental history searches. The default is ‘On’.
enable-bracketed-paste ¶When set to ‘On’, Readline configures the terminal to insert eachpaste into the editing buffer as a single string of characters, insteadof treating each character as if it had been read from the keyboard.This is called putting the terminal intobracketed paste mode;it prevents Readline from executing any editing commands boundto key sequences appearing in the pasted text.The default is ‘On’.
enable-keypad ¶When set to ‘on’, Readline tries to enable the applicationkeypad when it is called.Some systems need this to enable the arrow keys.The default is ‘off’.
enable-meta-key ¶When set to ‘on’, Readline tries to enable any metamodifier key the terminal claims to support when it is called.On many terminals, the Meta key is used to send eight-bit characters;this variable checks for the terminal capability that indicates theterminal can enable and disable a mode that sets the eighth bit of acharacter (0200) if the Meta key is held down when the character istyped (a meta character).The default is ‘on’.
expand-tilde ¶If set to ‘on’, Readline attempts tilde expansion when itattempts word completion.The default is ‘off’.
force-meta-prefix ¶If set to ‘on’, Readline modifies its behavior when binding keysequences containing\M- orMeta-(seeKey Bindings inReadline Init File Syntax)by converting a key sequence of the form\M-C orMeta-C to the two-character sequenceESCC (adding the meta prefix).Ifforce-meta-prefix is set to ‘off’ (the default),Readline uses the value of theconvert-meta variable to determinewhether to perform this conversion:ifconvert-meta is ‘on’,Readline performs the conversion described above;if it is ‘off’, Readline convertsC to a meta character bysetting the eighth bit (0200).The default is ‘off’.
history-preserve-point ¶If set to ‘on’, the history code attempts to place the point (thecurrent cursor position) at thesame location on each history line retrieved withprevious-historyornext-history.The default is ‘off’.
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 entriesare saved.If set to a value less than zero, the number of history entries is notlimited.By default, the number of history entries is not limited.If you try to sethistory-size to a non-numeric value,the maximum number of history entries will be set to 500.
horizontal-scroll-mode ¶Setting this variable to ‘on’ means that the text of the linesbeing edited will scroll horizontally on a single screen line whenthe lines are longer than the width of the screen, instead of wrappingonto a new screen line.This variable is automatically set to ‘on’ for terminals of height 1.By default, this variable is set to ‘off’.
input-meta ¶If set to ‘on’, Readline enables eight-bit input (that is, itdoes not clear the eighth bit in the characters it reads),regardless of what the terminal claims it can support.The default value is ‘off’, but Readline sets it to ‘on’if the locale contains characters whose encodings may include byteswith the eighth bit set.This variable is dependent on theLC_CTYPE locale category, andits value may change if the locale changes.The namemeta-flag is a synonym forinput-meta.
isearch-terminators ¶The string of characters that should terminate an incremental search withoutsubsequently executing the character as a command (seeSearching for Commands in the History).If this variable has not been given a value, the charactersESC andC-j terminate an incremental search.
keymap ¶Sets Readline’s idea of the current keymap for key binding commands.Built-inkeymap names areemacs,emacs-standard,emacs-meta,emacs-ctlx,vi,vi-move,vi-command, andvi-insert.vi is equivalent tovi-command (vi-move is also asynonym);emacs is equivalent toemacs-standard.Applications may add additional names.The default value isemacs;the value of theediting-mode variable also affects thedefault keymap.
keyseq-timeoutSpecifies the duration Readline will wait for a character whenreading 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 Readline doesn’t receive any input within the timeout, it uses theshorter but complete key sequence.Readline uses this value to determine whether or not input isavailable on the current input source (rl_instream by default).The value is specified in milliseconds, so a value of 1000 means thatReadline will wait one second for additional input.If this variable is set to a value less than or equal to zero, or to anon-numeric value, Readline waits until another key is pressed todecide which key sequence to complete.The default value is500.
mark-directoriesIf set to ‘on’, completed directory names have a slash appended.The default is ‘on’.
mark-modified-lines ¶When this variable is set to ‘on’, Readline displays anasterisk (‘*’) at the start of history lines which have been modified.This variable is ‘off’ by default.
mark-symlinked-directories ¶If set to ‘on’, completed names which are symbolic links to directorieshave a slash appended, subject to the value ofmark-directories.The default is ‘off’.
match-hidden-files ¶This variable, when set to ‘on’, forces Readline to match files whosenames begin with a ‘.’ (hidden files) when performing filenamecompletion.If set to ‘off’, the user must include the leading ‘.’in the filename to be completed.This variable is ‘on’ by default.
menu-complete-display-prefix ¶If set to ‘on’, menu completion displays the common prefix of thelist of possible completions (which may be empty) before cycling throughthe list.The default is ‘off’.
output-meta ¶If set to ‘on’, Readline displays characters with theeighth bit set directly rather than as a meta-prefixed escapesequence.The default is ‘off’, but Readline sets it to ‘on’if the locale contains characters whose encodings may includebytes with the eighth bit set.This variable is dependent on theLC_CTYPE locale category, andits value may change if the locale changes.
page-completions ¶If set to ‘on’, Readline uses an internal pager resemblingmore(1)to display a screenful of possible completions at a time.This variable is ‘on’ by default.
prefer-visible-bellSeebell-style.
print-completions-horizontallyIf set to ‘on’, Readline displays completions with matchessorted horizontally in alphabetical order, rather than down the screen.The default is ‘off’.
revert-all-at-newline ¶If set to ‘on’, Readline will undo all changes to history linesbefore returning when executingaccept-line.By default,history lines may be modified and retain individual undo lists acrosscalls toreadline().The default is ‘off’.
search-ignore-case ¶If set to ‘on’, Readline performs incremental and non-incrementalhistory list searches in a case-insensitive fashion.The default value is ‘off’.
show-all-if-ambiguous ¶This alters the default behavior of the completion functions.If set to ‘on’, words which have more than one possible completion cause thematches to be listed immediately instead of ringing the bell.The default value is ‘off’.
show-all-if-unmodified ¶This alters the default behavior of the completion functions ina fashion similar toshow-all-if-ambiguous.If set to ‘on’, words which have more than one possible completion without anypossible partial completion (the possible completions don’t sharea common prefix) cause the matches to be listed immediately insteadof ringing the bell.The default value is ‘off’.
show-mode-in-prompt ¶If set to ‘on’, add a string to the beginning of the promptindicating the editing mode: emacs, vi command, or vi insertion.The mode strings are user-settable (e.g.,emacs-mode-string).The default value is ‘off’.
skip-completed-text ¶If set to ‘on’, this alters the default completion behavior wheninserting 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 completionthat 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 cursoris after the first ‘e’ in ‘Makefile’ will result in‘Makefile’ rather than ‘Makefilefile’,assuming there is a single possible completion.The default value is ‘off’.
vi-cmd-mode-string ¶If theshow-mode-in-prompt variable is enabled,this string is displayed immediately before the last line of the primaryprompt when vi editing mode is active and in command mode.The value is expanded like a key binding, so the standard set ofmeta- and control- prefixes and backslash escape sequences is available.The ‘\1’ and ‘\2’ escapes begin and end sequences ofnon-printing characters, which can be used to embed a terminal controlsequence into the mode string.The default is ‘(cmd)’.
vi-ins-mode-string ¶If theshow-mode-in-prompt variable is enabled,this string is displayed immediately before the last line of the primaryprompt when vi editing mode is active and in insertion mode.The value is expanded like a key binding, so the standard set ofmeta- and control- prefixes and backslash escape sequences is available.The ‘\1’ and ‘\2’ escapes begin and end sequences ofnon-printing characters, which can be used to embed a terminal controlsequence into the mode string.The default is ‘(ins)’.
visible-stats ¶If set to ‘on’, a character denoting a file’s typeis appended to the filename when listing possiblecompletions.The default is ‘off’.
The syntax for controlling key bindings in the init file is simple.First you need to find the name of the command that youwant to change.The following sections contain tables of the commandname, the default keybinding, if any, and a short description of whatthe command does.
Once you know the name of the command, simply place on a linein the init file the name of the keyyou wish to bind the command to, a colon, and then the name of thecommand.There can be no space between the key name and the colon – that will beinterpreted as part of the key name.The name of the key can be expressed in different ways, depending onwhat you find most comfortable.
In addition to command names, Readline allows keys to be boundto a string that is inserted when the key is pressed (amacro).The difference between a macro and a command is that a macro isenclosed in single or double quotes.
keyname is the name of a key spelled out in English.For example:
Control-u: universal-argumentMeta-Rubout: backward-kill-wordControl-o: "> output"
In the example above,C-u is bound to the functionuniversal-argument,M-DEL is bound to the functionbackward-kill-word, andC-o is bound to run the macroexpressed on the right hand side (that is, to insert the text‘> output’ into the line).
This key binding syntax recognizes a number of symbolic character names:DEL,ESC,ESCAPE,LFD,NEWLINE,RET,RETURN,RUBOUT(a destructive backspace),SPACE,SPC,andTAB.
keyseq differs fromkeyname above in that stringsdenoting an entire key sequence can be specified, by placingthe key sequence in double quotes.SomeGNU Emacs style key escapes can be used,as in the following example, but none of thespecial character names are recognized.
"\C-u": universal-argument"\C-x\C-r": re-read-init-file"\e[11~": "Function Key 1"
In the above example,C-u is again bound to the functionuniversal-argument (just as it was in the first example),‘C-xC-r’ is bound to the functionre-read-init-file,and ‘ESC[11~’ is bound to insertthe text ‘Function Key 1’.
The followingGNU Emacs style escape sequences are available whenspecifying key sequences:
\C-A control prefix.
\M-Adding the meta prefix or converting the following character to a metacharacter, as described above underforce-meta-prefix(seeVariable Settings inReadline Init File Syntax).
\eAn escape character.
\\Backslash.
\"", a double quotation mark.
\'', a single quote or apostrophe.
In addition to theGNU Emacs style escape sequences, a secondset of backslash escapes is available:
\aalert (bell)
\bbackspace
\ddelete
\fform feed
\nnewline
\rcarriage return
\thorizontal tab
\vvertical tab
\nnnThe eight-bit character whose value is the octal valuennn(one to three digits).
\xHHThe eight-bit character whose value is the hexadecimal valueHH(one or two hex digits).
When entering the text of a macro, single or double quotes mustbe used to indicate a macro definition.Unquoted text is assumed to be a function name.The backslash escapes described above are expandedin the macro body.Backslash will quote any other character in the macro text,including ‘"’ and ‘'’.For example, the following binding will make ‘C-x \’insert a single ‘\’ into the line:
"\C-x\\": "\\"
Next:Sample Init File, Previous:Readline Init File Syntax, Up:Readline Init File [Contents]
Readline implements a facility similar in spirit to the conditionalcompilation features of the C preprocessor which allows keybindings and variable settings to be performed as the resultof tests.There are four parser directives available.
$ifThe$if construct allows bindings to be made based on theediting mode, the terminal being used, or the application usingReadline.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.
modeThemode= form of the$if directive is used to testwhether Readline is inemacs orvi mode.This may be used in conjunctionwith the ‘set keymap’ command, for instance, to set bindings intheemacs-standard andemacs-ctlx keymaps only ifReadline is starting out inemacs mode.
termTheterm= form may be used to include terminal-specifickey bindings, perhaps to bind the key sequences output by theterminal’s function keys.The word on the right side of the‘=’is tested against both the full name of the terminal and the portionof the terminal name before the first ‘-’.This allowsxterm to match bothxterm andxterm-256color, for instance.
versionTheversion test may be used to perform comparisons againstspecific Readline versions.Theversion expands to the current Readline version.The set of comparison operators includes‘=’ (and ‘==’), ‘!=’, ‘<=’, ‘>=’, ‘<’,and ‘>’.The version number supplied on the right side of the operator consistsof a major version number, an optional decimal point, and an optionalminor version (e.g., ‘7.1’).If the minor version is omitted, itdefaults to ‘0’.The operator may be separated from the stringversion andfrom the version number argument by whitespace.The following example sets a variable if the Readline version being usedis 7.0 or newer:
$if version >= 7.0set show-mode-in-prompt on$endif
applicationTheapplication construct is used to includeapplication-specific settings.Each program using the Readlinelibrary sets theapplication name, and you can test fora particular value. This could be used to bind key sequences to functions useful fora specific program.For instance, the following command adds akey sequence that quotes the current or previous word in Bash:
$if Bash# Quote the current or previous word"\C-xq": "\eb\"\ef\""$endif
variableThevariable construct provides simple equality tests for Readlinevariables and values.The permitted comparison operators are ‘=’, ‘==’, and ‘!=’.The variable name must be separated from the comparison operator bywhitespace; the operator may be separated from the value on the right handside by whitespace.String and boolean variables may be tested.Boolean variables must betested against the valueson andoff.The following example is equivalent to themode=emacs test describedabove:
$if editing-mode == emacsset show-mode-in-prompt on$endif
$elseCommands in this branch of the$if directive are executed ifthe test fails.
$endifThis command, as seen in the previous example, terminates an$if command.
$includeThis directive takes a single filename as an argument and reads commandsand key bindings from that file.For example, the following directive reads from/etc/inputrc:
$include /etc/inputrc
Previous:Conditional Init Constructs, Up:Readline Init File [Contents]
Here is an example of aninputrc file. This illustrates keybinding, variable assignment, and conditional syntax.
# This file controls the behavior 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=emacsMeta-Control-h:backward-kill-wordText 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-historyC-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 availableset bell-style visible# don't strip characters to 7 bits when readingset input-meta on# allow iso-latin1 characters to be inserted rather# than converted to prefix-meta sequencesset convert-meta off# display characters with the eighth bit set directly# rather than as meta-prefixed charactersset output-meta on# if there are 150 or more possible completions for a word,# ask whether or not the user wants to see all of themset completion-query-items 150# For FTP$if Ftp"\C-xg": "get \M-?""\C-xt": "put \M-?""\M-.": yank-last-arg$endifNext:Readline vi Mode, Previous:Readline Init File, Up:Command Line Editing [Contents]
This section describes Readline commands that may be bound to keysequences.Command names without an accompanying key sequence are unbound by default.
In the following descriptions,point refers to the current cursorposition, andmark refers to a cursor position saved by theset-mark command.The text between the point and mark is referred to as theregion.Readlinehas the concept of anactive region:when the region is active,Readline redisplay highlights the region using thevalue of theactive-region-start-colorvariable.Theenable-active-region variable turns this on and off.Several commands set the region to active; those are noted below.
beginning-of-line (C-a) ¶Move to the start of the current line.This may also be bound to the Home key on some keyboards.
end-of-line (C-e) ¶Move to the end of the line.This may also be bound to the End key on some keyboards.
forward-char (C-f) ¶Move forward a character.This may also be bound to the right arrow key on some keyboards.
backward-char (C-b) ¶Move back a character.This may also be bound to the left arrow key on some keyboards.
forward-word (M-f) ¶Move forward to the end of the next word.Words are composed of letters and digits.
backward-word (M-b) ¶Move back to the start of the current or previous word.Words are composed of letters and digits.
previous-screen-line () ¶Attempt to move point to the same physical screen column on the previousphysical screen line.This will not have the desired effect if the currentReadline line does not take up more than one physical line or if point is notgreater than the length of the prompt plus the screen width.
next-screen-line () ¶Attempt to move point to the same physical screen column on the nextphysical screen line.This will not have the desired effect if the currentReadline line does not take up more than one physical line or if the lengthof the current Readline line is not greater than the length of the promptplus the screen width.
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.
clear-screen (C-l) ¶Clear the screen,then redraw the current line,leaving the current line at the top of the screen.If given a numeric argument, this refreshes the current linewithout clearing the screen.
redraw-current-line () ¶Refresh the current line. By default, this is unbound.
Next:Commands For Changing Text, Previous:Commands For Moving, Up:Bindable Readline Commands [Contents]
accept-line (Newline or Return) ¶Accept the line regardless of where the cursor is.If this line is non-empty, you can add it to the history list usingadd_history().If this line is a modified history line, then restore the history lineto its original state.
previous-history (C-p) ¶Move ‘back’ through the history list, fetching the previous command.This may also be bound to the up arrow key on some keyboards.
next-history (C-n) ¶Move ‘forward’ through the history list, fetching the next command.This may also be bound to the down arrow key on some keyboards.
beginning-of-history (M-<) ¶Move to the first line in the history.
end-of-history (M->) ¶Move to the end of the input history, i.e., the line currentlybeing entered.
reverse-search-history (C-r) ¶Search backward starting at the current line and moving ‘up’ throughthe history as necessary.This is an incremental search.This command sets the region to the matched text and activates the region.
forward-search-history (C-s) ¶Search forward starting at the current line and moving ‘down’ throughthe history as necessary.This is an incremental search.This command sets the region to the matched text and activates the region.
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 searchfor a string supplied by the user.The search string may match anywhere in a history line.
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 searchfor a string supplied by the user.The search string may match anywhere in a history line.
history-search-backward () ¶Search backward through the history for the string of charactersbetween 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, but may be bound to the Page Downkey on some keyboards.
history-search-forward () ¶Search forward through the history for the string of charactersbetween 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, but may be bound to the Page Upkey on some keyboards.
history-substring-search-backward () ¶Search backward through the history for the string of charactersbetween 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.
history-substring-search-forward () ¶Search forward through the history for the string of charactersbetween 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.
yank-nth-arg (M-C-y) ¶Insert the first argument to the previous command (usuallythe second word on the previous line) at point.With an argumentn,insert thenth word from the previous command (the wordsin the previous command begin with word 0).A negative argument inserts thenth word from the end ofthe previous command.Once the argumentn is computed,this uses the history expansion facilities to extract thenth word, as if the‘!n’ history expansion had been specified.
yank-last-arg (M-. or M-_) ¶Insert last argument to the previous command (the last word of theprevious history entry).With a numeric argument, behave exactly likeyank-nth-arg.Successive calls toyank-last-arg move back through the historylist, inserting the last word (or the word specified by the argument tothe first call) of each line in turn.Any numeric argument supplied to these successive calls determinesthe direction to move through the history.A negative argument switches the direction through the history(back or forward).This uses the history expansion facilities to extract thelast word, as if the‘!$’ history expansion had been specified.
operate-and-get-next (C-o) ¶Accept the current line for return to the calling application as if anewline had been entered,and fetch the next line relative to the current line from the historyfor editing.A numeric argument, if supplied, specifies the history entryto use instead of the current line.
fetch-history () ¶With a numeric argument, fetch that entry from the history listand make it the current line.Without an argument, move back to the first entry in the history list.
Next:Killing And Yanking, Previous:Commands For Manipulating The History, Up:Bindable Readline Commands [Contents]
end-of-file (usually C-d) ¶The character indicating end-of-file as set, for example, bystty.If this character is read when there are no characterson the line, and point is at the beginning of the line, Readlineinterprets it as the end of input and returnsEOF.
delete-char (C-d) ¶Delete the character at point.If this function is bound to thesame character as the ttyEOF character, asC-dcommonly is, see above for the effects.This may also be bound to the Delete key on some keyboards.
backward-delete-char (Rubout) ¶Delete the character behind the cursor.A numeric argument meansto kill the characters, saving them on the kill ring,instead of deleting them.
forward-backward-delete-char () ¶Delete the character under the cursor, unless the cursor is at theend of the line, in which case the character behind the cursor isdeleted.By default, this is not bound to a key.
quoted-insert (C-q or C-v) ¶Add the next character typed to the line verbatim.This is how to insert key sequences likeC-q, for example.
tab-insert (M-TAB) ¶Insert a tab character.
self-insert (a, b, A, 1, !, …) ¶Insert the character typed.
bracketed-paste-begin () ¶This function is intended to be bound to the "bracketed paste" escapesequence 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 treatingeach character as if it had been read from the keyboard.The charactersare inserted as if each one was bound toself-insert instead ofexecuting any editing commands.
Bracketed paste sets the region (the characters between point and the mark)to the inserted text.It sets theactive region.
transpose-chars (C-t) ¶Drag the character before the cursor forward overthe character at the cursor, moving thecursor forward as well.If the insertion pointis at the end of the line, then thistransposes the last two characters of the line.Negative arguments have no effect.
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 transposesthe last two words on the line.
upcase-word (M-u) ¶Uppercase the current (or following) word.With a negative argument,uppercase the previous word, but do not move the cursor.
downcase-word (M-l) ¶Lowercase the current (or following) word.With a negative argument,lowercase the previous word, but do not move the cursor.
capitalize-word (M-c) ¶Capitalize the current (or following) word.With a negative argument,capitalize the previous word, but do not move the cursor.
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 onlyemacs mode;vi mode does overwrite differently.Each call toreadline() starts in insert mode.
In overwrite mode, characters bound toself-insert replacethe text at point rather than pushing the text to the right.Characters bound tobackward-delete-char replace the characterbefore point with a space.
By default, this command is unbound, but may be bound to the Insertkey on some keyboards.
Next:Specifying Numeric Arguments, Previous:Commands For Changing Text, Up:Bindable Readline Commands [Contents]
kill-line (C-k) ¶Kill the text from point to the end of the current line.With a negative numeric argument, kill backward from the cursor to thebeginning of the line.
backward-kill-line (C-x Rubout) ¶Kill backward from the cursor to the beginning of the current line.With a negative numeric argument, kill forward from the cursor to theend of the line.
unix-line-discard (C-u) ¶Kill backward from the cursor to the beginning of the current line.
kill-whole-line () ¶Kill all characters on the current line, no matter where point is.By default, this is unbound.
kill-word (M-d) ¶Kill from point to the end of the current word, or if betweenwords, to the end of the next word.Word boundaries are the same asforward-word.
backward-kill-word (M-DEL) ¶Kill the word behind point.Word boundaries are the same asbackward-word.
unix-word-rubout (C-w) ¶Kill the word behind point, using white space as a word boundary,saving the killed text on the kill-ring.
unix-filename-rubout () ¶Kill the word behind point, using white space and the slash characteras the word boundaries,saving the killed text on the kill-ring.
delete-horizontal-space () ¶Delete all spaces and tabs around point.By default, this is unbound.
kill-region () ¶Kill the text in the current region.By default, this command is unbound.
copy-region-as-kill () ¶Copy the text in the region to the kill buffer, so it can be yankedright away.By default, this command is unbound.
copy-backward-word () ¶Copy the word before point to the kill buffer.The word boundaries are the same asbackward-word.By default, this command is unbound.
copy-forward-word () ¶Copy the word following point to the kill buffer.The word boundaries are the same asforward-word.By default, this command is unbound.
yank (C-y) ¶Yank the top of the kill ring into the buffer at point.
yank-pop (M-y) ¶Rotate the kill-ring, and yank the new top.You can only do this ifthe prior command isyank oryank-pop.
Next:Letting Readline Type For You, Previous:Killing And Yanking, Up:Bindable Readline Commands [Contents]
digit-argument (M-0,M-1, …M--) ¶Add this digit to the argument already accumulating, or start a newargument.M-- starts a negative argument.
universal-argument () ¶This is another way to specify an argument.If this command is followed by one or more digits, optionally with aleading minus sign, those digits define the argument.If the command is followed by digits, executinguniversal-argumentagain ends the numeric argument, but is otherwise ignored.As a special case, if this command is immediately followed by acharacter that is neither a digit nor minus sign, the argument countfor the next command is multiplied by four.The argument count is initially one, so executing this function thefirst time makes the argument count four, a second time makes theargument count sixteen, and so on.By default, this is not bound to a key.
Next:Keyboard Macros, Previous:Specifying Numeric Arguments, Up:Bindable Readline Commands [Contents]
complete (TAB) ¶Attempt to perform completion on the text before point.The actual completion performed is application-specific.The default is filename completion.
possible-completions (M-?) ¶List the possible completions of the text before point.When displaying completions, Readline sets the number of columns usedfor display to the value ofcompletion-display-width, the value ofthe environment variableCOLUMNS, or the screen width, in that order.
insert-completions (M-*) ¶Insert all completions of the text before point that would havebeen generated bypossible-completions,separated by a space.
menu-complete () ¶Similar tocomplete, but replaces the word to be completedwith a single match from the list of possible completions.Repeatedly executingmenu-complete steps through the listof possible completions, inserting each match in turn.At the end of the list of completions,menu-complete rings the bell(subject to the setting ofbell-style)and restores the original text.An argument ofn movesn positions forward in the listof matches; a negative argument moves backward through the list.This command is intended to be bound toTAB, but is unboundby default.
menu-complete-backward () ¶Identical tomenu-complete, but moves backward through the listof possible completions, as ifmenu-complete had been given anegative argument.This command is unbound by default.
export-completions () ¶Perform completion on the word before point as described aboveand write the list of possible completions to Readline’s output streamusing the following format, writing information on separate lines:
If there are no matches, the first line will be “0”,and this command does not print any output after theS:E.If there is only a single match, this prints a single line containing it.If there is more than one match, this prints the common prefix of thematches, which may be empty, on the first line after theS:E,then the matches on subsequent lines.In this case,N will include the first line with the common prefix.
The user or applicationshould be able to accommodate the possibility of a blank line.The intent is that the user or application readsN lines afterthe line containingS:E to obtain the match list.This command is unbound by default.
delete-char-or-list () ¶Deletes the character under the cursor if not at the beginning orend of the line (likedelete-char).At the end of the line, it behaves identically topossible-completions.This command is unbound by default.
Next:Some Miscellaneous Commands, Previous:Letting Readline Type For You, Up:Bindable Readline Commands [Contents]
start-kbd-macro (C-x () ¶Begin saving the characters typed into the current keyboard macro.
end-kbd-macro (C-x )) ¶Stop saving the characters typed into the current keyboard macroand save the definition.
call-last-kbd-macro (C-x e) ¶Re-execute the last keyboard macro defined, by making the charactersin the macro appear as if typed at the keyboard.
print-last-kbd-macro () ¶Print the last keyboard macro defined in a format suitable for theinputrc file.
Previous:Keyboard Macros, Up:Bindable Readline Commands [Contents]
re-read-init-file (C-x C-r) ¶Read in the contents of theinputrc file, and incorporateany bindings or variable assignments found there.
abort (C-g) ¶Abort the current editing command andring the terminal’s bell (subject to the setting ofbell-style).
do-lowercase-version (M-A, M-B, M-x, …) ¶If the metafied characterx is upper case, run the commandthat is bound to the corresponding metafied lower case character.The behavior is undefined ifx is already lower case.
prefix-meta (ESC) ¶Metafy the next character typed.Typing ‘ESC f’ is equivalent to typingM-f.
undo (C-_ or C-x C-u) ¶Incremental undo, separately remembered for each line.
revert-line (M-r) ¶Undo all changes made to this line.This is like executing theundocommand enough times to get back to the initial state.
tilde-expand (M-~) ¶Perform tilde expansion on the current word.
set-mark (C-@) ¶Set the mark to the point.If a numeric argument is supplied, set the mark to that position.
exchange-point-and-mark (C-x C-x) ¶Swap the point with the mark.Set the current cursor position to the saved position,then set the mark to the old cursor position.
character-search (C-]) ¶Read a character and move point to the next occurrence of that character.A negative argument searches for previous occurrences.
character-search-backward (M-C-]) ¶Read a character and move point to the previous occurrence of that character.A negative argument searches for subsequent occurrences.
skip-csi-sequence () ¶Read enough characters to consume a multi-key sequence such as thosedefined for keys like Home and End.CSI sequences begin with a Control Sequence Indicator (CSI), usuallyESC [.If this sequence is bound to "\e[",keys producing CSI sequences have no effectunless explicitly bound to a Readline command,instead of inserting stray characters into the editing buffer.This is unbound by default, but usually bound toESC [.
insert-comment (M-#) ¶Without a numeric argument, insert the value of thecomment-beginvariable at the beginning of the current line.If a numeric argument is supplied, this command acts as a toggle: ifthe characters at the beginning of the line do not match the valueofcomment-begin, insert the value; otherwise deletethe characters incomment-begin from the beginning of the line.In either case, the line is accepted as if a newline had been typed.
dump-functions () ¶Print all of the functions and their key bindingsto the Readline output stream.If a numeric argument is supplied,the output is formatted in such a way that it can be made partof aninputrc file.This command is unbound by default.
dump-variables () ¶Print all of the settable variables and their valuesto the Readline output stream.If a numeric argument is supplied,the output is formatted in such a way that it can be made partof aninputrc file.This command is unbound by default.
dump-macros () ¶Print all of the Readline key sequences bound to macros and thestrings they outputto the Readline output stream.If a numeric argument is supplied,the output is formatted in such a way that it can be made partof aninputrc file.This command is unbound by default.
execute-named-command (M-x) ¶Read a bindable Readline command name from the input and execute thefunction to which it’s bound, as if the key sequence to which it wasbound appeared in the input.If this function is supplied with a numeric argument, it passes thatargument to the function it executes.
emacs-editing-mode (C-e) ¶When invi command mode, this causes a switch toemacsediting mode.
vi-editing-mode (M-C-j) ¶When inemacs editing mode, this causes a switch toviediting mode.
Previous:Bindable Readline Commands, Up:Command Line Editing [Contents]
While the Readline library does not have a full set ofviediting functions, it does contain enough to allow simple editingof the line.The Readlinevi mode behaves as specified in thesh description in thePOSIX standard.
In order to switch interactively betweenemacs andviediting modes, use the commandM-C-j (bound to emacs-editing-modewhen invi mode and to vi-editing-mode inemacs mode).The Readline default isemacs mode.
When you enter a line invi mode, you are already placed in‘insertion’ mode, as if you had typed an ‘i’. PressingESCswitches you into ‘command’ mode, where you can edit the text of theline with the standardvi movement keys, move to previoushistory lines with ‘k’ and subsequent lines with ‘j’, andso forth.
Previous:Command Line Editing, Up:GNU Readline Library [Contents]
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.http://fsf.org/Everyone is permitted to copy and distribute verbatim copiesof this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or otherfunctional and useful documentfree in the sense of freedom: toassure everyone the effective freedom to copy and redistribute it,with or without modifying it, either commercially or noncommercially.Secondarily, this License preserves for the author and publisher a wayto get credit for their work, while not being considered responsiblefor modifications made by others.
This License is a kind of “copyleft”, which means that derivativeworks of the document must themselves be free in the same sense. Itcomplements the GNU General Public License, which is a copyleftlicense designed for free software.
We have designed this License in order to use it for manuals for freesoftware, because free software needs free documentation: a freeprogram should come with manuals providing the same freedoms that thesoftware does. But this License is not limited to software manuals;it can be used for any textual work, regardless of subject matter orwhether it is published as a printed book. We recommend this Licenseprincipally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, thatcontains a notice placed by the copyright holder saying it can bedistributed under the terms of this License. Such a notice grants aworld-wide, royalty-free license, unlimited in duration, to use thatwork under the conditions stated herein. The “Document”, below,refers to any such manual or work. Any member of the public is alicensee, and is addressed as “you”. You accept the license if youcopy, modify or distribute the work in a way requiring permissionunder copyright law.
A “Modified Version” of the Document means any work containing theDocument or a portion of it, either copied verbatim, or withmodifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter sectionof the Document that deals exclusively with the relationship of thepublishers or authors of the Document to the Document’s overallsubject (or to related matters) and contains nothing that could falldirectly within that overall subject. (Thus, if the Document is inpart a textbook of mathematics, a Secondary Section may not explainany mathematics.) The relationship could be a matter of historicalconnection with the subject or with related matters, or of legal,commercial, philosophical, ethical or political position regardingthem.
The “Invariant Sections” are certain Secondary Sections whose titlesare designated, as being those of Invariant Sections, in the noticethat says that the Document is released under this License. If asection does not fit the above definition of Secondary then it is notallowed to be designated as Invariant. The Document may contain zeroInvariant Sections. If the Document does not identify any InvariantSections then there are none.
The “Cover Texts” are certain short passages of text that are listed,as Front-Cover Texts or Back-Cover Texts, in the notice that says thatthe Document is released under this License. A Front-Cover Text maybe at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy,represented in a format whose specification is available to thegeneral public, that is suitable for revising the documentstraightforwardly with generic text editors or (for images composed ofpixels) generic paint programs or (for drawings) some widely availabledrawing editor, and that is suitable for input to text formatters orfor automatic translation to a variety of formats suitable for inputto text formatters. A copy made in an otherwise Transparent fileformat whose markup, or absence of markup, has been arranged to thwartor discourage subsequent modification by readers is not Transparent.An image format is not Transparent if used for any substantial amountof text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plainASCII without markup, Texinfo input format, LaTeX inputformat,SGML orXML using a publicly availableDTD, and standard-conforming simpleHTML,PostScript orPDF designed for human modification. Examplesof transparent image formats includePNG,XCF andJPG. Opaque formats include proprietary formats that can beread and edited only by proprietary word processors,SGML orXML for which theDTD and/or processing tools arenot generally available, and the machine-generatedHTML,PostScript orPDF produced by some word processors foroutput purposes only.
The “Title Page” means, for a printed book, the title page itself,plus such following pages as are needed to hold, legibly, the materialthis License requires to appear in the title page. For works informats which do not have any title page as such, “Title Page” meansthe text near the most prominent appearance of the work’s title,preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copiesof the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whosetitle either is precisely XYZ or contains XYZ in parentheses followingtext that translates XYZ in another language. (Here XYZ stands for aspecific section name mentioned below, such as “Acknowledgements”,“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title”of such a section when you modify the Document means that it remains asection “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice whichstates that this License applies to the Document. These WarrantyDisclaimers are considered to be included by reference in thisLicense, but only as regards disclaiming warranties: any otherimplication that these Warranty Disclaimers may have is void and hasno effect on the meaning of this License.
You may copy and distribute the Document in any medium, eithercommercially or noncommercially, provided that this License, thecopyright notices, and the license notice saying this License appliesto the Document are reproduced in all copies, and that you add no otherconditions whatsoever to those of this License. You may not usetechnical measures to obstruct or control the reading or furthercopying of the copies you make or distribute. However, you may acceptcompensation in exchange for copies. If you distribute a large enoughnumber of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, andyou may publicly display copies.
If you publish printed copies (or copies in media that commonly haveprinted covers) of the Document, numbering more than 100, and theDocument’s license notice requires Cover Texts, you must enclose thecopies in covers that carry, clearly and legibly, all these CoverTexts: Front-Cover Texts on the front cover, and Back-Cover Texts onthe back cover. Both covers must also clearly and legibly identifyyou as the publisher of these copies. The front cover must presentthe full title with all words of the title equally prominent andvisible. You may add other material on the covers in addition.Copying with changes limited to the covers, as long as they preservethe title of the Document and satisfy these conditions, can be treatedas verbatim copying in other respects.
If the required texts for either cover are too voluminous to fitlegibly, you should put the first ones listed (as many as fitreasonably) on the actual cover, and continue the rest onto adjacentpages.
If you publish or distribute Opaque copies of the Document numberingmore than 100, you must either include a machine-readable Transparentcopy along with each Opaque copy, or state in or with each Opaque copya computer-network location from which the general network-usingpublic has access to download using public-standard network protocolsa complete Transparent copy of the Document, free of added material.If you use the latter option, you must take reasonably prudent steps,when you begin distribution of Opaque copies in quantity, to ensurethat this Transparent copy will remain thus accessible at the statedlocation until at least one year after the last time you distribute anOpaque copy (directly or through your agents or retailers) of thatedition to the public.
It is requested, but not required, that you contact the authors of theDocument well before redistributing any large number of copies, to givethem a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document underthe conditions of sections 2 and 3 above, provided that you releasethe Modified Version under precisely this License, with the ModifiedVersion filling the role of the Document, thus licensing distributionand modification of the Modified Version to whoever possesses a copyof it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections orappendices that qualify as Secondary Sections and contain no materialcopied from the Document, you may at your option designate some or allof these sections as invariant. To do this, add their titles to thelist of Invariant Sections in the Modified Version’s license notice.These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it containsnothing but endorsements of your Modified Version by variousparties—for example, statements of peer review or that the text hasbeen approved by an organization as the authoritative definition of astandard.
You may add a passage of up to five words as a Front-Cover Text, and apassage of up to 25 words as a Back-Cover Text, to the end of the listof Cover Texts in the Modified Version. Only one passage ofFront-Cover Text and one of Back-Cover Text may be added by (orthrough arrangements made by) any one entity. If the Document alreadyincludes a cover text for the same cover, previously added by you orby arrangement made by the same entity you are acting on behalf of,you may not add another; but you may replace the old one, on explicitpermission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this Licensegive permission to use their names for publicity for or to assert orimply endorsement of any Modified Version.
You may combine the Document with other documents released under thisLicense, under the terms defined in section 4 above for modifiedversions, provided that you include in the combination all of theInvariant Sections of all of the original documents, unmodified, andlist them all as Invariant Sections of your combined work in itslicense notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, andmultiple identical Invariant Sections may be replaced with a singlecopy. If there are multiple Invariant Sections with the same name butdifferent contents, make the title of each such section unique byadding at the end of it, in parentheses, the name of the originalauthor or publisher of that section if known, or else a unique number.Make the same adjustment to the section titles in the list ofInvariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History”in the various original documents, forming one section Entitled“History”; likewise combine any sections Entitled “Acknowledgements”,and any sections Entitled “Dedications”. You must delete allsections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documentsreleased under this License, and replace the individual copies of thisLicense in the various documents with a single copy that is included inthe collection, provided that you follow the rules of this License forverbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distributeit individually under this License, provided you insert a copy of thisLicense into the extracted document, and follow this License in allother respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separateand independent documents or works, in or on a volume of a storage ordistribution medium, is called an “aggregate” if the copyrightresulting from the compilation is not used to limit the legal rightsof the compilation’s users beyond what the individual works permit.When the Document is included in an aggregate, this License does notapply to the other works in the aggregate which are not themselvesderivative works of the Document.
If the Cover Text requirement of section 3 is applicable to thesecopies of the Document, then if the Document is less than one half ofthe entire aggregate, the Document’s Cover Texts may be placed oncovers that bracket the Document within the aggregate, or theelectronic equivalent of covers if the Document is in electronic form.Otherwise they must appear on printed covers that bracket the wholeaggregate.
Translation is considered a kind of modification, so you maydistribute translations of the Document under the terms of section 4.Replacing Invariant Sections with translations requires specialpermission from their copyright holders, but you may includetranslations of some or all Invariant Sections in addition to theoriginal versions of these Invariant Sections. You may include atranslation of this License, and all the license notices in theDocument, and any Warranty Disclaimers, provided that you also includethe original English version of this License and the original versionsof those notices and disclaimers. In case of a disagreement betweenthe translation and the original version of this License or a noticeor disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”,“Dedications”, or “History”, the requirement (section 4) to Preserveits Title (section 1) will typically require changing the actualtitle.
You may not copy, modify, sublicense, or distribute the Documentexcept as expressly provided under this License. Any attemptotherwise to copy, modify, sublicense, or distribute it is void, andwill automatically terminate your rights under this License.
However, if you cease all violation of this License, then your licensefrom a particular copyright holder is reinstated (a) provisionally,unless and until the copyright holder explicitly and finallyterminates your license, and (b) permanently, if the copyright holderfails to notify you of the violation by some reasonable means prior to60 days after the cessation.
Moreover, your license from a particular copyright holder isreinstated permanently if the copyright holder notifies you of theviolation by some reasonable means, this is the first time you havereceived notice of violation of this License (for any work) from thatcopyright holder, and you cure the violation prior to 30 days afteryour receipt of the notice.
Termination of your rights under this section does not terminate thelicenses of parties who have received copies or rights from you underthis License. If your rights have been terminated and not permanentlyreinstated, receipt of a copy of some or all of the same material doesnot give you any rights to use it.
The Free Software Foundation may publish new, revised versionsof the GNU Free Documentation License from time to time. Such newversions will be similar in spirit to the present version, but maydiffer in detail to address new problems or concerns. Seehttp://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number.If the Document specifies that a particular numbered version of thisLicense “or any later version” applies to it, you have the option offollowing the terms and conditions either of that specified version orof any later version that has been published (not as a draft) by theFree Software Foundation. If the Document does not specify a versionnumber of this License, you may choose any version ever published (notas a draft) by the Free Software Foundation. If the Documentspecifies that a proxy can decide which future versions of thisLicense can be used, that proxy’s public statement of acceptance of aversion permanently authorizes you to choose that version for theDocument.
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means anyWorld Wide Web server that publishes copyrightable works and alsoprovides prominent facilities for anybody to edit those works. Apublic wiki that anybody can edit is an example of such a server. A“Massive Multiauthor Collaboration” (or “MMC”) contained in thesite means any set of copyrightable works thus published on the MMCsite.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0license published by Creative Commons Corporation, a not-for-profitcorporation with a principal place of business in San Francisco,California, as well as future copyleft versions of that licensepublished by that same organization.
“Incorporate” means to publish or republish a Document, in whole orin part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under thisLicense, and if all works that were first published under this Licensesomewhere other than this MMC, and subsequently incorporated in wholeor in part into the MMC, (1) had no cover texts or invariant sections,and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the siteunder CC-BY-SA on the same site at any time before August 1, 2009,provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy ofthe License in the document and put the following copyright andlicense notices just after the title page:
Copyright (C)yearyour name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,replace the “with…Texts.” line with this:
with the Invariant Sections beinglist their titles, with the Front-Cover Texts beinglist, and with the Back-Cover Texts beinglist.
If you have Invariant Sections without Cover Texts, or some othercombination of the three, merge those two alternatives to suit thesituation.
If your document contains nontrivial examples of program code, werecommend releasing these examples in parallel under your choice offree software license, such as the GNU General Public License,to permit their use in free software.