History of this Notes:

91Oct28	revised		Yongguang Zhang -- 2nd release of cxterm 11.4.2
91Oct20	revised		Yongguang Zhang -- A slightly revision
91Apr01	revised		Yongguang Zhang -- Release X11R4 cxterm revision 2
90Dec31	revised		Yongguang Zhang -- For X11R4 cxterm revision 2 beta
90Nov06	revised		Yongguang Zhang -- fix some minor bugs and release
			to public.

9008-09	written		Man-Chi Pong - X11R4 cxterm beta
	include bug fix -- related to total no. of displayable lines
			=> use of program cxresize instead of resize

--------------

%% cxterm -- Chinese xterm
   ######

This is rev 2 for X11R4 (referred to as version 11.4.2).

cxterm 11.4.n is not compilable in X11R3, or X11R5.  X11R5 user
please use cxterm 11.5.1 instead, which is rewritten in X11R5.

See README file on how to install this version.

Previous X11R4 cxterm released on 90/Nov/06 is referred to as version 11.4.1.

--------------

%% HISTORY of cxterm:

In 1988, ccxterm for X11R2 was first developed jointly by
the Institute of Software, Academia Sinica, Beijing, China, and
the 6th Institute, the Ministry of Electronic Industries, Beijing, China.

X11R3 ccxterm was later modified from X11R2 ccxterm based on X11R3 xterm.

In 1990, Man-Chi Pong (then in U. of Kent, U.K.) started from X11R4 xterm
and developed a new cxterm.  Although some changes made to X11R3 xterm
by X11R3 ccxterm were adopted by cxterm (mainly the input methods),
the whole structure of X11R3 ccxterm was abandoned.

Comparing with X11R3 ccxterm, cxterm 11.4.1 has changed the mechanism to
display the HanZi (Chinese character) input area,
though it should be transparent to the user.
Moreover, cxterm 11.4.1 also fixed many bugs in X11R3 ccxterm.

cxterm 11.4.1 was released in Nov., 1990, after some minor modification
by Yongguang Zhang (CS Dept, Purdue University, USA).

cxterm 11.4.2 is a new revision of cxterm 11.4.1 developed by
Yongguang Zhang.

cxterm 11.4.2 has changed the mechanism to handle HanZi input.
It separates the HanZi input methods from cxterm program itself.
Input methods are now stored in external files as dictionaries.
cxterm 11.4.2 loads the input methods dynamically at runtime.
Users can change existing input methods, or define their own by
modifying the old dictionaries, or adding new ones.

From 11.4.2 onward, the design of cxterm diverges totally from X11R3 ccxterm.

--------------

%% PLATFORM:

cxterm has been tested quite thoroughly in Sun3, Sun4, Sun SparcStation,
and DECstation3100.

We can show and scroll HanZi files in cxterm, and input HanZi. Cut and paste
through primary cut buffer also works for HanZi.

The editor vi/emacs (for ASCII files) filters off the high-bit
of 8-bit byte input of HanZi.

An 8-bit clean editor called celvis (Chinese version of elvis, a vi/ex clone)
has been developed and released to public at the same time.

--------------

%% OTHER PLATFORM OR WINDOW SYSTEMS:

OpenWindows using X11/NeWS server "xnews" (not MIT X11)

    The difficulty was that Open Windows and X11R4 use completely
    different font formats. To make cxterm work under Open Windows, you
    have to use the Open Windows utilities convertfont and bldfamily to
    create font files called 8x18.ff and cclib16st.ff, etc., and then set
    up an appropriate font path. Once this was done, cxterm worked fine
    except a warning message about widget version mismatches.  It doesn't
    affect the operation of cxterm.  (By simpson@math.psu.edu)


DECstation & DECwindow

    When you compiles cxterm in DECstation, cc complains "illegal lhs
    of assignment operator" error in line 854, main.c.  To fix the problem,
    change line 854 in main.c from:

                fileno(stderr) = i;
    to
                (stderr)->_file = i;

    This is only an ad hoc approach.  It requires official patch from MIT.

    Moreover, X windows running on DECstations are often the DECwindows.
    To install Chinese X fonts, you have to use the DECwindow tool "dxfc"
    to create .pcf font files, and "dxmkfontdir" to create a font directory.
    For example, to install cclib16st and 8x18:

	zcat cclib16st.bdf.Z | dxfc -t > cclib16st.pcf
	cat 8x18.bdf | dxfc -t > 8x18.pcf
	dxmkfontdir .

    You can still use xset fp+ ... to add the font directory.  But when
    you use xfd to display the GB-coding font, remember to add one option:

	xfd -fn cclib16st -start 41216

    since the first Chinese code start at the page of 0xa100 (= 41216).


AIX

    Do a "stty pass8" in cxterm window first.


--------------

%% CHINESE ENCODING:

cxterm 11.4.2 is somewhat encoding independent. Currently, it supports
both GB (GuoBiao) and BIG5 encoding.  The default encoding is GB.
options "-BIG5", or "-hz BIG5" will start cxterm in BIG5 encoding.

GB is an *example* of such encodings that in which one Chinese character
is represented by two bytes, and the highest-bits (MSB, or the 8th-bit)
are set (i.e. == 1) in both bytes.

BIG5 is an *example* of such encodings that in which one Chinese character
is represented by two bytes, the highest-bit is set in the first byte but
it may be either set (i.e. == 1) or unset (i.e. == 0) in the second byte.

cxterm 11.4.1 uses only GB encoding for Chinese character.

--------------

%% FONTS:

cxterm works fine with the following two X11-format fonts:
        cclib16st.bdf
	hku-ch16.bdf	(a new version, slightly different with HKU-Ch16.bdf)
which come with this release of cxterm (in another directory).

Now they can both match 8x18.bdf (released with cclib16st.bdf), or
8x16.bdf (standard X11 font).

N.B.:
(1)
cclib16st.snf is converted from 16x16 Song4Ti3 font bitmap.

(2)
cxterm can be started with other ASCII & Hanzi fonts by the command:
        cxterm -fn AsciiFontName -fh HanziFontName

(3)
The font used must match the encoding adopted, otherwise all Chinese
will become meaningless garbage on the screen. To use BIG5:
        cxterm -fh hku-ch16 -fn 8x18 -BIG5

where hku-ch16 is a BIG5 encoding X11 font.

Note:   cxterm -help
        will give the list of command line options.

--------------

%% CXTERM 11.4.2 INPUT METHODS:

Input methods are stored as external files and are loaded by cxterm 11.4.2
in runtime on demand. Input method files have two formats: text format
and compiled format.

Text format has file name suffix .tit (tit for Text Input Table),
and is intended to be read and modified by human.

Compiled format has file name suffix .cit (cit for Compiled Input Table),
and is read by cxterm.

Utilities tit2cit and cit2tit convert input method files between
these two formats.

Cxterm can only understand .cit format.

Given a input method name FOO, cxterm will search the following places
for file "FOO.cit" in the order:
1) if environment variable HZINPUTDIR is set, try FOO.cit under $HZINPUTDIR;
2) try FOO.cit in the current directory;
3) try FOO.cit in your home directory.

Input method also has to match the encoding used by cxterm.

For GB encoding, 3 input methods are built-in:
        ASCII   (Normal English),
        IC      (Internal coding represented in 4 hexa-decimals),
        QW      (GB Qui Wei),

For BIG5 encoding, 2 input methods are built-in:
        ASCII
        IC

Actually, ASCII and IC are good for any encoding.

Special keys to switch between different input methods are in form of
cxterm resources and can be defined by user.  Normal place to put
these definitions is the file ".Xdefaults" at your home directory.
For advanced users, X11R4 manual X(1) contains more ways to put
user- or machine-specific resources.

Those who don't know the details of X can also use predefined input
methods by appending the file "CXterm.xd" to ~/.Xdefaults;
or simply use the built-in key binding (defined in charproc.c):

        <KeyPress> F1:  switch-HZ-mode(ASCII)   \n\
        <KeyPress> F2:  switch-HZ-mode(IC)      \n\

Here is the resources given in "CXterm.xd" for input method switching:

cxterm*VT100.Translations: #override\
        <KeyPress> F1:  switch-HZ-mode(ASCII)   \n\
        <KeyPress> F2:  switch-HZ-mode(IC)      \n\
 ~Shift <KeyPress> F3:  switch-HZ-mode(TONEPY)  \n\
  Shift <KeyPress> F3:  switch-HZ-mode(PY-b5)   \n\
 ~Shift <KeyPress> F4:  switch-HZ-mode(PY)      \n\
  Shift <KeyPress> F4:  switch-HZ-mode(ETZY)    \n\
 ~Shift <KeyPress> F5:  switch-HZ-mode(QJ)      \n\
  Shift <KeyPress> F5:  switch-HZ-mode(QJ-b5)   \n\
 ~Shift <KeyPress> F6:  switch-HZ-mode(Punct)   \n\
  Shift <KeyPress> F6:  switch-HZ-mode(Punct-b5)\n\
        <KeyPress> F7:  switch-HZ-mode(QW)      \n\
  ~Meta <KeyPress> Escape:  insert() switch-HZ-mode(ASCII)

In this example, pressing <F2> will switch the current input method
to IC; <F4> will switch again to PY method (an external input method,
requires PY.cit to be in the search path(s) of .cit files);
<shift>+<F4> will switch again to ETZY method, and so on.

Note that the last line above is a good setting for those who use the
editor "celvis".  Pressing <ESC> will pass ESC to "celvis" to end
insertion mode, and cause cxterm to switch back to ASCII (so that you
can continue to enter celvis command in ASCII mode).

Each keypress definition in cxterm resources takes the following form:

    [optional_mod_keys] <KeyPress> key_name: switch-HZ-mode(input-method-name)

"\n\" should be appended to the line except the last definition.

Examples:

-- <F2> switch to input method named MYNEW:

        <KeyPress> F2: switch-HZ-mode(MYNEW)

-- <Shift-F3> switch to input method IC:

        Shift <KeyPress> F3: switch-HZ-mode(IC)

-- <Ctrl-Meta-F6> switch to input method called CANTONESE:

        Ctrl Meta <KeyPress> F6: switch-HZ-mode(CANTONESE)

--------------

%% IMPLEMENTATION NOTES:

cxterm is modified from X11R4/mit/clients/xterm/.

Extra compilation flags CFLAGS are -DHANZI -DNEW_HANZI.
#ifdef HANZI     encloses code adopted from X11R3 ccxterm.
#ifdef NEW_HANZI encloses code added in X11R4 version.

Imakefile has been revised correctly.

To install cxterm, you have to regenerate Makefile from Imakefile (by xmkmf),
or edit the Makefile to give the correct paths for the X libraries &
include files.

The (very long) file "charproc.c" has been splitten into
2 files:
        charproc.c
        charVTparse.c

The file "resize.c" has been renamed to "cxresize.c"

The X11R3 "hzmenu.h" "hztermmenu.h" for HanZi menus are not
incorporated in this X11R4 cxterm.  Although these 2 .h files
are kept (& #include) in cxterm 11.4.1 files as in X11R3,
they, as well as the X11R3 ccxterm built-in HZ input dictionaries "hzscanner.h",
are removed from cxterm 11.4.2.

The major difference between X11R3 and X11R4 version of
Chinese xterm is in the showing of the HanZi input area:

-- X11R3 ccxterm used screen->buf equivalent to the full height
        of the window & took the bottom 3 lines of the buffer
        to show the HanZi input area.

-- X11R4 cxterm uses a screen->buf which does not include the
        bottom 2 lines of the window.  The HanZi input area
        occupies the area equivalent to the bottom 2 lines
        of the window.
        HanZi and ASCII characters are directly drawn to this
        area using XDraw...().  This is faster & make the
        the program structure better.

-- The HanZi input area is not an X window; thus,
        even if the mouse pointer is in this area,
        keystroke input is still received in the cxterm window.

%% IMPLEMENTATION NOTICE for 11.4.2:

-- The HanZi input methods are separated from the cxterm program itself
        in cxterm 11.4.2; thus the implementation is simpler.
        All the HZ input related code in input.c are removed.

-- New files "hzinput.h" and "hzinput.c" are created for input method
        Handlering.  Dictionaries are organized in TRIE data structures.

-- screen->hzInputWindow.pro_col is no longer useful, and is replaced
        by (hztbl->lenPrompt + dypInbufLen).  If you are not happy
        with the spaces between prompt and inbuf, don't change above,
        append some spaces to your prompt string.

-- "tit2cit.c", "cit2tit.c": newly created to convert input methods between
        ".cit" and ".tit" format. ".cit" is a compiled TRIE structure
        intended to be read only by cxterm.  ".tit" is a dictionary in
        text format intended to be read and written by human.

--------------

%% IMPORTANT NOTES:

cxterm requires an 8-bit clean Unix kernel & 8-bit clean SHELL
(SHELL means any shell program) to run successfully.

cxterm has made the effect of "stty -strip" when it is started,
thus 8-bit/byte data will pass through kernel & SHELL to cxterm.

8-bit HanZi data is often mistakenly input as command to SHELL;
and some SHELL (e.g. csh) regards the data as end-of-file to SHELL
causing cxterm to exit & the window to vanish.

To overcome this problem in C-shell, the user should use the c-shell
(or equivalent) command "set ignoreeof".
(Then the user types "exit", not <control-d>, to exit cxterm.)

Since the bottom 2 "lines" of the window are occupied by HanZi
input area, the program 'resize' coming with 'xterm' will get
the environment variable TERMCAP with attribute
        li#n
where n is 2 lines more than the displayable text;
i.e., n == ( fullVwin.fullheight / FontHeight )

This can cause problem in programs (e.g. vi) using TERMCAP.

Now cxterm will start with the correct TERMCAP attribute li#n-2.

Once started, cxterm will keep the total number of displayable
lines correct even if the cxterm window is resized.

Also, the original program 'resize' came with xterm
was modified to 'cxresize' so that it will set
the environment variable TERMCAP with attribute li#n-2
                                                   ^^^

Note that after resize of the cxterm window,
        the TERMCAP attribute li#
will become incorrect.  However, since cxterm's concept of
the total number of displayable line numbers is correct,
vi will work properly without doing cxresize.
Of course, if the user like, he/she can run
        cxresize (or the alias cxsize)
to update the TERMCAP attribute li#

--------------

%% 2 KNOWN BUG(S):

(1)
When a HanZi is input at the end of a text line which has only
1 ASCII char position left, the new HanZi will be displayed in
the next line.  Then if <Delete> is pressed till the cursor
moved back to the previous line, the cursor will be set at the
last ASCII char position of the line; i.e. the cursor will be
on top of a non-existing char (though the char before it has
already be deleted).

(2)
In main.c and screen.c, there is coding like:

#ifdef sun
        ...
#else   /* sun */

        ...

        /* height == screen->fullVwin.fullheight */
        /* width  == screen->fullVwin.fullwidth  */

        /* Set tty's idea of window size */
        ws.ws_row = rows;
        ws.ws_col = cols;
        ws.ws_xpixel = width;
        ws.ws_ypixel = height;  /* ??? will be problem ??? */
        /*
         * Now height is full window's, including HZInputArea !!!
         * NOT match that of rows, which excludes HZInputArea !!!
         * ??? will be problem ???
         */
        ioctl (screen->respond, TIOCSWINSZ, (char *)&ws);

        ...
#endif

Mismatch of ws.ws_row & ws.ws_xpixel may be potential problem ???

------------
END OF Notes
------------
