                                      Kisa
                      Pete Black <theblackpeter@gmail.com>

ABOUT
-----
Kisa provides spell checking as you type under X11 desktops (such as KDE) and
displays the result in a small window on your. You can type anywhere, in any
window and Kisa will spell check the word for you. Kisa uses GNU Aspell as a
back-end, so it's relatively easy to manage and install more dictionaries as
needed.

By connecting to the current X server running your desktop, Kisa subscribes for
event notifications from windows that it thinks interesting. Kisa uses standard
X11 event subscriptions to handle these event notifications. For example,
whenever there is a keypress event in a window, Kisa will be notified if
subscribing for keypress events from that window. There is no logging or screen
capturing performed and Kisa adheres to standard X11 security principles.
However, remember that anything you type will potentially be displayed. So when
typing a password it may be shown in clear text.

What Kisa is not:
  * a thesaurus (at least not yet)
  * a word completer, type first 3 characters and get the full word
  * a keylogger
  * a way to save the world, unfortunately

LICENCE
-------
GNU General Public License (GPL) version 2, see COPYING file.

RUNTIME REQUIREMENTS
--------------------
  * X11 (tested under X.org 7.2)
  * GNU Aspell spell-checker runtime library (debian package: libaspell15)
  * Qt 4 core GUI runtime library 4.3.2 or later (debian package: libqt4-gui)
  * Qt 4 DBus runtime library 4.3.2 or later (debian package: libqt4-dbus)

COMPILE REQUIREMENTS
--------------------
  * X11 client-side library development headers (debian package: libx11-dev)
  * GNU Aspell development libraries (debian package: libaspell-dev)
  * Qt 4 development files 4.3.2 or later (debian package: libqt4-dev)
  * GNU C++ compiler (debian package: g++)

PACKAGE INSTALLATION
--------------------
Gentoo
Unpack kisa-0.63.ebuild.tar.bz2 under your portage overlay directory
(usually /usr/local/portage). Form there run:
  ebuild kisa-0.63.ebuild digest
  emerge kisa

Translations will be installed if available for languages specified by the
LINGUAS variable in /etc/make.conf.

All other Distributions
Check your package manager documentation for details on how to install custom
packages.

INSTALLING FROM SOURCE
------------------------
Unpack kisa-0.63.tar.bz2 and from that folder do (make sure you use the Qt 4
version of qmake):
  qmake (1)(2)(3)
  make
  sudo make install (4)

(1) To install available translations files pass the desired language to qmake
in the LINGUAS variable:
  qmake LINGUAS="sv"

(2) For debug support do: (enable full debug output by setting FULL_DEBUG flag)
  qmake "DEFINES += FULL_DEBUG"
  make debug

(3) You can pass a path to the INSTALL_ROOT paramter, which will work like
./configure --prefix=PREFIX. The default INSTALL_ROOT is set to "/usr/local". To
change this simply do:
  qmake "INSTALL_ROOT = /usr"

Note: Remember to use an absolute path. Also, using -recursive when invoking
qmake will break INSTALL_ROOT support.

(4) Note: sudo might not be available to on your system. This step is only
necessary for installation or uninstallation, but requires root privileges. You
can run the application by executing the binary kisa in the resulting bin
folder.

UNINSTALLING FROM SOURCE
--------------------------
From the source folder do:
  sudo make uninstall

Kisa will install files to the following locations:
${INSTALL_ROOT}/bin
${INSTALL_ROOT}/share/applications
${INSTALL_ROOT}/share/doc/kisa-${VERSION}
${INSTALL_ROOT}/share/kisa
${INSTALL_ROOT}/share/kisa/icons
${INSTALL_ROOT}/share/pixmaps

where ${INSTALL_ROOT} is set to "/usr/local" by default.

HELP
----
Help yourself at http://code.google.com/p/kisa/wiki/Manual or help me by
giving constructive criticism ;).

ISSUES
------
Kisa won't start if it can't find an appropriate dictionary to use. Kisa will
first look for a dictionary based on the current keyboard layout. If none is
found then the system locale will be used. However, this can still lead to
situations where Kisa can't figure out which dictionary to use based on that
information.

What it basically comes down to is that most keyboard layout in the XKb system
are based on their country code. Currently there is no way to transition from
country to a language in Qt. Kisa provides this capability natively, but it's
far from perfect.

To overcome these issues there is a file containing mappings from keyboard
layout country code to language code. Look in the file called
mappings_override.txt, under ${INSTALL_ROOT}/share/kisa, and make changes
according to the information there. 

CODING STANDARD
---------------
Use most of KDE's[1], Qt's[2] and probably all of this[3] C++ coding style.

Exceptions:
  * Member variables are prefixed with m_
  * There is no need for an explicit get in get-methods
  * Indentation is set to 2 spaces
  * Pointers and references have their symbol next to the type
  * Everything except debug output and string literals is wrapped at 80 columns

DISCLAIMER
----------
THIS INFORMATION AND/OR SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS INFORMATION AND/OR
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

REFERENCES
----------
[1]http://techbase.kde.org/Policies/Kdelibs_Coding_Style
[2]http://doc.trolltech.com/qq/qq13-apis.html#sixcharacteristicsofgoodapis
[3]http://geosoft.no/development/cppstyle.html
