path: root/Master/texmf-dist/source/lualatex/arabluatex/arabluatex.dtx

% \iffalse meta-comment
% ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
% 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 3 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, see
% <http://www.gnu.org/licenses/>.
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{arabluatex.dtx}
%</driver>
%<package-info>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package-info>\ProvidesPackage{arabluatex}
%<*package-info>
    [2016/12/17 v1.6 An ArabTeX-like interface for LuaLaTeX]
%</package-info>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{filecontents}
\begin{filecontents}{\jobname.bib}
% This file is part of the `arabluatex' package
%
% ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
% 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 3 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, see
% <http://www.gnu.org/licenses/>.

@software{pkg:arabtex,
  author =	 {Lagally, Klaus},
  maintainer =	 {Lagally, Klaus},
  title =	 {Arab\TeX},
  indextitle =   {Arab\TeX},
  date =	 {2004-11-03},
  version =	 {4.00},
  url =
    {http://mirrors.ctan.org/language/arabic/arabtex/doc/html/arabtex.htm},
  subtitle =	 {Typesetting Arabic and Hebrew},
  titleaddon =	 {User Manual Version 4.00}
}

@software{pkg:amiri,
  author =	 {Hosny, Khaled},
  maintainer =	 {Hosny, Khaled},
  title =	 {Amiri},
  indextitle =	 {Amiri},
  date =	 {2015-09-20},
  url =		 {http://www.amirifont.org/}
}

@Book{Habash,
  author =	 {Habash, Nizar Y.},
  title =	 {Introduction to Arabic Natural Language Processing},
  year =	 2010,
  series =	 {Synthesis Lectures on Human Language Technologies},
  number =	 10,
  publisher =	 {Morgan \& Claypool Publishers},
  location =	 {Toronto}
}

@MVBook{Wright,
  author =	 {Wright, W. LL.D},
  title =	 {A Grammar of the Arabic Language},
  indextitle =	 {Grammar of the Arabic Language, A},
  year =	 1896,
  editor =	 {Robertson Smith, W. and de Goeje, M. J.},
  editortype =	 {reviser},
  foreword =	 {Cachia, Pierre},
  edition =	 3,
  volumes =	 2,
  pagination =	 {none},
  publisher =	 {Librairie du Liban},
  location =	 {Beirut},
  annote =	 {New impression, 1996}
}

@InProceedings{dmg,
  author =	 {Brockelmann, Carl and Fischer, August and Heffening,
                  W. and Taeschner, Franz},
  shorttitle = 	 {Die Transliteration der arabischen Schrift},
  title =	 {Die Transliteration der arabischen Schrift in ihrer
                  Anwendung auf die Hauptliteratursprachen der
                  islamischen Welt},
  indextitle = 	 {Transliteration der arabischen Schrift, Die},
  year =	 1935,
  booktitle =	 {Denkschrift dem 19. internationalen
                  Orientalistenkongreß in Rom},
  editor =	 {van Ronkel, Ph. S. and Spies, Otto},
  editortype =	 {collaborator},
  organization = {Deutschen Morgenländischen Gesellschaft},
  publisher =	 {Deutschen Morgenländischen Gesellschaft, in
                  Kommission bei F. A. Brockaus},
  url =
                  {http://www.naher-osten.uni-muenchen.de/studium_lehre/werkzeugkasten/dmgtransliteration.pdf},
  location =	 {Leipzig}
}

@MVBook{Lane,
  author =	 {Lane, Edward William},
  title =	 {An Arabic-English lexicon},
  date =	 {1863/1893},
  indextitle = 	 {Arabic-English Lexicon, An},
  volumes =	 8,
  shorthand = 	 {Lane, \emph{Lexicon}},
  pagination = 	 {none},
  publisher =	 {Williams and Norgate},
  location =	 {London -- Edinburgh}
}
\end{filecontents}
\usepackage[english]{babel}
\usepackage{dox}
\doxitem{Option}{option}{options}
\def\actualchar{ =} % there's a bug in doxitem; quick fix.
\usepackage{fontspec,luatextra}
\defaultfontfeatures{RawFeature={+liga}}
\setmainfont{Old Standard}[SmallCapsFont={Latin Modern Roman Caps},
  RawFeature={+mark;+ccmp;+ss05;+ss06}]
\usepackage{arabluatex}[2016/12/17]
\usepackage[nopar]{quran}
\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{lineno}
\usepackage{longtable}
\usepackage{booktabs}
\usepackage[defaultlines=3,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
\RecordChanges
\CodelineIndex
\begin{document}
  \DocInput{arabluatex.dtx}
  \printbibliography[heading=bibintoc]
  \phantomsection
  \addcontentsline{toc}{section}{Change History}
  \PrintChanges
  \phantomsection
  \addcontentsline{toc}{section}{Index}
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{694}
%
% \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{v1.0}{2016/03/29}{Initial release}
% \changes{v1.0.1}{2016/03/31}{Minor update of the documentation}
%
% \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,\verb,\let}
% \DoNotIndex{\enskip}
% 
% \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
% \pagebreak
% \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}
% \item development: \url{http://git.robertalessi.net/arabluatex}
% \item comments, feature requests, bug reports:
% \url{http://issues.robertalessi.net}
% \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 3 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, see
% <http://www.gnu.org/licenses/>.
%
% 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|
% \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 that, \package{arabtex} provided---and still
% does---an Arabic font in \arb[trans]{\cap{nasxI}} 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 that 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.
%
% \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}\marg{fontname}[Script=Arabic]}
% \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{Amiri}[Script=Arabic]}
% \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}\,. That is correct, as at least in the oldest
%   manuscripts {\newfontfamily\arabicfont{Amiri}[Script=Arabic,
%   RawFeature={+ss05}]\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{Amiri}[Script=Arabic,RawFeature={+ss05}]}
%
%   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 |N|, viz. \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 may be expressed
% at the beginning of a sentence (\arb{u} \arb{a} \arb{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}.
% 
% \subsubsection{Classic contrasted with modern typesetting of Arabic}
% \label{sec:classic-modern-typesetting}
% \NEWfeature{v.1.2} By default, \package{arabluatex} typesets Arabic
% in a classic, traditional style the most prominent features of which
% are the following:
% \begin{compactitem}
% \item \enquote*{Classic} \arb[trans]{maddaT}: when
% \arb[trans]{'alif} and \arb[trans]{hamzaT} accompanied by a simple
% vowel or \arb[trans]{tanwIn} is preceded by an \arb[trans]{'alif} of
% prolongation (\arb[voc]{BA}), then a mere \arb[trans]{hamzaT} is
% written on the line, and a \arb[trans]{maddaT} is placed over the
% \arb[trans]{'alif}, like so:---
% \begin{quote}
%   |samA'uN| \arb[voc]{samA'uN} \arb[trans]{samA'uN}, |jA'a|
%   \arb[voc]{jA'a} \arb[trans]{jA'a}, |yatasA'alUna|
%   \arb[voc]{yatasA'alUna} \arb[trans]{yatasA'alUna}\footnote{Note
%   that in old mss. such forms as \arb[voc]{samA"'a"'a},
%   \arb[voc]{jA"'a"'a} are also found; see \textcite[i. 24
%   D]{Wright}.} (see \vpageref{ref:madda} for further details).
% \end{quote}
% \item The euphonic \arb[trans]{ta^sdId} is generated (see
%   \vpageref{ref:euphonic-tashdid}).
% \item In |fullvoc| mode, the \arb[trans]{sukUn} is expressed.
% \end{compactitem}
% 
% \DescribeMacro{\SetArbEasy} \NEWfeature{v1.4.4}
% \DescribeMacro{\SetArbEasy*} \DescribeMacro{\SetArbDflt} Such
% refinements as \enquote*{classic} \arb[trans]{maddaT} may be
% discarded by the \cs{SetArb\allowbreak{}Easy} command, either
% globally in the preamble or locally at any point of the
% document. The difference between \cs{SetArbEasy} and its
% \enquote*{starred} version \cs{SetArbEasy*} is that the former keeps
% the \arb[trans]{sukUn} that is generated by the |fullvoc| mode,
% while the latter further takes it away. Default \enquote*{classic}
% rules may be set back at any point of the document with the
% \cs{SetArbDflt} command. \NEWfeature{v1.6}
% \DescribeMacro{\SetArbDflt*}Assimilation rules laid on
% \vref{ref:assimilation} may also be applied by the
% \enquote*{starred} version of this command \cs{SetArbDflt*} either
% in the preamble or at any point of the document.\footnote{For an
% example, see \vref{sec:poetry-example}.} Examples follow:---
% \begin{compactenum}[(a)]
% \item \cs{SetArbDflt}:
%   \begin{compactenum}[i.]
%   \item |voc| \arb[voc]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}
%   \item |fullvoc| \arb[fullvoc]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}
%   \item |trans| \arb[trans]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}
%   \end{compactenum}
% \item \cs{SetArbDflt*}:
%   \begin{compactenum}[i.]\SetArbDflt*
%   \item |voc| \arb[voc]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}
%   \item |fullvoc| \arb[fullvoc]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}
%   \item |trans| \arb[trans]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}\SetArbDflt
%   \end{compactenum}
% \item \cs{SetArbEasy}:
%   \begin{compactenum}[i.]\SetArbEasy
%   \item |voc| \arb[voc]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}
%   \item |fullvoc| \arb[fullvoc]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}
%   \item |trans| \arb[trans]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}\SetArbDflt
%   \end{compactenum}   
% \item \cs{SetArbEasy*}:
%   \begin{compactenum}[i.]\SetArbEasy*
%   \item |voc| \arb[voc]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}
%   \item |fullvoc| \arb[fullvoc]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}
%   \item |trans| \arb[trans]{wa-mAta istisqA'aN qabla 'an yutimma
%     kitAba-hu fI nujUm-i 'l-samA'-i}\SetArbDflt
%   \end{compactenum}   
% \end{compactenum}
%
% \iffalse
%<*example>
% \fi
\begin{arabluacode}[text only]
Please note that this document is typeset with \cs{SetArbDflt} throughout.
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
%\subsection{Typing Arabic}
% \DescribeMacro{\arb} Once \package{arabluatex} is loaded, a
% \cs{arb}\marg{Arabic text} command 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{.hurUf-u 'l-hijA'-i}, \arb{.hurUf-u
'l-tahajjI}, \arb{al-.hurUf-u 'l-hijA'iyyaT-u}, or
\arb{.hurUf-u 'l-mu`jam-i}) 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
%
% \paragraph{Caveat}
% For some reason, left-to-right paragraphs that start with Arabic
% words lose their indentation. For the time being, this can be
% circumvented by appending the \cs{indent} command at the
% commencement of such paragraphs.
%
% \label{ref:ltr-lists}%
% The same remark applies to left-to-right list environments: when
% items start with Arabic words, the \cs{arb} command must be prefixed
% with \cs{indent}. The following example comes from \textcite[i. 213
% C]{Wright}:--- %
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
  \begin{enumerate}[XVI.]
  \item \indent\arb{fawA`ilu}*.
    \begin{enumerate}[1.]
    \item \indent\arb{fA`aluN}; as \arb{_hAtamuN} \emph{a
        signet-ring}, ...
    \end{enumerate}
  \end{enumerate}
\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 fa-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 ra.gbata-ka fa-'l-.himAr-u laysa hunA
   'l-yawm-a.}  wa-qabla 'an yutimma ju.hA kalAma-hu bada'a
   'l-.himAr-u yanhaqu fI 'i.s.tabli-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-.himAr-a
   wa-tuka_d_diba-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}. The \arb[trans]{hamzaT} itself is
% encoded \texttt{<'>}. See below \vref{ref:hamza}.} & \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-'alif-u 'l-maq.sUraT-u}.}
%            & \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]{.hurUf-u 'l-madd-i}, \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-'alif-u 'l-ma.h_dUfaT-u}, 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'ikaT-u| |'l-ra.hm_an-u|
%   \arb[voc]{al-mal_a'ikaT-u 'l-ra.hm_an-u}, |.hu_dayfaT-u| |bn-u|
%   |'l-yamAn_i| \arb[fullvoc]{.hu_dayfaT-u bn-u 'l-yamAn_i} for
%   \arb[trans]{\cap{.hu_dayfaT-u} bn-u '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 be 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[voc]{murU'aTuN} \arb[trans]{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]{'alif-u 'l-wiqAyaT-i}, \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_ah-u| \arb[voc]{al-l_ah-u} \arb[trans]{al-l_ah-u},
%   |'il_ahuN| \arb[voc]{'il_ahuN} \arb[trans]{'il_ahuN}.
%
%   |al-ra.hm_an-u| \arb[voc]{al-ra.hm_an-u}
%   \arb[trans]{al-ra.hm_an-u}, |l_akin| \arb[voc]{l_akin}
%   \arb[trans]{l_akin}, |h_ahunA| \arb[voc]{h_ahunA}
%   \arb[trans]{h_ahunA}, |.hunayn-u| |bn-u| |'is.h_aq-a|
%   \arb[voc]{.hunayn-u bn-u 'is.h_aq-a} \arb[trans]{\cap{.hunayn}-u
%   bn-u \cap{'is.h_aq-a}}, |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 that
% 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_aIT-u| \arb[voc]{al-rib_aIT-u}
%   \arb[trans]{al-rib_aIT-u}.
% \end{quote}
%
% \paragraph{\arb[trans]{\cap{`amruNU}}, and the silent
% \arb[novoc]{U}} To that name a silent \arb[novoc]{U} is added to
% distinguish it from \arb[trans]{\cap{`umar-u}}: 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}: |`amr-uU| |bn-u| |mu.hammadiN| \arb[fullvoc]{`amr-uU
%   bnu mu.hammadiN} \arb[trans]{\cap{`amr-uU} bn-u
%   \cap{mu.hammadiN}}, |mu.hammad-u| |bn-u| |`amr-iU| |bn-i|
%   |_hAlidiN| \arb[fullvoc]{mu.hammad-u bn-u `amr-iU bn-i _hAlidiN}
%   \arb[trans]{\cap{mu.hammad-u} bn-u \cap{`amr-iU} bn-i
%   \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}
%
% In some cases, it may be useful to mark the root form of defective
% words so as to produce a more accurate transliteration of ending
% \arb[trans]{tanwIn}. As seen above, \arb[trans]{tanwIn} preceding
% \arb[novoc]{_A} is written \meta{aN\_A} or \meta{aNY}. Such forms as
% \arb[voc]{qA.diNI} may likewise be written \meta{iNI}:---
% \begin{quote}
%   |al-qA.dI| \arb[voc]{al-qA.dI} \arb[trans]{al-qA.dI}, |qA.diyaN|
%   \arb[voc]{qA.diyaN} \arb[trans]{qA.diyaN}, |qA.diNI|
%   \arb[voc]{qA.diNI} \arb[trans]{qA.diNI}.
% \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}.
%
%   \label{ref:initial-hamza}
%   \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}.
%
%   \arb[trans]{hamzaT} followed by the long vowel \arb[novoc]{I} is
%   encoded |'_I|: |'_ImAnuN| \arb[voc]{'_ImAnuN}
%   \arb[trans]{'_ImA\-nuN}.
%
%   \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'i\-laTuN} \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}\linebreak \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}, |^sifA'I|
%   \arb[voc]{^sifA'I} \arb[trans]{^sifA'I}.
%
%   |^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}.
%
%   \textbf{\arb[trans]{ta_hfIf-u 'l-hamzaT-i}}: if the
%   \arb[trans]{hamzaT} has \arb[trans]{jazmaT} and is preceded by
%   \emph{\arb[trans]{'alif} hamzatum}, it must be changed into the
%   letter of prolongation that is homogeneous with the preceding
%   vowel; hence: |'a'mana| \arb[voc]{'a'mana} \arb[trans]{'a'mana},
%   |'u'minu| \arb[voc]{'u'minu} \arb[trans]{'u'minu}, |'i'mAnuN|
%   \arb[voc]{'i'mAnuN} \arb[trans]{'i'mAnuN}. For other possible ways
%   of encoding such sequences, see \vpageref{ref:initial-hamza}
%   (\arb[trans]{hamzaT} followed by \arb[novoc]{U} and \arb[novoc]{I})
%   and the \arb[trans]{maddaT} \vpageref{ref:madda}.
% \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-'alif-u
% 'l-mamdUdaT-u} 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'An-u|
%   \arb[voc]{al-qur'An-u} \arb[trans]{al-qur'An-u}.
%
%   |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}}
% \label{ref: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{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]
  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-^sams-u|
  \arb[voc]{al-^sams-u} \arb[trans]{al-^sams-u}, or |a^s-^sams-u|
  \arb[voc]{a^s-^sams-u} \arb[trans]{a^s-^sams-u}.
\end{arabluacode}
% \iffalse
%</example>
% \fi
% \begin{quote}
%   |al-tamr-u| \arb[voc]{al-tamr-u} \arb[trans]{al-tamr-u},
%   |al-ra.hm_an-u| \arb[voc]{al-ra.hm_an-u}
%   \arb[trans]{al-ra.hm_an-u}, |al-.zulm-u| \arb[voc]{al-.zulm-u}
%   \arb[trans]{al-.zulm-u}, |al-lu.gaT-u| \arb[voc]{al-lu.gaT-u}
%   \arb[trans]{al-lu.gaT-u}.
% \end{quote}
% \item \label{ref:assimilation} 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}\SetArbDflt*
%   Note the absence of \arb[trans]{sukUn} above the passed over
%   \arb[novoc]{n} in the following examples, each of which is
%   accompanied by 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}.\SetArbDflt
% \end{quote}
% \iffalse
%<*example>
% \fi
\begin{arabluacode}[text only]
  \textsc{Rem.} This particular feature must be put into operation by
  the \cs{SetArbDflt*} command explicitly. See above
  \vref{sec:classic-modern-typesetting} for further details. Other
  kinds of assimilations, including the various cases of
  \arb[trans]{'id.gAm}, will be included in \package{arabluatex}
  gradually.
\end{arabluacode}
% \iffalse
%</example>
% \fi
% \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]{'alif-u 'l-wa.sl-i}}
% \label{ref:definite-article}
% At the beginning of a sentence, \arb[fullvoc]{"a} is never written,
% as \arb[fullvoc]{'l-.hamd-u li-ll_ah-i}; instead, to indicate that
% the \arb[trans]{'alif} is a connective \arb[trans]{'alif}
% (\arb[trans]{'alif-u 'l-wa.sl-i}), the \arb[trans]{hamzaT} is
% omitted and only its accompanying vowel is expressed:
% \begin{quote}
%   |al-.hamd-u| |li-l-l_ah-i| \arb[fullvoc]{al-.hamd-u li-l-l_ah-i}
%   \arb[trans]{al-.hamd-u li-l-l_ah-i}.
% \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 that 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}: |bAb-u| |'l-madrasaT-i| \arb[fullvoc]{bAb-u
%   'l-madrasaT-i} \arb[trans]{bAb-u 'l-madrasaT-i}, |al-maqAlaT-u|
%   |'l-'_Ul_A| \arb[fullvoc]{al-maqAlaT-u 'l-'_Ul_A}
%   \arb[trans]{al-maqAlaT-u 'l-'_Ul_A}, |al-lu.gaT-u|
%   |'l-`arabiyyaT-u| \arb[fullvoc]{al-lu.gaT-u 'l-`arabiyyaT-u}
%   \arb[trans]{al-lu.gaT-u 'l-`arabiyyaT-u}, |fI| |.sinA`aT-i|
%   |'l-.tibb-i| \arb[fullvoc]{fI .sinA`aT-i 'l-.tibb-i}
%   \arb[trans]{fI .sinA`aT-i 'l-.tibb-i}, |'il_A| |'l-intiqA.d-i|
%   \arb[fullvoc]{'il_A 'l-intiqA.d-i} \arb[trans]{'il_A
%   'l-intiqA.d-i}, |fI| |'l-ibtidA'-i| \arb[fullvoc]{fI 'l-ibtidA'-i}
%   \arb[trans]{fI 'l-ibtidA'-i}, |'abU| |'l-wazIr-i|
%   \arb[fullvoc]{'abU 'l-wazIr-i} \arb[trans]{'abU 'l-wazIr-i},
%   |fa-lammA| |ra'aW| |'l-najm-a| \arb[fullvoc]{fa-lammA ra'aW
%   'l-najm-a} \arb[trans]{fa-lammA ra'aW 'l-najm-a}.
%
%   \textbf{Particles}:---
%   \begin{compactenum}[(a)]
%   \item \arb[trans]{li-}: \arb[trans]{'alif-u 'l-wa.sl-i} is omitted
%     in the article \arb[fullvoc]{al} when it is preceded by the
%     preposition \arb[fullvoc]{li}: |li-l-rajul-i|
%     \arb[fullvoc]{li-l-rajul-i}
%     \arb[trans]{li-l-rajul-i}.\\
%     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-laylaT-i|
%     \arb[fullvoc]{li-l-laylaT-i} \arb[trans]{li-l-laylaT-i}.
%   \item \arb[trans]{la-}: the same applies to the affirmative
%   particle \arb[fullvoc]{la}: |la-l-.haqq-u|
%   \arb[fullvoc]{la-l-.haqq-u} \arb[trans]{la-l-.haqq-u}.
% \item With the other particles, \arb[trans]{'alif-u 'l-wa.sl-i} is
%   expressed: |fI| |'l-madInaT-i| \arb[fullvoc]{fI 'l-madInaT-i}
%   \arb[trans]{fI 'l-madInaT-i}, |wa-'l-rajul-u|
%   \arb[fullvoc]{wa-'l-rajul-u} \arb[trans]{wa-'l-rajul-u},
%   |bi-'l-qalam-i| \arb[fullvoc]{bi-'l-qalam-i}
%   \arb[trans]{bi-'l-qalam-i}, |bi-'l-ru`b-i|
%   \arb[fullvoc]{bi-'l-ru`b-i} \arb[trans]{bi-'l-ru`b-i}.
%   \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-iqtidAr-u|
%   \arb[fullvoc]{al-iqtidAr-u} \arb[trans]{al-iqtidAr-u}, |'il_A|
%   |'l-intiqA.d-i| \arb[fullvoc]{'il_A 'l-intiqA.d-i}
%   \arb[trans]{'il_A 'l-intiqA.d-i}, |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| |ibn-u| |`amriNU|
%   \arb[fullvoc]{\cap{z}ayduN ibn-u \cap{`amriNU}}
%   \arb[trans]{\cap{z}ayduN ibn-u
%   \cap{`amriNU}},\footnote{\label{fn:zayd-is-son}%
%   \enquote{\arb[trans]{\cap{z}ayd} is the son of
%   \arb[trans]{\cap{`a}mr}}: the second noun is not in apposition to
%   the first, but forms part of the predicate. Hence \arb[voc]{zayduN
%   ibn-u `amriNU} and not \arb[voc]{zayd-u bn-u `amriNU},
%   \enquote{Zayd, son of ʿAmr}.}  |`umar-u| |ibn-u| |'l-_ha.t.tAb-i|
%   \arb[fullvoc]{\cap{`umar}-u ibn-u \cap{'l-_ha.t.tAb-i}}
%   \arb[trans]{\cap{`umar}-u ibn-u
%   \cap{'l-_ha.t.tAb-i}},\footnote{\enquote{\arb[trans]{\cap{`umar}}
%   is the son of \arb[trans]{\cap{al-_ha.t.tAb}}} (see
%   \vref{fn:zayd-is-son}).}  |imru'-u| |'l-qays-i|
%   \arb[fullvoc]{imru'-u 'l-qays-i} \arb[trans]{\cap{i}mru'-u
%   \cap{'l-qays-i}}, |la-aymun-u| |'l-l_ah-i|
%   \arb[fullvoc]{la-aymun-u 'l-l_ah-i} \arb[trans]{la-aymun-u
%   'l-l_ah-i}.
% \end{quote}
%
% \subparagraph{\arb[trans]{'alif-u 'l-wa.sl-i} 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 does
% not appear in the Arabic script, but \package{arabluatex} takes it
% into account in some transliteration standards:---
% \begin{quote}
%   |fI| |'l-nAs-i| \arb[fullvoc]{fI 'l-nAs-i} \arb[trans]{fI
%   'l-nAs-i}, |'abU| |'l-wazIr-i| \arb[fullvoc]{'abU 'l-wazIr-i}
%   \arb[trans]{'abU 'l-wazIr-i}, |fI| |'l-ibtidA'-i| \arb[fullvoc]{fI
%   'l-ibtidA'-i} \arb[trans]{fI 'l-ibtidA'-i}, |_dU 'l-i`lAl-i|
%   \arb[fullvoc]{_dU 'l-i`lAl-i} \arb[trans]{_dU 'l-i`lAl-i},
%   |maqh_A| |'l-'amIr-i| \arb[voc]{maqh_A 'l-'amIr-i}
%   \arb[trans]{maqh_A 'l-'amIr-i}.
% \end{quote}
%
% \subparagraph{\arb[trans]{'alif-u 'l-wa.sl-i} 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-malik-i| \arb[fullvoc]{fI `aynay 'l-malik-i}
%   \arb[trans]{fI `aynay 'l-malik-i}, |ix^say| |'l-qawm-a|
%   \arb[fullvoc]{ix^say 'l-qawm-a} \arb[trans]{ix^say 'l-qawm-a},
%   |mu.s.tafaw| |'l-l_ah-i| \arb[fullvoc]{mu.s.tafaw 'l-l_ah-i}
%   \arb[trans]{mu.s.tafaw 'l-l_ah-i}.
%
%   |ramaW| |'l-.hijAraT-a| \arb[fullvoc]{ramaW 'l-.hijAraT-a}
%   \arb[trans]{ramaW 'l-.hijAraT-a}, |fa-lammA| |ra'aW | |'l-najm-a|
%   \arb[fullvoc]{fa-lammA ra'aW 'l-najm-a} \arb[trans]{fa-lammA ra'aW
%   'l-najm-a}.
% \end{quote}
%
% \subparagraph{\arb[trans]{'alif-u 'l-wa.sl-i} preceded by a consonant
% with \arb[trans]{sukUn}} The vowel which the consonant takes is
% 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_dib-Una| \arb[fullvoc]{'antumu 'l-kA_dib-Una}
%   \arb[trans]{'antumu 'l-kA_dib-Una}, |ra'aytumu| |'l-rajul-a|
%   \arb[fullvoc]{ra'aytumu 'l-rajul-a} \arb[trans]{ra'aytumu
%   'l-rajul-a}, |mani| |'l-ka_d_dAb-u| \arb[fullvoc]{mani
%   'l-ka_d_dAb-u} \arb[trans]{mani 'l-ka_d_dAb-u}, |qatalati|
%   |'l-rUm-u| \arb[fullvoc]{qatalati 'l-rUm-u} \arb[trans]{qatalati
%   \cap{'l-rUm-u}}.
% \end{quote}
% \label{ref:muhammaduni}
% However, the Arabic script does not show the \arb[trans]{kasraT} or
% the \arb[trans]{.dammaT} which may be 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 that automatically:---
% \begin{quote}
%   |mu.hammaduN| |'l-nabI| \arb[fullvoc]{mu.hammaduN 'l-nabI}
%   \arb[trans]{\cap{m}u.hammaduN 'l-nabI}, |salAmuN| |ud_hulUA|
%   \arb[fullvoc]{salAmuN ud_hulUA} \arb[trans]{salAmuN ud_hulUA},
%   |qa.sIdata-hu| |fI| |qatl-i| |\cap{'a}bI| |\cap{m}uslimiN|
%   |'llatI| |yaqUlu| |fI-hA| \arb[fullvoc]{qa.sIdata-hu fI qatl-i
%   \cap{'a}bI \cap{m}uslimiN 'llatI yaqUlu fI-hA}
%   \arb[trans]{qa.sIdata-hu fI qatl-i \cap{'a}bI \cap{m}uslimiN
%   'llatI yaqUlu fI-hA}.
% \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]{'ilAh-u} (noted
% \arb[fullvoc]{'il_ah-u} with the defective \arb[trans]{'alif}) so
% that it becomes \arb[fullvoc]{al-'ilAh-u}; 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_ah-u} \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{ref:euphonic-tashdid}), the
% name of God is therefore encoded |al-l_ah-u| or |'l-l_ah-u|:---
% \begin{quote}
%   |al-l_ah-u| \arb[fullvoc]{al-l_ah-u} \arb[trans]{al-l_ah-u},
%   \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-.tarIq-i}. See \vref{sec:pipe} on the
%   \enquote{pipe} and \vref{sec:transliteration} on |dmg| mode.}
%   |al-l_ah-u| \arb[fullvoc]{yA| al-l_ah-u} \arb[trans]{yA|
%   al-l_ah-u}, \verb+'a-fa|+\footnote{\label{fn:pipe-allah-02}See
%   \cref{fn:pipe-allah-01}.}|-al-l_ah-i| |la-ta.g`alanna|
%   \arb[fullvoc]{'a-fa|-al-l_ah-i la-ta.g`alanna}
%   \arb[trans]{'a-fa|-al-l_ah-i la-ta.g`alanna}, |bi-'l-l_ah-i|
%   \arb[fullvoc]{bi-'l-l_ah-i} \arb[trans]{bi-'l-l_ah-i},
%   |wa-'l-l_ah-i| \arb[fullvoc]{wa-'l-l_ah-i}
%   \arb[trans]{wa-'l-l_ah-i}, |bi-sm-i| |'l-l_ah-i|
%   \arb[fullvoc]{bi-sm-i 'l-l_ah-i} \arb[trans]{bi-sm-i 'l-l_ah-i},
%   |al-.hamd-u| |li-l-l_ah-i| \arb[fullvoc]{al-.hamd-u li-l-l_ah-i}
%   \arb[trans]{al-.hamd-u li-l-l_ah-i}, |li-l-l_ah-i| |'l-qA'il-u|
%   \arb[fullvoc]{li-l-l_ah-i 'l-qA'il-u} \arb[trans]{li-l-l_ah-i
%   'l-qA'il-u}.
% \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-malik-i| |'lla_dI| |ya.zlimu| |'l-nAs-a|
%   \arb[fullvoc]{'a_hAfu mina 'l-malik-i 'lla_dI ya.zlimu 'l-nAs-a}
%   \arb[trans]{'a_hAfu mina 'l-malik-i 'lla_dI ya.zlimu 'l-nAs-a},
%   |`udtu| |'l-^say_h-a| |'lla_dI| |huwa| |marI.duN|
%   \arb[fullvoc]{`udtu 'l-^say_h-a 'lla_dI huwa marI.duN}
%   \arb[trans]{`udtu 'l-^say_h-a 'lla_dI 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-jinn-i|
%   |wa-'l-'ins-i| \arb[fullvoc]{'ari-nA 'lla_dayni 'a.dallA-nA mina
%   'l-jinn-i wa-'l-'ins-i} \arb[trans]{'ari-nA 'lla_dayni 'a.dallA-nA
%   mina 'l-jinn-i wa-'l-'ins-i}.
% \end{quote}
% The other forms are encoded regularly as |al-l| or |'l-l|:---
% \begin{quote}
%   |fa-'innA| |na_dkuru| |'l-.sawt-ayni| |'l-la_dayni| |rawaynA-humA|
%   |`an| |ja.h.zaT-a| \arb[fullvoc]{fa-'innA na_dkuru 'l-.sawt-ayni
%   'l-la_dayni rawaynA-humA `an \cap{ja.h.zaT-a}}
%   \arb[trans]{fa-'innA na_dkuru 'l-.sawt-ayni 'l-la_dayni
%   rawaynA-humA `an \cap{ja.h.zaT-a}}.
%
%   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 `ilm-a 'l-hay'aT-i}; 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 `ilm-a 'l-hay'aT-i}, 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| |`ilm-a| |'l-hay'aT-i| \arb[novoc]{`"ullima `ilm-a
%   'l-hay'aT-i} \arb[trans]{`"ullima `ilm-a 'l-hay'aT-i}, |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" \cap{hinduN}}
%   \arb[trans]{jA'at" \cap{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]{'alif-u 'l-wa.sl-i}:---
% \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.d-u|
%   \arb[novoc]{al-"intiqA.d-u} \arb[trans]{al-"intiqA.d-u}.
% \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}, |ibn-u 'abI 'u.saybi`aT-"a| \arb[voc]{ibn-u 'abI
%     'u.saybi`aT-"a} \arb[trans]{\cap{ibn-u} \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]{wa.slaT} 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]{'alif-u 'l-wa.sl-i}:---
%   \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-jamr-u| |'l-.sayfiyy-u| |'lla_dI| |kAna|
%   \verb+bi-q"rAn"|nUn-a+ \arb[fullvoc]{al-jamr-u 'l-.sayfiyy-u
%   'lla_dI kAna \cap{bi-q"rAn"|nUn-a}} \arb[trans]{al-jamr-u
%   'l-.sayfiyy-u 'lla_dI kAna \cap{bi-q"rAn"|nUn-a}}.
% \end{quote}
%
% \subsubsection{\texorpdfstring{Quoting the
% \arb[trans]{hamzaT}}{Quoting the hamzah}}
% \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} that 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 that particular mechanism works in
% \vref{fn:pipe-allah-01} and in \vref{fn:pipe-madda}. One more example
% follows:---
% \begin{quote}
%   \verb+bi-qrAn|nUn-a+ \arb[voc]{\cap{bi-qrAn|nUn-a}}
%   \arb[trans]{\cap{bi-qrAn|nUn-a}}, \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 and diacritics which
% stand one above the other:--
% \begin{quote}
%   |.hunayn-u| |bn-u| |'is.h--_aq-a| \arb[voc]{.hunayn-u bn-u
%   'is.h--_aq-a} \arb[trans]{\cap{.hunayn-u} bn-u \cap{'is.h--_aq-a}}
% \end{quote} 
%
% \subsection{Digits}
% \label{sec:digits}
% \subsubsection{Numerical figures}
% \label{sec:numerical-figures}
% The \emph{Indian numbers}, \arb[trans]{al-raqam-u 'l-hindiyy-u}, 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|
%   |sanaT-i| |1024| \arb[voc]{fI sanaT-i 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.
%
% \DescribeMacro{\abjad} \NEWfeature{v.1.1} \arb[trans]{'abjad}
% numbers are inserted with the \cs{abjad}\marg{number} command 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-`AdAt-i| \arb[voc]{\abjad{45}
%   kitAbu-hu fI 'l-`AdAt-i} \arb[trans]{\abjad{45} kitAbu-hu fI
%   'l-`AdAt-i}.
% \end{quote}
% \begin{quoting}
%   \textsc{Rem.}~\emph{a.} As can be seen in the above given example,
%   \package{arabluatex} expresses the \arb[trans]{'abjad} numbers in
%   Roman numerals if it finds the \cs{abjad} command in any of the
%   transliteration modes.
%
%   \textsc{Rem.}~\emph{b.} \cs{abjad} may also be found outside
%   Arabic environments. In that case, \package{arabluatex} does not
%   print the stroke as a distinctive mark over the number for it is
%   not surrounded by other Arabic words. In case one nonetheless
%   wishes to print the stroke, he can use the \cs{aemph} command that
%   is described below in \vref{sec:emphasis}:---
%   \begin{quote}
%     |The| |\arb[trans]{'abjad}| |number| |for| |1874| |is|
%     |\abjad{1874}| The \arb[trans]{'abjad} number for 1874 is
%     \abjad{1874}.
%
%     |The| |\arb[trans]{'abjad}| |number| |for| |1874| |is|
%     |\aemph{\abjad{1874}}| The \arb[trans]{'abjad} number for 1874
%     is \aemph{\abjad{1874}}.
%   \end{quote}
% \end{quoting}
%
% \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 \cs{aemph}\marg{Arabic
% text} command to use the same technique to emphasize words, like so:---
% \begin{quote}
%   |\abjad{45}:| |kitAbu-hu| |\aemph{fI| |'l-`AdAt-i}|
%   \arb[voc]{\abjad{45}: kitAbu-hu \aemph{fI 'l-`AdAt-i}}
%   \arb[trans]{\abjad{45}: kitAbu-hu fI 'l-\cap{`AdAt-i}}.
% \end{quote}
%
% \section{Arabic poetry}
% \label{sec:poetry}
% \NEWfeature{v1.6} \package{arabluatex} provides a special
% environment for typesetting Arabic poetry. Every line in this
% environment must end with |\\|.
%
% \DescribeEnv{arabverse} The |arabverse| environment may take up to
% six optional \enquote*{named arguments} each of which is set using
% the syntax \meta{key}$=$\meta{value}, like so:---%
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
  \begin{arabverse}[key1=value1, key2=value2, ...]
    <verses>
  \end{arabverse}
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi
%
% The description of the optional arguments follows:---
%
% \DescribeOption{mode} |mode|$=$\meta{mode}, either |voc|, |fullvoc|,
% |novoc| or |trans|. The default mode is the one that is set at load
% time as already seen \vref{sec:options}.
%
% \DescribeOption{width} |width|$=$\meta{length}
% \hfill\arabluaverb{Default: 0.3\linewidth}\\ The default width of
% each hemistich that the verse consists of. It may be expressed in
% any accepted unit of measurement, such as |4cm| or |2in|. However,
% one must keep in mind that the total length of the two hemistichs
% added to the one of the gutter that separates them must not exceed
% the length of the base line, unless one wishes to have the
% hemistichs distributed on subsequent lines.
%
% \DescribeOption{gutter} |gutter|$=$\meta{width}
% \hfill\arabluaverb{Default: 0.15 x (hemistich width)}\\ The gutter
% consists of the blank space that is between the two hemistichs. By
% default, it is commensurate with the width of the hemistich, but it
% may be expressed in any accepted unit of measurement as well.
%
% \DescribeOption{metre} |metre|$=$\meta{name}
% \hfill\arabluaverb{Default: none}\\ If the name of the metre is
% expressed, it is printed after the lines and set flush left in
% |voc|, |fullvoc| and |novoc| modes or flush right in |trans| mode.
%
% \DescribeOption{delim} |delim|$=$|true|\verb+|+|false|
% \hfill\arabluaverb{Default: false}\\ This named argument does not
% need a value as it defaults to |true| if it is used. If so, a
% delimiter is printed between each of the hemistichs. By default, it
% is set to the \enquote*{star} character \enquote*{*}. The
% \DescribeMacro{\SetHemistichDelim}\cs{SetHemistichDelim}\marg{delimiter}
% command may be used at any point of the document to change this
% default setting.
%
% \DescribeOption{utf} |utf|$=$|true|\verb+|+|false|
% \hfill\arabluaverb{Default: false}\\ As the preceding one, this
% named argument does not need a value as it defaults to |true| if it
% is used. If so, unicode Arabic input is expected in the |arabverse|
% environment instead of \textsc{ascii} Arab\TeX\ or Buckwalter input
% schemes. See \vref{sec:unicode-input} for more details.
%
% \DescribeMacro{\bayt} Inside the |arabverse| environment, each line
% is typeset by the \cs{bayt} command which takes two mandatory
% arguments and may accept one optional argument. Additionally, every
% \cs{bayt} command \emph{must} be followed with |\\| like so:---%
% \iffalse
%<*example>
% \fi
\begin{arabluacode}[text only]
  \cs{bayt}\marg{\arb[trans]{.sadr}}\oarg{\arb[trans]{tadwIr}}%
  \marg{\arb[trans]{`ajuz}}|\\|
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% That two subsequent hemistichs should be connected with one another
% is technically named \arb[trans]{tadwIr}. Should that happen, either
% the \arb[trans]{.sadr} or the \arb[trans]{`ajuz} or both of them,
% may be connected to one another by letters that are naturally bound
% to the following or the preceding ones over the
% \arb[trans]{tadwIr}. The optional argument of the \cs{bayt} command
% is designed to deal with the various situations that may arise:---
% \begin{compactenum}[(a)]
% \item If the two hemistichs be connected with one another by a
% prominent horizontal flexible stroke, the \arb[trans]{tatwIl} should
% be used, like so: |[--]| (see \vref{sec:tatwil}). Of course, the
% ending word of the \arb[trans]{.sadr} and the word at the
% commencement of the \arb[trans]{`a^guz} must have the
% \arb[trans]{ta.twIl} too so that the proper shapes of the letters be
% selected. Consider for example the following:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
\begin{arabverse}[mode=fullvoc, width=.3\linewidth]
  \bayt{lA 'ar_A man `ahidtu fI-hA fa-'abkI 'l---}[--]{---yawma
    dalhaN wa-mA yu.hIru 'l-bukA'u}\\
\end{arabverse}
\end{arabluacode}
% \iffalse
%</example>
% \fi%
% As one can see, \emph{triple hyphens} have been used. In the
% \arb[trans]{.sadr}, the first hyphen triggers the rules that are
% related to the definite article and the \arb[trans]{'alif-u
% 'l-wa.sl-i},\footnote{See \vref{ref:definite-article}} while the
% following two select the figure of the letter \arb[trans]{lAm}
% connected with a following letter. In the \arb[trans]{`a^guz}, the
% last two hyphens select the letter \arb[trans]{yA'} connected with a
% preceding letter, while the first one is simply discarded in this
% mode, but still may appear as it should, if the |trans| mode be
% selected:---%
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
\begin{arabverse}[mode=trans, width=.4\linewidth]
  \bayt{lA 'ar_A man `ahidtu fI-hA fa-'abkI 'l---}[--]{---yawma
    dalhaN wa-mA yu.hIru 'l-bukA'u}\\
\end{arabverse}
\end{arabluacode}
% \iffalse
%</example>
% \fi%
% \item In some other cases, it may seem difficult, if not fairly
%   impossible, to split a given word into two parts. This happens
%   mostly because of the \arb[trans]{^saddaT}. Consider for example
%   the following:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
\begin{arabverse}[mode=fullvoc, width=.25\linewidth, gutter=1cm]
  \bayt{.gayra 'annI qad 'asta`Inu `al_A 'l-ha--}[--mmi ]{'i_dA
  _haffa bi-'l-_tawiyyi 'l-na^gA'u}\\
  \bayt{bi-zaf--UfiN ka-'anna-hA hiq--laTuN}[ 'ummu ]{ri'AliN
  dawwiyyaTuN saqfA'u}\\
\end{arabverse}
\end{arabluacode}
% \iffalse
%</example>
% \fi%
% In the first line, the word \arb{al-hammi} should be split into
% \arb{al-ham"-- --mi} as the first part of it belongs to the
% \arb[trans]{.sadr} and the second to the \arb[trans]{`a^guz}. One
% solution to avoid splitting this word in such a way is to write
% inside the \arb[trans]{tadwIr} the part of it that belongs to either
% hemistich, without omitting to add a space after it. In the second
% line, the word \arb{'ummu} should be split into \arb{'um"-- --mu},
% so that the only way to avoid splitting it into two parts is to
% write it all inside the \arb[trans]{tadwIr}. In that case, as the
% word is to be placed in the middle, it has been surrounded by
% spaces.
% \end{compactenum}
%
% \paragraph{Scaling and distortion of characters}
% The |arabverse| environment and the \cs{bayt} command are designed
% to typeset the verses in a two-column, fixed width layout. This may
% result in somewhat distorted text. Should that happen, one may adapt
% the layout by modifying the values of the above described |width|
% and |gutter| named arguments until the visual aspect of the layout
% be satisfactory. It has to be noted that distortion and warping may
% be even more perceptible in Roman than in Arabic characters.
%
% \paragraph{Footnotes}
% Footnotes are not set by default inside the \cs{bayt} command, but
% there are two easy ways to have them printed.
%
% If they are little in number, each footnote may be split into pairs
% of \cs{footnote\allowbreak{}mark}|{}| (please mind the braces) in
% either argument of the \cs{bayt} command and \cs{footnotetext}
% outside the \cs{bayt} command.
%
% If the footnotes are abundant in number, it is advised to load the
% \package{footnote} package which \package{arabluatex} will then use
% to typeset any kind of footnote that is called from the arguments of
% the \cs{bayt} command. Please note that the \package{footnote}
% package must be loaded \emph{after} \package{arabluatex}.
%
% \paragraph{Line numbering}
% Inside the |arabverse| environment, the |linenumbers| environment of
% the \package{lineno} package may be used to have the lines of
% succeeding verses numbered. Please refer to the documentation of
% this package for more information or to the example below for a
% basic implementation of this technique.
%
% \subsection{Example}
% \label{sec:poetry-example}
% Here follow the first lines of \arb[trans]{\upshape{}\cap{i}mru'u
% 'l-\cap{q}aysi}'s \arb[trans]{\cap{m}u`allaqaT}. In this example,
% \cs{SetArbDflt*} has been selected so as to mark the
% \arb[trans]{'id.gAm} that is fit to this declamatory
% poetry:---\footnote{See \vref{sec:classic-modern-typesetting} for
% more information.}%
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
\begin{arab}[fullvoc]
  qAla \cap{i}mru'u 'l-\cap{q}aysi fI mu`allaqati-hi:
\end{arab}

\begin{arabverse}[mode=fullvoc, metre={(al-.darbu 'l-_tAnI mina
  'l-`arU.di 'l-'_Ul_A mina 'l-.tawIli)}]
  \SetArbDflt*
  \begin{linenumbers*}
    \bayt{qifA nabki min _dikr_A .habibiN wa-manzili}{bi-saq.ti
      'l-liw_A bayna \cap{'l-d}a_hUli wa-\cap{.h}awmali}\\
    \bayt{fa-\cap{t}Udi.ha fa-'l-\cap{m}iqrATi lam ya`fu
      rasmu-hA}{limA nasa^gat-hA min ^ganUbiN wa-^sam'ali}\\
    \bayt{tar_A ba`ara 'l-'ar'Ami fI `ara.sAti-hA}{wa-qI`Ani-hA
      ka-'anna-hu .habbu fulfuli}\\
    \bayt{ka-'annI .gadATa 'l-bayni yawma ta.hammalUA}{laday
      samurAti 'l-.hayyi nAqifu .han.zali}\\
    \bayt{wuqUfaN bi-hA .sa.hbI `alayya ma.tiyya-hum}{yaqUlUna lA
      tahlik 'asaN_A wa-ta^gammali}\\
    \bayt{wa-'inna ^sifA'I `abraTuN muhrAqaTuN}{fa-hal `inda rasmiN
      dAsiriN min mu`awwali}\\
  \end{linenumbers*}
\end{arabverse}
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi%
% \begin{arab}[fullvoc]
%   qAla \cap{i}mru'u 'l-\cap{q}aysi fI mu`allaqati-hi:
% \end{arab}
% 
% \begin{arabverse}[mode=fullvoc, metre={(al-.darbu 'l-_tAnI mina
%  'l-`arU.di 'l-'_Ul_A mina 'l-.tawIli)}, width=.25\linewidth]
%  \SetArbDflt*
%   \begin{linenumbers*}
%     \bayt{qifA nabki min _dikr_A .habibiN wa-manzili}{bi-saq.ti
%     'l-liw_A bayna \cap{'l-d}a_hUli wa-\cap{.h}awmali}\\
%     \bayt{fa-\cap{t}Udi.ha fa-'l-\cap{m}iqrATi lam ya`fu
%     rasmu-hA}{limA nasa^gat-hA min ^ganUbiN wa-^sam'ali}\\
%     \bayt{tar_A ba`ara 'l-'ar'Ami fI `ara.sAti-hA}{wa-qI`Ani-hA
%     ka-'anna-hu .habbu fulfuli}\\
%     \bayt{ka-'annI .gadATa 'l-bayni yawma ta.hammalUA}{laday
%     samurAti
%     'l-.hayyi nAqifu .han.zali}\\
%     \bayt{wuqUfaN bi-hA .sa.hbI `alayya ma.tiyya-hum}{yaqUlUna lA
%     tahlik 'asaN_A wa-ta^gammali}\\
%     \bayt{wa-'inna ^sifA'I `abraTuN muhrAqaTuN}{fa-hal `inda rasmiN
%     dAsiriN min mu`awwali}\\
%   \end{linenumbers*}
% \end{arabverse}
% 
% \begin{arab}[trans]
%   qAla \cap{i}mru'u 'l-\cap{q}aysi fI mu`allaqati-hi:
% \end{arab}
% 
% \begin{arabverse}[mode=trans, metre={(al-.darbu 'l-_tAnI mina
%  'l-`arU.di 'l-'_Ul_A mina 'l-.tawIli)}, width=.4\linewidth]
%  \SetArbDflt*
%   \begin{linenumbers*}
%     \bayt{qifA nabki min _dikr_A .habibiN wa-manzili}{bi-saq.ti
%     'l-liw_A bayna \cap{'l-d}a_hUli wa-\cap{.h}awmali}\\
%     \bayt{fa-\cap{t}Udi.ha fa-'l-\cap{m}iqrATi lam ya`fu
%     rasmu-hA}{limA nasa^gat-hA min ^ganUbiN wa-^sam'ali}\\
%     \bayt{tar_A ba`ara 'l-'ar'Ami fI `ara.sAti-hA}{wa-qI`Ani-hA
%     ka-'anna-hu .habbu fulfuli}\\
%     \bayt{ka-'annI .gadATa 'l-bayni yawma ta.hammalUA}{laday
%     samurAti
%     'l-.hayyi nAqifu .han.zali}\\
%     \bayt{wuqUfaN bi-hA .sa.hbI `alayya ma.tiyya-hum}{yaqUlUna lA
%     tahlik 'asaN_A wa-ta^gammali}\\
%     \bayt{wa-'inna ^sifA'I `abraTuN muhrAqaTuN}{fa-hal `inda rasmiN
%     dAsiriN min mu`awwali}\\
%   \end{linenumbers*}
% \end{arabverse}
% 
% \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}
%
% \paragraph{Brackets}
% \NEWfeature{v1.4.3} The various bracket symbols are useful in
% technical documents such as critical editions for indicating that
% some words or some letters must be added or
% removed. \package{arabluatex} will automatically fit those symbols
% to the direction of the text. For the time being, the following
% symbols are supported:
% \begin{compactitem}
% \item parentheses: |()|
% \item square brackets: |[]|
% \item angle brackets: |<>|
% \item braces: |{}|
% \end{compactitem}
%
% \DescribeMacro{\abraces} Parentheses, square and angle brackets may
% be input directly at the keyboard; however, words or letters that
% are to be read between braces must be passed as arguments to the
% \cs{abraces} command:---%
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
  \begin{arab}
    \abraces{wa-qAla} 'inna 'abI kAna mina 'l-muqAtilaTi
    wa-kAna--<--t> 'ummI min `u.zamA'i buyUti 'l-zamAzimaTi.
  \end{arab}
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% \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
% \cs{SetTranslitConvention}\marg{mode} command , 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 \cs{SetTranslitStyle}\marg{style}
% command , where \meta{style} may be any font shape selection
% command, eg. \cs{upshape}, \cs{itshape}, \cs{slshape}, and so forth.
%
% \paragraph{Font} \NEWfeature{v1.4} \DescribeMacro{\SetTranslitFont}
% \cs{SetTranslitFont}\marg{font selection command} allows any
% specific font to be selected for rendering transliterated text with
% the font-selecting commands of the \package{fontspec} or
% \package{luaotfload} package. Of course, this font must have been
% defined properly. To take one example, here is how the \emph{Gentium
% Plus} font may be used for rendering transliterated text:---
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
\newfontfamily\translitfont{Gentium Plus}[Ligatures=TeX]
\SetTranslitFont{\translitfont}
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi
%
% \paragraph{Proper names} \DescribeMacro{\cap} Proper names or book
% titles that must have their first letters uppercased may be passed
% as arguments to the \cs{cap}\marg{word} command. \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{.hunayn-u}| |bn-u| |\cap{'is.h_aq-a}|
%   \arb[voc]{\cap{.hunayn-u} bn-u \cap{'is.h_aq-a}}
%   \arb[trans]{\cap{.hunayn-u} bn-u \cap{'is.h_aq-a}},
%   |\cap{`u_tm_an-u}| \arb[voc]{\cap{`u_tm_an-u}}
%   \arb[trans]{\cap{`u_tm_an-u}}, |.daraba| |\cap{zayd-u}| |bn-u|
%   |\cap{_h_alidiN}| |\cap{sa`d-a}| |bn-a| |\cap{`awf-i}| |bn-i|
%   |\cap{`abd-i}| |\cap{'l-l_ah-i}| \arb[fullvoc]{.daraba
%   \cap{zayd-u} bn-u \cap{_h_alidiN} \cap{sa`d-a} bn-a \cap{`awf-i}
%   bn-i \cap{`abd-i} \cap{'l-l_ah-i}} \arb[trans]{.daraba
%   \cap{zayd-u} bn-u \cap{_h_alidiN} \cap{sa`d-a} bn-a \cap{`awf-i}
%   bn-i \cap{`abd-i} \cap{'l-l_ah-i}}.
% \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 that 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|.
%
% \paragraph{Hyphenation}
% In case transliterated Arabic words break the \TeX\ hyphenation
% algorithm, one may use the |\-| command to insert discretionary
% hyphens. This command will be discarded in all of the Arabic modes
% of \package{arabluatex}, but will be processed by any of the
% transliteration modes:---
% \begin{quote}
%   |\cap{'abU}| |\cap{bakriN}| |\cap{mu\-.ham\-madu}| |bnu|
%   |\cap{za\-ka| |\-riy\-yA'a}| |\cap{'l-rAzI}| \arb{\cap{'abU}
%   \cap{bakriN} \cap{mu\-.ham\-mad-u} bnu \cap{za\-ka\-riy\-yA'a}
%   \cap{'l-rAzI}} \arb[trans]{\cap{'abU} \cap{bakriN}
%   \cap{mu\-.ham\-mad-u} bn-u \cap{za\-ka\-riy\-yA'-a}
%   \cap{'l-rAzI}}.
% \end{quote}
%
% \subsection{Additional note on \texttt{dmg} convention}
% \label{sec:additional-note-dmg}
% \NEWfeature{v1.3} According to \textcite[6]{dmg}, Arabic
% \arb[trans]{'i`rAb} may be rendered into |dmg| in three different
% ways:
% \begin{compactenum}[(a)]
% \item \label{ref:dmg-full-rend}In full:
%   \NoArbUp\arb[trans]{\cap{`amruNU}}\ArbUpDflt\,;
% \item \label{ref:dmg-up-rend}As superscript text:
%   \arb[trans]{\cap{`amruNU}}\,;
% \item Discarded: \arb[trans]{\cap{`amr}}.
% \end{compactenum}
% \DescribeMacro{\arbup} By default, \package{arabluatex} applies rule
% \ref{ref:dmg-up-rend}. Once delimited by a set of Lua functions,
% \arb[trans]{'i`rAb} is passed as an argument on to a \cs{arbup}
% command which is set to \cs{textsuperscript}.
%
% \DescribeMacro{\NoArbUp} \DescribeMacro{\ArbUpDflt} \cs{NoArbUp} may
% be used either in the preamble or at any point of the document in
% case one wishes to apply rule \ref{ref:dmg-full-rend}. The default
% rule \ref{ref:dmg-up-rend} can be set back with \cs{ArbUpDflt} at
% any point of the document.
%
% \DescribeMacro{\SetArbUp} Finally, \cs{SetArbUp}\marg{formatting
% directives} may be used to customize the way \arb[trans]{'i`rAb} is
% displayed. To take one example, here is how Arabic
% \arb[trans]{'i`rAb} may be rendered as subscript text:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
\SetArbUp{\textsubscript{#1}}
Arabic |dmg| transliteration for \arb{ra'aytu ^gAmi`aN
muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu
^gAmi`aN muhaddamaTaN mi'_danatu-hu.}
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% As shown in the above example, |#1| is the token that is replaced
% with the actual \arb[trans]{tanwIn} in the formatting directives of
% the \cs{SetArbUp} command.
%
% \paragraph{\arb[trans]{'i`rAb} boundaries}
% Every declinable noun (\arb[trans]{mu`rab}) may be declined either
% with or without \arb[trans]{tanwIn}, viz. \arb[trans]{mun.sarifuN}
% or \arb[trans]{.gayr-u mun.sarifiN}. The former is automatically
% parsed by \package{arabluatex}, whereas the latter has to be
% delimited with an hyphen, like so:---
% \begin{quote}
%   \arb[trans]{\textbf{mun.sarif}}: |mu`allimuN|
%   \arb[voc]{mu`allimuN} \arb[trans]{mu`allimuN}, |kA'inuN|
%   \arb[voc]{kA'inuN} \arb[trans]{kA'inuN}, |kA'inAtuN|
%   \arb[voc]{kA'inAtuN} \arb[trans]{kA'inAtuN}, |\cap{`amraNU}|
%   \arb[voc]{\cap{`amraNU}} \arb[trans]{\cap{`amraNU}}, |fataN_A|
%   \arb[voc]{fataN_A} \arb[trans]{fataN_A}, |qA.diNI| \arb{qA.diNI}
%   \arb[trans]{qA.diNI}.
%
%   \arb[trans]{\textbf{.gayr mun.sarif}}: |al-mu`allim-u|
%   \arb[voc]{al-mu`allim-u} \arb[trans]{al-mu`allim-u}, |kitAb-Ani|
%   \arb[voc]{kitAb-Ani} \arb[trans]{kitAb-Ani}, |ra^sa'-Ani|
%   \arb[voc]{ra^sa'-Ani} \arb[trans]{ra^sa'-Ani}, |sAriq-Una|
%   \arb[voc]{sAriq-Una} \arb[trans]{sAriq-Una}, |qA.d-Una|
%   \arb[voc]{qA.d-Una} \arb[trans]{qA.d-Una}, |al-.zulm-Atu|
%   \arb[voc]{al-.zulm-Atu} \arb[trans]{al-.zulm-Atu}.
% \end{quote}
%
% \begin{quoting}
%   \textsc{Rem.}~\emph{a.} As the \arb[trans]{tanwIn} is passed over
%   in pronunciation when it is followed by the letters
%   \arb[novoc]{r}, \arb[novoc]{l}, \arb[novoc]{m}, \arb[novoc]{w},
%   \arb[novoc]{y} (see \vref{ref:assimilation}), it may be desirable
%   to further distinguish it by putting it above the line, but not to
%   do the same for \arb[trans]{.gayr mun.sarif} terminations. This
%   can be achieved by simply omitting the hyphen before any
%   \arb[trans]{.gayr mun.sarif} termination:---\\
%   |kAna| |.ganiyyaN| |l_akinna-hu| |labisa| |^gubbaTaN| |mumazzaqaN|
%   |'aydu-hA| \arb[voc]{kAna .ganiyyaN l_akinna-hu labisa ^gubbaTaN
%   mumazzaqaN 'aydu-hA} \arb[trans]{kAna .ganiyyaN l_akinna-hu labisa
%   ^gubbaTaN mumazzaqaN 'aydu-hA}.
%
%   \textsc{Rem.}~\emph{b.} Although the hyphen before the
%   \arb[trans]{tanwIn} is optional as \package{arabluatex} always
%   parses nouns with such termination, it may also be used to mark
%   better the inflectional endings:---\\
%   |mana`a| |'l-nAs-a| |kAffaT-aN| |min| |mu_hA.tabati-hi|
%   |'a.had-uN| |bi-sayyidi-nA| \arb[voc]{mana`a 'l-nAs-a kAffaT-aN
%   min mu_hA.tabati-hi 'a.had-uN bi-sayyidi-nA} \arb[trans]{mana`a
%   'l-nAs-a kAffaT-aN min mu_hA.tabati-hi 'a.had-uN bi-sayyidi-nA}.
% \end{quoting}
%
% \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 fa-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 ra.gbata-ka fa-'l-.himAr-u laysa hunA 'l-yawm-a.}  wa-qabla
%   'an yutimma \cap{ju.hA} kalAma-hu bada'a 'l-.himAr-u yanhaqu fI
%   'i.s.tabli-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-.himAr-a
%   wa-tuka_d_diba-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 fa-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 ra.gbata-ka fa-'l-.himAr-u laysa hunA 'l-yawm-a.}  wa-qabla
%   'an yutimma \cap{ju.hA} kalAma-hu bada'a 'l-.himAr-u yanhaqu fI
%   'i.s.tabli-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-.himAr-a
%   wa-tuka_d_diba-nI?}
% \end{arab}
% \SetTranslitConvention{dmg}
%
% \section{Buckwalter input scheme}
% \label{sec:buckwalter-scheme}
% \NEWfeature{v1.4} Even though \package{arabluatex} is primarily
% designed to process the Arab\TeX\ notation, it can also process the
% Buckwalter input scheme to a large extent.\footnote{See
% \url{http://www.qamus.org/transliteration.htm}} The Buckwalter
% scheme is actually processed in two steps, as it is first converted
% into Arab\TeX. Then, once this is accomplished, the Arab\TeX\ scheme
% is processed through the above described functions. In this way, the
% Buckwalter input scheme can make the most of the
% \package{arabluatex} special features that are presented in
% \vref{sec:options}.
%
% \DescribeMacro{\SetInputScheme} The input scheme, which is set to
% |arabtex| by default, may be changed at any point of the document by
% the \cs{SetInputScheme}\marg{scheme} command, where \meta{scheme}
% may be either |arabtex| or |buckwalter|. This command is also
% accepted in the preamble should one wish to set the input scheme
% globally, like so:---
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
\usepackage{arabluatex}
\SetInputScheme{buckwalter}
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi
%
% \paragraph{\enquote*{base}, \enquote*{\texttt{xml}} and
% \enquote*{safe} schemes}
% \package{arabluatex} can use any of the so-called Buckwalter
% \enquote*{base}, \enquote*{\texttt{xml}} or \enquote*{safe} schemes
% as they are described in \textcite[25--26]{Habash}.\footnote{I am
% grateful to Graeme Andrews who suggested that the \enquote*{safe}
% scheme be included in \package{arabluatex}.} However, the following
% limitation apply to the \enquote*{base} and \enquote*{\texttt{xml}}
% schemes: the braces |{| and |}|, which are used to encode
% \arb[novoc]{"a} and \arb[novoc]{y"'}, must be replaced with square
% brackets viz. |[| and |]| respectively.
%
% It is therefore recommended to use the Buckwalter \enquote*{safe}
% scheme.
%
% \Cref{tab:buckwalter-scheme} gives the Buckwalter equivalents that
% are currently used by \package{arabluatex}. The additional
% characters that are defined in \vref{tab:additional-arabic-codings}
% are also available.
% 
% \begin{longtable}{lllll}
% \captionlistentry{Buckwalter scheme}\\[-1em]
% \toprule
% Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
% & \multicolumn{2}{l}{Buckwalter notation} \\
% & \texttt{dmg} & \texttt{loc} & |base/xml| & |safe| \\ \midrule
% \endfirsthead
% \toprule
% Letter & \multicolumn{2}{l}{Transliteration}
% & \multicolumn{2}{l}{Buckwalter notation} \\
% & \texttt{dmg} & \texttt{loc} & |base/xml| & |safe| \\ \midrule
% \endhead \footnotetext{See \vref{sec:transliteration}.}
% \label{tab:buckwalter-scheme}
% \arb[novoc]{a} & \dmg{a} & \loc{a} & |A| & |A| \\
% \arb[novoc]{b} & \dmg{b} & \loc{b} & |b| & |b| \\
% \arb[novoc]{t} & \dmg{t} & \loc{t} & |t| & |t| \\
% \arb[novoc]{_t} & \dmg{_t} & \loc{_t} & |v| & |v| \\
% \arb[novoc]{j} & \dmg{j} & \loc{j} & |j| & |j| \\
% \arb[novoc]{.h} & \dmg{.h} & \loc{.h} & |H| & |H| \\
% \arb[novoc]{x} & \dmg{x} & \loc{x} & |x| & |x| \\
% \arb[novoc]{d} & \dmg{d} & \loc{d} & |d| & |d| \\
% \arb[novoc]{_d} & \dmg{_d} & \loc{_d} & |*| & |V| \\
% \arb[novoc]{r} & \dmg{r} & \loc{r} & |r| & |r| \\
% \arb[novoc]{z} & \dmg{z} & \loc{z} & |z| & |z| \\
% \arb[novoc]{s} & \dmg{s} & \loc{s} & |s| & |s| \\
% \arb[novoc]{^s} & \dmg{^s} & \loc{^s} & |$| & |c| \\
% \arb[novoc]{.s} & \dmg{.s} & \loc{.s} & |S| & |S| \\
% \arb[novoc]{.d} & \dmg{.d} & \loc{.d} & |D| & |D| \\
% \arb[novoc]{.t} & \dmg{.t} & \loc{.t} & |T| & |T| \\
% \arb[novoc]{.z} & \dmg{.z} & \loc{.z} & |Z| & |Z| \\
% \arb[novoc]{`} & \dmg{`} & \loc{`} & |E| & |E| \\
% \arb[novoc]{.g} & \dmg{.g} & \loc{.g} & |g| & |g| \\
% \arb[novoc]{f} & \dmg{f} & \loc{f} & |f| & |f| \\
% \arb[novoc]{q} & \dmg{q} & \loc{q} & |q| & |q| \\
% \arb[novoc]{k} & \dmg{k} & \loc{k} & |k| & |k| \\
% \arb[novoc]{l} & \dmg{l} & \loc{l} & |l| & |l| \\
% \arb[novoc]{m} & \dmg{m} & \loc{m} & |m| & |m| \\
% \arb[novoc]{n} & \dmg{n} & \loc{n} & |n| & |n| \\
% \arb[novoc]{h} & \dmg{h} & \loc{h} & |h| & |h| \\
% \arb[novoc]{w} & \dmg{w} & \loc{w} & |w| & |w| \\
% \arb[novoc]{y} & \dmg{y} & \loc{y} & |y| & |y| \\
% \arb[novoc]{Y} & \dmg{Y} & \loc{Y} & |Y| & |Y| \\
% \arb[novoc]{T} & \dmg{aT} & \loc{aT} & |p| & |p| \\
% \midrule
% \arb[novoc]{|"'} & \dmg{|"'} & \loc{|"'} & \verb|'| & |C| \\
% \arb[novoc]{A"'} & \dmg{A"'} & \loc{A"'} & \verb+|+ & |M| \\
% \arb[novoc]{a"'} & \dmg{a"'} & \loc{a"'} & \verb|>| & |O| \\
% \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|]| & |Q| \\
% \midrule
% \arb[novoc]{BB} & --- & --- & \verb|~| & |~| \\
% \arb[novoc]{"a} & ' & ' & |[| & |L| \\
% \midrule
% \arb[voc]{Ba} & \dmg{Ba} & \loc{Ba} & \verb|a| & |a| \\
% \arb[voc]{Bu} & \dmg{Bu} & \loc{Bu} & \verb|u| & |u| \\
% \arb[voc]{Bi} & \dmg{Bi} & \loc{Bi} & \verb|i| & |i| \\
% \arb[voc]{BaN} & \dmg{BaN} & \loc{BaN} & \verb|F| & |F| \\
% \arb[voc]{BuN} & \dmg{BuN} & \loc{BuN} & \verb|N| & |N| \\
% \arb[voc]{BiN} & \dmg{BiN} & \loc{BiN} & \verb|K| & |K| \\
% \arb[voc]{B"} & --- & --- & \verb|o| & |o| \\
% \midrule
% \arb[novoc]{B_a} & \dmg{B_a} & \loc{B_a} & |`| & |e| \\
% \midrule
% \arb[novoc]{--} (\arb[trans]{ta.twIl}) & --- & --- & |_| & |_| \\
% \bottomrule
% \caption*{\Cref*{tab:buckwalter-scheme}: Buckwalter scheme}
% \end{longtable}
%
% \paragraph{Transliteration}
% The Buckwalter notation can also be transliterated into any accepted
% romanization standard of Arabic. See above
% \vref{sec:transliteration} for more information. However, it should
% be pointed out again that only accurate coding produces accurate
% transliteration. It is therefore at the very least highly advisable
% to use the hyphen for tying the definite article and the inseparable
% particles (viz. prepositions, adverbs and conjunctions) to words,
% like so:--- \SetInputScheme{buckwalter}
% \begin{quote}
%   |Al-EaAlamu| \arb{Al-EaAlam-u} \arb[trans]{Al-EaAlam-u},
%   |Al-camsu| \arb{Al-cams-u} \arb[trans]{Al-cams-u},
%   |bi-SinaAEapi| |Al-T~ib~i|, \arb{bi-SinaAEap-i Al-T~ib~-i}
%   \arb[trans]{bi-SinaAEap-i Al-T~ib~-i}.
%
%   |wa-Al-l~ehi| \arb{wa-Al-l~eh-i} \arb[trans]{wa-Al-l~eh-i},
%   |Al-Hamdu| |li-l~ehi| \arb{Al-Hamd-u li-l~eh-i}
%   \arb[trans]{Al-Hamd-u li-l~eh-i}.
% \end{quote}
% \SetInputScheme{arabtex}
%
% Similary, it is not advisable to use \verb+|+ and |[|
% (\enquote*{base} and \enquote*{\texttt{xml}} schemes) or |M| and |L|
% (\enquote*{safe} scheme) to encode the \arb[trans]{'alif-u
% 'l-mamdUdaT-i} and the \arb[trans]{'alif-u 'l-wa.sl-i} for such
% signs are supposed to be generated by \package{arabluatex} internal
% functions.  Besides, as they do not \emph{per se} convey any
% morphological information on what they are derived from, they cannot
% be transliterated accurately. To take one example, %
% \SetInputScheme{buckwalter}%
% |<ilY Al-LntiqaADi| gives \arb{>ilY Al-LntiqaADi} as expected, but
% only |<ilY Al-intiqADi| can be transliterated as \arb[trans]{<ilY
% Al-intiqaADi} with the correct vowel \meta{i} in place of the %
% \SetInputScheme{arabtex}%
% \arb[trans]{'alif-u 'l-wa.sl-i}.
%
% \section{Unicode Arabic input}
% \label{sec:unicode-input}
% \NEWfeature{v1.5} As said above in \vref{sec:buckwalter-scheme}
% about the Buckwalter input scheme, even though \package{arabluatex}
% is primarily designed to process the Arab\TeX\ notation, it also
% accepts unicode Arabic input. It should be noted that
% \package{arabluatex} does in no way interfere with unicode Arabic
% input: none of the options |voc|, |fullvoc|, |novoc| or |trans| will
% have any effect on plain unicode Arabic for the time being.
%
% That said, there are two ways of inserting unicode
% Arabic:
% \begin{compactenum}[(a)] 
% \item \DescribeMacro{\txarb} The \cs{txarb}\marg{unicode Arabic}
%   command for inserting unicode Arabic text in paragraphs;
% \item The \DescribeEnv{txarab} |txarab| environment for inserting
%   running paragraphs of Arabic text, like so:---\\%
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
  \begin{txarab}
    <Unicode Arabic text>
  \end{txarab}
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi
% \end{compactenum}
%
% \section{\LaTeX\ Commands in Arabic environments}
% \label{sec:commands-in-arb}
% \paragraph{General principle} \label{ref:cmd-inside-arabic}\LaTeX\
% 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{`AdAt-i}}|
%   \arb[voc]{\abjad{45} kitAbu-hu \emph{fI 'l-\cap{`AdAt-i}}}
%   \arb[trans]{\abjad{45} kitAbu-hu \emph{fI
%   'l-\cap{`AdAt-i}}}.\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-muqAtilaT-i\footnote{al-muqAtilaT-i:
al-muqAtil-Ina.}, wa-kAnat 'ummI min `u.zamA'-i buyUt-i
'l-zamAzimaT-i\footnote{al-zamAzimaT-u: .tA'ifaT-u mina
'l-furs-i.}.
\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 right to left. 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}
_tumma "intalaqa _dU 'l-qarn-ayni 'il_A 'ummaT-iN 'u_hr_A fI
\LR{\textcolor{red}{\arb[fullvoc]{((ma.tli`-i 'l-^sams-i))}}}
wa-lA binA'-a la-hum yu'amminu-hum mina 'l-^sams-i.
\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}ayd-uN\LRfootnote{%
\enquote{\arb[trans]{\cap{z}ayd} is the son of
\arb[trans]{\cap{`a}mr}}: the second
noun is not in apposition to the first, but forms
part of the predicate\ldots} "ibn-u \cap{`a}mr-iNU}
\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 that, 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
% \cs{FixArbFtnmk} command. 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 \cs{LRmarginpar} command 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 bn-i 'l-buxtikAni}}
\setLR
\begin{arab}
qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a...
\end{arab}
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% \subsection{Environments}
% \label{sec:environments}
% \changes{v1.5}{2016/11/14}{Environments may be nested inside the
%   \texttt{arab} environment}
% \NEWfeature{v1.5} Environments such as
% \arabluaverb{\begin{quote}... \end{quote}} may be nested inside the
% |arab| environment. Up to one optional argument may be passed to
% each nested environment, like so:---
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
\begin{arab}
  \begin{<environment>}[<options>]
    <Arabic text>
  \end{<environment>}
\end{arab}
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi
%
% In the following example, the \package{quoting} package is used:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
  \setquotestyle{arabic}
  \begin{arab}[fullvoc]
    kAna \cap{'abU} \cap{'l-hu_dayli} 'ahd_A 'il_A \cap{muwaysiN}
    dajAjaTaN. wa-kAnat dajAjatu-hu 'llatI 'ahdA-hA dUna mA kAna
    yuttaxa_du li-\cap{muwaysiN}. wa-l_akinna-hu bi-karami-hi
    wa-bi-.husni xuluqi-hi 'a.zhara 'l-ta`ajjuba min simani-hA
    wa-.tIbi la.hmi-hA. wa-kAna <\cap{'abU} \cap{'l-hu_dayli}> yu`rafu
    bi-'l-'imsAki 'l-^sadIdi. fa-qAla: \enquote{wa-kayfa ra'ayta yA
      \cap{'abA} \cap{`imrAna} tilka 'l-dajAjaTa?} qAla:
    \enquote{kAnat `ajabaN mina 'l-`ajabi!}  fa-yaqUlu:
    \begin{quoting}[begintext=», endtext=«]
      wa-tadrI mA jinsu-hA? wa-tadrI mA sinnu-hA?  fa-'inna
      'l-dajAjaTa 'inna-mA ta.tIbu bi-'l-jinsi wa-'l-sinni. wa-tadrI
      bi-'ayyi ^say'iN kunnA nusamminu-hA? wa-fI 'ayyi makAniN kunnA
      na`lifu-hA?
    \end{quoting}
    fa-lA yazAlu fI h_a_dA wa-'l-'A_haru ya.d.haku .da.hkaN na`rifu-hu
    na.hnu wa-lA ya`rifu-hu \cap{'abU} \cap{'l-hu_dayli}.
  \end{arab}
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% \subsubsection{Lists}
% \label{sec:lists}
% Lists environments are also accepted inside the |arab|
% environment. One may either use any of the three standard list
% environments, viz. |itemize|, |enumerate| and |description| or use a
% package that provides additional refinements such as
% \package{paralist}.
%
% To take a first example, should one wish to typeset a list of
% manuscripts, the |description| environment may be used like so:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
 \setRL\paragraph{\arb[novoc]{rumUzi 'l-kitAbi}}\setLR
 \begin{arab}[novoc]
  \begin{description}
   \item[b] max.tU.tu 'l-maktabaTi 'l-'ahliyyaTi bi-\cap{bArIs} 2860
    `arabiyyuN.
   \item[s] max.tU.tu 'l-maktabaTi 'l-'ahliyyaTi bi-\cap{bArIs} 2859
    `arabiyyuN.
   \item[m] max.tU.tu majlisi \arb[novoc]{^sUrAY malY} .tahrAna 521.
  \end{description}
 \end{arab}
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% As a second example, the contents of a treatise may be typeset with
% the standard list environments, like so:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
  \setRL\centerline{\arb{\textbf{al-qAnUnu fI 'l-.tibbi}}}\setLR
  \begin{arab}
    \begin{itemize}
    \item \textbf{al-fannu 'l-'awwalu} fI .haddi 'l-.tibbi
      wa-maw.dU`Ati-hi mina 'l-'umUri 'l-.tabI`iyyaTi wa-ya^stamilu
      `al_A sittaTi ta`AlImiN
      \begin{itemize}
        \item \textbf{al-ta`lImu 'l-'awwalu} [wa-huwa fa.slAni]
          \begin{itemize}
          \item \textbf{al-fa.slu 'l-'awwalu}
          \end{itemize}
      \end{itemize}
    \end{itemize}
  \end{arab}
\end{arabluacode}
% \iffalse
%</example>
% \fi
%
% \paragraph{Caveat}
% The various French definition files of the \package{babel} package
% viz. |acadian|, |canadien|, |francais|, |frenchb| or |french| all
% redefine the list environments, which breaks the standard definition
% file that is used by \package{arabluatex}. Therefore,
% \package{babel-french} must be loaded with the option
% |StandardLayout=true|, like so:---
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
\usepackage[french]{babel}
\frenchbsetup{StandardLayout=true}
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi%
% This option will prevent \package{babel-french} from interfering
% with the layout of the document. Then the package \package{paralist}
% may be used to make the lists \enquote*{compact} as
% \package{babel-french} do.
%
% \subsection{\package{csquotes}}
% \label{sec:csquotes}
% The recommended way of inserting quotation marks in running Arabic
% text is to use \package{csquotes}. With the help of the
% \cs{DeclareQuoteStyle} command, one can define an Arabic style, like
% so:---
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
\usepackage{csquotes}
\DeclareQuoteStyle{arabic}
{\rmfamily\textquotedblright}{\rmfamily\textquotedblleft}
{\rmfamily\textquoteright}{\rmfamily\textquoteleft}
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi
% Then, use this newly defined style with \cs{setquotestyle}, like so:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
\setquotestyle{arabic}
\begin{arab}
  fa-qAla la-hu ju.hA: \enquote{.garIb-uN 'amru-ka yA .sadIqI
    'a-tu.saddiqu 'l-.himAr-a wa-tuka_d_diba-nI?}
\end{arab}
\setquotestyle{english}
\end{arabluacode}
% \iffalse
%</example>
% \fi
% \begin{quoting}
%   \textsc{Rem.} Do not forget to set back the quoting style to its
%   initial state once the Arabic environment is closed. See the last
%   line in the code above.
% \end{quoting}
% 
% \subsection{\package{reledmac}}
% \label{sec: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-jild-i
\edtext{\arb{.sadId-uN}}{\Afootnote{M: \arb{.sadId-aN} E1}}
\end{arab}
\pend
\endnumbering
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi
%
% \subsection{\package{quran}}
% \label{sec:pkg-quran}
% \changes{v1.5}{2016/11/14}{Compatibility with the \textsf{quran}
% package} \package{arabluatex} is compatible with the \package{quran}
% package so that both can be used in conjunction with one another for
% typesetting the \arb[trans]{\cap{qur'An}}. As \package{quran} draws
% the text of the \arb[trans]{\cap{qur'An}} from a unicode encoded
% database, its commands have to be passed as arguments to the
% \cs{txarb} command for short insertions in left-to-right paragraphs,
% or inserted inside the \index{txarab=txarab (environment)}|txarab|
% environment for typesetting running paragraphs of
% \arb[trans]{\cap{qur'An}}\emph{ic} text (see above
% \vref{sec:unicode-input} for more details). Please note that
% \package{arabluatex} takes care of formatting the Arabic: therefore,
% it is recommended to load the \package{quran} package with the
% option |nopar|, after \package{arabluatex} itself has been loaded,
% like so:--- %
% \iffalse
%<*example>
% \fi
\begin{arabluaverbatim}
  \usepackage{arabluatex}
  \usepackage[nopar]{quran}
\end{arabluaverbatim}
% \iffalse
%</example>
% \fi
%
% As an example, the following code will typeset the \arb[trans]{sUraT}
% \arb[trans]{al-\cap{fAti.haT}}:---
% \iffalse
%<*example>
% \fi
\begin{arabluacode}
  \begin{txarab}
    \quransurah[1]
  \end{txarab}
\end{arabluacode}
% \iffalse
%</example>
% \fi
% 
% \section{Future work}
% \label{sec:future-work}
% 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 \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/12/17 v1.6 An 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}
% Packages that are required by \package{arabluatex}:
%    \begin{macrocode}
\RequirePackage{etoolbox}
\RequirePackage{arabluatex-patch}
\RequirePackage{fontspec}
\RequirePackage{amsmath}
\RequirePackage{luacode}
\RequirePackage{xparse}
\RequirePackage{environ}
\RequirePackage{adjustbox}
\RequirePackage{xkeyval}
%    \end{macrocode}
% The following boolean will be set to |true| in |RL| mode:
%    \begin{macrocode}
\newbool{al@rlmode}
%    \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{\booltrue{al@rlmode}\pardir TRT\textdir TRT}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\setLR}
%   The same applies to \cs{setLR}:
%    \begin{macrocode}
\AtBeginDocument{\def\setLR{\boolfalse{al@rlmode}\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}
% \begin{macro}{\SetInputScheme}
%   \changes{v1.4}{2016/07/05}{\cs{SetInputScheme} may be used to
%   process other input schemes such as \enquote*{Buckwalter}}
%   \package{arabluatex} is designed for processing Arab\TeX\ input
%   notation. \cs{SetInputScheme} may be used in the preamble or at
%   any point of the document should the user wish to use a different
%   notation such as the \enquote*{Buckwalter scheme}.
%    \begin{macrocode}
\def\al@input@scheme{arabtex}
\NewDocumentCommand{\SetInputScheme}{m}{\def\al@input@scheme{#1}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{macro}{\SetArbEasy}
%   \changes{v1.2}{2016/05/09}{New \cs{SetArbEasy}/\cs{SetArbDflt} for
%   \enquote*{modern} or \enquote*{classic} Arabic styles.}
% \begin{macro}{\SetArbEasy*}
%   \changes{v1.4.4}{2016/09/28}{this starred version discards the
%   \arb[trans]{sukUn} in addition to what is already discarded by
%   \cs{SetArbEasy}.}
% \begin{macro}{\SetArbDflt}
%   By default, \package{arabluatex} applies complex rules to generate
%   euphonic \arb[trans]{ta^sdId}, \arb[trans]{'alif mamdUdaT} and
%   \arb[trans]{sukUn} depending on the modes which are selected,
%   either |voc|, |fullvoc| or |trans|. Such refinements can be
%   discarded with \cs{SetArbEasy}, either globally in the preamble or
%   at any point of the document. Note that \cs{SetArbEasy} keeps the
%   \arb[trans]{sukUn} that is generated, while the starred version
%   \cs{SetArbEasy*} takes it away. Default complex rules can be set
%   back at any point of the document with \cs{SetArbDflt}.
% \begin{macro}{\SetArbDflt*}
%   \changes{v1.6}{2016/12/17}{This starred version applies the
%   assimilation rules in addition to what \cs{SetArbDflt} already
%   does.} As of v1.6, \package{arabluatex} does not applies any more
%   the assimilation rules that are laid on \vref{ref:assimilation}; a
%   new starred version \cs{SetArbDflt*} is now available to the user
%   should he wish to apply them.
%    \begin{macrocode}
\def\al@arb@rules{dflt}
\NewDocumentCommand{\SetArbEasy}{s}{%
  \IfBooleanTF{#1}
  {\def\al@arb@rules{easynosukun}}
  {\def\al@arb@rules{easy}}}
\NewDocumentCommand{\SetArbDflt}{s}{%
  \IfBooleanTF{#1}
  {\def\al@arb@rules{idgham}}
  {\def\al@arb@rules{dflt}}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\SetTranslitFont}
%   \changes{v1.4}{2016/07/05}{For selecting a specific font for
%   transliterated texts} By default, the font that is used for
%   transliterated text is the main font of the document. Any other
%   font may also be selected with the font-selecting commands of the
%   \package{fontspec} package.
%    \begin{macrocode}
\def\al@trans@font{\rmfamily}%
\NewDocumentCommand{\SetTranslitFont}{m}{\def\al@trans@font{#1}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\SetTranslitStyle} By default any transliterated
%   Arabic text is printed in italics. This can be changed either
%   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 transliteration 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}{\arbup}
% \changes{v1.3}{2016/05/28}{\arb[trans]{'i`rAb} is now written as
% superscript text in \texttt{dmg} mode by default.}
% \begin{macro}{\NoArbUp}
% \begin{macro}{\ArbUpDflt}
% \begin{macro}{\SetArbUp}
%   By default, \cs{arbup} is set to \cs{textsuperscript}. This is how
%   the \arb[trans]{tanwIn} that takes place at the end of a word
%   should be displayed in |dmg| mode. \cs{NoArbUp} may be used
%   either in the preamble or at any point of the document in case one
%   wishes to have the \arb[trans]{tanwIn} on the line. The default
%   rule can be set back with \cs{ArbUpDflt} at any point of the
%   document. Finally \cs{SetArbUp} may be used to customize the way
%   \arb[trans]{tanwIn} is displayed: this command takes the
%   formatting directives as argument, like so:
%   \cs{SetArbUp}\marg{code}.
%    \begin{macrocode}
\NewDocumentCommand{\al@arbup@dflt}{m}{\textsuperscript{\thinspace#1}}%
\NewDocumentCommand{\al@arbup}{m}{\al@arbup@dflt{#1}}
\NewDocumentCommand{\arbup}{m}{\al@arbup{#1}}
\NewDocumentCommand{\ArbUpDflt}{}{\let\al@arbup=\al@arbup@dflt}
\NewDocumentCommand{\NoArbUp}{}{\RenewDocumentCommand{\al@arbup}{m}{##1}}
\NewDocumentCommand{\SetArbUp}{m}{\RenewDocumentCommand{\al@arbup}{m}{#1}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \begin{macro}{\cap} Proper Arabic names or book titles should be
% passed to the \cs{cap} command 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. It is used internally by several Lua
%   functions, but available to the user should he wish to insert
%   |utf8| Arabic text in his document.
% \begin{macro}{\txtrans} \cs{txtrans} is used internally by several
% Lua functions to insert transliterated Arabic text. Therefore, it is
% not documented.
%    \begin{macrocode}
\DeclareDocumentCommand{\txarb}{+m}{\bgroup\textdir
  TRT\arabicfont#1\egroup}
\DeclareDocumentCommand{\txtrans}{+m}{\bgroup\textdir
  TLT\al@trans@font#1\egroup}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \begin{environment}{txarab}
%   \changes{v1.5}{2016/11/14}{New \texttt{txarab} environment for
%   typesetting running paragraphs in unicode Arabic} The |txarab|
%   environment does for paragraphs the same as \cs{txarb} does for
%   short insertions of |utf8| Arabic text.
%    \begin{macrocode}
\NewDocumentEnvironment{txarab}{}{%
  \par%
  \booltrue{al@rlmode}%
  \pardir TRT\textdir TRT\arabicfont}{\par}
%    \end{macrocode}
% \end{environment}
% \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},
    \luastringO{\al@arb@rules}, \luastringO{\al@input@scheme}))}\egroup%
  \else%
  \ifx\@tempa\al@mode@fullvoc%
  \bgroup\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processfullvoc(\luastringN{#2},
    \luastringO{\al@arb@rules}, \luastringO{\al@input@scheme}))}\egroup%
  \else%
  \ifx\@tempa\al@mode@novoc%
  \bgroup\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processnovoc(\luastringN{#2},
    \luastringO{\al@arb@rules}, \luastringO{\al@input@scheme}))}\egroup%
  \else%
  \ifx\@tempa\al@mode@trans%
  \bgroup\textdir TLT\al@trans@style%
  \luadirect{tex.sprint(processtrans(\luastringN{#2},
    \luastringO{\al@trans@convention},
    \luastringO{\al@arb@rules},
    \luastringO{\al@input@scheme}))}\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%
  \booltrue{al@rlmode}%
  \bgroup\pardir TRT\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processvoc(\luastringO{\BODY},
    \luastringO{\al@arb@rules}, \luastringO{\al@input@scheme}))}\egroup%
  \else%
  \ifx\@tempa\al@mode@fullvoc%
  \booltrue{al@rlmode}%
  \bgroup\pardir TRT\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processfullvoc(\luastringO{\BODY},
    \luastringO{\al@arb@rules}, \luastringO{\al@input@scheme}))}\egroup%
  \else%
  \ifx\@tempa\al@mode@novoc%
  \booltrue{al@rlmode}%
  \bgroup\pardir TRT\textdir TRT\arabicfont%
  \luadirect{tex.sprint(processnovoc(\luastringO{\BODY},
    \luastringO{\al@arb@rules}, \luastringO{\al@input@scheme}))}\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},
    \luastringO{\al@arb@rules},
    \luastringO{\al@input@scheme}))}\egroup%
  \else \fi\fi\fi\fi}[\par]
%    \end{macrocode}
% \end{environment}
% \begin{environment}{arabverse}
%   \changes{v1.6}{2016/12/17}{New environment \texttt{arabverse} for
%   typesetting Arabic poetry} The |arabverse| environment may receive
%   different options: |mode|, |width|, |gutter|, |metre|, |utf|
%   and |delim|; all of them are defined here just before the
%   |arabverse| environment:
%    \begin{macrocode}
\newlength{\al@bayt@width}
\newlength{\al@gutter@width}
\setlength{\al@bayt@width}{.3\textwidth}
\setlength{\al@gutter@width}{.15\al@bayt@width}
\define@key[al]{verse}{width}{\setlength{\al@bayt@width}{#1}}
\define@key[al]{verse}{gutter}{\setlength{\al@gutter@width}{#1}}
\define@key[al]{verse}{metre}{\arb{#1}}
\define@boolkey[al]{verse}{utf}[true]{}
\define@boolkey[al]{verse}{delim}[true]{}
\define@choicekey[al]{verse}{mode}{fullvoc, voc, novoc,
  trans}{\def\al@mode{#1}}
\presetkeys[al]{verse}{metre=\LR{\vskip -\baselineskip}, utf=false,
  delim=false}{}
%    \end{macrocode}
% Then follows the environment itself:
%    \begin{macrocode}
\NewDocumentEnvironment{arabverse}{O{}}%
{\par\centering\noindent\bgroup\setkeys[al]{verse}[metre]{#1}%
  \ifx\al@mode\al@mode@trans%
  \ifal@verse@utf\setRL\else\setLR\fi%
  \else\setRL\fi}%
{\hfill\setkeys[al]{verse}[width,gutter,utf,mode]{#1}\egroup}
%    \end{macrocode}
% \begin{macro}{\bayt}
%   \changes{v1.6}{2016/12/17}{New macro \cs{bayt} for typesetting
%   each verse inside the \texttt{arabverse} environment} Each verse
%   consists of two hemistichs; therefore the \cs{bayt} command takes
%   two arguments, the first receives the \arb[trans]{.sadr} and the
%   second the \arb[trans]{`ajuz}. That two subsequent hemistichs
%   should be connected with one another is technically named
%   \arb[trans]{tadwIr}. In some of these cases, the hemistichs may be
%   connected by a prominent horizontal flexible stroke which is drawn
%   by the \cs{al@verse@stroke} command.
% \begin{macro}{\SetHemistichDelim}
%   \changes{v1.6}{2016/12/17}{New \cs{SetHemistichDelim} command for
%   changing the default delimiter between hemistichs} A hemistich
%   delimiter also may be defined. By default, it is set to the
%   \enquote*{star} character: |*|. The
%   \cs{SetHemistichDelim}\marg{delimiter} command may be used at any
%   point of the document to change this default setting.
% \end{macro}
%    \begin{macrocode}
\NewDocumentCommand{\arb@utf}{m}{%
  \ifal@verse@utf\txarb{#1}\else\arb{#1}\fi}
\def\al@hemistich@delim{*}
\NewDocumentCommand{\SetHemistichDelim}{m}{\def\al@hemistich@delim{#1}}
\def\al@verse@stroke{\leavevmode\xleaders\hbox{\arb{--}}\hfill\kern0pt}
\NewDocumentCommand{\bayt}{m o m}{%
  \ifdefined\savenotes\savenotes\else\fi%
  \edef\al@tatweel{--}%
  \adjustbox{width=\al@bayt@width, height=\Height}{\arb@utf{#1}}%
  \IfNoValueTF{#2}{%
    \ifal@verse@delim\makebox[\al@gutter@width][c]{\al@hemistich@delim}%
    \else%
    \hspace{\al@gutter@width}%
    \fi
  }{%
    \edef\@tempa{#2}%
    \ifx\@tempa\al@tatweel%
    \ifx\al@mode\al@mode@trans%
    \hspace{\al@gutter@width}%
    \else%
    \makebox[\al@gutter@width][s]{\al@verse@stroke}%
    \fi%
    \else%
    \ifx\al@mode\al@mode@trans%
    \adjustbox{width=\al@gutter@width, height=\Height}{\arb@utf{#2}}%
    \else%
    \makebox[\al@gutter@width][s]{\arb@utf{#2}}%
    \fi\fi}%
  \adjustbox{width=\al@bayt@width, height=\Height}{\arb@utf{#3}}%
  \ifdefined\spewnotes\spewnotes\else\fi%
}
%    \end{macrocode}
%   
% \end{macro} 
% \end{environment}
% \begin{macro}{\abjad} \cs{abjad}\marg{number} expresses its argument
%   in Arabic letters in accordance with the \arb[trans]{'abjad}
%   arrangement of the alphabet. \meta{number} must be between 1 and
%   1999. It is now coded in Lua so that \package{polyglossia} is no
%   longer needed. See |arabluatex.lua| for more information.
%   \changes{v1.1}{2016/04/26}{New and more flexible \protect\cs{abjad}
%   command.}
%    \begin{macrocode}
\AtBeginDocument{%
  \ifdefined\abjad%
  \RenewDocumentCommand{\abjad}{m}%
  {\luadirect{tex.sprint(abjadify(#1))}}%
  \else%
  \NewDocumentCommand{\abjad}{m}%
  {\luadirect{tex.sprint(abjadify(#1))}}
\fi}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\abraces}
%   \cs{abraces}\marg{Arabic text} puts its argument between
%   braces. This macro is written in Lua and is dependent on the
%   current value of |tex.textdir|.
%   \changes{v1.4.3}{2016/09/14}{New \cs{abraces} command which
%   expresses its argument between braces.}
%    \begin{macrocode}
\NewDocumentCommand{\abraces}{+m}{%
  \luadirect{tex.sprint(abraces(\luastringN{#1}))}}
%    \end{macrocode}
% \end{macro}
% \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.
%
% \iffalse
%</package>
% \fi
%
% \subsection*{Patches}
% \label{sec:patches}
%
% \iffalse
%<*patch>
% \fi
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{arabluatex-patch}%
[2016/11/14 v1.0 patches for arabluatex]
%    \end{macrocode}
% I have put in a separate |.sty| file external lines of code that
% I had to patch for a good reason. I hate doing this, and hopefully,
% most of these lines will disappear as soon as they are not required
% anymore.
%
% The following is taken from |latex.ltx|. I had to make this patch
% for I could not find a way to process the list environments in
% right-to-left mode. The \LuaTeX\ primitives \cs{bodydir} and
% \cs{pagedir} will eventually allow us to get rid of this:
%    \begin{macrocode}
\def\list#1#2{%
  \ifnum \@listdepth >5\relax
    \@toodeep
  \else
    \global\advance\@listdepth\@ne
  \fi
  \rightmargin\z@
  \listparindent\z@
  \itemindent\z@
  \csname @list\romannumeral\the\@listdepth\endcsname
  \def\@itemlabel{#1}%
  \let\makelabel\@mklab
  \@nmbrlistfalse
  #2\relax
  \@trivlist
  \parskip\parsep
  \parindent\listparindent
  \advance\linewidth -\rightmargin
  \advance\linewidth -\leftmargin
%    \end{macrocode}
% patch begins:
%    \begin{macrocode}
  \ifbool{al@rlmode}{\advance\@totalleftmargin \rightmargin}%
  {\advance\@totalleftmargin \leftmargin}
%    \end{macrocode}
% patch ends.
%    \begin{macrocode}
  \parshape \@ne \@totalleftmargin \linewidth
  \ignorespaces}
\def\@item[#1]{%
  \if@noparitem
    \@donoparitem
  \else
    \if@inlabel
      \indent \par
    \fi
    \ifhmode
      \unskip\unskip \par
    \fi
    \if@newlist
      \if@nobreak
        \@nbitem
      \else
        \addpenalty\@beginparpenalty
        \addvspace\@topsep
        \addvspace{-\parskip}%
      \fi
    \else
      \addpenalty\@itempenalty
      \addvspace\itemsep
    \fi
    \global\@inlabeltrue
  \fi
  \everypar{%
    \@minipagefalse
    \global\@newlistfalse
    \if@inlabel
      \global\@inlabelfalse
      {\setbox\z@\lastbox
       \ifvoid\z@
         \kern-\itemindent
       \fi}%
      \box\@labels
      \penalty\z@
    \fi
    \if@nobreak
      \@nobreakfalse
      \clubpenalty \@M
    \else
      \clubpenalty \@clubpenalty
      \everypar{}%
    \fi}%
  \if@noitemarg
    \@noitemargfalse
    \if@nmbrlist
      \refstepcounter\@listctr
    \fi
  \fi
%    \end{macrocode}
% patch begins:
%    \begin{macrocode}
  \ifbool{al@rlmode}{\sRLbox\@tempboxa{\makelabel{#1}}}{%
  \sbox\@tempboxa{\makelabel{#1}}}%
  \ifbool{al@rlmode}{\global\setbox\@labels\hbox dir TRT}%
  {\global\setbox\@labels\hbox}{%
%    \end{macrocode}
% patch ends.
%    \begin{macrocode}
    \unhbox\@labels
    \hskip \itemindent
    \hskip -\labelwidth
    \hskip -\labelsep
    \ifdim \wd\@tempboxa >\labelwidth
      \box\@tempboxa
    \else
      \hbox to\labelwidth {\unhbox\@tempboxa}%
    \fi
    \hskip \labelsep}%
  \ignorespaces}
%    \end{macrocode}
% This is adapted from Vafa Khalighi's \package{bidi} package. Thanks
% to him.
%    \begin{macrocode}
\long\def\sRLbox#1#2{\setbox#1\hbox dir TRT{%
  \color@setgroup#2\color@endgroup}}
%    \end{macrocode}
%
% \iffalse
%</patch>
% \fi
%
% \Finale
\endinput