1 files changed, 86 insertions, 17 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 0541b69..eff2045 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -312,7 +312,7 @@
 %
 % \subsection{Options}
 % \package{arabluatex} may be loaded with four global options, each of
-% which may be overriden at any point of the document (see below **):
+% which may be overriden at any point of the document (see below **o):
 % 
 % \DescribeOption{voc}\hfill\arabluaverb{default}\\ In this mode,
 % which is the one selected by default, every short vowel written
@@ -332,7 +332,7 @@
 %
 % \DescribeOption{novoc}\\ None of the diacritics is showed in |novoc|
 % mode, unless otherwise specified (see \enquote{quoting} technique
-% below **).
+% below \vref{sec:quoting}).
 %
 % \DescribeOption{trans} \\ This mode transliterates the Arab\TeX\
 % input into one of the accepted standards. At present, two standards
@@ -428,7 +428,7 @@ consonants, though three of them are also used as vowels
 % Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
-% \endhead \footnotetext{See below **}
+% \endhead \footnotetext{See below **t}
 % \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| \\
@@ -473,7 +473,7 @@ consonants, though three of them are also used as vowels
 % Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
-% \endhead \footnotetext{See below **}
+% \endhead \footnotetext{See below **t}
 % \label{tab:arabtex-long-vowels}
 % \arb[novoc]{A} & \dmg{A} & \loc{A} & \verb|A| \\
 % \arb[novoc]{U} & \dmg{U} & \loc{U} & \verb|U| \\
@@ -516,7 +516,7 @@ consonants, though three of them are also used as vowels
 % Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
-% \endhead \footnotetext{See below **}
+% \endhead \footnotetext{See below **t}
 % \label{tab:arabtex-short-vowels}
 % \arb[voc]{Ba} & \dmg{Ba} & \loc{Ba} & \verb|a| \\
 % \arb[voc]{Bu} & \dmg{Bu} & \loc{Bu} & \verb|u| \\
@@ -533,7 +533,7 @@ consonants, though three of them are also used as vowels
 % 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 **}
+% below \vref{sec:quoting}}
 %
 % \iffalse
 %<*example>
@@ -553,7 +553,7 @@ consonants, though three of them are also used as vowels
 % \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 **);
+% below \vref{sec:quoting});
 % \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
@@ -692,7 +692,7 @@ consonants, though three of them are also used as vowels
 % \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 **.
+% that is described below \vref{sec:quoting}.
 % \begin{quote}
 %   \textbf{Initial \arb[trans]{hamzaT}}: |'asaduN| \arb[voc]{'asaduN}
 %   \arb[trans]{'asaduN}, |'u_htuN| \arb[voc]{'u_htuN}
@@ -755,12 +755,12 @@ consonants, though three of them are also used as vowels
 %   \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
+% \paragraph{\arb[trans]{maddaT}} \label{ref:madda}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}.
 %
@@ -1022,8 +1022,8 @@ consonants, though three of them are also used as vowels
 %   is needed by the |dmg| transliteration mode as in this mode any
 %   vowel at the commencement of a word preceded by a word that ends
 %   with a vowel, either short or long, is absorbed by this vowel
-%   viz. \arb[trans]{`al_A 'l-.tarIqi}. See ** on the \enquote{pipe}
-%   and ** on |dmg| mode.}  |al-l_ahu| \arb[fullvoc]{yA| al-l_ahu}
+%   viz. \arb[trans]{`al_A 'l-.tarIqi}. See **p on the \enquote{pipe}
+%   and **t on |dmg| mode.}  |al-l_ahu| \arb[fullvoc]{yA| al-l_ahu}
 %   \arb[trans]{yA| al-l_ahu},
 %   \verb+'a-fa|+\footnote{\label{fn:pipe-allah-02}See
 %   \cref{fn:pipe-allah-01}.}|-al-l_ahi| |la-ta.g`alanna|
@@ -1037,8 +1037,77 @@ consonants, though three of them are also used as vowels
 %   |'l-qA'ilu| \arb[fullvoc]{li-l-l_ahi 'l-qA'ilu}
 %   \arb[trans]{li-l-l_ahi 'l-qA'ilu}.
 % \end{quote}
-% 
 %
+% \paragraph{The conjunctive \arb[voc]{alla_dI}}
+% Although it is compounded of the article \arb[fullvoc]{al}, the
+% demonstrative letter \arb[novoc]{l} and the demonstrative pronoun
+% \arb[voc]{_dA}, both masculine and feminine forms that are written
+% defectively are encoded |alla_dI| and |allatI| respectively. Forms
+% starting with the connective \arb[trans]{'alif} are encoded
+% |'lla_dI| and |'llatI|:---
+% \begin{quote}
+%   |'a_hAfu| |mina| |'l-maliki| |'lla_dI| |ya.zlimu| |'l-nAsa|
+%   \arb[fullvoc]{'a_hAfu mina 'l-maliki 'lla_dI ya.zlimu 'l-nAsa}
+%   \arb[trans]{'a_hAfu mina 'l-maliki 'lla_dI ya.zlimu 'l-nAsa},
+%   |`udtu| |'l-^say_ha| |'lladI| |huwa| |marI.duN|
+%   \arb[fullvoc]{`udtu 'l-^say_ha 'lladI huwa marI.duN}
+%   \arb[trans]{`udtu 'l-^say_ha 'lladI huwa marI.duN}, |mA| |'anA|
+%   |bi-'lla_dI| |qA'iluN| |la-ka| |^say'aN| \arb[fullvoc]{mA 'anA
+%   bi-'lla_dI qA'iluN la-ka ^say'aN} \arb[trans]{mA 'anA bi-'lla_dI
+%   qA'iluN la-ka ^say'aN}.
+%
+%   |'ari-nA| |'lla_dayni| |'a.dallA-nA| |mina| |'l-jinni|
+%   |wa-'l-'insi| \arb[fullvoc]{'ari-nA 'lla_dayni 'a.dallA-nA mina
+%   'l-jinni wa-'l-'insi} \arb[trans]{'ari-nA 'lla_dayni 'a.dallA-nA
+%   mina 'l-jinni wa-'l-'insi}.
+% \end{quote}
+% The other forms are encoded regularly as |al-l| or |'l-l|:---
+% \begin{quote}
+%   |fa-'innA| |na_dkuru| |'l-.sawtayni| |'l-la_dayni| |rawaynA-humA|
+%   |`an| |ja.h.zaTa| \arb[fullvoc]{fa-'innA na_dkuru 'l-.sawtayni
+%   'l-la_dayni rawaynA-humA `an \cap{ja.h.zaTa}} \arb[trans]{fa-'innA
+%   na_dkuru 'l-.sawtayni 'l-la_dayni rawaynA-humA `an
+%   \cap{ja.h.zaTa}}.
+%
+%   And also: |al-la_dAni| \arb[fullvoc]{al-la_dAni}
+%   \arb[trans]{al-la_dAni}, |al-la_dayni| \arb[fullvoc]{al-la_dayni}
+%   \arb[trans]{al-la_dayni}, |al-latAni| \arb[fullvoc]{al-latAni}
+%   \arb[trans]{al-latAni}, |al-latayni| \arb[fullvoc]{al-latayni}
+%   \arb[trans]{al-latayni}, |al-lAtI| \arb[fullvoc]{al-lAtI}
+%   \arb[trans]{al-lAtI}, \verb+al-lA'|Ati+\footnote{Note here the
+%   \enquote{pipe} character \enquote*{\textbar}: as already
+%   stated \vpageref{ref:madda}, the sequence |'A| usually encodes
+%   \arb[trans]{'alif} with \arb[trans]{hamzaT} followed by
+%   \arb[trans]{'alif} of prolongation which is represented in writing
+%   \arb[trans]{'alif} with \arb[trans]{maddaT}: \arb[voc]{A"'}. The
+%   \enquote{pipe} character prevents this rule from being
+%   applied. See **p.}
+%   \arb[fullvoc]{al-lA'|Ati} \arb[trans]{al-lA'|Ati}, |al-lA'I|
+%   \arb[fullvoc]{al-lA'I} \arb[trans]{al-lA'I}, and so forth.
+% \end{quote}
+%
+% \subsection{Quoting}
+% \label{sec:quoting}
+% It is here referred to \enquote{quoting} after the package
+% \package{arabtex}.\footnote{See \textcite[22]{pkg:arabtex}} The
+% \enquote{quoting} mechanism of \package{arabluatex} is designed to
+% be very similar in effect to the one of \package{arabtex}.
+%
+% To start with an example, suppose one types the following in |novoc|
+% mode: \arb[novoc]{`ullima `ilma 'l-hay'aTi}; is it
+% \arb[fullvoc]{`ullima}, \emph{he was taught the science of
+% astronomy}, or \arb[fullvoc]{`allama}, \emph{he taught the science
+% of astronomy}? In order to disambiguate this clause, it may be
+% sensible to put a \arb[trans]{.dammaT} above the first \arb[voc]{`}:
+% \arb[novoc]{`"ullima `ilma 'l-hay'aTi}, which is achieved by
+% \enquote{quoting} the vowel |u|, like so: |`"ullima|, or, with no
+% other vowel than the required |u|: |`"ullm|.
+%
+% This is how the \enquote{quoting} mechanism works: metaphorically
+% speaking, it acts as a \emph{toggle switch}. If something, in a
+% given mode, is supposed to be visible, \enquote{quoting} hides it;
+% conversely, if it is supposed not to, it makes it visible.
+% 
 %
 % \StopEventually{}
 %