vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

arabic.txt (12203B)


      1 *arabic.txt*	For Vim version 9.2.  Last change: 2026 Feb 14
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Nadim Shaikli
      5 
      6 
      7 Arabic Language support (options & mappings) for Vim		*Arabic*
      8 
      9 
     10 								*E800*
     11 In order to use right-to-left and Arabic mapping support, it is
     12 necessary to compile Vim with the |+arabic| feature.
     13 
     14 These functions have been created by Nadim Shaikli <nadim-at-arabeyes.org>
     15 
     16 It is best to view this file with these settings within Vim's GUI: >
     17 
     18 	:set encoding=utf-8
     19 	:set arabicshape
     20 
     21 
     22 Introduction
     23 ------------
     24 Arabic is a rather demanding language in which a number of special
     25 features are required.	Characters are right-to-left oriented and
     26 ought to appear as such on the screen (i.e. from right to left).
     27 Arabic also requires shaping of its characters, meaning the same
     28 character has a different visual form based on its relative location
     29 within a word (initial, medial, final or stand-alone).	Arabic also
     30 requires two different forms of combining and the ability, in
     31 certain instances, to either superimpose up to two characters on top
     32 of another (composing) or the actual substitution of two characters
     33 into one (combining).  Lastly, to display Arabic properly one will
     34 require not only ISO-8859-6 (U+0600-U+06FF) fonts, but will also
     35 require Presentation Form-B (U+FE70-U+FEFF) fonts both of which are
     36 subsets within a so-called ISO-10646-1 font.
     37 
     38 The commands, prompts and help files are not in Arabic, therefore
     39 the user interface remains the standard Vi interface.
     40 
     41 
     42 Highlights
     43 ----------
     44 o  Editing left-to-right files as in the original Vim hasn't changed.
     45 
     46 o  Viewing and editing files in right-to-left windows.	 File
     47    orientation is per window, so it is possible to view the same
     48    file in right-to-left and left-to-right modes, simultaneously.
     49 
     50 o  No special terminal with right-to-left capabilities is required.
     51    The right-to-left changes are completely hardware independent.
     52    Only Arabic fonts are necessary.
     53 
     54 o  Compatible with the original Vim.   Almost all features work in
     55    right-to-left mode (there are liable to be bugs).
     56 
     57 o  Changing keyboard mapping and reverse insert modes using a single
     58    command.
     59 
     60 o  Toggling complete Arabic support via a single command.
     61 
     62 o  While in Arabic mode, numbers are entered from left to right.  Upon
     63    entering a none number character, that character will be inserted
     64    just into the left of the last number.
     65 
     66 o  Arabic keymapping on the command line in reverse insert mode.
     67 
     68 o  Proper Bidirectional functionality is possible given Vim is
     69    started within a Bidi capable terminal emulator.
     70 
     71 
     72 Arabic Fonts						*arabicfonts*
     73 ------------
     74 
     75 Vim requires monospaced fonts of which there are many out there.
     76 Arabic requires ISO-8859-6 as well as Presentation Form-B fonts
     77 (without Form-B, Arabic will _NOT_ be usable).	It is highly
     78 recommended that users search for so-called 'ISO-10646-1' fonts.
     79 Do an Internet search or check www.arabeyes.org for further
     80 info on where to obtain the necessary Arabic fonts.
     81 
     82 
     83 Font Installation
     84 -----------------
     85 
     86 o  Installation of fonts for X Window systems (Unix/Linux)
     87 
     88    Depending on your system, copy your_ARABIC_FONT file into a
     89    directory of your choice.  Change to the directory containing
     90    the Arabic fonts and execute the following commands:
     91 
     92      %	mkfontdir
     93      %	xset +fp path_name_of_arabic_fonts_directory
     94 
     95 
     96 Usage
     97 -----
     98 Prior to the actual usage of Arabic within Vim, a number of settings
     99 need to be accounted for and invoked.
    100 
    101 o  Setting the Arabic fonts
    102 
    103    +  For Vim GUI set the 'guifont' to your_ARABIC_FONT.  This is done
    104       by entering the following command in the Vim window.
    105 >
    106 		:set guifont=your_ARABIC_FONT
    107 <
    108       NOTE: the string 'your_ARABIC_FONT' is used to denote a complete
    109 	    font name akin to that used in Linux/Unix systems.
    110 	    (e.g. -misc-fixed-medium-r-normal--20-200-75-75-c-100-iso10646-1)
    111 
    112       You can append the 'guifont' set command to your .vimrc file
    113       in order to get the same above noted results.  In other words,
    114       you can include ':set guifont=your_ARABIC_FONT' to your .vimrc
    115       file.
    116 
    117    +  Under the X Window environment, you can also start Vim with
    118       '-fn your_ARABIC_FONT' option.
    119 
    120 o  Setting the appropriate character Encoding
    121    To enable the correct Arabic encoding the following command needs
    122    to be appended,
    123 >
    124 		:set encoding=utf-8
    125 <
    126    to your .vimrc file (entering the command manually into your Vim
    127    window is highly discouraged).  In short, include ':set
    128    encoding=utf-8' to your .vimrc file.
    129 
    130    Attempts to use Arabic without UTF-8 will result the following
    131    warning message,
    132 
    133 								*W17*  >
    134      Arabic requires UTF-8, do ':set encoding=utf-8'
    135 
    136 o  Enable Arabic settings [short-cut]
    137 
    138    In order to simplify and streamline things, you can either invoke
    139    Vim with the command-line option,
    140 
    141      % vim -A my_utf8_arabic_file ...
    142 
    143    or enable 'arabic' via the following command within Vim
    144 >
    145 		:set arabic
    146 <
    147    The two above noted possible invocations are the preferred manner
    148    in which users are instructed to proceed.  Barring an enabled 'termbidi'
    149    setting, both command options:
    150 
    151      1. set the appropriate keymap
    152      2. enable the deletion of a single combined pair character
    153      3. enable rightleft    mode
    154      4. enable rightleftcmd mode (affecting the command-line)
    155      5. enable arabicshape  mode (do visual character alterations)
    156 
    157    You may also append the command to your .vimrc file and simply
    158    include ':set arabic' to it.
    159 
    160    You are also capable of disabling Arabic support via
    161 >
    162 		:set noarabic
    163 <
    164    which resets everything that the command had enabled without touching
    165    the global settings as they could affect other possible open buffers.
    166    In short the 'noarabic' command,
    167 
    168      1. resets to the alternate keymap
    169      2. disables the deletion of a single combined pair character
    170      3. disables rightleft mode
    171 
    172    NOTE: the 'arabic' command takes into consideration 'termbidi' for
    173 	 possible external bi-directional (bidi) support from the
    174 	 terminal ("mlterm" for instance offers such support).
    175 	 'termbidi', if available, is superior to rightleft support
    176 	 and its support is preferred due to its level of offerings.
    177 	 'arabic' when 'termbidi' is enabled only sets the keymap.
    178 
    179 	 For vertical window isolation while setting 'termbidi' an LTR
    180 	 vertical separator like "l" or "𝖨" may be used.  It may also be
    181 	 hidden by changing its color to the foreground color: >
    182 		:set fillchars=vert:l
    183 		:hi VertSplit ctermbg=White
    184 <	Note that this is a workaround, not a proper solution.
    185 
    186    If, on the other hand, you'd like to be verbose and explicit and
    187    are opting not to use the 'arabic' short-cut command, here's what
    188    is needed (i.e. if you use ':set arabic' you can skip this section) -
    189 
    190    +  Arabic Keymapping Activation
    191 
    192       To activate the Arabic keymap (i.e. to remap your English/Latin
    193       keyboard to look-n-feel like a standard Arabic one), set the
    194       'keymap' option to "arabic".  This is done by entering
    195 >
    196 		:set keymap=arabic
    197 <
    198       in your Vim window.  You can also append the 'keymap' set command to
    199       your .vimrc file.  In other words, you can include ':set keymap=arabic'
    200       to your .vimrc file.
    201 
    202       To turn toggle (or switch) your keymapping between Arabic and the
    203       default mapping (English), it is advised that users use the 'CTRL-^'
    204       key press while in insert (or add/replace) mode.	The command-line
    205       will display your current mapping by displaying an "Arabic" string
    206       next to your insertion mode (e.g. -- INSERT Arabic --) indicating
    207       your current keymap.
    208 
    209    +  Arabic deletion of a combined pair character
    210 
    211       By default Vim has the 'delcombine' option disabled.  This option
    212       allows the deletion of ALEF in a LAM_ALEF (LAA) combined character
    213       and still retain the LAM (i.e. it reverts to treating the combined
    214       character as its natural two characters form -- this also pertains
    215       to harakat and their combined forms).  You can enable this option
    216       by entering
    217 >
    218 		:set delcombine
    219 <
    220       in our Vim window.  You can also append the 'delcombine' set command
    221       to your .vimrc file.  In other words, you can include ':set delcombine'
    222       to your .vimrc file.
    223 
    224    +  Arabic right-to-left Mode
    225 
    226       By default Vim starts in Left-to-right mode.  'rightleft' is the
    227       command that allows one to alter a window's orientation - that can
    228       be accomplished via,
    229 
    230       - Toggling between left-to-right and right-to-left modes is
    231 	accomplished through ':set rightleft' and ':set norightleft'.
    232 
    233       - While in Left-to-right mode, enter ':set rl' in the command line
    234 	('rl' is the abbreviation for rightleft).
    235 
    236       - Put the ':set rl' line in your '.vimrc' file to start Vim in
    237 	right-to-left mode permanently.
    238 
    239    +  Arabic right-to-left command-line Mode
    240 
    241       For certain commands the editing can be done in right-to-left mode.
    242       Currently this is only applicable to search commands.
    243 
    244       This is controlled with the 'rightleftcmd' option.  The default is
    245       "search", which means that windows in which 'rightleft' is set will
    246       edit search commands in right-left mode.	To disable this behavior,
    247 >
    248 		:set rightleftcmd=
    249 <
    250       To enable right-left editing of search commands again,
    251 >
    252 		:set rightleftcmd&
    253 <
    254    +  Arabic Shaping Mode
    255 
    256       To activate the required visual characters alterations (shaping,
    257       composing, combining) which the Arabic language requires, enable
    258       the 'arabicshape' command.  This is done by entering
    259 >
    260 		:set arabicshape
    261 <
    262       in our Vim window.  You can also append the 'arabicshape' set
    263       command to your .vimrc file.  In other words, you can include
    264       ':set arabicshape' to your .vimrc file.
    265 
    266 
    267 Keymap/Keyboard						*arabickeymap*
    268 ---------------
    269 
    270 The character/letter encoding used in Vim is the standard UTF-8.
    271 It is widely discouraged that any other encoding be used or even
    272 attempted.
    273 
    274 Note: UTF-8 is an all encompassing encoding and as such is
    275       the only supported (and encouraged) encoding with
    276       regard to Arabic (all other proprietary encodings
    277       should be discouraged and frowned upon).
    278 
    279 o  Keyboard
    280 
    281    +  CTRL-^ in insert/replace mode toggles between Arabic/Latin mode
    282 
    283    +  Keyboard mapping is based on the Microsoft's Arabic keymap (the
    284       de facto standard in the Arab world):
    285 
    286   +---------------------------------------------------------------------+
    287   |!   |@   |#   |$   |%   |^   |&   |*   |(   |)   |_   |+   ||   |~  ّ |
    288   |1 ١ |2 ٢ |3 ٣ |4 ٤ |5 ٥ |6 ٦ |7 ٧ |8 ٨ |9 ٩ |0 ٠ |-   |=   |\   |` ذ |
    289   +---------------------------------------------------------------------+
    290        |Q  َ |W  ً |E  ُ |R  ٌ |T لإ |Y إ |U ` |I ÷ |O x |P ؛ |{ < |} > |
    291        |q ض |w ص |e ث |r ق |t ف |y غ |u ع |i ه |o خ |p ح |[ ج |] د |
    292        +-----------------------------------------------------------+
    293 	 |A  ِ |S  ٍ |D [ |F ] |G لأ |H أ |J ـ |K ، |L / |:   |"   |
    294 	 |a ش |s س |d ي |f ب |g ل |h ا |j ت |k ن |l م |; ك |' ط |
    295 	 +------------------------------------------------------+
    296 	   |Z ~ |X  ْ |C { |V } |B لآ |N آ |M ' |< , |> . |? ؟ |
    297 	   |z ئ |x ء |c ؤ |v ر |b لا |n ى |m ة |, و |. ز |/ ظ |
    298 	   +-------------------------------------------------+
    299 
    300 Restrictions
    301 ------------
    302 
    303 o  Vim in its GUI form does not currently support Bi-directionality
    304    (i.e. the ability to see both Arabic and Latin intermixed within
    305    the same line).
    306 
    307 
    308 Known Bugs
    309 ----------
    310 
    311 There is one known minor bug,
    312 
    313  1. If you insert a haraka (e.g. Fatha (U+064E)) after a LAM (U+0644)
    314     and then insert an ALEF (U+0627), the appropriate combining will
    315     not happen due to the sandwiched haraka resulting in something
    316     that will NOT be displayed correctly.
    317 
    318     WORK-AROUND: Don't include harakats between LAM and ALEF combos.
    319 		 In general, don't anticipate to see correct visual
    320 		 representation with regard to harakats and LAM+ALEF
    321 		 combined characters (even those entered after both
    322 		 characters).  The problem noted is strictly a visual
    323 		 one, meaning saving such a file will contain all the
    324 		 appropriate info/encodings - nothing is lost.
    325 
    326 No other bugs are known to exist.
    327 
    328  vim:tw=78:ts=8:noet:ft=help:norl: