<reference>
    <title>@PACKAGE@ - Version @VERSION@</title>
    <partintro>
        <title>Packages</title>

        <para>
            The various source and binary packages are available at <ulink
            url="http://www.five-ten-sg.com/@PACKAGE@/packages/">http://www.five-ten-sg.com/@PACKAGE@/packages/</ulink>.
            The most recent documentation is available at <ulink
            url="http://www.five-ten-sg.com/@PACKAGE@/">http://www.five-ten-sg.com/@PACKAGE@/</ulink>.
        </para>

        <para>
            A <ulink url="http://www.selenic.com/mercurial/wiki/">Mercurial</ulink> source
            code repository for this project is available at <ulink
            url="http://hg.five-ten-sg.com/@PACKAGE@/">http://hg.five-ten-sg.com/@PACKAGE@/</ulink>.
        </para>

        <para>
            A companion terminal monitor project is available at <ulink
            url="http://www.five-ten-sg.com/510ConnectbotMonitor">http://www.five-ten-sg.com/510ConnectbotMonitor</ulink>
        </para>
    </partintro>

    <refentry id="x@PACKAGE@.1">
        <refentryinfo>
            <date>2014-07-08</date>
            <author>
                <firstname>Carl</firstname>
                <surname>Byington</surname>
                <affiliation><orgname>510 Software Group</orgname></affiliation>
            </author>
        </refentryinfo>

        <refmeta>
            <refentrytitle>@PACKAGE@</refentrytitle>
            <manvolnum>1</manvolnum>
            <refmiscinfo>@PACKAGE@ @VERSION@</refmiscinfo>
        </refmeta>

        <refnamediv id='name.1'>
            <refname>@PACKAGE@</refname>
            <refpurpose>an android vt320/tn5250 terminal emulator for telnet/ssh connections</refpurpose>
        </refnamediv>

        <refsect1 id='build.1'>
            <title>Build method</title>
            <para>
                This is an android project with native code, so
                "ndk-build clean; ndk-build; android update project -p . -t android-16; ant debug"
                should build cleanly.
            </para>
        </refsect1>

        <refsect1 id='introduction.1'>
            <title>Introduction</title>
            <para>
                I belive that the previous connectbot projects are improperly licensed.
                They contain a mix of Apache 2.0 and GPLv2+ code, and those two licenses
                are incompatible. I have relicensed this as GPLv3+, since that is
                compatible with the licenses of all the sub-parts.
            </para>
            <para>
                This fork extends previous connectbot projects in two ways. It includes
                tn5250 terminal emulation, in addition to the previous vt320 terminal
                emulation. It also contains hooks for a separate monitoring process
                that has access to some of the internal operations in this emulator.
            </para>
        </refsect1>

        <refsect1 id='changes.1'>
            <title>Changes from previous Connectbots</title>
            <itemizedlist>
                <listitem><para>
                    The soft function keypad now has better labels, and can generate
                    all 24 function keys for 5250 emulation. A hardware button can
                    be configured to display that function keypad.
                </para></listitem>

                <listitem><para>
                    A deployment.connections text file is read (and deleted) on
                    startup. This may be used to preconfigure the global options
                    and to create an initial set of host connections.
                </para></listitem>

                <listitem><para>
                    The font sizes are now kept with one decimal point, and font
                    size changes are done by scaling by a constant factor of 1.1,
                    rather than the linear additive 2 point factor.
                </para></listitem>
            </itemizedlist>
        </refsect1>

        <refsect1 id='monitor.1'>
            <title>Terminal Monitor</title>
            <para>
                For every terminal session (local, telnet, ssh or tn5250), this
                terminal emulator also makes a connection to a terminal monitor
                process, which can see cursor movement and screen contents, and can
                inject characters to send to the host.
            </para>

            <para>
                The terminal monitor is invoked by calling an android Intent
                named "com.five_ten_sg.connectbot.monitor.MonitorService". That
                ensures that the monitor process is running, and should then
                be listening on TCP port 6000 for incoming connections. The terminal
                emulator then connects to the terminal monitor on port 6000.
                The native android Intent and Service communication mechanisms
                are not used.
            </para>

            <para>
                The messages exchanged between the terminal emulator and the
                terminal monitor are arrays of uint16 values in network byte
                order. Each message starts with a uint16 message byte length,
                followed by that many bytes of data. Note that the message length
                will always be even. The next uint16 contains the message
                command value, and the remaining uint16 values are the arguments
                if any for that command.
            </para>

            <para>
                Any arguments that are keystrokes or characters are represented
                as 16 bit unicode. Note that the first 256 such characters are
                identical to the ISO-8859-1 latin character set.
            </para>

            <para>
                INIT = 0 (TE -> Monitor). The argument is a string of uint16
                characters. The meaning of these characters is defined by the
                monitor. It might be a fully qualified path name, or some other
                data used by the monitor to drive the monitoring of this
                connection.
            </para>

            <para>
                ACTIVATE = 1 (TE -> Monitor).  The first argument is the
                number of lines. The second argument is the number of columns.
                That is followed by lines*columns uint16 character codes.
                This connection is now the active connection. It is the
                topmost (or only) window visible to the user - typed keystrokes
                will be sent to the host on the other end of this connection.
            </para>

            <para>
                KEYSTATE = 2 (TE -> Monitor). The argument is a single uint16
                value, 1 for key down, 0 for key up. The TE tracks a single special
                key for the monitor, and reports key up/down state when it changes.
                The actual key is configurable.
            </para>

            <para>
                CURSORMOVE = 3 (TE -> Monitor).
                The first argument is the line number (0..23),
                the second argument is the column number (0..79), and the third
                argument is the reason for sending this cursor update. REASON=0 is
                from a previous CURSORREQUEST command. REASON=1 is a cursor update
                related to the previous SCREENCHANGE buffer update. REASON=2 is
                a cursor update caused by user keystrokes.
            </para>

            <para>
                SCREENCHANGE = 4 (TE -> Monitor). The first argument is the
                number of lines. The second argument is the number of columns.
                That is followed by lines*columns uint16 character codes.
            </para>

            <para>
                FIELDVALUE = 5 (TE -> Monitor).
                SETFIELD = 5 (Monitor -> TE).
                The first argument is the line number (0..23)
                and the second argument is the column number (0..79).
                That is followed by the field value, a sequence of uint16
                character codes from the screen buffer. The field
                covers N columns, where N = (message length - 4) / 2.
                When sent from the monitor to the emulator, this causes
                the emulator to send the field codes to the host. This is
                also used as the reply message from the emulator to the
                monitor for a previous GETFIELD from the monitor.
            </para>

            <para>
                GETFIELD = 6 (Monitor -> TE).
                The first argument is the line number (0..23)
                and the second argument is the starting column number (0..79),
                and the third argument is the field length in columns.
                This command causes the emulator to send a FIELDVALUE message
                back to the monitor.
            </para>

            <para>
                SCREENWATCH = 7 (Monitor -> TE).
                The first argument is the line number (0..23)
                and the second argument is the starting column number (0..79),
                and the third argument is the field length in columns.
                This command causes the emulator to watch the specified
                part of the screen for changes. When that part of the screen
                changes, the emulator will send a SCREENCHANGE message back
                to the monitor.
            </para>

            <para>
                DEPRESS = 8 (Monitor -> TE). The argument is a single uint16
                value containing the vk_key value. This command causes the emulator
                to simulate a keypress for that key. The codes are defined
                <ulink url="http://msdn.microsoft.com/en-us/library/windows/desktop/dd375731">here</ulink>.
            </para>

            <para>
                SHOWURL = 9 (Monitor -> TE). The single argument is a sequence
                of uint16 character codes forming a URL to be displayed.
            </para>

            <para>
                SWITCHSESSION = 10 (Monitor -> TE). There are no arguments. The TE
                should display this session.
            </para>

            <para>
                CURSORREQUEST = 11 (Monitor -> TE). There are no arguments. The TE
                should send a CURSORMOVE update to the monitor. Cursor movement caused
                by SETFIELD or DEPRESS commands does not trigger CURSORMOVE updates
                in block mode (tn5250) sessions. Those commands do trigger CURSORMOVE
                updates in async mode (telnet, ssh) sessions.
            </para>
        </refsect1>

        <refsect1 id='todo.1'>
            <title>TODO</title>
            <para>
                The tn5250 ssl/tls key storage should use the same storage mechanism
                as the base ssh key storage.
            </para>
        </refsect1>

        <refsect1 id='copyright.1'>
            <title>Copyright</title>
            <para>
                Copyright (C) 2014 by 510 Software Group &lt;carl@five-ten-sg.com&gt;
            </para>
            <para>
                This program is free software; you can redistribute it and/or modify it
                under the terms of the GNU General Public License as published by the
                Free Software Foundation; either version 3, or (at your option) any
                later version.
            </para>
            <para>
                You should have received a copy of the GNU General Public License along
                with this program; see the file COPYING.  If not, please write to the
                Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
            </para>
        </refsect1>

        <refsect1 id='credits.1'>
            <title>Credits</title>
            <para>
                Based on VX Connectbot provided under the Apache
                License, Version 2.0. Copyright (C) 2012 Martin
                Matuska http://connectbot.vx.sk
            </para>
            <para>
                Based on Irssiconnectbot provided under the Apache
                License, Version 2.0. Copyright (C) 2013
                Iiro Uusitalo and Ville Kerminen
                https://github.com/irssiconnectbot/irssiconnectbot
            </para>
            <para>
                Based on ConnectBot provided under the Apache License,
                Version 2.0. Copyright (C) 2007-2008 Kenny Root
                http://the-b.org and Jeffrey Sharkey http://jsharkey.org
            </para>
            <para>
                Based on the Trilead SSH2 client provided
                under a BSD-style license. Copyright (C) 2007 Trilead
                AG. http://www.trilead.com
            </para>
            <para>
                Based on JTA Telnet/SSH client provided under the
                GPLv2 license.  Copyright (C) 1996-2005 Matthias L. Jugel and
                Marcus Meiner. http://www.javassh.org
            </para>
            <para>
                Based on TN5250J terminal emulator provided under the GPLv2
                license. Copyright (C) 2001 Kenneth J. Pouncey.
                http://tn5250j.sourceforge.net/
            </para>
            <para>
                Includes the JSOCKS library, provided
                under the GNU LGPL license. http://jsocks.sourceforge.net
            </para>
            <para>
                Includes JZlib provided under a BSD-style
                license. Copyright (C) 2000-2004 JCraft, Inc.
                http://www.jcraft.com
            </para>
            <para>
                Includes the ssh-agent service developed by Roberto
                Tyley https://github.com/rtyley
            </para>
            <para>
                SCP file transfer support is based on
                https://github.com/staktrace/connectbot/commits/filetransfer
                modifications by Kartikaya Gupta.
            </para>
            <para>
                Internal file selection dialog is based on Android File
                Dialog by Alexander Ponomarev, provided under a BSD-style
                license.
                http://code.google.com/p/android-file-dialog
            </para>
        </refsect1>

        <refsect1 id='version.1'>
            <title>Version</title>
            <para>
                @VERSION@
            </para>
        </refsect1>
    </refentry>

</reference>