path: root/arabluatex.dtx

% \iffalse meta-comment
% copyright (C) 2016  Robert Alessi
%
% Please send error reports and suggestions for improvements to
% Robert Alessi <alessi@robertalessi.net>
%
% This program is free software; you can redistribute it and/or
% modify it under the terms of the GNU General Public License
% as published by the Free Software Foundation; either version 2
% of the License, or (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
% 02111-1307, USA.
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{arabluatex.dtx}
%</driver>
%<package-info>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package-info>\ProvidesPackage{arabluatex}
%<*package-info>
    [2016/01/26 v1.0 This is ArabTeX for LuaLaTeX]
%</package-info>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage[english]{babel}
\usepackage{dox}
\doxitem{Option}{option}{options}
\usepackage{fontspec,luatextra,realscripts}
\defaultfontfeatures{RawFeature={+liga}}
\setmainfont{Libertinus Serif}
\setsansfont{Libertinus Sans}
\setmonofont[Scale=.9]{Libertinus Mono}
\usepackage{arabluatex}[2016/01/26]
\usepackage{hypdoc}
\hypersetup{colorlinks, allcolors=blue}
\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[defaultlines=2,all]{nowidow}
\usepackage{tikz}
\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}{#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,
    bottom=0mm, colback=white, boxrule=.15mm,
    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}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{arabluatex.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{1.0}{2016/01/26}{Converted to DTX file}
%
% \DoNotIndex{\newcommand,\newenvironment,\renewcommand}
%
% \providecommand*{\url}{\texttt}
% \GetFileInfo{arabluatex.dtx}
% 
% \title{\tcbox[enhanced, tikznode, drop lifted shadow, colback=white,
% boxrule=.25mm]%
% {The \textsf{arabluatex} package\\
% \fileversion~from \filedate}}
% 
% \newcommand*{\NEWfeature}[1]{%
%     \hskip 1sp \marginpar{\small\sffamily\raggedright
%     New feature\\#1}}
% 
% \author{Robert Alessi \\
% \href{mailto:alessi@robertalessi.net?Subject=arabluatex}%
% {\texttt{alessi@robertalessi.net}}}
% \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}
% 
% \begin{abstract}
%   This package provides for \LuaLaTeX\ an Arab{\TeX}-like interface
%   to generate Arabic writing from an \textsc{ascii}
%   transliteration. It is particularly well-suited for complex
%   documents such as technical documents or critical editions where a
%   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
%   transliterations. It further allows some typographical
%   refinements.
% \end{abstract}
%
% \section*{License and disclamer}
% \addcontentsline{toc}{section}{License and disclamer} Please send
% error reports and suggestions for improvements to Robert Alessi:
% \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{compactitem}
% 
%
% This program is free software; you can redistribute it and/or
% modify it under the terms of the GNU General Public License
% as published by the Free Software Foundation; either version 2
% of the License, or (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with this program; if not, write to the Free Software
% Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
% 02111-1307, USA.
% 
% \section{Introduction}
% In comparison to Prof. Lagally's outstanding Arab\TeX,\footnote{See
% \url{http://ctan.org/pkg/arabtex}} Arab\LuaTeX\ is at present
% nothing more than a modest piece of software. Hopefully---if I may
% say so---it will eventually provide all of its valuable qualities to
% the \LuaLaTeX\ users.
%
% \package{arabtex} dates back to 1992. As far as I know, it was then the
% first and only way to typeset Arabic texts with \TeX\ and \LaTeX. To
% achieve this, \package{arabtex} provided---and still does---an Arabic
% font in \emph{Nasḫī} style and a macro package that defined its own
% input notation which was, as the author stated, \enquote{both
% machine, and human, readable, and suited for electronic transmission
% and e-mail communication}.\footnote{\textcite[2]{pkg:arabtex}.} Even
% if the same can be said about Unicode, Arab\TeX\ \textsc{ASCII}
% input notation still surpasses Unicode input, in my opinion, when it
% comes to typesetting complex documents, such as scientific documents
% or critical editions where footnotes and other kind of annotations
% can be particulary abundant. It must also be said that most text
% editors have trouble in displaying Arabic script connected with
% preceding or following \LaTeX\ commands: it often happens that
% commands seem misplaced, not to mention punctuation marks, or
% opening or closing braces, brackets or parentheses that are
% unexpectedly displayed in the wrong direction. Of course, some text
% editors provide ways to get around such difficulties by inserting
% invisible Unicode characters, such as LEFT-TO-RIGHT or RIGHT-TO-LEFT
% MARKS (\texttt{U+200E}, \texttt{U+200F}), RTL/LTR \enquote{embed}
% characters (\texttt{U+202B}, \texttt{U+202A}) and RLO/LRO
% \enquote{bidi-override} characters (\texttt{U+202E},
% \texttt{U+202D}).\footnote{Gáspár Sinai's Yudit probably has the
% best Unicode support. See \url{http://www.yudit.org}.} Nonetheless, it
% remains that inserting all the time these invisible characters in
% complex documents rapidly becomes confusing and cumbersome.
%
% The great advantage of Arab\TeX\ notation is that it is immune from
% all these difficulties, let alone its being clear and
% straightforward. One also must remember that computers are designed
% to process code. Arab\TeX\ notation is a way of encoding Arabic
% language, just as \TeX\ \enquote{mathematics mode} is a way of
% processing code to display mathematics. As such, not only does it
% allow greater control over typographical features, but it also can
% be processed in several different ways: so without going into
% details, depending on one's wishes, Arab\TeX\ input can be full
% vocalized Arabic (\emph{scriptio plena}), vocalized Arabic or
% non-vocalized Arabic (\emph{scriptio defectiva}); it further can be
% transliterated into whichever romanization standard the user may
% choose.
%
% But there may be more to be said on this point, as encoding Arabic
% also naturally encourages the coder to vocalize the texts---without
% compelling him to do so, of course. Accurate coding may even have
% other virtuous effects. For instance, hyphens may be used for tying
% particles or prefixes to words, or to mark inflectional endings, and
% so forth. In other words, accurate coding produces accurate texts
% that can stand to close grammatical scrutiny and to complex textual
% searches as well.
%
% Having that in mind, I started \package{arabluatex}. With the help
% of Lua, it will eventually interact with some other packages yet to
% come to produce from \verb|.tex| source files, in addition to
% printed books, \texttt{TEI xml} compliant critical editions and/or
% lexicons that can be searched, analyzed and correlated in various
% ways.
%
%\subsection{\package{arabluatex} is for \LuaLaTeX}
% It goes without saying that \package{arabluatex} requires
% \LuaLaTeX. \TeX\ and \LaTeX\ have \package{arabtex}, and \XeLaTeX\
% has \package{arabxetex}. Both of them are much more advanced than
% \package{arabluatex}, as they can process a number of different
% languages,\footnote{To date, both packages support Arabic, Maghribi,
% Urdu, Pashto, Sindhi, Kashmiri, Uighuric and Old Malay; in addition
% to these, \package{arabtex} also has a Hebrew mode, including
% Judeo-Arabic and Yiddish.} whereas \package{arabluatex} can process
% only Arabic for the time being. More languages will be included in
% future releases of \package{arabluatex}.
%
% In comparison to \package{arabxetex}, \package{arabluatex} works in
% a very different way. The former relies on the
% \href{http://scripts.sil.org/TECkitIntro}{\texttt{TECkit}} engine
% which converts Arab\TeX\ input on the fly into Unicode Arabic
% script, whereas the latter passes Arab\TeX\ input on to a set of Lua
% functions. At first, \LaTeX\ commands are taken care of in different
% ways: some, as \cs{emph}, \cs{textbf} and the like are expected to
% have Arabic text as arguments, while others, as \cs{LR}, for
% \enquote{left-to-right text}, are not. Then, once what is Arabic is
% carefully separated form what is not, it is processed by other Lua
% functions which rely on different sets of correpondence tables to do
% the actual conversion in accordance with one's wishes. Finally, Lua
% returns to \TeX\ the converted strings---which may in turn contain
% some other Arab\TeX\ input yet to be processed---for further
% processing.
%
% \section{The basics of \package{arabluatex}}
% \subsection{Activating \package{arabluatex}}
% As usual put in your preamble:\\
% \arabluaverb{\usepackage{arabluatex}}\\
% The only requirement of \package{arabluatex} is \LuaLaTeX; it will
% 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.
%
% \paragraph{Font setup}
% If you wish to use your own Arabic font, you can define it before
% loading \package{arabluatex}. Assuming that \package{fontspec} is
% loaded, put this in your preamble just above the line that loads
% \package{arabluatex}:
% \arabluabox{\cs{newfontfamily}\cs{arabicfont}[Script=Arabic]\marg{fontname}}
% \noindent where \meta{fontname} is the standard name of the Arabic
% font you wish to use.
%
% By default, if no Arabic font is selected, \package{arabluatex} will
% issue a warning message and attempt to load the Amiri
% font\footnote{\textcite{pkg:amiri}.} like so:---\\
% \arabluaverb{\newfontfamily\arabicfont[Script=Arabic]{Amiri}}
% \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,
%   RawFeature={+ss05}]{Amiri}\arb{BBi}} may stand for \arb{BBa} as
%   well as \arb{BBi}\,. See \textcite[i.14.C--D]{Wright}. The placement
%   of the \arb[trans]{kasraT} above the consonant may be obtained by
%   selecting the |ss05| feature of the Amiri font, like
%   so:---\footnote{See the documentation of \package{amiri},
%   \textcite[5]{pkg:amiri}.}\\
%   \arabluaverb{\newfontfamily\arabicfont[Script=Arabic,RawFeature={+ss05}]{Amiri}}
%
%   Other Arabic fonts may behave differently.
% \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 **):
% 
% \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{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
% does not show the \arb[trans]{wa.slaT} above the \arb[trans]{'alif};
% instead, the accompanying vowel is expressed (\arb{u a i}).
%
% \DescribeOption{fullvoc}\\ \label{fullvoc-mode}In addition to what
% the |voc| mode does, |fullvoc| expresses the \arb[trans]{sukUn} and
% the \arb[trans]{wa.slaT}.
%
% \DescribeOption{novoc}\\ None of the diacritics is showed in |novoc|
% 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}}
% \newcommand{\loc}[1]{%
%   \SetTranslitConvention{loc}%
%   \arb[trans]{#1}\SetTranslitConvention{dmg}}
% \begin{longtable}{llll}
% \toprule
% Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
% & Arab\TeX\ notation \\
%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
% \endhead \footnotetext{See below **}
% \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| \\
% \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| \\
% \arb[novoc]{T} & \dmg{aT} & \loc{aT} & |T| \\
% \bottomrule
% \caption[Arab\TeX\ consonants]{Standard Arab\TeX\ (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 **}
% \label{tab:arabtex-long-vowels}
% \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-'alifu 'l-maq.sUraTu}.}
%            & \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)}
% \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 **}
% \label{tab:arabtex-short-vowels}
% \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)}
% \end{longtable}
%
% Whether Arabic texts are vocalized or not is essentially a matter of
% personal choice. So one may use |voc| mode and decide not to write
% 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 **}
%
% \iffalse
%<*example>
% \fi
\begin{arabluacode}[text only]
  However, it may be wise to always write the vowels, leaving to the
  various modes provided by \package{arabluatex} to take care of
  showing or not showing the vowels.
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% That said, there is no need to write the short vowels
% \arb[trans]{fat.haT}, \arb[trans]{.dammaT} or \arb[trans]{kasraT}
% except in the following cases:
% \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 **);
% \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
% expressed  in romanized Arabic.
% \end{compactitem}
%
%\section{\package{arabluatex} in action}
%\subsection{The vowels and diphthongs}
% \paragraph{Short vowels} As said above, they are written \meta{a, u,
% i}:
% \begin{quote}
%   |_halaqa| (or |xalaqa|) \arb[voc]{xalaqa} \arb[trans]{xalaqa},
%   |^samsuN| \arb[voc]{^samsuN} \arb[trans]{^samsuN}, |karImuN|
%   \arb[voc]{karImuN} \arb[trans]{\cap{karImuN}}.
%
%   |bi-hi| \arb[voc]{bi-hi} \arb[trans]{bi-hi}, |'aqi.tuN|
%   \arb[voc]{'aqi.tuN} \arb[trans]{'aqi.tuN}.
%
%   |la-hu| \arb[voc]{la-hu} \arb[trans]{la-hu}, |.hujjaTuN|
%   \arb[voc]{.hujjaTuN} \arb[trans]{.hujjaTuN}.
% \end{quote}
%
%\paragraph{Long vowels} They are written \meta{U, A, I}:
% \begin{quote}
%   |qAla| \arb[voc]{qAla} \arb[trans]{qAla}, |bI`a| \arb[voc]{bI`a}
%   \arb[trans]{bI`a}, |.tUruN| \arb[voc]{.tUruN} \arb[trans]{.tUruN},
%   |.tInuN| \arb[voc]{.tInuN} \arb[trans]{.tInuN}, |murU'aTuN|
%   \arb[trans]{murU'aTuN} \arb[voc]{murU'aTuN}
% \end{quote}
%
% \paragraph{\arb[trans]{'alif maq.sUraT}} It is written \meta{\_A} or
% \meta{Y}:
% \begin{quote}
%   |al-fat_A| \arb[voc]{al-fat_A} \arb[trans]{al-fat_A}, |al-maqh_A|
%   \arb[voc]{al-maqh_A} \arb[trans]{al-maqh_A}, |'il_A|
%   \arb[voc]{'il_A} \arb[trans]{'il_A}.
% \end{quote}
% 
% \paragraph{\arb[trans]{'alif} \emph{otiosum}} Said
% \arb[trans]{'alifu 'l-wiqAyaTi}, \enquote{the guarding
% \arb[trans]{'alif}}\,, after \arb[novoc]{U} at the end of a word, both
% when preceded by \arb[trans]{.dammaT} and by \arb[trans]{fat.haT} is
% written \meta{UA} or \meta{aW, aWA}:
% \begin{quote}
%   |na.sarUA| \arb[voc]{na.sarUA} \arb[trans]{na.sarUA}, |katabUA|
%   \arb[voc]{katabUA} \arb[trans]{katabUA}, |ya.gzUA|
%   \arb[voc]{ya.gzUA} \arb[trans]{ya.gzUA}, |ramaW|
%   \arb[fullvoc]{ramaW} \arb[trans]{ramaW}, |banaWA|
%   \arb[fullvoc]{banaWA}, \arb[trans]{banaWA}.
% \end{quote}
%
% \paragraph{\arb[trans]{'alif ma.h_dUfaT} and defective
% \arb[trans]{U, I}} they are written \meta{\_a, \_i \_u}:
% \begin{quote}
%   |al-l_ahu| \arb[voc]{al-l_ahu} \arb[trans]{al-l_ahu}, |'il_ahuN|
%   \arb[voc]{'il_ahuN} \arb[trans]{'il_ahuN}, |al-ra.hm_anu|
%   \arb[voc]{al-ra.hm_anu} \arb[trans]{al-ra.hm_anu}, |l_akin|
%   \arb[voc]{l_akin} \arb[trans]{l_akin}, |h_ahunA|
%   \arb[voc]{h_ahunA} \arb[trans]{h_ahunA},
%   |.hunaynu| |bnu| |'is.h_aqa|
%   \arb[voc]{.hunaynu bnu 'is.h_aqa} \arb[trans]{\cap{.hunaynu} bnu
%   \cap{'is.h_aqa}}, |rabb_i| \arb[voc]{rabb_i} \arb[trans]{rabb_i},
%   |al-`A.s_i| \arb[voc]{al-`A.s_i} \arb[trans]{al-\cap{`A.s_i}}.
% \end{quote}
%
% \paragraph{Silent \arb[novoc]{U}/\arb[novoc]{I}}
% Some words ending with \arb[voc]{BAT} are usually written
% \arb[voc]{BawT} or \arb[voc]{B_aUT} instead of \arb[voc]{BAT}: see
% \textcite[i. 12 A]{Wright}. \package{arabluatex} preserves this
% particular writing; the same applies to words ending in
% \arb[voc]{BayT} for \arb[voc]{BAT}. long vowels \meta{U, I} shall
% receive no \arb[trans]{sukUn} after a \arb[trans]{'alif ma.h_dUfaT}
% and are discarded in |trans| mode:
% \begin{quote}
%   |.hay_aUTuN| \arb[voc]{.hay_aUTuN} \arb[trans]{.hay_aUTuN},
%   |.sal_aUTuN| \arb[voc]{.sal_aUTuN} \arb[trans]{.sal_aUTuN},
%   |mi^sk_aUTuN| \arb[voc]{mi^sk_aUTuN} \arb[trans]{mi^sk_aUTuN},
%   |tawr_aITuN| \arb[voc]{tawr_aITuN} \arb[trans]{tawr_aITuN}.
%
%   And so also: |al-rib_aITu| \arb[voc]{al-rib_aITu}.
%   \arb[trans]{al-rib_aITu}
% \end{quote}
%
% \paragraph{\arb[trans]{\cap{`amruNU}}, and the silent
% \arb[novoc]{U}} To this name a silent \arb[novoc]{U} is added to
% distinguish it from \arb[trans]{\cap{`umaruN}}: see \textcite[i. 12
% C]{Wright}. In no way this affects the sound of the
% \arb[trans]{tanwIn}, so it has to be discarded in |trans| mode:
% \begin{quote}
%   |`amruNU| \arb[voc]{`amruNU} \arb[trans]{`amruNU}, |`amraNU|
%   \arb[voc]{`amraNU} \arb[trans]{`amraNU}, |`amriNU|
%   \arb[voc]{`amriNU} \arb[trans]{`amriNU}.
%
%   When the \arb[trans]{tanwIn} falls away \parencite[i. 249
%   B]{Wright}: |`amruU| |bnu| |mu.hammadiN| \arb[fullvoc]{`amruU bnu
%   mu.hammadiN} \arb[trans]{\cap{`amruU} bnu \cap{mu.hammadiN}},
%   |mu.hammadu| |bnu| |`amriU| |bni| |_hAlidiN|
%   \arb[fullvoc]{mu.hammadu bnu `amriU bni _hAlidiN}
%   \arb[trans]{\cap{mu.hammadu} bnu \cap{`amriU} bni \cap{_hAlidiN}}.
%
%   And so also: |al-rib_aUA| \arb[voc]{al-rib_aUA}
%   \arb[trans]{al-rib_aUA}, |ribaNU| \arb[voc]{ribaNU}
%   \arb[trans]{ribaNU}.
% \end{quote}
%
%\paragraph{\arb[trans]{tanwIn}}
% The marks of doubled short vowels, \arb{BuN}, \arb{BaN}, \arb{BiN},
% are written \meta{uN, aN, iN} respectively. \package{arabluatex}
% deals with special cases, such as \arb{BaN} taking an \arb[novoc]{A}
% after all consonants except \arb[novoc]{T}, and \arb[trans]{tanwIn}
% preceding \arb[novoc]{Y} as in \arb[voc]{hudaN_A}, which is written
% \meta{aN\_A} or \meta{aNY}:
% \begin{quote}
%   |mAluN| \arb[voc]{mAluN} \arb[trans]{mAluN}, |bAbaN|
%   \arb[voc]{bAbaN} \arb[trans]{bAbaN}, |madInaTaN|
%   \arb[voc]{madInaTaN} \arb[trans]{madInaTaN}, |bintiN|
%   \arb[voc]{bintiN} \arb[trans]{bintiN} |maqhaN_A|
%   \arb[voc]{maqhaN_A} \arb[trans]{maqhaN_A}, |fataNY|
%   \arb[voc]{fataNY} \arb[trans]{fataNY}.
%
%   \package{arabluatex} is aware of special orthographies: |^say'uN|
%   \arb[voc]{^say'uN} \arb[trans]{^say'uN}, |^say'aN|
%   \arb[voc]{^say'aN} \arb[trans]{^say'aN}, |^say'iN|
%   \arb[voc]{^say'iN} \arb[trans]{^say'iN}.
% \end{quote}
%
% \subsection{Other orthographic signs}
% \paragraph{\arb[trans]{tA' marbU.taT}}
% It is written \meta{T}:
% \begin{quote}
%   |madInaTuN| \arb[voc]{madInaTuN} \arb[trans]{madInaTuN},
%   |madInaTaN| \arb[voc]{madInaTaN} \arb[trans]{madInaTaN},
%   |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 **.
% \begin{quote}
%   \textbf{Initial \arb[trans]{hamzaT}}: |'asaduN| \arb[voc]{'asaduN}
%   \arb[trans]{'asaduN}, |'u_htuN| \arb[voc]{'u_htuN}
%   \arb[trans]{'u_htuN}, |'iqlIduN| \arb[voc]{'iqlIduN}
%   \arb[trans]{'iqlIduN}, |'anna| \arb[voc]{'anna}
%   \arb[trans]{'anna}, |'inna| \arb[voc]{'inna} \arb[trans]{'inna}.
%
%   \arb[trans]{hamzaT} followed by the long vowel \arb[novoc]{U} is
%   encoded |'_U|: |'_Ul_A| \arb[voc]{'_Ul_A} \arb[trans]{'_Ul_A}, |'_UlU|
%   \arb[voc]{'_UlU} \arb[trans]{'_UlU}, |'_UlA'ika|
%   \arb[voc]{'_UlA'ika} \arb[trans]{'_UlA'ika}.
%
%   \textbf{Middle \arb[trans]{hamzaT}}: |xA.ti'Ina|
%   \arb[voc]{xA.ti'Ina} \arb[trans]{xA.ti'Ina}, |ru'UsuN|
%   \arb[voc]{ru'UsuN}, \arb[trans]{ru'UsuN}, |xa.tI'aTuN|
%   \arb[voc]{xa.tI'aTuN} \arb[trans]{xa.tI'aTuN}, |su'ila|
%   \arb[voc]{su'ila} \arb[trans]{su'ila}, |'as'ilaTuN|
%   \arb[voc]{'as'ilaTuN} \arb[trans]{'as'ilaTuN}, |mas'alaTuN|
%   \arb[voc]{mas'alaTuN} \arb[trans]{mas'alaTuN}, |'as'alu|
%   \arb[voc]{'as'alu} \arb[trans]{'as'alu}, |yatasA'alUna|
%   \arb[voc]{yatasA'alUna} \arb[trans]{yatasA'alUna}, |murU'aTuN|
%   \arb[voc]{murU'aTuN} \arb[trans]{murU'aTuN}, |ta'xIruN|
%   \arb[fullvoc]{ta'xIruN} \arb[trans]{ta'xIruN}, |ta'axxara|
%   \arb[voc]{ta'axxara} \arb[trans]{ta'axxara}, |ji'tu-ka|
%   \arb[voc]{ji'tu-ka} \arb[trans]{ji'tu-ka}, |qA'iluN|
%   \arb[voc]{qA'iluN} \arb[trans]{qA'iluN}.
%
%   From \textcite[i. 14 B]{Wright}:--- All consonants, whatsoever,
%   not even \arb[trans]{'alif} \emph{hèmzatum} excepted, admit of
%   being doubled and take \arb[trans]{ta^sdId}. Hence we speak and
%   write |ra''AsuN| \arb[voc]{ra''AsuN} \arb[trans]{ra''AsuN},
%   |sa''AluN| \arb[voc]{sa''AluN} \arb[trans]{sa''AluN}, |na''AjuN|
%   \arb[voc]{na''AjuN} \arb[trans]{na''AjuN}.
%
%   \textbf{Final \arb[trans]{hamzaT}}: |xa.ta'uN| \arb[voc]{xa.ta'uN}
%   \arb[trans]{xa.ta'uN}, |xa.ta'aN| \arb[voc]{xa.ta'aN}
%   \arb[trans]{xa.ta'aN}, |xa.ta'iN| \arb[voc]{xa.ta'iN}
%   \arb[trans]{xa.ta'iN}, |'aqra'u| \arb[voc]{'aqra'u}
%   \arb[trans]{'aqra'u}, |taqra'Ina| \arb[voc]{taqra'Ina}
%   \arb[trans]{taqra'Ina}, |taqra'Una| \arb[voc]{taqra'Una}
%   \arb[trans]{taqra'Una}, |yaqra'na| \arb[fullvoc]{yaqra'na}
%   \arb[trans]{yaqra'na}, |yaxba'Ani| \arb[voc]{yaxba'Ani}
%   \arb[trans]{yaxba'Ani}, |xaba'A| \arb[voc]{xaba'A}
%   \arb[trans]{xaba'A}, |xubi'a| \arb[voc]{xubi'a}
%   \arb[trans]{xubi'a}, |xubi'UA| \arb[voc]{xubi'UA}
%   \arb[trans]{xubi'UA}, |jA'a| \arb[voc]{jA'a} \arb[trans]{jA'a},
%   |ridA'uN| \arb[voc]{ridA'uN} \arb[trans]{ridA'uN}, |ridA'aN|
%   \arb[voc]{ridA'aN} \arb[trans]{ridA'aN}, |jI'a| \arb[voc]{jI'a}
%   \arb[trans]{jI'a}, |radI'iN| \arb[voc]{radI'iN}
%   \arb[trans]{radI'iN}, |sU'uN| \arb[voc]{sU'uN} \arb[trans]{sU'uN},
%   |.daw'uN| \arb[voc]{.daw'uN} \arb[trans]{.daw'uN}, |qay'iN|
%   \arb[voc]{qay'iN} \arb[trans]{qay'iN}.
%
%   |^say'uN| \arb[voc]{^say'uN} \arb[trans]{^say'uN}, |^say'aN|
%   \arb[voc]{^say'aN} \arb[trans]{^say'aN}, |^say'iN|
%   \arb[voc]{^say'iN} \arb[trans]{^say'iN}, |al-^say'u|
%   \arb[voc]{al-^say'u} \arb[trans]{al-^say'u}, |'a^syA'u|
%   \arb[voc]{'a^syA'u} \arb[trans]{'a^syA'u}, |'a^syA'a|
%   \arb[voc]{'a^syA'a} \arb[trans]{'a^syA'a}, |.zim'aN| \arb[voc]{.zim'aN}
%   \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
% \arb[trans]{maddaT}: \arb[voc]{A"'} \parencite[see][i. 25
% A--B]{Wright}.
%
% \iffalse
%<*example>
% \fi
\begin{arabluacode}[text only]
  Hence one should keep to this distinction and encode |'a'kulu|
  \arb[voc]{'a'kulu} \arb[trans]{'a'kulu} and |'AkiluN|
  \arb[voc]{'AkiluN} \arb[trans]{'AkiluN} respectively.
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% \package{arabluatex} otherwise determines \arb[trans]{al-'alifu
% 'l-mamdUdaTu} by context analysis.
% 
% \begin{quote}
%   |'is'AduN| \arb[voc]{'is'AduN} \arb[trans]{'is'AduN}, |'AkilUna|
%   \arb[voc]{'AkilUna} \arb[trans]{'AkilUna}, |'a'mannA|
%   \arb[voc]{'a'mannA} \arb[trans]{'a'mannA}, |al-qur'Anu|
%   \arb[voc]{al-qur'Anu} \arb[trans]{al-qur'Anu}.
%
%   |jA'a| \arb[voc]{jA'a} \arb[trans]{jA'a}, |yatasA'alUna|
%   \arb[voc]{yatasA'alUna} \arb[trans]{yatasA'alUna}, |ridA'uN|
%   \arb[voc]{ridA'uN} \arb[trans]{ridA'uN}, |xaba'A|
%   \arb[voc]{xaba'A} \arb[trans]{xaba'A}, |yaxba'Ani|
%   \arb[voc]{yaxba'Ani} \arb[trans]{yaxba'Ani}.
% \end{quote}
%
% \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
% 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}
%   |`allaqa| \arb[voc]{`allaqa} \arb[trans]{`allaqa}, |mAdduN|
%   \arb[voc]{mAdduN} \arb[trans]{mAdduN}, |'ammara|
%   \arb[voc]{'ammara} \arb[trans]{ammara}, |murruN| \arb[voc]{murruN}
%   \arb[trans]{murruN}
% \end{quote}
% 
% \subparagraph{The euphonic \arb[trans]{ta^sdId}}
% \label{euphonic-tashdid}
% always follows a vowelless consonant which is passed over in
% pronunciation and assimilated to a following consonant. It may be
% found \parencite[i. 15 B--16 C]{Wright}:---
% \begin{enumerate}[(a)]
% \item With the \emph{solar} letters \arb[novoc]{t}, \arb[novoc]{_t},
%   \arb[novoc]{d}, \arb[novoc]{_d}, \arb[novoc]{r}, \arb[novoc]{z},
%   \arb[novoc]{s}, \arb[novoc]{^s}, \arb[novoc]{.s}, \arb[novoc]{.d},
%   \arb[novoc]{.t}, \arb[novoc]{.z}, \arb[novoc]{l}, \arb[novoc]{n},
%   after the article \arb[fullvoc]{al-}:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}[text only]
  Unlike \package{arabtex} and \package{arabxetex},
  \package{arabluatex} \emph{never requires the solar letter to be
    written twice}, as it automatically generates the euphonic
  \arb[trans]{ta^sdId} above the letter that carries it, whether the
  article is written in the assimilated form or not, e.g. |al-^samsu|
  \arb[voc]{al-^samsu} \arb[trans]{al-^samsu}, or |a^s-^samsu|
  \arb[voc]{a^s-^samsu} \arb[trans]{a^s-^samsu}.
\end{arabluacode}
% \iffalse
%</example>
% \fi
% \begin{quote}
%   |al-tamru| \arb[voc]{al-tamru} \arb[trans]{al-tamru},
%   |al-ra.hm_anu| \arb[voc]{al-ra.hm_anu} \arb[trans]{al-ra.hm_anu},
%   |al-.zulmu| \arb[voc]{al-.zulmu} \arb[trans]{al-.zulmu},
%   |al-lu.gaTu| \arb[voc]{al-lu.gaTu} \arb[trans]{al-lu.gaTu}.
% \end{quote}
% \item With the letters \arb[novoc]{r}, \arb[novoc]{l}, \arb[novoc]{m},
% \arb[novoc]{w}, \arb[novoc]{y} after \arb[voc]{n} with
% \arb[trans]{jazmaT}, and also after the \arb[trans]{tanwIn}:---
% \begin{quote}
%   Note the absence of \arb[trans]{sukUn} above the passed over
%   \arb[novoc]{n} in the following examples, each of which is
%   accompanied with a consistent transliteration: |min rabbi-hi|
%   \arb[fullvoc]{min rabbi-hi}, \arb[trans]{min rabbi-hi},
%   |min| |layliN| \arb[fullvoc]{min layliN} \arb[trans]{min layliN},
%   |'an| |yaqtula| \arb[fullvoc]{'an yaqtula} \arb[trans]{'an yaqtula}.
%   
%   With \arb[trans]{tanwIn}: |kitAbuN| |mubInuN| \arb[voc]{kitAbuN
%   mubInuN} \arb[trans]{kitAbuN mubInuN}.
% \end{quote}
% \item With the letter \arb[voc]{t} after the dentals
%   \arb[novoc]{_t}, \arb[novoc]{d}, \arb[novoc]{_d}, \arb[novoc]{.d},
%   \arb[novoc]{.t}, \arb[novoc]{.z} in certain parts of the verb:
%   this kind of assimilation, e.g. \arb[voc]{labi_tttu} for
%   \arb[voc]{labi_ttu} \arb[trans]{labi_ttu}, will be discarded here,
%   as it is largely condemned by the
%   grammarians \parencite[see][i. 16 B--C]{Wright}.
% \end{enumerate}
%
% \paragraph{The definite article and the \arb[trans]{'alifu 'l-wa.sli}}
% At the beginning of a sentence, \txarb{\char"0671} is never written,
% as \arb[fullvoc]{'l-.hamdu li-ll_ahi}; instead, to indicate that the
% \arb[trans]{'alif} is a connective \arb[trans]{'alif}
% (\arb[trans]{'alifu 'l-wa.sli}), the \arb[trans]{hamzaT} is omitted
% and only its accompanying vowel is expressed:
% \begin{quote}
%   |al-.hamdu| |li-l-l_ahi| \arb[fullvoc]{al-.hamdu li-l-l_ahi}
%   \arb[trans]{al-.hamdu li-l-l_ahi}.
% \end{quote}
% As said above in section\vref{fullvoc-mode}, |fullvoc| is the mode
% in which \package{arabluatex} expresses the \arb[trans]{sukUn} and
% the \arb[trans]{wa.slaT}. \package{arabluatex} will take care of
% doing this automatically provided that the vowel which is to be
% absorbed by the final vowel of the preceding word is properly
% encoded, like so:---
% \begin{enumerate}[(a)]
% \item Definite article at the beginning of a sentence is encoded\\
%   \arabluaverb{al-}, or \arabluaverb{a<solar letter>-}\\ if one
%   wishes to mark the assimilation---which is in no way required, as
%   \package{arabulatex} will detect all cases of assimilation.
% \item Definite article inside sentences is encoded\\ \arabluaverb{'l-}
%   or \arabluaverb{'<solar letter>-}.
% \item In all remaining cases of elision, the \arb[trans]{'alifu
% 'l-wa.sli} is expressed by the vowel that accompanies the omitted
% \arb[trans]{hamzaT}: \meta{u, a, i}.
% \end{enumerate}
% \begin{quote}
%   \textbf{Article}: |bAbu| |'l-madrasaTi| \arb[fullvoc]{bAbu
%   'l-madrasaTi} \arb[trans]{bAbu 'l-madrasaTi}, |al-maqAlaTu|
%   |'l-'_Ul_A| \arb[fullvoc]{al-maqAlaTu 'l-'_Ul_A}
%   \arb[trans]{al-maqAlaTu 'l-'_Ul_A}, |al-lu.gaTu| |'l-`arabiyyaTu|
%   \arb[fullvoc]{al-lu.gaTu 'l-`arabiyyaTu} \arb[trans]{al-lu.gaTu
%   'l-`arabiyyaTu}, |fI| |.sinA`aTi| |'l-.tibbi| \arb[fullvoc]{fI
%   .sinA`aTi 'l-.tibbi} \arb[trans]{fI .sinA`aTi 'l-.tibbi}, |'il_A|
%   |'l-intiqA.di| \arb[fullvoc]{'il_A 'l-intiqA.di} \arb[trans]{'il_A
%   'l-intiqA.di}, |fI| |'l-ibtidA'i| \arb[fullvoc]{fI 'l-ibtidA'i}
%   \arb[trans]{fI 'l-ibtidA'i}, |'abU| |'l-wazIri| \arb[fullvoc]{'abU
%   'l-wazIri} \arb[trans]{'abU 'l-wazIri}, |fa-lammA| |ra'aW|
%   |'l-najma| \arb[fullvoc]{fa-lammA ra'aW 'l-najma}
%   \arb[trans]{fa-lammA ra'aW 'l-najma}.
%
%   \textbf{Particles}:---
%   \begin{enumerate}[(a)]
%   \item \arb[trans]{li-}: \arb[trans]{'alifu 'l-wa.sli} is omitted
%     in the article \arb[fullvoc]{al} when it is preceded by the
%     preposition \arb[fullvoc]{li}: |li-l-rajuli|
%     \arb[fullvoc]{li-l-rajuli}
%     \arb[trans]{li-l-rajuli}.\\
%     If the first letter of the noun be \arb[novoc]{l}, then the
%     \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
%   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
%   expressed: |fI| |'l-madInaTi| \arb[fullvoc]{fI 'l-madInaTi}
%   \arb[trans]{fI 'l-madInaTi}, |wa-'l-rajulu|
%   \arb[fullvoc]{wa-'l-rajulu} \arb[trans]{wa-'l-rajulu},
%   |bi-'l-qalami| \arb[fullvoc]{bi-'l-qalami}
%   \arb[trans]{bi-'l-qalami}, |bi-'l-ru`bi|
%   \arb[fullvoc]{bi-'l-ru`bi} \arb[trans]{bi-'l-ru`bi}.
%   \end{enumerate}
%   
%   \textbf{Perfect active, imperative, nomen actionis}: |qAla|
%   |isma`| \arb[fullvoc]{qAla isma`} \arb[trans]{qAla isma`}, |qAla|
%   |uqtul| \arb[fullvoc]{qAla uqtul} \arb[trans]{qAla uqtul}, |huwa|
%   |inhazama| \arb[fullvoc]{huwa inhazama} \arb[trans]{huwa
%   inhazama}, |wa-ustu`mila| \arb[fullvoc]{wa-ustu`mila}
%   \arb[trans]{wa-ustu`mila}, |qad-i| |in.sarafa| \arb[fullvoc]{qadi
%   in.sarafa} \arb[trans]{qadi in.sarafa}, |al-iqtidAru|
%   \arb[fullvoc]{al-iqtidAru} \arb[trans]{al-iqtidAru}, |'il_A|
%   |'l-intiqA.di| \arb[fullvoc]{'il_A 'l-intiqA.di} \arb[trans]{'il_A
%   'l-intiqA.di}, |lawi| |istaqbala| \arb[fullvoc]{lawi istaqbala}
%   \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}.
% \end{quote}
%
% \subparagraph{\arb[trans]{'alifu 'l-wa.sli} preceded by a long
% vowel} The long vowel preceding the connective \arb[trans]{'alif} is
% shortened in pronunciation \parencite[i. 21 B--D]{Wright}. This is
% does not appear in the Arabic script, but \package{arabluatex} takes
% it into account in some transliteration standards:---
% \begin{quote}
%   |fI| |'l-nAsi| \arb[fullvoc]{fI 'l-nAsi} \arb[trans]{fI 'l-nAsi},
%   |'abU| |'l-wazIri| \arb[fullvoc]{'abU 'l-wazIri} \arb[trans]{'abU
%   'l-wazIri}, |fI| |'l-ibtidA'i| \arb[fullvoc]{fI 'l-ibtidA'i}
%   \arb[trans]{fI 'l-ibtidA'i}, |_dU 'l-i`lAli| \arb[fullvoc]{_dU
%   'l-i`lAli} \arb[trans]{_dU 'l-i`lAli}.
% \end{quote}
%
% \subparagraph{\arb[trans]{'alifu 'l-wa.sli} preceded by a diphthong}
% The diphthong is resolved into two simple vowels \parencite[i. 21
% D--22 A]{Wright} viz. \emph{ay}~→ \emph{\u{a}\u{i}} and \emph{aw}~→
% \emph{\u{a}\u{u}}. \package{arabluatex} detects the cases in which
% this rule applies:---
% \begin{quote}
%   |fI| |`aynay| |'l-maliki| \arb[fullvoc]{fI `aynay 'l-maliki}
%   \arb[trans]{fI `aynay 'l-maliki}, |ix^say| |'l-qawma|
%   \arb[fullvoc]{ix^say 'l-qawma} \arb[trans]{ix^say 'l-qawma},
%   |mu.s.tafaw| |'l-l_ahi| \arb[fullvoc]{mu.s.tafaw 'l-l_ahi}
%   \arb[trans]{mu.s.tafaw 'l-l_ahi}.
%
%   |ramaW| |'l-.hijAraTa| \arb[fullvoc]{ramaW 'l-.hijAraTa}
%   \arb[trans]{ramaW 'l-.hijAraTa}, |fa-lammA| |ra'aW | |'l-najma|
%   \arb[fullvoc]{fa-lammA ra'aW 'l-najma} \arb[trans]{fa-lammA ra'aW
%   'l-najma}.
% \end{quote}
%
% \subparagraph{\arb[trans]{'alifu 'l-wa.sli} preceded by a consonant
% with \arb[trans]{sukUn}}
% The vowel which the consonant takes, either its original vowel, or
% that which belongs to the connective \arb[trans]{'alif} or the
% \arb[trans]{kasraT}; in most of the cases \parencite[i. 22
% A--C]{Wright}, it is encoded explicitly, like so:---
% \begin{quote}
%   |'antumu| |'l-kA_dibUna| \arb[fullvoc]{'antumu 'l-kA_dibUna}
%   \arb[trans]{'antumu 'l-kA_dibUna}, |ra'aytumu| |'l-rajula|
%   \arb[fullvoc]{ra'aytumu 'l-rajula} \arb[trans]{ra'aytumu
%   'l-rajula}, |mani| |'l-ka_d_dAbu| \arb[fullvoc]{mani 'l-ka_d_dAbu}
%   \arb[trans]{mani 'l-ka_d_dAbu}, |qatalati| |'l-rUmu|
%   \arb[fullvoc]{qatalati 'l-rUmu} \arb[trans]{qatalati
%   \cap{'l-rUmu}}.
% \end{quote}
% However, the Arabic script does not shows the \arb[trans]{kasraT}
% which is taken by the nouns having \arb[trans]{tanwIn} although it
% is explicit in pronunciation and must appear in some transliteration
% standards. \package{arabluatex} takes care of this automatically:---
% \begin{quote}
%   |mu.hammaduN| |'l-nabI| \arb[fullvoc]{mu.hammaduN 'l-nabI}
%   \arb[trans]{\cap{m}u.hammaduN 'l-nabI}.
% \end{quote}
%
% \subsection{Special orthographies}
% \paragraph{The name of God}
% The name of God, \arb[voc]{al-l_ahu}, is compounded of the article
% \arb[fullvoc]{al-}, and \arb[fullvoc]{'ilAhu} (noted
% \arb[fullvoc]{'il_ahu} with the defective \arb[trans]{'alif}) so
% that it becomes \arb[fullvoc]{al-'ilAhu}; then the
% \arb[trans]{hamzaT} is suppressed, its vowel being transferred to
% the \arb[novoc]{l} before it, so that there remains
% \arb[voc]{alil_ahu} \parencite[I refer to][I. 83
% col. 1]{Lane}. Finally, the first \arb[novoc]{l} is made quiescent
% and incorporated into the other, hence the \arb[trans]{ta^sdId}
% above it. As \package{arabluatex} never requires a solar letter to
% be written twice (see above, section\vref{euphonic-tashdid}), the
% name of God is therefore encoded |al-l_ahu| or |'l-l_ahu|:---
% \begin{quote}
%   |al-l_ahu| \arb[fullvoc]{al-l_ahu} \arb[trans]{al-l_ahu},
%   \verb+yA|+ |al-l_ahu| \arb[fullvoc]{yA| al-l_ahu} \arb[trans]{yA|
%   al-l_ahu}, \verb+'a-fa|-al-l_ahi+ |la-ta.g`alanna|
%   \arb[fullvoc]{'a-fa|-al-l_ahi la-ta.g`alanna}
%   \arb[trans]{'a-fa|-al-l_ahi la-ta.g`alanna}, |bi-'l-l_ahi|
%   \arb[fullvoc]{bi-'l-l_ahi} \arb[trans]{bi-'l-l_ahi}, |wa-'l-l_ahi|
%   \arb[fullvoc]{wa-'l-l_ahi} \arb[trans]{wa-'l-l_ahi}, |bi-smi|
%   |'l-l_ahi| \arb[fullvoc]{bi-smi 'l-l_ahi} \arb[trans]{bi-smi
%   'l-l_ahi}, |al-.hamdu| |li-l-l_ahi| \arb[fullvoc]{al-.hamdu
%   li-l-l_ahi} \arb[trans]{al-.hamdu li-l-l_ahi}, |li-l-l_ahi|
%   |'l-qA'ilu| \arb[fullvoc]{li-l-l_ahi 'l-qA'ilu}
%   \arb[trans]{li-l-l_ahi 'l-qA'ilu}.
% \end{quote}
% 
%
%
% \StopEventually{}
%
% \section{Implementation}
%
% \iffalse
%<*package>
% \fi
% 
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{arabluatex}%
[2016/01/26 v1.0 ArabTeX-like interface for LuaLaTeX]
\RequirePackage{ifluatex}
%    \end{macrocode}
% \package{arabluatex} requires \LuaLaTeX\ of course.
%    \begin{macrocode}
\ifluatex\else
 \PackageError{arabluatex}{lualatex needed}{%
  Package `arabluatex' needs LuaTeX.\MessageBreak
  So you should use `lualatex' to process your document!\MessageBreak
  See documentation of `arabluatex' for further information.}%
  \expandafter\expandafter\expandafter\csname endinput\endcsname
\fi
%    \end{macrocode}
%    \begin{macrocode}
\DeclareOption{voc}{\def\al@mode{voc}}
\DeclareOption{fullvoc}{\def\al@mode{fullvoc}}
\DeclareOption{novoc}{\def\al@mode{novoc}}
\DeclareOption{trans}{\def\al@mode{trans}}
\ExecuteOptions{voc}
\ProcessOptions\relax
\def\al@mode@voc{voc}
\def\al@mode@fullvoc{fullvoc}
\def\al@mode@novoc{novoc}
\def\al@mode@trans{trans}
% \newif\ifal@mode@defined
\RequirePackage{fontspec}
\RequirePackage{amsmath}
\RequirePackage{etoolbox}
\RequirePackage{luacode}
\RequirePackage{xparse}
\RequirePackage{environ}
\luadirect{dofile(kpse.find_file("arabluatex.lua"))}
%    \end{macrocode}
% This is needed by the current versions of \package{polyglossia} and
% \package{luabidi}.  \package{luabidi} provides a \cs{Footnote}
% command. Use it as well if it is loaded.
%    \begin{macrocode}
\luadirect{tex.enableprimitives("luatex",tex.extraprimitives("omega"))}
%    \end{macrocode}
%    \begin{macrocode}
\AtBeginDocument{\ifdefined\arabicfont\relax\else
\PackageWarning{arabluatex}{\string\arabicfont\ is not defined!^^JI
  will try to load Amiri}%
\newfontfamily\arabicfont[Script=Arabic]{Amiri}\fi}%
\AtBeginDocument{\def\setRL{\pardir TRT\textdir TRT}}
\AtBeginDocument{\def\setLR{\pardir TLT\textdir TLT}}
\AtBeginDocument{\ifdef{\LR}%
  {\RenewDocumentCommand{\LR}{m}{\bgroup\textdir TLT\rmfamily#1\egroup}}
  {\NewDocumentCommand{\LR}{m}{\bgroup\textdir TLT\rmfamily#1\egroup}}}
\AtBeginDocument{\ifdef{\RL}%
  {\RenewDocumentCommand{\RL}{m}{\bgroup\textdir TRT\rmfamily#1\egroup}}
  {\NewDocumentCommand{\RL}{m}{\bgroup\textdir TRT#1\rmfamily\egroup}}}
\AtBeginDocument{\ifdef{\aemph}%
  {\RenewDocumentCommand{\aemph}{m}{$\overline{\text{#1}}$}}
  {\NewDocumentCommand{\aemph}{m}{$\overline{\text{#1}}$}}}
\def\al@trans@style{\itshape}%
\NewDocumentCommand{\SetTranslitStyle}{m}{\def\al@trans@style{#1}}
\def\al@trans@convention{dmg}
\NewDocumentCommand{\SetTranslitConvention}{m}{\def\al@trans@convention{#1}}
\DeclareDocumentCommand{\cap}{m}%
  {\luadirect{tex.sprint(cap(\luastringN{#1}))}}
\DeclareDocumentCommand{\txarb}{+m}{\bgroup\textdir
  TRT\arabicfont#1\egroup}
\DeclareDocumentCommand{\txtrans}{+m}{\bgroup\textdir
  TLT\rmfamily#1\egroup}
%    \end{macrocode}
% \begin{macro}{\arb}
% Here begins the description of \cs{arb}
%    \begin{macrocode}
\DeclareDocumentCommand{\arb}{O{\al@mode} +m}%
{\edef\@tempa{#1}%
  \ifx\@tempa\al@mode@voc%
  \bgroup\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processvoc(\luastringN{#2}))}\egroup%
  \else%
  \ifx\@tempa\al@mode@fullvoc%
  \bgroup\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processfullvoc(\luastringN{#2}))}\egroup%
  \else%
  \ifx\@tempa\al@mode@novoc%
  \bgroup\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processnovoc(\luastringN{#2}))}\egroup%
  \else%
  \ifx\@tempa\al@mode@trans%
  \bgroup\textdir TLT\al@trans@style%
  \luadirect{tex.sprint(processtrans(\luastringN{#2},
    \luastringO{\al@trans@convention}))}\egroup%
  \else%
  \fi\fi\fi\fi}
%    \end{macrocode}
% \end{macro}
% \begin{environment}{arab}
% Here comes the description of the environment |arab|
%    \begin{macrocode}
\NewEnviron{arab}[1][\al@mode]%
{\par\edef\@tempa{#1}%
  \ifx\@tempa\al@mode@voc%
  \bgroup\pardir TRT\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processvoc(\luastringO{\BODY}))}\egroup%
  \else%
  \ifx\@tempa\al@mode@fullvoc%
  \bgroup\pardir TRT\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processfullvoc(\luastringO{\BODY}))}\egroup%
  \else%
  \ifx\@tempa\al@mode@novoc%
  \bgroup\pardir TRT\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processnovoc(\luastringO{\BODY}))}\egroup%
  \else \ifx\@tempa\al@mode@trans%
  \bgroup\pardir TLT\textdir TLT\al@trans@style%
  \luadirect{tex.sprint(processtrans(\luastringO{\BODY},
    \luastringO{\al@trans@convention}))}\egroup%
  \else \fi\fi\fi\fi}[\par]
%    \end{macrocode}
% \end{environment}
%    \begin{macrocode}
\DeclareDocumentCommand{\Marginpar}{m}{\marginpar{\textdir TLT #1}}
\RenewDocumentCommand{\thefootnote}{}{\bgroup\textdir
  TLT\arabic{footnote}\egroup}
\DeclareDocumentCommand{\LRfootnote}{m}{\bgroup\pardir
  TLT\LR{\footnote{#1}}\egroup}
\endinput
%    \end{macrocode}
%
% \printbibliography
%
% \iffalse
%</package>
% \fi
%
% \Finale
\endinput