<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
 <!ENTITY konsole "<application>Konsole</application>">
 <!ENTITY % addindex "IGNORE">
 <![ %addindex; [ <!ENTITY kdedocindex SYSTEM "docindex.docbook"> ]]>
]>
<book lang="en">
 <bookinfo>
  <title>Manual da &konsole;</title>
  <author>
   <firstname>Lars</firstname>
   <surname>D&ouml;lle</surname>
   <affiliation>
    <address><email><ulink url="mailto:lars.doelle@on-line.de">lars.doelle@on-line.de</ulink></email></address>
   </affiliation>
  </author>
  <date>06/06/1998</date>
  <releaseinfo>0.0.1</releaseinfo>
  <abstract>
   <para>
   Este documento descreve a versão 0.8.6 da &konsole;.
   </para>
  </abstract>
 </bookinfo>

 <chapter id="Introduction">
  <title>Introdução</title>

  <para>
  &konsole; é emulador de terminal para X para o KDE
  </para>

  <para>
  No contexto de uma interface gráfica uma emulação de terminal permite
  correr aplicações que foram originalmente concebidas para correr
  numa computador com um terminal alfanumérico ligado.
  </para>

  <para>To give a short taxonomy of free X terminals, there' two other
  of this kind: <application>xterm</application>, which is the
  original, written even before X itself (a month or two), and
  <application>xvt</application>, a light-wight xterm clone, on which
  most other currently available derivates (notably
  <application>eterm</application>) base. After a decade, &konsole; is
  the first rewrite from ground up.  While
  <application>xterm</application> has definitely been hacked to death
  meanwhile (its <filename>README</filename> starts with the words
  "Abandon All Hope, Ye Who Enter Here"), &konsole; offers a fresh
  start using contemporary technologies and understanding of X.</para>
</chapter>

<chapter id="Overview">
<title>Overview</title>

<para>
Quando invocada, &konsole; inicia a aplicação cliente (que por omissão é
uma linha de comando) e mostra as mensagens produzidas pela aplicação
na sua janela, ao mesmo tempo que envia as teclas ou botões de
rato premidos para esta.
</para>

<para>
Na verdade a maior parte do comportamento da &konsole; é contralado
pela aplicação nela executada. Há apenas algumas funcionalidades que a
&konsole; adiciona. Estas funcionalidades são bastante comuns, pelo que
a descrição que se segue é valida para quase todas as emulações de
terminais.
</para>

<para>
<variablelist>
<varlistentry>
<term>Tampão com Historial</term>
<listitem>
<para>
O texto que saí do ecrã é mantido num tampão para posterior consulta.
Actualmente são guardadas no máximo 100 linhas de texto neste tampão.
Embora não seja possivel alterar o texto colocado neste tampão, podes
visualizá-lo e copiá-lo parcial ou totalmente para a área de
transferência.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Teclado</term>
<listitem>
<para>As combinações de teclas
<keycombo><keycap>Shift</keycap><keycap>PageUp</keycap></keycombo>,
<keycombo><keycap>Shift</keycap><keycap>PageDown</keycap></keycombo>,
<keycombo><keycap>Shift</keycap><keycap>Up</keycap></keycombo> e
<keycombo><keycap>Shift</keycap><keycap>Down</keycap></keycombo>
são utilizadas para viajar através do tampão do historial.
Todas a outras teclas premidas são passadas à aplicação que corre
dentro do terminal. Não te esqueças que as algumas das teclas premidas
podem ser "teclas mortas".
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Rato</term>
<listitem>
<para>
Necessita de uma rato com três botões para utilizar ao máximo o terminal.
Os botões têm as seguintes funções:
</para>
<para><variablelist>
<varlistentry>
<term>Botão esquerdo</term>
<listitem>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<para>To mark text on a mouse aware application the shift key has to
be pressed when clicking.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Botão Central</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Botão Direito</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Sessões</term>
<listitem>
<para>&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.</para> <para>The session menu can be freely configured due
to the local needs.  (A section explaining how is missing, see
<filename>/opt/kde/share/apps/konsole</filename> for some
examples.)</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</chapter>

<chapter id="Configuration">
<title>Configuração</title>

<para>
Ao utilizar esta entrada no menu pode controlar grande parte da
aparência da &konsole;. A configuração está igualmente disponível
carregando na &konsole; com o botão direito do rato.
<variablelist>
<varlistentry>
<term>Menu Bar</term>
<listitem>
<para>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 <keycap>ALT</keycap>-key
combinations unusable for the client applications.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Frame</term>
<listitem>
<para>Selects whether a decorating border is to be drawn.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Scrollbar</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Font</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Size</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Color Schema</term>
<listitem>
<para>This option allows one to select a color schema.  (A section
explaining how is missing, see
<filename>/opt/kde/share/apps/konsole</filename> for some
examples.)</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>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
<itemizedlist>
<listitem>
<para>BS envia DEL</para>
</listitem>
</itemizedlist>

está seleccionada.</para>

<para>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.</para>

<para>All the above options take effect immediately but only for the
current invocation. To make the adjustments permanent, click the
option:
<itemizedlist>
<listitem>
<para>Save options</para>
</listitem>
</itemizedlist>
</para>
</chapter>

<chapter id="Installation">
<title>Installation</title>

<para>&konsole; is currently part of the kdenonbeta package and should be
compiled and installed as indicated in the package's main directory.</para>

<para>If you experience problems with that, please refer to 
<link linkend="probPack">installation problems</link> below.</para>
</chapter>

<chapter id="Bugs-and-FAQ">
<title>Bugs and FAQ</title>

<para>Before sending bug reports, please check the problem with another
X terminal to find out whether it is `&konsole;' specific or not.</para>

<sect1 id="probPack">
<title>Installation Related Problems</title>

<para>
&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 <filename>README.linux.console</filename> for
details.</para>
</sect1>

<sect1 id="application-related-problems">
<title>Application Related Problems</title>

<para>Some programs have flaws when run under a X console.</para>

<sect2 id="midnight-commander">
<title>MC (midnight commander 4.1.21)</title>

<para><itemizedlist>
<listitem>
<para> 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.
</para>
</listitem>
<listitem>
<para> After &circ;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.
</para>
</listitem>
<listitem>
<para> 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.
</para>
</listitem>
<listitem>
<para> sends out at least newlines but often more stuff when resizing while
the panels are shown.
</para>
</listitem>
<listitem>
<para> 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
<application>kvt</application>, <application>rxvt</application> and
<application>xterm</application>, 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.
</para>
</listitem>
<listitem>
<para> 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.
</para>
</listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="vim">
<title>Vim 4.6</title>

<para><itemizedlist>
<listitem>
<para> emits a newline at exit, thereby producing a strange image on the
secondary screen when run together with mc as default editor.</para>
</listitem>
</itemizedlist>
</para>
</sect2>

<sect2 id="dselect">
<title>dselect (Debian package manager front end):</title>

<para><itemizedlist>
<listitem>
<para> 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).</para>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>

<sect1 id="broken-termacap-and-terminfo">
<title>Broken Termcap and Terminfo Databases</title>

<para>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.</para>

<para>So, for example:
<itemizedlist>
<listitem>
<para>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.
</para>
</listitem>
<listitem>
<para>the mc 4.1.21 distribution contains a xterm.ti with faulty hpa, vpa
entries (with <literal remap="tt">[</literal> omitted after <literal remap="tt">ESC</literal>). Even stranger, xterm runs
happily with them, because of a feature, that allows to accept errorness
sequences under some circumstances (<literal remap="tt">ESC Pn C</literal> is treated like 
<literal remap="tt">ESC [ Pn C</literal>, where <literal remap="tt">C</literal> is a non-digit.).
</para>
</listitem>
<listitem>
<para>I've included a xterm.ti for this reason. (Compile using tic.)</para>
</listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="problems-with-backspace-delete">
<title>Problems with BACKSPACE, DELETE and Likely Keyboard Issues.</title>

<para>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;.</para>

<para>&konsole; emits DEL (0x7f) for the BS key and ESC&lsqb;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.</para>

<para>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.</para>

<para>&lsqb; 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. ]</para>

<para>ctrl-&circ; == 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.</para>
</sect1>

<sect1 id="color-scheme">
<title>Color Scheme</title>

<para>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.</para>
</sect1>

<sect1 id="fonts">
<title>Fonts</title>

      <para>(Slightly outdated, check
      <filename>README.linux.console</filename>)</para>

<para><itemizedlist>
<listitem>
<para> 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.
</para>
</listitem>
<listitem>
<para> 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.
</para>
</listitem>
<listitem>
<para> 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.</para>
</listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="security">
<title>Security</title>

<para>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.</para>

<para>&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;:
<screen>
<prompt>$</prompt> <userinput>tty</userinput>
<computeroutput>/dev/ttyp3</computeroutput></screen>
</para>

<para>As another (non-root) user, try:
<screen>
<prompt>$</prompt> <userinput>echo 'test' &gt; /dev/ttyp3</userinput></screen>
</para>

<para>If you receive the string within the &konsole;'s session, the
session is insecure.</para>

<para>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.</para>
</sect1>

<sect1 id="known-bugs">
<title>Known Bugs (&konsole;-0.8.6)</title>

<para><itemizedlist>
<listitem>
<para> 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 &num;ffff. Think this comes from the eventFilter i had to
install to get the key-presses.
</para>
</listitem>
<listitem>
<para>
leia o ficheiro TODO para ficar a par das funcionalidades que ainda não
foram implementadas.
</para>
</listitem>
</itemizedlist>
</para>
</sect1>

<sect1 id="not-to-implement">
<title>Características que não serão implementadas</title>

<para><variablelist>
<varlistentry>
<term>Entradas utmp.</term>
<listitem>
<para>
O utmp é uma base de dados que regista quem está actualmente ligado.
É utilizada por comandos como o who, finger, wall, talk, etc. para
listar os utilizadores de uma máquina e contactá-los.
</para>

<para>Não faz sentido utilizá-la em conjunto com um terminal para X, uma
vez que não há <emphasis>o</emphasis> terminal para o qual se podem
enviar avisos.
</para>

<para>
A solução correcta seria actualizar o utmp com o gestor de sessões
xdm/kdm. Para mais, um programa de gestão de avisos/conversações poderia
ser automáticamente executado quando a sessão começa (ktalk?), de modo
que esteja disponível um canal de comunicação com o utilizador.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
</chapter>
<![ %addindex; [ &kdedocindex; ]]>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-general-insert-case: lower
sgml-shorttag: t
End:
-->
<!-- actualizado para a versão CVS :1.2: -->

<!--
<para>
Tradução da documentação por Pedro Morais <email>morais@kde.org</email>
</para>     
-->
