1 files changed, 208 insertions, 33 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index ef1a9a6..b388438 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -46,14 +46,21 @@
 \usepackage{multicol}
 \usepackage{paralist}
 \setdefaultitem{\textendash}{\textendash}{\textendash}{\textendash}
+\usepackage{varioref}
+\usepackage{quoting}
+\quotingsetup{noorphans, rightmargin=0pt}
+\renewcommand*{\quotingfont}{\footnotesize}
 \usepackage{longtable}
 \usepackage{booktabs}
 \usepackage{tikz}
-\usepackage[breakable, skins,listings,xparse]{tcolorbox}
-\DeclareTCBListing{arabluacode}{s}{colback=white, boxrule=.15mm,
-  colframe=red!50!white, listing options={style=tcblatex,
+\usepackage[breakable, skins, listings, xparse]{tcolorbox}
+\DeclareTCBListing{arabluacode}{s O{}}{colback=white, boxrule=.15mm,
+  colframe=red!50!white, breakable, listing options={style=tcblatex,
     numbers=left, numberstyle=\tiny}, IfBooleanTF={#1}{listing side
-    text}{}}
+    text}{#2}}
+\DeclareTCBListing{arabluaverbatim}{}{colback=white, boxrule=.15mm,
+  colframe=red!50!white, breakable, listing options={style=tcblatex,
+    numbers=left, numberstyle=\tiny}, listing only}
 \DeclareTotalTCBox{\arabluaverb}{v}{verbatim, colback=white,
     boxrule=.15mm, colframe=red!50!white}{#1}
 \DeclareTotalTCBox{\arabluabox}{m}{left=0mm, right=0mm, top=0mm,
@@ -61,6 +68,9 @@
     colframe=red!50!white}{#1}
 \newcommand{\package}[1]{\textsf{#1}\index{#1=#1 (package)}}
 \usepackage{csquotes}
+\DeclareQuoteStyle{arabic}
+{\rmfamily\textquotedblright}{\rmfamily\textquotedblleft}
+{\rmfamily\textquoteright}{\rmfamily\textquoteleft}
 \usepackage[style=authoryear, indexing=cite]{biblatex}
 \DeclareIndexFieldFormat{indextitle}{\index{#1=\emph{#1}}}
 \addbibresource{arabluatex.bib}
@@ -144,11 +154,11 @@
 % \section*{License and disclamer}
 % \addcontentsline{toc}{section}{License and disclamer} Please send
 % error reports and suggestions for improvements to Robert Alessi:
-% \begin{itemize}
+% \begin{compactitem}
 % \item email: <\href{mailto:alessi@robertalessi.net?Subject=arabluatex}%
 %   {\texttt{alessi@{\allowbreak}robertalessi.net}}>
 % \item website: \url{http://www.robertalessi.net/arabluatex}
-% \end{itemize}
+% \end{compactitem}
 % 
 %
 % This program is free software; you can redistribute it and/or
@@ -258,7 +268,7 @@
 % some other Arab\TeX\ input yet to be processed---for further
 % processing.
 %
-% \section{Usage}
+% \section{The basics of \package{arabluatex}}
 % \subsection{Activating \package{arabluatex}}
 % As usual put in your preamble:\\
 % \arabluaverb{\usepackage{arabluatex}}\\
@@ -281,8 +291,8 @@
 % issue a warning message and attempt to load the Amiri
 % font\footnote{\textcite{pkg:amiri}.} like so:\\
 % \arabluaverb{\newfontfamily\arabicfont[Script=Arabic]{Amiri}}
-% \begin{quote}\footnotesize
-%   \textbf{Rem.} By default Amiri places the \arb[trans]{kasraT} in
+% \begin{quoting}
+%   \textsc{Rem.} By default Amiri places the \arb[trans]{kasraT} in
 %   combination with the \arb[trans]{ta^sdId} below the consonant,
 %   like so: \arb{BBi}\,. This is correct, as at least in the oldest
 %   manuscripts {\newfontfamily\arabicfont[Script=Arabic,
@@ -295,18 +305,18 @@
 %   \arabluaverb{\newfontfamily\arabicfont[Script=Arabic,RawFeature={+ss05}]{Amiri}}
 %
 %   Other Arabic fonts may behave differently.
-% \end{quote}
+% \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:
+% which may be overriden at any point of the document (see below **):
 % 
 % \DescribeOption{voc}\hfill\arabluaverb{default}\\ In this mode,
 % which is the one selected by default, every short vowel written
 % generates its corresponding diacritical mark: \arb[trans]{.dammaT}
 % (\arb{Bu}), \arb[trans]{fat.haT} (\arb{Ba}) and \arb[trans]{kasraT}
-% (\arb{Bi}). If a vowel is followed by \meta{N}, then the
-% corresponding \arb[trans]{tanwIn} (\arb{BuN}, \arb{BaN}\,,
+% (\arb{Bi}). If a vowel is followed by \meta{uN, aN, iN}, then the
+% corresponding \arb[trans]{tanwIn} (\arb{BuN}, \arb{B|aN}\,,
 % \arb{TaN}, \arb{BaN_A} or \arb{BiN}) is generated. Finally, \meta{u,
 % a, i} at the commencement of a word indicate a \enquote{connective
 % \arb[trans]{'alif}\,} (\arb[trans]{'alifu 'l-wa.sli}), but |voc| mode
@@ -318,16 +328,92 @@
 % \arb[trans]{wa.slaT}.
 %
 % \DescribeOption{novoc}\\ None of the diacritics is showed in |novoc|
-% mode, unless otherwise specified.
-%
-% \DescribeOption{trans} \\
-%
-%
-% \begin{itemize}
-%   \item voc Vocalized Arabic
-%   \item novoc Full vocalized Arabic
-% \end{itemize}
+% mode, unless otherwise specified (see \enquote{quoting} technique
+% below **).
+%
+% \DescribeOption{trans} \\ This mode transliterates the Arab\TeX\
+% input into one of the accepted standards. At present, two standards
+% are supported:
+% \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}.
+%
+%\subsection{Typing Arabic}
+% \DescribeMacro{arb} Once \package{arabluatex} is loaded, a command
+% \cs{arb}\marg{Arabic text} is available for inserting Arabic text in
+% paragraphs, like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+From \textcite[i. 1 A]{Wright}:--- Arabic, like Hebrew and
+Syriac, is written and read from right to left. The letters
+of the alphabet (\arb{.hurUfu 'l-hijA'i}, \arb{.hurUfu
+'l-tahajjI}, \arb{al-.hurUfu 'l-hijA'iyyaTu}, or \arb{.hurUfu
+'l-mu`jami}) are twenty-eight in number and are all
+consonants, though three of them are also used as vowels
+(see §~3).
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+% 
+% \DescribeEnv{arab} Running paragraphs of Arabic text should rather
+% be placed inside an \emph{Arabic environment}
 % 
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+  \begin{arab}
+  [...]
+  \end{arab}
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi
+% like so:---
+% \setquotestyle{arabic}
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+ \begin{arab}
+   'at_A .sadIquN 'il_A ju.hA ya.tlubu min-hu .himAra-hu
+   li-yarkaba-hu fI safraTiN qa.sIraTiN wa-qAla la-hu:
+   \enquote{sawfa 'u`Idu-hu 'ilay-ka fI 'l-masA'i
+   wa-'adfa`u la-ka 'ujraTaN.} fa-qAla ju.hA:
+   \enquote{'anA 'AsifuN jiddaN 'annI lA 'asta.tI`u 'an
+   'u.haqqiqa la-ka .garbata-ka fa-'l-.himAru laysa hunA
+   'l-yawma.}  wa-qabla 'an yutimma ju.hA kalAma-hu bada'a
+   'l-.himAru yanhaqu fI 'i.s.tabili-hi. fa-qAla la-hu
+   .sadIqu-hu: \enquote{'innI 'asma`u .himAra-ka yA ju.hA
+   yanhaqu.} fa-qAla la-hu ju.hA: \enquote{.garIbuN
+   'amru-ka yA .sadIqI 'a-tu.saddiqu 'l-.himAra
+   wa-tuka_d_dibu-nI?}
+  \end{arab}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+% \setquotestyle{english}
+%
+%\section{Standard Arab\TeX\ input}
+%\subsection{Consonants}
+% Table\vref{tab:arabtex-consonants} gives the Arab\TeX\ equivalents for
+% all of the Arabic consonants.
 % \newcommand{\dmg}[1]{%
 %   \SetTranslitConvention{dmg}%
 %   \arb[trans]{#1}}
@@ -340,19 +426,108 @@
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
 % \endhead \footnotetext{See below **}
-% \arb[novoc]{a} & \dmg{A} & \loc{A} & \verb|A| \\
-% \arb[novoc]{b} & \dmg{b} & \loc{b} & \verb|b| \\
-% \arb[novoc]{t} & \dmg{t} & \loc{t} & \verb|t| \\
-% \arb[novoc]{_t} & \dmg{_t} & \loc{_t} & \verb|_t| \\
-% \arb[novoc]{j} & \dmg{j} & \loc{j} & \verb|^g| or \verb|j| \\
-% \arb[novoc]{.h} & \dmg{.h} & \loc{.h} & \verb|.h| \\
-% \arb[novoc]{x} & \dmg{x} & \loc{x} & \verb|_h| or \verb|x|\\
-% \arb[novoc]{d} & \dmg{d} & \loc{d} & \verb|d| \\
-% \arb[novoc]{_d} & \dmg{_d} & \loc{_d} & \verb|_d| \\
-% \arb[novoc]{r} & \dmg{r} & \loc{r} & \verb|r| \\
+% \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| \\
+% \arb[novoc]{t} & \dmg{t} & \loc{t} & |t| \\
+% \arb[novoc]{_t} & \dmg{_t} & \loc{_t} & |_t| \\
+% \arb[novoc]{j} & \dmg{j} & \loc{j} & |^g| or |j| \\
+% \arb[novoc]{.h} & \dmg{.h} & \loc{.h} & |.h| \\
+% \arb[novoc]{x} & \dmg{x} & \loc{x} & |_h| or |x|\\
+% \arb[novoc]{d} & \dmg{d} & \loc{d} & |d| \\
+% \arb[novoc]{_d} & \dmg{_d} & \loc{_d} & |_d| \\
+% \arb[novoc]{r} & \dmg{r} & \loc{r} & |r| \\
+% \arb[novoc]{z} & \dmg{z} & \loc{z} & |z| \\
+% \arb[novoc]{s} & \dmg{s} & \loc{s} & |s| \\
+% \arb[novoc]{^s} & \dmg{^s} & \loc{^s} & |^s| \\
+% \arb[novoc]{.s} & \dmg{.s} & \loc{.s} & |.s| \\
+% \arb[novoc]{.d} & \dmg{.d} & \loc{.d} & |.d| \\
+% \arb[novoc]{.t} & \dmg{.t} & \loc{.t} & |.t| \\
+% \arb[novoc]{.z} & \dmg{.z} & \loc{.z} & |.z| \\
+% \arb[novoc]{`} & \dmg{`} & \loc{`} & |`| \\
+% \arb[novoc]{.g} & \dmg{.g} & \loc{.g} & |.g| \\
+% \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]{l} & \dmg{l} & \loc{l} & |l| \\
+% \arb[novoc]{m} & \dmg{m} & \loc{m} & |m| \\
+% \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]{T} & \dmg{aT} & \loc{aT} & |T| \\
 % \bottomrule
-% \caption{Standard notation for Arabic}
+% \caption[Arab\TeX\ consonants]{Standard Arab\TeX\ (consonants)}
+% \label{tab:arabtex-consonants}
 % \end{longtable}
+%
+% \subsection{Vowels}
+% \subsubsection{Long vowels}
+% Table\vref{tab:arabtex-long-vowels} gives the Arab\TeX\ equivalents for
+% the Arabic long vowels. 
+% \begin{longtable}{llll}
+% \toprule
+% Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
+% & Arab\TeX\ notation \\
+%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \endhead \footnotetext{See below **}
+% \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}.}
+%            & \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| \\
+% \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}
+%   \textsc{Rem.}~\emph{a.} The long vowels \arb[trans]{A, U, I},
+%   otherwise called \arb[trans]{.hurUfu 'l-maddi}, \emph{the letters
+%   of prolongation}, involve the placing of the short vowels
+%   \arb[trans]{Ba, Bu, Bi} before the letters \arb[novoc]{A},
+%   \arb[novoc]{U}, \arb[novoc]{I} respectively. \package{arabluatex}
+%   does that automatically in case any from |voc|, |fullvoc| or
+%   |trans| modes is selected e.g. \arb[voc]{qAla} \arb[trans]{qAla},
+%   \arb[voc]{qIla} \arb[trans]{qIla}, \arb[voc]{yaqUlu}
+%   \arb[trans]{yaqUlu}.
+%
+%   \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.
+% \end{quoting}
+% 
+% \subsubsection{Short vowels}
+% Table\vref{tab:arabtex-short-vowels} gives the Arab\TeX\ equivalents for
+% 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 **}
+% \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| \\
+% \arb[voc]{BaN} & \dmg{BaN} & \loc{BaN} & \verb|aN| \\
+% \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)}
+% \label{tab:arabtex-short-vowels}
+% \end{longtable}
+%
+% 
+% 
 % Usage goes here. \cs{hop}\oarg{ah}\marg{ouh}\meta{pop}
 %
 %