konsole/doc/sgml/konsole.sgml

<!doctype linuxdoc system>

<!-- The Konsole Handbook -->

<article>

<!-- Title information -->

<title>The Konsole Handbook
<author>Lars D&ouml;lle,
<htmlurl url="mailto:lars.doelle@on-line.de" name="lars.doelle@on-line.de">
<date>Version 0.0.1, 06 Jun 1998
<abstract>This document describes Konsole version 0.8.6
Please be aware of the fact that this document is under construction.

<!-- Table of contents -->
<toc>
<!-- Begin the document -->

<sect>Introduction
<p>
Konsole is a X terminal emulation for the K Desktop Environment.
<p>
In the context of a graphical user interface being a terminal
emulation means, that it's task is to provide a display
to an application that is originally designed to run on a computer
with a character terminal attached.
<p>
To give a short taxonomy of free X terminals, there' two other
of this kind: xterm, which is the original, written even before X
itself (a month or two), and xvt, a light-wight xterm clone, on
which most other currently available derivates (notably eterm)
base. After a decade, konsole is the first rewrite from ground up.
While xterm has definitely been hacked to death meanwhile (it's
README starts with the words "Abandon All Hope, Ye Who Enter Here"),
konsole offers a fresh start using contemporary technologies and
understanding of X.

<sect>Overview
<p>
When invoked, konsole starts this client application (which is
the shell by default) and displays all the clients output in it's
window while forwarding key presses and mouse clicks to the client.
<p>
By this most of konsole's behavior is really controlled by the
application that actually runs in it. There are only a few
special features that konsole adds to this. These additional
features are not uncommon, so much of the following description
applies to any decent terminal emulation.
<p>

<itemize>
<item>History Buffer
<p>
Text that is scrolled out of the screen is kept in a history buffer
for later review. Currently a maximum of 100 lines are kept in this
buffer. While it is not possible to change text that has ended up
in the buffer, one can look at it and copy it partially or entirely
to the clipboard.

<item>Keyboard
<p>
The Shift-PageUp and Shift-PageDown keys are used to scroll through
the history buffer. All other keystrokes are passed on to the 
application run within the emulation. Note that their might be
some dead keys.

<item>Mouse
<p>
You need a three button mouse to make full use of the terminal.
The buttons have different functions:
<p>
  <itemize>
  <item>Left button
    <p>
    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 ibeam (bar) cursor is shown.
    <p>
    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 reverse for visual
    feedback. As soon as the button is released, the marked text copied
    to the clipboard for further use within Konsole or another application.
    <P>
    Normally, new-line characters are inserted at the end of each line
    selected.  This is normally 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.
    <p>
    It the upper or lower edge of the text area is touched while marking,
    Konsole scrolls up or down, thereby eventually exposing text within the
    history buffer. The scrolling stops as soon as you stop moving the
    mouse.
    <p>
    After releasing the mouse, 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 you've clicked the left mouse button.
    <p>
    To mark text on a mouse aware application the shift key has to
    be pressed when clicking.

  <item>Middle Button
    <p>
    Pressing the middle button copies text currently in the clipboard.
    This works just as if clipboard contents is typed on the keyboard,
    so the application running in the emulation will react by it's own
    way on it.

  <item>Right Button
    <p>
    The right button brings up the configuration menu. Additionally,
    the shift and the control key may be uses with this button to
    get access to other parts of the menu.
  </itemize>
<p>
<item>Sessions
<p>
Konsole offers to run several sessions (programs) at once. New sessions
can be started using the "New"-menu. One can switch between sessions
with the "Sessions"-menu. Both menus are available as right mouse button
menus, too, when pression the shift or the control key as modifiers.
<p>
The session menu can be freely configured due to the local needs.
(A section explaining how is missing, see /opt/kde/share/apps/konsole
for some examples.)

</itemize>

<sect>Configuration
<p>
Using the option menu one can control much of konsole's appearance.
The configuration is both available using the menu bar or clicking
on konsole's window with the right mouse button.
<itemize>
<item>Menu Bar
   <p>
  Having this option checked provides a menu bar in the top of the
  window. Different from the regular behavior, the menu bar does
  not accept "hot keys" to prevent making some ALT-key combinations
  unusable for the client applications.
   <p>
<item>Frame
   <p>
  Selects whether a decorating border is to be drawn.
   <p>
<item>Scrollbar
   <p>
  Having a scrollbar provides another way to control the history
  buffer. Do not confuse this feature with scrolling inside the
  client application, although it often may (and shall) look like.
   <p>
<item>Font
   <p>
   The font menu offers two completely different adjustments.
   First, a collection of fonts of different sizes given, so
   that a font that matches both the resolution and the prefered
   window size can be chosen. Second, there is one additional
   "Linux" font, that is different from all the above by it's
   encoding. One needs to have this font set when running a
   linux console emulation.
   <p>
<item>Size
   <p>
   While the size of the window is freely adjustable by the regular
   means, it may sometimes be desireable to set the size of konsole
   window to match the requierements of old, size unaware programs.
   The size menu offeres the most often used sizes. If non of them
   match, resize the screen due to your needs. When the size is
   changed, konsole displays it in the title to help with the
   adjustment.
   <p>
<item>Color Schema
   <p>
   This option allows one to select a color schema.
   (A section explaining how is missing, see /opt/kde/share/apps/konsole
   for some examples.)
   <p>
</itemize>
<p>
For more historical reasons, the backspace key shall not emit
CTRL-H when running with Linux. (The only application that i
know which really depends on this special behavior is "emacs",
where CTRL-H means "Help"). Although every application is
properly configurable, so one could have configured emacs to
accept F1 as the help key, an uncommon use of the keyboard
codes has been traditionalized. Don't worry about it, just
make sure that the option
<itemize>
<item>BS sends DEL
</itemize>
is checked.
<p>
In this case, konsole send a DEL character (hex 7F) when pressing
the backspace key instead of the regular BS character (hex 08).
The delete key is also sending something different from the DEL
character in this case.
<p>
All the above options take effect immediately but only for the
current invocation. To make the adjustments permanent, click the
option:
<itemize>
<item>Save options
</itemize>

<sect>Installation
<p>
Konsole is currently part of the kdenonbeta package and should be
compiled and installed as indicated in the package's main directory.
<p>
If you experience problems with that, please refer to 
<ref id="probPack" name="installation problems"> below.

<sect>Bugs and FAQ
<p>
Before sending bug reports, please check the problem with another
X terminal to find out whether it is `konsole' specific or not.

<sect1>Installation Related Problems
<p>
Konsole requieres some specific fonts that come along with it's
distribution but are not installed due to the authors preference
not claim root privileges during the installation process. You'll
have to do this manually. See README.linux.console for details.

<sect1>Application Related Problems
<p>
Some programs have flaws when run under a X console.

<sect2>MC (midnight commander 4.1.21)
<p>
<itemize>
<item> only when the emulation is called 'xterm' mc reacts on resize events
    (before any key is pressed) and on (xterm) mouse events. Note that
    xterm mouse events aren't specific at all, e.g. the Linux console
    produces them also.

<item> After ^O (showing the secondary screen) mc does not propagate resize
    events at all to it's sub shell. Try this with xterm, or whatever else
    terminal emulation.

<item> Apparently it does more strange things with the sub shell.
    When resizing the window with the mc panels shown, the secondary
    screen gets somehow affected (by real or faked prompts). This gets
    even worse when an application program is running while doing so.

<item> sends out at least newlines but often more stuff when resizing while
    the panels are shown.

<item> Under high traffic, some parts of the text is known to get lost.
    Try `ripple' in the test directory until you notice a drop. Since
    i've been able to reproduce this bug with kvt, rxvt and xterm, and
    i validated also that the data is already lost at read(3), i may
    well have stumbled into something different here. Because i was
    also only able to produce this effect while running mc, i feel
    pretty certain that mc's sub shell handling causes this effect.

<item> Resizing does not work well when running under linux console emulation.
    Especially, mc does not forward the resize information to the subshell.
    It is not mouse aware then any longer, too.

</itemize>
   
<sect2>Vim 4.6
<p>
<itemize>
<item> emits a newline at exit, thereby producing a strange image on the
    secondary screen when run together with mc as default editor.
</itemize>
  
<sect2>dselect (Debian package manager front end):
<p>
<itemize>

<item> assumes black background. So turn to white-on-black color scheme
    when using it. When run under the linux console emulation, it does
    not cope well with resize events (segfault).
</itemize>


<sect1>Broken Termcap and Terminfo Databases
<p>
  Please be aware of the fact that most applications (those using ncurses)
  base their knowledge on how to talk to a terminal emulation on the 
  information within a database. This might well be wrong. Again, you
  should experience likely problems then with other emulations.
<p>
  So, for example:
<itemize>
<item>debian 1.3.1 (Bo) omits the kdch1 entry, thus the DELETE key does
    appear not to work properly. Other keys might be missing as well.

<item>the mc 4.1.21 distribution contains a xterm.ti with faulty hpa, vpa
    entries (with <tt/[/ omitted after <tt/ESC/). Even stranger, xterm runs
    happily with them, because of a feature, that allows to accept errorness
    sequences under some circumstances (<tt/ESC Pn C/ is treated like 
    <tt/ESC [ Pn C/, where <tt/C/ is a non-digit.).

<item>I've included a xterm.ti for this reason. (Compile using tic.)
</itemize>


<sect1>Problems with BACKSPACE, DELETE and Likely Keyboard Issues.
<p>
  Once upon a time there was a terminal without a delete key.
  This problem has been perpetuated in Linux and is still a 
  never ending nightmare. It has been worked around separately
  in all programs that have to deal with these keys and they
  have now ended up to be configurable and therefore are likely
  to come in configured wrong. And so is konsole.
<p>
  Konsole emits DEL (0x7f) for the BS key and ESC[3~ for the
  DEL key if the `BS sends DEL' option is activated, and then
  behaves like a typically configured Linux console. Ctrl-H (0x08)
  is then left for the use of the application programs, e.g. 
  typically configured emacs help.
<p>
  When this options is not set, the BS key sends BS (0x08) and
  the DEL key sends DEL (0x7f), as regular VT100s and IBM PCs do.
<p>
  [ Since every program can be configured BS=BS, DEL=DEL, and
    the poor terminal without delete key mentioned above exists
    today only in legends, the author wonders why this BS hack
    is still around. ]
<p>
  ctrl-^ == ctrl-~ == ctrl-` == RS == 0x1e cannot be typed with
  an european keyboard map loaded, since all three base characters
  are prefixes (i.e. are eventually to be continued with a second 
  character). X11 is known to have these dead keys.


<sect1>Color Scheme
<p>
  Because of a storm of complaints about the color scheme,
  konsole offers configurable color schemes in it's latest
  versions. A proper document on them is still missing.

<sect1>Fonts
<p>
(Slightly outdated, check README.linux.console)
<p>
<itemize>
<item> the VGA font uses a different encoding then the other ones,
    and will therefore not display graphic and national characters
    when run with TERM=xterm. It is best suited to dos(1) and
    also work somewhat with TERM=linux. Note that the inclusion
    of this font is experimental.

<item> other fonts but the ones included appear not to be usable for
    terminal applications. This is not that much due to their
    variable pitch (which i'd implemented experimentally), but
    because they miss the graphical subset. Try xfd(1x) to check
    this.

<item> In general a proper font family for terminals seems to be 
    missing at all. If you know about a scalable terminal font
    family, please drop me a line.
</itemize>


<sect1>Security
<p>
  Although konsole is prepared to be installed root-suid, it is not
  intented to be used so. Don't do it. Konsole drops privileges
  immediately after being started. Secure keyboard (X11) is not
  implemented which means that other X11 applications can get the
  keyevents from konsole, if they want. Beware of trojan horses.
<p>
  konsole does not fchown(2) the pseudo tty. This means, that in a
  multiuser environment someone may eavesdrop your (root) session.
  For newer Linux kernels (2.1/2.2), konsole will deny such attempts.
  To validate whether this is possible or not, try the following within
  konsole:
<p>
<verb>
    $ tty
    /dev/ttyp3
</verb>
<p>
  As another (non-root) user, try:
<p>
<verb>
    $ echo 'test' > /dev/ttyp3
</verb>
<p>  
  If you receive the string within the konsole's session, the session
  is insecure.
<p>  
  For other UNIXes, this hole will be closed in a bit,
  but the solution will require konsole being installed root/suid.
  I'm aware, that this might not be possible in every installation,
  but i cannot help that.

<sect1>Known Bugs (konsole-0.8.6)
<p>
<itemize>
<item> keys on the keypad does not cause any effect when numlock is not
  set. This truly reflects, what i receive from Qt. All the keys
  come in as #ffff. Think this comes from the eventFilter i had to
  install to get the key-presses.

<item> check TODO for "bugs" due to missing features, also.
</itemize>


<sect1>Features That Will Not Be Implemented.
<p>
<itemize>
<item> utmp entries.
<p>
  The utmp is a database that reports who is currently logged on.
  This is used by programs like who, finger, wall, talk, etc. to
  list the users of a system and to contact them.
<p>
  It does not make sense when used with an X terminal, since there
  is nothing like _the_ terminal then, to which one can send notices.
<p>
  The proper solution would be, to stamp the utmp with the xdm/kdm
  session manager. Further, a proper notification/chat program should
  be run automatically when the X session starts (ktalk?), so that
  a communication channel is available to the one at the console.
</itemize>

</article>