arabtex.doc 20.11.1993 A r a b T e X Version 3 ======================== ------------------------------------------------------------------------ The introduction below is slightly out of date but may be used as a first start. ------------------------------------------------------------------------ arabtex.doc 05.11.1992 A r a b T e X Version 2 ======================== What is ArabTeX? ================ ArabTeX is a package extending the capabilities of TeX/LaTeX to generate the arabic writing from an ASCII transliteration for texts in several languages using the arabic script. It consists of a TeX macro package and an arabic font in several sizes, presently only available in the Naskhi style. ArabTeX will run with Plain TeX and also with LaTeX; other additions to TeX have not been tried. ArabTeX is primarily intended for generating the arabic writing, but the scientific transcription can be also easily generated. For other languages using the arabic script limited support is available. Installing ArabTeX: =================== The installation procedure is system dependent. You have to install the "nash14" font with its "*.pk" and "*.tfm" files on the font search path of your TeX system, and the "*.sty" files and "arabtex.tex" on the source search path of your system. Possibly you will have to rename the "*.pk" files according to local conventions, and as a last resort you can try to recreate the font from the "*.mf" METAFONT sources. Additional fonts if available are installed analogously. Activating ArabTeX: =================== With Plain TeX, load the ArabTeX macros by "\input arabtex". With LaTeX, include the option "arabtex" in the document header. In both cases several additional files will be loaded automatically. ArabTeX defines several additional commands as indicated below, and also a large number of internal commands which could lead to storage overflow in a small TeX implementation. All internal commands contain an "at" sign <@> in their names and thus should not interfere with any user defined commands (but possibly with TeX extensions we do not know about). With Plain TeX, the arabic font is only available at the normal 14 point size which ought to cooperate well with the "cm" fonts at 10 points. For other sizes, change the "\magnification" or define additional font identifiers yourself. To change the default, inspect "arabtex.tex" and redefine the "\pnash" command accordingly. With LaTeX, the size changing commands will also operate on the arabic font. Input to ArabTeX: ================= After activating ArabTeX, your modified TeX/LaTeX system will recognize the following items: - normal TeX/LaTeX text and commands, - short arabic quotations bracketed by < and >; these must fit on one line of output, and you have to select one of the Arabic writing styles, e.g \setarab, before using this feature. A quotation may also be started with \<. - longer arabic texts bracketed by \begin{arabtext} and \end{arabtext}, called "Arabic Environments" in the sequel. An Arabic Environment consists of one or several paragraphs separated by blank lines or \par commands. Every paragraph and every arabic quotation is a sequence of the following kinds of items, separated by blank spaces or newlines: - isolated (legal) special characters, interpreted as the corresponding arabic special character; - "numbers", character sequences starting with a digit. A "number" will be translated in the normal writing sequence from left to right even if it contains letters and/or special characters; - "arabic quotes", coded as two left quotes or two right quotes each; - "words", character sequences starting with a letter or special character followed by a letter. The (coded) characters of a word will in the output be arranged from right to left. - TeX/LaTeX control sequences WITHOUT parameters. These will be executed immediately. - ArabTeX control sequences with or without parameters. These will be executed immediately. - a sequence of items enclosed in curly braces { and }. The output from the constituents will be arranged from right to left and must fit on one output line. As far as TeX is concerned, this is NO group. This feature may not be nested. Output from all items will be arranged from right to left, lines will be broken as necessary. Inside an Arabic Environment, but NOT in an arabic quotation, you may also have: - short mathematical insertions, bracketed by SINGLE $ signs. They must fit on one output line and are processed as usual; - short non-arabic text quotations, bracketed by < and >. These must fit on one output line and introduce a new level of grouping, so if they contain any TeX/LaTeX assignments the effects of these will be local. Control sequences in an Arabic Environment may be of the following kinds: - ArabTeX option changing commands. These may also be used outside an Arabic Environment and generally have a global effect; - \\ for a new line; - \par (or a blank line) for a new paragraph, \noindent for a new paragraph without indentation (NOT in arabic quotations); - \emphasize will put a bar over the next ; - \setnash, \setnashbf, \setnastaliq font selection commands, see below; - size changing LaTeX commands like \large etc., only if you use LaTeX; - most other TeX/LaTeX commands make no sense in an Arabic Environment. - you MUST NOT nest another LaTeX environment inside an Arabic Environment (except possibly display math which we did not test, and might work); - if you really need to use a control sequence with parameters, define a new TeX macro or enclose the whole construct in curly braces { and }. Font selection: =============== For space economy, only the Naskh font is available by default. With LaTeX, additional fonts can be loaded by the document style options "nashbf" and/or "nastaliq" (when available). Users of Plain TeX can load and define suitable fonts themselves. The following font selection commands are available: - \setnash (default) selects the Naskh font. - \setnashbf selects a bold-face version of Naskh. - \setnastaliq selects the Nastaliq font. If a font is not available or has not been loaded, the corresponding command will select the default font. With LaTeX, the size changing commands will also operate on the additional fonts. Input coding: ============= The ASCII input notation for arabic text is modelled closely after the transliteration standards ISO/R 233 and DIN 31 635. As these standards do not guarantee unique re-transliteration and are also not ASCII compatible, some modifications were necessary. These follow the general rules: - if the transliteration uses a single letter, code that letter; - if the transliteration uses a letter with a diacritical mark, put a special character similar to the diacritical mark BEFORE the letter. Standard arabic and persian characters: --------------------------------------- b bah | d dal | .s ssad | f fah | h hah | ' hamza t tah | _d dhal | .d ddad | q qaf | w waw | N tanween _t thah | r rah | .t ttah | k kaf | y yah | Y alif maqsoura ^g geem | z zay | .z tthah | l lam | g gaf | _A alif maqsoura .h hhah | s seen | ` `ain | m meem | p pah | T tah marbouta _h khah | ^s sheen | .g ghain | n noon | v vah | W waw (see below) Additional characters generally available: ------------------------------------------ c hhah with hamza ^c gim with three dots (below) ,c khah with three dots (above) ^z zay with three dots (above) ~n kaf with three dots (Ottoman) ~l law with a bow accent (Kurdish) ~r rah with two bows (Kurdish) See also "Urdu" and "Pashto" below. Additional coding rules: ------------------------ - For long vowels, use capital letters , , , or <_a>, <_i>, <_u>. - As the transliteration is ambiguous, use for , for , or <_A> for . - Short vowels , , need not generally be written except in the following cases: - at the beginning of a word where they generate , - adjacent to where they will influence the carrier, - when the transcription is wanted, - in \fullvocalize mode. - is denoted by a single RIGHT quote; its carrier will be determined from the context according to the rules for writing arabic words. If that is not wanted, "quote" it (see below). - <`ain> is a single LEFT quote, don't confuse it with ! - is generated by a right quote () before : <'A>. - The "invisible letter" <|> may be inserted in order to break unwanted ligatures and to influence the writing. It will not show in the arabic output or in the transcription. - is indicated by doubling the appropriate letter. - The article is always written (with hyphen!). - Hyphens <-> may be used freely, and generally do not change the writing, but will show up in the transcription. At the beginning and the end of a word they enforce the use of the connection form of the adjacent letter (if it exists), like e.g. in the date <1400 h->. - A double hyphen <--> between two otherwise joining letters will break any ligature and will insert a horizontal stroke (, ) without appearing in the transcription. It may be used repeatedly. Quoting: ======== A double quote <"> will modify the meaning of the following character as follows: - if a short vowel follows, the appropriate diacritical mark , , will be put on the preceding character even if the vocalization is off otherwise. If follows the short vowel, the appropriate form of will be generated instead. At the beginning of a word, is assumed as the first character. If the previous word ended with a vowel, is generated instead of the vowel indicator. - if the following character is a single right quote, a mark will be put on the preceding character even if in conflict with the rules. - if the following character is the "invisible letter" <|>, the connection between the adjacent letters will be broken and a small space inserted. - otherwise: a will be put on the preceding character. The following character will be processed again. The double quote will not show up in the transcription. Ligatures: ========== There is no way to explicitly indicate ligatures as a large number of them are generated automatically. Any unwanted ligature can be suppressed by interposing the invisible letter <|> between the two letters otherwise combined into a ligature. After "\ligsfalse" ligatures in the middle of a word will not normally be produced; for some texts this looks better. You can return to the normal strategy by "\ligstrue". Vocalization: ============= There are three modes of rendering short vowels: \fullvocalize: - every short vowel will generate the corresponding diacritic mark , , . - If follows a short vowel, the corresponding form of is generated instead. - <_a> will produce a accent instead of an explicit character which is coded . - if a long vowel follows a consonant, the corresponding short vowel is implied. The long vowel itself carries no diacritical mark. - if no vowel is given after a consonant, will be generated except if a double "sun letter" follows . - at the beginning of a word carries instead of the vowel indicator if the preceding word ended with a vowel. \vocalize: as above, but and will not be generated except if explicitly indicated by "quoting". \novocalize: no diacritics will be generated except if explicitly asked for by "quoting". In all modes, a double consonant will generate , and <'A> always generates on . After the silent character is generated if necessary. The silent may also be explicitly indicated by or , or coded literally as in \novocalize mode. If a silent is wanted instead, write , , or <_A>. A silent after is indicated by , or , (with a capital !). Transcription: ============== In addition to the arabic writing, the standard scientific transcription may also be obtained from a fully vocalized input text. This is indicated by "\transtrue" and may be switched off again by "\transfalse". If ONLY the transcription is wanted, you can deactivate the arabic writing by "\arabfalse"; it can be reactivated by "\arabtrue". If both modes are active their output will be interleaved line by line. The transcription mode assumes that the input text is in the Arabic language and has been coded according to the rules given above. For words from other languages the transcription might be in error. For Arabic text, the following special cases are handled: - after the article, a double consonant will be assimilated; - an initial vowel will be omitted if the preceding word ended with a vowel. If that is not wanted start with . - a silent or after () and is omitted in the transcription. The same happens after if it is written . For space economy, the transcription module is NOT loaded by default. If you want to use it, add the style option "atrans" with LaTeX; and with Plain TeX, say "\input atrans.sty". Support for other languages: ============================ ArabTeX is primarily intended for writing texts in classical and modern Arabic, but it also provides limited support for several other languages that are customarily written in the arabic alphabet. The vocalization and the transcription cannot generally be expected to be correct, but might work by accident. In order to switch to the conventions for one of these languages, say "\setfarsi", "\seturdu", "\setpashto", "\setmaghribi"; "\setarab" is the default and can also be used to switch back to the arabic conventions. - Farsi, Dari: -------------- All characters needed for writing Farsi are available by default. The short vowels and are mapped to and , the long vowels and to and . The connection may be written literally, which may look awkward in the case of , or always as <-i> (with hyphen); then the correct spelling will be determined from the context. Likewise the can always be written <-I>. The final carries no dots. Farsi uses the Nasta`liq font if available. - Ottoman: see Farsi. ---------- - Kurdish: see Farsi. ---------- - Urdu: ------- The additional characters in Urdu are coded as follows: h always denotes the "two-eyed " ,h the "wavy" letter ,t with a small accent ,d with a small accent ,r with a small accent .n without a dot (modifies a preceding vowel) E in the final position, otherwise mapped to O mapped to The short vowels and are mapped to and . Note: Some of the given codings also occur in Pashto but with a different meaning, see below. Urdu uses the Nasta`liq font if available. - Pashto: --------- The additional characters for Pashto are coded as follows: ,t with a small loop ,d with a small loop ,r with a small loop .n with a small loop g is written with a small loop instead of a bar ,z with one dot above and one below ,s with one dot above and one below e like , with a mark if vocalized e'i with E with two dots below aligned vertically Ey written with a final stroke o mapped to O mapped to w"' on h"' on The accent is not available for Pashto. The rules for and apply. Note: Some of the given codings also occur in Urdu but with a different meaning, see above. For writing some words in the Urdu style, write the command \seturdu and afterwards switch back to the Pashto conventions by \setpashto. - Maghribi: ----------- This is just a different writing convention. is written with one dot below the letter, with one dot above the normal letter form of . The three dots of are put below the letter. Otherwise like Arabic. Miscellaneous features: ======================= - As ArabTeX is slow, it will produce some terminal output while running to indicate it is still alive. If that is not wanted, say "\quiet" or "\tracingarab = 0 " (outside an Arabic Environment). "\tracingarab = 1 " will report arabic paragraphs, a value of 2: arabic lines and insertions, a value of 3 or more: individual items. - Whether in the final position carries dots or not depends on the chosen language convention. You can override this by "\yahdots" and "\yahnodots". - To reproduce erroneous or archaic texts exactly as they are, the following additional codings are available: .k in final position without a diacritical mark .f without a dot .b without a dot .n without a dot (not available for Pashto) Y , without dots in all positions. How to move from Version 1 to Version 2: ======================================== Version 2 is not fully compatible with Version 1; however, moving to the new version should cause little problems, and is recommended as version 1 is no longer supported. Apart from some extensions, most changes were introduced in order to better conform to the transliteration standards, and to have less compatibility problems with TeX and LaTeX. Further versions are expected to be upward compatible if no grave bugs turn up. The main differences between versions 1 and 2 are: - The font size has increased, so the document layout may change. The old font can no more be used. - Some arabic characters are now coded differently: <`ain> is denoted by a left quote, and , <^z>, <^t>, and <.n> denote different characters from what they did before. This was changed in order to better conform to the standard transliteration. - There are a lot more ligatures than before. This normally need not concern the user. - \vocalize will no more generate and except if explicitly indicated by quoting. See \fullvocalize. - Arabic Environments are always bracketed by the new control sequences \begin{arabtext} and \end{arabtext} even if only the transcription is wanted. - Short arabic quotations are now bracketed by \< and > so < has its standard TeX meaning. We recommend converting existent input files to the new notation. If that is impractical in special cases, the LaTeX option "oldarabtex" and/or the command "\oldarabtex" will switch back to most of the old conventions (and problems). This shortcut will probably go away in some future version. Acknowledgments: ================ The development of ArabTeX would not have been possible without the assistance of many people. Apart from my local team, helpful advice came among others from Wolfdietrich Fischer, Ahmed El-Hadi, Abdelsalam Heddaya, Iqbal Khan, Tom Koornwinder, Eberhard Krueger, Asif Lakehsar, Jan Lodder, Richard Lorch, Eberhard Mattes, and Bernd Raichle. I also have to thank the many people who sent bug reports and comments. Please send bug reports, suggestions and inquiries to the author: ================================================================= Prof. Klaus Lagally Institut fuer Informatik Universitaet Stuttgart Breitwiesenstrasse 20-22 D-70565 Stuttgart GERMANY lagally@informatik.uni-stuttgart.de -------------------------------------------------------------------------- Copyright (c) 1990 - 1993, Klaus Lagally --------------------------------------------------------------------------