path: root/Master/texmf-dist/doc/latex/arabtex/arabtex.doc

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 <item> will put a bar over the next <item>;

- \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 <A>, <I>, <U>, or <_a>, <_i>, <_u>.

- As the transliteration is ambiguous, use <T> for <tah marbouta>, 
  <N> for <tanween>, <Y> or <_A> for <alif maqsoura>.

- Short vowels <a>, <i>, <u> need not generally be written except in the 
  following cases: 
  - at the beginning of a word where they generate <alif>, 
  - adjacent to <hamza> where they will influence the carrier, 
  - when the transcription is wanted, 
  - in \fullvocalize mode. 

- <hamza> 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 <hamza>!

- <madda> is generated by a right quote (<hamza>) before <A>: <'A>.

- The "invisible letter" <|> may be inserted in order to break unwanted 
  ligatures and to influence the <hamza> writing. It will not show in the 
  arabic output or in the transcription. 

- <tashdid> is indicated by doubling the appropriate letter.

- The article is always written <al-> (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 (<tatweel>, <kashida>) 
  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 <fatha>, 
  <kasra>, <damma> will be put on the preceding character even if the
  vocalization is off otherwise. If <N> follows the short vowel, the 
  appropriate form of <tanween> will be generated instead. At the 
  beginning of a word, <alif> is assumed as the first character. If the 
  previous word ended with a vowel, <wasla> is generated instead of the 
  vowel indicator. 

- if the following character is a single right quote, a <hamza> mark will 
  be put on the preceding character even if in conflict with the <hamza> 
  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 <sukun> 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 
    <fatha>, <kasra>, <damma>. 
  
  - If <N> follows a short vowel, the corresponding form of <tanween> is 
    generated instead.

  - <_a> will produce a <qur'an alif> accent instead of an explicit 
    <alif> character which is coded <A>. 
  
  - 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, <sukun> will be generated 
    except if a double "sun letter" follows <lam>. 

  - <alif> at the beginning of a word carries <wasla> instead of the vowel 
    indicator if the preceding word ended with a vowel.

\vocalize: as above, but <sukun> and <wasla> 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 <tashdid>, and <'A> always 
generates <madda> on <alif>. After <aN> the silent <alif> character is 
generated if necessary. The silent <alif> may also be explicitly indicated 
by <aNa> or <aNA>, or coded literally as <A> in \novocalize mode. If a 
silent <alif maqsoura> is wanted instead, write <aNY>, <aN_A>, <Y> or <_A>. 
A silent <alif> after <waw> is indicated by <Ua>, <UA> or <Wa>, <WA> (with 
a capital <W>!).


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 <hamza>. 

- a silent <alif> or <alif maqsoura> after <N> (<tanwin>) and <U> is 
  omitted in the transcription. The same happens after <waw> if it is 
  written <W>. 

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 <e> and <o> are mapped to <i> and <u>, the long vowels <E> 
and <O> to <I> and <U>. 

The <izafet> connection may be written literally, which may look awkward 
in the case of <h"'>, or always as <-i> (with hyphen); then the correct 
spelling will be determined from the context. Likewise the <yah-i-wahdat> 
can always be written <-I>. 

The final <yah> 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 <hah>"
,h    the "wavy" <hah> letter
,t    <tah> with a small <ttah> accent
,d    <dal> with a small <ttah> accent
,r    <rah> with a small <ttah> accent
.n    <noon> without a dot (modifies a preceding vowel)
E     <yah bari> in the final position, otherwise mapped to <yah>
O     mapped to <U>

The short vowels <e> and <o> are mapped to <a> and <u>.

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    <tah> with a small loop 
,d    <dal> with a small loop 
,r    <rah> with a small loop 
.n    <noon> with a small loop 
g     <gaf> is written with a small loop instead of a bar
,z    <rah> with one dot above and one below
,s    <sin> with one dot above and one below
e     like <a>, with a <zwarakay> mark if vocalized
e'i   <yah> with <hamza>
E     <yah> with two dots below aligned vertically
Ey    <yah> written with a final stroke
o     mapped to <u>
O     mapped to <U>
w"'   <hamza> on <waw>
h"'   <hamza> on <hah>

The <qur'an alif> accent is not available for Pashto.

The rules for <izafet> and <yah-i-wahdat> 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. <fah> is written with one dot 
below the letter, <qaf> with one dot above the normal letter form of 
<fah>. The three dots of <vah> 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 <yah> 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   <kaf> in final position without a diacritical mark
  .f   <fah> without a dot
  .b   <bah> without a dot
  .n   <noon> without a dot (not available for Pashto)
  Y    <alif maqsoura>, <yah> 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 <c>, <^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 <sukun> and <wasla> 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
--------------------------------------------------------------------------