
              VIP  -   vi(m) on PocketBooks

This program allows to use the vim editor on PocketBook devices
with touch screens, using a on-screen keyboard and a few guestures.

Actully, it's two programs: one the one hand there's a slightly
modified version of the 9at the moment) most recent version 7.4
of vim - while comes with the PocketBook as a pre-installed version
of vi it is too badly crippled to be of any use here. On the other
hand there's the vip application which is basically a "graphical
interface" (more or less a "terminal emulator) that starts and then
communicates with the vim editor (running in the background). So
vip receives your input, passes it on to vi and then shows what
vi makes of the input.

There's one important restriction: for principle reasons the pro-
gram can only work on devices were pseduoterminals can be used -
some older PocketBook models (or firmware versions) didn't allow
this!

Before you start please be aware that vim (an improved version
of the "classical" vi editor) isn't a modern WYSIWYG ("what you
see is what you get") editor - there are no menus, help windows
or whatever else you might be used to. It's basically a keyboard-
driven editor and requires quite a bit of getting used to. If you
never have used vi(m) before I would recommend that you try to
become aquainted with it with some version available for a
"normal" computer to avoid disappointment!

The installation requires several steps, first for the vip
program:

1) Copy the 'vip.app' program to the "applications" directory on
   the mounted PocketBook device
2) Modify the file 'vip.cfg' according to your preferences and
   then copy it to the "system/config" directory
3) Modify the file 'vip.kbd' as suitable, create a subdirectory
   named "system/share/vip" and copy the file into  this direc-
   tory

Everything related to vim is in the 'vim' subdirectory of the
package. To install vim do:

1) From the "vim/src" directory copy the file 'vim' to the
   "system/bin" directory of the PocketBook.
2) Create a direcory "system/share/vim" and copy the directory
   "vim/runtime" to it (you may remove everything you don't
   need from it, it contains a lot of scripts for vim as well
   as documentation).
3) Copy the "vim/etc" directory to "system/share/vim" - it
   contains the 'vimrc' initialization file read whenever vim
   is started.
4) You may also create files named "system/share/vim/.vimrc"
   and "system/share/vim/.exrc", containing settings for vim,
   that also get read in at each start-up.

Once you start the program the upper portion of the screen is used
for the editor while in the lower part an on-screen keyboard is
shown all of the time.

If you're used to vi(m) you should have no major problems. For ease
of use some touch screen support has been added. There are two modes
for handling touch screen events:

  In the default mode short taps into the left, upper, lower or
  right part of the editor area sends the key-codes for the arrow
  keys to vim, i.e. these taps have the same effect as using the
  arrow cursor keys on a "normal" keyboard. Swiping up and down
  scrolls up and down, where swipes of less than half the editor
  area height scroll by half a page, while longer swipes scroll a
  full page (unfortunately, half-page scroll doesn't work in insert
  mode!). Pinch gestures decrease (when the fingers are moved to-
  gether) or increase the font size used in the editor part of the
  window. A long tap opens up an on-screen menu.

  In the alternative mode taps and swipes are interpreted as
  clicks and drags of the mouse with the left mouse button (and 
  no other functionality is available). This alternative mode can
  only be selected when mouse support has been enabled within vim,
  e.g. by entering the ":set mouse=a" command!

the first submenu in the on-screen menu allows you to switch be-
tween the two touch screen modes (if mouse handling is enabled in
vim). With the second submenu you can switch between keyboard
layouts (english, german, russian and greek are available per de-
fault, but that's just for demonstration purposes, you can easily
write your own keyboard layout file). Further menu entries are for
rotation and exiting the program. Please note that exiting the pro-
gram via the menu is a rather brutal way to get out since it simply
kills the editor without giving it a chance to ask you if modified
buffers still unsafed should be written out - the result might be
that a swap file is left. So better use the vim command ":qa" or
":qa!" to exit the program!

The on-screen menu can also brought up using the menu button.
Cycling through the keyboard can be done via short presses of the
forward button. The backward button toggles between the two modes
for touch screen taps and swipes. To Increasing or decreasing the
font size used in the editor use a long press of the forward or
backward button.

To compile both programs yourself you need to make a number of
adjustements. First of all, I keep the vip directory in the
'source' subdirectory of the newest SDK for Linux. This is re-
flected in the path settings in the CMakeList.txt file used
for compiling and linking vip.app. If you try to compile it
from a different place you need to adjust the 'TOOLCHAIN_PATH'
variable.

Compiling vim for the Pocketbook in some other location requires
that you adjust the path to gcc in 'vim/src/auto/config.mk'.
Unless you are looking for a bit of fun don't run 'make config'
- if you do so the path to gcc in 'vim/src/auto/config.mk'
must be set to the "normal" compiler" first to be able to do
clean all the generated files. After having run "make config"
you must again modify 'vim/src/auto/config.mk', both setting
up gcc for ARM and alsh change the 'LIBS' variable to not
require a shared library for terminal settings. Moreover
you have to make a number of adjustments to the file
'vim/src/auto/config.h'. If you compile vim yourself it pro-
bably would be a good idea to make some backups of these two
files for comparison.

21.10.2013   Jens Thoms Toerring
             Email:     jt@toerring.de>
             Homepage:  http://toerring.de
