new file mode 100644
--- /dev/null
+++ b/runtime/doc/farsi.txt
@@ -0,0 +1,269 @@
+*farsi.txt*     For Vim version 7.0aa.  Last change: 2002 Oct 29
+
+
+		  VIM REFERENCE MANUAL    by Mortaza Ghassab Shiran
+
+
+Right to Left and Farsi Mapping for Vim		*farsi* *Farsi*
+
+{Vi does not have any of these commands}
+
+						*E27*
+In order to use right-to-left and Farsi mapping support, it is necessary to
+compile Vim with the |+farsi| feature.
+
+These functions have been made by Mortaza G. Shiran <shiran@jps.net>
+
+
+Introduction
+------------
+In right-to-left oriented files the characters appear on the screen from right
+to left.  This kind of file is most useful when writing Farsi documents,
+composing faxes or writing Farsi memos.
+
+The commands, prompts and help files are not in Farsi, therefore the user
+interface remains the standard Vi interface.
+
+
+Highlights
+----------
+o  Editing left-to-right files as in the original Vim, no change.
+
+o  Viewing and editing files in right-to-left windows.   File orientation is
+   per window, so it is possible to view the same file in right-to-left and
+   left-to-right modes, simultaneously.
+
+o  Compatibility to the original Vim.   Almost all features work in
+   right-to-left mode (see bugs below).
+
+o  Changing keyboard mapping and reverse insert modes using a single
+   command.
+
+o  Backing from reverse insert mode to the correct place in the file
+   (if possible).
+
+o  While in Farsi mode, numbers are entered from left to right. Upon entering
+   a none number character, that character will be inserted just into the
+   left of the last number.
+
+o  No special terminal with right-to-left capabilities is required.  The
+   right-to-left changes are completely hardware independent.  Only
+   Farsi font is necessary.
+
+o  Farsi keymapping on the command line in reverse insert mode.
+
+o  Toggling between left-to-right and right-to-left via F8 function key.
+
+o  Toggling between Farsi ISIR-3342 standard encoding and VIM Farsi via F9
+   function key. Since this makes sense only for the text written in
+   right-to-left mode, this function is also supported only in right-to-left
+   mode.
+
+Farsi Fonts					*farsi fonts*
+-----------
+
+If the "extra" archive has been unpacked, the following files are found in the
+subdirectories of the '$VIM/farsi' directory:
+
+   +  far-a01.pcf    X Windows fonts for Unix including Linux systems
+   +  far-a01.bf     X Windows fonts for SunOs
+   +  far-a01.f16    a screen fonts for Unix including Linux systems
+   +  far-a01.fon    a monospaced fonts for Windows NT/95/98
+   +  far-a01.com    a screen fonts for DOS
+
+
+Font Installation
+-----------------
+
+o  Installation of fonts for MS Window systems (NT/95/98)
+
+   From 'Control Panel' folder, start the 'Fonts' program. Then from 'file'
+   menu item select 'Install New Fonts ...'. Browse and select the
+   'far-a01.fon', then follow the installation guide.
+   NOTE: several people have reported that this does not work.  The solution
+   is unknown.
+
+o  Installation of fonts for X Window systems (Unix/Linux)
+
+   Depending on your system, copy far-a01.pcf.Z or far-a01.pcf.gz into a
+   directory of your choice.  Change to the directory containing the Farsi
+   fonts and execute the following commands:
+
+   >  mkfontdir
+   >  xset +fp path_name_of_farsi_fonts_directory
+
+o  Installation of fonts for X Window systems (SunOs)
+
+   Copy far-a01.bf font into a directory of your choice.
+   Change to the directory containing the far-a01.fb fonts and
+   execute the following commands:
+
+   >  fldfamily
+   >  xset +fp path_name_of_fonts_directory
+
+o  Installation of ASCII screen fonts (Unix/Linux)
+
+   For Linux system, copy the far-a01.f16 fonts into /usr/lib/kbd/consolefonts
+   directory and execute the setfont program as "setfont far-a01.f16". For
+   other systems (e.g. SCO Unix), please refer to the fonts installation
+   section of your system administration manuals.
+
+o  Installation of ASCII screen fonts (DOS)
+
+   After system power on, prior to the first use of VIM, upload the Farsi
+   fonts by executing the far-a01.com font uploading program.
+
+
+Usage
+-----
+Prior to starting VIM, the environment in which VIM can run in Farsi mode,
+must be set.  In addition to installation of Farsi fonts, following points
+refer to some of the system environments, which you may need to set:
+Key code mapping, loading graphic card in ASCII screen mode, setting the IO
+driver in 8 bit clean mode ... .
+
+o  Setting the Farsi fonts
+
+   +  For VIM GUI set the 'guifont' to far-a01. This is done by entering
+      ':set guifont=far-a01' in the VIM window.
+
+      You can have 'guifont' set to far-a01 by VIM during the VIM startup
+      by appending the ':set guifont=far-a01' into your .vimrc file
+      (in case of NT/95/98 platforms _vimrc).
+
+      Under the X Window environment, you can also start the VIM with
+      '-fn far-a01' option.
+
+   +  For the VIM within a xterm, start a xterm with the Farsi fonts (e.g.
+      kterm -fn far-a01). Then start the VIM inside the kterm.
+
+   +  For VIM under DOS, prior to the first usage of VIM, upload the Farsi
+      fonts by executing the far-a01.com fonts uploading program.
+
+o  Farsi Keymapping Activation
+
+   To activate the Farsi keymapping, set either 'altkeymap' or 'fkmap'.
+   This is done by entering ':set akm' or ':set fk' in the VIM window.
+   You can have 'altkeymap' or 'fkmap' set as default by appending ':set akm'
+   or ':set fk' in your .vimrc file or _vimrc in case of NT/95/98 platforms.
+
+   To turn off the Farsi keymapping as a default second language keymapping,
+   reset the 'altkeymap' by entering ':set noakm'.
+
+o  right-to-left Farsi Mode
+
+   By default VIM starts in Left-to-right mode. Following are ways to change
+   the window orientation:
+
+   + Start the VIM with -F option (e.g. vim -F ... ).
+
+   + Use F8 function key to toggle between left-to-right and right-to-left.
+
+   + While in Left-to-right mode, enter 'set rl' in the command line ('rl' is
+     the abbreviation for rightleft).
+
+   + Put the 'set rl' line in your '.vimrc' file to start the  VIM in
+     right-to-left mode permanently.
+
+Encoding
+--------
+
+The letter encoding used is the VIM extended ISIR-3342 standard with a built
+in function to convert between VIM extended ISIR-3342 and ISIR-3342 standard.
+
+For document portability reasons, the letter encoding is kept the same across
+different platforms (i.e. UNIX's, NT/95/98, MS DOS, ...).
+
+
+o  Keyboard
+
+   +  CTRL-_ in insert/replace modes toggles between Farsi(akm)/Latin
+      mode as follows:
+
+   +  CTRL-_ moves the cursor to the end of the typed text in edit mode.
+
+   +  CTRL-_ in command mode only toggles keyboard mapping between Farsi(akm)/
+      Latin. The Farsi text is then entered in reverse insert mode.
+
+   +  F8 - Toggles between left-to-right and right-to-left.
+
+   +  F9 - Toggles the encoding between ISIR-3342 standard and VIM extended
+      ISIR-3342 (supported only in right-to-left mode).
+
+   +  Keyboard mapping is based on the Iranian ISIRI-2901 standard.
+      Following table shows the keyboard mapping while Farsi(akm) mode set:
+
+	-------------------------------------
+	`  1  2  3  4  5  6  7  8  9  0  -  =
+	¢  ±  ²  ³  ´  µ  ¶  ·  ¸  ¹  °  ­  ½
+	-------------------------------------
+	~  !  @  #  $  %  ^  &  *  (  )  _  +
+	~  £  §  ®  ¤  ¥  ª  ¬  è  ¨  ©  é  «
+	-------------------------------------
+	q  w  e  r  t  z  u  i  o  p  [  ]
+	Ó  Ò  Æ  Ù  Ø  Õ  Ö  à  Ê  É  Ç  ˆ
+	-------------------------------------
+	Q  W  E  R  T  Z  U  I  O  P  {  }
+	÷  õ  ô  ó  ò  ý  ð  ö  [  ]  {  }
+	-------------------------------------
+	a  s  d  f  g  h  j  k  l  ;  '  \
+	Ñ  Ð  á  Ã  Ü  Á  Å  Þ  Ý  Ú  Û  ë
+	-------------------------------------
+	A  S  D  F  G  H  J  K  L  :  "  |
+	ù  û  þ  ú  ø  À  ü  æ  ç  º  »  ê
+	-------------------------------------
+	<  y  x  c  v  b  n  m  ,  .  /
+	¾  ×  Ô  Î  Í  Ì  Ë  Ä  ß  ¦  ¯
+	-------------------------------------
+	>  Y  X  C  V  B  N  M  <  >  ?
+	¼  ñ  Ô  Ï  Í  ¡  Ë  Â  ¾  ¼  ¿
+	-------------------------------------
+
+Note:
+	¡  stands for Farsi PSP (break without space)
+
+	¢  stands for Farsi PCN (for HAMZE attribute )
+
+Restrictions
+------------
+
+o  In insert/replace mode and fkmap (Farsi mode) set, CTRL-B is not
+   supported.
+
+o  If you change the character mapping between Latin/Farsi, the redo buffer
+   will be reset (emptied). That is, redo is valid and will function (using
+   '.') only within the mode you are in.
+
+o  While numbers are entered in Farsi mode, the redo buffer will be reset
+   (emptied). That is, you can not redo the last changes (using '.') after
+   entering numbers.
+
+o  While in left-to-right and Farsi mode set, CTRL-R is not supported.
+
+o  While in right-to-left mode, the search on 'Latin' pattern does not work,
+   except if you enter the Latin search pattern in reverse.
+
+o  In the command mode, there is no support for entering the numbers from left
+   to right and also for the sake of the flexibility the keymapping logic is
+   restricted.
+
+o  Under X Window environment, if you want to run the VIM within a xterm
+   terminal emulator and Farsi mode set, you need to have an ANSI compatible
+   xterm terminal emulator. This is because the letter codes above 128 decimal
+   have certain meanings in the standard xterm terminal emulator.
+
+   Note: Under X Window environment, VIM GUI works fine in Farsi mode.
+	 This eliminates the need of any xterm terminal emulator.
+
+
+Bugs
+----
+While in insert/replace and Farsi mode set, if you repeatedly change the
+cursor position (via cursor movement) and enter new text and then try to undo
+the last change, the undo will lag one change behind.  But as you continue to
+undo, you will reach the original line of text. You can also use U to undo all
+changes made in the current line.
+
+For more information about the bugs refer to rileft.txt.
+
+ vim:tw=78:ts=8:ft=help:norl: