1 files changed, 269 insertions, 0 deletions
diff --git a/runtime/doc/farsi.txt b/runtime/doc/farsi.txt
new file mode 100644
index 0000000..493714e
--- /dev/null
+++ b/runtime/doc/farsi.txt
@@ -0,0 +1,269 @@
+*farsi.txt*     For Vim version 8.1.  Last change: 2015 Aug 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*
+-----------
+
+The following files are found in the subdirectories of the '$VIM/farsi/fonts'
+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 Vim with the
+      '-fn far-a01' option.
+
+   +  For Vim within a xterm, start a xterm with the Farsi fonts (e.g.
+      kterm -fn far-a01).  Then start 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 Vim with the -F option (e.g. vim -F ...).
+
+   + Use the 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 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 cannot redo the last changes (using '.') after
+   entering numbers.
+
+o  While in left-to-right mode 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 command mode there is no support for entering numbers from left
+   to right and also for the sake of flexibility the keymapping logic is
+   restricted.
+
+o  Under the X Window environment, if you want to run 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:noet:ft=help:norl: