Mercurial > vim
annotate runtime/doc/arabic.txt @ 18486:9d887cad7315
Added tag v8.1.2237 for changeset 63ee3c2b140fe1b4801389872a8e47aec19d028b
| author | Bram Moolenaar <Bram@vim.org> |
|---|---|
| date | Thu, 31 Oct 2019 20:00:04 +0100 |
| parents | 0e473e9e70c2 |
| children | af69c9335223 |
| rev | line source |
|---|---|
|
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
14421
diff
changeset
|
1 *arabic.txt* For Vim version 8.1. Last change: 2019 May 05 |
| 7 | 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 | |
| 11473 | 12 necessary to compile Vim with the |+arabic| feature. |
| 7 | 13 |
| 14 These functions have been created by Nadim Shaikli <nadim-at-arabeyes.org> | |
| 15 | |
| 11473 | 16 It is best to view this file with these settings within Vim's GUI: > |
| 7 | 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 | |
| 237 | 26 ought to appear as such on the screen (i.e. from right to left). |
| 7 | 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 ---------- | |
| 11473 | 44 o Editing left-to-right files as in the original Vim hasn't changed. |
| 7 | 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 | |
| 11473 | 54 o Compatible with the original Vim. Almost all features work in |
| 7 | 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 | |
| 237 | 62 o While in Arabic mode, numbers are entered from left to right. Upon |
| 7 | 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 | |
| 11473 | 68 o Proper Bidirectional functionality is possible given Vim is |
| 7 | 69 started within a Bidi capable terminal emulator. |
| 70 | |
| 71 | |
| 72 Arabic Fonts *arabicfonts* | |
| 73 ------------ | |
| 74 | |
| 11473 | 75 Vim requires monospaced fonts of which there are many out there. |
| 7 | 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 attain 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 ----- | |
| 11473 | 98 Prior to the actual usage of Arabic within Vim, a number of settings |
| 7 | 99 need to be accounted for and invoked. |
| 100 | |
| 101 o Setting the Arabic fonts | |
| 102 | |
| 11473 | 103 + For Vim GUI set the 'guifont' to your_ARABIC_FONT. This is done |
| 104 by entering the following command in the Vim window. | |
| 7 | 105 > |
| 106 :set guifont=your_ARABIC_FONT | |
| 107 < | |
| 108 NOTE: the string 'your_ARABIC_FONT' is used to denote a complete | |
| 237 | 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) | |
| 7 | 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 | |
| 11473 | 117 + Under the X Window environment, you can also start Vim with |
| 7 | 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 < | |
| 11473 | 126 to your .vimrc file (entering the command manually into you Vim |
| 7 | 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 | |
| 11473 | 139 Vim with the command-line option, |
| 7 | 140 |
| 141 % vim -A my_utf8_arabic_file ... | |
| 142 | |
| 11473 | 143 or enable 'arabic' via the following command within Vim |
| 7 | 144 > |
| 145 :set arabic | |
| 146 < | |
| 147 The two above noted possible invocations are the preferred manner | |
| 2642 | 148 in which users are instructed to proceed. Barring an enabled 'termbidi' |
| 7 | 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 If, on the other hand, you'd like to be verbose and explicit and | |
| 180 are opting not to use the 'arabic' short-cut command, here's what | |
| 237 | 181 is needed (i.e. if you use ':set arabic' you can skip this section) - |
| 7 | 182 |
| 183 + Arabic Keymapping Activation | |
| 184 | |
| 237 | 185 To activate the Arabic keymap (i.e. to remap your English/Latin |
| 7 | 186 keyboard to look-n-feel like a standard Arabic one), set the |
| 187 'keymap' command to "arabic". This is done by entering | |
| 188 > | |
| 189 :set keymap=arabic | |
| 190 < | |
| 11473 | 191 in your Vim window. You can also append the 'keymap' set command to |
| 7 | 192 your .vimrc file. In other words, you can include ':set keymap=arabic' |
| 193 to your .vimrc file. | |
| 194 | |
| 195 To turn toggle (or switch) your keymapping between Arabic and the | |
| 196 default mapping (English), it is advised that users use the 'CTRL-^' | |
| 197 key press while in insert (or add/replace) mode. The command-line | |
| 198 will display your current mapping by displaying an "Arabic" string | |
| 237 | 199 next to your insertion mode (e.g. -- INSERT Arabic --) indicating |
| 7 | 200 your current keymap. |
| 201 | |
| 202 + Arabic deletion of a combined pair character | |
| 203 | |
| 11473 | 204 By default Vim has the 'delcombine' option disabled. This option |
| 7 | 205 allows the deletion of ALEF in a LAM_ALEF (LAA) combined character |
| 237 | 206 and still retain the LAM (i.e. it reverts to treating the combined |
| 7 | 207 character as its natural two characters form -- this also pertains |
| 208 to harakat and their combined forms). You can enable this option | |
| 209 by entering | |
| 210 > | |
| 211 :set delcombine | |
| 212 < | |
| 11473 | 213 in our Vim window. You can also append the 'delcombine' set command |
| 7 | 214 to your .vimrc file. In other words, you can include ':set delcombine' |
| 215 to your .vimrc file. | |
| 216 | |
| 217 + Arabic right-to-left Mode | |
| 218 | |
| 11473 | 219 By default Vim starts in Left-to-right mode. 'rightleft' is the |
| 7 | 220 command that allows one to alter a window's orientation - that can |
| 221 be accomplished via, | |
| 222 | |
| 223 - Toggling between left-to-right and right-to-left modes is | |
| 224 accomplished through ':set rightleft' and ':set norightleft'. | |
| 225 | |
| 226 - While in Left-to-right mode, enter ':set rl' in the command line | |
| 227 ('rl' is the abbreviation for rightleft). | |
| 228 | |
| 237 | 229 - Put the ':set rl' line in your '.vimrc' file to start Vim in |
| 7 | 230 right-to-left mode permanently. |
| 231 | |
| 232 + Arabic right-to-left command-line Mode | |
| 233 | |
| 234 For certain commands the editing can be done in right-to-left mode. | |
| 235 Currently this is only applicable to search commands. | |
| 236 | |
| 237 This is controlled with the 'rightleftcmd' option. The default is | |
| 238 "search", which means that windows in which 'rightleft' is set will | |
| 239 edit search commands in right-left mode. To disable this behavior, | |
| 240 > | |
| 241 :set rightleftcmd= | |
| 242 < | |
| 243 To enable right-left editing of search commands again, | |
| 244 > | |
| 245 :set rightleftcmd& | |
| 246 < | |
| 247 + Arabic Shaping Mode | |
| 248 | |
| 249 To activate the required visual characters alterations (shaping, | |
| 250 composing, combining) which the Arabic language requires, enable | |
| 251 the 'arabicshape' command. This is done by entering | |
| 252 > | |
| 253 :set arabicshape | |
| 254 < | |
| 11473 | 255 in our Vim window. You can also append the 'arabicshape' set |
| 7 | 256 command to your .vimrc file. In other words, you can include |
| 257 ':set arabicshape' to your .vimrc file. | |
| 258 | |
| 259 | |
| 260 Keymap/Keyboard *arabickeymap* | |
| 261 --------------- | |
| 262 | |
| 11473 | 263 The character/letter encoding used in Vim is the standard UTF-8. |
| 7 | 264 It is widely discouraged that any other encoding be used or even |
| 265 attempted. | |
| 266 | |
| 267 Note: UTF-8 is an all encompassing encoding and as such is | |
| 268 the only supported (and encouraged) encoding with | |
| 269 regard to Arabic (all other proprietary encodings | |
| 270 should be discouraged and frowned upon). | |
| 271 | |
| 272 o Keyboard | |
| 273 | |
| 274 + CTRL-^ in insert/replace mode toggles between Arabic/Latin mode | |
| 275 | |
| 276 + Keyboard mapping is based on the Microsoft's Arabic keymap (the | |
|
2409
0ca06a92adfb
Add support for horizontal scroll wheel. (Bjorn Winckler)
Bram Moolenaar <bram@vim.org>
parents:
2345
diff
changeset
|
277 de facto standard in the Arab world): |
| 7 | 278 |
| 279 +---------------------------------------------------------------------+ | |
| 280 |! |@ |# |$ |% |^ |& |* |( |) |_ |+ || |~ ّ | | |
| 281 |1 ١ |2 ٢ |3 ٣ |4 ٤ |5 ٥ |6 ٦ |7 ٧ |8 ٨ |9 ٩ |0 ٠ |- |= |\ |` ذ | | |
| 282 +---------------------------------------------------------------------+ | |
| 283 |Q َ |W ً |E ُ |R ٌ |T لإ |Y إ |U ` |I ÷ |O x |P ؛ |{ < |} > | | |
| 284 |q ض |w ص |e ث |r ق |t ف |y غ |u ع |i ه |o خ |p ح |[ ج |] د | | |
| 285 +-----------------------------------------------------------+ | |
| 286 |A ِ |S ٍ |D [ |F ] |G لأ |H أ |J ـ |K ، |L / |: |" | | |
| 287 |a ش |s س |d ي |f ب |g ل |h ا |j ت |k ن |l م |; ك |' ط | | |
| 288 +------------------------------------------------------+ | |
| 289 |Z ~ |X ْ |C { |V } |B لآ |N آ |M ' |< , |> . |? ؟ | | |
| 290 |z ئ |x ء |c ؤ |v ر |b لا |n ى |m ة |, و |. ز |/ ظ | | |
| 291 +-------------------------------------------------+ | |
| 292 | |
| 293 Restrictions | |
| 294 ------------ | |
| 295 | |
| 11473 | 296 o Vim in its GUI form does not currently support Bi-directionality |
| 237 | 297 (i.e. the ability to see both Arabic and Latin intermixed within |
| 7 | 298 the same line). |
| 299 | |
| 300 | |
| 301 Known Bugs | |
| 302 ---------- | |
| 303 | |
| 304 There is one known minor bug, | |
| 305 | |
| 237 | 306 1. If you insert a haraka (e.g. Fatha (U+064E)) after a LAM (U+0644) |
| 7 | 307 and then insert an ALEF (U+0627), the appropriate combining will |
| 308 not happen due to the sandwiched haraka resulting in something | |
| 309 that will NOT be displayed correctly. | |
| 310 | |
| 311 WORK-AROUND: Don't include harakats between LAM and ALEF combos. | |
| 312 In general, don't anticipate to see correct visual | |
| 313 representation with regard to harakats and LAM+ALEF | |
| 314 combined characters (even those entered after both | |
| 315 characters). The problem noted is strictly a visual | |
| 316 one, meaning saving such a file will contain all the | |
| 317 appropriate info/encodings - nothing is lost. | |
| 318 | |
| 319 No other bugs are known to exist. | |
| 320 | |
| 14421 | 321 vim:tw=78:ts=8:noet:ft=help:norl: |