% \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/03/29 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;+onum;+hlig}}
\setmainfont{Libertinus Serif}
\setsansfont{Libertinus Sans}
\setmonofont[Scale=.9]{Libertinus Mono}
\usepackage{arabluatex}[2016/03/29]
\usepackage{polyglossia}
\setdefaultlanguage{english}
\setotherlanguage{arabic}
\usepackage{varioref}
\usepackage{hypdoc}
\hypersetup{unicode=true, colorlinks, allcolors=blue,
  linktocpage=true, pdfauthor={Robert Alessi}, pdftitle={The
    arabluatex package}}
\usepackage[toc,lot]{multitoc}
\usepackage{paralist}
\setdefaultitem{\textendash}{\textendash}{\textendash}{\textendash}
\usepackage{cleveref}
\usepackage{quoting}
\quotingsetup{noorphans, rightmargin=0pt}
\renewcommand*{\quotingfont}{\footnotesize}
\usepackage[position=below]{caption}
\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}
\usepackage{xcolor}
\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}
  \addcontentsline{toc}{section}{Change History}
  \PrintChanges
  \addcontentsline{toc}{section}{Index}
  \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/03/29}{Initial release}
%
% \DoNotIndex{\newcommand,\newenvironment,\renewcommand}
% \DoNotIndex{\~,\AtBeginDocument,\bgroup,\csname}
% \DoNotIndex{\DeclareDocumentCommand,\def,\edef,\egroup}
% \DoNotIndex{\else,\endcsname,\endinput,\expandafter,\fi}
% \DoNotIndex{\ifdef,\ifdefined,\ifx,\MessageBreak,\NeedsTeXFormat}
% \DoNotIndex{\NewDocumentCommand,\newif,\PackageError,\PackageWarning}
% \DoNotIndex{\relax,\RenewDocumentCommand,\string}
% 
% \providecommand*{\url}{\texttt}
% \GetFileInfo{arabluatex.dtx}
% 
% \title{\tcbox[enhanced, tikznode, drop lifted shadow, colback=white,
% boxrule=.25mm]%
% {The \textsf{arabluatex} package\\
% \fileversion\ -- \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
% \footnotesize
% \tableofcontents
% \listoftables
% \normalsize
% 
% \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, or in different roman
%   transliterations. It further allows many typographical
%   refinements. 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.
% \end{abstract}
%
% \section*{License and disclamer}
% Copyright \textcopyright\ 2016  Robert Alessi
%
% \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.
%
% This release of \package{arabluatex} consists of the following
% source files:
% \begin{compactitem}
% \item |arabluatex.ins|
% \item |arabluatex.dtx|
% \item |arabluatex.lua|
% \item |arabluatex_voc.lua|
% \item |arabluatex_fullvoc.lua|
% \item |arabluatex_novoc.lua|
% \item |arabluatex_trans.lua|
% \item |arabluatex.bib|
% \end{compactitem}
%
% \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.
%
% \label{ref:tei-to-come}
% 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{\label{fn:arabtex-languages}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.\footnote{With
% one exception: see \vref{sec:abjad}.}
%
% \paragraph{Font setup}
% If you wish to use your own Arabic font, you can define it before
% 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}
% \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
% 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 \vref{sec:quoting}).
%
% \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 is
%   selected by default;
% \item[loc] \emph{Library of Congress}.
% \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:---\label{ref:juha-code}
% \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}
%
% \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
% 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}
% \captionlistentry{Arab\TeX\ consonants}\\[-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: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*{\Cref*{tab:arabtex-consonants}: Standard Arab\TeX\ (consonants)}
% \end{longtable}
%
% \subsection{Vowels}
% \subsubsection{Long 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
% \endfirsthead
% \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| \\
% \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*{\Cref*{tab:arabtex-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}
% \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
% \endfirsthead
% \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| \\
% \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*{\Cref*{tab:arabtex-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 \vref{sec:quoting}.}
%
% \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 \vref{sec:quoting});
% \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}} \label{ref:hamza}It is written
% \meta{\texttt{'}}, its carrier being determined by contextual
% analysis. In case one wishes to bypass this mechanism, he can use
% the \enquote{quoting} feature that is described below in
% \vref{sec:quoting}.
% \begin{quote}
%   \textbf{Initial \arb[trans]{hamzaT}}: |'asaduN| \arb[voc]{'asaduN}
%   \arb[trans]{'asaduN}, |'u_htuN| \arb[voc]{'u_htuN}
%   \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}} \label{ref:madda}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}} \label{ref:necessary-tashdid}always follows a
% vowel, whether short or long \parencite[see][i. 15 A--B]{Wright}. It
% is encoded in writing the consonant that carries it twice:
% \begin{quote}
%   |`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}}
% 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{compactenum}[(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]\label{euphonic-tashdid}
  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 be 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{compactenum}
%
% \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 on \cpageref{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{compactenum}[(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{compactenum}
% \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{compactenum}[(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 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
%   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{compactenum}
%   
%   \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}, |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 forms 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
% 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}
% \label{ref:muhammaduni}
% 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, \vpageref{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|+\footnote{\label{fn:pipe-allah-01}Note the
%   \enquote{pipe} character \enquote*{\textbar} here after |yA| and
%   below after |fa| before footnote mark \ref{fn:pipe-allah-02}: it
%   is needed by the |dmg| transliteration mode as in this mode any
%   vowel at the commencement of a word preceded by a word that ends
%   with a vowel, either short or long, is absorbed by this vowel
%   viz. \arb[trans]{`al_A 'l-.tarIqi}. See \vref{sec:pipe} on the
%   \enquote{pipe} and \vref{sec:transliteration} 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}
%   \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}
%
% \paragraph{The conjunctive \arb[voc]{alla_dI}}
% Although it is compounded of the article \arb[fullvoc]{al}, the
% demonstrative letter \arb[novoc]{l} and the demonstrative pronoun
% \arb[voc]{_dA}, both masculine and feminine forms that are written
% defectively are encoded |alla_dI| and |allatI| respectively. Forms
% starting with the connective \arb[trans]{'alif} are encoded
% |'lla_dI| and |'llatI|:---
% \begin{quote}
%   |'a_hAfu| |mina| |'l-maliki| |'lla_dI| |ya.zlimu| |'l-nAsa|
%   \arb[fullvoc]{'a_hAfu mina 'l-maliki 'lla_dI ya.zlimu 'l-nAsa}
%   \arb[trans]{'a_hAfu mina 'l-maliki 'lla_dI ya.zlimu 'l-nAsa},
%   |`udtu| |'l-^say_ha| |'lladI| |huwa| |marI.duN|
%   \arb[fullvoc]{`udtu 'l-^say_ha 'lladI huwa marI.duN}
%   \arb[trans]{`udtu 'l-^say_ha 'lladI huwa marI.duN}, |mA| |'anA|
%   |bi-'lla_dI| |qA'iluN| |la-ka| |^say'aN| \arb[fullvoc]{mA 'anA
%   bi-'lla_dI qA'iluN la-ka ^say'aN} \arb[trans]{mA 'anA bi-'lla_dI
%   qA'iluN la-ka ^say'aN}.
%
%   |'ari-nA| |'lla_dayni| |'a.dallA-nA| |mina| |'l-jinni|
%   |wa-'l-'insi| \arb[fullvoc]{'ari-nA 'lla_dayni 'a.dallA-nA mina
%   'l-jinni wa-'l-'insi} \arb[trans]{'ari-nA 'lla_dayni 'a.dallA-nA
%   mina 'l-jinni wa-'l-'insi}.
% \end{quote}
% The other forms are encoded regularly as |al-l| or |'l-l|:---
% \begin{quote}
%   |fa-'innA| |na_dkuru| |'l-.sawtayni| |'l-la_dayni| |rawaynA-humA|
%   |`an| |ja.h.zaTa| \arb[fullvoc]{fa-'innA na_dkuru 'l-.sawtayni
%   'l-la_dayni rawaynA-humA `an \cap{ja.h.zaTa}} \arb[trans]{fa-'innA
%   na_dkuru 'l-.sawtayni 'l-la_dayni rawaynA-humA `an
%   \cap{ja.h.zaTa}}.
%
%   And also: |al-la_dAni| \arb[fullvoc]{al-la_dAni}
%   \arb[trans]{al-la_dAni}, |al-la_dayni| \arb[fullvoc]{al-la_dayni}
%   \arb[trans]{al-la_dayni}, |al-latAni| \arb[fullvoc]{al-latAni}
%   \arb[trans]{al-latAni}, |al-latayni| \arb[fullvoc]{al-latayni}
%   \arb[trans]{al-latayni}, |al-lAtI| \arb[fullvoc]{al-lAtI}
%   \arb[trans]{al-lAtI},
%   \verb+al-lA'|Ati+\footnote{\label{fn:pipe-madda}Note here the
%   \enquote{pipe} character \enquote*{\textbar}: as already stated
%   \vpageref{ref:madda}, the sequence |'A| usually encodes
%   \arb[trans]{'alif} with \arb[trans]{hamzaT} followed by
%   \arb[trans]{'alif} of prolongation which is represented in writing
%   \arb[trans]{'alif} with \arb[trans]{maddaT}: \arb[voc]{A"'}. The
%   \enquote{pipe} character prevents this rule from being
%   applied. See \vref{sec:pipe}.}  \arb[fullvoc]{al-lA'|Ati}
%   \arb[trans]{al-lA'|Ati}, |al-lA'I| \arb[fullvoc]{al-lA'I}
%   \arb[trans]{al-lA'I}, and so forth.
% \end{quote}
%
% \subsection{Quoting}
% \label{sec:quoting}
% It is here referred to \enquote{quoting} after the package
% \package{arabtex}.\footnote{See \textcite[22]{pkg:arabtex}} The
% \enquote{quoting} mechanism of \package{arabluatex} is designed to
% be very similar in effect to the one of \package{arabtex}.
%
% To start with an example, suppose one types the following in |novoc|
% mode: \arb[novoc]{`ullima `ilma 'l-hay'aTi}; is it
% \arb[fullvoc]{`ullima}, \emph{he was taught the science of
% astronomy}, or \arb[fullvoc]{`allama}, \emph{he taught the science
% of astronomy}? In order to disambiguate this clause, it may be
% sensible to put a \arb[trans]{.dammaT} above the first \arb[voc]{`}:
% \arb[novoc]{`"ullima `ilma 'l-hay'aTi}, which is achieved by
% \enquote{quoting} the vowel |u|, like so: |`"ullima|, or, with no
% other vowel than the required |u|: |`"ullm|.
%
% This is how the \enquote{quoting} mechanism works: metaphorically
% speaking, it acts as a \emph{toggle switch}. If something, in a
% given mode, is supposed to be visible, \enquote{quoting} hides it;
% conversely, if it is supposed not to, it makes it visible.
%
% As shown above, \enquote{quoting} means inserting one straight
% double quote (|"|) \emph{before} the letter that is to be acted
% upon. Its effects depend on the mode which is currently selected,
% either |novoc|, |voc| or |fullvoc|:---
%
% \paragraph{\texttt{novoc}} In this mode, \enquote{quoting}
% essentially means make visible something that ought not to be so.
% \begin{compactenum}[(a)]
% \item Quoting a vowel, either short or long, makes the
%   \arb[trans]{.dammaT}, \arb[trans]{fat.haT} or \arb[trans]{kasraT}
%   appear above the appropriate consonant:---
% \begin{quote}
%   |`"ullima| |`ilma| |'l-hay'aTi| \arb[novoc]{`"ullima `ilma
%   'l-hay'aTi} \arb[trans]{`"ullima `ilma 'l-hay'aTi}, |ya.gz"UA|
%   \arb[novoc]{ya.gz"UA} \arb[trans]{ya.gz"UA}.
% \end{quote}
% \item The same applies when \enquote{quoting} the
%   \arb[trans]{tanwIn}:---
% \begin{quote}
%   |wa-'innA| |sawfa| |tudriku-nA| |'l-manAyA| |muqadd"araT"aN|
%   \arb[novoc]{wa-'innA sawfa tudriku-nA 'l-manAyA muqadd"araT"aN},
%   \arb[trans]{wa-'innA sawfa tudriku-nA 'l-manAyA muqadd"araT"aN}.
% \end{quote}
% \item \label{ref:quoted-sukun-b}If no vowel follows the straight
%   double quote, then a \arb[trans]{sukUn} is put above the preceding
%   consonant:---
% \begin{quote}
%   |qAla isma`"| \arb[novoc]{qAla isma`"} \arb[trans]{qAla isma`"},
%   |jA'at"| |hinduN| \arb[voc]{jA'at" hinduN} \arb[trans]{jA'at"
%   hinduN}, |^sabIhuN| |bi-man| |q"u.ti`at"| |qadamA-hu|
%   \arb[novoc]{^sabIhuN bi-man q"u.ti`at" qadamA-hu}
%   \arb[trans]{^sabIhuN bi-man q"u.ti`at" qadamA-hu}.
% \end{quote}
% \item At the commencement of a word, the straight double quote is
%   interpreted as \arb[trans]{'alifu 'l-wa.sli}:---
% \begin{quote}
%   |wa-"ust"u`mila| \arb[novoc]{wa-"ust"u`mila}
%   \arb[trans]{wa-"ust"u`mila}, |huwa| |"inhazama| \arb[novoc]{huwa
%   "inhazama} \arb[trans]{huwa "inhazama}, |al-"intiqA.du|
%   \arb[novoc]{al-"intiqA.du} \arb[trans]{al-"intiqA.du}.
% \end{quote}
% \end{compactenum}
%
% \paragraph{\texttt{voc}}
% In accordance with the general rule, in this mode, \enquote{quoting}
% makes the vowels and the \arb[trans]{tanwIn} disappear, should this
% feature be required for some reason:---
% \begin{compactenum}[(a)]
% \item Short and long vowels:---
%   \begin{quote}
%     |q"Ala q"A'iluN| \arb[voc]{q"Ala q"A'iluN} \arb[trans]{q"Ala
%     q"A'iluN}, |ibnu 'abI 'u.saybi`aT"a| \arb[voc]{ibnu 'abI
%     'u.saybi`aT"a} \arb[trans]{\cap{ibnu} \cap{'abI}
%     \cap{'u.saybi`aT"a}}.
%   \end{quote}
% \item \arb[trans]{tanwIn}:---
%   \begin{quote}
%     |madInaT"aN| \arb[voc]{madInaT"aN} \arb[trans]{madInaT"aN},
%     |bAb"aN| \arb[voc]{bAb"aN} \arb[trans]{bAb"aN}, |hud"aN_A|
%     \arb[voc]{hud"aN_A} \arb[trans]{hud"aN_A}, |^say'"iN|
%     \arb[voc]{^say'"iN} \arb[trans]{^say'"iN}.
%   \end{quote}
% \end{compactenum}
% One may more usefully \enquote{quote} the initial vowels to write
% the \arb[trans]{hamzaT} above the \arb[trans]{'alif} or insert a
% straight double quote after a consonant not followed by a vowel to
% make the \arb[trans]{sukUn} appear:---
% \begin{compactenum}[(a)]
% \item \arb[trans]{'alifu 'l-wa.sli}:---
%   \begin{quote}
%     |fI "istisqA'a| \arb[voc]{fI "istisqA'a} \arb[trans]{fI
%     "istisqA'a}, |wa-"istisqA'u| \arb[voc]{wa-"istisqA'u}
%     \arb[trans]{wa-"istisqA'u}, |qAla| |"uhrub| |fa-lan| |tuqtala|
%     \arb[voc]{qAla "uhrub fa-lan tuqtala} \arb[trans]{qAla "uhrub
%     fa-lan tuqtala}.
%   \end{quote}
% \item \arb[trans]{sukUn}:---
%   \begin{quote}
%     |qAla| |uqtul"| |fa-lan| |tuqtala| \arb[voc]{qAla uqtul" fa-lan
%     tuqtala} \arb[trans]{qAla uqtul" fa-lan tuqtala}, |mA| |jA'at"|
%     |mini| |imra'aTiN| \arb[voc]{mA jA'at" mini imra'aTiN}
%     \arb[trans]{mA jA'at" mini imra'aTiN}, |kam"| |qad"| |ma.dat"|
%     |min"| |laylaTiN| \arb[voc]{kam" qad" ma.dat" min" laylaTiN}
%     \arb[trans]{kam" qad" ma.dat" min"
%     laylaTiN}.\label{ref:quoted-sukun-e}
%   \end{quote}
% \end{compactenum}
%
% \paragraph{\texttt{fullvoc}}
% In this mode, \enquote{quoting} may be used to take away any short
% vowel (or \arb[trans]{tanwIn}, as seen above) or any
% \arb[trans]{sukUn}:---
% \begin{quote}\label{ref:qrannun-full}
%   |al-jamru| |'l-.sayfiyyu| |'lla_dI| |kAna| \verb+bi-q"rAn"|nUna+
%   \arb[fullvoc]{al-jamru 'l-.sayfiyyu 'lla_dI kAna
%   \cap{bi-q"rAn"|nUna}} \arb[trans]{al-jamru 'l-.sayfiyyu 'lla_dI
%   kAna \cap{bi-q"rAn"|nUna}}.
% \end{quote}
%
% \subsubsection{\texorpdfstring{Quoting the
% \arb[trans]{hamzaT}}{Quoting the hamza}}
% \label{sec:quoting-hamza}
% As said above in \vref{ref:hamza}, the \arb[trans]{hamzaT} is always
% written \meta{\texttt{'}}, its carrier being determined by contextual
% analysis. \enquote{Quoting} this straight single quote character
% like so: \meta{\texttt{"'}} allows to determine the carrier of the
% \arb[trans]{hamzaT} freely, without any consideration for the
% context. \Cref{tab:quoted-hamza} gives the equivalents for all the
% possible carriers the \arb[trans]{hamzaT} may take:
% \begin{longtable}{llll}
% \captionlistentry{\enquote{Quoted} \arb[trans]{hamzaT}}\\[-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:quoted-hamza}
% \arb[novoc]{|"'} & \dmg{|"'} & \loc{|"'} & \verb+|"'+ \\
% \arb[novoc]{A"'} & \dmg{A"'} & \loc{A"'} & \verb|A"'| \\
% \arb[novoc]{a"'} & \dmg{a"'} & \loc{a"'} & \verb|a"'| \\
% \arb[novoc]{u"'} & \dmg{u"'} & \loc{u"'} & \verb|u"'| \\
% \arb[novoc]{w"'} & \dmg{w"'} & \loc{w"'} & \verb|w"'| \\
% \arb[novoc]{i"'} & \dmg{i"'} & \loc{i"'} & \verb|i"'| \\
% \arb[novoc]{y"'} & \dmg{y"'} & \loc{y"'} & \verb|y"'| \\
% \bottomrule
% \caption*{\Cref*{tab:quoted-hamza}: \enquote{Quoted} \arb[trans]{hamzaT}}
% \end{longtable}
%
% As one can see from \vref{tab:quoted-hamza}, the carrier of the
% \arb[trans]{hamzaT} is inferred from the letter that precedes the
% straight double quote \meta{\texttt{"}}. Of course, any
% \enquote{quoted} \arb[trans]{hamzaT} may take a short vowel, which
% is to be written \emph{after} the Arab\TeX\ equivalent for the
% \arb[trans]{hamzaT} itself, namely \meta{\texttt{'}}. For example,
% \arb[voc]{w"'a} is encoded \meta{\texttt{w"'a}}, while
% \arb[voc]{w"'"} is encoded \meta{\texttt{w"'"}}. In the latter
% example, the second straight double quote encodes the
% \arb[trans]{sukUn} in |voc| mode in accordance with the rule laid
% above \vpagerefrange{ref:quoted-sukun-b}{ref:quoted-sukun-e}.
% \begin{quote}
%   |'a`dA'ukum| \arb[fullvoc]{'a`dA'ukum} \arb[trans]{'a`dA'ukum},
%   \verb+'a`dA|"'ukum+ \arb[fullvoc]{'a`daA"'|"'ukum}
%   \arb[trans]{'a`dA|"'ukum}, |'a`dA'ikum| \arb[fullvoc]{'a`dA'ikum}
%   \arb[trans]{'a`dA'ikum}, \verb+'a`dA|"'ikum+
%   \arb[fullvoc]{'a`daA"'|"'ikum} \arb[trans]{'a`dA|"'ikum}.
% \end{quote}
%
% \subsection{The \enquote{pipe} character (\textbar)}
% \label{sec:pipe}
% In the terminology of Arab\TeX, the \enquote{pipe} character
% \enquote*{\textbar} is referred to as the \enquote{invisible
% consonant}. Hence, as already seen above in
% \vref{sec:quoting-hamza}, its usage to encode the
% \arb[trans]{hamzaT} alone, with no carrier: \verb+|"'+
% \arb[novoc]{|"'}.
%
% Aside from that usage, the \enquote{pipe} character is used to
% prevent almost any of the contextual analysis rules that are
% described above from being applied. Two examples have already been
% given to demonstrate how this particular mechanism works in
% \vref{fn:pipe-allah-01} and in \vref{fn:pipe-madda}. One more example
% follows:---
% \begin{quote}
%   \verb+bi-qrAn|nUna+ \arb[voc]{\cap{bi-qrAn|nUna}}
%   \arb[trans]{\cap{bi-qrAn|nUna}}, \enquote{in Crannon} (Thessaly,
%   Greece).\footnote{See more context \vpageref{ref:qrannun-full}.}
% \end{quote}
% As one can see, the \enquote{pipe} character between the two
% \meta{n} prevents the necessary \arb[trans]{ta^sdId} rule
% (\cpageref{ref:necessary-tashdid}) from being applied.
%
% \subsection{\texorpdfstring{Stretching characters: the
% \arb[trans]{ta.twIl}}{Stretching characters: the taṭ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}
% \label{sec:numerical-figures}
% The \emph{Indian numbers}, \arb[trans]{al-raqamu 'l-hindiyyu}, are
% ten in number, and they are compounded in exactly the same way as
% our numerals:---
% \begin{quote}
%   |1874| \arb[voc]{1874}, |123-456,789| \arb[voc]{123-456,789}, |fI|
%   |sanaTi| |1024| \arb[voc]{fI sanaTi 1024}
% \end{quote}
%
% \subsubsection{The \emph{abjad}}
% \label{sec:abjad}
% The numbers may also be expressed with letters from right to left
% arranged in accordance with the order of the Hebrew and Aramaic
% alphabets \parencite[see][i. 28 B--C]{Wright}. The
% \arb[trans]{'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
% help of \package{polyglossia}. If you wish to use the
% \arb[trans]{abjad} system, put in your preamble:---
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
\usepackage{polyglossia}
\setdefaultlanguage{english} % please adapt
\setotherlanguage{arabic} % to enable the 'abjad' numbers
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi %
% \DescribeMacro{\abjad} Then you may use the command
% \cs{abjad}\marg{number} in any of the |voc|, |fullvoc| and |novoc|
% modes, where \meta{number} may be any number between 1 and 1999,
% like so:---
% \begin{quote}
%   |\abjad{45}| |kitAbu-hu| |fI| |'l-`AdAti| \arb[voc]{\abjad{45}
%   kitAbu-hu fI 'l-`AdAti} \arb[trans]{45 kitAbu-hu fI
%   'l-`AdAti}.
% \end{quote}
%
% \iffalse
%<*example>
% \fi
\begin{arabluacode}[text only]
  Apart from this case, \package{arabluatex} makes no use of
  \package{polyglossia}. The support for the \arb[trans]{'abjad}
  numbering system is planned for inclusion in a future version of
  \package{arabluatex}.
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% \subsection{Additional characters}
% \label{sec:additional-characters}
% 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{Special applications}
% \label{sec:special-applications}
% \paragraph{Linguistics}
% The same horizontal stroke as the \arb[trans]{ta.twIl} (see
% \vref{sec:tatwil}) may be encoded \meta{B}; \meta{BB} will receive
% the \arb[trans]{ta^sdId}. This is useful to make linguistic
% annotations and comments on vowels:---
% \begin{quote}
%   |Bu| |Ba| |Bi| |BuN| |BaN| |BiN| \arb[voc]{Bu Ba Bi BuN BaN BiN}
%   \arb[trans]{Bu Ba Bi BuN BaN BiN}, |BBu| |BBa| |BBi| \arb[voc]{BBu
%   BBa BBi} \arb[trans]{BBu BBa BBi}, |B--aN| \arb[voc]{B--aN}
%   \arb[trans]{B--aN}, |B| \arb[voc]{B"}\,.
% \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. As 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, for 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}}, |.daraba| |\cap{zaydu}| |bnu|
%   |\cap{_h_alidiN}| |\cap{sa`da}| |bna| |\cap{`awfi}| |bni|
%   |\cap{`abdi}| |\cap{'l-l_ahi}| \arb[fullvoc]{.daraba \cap{zaydu}
%   bnu \cap{_h_alidiN} \cap{sa`da} bna \cap{`awfi} bni \cap{`abdi}
%   \cap{'l-l_ahi}} \arb[trans]{.daraba \cap{zaydu} bnu
%   \cap{_h_alidiN} \cap{sa`da} bna \cap{`awfi} bni \cap{`abdi}
%   \cap{'l-l_ahi}}.
% \end{quote}
% However, \cs{cap} must be used cautiously in some very particular
% cases, for the closing brace of its argument may prevent a rule from
% being applied. To take an example, as seen above
% \vpageref{ref:muhammaduni}, the transliteration of
% \arb[fullvoc]{\cap{m}u.hammaduN 'l-nabI} must be
% \arb[trans]{\cap{m}u.hammaduN 'l-nabI}, as nouns having the
% \arb[trans]{tanwIn} take a \arb[trans]{kasraT} in pronunciation
% before \arb[trans]{'alifu 'l-wa.sli}. In this case, encoding
% \arb[fullvoc]{mu.hammaduN} like so: |\cap{mu.hammaduN}| is wrong,
% because the closing brace would prevent \package{arabluatex} from
% detecting the sequence \meta{-uN} immediately followed by
% \meta{'-l}. Fortunately, this can be circumvented in a
% straightforward way by inserting only part of the noun in the
% argument of \cs{cap} vz. up to the first letter that is to be
% uppercased, like so: |\cap{m}u.hammaduN|.
%
% \subsection{Examples}
% \label{sec:examples-translit}
% Here follows in transliteration the story of
% \arb[trans]{\cap{ju.hA}} and his donkey (\arb[voc]{\cap{ju.hA
% wa-.himAru-hu}}). See the code \vpageref{ref:juha-code}:---
%
% \SetTranslitConvention{dmg}
% \begin{arab}[trans]
%   \LR{\textbf{\emph{\enquote*{dmg}} standard}:} 'at_A .sadIquN 'il_A
%   \cap{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 \cap{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 \cap{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 \cap{ju.hA} yanhaqu.} fa-qAla la-hu \cap{ju.hA}:
%   \enquote{.garIbuN 'amru-ka yA .sadIqI 'a-tu.saddiqu 'l-.himAra
%   wa-tuka_d_dibu-nI?}
% \end{arab}
% 
% \SetTranslitConvention{loc}
% \begin{arab}[trans]
%   \LR{\textbf{\emph{\enquote*{loc}} standard}:} 'at_A .sadIquN 'il_A
%   \cap{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 \cap{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 \cap{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 \cap{ju.hA} yanhaqu.} fa-qAla la-hu \cap{ju.hA}:
%   \enquote{.garIbuN 'amru-ka yA .sadIqI 'a-tu.saddiqu 'l-.himAra
%   wa-tuka_d_dibu-nI?}
% \end{arab}
% \SetTranslitConvention{dmg}
%
% \section{\LaTeX\ Commands in Arabic environments}
% \label{sec:commands-in-arb}
% \paragraph{General principle} \label{ref:cmd-inside-arabic}\LaTeX\
% commands are accepted in
% Arabic environments. The general principle which applies is that
% single-argument commands (\cs{command}\marg{arg}) such as
% \cs{emph}\marg{text}, \cs{textbf}\marg{text} and the like, are
% assumed to have Arabic text as their arguments:---
% \begin{quote}
%   |\abjad{45}| |kitAbu-hu| |\emph{fI| |'l-\cap{`AdAti}}|
%   \arb[voc]{\abjad{45} kitAbu-hu \emph{fI l-\cap{`AdAti}}}
%   \arb[trans]{45 kitAbu-hu \emph{fI 'l-\cap{`AdAti}}}.\footnote{This
%   is odd in Arabic script, but using such features as \cs{emph} or
%   \cs{textbf} is a matter of personal taste.}
% \end{quote}
% 
% The same applies to footnotes:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
\renewcommand{\footnoterule}%
   {\hfill\noindent\rule[1mm]{.4\textwidth}{.15mm}}
\begin{arab}
'inna 'abI kAna mina 'l-muqAtilaTi\footnote{al-muqAtilaTi:
al-muqAtilIna.}, wa-kAnat 'ummI min `u.zamA'i buyUti
'l-zamAzimaTi\footnote{al-zamAzimaTu: .tA'ifaTu mina
'l-fursi.}.
\end{arab}
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% Some commands, however, do not expect running text in their
% arguments, or one may wish to insert English text eg. in footnotes
% or in marginal notes. \package{arabluatex} provides a set of
% commands to handle such cases.
%
% \DescribeMacro{\LR} \cs{LR}\marg{arg} is designed to typeset its
% argument from left to right. It may be used in an Arabic
% environment, either \cs{arb}\marg{Arabic text} or \cs{begin}|{arab}|
% \meta{Arabic text} \cs{end}|{arab}|, for short insertions of left to
% right text, or to insert any \LaTeX\ command that would otherwise be
% rejected by \package{arabluatex}, such as commands the argument of
% which is expected to be a dimension or a unit of measurement.
%
% \DescribeMacro{\RL} \cs{RL}\marg{arg} does the same as
% \cs{LR}\marg{arg}, but typesets its argument from left to right. Even
% in an Arabic environment, this command may be useful. For example, to
% distinguish words with a different color, one may proceed like
% so:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
\begin{arab}
wa-'at_A _dU 'l-qarnayni 'ummaTaN 'llatI hiya fI
\LR{\textcolor{red}{\arb[fullvoc]{((ma.gribi 'l-^samsi))}}}
wa-lA binA'a la-hum yu'amminu-hum mina 'l-^samsi.
\end{arab}
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% \DescribeMacro{\LRfootnote} \DescribeMacro{\RLfootnote}
% \cs{LRfootnote}\marg{text} and \cs{RLfootnote}\marg{text} typeset
% left-to-right and right-to-left footnotes respectively in Arabic
% environments. Unlike \cs{footnote}\marg{text}, the arguments of both
% \cs{LRfootnote} and \cs{RLfootnote} are not expected to be Arabic
% text. For example, \cs{LRfootnote} may be used to insert English
% footnotes in running Arabic text:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
\arb[fullvoc]{\cap{z}ayduN\LRfootnote{\enquote{Zayd
is the son of ʿAmr}: the second noun is not in
apposition to the first, but forms part of
the predicate\ldots} "ibnu \cap{`amriNU}}
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% When footnotes are typeset from right to left, it may happen that
% the numbers of the footnotes that are at the bottom of the page be
% typeset in the wrong direction. For example, instead of an expected
% number 18, one may get 81. \package{arabluatex} is not responsible
% for this, but should it happen, it may be necessary to redefine in
% the preamble the \LaTeX\ macro \cs{thefootnote} like so:---\\
% \arabluaverb{\renewcommand*{\thefootnote}{\textsuperscript{\LR{\arabic{footnote}}}}}
% \DescribeMacro{\FixArbFtnmk} Another solution is to put in the
% preamble, below the line that loads \package{arabluatex}, the
% command \cs{FixArbFtnmk}. However, for more control over the layout
% of footnotes marks, it is advisable to use the package
% \package{scrextend}.\footnote{See
% \url{http://ctan.org/pkg/koma-script}; read the documentation of
% \package{KOMA-script} for details about the \cs{deffootnotemark} and
% \cs{deffootnote} commands.}
%
% \DescribeMacro{\LRmarginpar} The command \cs{LRmarginpar} does for
% marginal notes the same as \cs{LRfootnote} does for footnotes. Of
% course, it is supposed to be used in Arabic environments. Note that
% \cs{marginpar} also works in Arabic environments, but it acts as any
% other single-argument command inserted in Arabic environments. The
% general principle laid \vpageref{ref:cmd-inside-arabic} applies.
%
% \DescribeMacro{\setRL} \DescribeMacro{\setLR} \cs{setRL} and
% \cs{setLR} may be used to change the direction of paragraphs, either
% form left to right or from right to left. As an example, an
% easy way to typeset a right-to-left sectional title follows:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
\setRL
\section*{\arb{barzawayhi li-buzurjumihra bni 'l-buxtikAni}}
\setLR
\begin{arab}
qAla barzawayhi bnu 'azhara, ra'su 'a.tibbA'i fArisa...
\end{arab}
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% \paragraph{\package{reledmac}} The two-arguments command
% \cs{edtext}\marg{lemma}\marg{commands} is supported inside
% \cs{begin}|{arab}| \ldots\ \cs{end}|{arab}|. As an example, one may
% get \package{arabluatex} and \package{reledmac} to work together
% like so:---
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
\beginnumbering
\pstart
\begin{arab}
wa-ya.sIru ta.hta 'l-jildi
\edtext{\arb{.sadIduN}}{\Afootnote{M: \arb{.sadIdaN} E1}}
\end{arab}
\pend
\endnumbering
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi
% 
% \section{Future work}
% \label{sec:future-work}
% A short, uncommented, list of what is planned in the versions of
% \package{arabluatex} to come follows:
% \begin{compactenum}[(a)]
% \item Short-term:
%   \begin{compactenum}[i.] 
%   \item Support for typesetting Arabic poetry.
%   \item The \arb[trans]{\cap{qur'An}}: support for typesetting the
%     \arb[trans]{\cap{Qur'An}}.
%   \item \texttt{TEI xml} support: \package{arabluatex} will
%     interoperate with \texttt{TEI xml} through new global and local
%     options that will output Arabic in a \texttt{TEI xml} compliant
%     file in addition to the usual PDF output: see
%     \vpageref{ref:tei-to-come}.
%   \end{compactenum}
% \item Medium-term:
%   \begin{compactenum}[i.]
%   \item More languages: the list of supported languages will
%     eventually be the same as \package{arabtex}: see
%     \vref{fn:arabtex-languages}.
%   \item Formulate propositions for extending the Arab\TeX\ notation
%     and the transliteration tables. Include them in
%     \package{arabluatex}. See \vref{sec:additional-characters}.
%   \end{compactenum}
% \end{compactenum}
%
% \StopEventually{}
%
% \section{Implementation}
%
% \iffalse
%<*package>
% \fi
%
% The most important part of \package{arabluatex} relies on Lua
% functions and tables. Read the |.lua| files that accompany
% \package{arabluatex} for more information.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{arabluatex}%
[2016/03/29 v1.0 ArabTeX-like interface for LuaLaTeX]
\RequirePackage{ifluatex}
%    \end{macrocode}
% \package{arabluatex} requires \LuaLaTeX\ of course. Issue a warning
% if the document is processed with another engine.
%    \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}
% Declare the global options, and define them:
%    \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}
%    \end{macrocode}
% The following line will be used in the next release of
% \package{arabluatex}:
%    \begin{macrocode}
% \newif\ifal@mode@defined
%    \end{macrocode}
% Packages that are required by \package{arabluatex}:
%    \begin{macrocode}
\RequirePackage{fontspec}
\RequirePackage{amsmath}
\RequirePackage{etoolbox}
\RequirePackage{luacode}
\RequirePackage{xparse}
\RequirePackage{environ}
%    \end{macrocode}
% Here begins the real work: load |arabluatex.lua|:
%    \begin{macrocode}
\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}
% Font setup. If no Arabic font is selected, issue a warning message
% and attempt to load the Amiri font which is included in \TeX{}live:
%    \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}%
%    \end{macrocode}
% \begin{macro}{\setRL}
%   This neutralizes what is defined by the same command in
%   \package{luabidi}:
%    \begin{macrocode}
\AtBeginDocument{\def\setRL{\pardir TRT\textdir TRT}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\setLR}
%   The same applies to \cs{setLR}:
%    \begin{macrocode}
\AtBeginDocument{\def\setLR{\pardir TLT\textdir TLT}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\LR} This command typesets its argument from left to
% right. As \cs{LR} may be already defined, we need to redefine for
% it to suit our purpose:
%    \begin{macrocode}
\AtBeginDocument{\ifdef{\LR}%
  {\RenewDocumentCommand{\LR}{m}{\bgroup\textdir TLT\rmfamily#1\egroup}}
  {\NewDocumentCommand{\LR}{m}{\bgroup\textdir TLT\rmfamily#1\egroup}}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\RL} This one typesets its argument from right to
% left. Same remark as above regarding the need of redefinition.
%    \begin{macrocode}
\AtBeginDocument{\ifdef{\RL}%
  {\RenewDocumentCommand{\RL}{m}{\bgroup\textdir TRT\rmfamily#1\egroup}}
  {\NewDocumentCommand{\RL}{m}{\bgroup\textdir TRT#1\rmfamily\egroup}}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\aemph} Arabic emphasis. Needs to be redefined as well.
%    \begin{macrocode}
\AtBeginDocument{\ifdef{\aemph}%
  {\RenewDocumentCommand{\aemph}{m}{$\overline{\text{#1}}$}}
  {\NewDocumentCommand{\aemph}{m}{$\overline{\text{#1}}$}}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\SetTranslitStyle} By default any transliterated
% Arabic text is printed in italics. This can be changed globally in
% the preamble or at any point of the document:
%    \begin{macrocode}
\def\al@trans@style{\itshape}%
\NewDocumentCommand{\SetTranslitStyle}{m}{\def\al@trans@style{#1}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\SetTranslitConvention}
% \cs{SetTranslitConvention}\marg{convention} may be used to change
% the convention, which is |dmg| by default:
%    \begin{macrocode}
\def\al@trans@convention{dmg}
\NewDocumentCommand{\SetTranslitConvention}{m}{\def\al@trans@convention{#1}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\cap} Proper Arabic names or book titles should be
% passed to the command \cs{cap} so that they have their first letters
% uppercased. \cs{cap} is actually coded in Lua.
%    \begin{macrocode}
\DeclareDocumentCommand{\cap}{m}%
  {\luadirect{tex.sprint(cap(\luastringN{#1}))}}
%    \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
%   |utf8| Arabic text in his document.
% \begin{macro}{\txtrans} \cs{txtrans} is used internally by several
% Lua functions to insert transliterated Arabic text.
%    \begin{macrocode}
\DeclareDocumentCommand{\txarb}{+m}{\bgroup\textdir
  TRT\arabicfont#1\egroup}
\DeclareDocumentCommand{\txtrans}{+m}{\bgroup\textdir
  TLT\rmfamily#1\egroup}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\arb}
%   The \cs{arb} command detects which Arabic mode is to be used,
%   either globally if no option is set, or locally, then passes its
%   argument to the appropriate Lua function.
%    \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}
% The |arab| environment does for paragraphs the same as \cs{arb} does
% for short insertions of Arabic text.
%    \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{macro}{\LRmarginpar} \cs{LRmarginpar} is supposed to be
%   inserted in an Arabic environment. It typsets his argument in a
%   marginal note from left to right.
%    \begin{macrocode}
\DeclareDocumentCommand{\LRmarginpar}{m}{\marginpar{\textdir TLT #1}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\LRfootnote} \cs{LRfootnote} and \cs{RLfootnote} are
%   supposed to be used in Arabic environments for insertions of non
%   Arabic text. \cs{LRfootnote} typesets its argument left-to-right\ldots
%   \begin{macro}{\RLfootnote} while \cs{RLfootnote} typesets its
%   argument left-to-right.
%    \begin{macrocode}
\DeclareDocumentCommand{\LRfootnote}{m}{\bgroup\pardir
  TLT\LR{\footnote{#1}}\egroup}
\DeclareDocumentCommand{\RLfootnote}{m}{\bgroup\pardir
  TRT\LR{\footnote{#1}}\egroup}
%    \end{macrocode}
%   \end{macro}
% \end{macro}
% \begin{macro}{\FixArbFtnmk} In the preamble, just below
%   \cs{usepackage}|{arabluatex}|, \cs{FixArbFtnmk} may be of some
%   help in case the footnote numbers at the bottom of the page are
%   printed in the wrong direction. This quick fix uses and loads
%   \package{scrextend} if it is not already loaded.
%    \begin{macrocode}
\NewDocumentCommand{\FixArbFtnmk}{}{%
  \@ifpackageloaded{scrextend}%
  {\AtBeginDocument{\deffootnote{2em}{1.6em}{\LR{\thefootnotemark}.\enskip}}}%
  {\RequirePackage{scrextend}
  \AtBeginDocument{\deffootnote{2em}{1.6em}{\LR{\thefootnotemark}.\enskip}}}}
%    \end{macrocode}
% \end{macro}
% That is it. Say goodbye before leaving.
%    \begin{macrocode}
\endinput
%    \end{macrocode}
%
% \printbibliography[heading=bibintoc]
%
% \iffalse
%</package>
% \fi
%
% \Finale
\endinput
