small bugfix regarding madda; still documenting

1 files changed, 171 insertions, 36 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index ce814f9..d82f720 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -41,16 +41,20 @@
 \setsansfont{Libertinus Sans}
 \setmonofont[Scale=.9]{Libertinus Mono}
 \usepackage{arabluatex}[2016/01/26]
+\usepackage{polyglossia}
+\setdefaultlanguage{english}
+\setotherlanguage{arabic}
 \usepackage{varioref}
 \usepackage{hypdoc}
-\hypersetup{colorlinks, allcolors=blue}
-\usepackage{multicol}
+\hypersetup{colorlinks, allcolors=blue, linktocpage=true}
+\usepackage[toc,lot]{multitoc}
 \usepackage{paralist}
 \setdefaultitem{\textendash}{\textendash}{\textendash}{\textendash}
 \usepackage{cleveref}
 \usepackage{quoting}
 \quotingsetup{noorphans, rightmargin=0pt}
 \renewcommand*{\quotingfont}{\footnotesize}
+\usepackage[format=hang,position=below]{caption}
 \usepackage{longtable}
 \usepackage{booktabs}
 \usepackage[defaultlines=2,all]{nowidow}
@@ -128,17 +132,10 @@
 % \date{}
 % 
 % \maketitle
-% \begin{multicols}{2}[\section*{\large Contents}]\footnotesize
-%   \makeatletter
-%   \@starttoc{toc}
-%   \makeatother
-% \end{multicols}
-% \begin{multicols}{2}[\section*{\large List of tables}]
 % \footnotesize
-%   \makeatletter
-%   \@starttoc{lot}
-%   \makeatother
-% \end{multicols}
+% \tableofcontents
+% \listoftables
+% \normalsize
 % 
 % \begin{abstract}
 %   This package provides for \LuaLaTeX\ an Arab{\TeX}-like interface
@@ -279,7 +276,8 @@
 % complain if you try to compile your document with another
 % engine. That aside, \package{arabluatex} does not load packages such
 % as \package{polyglossia} or \package{luabidi}. It can work with
-% \package{polyglossia} though, but does not require it.
+% \package{polyglossia} though, but does not require it.\footnote{With
+% one exception: see \vref{sec:abjad}.}
 %
 % \paragraph{Font setup}
 % If you wish to use your own Arabic font, you can define it before
@@ -428,6 +426,8 @@ consonants, though three of them are also used as vowels
 % Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \captionlistentry{Arab\TeX\ consonants}
+% \endfirsthead
 % \endhead \footnotetext{See below **t}
 % \label{tab:arabtex-consonants}
 % \arb[novoc]{a}\footnote{For \arb[trans]{'alif} as a consonant, see
@@ -461,7 +461,7 @@ consonants, though three of them are also used as vowels
 % \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)}
+% \caption*{\Cref*{tab:arabtex-consonants}: Standard Arab\TeX\ (consonants)}
 % \end{longtable}
 %
 % \subsection{Vowels}
@@ -473,6 +473,8 @@ consonants, though three of them are also used as vowels
 % Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \captionlistentry{Arab\TeX\ long vowels}
+% \endfirsthead
 % \endhead \footnotetext{See below **t}
 % \label{tab:arabtex-long-vowels}
 % \arb[novoc]{A} & \dmg{A} & \loc{A} & \verb|A| \\
@@ -484,7 +486,7 @@ consonants, though three of them are also used as vowels
 % \arb[novoc]{B_u} & \dmg{B_u} & \loc{B_u} & \verb|_u| \\
 % \arb[novoc]{B_i} & \dmg{B_i} & \loc{B_i} & \verb|_i| \\
 % \bottomrule
-% \caption[Arab\TeX\ long vowels]{Standard Arab\TeX\ (long vowels)}
+% \caption*{\Cref*{tab:arabtex-long-vowels}: Standard Arab\TeX\ (long vowels)}
 % \end{longtable}
 %
 % \begin{quoting}
@@ -516,6 +518,8 @@ consonants, though three of them are also used as vowels
 % Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \captionlistentry{Arab\TeX\ short vowels}
+% \endfirsthead
 % \endhead \footnotetext{See below **t}
 % \label{tab:arabtex-short-vowels}
 % \arb[voc]{Ba} & \dmg{Ba} & \loc{Ba} & \verb|a| \\
@@ -525,7 +529,7 @@ consonants, though three of them are also used as vowels
 % \arb[voc]{BuN} & \dmg{BuN} & \loc{BuN} & \verb|uN| \\
 % \arb[voc]{BiN} & \dmg{BiN} & \loc{BiN} & \verb|iN| \\
 % \bottomrule
-% \caption[Arab\TeX\ short vowels]{Standard Arab\TeX\ (short vowels)}
+% \caption*{\Cref*{tab:arabtex-short-vowels}: Standard Arab\TeX\ (short vowels)}
 % \end{longtable}
 %
 % Whether Arabic texts are vocalized or not is essentially a matter of
@@ -690,10 +694,11 @@ 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{\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 \vref{sec:quoting}.
+% \paragraph{\arb[trans]{hamzaT}} \label{ref:hamza}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 in
+% \vref{sec:quoting}.
 % \begin{quote}
 %   \textbf{Initial \arb[trans]{hamzaT}}: |'asaduN| \arb[voc]{'asaduN}
 %   \arb[trans]{'asaduN}, |'u_htuN| \arb[voc]{'u_htuN}
@@ -796,7 +801,8 @@ consonants, though three of them are also used as vowels
 % \paragraph{\arb[trans]{^saddaT}}
 % \arb[trans]{ta^sdId} is either \emph{necessary} or \emph{euphonic}.
 %
-% \subparagraph{The necessary \arb[trans]{ta^sdId}} always follows a
+% \subparagraph{The necessary
+% \arb[trans]{ta^sdId}} \label{ref:necessary-tashdid}always follows a
 % vowel, whether short or long \parencite[see][i. 15 A--B]{Wright}. It
 % is encoded in writing the consonant that carries it twice:
 % \begin{quote}
@@ -1023,9 +1029,9 @@ 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 **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},
+%   viz. \arb[trans]{`al_A 'l-.tarIqi}. See \vref{sec:pipe} 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|
 %   \arb[fullvoc]{'a-fa|-al-l_ahi la-ta.g`alanna}
@@ -1075,16 +1081,17 @@ consonants, though three of them are also used as vowels
 %   \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]{al-lAtI},
+%   \verb+al-lA'|Ati+\footnote{\label{fn:pipe-madda}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.
+%   applied. See \vref{sec:pipe}.}  \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}
@@ -1132,8 +1139,9 @@ consonants, though three of them are also used as vowels
 %   \arb[novoc]{wa-'innA sawfa tudriku-nA 'l-manAyA muqadd"araT"aN},
 %   \arb[trans]{wa-'innA sawfa tudriku-nA 'l-manAyA muqadd"araT"aN}.
 % \end{quote}
-% \item If no vowel follows the straight double quote, then a
-%   \arb[trans]{sukUn} is put above the preceding consonant:---
+% \item \label{ref:quoted-sukun-b}If no vowel follows the straight
+%   double quote, then a \arb[trans]{sukUn} is put above the preceding
+%   consonant:---
 % \begin{quote}
 %   |qAla isma`"| \arb[novoc]{qAla isma`"} \arb[trans]{qAla isma`"},
 %   |jA'at"| |hinduN| \arb[voc]{jA'at" hinduN} \arb[trans]{jA'at"
@@ -1191,7 +1199,8 @@ consonants, though three of them are also used as vowels
 %     |mini| |imra'aTiN| \arb[voc]{mA jA'at" mini imra'aTiN}
 %     \arb[trans]{mA jA'at" mini imra'aTiN}, |kam"| |qad"| |ma.dat"|
 %     |min"| |laylaTiN| \arb[voc]{kam" qad" ma.dat" min" laylaTiN}
-%     \arb[trans]{kam" qad" ma.dat" min" laylaTiN}.
+%     \arb[trans]{kam" qad" ma.dat" min"
+%     laylaTiN}.\label{ref:quoted-sukun-e}
 %   \end{quote}
 % \end{enumerate}
 %
@@ -1199,16 +1208,142 @@ consonants, though three of them are also used as vowels
 % In this mode, \enquote{quoting} may be used to take away any short
 % vowel (or \arb[trans]{tanwIn}, as seen above) or any
 % \arb[trans]{sukUn}:---
-% \begin{quote}
+% \begin{quote}\label{ref:qrannun-full}
 %   |al-jamru| |'l-.sayfiyyu| |'lla_dI| |kAna| \verb+bi-q"rAn"|nUna+
 %   \arb[fullvoc]{al-jamru 'l-.sayfiyyu 'lla_dI kAna
 %   \cap{bi-q"rAn"|nUna}} \arb[trans]{al-jamru 'l-.sayfiyyu 'lla_dI
 %   kAna \cap{bi-q"rAn"|nUna}}.
 % \end{quote}
 %
-% \subsubsection{Quoting the \arb[trans]{hamzaT}}
+% \subsubsection{\texorpdfstring{Quoting the
+% \arb[trans]{hamzaT}}{Quoting the hamza}}
 % \label{sec:quoting-hamza}
-% 
+% As said above in \vref{ref:hamza}, the \arb[trans]{hamzaT} is always
+% written \meta{\texttt{'}}, its carrier being determined by contextual
+% analysis. \enquote{Quoting} this straight single quote character
+% like so: \meta{\texttt{"'}} allows to determine the carrier of the
+% \arb[trans]{hamzaT} freely, without any consideration for the
+% context. \Cref{tab:quoted-hamza} gives the equivalents for all the
+% possible carriers the \arb[trans]{hamzaT} may take:
+% \begin{longtable}{llll}
+% \toprule
+% Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
+% & Arab\TeX\ notation \\
+%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \captionlistentry{\enquote{Quoted} \arb[trans]{hamzaT}}
+% \endfirsthead
+% \endhead \footnotetext{See below **t}
+% \label{tab:quoted-hamza}
+% \arb[novoc]{|"'} & \dmg{|"'} & \loc{|"'} & \verb+|"'+ \\
+% \arb[novoc]{A"'} & \dmg{A"'} & \loc{A"'} & \verb|A"'| \\
+% \arb[novoc]{a"'} & \dmg{a"'} & \loc{a"'} & \verb|a"'| \\
+% \arb[novoc]{u"'} & \dmg{u"'} & \loc{u"'} & \verb|u"'| \\
+% \arb[novoc]{w"'} & \dmg{w"'} & \loc{w"'} & \verb|w"'| \\
+% \arb[novoc]{i"'} & \dmg{i"'} & \loc{i"'} & \verb|i"'| \\
+% \arb[novoc]{y"'} & \dmg{y"'} & \loc{y"'} & \verb|y"'| \\
+% \bottomrule
+% \caption*{\Cref*{tab:quoted-hamza}: \enquote{Quoted} \arb[trans]{hamzaT}}
+% \end{longtable}
+%
+% As one can see from \vref{tab:quoted-hamza}, the carrier of the
+% \arb[trans]{hamzaT} is inferred from the letter that precedes the
+% straight double quote \meta{\texttt{"}}. Of course, any
+% \enquote{quoted} \arb[trans]{hamzaT} may take a short vowel, which
+% is to be written \emph{after} the Arab\TeX\ equivalent for the
+% \arb[trans]{hamzaT} itself, namely \meta{\texttt{'}}. For example,
+% \arb[voc]{w"'a} is encoded \meta{\texttt{w"'a}}, while
+% \arb[voc]{w"'"} is encoded \meta{\texttt{w"'"}}. In the latter
+% example, the second straight double quote encodes the
+% \arb[trans]{sukUn} in |voc| mode in accordance with the rule laid
+% above \vpagerefrange{ref:quoted-sukun-b}{ref:quoted-sukun-e}.
+% \begin{quote}
+%   |'a`dA'ukum| \arb[fullvoc]{'a`dA'ukum} \arb[trans]{'a`dA'ukum},
+%   \verb+'a`dA|"'ukum+ \arb[fullvoc]{'a`daA"'|"'ukum}
+%   \arb[trans]{'a`dA|"'ukum}, |'a`dA'ikum| \arb[fullvoc]{'a`dA'ikum}
+%   \arb[trans]{'a`dA'ikum}, \verb+'a`dA|"'ikum+
+%   \arb[fullvoc]{'a`daA"'|"'ikum} \arb[trans]{'a`dA|"'ikum}.
+% \end{quote}
+%
+% \subsection{The \enquote{pipe} character (\textbar)}
+% \label{sec:pipe}
+% In the terminology of Arab\TeX, the \enquote{pipe} character
+% \enquote*{\textbar} is referred to as the \enquote{invisible
+% consonant}. Hence, as already seen above in
+% \vref{sec:quoting-hamza}, its usage to encode the
+% \arb[trans]{hamzaT} alone, with no carrier: \verb+|"'+
+% \arb[novoc]{|"'}.
+%
+% Aside from that usage, the \enquote{pipe} character is used to
+% prevent almost any of the contextual analysis rules that are
+% described above from being applied. Two examples have already been
+% given to demonstrate how this particular mechanism works in
+% \vref{fn:pipe-allah-01} and in \vref{fn:pipe-madda}. One more example
+% follows:---
+% \begin{quote}
+%   \verb+bi-qrAn|nUna+ \arb[voc]{\cap{bi-qrAn|nUna}}
+%   \arb[trans]{\cap{bi-qrAn|nUna}}, \enquote{in Crannon} (Thessaly,
+%   Greece).\footnote{See more context \vpageref{ref:qrannun-full}.}
+% \end{quote}
+% As one can see, the \enquote{pipe} character between the two
+% \meta{n} prevents the necessary \arb[trans]{ta^sdId} rule
+% (\cpageref{ref:necessary-tashdid}) from being applied.
+%
+% \subsection{Digits}
+% \label{sec:digits}
+% \subsubsection{Numerical figures}
+% \label{sec:numerical-figures}
+% The \emph{Indian numbers}, \arb[trans]{al-raqamu 'l-hindiyyu}, are
+% ten in number, and they are compounded in exactly the same way as
+% our numerals:---
+% \begin{quote}
+%   |1874| \arb[voc]{1874}, |123-456,789| \arb[voc]{123-456,789}, |fI|
+%   |sanaTi| |1024| \arb[voc]{fI sanaTi 1024}
+% \end{quote}
+%
+% \subsubsection{The \emph{abjad}}
+% \label{sec:abjad}
+% The numbers may also be expressed with letters from right to left
+% arranged in accordance with the order of the Hebrew and Aramaic
+% alphabets \parencite[see][i. 28 B--C]{Wright}. The
+% \arb[trans]{Adjad} numbers are usually distinguished from the
+% surrounding words by a stroke placed over them.
+%
+% For time being, \package{arabluatex} inserts those numbers with the
+% help of \package{polyglossia}. If you wish to use the
+% \arb[trans]{abjad} system, put in your preamble:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+\usepackage{polyglossia}
+\setdefaultlanguage{english} % please adapt
+\setotherlanguage{arabic} % to enable the 'abjad' numbers
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi %
+% \DescribeMacro{abjad} Then you may use the command
+% \cs{abjad}\marg{number} in any of the |voc|, |fullvoc| and |novoc|
+% modes, where \meta{number} may be any number between 1 and 1999,
+% like so:---
+% \begin{quote}
+%   |\abjad{45}| |kitAbu-hu| |fI| |'l-`AdAti| \arb[voc]{\abjad{45}
+%   kitAbu-hu fI 'l-`AdAti} \arb[trans]{45 kitAbu-hu fI
+%   'l-`AdAti}.
+% \end{quote}
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}[text only]
+  Apart from this case, \package{arabluatex} makes no use of
+  \package{polyglossia}. The support for the \arb[trans]{abjad}
+  numbering system is planned for inclusion in a future version of
+  \package{arabluatex}.
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
 %
 % \StopEventually{}
 %