runtime/doc/farsi.txt - third_party/vim - Git at Google

 *farsi.txt*     For Vim version 7.2c.  Last change: 2005 Mar 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 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:ft=help:norl:
	farsi.txt For Vim version 7.2c. Last change: 2005 Mar 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 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:ft=help:norl: