Welcome!

This file gives an overview of the Term48
shell, and is broken down into topics:

1. QUICK START 
2. PREFERENCES 
3. WHAT'S INSTALLED 
4. FOR DEVELOPERS

============================================

1. QUICK START

You can access the various special keys
(Crtl, Alt, arrows, etc.) by touching the top
left corner of the screen, and then pressing
special keys on the keyboard. When you touch
the top left corner of the screen, you will
enter 'metamode', which remaps the keyboard
keys to other functions. You can tell when
you are in metamode by the green 'M' in the
top right corner of the screen. Touching the
top left corner of the screen will toggle
metamode on and off. The default metamode
keys are:

  h: left arrow 
  j: down arrow 
  k: up arrow 
  l: right arrow 
  t: tab 
  e: escape 
  c: control 
  a: alt 
  v: paste

After pressing a key in metamode you will be
returned to normal input, excepting the arrow
keys, which leave you in metamode so you can
move the cursor around easily. 

For example, if you wanted to type Ctrl-C
(^C), then you would touch the top left
corner of the screen to enter metamode, press
'c' to hold down control, and then 'c' again
to send ^C. If you wanted to move the cursor
left, you would touch the top left corner of
the screen to enter metamode, then 'h' to
move the cursor left (perhaps several times).
Once you have the cursor where you want it,
you can start typing again by touching
the top left corner of the screen
(exiting metamode). Typing any key that
is not bound to a metamode function will
simply exit metamode.

If you have a physical keyboard on your
device, you can hold the space key to toggle
metamode on, and also hold down ordinary keys
to get uppercase letters.

If your device has a physical shift key, or
you are using a bluetooth keyboard, you can
also doubletap the right shift key to toggle
metamode on and off. Note that some keyboards
may not send right shift when you press the
right shift key (it may send left shift), but
this can be addressed in preferences.

The metamode keys are all configurable, as
described below.

============================================

2. PREFERENCES

Preferences are read from the .term48rc file
in $HOME. If this file does not exist at
startup it will be created at launch time
with the default settings (along with this
README). Term48 uses libconfig for
preferences, so the syntax of the .term48rc
file is as per libconfig. If there is an
error reading the preference file it will be
ignored and Term48 will launch with the
defaults.

Each of the preference options and their
default is shown below:

font_path = "/usr/fonts/font_repository/monotype/cour.ttf";
/* The path to the Unicode TTF font file to
 * use in the shell. This can be an absolute
 * or relative path. */

font_size = 16;
/* The font size for the shell. Term48 will
 * try to guess a reasonable size for your
 * screen, but otherwise defaults to this
 * value. */

text_color = [255, 255, 255];
/* The color for text, in RGB format. If you
 * would like classic green text on black
 * background, you can change this to [0,
 * 255, 0]. */

background_color = [0, 0, 0];
/* The background color, in RGB format. */

screen_idle_awake = false;
/* If set to true, Term48 will force the
 * screen to stay awake when idle instead
 * of dimming and eventually turning off as
 * usual. */

auto_show_vkb = true;
/* When set to true, will automatically
 * display the virtual keyboard at launch
 * time unless you have a Bluetooth
 * keyboard. Set to false to disable. On
 * a Passport, this is always true so the
 * symbol keys can be accessed. */

metamode_doubletap_key = 61666;
/* Which key to double tap in order to
 * toggle metamode on and off. This is an
 * integer corresponding to the key symbol
 * and defaults to KEYCODE_RIGHT_SHIFT.  */

metamode_doubletap_delay = 500000000;
/* When double tapping to invoke metamode,
 * the time in which to double tap, in
 * nanoseconds. Defaults to 0.5 seconds. */

keyhold_actions = true;
/* Enables special actions when holding down
 * a key. By default, Term48 will upcase
 * letters if you hold them, and will toggle
 * metamode on if you hold space. */

keyhold_actions_exempt = [KEYCODE_BACKSPACE,
                          KEYCODE_RETURN];
/* These keys do not trigger special
 * handling when held down, so they will
 * repeat as usual. */

metamode_hold_key = 32;
/* If keyhold_actions is true, then
 * holding this key will toggle metamode
 * on. Defaults to KEYCODE_SPACE. */

tty_encoding = "UTF-8";
/* Term48 uses 16 bit Unicode internally,
 * but when doing IO with the tty / shell,
 * will convert between Unicode and the
 * tty_encoding. Defaults to UTF-8,
 * but can be any encoding that the
 * International Components for Unicode
 * (ICU) understands. */

metamode_hitbox : { x = 0; y = 0; 
                    w = 100; h = 100; };
/* This is the area of the screen that you
 * touch to toggle metamode on and off,
 * specified from the top left corner of
 * the screen. Defaults to a 100x100 pixel
 * box in the top left corner, but you can
 * move it somewhere else if you like by
 * specifying the top left corner of the box
 * (x from the left, y from the top) and the
 * witdh (w) and height (h) in pixels. */

metamode_keys : (
    ("e", "\x1B"),
    ("t", "\t")
  );
/* When in metamode, pressing the given key
 * will send the specified string into the
 * shell and then turn off metamode. Strings
 * are read according to the rules for
 * string parsing in libconfig. You can
 * specify hex characters using \x and
 * exactly two characters. Term48 uses this
 * mechanism to send control sequences into
 * the shell, but you could specify any
 * character string you want, including
 * UTF-8 sequences. 
 *
 * Term48 supports terminfo aliases for some
 * common escape sequences. Specifically, if
 * a metamode key is set to one of kcuu1,
 * kcud1, kcuf1, kcub1, khome, kend, or kf1
 * through kf12, then the correct escape
 * sequence will be sent for cursor up, down,
 * right, left, home, end or the
 * corresponding function key. */

metamode_sticky_keys : ( 
    ("k", "kcuu1"),
    ("j", "kcud1"),
    ("l", "kcuf1"),
    ("h", "kcub1")
  );
/* Like metamode_keys above, but leaves
 * metamode on afterwards, so you can press
 * another metamode key immediately. */

metamode_func_keys : ( 
    ("a", "alt_down"),
    ("c", "ctrl_down"),
    ("s", "rescreen"),
    ("v", "paste_clipboard")
  );
/* These keys map to special functions in 
   Term48:

  alt_down: Will 'hold down' the alt key and
  send it as a modifier with the next
  keypress.  

  ctrl_down: Will 'hold down' the ctrl key.  

  rescreen: Will reinitialize the screen
  surface and fonts, including font size. You
  may want this is you have
  allow_resize_columns = true.

  paste_clipboard: Will paste the contents of
  the system keyboard. Handy for pasting URLs
  into the shell. Note that no character
  encoding or conversion will be done. 
*/

rescreen_on_symmenu = true;
/* If rescreen_on_symmenu is true, then opening a symbol
  menu will cause the screen to readjust to new dimensions
*/

main_symmenu : ( (
    ("a", "="),
    ("s", "-"),
    ("d", "*"),
    ("f", "/"),
    ("g", "\\"),
    ("h", "|"),
    ("j", "&"),
    ("k", "'"),
    ("l", "\"")
  ), 
  (
    ("q", "~"),
    ("w", "`"),
    ("e", "{"),
    ("r", "}"),
    ("t", "["),
    ("y", "]"),
    ("u", "<"),
    ("i", ">"),
    ("o", "^"),
    ("p", "%")
  ) );
/* For devices with a Sym key, this
 * preference controls the contents of the
 * symbol menu.
 *
 * The sym_keys preference is a list of
 * key -> symbol groups, one group per
 * row in the symbol menu. Keys indicate
 * keyboard shortcuts, and symbols can
 * be any character string, including
 * UTF-8 strings. Hex characters can be
 * represented with a \x and exactly two
 * hexadecimal digits.
 *
 * The symbol menu is drawn from the
 * bottom of the screen to the top, so the
 * first group in sym_keys is drawn at the
 * bottom, the second is drawn above it,
 * and so on. The size of the symbol menu
 * is scaled with the number of items in
 * the largest group in order to fit in
 * the screen width. Users who prefer to
 * use the keyboard shortcuts instead of
 * the touchscreen may want to collapse
 * the symbol menu into one large group,
 * which will result in a small symbol menu
 * along the bottom of the screen. There
 * is no limit on the number of items in
 * the symbol menu, but all keys must be
 * unique and only one key can be bound to
 * a keyboard shortcut. */

sticky_sym_key = false;
/* For devices with a Sym key, controls
 * whether the Sym menu stays open after
 * hitting a key. */

sticky_shift_key = false;
/* For devices with physical shift keys,
 * this setting controls whether the shift
 * key 'sticks' after being pressed, and
 * applies to the next keypress. */

allow_resize_columns = false;
/* This setting controls whether a program
 * can change the number of columns on the
 * screen. Defaults to false (no resizing).
 * When set to true, programs can set the
 * number of columns (80 or 132), but this
 * may make the text really small. Use the
 * metamode 'rescreen' function to reset the
 * font size to your preference. */

prefs_version = <int>
/* This is the current version of the
 * preferences file, according to Term48. If
 * it is different than the app version,
 * then Term48 will update the preferences
 * file to the new version. You don't need
 * to worry about this. */

============================================

3. WHAT'S INSTALLED

The default userland that comes with your
device is pretty sparse, and some of the
versions are somewhat old. You have the basic
file utilities (ls, less, mv, cp, etc.), but
no compiler and no man pages. Some commands
have 'use' information available (eg. 'use
/bin/ls') which can help out with the
flags for the QNX userland tools. You do have
python so you can get some work done with
that. You can edit files with elvis, which is
like vi. 

The default version of ksh is quite old, so
Term48 bundles mksh, which is better in
general and much better about unicode in
particular. Term48 also bundles ssh, scp,
sftp and ssh-keygen, due to popular demand.


It is possible to install other programs and
round out the userland, as described below in
FOR DEVELOPERS.

============================================

4. FOR DEVELOPERS

Term48 is Open Source

Term48 is a 'from scratch' terminal emulator
in that it is not a port of another program.
It uses SDL to draw to the screen, freetype
to render fonts, libconfig to manage
preferences, ICU to convert between character
encodings, and implements (parts of) the
xterm specification. It is not by any means
perfect, and will certainly have bugs or
missing features.  Because the author enjoyed
access to so many high quality libraries that
made the development of Term48 significantly
easier, Term48 is open source:

https://github.com/mordak/Term48

If you find a bug, missing feature, or
something else, feel free to bring it up on
github. Pull requests are welcome. 

Adding Programs to the Userland

Because you have python and sh, and
BlackBerry provides a cross compiler with
their dev tools, it is possible to cross
compile programs and install them into your
userland.  Because the dev tools use gcc, it
is possible to cross compile gcc and install
that into your userland, and then you can
compile other programs locally. This is not
trivial, but is also not too hard. The author
has a very rudimentary bootstraap system that
will cross compile gcc and some other useful
tools and then install them over the air onto
your device - no root required.  You can give
it a try if you like:

https://github.com/mordak/playbook-dev-tools

This has been tested with a Linux (ubuntu)
build machine and a Passport target. Again,
feel free to use github to contribute or
raise issues. In the long term the goal is
to port some kind of existing package
management system and bundle it with
Term48, but we're not there yet.

Happy hacking!

