1 files changed, 157 insertions, 28 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 556328b..8ae511d 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -52,6 +52,7 @@
 \renewcommand*{\quotingfont}{\footnotesize}
 \usepackage{longtable}
 \usepackage{booktabs}
+\usepackage[defaultlines=2,all]{nowidow}
 \usepackage{tikz}
 \usepackage[breakable, skins, listings, xparse]{tcolorbox}
 \DeclareTCBListing{arabluacode}{s O{}}{colback=white, boxrule=.15mm,
@@ -289,7 +290,7 @@
 %
 % By default, if no Arabic font is selected, \package{arabluatex} will
 % issue a warning message and attempt to load the Amiri
-% font\footnote{\textcite{pkg:amiri}.} like so:\\
+% font\footnote{\textcite{pkg:amiri}.} like so:---\\
 % \arabluaverb{\newfontfamily\arabicfont[Script=Arabic]{Amiri}}
 % \begin{quoting}
 %   \textsc{Rem.} By default Amiri places the \arb[trans]{kasraT} in
@@ -300,7 +301,7 @@
 %   well as \arb{BBi}\,. See \textcite[i.14.C--D]{Wright}. The placement
 %   of the \arb[trans]{kasraT} above the consonant may be obtained by
 %   selecting the |ss05| feature of the Amiri font, like
-%   so:\footnote{See the documentation of \package{amiri},
+%   so:---\footnote{See the documentation of \package{amiri},
 %   \textcite[5]{pkg:amiri}.}\\
 %   \arabluaverb{\newfontfamily\arabicfont[Script=Arabic,RawFeature={+ss05}]{Amiri}}
 %
@@ -426,6 +427,7 @@ consonants, though three of them are also used as vowels
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
 % \endhead \footnotetext{See below **}
+% \label{tab:arabtex-consonants}
 % \arb[novoc]{a}\footnote{For \arb[trans]{'alif} as a consonant, see
 % \textcite[i. 16 D]{Wright}.} & \dmg{a} & \loc{a} & \verb|a| \\
 % \arb[novoc]{b} & \dmg{b} & \loc{b} & |b| \\
@@ -458,7 +460,6 @@ consonants, though three of them are also used as vowels
 % \arb[novoc]{T} & \dmg{aT} & \loc{aT} & |T| \\
 % \bottomrule
 % \caption[Arab\TeX\ consonants]{Standard Arab\TeX\ (consonants)}
-% \label{tab:arabtex-consonants}
 % \end{longtable}
 %
 % \subsection{Vowels}
@@ -471,6 +472,7 @@ consonants, though three of them are also used as vowels
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
 % \endhead \footnotetext{See below **}
+% \label{tab:arabtex-long-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| \\
@@ -481,7 +483,6 @@ consonants, though three of them are also used as vowels
 % \arb[novoc]{B_i} & \dmg{B_i} & \loc{B_i} & \verb|_i| \\
 % \bottomrule
 % \caption[Arab\TeX\ long vowels]{Standard Arab\TeX\ (long vowels)}
-% \label{tab:arabtex-long-vowels}
 % \end{longtable}
 %
 % \begin{quoting}
@@ -498,23 +499,24 @@ consonants, though three of them are also used as vowels
 %   \textsc{Rem.}~\emph{b.} Defective writings, such as
 %   \arb[novoc]{B_a}, \arb[trans]{al-'alifu 'l-ma.h_dUfaTu}, or
 %   defective writings of \arb[trans]{B_u} and \arb[trans]{B_i} are
-%   encoded |_a| |_u| and |_i| respectively, e.g. |_d_alika|
-%   \arb[voc]{_d_alika}, |al-mal_a'ikaTu 'l-ra.hm_anu|
-%   \arb[voc]{al-mal_a'ikaTu 'l-ra.hm_anu},
-%   |.hu_dayfaTu bnu 'l-yamAn_i| \arb[fullvoc]{.hu_dayfaTu bnu
-%   'l-yamAn_i} for \arb[trans]{\cap{.hu_dayfaTu} bnu
-%   'l-\cap{yamAn_i}}, etc.
+%   encoded |_a| |_u| and |_i| respectively, e.g. |_d_alika| %
+%   \arb[voc]{_d_alika}, |al-mal_a'ikaTu 'l-ra.hm_anu| %
+%   \arb[voc]{al-mal_a'ikaTu 'l-ra.hm_anu}, %
+%   |.hu_dayfaTu bnu 'l-yamAn_i| %
+%   \arb[fullvoc]{.hu_dayfaTu bnu 'l-yamAn_i} for
+%   \arb[trans]{\cap{.hu_dayfaTu} bnu 'l-\cap{yamAn_i}}, etc.
 % \end{quoting}
 % 
 % \subsubsection{Short vowels}
 % Table\vref{tab:arabtex-short-vowels} gives the Arab\TeX\ equivalents for
-% the Arabic short vowels. 
+% the Arabic short vowels.
 % \begin{longtable}{llll}
 % \toprule
 % Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
 % \endhead \footnotetext{See below **}
+% \label{tab:arabtex-short-vowels}
 % \arb[voc]{Ba} & \dmg{Ba} & \loc{Ba} & \verb|a| \\
 % \arb[voc]{Bu} & \dmg{Bu} & \loc{Bu} & \verb|u| \\
 % \arb[voc]{Bi} & \dmg{Bi} & \loc{Bi} & \verb|i| \\
@@ -523,7 +525,6 @@ consonants, though three of them are also used as vowels
 % \arb[voc]{BiN} & \dmg{BiN} & \loc{BiN} & \verb|iN| \\
 % \bottomrule
 % \caption[Arab\TeX\ short vowels]{Standard Arab\TeX\ (short vowels)}
-% \label{tab:arabtex-short-vowels}
 % \end{longtable}
 %
 % Whether Arabic texts are vocalized or not is essentially a matter of
@@ -533,9 +534,17 @@ consonants, though three of them are also used as vowels
 % 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.
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}[text only]
+  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.
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
 %
 % That said, there is no need to write the short vowels
 % \arb[trans]{fat.haT}, \arb[trans]{.dammaT} or \arb[trans]{kasraT}
@@ -552,12 +561,12 @@ consonants, though three of them are also used as vowels
 %
 %\section{\package{arabluatex} in action}
 %\subsection{The vowels and diphthongs}
-% \paragraph{Short vowels} Ss said above, they are written \meta{a, u,
+% \paragraph{Short vowels} As 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}.
+%   \arb[voc]{karImuN} \arb[trans]{\cap{karImuN}}.
 %
 %   |bi-hi| \arb[voc]{bi-hi} \arb[trans]{bi-hi}, |'aqi.tuN|
 %   \arb[voc]{'aqi.tuN} \arb[trans]{'aqi.tuN}.
@@ -602,7 +611,8 @@ consonants, though three of them are also used as vowels
 %   \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]{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}}.
@@ -637,11 +647,13 @@ consonants, though three of them are also used as vowels
 %   \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}}.
+%   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}
@@ -677,8 +689,10 @@ consonants, though three of them are also used as vowels
 %   |madInaTiN| \arb[voc]{madInaTiN} \arb[trans]{madInaTiN}.
 % \end{quote}
 %
-% \paragraph{\arb[trans]{hamzaT}} It is written \meta{'}, its carrier
-% being determined by contextual analysis:
+% \paragraph{\arb[trans]{hamzaT}} It is written \meta{\texttt{'}}, its
+% carrier being determined by contextual analysis. In case one wishes
+% to bypass this mechanism, he can use the \enquote{quoting} feature
+% that is described below **.
 % \begin{quote}
 %   \textbf{Initial \arb[trans]{hamzaT}}: |'asaduN| \arb[voc]{'asaduN}
 %   \arb[trans]{'asaduN}, |'u_htuN| \arb[voc]{'u_htuN}
@@ -686,12 +700,127 @@ consonants, though three of them are also used as vowels
 %   \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' quri'a quri'A quri'Ani xubi'Ani} RAAH!
+%   \textbf{Middle \arb[trans]{hamzaT}}: |xA.ti'Ina|
+%   \arb[voc]{xA.ti'Ina} \arb[trans]{xA.ti'Ina}, |ru'UsuN|
+%   \arb[voc]{ru'UsuN}, \arb[trans]{ru'UsuN}, |xa.tI'aTuN|
+%   \arb[voc]{xa.tI'aTuN} \arb[trans]{xa.tI'aTuN}, |su'ila|
+%   \arb[voc]{su'ila} \arb[trans]{su'ila}, |'as'ilaTuN|
+%   \arb[voc]{'as'ilaTuN} \arb[trans]{'as'ilaTuN}, |mas'alaTuN|
+%   \arb[voc]{mas'alaTuN} \arb[trans]{mas'alaTuN}, |'as'alu|
+%   \arb[voc]{'as'alu} \arb[trans]{'as'alu}, |yatasA'alUna|
+%   \arb[voc]{yatasA'alUna} \arb[trans]{yatasA'alUna}, |murU'aTuN|
+%   \arb[voc]{murU'aTuN} \arb[trans]{murU'aTuN}, |ta'xIruN|
+%   \arb[fullvoc]{ta'xIruN} \arb[trans]{ta'xIruN}, |ta'axxara|
+%   \arb[voc]{ta'axxara} \arb[trans]{ta'axxara}, |ji'tu-ka|
+%   \arb[voc]{ji'tu-ka} \arb[trans]{ji'tu-ka}, |qA'iluN|
+%   \arb[voc]{qA'iluN} \arb[trans]{qA'iluN}.
+%
+%   From \textcite[i. 14 B]{Wright}:--- All consonants, whatsoever,
+%   not even \arb[trans]{'alif} \emph{hèmzatum} excepted, admit of
+%   being doubled and take \arb[trans]{ta^sdId}. Hence we speak and
+%   write |ra''AsuN| \arb[voc]{ra''AsuN} \arb[trans]{ra''AsuN},
+%   |sa''AluN| \arb[voc]{sa''AluN} \arb[trans]{sa''AluN}, |na''AjuN|
+%   \arb[voc]{na''AjuN} \arb[trans]{na''AjuN}.
+%
+%   \textbf{Final \arb[trans]{hamzaT}}: |xa.ta'uN| \arb[voc]{xa.ta'uN}
+%   \arb[trans]{xa.ta'uN}, |xa.ta'aN| \arb[voc]{xa.ta'aN}
+%   \arb[trans]{xa.ta'aN}, |xa.ta'iN| \arb[voc]{xa.ta'iN}
+%   \arb[trans]{xa.ta'iN}, |'aqra'u| \arb[voc]{'aqra'u}
+%   \arb[trans]{'aqra'u}, |taqra'Ina| \arb[voc]{taqra'Ina}
+%   \arb[trans]{taqra'Ina}, |taqra'Una| \arb[voc]{taqra'Una}
+%   \arb[trans]{taqra'Una}, |yaqra'na| \arb[fullvoc]{yaqra'na}
+%   \arb[trans]{yaqra'na}, |yaxba'Ani| \arb[voc]{yaxba'Ani}
+%   \arb[trans]{yaxba'Ani}, |xaba'A| \arb[voc]{xaba'A}
+%   \arb[trans]{xaba'A}, |xubi'a| \arb[voc]{xubi'a}
+%   \arb[trans]{xubi'a}, |xubi'UA| \arb[voc]{xubi'UA}
+%   \arb[trans]{xubi'UA}, |jA'a| \arb[voc]{jA'a} \arb[trans]{jA'a},
+%   |ridA'uN| \arb[voc]{ridA'uN} \arb[trans]{ridA'uN}, |ridA'aN|
+%   \arb[voc]{ridA'aN} \arb[trans]{ridA'aN}, |jI'a| \arb[voc]{jI'a}
+%   \arb[trans]{jI'a}, |radI'iN| \arb[voc]{radI'iN}
+%   \arb[trans]{radI'iN}, |sU'uN| \arb[voc]{sU'uN} \arb[trans]{sU'uN},
+%   |.daw'uN| \arb[voc]{.daw'uN} \arb[trans]{.daw'uN}, |qay'iN|
+%   \arb[voc]{qay'iN} \arb[trans]{qay'iN}.
+%
+%   |^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}, |al-^say'u|
+%   \arb[voc]{al-^say'u} \arb[trans]{al-^say'u}, |'a^syA'u|
+%   \arb[voc]{'a^syA'u} \arb[trans]{'a^syA'u}, |'a^syA'a|
+%   \arb[voc]{'a^syA'a} \arb[trans]{'a^syA'a}, |.zim'aN| \arb[voc]{.zim'aN}
+%   \arb[trans]{.zim'aN} 
 % \end{quote}
+%
+% \paragraph{\arb[trans]{maddaT}} At the beginning of a syllabe,
+% \arb[trans]{'alif} with \arb[trans]{hamzaT} and \arb[trans]{fat.haT}
+% (\arb[voc]{'a}) followed by \arb[trans]{'alifu 'l-maddi}
+% (\arb[trans]{'alif} of prolongation) or \arb[trans]{'alif} with
+% \arb[trans]{hamzaT} and \arb[trans]{jazmaT} (\arb[voc]{a"'"}) are
+% both represented in writing \arb[trans]{'alif} with
+% \arb[trans]{maddaT}: \arb[voc]{A"'} \parencite[see][i. 25
+% A--B]{Wright}.
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}[text only]
+  Hence one should keep to this distinction and encode |'a'kulu|
+  \arb[voc]{'a'kulu} \arb[trans]{'a'kulu} and |'AkiluN|
+  \arb[voc]{'AkiluN} \arb[trans]{'AkiluN} respectively.
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
+% \package{arabluatex} otherwise determines \arb[trans]{al-'alifu
+% 'l-mamdUdaTu} by context analysis.
 % 
+% \begin{quote}
+%   |'is'AduN| \arb[voc]{'is'AduN} \arb[trans]{'is'AduN}, |'AkilUna|
+%   \arb[voc]{'AkilUna} \arb[trans]{'AkilUna}, |'a'mannA|
+%   \arb[voc]{'a'mannA} \arb[trans]{'a'mannA}, |al-qur'Anu|
+%   \arb[voc]{al-qur'Anu} \arb[trans]{al-qur'Anu}.
+%
+%   |jA'a| \arb[voc]{jA'a} \arb[trans]{jA'a}, |yatasA'alUna|
+%   \arb[voc]{yatasA'alUna} \arb[trans]{yatasA'alUna}, |ridA'uN|
+%   \arb[voc]{ridA'uN} \arb[trans]{ridA'uN}, |xaba'A|
+%   \arb[voc]{xaba'A} \arb[trans]{xaba'A}, |yaxba'Ani|
+%   \arb[voc]{yaxba'Ani} \arb[trans]{yaxba'Ani}.
+% \end{quote}
+%
+% \paragraph{\arb[trans]{^saddaT}}
+% The \emph{necessary} \arb[trans]{ta^sdId} that always follows a
+% vowel, whether short or long \parencite[see][i. 15 A--B]{Wright}, is
+% encoded in writing the consonant that carries it twice:
+% \begin{quote}
+%   |`allaqa| \arb[voc]{`allaqa} \arb[trans]{`allaqa}, |mAdduN|
+%   \arb[voc]{mAdduN} \arb[trans]{mAdduN}, |'ammara|
+%   \arb[voc]{'ammara} \arb[trans]{ammara}, |murruN| \arb[voc]{murruN}
+%   \arb[trans]{murruN}
+% \end{quote}
 %
+% The same applies e.g. for the \emph{euphonic} \arb[trans]{ta^sdId}
+% with the letters \arb[novoc]{r}, \arb[novoc]{l}, \arb[novoc]{m},
+% \arb[novoc]{w}, \arb[novoc]{y} after \arb[voc]{n} with
+% \arb[trans]{jazmaT}, or with the letter \arb[voc]{t} after the
+% dentals (\arb[novoc]{_t}, \arb[novoc]{d}, \arb[novoc]{_d},
+% \arb[novoc]{.d}, \arb[novoc]{.t}, \arb[novoc]{.z}):
+% \begin{quote}
+%   |min rrabbi-hi| \arb[voc]{min rrabbi-hi}, \arb[trans]{min
+%   rrabbi-hi},\footnote{\arb[trans]{min rrabbi-hi} is actually wrong;
+%   the correct romanization should be \emph{mir rabbi-hi}. Please
+%   adapt. This feature will be implemented in the next release of
+%   \package{arabluatex}.} %
+%   |min llayliN| \arb[voc]{min llayliN} \arb[trans]{min
+%   llayliN},\footnote{For \emph{mil laylin}.}, %
+%   |'an yyaqtula| \arb[voc]{'an yyaqtula} \arb[trans]{'an
+%   yyaqtula},\footnote{For \emph{ʾay yaqtula}.}
+%
+%   The second kind of assimilation, e.g. \arb[voc]{labi_tttu} for
+%   \arb[voc]{labi_ttu} \arb[trans]{labi_ttu}, will be discarded here,
+%   as it is largely condemned by the
+%   grammarians \parencite[see][i. 16 B--C]{Wright}.
+% \end{quote}
+% 
 %
 % \StopEventually{}
 %