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