WnnIM for OS/2 - PREVIEW BUILD 3
================================

***************************************************************************

This is a preview build of WnnIM for OS/2.  Release notes specific to this
build follow.

This build supports Japanese hiragana and katakana input via romaji (wapuro 
style) phonetic conversion, as well as fullwidth ASCII.  It also supports 
kanji input via clause conversion using the FreeWnn server.

Requirements:
  - The kLIBC 0.6.6 and GCC1 runtimes (available from NetLabs YUM repository)
  - The LIBCX0 runtime (available from NetLabs YUM repository)
  - The FreeWnn Japanese server and runtime packages (see below under 'For 
     Users' for information on where to get these). 
  - Extended Japanese codepage support (or at least codepage 954) must be
     installed.  This is included in the 'Japanese fonts' option in OS/2 MCP,
     ArcaOS and/or eCS installation.  You can also install them after the
     fact by locating the file `\OS2IMAGE\FI\FONT\JPCODEPG.ZIP` on your 
     installation CD/DVD, and unzipping it into the `\LANGUAGE\CODEPAGE`
     directory on your OS/2 boot drive.

I have provided somewhat customized versions of the romaji conversion tables
used by FreeWnn.  These are in the `rk` directory.  If you choose to use them
(which I recommend), then define the environment variable ROMKAN_TABLE to
point to either the `modew` or `modec` file -- see below for details.  Besides
the differences between the two, described below, both of these configurations 
feature the following differences from the standard configuration files shipped
with FreeWnn:
  - Backslash (or yen) is entered as-is, and is no longer treated as an
     alternate for 'x'.
  - The key combination 'z/' enters a fullwidth backslash; this may be useful
     when using certain non-Japanese keyboards. (Note that FreeWnn already
     allows you to enter a fullwidth tilde using 'z-'.)
  - Typing 'q' no longer disables all conversion.
  - Several unused and unnecessary definitions have been removed.

This build is still rough around the edges, and has a number of annoying
'features' and other limitations, including:

  - Odd things will happen if you switch to another PM window while
     the kanji (clause) conversion overlay is active.  Don't do this.

  - The current input mode is global, i.e. if you open or switch to a new
     window, the current input mode stays as it was in the previous window.
     (This seemed to me like a logical design, but is different from how
     basically every other IME behaves; in retrospect, it can be somewhat 
     annoying.)

  - The conversion function is not yet able to remember previously-accepted
     kanji, and therefore will not 'learn' commonly-used selections the way
     most modern IMEs do.  (This feature is planned for a future release.)

For other, general limitations, see the appropriately-named section below.


Manual Installation
-------------------

Follow the steps described below under 'For Users'.  Note that if you 
installed my original release of the FreeWnn rpm (with the filename
`FreeWnn-1.1.1-0.a023.0.i386.rpm` -- note the _0_ after _a023_), it has a
bug wherein it fails to update CONFIG.SYS on some systems.  Therefore, make
sure that your CONFIG.SYS file contains the environment variable `SET JSERVER`
as described below (if you installed FreeWnn from the rpm, it is _not_ 
normally necessary to add `SET WNNLIB`).  

If you install the updated `FreeWnn-1.1.1-0.a023.1.i386.rpm`, it does not
have this bug.  

Reboot after installing FreeWnn and/or after updating CONFIG.SYS.

***************************************************************************

WnnIM for OS/2
==============

WnnIM for OS/2 (a.k.a. 'WnnIM/2' or just 'WnnIM') is an Input Method Editor for
typing East Asian (CJK) text under Presentation Manager.

Specifically, WnnIM itself is the front-end processor component, and is designed
to work in conjunction with the open source FreeWnn IME engine on the back-end.
As such, it requires the FreeWnn server for the desired language to be installed 
and running (not necessarily on the same computer, but accessible via TCP/IP).

Only Presentation Manager (OS/2 graphical) sessions are supported; DOS and
Win-OS/2 sessions are not.  OS/2 command lines are not supported either,
_except_ for windowed VIO sessions running on DBCS versions of OS/2.

The current version supports Japanese input.  Support for other Asian languages
is planned for future releases.


For Users
---------

### Installing FreeWnn (prerequisite)

The FreeWnn server and runtime files are required.  These are provided in the
FreeWnn RPM packages, which should soon be available from a repository near you;
in the meantime, you can get `FreeWnn-1.1.1-0.a023.1.i386.rpm` from
[here](https://drive.google.com/file/d/1JmNSX-I38-6eaGrbLewF9kiKDB_UixyL/view?usp=sharing).

Reboot after installing the FreeWnn RPM.

#### Running FreeWnn remotely (optional)

If you prefer not to install the FreeWnn server locally, you can set it up
to use an installation of FreeWnn anywhere on your network (for example, on
a separate Linux box).  In this case, you will still need to install the 
runtime files locally, which you can do by following these steps:

1. Extract `wnn0.dll` from the RPM and place it in a directory on your LIBPATH.
2. Extract the contents of `usr\lib\wnn` (including all subdirectories); 
   place them somewhere convenient (e.g. `E:\usr\local\lib\wnn`).  (Note: The
   maximum allowed length of this path is 200 characters.)
3. Set the environment variable `WNNLIB` to the fully-qualified path of
   the directory in step (2) (e.g. `SET WNNLIB=E:\usr\local\lib\wnn`).
   This allows WnnIM to locate the Wnn configuration files.
4. Set the environment variable `JSERVER` to the hostname and instance
   number of the FreeWnn server on your network, in the form `hostname:#`
   (e.g. `SET JSERVER=localhost:1`).  (The instance number is usually 1,
   at least for the Japanese FreeWnn server; it corresponds to the `-N` 
   parameter specified on the server command line.)
5. Shut down and reboot.

The above steps are not needed if you installed the FreeWnn RPM.

### Installing WnnIM

Make sure FreeWnn is available (using either method described above).  

You can install WnnIM from RPM using the rpm command line or a program like 
ANPM.  Alternatively, you can install it manually using the following steps:

1. Place `wnnhook.dll` and `wnnim.exe` together in a directory of your choice.

   (Optionally, put the files with names ending in `.xqs` in the same directory;
   these are used for debugging but are not required for normal use.)

2. Place the `rk` directory and its contents somewhere.  

   You can put these files into `%UNIXROOT%\usr\lib\wnn\ja_JP\rk`, which is 
   created by the FreeWnn installer (or in `ja_JP\rk` under whatever path is
   defined by the environment variable %WNNLIB%, if set).  If you do this, 
   note that the file `1B_TOUPPER` is identical to the one included with
   FreeWnn, and can be omitted in this case (the other files, however, are 
   required).  If you put the files in this location, then edit your CONFIG.SYS
   file and add the line `SET ROMKAN_TABLE=modew`.  

   If you put these files in any location other than the above, then edit 
   CONFIG.SYS and add the line `SET ROMKAN_TABLE=<rk_path>\modew`, where
   `<rk_path>` is the fully-qualified path to the files.

   *Note:* In either case, you can specify `modec` instead of `modew` in the
   aforementioned ROMKAN_TABLE value.  Doing so will change the romaji input
   configuration slightly -- see below for the differences.  

   Reboot after updating CONFIG.SYS.

3. Create a program object for `wnnim.exe` if you desire.

#### `modew` vs `modec`

Two different configuration files for romaji-to-kana input conversion are
provided.  You can choose which one to use, according to your preference:

 * `modew` is designed to work similarly to the Japanese IME on Windows.
   Of note is that in order to enter a 'ん' or 'ン' kana, you must type 'NN'.
   (Thus, to enter the word 'みんな', you type 'MINNNA'.)

 * `modec` is a custom configuration file with a few key differences from
   `modew`.  First, you enter 'ん' or 'ン' by typing 'N' _once_, followed by
   either an apostrophe ('), a punctuation character, or any letter other than
   a vowel -- or, in clause conversion mode, activating clause conversion or
   accepting the current clause.  (Thus, to enter the word 'みんな', you type
   'MINNA'.)  This behaviour is more like that of older non-Windows IMEs.

   Second, with this configuration file, typing 'TU' or 'DU' while in katakana
   input mode will produce トゥ or ドゥ, respectively (type 'TSU'/'TZU' to 
   produce 'ツ'/'ヅ'); and typing 'TI/DI' will similarly produce 'ティ'/'ディ' 
   (type 'CHI'/'DZI' for 'チ'/'ヂ').  These special sequences apply _only_ when
   typing in katakana (not hiragana).

### Using WnnIM

Run `wnnim.exe` to start the IME.  The WnnIM user interface consists of a small
window located (by default) at the bottom right of your screen (you can move it
around by dragging).  This UI consists of two small buttons and a status panel.

 * The button labelled 'I' (or '入') toggles input conversion on or off.  You 
   can also toggle this setting using Ctrl+Space.
 * The button labelled 'C' (or '変') toggles CJK clause conversion on or off.  
   You can also toggle this setting using Ctrl+Shift.

There is also a popup context menu which allows you to do various things, such
as select the input conversion mode (currently hiragana, katakana and fullwidth
ASCII are supported), adjust settings, or close the program.

You can also change the input conversion mode using Shift+Space, which will
cycle through the available modes.

When in clause conversion mode, the following hotkey commands apply:

    Space:            Convert the current clause text
    Enter or Return:  Accept the current text as shown
    Esc:              Cancel conversion (this will clear the current clause text)
    Backspace or Del: Delete the last character

The currently-active mode is system wide, i.e. switching from one program to 
another will retain the current conversion mode.  (This may change in the 
future.)

Most of the aforementioned hotkey commands (except for Esc and Backspace) can be 
changed via the settings dialog.

Romaji input works much the same way as it does in other IMEs (subject to the
differences between the `modew` and `modec` configuration files noted above).
However, some possibly non-obvious input sequences include:

	TYA	ちゃ		DYA	ぢゃ
	TYI	てぃ		DYI	でぃ
	TYU	ちゅ		DYU	ぢゅ
	TYE	ちぇ		DYE	ぢぇ
	TYO	ちょ		DYO	ぢょ
	XTI	てぃ		XDI	でぃ
	XDU	どぅ		XDE	でぇ
	XDO	どぉ		XWI	うぃ
	XWE	うぇ		XWO	うぉ
	Z.	…		Z-	〜
	Z/	＼

(The above apply to both hiragana and katakana input.)

### Environment variables

The following environment variables affect the operation of WnnIM/2:

 * `JSERVER`: Indicates the host and instance number where the FreeWnn server
   is running.  For most local installations this will be `localhost:1`.

 * `WNNLIB`: Indicates the path to the FreeWnn configuration files.  (This path
    may be no more than 200 characters long.)  If not defined, WnnIM/2 will look
    for them under the directory `%UNIXROOT%\usr\lib\wnn`.  

 * `ROMKAN_TABLE`: Indicates a custom romaji input conversion table to be used.
    If this value includes a path specifier, it is taken as the fully-qualified
    name of the conversion table file.  If it contains a filename only, that 
    file is assumed to be located under the usual FreeWnn configuration file 
    directory (determined as described above), in the subdirectory `<lang>\rk`
    (in this case the name of the file without the path cannot be longer than
    49 characters).  If this environment variable is not defined, the default 
    FreeWnn romaji conversion table (`mode` in the aforementioned directory) 
    will be used.


Limitations
-----------

1. In general, an application must be running under the corresponding DBCS
   codepage in order for WnnIM text entry to work.  This is especially true
   for applications that try to interpret text intelligently based on the
   codepage (e.g. by converting into Unicode).  For reference, the relevant
   codepages are:

    - Japanese: 932
    - Korean: 949
    - Simplified Chinese: 1386
    - Traditional Chinese: 950

   Note that running under these codepages without also using the corresponding
   language OS version and keyboard driver may prevent you from typing certain 
   characters (mainly tilde and backslash).

2. For the characters to display properly in the application, it will need to
   use fonts that support the language in question.  In other words, Japanese
   text requires the target program to be using a Japanese font (in addition
   to the Japanese codepage, as noted above).  If you would rather not change
   a program's font to Japanese, then it may be possible to make use of
   Presentation Manager's "font association" feature (`PM_SystemFonts` ->
   `PM_AssociateFont` in OS2.INI), at least for programs which use standard PM
   controls or GPI text rendering.  However, this does have certain limitations.

3. Not all applications support positioning of the clause overlay window at the
   cursor.  (Qt-based applications are an example, as is OpenOffice.)  In such
   cases, the window will appear, enlarged, at the bottom left of the screen
   instead.  

4. Some applications do not support input of double-byte text in the normal way. 
   In some cases this can be worked around, but WnnIM has to explicitly add
   logic for these applications.  If you encounter such an application, please
   open a ticket for it so that it can be addressed.

5. Apache OpenOffice is a somewhat special case.  Current OS/2 builds do not
   support double-byte character input at all.  A workaround has been
   implemented to use the clipboard (instead of input messages) to insert the
   text in OpenOffice windows.  However, the nature of this workaround means
   that _anything in the clipboard will be lost_ whenever text is entered into
   OpenOffice using WnnIM.


Notices
-------

WnnIM for OS/2  
(C) 2019 Alexander Taylor

Some of the PM hook logic was derived from `xray` by Michael Shillingford, and
his [EDM/2 programming article](http://www.edm2.com/0501/hooks.html) on the
subject.

  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 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  02111-1307  USA

WnnIM program source: [https://github.com/altsan/os2-wnnim]()
