diff options
Diffstat (limited to 'runtime/doc/arabic.txt')
| -rw-r--r-- | runtime/doc/arabic.txt | 328 |
1 files changed, 328 insertions, 0 deletions
diff --git a/runtime/doc/arabic.txt b/runtime/doc/arabic.txt new file mode 100644 index 0000000..ff1cac4 --- /dev/null +++ b/runtime/doc/arabic.txt @@ -0,0 +1,328 @@ +*arabic.txt* For Vim version 9.0. Last change: 2021 Jun 22 + + + VIM REFERENCE MANUAL by Nadim Shaikli + + +Arabic Language support (options & mappings) for Vim *Arabic* + + + *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 obtain 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 your 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. + + For vertical window isolation while setting 'termbidi' an LTR + vertical separator like "l" or "𝖨" may be used. It may also be + hidden by changing its color to the foreground color: > + :set fillchars=vert:l + :hi VertSplit ctermbg=White +< Note that this is a workaround, not a proper solution. + + 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:noet:ft=help:norl: |