Subject: Update CXTERM Help File

From: Rupert Zhu <[email-masked]>
Date: Tue, 26 Nov 91 09:12:55 -0500

Minghui and Weihe:

      I am forwarding to you the updated CXTERM Help File.

-- Ruopeng

----------------------------------------------------------------
>From [email-masked] Tue Nov 26 00:05 EST 1991
To: rzhu@WATMATH
Cc: [email-masked]
Subject: New CXTERM HELP file for CCMAN and CHPOEM

Hi.  Here is lastest CXTERM help file for CCMAN and CHPOEM.
It is to replace the Apr/91 version of CXTERM help file.
The major changes are: modification that reflects the new release of CXTERM,
better instructions, and updated FAQ list.

Thank you very much.

Yongguang Zhang

---------
This file is also ftp'able from cs.purdue.edu:pub/ygz/CND-CM-HELP

----------
File Name:				CND-CM-HELP (cs.purdue.edu:~ftp/pub/ygz)
Last Update:				Fri Nov 22 22:13:09 EST 1991

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 RS (running AIX), SGI IRIS,
    Tektronix stations, Apple Macintosh, etc.

(2) If you are using on 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, you
    may need exact work to set up Chinese software in those 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.mnsu.edu		[IP: 128.123.1.14]
	Directory:	pub/chinese	
	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 should read the 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 workstation, 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 pathname 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 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 to 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 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 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: When I compile cxterm on a DECstation, warning message shows:

    cc -c -O -Wf,-XNh2000 -Olimit 2000  -I/usr/include -DHANZI -DNEW_HANZI
    -DUTMP -DWTMP -DLASTLOG  main.c
    ccom: Warning: main.c, line 692: illegal combination of pointer and
    integer, op=
                                        0, 0);
          -----------------------------------^

 A: This warning message doesn't do any harm.  By adding "-D_NO_PROTO", you
    can get ride of it.  (Actually that definition should be in your
    system-wide X11/config template file.)

 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.

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.
    See section 2(1) above for the location of these software packages. 

 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.