1 files changed, 220 insertions, 40 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index d82f720..833b0e8 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -46,7 +46,7 @@
 \setotherlanguage{arabic}
 \usepackage{varioref}
 \usepackage{hypdoc}
-\hypersetup{colorlinks, allcolors=blue, linktocpage=true}
+\hypersetup{unicode=true, colorlinks, allcolors=blue, linktocpage=true}
 \usepackage[toc,lot]{multitoc}
 \usepackage{paralist}
 \setdefaultitem{\textendash}{\textendash}{\textendash}{\textendash}
@@ -54,7 +54,7 @@
 \usepackage{quoting}
 \quotingsetup{noorphans, rightmargin=0pt}
 \renewcommand*{\quotingfont}{\footnotesize}
-\usepackage[format=hang,position=below]{caption}
+\usepackage[position=below]{caption}
 \usepackage{longtable}
 \usepackage{booktabs}
 \usepackage[defaultlines=2,all]{nowidow}
@@ -85,7 +85,9 @@
 \RecordChanges
 \begin{document}
   \DocInput{arabluatex.dtx}
+  \addcontentsline{toc}{section}{Change History}
   \PrintChanges
+  \addcontentsline{toc}{section}{Index}
   \PrintIndex
 \end{document}
 %</driver>
@@ -145,7 +147,7 @@
 %   lot of left-to-right commands intertwine with Arabic
 %   writing. \package{arabluatex} is able to process any Arab\TeX\
 %   input notation. Its output can be set in the same modes of
-%   vocalization as Arab\TeX\ ones, or in different roman
+%   vocalization as Arab\TeX, or in different roman
 %   transliterations. It further allows some typographical
 %   refinements.
 % \end{abstract}
@@ -309,8 +311,10 @@
 % \end{quoting}
 %
 % \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 **o):
+% \label{sec:options}
+% \package{arabluatex} may be loaded with four mutually exclusive
+% global options, each of which may be overriden at any point of the
+% document (see below \vref{sec:local-options}):
 % 
 % \DescribeOption{voc}\hfill\arabluaverb{default}\\ In this mode,
 % which is the one selected by default, every short vowel written
@@ -332,21 +336,14 @@
 % mode, unless otherwise specified (see \enquote{quoting} technique
 % below \vref{sec:quoting}).
 %
-% \DescribeOption{trans} \\ This mode transliterates the Arab\TeX\
-% input into one of the accepted standards. At present, two standards
-% are supported:
+% \DescribeOption{trans} \\ \label{ref:describe-trans}This mode
+% transliterates the Arab\TeX\ input into one of the accepted
+% standards. At present, two standards are supported (see below
+% \vref{sec:transliteration} for more details):
 % \begin{compactdesc}
-% \item[dmg] \emph{Deutsche Morgenländische Gesellschaft}, which was
-% adopted by the International Convention of Orientalist Scholars in
-% Rome in 1935.\footnote{See \textcite{dmg}.} |dmg| transliteration
-% convention is selected by default;
-% \item[loc] \emph{Library of Congress}: this standard is part of a
-%   large set of standards for romanization of non-roman scripts
-%   adopted by the American Library Association and the Library of
-%   Congress.\footnote{See
-%   \url{http://www.loc.gov/catdir/cpso/roman.html} for the
-%   \href{http://www.loc.gov/catdir/cpso/romanization/arabic.pdf}{source
-%   document concerning Arabic language}.}
+% \item[dmg] \emph{Deutsche Morgenländische Gesellschaft}, which is
+%   selected by default;
+% \item[loc] \emph{Library of Congress}.
 % \end{compactdesc}
 % More standards will be included in future releases of
 % \package{arabluatex}.
@@ -411,6 +408,27 @@ consonants, though three of them are also used as vowels
 % \fi
 % \setquotestyle{english}
 %
+% \subsubsection{Local options}
+% \label{sec:local-options}
+% As seen above in \vref{sec:options}, \package{arabluatex} may be
+% loaded with four mutually exclusive global options: |voc| (which is
+% the default option), |fullvoc|, |novoc| and |trans|. Whatever choice
+% has been made globally, it may be overriden at any point of the
+% document, as the \cs{arb} command may take any of the |voc|,
+% |fullvoc|, |novoc| or |trans| modes as optional arguments, like
+% so:---
+% \begin{compactitem}
+% \item \DescribeOption{voc} \cs{arb}|[voc]|\marg{Arabic text};
+% \item \DescribeOption{fullvoc} \cs{arb}|[fullvoc]|\marg{Arabic text};
+% \item \DescribeOption{novoc} \cs{arb}|[novoc]|\marg{Arabic text};
+% \item \DescribeOption{trans} \cs{arb}|[trans]|\marg{Arabic text}.
+% \end{compactitem}
+%
+% The same optional arguments may be passed to the environment |arab|:
+% one may have \cs{begin}|{arab}|\oarg{mode}|...|\cs{end}|{arab}|,
+% where \meta{mode} may be any of |voc|, |fullvoc|, |novoc| or
+% |trans|.
+%
 %\section{Standard Arab\TeX\ input}
 %\subsection{Consonants}
 % \Cref{tab:arabtex-consonants} gives the Arab\TeX\ equivalents for
@@ -422,13 +440,17 @@ consonants, though three of them are also used as vowels
 %   \SetTranslitConvention{loc}%
 %   \arb[trans]{#1}\SetTranslitConvention{dmg}}
 % \begin{longtable}{llll}
+% \captionlistentry{Arab\TeX\ consonants}\\[-1em]
 % \toprule
 % Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
-% \captionlistentry{Arab\TeX\ consonants}
 % \endfirsthead
-% \endhead \footnotetext{See below **t}
+% \toprule
+% Letter & \multicolumn{2}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \endhead \footnotetext{See below \vref{sec:transliteration}.}
 % \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| \\
@@ -469,13 +491,17 @@ consonants, though three of them are also used as vowels
 % \Cref{tab:arabtex-long-vowels} gives the Arab\TeX\ equivalents for
 % the Arabic long vowels. 
 % \begin{longtable}{llll}
+% \captionlistentry{Arab\TeX\ long vowels}\\[-1em]
 % \toprule
 % 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}
+% \toprule
+% Letter & \multicolumn{2}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \endhead \footnotetext{See below \vref{sec:transliteration}.}
 % \label{tab:arabtex-long-vowels}
 % \arb[novoc]{A} & \dmg{A} & \loc{A} & \verb|A| \\
 % \arb[novoc]{U} & \dmg{U} & \loc{U} & \verb|U| \\
@@ -514,13 +540,17 @@ consonants, though three of them are also used as vowels
 % \Cref{tab:arabtex-short-vowels} gives the Arab\TeX\ equivalents for
 % the Arabic short vowels.
 % \begin{longtable}{llll}
+% \captionlistentry{Arab\TeX\ short vowels}\\[-1em]
 % \toprule
 % 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}
+% \toprule
+% Letter & \multicolumn{2}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \endhead \footnotetext{See below \vref{sec:transliteration}.}
 % \label{tab:arabtex-short-vowels}
 % \arb[voc]{Ba} & \dmg{Ba} & \loc{Ba} & \verb|a| \\
 % \arb[voc]{Bu} & \dmg{Bu} & \loc{Bu} & \verb|u| \\
@@ -537,7 +567,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 \vref{sec:quoting}}
+% below \vref{sec:quoting}.}
 %
 % \iffalse
 %<*example>
@@ -919,7 +949,7 @@ consonants, though three of them are also used as vowels
 %     \arb[novoc]{l} of the article also falls away, but
 %     \package{arabluatex} is aware of that: |li-l-laylaTi|
 %     \arb[fullvoc]{li-l-laylaTi} \arb[trans]{li-l-laylaTi}.
-%   \item \arb[trans]{la-}: the same applies for the affirmative
+%   \item \arb[trans]{la-}: the same applies to the affirmative
 %   particle \arb[fullvoc]{la}: |la-l-.haqqu|
 %   \arb[fullvoc]{la-l-.haqqu} \arb[trans]{la-l-.haqqu}.
 % \item With the other particles, \arb[trans]{'alifu 'l-wa.sli} is
@@ -944,12 +974,16 @@ consonants, though three of them are also used as vowels
 %   \arb[trans]{lawi istaqbala}.
 %
 %   \textbf{Other cases}: |'awi| |ismu-hu| \arb[fullvoc]{'awi ismu-hu}
-%   \arb[trans]{'awi ismu-hu}, |.hunaynu| |ibnu| |'is.h_aqa|
-%   \arb[fullvoc]{.hunaynu ibnu 'is.h_aqa} \arb[trans]{\cap{.h}unaynu
-%   ibnu \cap{'is.h_aqa}}, |imru'u| |'l-qaysi| \arb[fullvoc]{imru'u
-%   'l-qaysi} \arb[trans]{\cap{i}mru'u \cap{'l-qaysi}}, |la-aymunu|
-%   |'l-l_ahi| \arb[fullvoc]{la-aymunu 'l-l_ahi} \arb[trans]{la-aymunu
-%   'l-l_ahi}.
+%   \arb[trans]{'awi ismu-hu}, |zayduN| |ibnu| |`amriNU|
+%   \arb[fullvoc]{\cap{z}ayduN ibnu \cap{`amriNU}}
+%   \arb[trans]{\cap{z}ayduN ibnu
+%   \cap{`amriNU}},\footnote{\enquote{Zayd is the son of ʿAmr}: the
+%   second noun is not in apposition to the first, but form part of
+%   the predicate. Hence \arb[voc]{zayduN ibnu `amriNU} and not
+%   \arb[voc]{zaydu bnu `amriNU}, \enquote{Zayd, son of ʿAmr}.}
+%   |imru'u| |'l-qaysi| \arb[fullvoc]{imru'u 'l-qaysi}
+%   \arb[trans]{\cap{i}mru'u \cap{'l-qaysi}}, |la-aymunu| |'l-l_ahi|
+%   \arb[fullvoc]{la-aymunu 'l-l_ahi} \arb[trans]{la-aymunu 'l-l_ahi}.
 % \end{quote}
 %
 % \subparagraph{\arb[trans]{'alifu 'l-wa.sli} preceded by a long
@@ -1030,8 +1064,8 @@ consonants, though three of them are also used as vowels
 %   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 \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},
+%   \enquote{pipe} and **td 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}
@@ -1226,13 +1260,17 @@ consonants, though three of them are also used as vowels
 % context. \Cref{tab:quoted-hamza} gives the equivalents for all the
 % possible carriers the \arb[trans]{hamzaT} may take:
 % \begin{longtable}{llll}
+% \captionlistentry{\enquote{Quoted} \arb[trans]{hamzaT}}\\[-1em]
 % \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}
+% \toprule
+% Letter & \multicolumn{2}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \endhead \footnotetext{See below \vref{sec:transliteration}.}
 % \label{tab:quoted-hamza}
 % \arb[novoc]{|"'} & \dmg{|"'} & \loc{|"'} & \verb+|"'+ \\
 % \arb[novoc]{A"'} & \dmg{A"'} & \loc{A"'} & \verb|A"'| \\
@@ -1288,6 +1326,20 @@ consonants, though three of them are also used as vowels
 % \meta{n} prevents the necessary \arb[trans]{ta^sdId} rule
 % (\cpageref{ref:necessary-tashdid}) from being applied.
 %
+% \subsection{\texorpdfstring{Stretching characters: the
+% \arb[trans]{.ta.twIl}}{Stretching characters: the ṭaṭwīl}}
+% \label{sec:tatwil}
+% A double hyphen \meta{-\,-} stretches the ligature in which one
+% letter is bound to another. Although it is always better to rely on
+% automatic stretching, this technique may be used to a modest extent,
+% especially to increase legibility of letters an diacritics which
+% stand one above the other:--
+% \begin{quote}
+%   |.hunaynu| |bnu| |'is.h--_aqa| \arb[voc]{.hunaynu bnu 'is.h--_aqa}
+%   \arb[trans]{\cap{.hunaynu} bnu \cap{'is.h--_aqa}}
+% \end{quote}
+% 
+%
 % \subsection{Digits}
 % \label{sec:digits}
 % \subsubsection{Numerical figures}
@@ -1305,7 +1357,7 @@ consonants, though three of them are also used as vowels
 % 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
+% \arb[trans]{'abjad} numbers are usually distinguished from the
 % surrounding words by a stroke placed over them.
 %
 % For time being, \package{arabluatex} inserts those numbers with the
@@ -1337,7 +1389,7 @@ consonants, though three of them are also used as vowels
 % \fi
 \begin{arabluacode}[text only]
   Apart from this case, \package{arabluatex} makes no use of
-  \package{polyglossia}. The support for the \arb[trans]{abjad}
+  \package{polyglossia}. The support for the \arb[trans]{'abjad}
   numbering system is planned for inclusion in a future version of
   \package{arabluatex}.
 \end{arabluacode}
@@ -1345,6 +1397,134 @@ consonants, though three of them are also used as vowels
 %</example>
 % \fi
 %
+% \subsection{Additional characters}
+% \label{sec:additional-letters}
+% In the manuscripts, the unpointed letters, \arb[trans]{al-.hurUfu
+% 'l-muhmalaTu}, are sometimes further distinguished from the pointed
+% by various contrivances, as explained in \textcite[i. 4
+% B--C]{Wright}. One may find these letters written in a smaller size
+% below the line, or with a dot or another mark below. As representing
+% all the possible contrivances leads to much complexity and also
+% needs to be agreed among scholars, new ways of encoding them will be
+% proposed and gradually included as \package{arabluatex} will mature.
+%
+% For the time being, the following is included:---
+% \begin{longtable}{llll}
+% \captionlistentry{Additional Arabic codings}\\[-1em]
+% \toprule
+% Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
+% & Arab\TeX\ notation \\
+%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \endfirsthead
+% \toprule
+% Letter & \multicolumn{2}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \endhead \footnotetext{See below \vref{sec:transliteration}.}
+% \label{tab:additional-arabic-codings}
+% \arb[novoc]{.b} & \dmg{.b} & \loc{.b} & |.b| \\
+% \arb[novoc]{^d} & \dmg{^d} & \loc{^d} & |^d| \\
+% \arb[novoc]{.f} & \dmg{.f} & \loc{.f} & |.f| \\
+% \arb[novoc]{.q} & \dmg{.q} & \loc{.q} & |.q| \\
+% \arb[novoc]{.k} & \dmg{.k} & \loc{.k} & |.k| \\
+% \arb[novoc]{.n} & \dmg{.n} & \loc{.n} & |.n| \\
+% \arb[novoc]{((} & \dmg{((} & \loc{((} & |((| \\
+% \arb[novoc]{))} & \dmg{))} & \loc{))} & |))| \\
+% \bottomrule
+% \caption*{\Cref*{tab:additional-arabic-codings}: Additional Arabic
+% codings}
+% \end{longtable}
+% 
+% \begin{quote}
+%   |'afAman.tUs| Gal.(M) |.fmn.n.ts| (sic) Gal.(E1),
+%   \arb[novoc]{'afAman.tUs} Gal.(M) \arb[novoc]{.fmn.n.ts} (sic)
+%   Gal.(E1), \arb[trans]{'afAman.tUs} Gal.(M) \arb[trans]{.fmn.n.ts}
+%   (sic) Gal.(E1).
+% \end{quote}
+%
+% \subsection{Arabic emphasis}
+% \label{sec:emphasis}
+% As already seen in \vref{sec:abjad}, the \arb[trans]{'abjad} numbers
+% are distinguished from the surrounding words by a stroke placed
+% over them. This technique is used to distinguish further words that
+% are proper names or book titles.
+%
+% \DescribeMacro{aemph} One may use the command \cs{aemph}\marg{Arabic
+% text} to use the same technique to emphasize words, like so:---
+% \begin{quote}
+%   |\abjad{45}:| |kitAbu-hu| |\aemph{fI| |'l-`AdAti}|
+%   \arb[voc]{\abjad{45}: kitAbu-hu \aemph{fI 'l-`AdAti}}
+%   \arb[trans]{45: kitAbu-hu fI 'l-\cap{`AdAti}}.
+% \end{quote}
+%
+% \section{Transliteration}
+% \label{sec:transliteration}
+% It may be more appropriate to speak of \enquote{romanization} than
+% \enquote{transliteration} of Arabic. As seen above in
+% \cref{sec:options} \vpagerefrange{sec:options}{sec:local-options},
+% the \enquote{transliteration mode} may be selected globally or locally.
+%
+% This mode transliterates the Arab\TeX\ input into one of the
+% accepted standards. At said above \vpageref{ref:describe-trans}, two
+% standards are supported at present:
+% \begin{compactdesc}
+% \item[dmg] \emph{Deutsche Morgenländische Gesellschaft}, which was
+% adopted by the International Convention of Orientalist Scholars in
+% Rome in 1935.\footnote{See \textcite{dmg}.} |dmg| transliteration
+% convention is selected by default;
+% \item[loc] \emph{Library of Congress}: this standard is part of a
+%   large set of standards for romanization of non-roman scripts
+%   adopted by the American Library Association and the Library of
+%   Congress.\footnote{See
+%   \url{http://www.loc.gov/catdir/cpso/roman.html} for the
+%   \href{http://www.loc.gov/catdir/cpso/romanization/arabic.pdf}{source
+%   document concerning Arabic language}.}
+% \end{compactdesc}
+% More standards will be included in future releases of
+% \package{arabluatex}.
+%
+% \paragraph{Convention} \DescribeMacro{SetTranslitConvention} The
+% transliteration mode, which is set to |dmg| by default, may be
+% changed at any point of the document by the command
+% \cs{SetTranslitConvention}\marg{mode}, where \meta{mode} may be
+% either |dmg| or |loc|. This command is also accepted in the preamble
+% should one wish to set the transliteration mode globally, eg.:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+\usepackage{arabluatex}
+\SetTranslitConvention{loc}
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Style} \DescribeMacro{SetTranslitStyle} Any
+% transliterated Arabic text is printed in italics by default. This
+% also can be changed either globally in the preamble or locally at
+% any point of the document by the command
+% \cs{SetTranslitStyle}\marg{style}, where \meta{style} may be any
+% font shape selection command, eg. \cs{upshape}, \cs{itshape},
+% \cs{slshape}, and so forth. Any specific font may also be selected
+% using the font-selecting commands of the \package{fontspec} package.
+%
+% \paragraph{Proper names} \DescribeMacro{cap} Proper names or book
+% titles that must have their first letters uppercased may be passed
+% as arguments to the command \cs{cap}\marg{word}. \cs{cap} is a
+% clever command, as it will give the definite article
+% \arb[trans]{al-} in lower case in all positions. Moreover, if the
+% inital letter, apart from the article, cannot be uppercased,
+% viz. \arb[trans]{'} or \arb[trans]{`}, the letter next to it will be
+% uppercased:---
+% \begin{quote}
+%   |\cap{.hunaynu}| |bnu| |\cap{'is.h_aqa}| \arb[voc]{\cap{.hunaynu}
+%   bnu \cap{'is.h_aqa}} \arb[trans]{\cap{.hunaynu} bnu
+%   \cap{'is.h_aqa}}, |\cap{`u_tm_anu}| \arb[voc]{\cap{`u_tm_anu}}
+%   \arb[trans]{\cap{`u_tm_anu}}.
+% \end{quote}
+% 
+%
 % \StopEventually{}
 %
 % \section{Implementation}
@@ -1482,7 +1662,7 @@ consonants, though three of them are also used as vowels
 \endinput
 %    \end{macrocode}
 %
-% \printbibliography
+% \printbibliography[heading=bibintoc]
 %
 % \iffalse
 %</package>