- Quick Manual
- Keymap Syntax
Quick Manual
(Bản tiếng Việt (version 0.9.2) xem tại đây.)
Unikey Input Method for X-Window
Copyright (C) 2004-2005 Pham Kim Long
Contact:
unikey@gmail.com
UniKey project: http://unikey.org
======================================================================
About this manual
This is a very brief manual. Only English version is available
at the moment. Your contribution to documentation and/or translation
are always welcome.
----------------------------------------------------------------------
About x-unikey package
This package contains the following components:
- ukxim: Unikey XIM (X Input Method) server
- unikey: GUI for ukxim and unikey-gtk
- unikey-gtk: GTK vietnamese input method module
In most cases you only need unikey and ukxim to type Vietnamese in
applications. unikey-gtk can be used only with in GTK
applications. (GTK applications can use either unikey-gtk or ukxim).
----------------------------------------------------------------------
----------------
1. Requirements
----------------
- The system must have either en_US.UTF-8 or vi_VN.UTF-8 locale
installed
- XMODIFIERS environment variable must be set to use unikey as X input
method, i.e. XMODIFIERS="@im=unikey".
- If you want to use unicode charset, LANG variable must be set as
follows (preferably in ~/.bash_profile or ~/.bashrc)
export LANG=en_US.UTF-8
or
export LANG=vi_VN.UTF-8
------------
2. Features
------------
Unikey provides:
- TELEX, VNI, VIQR, and one user-defined input methods.
- UNICODE (UTF-8), TCVN, VNI, VIQR charsets.
- Support for macro (auto text)
----------------------
3. Start using Unikey
----------------------
After installing Unikey, please log out and login again. Then
run "unikey", you should be able to use Unikey right away
without having to do anything else. If that's not the case,
try following steps:
- Put these lines into ~/.bash_profile or ~/.bashrc:
export XMODIFIERS="@im=unikey"
export GTK_IM_MODULE="xim"
- Re-login
- Run unikey
$ unikey
- Run applications and start using unikey!
See 4.2 on how to close unikey
------------
4. Usage
------------
4.1 Change settings
-------------------------
4.1.1 Keyboard shortcuts
The following shortcuts are provided to change Unikey's settings:
ALT-SHIFT: switch on/off
CTRL-SHIFT-F1: Change to UNICODE charset
CTRL-SHIFT-F2: VIQR charset
CTRL-SHIFT-F3: TCVN charset
CTRL-SHIFT-F4: VNI charset
CTRL-SHIFT-F5: Change to TELEX input method
CTRL-SHIFT-F6: VNI input method
CTRL-SHIFT-F7: VIQR input method
CTRL-SHIFT-F8: User-defined input method
4.1.2 Using Unikey window
The settings can also be changed by clicking the Unikey icon:
- Left-click: Switch on/off
- Right-click: rotate through charsets
- Control + Right-click: rotate through input methods
- Control-Alt + Left-click: Quit Unikey (See 4.6 Cautions!!!)
4.1.3 Reloading settings
-------------------------
Settings in a configuration file can be reloaded by one of 2 ways:
[CTRL-SHIFT] + Left Click unikey icon
or programatically:
$ kill -s USR1 `pidof ukxim`
4.2 Closing unikey
-------------------------
Control-Alt + Left-click
If you press [Control-Alt + Left-click], unikey window will disappear
and the unikey XIM server is disabled, but unikey and ukxim processes
still remain in the memory. Everything will work exactly as if unikey
has never been loaded. To start using unikey again, just run unikey
again.
If you really want to get rid of unikey from memory (although it is
not reccomended, and should be used only in few rare occasions), run:
$ killall unikey
CAUTIONS: When you kill unikey process this way, some applications
that have established a connection with Unikey may crash. Therefore
it is not recommended to do so. If all what you want is to make unikey
reload your settings, see 4.1.3.
4.3 Command line options:
-------------------------
4.3.1 unikey:
Command line:
unikey [OPTIONS]
Options:
-h, -help Print help and exit
-v, -version Show version and exit
-display <name> Display name to connect to
-xim <ukxim> Path to Unikey XIM server (ukxim)
-config <file> Specify configuration file (default: ~/.unikeyrc)
-macro <file> Load macro file
-l, -locales <list> Locales accepted by unikey (default:"C,en_US,vi_VN,fr_FR")
Examples:
$ unikey
Unikey will search for ukxim in the default search path
$ unikey -xim /usr/local/bin/ukxim -macro ~/ukmacro
Explicitly specifies ukxim, and loads ukmacro
$ unikey -locales "en_US,fr_BE"
Runs unikey with support for en_US and fr_BE locales
** Notes on option -locales:
By default unikey supports C, en_US, vi_VN, fr_FR locales. If your
application run in a different locale, use this option with your
desired locale. E.g. unikey -locales "en_US,fr_BE"
4.3.2 ukxim:
(See 6.2 on how you can run ukxim independently)
Command line:
ukxim [OPTIONS]
Options:
-h, -help Print help and exit
-v, -version Show version and exit
-display <name> Display name to connect to
-xvnkb-sync Enable synchronization with xvnkb GUI
-config <file> Specify configuration file (default: ~/.unikeyrc)
-macro <file> Load macro file
-l, -locales <list> Locales accepted by unikey (default:"C,en_US,vi_VN,fr_FR")
Examples:
$ ukxim &
Runs ukxim with default options
$ unikey -macro ~/ukmacro &
Runs ukxim with ukmacro file loaded from home directory
$ ukxim -locales "en_US,fr_FR"
Runs ukxim with support for en_US and fr_FR locales
4.4 Configuration file
------------------------
Initial settings for Unikey can be put into a configuration file. Upon
starting, unikey looks for '.unikey/options' in your home directory. If this
file does not exist, unikey will create it with default options.
You can explicitly specify configuration file on command line (see
4.3)
See the sample options file in this directory for syntax of
configuration file.
4.5 Macro (auto-text)
------------------------
Macro feature lets you type frequently used words quickly. E.g.: "vn"
for "Vie^.t Nam", "cntt" for "Co^ng nghe^. tho^ng tin".
Write macros in a file, then specify it in unikey command line, or in
configuration file.
The syntax for macro file is shown in the sample file ukmacro in this
directory.
Note: Macro file uses VIQR encoding.
Examples:
cntt:co^ng nghe^. tho^ng tin
dh:DDa.i ho.c
4.6 User-defined input method
--------------------------------
Besides the built-in input methods TELEX, VNI, VIQR, Unikey lets you
define your own input method. Once you have defined and loaded it, it
can be selected from unikey window, just as other built-in
methods. When selected, the user-defined method is dislayed as "UR" in
unikey window.
To enable user-defined input method, set 'UsrKeyMapFile' (in unikey
options file) to the file specifying the method.
Syntax of the user-defined input method file is described in
keymap-syntax file, provided in the same folder as this manual. You
can build your method from sample methods in this folder.
4.7 Cautions!!!
----------------
4.7.1
Once Unikey has been started, you should not kill unikey process. Some
applications that have established a connection with unikey may crash
if unikey is not present any more. Xterm, Mozilla Firefox are known to
have this problem with unikey, and XIM servers in general. Note that,
just closing unikey window (as mentioned in 4.2) is safe, since unikey
process still remains in the memory.
4.7.2
When using unikey, other Vietnamese input programs (such as xnvkb)
should be disabled/deactivated. (Just disable, not necessarily to
uninstall it).
---------------------
5. GTK applications
---------------------
GTK applications can either use unikey XIM (ukxim) or unikey-gtk for
Vietnamese input. To use XIM by default, set this variable in
~/.bash_profile:
export GTK_IM_MODULE=xim
To use unikey GTK module by default:
export GTK_IM_MODULE=unikey
To change between these two modes: right-click the input box and
select the desired input method ("Unikey" or "X Input Method" menu
item).
Notes: These two modes work almost the same in GTK applications
. In the future unikey-gtk may have more special features.
-----------------
6. Miscellaneous
-----------------
6.1 Using xterm with unikey
------------------------------
If in the configuration file you set "CommitMethod=Forward" and unikey
works fine with xterm, then you don't have to read this section.
If xterm does not work with "CommitMethod=Forward" then set
"CommitMethod=Send" in the config file. You also have to change change
xterm settings by putting this line in ~/.Xresources:
xterm*allowSendEvents: 1
Then run:
$ xrdb -load ~/.Xresources
Reason: By default xterm does not accept synthetic messages sent by
other applications.
6.2 Synchronizing ukxim with xvnkb GUI
----------------------------------
ukxim has been designed to to work with xvnkb GUI. Run these commands:
$ ukxim -xvnkb-sync &
$ xvnkb
In this mode, you MUST disable xvnkb core. (unset LD_PRELOAD, or
remove the line that loads xvnkb core in /etc/ld.preload)
(Many thanks to Dao Hai Lam and Nguyen Thai Ngoc Duy for this feature)
6.3 Auto-start Unikey when GNOME starts
------------------------------------------------
In Debian, put this line to ~/.gnomerc
unikey
Note: This may not work in other distributions
6.4 Auto-start Unikey when KDE starts
------------------------------------------------
Create a symbolic link in ~/.kde/AutoStart
$ ln -s /usr/local/bin/unikey ~/.kde/AutoStart
6.5 How to unload/restart unikey
------------------------------------------------------------
As pointed out in 4.2, when you close Unikey, it still remains in
the memory. This would be sufficient in most cases. However, changing
certain options require that you unload and run unikey again for the
changes to have effect.
The proper order is as follows:
- run: 'killall unikey'
- Change the 'options' file as you wish.
- run unikey again.
Note:
- Restarting unikey this way may cause some applications to crash.
- In the current version, there are 2 options that require reloading
unikey this way: XimFlow and CommitMethod.
6.6 If some application does not work with unikey
------------------------------------------------
Try the following steps:
- run: 'killall unikey'
- Edit options file, change "XimFlow" option from Static to Dynamic or
vice versa (if it was Dynamic).
- run unikey again.
- reset your application.
If it still does not work, try further:
- run: kill `pidof unikey`
- Edit options file, change "CommitMethod" option from Send to Forward or
vice versa (if it was Forward).
See 4.7 for cautions.
======================================================================
======================================================================
Keymap Syntax
An user-defined input method is a set of lines in the following format:
<key> = <action>
- key is a single character, which is any key you can type on your keyboard.
- action is the action to take when <key> is typed. Unikey defines a set of
actions you can use to describe your input method.
Empty lines and lines beginning with ';' are ignored.
*** Example:
[a = Roof-A] means that when you type 'a', Unikey will try to put a
roof above an 'a' character to make it become a^, if possible.
[6 = Hook-UO] means that when you type '6', unikey will try to put a
hook to any 'u' or 'o' character to make it become 'u+', or 'o+'
respectively.
***
Following is the list of actions understood by unikey:
------------------------------------------------------------------------
ACTION TABLE
------------------------------------------------------------------------
Roof-All: put a roof to any applicable character (a, o, e)
Roof-A: put a roof above 'a'
Roof-E: put a roof above 'e'
Roof-O: put a roof above 'o'
Hook-Bowl: put a hook to 'u' or 'o', or a bowl to 'a', if applicable
Hook-UO: put a hook to 'u' or 'o'
Hook-U: put a hook to 'u'
Hook-O: put a hook to 'o'
Bowl: put a bowl to 'a'
D-mark: make 'd' become 'dd'
Tone0: clear an existing tone
Tone1: sa('c
Tone2: huye^`n
Tone3: ho?i
Tone4: nga~
Tone5: na(.ng
Telex-W: special key, has all the functions of 'w' key in telex method.
A^: generate 'A^' character
a^: generate 'a^' character
A(: generate 'A(' character
a(: generate 'a(' character
E^: generate 'E^' character
e^: generate 'e^' character
O^: generate 'O^' character
o^: generate 'o^' character
O+: generate 'O+' character
o+: generate 'o+' character
U+: generate 'U+' character
u+: generate 'u+' character
DD: generate 'DD' character
dd: generate 'dd' character
----------------------------------------------------------------------
NOTE:
Action names are case sensitive. That means 'A^' is different from
'a^'. If you type "Roof-a", it will not be understood, the correct
name is "Roof-A".
If <key> is an alpha character (a-z), both cases of the character will
get the same action. For example: [a = Roof-A] implies [A = Roof-A],
and vice versa, so you need to specify only one of them.
An input method does not need to assign keys to all available
actions. You need to assign only enough keys for you to type any vietnamese
word.
See im-samples/ folder for some sample input method files.
Example for TELEX:
z = Tone0
s = Tone1
f = Tone2
r = Tone3
x = Tone4
j = Tone5
w = Telex-W
a = Roof-A
e = Roof-E
o = Roof-O
d = D-Mark
[ = u+
] = o+
{ = U+
} = O+
