<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>

        <para>
            Bitcoin donations for this project may be sent to
            <ulink url="bitcoin:1EkbpYhcbAwmU3L7xXPisHQdwWSyjdaY2A">bitcoin:1EkbpYhcbAwmU3L7xXPisHQdwWSyjdaY2A</ulink>
        </para>
    </partintro>

    <refentry id="x@PACKAGE@.1">
        <refentryinfo>
            <date>2019-10-04</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 and ssh connections</refpurpose>
        </refnamediv>

        <refsect1 id='build.1'>
            <title>Build method</title>
            <para>
                This is an android project with native code, so
                "make builder style=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>Other changes from previous Connectbots</title>
            <itemizedlist>
                <listitem><para>
                    The Android SecureRandom bug has been fixed in newer versions
                    of Android, but this code now compensates for that bug in
                    older versions. If you have keys generated on older Android
                    devices, those keys should be discarded, and you should generate
                    new keys.
                </para></listitem>

                <listitem><para>
                    The underlying compression code from jcraft has
                    been updated. The underlying socks proxy code has
                    been updated. The underlying ssh code has been
                    updated from trilead to ganymed. Elliptic curve
                    crypto is now supported, but the NIST curves are
                    placed after the RSA and DH types in the list of
                    key exchange algorithms, so they should only be
                    used if the server does not support RSA or
                    DH. This change is based on on a general lack of
                    trust in NIST curves that have possibly been
                    compromised by the NSA.
                </para></listitem>

                <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 optionally deleted) on
                    startup. This may be used to preconfigure the global options
                    and to create an initial set of host connections. This is only
                    useful for bulk deployments.
                </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>

                <listitem><para>
                    On a per-host basis, you can either allow the font size to change
                    the number of rows and columns depending on the visibility
                    of the soft keyboard, or you can fix the number of rows and colums.
                    Using a larger font with a fixed number of rows and columns, you
                    may only be able to see the top left part of the logical screen that
                    is being used by the host system. There is no vertical or horizontal
                    scrolling yet.
                </para></listitem>

                <listitem><para>
                    The configurable hardware buttons can now change the font size.
                </para></listitem>

                <listitem><para>
                    The soft function keypad now includes the cursor movement keys.
                </para></listitem>

            </itemizedlist>
        </refsect1>

        <refsect1 id='helppages.1'>
            <title>Help Pages</title>
            <itemizedlist>
                <listitem><para><ulink url="About.html">About</ulink> - including list of credits</para></listitem>
                <listitem><para><ulink url="Hints.html">Hints</ulink></para></listitem>
                <listitem><para><ulink url="PhysicalKeyboard.html">Physical Keyboard</ulink></para></listitem>
                <listitem><para><ulink url="5250Keys.html">5250 Keys</ulink></para></listitem>
                <listitem><para><ulink url="ScreenGestures.html">Screen Gestures</ulink></para></listitem>
                <listitem><para><ulink url="VirtualKeyboard.html">Virtual Keyboard</ulink></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 length,
                followed by that many uint16 values.
                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 characters are represented as 16 bit
                unicode. Note that the first 256 such characters are identical to the
                ISO-8859-1 latin character set. There is no provision for handling
                surrogate pairs as in UTF-16. Keystroke arguments (see DEPRESS) are
                represented as Microsoft Virtual-Key codes, defined
                <ulink url="https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes">here</ulink>.
            </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 for
                the current screen contents.
                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 for
                the current screen contents.
            </para>

            <para>
                Every SCREENCHANGE message from the TE will be followed by a
                CURSORMOVE message.
            </para>

            <para>
                When the TE sends the screen contents as a result of a previous screen
                watch, the screen watch area is then reset to the entire screen. The
                monitor is then responsible for sending a screenwatch
                command to set the watch area to something appropriate for that new
                screen. Once the monitor has set the watch area to some part of a
                single line, there is no mechanism for the monitor to reset it to
                back to the entire screen. That reset only happens when the TE sends
                the screen contents.
            </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).
                When sent from the monitor to the emulator, this causes
                the emulator to send the field codes to the host (for async
                modes) or to set the specified field contents (for block modes).
                If the field length is zero, the TE should move the cursor to the specified line/column.
            </para>

            <para>
                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. The initial screen watch area is the entire
                screen.
            </para>

            <para>
                Subsequent screenwatch requests replace the current one, so the TE
                has only one watch area at any time.
            </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="https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes">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>

            <para>
                SAYSTRING = 12 (TE -> Monitor). The first argument is nonzero if
                any current speech should be flushed. The second argument is nonzero
                if this speech should be synchronous. That is followed by uint16
                character codes to be spoken. Note that the language is specified
                by the monitor, not the TE.
            </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) 2019 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='version.1'>
            <title>Version</title>
            <para>
                @VERSION@
            </para>
        </refsect1>
    </refentry>

    <refentry id="x@PACKAGE@.5">
        <refentryinfo>
            <date>2019-10-04</date>
            <author>
                <firstname>Carl</firstname>
                <surname>Byington</surname>
                <affiliation><orgname>510 Software Group</orgname></affiliation>
            </author>
        </refentryinfo>

        <refmeta>
            <refentrytitle>deployment.connections</refentrytitle>
            <manvolnum>5</manvolnum>
            <refmiscinfo>@PACKAGE@ @VERSION@</refmiscinfo>
        </refmeta>

        <refnamediv id='name.5'>
            <refname>deployment.connections</refname>
            <refpurpose>deployment file for @PACKAGE@</refpurpose>
        </refnamediv>

        <refsect1 id='description.5'>
            <title>Description</title>

            <para>The <command>deployment.connections</command> sample
            file is below. If this file exists at the top
            level of the external storage (as returned by
            Environment.getExternalStorageDirectory().getAbsolutePath()),
            it is read, parsed, and optionally deleted.  Comments start with #
            and extend to the end of the line.
            </para>

            <para>
            The deployment file is deleted unless it contains "delete_deployment=false"
            in the global options section. In that case, the file remains, and
            it is read and parsed every time the app is launched.
            </para>

            <literallayout class="monospaced"><![CDATA[
#
# available host keys:
#
# nickname          (string)
# color             (string)    ("red", "green", "blue", "gray")
# fontsize          (float)
# fixed_size        (boolean)
# fixed_width       (integer)
# fixed_height      (integer)
# pubkeyid          (integer)   (-2, -1)    -2=none, -1=any
# useauthagent      (string)    ("no", "confirm", "yes")
# postlogin         (string)
# compression       (boolean)
# httpproxy         (string)
# wantsession       (boolean)
# stayconnected     (boolean)
# delkey            (string)    ("del", "backspace")
# encoding          (string)    ("UTF-8", etc)
# username          (string)
# hostname          (string)
# port              (integer)
# monitor           (string)
# emulation         (string)    ("xterm-color", "xterm-256color", "xterm", "vt100", "ansi", "screen", or other answerback string)
# encryption5250    (string)    ("NONE", "SSLv2", "SSLv3", "TLS")
# library5250       (string)
# menu5250          (string)
# program5250       (string)
# wantx11forward    (boolean)
# x11host           (string)
# x11port           (integer)
# autolaunch        (boolean)


tn5250://pub400.com:23#battleship
    encryption5250=NONE
    fontsize=20
    fixed_size=true
    fixed_width=80
    fixed_height=25
    monitor=socket://localhost/pub400


#
# global settings are under global:// tag
#
# available global keys:
#
#   memkeys                     (boolean)
#   connPersist                 (boolean)
#   emulation                   (string) ("xterm-color", "xterm-256color", "xterm", "vt100", "ansi", "screen")
#   scrollback                  (integer)
#   rotation                    (string) ("Default", "Force landscape", "Force portrait", "Automatic")
#   shiftfkeys                  (boolean)
#   ctrlfkeys                   (boolean)
#   keymode                     (string) ("Use right-side keys", "Use left-side keys", "none")
#   camera                      (string) ("CTRL", "Esc", "Tab", "Screen Capture", "Ctrl+A then Space", "Ctrl+A", "Esc+A", "Monitor Key", "Soft Function Keypad", "Increase Font Size", "Decrease Font Size", "None")
#   volup                       (string) ("CTRL", "Esc", "Tab", "Screen Capture", "Ctrl+A then Space", "Ctrl+A", "Esc+A", "Monitor Key", "Soft Function Keypad", "Increase Font Size", "Decrease Font Size", "None")
#   voldn                       (string) ("CTRL", "Esc", "Tab", "Screen Capture", "Ctrl+A then Space", "Ctrl+A", "Esc+A", "Monitor Key", "Soft Function Keypad", "Increase Font Size", "Decrease Font Size", "None")
#   search                      (string) ("CTRL", "Esc", "Tab", "Screen Capture", "Ctrl+A then Space", "Ctrl+A", "Esc+A", "Monitor Key", "Soft Function Keypad", "Increase Font Size", "Decrease Font Size", "None")
#   ptt                         (string) ("CTRL", "Esc", "Tab", "Screen Capture", "Ctrl+A then Space", "Ctrl+A", "Esc+A", "Monitor Key", "Soft Function Keypad", "Increase Font Size", "Decrease Font Size", "None")
#   keepalive                   (boolean)
#   wifilock                    (boolean)
#   bumpyarrows                 (boolean)
#   eula                        (boolean)
#   extended_longpress          (boolean)
#   ctrl_string                 (string)
#   picker_string               (string)
#   picker_keep_open            (boolean)
#   list_custom_keymap          (string)    ("none", "full", "asus_tf", "sgh_i927", "sgh_i927_ics", "se_xppro")
#   bell                        (boolean)
#   bellVolume                  (float)
#   bellVibrate                 (boolean)
#   bellNotification            (boolean)
#   screen_capture_folder       (string)
#   screen_capture_popup        (boolean)
#   file_dialog                 (string)
#   download_folder             (string)
#   remote_upload_folder        (string)
#   upload_dest_prompt          (boolean)
#   background_file_transfer    (boolean)
#   debug_keycodes              (boolean)
#   delete_deployment           (boolean)
#   fg_color                    (integer)   (1 based just as shown by color activity)
#   bg_color                    (integer)   (1 based just as shown by color activity)
#

global://
    emulation=xterm-256color
    scrollback=200
    rotation=Force landscape
    camera=None
    volup=Soft Function Keypad
    voldn=Tab
    search=None
    ptt=Monitor Key
    eula=true
    fg_color=11
    bg_color=1

#
# end
]]></literallayout>
        </refsect1>

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

    </refentry>
</reference>