| *arabic.txt* For Vim version 7.4. Last change: 2010 Nov 13 |
| |
| |
| VIM REFERENCE MANUAL by Nadim Shaikli |
| |
| |
| Arabic Language support (options & mappings) for Vim *Arabic* |
| |
| {Vi does not have any of these commands} |
| |
| *E800* |
| In order to use right-to-left and Arabic mapping support, it is |
| necessary to compile VIM with the |+arabic| feature. |
| |
| These functions have been created by Nadim Shaikli <nadim-at-arabeyes.org> |
| |
| It is best to view this file with these settings within VIM's GUI: > |
| |
| :set encoding=utf-8 |
| :set arabicshape |
| |
| |
| Introduction |
| ------------ |
| Arabic is a rather demanding language in which a number of special |
| features are required. Characters are right-to-left oriented and |
| ought to appear as such on the screen (i.e. from right to left). |
| Arabic also requires shaping of its characters, meaning the same |
| character has a different visual form based on its relative location |
| within a word (initial, medial, final or stand-alone). Arabic also |
| requires two different forms of combining and the ability, in |
| certain instances, to either superimpose up to two characters on top |
| of another (composing) or the actual substitution of two characters |
| into one (combining). Lastly, to display Arabic properly one will |
| require not only ISO-8859-6 (U+0600-U+06FF) fonts, but will also |
| require Presentation Form-B (U+FE70-U+FEFF) fonts both of which are |
| subsets within a so-called ISO-10646-1 font. |
| |
| The commands, prompts and help files are not in Arabic, therefore |
| the user interface remains the standard Vi interface. |
| |
| |
| Highlights |
| ---------- |
| o Editing left-to-right files as in the original VIM hasn't changed. |
| |
| o Viewing and editing files in right-to-left windows. File |
| orientation is per window, so it is possible to view the same |
| file in right-to-left and left-to-right modes, simultaneously. |
| |
| o No special terminal with right-to-left capabilities is required. |
| The right-to-left changes are completely hardware independent. |
| Only Arabic fonts are necessary. |
| |
| o Compatible with the original VIM. Almost all features work in |
| right-to-left mode (there are liable to be bugs). |
| |
| o Changing keyboard mapping and reverse insert modes using a single |
| command. |
| |
| o Toggling complete Arabic support via a single command. |
| |
| o While in Arabic mode, numbers are entered from left to right. Upon |
| entering a none number character, that character will be inserted |
| just into the left of the last number. |
| |
| o Arabic keymapping on the command line in reverse insert mode. |
| |
| o Proper Bidirectional functionality is possible given VIM is |
| started within a Bidi capable terminal emulator. |
| |
| |
| Arabic Fonts *arabicfonts* |
| ------------ |
| |
| VIM requires monospaced fonts of which there are many out there. |
| Arabic requires ISO-8859-6 as well as Presentation Form-B fonts |
| (without Form-B, Arabic will _NOT_ be usable). It is highly |
| recommended that users search for so-called 'ISO-10646-1' fonts. |
| Do an Internet search or check www.arabeyes.org for further |
| info on where to attain the necessary Arabic fonts. |
| |
| |
| Font Installation |
| ----------------- |
| |
| o Installation of fonts for X Window systems (Unix/Linux) |
| |
| Depending on your system, copy your_ARABIC_FONT file into a |
| directory of your choice. Change to the directory containing |
| the Arabic fonts and execute the following commands: |
| |
| % mkfontdir |
| % xset +fp path_name_of_arabic_fonts_directory |
| |
| |
| Usage |
| ----- |
| Prior to the actual usage of Arabic within VIM, a number of settings |
| need to be accounted for and invoked. |
| |
| o Setting the Arabic fonts |
| |
| + For VIM GUI set the 'guifont' to your_ARABIC_FONT. This is done |
| by entering the following command in the VIM window. |
| > |
| :set guifont=your_ARABIC_FONT |
| < |
| NOTE: the string 'your_ARABIC_FONT' is used to denote a complete |
| font name akin to that used in Linux/Unix systems. |
| (e.g. -misc-fixed-medium-r-normal--20-200-75-75-c-100-iso10646-1) |
| |
| You can append the 'guifont' set command to your .vimrc file |
| in order to get the same above noted results. In other words, |
| you can include ':set guifont=your_ARABIC_FONT' to your .vimrc |
| file. |
| |
| + Under the X Window environment, you can also start VIM with |
| '-fn your_ARABIC_FONT' option. |
| |
| o Setting the appropriate character Encoding |
| To enable the correct Arabic encoding the following command needs |
| to be appended, |
| > |
| :set encoding=utf-8 |
| < |
| to your .vimrc file (entering the command manually into you VIM |
| window is highly discouraged). In short, include ':set |
| encoding=utf-8' to your .vimrc file. |
| |
| Attempts to use Arabic without UTF-8 will result the following |
| warning message, |
| |
| *W17* > |
| Arabic requires UTF-8, do ':set encoding=utf-8' |
| |
| o Enable Arabic settings [short-cut] |
| |
| In order to simplify and streamline things, you can either invoke |
| VIM with the command-line option, |
| |
| % vim -A my_utf8_arabic_file ... |
| |
| or enable 'arabic' via the following command within VIM |
| > |
| :set arabic |
| < |
| The two above noted possible invocations are the preferred manner |
| in which users are instructed to proceed. Barring an enabled 'termbidi' |
| setting, both command options: |
| |
| 1. set the appropriate keymap |
| 2. enable the deletion of a single combined pair character |
| 3. enable rightleft mode |
| 4. enable rightleftcmd mode (affecting the command-line) |
| 5. enable arabicshape mode (do visual character alterations) |
| |
| You may also append the command to your .vimrc file and simply |
| include ':set arabic' to it. |
| |
| You are also capable of disabling Arabic support via |
| > |
| :set noarabic |
| < |
| which resets everything that the command had enabled without touching |
| the global settings as they could affect other possible open buffers. |
| In short the 'noarabic' command, |
| |
| 1. resets to the alternate keymap |
| 2. disables the deletion of a single combined pair character |
| 3. disables rightleft mode |
| |
| NOTE: the 'arabic' command takes into consideration 'termbidi' for |
| possible external bi-directional (bidi) support from the |
| terminal ("mlterm" for instance offers such support). |
| 'termbidi', if available, is superior to rightleft support |
| and its support is preferred due to its level of offerings. |
| 'arabic' when 'termbidi' is enabled only sets the keymap. |
| |
| If, on the other hand, you'd like to be verbose and explicit and |
| are opting not to use the 'arabic' short-cut command, here's what |
| is needed (i.e. if you use ':set arabic' you can skip this section) - |
| |
| + Arabic Keymapping Activation |
| |
| To activate the Arabic keymap (i.e. to remap your English/Latin |
| keyboard to look-n-feel like a standard Arabic one), set the |
| 'keymap' command to "arabic". This is done by entering |
| > |
| :set keymap=arabic |
| < |
| in your VIM window. You can also append the 'keymap' set command to |
| your .vimrc file. In other words, you can include ':set keymap=arabic' |
| to your .vimrc file. |
| |
| To turn toggle (or switch) your keymapping between Arabic and the |
| default mapping (English), it is advised that users use the 'CTRL-^' |
| key press while in insert (or add/replace) mode. The command-line |
| will display your current mapping by displaying an "Arabic" string |
| next to your insertion mode (e.g. -- INSERT Arabic --) indicating |
| your current keymap. |
| |
| + Arabic deletion of a combined pair character |
| |
| By default VIM has the 'delcombine' option disabled. This option |
| allows the deletion of ALEF in a LAM_ALEF (LAA) combined character |
| and still retain the LAM (i.e. it reverts to treating the combined |
| character as its natural two characters form -- this also pertains |
| to harakat and their combined forms). You can enable this option |
| by entering |
| > |
| :set delcombine |
| < |
| in our VIM window. You can also append the 'delcombine' set command |
| to your .vimrc file. In other words, you can include ':set delcombine' |
| to your .vimrc file. |
| |
| + Arabic right-to-left Mode |
| |
| By default VIM starts in Left-to-right mode. 'rightleft' is the |
| command that allows one to alter a window's orientation - that can |
| be accomplished via, |
| |
| - Toggling between left-to-right and right-to-left modes is |
| accomplished through ':set rightleft' and ':set norightleft'. |
| |
| - While in Left-to-right mode, enter ':set rl' in the command line |
| ('rl' is the abbreviation for rightleft). |
| |
| - Put the ':set rl' line in your '.vimrc' file to start Vim in |
| right-to-left mode permanently. |
| |
| + Arabic right-to-left command-line Mode |
| |
| For certain commands the editing can be done in right-to-left mode. |
| Currently this is only applicable to search commands. |
| |
| This is controlled with the 'rightleftcmd' option. The default is |
| "search", which means that windows in which 'rightleft' is set will |
| edit search commands in right-left mode. To disable this behavior, |
| > |
| :set rightleftcmd= |
| < |
| To enable right-left editing of search commands again, |
| > |
| :set rightleftcmd& |
| < |
| + Arabic Shaping Mode |
| |
| To activate the required visual characters alterations (shaping, |
| composing, combining) which the Arabic language requires, enable |
| the 'arabicshape' command. This is done by entering |
| > |
| :set arabicshape |
| < |
| in our VIM window. You can also append the 'arabicshape' set |
| command to your .vimrc file. In other words, you can include |
| ':set arabicshape' to your .vimrc file. |
| |
| |
| Keymap/Keyboard *arabickeymap* |
| --------------- |
| |
| The character/letter encoding used in VIM is the standard UTF-8. |
| It is widely discouraged that any other encoding be used or even |
| attempted. |
| |
| Note: UTF-8 is an all encompassing encoding and as such is |
| the only supported (and encouraged) encoding with |
| regard to Arabic (all other proprietary encodings |
| should be discouraged and frowned upon). |
| |
| o Keyboard |
| |
| + CTRL-^ in insert/replace mode toggles between Arabic/Latin mode |
| |
| + Keyboard mapping is based on the Microsoft's Arabic keymap (the |
| de facto standard in the Arab world): |
| |
| +---------------------------------------------------------------------+ |
| |! |@ |# |$ |% |^ |& |* |( |) |_ |+ || |~ ّ | |
| |1 ١ |2 ٢ |3 ٣ |4 ٤ |5 ٥ |6 ٦ |7 ٧ |8 ٨ |9 ٩ |0 ٠ |- |= |\ |` ذ | |
| +---------------------------------------------------------------------+ |
| |Q َ |W ً |E ُ |R ٌ |T لإ |Y إ |U ` |I ÷ |O x |P ؛ |{ < |} > | |
| |q ض |w ص |e ث |r ق |t ف |y غ |u ع |i ه |o خ |p ح |[ ج |] د | |
| +-----------------------------------------------------------+ |
| |A ِ |S ٍ |D [ |F ] |G لأ |H أ |J ـ |K ، |L / |: |" | |
| |a ش |s س |d ي |f ب |g ل |h ا |j ت |k ن |l م |; ك |' ط | |
| +------------------------------------------------------+ |
| |Z ~ |X ْ |C { |V } |B لآ |N آ |M ' |< , |> . |? ؟ | |
| |z ئ |x ء |c ؤ |v ر |b لا |n ى |m ة |, و |. ز |/ ظ | |
| +-------------------------------------------------+ |
| |
| Restrictions |
| ------------ |
| |
| o VIM in its GUI form does not currently support Bi-directionality |
| (i.e. the ability to see both Arabic and Latin intermixed within |
| the same line). |
| |
| |
| Known Bugs |
| ---------- |
| |
| There is one known minor bug, |
| |
| 1. If you insert a haraka (e.g. Fatha (U+064E)) after a LAM (U+0644) |
| and then insert an ALEF (U+0627), the appropriate combining will |
| not happen due to the sandwiched haraka resulting in something |
| that will NOT be displayed correctly. |
| |
| WORK-AROUND: Don't include harakats between LAM and ALEF combos. |
| In general, don't anticipate to see correct visual |
| representation with regard to harakats and LAM+ALEF |
| combined characters (even those entered after both |
| characters). The problem noted is strictly a visual |
| one, meaning saving such a file will contain all the |
| appropriate info/encodings - nothing is lost. |
| |
| No other bugs are known to exist. |
| |
| vim:tw=78:ts=8:ft=help:norl: |