added compatibility with the 'quran' package; updated documentation. getting close to v1.5

2 files changed, 239 insertions, 13 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 3289b8e..9f54123 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -27,7 +27,7 @@
 %<package-info>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package-info>\ProvidesPackage{arabluatex}
 %<*package-info>
-    [2016/10/05 v1.4.5 An ArabTeX-like interface for LuaLaTeX]
+    [2016/11/14 v1.5 An ArabTeX-like interface for LuaLaTeX]
 %</package-info>
 %
 %<*driver>
@@ -145,7 +145,8 @@
 \defaultfontfeatures{RawFeature={+liga}}
 \setmainfont{Old Standard}[SmallCapsFont={Latin Modern Roman Caps},
   RawFeature={+mark;+ccmp;+ss05;+ss06}]
-\usepackage{arabluatex}[2016/10/05]
+\usepackage{arabluatex}[2016/11/14]
+\usepackage[nopar]{quran}
 \usepackage{varioref}
 \usepackage{hypdoc}
 \hypersetup{unicode=true, colorlinks, allcolors=blue,
@@ -249,10 +250,10 @@
 % \maketitle
 % \footnotesize
 % \tableofcontents
+% \pagebreak
 % \listoftables
 % \normalsize
 %
-% \pagebreak
 % \begin{abstract}
 %   This package provides for \LuaLaTeX\ an Arab{\TeX}-like interface
 %   to generate Arabic writing from an \textsc{ascii}
@@ -2163,7 +2164,37 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu
 % Al-intiqaADi} with the correct vowel \meta{i} in place of the %
 % \SetInputScheme{arabtex}%
 % \arb[trans]{'alif-u 'l-wa.sl-i}.
-% 
+%
+% \section{Unicode Arabic input}
+% \label{sec:unicode-input}
+% \NEWfeature{v1.5} As said above in \vref{sec:buckwalter-scheme}
+% about the Buckwalter input scheme, even though \package{arabluatex}
+% is primarily designed to process the Arab\TeX\ notation, it also
+% accepts unicode Arabic input. It should be noted that
+% \package{arabluatex} does in no way interfere with unicode Arabic
+% input: none of the options |voc|, |fullvoc|, |novoc| or |trans| will
+% have any effect on plain unicode Arabic for the time being.
+%
+% That said, there are two ways of inserting unicode
+% Arabic:
+% \begin{compactenum}[(a)] 
+% \item \DescribeMacro{\txarb} The \cs{txarb}\marg{unicode Arabic}
+%   command for inserting unicode Arabic text in paragraphs;
+% \item The \DescribeEnv{txarab} |txarab| environment for inserting
+%   running paragraphs of Arabic text, like so:---\\%
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+  \begin{txarab}
+    <Unicode Arabic text>
+  \end{txarab}
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi
+% \end{compactenum}
+%
 % \section{\LaTeX\ Commands in Arabic environments}
 % \label{sec:commands-in-arb}
 % \paragraph{General principle} \label{ref:cmd-inside-arabic}\LaTeX\
@@ -2296,6 +2327,133 @@ qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a...
 %</example>
 % \fi
 %
+% \subsection{Environments}
+% \label{sec:environments}
+% \changes{v1.5}{2016/11/14}{Environments may be nested inside the
+%   \texttt{arab} environment}
+% \NEWfeature{v1.5} Environments such as
+% \arabluaverb{\begin{quote}... \end{quote}} may be nested inside the
+% |arab| environment. Up to one optional argument may be passed to
+% each nested environment, like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+\begin{arab}
+  \begin{<environment>}[<options>]
+    <Arabic text>
+  \end{<environment>}
+\end{arab}
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi
+%
+% In the following example, the \package{quoting} package is used:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+  \setquotestyle{arabic}
+  \begin{arab}[fullvoc]
+    kAna \cap{'abU} \cap{'l-hu_dayli} 'ahd_A 'il_A \cap{muwaysiN}
+    dajAjaTaN. wa-kAnat dajAjatu-hu 'llatI 'ahdA-hA dUna mA kAna
+    yuttaxa_du li-\cap{muwaysiN}. wa-l_akinna-hu bi-karami-hi
+    wa-bi-.husni xuluqi-hi 'a.zhara 'l-ta`ajjuba min simani-hA
+    wa-.tIbi la.hmi-hA. wa-kAna <\cap{'abU} \cap{'l-hu_dayli}> yu`rafu
+    bi-'l-'imsAki 'l-^sadIdi. fa-qAla: \enquote{wa-kayfa ra'ayta yA
+      \cap{'abA} \cap{`imrAna} tilka 'l-dajAjaTa?} qAla:
+    \enquote{kAnat `ajabaN mina 'l-`ajabi!}  fa-yaqUlu:
+    \begin{quoting}[begintext=», endtext=«]
+      wa-tadrI mA jinsu-hA? wa-tadrI mA sinnu-hA?  fa-'inna
+      'l-dajAjaTa 'inna-mA ta.tIbu bi-'l-jinsi wa-'l-sinni. wa-tadrI
+      bi-'ayyi ^say'iN kunnA nusamminu-hA? wa-fI 'ayyi makAniN kunnA
+      na`lifu-hA?
+    \end{quoting}
+    fa-lA yazAlu fI h_a_dA wa-'l-'A_haru ya.d.haku .da.hkaN na`rifu-hu
+    na.hnu wa-lA ya`rifu-hu \cap{'abU} \cap{'l-hu_dayli}.
+  \end{arab}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
+% \subsubsection{Lists}
+% \label{sec:lists}
+% Lists environments are also accepted inside the |arab|
+% environment. One may either use any of the three standard list
+% environments, viz. |itemize|, |enumerate| and |description| or use a
+% package that provides additional refinements such as
+% \package{paralist}.
+%
+% To take a first example, should one wish to typeset a list of
+% manuscripts, the |description| environment may be used like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+ \setRL\paragraph{\arb[novoc]{rumUzi 'l-kitAbi}}\setLR
+ \begin{arab}[novoc]
+  \begin{description}
+   \item[b] max.tU.tu 'l-maktabaTi 'l-'ahliyyaTi bi-\cap{bArIs} 2860
+    `arabiyyuN.
+   \item[s] max.tU.tu 'l-maktabaTi 'l-'ahliyyaTi bi-\cap{bArIs} 2859
+    `arabiyyuN.
+   \item[m] max.tU.tu majlisi \arb[novoc]{^sUrAY malY} .tahrAna 521.
+  \end{description}
+ \end{arab}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
+% As a second example, the contents of a treatise may be typeset with
+% the standard list environments, like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+  \setRL\centerline{\arb{\textbf{al-qAnUnu fI 'l-.tibbi}}}\setLR
+  \begin{arab}
+    \begin{itemize}
+    \item \textbf{al-fannu 'l-'awwalu} fI .haddi 'l-.tibbi
+      wa-maw.dU`Ati-hi mina 'l-'umUri 'l-.tabI`iyyaTi wa-ya^stamilu
+      `al_A sittaTi ta`AlImiN
+      \begin{itemize}
+        \item \textbf{al-ta`lImu 'l-'awwalu} [wa-huwa fa.slAni]
+          \begin{itemize}
+          \item \textbf{al-fa.slu 'l-'awwalu}
+          \end{itemize}
+      \end{itemize}
+    \end{itemize}
+  \end{arab}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Caveat}
+% The various French definition files of the \package{babel} package
+% viz. |acadian|, |canadien|, |francais|, |frenchb| or |french| all
+% redefine the list environments, which breaks the standard definition
+% file that is used by \package{arabluatex}. Therefore,
+% \package{babel-french} must be loaded with the option
+% |StandardLayout=true|, like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+\usepackage[french]{babel}
+\frenchbsetup{StandardLayout=true}
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi%
+% This option will prevent \package{babel-french} from interfering
+% with the layout of the document. Then the package \package{paralist}
+% may be used to make the lists \enquote*{compact} as
+% \package{babel-french} do.
+%
 % \subsection{\package{csquotes}}
 % \label{sec:csquotes}
 % The recommended way of inserting quotation marks in running Arabic
@@ -2357,6 +2515,48 @@ wa-ya.sIru ta.hta 'l-jild-i
 % \iffalse
 %</example>
 % \fi
+%
+% \subsection{\package{quran}}
+% \label{sec:pkg-quran}
+% \changes{v1.5}{2016/11/14}{Compatibility with the \textsf{quran}
+% package} \package{arabluatex} is compatible with the \package{quran}
+% package so that both can be used in conjunction with one another for
+% typesetting the \arb[trans]{\cap{qur'An}}. As \package{quran} draws
+% the text of the \arb[trans]{\cap{qur'An}} from a unicode encoded
+% database, its commands have to be passed as arguments to the
+% \cs{txarb} command for short insertions in left-to-right paragraphs,
+% or inserted inside the \index{txarab=txarab (environment)}|txarab|
+% environment for typesetting running paragraphs of
+% \arb[trans]{\cap{qur'An}}\emph{ic} text (see above
+% \vref{sec:unicode-input} for more details). Please note that
+% \package{arabluatex} takes care of formatting the Arabic: therefore,
+% it is recommended to load the \package{quran} package with the
+% option |nopar|, after \package{arabluatex} itself has been loaded,
+% like so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+  \usepackage{arabluatex}
+  \usepackage[nopar]{quran}
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi
+%
+% As an example, the following code will typeset the \arb[trans]{sUraT}
+% \arb[trans]{al-\cap{fAti.haT}}:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+  \begin{txarab}
+    \quransurah[1]
+  \end{txarab}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
 % 
 % \section{Future work}
 % \label{sec:future-work}
@@ -2399,7 +2599,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 %    \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{arabluatex}%
-[2016/10/05 v1.4.5 An ArabTeX-like interface for LuaLaTeX]
+[2016/11/14 v1.5 An ArabTeX-like interface for LuaLaTeX]
 \RequirePackage{ifluatex}
 %    \end{macrocode}
 % \package{arabluatex} requires \LuaLaTeX\ of course. Issue a warning
@@ -2599,12 +2799,12 @@ wa-ya.sIru ta.hta 'l-jild-i
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\txarb} \cs{txarb} sets the direction to right-to-left
-%   and selects the Arabic font. As it is supposed to be used
-%   internally by several Lua functions, this command is not
-%   documented, but available to the user should he wish to insert
+%   and selects the Arabic font. It is used internally by several Lua
+%   functions, but available to the user should he wish to insert
 %   |utf8| Arabic text in his document.
 % \begin{macro}{\txtrans} \cs{txtrans} is used internally by several
-% Lua functions to insert transliterated Arabic text.
+% Lua functions to insert transliterated Arabic text. Therefore, it is
+% not documented.
 %    \begin{macrocode}
 \DeclareDocumentCommand{\txarb}{+m}{\bgroup\textdir
   TRT\arabicfont#1\egroup}
@@ -2614,7 +2814,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 % \end{macro}
 % \end{macro}
 % \begin{environment}{txarab}
-%   \changes{v1.5}{2016/11/13}{New \texttt{txarab} environment for
+%   \changes{v1.5}{2016/11/14}{New \texttt{txarab} environment for
 %   typesetting running paragraphs in unicode Arabic} The |txarab|
 %   environment does for paragraphs the same as \cs{txarb} does for
 %   short insertions of |utf8| Arabic text.
@@ -2764,11 +2964,21 @@ wa-ya.sIru ta.hta 'l-jild-i
 % \iffalse
 %<*patch>
 % \fi
-%
 %    \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{arabluatex-patch}%
-[2016/11/13 v1.0 patches for arabluatex]
+[2016/11/14 v1.0 patches for arabluatex]
+%    \end{macrocode}
+% I have put in a separate |.sty| file external lines of code that
+% I had to patch for a good reason. I hate doing this, and hopefully,
+% most of these lines will disappear as soon as they are not required
+% anymore.
+%
+% The following is taken from |latex.ltx|. I had to make this patch
+% for I could not find a way to process the list environments in
+% right-to-left mode. The \LuaTeX\ primitives \cs{bodydir} and
+% \cs{pagedir} will eventually allow us to get rid of this:
+%    \begin{macrocode}
 \def\list#1#2{%
   \ifnum \@listdepth >5\relax
     \@toodeep
@@ -2788,8 +2998,14 @@ wa-ya.sIru ta.hta 'l-jild-i
   \parindent\listparindent
   \advance\linewidth -\rightmargin
   \advance\linewidth -\leftmargin
+%    \end{macrocode}
+% patch begins:
+%    \begin{macrocode}
   \ifbool{al@rlmode}{\advance\@totalleftmargin \rightmargin}%
   {\advance\@totalleftmargin \leftmargin}
+%    \end{macrocode}
+% patch ends.
+%    \begin{macrocode}
   \parshape \@ne \@totalleftmargin \linewidth
   \ignorespaces}
 \def\@item[#1]{%
@@ -2841,10 +3057,16 @@ wa-ya.sIru ta.hta 'l-jild-i
       \refstepcounter\@listctr
     \fi
   \fi
+%    \end{macrocode}
+% patch begins:
+%    \begin{macrocode}
   \ifbool{al@rlmode}{\sRLbox\@tempboxa{\makelabel{#1}}}{%
   \sbox\@tempboxa{\makelabel{#1}}}%
   \ifbool{al@rlmode}{\global\setbox\@labels\hbox dir TRT}%
   {\global\setbox\@labels\hbox}{%
+%    \end{macrocode}
+% patch ends.
+%    \begin{macrocode}
     \unhbox\@labels
     \hskip \itemindent
     \hskip -\labelwidth
@@ -2856,6 +3078,10 @@ wa-ya.sIru ta.hta 'l-jild-i
     \fi
     \hskip \labelsep}%
   \ignorespaces}
+%    \end{macrocode}
+% This is adapted from Vafa Khalighi's \package{bidi} package. Thanks
+% to him.
+%    \begin{macrocode}
 \long\def\sRLbox#1#2{\setbox#1\hbox dir TRT{%
   \color@setgroup#2\color@endgroup}}
 %    \end{macrocode}
diff --git a/arabluatex.lua b/arabluatex.lua
index 6e5b042..38fe87b 100644
--- a/arabluatex.lua
+++ b/arabluatex.lua
@@ -47,7 +47,7 @@ return str
 end
 
 local function breakcmd(str)
-   -- handle \item[], then \item[]
+   -- process \item[], then \item[]
         str = string.gsub(str, "\\(item.?)(%b[])",
           function(tag, body)
           body = string.sub(body, 2, -2)