1 files changed, 165 insertions, 3 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index b388438..458a034 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -454,7 +454,7 @@ consonants, though three of them are also used as vowels
 % \arb[novoc]{n} & \dmg{n} & \loc{n} & |n| \\
 % \arb[novoc]{h} & \dmg{h} & \loc{h} & |h| \\
 % \arb[novoc]{w} & \dmg{w} & \loc{w} & |w| \\
-% \arb[novoc]{y} & \dmg{y} & \loc{y} & |y| \\ \hline
+% \arb[novoc]{y} & \dmg{y} & \loc{y} & |y| \\
 % \arb[novoc]{T} & \dmg{aT} & \loc{aT} & |T| \\
 % \bottomrule
 % \caption[Arab\TeX\ consonants]{Standard Arab\TeX\ (consonants)}
@@ -474,7 +474,7 @@ consonants, though three of them are also used as vowels
 % \arb[novoc]{A} & \dmg{A} & \loc{A} & \verb|A| \\
 % \arb[novoc]{U} & \dmg{U} & \loc{U} & \verb|U| \\
 % \arb[novoc]{I} & \dmg{I} & \loc{I} & \verb|I| \\
-% \arb[novoc]{_A}\footnote{$=$ \arb[trans]{al-'alif 'l-maq.sUraT}.}
+% \arb[novoc]{_A}\footnote{$=$ \arb[trans]{al-'alifu 'l-maq.sUraTu}.}
 %            & \dmg{_A} & \loc{_A} & \verb|_A| or \verb|Y| \\
 % \arb[novoc]{B_a} & \dmg{B_a} & \loc{B_a} & \verb|_a| \\
 % \arb[novoc]{B_u} & \dmg{B_u} & \loc{B_u} & \verb|_u| \\
@@ -526,9 +526,171 @@ consonants, though three of them are also used as vowels
 % \label{tab:arabtex-short-vowels}
 % \end{longtable}
 %
+% Whether Arabic texts are vocalized or not is essentially a matter of
+% personal choice. So one may use |voc| mode and decide not to write
+% vowels except at some particular places for disambiguation purposes,
+% or use |novoc| mode, not write vowels---as |novoc| normally does not
+% show them---except, again,  where disambiguation is needed.\footnote{See
+% below **}
+%
+% However, it may be wise to always write the vowels, leaving to the
+% various modes provided by \package{arabluatex} to take care of
+% showing or not showing the vowels.
+%
+% That said, there is no need to write the short vowels
+% \arb[trans]{fat.haT}, \arb[trans]{.dammaT} or \arb[trans]{kasraT}
+% except in the following cases:
+% \begin{compactitem}
+% \item at the commencement of a word, to indicate that a connective
+% \arb[trans]{'alif} is needed, with the exception of the article (see
+% below **);
+% \item when \package{arabluatex} needs to perform a contextual
+%   analysis to determine the carrier of the \arb[trans]{hamzaT};
+% \item in the various transliteration modes, as vowels are always
+% expressed  in romanized Arabic.
+% \end{compactitem}
+%
+%\section{\package{arabluatex} in action}
+%\subsection{The vowels and diphthongs}
+% \paragraph{Short vowels} Ss said above, they are written \meta{a, u,
+% i}:
+% \begin{quote}
+%   |_halaqa| (or |xalaqa|) \arb[voc]{xalaqa} \arb[trans]{xalaqa},
+%   |^samsuN| \arb[voc]{^samsuN} \arb[trans]{^samsuN}, |karImuN|
+%   \arb[voc]{karImuN} \arb[trans]{karImuN}.
+%
+%   |bi-hi| \arb[voc]{bi-hi} \arb[trans]{bi-hi}, |'aqi.tuN|
+%   \arb[voc]{'aqi.tuN} \arb[trans]{'aqi.tuN}.
+%
+%   |la-hu| \arb[voc]{la-hu} \arb[trans]{la-hu}, |.hujjaTuN|
+%   \arb[voc]{.hujjaTuN} \arb[trans]{.hujjaTuN}.
+% \end{quote}
+%
+%\paragraph{Long vowels} They are written \meta{U, A, I}:
+% \begin{quote}
+%   |qAla| \arb[voc]{qAla} \arb[trans]{qAla}, |bI`a| \arb[voc]{bI`a}
+%   \arb[trans]{bI`a}, |.tUruN| \arb[voc]{.tUruN} \arb[trans]{.tUruN},
+%   |.tInuN| \arb[voc]{.tInuN} \arb[trans]{.tInuN}, |murU'aTuN|
+%   \arb[trans]{murU'aTuN} \arb[voc]{murU'aTuN}
+% \end{quote}
+%
+% \paragraph{\arb[trans]{'alif maq.sUraT}} It is written \meta{\_A} or
+% \meta{Y}:
+% \begin{quote}
+%   |al-fat_A| \arb[voc]{al-fat_A} \arb[trans]{al-fat_A}, |al-maqh_A|
+%   \arb[voc]{al-maqh_A} \arb[trans]{al-maqh_A}, |'il_A|
+%   \arb[voc]{'il_A} \arb[trans]{'il_A}.
+% \end{quote}
 % 
+% \paragraph{\arb[trans]{'alif} \emph{otiosum}} Said
+% \arb[trans]{'alifu 'l-wiqAyaTi}, \enquote{the guarding
+% \arb[trans]{'alif}}\,, after \arb[novoc]{U} at the end of a word, both
+% when preceded by \arb[trans]{.dammaT} and by \arb[trans]{fat.haT} is
+% written \meta{UA} or \meta{aW, aWA}:
+% \begin{quote}
+%   |na.sarUA| \arb[voc]{na.sarUA} \arb[trans]{na.sarUA}, |katabUA|
+%   \arb[voc]{katabUA} \arb[trans]{katabUA}, |ya.gzUA|
+%   \arb[voc]{ya.gzUA} \arb[trans]{ya.gzUA}, |ramaW|
+%   \arb[fullvoc]{ramaW} \arb[trans]{ramaW}, |banaWA|
+%   \arb[fullvoc]{banaWA}, \arb[trans]{banaWA}.
+% \end{quote}
+%
+% \paragraph{\arb[trans]{'alif ma.h_dUfaT} and defective
+% \arb[trans]{U, I}} they are written \meta{\_a, \_i \_u}:
+% \begin{quote}
+%   |al-l_ahu| \arb[voc]{al-l_ahu} \arb[trans]{al-l_ahu}, |'il_ahuN|
+%   \arb[voc]{'il_ahuN} \arb[trans]{'il_ahuN}, |al-ra.hm_anu|
+%   \arb[voc]{al-ra.hm_anu} \arb[trans]{al-ra.hm_anu}, |l_akin|
+%   \arb[voc]{l_akin} \arb[trans]{l_akin}, |h_ahunA|
+%   \arb[voc]{h_ahunA} \arb[trans]{h_ahunA}, |.hunaynu bnu 'is.h_aqa|
+%   \arb[voc]{.hunaynu bnu 'is.h_aqa} \arb[trans]{\cap{.hunaynu} bnu
+%   \cap{'is.h_aqa}}, |rabb_i| \arb[voc]{rabb_i} \arb[trans]{rabb_i},
+%   |al-`A.s_i| \arb[voc]{al-`A.s_i} \arb[trans]{al-\cap{`A.s_i}}.
+% \end{quote}
+%
+% \paragraph{Silent \arb[novoc]{U}/\arb[novoc]{I}}
+% Some words ending with \arb[voc]{BAT} are usually written
+% \arb[voc]{BawT} or \arb[voc]{B_aUT} instead of \arb[voc]{BAT}: see
+% \textcite[i. 12 A]{Wright}. \package{arabluatex} preserves this
+% particular writing; the same applies to words ending in
+% \arb[voc]{BayT} for \arb[voc]{BAT}. long vowels \meta{U, I} shall
+% receive no \arb[trans]{sukUn} after a \arb[trans]{'alif ma.h_dUfaT}
+% and are discarded in |trans| mode:
+% \begin{quote}
+%   |.hay_aUTuN| \arb[voc]{.hay_aUTuN} \arb[trans]{.hay_aUTuN},
+%   |.sal_aUTuN| \arb[voc]{.sal_aUTuN} \arb[trans]{.sal_aUTuN},
+%   |mi^sk_aUTuN| \arb[voc]{mi^sk_aUTuN} \arb[trans]{mi^sk_aUTuN},
+%   |tawr_aITuN| \arb[voc]{tawr_aITuN} \arb[trans]{tawr_aITuN}.
+%
+%   And so also: |al-rib_aITu| \arb[voc]{al-rib_aITu}.
+%   \arb[trans]{al-rib_aITu}
+% \end{quote}
+%
+% \paragraph{\arb[trans]{\cap{`amruNU}}, and the silent
+% \arb[novoc]{U}} To this name a silent \arb[novoc]{U} is added to
+% distinguish it from \arb[trans]{\cap{`umaruN}}: see \textcite[i. 12
+% C]{Wright}. In no way this affects the sound of the
+% \arb[trans]{tanwIn}, so it has to be discarded in |trans| mode:
+% \begin{quote}
+%   |`amruNU| \arb[voc]{`amruNU} \arb[trans]{`amruNU}, |`amraNU|
+%   \arb[voc]{`amraNU} \arb[trans]{`amraNU}, |`amriNU|
+%   \arb[voc]{`amriNU} \arb[trans]{`amriNU}.
+%
+%   When the \arb[trans]{tanwIn} falls away \parencite[i. 249
+%   B]{Wright}: |`amruU bnu mu.hammadiN| \arb[fullvoc]{`amruU bnu
+%   mu.hammadiN} \arb[trans]{\cap{`amruU} bnu \cap{mu.hammadiN}}, %
+%   |mu.hammadu bnu `amriU bni _hAlidiN| \arb[fullvoc]{mu.hammadu bnu
+%   `amriU bni _hAlidiN} \arb[trans]{\cap{mu.hammadu} bnu \cap{`amriU}
+%   bni \cap{_hAlidiN}}.
+%
+%   And so also: |al-rib_aUA| \arb[voc]{al-rib_aUA}
+%   \arb[trans]{al-rib_aUA}, |ribaNU| \arb[voc]{ribaNU}
+%   \arb[trans]{ribaNU}.
+% \end{quote}
+%
+%\paragraph{\arb[trans]{tanwIn}}
+% The marks of doubled short vowels, \arb{BuN}, \arb{BaN}, \arb{BiN},
+% are written \meta{uN, aN, iN} respectively. \package{arabluatex}
+% deals with special cases, such as \arb{BaN} taking an \arb[novoc]{A}
+% after all consonants except \arb[novoc]{T}, and \arb[trans]{tanwIn}
+% preceding \arb[novoc]{Y} as in \arb[voc]{hudaN_A}, which is written
+% \meta{an\_A} or \meta{aNY}:
+% \begin{quote}
+%   |mAluN| \arb[voc]{mAluN} \arb[trans]{mAluN}, |bAbaN|
+%   \arb[voc]{bAbaN} \arb[trans]{bAbaN}, |madInaTaN|
+%   \arb[voc]{madInaTaN} \arb[trans]{madInaTaN}, |bintiN|
+%   \arb[voc]{bintiN} \arb[trans]{bintiN} |maqhaN_A|
+%   \arb[voc]{maqhaN_A} \arb[trans]{maqhaN_A}, |fataNY|
+%   \arb[voc]{fataNY} \arb[trans]{fataNY}.
+%
+%   \package{arabluatex} is aware of special orthographies: |^say'uN|
+%   \arb[voc]{^say'uN} \arb[trans]{^say'uN}, |^say'aN|
+%   \arb[voc]{^say'aN} \arb[trans]{^say'aN}, |^say'iN|
+%   \arb[voc]{^say'iN} \arb[trans]{^say'iN}.
+% \end{quote}
+%
+%\paragraph{\arb[trans]{tA' marbU.taT}}
+% It is written \meta{T}:
+% \begin{quote}
+%   |madInaTuN| \arb[voc]{madInaTuN} \arb[trans]{madInaTuN},
+%   |madInaTaN| \arb[voc]{madInaTaN} \arb[trans]{madInaTaN},
+%   |madInaTiN| \arb[voc]{madInaTiN} \arb[trans]{madInaTiN}.
+% \end{quote}
+%
+% \paragraph{\arb[trans]{hamzaT}} It is written \meta{'}, its carrier
+% being determined by contextual analysis:
+% \begin{quote}
+%   \textbf{Initial \arb[trans]{hamzaT}}: |'asaduN| \arb[voc]{'asaduN}
+%   \arb[trans]{'asaduN}, |'u_htuN| \arb[voc]{'u_htuN}
+%   \arb[trans]{'u_htuN}, |'iqlIduN| \arb[voc]{'iqlIduN}
+%   \arb[trans]{'iqlIduN}, |'anna| \arb[voc]{'anna}
+%   \arb[trans]{'anna}, |'inna| \arb[voc]{'inna} \arb[trans]{'inna}.
+%
+%   \textbf{Middle \arb[trans]{hamzaT}}: \arb[fullvoc]{xa.ta'uN xa.ta'aN
+%   xa.ta'iN rasA'uN rasA'aN rasA'iN xa.ta xAsi'Ina mas'UluN hAdi'uN
+%   yaqra'Una qara'a taxba'} RAAH!
+% \end{quote}
 % 
-% Usage goes here. \cs{hop}\oarg{ah}\marg{ouh}\meta{pop}
 %
 %
 % \StopEventually{}