--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mule-doc/arabic.txt	Mon Aug 13 09:02:59 2007 +0200
@@ -0,0 +1,355 @@
+HOW TO READ & WRITE ARABIC				94.8.4 TAKAHASHI Naoto
+
+1. STARTING UP
+
+1.1 INVOKING MULE
+
+    You must invoke Mule as an X client if you want to use Arabic.
+    Make sure that the environment variable DISPLAY is properly set.
+    So far only 16 dot font is available for Arabic.  First, set you X
+    resources appropriately, then invoke Mule from a shell window with
+    the following command to get enough line spaces.
+
+	% mule -fsp 0+9
+
+
+1.2 ENTERING AND LEAVING ARABIC-MODE
+
+    Hit C-] to enter arabic-mode.  Whenever you are in arabic-mode,
+    you are also in visual-mode.  Hitting C-] again brings you back
+    from arabic-mode, but you are still in visual-mode.  Hitting C-]
+    in visual-mode brings you into arabic-mode.  You can exit
+    visual-mode by hitting C-c C-c.  See the figure below.
+
+
+			           C-c C-c
+	     +----------------------------------------------+
+             |   +--------------------+                     |
+	     | 	 |      C-c C-c       | 	            |
+	     V   V                    |                     |
+	+-------------+         +-----------+   C-]   +-----------+
+	|             |   C-]   |arabic-mode| ------> |           |
+	|initial state| ------> |    and    |         |visual-mode|
+	|             |		|visual-mode| <------ |           |
+	+-------------+ 	+-----------+   C-]   +-----------+
+
+
+    The string "Arabic L2R" or "Arabic R2L" in mode-line means that
+    you are in both arabic-mode and visual-mode.  If you see "L2R" or
+    "R2L" but not "Arabic" in mode-line, you are in visual-mode but
+    not in arabic-mode.
+
+
+1.3 DISPLAY DIRECTION
+
+    Each buffer in Mule has a buffer local variable called
+    "display-direction".  If this variable is set to nil (this is the
+    default), the lines begin from the left edge of the screen.  On
+    the other hand, if display-direction is non-nil, the lines are
+    aligned to the right and texts are written from right to left.
+
+    If you are in visual-mode, the value of display-direction is
+    reflected in mode-line: if it is nil "L2R" is displayed; if it is
+    non-nil "R2L" is displayed.  In visual-mode, you can set
+    display-direction to nil by typing 'C-c <', and to t by typing
+    'C-c >'.
+
+    If you read a file (C-x C-f) which has the extension ".l2r", the
+    buffer automatically goes in visual-mode and display-direction is
+    set to nil.  Likewise, if a file has the extension ".r2l", the
+    buffer automatically goes in visual-mode and display-direction is
+    set to t.
+
+
+2. EDITING ARABIC TEXT
+
+2.1 INPUT
+
+    In arabic-mode, you can input Arabic characters and Arabic digits
+    from keyboard.  To input ASCII characters or ASCII digits, you
+    have to exit arabic-mode by hitting C-].  The translation table is
+    given below.  When you are in Arabic-mode, you can see the
+    keyboard layout by C-z.
+
+    Please note that this table is by no means a fixed one --- it is
+    just a quick hack.  Your suggestion on Arabic keyboard layout will
+    be greatly appreciated.
+
+
+	translate table in arabic-mode
+	------------------------------
+	"	isolated hamza
+	a~	madda above alif
+	a'	hamza above alif
+	w'	hamza above waaw
+	a''	hamza below alif
+	y'	hamza above yaa
+	a	alif
+	b	baa
+	o	taa marbuTa
+	t	taa
+	c	thaa
+	j	jiim
+	H	Haa
+	K	khaa
+	d	daal
+	x	dhaal
+	r	raa
+	z	zaay
+	s	siin
+	/	shiin
+	S	Saad
+	D	Daad
+	T	Taa
+	Z	Zaa
+	`	ayn
+	G	ghayn
+	f	faa
+	q	qaaf
+	k	kaaf
+	l	laam
+	m	miim
+	n	nuun
+	h	haa
+	w	waaw
+	A	alif maqSura
+	y	yaa
+	C	chim (Farsi)
+	g	gaaf (Farsi)
+	p	paa  (Farsi)
+	X	zhaa (Farsi)
+	_	make connection
+	|       cut connection
+
+
+    Appropriate ligature is automatically generated whenever a
+    character is input.  Special ligature of laam + alif will be
+    generated whenever an alif is input on the left of a laam.  If you
+    want to cut the connection between two adjacent Arabic characters,
+    type a `|' (vertical bar) at that point in arabic-mode.  An input
+    of a character preceded by a `|' produces a glyph which is not
+    connected to its right adjacent.  Typing a `_' (underscore)
+    connects the two characters at that point, if possible.
+
+    When display-direction is nil (i.e. lines are aligned to left),
+    the cursor stays at the same position after an Arabic character is
+    inserted. It moves to the right after an Arabic digit or an ASCII
+    character is inserted.
+
+    When display-direction is non-nil (i.e. lines are aligned to
+    right), the cursor moves to the left after an Arabic character is
+    inserted. It stays at the same position after an Arabic digit or
+    an ASCII character is inserted.
+
+
+2.2 DELETION, KILL & YANK
+
+    Use C-d to delete the character under the cursor.  If you are in
+    arabic-mode, the necessary ligature will be re-generated after the
+    character is deleted.
+
+    DEL key behave differently according to the value of
+    display-direction: if the value is nil (aligned to left), it
+    deletes a character on the left of the cursor; if the value is
+    non-nil (aligned to right), it deletes a character on the right of
+    the cursor.  If the display direction and the input character
+    direction are the same, lastly input character can be deleted with
+    DEL key, no matter what the value of display-direction is.
+
+    M-d (arabic-kill-word), M-DEL (arabic-backward-kill-word), C-k
+    (arabic-kill-line) and C-w (arabic-kill-region) remove the
+    specified stretch of string and put it in kill-ring.  M-w
+    (arabic-copy-region-as-kill) also puts the specified stretch of
+    string in kill-ring, but the original text is left unchanged.
+
+    The strings in kill ring can be reinserted in buffer by C-y
+    (arabic-yank) and M-y (arabic-yank-pop).
+
+    Make sure that you are in arabic-mode when you kill or yank
+    something, otherwise ligature is not maintained, or at the worst,
+    unexpected region will be deleted or a garbage string will be
+    inserted in the buffer.
+
+
+2.3 CURSOR MOTION
+
+    The following cursor motion commands are supplied in visual-mode
+    and in arabic-mode to handle bi-directional texts easily.  All
+    these commands accept an additional prefix numeric argument.
+
+
+	key	command name			function
+	-----------------------------------------------------------------
+	C-f	visual-forward-char		move the cursor visually
+						forward by 1 character
+
+	C-b	visual-backward-char		move the cursor visually
+						backward by 1 character
+
+	C-p	visual-previous-line		move the cursor up
+						by 1 line
+
+	C-n	visual-next-line		move the cursor down
+						by 1 line
+
+	C-a	visual-beginning-of-line	move the cursor to the
+						visual beginning of line
+
+	C-e	visual-end-of-line		move the cursor to the
+						visual end of line
+
+	M-f	visual-forward-word		move the cursor visually
+						forward by 1 word
+
+	M-b	visual-backward-word		move the cursor visually
+						backward by 1 word
+
+	M-<	visual-beginning-of-buffer	move the cursor to the
+						visual beginning of buffer
+
+	M->	visual-end-of-buffer		move the cursor to the
+						visual end of buffer
+
+
+    Note that ordinary cursor motion commands (forward-char,
+    backward-char, etc.) behave according to the logical order of the
+    text, whilst the above commands behave according to the visual
+    order.  Compare the difference of the two C-f commands.  (You can
+    exit visual-mode by typing "C-c C-c".)
+
+
+2.4 LR COMMANDS
+
+    Some of you may be confused by the words "forward" and "backward".
+    Here is a summary:
+
+
+		   display-direction	display-direction
+		   is nil		is non-nil
+	-------------------------------------------------
+	forward	        right               left
+
+	backward        left		    right
+
+
+    If you are using arrow keys to move the cursor, you may want to
+    move the cursor to left/right no matter what display-direction is.
+    Likewise, you may want the cursor to be put on the left-most
+    column when you hit C-a, and on the right-most column when you hit
+    C-e.  In such cases, rewrite the key definitions in visual.el and
+    arabic.el with the following commands.  These commands are called
+    "LR commands" because they act according to the absolute direction
+    (left or right) rather than relative direction (forward or
+    backward).
+
+
+	** LR commands in visual-mode **
+
+	command name			function
+	--------------------------------------------------------
+	visual-move-to-left-char	move the cursor to left
+					by one character
+
+	visual-move-to-right-char	move the cursor to right
+					by one character
+
+	visual-move-to-left-word	move the cursor to left
+					by one word
+
+	visual-move-to-right-word	move the cursor to right
+					by one word
+
+	visual-left-end-of-line		move the cursor to the
+					leftmost column
+
+	visual-right-end-of-line	move the cursor to the
+					rightmost column
+
+	visual-delete-left-char		delete the character on
+					the left of visual point
+
+	visual-delete-right-char	delete the character on
+					the right of visual point
+
+	visual-kill-left-word		kill one word on the left
+					of visual point
+
+	visual-kill-right-word		kill one word on the right
+					of visual point
+
+
+	** LR commands in arabic-mode **
+
+	command name			function
+	----------------------------------------------------------
+	arabic-delete-left-char		do visual-delete-left-char
+					and make Arabic ligature
+
+	arabic-delete-right-char	do visual-delete-right-char
+					and make Arabic ligature
+
+	arabic-kill-left-word		do visual-kill-left-word
+					and make Arabic ligature
+
+	arabic-kill-right-word		do visual-kill-right-word
+					and make Arabic ligature
+
+
+3. HARDCOPY
+
+  You can use m2ps to get a hardcopy of a file which contains arabic
+  characters.  See m2ps.1 for detail.  Note that input files to m2ps
+  must be written in *internal* coding system.  To save the content of
+  a buffer, use the following command in Mule:
+
+	C-u C-x C-w _filename_ RET *internal* RET
+
+  Please note that the current version of m2ps does not support r2l
+  printing direction (flushright mode).  If you try to print a file
+  which was created under r2l display direction, it will be printed
+  left-aligned.  Furthermore, you may get wrong word order.
+
+4. LIMITATIONS
+
+   There are many limitations in this release.  We need your help.
+
+4.1 NON-SPACING MARKS IN ARABIC
+
+    Only two non-spacing marks, i.e., madda and hamza, are available
+    in this release.  Any other marks, e.g. fatHa (short 'a'), Damma
+    (short 'u'), kasra (short 'i'), shadda (doubling sign), sukuun (no
+    vowel sign), waSla (joining hamza), etc., cannot be displayed.  It
+    seems that short vowels and waSla are not necessary to write
+    ordinary Arabic text, but shadda is often marked in Arabic
+    printings.  Please let me know if shadda is really indispensable,
+    in that case I will try to implement shadda in some way.
+
+
+4.2 FILE FORMAT
+
+    This package uses its own format (coding system) for file I/O.
+    You cannot read the files saved in other format, e.g., ISO 8859-6,
+    ISO 10646, UNICODE, ArabTeX, xaw, etc.  As a matter of fact, I do
+    not know what format is mostly used in the world to save Arabic
+    texts.  If you have texts saved in certain format and would like
+    to edit them with Mule, please send me the documentation of your
+    format.  I will try to implement file I/O routine for that format.
+
+
+4.3 MISCELLANEOUS LIMITATIONS
+
+    * Tab does not work if display-direction is non-nil.
+
+    * transpose commands and rectangle commands do not work in most cases.
+
+
+5. ADDRESS
+
+    Bug reports and comments should be sent to this mailing list
+    (mule@etl.go.jp) or directly to me (ntakahas@etl.go.jp).  Any
+    kinds of suggestions or demands are greatly appreciated.
+
+
+TAKAHASHI Naoto
+Electrotechnical Laboratory, Japan
+ntakahas@etl.go.jp