runtime/doc/arabic.txt

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