# The &konsole; Handbook

Jonathan
Singer

    jsinger@leeta.net

Chris
Machemer

    machey@ptd.net

Maintainer
Michael
McBride
Reviewer

    mmcbride@ematic.com

Lauri
Watts
Reviewer

    vampyr@atconnex.net

2000
2001
Jonathan Singer
&FDLNotice;
2001-07-09
1.00.20

This document is the user handbook for the &konsole; application.

&konsole; is an X terminal emulator for &kde; 2.0

KDE
konsole
kdebase
command
line

## Introduction to &konsole;

&konsole; is an X terminal emulator which provides a command-line interface (CLI) while using the graphical K Desktop Environment. &konsole; helps to better organize the user's desktop by containing multiple sessions in a single window (a less cluttered desktop).

Its advanced features include a simple configuration and the ability to use multiple terminal shells in a single window.

Using &konsole;, a user can open:

- &Linux; console sessions

- Midnight Commander file manager sessions

- Shell sessions

- Root console sessions

- Root Midnight Commander sessions

These sessions can be renamed to help you keep track of all your shells, or signaled (STOP, CONT, HUP, INT, TERM, KILL).

For more control over &konsole;, a user can:

- hide/show the menubar, toolbar and/or frame

- select the size of a &konsole; window, fonts, color schemes, and key mapping

- change location of the scrollbar or hide the scrollbar

All chosen settings can be made the default for forthcoming sessions by saving them.

### History

For those with a deep interest in the taxonomy of free X terminals, there are two others of this kind: xterm, the original, written even before X itself (a month or two), and xvt, a lightweight xterm clone, on which most other currently available derivatives (notably eterm) are based.

After a decade, &konsole; is the first rewrite from the ground up. While xterm has definitely been hacked to death (its `README` starts with the words Abandon All Hope, Ye Who Enter Here), &konsole; offers a fresh start using contemporary technologies and understanding of X.

## Use of &konsole;

### Startup

When &konsole; is started, an application (typically a Unix shell) runs in the window. Simply type at the prompt.

&konsole; Screen
&konsole; Screen

### History

As lines scroll off the top of the screen, they can be reviewed by moving the scroll bar upwards, or through the use of the ShiftPage Up (to move back a page), ShiftPage Down (to move forward a page), ShiftUp (to move up a line) and ShiftDown (to move down a line) keys (provided the "History" option is on).

### Mouse Buttons

Left

  Clicking the left button is passed as an event to the application running in the emulation, if it is mouse-aware. If a program will react on mouse clicks, &konsole; indicates this by showing an arrow cursor. If not, an I-beam (bar) cursor is shown.

  Holding the left button down and dragging the mouse over the screen with a mouse-unaware application running will mark a region of the text. While dragging, the marked text is displayed reversed for visual feedback. When the button is released, the marked text is copied to the clipboard for further use within &konsole; or another application.

  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 would prefer for the text to be a stream of characters that will be automatically re-formatted when pasted another application. To select in text-stream mode, hold down the &Ctrl; key while selecting normally.

  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 either the contents of the clipboard is changed, the text within the marked area is altered or the left mouse button is clicked.

  To mark text on a mouse-aware application the Shift key has to be pressed when clicking.

Middle

  Pressing the middle button pastes text currently in the clipboard.

  If you have a mouse with only two buttons, pressing both the left and right buttons together emulates the middle button of a three button mouse.

Right

  The right button brings up the Settings menu. The &Ctrl; right button brings up the File menu, while &Shift; right button brings up the Sessions menu.

### Menu Bar

The menubar is at the top of the &konsole; window. It can be hidden and restored by toggling Show Menubar in the Settings menu. When the menubar is hidden, Show Menubar can be reached by right clicking in the window.

#### The File menu

File Linux Console

  Opens a new session emulating a text-only Linux system.

  See the file `README.linux.console` in the &konsole; source package for detailed information on how the &Linux; console differs from a typical &UNIX; console.

File Midnight Commander

  Opens a new session with the Midnight Commander graphical file browser

File Shell

  Opens a new session with a terminal shell

File Root Console

  Opens a new session with a terminal shell, as the root user.

  After being prompted for the root password, the # prompt appears, indicating that the user is working with root privileges. This is frequently necessary for installing new software and other system maintenance, but care should be taken to avoid accidental damage.

File Root Midnight Commander

  Opens a new session with the Midnight Commander graphical file browser, as the root user.

  After being prompted for the root password, the # prompt appears under the browser window, indicating that the user is working with root privileges. Again, this is frequently necessary but care should be taken to avoid accidental damage.

File Quit

  Quits &konsole;, closing all sessions and any applications launched from them.

You can also open a new session with a key shortcut. By default, &Alt;&Ctrl;N is used. You can also define your own key shortcut to launch a new terminal session. The files with a `*.keytab` extension in `$`KDEDIR`/share/apps/konsole` define keyboard shortcuts.

For instance, adding the definition: `key F12 + Shift : newSession` to the active keytab files causes a new shell to be launched upon hitting &Shift;F12. Use the Settings Keyboard menu command to choose a keytab file. The file `README.KeyTab` contains more information on defining shortcuts.

#### The SessionsMenu

Sessions Send Signal

  Send Signal - Sends the specified signal to the shell process, or other process, that was launched when the new session was started.

  Currently available signals are:

  STOP | to stop process
  CONT | continue if stopped
  HUP | hangup detected on controlling terminal, or death of controlling process
  INT | interrupt from keyboard
  TERM | termination signal
  KILL | kill signal

  Refer to your system manual pages for further details by giving the command ``man` `7 signal``.

Sessions Rename Session...

  Changes the name of the active session

Sessions Session icons...

  At the bottom of the menu is a list of the available sessions. Selecting one makes that session active.

  You can also use the ShiftLeft/ShiftRight keys to cycle through the available sessions.

#### The Settings menu

Settings Rename Session...

  Changes the name of the active session

Settings Show Menubar

  Shows or hides the menubar

Settings Show Toolbar

  Shows or hides the toolbar

Settings Show Frame

  Shows or hides frame at side of window

Settings Scrollbar

  Controls location of scrollbar: none, left, or right

Settings Fullscreen

  Toggles window between full-screen and normal size

Settings Size

  Sets size of text area (given in columns x rows)

Settings Fonts

  Sets font and font size

  Select the Custom option to use any combination of font, size and style. The `README.fonts` file in the &konsole; source package gives tips on which fonts will work well.

Settings Schema

  Sets colors of text and background

  The list of these schemata is taken from `$KDEDIR/share/apps/konsole/*.schema`. The file `$KDEDIR/share/apps/konsole/README.Schema` describes the schema format in more detail. Add to or modify these files to match your needs. You can also create custom schema from the &kcontrolcenter; module System Konsole.

Settings History...

  Opens a dialog where you can configure the history.. The enable checkbox toggles saving of lines that have scrolled off the top of the window. You can enter the Number of lines to remember in the text field, or use the spinner buttons to increase or decrease the number in steps of 100 lines. The Default button will reset the history to 1000 lines. Press OK to save your changes, or Cancel to close the dialog without saving your settings. The Help button will open this manual, and display the text you're reading right now.

Settings Codec

  Not implemented yet

Settings Keyboard

  Chooses desired keymapping

  The list of these keymappings is taken from `$KDEDIR/share/apps/konsole/*.keytab`. The file `$KDEDIR/share/apps/konsole/README.KeyTab` describes the keytab format in more detail. Add to or modify these files to match your needs.

Settings Word Separators

  Specify characters that will be recognized as separators between words

  This affects what text will be selected when you double-click on text. It is most important for non-Western text encodings.

Settings Warn for Open Sessions on Quit

  When set, a warning appears when you try to close a &konsole; window with multiple sessions.

Settings Save Settings

  Saves the current settings as the new defaults

#### The Help menu

F1 Help Contents...

  Opens the table of contents of this document

Help Technical Reference

  Detailed information on terminal emulation and &konsole;

Help Report Bug...

  Submit a bug report or a feature request for &konsole;

Help About Konsole...

  Information about &konsole;'s author

Help About KDE...

  Information about the KDE project

### The toolbar

The toolbar is at the bottom of the &konsole; window.

It can be hidden and restored by toggling Show Toolbar in the Settings menu or by clicking the textured handle at the side of the bar. The bar contains a New icon and icons for the current sessions. Clicking New opens a new Shell session.

Clicking an existing session's icon makes that session active.

When the toolbar is hidden, Shift Left and Shift Right can be used to move between sessions.

### Command-line options

When &konsole; is started from the command-line, various options can be specified to modify its behavior.

`--help`

  List the various options

`--name`

  Set the name that appears in the titlebar

`--ls`

  Start a login shell

`--nowelcome`

  Suppress the "Welcome to &konsole;" message that normally appears in the titlebar

`-T,--title`

  Set the window title

`--xwin`

  Ignored

`--nohist`

  Disable the saving of lines that scroll off the top of the window

`--notoolbar`

  Start &konsole; without a toolbar

`--vt_sz` `CCxLL`

  Start a terminal window of CC Columns and LL lines

`-e` `command`

  Execute `command` instead of shell.

For instance:

    bash$ konsole--vt_sz 90x25--nohist

starts a &konsole; window with 90 columns and 25 rows, with no history

&konsole; also accepts generic &Qt; and &kde; options:

`--help-qt`

  List Qt-specific options

`--help-kde`

  List KDE-specific options

`--help-all`

  List all options

`--author`

  Show the author(s) names

`-v,--version`

  Show the version number

`--license`

  Show license information

## Credits and Copyright

&konsole; is maintained by Chris Machemer machey@ptd.net

The application &konsole; copyright 1997-2000 Lars Doelle lars.doelle@on-line.de

This document was written by Jonathan Singer jsinger@genome.wi.mit.edu

Converted to DocBook SGML by Michael McBride mmcbride@ematic.com and Lauri Watts vampyr@atconnex.net

&underFDL; &underGPL;

## Installation

&konsole; is part of the &kde; 2.0 base packages. It will automatically be installed with your &kde; installation, and requires &kde; 2.0 to function.

For more information, you should visit the &kde; website at http://www.kde.org/

To obtain &konsole; separately, download the kdebase package, and compile and install it as indicated in the package's main directory. New versions of kdebase can be obtained at ftp://ftp.kde.org/pub/

To build &konsole;:

    $  cd kdebase/konsole
    $  ./configure
    $  make
    Then as root:
    #  make install

Information on building &konsole; on platforms other than &Linux; is available in the `README.ports` file in the &konsole; source package. It provides a list of experts for certain platforms (Tru64, Solaris, OpenBSD) and requests volunteers from other &UNIX; platforms.

&documentation.index;