From: leung@DSG.Tandem.COM (Steven Leung)
Subject: Re: Looking for cxterm user's  guide
Organization: Tandem Computers
Date: Thu, 1 Oct 1992 19:48:07 GMT

cxterm is just an xterm with the capability to display chinese char.
To enter chinese char., you can use celvis (see the attached file),
or the brute-force method of cat > filename.

Steven
------
328. Seek opportunity, not security. ...
        - Life's Little Instruction Book by H. J. Brown, Jr.

File Name:			CND-CM-HELP.CXTERM (cs.purdue.edu:~ftp/pub/ygz)
Last Update:			Sat Aug  1 16:59:49 EST 1992

CONTENTS:
1.  WHAT DO YOU NEED
2.  HOW TO SET UP NECESSARY SOFTWARE TO READ CHINESE IN X WINDOW
    (1) How To Get The Software
    (2) How to Install X11 Chinese Font (cclib16st or others)
    (3) How To Install cxterm
    (4) How To Install cless
    (5) How To Install celvis
    (6) Where To Get Help If I Fail In The Installation
3. HOW TO USE CXTERM TO READ CHINESE ARTICLES
APPENDIX:  FREQUENTLY ASKED QUESTIONS
	General Questions
	About X Windows
	About cxterm/celvis
	Miscellaneous Questions
------------------------------------------------------------------------------

1. WHAT DO YOU NEED
^^^^^^^^^^^^^^^^^^^

(1) You need to have access to a Unix workstation or an X Terminal.
    Examples of such hardware are Sun, HP WorkStation, Appollo,
    DECstation (running Ultirx), IBM RT or RS (running AIX), SGI IRIS,
    Tektronix stations, Apple Macintosh, etc.

(2) If you are using a workstation, X Window System Version 11 (Release 4
    or Release 5) must be installed in the workstation.

    Note that some other window systems are claimed to be X compatible.
    However, you need extra work to set up Chinese software in such systems.
    Here are some examples we know:

	Open Windows		(Sun workstation, etc.)
	DECwindow		(DECstation)

(3) After all, you may need a lot of knowledge of Unix/X to or help from
    your system manager to set up the whole software system.  Once set up,
    it is easy to use.


2. HOW TO SET UP NECESSARY SOFTWARE TO READ CHINESE IN X WINDOW
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The software packages you may need to read/write Chinese file in X window are

    1) REQUIRED:

	a) Chinese fonts for X11
	    distribution format:	BDF font format.
	    files:			cclib16st.bdf, 8x18.bdf, fonts.alias
	    alternatives:		cclib16fs, or beijing24, etc.

        b) cxterm	(Chinese terminal emulator with input capability)
	    distribution format: 	source code, in tar format.
	    files: for X11R4:		cxterm-11.4.2.tar.Z
		or for X11R5:		cxterm-11.5.1.tar.Z
	    prerequisites:		Chinese fonts (cclib16st, 8x18, etc)
	    alternatives:		kterm (without input capability)
	    				xhzview (a simple X viewer for Chinese)

    2) RECOMMENDED:

	c) cless	(a pager program to facilitate Chinese browering)
	    distribution format: 	source code, in tar format.
	    prerequisites:		cxterm

        d) celvis	(a Chinese editor, in case you want to edit something)
	    distribution format: 	source code, in tar format.
	    prerequisites:		cxterm

    3) ADVANCED:

	cemacs, more Chinese fonts, more Chinese input methods for cxterm.

(1) How To Get The Software
    -----------------------

    FTP: all the software packages are available in several FTP sites.

	Site:		cs.purdue.edu		[IP: 128.10.2.1]
	Directory:	pub/ygz	
	Files:		x-fonts/cclib16st.bdf.Z		Chinese font cclib16st
			x-fonts/8x18.bdf		matching font 8x18
			x-fonts/fonts.alias		font alias file
			cxterm-11.4.2.tar.Z		X11R4 cxterm program
			cxterm-11.5.1.tar.Z		X11R5 cxterm program
			utils/cless.tar.Z		cless program
			celvis.tar.Z			celvis program
			cemacs.tar.Z			cemacs program

	Site:		crl.nmsu.edu		[IP: 128.123.1.18]
	Directory:	pub/chinese,	pub/misc	
	Files:		fonts/cclib16st.bdf.Z		Chinese font cclib16st
			fonts/8x18.bdf.Z		matching font 8x18
			cxterm-11.4.2.tar.Z		X11R4 cxterm program
			cxterm-11.5.1.tar.Z		X11R5 cxterm program
			celvis.tar.Z			celvis program
			kterm.tar.Z			kterm program
			xhzview.tar.Z			xhzview program
			ChTeX.tar.Z			Chinese TeX/LaTeX

	Site:		ahkcus.org		[IP: 192.55.187.25]
	Directory:	src/unix
			cxterm-11.4.2.tar.Z		X11R4 cxterm program
			cxterm-11.5.1.tar.Z		X11R5 cxterm program
			celvis.tar.Z			celvis program
			hz2ps-2.0.tar.Z			Chinese => PS program
			hzfont.tar.Z			fonts for hz2ps-2.0
			gb2ps.tar.Z			Chinese => PS program
			xhzview.3-0.shar		xhzview program


(2) How to Install X11 Chinese Font (cclib16st or others)
    -----------------------------------------------------

    Create a dedicated directory for the fonts in your workstation.
    Assuming ~/xfonts in the following illustration.

  1) Step I:  Installation

    Choose _one_ of the installation procedures, according to the window
    system you are using.

    - X11R4		(X Window System Version 11 Release 4)

        % mkdir ~/xfonts
        % mv cclib16st.bdf.Z 8x18.bdf fonts.alias ~/xfonts
        % cd ~/xfonts
        % bdftosnf -t 8x18.bdf > 8x18.snf
        % zcat cclib16st.bdf.Z | bdftosnf -t > cclib16st.snf
        % mkfontdir .

    - X11R5		(X Window System Version 11 Release 5)

        % mkdir ~/xfonts
        % mv cclib16st.bdf.Z fonts.alias ~/xfonts
        % cd ~/xfonts
        % zcat cclib16st.bdf.Z | bdftopcf -t > cclib16st.pcf
        % mkfontdir .

    - Open Window 2.0	(X11/NeWS window system server "xnews")

        % mkdir ~/xfonts
        % mv cclib16st.bdf.Z 8x18.bdf ~/xfonts
        % cd ~/xfonts
        % uncompress cclib16st.bdf.Z
        % convertfont 8x18.bdf
        % convertfont -M -n cclib16st -o cclib16st cclib16st.bdf
        % bldfamily

	(Note: ignore the error messages by "bldfamily", them won't harm.)

    - DECwindow		(X windows running on DECstations)

	% mkdir ~/xfonts
        % mv cclib16st.bdf.Z 8x18.bdf fonts.alias ~/xfonts
        % cd ~/xfonts
        % dxfc -t < 8x18.bdf > 8x18.pcf
        % zcat cclib16st.bdf.Z | dxfc -t > cclib16st.pcf
        % dxmkfontdir .

  2) Step II:  Configuration

    Each time after you start your X window, type

	% xset fp+ ~/xfonts;

    You will like to put the above line in your X startup script file,
    to include the fonts automatically next time.

    To test if the fonts are installed correctly, try

	% xfd -fn cclib16st -start 41216

    You should be able to see all the Chinese characters page by page.
    (All "real" Hanzi starts from the 16th page.)


(3) How to Install cxterm
    ---------------------

    - X11R4 cxterm

	Unpack cxterm after you get cxterm-11.4.2.tar.Z from ftp and make it

	% zcat cxterm-11.4.2.tar.Z | tar xvf -
	% cd cxterm
	% xmkmf
	% make Makefiles
	% make

	(Note:  DECstation user please read FAQ list below first.)

    - X11R5 cxterm

	Unpack cxterm after you get cxterm-11.4.2.tar.Z from ftp and make it

        % zcat cxterm-11.5.1.tar.Z | tar xvf -
        % cd cxterm
	% make

    If success, the executable cxterm program is produced. You can copy
    it to a safe directory for future use.

    If failed, read README file in the cxterm directory carefully.


(4) How to Install cless
    --------------------

    Unpack cless after you get cless.tar.Z from ftp and make it

	% zcat cless.tar.Z | tar xvf -
	% cd cless
	% sh ./install
	% make

    If success, the executable cless program is produced. You can copy
    it to a safe directory for future use.


(5) How to Install celvis
    ---------------------

    Unpack celvis after you get celvis.tar.Z from ftp and make it

	% zcat celvis.tar.Z | tar xvf -
	% cd celvis

    Read Makefile carefully.  Make necessary changes.

	% make

    If success, the executable celvis program is produced. You can copy
    it to a safe directory for future use.


(6) Where To Get Help If I Fail In The Installation
    -----------------------------------------------

    To successfully install a software in Unix and X window is not an easy
    task, especially if you are using a not-so-popular platform.  However,
    there are some places you can get help from.

    First, read the "Frequently Asked Questions" part to see if there are
    some similar situations and solutions which are not mentioned above.
    Then try them out yourself.

    Second, see your system manager or find a system guru in your lab
    to look at the problems with you.  In most cases, the failures in
    installation are not related to the Chinese software itself.  These
    errors are due to the unpredictable software configuration in your
    site, and they can be easily overcome if you know your systems well.
    So a knowledgeable-looking person in your department will be more
    helpful than a person who never use your computer.

    Third, send mail to the experts who are willing to help.  However,
    Unix and X11 are such configurable systems that most of the problems
    you come cross depend on the system configuration.  Usually the remote
    experts can only provide some useful hints based on their experiences.


3. HOW TO USE CXTERM TO READ CHINESE ARTICLES
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

(1) Decode your Chinese articles received by mail.

    Save your mail as a text file (say, "Chinese.uue"). Then do uudecode as:

	% uudecode Chinese.uue

    Then a decoded Chinese file (with name "cm9104c.gb" or alike) is produced.
    That is the Chinese articles in GB coding.

(2) Start cxterm using the cxterm program built in the section 2.

	% cxterm &

(3) Read Chinese article in the cxterm window, using more, or cless, or clevis:

	% more cm9104c.gb		(not recommended)
    or
	% cless cm9104c.gb
    or
	% celvis cm9104c.gb

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

APPENDIX:  FREQUENTLY ASKED QUESTIONS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

GENERAL QUESTIONS
^^^^^^^^^^^^^^^^^

ABOUT X WINDOWS
^^^^^^^^^^^^^^^

 Q: How to install the Chinese fonts in a X terminal?

 A: Fonts are hard to add to X terminal since X terminal doesn't have its
    own disk.  Different model of X terminal will have different solution.
    Many X terminals are set up to load the fonts by reading the font files
    via NFS.  In this case your font directory must be put in a file system
    which is exported to the X terminals.  Others may use font daemons.
    So the best way to do this is to give the *.bdf font files to your
    system manager and ask him/her to install them for you.

--------------------
 Q: I have access to more than one workstations, do I need to install
    a copy of Chinese fonts in each of them?

 A: It depends.  First, each workstation running X window system must be
    able to read the font files directly (e.g. by NFS).  Second, the .snf
    files generated during the installation are architecture dependent.
    For example, if you have a network of Sun, DEC, and HP workstations,
    which share some file systems, you can install one copy for Sun, one
    copy for DEC, and one copy for HP.  All workstations of the same
    architecture can share a same copy via NFS.

    There is exception in X11R5.  X11R5 .pcf files are machine independent.
    One copy of the .pcf fonts can be used by all workstations, no matter
    what architecture that copy of fonts were installed.

--------------------
 Q: I failed in install the fonts, what's wrong?

 A: Here is how to test your font installation:

    1)  run
		% xset q

	You will see a list of directories under "Font Path:" section.
	The path-name of your new-added font directory, should appear
	on the list exactly once.

	If you cannot find your new-added font directory in the list,
	your installation failed.  It may be caused by:

	a)  you didn't follow the steps to build the font directory
	    (e.g. you forgot to "mkfontdir");

	b)  you didn't give a *full* path name (the path name which starts
	    from the root as "/....") for "fontdir" in "xset fp+ fontdir";

	c)  the X server doesn't have the privilege to read your font
	    directory  (e.g. X server is not started by you and your directory
	    is protected);

	d)  there are too many directories in the "Font Path:" list (remove
	    some unimportant ones to make rooms for this new one); or

	e)  your font directory is actually in another machine, but that
	    directory is not mounted on the workstation where the X server
	    runs.  (In this case, try to put the font files in your
	    workstation.  If that is not possible, e.g. in a diskless
	    workstation, or X terminal, ask your system manager for help.)

	If your font directory appears twice or more.  Run

		% xset fp
		% xset fp+ your_font_directory

	and redo the testing again.

    2)  run
		% xset fp rehash
		% xlsfonts

	The output of the second command is a list of font names.
	The string "cclib16st" should appear in the list exactly once.

	If you cannot find "cclib16st", but you can find something like
	-cclib-...,  you forgot to put "fonts.alias" in your font directory.

	If you cannot find anything about cclib16st, or -cclib- font,
	you failed to convert the .bdf fonts into the proper format.

    3)  run
		% xfd -fn cclib16st -start 41216

	You should be able to see all the Chinese characters page by page.
	(All "real" Hanzi starts from the 16th page.)

--------------------
 Q: The fonts are quite large.  Is it possible to make them smaller?

 A: In X11R4, yes.  First, all the *.bdf or *.bdf.Z can be removed after
    the *.snf files are converted and the font path is installed.
    Second, if you want to trade time for space, you can compress all
    the *.snf files:

	% compress *.snf
	% mkfontdir .
	% set fp rehash

    This will save you a lot of space, but you have to wait longer
    for cxterm to start up.

    However, in X11R5, or some non-native X11R4 window systems like
    Open Windows, you cannot compress the font files.

--------------------
 Q: May I run cxterm in one machine but display window in another
    workstation (i.e. another machine)?

 A: Yes, X is a network-transparent window system.  Try the following:

	MachineA%  cxterm -display WorkstationB:0.0

    One thing you have to keep in mind is that X11 fonts are associated
    with X server (each workstation will run its own X server), not cxterm.
    Therefore the Chinese fonts must be locally installed and accessible
    in the workstation on which your cxterm window is going to display.


ABOUT CXTERM / CELVIS
^^^^^^^^^^^^^^^^^^^^^

 Q: How to install cxterm if I don't find "xmkmf" in my system?

 A: Read README file in the cxterm directory.  Try to follow the instruction.
    And ask your system manager and local X guru for help.

--------------------
 Q: When I compile X11R4 cxterm in DECstation, I get an error in main.c,
    line 854.

 A: Change line 854 in main.c from

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

    and try the make again.

--------------------
 Q: I still cannot compile cxterm in DECstation, or SGI.  There are many
    error messages produced.

 A: There is a directory of files contains some hints on compiling cxterm in
    various workstations and platforms (e.g. DECstation, SGI IRIS, etc.)
    It is by ftp in cs.purdue.edu (128.10.2.1): pub/ygz/cxterm-platforms.
    Get the corresponding file and study it before installing cxterm.

--------------------
 Q: I cannot compile cxterm 11.4.2 under OpenWindows 2.0.

 A: Although OpenWindows 2.0 is claimed to be X11R4 compatible, it doesn't
    have all the libraries that come with the MIT X11R4 distribution, which
    are required to compile cxterm.  However, once you compiled cxterm against
    X11R4 libraries, the executable code cxterm can be run under OpenWindows.

    Or, you can try OpenWindows 3.0.  It has all the prerequisite files.

--------------------
 Q: When I make cxterm 11.5.1, the error message is:
	......
	make: Fatal error in reader: Makefile, line 226: Extra `:', `::',
		or `:=' on dependency line
	......

 A: Most likely you was trying to install cxterm 11.5.1 in X11R4 (or X11R4-
    derived, e.g. OpenWin).  It won't work.  Try cxterm 11.4.2 instead.

--------------------
 Q: When I type "cxterm", it prints error messages "permission denied" or
    "cannot execute".

 A: You may mis-treat the name of the directory as the executable binaries.
    Double check to make sure what is the path-name of the cxterm executable.

--------------------
 Q: When I start cxterm, it prints error messages
	"cxterm:  unable to open font ...".

 A: This may be caused by improper installation of X11 font.  See the
    answer of the question "I failed in install the fonts, what's wrong?"

--------------------
 Q: When I start X11R5 cxterm (11.5.1), it prints error messages
	"cxterm:  unable to locate a suitable font".

 A: This may be a font installation problem, see the previous question.

    Or, your X window don't have "8x16" font.  (For example, in DECstation.)
    You can specify an alternative font explicitly as:

	% cxterm -fn '-sony-fixed-medium-r-normal--16-120-*-*-*-*-iso8859-1'
    or
	% cxterm -fn 8x18
    or
	% cxterm -fn fixed                      (the last resort)

    You may simply edit your ~/.Xdefaults file to replace the string
    "8x16" by the name of the alternative font.  For example:

        cxterm*font: -sony-fixed-medium-r-normal--16-120-*-*-*-*-iso8859-1

--------------------
 Q: When I start cxterm, several pieces of warning messages emerge:

	Widget class ... version mismatch ...

 A: These warning messages are not important.  You can just ignore them.
    Probably the version of X window you use to compile cxterm is not
    the version you run cxterm on.  E.g, compiling cxterm in X11R4 but
    run it on X11R3, or compiling cxterm in MIT X11, but run it on
    OpenWindows.  Anyway, these messages won't harm cxterm.

--------------------
 Q: I cannot switch the input methods, only F1 and F2 keys work.

 A: If you want to use Chinese input method, you should remember to set up
    the environment before starting cxterm.  First, the resource definitions
    contained in CXterm.ad (or CXterm.xd) file should be appended to your X
    window resource file (e.g. ~/.Xdefaults), as:

	cat CXterm.ad >> ~/.Xdefaults

    Here is a way to identify your X window resource file:
    1) if in your X window startup script (e.g. ~/.xinitrc), there is a line
       like "xrdb ... filename", then the "filename" is the resource file;
       (remember to rerun "xrdb ......" after the change)
    2) if the environment variable XENVIORNMENT is set, the one XENVIORNMENT
       points to is the resource file;
    3) finally, try ~/.Xdefaults. (Sometimes it could be ~/.Xdefaults.???,
       or ~/.Xresources, etc.  Consult your local X guru.)

    Second, the environment variable HZINPUTDIR should be set to the directory
    name containing all compiled cxterm dictionaries (*.cit files).  E.g.

	setenv HZINPUTDIR ~/dicts

--------------------
 Q: When I ran celvis, the prompt was: 

	Can't read /etc/termcap

 A: Your Unix system may be a SYS V deriver (ask your system manager to
    confirm this), and you may have a /etc/terminfo instead of /etc/termcap.
    Use Makefile.s5 as the Makefile. If it still doesn't work, change the
    line in Makefile.s5
		LIBS=   -ltermcap
    into
		LIBS=   -lterminfo
    or
		LIBS=	-ltermlib
    and try again.

--------------------
 Q: I cannot input or output Chinese in the shell prompt -- what I got is
    two random ASCII characters instead of a Chinese character.

 A: Maybe the 8th bits are stripped from the Chinese characters.

    Cxterm tries to set the proper tty for you, but the user or the system
    may later mistakenly reset it.

    Some shell (e.g. tcsh) strips the 8th bit.  In tcsh, hi-bit set characters
    are used for special key bindings.  To correct this, type "setenv LANG".
    Csh, sh, ksh usually don't have this problem.

    Some system (or your shell startup file, e.g. .cshrc or .login) set the
    tty to strip the 8th bit.  You can reset it by typing "stty pass8".
    (Different systems may have different stty format.  Read stty(1) manual
    for help.  Some possible stty options are "pass8", "cs8", "-istrip",
    "-parenb", etc.)

    Check your X resource file.  If you find something like "eightBitOutput",
    set it to be "true" or "on".  (Or simply remove it, the default is "on".)

    Some operating system may strip the 8th bit from every character.
    You are out of luck since such system is not for international use.

--------------------
 Q: I cannot input Chinese in celvis; it sometimes results in a beep.

 A: In celvis, you should be aware of the two vi modes, "input" mode (in
    which you insert English text), and the "edit" mode (in which you move
    the cursor).  Chinese input is only accepted in "input" mode.  Trying
    to enter Chinese characters in "command" mode will result in a beep.

    Also check the above question and answer.

--------------------
 Q: In celvis, the text seems to have been truncated at the right for each
    line.  Even extending the window width won't help.

 A: The lines that are longer then the window width are not truncated.
    They are side-scrolled by celvis.  To see the rest of the line, you
    need to move the cursor to the right until the hidden text is revealed.

    It is the feature (or bug, sometimes people look this way) of celvis
    that it side-scrolls instead of wraps a line.


MISCELLANEOUS
^^^^^^^^^^^^^

 Q: How to print a Chinese article that I displayed in X window?

 A: You may dump the Chinese window to a Postscript printer. Use
    X11 utilities xdpr

	% xdpr -device ps -Pprinter_name

    and click the mouse in the desired window (where ps is for Postscript
    printer.  Manual xdpr(1) describes options for other kinds of printers.

    However, there are two package to let you convert Chinese text file into
    a postscript file.  "Hz2ps-2.0" and "gb2ps" are good packages to print
    plain Chinese text.  Other software packages including ChTeX and pmTeX
    will be useful if you want to do some text formatting and typesetting.
    Both Hz2ps-2.0 and gb2ps can be found in ahkcus.org (192.55.187.25):
    ~ftp/src/unix; and both ChTeX and pmTeX are available at crl.nmsu.edu
    (128.123.1.18): ~ftp/pub/chinese, or ~ftp/pub/misc.

--------------------
 Q: When I use "more" to read Chinese article in cxterm, the Chinese
    characters are messed up from time to time.

 A: Try to use "cless" instead.  "more" is not designed for Chinese.