diff --git a/doc/manual/index.docbook b/doc/manual/index.docbook
index a11a1274..0e5f4394 100644
--- a/doc/manual/index.docbook
+++ b/doc/manual/index.docbook
@@ -1,1789 +1,1789 @@
AhmadSamir'>
a.samirh78@gmail.com'>
]>
The &konsole; Handbook
&Jonathan.Singer; &Jonathan.Singer.mail;
&Kurt.Hindenburg; &Kurt.Hindenburg.mail;
&Ahmad.Samir; &Ahmad.Samir.mail;
&Robert.Knight; &Robert.Knight.mail;
&Kurt.Hindenburg; &Kurt.Hindenburg.mail;
&Waldo.Bastian; &Waldo.Bastian.mail;
&Mike.McBride; &Mike.McBride.mail;
200020012002
&Jonathan.Singer;
200520082009201020112014201620172018
&Kurt.Hindenburg;
2018
&Ahmad.Samir;
&FDLNotice;
2018-04-03
Applications 18.08
&konsole; is &kde;'s terminal emulator.
KDE
konsole
kdebase
command
line
terminal
cli
Introduction
What is a terminal?
&konsole; is an X terminal
emulator, often referred to as a terminal or a shell. It emulates a command line interface in a text only window.
&konsole; typically runs a command shell, an application that executes commands that you type.
The shell the &konsole; runs depends on your account settings.
Consult your operating system documentation to know what the shell is, how to configure it and how to use it.
Scrollback
&konsole; uses the notion of scrollback
to allow users to view previously displayed output.
By default, scrollback is on
and set to save 1000 lines of
output in addition to what is currently displayed on the screen.
As lines of text scroll off the top of the screen, they can be reviewed
by moving the scroll bar upwards, scrolling with a mouse wheel or through
the use of the
&Shift;Page Up (to move
back),
&Shift;Page Down (to move forward),
&Shift;Up Arrow (to move up a line) and
&Shift;Down Arrow (to move down a line) keys.
The amount of scrolling using &Shift;Page Up/Down
can be switched between half and full page in the Scrolling tab of the profile configuration
window (use SettingsEdit Current Profile...
to open this window).
Profiles
Profiles allow the user to quickly and easily automate the running
of common commands. Examples could include:
ssh into another machine
starting an irc session
use tail to watch a file
All new and changed profiles are saved in the user's local home folder in $XDG_DATA_HOME/konsole.
Procedure to create a new profile:
Click on the menu entry SettingsManage Profiles...
Click on the button New Profile....
Fill in the first entry with a name. This is the
name that will show in the menu, and will be the default label instead
of Shell when you start a session of this type.
Enter a command just as you normally would if you opened a new
shell and were going to issue that command. For our first example above, you
might type ssh administration.
On the other tabs of the dialog, configure this session's appearance.
You can configure a different font, color scheme, $TERM type and many
other settings for each session.
Press the OK button. The new session
is now available in the Manage Profiles... dialog.
Any profiles which have Show in Menu checked will be listed by their name in the
FileNew Tab menu.
There will be no submenu if only the default profile is to be shown.
Mouse Buttons
This section details the use of the mouse buttons for the common
right handed mouse button order.
For the left handed mouse button order, swap left and right in the text below.
Left
All &LMB; clicks will be sent to a mouse-aware
application running in &konsole;.
If an application will react on mouse clicks, &konsole;
indicates this by showing an arrow cursor. If not, an I-beam (bar)
cursor is shown.
Holding the &LMB; down and
dragging the mouse over the screen with a mouse-unaware application
running will mark a region of the text. While dragging the mouse, the marked
text is displayed in reversed color for visual feedback. Select Copy
from the Edit menu to copy the marked text to the clipboard for further use
within &konsole; or another application. The selected text can also be
dragged and dropped into compatible applications. Hold the &Ctrl; key and
drag the selected text to the desired location.
Normally, new-line characters are inserted at the end of each
line selected. This is best for cut and paste of source code, or the output
of a particular command. For ordinary text, the line breaks are often
not important. One might prefer, however, for the text to be a stream
of characters that will be automatically re-formatted when pasted into
another application. To select in text-stream mode, hold down the
&Ctrl; key while selecting normally.
Pressing the &Ctrl; and &Alt; keys along with the &LMB;
will select text in columns.
Double-click with the &LMB; to select a word;
triple-click to select an entire line.
If the upper or lower edge of the text area is touched while
marking, &konsole; scrolls up or down, eventually exposing text within
the history buffer. The scrolling stops when the mouse stops
moving.
After the mouse is released, &konsole; attempts to keep the text
in the clipboard visible by holding the marked area reversed. The
marked area reverts back to normal as soon as the contents of the
clipboard change, the text within the marked area is altered or the
&LMB; is clicked.
To mark text in a mouse-aware application (Midnight Commander, for example)
the &Shift; key has to be pressed when clicking.
Middle
Pressing the &MMB;
pastes text currently in the clipboard. Holding down the &Ctrl; key as you
press the &MMB; pastes the text and appends a new-line. That is convenient
for executing pasted command quickly, but it can be dangerous so use it
with caution.
If you have a mouse with only two buttons, pressing both
the &LMB; and &RMB; together emulates the &MMB; of a three button mouse.
If you have a wheel as the middle button,
rolling it in a mouse-unaware program will move &konsole;'s scrollbar.
Right
These items appear in the menu when the &RMB;
is pressed:
Copy
Paste
With a text selection a submenu Search for with a list of the preferred Web Shortcuts and an option to configure web shortcuts.
Open File Manager
Set Encoding
Clear Scrollback
Adjust Scrollback...
Show Menu Bar, only when the menubar is hidden
Switch Profile
Edit Current Profile...
Close Tab
In a mouse aware application, press the &Shift; key along with the
&RMB; to get the popup menu.
Drag and Drop
If you drop a file, folder or &URL; on a &konsole; window, a context
menu appears with these actions:
Drag and Drop Context Menu
Drag and Drop Context Menu
&Shift;Move Here
Move the dropped item into the current folder. This item only appears in
the context menu, if you have the rights to delete the dropped file or folder.
&Ctrl;Copy Here
Copy the dropped item into the current folder.
&Ctrl;&Shift;Link Here
Insert a symbolic link to the dropped item.
Paste Location
Insert the full file path of the dropped item at the cursor.
Change Directory To
If a folder is dropped, this action appears in the context menu and allows you to
change the working folder of the &konsole; session.
&Esc;Cancel
Break the drag and drop action.
If you press the shortcuts before releasing the &LMB; during drag and drop, no context menu appears and
the actions will be executed immediately.
If you want to use the &Ctrl; key for drag and drop or disable the context
menu to insert &URL;s as text by default, enable the corresponding options
on the Mouse tab in the profile settings dialog.
Command Reference
&konsole; Dialogs
Rename Tab Dialog
The name of the current tab can be changed from this dialog.
The dialog can be displayed via the menu, the shortcut &Ctrl;&Alt;S or by
double-clicking on the tab in the tab bar.
These changes can be made permanent by editing the current profile.
&konsole; will substitute these tokens for local tabs:
%n : program name
%d : current directory (short)
%D : current directory (long)
%h : local host (short)
%u : user name
%w : window title set by shell
%# : session number
&konsole; will substitute these tokens for remote tabs:
%c : current program
%h : remote host (short)
%H : remote host (long)
%u : user name
%U : user name@ (if given)
%w : window title set by shell
%# : session number
Examples:
%d : %n
with /usr/src as current directory and running
bash will display
src : bash
%D : %n
with /usr/src as current directory and running
top will display
/usr/src : top
%w (%#)
with ~ as current directory and running
vim in the first tab will display
[No Name] (~) - VIM(1)
Copy Input Dialog
The text entered in one tab can simultaneously be sent to other tabs.
This dialog allows you to select which tabs will get that input.
The current tab will be greyed out.
Adjust Scrollback Dialog
The
scrollback
options for the history size can be changed in this dialog. Any changes are
for the current tab only and will not be saved to the profile.
Command-line Options
When &konsole; is started from the command line, various options
can be specified to modify its behavior.
List various options.
file
Start &konsole; using the specified profile
instead of the default profile.
Use the internal FALLBACK profile. This option is a shortcut for FALLBACK/.
dir
Open with
dir as the initial working directory.
Do not close the initial session automatically when it ends.
Create a new tab in an existing window rather than creating a new window.
file
Create tabs as specified in the given tabs configuration file.
The file has one tab per line in the following format:
Each line specifies a tab to open using up to 4 fields specifying how it is to open.
Fields are delimited with ;; and a field name must have a : appended.
Empty lines or lines with # at the beginning are ignored, so you can use line beginning with
# to add comments.
title: a name for this tab, tab default if blank or not specified
workdir: working directory, ~ if blank or not specified
profile: a &konsole; profile to use, the default if blank or not specified
command: a command to run
Each line should contain at least one of command or profile field.
Example: title: %n;; command: /usr/bin/top ;; profile: Shell
Start &konsole; in the background and bring to the front when &Ctrl;&Shift;F12 (by default) is pressed.
Run the new instance of &konsole; in a separate process.
Show the menubar, overriding the default behavior.
Hide the menubar, overriding the default behavior.
Show the tabbar, overriding the default behavior.
Hide the tabbar, overriding the default behavior.
Start &konsole; in fullscreen mode.
Disable transparent backgrounds, even if the system supports them.
List all available profiles.
List all possible properties with name and type. See option .
For more information, please visit
&konsole; API Reference.
property=value
Change the value of a profile property.
command
Execute
command instead of the normal shell.
This option will catch all following arguments passed to &konsole;, and execute it as command. So this option should always be used as the last option.
&konsole; also accepts generic &Qt; and &kf5-full; options, see man pages qt5options and kf5options.
Scripting &konsole;
&konsole; does support numerous methods that can be used with &DBus;.
There are two ways to use the &DBus; interface: &Qt;'s &GUI;
qdbusviewer
and the command line
qdbus.
Examples:
%
qdbus
will display all services available.
%
qdbus
will display the &DBus; interface for &konsole;.
%
qdbus
will display methods for controlling window 1.
%
qdbus
will display methods for controlling the current window.
%
qdbus
will display methods for controlling session 1.
%
qdbus
will display methods for controlling the current session.
%
qdbus
will display methods for controlling the current &konsole;'s session.
If any of the above commands outputs:
Service 'org.kde.konsole' does not exist, change
to one of the following:
(will select first pid)
(this can be used from the current &konsole;)
For more information, please visit
&DBus; tutorial.
Terminal Key Bindings
How &konsole; Uses Key Bindings
Introduction
&konsole; uses *.keytab files to translate key combinations into control characters and escape sequences that are sent to the shell or to interactive programs (typically programs that use the Alternate Screen buffer, ⪚ vim, less, screen) running in the shell.
Users can customize the key bindings settings in &konsole; using the Key Bindings Editor. A key combination can be configured to send a specific control or escape sequence to the terminal.
You can open the Key Bindings Editor from the menu entry SettingsEdit Current Profile, and going to the Keyboard tab. Listed there are the Key Bindings schemas that come by default with &konsole;.
Key Combinations and Modes
Key combinations follow the pattern:
Key (+|-) Modes
for example:
Up+Shift+AppScreen
Down+Shift-AppScreen
Space+Ctrl
Key names are defined in the qnamespace.h header file, with the Qt::Key_
prefix removed, for a list of key names check the Qt::Key enumeration in the &Qt; documentation.
A +
preceding a Mode name means that mode is set; for a modifier key, that means it's pressed, whereas for all other modes it means that particular mode is in effect (&ie; active). For example +Ctrl
means the key combination will work only if the &Ctrl; key is pressed.
A -
preceding a Mode name means that mode is reset; basically this is the opposite of putting +
before a Mode name, so for a modifier key that means the key isn't pressed, whereas for all other modes it means that particular mode is inactive. For example -Ctrl
means the key combination will work only if the &Ctrl; key is not pressed.
If a Mode name isn't present in a key combination, its state is ignored.
The supported Key Bindings modes are listed below:
Alt, Ctrl, Shift
One or more of these Modes can be used in a key combination, if any of them is set, the key combination uses that modifier key, respectively; and vice versa if it's reset
AnyModifier
If this mode is set, the key combination uses any modifier key (any of the previous three modifier keys); and vice versa if it's reset
Ansi
If this mode is set, &konsole; will send ANSI escape and control sequences
If this mode is reset &konsole; will send VT52 escape and control sequences
AppScreen
If this mode is set, the key combination will only affect interactive programs that use the Alternate Screen buffer
If this mode is reset the key combination will only affect the terminal when it's using the Normal Screen buffer
&konsole; makes use of two screen buffers:
The Normal Screen buffer (default): allows you to scroll back to view previous lines of output, this is the default buffer you usually use to execute commands... &etc;
The Alternate Screen buffer: the terminal switches to this buffer when you run an interactive program (⪚ less, vim, screen, tmux... &etc;)
KeyPad
If this mode is set, the key combination uses a key on the Keypad (Number Pad). This mode is useful to distinguish between keys on the keyboard and keys on the Keypad. For example when Num Lock is on you can configure two separate key combinations, one using the key labelled 1
on the keyboard (usually under the F1 key) and the other using the key labelled 1
on the Keypad. The same concept applies when Num Lock is off for the End, Home, Cursor Keys ...etc on the Keypad
AppCursorKeys
This mode implements the VT100 Cursor Keys Mode (DECCKM). It controls the escape sequences each Cursor Key (Up, Down, Right, Left) sends, depending on whether this mode is set or reset
By default &konsole; follows the XTerm behavior of treating the Home and End keys as cursor keys with respect to DECCKM
AppKeyPad
If this mode is set, the key combination will only work when the Keypad is in Application Mode (DECKPAM)
If this mode is reset, the key combination will only work when the Keypad is in Numeric Mode (DECKPNM)
NewLine
If this mode is set, the Return (Enter) key on the keyboard will send both Carriage Return "\r" and New Line "\n" control characters
If this mode is reset, the Return key will send only a Carriage Return "\r"
The same applies to the Enter key on the Keypad
This mode emulates the LNM - Line Feed/New Line Mode
Note that each combination of Key and Modes (set/reset) must be unique. For example, consider the following two rules:
A+Shift : A
a : a
&konsole; will not accept the small letter a
rule, you have to add a -Shift
to that rule to make it work.
The Output Field
In the Output field you can add the escape sequences or control characters that you want &konsole; to send to the terminal when the associated key combination is pressed.
You can also use any of the following keywords, each of which has a special meaning in &konsole;:
scrollUpLine : scroll up one line in the shell history scrollback buffer
scrollUpPage : scroll up one page in the shell history scrollback buffer
scrollDownLine : scroll down one line in the shell history scrollback buffer
scrollDownPage : scroll down one page in the shell history scrollback buffer
scrollUpToTop : scroll up to the begining of the shell history scrollback buffer
scrollDownToBottom : scroll down to the end of the shell history scrollback buffer
You can also use strings with C-string syntax; you may use the following escapes sequences:
\E : Escape
\\ : Backslash
\" : Double quote
\t : Tab
\r : Carriage Return
\n : New line
\b : Backspace
\xHH : where HH are two hex digits
This can be used to send ASCII control characters, ⪚ \x00
which is the NUL character
Other System Resources
There are other system resources that can affect terminal Key Bindings:
Consult the terminfo or termcap database for the expected escape sequences and control characters that each key combination is supposed to send.
It is likely that your system has other keyboard databases which have to be in sync too, (⪚ /etc/inputrc and readline for the BASH shell) as they affect the operations (interactions) bound to key combinations.
Further Reading
For more information on escape sequences and control characters, check the following documentation:
The VT100 user guide
The VT102 user guide
The comprehensive and indispensable XTerm Control Sequences documentation
Using Style Sheet for the Tab Bar
The default style sheet for the tab bar sets the minimum and maximum tab
widths. The user can create a .css file and have &konsole; use that as the
style sheet for the tab bar. In the .css file, the widget to use is
QTabBar::tab.
For more information, consider reading
&Qt; Style Sheets
Examples:
Change the selected tab's background to a light gray
QTabBar::tab:selected {
background: #999999
}
Change the selected tab's text to red
QTabBar::tab:selected {
color: red
}
All tabs will be at least 200 pixels in width
QTabBar::tab {
min-width: 200px
}
Only the selected tab will be at least 200 pixels in width
QTabBar::tab::selected {
min-width: 200px
}
Any of these can be combined in one file
QTabBar::tab::selected {
background: #999999;
color: red;
min-width: 200px;
}
QTabBar::tab {
min-width: 100px
}
Did You Know?, Common Issues and More
Did You Know?
Pressing &Ctrl; while selecting text will cause lines breaks to be converted to spaces when pasted.
Pressing the &Ctrl;&Alt; keys while selecting text will select columns.
The &Ctrl;Wheel combination will zoom text size, like in konqueror and firefox.
When a program evaluates either mouse button, pressing the &Shift; key will allow the popup menu to appear.
The &Ctrl;&Shift;F10 shortcut will activate the menu.
The &Shift;Insert keys will insert the clipboard.
Double-clicking will select a whole word. Continuing to hold the mouse button and moving the mouse will extend the selection.
Triple-clicking will select a whole line. Continuing to hold the mouse button and moving the mouse will extend the selection.
There is a hidden feature for the "%d" formatter in tab title. You can tell &konsole; to abbreviate a directory name into its first character. For example, "/path/to/konsole/src" can be abbreviated into "konsole/s". If you want to enable and control this hidden feature, open konsolerc
in qtpaths and add following lines:
[ProcessInfo]
CommonDirNames=name1,name2,name3...
If you are using Yakuake, you need to edit yakuakerc
in qtpaths instead.
Common Issues
Some fonts might be unavailable for usage in &konsole;, although they are available in other applications. That doesn't mean there is a bug in &konsole;. &konsole; requires monospaced fonts to provide the best visual result, so it asks &Qt; to only list monospaced fonts.
Starting with version 16.08 (August 2016), &konsole; can be configured to allow selecting any font with the caveat that the display may not be correct.
Since KDE4 all the tabs use the same process ID. This has the side-effect that if one tab's process has issues, all the other tabs may experience issues as well.
This is most noticeable when a command that connects to an external device or system (ssh, nfs) has issues.
&konsole; treats arguments after the option as one command and runs it directly, instead of parsing it and possibly dividing it into sub-commands for execution. This is different from xterm.
konsole -e "command1 ; command2" does not work
konsole -e $SHELL -c "command1 ; command2" works
&konsole; doesn't provide convenience for running login shell, because developers don't like the idea of running login shell in a terminal emulator.
Of course, users still can run login shell in &konsole; if they really need to. Edit the profile in use and modify its command to the form of starting a login shell explicitly, such as "bash -l" and "zsh -l".
The option sometimes behaves strangely. It may create new window, or it may create new tab in another existing &konsole; window instead of the current &konsole; window.
Those behaviors feel strange, but they are not necessarily bugs. The option tries to reuse existing &konsole; windows, but not all &konsole; windows are reusable. All &konsole; windows opened through &krunner; are reusable, while most &konsole; windows opened from command line are not.
Credits and Copyright
&konsole; is currently maintained by &Kurt.Hindenburg; &Kurt.Hindenburg.mail;
Previous &konsole; maintainers include: &Robert.Knight; &Robert.Knight.mail; and &Waldo.Bastian; &Waldo.Bastian.mail;
The application &konsole; Copyright © 1997-2008
&Lars.Doelle; &Lars.Doelle.mail;
This document was originally written by &Jonathan.Singer;
&Jonathan.Singer.mail;
This document was updated for &kde; 4.x by
&Kurt.Hindenburg; &Kurt.Hindenburg.mail;
This document was updated for &kde; 3.4 by
&Kurt.Hindenburg; &Kurt.Hindenburg.mail;
Originally converted to DocBook SGML by
&Mike.McBride; and &Lauri.Watts;
&underFDL;
&underGPL;
Links
For more information please visit these websites:
&konsole;'s homepage on &kde;'s UserBase
&konsole;'s homepage
&konsole;'s mailing list
&kde; on
FreeBSD
&kde; on &Solaris;
&documentation.index;