1*arabic.txt* For Vim version 8.2. Last change: 2021 Jun 22 2 3 4 VIM REFERENCE MANUAL by Nadim Shaikli 5 6 7Arabic Language support (options & mappings) for Vim *Arabic* 8 9 10 *E800* 11In order to use right-to-left and Arabic mapping support, it is 12necessary to compile Vim with the |+arabic| feature. 13 14These functions have been created by Nadim Shaikli <nadim-at-arabeyes.org> 15 16It is best to view this file with these settings within Vim's GUI: > 17 18 :set encoding=utf-8 19 :set arabicshape 20 21 22Introduction 23------------ 24Arabic is a rather demanding language in which a number of special 25features are required. Characters are right-to-left oriented and 26ought to appear as such on the screen (i.e. from right to left). 27Arabic also requires shaping of its characters, meaning the same 28character has a different visual form based on its relative location 29within a word (initial, medial, final or stand-alone). Arabic also 30requires two different forms of combining and the ability, in 31certain instances, to either superimpose up to two characters on top 32of another (composing) or the actual substitution of two characters 33into one (combining). Lastly, to display Arabic properly one will 34require not only ISO-8859-6 (U+0600-U+06FF) fonts, but will also 35require Presentation Form-B (U+FE70-U+FEFF) fonts both of which are 36subsets within a so-called ISO-10646-1 font. 37 38The commands, prompts and help files are not in Arabic, therefore 39the user interface remains the standard Vi interface. 40 41 42Highlights 43---------- 44o Editing left-to-right files as in the original Vim hasn't changed. 45 46o 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 50o 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 54o Compatible with the original Vim. Almost all features work in 55 right-to-left mode (there are liable to be bugs). 56 57o Changing keyboard mapping and reverse insert modes using a single 58 command. 59 60o Toggling complete Arabic support via a single command. 61 62o 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 66o Arabic keymapping on the command line in reverse insert mode. 67 68o Proper Bidirectional functionality is possible given Vim is 69 started within a Bidi capable terminal emulator. 70 71 72Arabic Fonts *arabicfonts* 73------------ 74 75Vim requires monospaced fonts of which there are many out there. 76Arabic requires ISO-8859-6 as well as Presentation Form-B fonts 77(without Form-B, Arabic will _NOT_ be usable). It is highly 78recommended that users search for so-called 'ISO-10646-1' fonts. 79Do an Internet search or check www.arabeyes.org for further 80info on where to obtain the necessary Arabic fonts. 81 82 83Font Installation 84----------------- 85 86o 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 96Usage 97----- 98Prior to the actual usage of Arabic within Vim, a number of settings 99need to be accounted for and invoked. 100 101o 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 120o 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 136o 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' command 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 267Keymap/Keyboard *arabickeymap* 268--------------- 269 270The character/letter encoding used in Vim is the standard UTF-8. 271It is widely discouraged that any other encoding be used or even 272attempted. 273 274Note: 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 279o 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 300Restrictions 301------------ 302 303o 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 308Known Bugs 309---------- 310 311There 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 326No other bugs are known to exist. 327 328 vim:tw=78:ts=8:noet:ft=help:norl: 329