summaryrefslogtreecommitdiff
path: root/language/arabic/dad/dad-user-guide.tex
blob: 988557686cc5bac2c724b03e9b81106631d68787 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
%%% ====================================================================
%%%  @LaTeX-file{
%%%     filename        = "dad-user-guide.tex",
%%%     version         = "1.2",
%%%     date            = "2017/05/20",
%%%     author          = "Yannis Haralambous",
%%%     copyright       = "This file is part of the dad package, released
%%%                        under the LPPL."
%%%     keywords        = "TeX, file header,
%%%     supported       = "yes",
%%%     abstract        = "This is the user's guide of the dad
%%%       system for typesetting in the Arabic language.",
%%%  }
%%% ====================================================================
% needs lualatex to be processed
\documentclass[11pt,a4paper]{article}
\usepackage{luatex85}
\pdfmapfile{/hom/yannis/projets/smf/0/smfpdftex.map}
\usepackage{graphicx,color,framed,a4wide}
\usepackage{ifpdf}
%\usepackage[utf8]{inputenc}
\ifpdf
\usepackage[breaklinks,hidelinks]{hyperref}
\usepackage{tikz}
\usetikzlibrary{arrows}
\else 
\usepackage{url}
\fi
\usepackage[colorinlistoftodos]{todonotes}
\usepackage{dad}
\def\hamza{'}%\textsuperscript{\ejective}}
\def\ayn{`}%\textsuperscript{\reveject}}
\usepackage{fontspec}

%%% Start of metadata %%%

\title{User's Guide of \arab{D} (\emph{\d{d}\=ad}),\\ a Simple Arabic Typesetting System\\ for Mixed Latin/Arabic Alphabet Documents\\[12pt]Version 1.2/2017-05-20}

% repeat info for each author.
\author{Yannis Haralambous\thanks{IMT Atlantique,
UMR~CNRS~6285 Lab-STICC,
Technop\^ole Brest Iroise
CS 83818, 29238~Brest~Cedex~3, France, \url{yannis.haralambous@imt-atlantique.fr}}}
%\netaddress{yannis.haralambous (at) telecom-bretagne dot eu}
%\personalURL{http://example.org/~user/}
\date{}
%%% End of metadata %%%


%\newfontfamily\arabicfont[Script=Arabic,Scale=1.2]{Scheherazade-Regular.ttf}
%\newcommand{\textarabic}[1]{\bgroup\textdir TRT\arabicfont #1\egroup}
\begin{document}

\maketitle

\section*{New features of version 1.2}

I added support for Lua\TeX\ 0.95 by including package \verb=luatex85= and by changing \verb=\luatextextdir= into \verb=\textdir=.

\section{Introduction}

\noindent\mbox{\arab{D}} is a package for typesetting Arabic in the simplest possible way. It is particularly well suited for mixed Arabic/Latin documents. ``Simplest possible'' means:
\begin{itemize}
\item it is compatible with all \LaTeX\ style files, since the code is minimal and all the complexity is in the font;
\item input can be done in Unicode or in transliteration, the latter being often the best choice when mixing left-to-right and right-to-left scripts;
\item the only \TeX nical requirement is Lua\TeX, not because of the Lua language (which is not used, for the moment), but because of features that have survived from Lua\TeX's $\Omega$ origins: bidirectionality and use of large fonts (OVF, OFM).
\end{itemize}
Choose Lua\TeX\ as your \TeX\ engine, load the package into your document, and \arab{AhlAaN Us-hlAaN!}, just start writing in Arabic using command \verb=\arab=.

More information about \arab{D} (history, evolution, rationale of technical choices, \TeX nicalities) can be found in \cite{tugboat}.

%\begin{framed}
%\noindent ATTENTION! \textbf{\arab{xTr!}} Because of bugs in Lua\TeX, in some cases appear mysterious blank spaces on the left of the text, word parts are duplicated, and sometimes \TeX\ breaks with an error message \texttt{This can't happen (sub\_disc\_widths).} These errors have been submitted to the Lua\TeX\ team (\url{http://tracker.luatex.org/view.php?id=912&history=1#history}), which will provide the necessary corrections \arab{'in shA| ALLh}.
%\end{framed}

\section{The name}

Thanks to the Internet, search engines, social media, and the like, people are becoming more and more aware of other languages and writing systems. Why not give this package an Arabic name, be it a single letter?

The author has chosen letter \arab{D}, called \emph{\d{d}\=ad}, because Arabic is traditionally called the ``language of the \emph{\d{d}\=ad},'' since this sound was considered as being unique to Arabic.

The reader is probably wondering how to pronounce this letter,technically a ``voiced velarized alveolar stop'' \cite[p.~16]{ryding2014}. Here is how \cite[p.~10]{learn2} describes its pronunciation:

\begin{quotation}
Pronounce the regular sound `d' and you will find that the tip of your tongue will touch in the region of the upper front teeth/gum. Now pronounce the sound again and at the same time depress the \emph{middle} of the tongue. This has the effect of creating a larger space between the tongue and the roof of the mouth and gives the sound produced a distinctive `hollow' characteristic, which also effects the surrounding vowels. It is difficult to find a parallel in English, but the difference between `Sam' and `psalm' (standard English pronunciation) gives a clue. Tense the tongue muscles in pronouncing `psalm' and you are nearly there. Now pronounce the a-vowel of `psalm' before and after `\d{d}', saying `a\d{d}a', keeping the tongue tense, and that's as near as we can get to describing it in print.
\end{quotation}

\section{How to use \arab{D}}

The package provides three PostScript Type~1 fonts (plain,  bold and typewriter), ``real'' fonts (regular TFM) and large virtual fonts (OVF and OFM files). There are also rudimentary FD and STY files, a MAP file, Perl scripts for conversion to (and from) UTF-8, the Perl script which builds the font and finally adjustment files, in case the user wants to change kerning and diacritic placement.

Once the package is installed, to use it just call
\begin{verbatim}
\usepackage{dad}
\end{verbatim}

Notice however that it requires Lua\TeX\ (for change of direction and OVF/OFM compliance).

To typeset in Arabic, one uses the command \verb=\arab= (which is ``long'': paragraph changes are allowed in its argument).

Arabic text can be input in transliteration, as described in Table~\ref{trans} or in Unicode UTF-8 (\S\,\ref{unicode}). 

{\tolerance5000 For example, to obtain \arab{AlkitAb} one would write in transliteration \verb=\arab{=\texttt{AlkitAb}\verb=}= or in Unicode \verb=\arab{=\arabtt{AlkitAb}\verb=}=. By writing \verb=\arabtt{=\texttt{AlkitAb}\verb=}= one obtains the typewriter version \arabtt{AlkitAb} (which is less appealing, but fits quite nicely with the Computer Modern Typewriter font).

}

\begin{table*}[t]
\centering{\renewcommand{\arraystretch}{2}

\caption{Transliteration of \arab{D} system\label{trans}}
\begin{tabular}{|c|c||c|c||c|c||c|c||c|c||c|c|}
\hline
\arab{|}&\texttt{|}&\arab{'A}&\texttt{'A}&\arab{'a}&\texttt{'a}&\arab{'u}&\texttt{'u}&\arab{'i}&\texttt{'i}&\arab{'I}&\texttt{'I}\\
\arab{A}&\texttt{A}&\arab{b}&\texttt{b}&\arab{t*}&\texttt{t*}&\arab{t}&\texttt{t}&\arab{th}&\texttt{th}&\arab{j}&\texttt{j}\\
\arab{H}&\texttt{H}&\arab{x}&\texttt{x}&\arab{d}&\texttt{d}&\arab{dh}&\texttt{dh}&\arab{r}&\texttt{r}&\arab{z}&\texttt{z}\\
\arab{s}&\texttt{s}&\arab{sh}&\texttt{sh}&\arab{S}&\texttt{S}&\arab{D}&\texttt{D}&\arab{T}&\texttt{T}&\arab{Z}&\texttt{Z}\\
\arab{`}&\texttt{`}&\arab{R}&\texttt{R}&\arab{f}&\texttt{f}&\arab{q}&\texttt{q}&\arab{k}&\texttt{k}&\arab{l}&\texttt{l}\\
\arab{m}&\texttt{m}&\arab{n}&\texttt{n}&\arab{h}&\texttt{h}&\arab{U}&\texttt{U}&\arab{I}&\texttt{I}&\arab{Y}&\texttt{Y}\\\hline
\arab{A*}&\texttt{A*}&\arab{^^^^00fbo}&\texttt{o}&\arab{^^^^00fba}&\texttt{a}&\arab{^^^^00fbi}&\texttt{i}&\arab{^^^^00fbu}&\texttt{u}&\arab{^^^^00fbaN}&\texttt{aN}\\
\arab{^^^^00fbiN}&\texttt{iN}&\arab{^^^^00fbuN}&\texttt{uN}&\arab{^^^^00fb+}&\texttt{+}&\arab{^^^^00fb+a}&\texttt{+a}&\arab{^^^^00fb+i}&\texttt{+i}&\arab{^^^^00fb+u}&\texttt{+u}\\
\arab{^^^^00fb+aN}&\texttt{+aN}&\arab{^^^^00fb+iN}&\texttt{+iN}&\arab{^^^^00fb+uN}&\texttt{+uN}&\arab{^^^^00fba*}&\texttt{a*}&\arab{^^^^00fb+a*}&\texttt{+a*}&\arab{LLh}&\texttt{LLh}\\\hline
\arab{p}&\texttt{p}&\arab{g}&\texttt{g}&\arab{C}&\texttt{C}&\arab{J}&\texttt{J}&\arab{e}&\texttt{e}&\arab{v}&\texttt{v}\\\hline
\arab{'b}&\texttt{'b}&\arab{'n}&\texttt{'n}&\arab{'f}&\texttt{'f}&\arab{'q}&\texttt{'q}&\arab{^^^^00fba**}&\texttt{a**}&\arab{^^^^00fb+a**}&\texttt{+a**}\\\hline
\end{tabular}

}
\end{table*}

\clubpenalty10000

\subsection{Rationale of the transliteration}

Here are the rules of the proposed transliteration: 
\begin{enumerate}
\item pharyngeal \arabttexample{H}, emphatic \arabttexample{S}, \arabttexample{D}, \arabttexample{T},
\arabttexample{Z} and velar \arabttexample{R} are \emph{uppercased}---do not confuse them with glottal \arabttexample{h}, non-emphatic \arabttexample{s}, \arabttexample{d}, \arabttexample{t}, \arabttexample{z}, and alveolar \arabttexample{r};
\item long vowels (\arabttexample{A}, \arabttexample{U}, \arabttexample{Y}) and
\emph{\hamza$\!$alif maq\d s\=ura} (\arabttexample{I}) are also
\emph{uppercased};

\item some consonants are modified by adding a character \texttt{h} (\arabttexample{dh}, \arabttexample{th}, \arabttexample{sh});

\item the stand-alone \emph{hamza} is obtained by a vertical bar \texttt{|} and letter ayn by a grave accent (which, in legacy \TeX\ produces an inverted curly apostrophe, which is sometimes used to transliterate this letter);

\item to avoid confusion between pairs of letters and letters obtained by digraphs, one has to use a dash to separate characters: compare \arabttexample{s-h} and \arabttexample{sh}, or \arabttexample{t-h} and \arabttexample{th};

\item more generally, the dash plays the r\^ole of \emph{zero-width joiner}\footnote{Except for the case of letter \arabttexample{dh} which is biform and hence is not connected with the following letter. By writing \arabttexample{d-h} one obtains letters \emph{d\=al} and \emph{h\=a\hamza}, but the \emph{h\=a\hamza} is not in medial form, as it would be in any other case when preceded by a dash.}: when writing \arabttexample{-b}, the letter \emph{b\=a\hamza} will be in final form; \arabttexample{b-} and \arabttexample{-b-} will produce initial and middle letters, provided of course the letter is quadriform (as is letter \emph{b\=a\hamza} in this example). This is very useful when describing grammar rules, to signify that a letter (or letter group) is an affix;

\item the dash can also be used to reestablish contextual forms when combined with \TeX\ commands, for example, to colorize letters. There is only one special case: when we want to colorize a letter of an isolated ligature \arab{lA}, instead of a dash, we use digit \texttt{4}. For the final ligature \arab{-lA} it will be a digit \texttt{5}. Example: to colorize the \emph{l\=am}s of \arab{t-\textcolor{red}{-l5-}-A5\textcolor{red}{l4-}-A4}, write
\begin{verbatim}
\arab{t-\textcolor{red}{-l5-}-A5%
\textcolor{red}{l4-}-A4}
\end{verbatim}

%\def\kesh{\leavevmode\leaders\hrule height\fontdimen8\hfill\kern0pt}

\item finally, there is yet another use of the dash: when doubled, it produces a kashida
%tatweel
%(also known as ``kashida'') 
stroke: compare \arabttexample{lYl} and \arabttexample{l--Y--l}. There is also a \verb=\kesh= command for extensible kashida (it is equivalent to a \verb=\hrulefill= using the default rule thickness font dimension \verb=\fontdimen8=): \verb=l--\kesh--Y--\kesh--l.= will produce:

\noindent\arab{l--\kesh--Y--\kesh--l.}

\item some digraphs start with an apostrophe: it is the case of \emph{hamza}-carriers \arabttexample{'a}, \arabttexample{'i}, \arabttexample{'u}, \arabttexample{'I}, \arabttexample{'A} but also of undotted letters \emph{b\=a\hamza} \arabttexample{'b}, \emph{n\=un} \arabttexample{'n}, \emph{f\=a\hamza} \arabttexample{'f} and \emph{q\=af} \arabttexample{'q};

\item other digraphs end with one or more asterisks: the most frequent one is the \emph{t\=a\hamza\ marbu\d{t}a} \arabttexample{t*} (which can be used also in initial and medial, and then becomes a regular \emph{t\=a\hamza}). The asterisk is also used for the \emph{Ua\d{s}la} (which is only placed on the \emph{\hamza$\!$alif}) \arabttexample{A*} as well as for the vertical \emph{fat\d{h}a} (as in \arabttexample{ha*dhA}) and the \emph{madda}. The latter is normally used only on the \emph{\hamza$\!$alif} (\arabttexample{'A}) but can be found also in the notorious \emph{muqa\d t\d ta\ayn\=at} in the Koran, as in \arab{`a**sa**qa**} (\emph{Koran} 42:2) or \arab{ka**ha*Ya*`a**Sa**} (\emph{Koran} 19:1)---sometimes it is even combined with a \emph{\v{s}adda} (as in \arab{Ala**m+a**Sa**}, \emph{Koran} 7:1 and \cite[p.~111]{syed} for the \emph{\v{s}adda});

\item there is a special transcription for the ligature \arabttexample{LLh} used for the \arab{اسم الجلالة} ``noun of majesty,'' which is the name of God \arab{ALLh}: in this case---and in this case only---an uppercase \texttt{L} is used. The reason is that we wish to avoid ambiguity with other uses of the trigram \emph{l\=am}-\emph{l\=am}-\emph{h\=a\hamza}, for example \arab{YuDolilohu} (\emph{Koran} 6:39) where we encounter letters \arab{llh} but not with the meaning ``God.'' Contrarily to other systems, the \arab{LLh} ligature is available also in final form (for \arab{faLiLhi} which occurs six times in the Koran, for example  \emph{Koran} 6:149), and it is possible to add diacritics to its first glyph (as in \arab{UaLiLhi}, \emph{Koran} 2:115 or \arab{L+iLhi}, \emph{Koran} 2:165).
\end{enumerate}

\begin{figure*}[p]
\arab{\begin{center}
\textbf{rbA`YAt AlxYAm}

\medskip

\begin{minipage}{10cm}
sm`t SUtA hAtfA fY AlsH--\kesh--r n--\kesh--AdI mn AlRYb rfAt Albsh--\kesh--r\\
hbUA Aml'aUA k'as AlmnI qb--\kesh--l 'an tml'a k--\kesh--'as Al`m--\kesh--r kf Alq--\kesh--dr\\
lA tshRl AlbAl bmADY Alzm--\kesh--An UlA b--\kesh--'At Al`Y--\kesh--sh qb--\kesh--l Al'aUAn\\
U'aR--\kesh--nm mn AlHAD--\kesh--r ldhAt--\kesh--h flYs f--\kesh--Y Tb--\kesh--` AllYAl--\kesh--Y Al'am--\kesh--An\\
Rd bZhr AlRYb UAlYUm l--\kesh--Y Ukm YxYb AlZ--\kesh--n f--\kesh--Y Almqb--\kesh--l\\
Uls--\kesh--t bAlRAf--\kesh--l Ht--\kesh--I 'arI jm--\kesh--Al dnY--\kesh--AY U lA Ajtl--\kesh--I\\
Alqlb qd 'aDnAh `shq Aljm--\kesh--Al UAlS--\kesh--dr q--\kesh--d D--\kesh--Aq bm--\kesh--A lA Yq--\kesh--Al\\
YA rb hl YrDYk hdhA AlZlm--\kesh--A UAlm--\kesh--A| Yns--\kesh--Ab 'am--\kesh--Am--\kesh--Y zlAl\\
'aUlI bhdhA Alqlb 'an Yxfq--\kesh--A U fY RrAm AlH--\kesh--b 'an YHtrq--\kesh--A\\
mA 'aDY` AlYUm AldhY m--\kesh--r b--\kesh--Y mn RYr 'an 'ahUI U 'an 'a`shq--\kesh--A\\
'afq xfYf AlZl hdhA AlsH--\kesh--r n--\kesh--AdI d` Aln--\kesh--Um Un--\kesh--AR AlUt--\kesh--r\\
fm--\kesh--A 'aT--\kesh--Al Aln--\kesh--Um `m--\kesh--rA UlA qSr mn Al'a`mAr TUl Als-h--\kesh--r\\
fk--\kesh--m tUl--\kesh--I AllY--\kesh--l b`--\kesh--d Alnh--\kesh--Ar UT--\kesh--Al bAl'anj--\kesh--m h--\kesh--dhA Alm--\kesh--dAr\\
f'amsh AlhUYnt* 'an hdhA Alc--\kesh--rI m--\kesh--n 'a`Y--\kesh--n sAH--\kesh--rt* AlAH--\kesh--UrAr\\
lA tUHsh Alnfs bxUf AlZn--\kesh--Un U'aRnm mn AlHADr 'amn AlYqY--\kesh--n\\
fqd tsAUI fY AlcrI rAH--\kesh--l RdA UmAD mn AlUf AlsnY--\kesh--n\\
ATf'I lZI Alqlb bshhd AlrD--\kesh--Ab f'inm--\kesh--A Al'aY--\kesh--Am mc--\kesh--l AlsH--\kesh--Ab\\
U`Yshn--\kesh--A TY--\kesh--f xY--\kesh--Al fn--\kesh--l HZ--\kesh--k mn--\kesh--h qb--\kesh--l f--\kesh--Ut Alshb--\kesh--Ab\\
lbst cUb Al`Ysh lm Astsh--\kesh--r UH--\kesh--rt fY--\kesh--h bY--\kesh--n sht--\kesh--I Alfk--\kesh--r\\
UsUf 'anDU AlcUb `nY Ul--\kesh--m 'adrk lm--\kesh--AdhA j'I--\kesh--t 'aY--\kesh--n AlmR--\kesh--r\\
YA mn YHAr Alfhm fY qdrt--\kesh--k UtTl--\kesh--b Alnf--\kesh--s Hm--\kesh--I TA`t--\kesh--k\\
Askrn--\kesh--Y Al'ic--\kesh--m U lknn--\kesh--Y SH--\kesh--Ut bAl'am--\kesh--Al f--\kesh--Y rHmt--\kesh--k\\
'in lm 'akn 'axlSt fY TA`t--\kesh--k f'inn--\kesh--Y 'aTm--\kesh--` f--\kesh--Y rHmt--\kesh--k\\
U'inm--\kesh--A Yshf--\kesh--` l--\kesh--Y b'ann--\kesh--Y q--\kesh--d `sh--\kesh--t lA 'ash--\kesh--rk fY UHdt--\kesh--k\\
nxfY `n AlnAs snI Tl`t--\kesh--k f'inn--\kesh--Y 'aTm--\kesh--` f--\kesh--Y rHmt--\kesh--k\\
f'an--\kesh--t mj--\kesh--lAh U'an--\kesh--t Al--\kesh--dhY t--\kesh--rI bdY--\kesh--` AlSn--\kesh--` f--\kesh--Y 'AYt--\kesh--k\\
An tfDl AlqTrt* mn bHrh--\kesh--A ff--\kesh--Y m--\kesh--dAh--\kesh--A mnt-h--\kesh--I 'amrh--\kesh--A\\
tqArb--\kesh--t Y--\kesh--A rb m--\kesh--A bYnn--\kesh--A msAf--\kesh--t* Alb`--\kesh--d `l--\kesh--I qdrh--\kesh--A\\
YA `Alm Al'asrAr `lm AlYq--\kesh--Y--\kesh--n Y--\kesh--A kAsh--\kesh--f AlD--\kesh--r `--\kesh--n AlbA'IsY--\kesh--n\\
Y--\kesh--A qAb--\kesh--l Al'a`--\kesh--dhAr `dn--\kesh--A 'il--\kesh--I Zl--\kesh--k f'aqb--\kesh--l tUb--\kesh--t* AltA'IbY--\kesh--n
\end{minipage}
\end{center}}
\caption{The lyrics of the song \arab{rbA`YAt AlxYAm} (Oum Kalthoum, 1950) \cite{oum}\label{oum}}
\end{figure*}

\begin{figure*}[p]

\kern-2cm

\scriptsize
\begin{verbatim}
\documentclass{article}
\usepackage{dad}
\begin{document}
\arab{
\begin{center}
\textbf{rbA`YAt AlxYAm}

\medskip

\begin{minipage}{10cm}
sm`t SUtA hAtfA fY AlsH--\kesh--r n--\kesh--AdI mn AlRYb rfAt Albsh--\kesh--r\\
hbUA Aml'aUA k'as AlmnI qb--\kesh--l 'an tml'a k--\kesh--'as Al`m--\kesh--r kf
Alq--\kesh--dr\\
lA tshRl AlbAl bmADY Alzm--\kesh--An UlA b--\kesh--'At Al`Y--\kesh--sh qb--\kesh--l
Al'aUAn\\
U'aR--\kesh--nm mn AlHAD--\kesh--r ldhAt--\kesh--h flYs f--\kesh--Y Tb--\kesh--`
AllYAl--\kesh--Y Al'am--\kesh--An\\
Rd bZhr AlRYb UAlYUm l--\kesh--Y Ukm YxYb AlZ--\kesh--n f--\kesh--Y Almqb--\kesh--l\\
Uls--\kesh--t bAlRAf--\kesh--l Ht--\kesh--I 'arI jm--\kesh--Al dnY--\kesh--AY U
lA Ajtl--\kesh--I\\
Alqlb qd 'aDnAh `shq Aljm--\kesh--Al UAlS--\kesh--dr q--\kesh--d D--\kesh--Aq bm--\kesh--A
lA Yq--\kesh--Al\\
YA rb hl YrDYk hdhA AlZlm--\kesh--A UAlm--\kesh--A| Yns--\kesh--Ab 'am--\kesh--Am--\kesh--Y
zlAl\\
'aUlI bhdhA Alqlb 'an Yxfq--\kesh--A U fY RrAm AlH--\kesh--b 'an YHtrq--\kesh--A\\
mA 'aDY` AlYUm AldhY m--\kesh--r b--\kesh--Y mn RYr 'an 'ahUI U 'an 'a`shq--\kesh--A\\
'afq xfYf AlZl hdhA AlsH--\kesh--r n--\kesh--AdI d` Aln--\kesh--Um Un--\kesh--AR
AlUt--\kesh--r\\
fm--\kesh--A 'aT--\kesh--Al Aln--\kesh--Um `m--\kesh--rA UlA qSr mn Al'a`mAr TUl
Als-h--\kesh--r\\
fk--\kesh--m tUl--\kesh--I AllY--\kesh--l b`--\kesh--d Alnh--\kesh--Ar UT--\kesh--Al
bAl'anj--\kesh--m h--\kesh--dhA Alm--\kesh--dAr\\
f'amsh AlhUYnt* 'an hdhA Alc--\kesh--rI m--\kesh--n 'a`Y--\kesh--n sAH--\kesh--rt*
AlAH--\kesh--UrAr\\
lA tUHsh Alnfs bxUf AlZn--\kesh--Un U'aRnm mn AlHADr 'amn AlYqY--\kesh--n\\
fqd tsAUI fY AlcrI rAH--\kesh--l RdA UmAD mn AlUf AlsnY--\kesh--n\\
ATf'I lZI Alqlb bshhd AlrD--\kesh--Ab f'inm--\kesh--A Al'aY--\kesh--Am mc--\kesh--l
AlsH--\kesh--Ab\\
U`Yshn--\kesh--A TY--\kesh--f xY--\kesh--Al fn--\kesh--l HZ--\kesh--k mn--\kesh--h
qb--\kesh--l f--\kesh--Ut Alshb--\kesh--Ab\\
lbst cUb Al`Ysh lm Astsh--\kesh--r UH--\kesh--rt fY--\kesh--h bY--\kesh--n sht--\kesh--I
Alfk--\kesh--r\\
UsUf 'anDU AlcUb `nY Ul--\kesh--m 'adrk lm--\kesh--AdhA j'I--\kesh--t 'aY--\kesh--n
AlmR--\kesh--r\\
YA mn YHAr Alfhm fY qdrt--\kesh--k UtTl--\kesh--b Alnf--\kesh--s Hm--\kesh--I TA`t--\kesh--k\\
Askrn--\kesh--Y Al'ic--\kesh--m U lknn--\kesh--Y SH--\kesh--Ut bAl'am--\kesh--Al
f--\kesh--Y rHmt--\kesh--k\\
'in lm 'akn 'axlSt fY TA`t--\kesh--k f'inn--\kesh--Y 'aTm--\kesh--` f--\kesh--Y
rHmt--\kesh--k\\
U'inm--\kesh--A Yshf--\kesh--` l--\kesh--Y b'ann--\kesh--Y q--\kesh--d `sh--\kesh--t
lA 'ash--\kesh--rk fY UHdt--\kesh--k\\
nxfY `n AlnAs snI Tl`t--\kesh--k f'inn--\kesh--Y 'aTm--\kesh--` f--\kesh--Y rHmt--\kesh--k\\
f'an--\kesh--t mj--\kesh--lAh U'an--\kesh--t Al--\kesh--dhY t--\kesh--rI bdY--\kesh--`
AlSn--\kesh--` f--\kesh--Y 'AYt--\kesh--k\\
An tfDl AlqTrt* mn bHrh--\kesh--A ff--\kesh--Y m--\kesh--dAh--\kesh--A mnt-h--\kesh--I
'amrh--\kesh--A\\
tqArb--\kesh--t Y--\kesh--A rb m--\kesh--A bYnn--\kesh--A msAf--\kesh--t* Alb`--\kesh--d
`l--\kesh--I qdrh--\kesh--A\\
YA `Alm Al'asrAr `lm AlYq--\kesh--Y--\kesh--n Y--\kesh--A kAsh--\kesh--f AlD--\kesh--r
`--\kesh--n AlbA'IsY--\kesh--n\\
Y--\kesh--A qAb--\kesh--l Al'a`--\kesh--dhAr `dn--\kesh--A 'il--\kesh--I Zl--\kesh--k
f'aqb--\kesh--l tUb--\kesh--t* AltA'IbY--\kesh--n
\end{minipage}
\end{center}
}
\end{document}
\end{verbatim}
\caption{\TeX\ code of Fig.~\ref{oum}, transliterated input}
\end{figure*}

\begin{figure*}[p]

\kern-2cm

\scriptsize
\begin{verbatim}
\documentclass{article}
\usepackage{dad}
\begin{document}
\arab{
\begin{center}
\end{verbatim}

\kern-1.2\baselineskip

\verb=\textbf{=\arabtt{rbA`YAt AlxYAm}\verb=}=

\kern-1.2\baselineskip

\begin{verbatim}

\medskip

\begin{minipage}{10cm}
\end{verbatim}
\def\CRCRCR{\textbackslash\textbackslash\\}
\arabtt{sm`t SUtA hAtfA fY AlsH--\textbackslash tT --r n--\textbackslash tT --AdI mn AlRYb rfAt Albsh--\textbackslash tT --r\CRCRCR
hbUA Aml'aUA k'as AlmnI qb--\textbackslash tT --l 'an tml'a k--\textbackslash tT --'as Al`m--\textbackslash tT --r kf
Alq--\textbackslash tT --dr\CRCRCR
lA tshRl AlbAl bmADY Alzm--\textbackslash tT --An UlA b--\textbackslash tT --'At Al`Y--\textbackslash tT --sh qb--\textbackslash tT --l
Al'aUAn\CRCRCR
U'aR--\textbackslash tT --nm mn AlHAD--\textbackslash tT --r ldhAt--\textbackslash tT --h flYs f--\textbackslash tT --Y Tb--\textbackslash tT --`
AllYAl--\textbackslash tT --Y Al'am--\textbackslash tT --An\CRCRCR
Rd bZhr AlRYb UAlYUm l--\textbackslash tT --Y Ukm YxYb AlZ--\textbackslash tT --n f--\textbackslash tT --Y Almqb--\textbackslash tT --l\CRCRCR
Uls--\textbackslash tT --t bAlRAf--\textbackslash tT --l Ht--\textbackslash tT --I 'arI jm--\textbackslash tT --Al dnY--\textbackslash tT --AY U
lA Ajtl--\textbackslash tT --I\CRCRCR
Alqlb qd 'aDnAh `shq Aljm--\textbackslash tT --Al UAlS--\textbackslash tT --dr q--\textbackslash tT --d D--\textbackslash tT --Aq bm--\textbackslash tT --A
lA Yq--\textbackslash tT --Al\CRCRCR
YA rb hl YrDYk hdhA AlZlm--\textbackslash tT --A UAlm--\textbackslash tT --A| Yns--\textbackslash tT --Ab 'am--\textbackslash tT --Am--\textbackslash tT --Y
zlAl\CRCRCR
'aUlI bhdhA Alqlb 'an Yxfq--\textbackslash tT --A U fY RrAm AlH--\textbackslash tT --b 'an YHtrq--\textbackslash tT --A\CRCRCR
mA 'aDY` AlYUm AldhY m--\textbackslash tT --r b--\textbackslash tT --Y mn RYr 'an 'ahUI U 'an 'a`shq--\textbackslash tT --A\CRCRCR
'afq xfYf AlZl hdhA AlsH--\textbackslash tT --r n--\textbackslash tT --AdI d` Aln--\textbackslash tT --Um Un--\textbackslash tT --AR\\
AlUt--\textbackslash tT --r\CRCRCR
fm--\textbackslash tT --A 'aT--\textbackslash tT --Al Aln--\textbackslash tT --Um `m--\textbackslash tT --rA UlA qSr mn Al'a`mAr TUl
Als-h--\textbackslash tT --r\CRCRCR
fk--\textbackslash tT --m tUl--\textbackslash tT --I AllY--\textbackslash tT --l b`--\textbackslash tT --d Alnh--\textbackslash tT --Ar UT--\textbackslash tT --Al
bAl'anj--\textbackslash tT --m h--\textbackslash tT --dhA Alm--\textbackslash tT --dAr\CRCRCR
f'amsh AlhUYnt* 'an hdhA Alc--\textbackslash tT --rI m--\textbackslash tT --n 'a`Y--\textbackslash tT --n sAH--\textbackslash tT --rt*
AlAH--\textbackslash tT --UrAr\CRCRCR
lA tUHsh Alnfs bxUf AlZn--\textbackslash tT --Un U'aRnm mn AlHADr 'amn AlYqY--\textbackslash tT --n\CRCRCR
fqd tsAUI fY AlcrI rAH--\textbackslash tT --l RdA UmAD mn AlUf AlsnY--\textbackslash tT --n\CRCRCR
ATf'I lZI Alqlb bshhd AlrD--\textbackslash tT --Ab f'inm--\textbackslash tT --A Al'aY--\textbackslash tT --Am mc--\textbackslash tT --l
AlsH--\textbackslash tT --Ab\CRCRCR
U`Yshn--\textbackslash tT --A TY--\textbackslash tT --f xY--\textbackslash tT --Al fn--\textbackslash tT --l HZ--\textbackslash tT --k mn--\textbackslash tT --h
qb--\textbackslash tT --l f--\textbackslash tT --Ut Alshb--\textbackslash tT --Ab\CRCRCR
lbst cUb Al`Ysh lm Astsh--\textbackslash tT --r UH--\textbackslash tT --rt fY--\textbackslash tT --h bY--\textbackslash tT --n sht--\textbackslash tT --I
Alfk--\textbackslash tT --r\CRCRCR
UsUf 'anDU AlcUb `nY Ul--\textbackslash tT --m 'adrk lm--\textbackslash tT --AdhA j'I--\textbackslash tT --t 'aY--\textbackslash tT --n
AlmR--\textbackslash tT --r\CRCRCR
YA mn YHAr Alfhm fY qdrt--\textbackslash tT --k UtTl--\textbackslash tT --b Alnf--\textbackslash tT --s Hm--\textbackslash tT --I TA`t--\textbackslash tT --k\CRCRCR
Askrn--\textbackslash tT --Y Al'ic--\textbackslash tT --m U lknn--\textbackslash tT --Y SH--\textbackslash tT --Ut bAl'am--\textbackslash tT --Al
f--\textbackslash tT --Y rHmt--\textbackslash tT --k\CRCRCR
'in lm 'akn 'axlSt fY TA`t--\textbackslash tT --k f'inn--\textbackslash tT --Y 'aTm--\textbackslash tT --` f--\textbackslash tT --Y
rHmt--\textbackslash tT --k\CRCRCR
U'inm--\textbackslash tT --A Yshf--\textbackslash tT --` l--\textbackslash tT --Y b'ann--\textbackslash tT --Y q--\textbackslash tT --d `sh--\textbackslash tT --t
lA 'ash--\textbackslash tT --rk fY UHdt--\textbackslash tT --k\CRCRCR
nxfY `n AlnAs snI Tl`t--\textbackslash tT --k f'inn--\textbackslash tT --Y 'aTm--\textbackslash tT --` f--\textbackslash tT --Y rHmt--\textbackslash tT --k\CRCRCR
f'an--\textbackslash tT --t mj--\textbackslash tT --lAh U'an--\textbackslash tT --t Al--\textbackslash tT --dhY t--\textbackslash tT --rI bdY--\textbackslash tT --`
AlSn--\textbackslash tT --` f--\textbackslash tT --Y 'AYt--\textbackslash tT --k\CRCRCR
An tfDl AlqTrt* mn bHrh--\textbackslash tT --A ff--\textbackslash tT --Y m--\textbackslash tT --dAh--\textbackslash tT --A mnt-h--\textbackslash tT --I
'amrh--\textbackslash tT --A\CRCRCR
tqArb--\textbackslash tT --t Y--\textbackslash tT --A rb m--\textbackslash tT --A bYnn--\textbackslash tT --A msAf--\textbackslash tT --t* Alb`--\textbackslash tT --d
`l--\textbackslash tT --I qdrh--\textbackslash tT --A\CRCRCR
YA `Alm Al'asrAr `lm AlYq--\textbackslash tT --Y--\textbackslash tT --n Y--\textbackslash tT --A kAsh--\textbackslash tT --f AlD--\textbackslash tT --r
`--\textbackslash tT --n AlbA'IsY--\textbackslash tT --n\CRCRCR
Y--\textbackslash tT --A qAb--\textbackslash tT --l Al'a`--\textbackslash tT --dhAr `dn--\textbackslash tT --A 'il--\textbackslash tT --I Zl--\textbackslash tT --k
f'aqb--\textbackslash tT --l tUb--\textbackslash tT --t*\\
AltA'IbY--\textbackslash tT --n\hfill}
\begin{verbatim}
\end{minipage}
\end{center}
}
\end{document}
\end{verbatim}
\caption{\TeX\ code of Fig.~\ref{oum}, Unicode input}
\end{figure*}

\subsection{Unicode input}\label{unicode}

Input can be transliterated or provided directly in Unicode Arabic: \texttt{\textbackslash arab\{YAnis\}} or \texttt{\textbackslash arab\{\arabtt{YAn--is}\}} or even \texttt{\textbackslash arab\{\arabtt{YA}\,nis\}} or \texttt{\textbackslash arab\{YA\,\arabtt{n--is}\}} will produce the same result: \arab{YAnis}.

All cells of Table~\ref{trans} can be obtained by the corresponding Unicode characters (mostly via a single character, except for \emph{\v{s}adda} + vowel combinations which require two characters). There is a special case, though: the \arab{LLh} ligature (see next section).

For the convenience of the user who wants to write kashida (so that Arabic input is not disrupted) we have defined a command (in Arabic characters) \arabtt{tT}\textbackslash{} (\arab{tT} are the first two letters of \arab{tTUYl} = \emph{ta\d{t}Uyl}, the Arabic name of kashida) which is exactly equivalent to \verb=\kesh= and has to be placed between Unicode \textsc{U+0640 arabic tatwell} characters.

\subsubsection{The \arab{LLh} ligature and Unicode}\label{allah}

The \arab{LLh} ligature is traditionally used for writing the name of God: \arab{ALLh}. It can be found in religious texts, but also in expressions (for example, \arab{'in shA| ALLh} which means ``hopefully'' appears even in French language as \emph{inchallah} and in Portuguese as \emph{oxal\'a}) and in the very common surname \arab{`bd ALLh} Abdallah.

The problem with this ligature is that it contains a rather rare diacritic (a \emph{\v{s}adda} combined with a vertical \emph{fat\d{h}a}---the latter us available on Apple Arabic keyboard layout but not on the Microsoft one) and, as a convenience, most standard fonts will replace the character string \emph{l\=am}-\emph{l\=am}-\emph{h\=a\hamza} (which would normally look like \arab{llh}) by the complete ligature \arab{LLh} (in other words: the font not only changes the glyphs but, at the same time, also adds the diacritics). This behavior is barely legitimate: a ligature (as in `fi' or `\arab{lA}') is normally limited to a change of glyphs, and should not add new characters (in this case, characters \textsc{U+0651 arabic shadda} and \textsc{U+0671 arabic letter superscript alef}) since this means that what is rendered does not correspond anymore to the underlying Unicode character string.

Nevertheless, for the user's convenience, we have adopted that behavior also in \arab{D}, but only in the case of Unicode input. Therefore when the user types Unicode \emph{l\=am}-\emph{l\=am}-\emph{h\=a\hamza} (the first \emph{l\=am} must not be preceded by a quadriform letter), the system will produce the \arab{LLh} ligature.

This method will not work if a diacritic is inserted between the two \emph{l\=am}s, or if the first \emph{l\=am} follows a quadriform letter and hence will be medial. For that case, we have defined a macro \arabtt{llh}\verb=/= (the macro name is in Arabic script so that right-to-left direction is not disrupted) which takes an argument: the vowel between the two \emph{l\=am}s. Hence, to obtain \arab{faLiLhi} the user can choose between one of the following two:
\begin{quote}
\arabtt{^^^^00fbi}\texttt{\{}\arabtt{^^^^00fbi}\texttt{\}}\arabtt{llh}\texttt{/}\arabtt{f--a}\\[6pt]
\texttt{faLiLhi}
\end{quote}
(The dotted circle, used to show the combining nature of short vowels and other diacritics, can be obtained by the macros \verb=\arabdottedcircle= or \arabtt{dA'Irt*}\verb=/= with the macro name in Arabic script.)

\begin{figure*}
{\centering

\begin{tikzpicture}[->,>=stealth',x=2cm,y=2cm,auto,node distance=3cm,
  thick,main node/.style={circle,inner sep=1pt,draw,align=center,font=\small}]

\node[main node] (8) at (-1,1)  {$\emptyset$};
\node[main node] (1) at (0,1)  {$l_0$\\\arab{l}};
\node[main node] (2) at (1.5,1)  {$ll_0$\\\arab{ll}};
\node[main node] (3) at (3,1)  {$ll_5A_3$\\\arab{llA}};
\node[main node] (4) at (3,0)  {$ll_1k_3$\\\arab{llk}};
\node[main node] (5) at (2,0)  {$LLh_0$\\\arab{LLh}};
\node[main node] (6) at (1,0) {$l_1k_3$\\\arab{lk}};
\node[main node] (7) at (0,0) {$l_4A_4$\\\arab{lA}};

\path[every node/.style={font=\small}]
(8) edge node {$l_0$ \arab{l}} (1)
(1) edge node {$l_0$ \arab{l}} (2)
(2) edge node {$A_0$ \arab{A}} (3)
(2) edge node {$k_0$ \arab{k}} (4)
(2) edge node {$h_0$ \arab{h}} (5)
(1) edge node {$k_0$ \arab{k}} (6)
(1) edge node {$A_0$ \arab{A}} (7)
;
\end{tikzpicture}

}
\caption{Finite state automaton starting with an isolated \emph{l\=am} (\emph{\hamza$\!$alif} \arab{A} stands for the set of letter $\mathcal{A}={}\{$ \arab{A}, \arab{'a}, \arab{'i}, \arab{'A}, \arab{A*} $\}$; \arab{k} stands for any Arabic letter besides \arab{h} and set $\mathcal{A}$.\label{fsa}}
\end{figure*}

\section{\TeX nicalities}\label{technica}

More information about \arab{D} (history, evolution, rationale of technical choices, \TeX nicalities) can be found in \cite{tugboat}.

\bibliographystyle{plain}  % we recommend the plain bibliography style
\bibliography{dad-user-guide}       % xampl.bib comes with BibTeX

\end{document}