本文簡述 xcin 相關操作細節:

1. Command line & 環境變數:

   直接執行 xcin -h, 您會見到以下的使用說明:

===========================================================================
XCIN (Chinese XIM server) version xcin <version number>
(module ver: <version number>, syscin ver: xcin-<version number>).
(use "-h" option for help)

Usage:  xcin [-h] [-d DISPLAY] [-x XIM_name] [-r rcfile]
Options:  -h: print this message.
          -d: set X Display.
          -x: register XIM server name to Xlib.
          -r: set user specified rcfile.

Useful environment variables:  $XCIN_RCFILE.
===========================================================================

   以前 xcin 大量的命令列選項已移至 rcfile 中 (見第 2 點的說明)。除了命
   令列選項與 rcfile 之外， xcin 還可接受以下的環境變數:

   LC_CTYPE:     設定字元處理的 locale, 預設是 "zh_TW.Big5"
   LC_MESSAGES:  設定訊息輸出的 locale, 預設是 "C" 或 "POSIX" (英文)
   XCIN_RCFILE:  預設的 rcfile 檔名


   如果有某項設定同時在命令列選項、環境變數、以及 rcfile 出現時，則 xcin
   內定的優先次序為:

	命令列選項 > 環境變數 > user rcfile > default rcfile > xcin default

   若不設任何命令列選項與環境變數， xcin 以內定值來啟動。 xcin 內定是讀取
   $RCPATH/xcinrc 做為預設的 rcfile, 其中 $RCPATH 值是 configure/make 時
   給定的 (預設是 /usr/local/etc 或 /etc)。 xcin 只會讀取一個 rcfile, 其
   搜尋 rcfile 的順序為:

	$HOME/.xcin/xcinrc	(假設您的 XCIN_USER_DIR 是設為 ".xcin", 見下述)
	$HOME/.xcinrc
	$RCPATH/xcinrc		(系統預設的 rcfile)

   因此，一般使用者若不滿意系統預設的 rcfile 設定值，原則上只要將系統預設
   的 rcfile 拷備一份到 $HOME/.xcin/ 或 $HOME/ 下，再將它修改成自己喜好的
   組態即可，或由命令列選項或環境變數中直接指定。


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


2. XIM (X Input Method) server:

   在 XIM 架構中，程式分成兩種，一為 XIM server, 另一為 XIM client 。 XIM
   server 是用來提供輸入法的程式，而 XIM client 則是一般 X window 應用程式,
   它們必須要支援 XIM 的協定，才能接受來自 XIM server 的字串輸入。

   xcin-2.5 是一個 XIM server, 它用以提供 XIM client 中文 (如 Big5 或 GB
   碼) 輸入。在一個執行中的 X Window 系統中 (X Display), 可以同時跑好幾個
   XIM server, 每一個 XIM server 都有一組唯一的標簽來做為識別: (LC_CTYPE,
   XIM_name) 。其中 LC_CTYPE 即為 locale 名，例如我們用的是 "zh_TW.Big5",
   而 XIM_name 則為 xcin 註冊在此 X Display 中的 XIM server 名。在 locale
   的環境中，一個 locale 可以跑多個以不同 XIM_name 啟動的 xcin, 故如果您需
   要同時輸入 Big5 與 GB 的文字，您必須開兩個 rxvt 視窗，分別設定 zh_TW.Big5
   與 GB 的 locale, 然後分別以不同的 XIM_name 來跑 xcin, 則以 zh_TW.Big5 
   locale 起動的 xcin 便會以 Big5 顯示/輸入中文，反之以 GB locale 起動的 
   xcin 便會以 GB 顯示/輸入中文。

   同理，每一個 XIM client (如 rxvt) 啟動時也必須同時設定其 locale 與希望
   與之建立連線的 XIM server 名 (即 XIM_name), 如此，在 zh_TW.Big5 locale
   下啟動的 XIM client 就可以接受來自 zh_TW.Big5 locale 下啟動的 xcin 的輸
   入， GB locale 的情況亦然。

   在預設的情況下， xcin 若是在 zh_TW.Big5 locale 下啟動的，則它所註冊的
   XIM_name 為 "xcin" 。若是在別的 locale 下啟動，例如: zh_CN.GB2312, 則
   它所註冊的 XIM_name 為 "xcin" 後頭再加 -"locale 名"，例如:

	xcin-zh_CN.GB2312

   當然，我們也可以在命令列選項中使用 -x 的選項來指定 xcin 用來註冊的名字。

   除此之外，標準的 XIM server 還可以支援數種不同的 input_style, 而目前 xcin
   只支援一種 input_style: "Root", 即組字區與狀態區全部都在 xcin 視窗中。
   因此當您要啟動 XIM client 與 xcin 連線時，您必須設定 client 的 input_style,
   未來 xcin 會再支援其他的 input_style。

   當 xcin 啟動時，所有上述的 XIM server 組態都會顯示出來，以供 XIM client
   設定時參考，例如在預設情況下直接啟動 xcin (不加任何選項)，則 xcin 會印出
   如下訊息:

XCIN (Chinese XIM server) version xcin <version number>.
(module ver: <version number>, syscin ver: <version number>).
(use "-h" option for help)

xcin: XIM server "xcin" locale "zh_TW.Big5" transport "X/" inp_style "Root".

   其意義是: XIM_name 為 "xcin", locale (LC_CTYPE) 環境為 "zh_TW.Big5", XIM
   傳輸模式是 "X protocol", 而 inp_style 為 "Root"。

   xcin 同時採用動態連結的方式與 XIM client 運作。當我們用「英數」、「半形」
   輸入時， xcin 與 XIM client 是處於「斷線」的狀態，故我們輸入的是一般
   ascii 碼。但當我們按下任何一個觸發鍵 (trigger key，詳見後述) 時，就恢
   復了 XIM client 與 server 之間的連線，而進行中文或全形字的輸入。


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


3. rcfile 格式 (請同時參考 xcinrc 檔):

   xcin-2.5 的 rcfile 採用 siod 做為語法分析器，其語法為 lisp/Scheme 的混
   合。其語法如下:

   a. 如一行中有 ';' 字元，則從此字元開始一直到行末都會視為注解。

   b. (define $cmd $value):
	設定 $cmd 的值為 $value 。若 $value 值只是單純字串，則必須用一對
	雙引號 " 括起來。例如:

	(define FG_COLOR "white")	; 設定前景色為白色

	$value 也可以是下一層的 $cmd, $value 的子集，則這些子集外圍必須
        再加一層括號，例如:

	; 設定輸入法 zh_hex 其中文名為 "Big5 內碼"，且 BEEP_WRONG 值為
	; "YES" 。請注意以下的括號配對。
	(define zh_hex  '((INP_CNAME   "Big5 內碼")
			  (BEEP_WRONG  "YES")
		         )
	)
        
   xcin-2.5 的架構分為 xcin 主程式與輸入法模組 (module) 兩部分。而 rcfile
   的設定分成三節: 主程式全域設定、主程式各 locale 的設定、以及各輸入法的
   細部設定。其中各輸入法的細部設定與該輸入法所套用的模組有關，其詳細內容
   請參考 doc/modules/ 的說明文件。以下解釋 xcin 主程式的 rcfile command 
   關鍵字意義 (見 xcinrc 檔):

 
   a. 主程式全域設定:
   ------------------
   XCIN_DEFAULT_DIR:
	xcin 預設資料目錄，該目錄存放輸入法表格、輸入法模組、及其他相關檔案。

   XCIN_USER_DIR:
	使用者自定的資料目錄。若它不是絕對路徑，則是以使用的 $HOME 目錄開始。

   INDEX_FONT:
	用來顯示英文輸入法名 (於 xcin 視窗的右下角) 的字型名。

   FG_COLOR:
	xcin 視窗的前景色。

   BG_COLOR:
	xcin 視窗的背景色。

   M_FG_COLOR:
	xcin 視窗的特殊顯示前景色 (如組字區、重覆字選擇鍵)。

   M_BG_COLOR:
	xcin 視窗的特殊顯示背景色 (如組字區、重覆字選擇鍵)。

   ULINE_COLOR:
	xcin 視窗片語標示線的顏色。

   GRID_COLOR:
	xcin 視窗表格格線的顏色。

   X_GEOMETRY:
	xcin 視窗開啟的大小、位置。

   XCIN_HIDE:
	是否在英文與半形輸入時隱藏 xcin?

   XKILL_DISABLE:
	是否將「可在 Window Manager 下直接關閉 xcin 」功能關掉?

   ICCHECK_DISABLE:
	是否將 IC 檢查功能關閉。此功能用於定時檢查所有 XIM client 的 IC
	與視窗是否存在。

   IM_FOCUS_ON:
	預設啟動輸入法鎖定功能，詳見後述。

   SINGLE_IM_CONTEXT:
	是否讓所有的 XIM client 共享輸入法資料結構。預設為 NO, 即各 XIM
	client 的輸入法資料結構是分開的，因此各 XIM client 的輸入法狀態
	各自獨立。若將它設為 YES 時，則所有的 XIM client 將會擁有相同的
	輸入法狀態。

   KEEP_POSITION_ON:
	是否開啟保持 xcin 視窗位置的功能。若此項選開啟時，則當我們在切
	換虛擬桌面時， xcin 會自動出現在目前使用的虛擬桌面上。同時當我
	們將 xcin 視窗移動超出螢幕邊界時， xcin 也會跑回原來的位置。此
	功能可以適用於一些簡單的 Window Manager, 例如 fvwm 系列，如果
	該 Window Manager 沒有提供將某視窗永遠固定於目前工作中的虛擬桌
	面時，則可以嘗試打開此選項。但如果您使用的 Window Manager 有提
	供此功能時，建議您將此選項關掉，以避免其他可能的問題。本選項預
	設是關。

   INPUT_STYLE:
	設定 XIM server 可接受的 input_style。其值可以為 (可多重設定):

	Root:  即傳統的 xcin 視窗。輸入時組字區與狀態區在 xcin 視窗中。

	OverTheSpot:  除了傳統的 xcin 視窗外，輸入時 xcin 會在您目前游
	       標所在位置附近另外顯示一個視窗，而輸入時的組字區會顯示在
	       那。

   FKEY_ZHEN:  (預設 "ctrl space")
	設定英數/中文切換鍵。

   FKEY_2BSB:  (預設 "shift space")
	設定全形/半形切換鍵。

   FKEY_CIRIM:  (預設 "ctrl shift")
	設定正向循環切換輸入法切換鍵。

   FKEY_CIRRIM:  (預設 "shift ctrl")
	設定逆向循環切換輸入法切換鍵。

   FKEY_CHREP:  (預設 "ctrl alt r")
	設定重複上次輸出的功能鍵。

   FKEY_SIMD:  (預設 "ctrl alt i")
	設定循環切換字碼顯示 (simd) 的功能鍵。

   FKEY_IMFOCUS:  (預設 "ctrl alt f")
	設定輸入法鎖定 (IM Focus) 的功能鍵。

   FKEY_IMN:  (預設 "ctrl alt")
	設定各輸入法切換輔助鍵。例如設為 "ctrl alt" 時, 則輸入 ctrl+alt+1
	即可切入 setkey 為 1 的輸入法。

   FKEY_QPHRASE:  (預設 "shift alt")
	設定快速片語的切換輔助鍵。例如設為 "shift alt" 時，則輸入
	shift+alt+o 則會輸出 o 碼所代表的片語。

   有關各功能鍵的設定方式與說明，請參考第 4 節。


   b. 主程式各 locale 的設定:
   --------------------------
   在這裏，您必須為每一個您會用到的 locale 分別做設定，其語法為:

	(define "locale name"   '(( "detailed settings" ....)))

   例如您會用到 zh_TW.Big5 與 zh_CN.GB2312, 則您在 xcinrc 中的設定看起來會像
   這樣:

==========================================================================
	(define "zh_TW.Big5"   '((cmd1  "value1")
				 (....  ........)))
	(define "zh_CN.GB2312" '((cmd1  "value1")
				 (....  ........)))
==========================================================================

   以下介紹所有的關鍵字與其意義:

   FONTSET:
	locale 所需的字型組的字型名 (必須中、英文字型各一個)。

   DEFAULT_IM:
	預設的輸入法名。

   DEFAULT_IM_MODULE:
	預設的輸入法模組名。

   DEFAULT_IM_SINMD:
	預設的輸入法字鍵顯示 (sinmd) 名稱。當您在做中文輸入時，每輸入一個
	中文字，則 xcin 視窗第二行的右半邊會出現您剛剛所輸入的字鍵。而這個
	選項就是用來設定顯示的方式。若是設定成任何一種輸入法名時，則不管您
	切換到那一個輸入法，它都會以您所設定的輸入法名來顯示。若是設定成 
	"DEFAULT" 時，則它會以您目前所用的輸入法來顯示 (當您切換輸入法時，
	顯示也會跟者切換)。

   PHRASE:
	指定快速鍵片語資料檔。快速鍵片語輸入即為 shift+alt+?, 其中 ? 是任
	何一個 ASCII 字鍵，例如要打出頓號我們會用 shift+alt+i 。

   CINPUT:
	指定此 locale 下欲使用的輸入法名稱。


   c. 各輸入法的細部設定:
   ----------------------
   所謂「輸入法名稱」其實就是輸入法表格名，但去掉末尾的 ".tab" 或 ".cin"
   等的副檔名，例如我們常見的倉頡輸入法即為 "cj", 注音輸入法即為 "phone"。 
   現在 xcin 不再硬性指定 ctrl+alt+3 是注音、 ctrl+alt+6 是詞音等等了，所有
   需要用的輸入法，全部都由 CINPUT 的設定才會載入使用。而 DEFAULT_IM 與
   DEFAULT_IM_SINMD 所指定的輸入法名，必須在所有的 CINPUT 的設定中找得到才
   行 (其中 DEFAULT_IM_SINMD 若指定為 "DEFAULT" 時例外)，若找不到， xcin 會
   自動選用其他 CINPUT 所指定的輸入法作為預設輸入法或作為預設字鍵顯示用。

   與過去另一個很大的不同點是， xcin 採用了輸入法模組 (module) 的架構。輸
   入法與模組的關係為: 輸入法是實體，而模組則是樣版 (或套模)。簡單來說，一
   個 .cin (或 .tab) 檔就是一個輸入法，如 cj.cin, 但該輸入法必須藉由模組所
   提供的函式才能工作，也就是「將輸入法套入模組中」。因此，一個模組可以套用
   多個輸入法，例如 gen_inp 模組，它可以套用目前常用的輸入法如倉頡、行列、
   無蝦米、大易 .... 等等。而特殊的輸入法，無法直接拿 gen_inp 模組來套用的，
   才另外寫一個專門的模組，如內碼 (zh_hex)、注音 (phone) .... 等。故就上述
   的設定中， DEFAULT_IM_MODULE 就是指定預設的 module 套模。若之後的輸入法
   細部設定中，不特別指定要套用那一個 module 的話，則用 DEFAULT_IM_MODULE
   所指定的 module 名來套用。

   當 rcfile 有了上述的設定之後，接下來便是要為所有在 CINPUT 指定要使用的
   輸入法做細部設定了。其格式如下 (舉例):

============================================================================
(define zh_hex 				; 這是 CINPUT 中有列的其中一個輸入法名
        '((INP_CNAME    "Big5 內碼")	; 以下是本輸入法的細部設定
          (SETKEY       0)
          (MODULE       zh_hex)
          (......	......)))

(define cj
        '((SETKEY       1)
	  (......	......)))
============================================================================

   各位可以見到，所有輸入法的細步設定是個自獨立的，故不會像舊版的 xcin 那
   樣，做一個輸入法的細部設定，則所有的輸入法都受到影響。每個輸入法的細部
   設定的細節，依其所套用的 module 而有不同，其相關說明請見 modules/ 目錄
   中各模組的說明文件。以下說明各模組均可使用的細部設定項:

   1. INP_CNAME:
	設定此輸入法的中文名，可有可無。但是否採用此設定則視該 module 的
	實作而定。

   2. SETKEY:
	定義該輸入法的切換鍵，如內碼為 ctrl+alt+0, 倉頡為 ctrl+alt+1。

   3. MODULE:
	指定本輸入法欲套用的 module 名。若不指定，則會以 DEFAULT_IM_MODULE
	所設定的 module 來套用。請注意，並非所有的 module 都可以套用所有的
	輸入法，例如 zh_hex module 只能套用 zh_hex 輸入法，不能拿來套用倉
	頡輸入法。故如果您做了不恰當的指定，將可能造成套用失敗，則 xcin 會
	顯示警告訊息，並忽略此輸入法。

   4. LOCALE:
	指定本輸入法適用的 locale。如果不指定的話，則在任何 locale 底下都
	可以使用本輸入法，否則只有在此指定的 locale 下才會載入使用。

   所有的輸入法與 module 只會在需要時才載入，故使用者可以在 rcfile 中設定
   5, 6 個輸入法，但只有當使用者真正會用到的 (即有按 ctrl+alt+? 切換到的)
   那幾個才會真正載入)。

   所有和 locale 相關的資料檔，包括所有的 .cin, .tab, 以及快速鍵片語輸入的
   資料檔等，預設都是放在 $XCIN_DEFAULT_DIR/tab/$LC_CTYPE/ 的目錄中，使用
   者也可以自行準備您的 .cin 與 .tab 檔，放在您的 $XCIN_USER_DIR 目錄中
   (例如 $HOME/.xcin/), xcin 啟動時搜尋這些資料檔的順序為:

	1. $XCIN_USER_DIR/tab/$LC_CTYPE/
	2. $XCIN_USER_DIR/tab/
	3. $XCIN_USER_DIR/
	4. $XCIN_DEFAULT_DIR/tab/$LC_CTYPE
	5. $XCIN_DEFAULT_DIR/tab/
	6. $XCIN_DEFAULT_DIR/


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


4. Trigger keys & Special keys:

   Trigger keys 用來「觸發」 XIM client 與 XIM server 的連線。目前歸類
   為觸發鍵的計有:

   a. FKEY_ZHEN:  			中文 / 英文切換。
   b. FKEY_IMN + [0123456790-=]:  	選擇輸入法。
   c. FKEY_2BSB:  			全形 / 半形切換。
   d. FKEY_CIRIM:  			依序切換輸入法 (正向切換)。
   e. FKEY_CIRRIM:  			依序切換輸入法 (反向切換)。
   f. FKEY_QPHRASE + [0-9a-z....]:	快速片語輸出。			

   其中快速片語輸出較為特殊，當原來 xcin 是處於英數輸入時，若使用
   FKEY_QPHRASE 觸發鍵，則 XIM client 會與 xcin 進行短暫連線，當完成片
   語的輸出後，隨即回復離線狀態。換句話說，在英數輸入時可以直接輸出片
   語，但 xcin 仍保持在英數輸入的模式下。

   除此之外， xcin 尚有一些不歸類為「觸發鍵」的功能鍵，也就是說您必須
   在 XIM client 與 xcin 連線時才能使用它 (即 xcin 處於中文或全形輸入
   時) ，這些功能鍵包括:

   a. FKEY_CHREP 可以重覆此 XIM client 剛剛輸入的中文字。

   b. FKEY_SIMD 可以循序切換輸入法字鍵顯示 (sinmd), 若 DEFAULT_IM_SINMD
      原先是設定成 "DEFAULT" 時，則按下此特殊鍵後 "DEFAULT" 模式即取消。

   c. FKEY_IMFOCUS 可以開啟、關閉輸入法鎖定功能。當輸入法鎖定功能開啟時，
      xcin 視窗右下角的輸入法名之前會多一個 "*" 號。此功能開啟時，每當有
      新的應用程式啟動 (即有新的 IC 產生)，則此應用程式會自動進入目前鎖
      定的輸入法，而不會以預設的英數輸入啟動。當您在切換輸入法時，其鎖定
      的輸入法也隨之改變。

      (此功能的引入，是為了讓 xcin 能順利在 netscape-4.5/6 下輸入，詳見
       FAQ 的說明)

   上述所有的功能鍵或觸發鍵，都可以依使用者的喜好在 rcfile 中進行設定，
   例如:

	(define FKEY_CHREP     "ctrl alt r")

   即是設定重複上次輸出鍵為 ctrl+alt+r, 請注意在此所有的字鍵名要有雙引號
   括起來，同時每個字鍵名必須用空格分開。字鍵的組合最多只能有三個鍵，且
   若設定多個鍵時，請注意有順序之分: 最後一個鍵稱之為「實鍵 (keysym) 」，
   而其餘的稱之為「輔助鍵 (modifier)」，操作順序為先按「輔助鍵」，再按「
   實鍵」，則該功能鍵組合才會有動作。

   因此，您要注意 "ctrl shift" 與 "shift ctrl" 的分別，前者 shift 為實鍵，
   而後者它卻變成了輔助鍵，故您按此二鍵的順序不同， xcin 會有不同的反應。

   同時要注意並非所有的鍵都可以做為輔助鍵，但所有的鍵都可以做為實鍵。目前
   xcin 定義可用的輔助鍵計有:

	shift, L-shift, R-shift, 	(此三鍵作用完全相同，以下類推)
	ctrl, L-ctrl, R-ctrl,
	alt, L-alt, R-alt,

   至於 xcin 所定義可用的實鍵請見本節末的列表。


   最後，在同時為中文輸入與全形模式中，若敲入的字鍵不是該輸入法的組字鍵，
   則直接變成全形符號輸出。若是該輸入法的組字鍵，若同時按下 shift 鍵時，則:

   a. 若此時 CapLock off, 則輸出小寫全形英文。

   b. 若此時 CapLock on, 則輸出大寫全形英文。


   xcin 所定義的實鍵列表
-------------------------------------------------------------------------
	鍵名			備注
    ===================================================
        "shift",       		與 L-shift 同義
        "L-shift",     
        "R-shift",     
        "ctrl",        		與 L-ctrl 同義
        "L-ctrl",      
        "R-ctrl",      
        "alt",         		與 L-alt 同義
        "L-alt",       
        "R-alt",       
        "esc",         		ESC 鍵
        "f1",          		F<n> 功能鍵區， <n> 為數字
        "f2",          
        "f3",          
        "f4",          
        "f5",          
        "f6",          
        "f7",          
        "f8",          
        "f9",          
        "f10",         
        "f11",         
        "f12",         
        "grave",       		「 ` 」反引號
        "1",           		數字鍵區
        "2",           
        "3",           
        "4",           
        "5",           
        "6",           
        "7",           
        "8",           
        "9",           
        "0",           
        "-",           
        "=",           
        "tab",         
        "space",       
        "backspace",   
        "a",           		英文鍵區
        "b",           
        "c",           
        "d",           
        "e",           
        "f",           
        "g",           
        "h",           
        "i",           
        "j",           
        "k",           
        "l",           
        "m",           
        "n",           
        "o",           
        "p",           
        "q",           
        "r",           
        "s",           
        "t",           
        "u",           
        "v",           
        "w",           
        "x",           
        "y",           
        "z",           
        "[",           
        "]",           
        "semicolon",   		「 ; 」分號
        "apostrophe",  		「 ' 」單引號
        "comma",       		「 , 」逗號
        "period",      		「 . 」小數點
        "slash",       		「 / 」正斜線
        "backslash",   		「 \ 」反斜線
    ===================================================


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


5. 有關各 module 的細部設定說明，請見 modules/ 目錄中的文件。


T.H.Hsieh
