summaryrefslogtreecommitdiff
path: root/macros/luatex/latex/arabluatex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/luatex/latex/arabluatex
Initial commit
Diffstat (limited to 'macros/luatex/latex/arabluatex')
-rw-r--r--macros/luatex/latex/arabluatex/README.md146
-rw-r--r--macros/luatex/latex/arabluatex/arabluatex.dtx5181
-rw-r--r--macros/luatex/latex/arabluatex/arabluatex.ins109
-rw-r--r--macros/luatex/latex/arabluatex/arabluatex.lua1187
-rw-r--r--macros/luatex/latex/arabluatex/arabluatex.pdfbin0 -> 685259 bytes
-rw-r--r--macros/luatex/latex/arabluatex/arabluatex_fullvoc.lua1015
-rw-r--r--macros/luatex/latex/arabluatex/arabluatex_novoc.lua166
-rw-r--r--macros/luatex/latex/arabluatex/arabluatex_trans.lua1018
-rw-r--r--macros/luatex/latex/arabluatex/arabluatex_voc.lua903
-rw-r--r--macros/luatex/latex/arabluatex/samples/al-Jahiz.pdfbin0 -> 114234 bytes
-rw-r--r--macros/luatex/latex/arabluatex/samples/al-Jahiz.tex178
-rw-r--r--macros/luatex/latex/arabluatex/samples/exporting.pdfbin0 -> 59687 bytes
-rw-r--r--macros/luatex/latex/arabluatex/samples/exporting.tex206
-rw-r--r--macros/luatex/latex/arabluatex/samples/template-01.pdfbin0 -> 65289 bytes
-rw-r--r--macros/luatex/latex/arabluatex/samples/template-01.tex109
15 files changed, 10218 insertions, 0 deletions
diff --git a/macros/luatex/latex/arabluatex/README.md b/macros/luatex/latex/arabluatex/README.md
new file mode 100644
index 0000000000..c9dec25920
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/README.md
@@ -0,0 +1,146 @@
+---
+author:
+- Robert Alessi
+title: 'The arabluatex package – README file'
+---
+
+Overview
+========
+
+This package provides for [LuaLaTeX](http://luatex.org) an
+[ArabTeX](http://ctan.org/pkg/arabtex)-like interface to generate Arabic
+writing from an <span style="font-variant:small-caps;">ascii</span>
+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. arabluatex is
+able to process any ArabTeX input notation. Its output can be set in the
+same modes of vocalization as ArabTeX, 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 `.tex` source files, in addition to printed books, `TEI xml`
+compliant critical editions and/or lexicons that can be searched,
+analyzed and correlated in various ways.
+
+License and disclamer
+=====================
+
+ArabLuaTeX – Processing ArabTeX notation under LuaLaTeX
+
+Copyright ⓒ 2016–2019 Robert Alessi
+
+Please send error reports and suggestions for improvements to Robert
+Alessi:
+
+- email: <alessi@robertalessi.net>
+
+- website: <http://www.robertalessi.net/arabluatex>
+
+- comments, feature requests, bug reports:
+ <https://gitlab.com/ralessi/arabluatex/issues>
+
+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 &lt;http://www.gnu.org/licenses/&gt;.
+
+This release of arabluatex consists of the following source files:
+
+- `arabluatex.ins`
+
+- `arabluatex.dtx`
+
+- `arabluatex.lua`
+
+- `arabluatex_voc.lua`
+
+- `arabluatex_fullvoc.lua`
+
+- `arabluatex_novoc.lua`
+
+- `arabluatex_trans.lua`
+
+License applicable to the documentation
+---------------------------------------
+
+Copyright ⓒ 2016–2019 Robert Alessi
+
+The documentation file `arabluatex.pdf` that is generated from the
+`arabluatex.dtx` source is licensed under the Creative Commons
+Attribution-ShareAlike 4.0 International License. To view a copy of this
+license, visit <http://creativecommons.org/licenses/by-sa/4.0/> or send
+a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+
+Installation
+============
+
+1. Run `'lualatex arabluatex.ins'` to produce the `arabluatex.sty`
+ file;
+
+2. To finish the installation you have to move the following files into
+ a directory where LaTeX can find them. See the FAQ on `texfaq.org`
+ at <https://texfaq.org/FAQ-inst-wlcf> for more on this:
+
+ - `arabluatex.sty`
+
+ - `arabluatex-patch.sty`
+
+ - `arabluatex.lua`
+
+ - `arabluatex_voc.lua`
+
+ - `arabluatex_fullvoc.lua`
+
+ - `arabluatex_novoc.lua`
+
+ - `arabluatex_trans.lua`
+
+3. Additionally, those who use emacs with AUCTeX may copy
+ `arabluatex.el` to their `~/.emacs.d/auctex/auto` local directory.
+ This will enable the appropriate hooks for ArabLuaTeX in AUCTeX.
+
+Development, Git Repository
+===========================
+
+Browse the code
+---------------
+
+You can browse ArabLuaTeX repository on the web:
+<http://git.robertalessi.net/arabluatex>
+
+From this page, you can download all the releases of ArabLuaTeX. For
+instructions on how to install ArabLuaTeX, please see above.
+
+Comments, Feature requests, Bug Reports
+---------------------------------------
+
+<https://gitlab.com/ralessi/arabluatex/issues>
+
+Download the repository
+-----------------------
+
+ArabLuaTeX development is facilitated by git, a distributed version
+control system. You will need to install git (most GNU/Linux
+distributions package it in their repositories).
+
+Use this command to download the repository
+
+ git clone http://git.robertalessi.net/arabluatex
+
+A new directory named arabluatex will have been created, containing
+ArabLuaTeX.
+
+Git hosting
+-----------
+
+Make an account on <https://gitlab.com> and navigate (while logged in)
+to <https://gitlab.com/ralessi/arabluatex>. Click *Fork* and you will
+have in your account your own repository of `arabluatex` where you will
+be able to make whatever changes you like to.
diff --git a/macros/luatex/latex/arabluatex/arabluatex.dtx b/macros/luatex/latex/arabluatex/arabluatex.dtx
new file mode 100644
index 0000000000..001f962c70
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/arabluatex.dtx
@@ -0,0 +1,5181 @@
+% \iffalse meta-comment
+% ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
+% Copyright (C) 2016--2019 Robert Alesssi
+%
+% 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>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{arabluatex}
+%<*package>
+ [2019/03/24 v1.17 An ArabTeX-like interface for LuaLaTeX]
+%</package>
+%
+%<*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--2019 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 = {2017-12-13},
+ 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}
+}
+
+@Manual{din31635,
+ label = {{DIN 31~635}},
+ title = {Information and Documentation - Romanization of the
+ Arabic Alphabet for Arabic, Ottoman-Turkish,
+ Persian, Kurdish, Urdu and Pushto},
+ date = {2011-07},
+ url = {http://www.din.de}
+}
+
+@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 vorgelegt von der
+ Transkriptionkommission der Deutschen
+ Morgenländischen Gesellschaft},
+ editor = {van Ronkel, Ph. S. and Spies, Otto},
+ editortype = {collaborator},
+ publisher = {Deutsche Morgenländische 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}
+\usepackage{fontspec}
+\usepackage{microtype}
+\defaultfontfeatures{RawFeature={+liga}}
+\setmainfont{Old Standard}[SmallCapsFont={Latin Modern Roman Caps},
+ RawFeature={+mark;+ccmp;+ss05;+ss06}]
+\usepackage{newunicodechar}
+\newunicodechar{ǧ}{ǧ} % Old Standard does not include ǧ/Ǧ
+\newunicodechar{Ǧ}{Ǧ} %
+\usepackage{metalogox}
+\usepackage{arabluatex}[2019/03/24]
+\SetArbUp{\textsuperscript{\thinspace#1}} % Old Standard needs this
+\usepackage[nopar]{quran}
+\usepackage[noindex]{nameauth}
+\usepackage{varioref}
+\usepackage{hyperxmp}
+\PassOptionsToPackage{pdfa}{hyperref}
+\usepackage{hypdoc}
+\usepackage{uri}
+\usepackage{bookmark}
+\usepackage{authblk}
+\hypersetup{unicode=true, colorlinks, allcolors=blue,
+ linktocpage=true, pdfauthor={Robert Alessi}, pdftitle={The
+ arabluatex package}, pdfcontactemail={alessi@robertalessi.net},
+ pdfcontacturl={http://www.robertalessi.net/arabluatex},
+ pdfcopyright={Copyright (C) 2016--2019 Robert Alessi
+ <alessi@robertalessi.net>. This document is licensed under the
+ Creative Commons Attribution-ShareAlike 4.0 International
+ License. To view a copy of this license, visit
+ http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to
+ Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.},
+ pdflicenseurl={https://creativecommons.org/licenses/by-sa/4.0/legalcode},
+ pdfmetalang={en-US}, pdftype={Text}, pdfkeywords={Arabic language,
+ arabtex, luatex}}
+\usepackage[scale=1.5]{ccicons}
+\usepackage[lot]{multitoc}
+\usepackage{enumitem}
+\setlist{nosep}
+\setlist[itemize]{label=\textendash}
+\setlist[enumerate,1]{label=(\alph*)}
+\setlist[enumerate,2]{label=\roman*.}
+\newlist{enumabjad}{enumerate}{10}
+\setlist[enumabjad]{label={\abjad{\arabic*}}}
+\usepackage{multicol}
+\usepackage{cleveref}
+\crefname{footnote}{note}{notes}
+\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{needspace}
+\usepackage{addlines}
+\usepackage{relsize}
+\usepackage{tikz}
+\usepackage[breakable, skins, xparse, minted]{tcolorbox}
+\tcbset{colback=white, boxrule=.15mm, colframe=red!50!white,
+ breakable}
+\newtcbox{\arabluabox}{boxrule=.3mm, left=0mm, right=0mm, top=0mm,
+ bottom=0mm}
+\newtcblisting{example}{minted options={linenos, numbersep=0mm,
+ fontsize=\smaller}}
+\newtcblisting{code}{minted options={linenos, numbersep=0mm,
+ fontsize=\smaller}, listing
+ only}
+\newcommand{\package}[1]{\textsf{#1}\index{#1=#1 (package)}}
+\usepackage[contents]{colordoc}
+\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}
+\usepackage{etoc}
+\etocsettocdepth{paragraph}
+\newcommand{\altableofcontents}{%
+ \begingroup
+ \etocsetstyle{section}{}{}
+ {\etocsavedsectiontocline{%
+ \numberline{\etocnumber}\etocname}{\etocpage}}{}
+ \etocsetstyle{subsection}{}{}
+ {\etocsavedsubsectiontocline{%
+ \numberline{\etocnumber}\etocname}{\etocpage}}{}%
+ \etocsetstyle{subsubsection}{}{}
+ {\etocsavedsubsubsectiontocline{%
+ \numberline{\etocnumber}\etocname}{\etocpage}}{}%
+ \etocsetstyle{paragraph}{}{\leftskip2cm\rightskip 2.2em \parfillskip
+ 0pt plus 1fil\relax \nobreak}
+ {\noindent\etocname{} \etocpage{} }{\par}%
+ \etocmulticolstyle[2]{\section*{Contents}}
+ \pdfbookmark[1]{Contents}{toc}
+ \tableofcontents
+ \endgroup}
+\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{919}
+%
+% \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 \~}
+%
+% \makeatletter
+% \let\org@changes@\changes@
+% \def\my@changes v#1.#2.#3\@nil{%
+% \org@changes@{v#1.\six@digits{#2}.#3=v#1.#2.#3}%
+% }%
+% \newcommand*{\six@digits}[1]{%
+% \ifnum#1<100000 0\fi
+% \ifnum#1<10000 0\fi
+% \ifnum#1<1000 0\fi
+% \ifnum#1<100 0\fi
+% \two@digits{#1}%
+% }%
+% \renewcommand*{\changes@}[1]{%
+% \my@changes#1.\@nil
+% }%
+% \makeatother
+%
+% \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}
+%
+% \newcommand*{\NEWfeature}[1]{%
+% \hskip 1sp \marginpar{\small\sffamily\raggedright
+% New feature\\#1}}
+%
+% \title{\tcbox[colframe=black, enhanced, tikznode, drop lifted
+% shadow, colback=white, boxrule=.25mm]%
+% {The \textsf{arabluatex} package\\
+% \fileversion\ -- \filedate}}
+%
+% \author{Robert Alessi \\
+% \href{mailto:alessi@robertalessi.net?Subject=arabluatex package}%
+% {\texttt{alessi@robertalessi.net}}}
+% \date{}
+%
+% \maketitle
+% \footnotesize
+% \altableofcontents
+% \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}
+% \addcontentsline{toc}{section}{License and disclamer}
+% \subsection*{License applicable to the software}
+% \label{sec:license-software}
+%
+% \package{arabluatex} --- Processing Arab\TeX\ notation under Lua\LaTeX.\\
+% Copyright \textcopyright\ 2016--2019 Robert Alessi
+%
+% Please send error reports and suggestions for improvements to Robert
+% Alessi:
+% \begin{itemize}
+% \item email: \mailto[arabluatex package]{alessi@roberalessi.net}
+% \item website: \url{http://www.robertalessi.net/arabluatex}
+% \item development: \url{http://git.robertalessi.net/arabluatex}
+% \item comments, feature requests, bug reports:
+% \url{https://gitlab.com/ralessi/arabluatex/issues}
+% \end{itemize}
+%
+% \marginpar{\texttt{gpl3+}}
+% 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{itemize}
+% \item |arabluatex.ins|
+% \item |arabluatex.dtx|
+% \item |arabluatex.lua|
+% \item |arabluatex_voc.lua|
+% \item |arabluatex_fullvoc.lua|
+% \item |arabluatex_novoc.lua|
+% \item |arabluatex_trans.lua|
+% \item |arabluatex.el|
+% \end{itemize}
+%
+% \subsection*{License applicable to this document}
+% \label{sec:documentation-license}
+% Copyright \textcopyright\ 2016--2019 Robert Alessi
+%
+% \ccbysa\marginpar{\texttt{CC BY-SA 4.0}}
+% This document is licensed under the Creative Commons
+% Attribution-ShareAlike 4.0 International License. To view a copy of
+% this license, visit
+% \url{http://creativecommons.org/licenses/by-sa/4.0/} or send a
+% letter to Creative Commons, PO Box 1866, Mountain View, CA 94042,
+% USA.
+%
+% \section{Introduction}
+% In comparison to Prof. Lagally's outstanding Arab\TeX,\footnote{See
+% \url{http://ctan.org/pkg/arabtex}} Arab{\LuaTeX} is at present
+% nothing more than a modest piece of software. Hopefully---if I may
+% say so---it will eventually provide all of its valuable qualities to
+% the {\LuaLaTeX} users.
+%
+% \package{arabtex} dates back to 1992. As far as I know, it was then
+% the first and only way to typeset Arabic texts with \TeX\ and
+% \LaTeX. To achieve that, \package{arabtex} provided---and still
+% does---an Arabic font in \arb[trans]{\uc{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}}
+% \package{arabluatex} is loaded the usual way:\\
+% \tcboxverb{\usepackage{arabluatex}}\\
+% The only requirement of \package{arabluatex} is {\LuaLaTeX};
+% it will complain if the document is compiled with another
+% engine. That aside, \package{arabluatex} does not load packages such
+% as \package{polyglossia}. Although it can work with
+% \package{polyglossia}, it does not require it.
+%
+% \paragraph{Font setup}
+% Any Arabic font can be defined to be used with
+% \package{arabluatex}. For example, assuming that \package{fontspec}
+% is loaded, this line may be inserted in the 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 to be used.
+%
+% 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:---\\
+% \tcboxverb{\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 {\renewfontfamily\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[6]{pkg:amiri}.}\\
+% \tcboxverb{\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 five global options, the
+% first four of which are mutually exclusive and may be overriden at
+% any point of the document (see below \vref{sec:local-options}):
+%
+% \DescribeOption{voc}\hfill\tcboxverb{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, three standards are supported (see below
+% \vref{sec:transliteration} for more details):
+% \begin{description}
+% \item[dmg] \emph{Deutsche Morgenländische Gesellschaft}, which is
+% selected by default;
+% \item[loc] \emph{Library of Congress};
+% \item[arabica] \emph{Arabica}.
+% \end{description}
+% More standards will be included in future releases of
+% \package{arabluatex}.
+%
+% \label{ref:export-global-opt}
+% \DescribeOption{export} |export|$=$|true|\verb+|+|false|
+% \hfill\tcboxverb{Default: false}\\ \label{export-mode}
+% \NEWfeature{v.1.13} This option acts as a named argument and does
+% not need a value as it defaults to |true| if it is used. It enables
+% \package{arabluatex} to produce a duplicate of the original |.tex|
+% source file in which all \textsc{ascii} strings are replaced with
+% Unicode equivalents. See below \vref{sec:arabtex2utf} for more
+% information.
+%
+% \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{itemize}
+% \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.
+% \item In such words as \arb{^say'aN}, \arb{.zim'aN} and the like,
+% the \arb[trans]{hamzaT} alone is not written over the letter
+% \arb[trans]{yA'} with no diacritical points below as in
+% \arb{^sayy"'aN}, \arb{.zimy"'aN}, but over a horizontal stroke
+% placed in the continuation of the preceding letter. %
+% \iffalse
+%<*example>
+% \fi
+\begin{tcblisting}{text only}
+ Please note that only few Arabic fonts provide such contrivances. In
+ case this feature is not supported by some Arabic font, it is
+ advisable to use \cs{SetArbEasy}.
+\end{tcblisting}
+% \iffalse
+%</example>
+% \fi
+% \end{itemize}
+%
+% \DescribeMacro{\SetArbEasy} \NEWfeature{v1.4.4} Such refinements as
+% \enquote*{classic} \arb[trans]{maddaT} may be discarded by the
+% \cs{SetArbEasy} command, either globally in the preamble or locally
+% at any point of the document. The difference between \cs{SetArbEasy}
+% and its \enquote*{starred} version
+% \DescribeMacro{\SetArbEasy*}\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 \DescribeMacro{\SetArbDflt}\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{enumerate}
+% \item \cs{SetArbDflt}:
+% \begin{enumerate}
+% \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{enumerate}
+% \item \cs{SetArbDflt*}:
+% \begin{enumerate}\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{enumerate}
+% \item \cs{SetArbEasy}:
+% \begin{enumerate}\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{enumerate}
+% \item \cs{SetArbEasy*}:
+% \begin{enumerate}\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{enumerate}
+% \end{enumerate}
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{tcblisting}{text only}
+ Please note that this document is typeset with \cs{SetArbDflt}
+ throughout.
+\end{tcblisting}
+% \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{example}
+ 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{example}
+% \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{example}
+ \begin{enumerate}[label=\Roman*., start=16]
+ \item \indent\arb{fawA`ilu}*.
+ \begin{enumerate}[label=\arabic*.]
+ \item \indent\arb{fA`aluN}; as \arb{_hAtamuN} \emph{a
+ signet-ring}, ...
+ \end{enumerate}
+ \end{enumerate}
+\end{example}
+% \iffalse
+%</example>
+% \fi
+%
+% \DescribeEnv{arab} Running paragraphs of Arabic text should rather
+% be placed inside an \emph{Arabic environment}
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ \begin{arab}
+ [...]
+ \end{arab}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% like so:---\label{ref:juha-code}
+% \setquotestyle{arabic}
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \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{example}
+% \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 argument, like
+% so:---
+% \begin{itemize}
+% \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{itemize}
+%
+% 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.
+%
+% \addlines[2]
+% \newcommand{\dmg}[1]{%
+% \SetTranslitConvention{dmg}%
+% \arb[trans]{#1}}
+% \newcommand{\loc}[1]{%
+% \SetTranslitConvention{loc}%
+% \arb[trans]{#1}\SetTranslitConvention{dmg}}
+% \newcommand{\brill}[1]{%
+% \SetTranslitConvention{arabica}%
+% \arb[trans]{#1}\SetTranslitConvention{dmg}}
+% \begin{longtable}{lllll}
+% \bottomrule
+% \caption*{\Cref*{tab:arabtex-consonants}: Standard Arab\TeX\
+% (consonants)}
+% \endfoot
+% \captionlistentry{Arab\TeX\ consonants}\\[-1em]
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration\footnotemark}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endfirsthead
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endhead \footnotetext{See below \vref{sec:transliteration}.}
+% \label{tab:arabtex-consonants}
+% \arb[voc]{'i 'a 'u}\footnote{See below, \emph{Rem{.} a.} For
+% \arb[trans]{'alif} as a consonant, see \textcite[i. 16
+% D]{Wright}. The \arb[trans]{hamzaT} itself is encoded \texttt{<'>}
+% and may be followed by either \meta{u, a} or \meta{i}. See below
+% \vref{ref:hamza}.} & \dmg{'u 'a 'i} &
+% \loc{|'u, |'a, |'i} & \brill{|'u, |'a, |'i} & |'u| or |'a| or |'i| \\
+% \arb[novoc]{b} & \dmg{b} & \loc{b} & \brill{b} & |b| \\
+% \arb[novoc]{t} & \dmg{t} & \loc{t} & \brill{t} & |t| \\
+% \arb[novoc]{_t} & \dmg{_t} & \loc{_t} & \brill{_t} & |_t| \\
+% \arb[novoc]{j} & \dmg{j} & \loc{j} & \brill{j} & |^g| or |j| \\
+% \arb[novoc]{.h} & \dmg{.h} & \loc{.h} & \brill{.h} & |.h| \\
+% \arb[novoc]{x} & \dmg{x} & \loc{x} & \brill{x} & |_h| or |x|\\
+% \arb[novoc]{d} & \dmg{d} & \loc{d} & \brill{d} & |d| \\
+% \arb[novoc]{_d} & \dmg{_d} & \loc{_d} & \brill{_d} & |_d| \\
+% \arb[novoc]{r} & \dmg{r} & \loc{r} & \brill{r} & |r| \\
+% \arb[novoc]{z} & \dmg{z} & \loc{z} & \brill{z} & |z| \\
+% \arb[novoc]{s} & \dmg{s} & \loc{s} & \brill{s} & |s| \\
+% \arb[novoc]{^s} & \dmg{^s} & \loc{^s} & \brill{^s} & |^s| \\
+% \arb[novoc]{.s} & \dmg{.s} & \loc{.s} & \brill{.s} & |.s| \\
+% \arb[novoc]{.d} & \dmg{.d} & \loc{.d} & \brill{.d} & |.d| \\
+% \arb[novoc]{.t} & \dmg{.t} & \loc{.t} & \brill{.t} & |.t| \\
+% \arb[novoc]{.z} & \dmg{.z} & \loc{.z} & \brill{.z} & |.z| \\
+% \arb[novoc]{`} & \dmg{`} & \loc{`} & \brill{`} & |`| \\
+% \arb[novoc]{.g} & \dmg{.g} & \loc{.g} & \brill{.g} & |.g| \\
+% \arb[novoc]{f} & \dmg{f} & \loc{f} & \brill{f} & |f| \\
+% \arb[novoc]{q} & \dmg{q} & \loc{q} & \brill{q} & |q| \\
+% \arb[novoc]{k} & \dmg{k} & \loc{k} & \brill{k} & |k| \\
+% \arb[novoc]{l} & \dmg{l} & \loc{l} & \brill{l} & |l| \\
+% \arb[novoc]{m} & \dmg{m} & \loc{m} & \brill{m} & |m| \\
+% \arb[novoc]{n} & \dmg{n} & \loc{n} & \brill{n} & |n| \\
+% \arb[novoc]{h} & \dmg{h} & \loc{h} & \brill{h} & |h| \\
+% \arb[novoc]{w} & \dmg{w} & \loc{w} & \brill{w} & |w| \\
+% \arb[novoc]{y} & \dmg{y} & \loc{y} & \brill{y} & |y|\footnote{For
+% the letter \arb[novoc]{.y} with no diacritical points below, see
+% \emph{Rem{.} b.} below.} \\
+% \arb[novoc]{T} & \dmg{aT} & \loc{aT} & \brill{aT} & |T| \\
+% \end{longtable}
+% \begin{quoting}
+% \textsc{Rem.}~\emph{a.} Please note that in all cases of elision,
+% the \arb[trans]{'alifu 'l-wa.sli} is expressed only by the vowel
+% that accompanies the omitted \arb[trans]{hamzaT}: \meta{u, a, i}
+% as in |wa-inhazama| \arb[fullvoc]{wa-inhazama}
+% \arb[trans]{wa-inhazama}. For more details on the definite article
+% and the \arb[trans]{'alifu 'l-wa.sli} see
+% \vref{ref:definite-article}.
+%
+% That said, \arb{.A} as a consonant is actually the \emph{spiritus
+% lenis} of the Greeks and is distinguished by the
+% \arb[trans]{hamzaT} \arb[novoc]{(|"')} as it is shown in the above
+% table. However, the bare \arb[trans]{'alif} may also be encoded as
+% |.A| whether it be followed by a vowel or not, like so: |wa-.An|
+% \arb{wa-.An} \arb[trans]{wa-.An} (where the dot symbolizes the
+% absence of vowel), |wa-.Aan| \arb{wa-.Aan} \arb[trans]{wa-.Aan},
+% |wa-.Ain| \arb{wa-.Ain} \arb[trans]{wa-.Ain}.
+%
+% \textsc{Rem.}~\emph{b.} The letter \arb[novoc]{y} with two points
+% below, \arb{al-yA'u 'l-mu_tannATu min ta.hti-hA}, may also be
+% written without diacritical points as \arb[novoc]{Y}. When it is
+% used as a consonant, it is encoded |aY|, where |a| recalls the
+% \arb[trans]{fat.haT} placed above the preceding letter in
+% vocalized Arabic, like so: |qaY'uN| \arb{qaY'uN}
+% \arb[trans]{qaY'uN}, |^saY'uN| \arb{^saY'uN} \arb[trans]{^saY'uN},
+% |^saY'aN| \arb[trans]{^saY'aN} \arb{^saY'aN}.
+%
+% The same result may be achieved by encoding this letter as |.y|,
+% like so: |qa.y'uN| \arb{qa.y'uN} \arb[trans]{qa.y'uN}, |^sa.y'uN|
+% \arb{^sa.y'uN} \arb[trans]{^sa.y'uN}, |^sa.y'aN|
+% \arb[trans]{^sa.y'aN} \arb{^sa.y'aN}.
+% \end{quoting}
+%
+% \subsection{Additional characters}
+% \changes{v1.8.5}{2017/06/20}{Six additional Persian characters are
+% now available}
+% \NEWfeature{v1.8.5}\Cref{tab:arabtex-additional-characters} gives
+% the Arab\TeX\ equivalents for some additional Persian characters.
+%
+% \begin{longtable}{lllll}
+% \bottomrule
+% \caption*{\Cref*{tab:arabtex-additional-characters}: Standard
+% Arab\TeX\ (additional characters)}
+% \endfoot
+% \captionlistentry{Arab\TeX\ additional characters}\\[-1em]
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration\footnotemark}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica}\footnotemark
+% & \\ \midrule
+% \endfirsthead
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endhead
+% \addtocounter{footnote}{-1}
+% \footnotetext{See below \vref{sec:transliteration}.}
+% \stepcounter{footnote}
+% \footnotetext{The characters that are listed in this table are not
+% included in this standard. However, as \texttt{arabica} is based on
+% \texttt{dmg}, the \texttt{dmg} equivalents have been used here.}
+% \label{tab:arabtex-additional-characters}
+% \hskip-1em\arb[novoc]{p} & \dmg{p} & \loc{p} & \brill{p} & \verb|p| \\
+% \arb[novoc]{^c} & \dmg{^c} & \loc{^c} & \brill{^c} & \verb|^c| \\
+% \arb[novoc]{^z} & \dmg{^z} & \loc{^z} & \brill{^z} & \verb|^z| \\
+% \arb[novoc]{v}\footnote{\label{fn:not-in-dmg}This character is not found in
+% \textcite[2]{dmg}. It is taken from the \textcite{din31635} standard.} &
+% \dmg{v} & \loc{v} & \brill{v} & \verb|v| \\
+% \arb[novoc]{g} & \dmg{g} & \loc{g} & \brill{g} & \verb|g| \\
+% \arb[novoc]{^n}\footnote{See \cref{fn:not-in-dmg}.} & \dmg{^n} &
+% \loc{^n} & \brill{^n} & \verb|^n| \\
+% \end{longtable}
+% \begin{quoting}
+% \textsc{Rem.} The alveolar consonants \arb[novoc]{^c} and
+% \arb[novoc]{^z} are processed as solar letters by
+% \package{arabluatex}.
+% \end{quoting}
+%
+% \subsection{Vowels}
+% \subsubsection{Long vowels}
+% \Cref{tab:arabtex-long-vowels} gives the Arab\TeX\ equivalents for
+% the Arabic long vowels.
+%
+% \begin{longtable}{lllll}
+% \bottomrule
+% \caption*{\Cref*{tab:arabtex-long-vowels}: Standard Arab\TeX\ (long
+% vowels)}
+% \endfoot
+% \captionlistentry{Arab\TeX\ long vowels}\\[-1em]
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration\footnotemark}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endfirsthead
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endhead \footnotetext{See below \vref{sec:transliteration}.}
+% \label{tab:arabtex-long-vowels}
+% \arb[novoc]{A} & \dmg{A} & \loc{A} & \brill{A} & \verb|A| \\
+% \arb[novoc]{U} & \dmg{U} & \loc{U} & \brill{U} & \verb|U| \\
+% \arb[novoc]{I} & \dmg{I} & \loc{I} & \brill{I} &
+% \verb|I|\footnote{For the letter \arb[novoc]{I} with no diacritical
+% points, see \emph{Rem{.} c.} below.} \\
+% \arb[novoc]{_A}\footnote{$=$ \arb[trans]{al-'alif-u 'l-maq.sUraT-u}.}
+% & \dmg{_A} & \loc{_A} & \brill{_A} & \verb|_A| or \verb|Y| \\
+% \arb[novoc]{B_a} & \dmg{B_a} & \loc{B_a} & \brill{B_a} & \verb|_a| \\
+% \arb[novoc]{B_u} & \dmg{B_u} & \loc{B_u} & \brill{B_u} & \verb|_u| \\
+% \arb[novoc]{B_i} & \dmg{B_i} & \loc{B_i} & \brill{B_i} & \verb|_i| \\
+% \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]{\uc{.hu_dayfaT-u} bn-u 'l-\uc{yamAn_i}}, etc.
+%
+% \textsc{Rem.}~\emph{c.} The letter \arb[novoc]{y} with two points
+% below, \arb{al-yA'u 'l-mu_tannATu min ta.hti-hA}, may also be
+% written without diacritical points as \arb[novoc]{Y}. When it is
+% used as a long vowel, it is encoded |iY|, where |i| recalls the
+% \arb[trans]{kasraT} placed below the preceding letter in vocalized
+% Arabic, like so: |liY| \arb{liY} \arb[trans]{liY}, |yam^siY|
+% \arb{yam^siY} \arb[trans]{yam^siY}.
+% \end{quoting}
+%
+% \subsubsection{Short vowels}
+% \Cref{tab:arabtex-short-vowels} gives the Arab\TeX\ equivalents for
+% the Arabic short vowels.
+%
+% \begin{longtable}{lllll}
+% \bottomrule
+% \caption*{\Cref*{tab:arabtex-short-vowels}: Standard Arab\TeX\
+% (short vowels)}
+% \endfoot
+% \captionlistentry{Arab\TeX\ short vowels}\\[-1em]
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration\footnotemark}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endfirsthead
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endhead \footnotetext{See below \vref{sec:transliteration}.}
+% \label{tab:arabtex-short-vowels}
+% \arb[voc]{Ba} & \dmg{Ba} & \loc{Ba} & \brill{Ba} & \verb|a| \\
+% \arb[voc]{Bu} & \dmg{Bu} & \loc{Bu} & \brill{Bu} & \verb|u| \\
+% \arb[voc]{Bi} & \dmg{Bi} & \loc{Bi} & \brill{Bi} & \verb|i| \\
+% \arb[voc]{BaN} & \dmg{BaN} & \loc{BaN} & \brill{BaN} & \verb|aN| \\
+% \arb[voc]{BuN} & \dmg{BuN} & \loc{BuN} & \brill{BuN} & \verb|uN| \\
+% \arb[voc]{BiN} & \dmg{BiN} & \loc{BiN} & \brill{BiN} & \verb|iN| \\
+% \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{tcblisting}{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{tcblisting}
+% \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{itemize}
+% \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{itemize}
+%
+%\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]{\uc{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{\texorpdfstring{\arb[trans]{'alif maq.sUraT}}{ʾalif
+% maqṣūrah}} 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{\texorpdfstring{\arb[trans]{'alif} \emph{otiosum}}{ʾalif
+% 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{\texorpdfstring{\arb[trans]{'alif ma.h_dUfaT} and
+% defective \arb[trans]{U, I}}{ʾalif maḥḏūfah and defective ū, ī}}
+% 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]{\uc{.hunayn}-u
+% bn-u \uc{'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-\uc{`A.s_i}}.
+% \end{quote}
+%
+% \paragraph{\texorpdfstring{Silent
+% \arb[novoc]{U}/\arb[novoc]{I}}{Silent ي/و}}
+% 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^s\-k_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{\texorpdfstring{\arb[trans]{\uc{`amruNU}}, and the silent
+% \arb[novoc]{U}}{ʿAmrun, and the silent و}} To that name a silent
+% \arb[novoc]{U} is added to distinguish it from
+% \arb[trans]{\uc{`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]{\uc{`amr-uU} bn-u
+% \uc{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]{\uc{mu.hammad-u} bn-u \uc{`amr-iU} bn-i
+% \uc{_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{\texorpdfstring{\arb[trans]{tanwIn}}{tanwīn}}
+% 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{\texorpdfstring{\arb[trans]{tA' marbU.taT}}{tāʾ marbūṭah}}
+% 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{\texorpdfstring{\arb[trans]{hamzaT}}{hamzah}}
+% \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}\footnote{For another way of encoding the
+% initial \arb[trans]{hamzaT} followed by a long vowel, see the
+% \arb[trans]{ta_hfIf-u 'l-hamzaT-i}\vpageref{ref:taxfif-hamzah}.}.
+%
+% \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}, |taw'amuN|
+% \arb[fullvoc]{taw'amuN} \arb[trans]{taw'amuN},
+% \arb[trans]{murU'aTuN}, |ta'xIruN| \arb[fullvoc]{ta'xIruN}
+% \arb[trans]{ta'xIruN}, |ta'ax|\allowbreak|xara|
+% \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}, |.hIna'i_diN|
+% \arb[trans]{.hIna'i_diN} \arb[voc]{.hIna'i_diN}, |hay'aTuN|
+% \arb[voc]{hay'aTuN} \arb[trans]{hay\-'aTuN}, |hay'AtuN|
+% \arb[voc]{hay'AtuN} \arb[trans]{hay'AtuN}.
+%
+% 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}, |man^sa'I|
+% \arb[trans]{man^sa'I} \arb[voc]{man^sa'I}, |nisA'uN|
+% \arb[voc]{nisA'uN} \arb[trans]{ni\-sA'uN}, |nisA'u-hu|
+% \arb[voc]{nisA'u-hu} \arb[trans]{nisA'u-hu}, |nisA'i-hi|
+% \arb[voc]{nisA'i-hi} \arb[trans]{nisA'i-hi}, |nisA'I|
+% \arb[voc]{nisA'I} \arb[trans]{nisA'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}, |radI'aN|
+% \arb[voc]{radI'aN} \arb[trans]{radI'aN}.
+%
+% \label{ref:taxfif-hamzah}
+% \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}.
+%
+% Imperatives of verbs that have the \arb[trans]{hamzaT} as the
+% first radical are other cases of \arb[trans]{ta_hfIf-u
+% 'l-hamzaT-i}: |i'sir| \arb[fullvoc]{i'sir} \arb[trans]{i'sir},
+% |i'_dan| \arb[fullvoc]{i'_dan} \arb[trans]{i'_dan}, |u'mul|
+% \arb[fullvoc]{u'mul} \arb[trans]{u'mul}. \package{arabluatex}
+% also provides ways of encoding those words when the initial
+% \arb[trans]{'alif} comes into \arb[trans]{wa.sl}, so as to make
+% the \arb[trans]{'alif wa.sl} fall away when preceded by
+% \arb[voc]{wa} or \arb[voc]{fa}: |wa-'sir| \arb[fullvoc]{wa-'sir}
+% \arb[trans]{wa-'sir}, |fa-'_dan| \arb[fullvoc]{fa-'_dan}
+% \arb[trans]{fa-'_dan}, |fa-'ti| \arb[fullvoc]{fa-'ti}
+% \arb[trans]{fa-'ti}, |wa-'tamirUA| \arb[fullvoc]{wa-'tamirUA}
+% \arb[trans]{wa-'tamirUA}; or be retained outside the imperative,
+% as in |fa-i'tazarat| \arb[fullvoc]{fa-i'tazarat}
+% \arb[trans]{fa-i'tazarat}, |ba`da| |i'tilAfiN| \arb[fullvoc]{ba`da
+% i'tilAfiN} \arb[trans]{ba`da i'tilAfiN}.
+%
+% \textbf{The strange spelling of \arb[trans]{mi'aTuN}}: |mi'aTuN|
+% \arb[voc]{mi'aTuN} \arb[trans]{mi'aTuN}, \linebreak |mi'atAni|
+% \arb[voc]{mi'atAni} \arb[trans]{mi'atAni}, |mi'atayni|
+% \arb[voc]{mi'atayni} \arb[trans]{mi'atayni}, |mi'Una|
+% \arb[voc]{mi'Una} \arb[trans]{mi'Una}, |mi'AtuN|
+% \arb[voc]{mi'AtuN} \arb[trans]{mi'AtuN}, |mi'aN_A|
+% \arb[voc]{mi'aN_A} \arb[trans]{mi'aN_A}. Of course, the
+% \enquote*{pipe} character can be used to prevent this rule from
+% being applied (see \vref{sec:pipe}): \verb+mi'a|TuN+
+% \arb[voc]{mi'a|TuN} \arb[trans]{mi'a|TuN}.
+% \end{quote}
+%
+% \paragraph{\texorpdfstring{\arb[trans]{maddaT}}{maddah}}
+% \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{tcblisting}{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{tcblisting}
+% \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{\texorpdfstring{\arb[trans]{^saddaT}}{šaddah}}
+% \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{enumerate}
+% \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{tcblisting}{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{tcblisting}
+% \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{tcblisting}{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{tcblisting}
+% \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{enumerate}
+%
+% \paragraph{\texorpdfstring{The definite article and the
+% \arb[trans]{'alif-u 'l-wa.sl-i}}{The definite article and the ʾalifu
+% 'l-waṣli}}
+% \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 be properly
+% encoded, like so:---
+% \begin{enumerate}
+% \item Definite article at the beginning of a sentence is encoded\\
+% \tcboxverb{al-}, or \tcboxverb{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\\ \tcboxverb{'l-}
+% or \tcboxverb{'<solar letter>-}.
+% \item In all remaining cases of elision, the \arb[trans]{'alifu
+% 'l-wa.sli} is expressed by the vowel that accompanies the omitted
+% \arb[trans]{hamzaT}: \meta{u, a, i}.
+% \end{enumerate}
+% \begin{quote}
+% \textbf{Article}: |bAb-u| |'l-madrasaT-i| \arb[fullvoc]{bAb-u
+% 'l-madrasaT-i} \arb[trans]{bAb-u 'l-madrasaT-i},
+% |al-maqA|\allowbreak|laT-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-`ara|\allowbreak|biyyaT-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{enumerate}
+% \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-madIna|\allowbreak|T-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-|\allowbreak|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{enumerate}
+%
+% \textbf{Perfect active, imperative, nomen actionis}: |qAla|
+% |isma`| \arb[fullvoc]{qAla isma`} \arb[trans]{qAla isma`}, |qAla|
+% |uqtul| \arb[fullvoc]{qAla uqtul} \arb[trans]{qAla uqtul}, |huwa|
+% |inhazama| \arb[fullvoc]{huwa inhazama} \arb[trans]{huwa
+% inhazama}, |wa-ustu`mila| \arb[fullvoc]{wa-ustu`mila}
+% \arb[trans]{wa-ustu`mila}, |qad-i| |in.sarafa| \arb[fullvoc]{qadi
+% in.sarafa} \arb[trans]{qadi in.sarafa}, |al-iqtidAr-u|
+% \arb[fullvoc]{al-iqtidAr-u} \arb[trans]{al-iqtidAr-u}, |'il_A|
+% |'l-inti|\allowbreak|qA.d-i| \arb[fullvoc]{'il_A 'l-intiqA.d-i}
+% \arb[trans]{'il_A 'l-intiqA.d-i}, |law| |istaqbala|
+% \arb[fullvoc]{law istaqbala} \arb[trans]{law istaqbala}.
+%
+% \textbf{Other cases}: |'awi| |ismu-hu| \arb[fullvoc]{'awi ismu-hu}
+% \arb[trans]{'awi ismu-hu}, |zayduN| |ibn-u| |`amriNU|
+% \arb[fullvoc]{\uc{z}ayduN ibn-u \uc{`amriNU}}
+% \arb[trans]{\uc{z}ayduN ibn-u
+% \uc{`amriNU}},\footnote{\label{fn:zayd-is-son}%
+% \enquote{\arb[trans]{\uc{z}ayd} is the son of
+% \arb[trans]{\uc{`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]{\uc{`umar}-u ibn-u \uc{'l-_ha.t.tAb-i}}
+% \arb[trans]{\uc{`umar}-u ibn-u
+% \uc{'l-_ha.t.tAb-i}},\footnote{\enquote{\arb[trans]{\uc{`umar}}
+% is the son of \arb[trans]{\uc{al-_ha.t.tAb}}} (see
+% \vref{fn:zayd-is-son}).} |imru'-u| |'l-qays-i|
+% \arb[fullvoc]{imru'-u 'l-qays-i} \arb[trans]{\uc{i}mru'-u
+% \uc{'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}
+% \label{sec:diphthong-alif}
+% 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-qaw|\allowbreak|m-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.ta\-faw
+% 'l-l_ah-i}.
+%
+% |ramaW| |'l-.hijAraT-a| \arb[fullvoc]{ramaW 'l-.hijAraT-a}
+% \arb[trans]{ramaW 'l-.hijAraT-a}, |fa-lammA| |ra'aW |\allowbreak{}
+% |'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
+% \uc{'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]{\uc{m}u.hammaduN 'l-nabI}, |salAmuN| |ud_hulUA|
+% \arb[fullvoc]{salAmuN ud_hulUA} \arb[trans]{salAmuN ud_hulUA},
+% |qa.sIdata-hu| |fI| |qatl-i| |\uc{'a}bI|
+% |\uc{m}|\allowbreak|uslimiN| |'llatI| |yaqUlu| |fI-hA|
+% \arb[fullvoc]{qa.sIdata-hu fI qatl-i \uc{'a}bI \uc{m}uslimiN
+% 'llatI yaqUlu fI-hA} \arb[trans]{qa.sIdata-hu fI qatl-i \uc{'a}bI
+% \uc{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-|\allowbreak|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-|\allowbreak|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{\texorpdfstring{The conjunctive \arb[voc]{alla_dI}}{The
+% conjunctive اَلَّذِي}}
+% 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 \uc{ja.h.zaT-a}}
+% \arb[trans]{fa-'innA na_dkuru 'l-.sawt-ayni 'l-la_dayni
+% rawaynA-humA `an \uc{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{arabtex}
+% package.\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{enumerate}
+% \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" \uc{hinduN}}
+% \arb[trans]{jA'at" \uc{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{enumerate}
+%
+% \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{enumerate}
+% \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]{\uc{ibn-u} \uc{'abI}
+% \uc{'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{enumerate}
+% 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{enumerate}
+% \item \arb[trans]{'alif-u 'l-wa.sl-i}:---
+% \begin{quote}
+% |fI "istiq.sA'-iN| \arb[voc]{fI "istiq.sA'-iN} \arb[trans]{fI
+% "istiq.sA'-iN}, |wa-"istiq.sA'-uN| \arb[voc]{wa-"istiq.sA'-uN}
+% \allowbreak\arb[trans]{wa-"istiq.sA'-uN}, |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{enumerate}
+%
+% \paragraph{\texttt{fullvoc}}
+% In this mode, \enquote{quoting} can 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 \uc{bi-q"rAn"|nUn-a}} \arb[trans]{al-jamr-u
+% 'l-.sayfiyy-u 'lla_dI kAna \uc{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}{lllll}
+% \bottomrule
+% \caption*{\Cref*{tab:quoted-hamza}: \enquote{Quoted}
+% \arb[trans]{hamzaT}}
+% \endfoot
+% \captionlistentry{\enquote{Quoted} \arb[trans]{hamzaT}}\\[-1em]
+% \toprule Letter & \multicolumn{3}{l}{Transliteration\footnotemark}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endfirsthead
+% \toprule Letter & \multicolumn{3}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endhead
+% \footnotetext{See below \vref{sec:transliteration}.}
+% \label{tab:quoted-hamza}
+% \arb[novoc]{|"'} & \dmg{|"'} & \loc{|"'} & \brill{|"'} & \verb+|"'+ \\
+% \pagebreak[1]
+% \arb[novoc]{A"'} & \dmg{A"'} & \loc{A"'} & \brill{A"'} & \verb|A"'| \\
+% \arb[novoc]{a"'} & \dmg{a"'} & \loc{a"'} & \brill{a"'} & \verb|a"'| \\
+% \arb[novoc]{u"'} & \dmg{u"'} & \loc{u"'} & \brill{u"'} & \verb|u"'| \\
+% \arb[novoc]{w"'} & \dmg{w"'} & \loc{w"'} & \brill{w"'} & \verb|w"'| \\
+% \arb[novoc]{i"'} & \dmg{i"'} & \loc{i"'} & \brill{i"'} & \verb|i"'| \\
+% \arb[novoc]{y"'} & \dmg{y"'} & \loc{y"'} & \brill{y"'} & \verb|y"'| \\
+% \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]{\uc{bi-qrAn|nUn-a}}
+% \arb[trans]{\uc{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{Putting back on broken contextual analysis rules}
+% \label{sec:arbnull}
+% \NEWfeature{v1.7} In complex documents such as critical editions
+% where footnotes and other kind of annotations can be particularly
+% abundant, the contextual analysis rules that are described above may
+% be broken by \LaTeX\ commands. To take an example, consider the
+% following:---%
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ This is wrong:
+ \begin{arab}[fullvoc]
+ fa-lammA ra'aW\LRfootnote{A footnote which interferes with
+ the contextual analysis.} 'l-na^gma...
+ \end{arab}
+\end{example}
+% \iffalse
+%</example>
+% \fi%
+% According to the rule stated \vpageref{sec:diphthong-alif}, the
+% diphthong in \arb[trans]{ra'aW} must be resolved into two simple
+% vowels before the \arb[trans]{'alif-u 'l-wa.sl-i}, as
+% \arb[fullvoc]{ra'aW 'l-na^gma}.
+%
+% \DescribeMacro{\arbnull} The \cs{arbnull} command is provided so as
+% to put back on contextual analysis rules in such situations. It
+% takes as argument the word that must be brought back for any given
+% rule to be applied as it ought to. Depending on the contexts that
+% have to be restored, \cs{arbnull} may be found just after or before
+% Arabic words.%
+% \iffalse
+%<*example>
+% \fi
+\begin{tcblisting}{text only}
+ In any case, \emph{no space must be left} after or before the Arabic
+ word that \cs{arbnull} is applied to.
+\end{tcblisting}
+% \iffalse
+%</example>
+% \fi%
+% The following shows how the Arabic should have been written in the
+% preceding example and gives further illustrations of the same
+% technique:---%
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \begin{arab}[fullvoc]
+ fa-lammA ra'aW\arbnull{'l-na^gma}\LRfootnote{A footnote
+ which interferes with the contextual analysis.}
+ 'l-na^gma...
+
+ qAla\LRfootnote{A footnote which interferes with the
+ contextual analysis.} \arbnull{qAla}uhrub fa-lan tuqtala.
+
+ \uc{z}ayduN\arbnull{ibnu}\LRfootnote{A footnote which
+ interferes with the contextual analysis.}
+ \arbnull{zayduN}ibn-u \uc{`a}mriNU.\LRfootnote{See
+ \vref{fn:zayd-is-son}.}
+ \end{arab}
+
+ \begin{arab}[trans]
+ \uc{z}ayduN\arbnull{ibnu}\LRfootnote{A footnote which
+ interferes with the contextual analysis.}
+ \arbnull{zayduN}ibn-u \uc{`a}mriNU.\LRfootnote{See
+ \vref{fn:zayd-is-son}.}
+ \end{arab}
+\end{example}
+% \iffalse
+%</example>
+% \fi%
+%
+% \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 can 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]{\uc{.hunayn-u} bn-u \uc{'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 either use the \cs{aemph}
+% command that is described below in \vref{sec:emphasis} or insert
+% the \arb[trans]{'ab^gad} number in |\arb[novoc]{}|:---
+% \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}}.
+%
+% |The| |\arb[trans]{'abjad}| |number| |for| |1874| |is|
+% |\arb[novoc]{\abjad{1874}}| The \arb[trans]{'abjad} number for
+% 1874 is \arb[novoc]{\abjad{1874}}.
+% \end{quote}
+% \end{quoting}
+%
+% \NEWfeature{v1.12}\cs{abjad} may also be used to convert values of
+% counters into \arb[trans]{'ab^gad} numbers, like so:--- %
+% \changes{v1.12}{2018/06/24}{\cs{abjad} can now process \LaTeX\
+% counters}%
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ The \arb[trans]{'ab^gad} number for the current page (\thepage) is
+ \abjad{\thepage}.
+\end{example}
+% \iffalse
+%</example>
+% \fi%
+%
+% This technique can be used to produce abjad-numbered lists as will
+% be demonstrated \vpageref{ref:abjad-list}.
+%
+% \subsection{Additional characters}
+% \label{sec:additional-characters}
+% In the manuscripts, the unpointed letters, \arb[trans]{al-.hurUf-u
+% 'l-muhmalaT-u}, 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}{lllll}
+% \bottomrule
+% \caption*{\Cref*{tab:additional-arabic-codings}: Additional Arabic
+% codings}
+% \endfoot
+% \captionlistentry{Additional Arabic codings}\\[-1em]
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration\footnotemark}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endfirsthead
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} \\ \midrule
+% \endhead \footnotetext{See below \vref{sec:transliteration}.}
+% \label{tab:additional-arabic-codings}
+% \arb[novoc]{.b} & \dmg{.b} & \loc{.b} & \brill{.b} & |.b| \\
+% \arb[novoc]{^d} & \dmg{^d} & \loc{^d} & \brill{^d} & |^d| \\
+% \arb[novoc]{.f} & \dmg{.f} & \loc{.f} & \brill{.f} & |.f| \\
+% \arb[novoc]{.q} & \dmg{.q} & \loc{.q} & \brill{.q} & |.q| \\
+% \arb[novoc]{.k} & \dmg{.k} & \loc{.k} & \brill{.k} & |.k| \\
+% \pagebreak[1]
+% \arb[novoc]{.n} & \dmg{.n} & \loc{.n} & \brill{.n} & |.n| \\
+% \arb[novoc]{((} & \dmg{((} & \loc{((} & \brill{((} & |((| \\
+% \arb[novoc]{))} & \dmg{))} & \loc{))} & \brill{))} & |))| \\
+% \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 \aemph{fI 'l-\uc{`AdAt-i}}}.
+% \end{quote}
+%
+% \begin{quoting}
+% \textsc{Rem.}~\emph{a.} As the above example shows,
+% \package{arabluatex} places the horizontal stroke \emph{under} the
+% emphasized words in any of the transliteration modes.
+%
+% \textsc{Rem.}~\emph{b.} \NEWfeature{v1.9.2}\DescribeMacro{\aemph*}
+% \cs{aemph*} is also provided should one wish to always have the
+% horizontal stroke printed over the emphasized words, like so:
+% |\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 \aemph*{fI 'l-\uc{`AdAt-i}}}.
+% \end{quoting}
+%
+% \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{code}
+ \begin{arabverse}[key1=value1, key2=value2, ...]
+ <verses>
+ \end{arabverse}
+\end{code}
+% \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\tcboxverb{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\tcboxverb{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\tcboxverb{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\tcboxverb{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\tcboxverb{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.
+%
+% \DescribeOption{color} |color|$=$\meta{color name}
+% \hfill\tcboxverb{Default: not set}\\
+% \NEWfeature{v1.13} The color in which lines of poetry are to be
+% rendered.
+%
+% \label{ref:poetry-export}
+% \DescribeOption{export} |export|$=$|true|\verb+|+|false|
+% \hfill\tcboxverb{Default: false}\\
+% \NEWfeature{v.1.13} This named argument does not need a value as it
+% defaults to |true| if it is used. If |export| is set as a global
+% option as well (see above \vpageref{export-mode}), all the lines
+% will be converted to Unicode and exported to the external selected
+% file. See below \vref{sec:arabtex2utf} 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.\footnote{\label{ref:bayt-star}A \enquote*{starred} version
+% \cs{bayt*} is also defined. \package{arabluatex} uses it internally
+% when \texttt{export} is set to \texttt{true} to instruct some Lua
+% functions that lines of poetry have already been processed. That
+% aside, \cs{bayt} and \cs{bayt*} do the same, and only \cs{bayt}
+% should be used.} Additionally, every \cs{bayt} command \emph{must}
+% be followed with |\\| like so:---%
+% \iffalse
+%<*example>
+% \fi
+\begin{tcblisting}{text only}
+ \cs{bayt}\marg{\arb[trans]{.sadr}}\oarg{\arb[trans]{tadwIr}}%
+ \marg{\arb[trans]{`ajuz}}|\\|
+\end{tcblisting}
+% \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{enumerate}
+% \item If the two hemistichs be connected with one another by a
+% prominent horizontal flexible stroke, the \arb[trans]{ta.twIl} 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{example}
+ \begin{arabverse}[mode=fullvoc, width=.3\linewidth]
+ \bayt{lA 'ar_A man `ahidtu fI-hA fa-'abkI 'l---}[--]{---yawma
+ dalhaN wa-mA yaruddu 'l-bukA'u}\\
+ \end{arabverse}
+\end{example}
+% \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{example}
+ \begin{arabverse}[mode=trans, width=.4\linewidth]
+ \bayt{lA 'ar_A man `ahidtu fI-hA fa-'abkI 'l---}[--]{---yawma
+ dalhaN wa-mA yaruddu 'l-bukA'u}\\
+ \end{arabverse}
+\end{example}
+% \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{example}
+ \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{example}
+% \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{enumerate}
+%
+% \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 a 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 or
+% \enquote{declare} |footnotemark| using \cs{MkArbBreak} to take it
+% out of the Arabic environment\footnote{See
+% \vref{sec:declare-new-commands}.}) in the 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{footnotehyper} package which \package{arabluatex} will then
+% use to typeset any kind of footnote that is called from the
+% arguments of the \cs{bayt} command.\footnote{The \package{footnote}
+% package can also be used for the same effect. However, it must be
+% loaded \emph{after} \package{arabluatex}.}
+%
+% \paragraph{Line numbering}
+% Inside the |arabverse| environment, the |linenumbers| environment of
+% the \package{lineno} package can 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 \prname{imru'u 'l-qaysi}'s
+% \arb[trans]{\uc{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{Please note that for the time
+% being only the assimilation rules that are laid on
+% \vref{ref:assimilation} are applied. See
+% \vref{sec:classic-modern-typesetting} for more information. None of
+% the editions of the \arb[trans]{\uc{M}u`allaqAt} that I know of
+% feature the \arb[trans]{'id.gAm} in the Arabic text, although it is
+% often strongly marked in declamation.}%
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ \begin{arab}[fullvoc]
+ qAla imru'u 'l-\uc{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 \uc{'l-d}a_hUli fa-\uc{.h}awmali}\\
+ \bayt{fa-\uc{t}U.di.ha fa-'l-\uc{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}{lad_A
+ 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 muharAqaTuN}{fa-hal `inda
+ rasmiN dAsiriN min mu`awwali}\\
+ \end{linenumbers*}
+ \end{arabverse}
+\end{code}
+% \iffalse
+%</example>
+% \fi%
+% \begin{arab}[fullvoc]
+% qAla imru'u 'l-\uc{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 \uc{'l-d}a_hUli fa-\uc{.h}awmali}\\
+% \bayt{fa-\uc{t}U.di.ha fa-'l-\uc{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}{lad_A
+% 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 muharAqaTuN}{fa-hal `inda rasmiN
+% dAsiriN min mu`awwali}\\
+% \end{linenumbers*}
+% \end{arabverse}
+%
+% \medskip
+%
+% \begin{arab}[trans]
+% qAla imru'u 'l-\uc{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 \uc{'l-d}a_hUli fa-\uc{.h}awmali}\\
+% \bayt{fa-\uc{t}U.di.ha fa-'l-\uc{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}{lad_A
+% 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 muharAqaTuN}{fa-hal `inda rasmiN
+% dAsiriN min mu`awwali}\\
+% \end{linenumbers*}
+% \end{arabverse}
+%
+% \section{Special applications}
+% \label{sec:special-applications}
+% \phantomsection
+% \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}
+% \phantomsection
+% \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{itemize}
+% \item parentheses: |()|
+% \item square brackets: |[]|
+% \item angle brackets: |<>|
+% \item braces: |{}|
+% \end{itemize}
+%
+% \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{example}
+ \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{example}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Additional Arabic marks}
+% \label{sec:arabic-marks}
+% In addition to common letters, many symbols and ligatures are
+% encoded in Arabic Unicode standard, such as honorifics consisting of
+% complex ligatures, and annotation signs used in the
+% \arb[trans]{\uc{qur'An}} or in classical poetry.
+%
+% \DescribeMacro{\arbmark}
+% \NEWfeature{v1.11}\cs{arbmark}\oarg{rl\textbar{}lr}\marg{shorthand}
+% can be used to insert such characters either in Unicode or in
+% romanized Arabic environments. It takes as argument a shorthand
+% defined beforehand in a default list which consists of the following
+% at the time of writing:---\\
+% \begin{longtable}{llp{.3\linewidth}p{.3\linewidth}}
+% \bottomrule
+% \caption*{\Cref*{tab:arabtex-additional-marks}: Additional Arabic
+% marks}
+% \endfoot
+% \captionlistentry{Additional Arabic marks}\\[-1em]
+% \toprule
+% Codepoint & Shorthand & Glyph & Transliteration \\ \midrule
+% \endfirsthead
+% \toprule
+% Codepoint & Shorthand & Glyph & Transliteration \\ \midrule
+% \endhead\label{tab:arabtex-additional-marks}%
+% |FDFD| & |bismillah| & \arb{\arbmark{bismillah}} &
+% \arbmark{bismillah} \\
+% |FDF5| & |salam| & \arb{\arbmark{salam}} & \arbmark{salam} \\
+% |FDFA| & |slm| & \arb{\arbmark{slm}} & \arbmark{slm} \\
+% |FDFB| & |jalla| & \arb{\arbmark{jalla}} & \arbmark{jalla} \\
+% \end{longtable}
+%
+% \NEWfeature{v1.13}
+% The mark to be inserted is determined by contextual analysis, or by
+% an optional argument, either |rl| to have the Arabic glyph printed,
+% or |lr| to print the tranliterated equivalent.
+%
+% \DescribeMacro{\newarbmark} \NEWfeature{v1.11} \cs{newarbmark} is
+% also provided should one wish to define new marks in addition to the
+% marks defined above. This command takes three arguments, like so:---
+% \arabluabox{\cs{newarbmark}\marg{shorthand}\marg{RTL
+% codepoint}\marg{LTR rendition}}
+%
+% As regards the right-to-left codepoint, it may be either typed in
+% Unicode or selected as Unicode codepoint. To that end, the \LaTeX\
+% command \tcboxverb{\symbol{"XYZT}} or its plain \TeX\ variant
+% \tcboxverb{\char"XYZT\relax} may be used, where |XYZT| are
+% uppercase hex digits (|0| to |9| or |A| to |F|).
+%
+% It is also possible to use the so-called `|^^^^| notation' like so:
+% \tcboxverb{^^^^xyzt}, where |xyzt| are lowercase hex digits (|0|
+% to |9| or |a| to |f|).
+%
+% As regards the third argument (left-to-right rendition), it may be
+% either left empty or typed by means of
+% \cs{arb}|[trans]|\marg{arabtex code} so as to have it printed in
+% romanized Arabic.%
+% \iffalse
+%<*example>
+% \fi
+\begin{tcblisting}{text only}
+ It must be noted that \cs{newarbmark} expects Arab\TeX\ input scheme
+ inside \cs{arb}|[trans]{}| to the exclusion of \textsf{buckwalter}
+ input scheme.
+\end{tcblisting}
+% \iffalse
+%</example>
+% \fi%
+%
+% The example below provides an implementation of this technique. It
+% may be observed that \cs{arbcolor} is used so as to have the marks
+% printed in red:---%
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \SetArbDflt*
+ \newarbmark{sly}{\arbcolor[red]{^^^^06d6}}{}
+ \newarbmark{jim}{\arbcolor[red]{^^^^06da}}{}
+ \begin{arab}
+ sUraTu 'l-nisA'i, 19:
+ \end{arab}
+ \begin{center}
+ \begin{arab}
+ \arbmark{bismillah}
+ \end{arab}
+ \end{center}
+ \begin{arab}[fullvoc]
+ y_a'ayyuhA 'lla_dIna 'a'manUA lA ya.hillu la-kum 'an tari_tUA
+ 'l-nisA'a karhaN\arbmark{sly} wa-lA ta`.dulU-hunna li-ta_dhabUA
+ bi-ba`.di mA 'a'taytumU-hunna 'illA 'an ya'tIna bi-fA.hi^saTiN
+ mubayyinaTiN\arbmark{jim} wa-`A^sirU-hunna
+ bi-'l-ma`rUfi\arbmark{jim} fa-'in karihtumU-hunna fa-`as_A_a
+ 'an takrahUA ^say'aN wa-ya^g`ala 'l-l_ahu fI-hi _hayraN
+ ka_tIraN ((19))
+ \end{arab}
+\end{example}
+% \iffalse
+%</example>
+% \fi
+%
+% \subsection{\texorpdfstring{The \prname{qur'An}}{The Qurʾān}}
+% \label{sec:the-quran}
+% This sub-part is destined to become a part of its own, as fine
+% typesetting of \prname{qur'An}ic text is planned in the versions of
+% \package{arabluatex} to come in the medium-term. New functions and
+% new Arabic modes will be available as \package{arabluatex} will
+% mature.
+%
+% \DescribeMacro{\ayah}\NEWfeature{v1.15}For the time being,
+% \cs{ayah}\marg{3-digit number} is provided so as to typeset the
+% number of the \arb[trans]{'AyaT} that it is referred to inside the
+% dedicated mark---Unicode |U+06DD|: \txarb{^^^^06dd}---in Arabic
+% script or inside parentheses in romanized Arabic:---
+% \begin{quote}
+% |\ayah{123}| \arb{\ayah{123}} \arb[trans]{\ayah{123}}.
+% \end{quote}
+%
+% An example follows:---
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \SetArbDflt*
+ \newarbmark{alifsp}{^^^^0627}{\arb[trans]{'alif} }
+ \newarbmark{lamsp}{^^^^0644^^^^0653}{\arb[trans]{lAm} }
+ \newarbmark{mim}{^^^^0645^^^^0653}{\arb[trans]{mIm}}
+ \begin{arab}[fullvoc]
+ min ((sUraTi \uc{'l-b}aqaraTi)):
+ \end{arab}
+ \begin{arab}[fullvoc]
+ \arbmark{alifsp}\arbmark{lamsp}\arbmark{mim}~\ayah{1}
+ _d_alika 'l-kit_abu lA rayba fI-hi hudaN_A
+ li-l-muttaqIna~\ayah{2} 'lla_dIna yu'minUna bi-'l-.gaybi
+ wa-yuqImUna 'l-.sal_aUTa wa-mimmA razaqn_a-hum
+ yunfiqUna~\ayah{3}
+ \end{arab}
+\end{example}
+\begin{tcblisting}{text only}
+ \SetArbDflt*
+ \begin{arab}[trans]
+ min ((sUraTi \uc{'l-b}aqaraTi)):
+ \end{arab}
+ \begin{arab}[trans]
+ \arbmark{alifsp}\arbmark{lamsp}\arbmark{mim}~\ayah{1}
+ _d_alika 'l-kit_abu lA rayba fI-hi hudaN_A
+ li-l-muttaqIna~\ayah{2} 'lla_dIna yu'minUna bi-'l-.gaybi
+ wa-yuqImUna 'l-.sal_aUTa wa-mimmA razaqn_a-hum
+ yunfiqUna~\ayah{3}
+ \end{arab}
+\end{tcblisting}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Caveat}
+% For some reason, most of the Arabic fonts do not show the number
+% properly: some are only able to display at most two digits, while
+% others display the digits outside the \enquote*{end of
+% \arb[trans]{'AyaT}} sign, let alone those that print the digits
+% stacked. To the knowledge of the writer, this should be reported to
+% the developers of those fonts.
+%
+% \section{Color}
+% \label{sec:color}
+% \NEWfeature{v1.12}\package{arabluatex} is able to render in color
+% either words, parts of words or diacritics. As the techniques
+% implemented in this section may lead to some complexity, the reader
+% should first become well acquainted with the following
+% points:\footnote{Regarding the colors themselves and the way new
+% colors can be defined in addition to those that are already
+% available, please refer to the \package{xcolor} package.}---
+% \begin{enumerate}
+% \item The \enquote{pipe} character (\textbar, \vref{sec:pipe});
+% \item \enquote*{Quoting} technique (\vref{sec:quoting}), and more
+% specifically \enquote*{quoting the \arb[trans]{hamzaT}}
+% (\vpageref{sec:quoting-hamza});
+% \item Putting back on broken contextual analysis rules
+% (\vref{sec:arbnull});
+% \item Arabic marks (\vref{sec:arabic-marks}).
+% \end{enumerate}
+%
+% \DescribeMacro{\arbcolor} \cs{arbcolor} takes the text to be colored
+% into \meta{color} as an argument:---
+% \arabluabox{\cs{arbcolor}\oarg{color}\marg{Arabic text}}
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \begin{arab}
+ \arbcolor[red]{al-bAbu 'l-_hAmisu} fI .tabaqAti 'l-'a.tibbA'i
+ 'lla_dIna kAnUA mun_du zamAni \uc{^gAlInUsa} wa-qarIbaN
+ min-hu. \arbcolor[red]{\uc{^gAlInUsu}}: wa-li-na.da` 'awwalaN
+ kalAmaN kulliyyaN fI 'a_hbAri \uc{^gAlInUsa} wa-mA kAna
+ `alay-hi...
+ \end{arab}
+ \begin{arab}[trans]
+ \arbcolor[red]{al-bAbu 'l-_hAmisu} fI .tabaqAti 'l-'a.tibbA'i
+ 'lla_dIna kAnUA mun_du zamAni \uc{^gAlInUsa} wa-qarIbaN
+ min-hu. \arbcolor[red]{\uc{^gAlInUsu}}: wa-li-na.da` 'awwalaN
+ kalAmaN kulliyyaN fI 'a_hbAri \uc{^gAlInUsa} wa-mA kAna
+ `alay-hi...
+ \end{arab}
+\end{example}
+% \iffalse
+%</example>
+% \fi
+%
+% As this example shows, \cs{arbcolor} has been used to render
+% headings in red with the same encoding both in vocalized and in
+% romanized Arabic. The same technique also applies to syllabes inside
+% words. \package{arabluatex} takes care of selecting the appropriate
+% shape of the letters while coloring them:---
+% \begin{quote}\textbf{\enquote*{voc} mode}:\\
+% |i^stara\arbcolor[brown]{y}tu-hu| |bi-_tama\arbcolor[red]{niN}|
+% |'a`\arbcolor[blue]{^ga}ba-ka|
+% \arb{i^stara\arbcolor[brown]{y}tu-hu bi-_tama\arbcolor[red]{niN}
+% 'a`\arbcolor[blue]{^ga}ba-ka}
+% \arb[trans]{i^stara\arbcolor[brown]{y}tu-hu
+% bi-_tama\-\arbcolor[red]{niN} 'a`\arbcolor[blue]{^ga}ba-ka}.
+% \end{quote}
+% \begin{quote}\textbf{\enquote*{fullvoc} mode}:\\
+% |i^stara\arbcolor[brown]{y}tu-hu| |bi-_tama\arbcolor[red]{niN}|
+% |'a`\arbcolor[blue]{^ga}ba-ka|
+% \arb[fullvoc]{i^stara\arbcolor[brown]{y}tu-hu
+% bi-_tama\arbcolor[red]{niN} 'a`\arbcolor[blue]{^ga}ba-ka}
+% \arb[trans]{i^stara\arbcolor[brown]{y}tu-hu
+% bi-_tama\-\arbcolor[red]{niN} 'a`\arbcolor[blue]{^ga}ba-ka}.
+% \end{quote}
+%
+% \subsection{Tricks of the trade}
+% \label{sec:color-tricks}
+% \paragraph{Diacritics}
+% Depending on the mode selected, either |voc|, |novoc| or |fullvoc|,
+% coloring the diacritics requires more attention for the insertion of
+% \cs{arbcolor} may prevent contextual analysis from being applied.
+%
+% Furthermore, depending on the surrounding letters, the standard
+% encoding of short vowels \meta{u, a, i} may result either in
+% diacritics or in a connective \arb[trans]{'alif} with the
+% \arb[trans]{wa.slaT} or its accompanying vowel. As for the
+% \arb[trans]{sukUn}, it is generated by contextual analysis. Thus
+% applying colors to bare diacritics requires them to have specific
+% encodings.
+%
+% \Cref{tab:arbcolor-diacritics} gives the Arab\TeX\ equivalents for
+% the diacritics to be printed inside or just after \cs{arbcolor}.
+%
+% \needspace{7\baselineskip}
+% \begin{longtable}{lllll}
+% \bottomrule
+% \caption*{\Cref*{tab:arbcolor-diacritics}: Arab\TeX\ diacritics
+% for \cs{arbcolor}}
+% \endfoot
+% \captionlistentry{Arab\TeX\ diacritics for \cs{arbcolor}}\\[-1em]
+% \toprule
+% Diacritic & \multicolumn{3}{l}{Transliteration\footnotemark}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endfirsthead
+% \toprule
+% Diacritic & \multicolumn{3}{l}{Transliteration}
+% & Arab\TeX\ notation \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & \\ \midrule
+% \endhead \footnotetext{See below \vref{sec:transliteration}.}
+% \label{tab:arbcolor-diacritics}
+% \arb{B.a} & \dmg{.a} & \loc{.a} & \brill{.a} & \verb|.a| \\
+% \pagebreak[1]
+% \arb{B.u} & \dmg{.u} & \loc{.u} & \brill{.u} & \verb|.u| \\
+% \arb{B.i} & \dmg{.i} & \loc{.i} & \brill{.i} & \verb|.i| \\ \midrule
+% \arb{Bo} & \dmg{o} & \loc{o} & \brill{o} & \verb|o| \\
+% \end{longtable}
+%
+% The following examples show how the letters, or the diacritics above
+% or under them or both the letters and the diacritics can be rendered
+% in different colors:---
+% \begin{quote}\textbf{\enquote*{voc} mode}:\\
+% |i^staraytu-hu| |bi-_taman\arbcolor[red]{iN}|
+% |'a`^g\arbcolor[red]|\allowbreak|{.a}ba-ka|
+% \arb{i^staraytu-hu bi-_taman\arbcolor[red]{iN}
+% 'a`^g\arbcolor[red]{.a}ba-ka}
+% \arb[trans]{i^staraytu-hu bi-_taman\arbcolor[red]{iN}
+% 'a`^g\arbcolor[red]{.a}ba-ka}.
+%
+% |i^staraytu-hu| |bi-_tama\arbcolor[red]{n}iN|
+% |'a`\arbcolor[red]|\allowbreak|{^g}.aba-ka|
+% \arb{i^staraytu-hu bi-_tama\arbcolor[red]{n}iN
+% 'a`\arbcolor[red]{^g}.aba-ka}
+% \arb[trans]{i^staraytu-hu bi-_tama\arbcolor[red]{n}iN
+% 'a`\arbcolor[red]{^g}.aba-ka}.
+%
+% |i^staraytu-hu| |bi-_tama\arbcolor[red]{n}\arbcolor[blue]{iN}|
+% \allowbreak
+% |'a`\arbcolor[red]|\allowbreak|{^g}\arbcolor[blue]{.a}ba-ka|
+% \arb{i^staraytu-hu bi-_tama\arbcolor[red]{n}\arbcolor[blue]{iN}
+% 'a`\arbcolor[red]{^g}\arbcolor[blue]{.a}ba-ka} \linebreak
+% \arb[trans]{i^staraytu-hu
+% bi-_tama\arbcolor[red]{n}\arbcolor[blue]{iN}
+% 'a`\arbcolor[red]{^g}\arbcolor[blue]{.a}ba-ka}.
+% \end{quote}
+%
+% \begin{quote}\textbf{\enquote*{fullvoc} mode}:\\
+% |i^staray"\arbcolor[red]{o}tu-hu| |bi-_taman"\arbcolor[red]{iN}|
+% |'a`^g"\arbcolor[red]{.a}ba-ka|
+% \arb[fullvoc]{i^staray"\arbcolor[red]{o}tu-hu
+% bi-_taman"\arbcolor[red]{iN} 'a`^g"\arbcolor[red]{.a}ba-ka}
+% \arb[trans]{i^staray"\arbcolor[red]{o}tu-hu
+% bi-_taman"\arbcolor[red]{iN}
+% \linebreak 'a`^g"\arbcolor[red]{.a}ba-ka}.
+%
+% |i^stara\arbcolor[red]{y"}otu-hu| |bi-_tama\arbcolor[red]{n"}iN|
+% |'a`\arbcolor[red]|\allowbreak|{^g"}.aba-ka|
+% \arb[fullvoc]{i^stara\arbcolor[red]{y"}otu-hu
+% bi-_tama\arbcolor[red]{n"}iN 'a`\arbcolor[red]{^g"}.aba-ka}
+% \arb[trans]{i^stara\arbcolor[red]{y"}otu-hu
+% bi-_tama\arbcolor[red]{n"}iN 'a`\arbcolor[red]{^g"}.aba-ka}.
+%
+% |i^stara\arbcolor[red]{y"}\arbcolor[blue]{o}tu-hu|
+% |bi-_tama\arb|\allowbreak|color[red]{n"}\arbcolor[blue]{iN}|
+% |'a`\arbcolor[red]|\allowbreak|{^g"}\arb|\allowbreak%
+% |color[blue]{.a}ba-ka|
+% \arb[fullvoc]{i^stara\arbcolor[red]{y"}\arbcolor[blue]{o}tu-hu
+% bi-_tama\arbcolor[red]{n"}\arbcolor[blue]{iN}
+% 'a`\arbcolor[red]{^g"}\arbcolor[blue]{.a}ba-ka}
+% \arb[trans]{i^stara\arbcolor[red]{y"}\arbcolor[blue]{o}tu-hu
+% bi-_tama\arbcolor[red]{n"}\arbcolor[blue]{iN}
+% 'a`\arbcolor[red]{^g"}\arbcolor[blue]{.a}ba-ka}.
+% \end{quote}
+%
+% As can be seen, |fullvoc| required the letters |y|, |n| and |^g|
+% before \cs{arbcolor} to be \enquote*{quoted}. Otherwise, unwanted
+% \arb[trans]{sukUn}\txtrans{s} would have been generated because of
+% the absence of a vowel after those consonants.
+%
+% \paragraph{\texorpdfstring{\arb[trans]{tanwIn}}{tanwīn}}
+% \cs{arbnull} must be used with \arb[trans]{fat.haTAn} (\arb{BaN}) so
+% as to put back on contextual analysis rules:---
+% \begin{quote}
+% |mu`allim\arbcolor[red]{\arbnull{m}aN}|
+% \arb{mu`allim\arbcolor[red]{\arbnull{m}aN}}
+% \arb[trans]{mu`allim\arbcolor[red]{\arbnull{m}aN}},\\
+% |istisqA'\arbcolor[red]{\arbnull{A'}aN}|
+% \arb{istisqA'\arbcolor[red]{\arbnull{A'}aN}}
+% \arb[trans]{istisqA'\arbcolor[red]{\arbnull{A'}aN}},\\
+% |^say'\arbcolor[red]{\arbnull{ay'}aN}|
+% \arb{^say'\arbcolor[red]{\arbnull{ay'}aN}}
+% \arb[trans]{^say'\arbcolor[red]{\arbnull{ay'}aN}},\\
+% \verb+^gAmi`aT|\arbcolor[red]{\arbnull{T}aN}+
+% \arb{^gAmi`aT|\arbcolor[red]{\arbnull{T}aN}}
+% \arb[trans]{^gAmi`aT|\arbcolor[red]{\arbnull{T}aN}}.
+% \end{quote}
+% \begin{quoting}
+% \textsc{Rem.} Note that in the last example
+% (\arb[trans]{^gAmi`aT|\arbcolor[red]{\arbnull{T}aN}}), the
+% \enquote*{pipe} character has been inserted before
+% \cs{arbcolor}. Otherwise, the |dmg| mode of the transliteration
+% rules would have interpreted the \arb[trans]{tA' marbU.taT} as
+% \emph{final} (e.g. \txtrans{h} instead of the expected
+% \txtrans{t}).\footnote{See also \vpageref{ref:ta-marbutah-pipe}
+% \enquote{Discarding the \arb[trans]{'i`rAb}} for more
+% information.}
+% \end{quoting}
+%
+% The \arb[trans]{tanwIn} preceding a \arb[novoc]{_A} conveys even
+% more intricate business to the rendering with the utmost accuracy in
+% both romanized and non-romanized modes. First, a new Arabic mark
+% needs to be defined. It should print \arb[novoc]{_A} in Arabic
+% script and not a thing in transliteration. It is to be appended after
+% \cs{arbcolor}, like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \newarbmark{Y}{^^^^0649}{}
+ \arb{hud\arbcolor[red]{aN\arbnull{_A}}\arbmark{Y}}
+ \arb[trans]{hud\arbcolor[red]{aN\arbnull{_A}}\arbmark{Y}}
+\end{example}
+% \iffalse
+%</example>
+% \fi%
+%
+% \paragraph{\texorpdfstring{\arb[trans]{wa.slaT} and
+% \arb[trans]{maddaT}}{waṣlah and maddah}}
+% Both can be generated with the help of \cs{arbnull}:---
+% \begin{quote}
+% |wa-\arbcolor[red]{\arbnull{wa}i}stisqA'uN|
+% \arb[fullvoc]{wa-\arbcolor[red]{\arbnull{wa}i}stisqA'uN}
+% \arb[trans]{wa-\arbcolor[red]{\arbnull{wa}i}stisqA'uN}\footnote{To
+% the knowledge of the writer, the \arb[trans]{wa.slaT} alone is not
+% part of the Arabic Unicode block.}.
+%
+% |fI| |"al".i-\arbcolor[red]{\arbnull{'l-}i}btidA'i|
+% \arb[fullvoc]{fI "al".i-\arbcolor[red]{\arbnull{'l-}i}btidA'i}
+% \linebreak
+% \arb[trans]{fI "al".i-\arbcolor[red]{\arbnull{'l-}i}btidA'i}.
+%
+% |\arbcolor[red]{'a'\arbnull{k}}kulu|
+% \arb{\arbcolor[red]{'a'\arbnull{k}}kulu}
+% \arb[trans]{\arbcolor[red]{'a'\arbnull{k}}kulu},\\
+% |\arbcolor[red]{'A\arbnull{k}}kiluN|
+% \arb{\arbcolor[red]{'A\arbnull{k}}kiluN}
+% \arb[trans]{\arbcolor[red]{'A\arbnull{k}}kiluN}.
+% \end{quote}
+%
+% The Unicode codepoint of the \arb[trans]{maddaT} is 0653, while bare
+% \arb[trans]{'alif} is 0627. So:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \newarbmark{alifmaddahred}{^^^^0627\arbcolor[red]{^^^^0653}}%
+ {\arb[trans]{\arbcolor[red]{'a'\arbnull{k}}}}
+ \arb{\arbmark{alifmaddahred}kulu}
+ \arb[trans]{\arbmark{alifmaddahred}kulu}.
+\end{example}
+% \iffalse
+%</example>
+% \fi%
+%
+% \begin{quoting}
+% \textsc{Rem.} In the preceding example, any consonant could have
+% been passed as argument to the \cs{arbnull} command.
+% \end{quoting}
+%
+% \paragraph{\texorpdfstring{\arb[trans]{^sad\-daT}}{šaddah}}
+% In the following example, it is assumed that the
+% \arb[trans]{^saddaT} above the letter \arb[novoc]{l} in
+% \arb[fullvoc]{al-mu`allimUna}, \arb[trans]{al-mu`allimUna}, is to be
+% rendered in red. Thus the Arabic mark must generate the
+% \arb[trans]{^saddaT} alone---of which the Unicode codepoint is
+% 0651---in Arabic script and the letter \enquote*{l} in
+% transliteration:--- %
+%\iffalse
+%<*example>
+% \fi
+\begin{example}
+ \newarbmark{lamshaddah}{^^^^0651}{l}
+ \arb[fullvoc]{al-mu`al"\arbcolor[red]{\arbmark{lamshaddah}}.imUna}
+ \arb[trans]{al-mu`al"\arbcolor[red]{\arbmark{lamshaddah}}.imUna}.
+\end{example}
+% \iffalse
+%</example>
+% \fi%
+%
+% \paragraph{\texorpdfstring{The definite article and the euphonic
+% \arb[trans]{ta^sdId}}{The definite article and the euphonic tašdīd}}
+% The intricate business of rendering in color the initial
+% \arb[trans]{'alif al-wa.sl} of the definite article followed by a
+% solar consonant must be unraveled.
+%
+% From the examples provided above, in |fI 'l-nAsi| \arb[fullvoc]{fI
+% 'l-nAsi} \arb[trans]{fI 'l-nAsi}, the initial \arb[trans]{'alif-u
+% 'l-wa.sl-i} can be rendered in red like so:
+% |\arbcolor[red]{\arbnull{al-}a}|
+% \arb[fullvoc]{\arbcolor[red]{\arbnull{al-}a}}. Then, the following
+% two letters, namely |l-n|, must print the string \arb[trans]{lAm}
+% $+$ \arb[trans]{nUn} $+$ \arb[trans]{^saddaT} in Arabic, and exactly
+% \txtrans{n-n} in transliteration. Thus an Arabic mark is
+% needed:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \newarbmark{lnn}{^^^^0644^^^^0646^^^^0651}{n-n}
+ \arb[fullvoc]{fI\arbnull{al-}
+ \arbcolor[red]{\arbnull{al-}a}\arbmark{lnn}Asi}
+ \arb[trans]{fI\arbnull{al-}
+ \arbcolor[red]{\arbnull{al-}a}\arbmark{lnn}Asi}.
+\end{example}
+% \iffalse
+%</example>
+% \fi%
+%
+% \paragraph{\texorpdfstring{\arb[trans]{hamzaT}}{hamzah}}
+% The \enquote*{quoting} technique provides an easy way to determine
+% the carrier of the \arb[trans]{hamzaT}, as shown in
+% \vref{tab:quoted-hamza}---:
+% \begin{quote}
+% \verb+yatasA\arbnull{'a}\arbcolor[red]{|"'}.alUna+
+% \arb{yatasA\arbnull{'a}\arbcolor[red]{|"'}.alUna}
+% \arb[trans]{yatasA\arbnull{'a}\-\arbcolor[red]{|"'}.a\-lUna},
+% \verb+^say\arbcolor[red]{|"'}\arbnull{'}aN+
+% \arb{^say\arbcolor[red]{|"'}\arbnull{'}aN}
+% \arb[trans]{^say\arbcolor[red]{|"'}\arbnull{'}aN},
+% \verb+^say\ar+\allowbreak\verb+bcolor[red]{|"'}iN+
+% \arb{^say\arbcolor[red]{|"'}iN}
+% \arb[trans]{^say\arbcolor[red]{|"'}iN},
+% |\arbcolor[red]{a"'}.as\arbcolor|\allowbreak|[red]{y"'}.ilaTuN|
+% \arb{\arbcolor[red]{a"'}.as\arbcolor[red]{y"'}.ilaTuN}
+% \arb[trans]{\arbcolor[red]{a"'}.as\arbcolor[red]{y"'}.ilaTuN}.
+% \end{quote}
+%
+%
+% \section{Transliteration}
+% \label{sec:transliteration}
+% It may be more appropriate to speak of \enquote{romanization} than
+% \enquote{transliteration} of Arabic. As seen above in
+% \cref{sec:options} \vpagerefrange{sec:options}{sec:local-options},
+% the \enquote{transliteration mode} may be selected globally or locally.
+%
+% This mode transliterates the Arab\TeX\ input into one of the
+% accepted standards. As said above \vpageref{ref:describe-trans},
+% three standards are supported at present:
+% \begin{description}
+% \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}.}
+% \item[arabica] \NEWfeature{v1.8}
+% \changes{v1.8}{2017/03/30}{\texttt{arabica} transliteration
+% standard is now supported} \emph{Journal of Arabic and Islamic
+% Studies}/\emph{Revue d'études arabes et islamiques}: this standard
+% is most widely used by scholars in the field of Arabic
+% studies.\footnote{See
+% \url{http://www.brill.nl/files/brill.nl/specific/authors_instructions/ARAB.pdf}.}
+% \end{description}
+% 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|, |loc| or |arabica|. This command is also
+% accepted in the preamble should one wish to set the transliteration
+% mode globally, e.g.:---%
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ \usepackage{arabluatex}
+ \SetTranslitConvention{loc}
+\end{code}
+% \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, e.g. \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 can be used for rendering transliterated text:---
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ \newfontfamily\translitfont{Gentium Plus}[Ligatures=TeX]
+ \SetTranslitFont{\translitfont}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Proper names} \DescribeMacro{\uc} Proper names or book
+% titles that must have their first letters uppercased may be passed
+% as arguments to the \cs{uc}\marg{word} command. \cs{uc} 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}
+% |\uc{.hunayn-u}| |bn-u| |\uc{'is.h_aq-a}|
+% \arb[voc]{\uc{.hunayn-u} bn-u \uc{'is.h_aq-a}}
+% \arb[trans]{\uc{.hunayn-u} bn-u \uc{'is.h_aq-a}},
+% |\uc{`u_tm_an-u}| \arb[voc]{\uc{`u_tm_an-u}}
+% \arb[trans]{\uc{`u_tm_an-u}}, |.daraba| |\uc{zayd-u}| |bn-u|
+% |\uc{_h_alidiN}| |\uc{sa`d-a}| |bn-a| |\uc{`awf-i}| |bn-i|
+% |\uc{|\allowbreak|`abd-i}| |\uc{'l-l_ah-i}|
+% \arb[fullvoc]{.daraba \uc{zayd-u} bn-u \uc{_h_alidiN}
+% \uc{sa`d-a} bn-a \uc{`awf-i} bn-i \uc{`abd-i} \uc{'l-l_ah-i}}
+% \arb[trans]{.daraba \uc{zayd-u} bn-u \uc{_h_alidiN} \uc{sa`d-a}
+% bn-a \uc{`awf-i} bn-i \uc{`abd-i} \uc{'l-l_ah-i}}.
+% \end{quote}
+% However, \cs{uc} 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]{\uc{m}u.hammaduN 'l-nabI} must be
+% \arb[trans]{\uc{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: |\uc{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{uc} vz. up to the first letter that is to be
+% uppercased, like so: |\uc{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}
+% |\uc{'abU}| |\uc{bakriN}| |\uc{mu\-.ham\-madu}| |bnu|
+% |\uc{za\-ka| |\-riy\-yA'a}| |\uc{'l-rAziyyu}| \arb{\uc{'abU}
+% \uc{bakriN} \uc{mu\-.ham\-mad-u} bnu \uc{za\-ka\-riy\-yA'a}
+% \uc{'l-rAziyyu}} \arb[trans]{\uc{'abU} \uc{bakriN}
+% \uc{mu\-.ham\-mad-u} bn-u \uc{za\-ka\-riy\-yA'-a}
+% \uc{'l-rAziyyu}}.
+% \end{quote}
+%
+% \paragraph{\enquote*{Long} pro\-per names}
+% \NEWfeature{v1.10} \cs{uc} is also able to process proper names
+% consisting of several subsequent words:---
+% \begin{quote}
+% |\arb[trans]{\uc{'abU| |zaydiN| |.hunaynu| |bnu| |'is.h_aqa|
+% |'l-`ibAdiyyu}}| \arb[trans]{\uc{'abU zaydiN .hunaynu bnu
+% 'is.h_aqa 'l-`ibAdiyyu}}.
+% \end{quote}
+%
+% \paragraph{Proper names outside Arabic environments}
+% \changes{v1.10}{2018/01/03}{\cs{uc} supersedes \cs{cap}}
+% \DescribeMacro{\prname}\NEWfeature{v1.10} Transliterated proper
+% names inserted in paragraphs of English text should be printed in
+% the same typeface as the surrounding text. \cs{prname}\marg{Arabic
+% proper name} is provided to that effect:\footnote{Just as \cs{uc},
+% \cs{prname} is also able to process proper names consisting of
+% several subsequent words.}---
+%\iffalse
+%<*example>
+% \fi
+\begin{example}
+ From \textcite[i. 23 C]{Wright}:--- If the name following
+ \arb[fullvoc]{ibnuN} be that of the mother or the grandfather, the
+ \arb[fullvoc]{"a} is retained; as \arb[fullvoc]{`Is_A ibnu maryama},
+ \enquote{Jesus the son of Mary}; \arb[fullvoc]{`ammAru ibnu
+ man.sUriN}, \enquote{\prname{`ammAr} the (grand)son of
+ \prname{man.sUr}}.
+\end{example}
+% \iffalse
+%</example>
+% \fi
+%
+% The following example shows how \cs{prname} can be used in
+% conjunction with the \package{nameauth} package to have Arabic
+% proper names printed first in full then in partial
+% forms:\footnote{See the documentation of \package{nameauth} for more
+% details: \url{https://ctan.org/pkg/nameauth}}--- %
+%\iffalse
+%<*example>
+% \fi
+\begin{example}
+ \begin{nameauth}
+ \< Hunayn & \prname{'abU zayd} & \prname{.hunayn}, \prname{{i}bn
+ 'is.h_aq al-`ibAdiyy} & > %
+ \< Razi & \prname{'abU bakr mu.hammad ibn zakariyyA'} &
+ \prname{al-rAziyy} & > %
+ \end{nameauth}
+
+ On first occurrence, proper names are printed as \Hunayn, \Razi.
+ Then as \Hunayn, \Razi.
+\end{example}
+% \iffalse
+%</example>
+% \fi
+%
+% \begin{quoting}\label{ref:prname-star}
+% \textsc{Rem.} \DescribeMacro{\prname*} \package{arabluatex} also
+% provides \cs{prname*} which only renders in upright roman style
+% already transliterated proper names without applying any further
+% processing. It is mostly used internally and applied to proper
+% names exported in Unicode to an external selected
+% file.\footnote{See below \vref{sec:arabtex2utf} for more details.}
+% \end{quoting}
+%
+% \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{enumerate}
+% \item \label{ref:dmg-full-rend}In full:
+% \NoArbUp\arb[trans]{\uc{`amruNU}}\ArbUpDflt\,;
+% \item \label{ref:dmg-up-rend}As superscript text:
+% \arb[trans]{\uc{`amruNU}}\,;
+% \item \label{ref:irab-discarded}Discarded: \arb[trans]{\uc{`amr}}.
+% \end{enumerate}
+% \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} can 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{example}
+ \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{example}
+% \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{\texorpdfstring{\arb[trans]{'i`rAb} boundaries}{ʾiʿrāb
+% 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}, |\uc{`amraNU}|
+% \arb[voc]{\uc{`amraNU}} \arb[trans]{\uc{`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}
+%
+% \paragraph{\texorpdfstring{Discar\-ding the
+% \arb[trans]{'i`rAb}}{Discarding the ʾiʿrāb}}
+% \label{ref:ta-marbutah-pipe}
+% As said above (\vref{ref:irab-discarded}), the \arb[trans]{'i`rAb}
+% may be discarded in some cases, as in transliterated proper names or
+% book titles. \package{arabluatex} is able to render words ending
+% with \arb[trans]{tA' marbU.taT} in different ways, depending on
+% their function:---
+% \begin{enumerate}
+% \item Nouns followed by an adjective in apposition: |madInaT|
+% |kabIraT| \arb[trans]{madInaT kabIraT}, |al-madInaT| |al-kabIraT|
+% \arb[trans]{al-madInaT al-kabIraT}.
+% \item Nouns followed by another noun in the genitive (contruct
+% state): |.hikmaT| |al-l_ah| \arb[trans]{.hikmaT| \uc{al-l_ah}},
+% |fi.d.daT| |al-darAhim| \arb[trans]{fi.d.daT al-darAhim}.
+% \end{enumerate}
+% \begin{quoting}
+% \textsc{Rem.} It may so happen, as in the absence of the article
+% before the annexed word, that \package{arabluatex} be unable to
+% determine which of the above two cases the word ending with
+% \arb[trans]{tA' marbU.taT} falls into. The \enquote*{pipe}
+% character (see \vref{sec:pipe}) may be appended to that word to
+% indicate that what follows is in the construct state:
+% |\uc{r}isAlaT| |fI| |tartIb| \verb+qirA'aT|+ |kutub|
+% |\uc{^g}AlInUs| \arb[trans]{\uc{r}isAlaT fI tartIb qirA'aT|
+% kutub \uc{^g}AlInUs}.
+% \end{quoting}
+%
+%
+% \paragraph{Uncertain short vowels}
+% In some printed books, it may happen that more than one short vowel
+% be placed on a consonant in cases where the vocalization is
+% uncertain or ambiguous, like so: \arb[voc]{fa`uaila}. In
+% transliteration, the uncertain vowels go between slashes and are
+% separated by commas: |fa`uaila| \arb[voc]{fa`uaila}
+% \arb[trans]{fa`uaila}.
+%
+% \subsection{Examples}
+% \label{sec:examples-translit}
+% Here follows in transliteration the story of
+% \arb[trans]{\uc{ju.hA}} and his donkey (\arb[voc]{\uc{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
+% \uc{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 \uc{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 \uc{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 \uc{ju.hA} yanhaqu.} fa-qAla la-hu \uc{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
+% \uc{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 \uc{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 \uc{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 \uc{ju.hA} yanhaqu.} fa-qAla la-hu \uc{ju.hA}:
+% \enquote{.garIbuN 'amru-ka yA .sadIqI 'a-tu.saddiqu 'l-.himAr-a
+% wa-tuka_d_diba-nI?}
+% \end{arab}
+% \SetTranslitConvention{dmg}
+%
+% \SetTranslitConvention{arabica}
+% \begin{arab}[trans]
+% \LR{\textbf{\emph{\enquote*{arabica}} standard:}} 'at_A .sadIquN
+% 'il_A \uc{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
+% \uc{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 \uc{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 \uc{ju.hA} yanhaqu.} fa-qAla la-hu
+% \uc{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{code}
+ \usepackage{arabluatex}
+ \SetInputScheme{buckwalter}
+\end{code}
+% \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.
+%
+% \enlargethispage{\baselineskip}
+% \begin{longtable}{llllll}
+% \bottomrule
+% \caption*{\Cref*{tab:buckwalter-scheme}: Buckwalter scheme}
+% \endfoot
+% \captionlistentry{Buckwalter scheme}\\[-1em]
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration\footnotemark}
+% & \multicolumn{2}{l}{Buckwalter notation} \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & |base/xml| &
+% |safe| \\ \midrule
+% \endfirsthead
+% \toprule
+% Letter & \multicolumn{3}{l}{Transliteration}
+% & \multicolumn{2}{l}{Buckwalter notation} \\
+% & \texttt{dmg} & \texttt{loc} & \texttt{arabica} & |base/xml| &
+% |safe| \\ \midrule
+% \endhead \footnotetext{See \vref{sec:transliteration}.}
+% \label{tab:buckwalter-scheme}
+% \arb[novoc]{a} & \dmg{a} & \loc{a} & \brill{a} & |A| & |A| \\
+% \pagebreak[1]
+% \arb[novoc]{b} & \dmg{b} & \loc{b} & \brill{b} & |b| & |b| \\
+% \arb[novoc]{t} & \dmg{t} & \loc{t} & \brill{t} & |t| & |t| \\
+% \arb[novoc]{_t} & \dmg{_t} & \loc{_t} & \brill{_t} & |v| & |v| \\
+% \arb[novoc]{j} & \dmg{j} & \loc{j} & \brill{j} & |j| & |j| \\
+% \arb[novoc]{.h} & \dmg{.h} & \loc{.h} & \brill{.h} & |H| & |H| \\
+% \arb[novoc]{x} & \dmg{x} & \loc{x} & \brill{x} & |x| & |x| \\
+% \arb[novoc]{d} & \dmg{d} & \loc{d} & \brill{d} & |d| & |d| \\
+% \arb[novoc]{_d} & \dmg{_d} & \loc{_d} & \brill{_d} & |*| & |V| \\
+% \arb[novoc]{r} & \dmg{r} & \loc{r} & \brill{r} & |r| & |r| \\
+% \arb[novoc]{z} & \dmg{z} & \loc{z} & \brill{z} & |z| & |z| \\
+% \arb[novoc]{s} & \dmg{s} & \loc{s} & \brill{s} & |s| & |s| \\
+% \arb[novoc]{^s} & \dmg{^s} & \loc{^s} & \brill{^s} & |$| & |c| \\
+% \arb[novoc]{.s} & \dmg{.s} & \loc{.s} & \brill{.s} & |S| & |S| \\
+% \arb[novoc]{.d} & \dmg{.d} & \loc{.d} & \brill{.d} & |D| & |D| \\
+% \arb[novoc]{.t} & \dmg{.t} & \loc{.t} & \brill{.t} & |T| & |T| \\
+% \arb[novoc]{.z} & \dmg{.z} & \loc{.z} & \brill{.z} & |Z| & |Z| \\
+% \arb[novoc]{`} & \dmg{`} & \loc{`} & \brill{`} & |E| & |E| \\
+% \arb[novoc]{.g} & \dmg{.g} & \loc{.g} & \brill{.g} & |g| & |g| \\
+% \arb[novoc]{f} & \dmg{f} & \loc{f} & \brill{f} & |f| & |f| \\
+% \arb[novoc]{q} & \dmg{q} & \loc{q} & \brill{q} & |q| & |q| \\
+% \arb[novoc]{k} & \dmg{k} & \loc{k} & \brill{k} & |k| & |k| \\
+% \arb[novoc]{l} & \dmg{l} & \loc{l} & \brill{l} & |l| & |l| \\
+% \arb[novoc]{m} & \dmg{m} & \loc{m} & \brill{m} & |m| & |m| \\
+% \arb[novoc]{n} & \dmg{n} & \loc{n} & \brill{n} & |n| & |n| \\
+% \arb[novoc]{h} & \dmg{h} & \loc{h} & \brill{h} & |h| & |h| \\
+% \arb[novoc]{w} & \dmg{w} & \loc{w} & \brill{w} & |w| & |w| \\
+% \arb[novoc]{y} & \dmg{y} & \loc{y} & \brill{y} & |y| & |y| \\
+% \arb[novoc]{Y} & \dmg{Y} & \loc{Y} & \brill{Y} & |Y| & |Y| \\
+% \arb[novoc]{T} & \dmg{aT} & \loc{aT} & \brill{aT} & |p| & |p| \\
+% \midrule
+% \arb[novoc]{|"'} & \dmg{|"'} & \loc{|"'} & \brill{|"'} & \verb|'| & |C| \\
+% \arb[novoc]{A"'} & \dmg{A"'} & \loc{A"'} & \brill{A"'} & \verb+|+ & |M| \\
+% \arb[novoc]{a"'} & \dmg{a"'} & \loc{a"'} & \brill{a"'} & \verb|>| & |O| \\
+% \arb[novoc]{w"'} & \dmg{w"'} & \loc{w"'} & \brill{w"'} & \verb|&| & |W| \\
+% \arb[novoc]{i"'} & \dmg{i"'} & \loc{i"'} & \brill{i"'} & \verb|<| & |I| \\
+% \arb[novoc]{y"'} & \dmg{y"'} & \loc{y"'} & \brill{y"'} & \verb|]| & |Q| \\
+% \midrule
+% \arb[novoc]{BB} & --- & --- & --- & \verb|~| & |~| \\
+% \arb[novoc]{"a} & ' & ' & --- & |[| & |L| \\
+% \midrule
+% \arb[voc]{Ba} & \dmg{Ba} & \loc{Ba} & \brill{Ba} & \verb|a| & |a| \\
+% \arb[voc]{Bu} & \dmg{Bu} & \loc{Bu} & \brill{Bu} & \verb|u| & |u| \\
+% \arb[voc]{Bi} & \dmg{Bi} & \loc{Bi} & \brill{Bi} & \verb|i| & |i| \\
+% \arb[voc]{BaN} & \dmg{BaN} & \loc{BaN} & \brill{BaN} & \verb|F| & |F| \\
+% \arb[voc]{BuN} & \dmg{BuN} & \loc{BuN} & \brill{BuN} & \verb|N| & |N| \\
+% \arb[voc]{BiN} & \dmg{BiN} & \loc{BiN} & \brill{BiN} & \verb|K| & |K| \\
+% \arb[voc]{B"} & --- & --- & --- & \verb|o| & |o| \\
+% \midrule
+% \arb[novoc]{B_a} & \dmg{B_a} & \loc{B_a} & \brill{B_a} & |`| & |e| \\
+% \midrule
+% \arb[novoc]{--} (\arb[trans]{ta.twIl}) & --- & --- & --- & |_| & |_| \\
+% \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 |voc|, |fullvoc|, |novoc| or |trans| options will
+% have any effect on plain Unicode Arabic for the time being.
+%
+% That said, there are two ways of inserting Unicode
+% Arabic:
+% \begin{enumerate}
+% \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{code}
+ \begin{txarab}
+ <Unicode Arabic text>
+ \end{txarab}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% \end{enumerate}
+%
+% \needspace{4\baselineskip}
+% \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 any single-argument command with up to
+% \emph{two optional arguments}---that is:
+% \cs{command}\oarg{opt1}\oarg{opt2}\marg{arg}---such as
+% \cs{emph}\marg{text}, \cs{textbf}\marg{text} and the like, is
+% assumed to have Arabic text in its mandatory argument:---
+% \begin{quote}
+% |\abjad{45}| |kitAbu-hu| |\emph{fI| |'l-\uc{`AdAt-i}}|
+% \arb[voc]{\abjad{45} kitAbu-hu \emph{fI 'l-\uc{`AdAt-i}}}
+% \arb[trans]{\abjad{45} kitAbu-hu \emph{fI
+% 'l-\uc{`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.}
+% \NewDocumentCommand{\rlframebox}{o o m}{
+% \IfNoValueTF{#2}{\IfNoValueTF{#1}{
+% \framebox{\setRL#3}}{\framebox[#1]{\setRL#3}}
+% }{\framebox[#1][#2]{\setRL#3}}}
+%
+% |\arb{\abjad{45} \rlframebox[1in][s]{kitAbu-hu fI 'l-`AdAti}}|\\
+% \arb{\abjad{45} \rlframebox[1in][s]{kitAbu-hu fI
+% 'l-`AdAti}}\,\footnote{\cs{rlframefox} has been adapted from
+% \cs{framebox} for insertions of right-to-left text.}
+% \end{quote}
+%
+% The same applies to footnotes:---
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \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{example}
+% \iffalse
+%</example>
+% \fi
+%
+% Some commands, however, do not expect running text in their
+% arguments, or one may wish to insert English text e.g. 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.
+%
+% \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} can be used to insert English
+% footnotes in running Arabic text:---
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \begin{arab}[fullvoc]
+ \uc{z}ayd-uN\arbnull{ibnu}\LRfootnote{%
+ \enquote{\arb[trans]{\uc{z}ayd} is the son of
+ \arb[trans]{\uc{`a}mr}}: the second noun is not in
+ apposition to the first, but forms part of the
+ predicate\ldots} \arbnull{zayduN}ibn-u \uc{`a}mr-iNU
+ \end{arab}
+\end{example}
+% \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:---\\
+% \tcboxverb{\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{scrextend}
+% package.\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}\oarg{left}\marg{right} 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.
+%
+% \label{ref:setrl-setlr}
+% \DescribeMacro{\setRL} \DescribeMacro{\setLR} \cs{setRL} and
+% \cs{setLR} can 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{example}
+ \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{example}
+% \iffalse
+%</example>
+% \fi
+%
+% \subsection{New commands}
+% \label{sec:declare-new-commands}
+% \NEWfeature{v1.9}%
+% In some particular cases, it may be useful to define new commands to
+% be inserted in Arabic environments. From the general principle laid
+% \vpageref{ref:cmd-inside-arabic}, it follows that any command that
+% is found inside an Arabic environment is assumed to have Arabic text
+% in its argument which \package{arabluatex} will process as such
+% before passing it on to the command itself for any further
+% processing. As a result of this feature, such a command as:\\
+% \tcboxverb{\newcommand{\fvarabic}[1]{\arb[fullvoc]{#1}}}\\
+% will work as expected, but will always output non-vocalized Arabic
+% if it is inserted in a |novoc| Arabic environment because its
+% argument will have been processed by the |novoc| rules before the
+% command |\fvarabic| itself can see it.
+%
+% \DescribeMacro{\MkArbBreak} The \cs{MkArbBreak}\marg{csv list of
+% commands} command can be used in the preamble to give any
+% command---either new or already existing---the precedence over
+% \package{arabluatex} inside Arabic environments. It takes as
+% argument a comma-separated list of commands each of which must be
+% stripped of its leading character
+% |\|, like so:---\\
+% \tcboxverb{\MkArbBreak{onecmd, anothercmd, yetanothercmd, ...}}
+%
+% For example, here follows a way to define a new command |\fvred| to
+% distinguish words with a different color and always print them in
+% fully vocalized Arabic:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \MkArbBreak{fvred}
+ \newcommand{\fvred}[1]{\arbcolor[red]{\arb[fullvoc]{#1}}}
+ \begin{arab}[voc]
+ _tumma "intalaqa _dU 'l-qarn-ayni 'il_A 'ummaT-iN 'u_hr_A fI
+ \fvred{((ma.tli`-i 'l-^sams-i))} wa-lA binA'-a la-hum
+ yu'amminu-hum mina 'l-^sams-i.
+ \end{arab}
+\end{example}
+% \iffalse
+%</example>
+% \fi
+%
+% It must be noted that the arguments, either optional or mandatory,
+% of commands declared with \cs{MkArbBreak} are not to be processed by
+% \package{arabluatex}. Therefore, as in the previous example, any of
+% their argument to be rendered in Arabic must be inserted again in
+% \cs{arb}. \NEWfeature{v1.12}These commands themselves may have up to
+% two optional and/or mandatory arguments followed by one optional
+% argument, like so:---
+% \begin{enumerate}
+% \item \cs{command} (no argument, lowermost combination)
+% \item \cs{command}\oarg{opt1} (one optional argument)
+% \item \cs{command}\marg{arg1} (one mandatory argument)
+% \item \cs{command}\oarg{opt1}\marg{arg1} (one optional and one
+% mandatory argument)
+% \item{} [\ldots]
+% \item \cs{command}\oarg{opt1}\oarg{opt2}\marg{arg1}\marg{arg2}
+% \item
+% \cs{command}\oarg{opt1}\oarg{opt2}\marg{arg1}\marg{arg2}\oarg{opt3}
+% (uppermost combination)
+% \end{enumerate}
+%
+% \DescribeMacro{\MkArbBreak*}\NEWfeature{v1.12} As said above,
+% \cs{MkArbBreak} prevents \package{arabluatex} from processing the
+% arguments of \enquote*{declared} commands as Arabic text. This
+% technique proves sufficient in most cases. However, a
+% \enquote*{starred} version of this
+% command---\cs{MkArbBreak*}\marg{csv list of commands}---is also
+% provided. It goes a step further, as it directs \package{arabluatex}
+% to \emph{close} the current Arabic environment before any of the
+% \enquote*{declared} commands, then \emph{resume} it just after.
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{tcblisting}{text only}
+ It must be noted that \cs{MkArbBreak*} must be used with the utmost
+ care and \emph{should never be used} if \cs{MkArbBreak} gives
+ satisfaction. At any rate, the latter must always be tested before
+ the former.
+\end{tcblisting}
+% \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
+% \tcboxverb{\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{code}
+ \begin{arab}
+ \begin{<environment>}[<options>]
+ <Arabic text>
+ \end{<environment>}
+ \end{arab}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+%
+% In the following example, the \package{quoting} package is used:---
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \setquotestyle{arabic}
+ \begin{arab}[fullvoc]
+ kAna \uc{'abU} \uc{'l-hu_dayli} 'ahd_A 'il_A \uc{muwaysiN}
+ dajAjaTaN. wa-kAnat dajAjatu-hu 'llatI 'ahdA-hA dUna mA kAna
+ yuttaxa_du li-\uc{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 <\uc{'abU} \uc{'l-hu_dayli}>
+ yu`rafu bi-'l-'imsAki 'l-^sadIdi. fa-qAla: \enquote{wa-kayfa
+ ra'ayta yA \uc{'abA} \uc{`imrAna} tilka 'l-dajAjaTa?} qAla:
+ \enquote{kAnat `ajabaN mina 'l-`ajabi!} fa-yaqUlu:
+ \begin{quoting}[begintext=\textquotedblright,
+ endtext=\textquotedblleft]
+ 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 \uc{'abU} \uc{'l-hu_dayli}.
+ \end{arab}
+\end{example}
+% \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
+% packages that provide additional refinements such as
+% \package{paralist} or \package{enumitem}.
+%
+% To take a first example, should one wish to typeset a list of
+% manuscripts, the |description| environment can be used like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \setRL\paragraph{\arb[novoc]{rumUzi 'l-kitAbi}}\setLR
+ \begin{arab}[novoc]
+ \begin{description}
+ \item[b] max.tU.tu 'l-maktabaTi 'l-'ahliyyaTi bi-\uc{bArIs} 2860
+ `arabiyyuN.
+ \item[s] max.tU.tu 'l-maktabaTi 'l-'ahliyyaTi bi-\uc{bArIs} 2859
+ `arabiyyuN.
+ \item[m] max.tU.tu majlisi \arb[novoc]{^sUrAY malY} .tahrAna 521.
+ \end{description}
+ \end{arab}
+\end{example}
+% \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{example}
+ \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{example}
+% \iffalse
+%</example>
+% \fi
+%
+% \label{ref:abjad-list}
+% As a third example, abjad-numbered lists can be typeset in
+% conjunction with the \package{enumitem} package,\footnote{See the
+% documentation of \package{enumitem} for more details:
+% \url{https://ctan.org/pkg/enumitem}} like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ % preamble:---
+ \usepackage{enumitem}
+ \newlist{enumabjad}{enumerate}{10}
+ \setlist[enumabjad]{nosep, label={\abjad{\arabic*}}}
+ \usepackage{multicol}
+\end{code}
+\begin{example}
+ From \textcite[i. 29 B--C]{Wright}:--- The derived forms of the
+ triliteral verb are usually reckoned fifteen in number, but the
+ learner may pass over the last four, because (with the exception
+ of the twelfth) they are of very rare occurrence.
+ \RLmulticolcolumns
+ \begin{multicols}{3}
+ \begin{arab}[fullvoc]
+ \begin{enumabjad}
+ \item fa`ala
+ \item fa``ala
+ \item fA`ala
+ \item 'af`ala
+ \item tafa``ala
+ \item tafA`ala
+ \item infa`ala
+ \item ifta`ala
+ \item if`alla
+ \item istaf`ala
+ \item if`Alla
+ \item if`aw`ala
+ \item if`awwala
+ \item if`anlala
+ \item if`anl_A
+ \end{enumabjad}
+ \end{arab}
+ \end{multicols}
+\end{example}
+% \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 |StandardLists=true|
+% option, like so:---%
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ \usepackage[french]{babel}
+ \frenchsetup{StandardLists=true}
+\end{code}
+% \iffalse
+%</example>
+% \fi%
+% This option will prevent \package{babel-french} from interfering
+% with the layout of the document. Then the \package{paralist} or
+% \package{enumitem} packages can 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{code}
+ \usepackage{csquotes}
+ \DeclareQuoteStyle{arabic}
+ {\textquotedblright}{\textquotedblleft}
+ {\textquoteright}{\textquoteleft}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% Then, use this newly defined style with \cs{setquotestyle}, like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \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{example}
+% \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{Two-argument special commands}
+% \label{sec:two-arg-cmds}
+%
+% \paragraph{textcolor}
+% \label{sec:textcolor}
+% The two-argument command \cs{textcolor}\marg{color}\marg{Ara\-bic
+% text} is supported inside \cs{begin}|{arab}| \ldots\
+% \cs{end}|{arab}|. One simple example
+% follows:\footnote{\package{arabluatex} provides its own
+% \cs{arbcolor} command which is able to render syllabes or diacritics
+% in colors. See \vref{sec:color}.}--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \begin{arab}
+ \textcolor{red}{\uc{m}uha_d_dabu \uc{'l-d}Ini \uc{`a}bdu
+ \uc{'l-r}a.hImi bnu \uc{`a}liyyiN} huwa ^say_hu-nA 'l-'imAmu
+ 'l-.sadru 'l-kabIru 'l-`Alimu 'l-fA.dilu \uc{m}uha_d_dabu
+ \uc{'l-d}Ini \uc{'a}bU \uc{m}u.hammadiN \uc{`a}bdu
+ \uc{'l-r}a.hImi bnu \uc{`a}liyyi bni \uc{.h}AmidiN wa-yu`rafu
+ bi-\uc{'l-d}a_hwari.
+ \end{arab}
+ \begin{arab}[trans]
+ \textcolor{red}{\uc{m}uha_d_dabu \uc{'l-d}Ini \uc{`a}bdu
+ \uc{'l-r}a.hImi bnu \uc{`a}liyyiN} huwa ^say_hu-nA 'l-'imAmu
+ 'l-.sadru 'l-kabIru 'l-`Alimu 'l-fA.dilu \uc{m}uha_d_dabu
+ \uc{'l-d}Ini \uc{'a}bU \uc{m}u.hammadiN \uc{`a}bdu
+ \uc{'l-r}a.hImi bnu \uc{`a}liyyi bni \uc{.h}AmidiN wa-yu`rafu
+ bi-\uc{'l-d}a_hwari.
+ \end{arab}
+\end{example}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{\package{reledmac}}
+% \label{sec:reledmac}
+% The two-argument command \cs{edtext}\marg{lemma}\marg{commands} is
+% supported inside \cs{begin}|{arab}| \ldots\
+% \cs{end}|{arab}|.\footnote{\cs{pstart} and \cs{pend} are also
+% supported inside the |arab| environment.} As an example, one may get
+% \package{arabluatex} and \package{reledmac} to work together like
+% so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ \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{code}
+% \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]{\uc{qur'An}}. As \package{quran} draws
+% the text of the \arb[trans]{\uc{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]{\uc{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
+% |nopar| option, after \package{arabluatex} itself has been loaded,
+% like so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ \usepackage{arabluatex}
+ \usepackage[nopar]{quran}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+%
+% As an example, the following code will typeset the \arb[trans]{sUraT
+% al-\uc{fAti.haT}}:---
+% \iffalse
+%<*example>
+% \fi
+\begin{example}
+ \begin{txarab}
+ \quransurah[1]
+ \end{txarab}
+\end{example}
+% \iffalse
+%</example>
+% \fi
+%
+% \section{Exporting Unicode Arabic to an external file}
+% \label{sec:arabtex2utf}
+% \NEWfeature{v.1.13}\package{arabluatex} is able to produce a
+% duplicate of the original |.tex| source file in which all |arabtex|
+% or |buckwalter| strings will have been replaced with Unicode
+% equivalents, either in Arabic script or in any accepted standard of
+% transliteration. Exporting \textsc{ascii} strings to Unicode while
+% preserving the exact selected global or local options is a fairly
+% complex operation which may require {\LuaLaTeX} to be run several
+% times as will be explained below.
+%
+% \subsection{Commands and environments}
+% \paragraph{\texttt{export} global option}
+% \DescribeOption{export} First, \package{arabluatex} must be loaded
+% with the |export| global option enabled,\footnote{See above
+% \vpageref{ref:export-global-opt} for more information.} like
+% so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ % preamble
+ \usepackage[export]{arabluatex}
+ % or:
+ \usepackage[export=true]{arabluatex}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+%
+% Once that is done, compiling the current file will produce a new
+% empty external |.tex| file with the same preamble as the original
+% file.
+%
+% \DescribeMacro{\SetArbOutSuffix} By default, |_out| is appended as a
+% suffix to the external file name. Any other suffix may be set with
+% the command \cs{SetArbOutSuffix}\marg{suffix}.
+%
+% \paragraph{Exporting running paragraphs}
+% \DescribeEnv{arabexport} Then, the |arabexport| environment is
+% provided to actually exporting running paragraphs with or without
+% Arabic environments to the external selected file, like so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ \begin{arabexport}
+ <Running paragraphs of either Arabic or non-Arabic text>
+ \end{arabexport}
+\end{code}
+% \iffalse
+%</example>
+% \fi
+%
+% \package{arabluatex} converts to Unicode and writes to the external
+% file what is found inside Arabic environments. As to non-Arabic
+% text, it is appended untouched to this file, which is formatted as
+% follows:---
+% \begin{enumerate}
+% \item Unicode Arabic text, either in Arabic script or in
+% transliteration, is inserted as argument of
+% \cs{txarb}\footnote{See above \vref{sec:unicode-input}.} or
+% \cs{txtrans}\footnote{\cs{txtrans} is used internally by several
+% Lua functions to format transliterated Arabic. Therefore, it is
+% not documented.} accordingly.
+% \item \DescribeMacro{\arbpardir}Additionally, Arabic paragraphs may
+% receive \cs{arbpardir}, which \package{arabluatex} uses to
+% determine the direction of Arabic paragraphs to be set by default,
+% or either \cs{setRL} or \cs{setLR} depending on what may have been
+% set locally.\footnote{See above \vpageref{ref:setrl-setlr}.}
+% \item \DescribeMacro{\prname*}Proper names are inserted as arguments
+% of \cs{prname*}.\footnote{See above \vpageref{ref:prname-star}.}
+% \end{enumerate}
+%
+% \paragraph{Appending words or commands to the external file only}
+% \DescribeMacro{\ArbOutFile}\DescribeMacro{\ArbOutFile*}
+% \cs{ArbOutFile}\oarg{newline}\allowbreak\marg{argument} silently
+% exports its argument to the external file. It may take the string
+% |newline| as an optional argument, in which case a carriage return
+% is appended to the contents of the
+% argument. \cs{ArbOutFile*}\oarg{newline}\marg{argument} does the
+% same as \cs{ArbOutFile}, but also inserts its argument into the
+% current |.tex| source file.
+%
+% \paragraph{Exporting Arabic poetry}
+% Lines of Arabic poetry are exported as described above
+% \vpageref{ref:poetry-export} when the |export| option that is
+% specific to the |arabverse| environment is set to |true|. As a
+% result of this particular feature, |arabverse| environments must be
+% left outside |\begin{arabexport}| \ldots\ |\end{arabexport}|.
+%
+% Please note that inside |arabverse| environments \cs{bayt} is
+% replaced with \cs{bayt*}.\footnote{See above \vref{ref:bayt-star} for
+% more information.}
+%
+% \subsection{Nested Arabic environments}
+% The exporting mechanism described above converts only the outermost
+% level of nested Arabic environments. This may be sufficient in some
+% cases, but if nested Arabic environments be found in the original
+% |.tex| source file, then the Unicode converted file must be opened
+% and compiled in turn, and so on until the innermost Arabic
+% environment be converted and exported. In such cases,
+% \package{arabluatex} issues a warning, so that authors do not have
+% to check the entire file that just has been exported:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ Package arabluatex Warning: There are still 'arabtex' strings
+ to be converted. Please open <jobname><suffix>.tex and compile
+ it one more time.
+\end{code}
+% \iffalse
+%</example>
+% \fi
+% Where \meta{jobname} is the name of the original |.tex| source file,
+% and \meta{suffix} the suffix appended to the file that is to be
+% opened and compiled again.
+%
+% \subsection{Further processing of Unicode converted files}
+% \label{sec:further-processing-utf-files}
+% Unicode files can be further processed by document converters such
+% as John McFarlane's |pandoc|\footnote{See
+% \url{http://pandoc.org/}}. To take here one simple example, here is
+% how |file_out.tex| can be converted from {\LuaLaTeX} into Open
+% Document format (|.odt|):---%
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ pandoc file_out.tex -s -o file_out.odt
+\end{code}
+% \iffalse
+%</example>
+% \fi
+%
+% However, specific commands such as \cs{txarb}, \cs{txtrans} or
+% \cs{prname*}, which are not known to |pandoc|, must be redefined
+% explicitly in the preamble to prevent the converter from gobbling
+% their arguments, like so:---%
+% \iffalse
+%<*example>
+% \fi
+\begin{code}
+ % preamble:
+ \usepackage{arabluatex} % note that 'export' has been removed
+ \renewcommand{\txarb}[1]{#1}
+ \renewcommand{\txtrans}[1]{\emph{#1}}
+ \renewcommand{\arbup}[1]{\textsuperscript{#1}}
+ % now that \prname{} has been replaced with \prname*{} it should
+ % be safe to say:
+ \renewcommand{\prname}[2]{#2}
+ % &c
+\end{code}
+% \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{enumerate}
+% \item Short-term:
+% \begin{enumerate}
+% \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{enumerate}
+% \item Medium-term:
+% \begin{enumerate}
+% \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{enumerate}
+% \end{enumerate}
+%
+% \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}
+\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}
+\RequirePackage{xkeyval}
+\DeclareOptionX{voc}{\def\al@mode{voc}}
+\DeclareOptionX{fullvoc}{\def\al@mode{fullvoc}}
+\DeclareOptionX{novoc}{\def\al@mode{novoc}}
+\DeclareOptionX{trans}{\def\al@mode{trans}}
+\define@boolkey{arabluatex.sty}[@pkg@]{export}[true]{%
+ \if@pkg@export%
+ \AtBeginDocument{\luadirect{arabluatex.openstream()}%
+ \MkArbBreak{@al@ob,@al@cb,@al@cb@sp}}
+ \AtEndDocument{\luadirect{arabluatex.closestream()}}
+ \else\fi}
+\ExecuteOptionsX{voc}
+\ProcessOptionsX\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{xcolor}
+\RequirePackage{luacolor}
+\RequirePackage{etoolbox}
+\RequirePackage{arabluatex-patch}
+\RequirePackage{fontspec}
+\RequirePackage{luacode}
+\RequirePackage{xparse}
+\RequirePackage{adjustbox}
+\RequirePackage{xstring}
+\PassOptionsToPackage{normalem}{ulem}
+\RequirePackage{ulem}
+% \end{macrocode}
+% The following boolean will be set to |true| in |RL| mode:
+% \begin{macrocode}
+\providebool{al@rlmode}
+% \end{macrocode}
+% Here begins the real work: load |arabluatex.lua|:
+% \begin{macrocode}
+\luadirect{dofile(kpse.find_file("arabluatex.lua"))}
+% \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.^^J
+ I will try to load Amiri}%
+\newfontfamily\arabicfont[Script=Arabic]{Amiri}\fi}%
+% \end{macrocode}
+% \begin{macro}{\setRL}
+% This neutralizes what may be defined by other packages:
+% \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}{\MkArbBreak}
+% \changes{v1.9}{2017/07/05}{New \cs{MkArbBreak} command for
+% inserting user-defined macros in Arabic environments} The
+% \cs{MkArbBreak}\marg{csv list of commands} command can be used to
+% give any command---either new or already existing---the precedence
+% over \package{arabluatex} inside Arabic environments. It is
+% actually coded in Lua.
+% \begin{macro}{\MkArbBreak*}
+% \changes{v1.12}{2018/06/24}{\enquote*{starred} version which
+% closes Arabic environments before processing declared commands.}
+% \cs{MkArbBreak*} goes a step further as it directs
+% \package{arabluatex} to close the current Arabic environment before
+% processing any \enquote*{declared} command then resume it just
+% after.
+% \begin{macrocode}
+\NewDocumentCommand{\MkArbBreak}{s m}{%
+ \IfBooleanTF{#1}
+ {\luadirect{arabluatex.mkarbbreak(\luastringN{#2}, "out")}}
+ {\luadirect{arabluatex.mkarbbreak(\luastringN{#2}, "dflt")}}
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\aemph} Arabic emphasis. Needs to be redefined as
+% well. The function is actually coded in Lua.
+% \changes{v1.16}{2018/11/06}{Now uses \textsf{ulem}}
+% \begin{macro}{\aemph*} The \enquote*{starred} version of this
+% command alway puts the stroke over its argument.
+% \changes{v1.9.2}{2017/10/24}{Starred version which always puts the
+% stroke over its argument}As of v1.16 \package{arabluatex} uses
+% \package{ulem} to render the strokes, thus allowing line breaks
+% and manual hyphenation for transliterated Arabic.
+% \begin{macrocode}
+\def\oline{\@ifstar\@oline\@@oline}
+\def\@oline#1{\ensuremath{\overline{\mbox{#1}}}}
+\def\@@oline{\bgroup \ULdepth=-3ex \ULset}
+\AtBeginDocument{\ifdef{\aemph}%
+ {\RenewDocumentCommand{\aemph}{s m}{%
+ \IfBooleanTF{#1}{%
+ \luadirect{tex.sprint(arabluatex.aemph(\luastringN{#2},
+ "over"))}}
+ {\luadirect{tex.sprint(arabluatex.aemph(\luastringN{#2},
+ "dflt"))}}}}
+ {\NewDocumentCommand{\aemph}{s m}{%
+ \IfBooleanTF{#1}{%
+ \luadirect{tex.sprint(arabluatex.aemph(\luastringN{#2},
+ "over"))}}
+ {\luadirect{tex.sprint(arabluatex.aemph(\luastringN{#2},
+ "dflt"))}}}}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\arbcolor}\changes{v1.12}{2018/06/24}{Standard color
+% command for Arabic environments}
+% \cs{arbcolor}\oarg{color}\marg{Arabic text} takes the Arabic text to
+% be colored as argument.
+% \begin{macrocode}
+\NewDocumentCommand{\arbcolor}{o m}{%
+ \IfNoValueTF{#1}{#2}{\textcolor{#1}{#2}}}
+% \end{macrocode}
+%
+% \end{macro}
+% \begin{macro}{\SetInputScheme}
+% \changes{v1.4}{2016/07/05}{\cs{SetInputScheme} can 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}
+% \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} can 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} can 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{#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}{\uc} Proper Arabic names or book titles should be
+% passed to the \cs{uc} command so that they have their first letters
+% uppercased. \cs{uc} is actually coded in Lua.
+% \begin{macrocode}
+\NewDocumentCommand{\uc}{m}%
+ {\luadirect{tex.sprint(arabluatex.uc(\luastringN{#1}))}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\Uc} \cs{uc} can be used safely in all of the modes
+% that are provided by \package{arabluatex} as any of the |voc|,
+% |fullvoc| and |novoc| modes discard it on top of any other
+% functions to be run. \cs{Uc} does the same as \cs{uc} except
+% that \emph{it is never discarded}. For that reason, \cs{Uc}
+% \emph{should never be used outside the} |trans|
+% \emph{mode}. \package{arabluatex} uses \cs{Uc} internally so as
+% to prevent \cs{uc} from being discarded in case words that are to
+% be transliterated are inserted into Arabic commands or
+% environments where transliteration is not required. Therefore, it
+% is not documented.
+% \begin{macrocode}
+\let\Uc\uc
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\prname}\changes{v1.10}{2018/01/03}{New command for
+% typesetting Arabic proper names in transliteration} \cs{prname} is
+% to be used outside Arabic environments for proper names. It takes as
+% argument one or more Arabic words, each of which will be rendered in
+% upright roman style with its first letter uppercased.
+% \begin{macro}{\prname*}\changes{v1.13}{2018/08/27}{Renders proper
+% names already converted to Unicode in upright roman style}
+% Unlike \cs{prname}, \cs{prname*} does not take |arabtex| or
+% |buckwalter| input as argument, but already Unicode converted
+% names and renders them in upright roman style.
+% \begin{macrocode}
+\NewDocumentCommand{\prname}{s m}{%
+ \bgroup\SetTranslitStyle{\relax}%
+ \IfBooleanTF{#1}{\txtrans{#2}}{\arb[trans]{\uc{#2}}}\egroup}
+% \end{macrocode}
+% \end{macro}
+% \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}
+\NewDocumentCommand{\txarb}{+m}{%
+ \bgroup\textdir TRT\arabicfont#1\egroup}
+\NewDocumentCommand{\txtrans}{+m}{%
+ \bgroup\textdir TLT\al@trans@font\al@trans@style#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}
+\NewDocumentCommand{\arb}{O{\al@mode} +m}%
+{\edef\@tempa{#1}%
+ \ifx\@tempa\al@mode@voc%
+ \bgroup\booltrue{al@rlmode}\textdir TRT\arabicfont%
+ \luadirect{tex.sprint(arabluatex.processvoc(\luastringN{#2},
+ \luastringO{\al@arb@rules}, \luastringO{\al@input@scheme}))}\egroup%
+ \else%
+ \ifx\@tempa\al@mode@fullvoc%
+ \bgroup\booltrue{al@rlmode}\textdir TRT\arabicfont%
+ \luadirect{tex.sprint(arabluatex.processfullvoc(\luastringN{#2},
+ \luastringO{\al@arb@rules}, \luastringO{\al@input@scheme}))}\egroup%
+ \else%
+ \ifx\@tempa\al@mode@novoc%
+ \bgroup\booltrue{al@rlmode}\textdir TRT\arabicfont%
+ \luadirect{tex.sprint(arabluatex.processnovoc(\luastringN{#2},
+ \luastringO{\al@arb@rules}, \luastringO{\al@input@scheme}))}\egroup%
+ \else%
+ \ifx\@tempa\al@mode@trans%
+ \bgroup\textdir TLT\al@trans@font\al@trans@style%
+ \luadirect{tex.sprint(arabluatex.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{macro}{\arbmark}
+% \changes{v1.11}{2018/03/31}{New command for inserting additional
+% marks in Arabic environments}
+% \cs{arbmark}\oarg{rl\textbar{}lr}\marg{shorthand} takes one
+% argument from a list of defined elements.
+% \changes{v1.13}{2018/08/27}{New optional argument: either
+% \texttt{rl} or \texttt{lr}} The mark to be inserted is determined
+% by contextual analysis or by an optional argument, either |rl| or
+% |lr|. This command is coded in Lua.
+% \begin{macrocode}
+\NewDocumentCommand{\arbmark}{O{} m}{%
+ \bgroup%
+ \SetInputScheme{arabtex}%
+ \luadirect{tex.sprint(arabluatex.processarbmarks(\luastringN{#2},
+ \luastringN{#1}))}%
+ \egroup}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\newarbmark}
+% \changes{v1.11}{2018/03/31}{Allows defining additional sets of Arabic
+% marks} \cs{newarbmark} lets the user define additional Arabic
+% marks. As \cs{arbmark}, this command is coded in Lua. It takes
+% three arguments: the abbreviated form to be used as argument of
+% \cs{arbmark}, the rendition in Arabic script and the rendition in
+% romanized Arabic.
+% \begin{macrocode}
+\NewDocumentCommand{\newarbmark}{m m m}{%
+ \luadirect{arabluatex.newarbmark(\luastringN{#1}, \luastringN{#2},
+ \luastringN{#3})}}
+% \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}
+\NewDocumentEnvironment{arab}{O{\al@mode} +b}%
+{\par\edef\@tempa{#1}%
+ \ifx\@tempa\al@mode@voc%
+ \booltrue{al@rlmode}%
+ \bgroup\pardir TRT\textdir TRT\arabicfont%
+ \luadirect{tex.sprint(arabluatex.processvoc(\luastringN{#2},
+ \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(arabluatex.processfullvoc(\luastringN{#2},
+ \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(arabluatex.processnovoc(\luastringN{#2},
+ \luastringO{\al@arb@rules}, \luastringO{\al@input@scheme}))}\egroup%
+ \else%
+ \ifx\@tempa\al@mode@trans%
+ \bgroup\pardir TLT\textdir TLT\al@trans@font\al@trans@style%
+ \luadirect{tex.sprint(arabluatex.processtrans(\luastringN{#2},
+ \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|, |color|,
+% |utf|, |delim| and |export|; all of them are defined here just
+% before the |arabverse|
+% environment. \changes{v1.13}{2018/08/27}{New options
+% \texttt{color} and \texttt{export} to \texttt{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@key[al]{verse}{color}[]{\color{#1}}
+\define@boolkey[al]{verse}{utf}[true]{}
+\define@boolkey[al]{verse}{delim}[true]{}
+\define@boolkey[al]{verse}{export}[true]{}
+\define@choicekey[al]{verse}{mode}{fullvoc, voc, novoc,
+ trans}{\def\al@mode{#1}}
+\presetkeys[al]{verse}{metre={}, utf=false,
+ delim=false}{}
+% \end{macrocode}
+% Then follows the environment itself:
+% \begin{macrocode}
+\NewDocumentEnvironment{arabverse}{O{}}%
+{\bgroup\setkeys[al]{verse}[width, gutter, color, utf, delim,
+ metre]{#1}%
+ \if@pkg@export\ifal@verse@export%
+ \ArbOutFile{\begin{arabverse}}%
+ % \ifx\al@mode\al@mode@trans%
+ % \luadirect{arabluatex.tooutfile(\luastringN{[#1]})}%
+ % \else%
+ \IfSubStr[1]{#1}{utf}%
+ {\luadirect{arabluatex.tooutfile(\luastringN{[#1]})}}%
+ {\luadirect{arabluatex.tooutfile(\luastringN{[#1, utf]})}}%
+ % \fi
+ \else\fi\else\fi\egroup%
+ \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%
+ \ifal@verse@utf%
+ \ifx\al@mode\al@mode@trans\setLR\else\setRL\fi%
+ \else%
+ \ifx\al@mode\al@mode@trans\setLR\else\setRL\fi%
+ \fi%
+ \arab@v@export[#1]
+ }%
+ {\endarab@v@export
+ \hfill\setkeys[al]{verse}[width, gutter, color, utf, delim, mode,
+ export]{#1}%
+ \egroup\par%
+ \bgroup\setkeys[al]{verse}[width, gutter, color, utf, delim, mode,
+ metre]{#1}%
+ \if@pkg@export\ifal@verse@export%
+ \ArbOutFile{\end{arabverse}}
+ \else\fi\else\fi\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 can 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}{s m o m}{%
+ \IfBooleanTF{#1}{\relax}{\relax}%
+ \ifdefined\savenotes\savenotes\else\fi%
+ \edef\al@tatweel{--}%
+ \adjustbox{width=\al@bayt@width, height=\Height}{\arb@utf{#2}}%
+ \IfNoValueTF{#3}{%
+ \ifal@verse@delim\makebox[\al@gutter@width][c]{\al@hemistich@delim}%
+ \else%
+ \hspace{\al@gutter@width}%
+ \fi
+ }{%
+ \edef\@tempa{#3}%
+ \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{#3}}%
+ \else%
+ \makebox[\al@gutter@width][s]{\arb@utf{#3}}%
+ \fi\fi}%
+ \adjustbox{width=\al@bayt@width, height=\Height}{\arb@utf{#4}}%
+ \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}%
+ {\ifbool{al@rlmode}%
+ {\oline*{%
+ \luadirect{tex.sprint(arabluatex.abjadify(\luastring{#1}))}}}
+ {\luadirect{tex.sprint(arabluatex.abjadify(\luastring{#1}))}}}
+ \else%
+ \NewDocumentCommand{\abjad}{m}%
+ {\ifbool{al@rlmode}%
+ {\oline*{%
+ \luadirect{tex.sprint(arabluatex.abjadify(\luastring{#1}))}}}
+ {\luadirect{tex.sprint(arabluatex.abjadify(\luastring{#1}))}}}
+ \fi}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ayah}\changes{v1.15}{2018/10/09}{Prints End of Ayah
+% sign}\cs{ayah}\marg{number} prints up to 3-digit numbers inside
+% \enquote*{end of Ayah} sign (|U+06DD|) or inside parentheses
+% depending on the mode which is selected.
+% \begin{macrocode}
+\NewDocumentCommand{\ayah}{m}{%
+ \luadirect{tex.sprint(arabluatex.ayah(\luastringN{#1}))}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\arbnull}
+% \changes{v1.7}{2016/12/24}{New \cs{arbnull} command for putting
+% back on any contextual analysis rule broken by other commands.}
+% The \cs{arbnull} command does nothing by itself. It is processed
+% only if it is found in Arabic context so as to put back on
+% contextual analysis in case it has been broken by other commands.
+% \begin{macrocode}
+\NewDocumentCommand{\arbnull}{m}{\relax}
+% \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(arabluatex.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}{o m}{%
+ \IfNoValueTF{#1}
+ {\marginpar{\textdir TLT #2}}
+ {\marginpar[\textdir TLT #1]{\textdir TLT #2}}}
+% \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\textdir TLT\footnote{#1}\egroup}
+\DeclareDocumentCommand{\RLfootnote}{m}{\bgroup\pardir
+ TRT\textdir TRT\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}
+%
+% \paragraph*{Exporting Unicode Arabic to external file}
+% \begin{macro}{\SetArbOutSuffix}
+% \changes{v1.13}{2018/08/27}{Sets a suffix to be appended to the
+% filename of the external Unicode file.}By default, |_out| is the
+% suffix to be appended to the external file in which
+% \package{arabluatex} exports Unicode in place of
+% |arabtex| or |buckwalter| strings. Any other suffix may be
+% set with \cs{SetArbOutSuffix}\marg{suffix}.
+% \begin{macrocode}
+\NewDocumentCommand{\SetArbOutSuffix}{m}{
+ \luadirect{arabluatex.utffilesuffix(\luastringN{#1})}}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ArbOutFile}
+% \changes{v1.13}{2018/08/27}{Silently exports its argument in the
+% selected external file.}
+% \cs{ArbOutFile}\oarg{newline}\marg{string} silently exports
+% \meta{string} to the external selected file. It may take |newline|
+% as an optional argument in which case a carriage return is
+% appended to |string|.
+% \begin{macro}{\ArbOutFile*}
+% \cs{ArbOutFile*}\oarg{newline}\marg{string} does the same as
+% \cs{ArbOutFile} but also inserts \meta{string} in the current
+% |.tex| source file.
+% \begin{macrocode}
+\NewDocumentCommand{\ArbOutFile}{s O{no} +m}{%
+ \if@pkg@export%
+ \IfBooleanTF{#1}{%
+ #3\luadirect{arabluatex.tooutfile(\luastringN{#3}, "#2")}}{%
+ \luadirect{arabluatex.tooutfile(\luastringN{#3}, "#2")}}%
+ \else\IfBooleanTF{#1}{#3}{}\fi}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{environment}{arabexport}
+% \changes{v1.13}{2018/08/27}{Processes and print its argument in
+% the current file and exports it in full Unicode in the external
+% selected \texttt{.tex} file.} The |arabexport| environment
+% processes and prints its argument unchanged to the current |.pdf|
+% file. Additionally, if \package{arabluatex} is loaded with the
+% |export| option, this argument is exported to the external
+% selected |.tex| file with Unicode in place of the original
+% |arabtex| or |buckwalter| strings.
+% \begin{macrocode}
+\NewDocumentEnvironment{arabexport}{+b}{%
+ \if@pkg@export%
+ \par
+ #1
+ \luadirect{arabluatex.doexport("yes")}
+ \luadirect{tex.sprint(arabluatex.arbtoutf(\luastringN{#1}))}
+ \luadirect{arabluatex.doexport("no")}
+ \else\par#1\fi
+ }{\par}
+% \end{macrocode}
+% \end{environment}
+% \begin{environment}{arab@v@export} The |arab@v@export| environment
+% does for |arabverse| the same as |arabexport|. It is used
+% internally by |arabverse|.
+% \begin{macrocode}
+\NewDocumentEnvironment{arab@v@export}{O{} +b}{%
+ \setkeys[al]{verse}[width, gutter, color, utf, delim, mode,
+ metre]{#1}
+ \if@pkg@export\ifal@verse@export%
+ \par
+ #2
+ \luadirect{arabluatex.doexport("arabverse")}
+ \luadirect{tex.sprint(arabluatex.arbtoutf(\luastringN{#2}))}
+ \luadirect{arabluatex.doexport("no")}
+ \else\par#2\fi\else\par#2\fi
+}{\par}
+% \end{macrocode}
+% \end{environment}
+% \begin{macro}{\arbpardir}
+% \changes{v1.13}{2018/08/27}{Sets the direction of Arabic paragraphs
+% once they are converted to Unicode.} \cs{arbpardir} is automatically
+% inserted by \package{arabluatex} at the beginning of Arabic
+% paragraphs converted to Unicode so that they are printed in the
+% right direction.
+% \begin{macrocode}
+\NewDocumentCommand{\arbpardir}{}{%
+ \ifx\al@mode\al@mode@trans\setLR\else\setRL\fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection*{Errors and Warnings}
+% \begin{macrocode}
+\newcommand{\al@warning}[1]{\PackageWarning{arabluatex}{#1}}
+\newcommand{\al@error}[2]{\PackageError{arabluatex}{#1}{#2}}
+\newcommand{\al@wrong@nesting}{\al@error{%
+ (RL/LR)\string\footnote\space is not allowed\MessageBreak inside
+ \string\RL{} and \string\RL{} commands}{%
+ Get rid of the surrounding \string\RL{} or \string\LR{} command.}}
+\newcommand{\al@wrong@mark}{\al@warning{%
+ Unknown Arabic mark in \string\arbmark{}. Replaced
+ with\MessageBreak <??>. Please check your code}}
+% \end{macrocode}
+%
+% 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
diff --git a/macros/luatex/latex/arabluatex/arabluatex.ins b/macros/luatex/latex/arabluatex/arabluatex.ins
new file mode 100644
index 0000000000..ea5a73ebcf
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/arabluatex.ins
@@ -0,0 +1,109 @@
+%% This file is part of the `arabluatex' package
+%%
+%% ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
+%% Copyright (C) 2016--2019 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/>.
+%%
+%% This release of 'arabluatex' consists of the following source files:
+%% - arabluatex.ins
+%% - arabluatex.dtx
+%% - arabluatex.lua
+%% - arabluatex_voc.lua
+%% - arabluatex_fullvoc.lua
+%% - arabluatex_novoc.lua
+%% - arabluatex_trans.lua
+%%
+
+
+\input docstrip.tex
+\keepsilent
+
+\usedir{tex/lualatex/arabluatex}
+
+\preamble
+
+This is a generated file.
+
+This file is part of the `arabluatex' package
+
+ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
+Copyright (C) 2016--2019 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/>.
+
+This release of 'arabluatex' consists of the following source files:
+- arabluatex.ins
+- arabluatex.dtx
+- arabluatex.lua
+- arabluatex_voc.lua
+- arabluatex_fullvoc.lua
+- arabluatex_novoc.lua
+- arabluatex_trans.lua
+
+\endpreamble
+
+\generate{%
+ \file{arabluatex.sty}{\from{arabluatex.dtx}{package}}
+ \file{arabluatex-patch.sty}{\from{arabluatex.dtx}{patch}}
+ }
+
+\Msg{***********************************************************}
+\Msg{*}
+\Msg{* To finish the installation you have to move the following}
+\Msg{* files into a directory where LaTeX canfind them. See the}
+\Msg{* FAQ at https://texfaq.org/FAQ-inst-wlcf for}
+\Msg{* more on this}
+\Msg{*}
+\Msg{* \space\space arabluatex.sty}
+\Msg{* \space\space arabluatex-patch.sty}
+\Msg{* \space\space arabluatex.lua}
+\Msg{* \space\space arabluatex_voc.lua}
+\Msg{* \space\space arabluatex_fullvoc.lua}
+\Msg{* \space\space arabluatex_novoc.lua}
+\Msg{* \space\space arabluatex_trans.lua}
+\Msg{*}
+\Msg{* To produce the documentation run the files ending with}
+\Msg{* `.dtx' through LuaLaTeX.}
+\Msg{*}
+\Msg{* For an index, do:}
+\Msg{* \space makeindex -s gind.ist -o arabluatex.ind arabluatex.idx}
+\Msg{* For a list of changes, do:}
+\Msg{* \space makeindex -s gglo.ist -o arabluatex.gls arabluatex.glo}
+\Msg{* For a bibliography, do:}
+\Msg{* \space biber arabluatex}
+\Msg{*}
+\Msg{* Happy TeXing!}
+\Msg{***********************************************************}
+
+\endbatchfile
diff --git a/macros/luatex/latex/arabluatex/arabluatex.lua b/macros/luatex/latex/arabluatex/arabluatex.lua
new file mode 100644
index 0000000000..df031569c0
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/arabluatex.lua
@@ -0,0 +1,1187 @@
+--[[
+This file is part of the `arabluatex' package
+
+ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
+Copyright (C) 2016--2019 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/>.
+--]]
+
+arabluatex = {}
+
+require("arabluatex_voc")
+require("arabluatex_fullvoc")
+require("arabluatex_novoc")
+require("arabluatex_trans")
+
+-- lpeg equivalent for string.gsub()
+local function gsub(s, patt, repl)
+ patt = lpeg.P(patt)
+ patt = lpeg.Cs((patt / repl + 1)^0)
+ return lpeg.match(patt, s)
+end
+
+-- makeatletter, makeatother
+local atletter = "\\makeatletter{}"
+local atother = "\\makeatother{}"
+
+-- some basic patterns:
+local ascii = lpeg.R("az", "AZ", "@@")
+local dblbkslash = lpeg.Cs("\\")
+local bsqbrackets = lpeg.Cs{ "[" * ((1 - lpeg.S"[]") + lpeg.V(1))^0 * "]" }
+local bcbraces = lpeg.Cs{ "{" * ((1 - lpeg.S"{}") + lpeg.V(1))^0 * "}" }
+local spce = lpeg.Cs(" ")
+local spcenc = lpeg.P(" ")
+local cmdstar = lpeg.Cs(spce * lpeg.P("*"))
+local bsqbracketsii = lpeg.Cs(bsqbrackets^-2)
+local bcbracesii = lpeg.Cs(bcbraces^-2)
+local cmd = lpeg.Cs(dblbkslash * ascii^1 * cmdstar^-1)
+local rawcmd = lpeg.Cs(dblbkslash * ascii^1)
+local aftercmd = lpeg.Cs(lpeg.S("*[{,.?;:'`\"") + dblbkslash)
+local cmdargs = lpeg.Cs(spce^-1 * bsqbracketsii * bcbracesii * bsqbrackets^-1)
+local arbargs = lpeg.Cs(spce^-1 * bsqbrackets^-1 * bcbraces)
+local baytargs = lpeg.Cs(spce * bcbraces * bsqbrackets^-1 * bcbraces)
+
+local function protectarb(str)
+ str = string.gsub(str, "(\\arb%s?)(%[.-%])(%b{})", "\\al@brk{\\arb%2%3}")
+ str = string.gsub(str, "(\\LR%s?)(%b{})", "\\@LR%2")
+ str = string.gsub(str, "(\\RL%s?)(%b{})", "\\@RL%2")
+ return str
+end
+
+local function unprotectarb(str)
+ str = string.gsub(str, "(\\@arb)(%[.-%])(%b{})", "\\arb%2%3")
+ str = string.gsub(str, "(\\@LR)(%b{})", "\\LR%2")
+ str = string.gsub(str, "(\\@RL)(%b{})", "\\RL%2")
+ str = gsub(str, lpeg.Cs("\\al@brk") * bcbraces, function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s", body)
+ end)
+ return str
+end
+
+-- the following is to be taken out of \arb{}
+local outofarb = {
+ "LRfootnote",
+ "RLfootnote",
+ "edtext",
+ "pstart",
+ "pend"
+}
+-- commands the arguments of which must not be processed by arabluatex
+-- inside \arb{}. 'albrkcmds' is what is set by default. 'brkcmds'
+-- collects the commands set in the preamble with \MkArbBreak{}
+local albrkcmds = {
+ "begin",
+ "end",
+ "par",
+ "LRmarginpar",
+ "arbmark",
+ "abjad",
+ "ayah"
+}
+local brkcmds = {}
+
+function arabluatex.mkarbbreak(str, opt)
+ str = str ..","
+ str = string.gsub(str, "%s+", "")
+ local fieldstart = 1
+ if opt == "dflt" then
+ repeat
+ local nexti = string.find(str, "%,", fieldstart)
+ table.insert(brkcmds, string.sub(str, fieldstart, nexti-1))
+ fieldstart = nexti +1
+ until fieldstart > string.len(str)
+ return brkcmds
+ elseif opt == "out" then
+ repeat
+ local nexti = string.find(str, "%,", fieldstart)
+ table.insert(outofarb, string.sub(str, fieldstart, nexti-1))
+ fieldstart = nexti +1
+ until fieldstart > string.len(str)
+ return outofarb
+ end
+end
+
+local function breakcmd(str)
+ -- process \item[], then \item[]
+ str = string.gsub(str, "\\(item.?)(%b[])",
+ function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("\\al@brk{\\item[\\arb{%s}] }", body)
+ end)
+ str = string.gsub(str, "(\\item)(%s+)", "%1{}%2")
+ -- \textcolor
+ str = string.gsub(str, "\\(textcolor%s?)(%b{})(%b{})",
+ function(tag, bodycolor, bodytext)
+ bodycolor = string.sub(bodycolor, 2, -2)
+ bodytext = string.sub(bodytext, 2, -2)
+ return string.format("\\al@brk{\\%s{%s}{\\arb{%s}}}", tag, bodycolor, bodytext)
+ end)
+ -- commands set by default in outofarb
+ for i = 1,#outofarb do
+ str = gsub(str, dblbkslash * lpeg.Cs(outofarb[i]) * cmdargs, "}%1%2%3\\arb{")
+ end
+ -- commands set by default in albrkcmds
+ for i = 1,#albrkcmds do
+ str = gsub(str, dblbkslash * lpeg.Cs(albrkcmds[i]) * cmdargs, "\\al@brk{%1%2%3}")
+ end
+ -- user commands (brkcmds)
+ if next(brkcmds) == nil then
+ -- nothing to do
+ else
+ for i = 1,#brkcmds do
+ str = gsub(str, dblbkslash * lpeg.Cs(brkcmds[i]) * cmdargs, "\\al@brk{%1%2%3}")
+ end
+ end
+ return str
+end
+
+local function holdcmd(str)
+ str = gsub(str, lpeg.Cs("\\arb") * bcbraces, function(tag, body)
+ body = string.sub(body, 2, -2)
+ body = gsub(body, cmd * spcenc^-1 * bsqbracketsii * spcenc^-1 * bcbraces, function(btag, bopt, bbody)
+ bbody = string.sub(bbody, 2, -2)
+ if string.find(btag, "@") then
+ return holdcmd(string.format("}%s%s{%s}\\arb{", btag, bopt, bbody))
+ else
+ return holdcmd(string.format("}%s%s{\\arb{%s}}\\arb{", btag, bopt, bbody))
+ end
+ end)
+ return string.format("%s{%s}", tag, body)
+ end)
+ str = string.gsub(str, "\\arb{}", "")
+ return str
+end
+
+local function arbnum(str)
+ str = string.gsub(str, "([0-9%,%-%/]+)", function(num)
+ return string.reverse(num)
+ end)
+ return str
+end
+
+local function indnum(str)
+ str = string.gsub(str, "([0-9%,%-%/]+)", function(num)
+ return string.reverse(num)
+ end)
+ for i = 1,#numbers do
+ str = string.gsub(str, numbers[i].a, numbers[i].b)
+ end
+ return str
+end
+
+local function processdiscretionary(str)
+ str = string.gsub(str, "\\%-", "\\-{}")
+ return str
+end
+
+local function processarbnull(str, scheme)
+ if scheme == "buckwalter" then
+ str = string.gsub(str, "(\\arbnull.?)(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("P%sP", body)
+ end)
+ else
+ str = string.gsub(str, "(\\arbnull.?)(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("O%sO", body)
+ end)
+ end
+ return str
+end
+
+local function takeout_abjad_ayah(str)
+ str = string.gsub(str, "(\\abjad.?)(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s", body)
+ end)
+ str = string.gsub(str, "(\\ayah.?)(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ if tonumber(body) ~= nil and str.len(body) < 4 then
+ return string.format("(%s)", body)
+ else
+ return "<??>"
+ end
+ end)
+ return str
+end
+
+local function takeoutcapetc(str)
+ str = string.gsub(str, "(\\arb.?%[trans%])(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ body = string.gsub(body, "(\\uc%s?)(%b{})", "\\Uc%2")
+ return string.format("%s{%s}", tag, body)
+ end)
+ str = string.gsub(str, "(\\arbup.?)(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s", body)
+ end)
+ str = string.gsub(str, "(\\uc%s?)(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s", body)
+ end)
+ str = string.gsub(str, "\\uc%s", "")
+ str = string.gsub(str, "\\linebreak", "")
+ str = string.gsub(str, "\\%-", "")
+ return str
+end
+
+local function checkwrnested(str)
+ for i = 1,#outofarb do
+ str = gsub(str, dblbkslash * lpeg.Cs(lpeg.P("LR") + lpeg.P("RL")) * cmdargs,
+ function(prefix, tag, body)
+ body = string.sub(body, 2, -2)
+ if string.find(body, "\\"..outofarb[i]) then
+ return atletter.."\\al@wrong@nesting{}"..atother
+ else
+ -- nothing to do, so proceed.
+ end
+ end)
+ end
+ return str
+end
+
+local function takeoutarb(str)
+ str = checkwrnested(str)
+ for i = 1,#outofarb do
+ str = gsub(str, dblbkslash * lpeg.Cs(outofarb[i]) * cmdargs,
+ function(prefix, tag, body)
+ body = gsub(body, lpeg.P("\\arb"), "\\@rb")
+ return string.format("%s%s%s", prefix, tag, body)
+ end)
+ end
+ str = string.gsub(str, "(\\arb%s?)(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s", body)
+ end)
+ str = string.gsub(str, "\\@rb", "\\arb")
+ str = "\\arb{"..str.."}"
+ return str
+end
+
+local function voc(str, rules)
+ str = string.gsub(str, "\\arb(%b{})", function(inside)
+ inside = string.sub(inside, 2, -2)
+ for i = 1,#hamza do
+ inside = string.gsub(inside, hamza[i].a, hamza[i].b)
+ end
+ if rules == "idgham" then
+ for i = 1,#tanwin do
+ inside = string.gsub(inside, tanwin[i].a, tanwin[i].b)
+ end
+ else
+ for i = 1,#tanwineasy do
+ inside = string.gsub(inside, tanwineasy[i].a, tanwineasy[i].b)
+ end
+ end
+ for i = 1,#trigraphs do
+ inside = string.gsub(inside, trigraphs[i].a, trigraphs[i].b)
+ end
+ if rules == "idgham" then
+ for i = 1,#idgham do
+ inside = string.gsub(inside, idgham[i].a, idgham[i].b)
+ end
+ end
+ for i = 1,#digraphs do
+ inside = string.gsub(inside, digraphs[i].a, digraphs[i].b)
+ end
+ for i = 1,#single do
+ inside = string.gsub(inside, single[i].a, single[i].b)
+ end
+ for i = 1,#longv do
+ inside = string.gsub(inside, longv[i].a, longv[i].b)
+ end
+ for i = 1,#shortv do
+ inside = string.gsub(inside, shortv[i].a, shortv[i].b)
+ end
+ for i = 1,#punctuation do
+ inside = string.gsub(inside, punctuation[i].a, punctuation[i].b)
+ end
+ for i = 1,#null do
+ inside = string.gsub(inside, null[i].a, null[i].b)
+ end
+ inside = indnum(inside)
+ return string.format("\\arabicfont{}%s", inside)
+ end)
+return str
+end
+
+local function voceasy(str)
+ str = string.gsub(str, "\\arb(%b{})", function(inside)
+ inside = string.sub(inside, 2, -2)
+ for i = 1,#hamzaeasy do
+ inside = string.gsub(inside, hamzaeasy[i].a, hamzaeasy[i].b)
+ end
+ for i = 1,#tanwineasy do
+ inside = string.gsub(inside, tanwineasy[i].a, tanwineasy[i].b)
+ end
+ for i = 1,#trigraphseasy do
+ inside = string.gsub(inside, trigraphseasy[i].a, trigraphseasy[i].b)
+ end
+ for i = 1,#digraphs do
+ inside = string.gsub(inside, digraphs[i].a, digraphs[i].b)
+ end
+ for i = 1,#single do
+ inside = string.gsub(inside, single[i].a, single[i].b)
+ end
+ for i = 1,#longv do
+ inside = string.gsub(inside, longv[i].a, longv[i].b)
+ end
+ for i = 1,#shortv do
+ inside = string.gsub(inside, shortv[i].a, shortv[i].b)
+ end
+ for i = 1,#punctuation do
+ inside = string.gsub(inside, punctuation[i].a, punctuation[i].b)
+ end
+ for i = 1,#null do
+ inside = string.gsub(inside, null[i].a, null[i].b)
+ end
+ inside = indnum(inside)
+ return string.format("\\arabicfont{}%s", inside)
+ end)
+return str
+end
+
+local function fullvoc(str, rules)
+ str = string.gsub(str, "\\arb(%b{})", function(inside)
+ inside = string.sub(inside, 2, -2)
+ for i = 1,#hamzafv do
+ inside = string.gsub(inside, hamzafv[i].a, hamzafv[i].b)
+ end
+ if rules == "idgham" then
+ for i = 1,#tanwinfv do
+ inside = string.gsub(inside, tanwinfv[i].a, tanwinfv[i].b)
+ end
+ else
+ for i = 1,#tanwinfveasy do
+ inside = string.gsub(inside, tanwinfveasy[i].a, tanwinfveasy[i].b)
+ end
+ end
+ for i = 1,#trigraphsfv do
+ inside = string.gsub(inside, trigraphsfv[i].a, trigraphsfv[i].b)
+ end
+ if rules == "idgham" then
+ for i = 1,#idgham do
+ inside = string.gsub(inside, idgham[i].a, idgham[i].b)
+ end
+ end
+ if rules == "idgham" then
+ for i = 1,#digraphsfvidgham do
+ inside = string.gsub(inside, digraphsfvidgham[i].a, digraphsfvidgham[i].b)
+ end
+ else
+ for i = 1,#digraphsfv do
+ inside = string.gsub(inside, digraphsfv[i].a, digraphsfv[i].b)
+ end
+ end
+ for i = 1,#singlefv do
+ inside = string.gsub(inside, singlefv[i].a, singlefv[i].b)
+ end
+ for i = 1,#longv do
+ inside = string.gsub(inside, longv[i].a, longv[i].b)
+ end
+ for i = 1,#shortv do
+ inside = string.gsub(inside, shortv[i].a, shortv[i].b)
+ end
+ for i = 1,#punctuation do
+ inside = string.gsub(inside, punctuation[i].a, punctuation[i].b)
+ end
+ for i = 1,#null do
+ inside = string.gsub(inside, null[i].a, null[i].b)
+ end
+ inside = indnum(inside)
+ return string.format("\\arabicfont{}%s", inside)
+ end)
+return str
+end
+
+local function fullvoceasy(str, rules)
+ str = string.gsub(str, "\\arb(%b{})", function(inside)
+ inside = string.sub(inside, 2, -2)
+ for i = 1,#hamzafveasy do
+ inside = string.gsub(inside, hamzafveasy[i].a, hamzafveasy[i].b)
+ end
+ for i = 1,#tanwinfveasy do
+ inside = string.gsub(inside, tanwinfveasy[i].a, tanwinfveasy[i].b)
+ end
+ for i = 1,#trigraphsfveasy do
+ inside = string.gsub(inside, trigraphsfveasy[i].a, trigraphsfveasy[i].b)
+ end
+ if rules == "nosukun" then
+ for i = 1,#digraphsfveasy do
+ inside = string.gsub(inside, digraphsfveasy[i].a, digraphsfveasy[i].b)
+ end
+ else
+ for i = 1,#digraphsfv do
+ inside = string.gsub(inside, digraphsfv[i].a, digraphsfv[i].b)
+ end
+ end
+ if rules == "nosukun" then
+ for i = 1,#singlefveasy do
+ inside = string.gsub(inside, singlefveasy[i].a, singlefveasy[i].b)
+ end
+ else
+ for i = 1,#singlefv do
+ inside = string.gsub(inside, singlefv[i].a, singlefv[i].b)
+ end
+ end
+ for i = 1,#longv do
+ inside = string.gsub(inside, longv[i].a, longv[i].b)
+ end
+ for i = 1,#shortv do
+ inside = string.gsub(inside, shortv[i].a, shortv[i].b)
+ end
+ for i = 1,#punctuation do
+ inside = string.gsub(inside, punctuation[i].a, punctuation[i].b)
+ end
+ for i = 1,#null do
+ inside = string.gsub(inside, null[i].a, null[i].b)
+ end
+ inside = indnum(inside)
+ return string.format("\\arabicfont{}%s", inside)
+ end)
+return str
+end
+
+local function novoc(str)
+ str = string.gsub(str, "\\arb(%b{})", function(inside)
+ inside = string.sub(inside, 2, -2)
+ for i = 1,#hamza do
+ inside = string.gsub(inside, hamza[i].a, hamza[i].b)
+ end
+ for i = 1,#tanwinnv do
+ inside = string.gsub(inside, tanwinnv[i].a, tanwinnv[i].b)
+ end
+ for i = 1,#trigraphsnv do
+ inside = string.gsub(inside, trigraphsnv[i].a, trigraphsnv[i].b)
+ end
+ for i = 1,#digraphs do
+ inside = string.gsub(inside, digraphs[i].a, digraphs[i].b)
+ end
+ for i = 1,#single do
+ inside = string.gsub(inside, single[i].a, single[i].b)
+ end
+ for i = 1,#longvnv do
+ inside = string.gsub(inside, longvnv[i].a, longvnv[i].b)
+ end
+ for i = 1,#shortvnv do
+ inside = string.gsub(inside, shortvnv[i].a, shortvnv[i].b)
+ end
+ for i = 1,#punctuation do
+ inside = string.gsub(inside, punctuation[i].a, punctuation[i].b)
+ end
+ for i = 1,#null do
+ inside = string.gsub(inside, null[i].a, null[i].b)
+ end
+ inside = indnum(inside)
+ return string.format("\\arabicfont{}%s", inside)
+ end)
+ return str
+end
+
+local function novoceasy(str)
+ str = string.gsub(str, "\\arb(%b{})", function(inside)
+ inside = string.sub(inside, 2, -2)
+ for i = 1,#hamzaeasy do
+ inside = string.gsub(inside, hamzaeasy[i].a, hamzaeasy[i].b)
+ end
+ for i = 1,#tanwinnv do
+ inside = string.gsub(inside, tanwinnv[i].a, tanwinnv[i].b)
+ end
+ for i = 1,#trigraphsnv do
+ inside = string.gsub(inside, trigraphsnv[i].a, trigraphsnv[i].b)
+ end
+ for i = 1,#digraphs do
+ inside = string.gsub(inside, digraphs[i].a, digraphs[i].b)
+ end
+ for i = 1,#single do
+ inside = string.gsub(inside, single[i].a, single[i].b)
+ end
+ for i = 1,#longvnv do
+ inside = string.gsub(inside, longvnv[i].a, longvnv[i].b)
+ end
+ for i = 1,#shortvnv do
+ inside = string.gsub(inside, shortvnv[i].a, shortvnv[i].b)
+ end
+ for i = 1,#punctuation do
+ inside = string.gsub(inside, punctuation[i].a, punctuation[i].b)
+ end
+ for i = 1,#null do
+ inside = string.gsub(inside, null[i].a, null[i].b)
+ end
+ inside = indnum(inside)
+ return string.format("\\arabicfont{}%s", inside)
+ end)
+ return str
+end
+
+local function transdmg(str, rules)
+ str = string.gsub(str, "\\arb(%b{})", function(inside)
+ inside = string.sub(inside, 2, -2)
+ for i = 1,#hamzatrdmg do
+ inside = string.gsub(inside, hamzatrdmg[i].a, hamzatrdmg[i].b)
+ end
+ for i = 1,#tanwintrdmg do
+ inside = string.gsub(inside, tanwintrdmg[i].a, tanwintrdmg[i].b)
+ end
+ for i = 1,#trigraphstrdmg do
+ inside = string.gsub(inside, trigraphstrdmg[i].a, trigraphstrdmg[i].b)
+ end
+ if rules == "idgham" then
+ for i = 1,#idghamtrdmg do
+ inside = string.gsub(inside, idghamtrdmg[i].a, idghamtrdmg[i].b)
+ end
+ end
+ for i = 1,#digraphstrdmg do
+ inside = string.gsub(inside, digraphstrdmg[i].a, digraphstrdmg[i].b)
+ end
+ for i = 1,#singletrdmg do
+ inside = string.gsub(inside, singletrdmg[i].a, singletrdmg[i].b)
+ end
+ for i = 1,#longvtrdmg do
+ inside = string.gsub(inside, longvtrdmg[i].a, longvtrdmg[i].b)
+ end
+ for i = 1,#shortvtrdmg do
+ inside = string.gsub(inside, shortvtrdmg[i].a, shortvtrdmg[i].b)
+ end
+ for i = 1,#punctuationtr do
+ inside = string.gsub(inside, punctuationtr[i].a, punctuationtr[i].b)
+ end
+ for i = 1,#nulltr do
+ inside = string.gsub(inside, nulltr[i].a, nulltr[i].b)
+ end
+ return string.format("%s", inside)
+ end)
+ return str
+end
+
+local function transloc(str)
+ str = string.gsub(str, "\\arb(%b{})", function(inside)
+ inside = string.sub(inside, 2, -2)
+ for i = 1,#hamzatrloc do
+ inside = string.gsub(inside, hamzatrloc[i].a, hamzatrloc[i].b)
+ end
+ for i = 1,#tanwintrloc do
+ inside = string.gsub(inside, tanwintrloc[i].a, tanwintrloc[i].b)
+ end
+ for i = 1,#trigraphstrloc do
+ inside = string.gsub(inside, trigraphstrloc[i].a, trigraphstrloc[i].b)
+ end
+ for i = 1,#digraphstrloc do
+ inside = string.gsub(inside, digraphstrloc[i].a, digraphstrloc[i].b)
+ end
+ for i = 1,#singletrloc do
+ inside = string.gsub(inside, singletrloc[i].a, singletrloc[i].b)
+ end
+ for i = 1,#longvtrloc do
+ inside = string.gsub(inside, longvtrloc[i].a, longvtrloc[i].b)
+ end
+ for i = 1,#shortvtrloc do
+ inside = string.gsub(inside, shortvtrloc[i].a, shortvtrloc[i].b)
+ end
+ for i = 1,#finaltrloc do
+ inside = string.gsub(inside, finaltrloc[i].a, finaltrloc[i].b)
+ end
+ for i = 1,#punctuationtr do
+ inside = string.gsub(inside, punctuationtr[i].a, punctuationtr[i].b)
+ end
+ for i = 1,#nulltr do
+ inside = string.gsub(inside, nulltr[i].a, nulltr[i].b)
+ end
+ return string.format("%s", inside)
+ end)
+ return str
+end
+
+local function transarabica(str)
+ str = string.gsub(str, "\\arb(%b{})", function(inside)
+ inside = string.sub(inside, 2, -2)
+ for i = 1,#hamzatrarabica do
+ inside = string.gsub(inside, hamzatrarabica[i].a, hamzatrarabica[i].b)
+ end
+ for i = 1,#tanwintrloc do
+ inside = string.gsub(inside, tanwintrloc[i].a, tanwintrloc[i].b)
+ end
+ for i = 1,#trigraphstrarabica do
+ inside = string.gsub(inside, trigraphstrarabica[i].a, trigraphstrarabica[i].b)
+ end
+ for i = 1,#digraphstrarabica do
+ inside = string.gsub(inside, digraphstrarabica[i].a, digraphstrarabica[i].b)
+ end
+ for i = 1,#singletrarabica do
+ inside = string.gsub(inside, singletrarabica[i].a, singletrarabica[i].b)
+ end
+ for i = 1,#longvtrarabica do
+ inside = string.gsub(inside, longvtrarabica[i].a, longvtrarabica[i].b)
+ end
+ for i = 1,#shortvtrloc do
+ inside = string.gsub(inside, shortvtrloc[i].a, shortvtrloc[i].b)
+ end
+ for i = 1,#punctuationtr do
+ inside = string.gsub(inside, punctuationtr[i].a, punctuationtr[i].b)
+ end
+ for i = 1,#nulltr do
+ inside = string.gsub(inside, nulltr[i].a, nulltr[i].b)
+ end
+ return string.format("%s", inside)
+ end)
+ return str
+end
+
+local function processbuckw(str)
+ str = string.gsub(str, "\\arb(%b{})", function(inside)
+ inside = string.sub(inside, 2, -2)
+ for i = 1,#buckwalter do
+ inside = string.gsub(inside, buckwalter[i].a, buckwalter[i].b)
+ end
+ return string.format("\\arb{%s}", inside)
+ end)
+ return str
+end
+
+-- The following functions produce a copy of the original .tex source
+-- file in which all arabtex strings are replaced with Unicode
+-- equivalents
+local utffilesuffix = "_out"
+local export_utf = "no"
+
+function arabluatex.utffilesuffix(str)
+ utffilesuffix = str
+ return true
+end
+
+function arabluatex.doexport(str)
+ export_utf = str
+ return true
+end
+
+function arabluatex.openstream()
+ local f = io.open(tex.jobname..utffilesuffix.."_tmp.tex", "a+")
+ local preamble = io.open(tex.jobname..".tex", "r")
+ for line in preamble:lines() do
+ f:write(line, "\n")
+ if string.find(line, "^%s-\\begin%s?{document}") then
+ break
+ end
+ end
+ preamble:close()
+ f:close()
+ return true
+end
+
+local function processarbtoutf(str)
+ if export_utf ~= "arabverse" then
+ str = "\\begin{arabexport}"..str
+ else end
+ --[[ -- of no use, see above takeout_abjad_ayah()
+ str = string.gsub(str, "(\\txtrans%s?)(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ body = string.gsub(body, "(\\abjad%s?)(%b{})", function(btag, bbody)
+ bbody = string.sub(bbody, 2, -2)
+ return string.format("%s", bbody)
+ end)
+ body = string.gsub(body, "(\\ayah%s?)(%b{})", function(btag, bbody)
+ bbody = string.sub(bbody, 2, -2)
+ return string.format("(%s)", bbody)
+ end)
+ return string.format("%s{%s}", tag, body)
+ end)
+ --]]
+ str = string.gsub(str, "(\\txarb%s?)(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ body = string.gsub(body, "(\\abjad%s?)(%b{})", function(btag, bbody)
+ bbody = string.sub(bbody, 2, -2)
+ if tonumber(bbody) ~= nil then
+ bbody = arabluatex.abjadify(bbody)
+ return string.format("\\oline*{\\arb[novoc]{%s}}", bbody)
+ else
+ return string.format("%s{%s}", btag, bbody)
+ end
+ end)
+ body = string.gsub(body, "(\\arbmark%s?)(%b{})", function(btag, bbody)
+ bbody = string.sub(bbody, 2, -2)
+ return string.format("%s[rl]{%s}", btag, bbody)
+ end)
+ body = string.gsub(body, "(\\ayah%s?)(%b{})", function(btag, bbody)
+ bbody = string.sub(bbody, 2, -2)
+ return string.format("\\arb[novoc]{%s^^^^06dd}", bbody)
+ end)
+ return string.format("%s{%s}", tag, body)
+ end)
+ str = string.gsub(str, "(\\bayt)%s?(%b{})(%b[])(%b{})", function(tag, argi, argii, argiii)
+ argi = string.sub(argi, 2, -2)
+ argii = string.sub(argii, 2, -2)
+ argiii = string.sub(argiii, 2, -2)
+ return string.format("%s*{\\arb{%s}}[\\arb{%s}]{\\arb{%s}}", tag, argi, argii, argiii)
+ end)
+ str = string.gsub(str, "(\\bayt)%s?(%b{})(%b{})", function(tag, argi, argii)
+ argi = string.sub(argi, 2, -2)
+ argii = string.sub(argii, 2, -2)
+ return string.format("%s*{\\arb{%s}}{\\arb{%s}}", tag, argi, argii)
+ end)
+ str = string.gsub(str, "(\\prname)%s?(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ if string.find(body, "\\uc%s?%b{}") then
+ return string.format("%s*{%s}", tag, body)
+ else
+ return string.format("%s{\\arb[trans]{\\uc{%s}}}", tag, body)
+ end
+ end)
+ str = string.gsub(str, "(\\begin%s?{arab})(%b[])", function(tag, body)
+ if string.find(body, "trans") then
+ return string.format("\\par\\bgroup\\setLR\\arb%s{", body)
+ else
+ return string.format("\\par\\bgroup\\setRL\\arb%s{", body)
+ end
+ end)
+ str = string.gsub(str, "(\\begin%s?{arab})", "\\par\\bgroup\\arbpardir\\arb{")
+ str = string.gsub(str, "\\end%s?{arab}", "}\\egroup\\par")
+ -- This does not work, while the following two do. Look into this later.
+ -- str = gsub(str, lpeg.Cs("\\arb") * spcenc * bsqbrackets^-1 * bcbraces, function(tag, opt, body)
+ -- body = string.sub(body, 2, -2)
+ -- return string.format("%s%s\\@al@pr@ob%s\\@al@pr@cb", tag, opt, body)
+ -- end)
+ str = string.gsub(str, "(\\arb%s?)(%b[])(%b{})", function(tag, opt, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s%s\\@al@pr@ob%s\\@al@pr@cb", tag, opt, body)
+ end)
+ str = string.gsub(str, "(\\arb)%s?(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s\\@al@pr@ob%s\\@al@pr@cb", tag, body)
+ end)
+ str = string.gsub(str, "(\\arbmark)%s?(%b[])(%b{})", function(tag, opt, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s%s\\@al@pr@ob%s\\@al@pr@cb", tag, opt, body)
+ end)
+ str = string.gsub(str, "(\\arbmark)%s?(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s\\@al@pr@ob%s\\@al@pr@cb", tag, body)
+ end)
+ str = string.gsub(str, "(\\[Uu]c)%s?(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s\\@al@pr@ob%s\\@al@pr@cb", tag, body)
+ end)
+ str = string.gsub(str, "{", "\\@al@ob")
+ str = string.gsub(str, "} ", "\\@al@cb@sp")
+ str = string.gsub(str, "}", "\\@al@cb")
+ str = string.gsub(str, "\\@al@pr@ob", "{")
+ str = string.gsub(str, "\\@al@pr@cb", "}")
+ str = string.gsub(str, "(%b{})", function(body)
+ body = string.sub(body, 2, -2)
+ body = string.gsub(body, "(%s?)(\\@al@ob)", "%1{")
+ body = string.gsub(body, "(\\@al@cb@sp)", "} ")
+ body = string.gsub(body, "(\\@al@cb)(%s?)", "}%2")
+ return string.format("{%s}", body)
+ end)
+ if export_utf ~= "arabverse" then
+ str = str.."\\end{arabexport}"
+ else end
+ return str
+end
+
+function arabluatex.arbtoutf(str)
+ str = processarbtoutf(str)
+ str = "\\ArbOutFile{"..str.."}"
+ str = string.gsub(str, "(\\ArbOutFile)%s?(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ body = gsub(body, lpeg.Cs("\\arb") * arbargs, "}%1%2\\ArbOutFile{")
+ return string.format("%s{%s}", tag, body)
+ end)
+ str = string.gsub(str, "(\\ArbOutFile)%s?(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ body = string.gsub(body, "(\\[Uu]c)%s?(%b{})", "}%1%2\\ArbOutFile{")
+ return string.format("%s{%s}", tag, body)
+ end)
+ str = string.gsub(str, "(\\ArbOutFile)%s?(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ body = gsub(body, lpeg.Cs("\\arbmark") * arbargs, "}%1%2\\ArbOutFile{")
+ return string.format("%s{%s}", tag, body)
+ end)
+ return str
+end
+
+function arabluatex.tooutfile(str, nl)
+ local f = io.open(tex.jobname..utffilesuffix.."_tmp.tex", "a+")
+ if nl == "newline" then
+ f:write(str, "\n\n")
+ else
+ f:write(str)
+ end
+ f:close()
+ return str
+end
+
+function arabluatex.closestream()
+ local f = io.open(tex.jobname..utffilesuffix.."_tmp.tex", "r")
+ local o = io.open(tex.jobname..utffilesuffix..".tex", "w")
+ local t = f:read("*a")
+ t = string.gsub(t, "\\arabicfont{}", "")
+ t = string.gsub(t, "\\par ", "\n\n")
+ t = string.gsub(t, "(\\@al@ob)", "{")
+ t = string.gsub(t, "(\\@al@cb@sp)", "} ")
+ t = string.gsub(t, "(\\@al@cb)(%s?)", "}")
+ t = gsub(t, lpeg.Cs("\\begin") * spcenc^-1 * bcbraces * cmdargs,
+ "\n%1%2%3\n")
+ t = string.gsub(t, "(\\\\)(%s?)", "%1\n")
+ t = string.gsub(t, "(\\\\)(\n)(\\end%s?)(%b{})", "%1%3%4")
+ t = string.gsub(t, "%s-\n(\\begin%s?)(%b{})", "\n%1%2")
+ t = string.gsub(t, "(\\item)", "\n%1")
+ t = string.gsub(t, "\n\n(\\item)", "\n%1")
+ t = string.gsub(t, "(\\end%s?)(%b{})", "%1%2\n")
+ t = string.gsub(t, "([^\n]%s-)(\\end)%s?(%b{})", "%1\n%2%3")
+ t = string.gsub(t, "\n\n\n", "\n\n")
+ t = string.gsub(t, "(\\txarb%s?%{)(\\txarb%s?)(%b{})(%})",
+ function(tagio, tagii, body, tagic)
+ body = string.sub(body, 2, -2)
+ return
+ string.format("%s%s%s", tagio, body, tagic)
+ end)
+ t = string.gsub(t, "(\\prname%s?%*%{)(\\txtrans%s?)(%b{})(%})",
+ function(tagio, tagii, body, tagic)
+ body = string.sub(body, 2, -2)
+ return string.format("%s%s%s", tagio, body, tagic)
+ end)
+ if string.find(t, "\\begin%s?{document}.-\\arb%s?[%[%{]")
+ or
+ string.find(t, "\\begin%s?{document}.-\\[Uu]c%s?%b{}")
+ or
+ string.find(t, "\\begin%s?{document}.-\\abjad%s?%b{}")
+ or
+ string.find(t, "\\begin%s?{document}.-\\ayah%s?%b{}")
+ then
+ -- issue a warning:
+ tex.print([[\unexpanded{\PackageWarningNoLine{arabluatex}{]]
+ ..
+ [[There are still 'arabtex' strings to be converted. ]]
+ ..
+ [[Please open ]] .. tex.jobname .. utffilesuffix .. ".tex" ..
+ [[ and compile it one more time}}]])
+ --
+ else end
+ t = gsub(t, rawcmd * spce^1 * aftercmd, "%1%3")
+ t = t.."\n\\end{document}"
+ io.write(t)
+ o:write(t)
+ f:close()
+ o:close()
+ os.remove(tex.jobname..utffilesuffix.."_tmp.tex")
+ return true
+end
+
+-- Process standard arabluatex modes:
+function arabluatex.processvoc(str, rules, scheme)
+ str = takeoutarb(str)
+ str = processarbnull(str, scheme)
+ str = takeoutcapetc(str)
+ str = protectarb(str)
+ str = breakcmd(str)
+ str = holdcmd(str)
+ if scheme == "buckwalter" then
+ str = processbuckw(str)
+ else end
+ if rules == "easy" or rules == "easynosukun" then
+ str = voceasy(str)
+ elseif rules == "dflt" or rules == "idgham" then
+ str = voc(str, rules)
+ else end
+ str = unprotectarb(str)
+ if export_utf == "yes" then
+ tofile = "\\txarb{"..str.."}"
+ arabluatex.tooutfile(tofile)
+ elseif export_utf == "arabverse" then
+ tofile = "\\txarb{"..str.."}"
+ arabluatex.tooutfile(tofile)
+ else
+ return str
+ end
+ return ""
+end
+
+function arabluatex.processfullvoc(str, rules, scheme)
+ str = takeoutarb(str)
+ str = processarbnull(str, scheme)
+ str = takeoutcapetc(str)
+ str = protectarb(str)
+ str = breakcmd(str)
+ str = holdcmd(str)
+ if scheme == "buckwalter" then
+ str = processbuckw(str)
+ else end
+ if rules == "easy" then
+ str = fullvoceasy(str, "sukun")
+ elseif rules == "easynosukun" then
+ str = fullvoceasy(str, "nosukun")
+ elseif rules == "dflt" or rules == "idgham" then
+ str = fullvoc(str, rules)
+ else end
+ str = unprotectarb(str)
+ if export_utf == "yes" then
+ tofile = "\\txarb{"..str.."}"
+ arabluatex.tooutfile(tofile)
+ elseif export_utf == "arabverse" then
+ tofile = "\\txarb{"..str.."}"
+ arabluatex.tooutfile(tofile)
+ else
+ return str
+ end
+ return ""
+end
+
+function arabluatex.processnovoc(str, rules, scheme)
+ str = takeoutarb(str)
+ str = processarbnull(str, scheme)
+ str = takeoutcapetc(str)
+ str = protectarb(str)
+ str = breakcmd(str)
+ str = holdcmd(str)
+ if scheme == "buckwalter" then
+ str = processbuckw(str)
+ else end
+ if rules == "easy" or rules == "easynosukun" then
+ str = novoceasy(str)
+ elseif rules == "dflt" or rules == "idgham" then
+ str = novoc(str)
+ else end
+ str = unprotectarb(str)
+ if export_utf == "yes" then
+ tofile = "\\txarb{"..str.."}"
+ arabluatex.tooutfile(tofile)
+ elseif export_utf == "arabverse" then
+ tofile = "\\txarb{"..str.."}"
+ arabluatex.tooutfile(tofile)
+ else
+ return str
+ end
+ return ""
+end
+
+function arabluatex.processtrans(str, mode, rules, scheme)
+ str = takeoutarb(str)
+ str = processdiscretionary(str)
+ str = processarbnull(str, scheme)
+ str = takeout_abjad_ayah(str)
+ str = protectarb(str)
+ str = breakcmd(str)
+ str = holdcmd(str)
+ if scheme == "buckwalter" then
+ str = processbuckw(str)
+ end
+ if mode == "dmg" then
+ str = transdmg(str, rules)
+ elseif mode == "loc" then
+ str = transloc(str)
+ elseif mode == "arabica" then
+ str = transarabica(str)
+ end
+ str = unprotectarb(str)
+ if export_utf == "yes" then
+ tofile = "\\txtrans{"..str.."}"
+ arabluatex.tooutfile(tofile)
+ elseif export_utf == "arabverse" then
+ tofile = "\\txtrans{"..str.."}"
+ arabluatex.tooutfile(tofile)
+ else
+ return str
+ end
+ return ""
+end
+
+function arabluatex.newarbmark(abbr, rtlmk, ltrmk)
+ abbr = "@"..abbr
+ rtlmk = "\\arabicfont{}"..rtlmk
+ table.insert(arbmarks, {a = abbr, b = rtlmk, c = ltrmk})
+ table.sort(arbmarks, function(a ,b) return(#a.a > #b.a) end)
+ return true
+end
+
+local function isintable(table, element)
+ for i = 1,#table do
+ if table[i].a == element then
+ return true
+ end
+ end
+ return false
+end
+
+function arabluatex.processarbmarks(str, dir)
+ str = "@"..str
+ if not isintable(arbmarks, str) then
+ str = "\\LR{<??>}"..atletter.."\\al@wrong@mark{}"..atother
+ else
+ if dir == "lr" then
+ for i = 1,#arbmarks do
+ str = string.gsub(str, arbmarks[i].a, arbmarks[i].c)
+ end
+ elseif dir == "rl" then
+ for i = 1,#arbmarks do
+ str = string.gsub(str, arbmarks[i].a, arbmarks[i].b)
+ end
+ elseif tex.textdir == "TLT" then
+ for i = 1,#arbmarks do
+ str = string.gsub(str, arbmarks[i].a, arbmarks[i].c)
+ end
+ else
+ for i = 1,#arbmarks do
+ str = string.gsub(str, arbmarks[i].a, arbmarks[i].b)
+ end
+ end
+ end
+ if export_utf == "yes" then
+ tofile = str
+ arabluatex.tooutfile(tofile)
+ elseif export_utf == "arabverse" then
+ tofile = str
+ arabluatex.tooutfile(tofile)
+ else
+ return str
+ end
+ return ""
+end
+
+function arabluatex.uc(str)
+ str = string.gsub(str, "(\\txtrans.?)(%b{})", function(tag, body)
+ body = string.sub(body, 2, -2)
+ return string.format("%s", body)
+ end)
+ str = string.gsub(str, "{", "\\@al@ob")
+ str = string.gsub(str, "} ", "\\@al@cb@sp ")
+ str = string.gsub(str, "}", "\\@al@cb")
+ -- Allah and ibn
+ str = string.gsub(str, "(al%-lāh)([uai]?)", "{Allāh%2}")
+ str = string.gsub(str, "([%'%-]?)(l%-lāh)([uai]?)", "%1{Llāh%3}")
+ str = string.gsub(str, "(%s[%(%<%[]?)([i%']?b[n%.])", "%1{%2}")
+ for i = 1,#lcuc do
+ str = string.gsub(str, "^([%S]-%-[`']?)"..lcuc[i].a, "{%1"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "(%s[%(%<%[]?)([%S]-%-[`']?)"..lcuc[i].a, "%1{%2"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "^([%S]-%-ʿ)"..lcuc[i].a, "{%1"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "(%s[%(%<%[]?)([%S]-%-ʿ)"..lcuc[i].a, "%1{%2"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "^([%S]-%-ʾ)"..lcuc[i].a, "{%1"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "(%s[%(%<%[]?)([%S]-%-ʾ)"..lcuc[i].a, "%1{%2"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "^([`'])"..lcuc[i].a, "{%1"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "(%s[%(%<%[]?)([`'])"..lcuc[i].a, "%1{%2"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "^(ʾ)"..lcuc[i].a, "{%1"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "(%s[%(%<%[]?)(ʾ)"..lcuc[i].a, "%1{%2"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "^(ʿ)"..lcuc[i].a, "{%1"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "(%s[%(%<%[]?)(ʿ)"..lcuc[i].a, "%1{%2"..lcuc[i].b.."}")
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "^"..lcuc[i].a, lcuc[i].b)
+ end
+ for i = 1,#lcuc do
+ str = string.gsub(str, "(%s[%(%<%[]?)"..lcuc[i].a, "%1"..lcuc[i].b)
+ end
+ str = string.gsub(str, "{", "")
+ str = string.gsub(str, "}", "")
+ str = string.gsub(str, "\\@al@ob", "{")
+ str = string.gsub(str, "\\@al@cb@sp ", "} ")
+ str = string.gsub(str, "\\@al@cb", "}")
+ if export_utf == "yes" then
+ tofile = str
+ arabluatex.tooutfile(tofile)
+ elseif export_utf == "arabverse" then
+ tofile = str
+ arabluatex.tooutfile(tofile)
+ else
+ return str
+ end
+ return ""
+end
+
+-- this function is adapted from an 'obsolete project' of Khaled
+-- Hosny's that dates back to 2010. Thanks to him.
+-- See https://github.com/khaledhosny/lualatex-arabic
+function arabluatex.abjadify(n)
+ local abjadnum = ""
+ n = tonumber(n)
+ if n >= 1000 then
+ for i=1,math.floor(n/1000) do
+ abjadnum = abjadnum .. abjad[4][1]
+ end
+ n = math.fmod(n,1000)
+ end
+ if n >= 100 then
+ abjadnum = abjadnum .. abjad[3][math.floor(n/100)]
+ n = math.fmod(n, 100)
+ end
+ if n >= 10 then
+ abjadnum = abjadnum .. abjad[2][math.floor(n/10)]
+ n = math.fmod(n, 10)
+ end
+ if n >= 1 then
+ abjadnum = abjadnum .. abjad[1][math.floor(n/1)]
+ end
+ return "\\arb[novoc]{"..abjadnum.."}"
+end
+
+function arabluatex.abraces(str)
+ if tex.textdir == "TRT" then
+ str = "\\}"..str.."\\{"
+ elseif tex.textdir == "TLT" then
+ str = "\\{"..str.."\\}"
+ end
+ return str
+end
+
+function arabluatex.aemph(str, opt)
+ if tex.textdir == "TRT" then
+ str = "\\oline{\\textdir TRT{}"..str.."}"
+ elseif tex.textdir == "TLT" then
+ if opt == "over" then
+ str = "\\oline{"..str.."}"
+ else
+ str = "\\uline{"..str.."}"
+ end
+ end
+ return str
+end
+
+function arabluatex.ayah(str)
+ if tonumber(str) ~= nil and str.len(str) < 4 then
+ if tex.textdir == "TRT" then
+ str = indnum(str).."^^^^06dd"
+ elseif tex.textdir == "TLT" then
+ str = "\\arb[trans]{("..str..")}"
+ end
+ return str
+ else
+ return "\\LR{<??>}"
+ end
+end
diff --git a/macros/luatex/latex/arabluatex/arabluatex.pdf b/macros/luatex/latex/arabluatex/arabluatex.pdf
new file mode 100644
index 0000000000..5374b0aef2
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/arabluatex.pdf
Binary files differ
diff --git a/macros/luatex/latex/arabluatex/arabluatex_fullvoc.lua b/macros/luatex/latex/arabluatex/arabluatex_fullvoc.lua
new file mode 100644
index 0000000000..f524c3b6d9
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/arabluatex_fullvoc.lua
@@ -0,0 +1,1015 @@
+--[[
+This file is part of the `arabluatex' package
+
+ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
+Copyright (C) 2016--2019 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/>.
+--]]
+
+hamzafv = {
+ -- next line for ʾiʿrāb hyphen
+ {a="(')(%-)([uaiUAI])", b="%1%3"},
+ -- next lines for ʾalif alone
+ {a="(%.A)([uai]?)l%-(%^n)", b="ا%2ل%3"}, --additional (^n is lunar)
+ {a="([%(%[%|%<%s%-O])(%.A)([uai]?)l%-(%^n)", b="%1ا%3%4"}, --additional (^n is lunar) --p
+ {a="(%.A)([uai]?)l%-([%_%^%.]?[tdrzsnc])", b="ا%2ل%3%3"},
+ {a="([%(%[%|%<%s%-O])(%.A)([uai]?)l%-([%_%^%.]?[tdrzsnc])", b="%1ا%3ل%4%4"}, --p
+ {a="%.A", b="ا"},
+ -- hard coded hamza
+ {a="|\"'", b="ء"},
+ {a="A\"'", b="آ"},
+ {a="[au]\"'", b="أ"},
+ {a="w\"'", b="ؤ"},
+ {a="i\"'", b="إ"},
+ {a="y\"'", b="ئ"},
+ {a="ؤ([^uaiUAI])", b="ؤْ%1"},
+ {a="ؤ(%p*)$", b="ؤْ%1"},
+ {a="ؤ(%p*%s)", b="ؤْ%1"},
+ {a="أ([^uaiUAI])", b="أْ%1"},
+ {a="أ(%p*)$", b="أْ%1"},
+ {a="أ(%p*%s)", b="أْ%1"},
+ {a="ئ([^uaiUAI])", b="ئْ%1"},
+ {a="ئ(%p*)$", b="ئْ%1"},
+ {a="ئ(%p*%s)", b="ئْ%1"},
+ -- hamza takes tašdīd too
+ {a="''([Uu])", b="ؤؤ%1"},
+ {a="''([Aa])", b="أأ%1"},
+ {a="''([Ii])", b="ئئ%1"},
+ -- inseparable adverbial particle 'a- + 'a
+ {a="\'(a)%-\'(a)", b="أ%1اأ%2"},
+ -- initial long u and i (for a, see below)
+ {a="%'%_U", b="أU"},
+ {a="%'%_I", b="إI"},
+ -- taḫfīfu 'l-hamza
+ {a="'u'([^uaiUAI])", b="أU%1"},
+ {a="'i'([^uaiUAI])", b="إI%1"},
+ {a="([wf]a)%-\'([^uaiUAIl][^%-])", b="%1أْ%2"},
+ {a="^u'([^uaiUAI])", b="اU%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])u'([^uaiUAI])", b="%1اU%2"},
+ {a="^i'([^uaiUAI])", b="اI%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])i'([^uaiUAI])", b="%1اI%2"},
+ -- madda (historic writing below)
+ {a="'a'([^uaiUAI])", b="آ%1"},
+ {a="([^uiyUI])\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="%1آ%2"},
+ {a="^\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="آ%1"},
+ {a="\'a?A(O[%_%^%.]?[%`%'btjghxdrzsfqklmnywAY]-O)", b="آ"},
+ {a="(%W)\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="%1آ%2"},
+ {a="(A)(O%'[%S]-O)", b="آ"},
+ {a="(A)(')(uN?%p*)$", b="aآء%3"},
+ {a="(A)(')(uN?)(%p*%s)", b="aآء%3%4"},
+ {a="(A)(')(iN?%p*)$", b="aآء%3"},
+ {a="(A)(')(iN?)(%p*%s)", b="aآء%3%4"},
+ {a="(A)(')([iI])", b="aآئ%3"}, -- historic madda
+ {a="(A)(')(u)", b="aآؤ%3"}, -- historic madda
+ {a="(A)(')", b="aآء"}, -- historic madda
+ -- initial (needs both ^ and %W patterns)
+ -- 'aw: the diphthong is to be resolved into 'awi' (next 8 lines)
+ {a="^('aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(%W)('aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1%2i"},
+ {a="^('aw)(O)([%(%[%|%<]?\"?[uai])([%S]-O)", b="%1i"},
+ {a="(%W)('aw)(O)([%(%[%|%<]?\"?[uai])([%S]-O)", b="%1%2i"},
+ {a="^('aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ {a="(%W)('aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1%2i%3%4"},
+ {a="^('aw)(%s)([%(%[%|%<]?\"?[uai])", b="%1i%2%3"},
+ {a="(%W)('aw)(%s)([%(%[%|%<]?\"?[uai])", b="%1%2i%3%4"},
+ -- then the 'initial' rules for the remaining cases
+ {a="^(')([ua])", b="أ%2"},
+ {a="^(')(i)", b="إ%2"},
+ -- consider replacing initial %W with [%s%(%[%<%-]:
+ -- {a="(%W)(')([ua])", b="%1أ%3"},
+ -- {a="(%W)(')(i)", b="%1إ%3"},
+ {a="([%s%(%[%<%-])(')([ua])", b="%1أ%3"},
+ {a="([%s%(%[%<%-])(')(i)", b="%1إ%3"},
+ -- final
+ -- mi'aT is special orthography (unlike ^say'aN and .zim'aN):
+ -- {a="(%^sa%.?[yY])(\"?%|?)(%')(aN)", b="%1%2ئ%4"}, --new
+ -- {a="(.zi?m)(%')(aN)", b="%1ئ%3"}, --new
+ {a="(mi)(%')(a[Tt])", b="%1ائ%3"},
+ {a="(mi)(%')(aN%_?[AY])", b="%1أ%3"},
+ -- final hamzah is on the line after a letter of prolongation or a
+ -- consonant with sukūn
+ {a="([^Auai])(')(\"?[uai]N?)(%p*)$", b="%1ء%3%4"}, --new
+ {a="([^Auai])(')(\"?[uai]N?)(%p*%s)", b="%1ء%3%4"},
+-- u
+ {a="(u)(')([uai]N?%p*)$", b="%1ؤ%3"},
+ {a="(u)(')([uai]N?)(%p*%s)", b="%1ؤ%3%4"},
+ {a="(u)(')(%p*)$", b="%1ؤْ%3"},
+ {a="(u)(')(%p*%s)", b="%1ؤْ%3"},
+-- a
+ {a="(a)(')(A%p*)$", b="%1آ"},
+ {a="(a)(')(A)(%p*%s)", b="%1آ%4"},
+ {a="(a)(')([u]N?%p*)$", b="%1أ%3"},
+ {a="(a)(')([u]N?)(%p*%s)", b="%1أ%3%4"},
+ {a="(a)(')(a%p*)$", b="%1أ%3"},
+ {a="(a)(')(a)(%p*%s)", b="%1أ%3%4"},
+ {a="(a)(')(aN%p*)$", b="%1أً"},
+ {a="(a)(')(aN)(%p*%s)", b="%1أً%4"},
+ {a="(a)(')([i]N?%p*)$", b="%1إ%3"},
+ {a="(a)(')([i]N?)(%p*%s)", b="%1إ%3%4"},
+ {a="(a)(')(%p*)$", b="%1أْ%3"},
+ {a="(a)(')(%p*%s)", b="%1أْ%3"},
+-- i
+ {a="(i)(')([uai]N?%p*)$", b="%1ئ%3"},
+ {a="(i)(')([uai]N?)(%p*%s)", b="%1ئ%3%4"},
+ {a="(i)(')(%p*)$", b="%1ئْ%3"},
+ {a="(i)(')(%p*%s)", b="%1ئْ%3"},
+--
+ -- middle
+ {a="([UIwy])(')", b="%1ء"}, --new
+ -- {a="([Iy])(')", b="%1ئ"}, --included in the above line
+ {a="([^uai])(')([uU])", b="%1ؤ%3"},
+ {a="([^uai])(')(%_?[aAY])", b="%1أ%3"},
+ {a="([^uai])(')([iI])", b="%1ئ%3"},
+ {a="(u)(')([uU])", b="%1ؤ%3"},
+ {a="(u)(')(%_?[aAY])", b="%1ؤ%3"},
+ {a="(u)(')([iI])", b="%1ئ%3"},
+ {a="(a)(')(%_?[aAY])", b="%1أ%3"},
+ {a="(a)(')([uU])", b="%1ؤ%3"},
+ {a="(a)(')([iI])", b="%1ئ%3"},
+ {a="(i)(')(%_?[aAY])", b="%1ئ%3"},
+ {a="(i)(')([uU])", b="%1ئ%3"},
+ {a="(i)(')([iI])", b="%1ئ%3"},
+ {a="(a)(')([^uaiUAI])", b="%1أْ%3"},
+ {a="(u)(')([^uaiUAI])", b="%1ؤْ%3"},
+ {a="(i)(')([^uaiUAI])", b="%1ئْ%3"}
+}
+
+hamzafveasy = { -- differences marked below with 'easy'
+ -- next line for ʾiʿrāb hyphen
+ {a="(')(%-)([uaiUAI])", b="%1%3"},
+ -- next lines for ʾalif alone
+ {a="(%.A)([uai]?)l%-(%^n)", b="ا%2ل%3"}, --additional (^n is lunar)
+ {a="([%(%[%|%<%s%-O])(%.A)([uai]?)l%-(%^n)", b="%1ا%3%4"}, --additional (^n is lunar) --p
+ {a="(%.A)([uai]?)l%-([%_%^%.]?[tdrzsnc])", b="ا%2ل%3%3"},
+ {a="([%(%[%|%<%s%-O])(%.A)([uai]?)l%-([%_%^%.]?[tdrzsnc])", b="%1ا%3ل%4%4"}, --p
+ {a="%.A", b="ا"},
+ -- hard coded hamza
+ {a="|\"'", b="ء"},
+ {a="A\"'", b="آ"},
+ {a="[au]\"'", b="أ"},
+ {a="w\"'", b="ؤ"},
+ {a="i\"'", b="إ"},
+ {a="y\"'", b="ئ"},
+ {a="ؤ([^uaiUAI])", b="ؤْ%1"},
+ {a="ؤ(%p*)$", b="ؤْ%1"},
+ {a="ؤ(%p*%s)", b="ؤْ%1"},
+ {a="أ([^uaiUAI])", b="أْ%1"},
+ {a="أ(%p*)$", b="أْ%1"},
+ {a="أ(%p*%s)", b="أْ%1"},
+ {a="ئ([^uaiUAI])", b="ئْ%1"},
+ {a="ئ(%p*)$", b="ئْ%1"},
+ {a="ئ(%p*%s)", b="ئْ%1"},
+ -- hamza takes tašdīd too
+ {a="''([Uu])", b="ؤؤ%1"},
+ {a="''([Aa])", b="أأ%1"},
+ {a="''([Ii])", b="ئئ%1"},
+ -- inseparable adverbial particle 'a- + 'a
+ {a="\'(a)%-\'(a)", b="أ%1اأ%2"},
+ -- initial long u and i (for a, see below)
+ {a="%'%_U", b="أU"},
+ {a="%'%_I", b="إI"},
+ -- taḫfīfu 'l-hamza
+ {a="'u'([^uaiUAI])", b="أU%1"},
+ {a="'i'([^uaiUAI])", b="إI%1"},
+ {a="([wf]a)%-\'([^uaiUAIl][^%-])", b="%1أْ%2"},
+ {a="^u'([^uaiUAI])", b="اU%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])u'([^uaiUAI])", b="%1اU%2"},
+ {a="^i'([^uaiUAI])", b="اI%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])i'([^uaiUAI])", b="%1اI%2"},
+ -- madda (historic writing below)
+ {a="'a'([^uaiUAI])", b="آ%1"},
+ {a="([^uiyUI])\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="%1آ%2"},
+ {a="^\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="آ%1"},
+ {a="\'a?A(O[%_%^%.]?[%`%'btjghxdrzsfqklmnywAY]-O)", b="آ"},
+ {a="(%W)\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="%1آ%2"},
+ --easy (begin)
+ {a="(A)(O%'[%S]-O)", b="ا"},
+ {a="(A)(')(uN?%p*)$", b="aاء%3"},
+ {a="(A)(')(uN?)(%p*%s)", b="aاء%3%4"},
+ {a="(A)(')(iN?%p*)$", b="aاء%3"},
+ {a="(A)(')(iN?)(%p*%s)", b="aاء%3%4"},
+ {a="(A)(')([iI])", b="aائ%3"}, -- historic madda
+ {a="(A)(')(u)", b="aاؤ%3"}, -- historic madda
+ {a="(A)(')", b="aاء"}, -- historic madda
+ --easy (end)
+ -- initial (needs both ^ and %W patterns)
+ -- 'aw: the diphthong is to be resolved into 'awi' (next 8 lines)
+ {a="^('aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(%W)('aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1%2i"},
+ {a="^('aw)(O)([%(%[%|%<]?\"?[uai])([%S]-O)", b="%1i"},
+ {a="(%W)('aw)(O)([%(%[%|%<]?\"?[uai])([%S]-O)", b="%1%2i"},
+ {a="^('aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ {a="(%W)('aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1%2i%3%4"},
+ {a="^('aw)(%s)([%(%[%|%<]?\"?[uai])", b="%1i%2%3"},
+ {a="(%W)('aw)(%s)([%(%[%|%<]?\"?[uai])", b="%1%2i%3%4"},
+ -- then the 'initial' rules for the remaining cases
+ {a="^(')([ua])", b="أ%2"},
+ {a="^(')(i)", b="إ%2"},
+ -- consider replacing initial %W with [%s%(%[%<%-]:
+ -- {a="(%W)(')([ua])", b="%1أ%3"},
+ -- {a="(%W)(')(i)", b="%1إ%3"},
+ {a="([%s%(%[%<%-])(')([ua])", b="%1أ%3"},
+ {a="([%s%(%[%<%-])(')(i)", b="%1إ%3"},
+ -- final
+ -- mi'aT is special orthography (unlike ^say'aN and .zim'aN)
+ -- {a="(%^sa%.?[yY])(\"?%|?)(%')(aN)", b="%1%2ئ%4"}, --new
+ -- {a="(.zi?m)(%')(aN)", b="%1ئ%3"}, --new
+ {a="(mi)(%')(a[Tt])", b="%1ائ%3"},
+ {a="(mi)(%')(aN%_?[AY])", b="%1أ%3"},
+ -- easy (begin)
+ -- The Munjid says that such words as radI'aN do not have the
+ -- hamzah alone on the line, so take out the following two lines
+ -- (final hamzah is on the line after a letter of prolongation or a
+ -- consonant with sukūn)
+ -- {a="([^Auai])(')(\"?[uai]N?)(%p*)$", b="%1ء%3%4"}, --new
+ -- {a="([^Auai])(')(\"?[uai]N?)(%p*%s)", b="%1ء%3%4"},
+ {a="([^Auai])(')(\"?aN)(%p*)$", b="%1ئ%3%4"}, --new
+ {a="([^Auai])(')(\"?aN)(%p*%s)", b="%1ئ%3%4"}, --new
+ {a="([^uai])(')(\"?a)(%p*)$", b="%1ء%3%4"}, --new
+ {a="([^uai])(')(\"?a)(%p*%s)", b="%1ء%3%4"}, --new
+ {a="([^uai])(')(\"?[ui]N?)(%p*)$", b="%1ء%3%4"}, --new
+ {a="([^uai])(')(\"?[ui]N?)(%p*%s)", b="%1ء%3%4"}, --new
+ --easy (end)
+-- u
+ {a="(u)(')([uai]N?%p*)$", b="%1ؤ%3"},
+ {a="(u)(')([uai]N?)(%p*%s)", b="%1ؤ%3%4"},
+ {a="(u)(')(%p*)$", b="%1ؤْ%3"},
+ {a="(u)(')(%p*%s)", b="%1ؤْ%3"},
+-- a
+ {a="(a)(')(A%p*)$", b="%1آ"},
+ {a="(a)(')(A)(%p*%s)", b="%1آ%4"},
+ {a="(a)(')([u]N?%p*)$", b="%1أ%3"},
+ {a="(a)(')([u]N?)(%p*%s)", b="%1أ%3%4"},
+ {a="(a)(')(a%p*)$", b="%1أ%3"},
+ {a="(a)(')(a)(%p*%s)", b="%1أ%3%4"},
+ {a="(a)(')(aN%p*)$", b="%1أً"},
+ {a="(a)(')(aN)(%p*%s)", b="%1أً%4"},
+ {a="(a)(')([i]N?%p*)$", b="%1إ%3"},
+ {a="(a)(')([i]N?)(%p*%s)", b="%1إ%3%4"},
+ {a="(a)(')(%p*)$", b="%1أْ%3"},
+ {a="(a)(')(%p*%s)", b="%1أْ%3"},
+-- i
+ {a="(i)(')([uai]N?%p*)$", b="%1ئ%3"},
+ {a="(i)(')([uai]N?)(%p*%s)", b="%1ئ%3%4"},
+ {a="(i)(')(%p*)$", b="%1ئْ%3"},
+ {a="(i)(')(%p*%s)", b="%1ئْ%3"},
+--
+ -- middle
+ {a="([Uw])(')", b="%1ء"}, --new
+ {a="([Iy])(')", b="%1ئ"}, --easy
+ {a="([^uai])(')([uU])", b="%1ؤ%3"},
+ {a="([^uai])(')(%_?[aAY])", b="%1أ%3"},
+ {a="([^uai])(')([iI])", b="%1ئ%3"},
+ {a="(u)(')([uU])", b="%1ؤ%3"},
+ {a="(u)(')(%_?[aAY])", b="%1ؤ%3"},
+ {a="(u)(')([iI])", b="%1ئ%3"},
+ {a="(a)(')(%_?[aAY])", b="%1أ%3"},
+ {a="(a)(')([uU])", b="%1ؤ%3"},
+ {a="(a)(')([iI])", b="%1ئ%3"},
+ {a="(i)(')(%_?[aAY])", b="%1ئ%3"},
+ {a="(i)(')([uU])", b="%1ئ%3"},
+ {a="(i)(')([iI])", b="%1ئ%3"},
+ {a="(a)(')([^uaiUAI])", b="%1أْ%3"},
+ {a="(u)(')([^uaiUAI])", b="%1ؤْ%3"},
+ {a="(i)(')([^uaiUAI])", b="%1ئْ%3"}
+}
+
+tanwinfv = { -- with assimilations (\SetArbDflt*)
+ -- assimilations (begin)
+ {a="(O[%S]-)(%-?[uai]N[UI]?)(O)([rlmnwy])", b="%4%4"},
+ {a="(%-?[uai]NU)(%s)([rlmnwy])", b="%1%2%3%3"},
+ -- assimilations (end)
+ {a="(O[%S]-)(%-?[uai]N[UI]?)(O)([uai])", b="ٱ"},
+ {a="%-?(uNU)(%s)([uai])", b="%1%2ٱ"},
+ {a="%-?(aNU)(%s)([uai])", b="%1%2ٱ"},
+ {a="%-?(iNU)(%s)([uai])", b="%1%2ٱ"},
+ {a="%-?uNU", b="ٌو"},
+ {a="%-?aNU", b="ًوا"},
+ {a="%-?iNU", b="ٍو"},
+ {a="%-?([uai]N)(%s)([uai])", b="%1%2ٱ"},
+ {a="%-?(aN[%_]?[AY])(%s)([uai])", b="%1%2ٱ"},
+ -- assimilations (begin)
+ {a="%-?(uN)(%s)([rlmnwy])", b="ٌ%2%3%3"},
+ {a="(O[%S]-)(%-?aN)(_A)(O)([rlmnwy])", b="%5%5"},
+ {a="(O[%S]-)(%-?aN)(Y)(O)([rlmnwy])", b="%5%5"},
+ {a="%-?(aN)(_A)(%s)([rlmnwy])", b="ًى%3%4%4"},
+ {a="%-?(aN)(Y)(%s)([rlmnwy])", b="ًى%3%4%4"},
+ {a="(T)%-?(aN)(%s)([rlmnwy])", b="%1ً%3%4%4"},
+-- {a="(ء)%-?(aN)(%s)([rlmnwy])", b="%1%2%3%4%4"}, --new
+ {a="([^TA])%-?(aN)(%s)([rlmnwy])", b="%1ًا%3%4%4"},
+ {a="%-?(iNI?)(%s)([rlmnwy])", b="ٍ%2%3%3"},
+ -- assimilations (end)
+ {a="(O[%S]-)(%-?aN)(_A)(O)([uai])", b="ٱ"},
+ {a="(O[%S]-)(%-?aN)(Y)(O)([uai])", b="ٱ"},
+ -- quoted tanwīn (begin)
+ {a="%-?(\"uN)", b=""},
+ {a="(B)%-?(\"aN)", b="%1"},
+ {a="%-?(\"aN)(_A)", b="ى"},
+ {a="%-?(\"aN)(Y)", b="ى"},
+ {a="(T)%-?(\"aN)", b="%1"},
+ {a="([اآ])(ء)%-?(\"aN)", b="%1%2"}, --new
+ {a="([^TA])%-?(\"aN)", b="%1ا"},
+ {a="%-?(\"iNI?)", b=""},
+ -- quoted tanwīn (end)
+ {a="%-?(uN)", b="ٌ"},
+ {a="(B)%-?(aN)", b="%1ً"},
+ -- needed by \arbcolor:
+ {a="%-?(aN)(O[%S]-%_AO)", b="ً"},
+ {a="%-?(aN)(O[%S]-YO)", b="ً"},
+ {a="(O[%S]-TO)%-?(aN)", b="ً"},
+ {a="(O[%S]-)([اآ])(ء)(O)%-?(aN)", b="ً"}, --new
+ {a="(O[%S]-[^TA]O)%-?(aN)", b="ًا"},
+ --
+ {a="%-?(aN)(_A)", b="ًى"},
+ {a="%-?(aN)(Y)", b="ًى"},
+ {a="(T)%-?(aN)", b="%1ً"},
+ {a="([اآ])(ء)%-?(aN)", b="%1%2ً"}, --new
+ {a="([^TA])%-?(aN)", b="%1ًا"},
+ {a="%-?(iNI?)", b="ٍ"}
+}
+
+tanwinfveasy = { -- no assimilations (see below)
+ -- assimilations (begin)
+--easy {a="(O[%S]-)(%-?[uai]N[UI]?)(O)([rlmnwy])", b="%4%4"},
+--easy {a="(%-?[uai]NU)(%s)([rlmnwy])", b="%1%2%3%3"},
+ -- assimilations (end)
+ {a="(O[%S]-)(%-?[uai]N[UI]?)(O)([uai])", b="ٱ"},
+ {a="%-?(uNU)(%s)([uai])", b="%1%2ٱ"},
+ {a="%-?(aNU)(%s)([uai])", b="%1%2ٱ"},
+ {a="%-?(iNU)(%s)([uai])", b="%1%2ٱ"},
+ {a="%-?uNU", b="ٌو"},
+ {a="%-?aNU", b="ًوا"},
+ {a="%-?iNU", b="ٍو"},
+ {a="%-?([uai]N)(%s)([uai])", b="%1%2ٱ"},
+ {a="%-?(aN[%_]?[AY])(%s)([uai])", b="%1%2ٱ"},
+ -- assimilations (begin)
+--easy {a="%-?(uN)(%s)([rlmnwy])", b="ٌ%2%3%3"},
+--easy {a="(O[%S]-)(%-?aN)(_A)(O)([rlmnwy])", b="%5%5"},
+--easy {a="(O[%S]-)(%-?aN)(Y)(O)([rlmnwy])", b="%5%5"},
+--easy {a="%-?(aN)(_A)(%s)([rlmnwy])", b="ًى%3%4%4"},
+--easy {a="%-?(aN)(Y)(%s)([rlmnwy])", b="ًى%3%4%4"},
+--easy {a="(T)%-?(aN)(%s)([rlmnwy])", b="%1ً%3%4%4"},
+--easy {a="(ء)%-?(aN)(%s)([rlmnwy])", b="%1%2%3%4%4"}, --new
+--easy {a="([^TA])%-?(aN)(%s)([rlmnwy])", b="%1ًا%3%4%4"},
+--easy {a="%-?(iNI?)(%s)([rlmnwy])", b="ٍ%2%3%3"},
+ -- assimilations (end)
+ {a="(O[%S]-)(%-?aN)(_A)(O)([uai])", b="ٱ"},
+ {a="(O[%S]-)(%-?aN)(Y)(O)([uai])", b="ٱ"},
+ -- quoted tanwīn (begin)
+ {a="%-?(\"uN)", b=""},
+ {a="(B)%-?(\"aN)", b="%1"},
+ {a="%-?(\"aN)(_A)", b="ى"},
+ {a="%-?(\"aN)(Y)", b="ى"},
+ {a="(T)%-?(\"aN)", b="%1"},
+ {a="([اآ])(ء)%-?(\"aN)", b="%1%2"}, --new
+ {a="([^TA])%-?(\"aN)", b="%1ا"},
+ {a="%-?(\"iNI?)", b=""},
+ -- quoted tanwīn (end)
+ {a="%-?(uN)", b="ٌ"},
+ {a="(B)%-?(aN)", b="%1ً"},
+ -- needed by \arbcolor:
+ {a="%-?(aN)(O[%S]-%_AO)", b="ً"},
+ {a="%-?(aN)(O[%S]-YO)", b="ً"},
+ {a="(O[%S]-TO)%-?(aN)", b="ً"},
+ {a="(O[%S]-)([اآ])(ء)(O)%-?(aN)", b="ً"}, --new
+ {a="(O[%S]-[^TA]O)%-?(aN)", b="ًا"},
+ --
+ {a="%-?(aN)(_A)", b="ًى"},
+ {a="%-?(aN)(Y)", b="ًى"},
+ {a="(T)%-?(aN)", b="%1ً"},
+ {a="([اآ])(ء)%-?(aN)", b="%1%2ً"}, --new
+ {a="([^TA])%-?(aN)", b="%1ًا"},
+ {a="%-?(iNI?)", b="ٍ"}
+}
+
+trigraphsfv = { -- trigraphs or more
+ -- ʾalif al-waṣl: put it back on with \arbnull
+ {a="(O[%S]-)([%'a]l%-)(O)(\"?[uai])", b="ٱ"},
+ -- 'llatI / 'llad_I
+ {a="^'ll(a)([%_]?[dt])", b="ٱلّ%1%2"},
+ {a="([%(%[%|%<%s%-])'ll(a)([%_]?[dt])", b="%1ٱلّ%2%3"}, --p
+ -- law: the diphthong is to be resolved into 'awi' (next 8 lines)
+ {a="^(law)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(%W)(law)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1%2i"},
+ {a="^(law)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(%W)(law)(O)(\"?[uai])([%S]-O)", b="%1%2i"},
+ {a="^(law)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ {a="(%W)(law)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1%2i%3%4"},
+ {a="^(law)(%s)([%(%[%|%<]?\"?[uai])", b="%1i%2%3"},
+ {a="(%W)(law)(%s)([%(%[%|%<]?\"?[uai])", b="%1%2i%3%4"},
+ -- al- + lām
+ {a="^(a)l%-(l)", b="ا%1ل%2%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-(l)", b="%1ا%2ل%3%3"}, --p
+ -- al- + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)l%-(%^n)", b="ا%1ل%2"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-O])(a)l%-(%^n)", b="%1ا%2ل%3"}, -- ^n is lunar --p
+ {a="^(a)l%-([%_%^%.]?[tdrzsnc])", b="ا%1ل%2%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-([%_%^%.]?[tdrzsnc])", b="%1ا%2ل%3%3"}, --p
+ -- assim. art. + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)(%^n)%-", b="ا%1ل"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-O])(a)(%^n)%-", b="%1ا%2ل"}, -- ^n is lunar --p
+ {a="^(a)([%_%^%.]?[tdrzsnc])%-", b="ا%1ل%2"},
+ {a="([%(%[%|%<%s%-O])(a)([%_%^%.]?[tdrzsnc])%-", b="%1ا%2ل%3"}, --p
+ -- al- + initial unstable hamza
+ {a="^(a)l%-(\"?[uai])", b="ا%1ل%2ٱ"},
+ {a="([%(%[%|%<%s%-O])(a)l%-(\"?[uai])", b="%1ا%2ل%3ٱ"}, --p
+ -- li-/la + art. + initial unstable hamza is a special orthography
+ {a="l([ai])%-l%-(\"?[uai])", b="ل%1ل%2ٱ"},
+ -- al- + lunar consonant (i.e. what remains)
+ {a="^(a)l%-", b="ا%1لْ"},
+ {a="([%(%[%|%<%s%-O])(a)l%-", b="%1ا%2لْ"}, --p
+ -- diphthongs to be resolved before ʾalif conjunctionis
+ {a="(aW)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="awuا"},
+ {a="(aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1u"},
+ {a="(ay)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(aW)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="awuا%2%3"},
+ {a="(aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1u%2%3"},
+ {a="(ay)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ -- art. with waṣla + lām
+ {a="'l%-(l)", b="ٱل%1%1"},
+ -- art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'l%-(%^n)", b="ٱل%1"}, -- ^n is lunar
+ {a="'l%-([%_%^%.]?[tdrzsnc])", b="ٱل%1%1"},
+ -- li-/la- + art. + lām
+ {a="l([ai])%-l%-(l)", b="ل%1%2%2"},
+ -- assim. art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'(%^n)%-", b="ٱل"}, -- ^n is lunar
+ {a="'([%_%^%.]?[tdrzsnc])%-", b="ٱل%1"},
+ -- li-/la- + art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-l%-(%^n)", b="ل%1ل%2"}, -- ^n is lunar
+ {a="l([ai])%-l%-([%_%^%.]?[tdrzsnc])", b="ل%1ل%2%2"},
+ -- li-/la- + assim. art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-(%^n)%-(%^n)", b="ل%1ل%3"}, -- ^n is lunar
+ {a="l([ai])%-([%_%^%.]?[tdrzsnc])%-([%_%^%.]?[tdrzsnc])", b="ل%1ل%3%3"},
+ -- art. with waṣla + initial unstable hamza
+ {a="'l%-(\"?[uai])", b="ٱل%1ٱ"},
+ -- art. with waṣla + lunar consonant (i.e. what remains)
+ {a="'l%-", b="ٱلْ"},
+ -- the silent wāw
+ {a="uU(%p*)$", b="uو%1"},
+ {a="uU(%p*%s)", b="uو%1"},
+ {a="aU(%p*)$", b="aو%1"},
+ {a="aU(%p*%s)", b="aو%1"},
+ {a="iU(%p*)$", b="iو%1"},
+ {a="iU(%p*%s)", b="iو%1"},
+ -- words ending in -āT with silent wāw/yāʾ
+ {a="(_a)UA", b="%1وا"},
+ {a="(_a)U", b="%1و"},
+ {a="(_a)I", b="%1ي"}
+}
+
+-- idgham/assimilation rules for trigraphs apply here : see voc lua
+-- file.
+
+trigraphsfveasy = { -- trigraphs or more (see 'easy' tag below for the diffs)
+ -- ʾalif al-waṣl: put it back on with \arbnull
+ {a="(O[%S]-)([%'a]l%-)(O)(\"?[uai])", b="ٱ"},
+ -- 'llatI / 'llad_I
+ {a="^'ll(a)([%_]?[dt])", b="ٱلّ%1%2"},
+ {a="([%(%[%|%<%s%-])'ll(a)([%_]?[dt])", b="%1ٱلّ%2%3"}, --p
+ -- law: the diphthong is to be resolved into 'awi' (next 8 lines)
+ {a="^(law)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(%W)(law)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1%2i"},
+ {a="^(law)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(%W)(law)(O)(\"?[uai])([%S]-O)", b="%1%2i"},
+ {a="^(law)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ {a="(%W)(law)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1%2i%3%4"},
+ {a="^(law)(%s)([%(%[%|%<]?\"?[uai])", b="%1i%2%3"},
+ {a="(%W)(law)(%s)([%(%[%|%<]?\"?[uai])", b="%1%2i%3%4"},
+ -- al- + lām
+ {a="^(a)l%-(l)", b="ا%1ل%2%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-(l)", b="%1ا%2ل%3%3"}, --p
+ -- al- + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)l%-(%^n)", b="ا%1ل%2"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-O])(a)l%-(%^n)", b="%1ا%2ل%3"}, -- ^n is lunar --p
+ {a="^(a)l%-([%_%^%.]?[tdrzsnc])", b="ا%1ل%2%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-([%_%^%.]?[tdrzsnc])", b="%1ا%2ل%3%3"}, --p
+ -- assim. art. + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)(%^n)%-", b="ا%1ل"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-O])(a)(%^n)%-", b="%1ا%2ل"}, -- ^n is lunar --p
+ {a="^(a)([%_%^%.]?[tdrzsnc])%-", b="ا%1ل%2"},
+ {a="([%(%[%|%<%s%-O])(a)([%_%^%.]?[tdrzsnc])%-", b="%1ا%2ل%3"}, --p
+ -- al- + initial unstable hamza
+ {a="^(a)l%-(\"?[uai])", b="ا%1ل%2ٱ"},
+ {a="([%(%[%|%<%s%-O])(a)l%-(\"?[uai])", b="%1ا%2ل%3ٱ"}, --p
+ -- li-/la + art. + initial unstable hamza is a special orthography
+ {a="l([ai])%-l%-(\"?[uai])", b="ل%1ل%2ٱ"},
+ -- al- + lunar consonant (i.e. what remains)
+ {a="^(a)l%-", b="ا%1لْ"},
+ {a="([%(%[%|%<%s%-O])(a)l%-", b="%1ا%2لْ"}, --p
+ -- diphthongs to be resolved before ʾalif conjunctionis
+ {a="(aW)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="awuا"},
+ {a="(aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1u"},
+ {a="(ay)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(aW)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="awuا%2%3"},
+ {a="(aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1u%2%3"},
+ {a="(ay)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ -- art. with waṣla + lām
+ {a="'l%-(l)", b="ٱل%1%1"},
+ -- art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'l%-(%^n)", b="ٱل%1"}, -- ^n is lunar
+ {a="'l%-([%_%^%.]?[tdrzsnc])", b="ٱل%1%1"},
+ -- li-/la- + art. + lām
+ {a="l([ai])%-l%-(l)", b="ل%1%2%2"},
+ -- assim. art. with waṣla + solar consonant
+ -- ('c' and '^n' are is an additional characters)
+ {a="'(%^n)%-", b="ٱل"}, -- ^n is lunar
+ {a="'([%_%^%.]?[tdrzsnc])%-", b="ٱل%1"},
+ -- li-/la- + art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-l%-(%^n)", b="ل%1ل%2"}, -- ^n is lunar
+ {a="l([ai])%-l%-([%_%^%.]?[tdrzsnc])", b="ل%1ل%2%2"},
+ -- li-/la- + assim. art. + solar consonant is a special orthography
+ -- ('c and '^n' are additional characters)
+ {a="l([ai])%-(%^n)%-(%^n)", b="ل%1ل%3"}, -- ^n is lunar
+ {a="l([ai])%-([%_%^%.]?[tdrzsnc])%-([%_%^%.]?[tdrzsnc])", b="ل%1ل%3%3"},
+ -- art. with waṣla + initial unstable hamza
+ {a="'l%-(\"?[uai])", b="ٱل%1ٱ"},
+ -- art. with waṣla + lunar consonant (i.e. what remains)
+ {a="'l%-", b="ٱلْ"},
+ -- the silent wāw
+ {a="uU(%p*)$", b="uو%1"},
+ {a="uU(%p*%s)", b="uو%1"},
+ {a="aU(%p*)$", b="aو%1"},
+ {a="aU(%p*%s)", b="aو%1"},
+ {a="iU(%p*)$", b="iو%1"},
+ {a="iU(%p*%s)", b="iو%1"},
+ -- words ending in -āT with silent wāw/yāʾ
+ {a="(_a)UA", b="%1وا"},
+ {a="(_a)U", b="%1و"},
+ {a="(_a)I", b="%1ي"}
+}
+
+digraphsfvidgham = {
+ -- ʾiʿrāb: straight double quote must be discarded
+ {a="(%-)(\"?[UI]na)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?[UI]na)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*)$", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?[uai])(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?[uai])(%p*)$", b="%2%3"},
+ -- ʾiʿrāb (end)
+ -- initial straight double quote gives a connective ʾalif
+ {a="^\"[uai]", b="ٱ"},
+ {a="([%(%[%|%<%s%-])\"[uai]", b="%1ٱ"}, --p
+ -- diphthongs to be resolved before ʾalif conjunctionis
+ {a="(aW)(O)(\"?[uai])([%S]-O)", b="awuا"},
+ {a="(aW)(%s)([%(%[%|%<]?)(\"?[uai])", b="awuا%2%3ٱ"}, --p
+ {a="(aw)(O)(\"?[uai])([%S]-O)", b="%1u"},
+ {a="(aw)(%s)([%(%[%|%<]?)(\"?[uai])", b="%1u%2%3ٱ"}, --p
+ {a="(ay)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(ay)(%s)([%(%[%|%<]?)(\"?[uai])", b="%1i%2%3ٱ"}, --p
+ -- hyphen + initial alif without hamza
+ -- {a="([uai]%-)(\"?[uai])", b="%1ٱ"},
+ {a="([uai]%-)(\"?[uai])([%^%_%.%`]?)([%aأإؤئ])", b="%1ٱ%3%4"},
+ -- initial alif without hamza (next 4 lines)
+ {a="(O[%S]-)([uaiUAIY])(O)(\"?[uai])", b="ٱ"},
+ {a="([%_]?[uaiUAIY])(%s[%(%[%|%<]?)(\"?[uai])", b="%1%2ٱ"}, --p
+ {a="^([%(%[%|%<]?)(\"?[uai])", b="%1ا%2"}, --p
+ {a="(%s)([%(%[%|%<]?)(\"?[uai])", b="%1%2ا%3"}, --p
+ {a="%-%-", b="ـ"},
+ {a="ؤؤ", b="ؤّ"},
+ {a="أأ", b="أّ"},
+ {a="ئئ", b="ئّ"},
+ {a="bb", b="بّ"},
+ {a="BB", b="ـّ"},
+ {a="([%_%^%.])([tghdsz])([tghdsz])", b="%1%2|%3"},
+ -- same as above for additional characters:
+ {a="([%_%^%.])([cn])([cn])", b="%1%2|%3"},
+ {a="tt", b="تّ"},
+ {a="%_t%_t", b="ثّ"},
+ {a="jj", b="جّ"},
+ {a="%^g%^g", b="جّ"},
+ {a="%.h%.h", b="حّ"},
+ {a="xx", b="خّ"},
+ {a="%_h%_h", b="خّ"},
+ {a="dd", b="دّ"},
+ {a="%_d%_d", b="ذّ"},
+ {a="rr", b="رّ"},
+ {a="zz", b="زّ"},
+ {a="ss", b="سّ"},
+ {a="%^s%^s", b="شّ"},
+ {a="%.s%.s", b="صّ"},
+ {a="%.d%.d", b="ضّ"},
+ {a="%.t%.t", b="طّ"},
+ {a="%.z%.z", b="ظّ"},
+ {a="%`%`", b="عّ"},
+ {a="%.g%.g", b="غّ"},
+ {a="ff", b="فّ"},
+ {a="qq", b="قّ"},
+ {a="kk", b="كّ"},
+ {a="ll", b="لّ"},
+ {a="mm", b="مّ"},
+ {a="nn", b="نّ"},
+ {a="hh", b="هّ"},
+ {a="ww", b="وّ"},
+ {a="yy", b="يّ"},
+ {a="%.y%.y", b="ىّ"},
+ -- additional characters + šaddah (begin)
+ {a="pp", b="پّ"},
+ {a="vv", b="ڤّ"},
+ {a="gg", b="گّ"},
+ {a="%^c%^c", b="چّ"},
+ {a="%^z%^z", b="ژّ"},
+ {a="%^n%^n", b="ڭّ"},
+ -- additional characters + šaddah (end)
+ -- sukūn begin
+ -- first, take out hyphen if any (next two lines):
+ {a="([ai]Y)%-([uaiUAI])", b="%1%2"},
+ {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])%-([uaiUAI])", b="%1%2"},
+ {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])(%p*)$", b="%1ْ%2"},
+ {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])(%p*%s)", b="%1ْ%2"},
+ {a="([ai]Y)([%_]?[^%_uaiUAIYًٌٍ])", b="%1ْ%2"},
+ {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])([%_]?[^%_uaiUAIYًٌٍ])", b="%1ْ%2"},
+ -- take out sukūn in cases of assimilation
+ {a="(n)(ْ)(%s)(ر)", b="%1%3%4"},
+ {a="(n)(ْ)(%s)(و)", b="%1%3%4"},
+ {a="(n)(ْ)(%s)(ي)", b="%1%3%4"},
+ {a="(n)(ْ)(%s)(ل)", b="%1%3%4"},
+ {a="(n)(ْ)(%s)(م)", b="%1%3%4"},
+ {a="(n)(ْ)(%s)(ن)", b="%1%3%4"},
+ {a="ْ\"", b="\""},
+ -- sukūn end
+ {a="_t", b="ث"},
+ {a="%^g", b="ج"},
+ {a="%.h", b="ح"},
+ {a="_h", b="خ"},
+ {a="_d", b="ذ"},
+ {a="%^s", b="ش"},
+ {a="%.s", b="ص"},
+ {a="%.d", b="ض"},
+ {a="%.t", b="ط"},
+ {a="%.z", b="ظ"},
+ {a="%.g", b="غ"},
+ {a="%.y", b="ى"},
+ -- additional characters (begin)
+ {a="%^c", b="چ"},
+ {a="%^z", b="ژ"},
+ {a="%^n", b="ڭ"},
+ -- additional characters (end)
+ {a="(U)(A)", b="%1ا"},
+ {a="WA", b="وْا"},
+ {a="(a)W\"", b="%1وا"},
+ {a="(a)W", b="%1وْا"},
+ {a="_A", b="aى"},
+ {a="_u", b="ٗ"},
+ {a="_a", b="ٰ"},
+ {a="_i", b="ٖ"},
+ {a="%.b", b="ٮ"},
+ {a="%.f", b="ڡ"},
+ {a="%.q", b="ٯ"},
+ {a="%.k", b="ک"},
+ {a="%.n", b="ں"},
+ {a="%^d", b="ڊ"}
+}
+
+digraphsfv = {
+ -- iʿrāb: straight double quote must be discarded
+ {a="(%-)(\"?[UI]na)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?[UI]na)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*)$", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?[uai])(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?[uai])(%p*)$", b="%2%3"},
+ -- ʾiʿrāb (end)
+ -- initial straight double quote gives a connective ʾalif
+ {a="^\"[uai]", b="ٱ"},
+ {a="([%(%[%|%<%s%-])\"[uai]", b="%1ٱ"}, --p
+ -- diphthongs to be resolved before ʾalif conjunctionis
+ {a="(aW)(O)(\"?[uai])([%S]-O)", b="awuا"},
+ {a="(aW)(%s)([%(%[%|%<]?)(\"?[uai])", b="awuا%2%3ٱ"}, --p
+ {a="(aw)(O)(\"?[uai])([%S]-O)", b="%1u"},
+ {a="(aw)(%s)([%(%[%|%<]?)(\"?[uai])", b="%1u%2%3ٱ"}, --p
+ {a="(ay)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(ay)(%s)([%(%[%|%<]?)(\"?[uai])", b="%1i%2%3ٱ"}, --p
+ -- hyphen + initial alif without hamza
+ -- {a="([uai]%-)(\"?[uai])", b="%1ٱ"},
+ {a="([uai]%-)(\"?[uai])([%^%_%.%`]?)([%aأإؤئ])", b="%1ٱ%3%4"},
+ -- initial alif without hamza (next 4 lines)
+ {a="(O[%S]-)([uaiUAIY])(O)(\"?[uai])", b="ٱ"},
+ {a="([%_]?[uaiUAIY])(%s[%(%[%|%<]?)(\"?[uai])", b="%1%2ٱ"}, --p
+ {a="^([%(%[%|%<]?)(\"?[uai])", b="%1ا%2"}, --p
+ {a="(%s)([%(%[%|%<]?)(\"?[uai])", b="%1%2ا%3"}, --p
+ {a="%-%-", b="ـ"},
+ {a="ؤؤ", b="ؤّ"},
+ {a="أأ", b="أّ"},
+ {a="ئئ", b="ئّ"},
+ {a="bb", b="بّ"},
+ {a="BB", b="ـّ"},
+ {a="([%_%^%.])([tghdsz])([tghdsz])", b="%1%2|%3"},
+ -- same as above for additional characters:
+ {a="([%_%^%.])([cn])([cn])", b="%1%2|%3"},
+ {a="tt", b="تّ"},
+ {a="%_t%_t", b="ثّ"},
+ {a="jj", b="جّ"},
+ {a="%^g%^g", b="جّ"},
+ {a="%.h%.h", b="حّ"},
+ {a="xx", b="خّ"},
+ {a="%_h%_h", b="خّ"},
+ {a="dd", b="دّ"},
+ {a="%_d%_d", b="ذّ"},
+ {a="rr", b="رّ"},
+ {a="zz", b="زّ"},
+ {a="ss", b="سّ"},
+ {a="%^s%^s", b="شّ"},
+ {a="%.s%.s", b="صّ"},
+ {a="%.d%.d", b="ضّ"},
+ {a="%.t%.t", b="طّ"},
+ {a="%.z%.z", b="ظّ"},
+ {a="%`%`", b="عّ"},
+ {a="%.g%.g", b="غّ"},
+ {a="ff", b="فّ"},
+ {a="qq", b="قّ"},
+ {a="kk", b="كّ"},
+ {a="ll", b="لّ"},
+ {a="mm", b="مّ"},
+ {a="nn", b="نّ"},
+ {a="hh", b="هّ"},
+ {a="ww", b="وّ"},
+ {a="yy", b="يّ"},
+ {a="%.y%.y", b="ىّ"},
+ -- additional characters + šaddah (begin)
+ {a="pp", b="پّ"},
+ {a="vv", b="ڤّ"},
+ {a="gg", b="گّ"},
+ {a="%^c%^c", b="چّ"},
+ {a="%^z%^z", b="ژّ"},
+ {a="%^n%^n", b="ڭّ"},
+ -- additional characters + šaddah (end)
+ -- sukūn begin
+ -- first, take out hyphen if any (next two lines):
+ {a="([ai]Y)%-([uaiUAI])", b="%1%2"},
+ {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])%-([uaiUAI])", b="%1%2"},
+ {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])(%p*)$", b="%1ْ%2"},
+ {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])(%p*%s)", b="%1ْ%2"},
+ {a="([ai]Y)([%_]?[^%_uaiUAIYًٌٍ])", b="%1ْ%2"},
+ {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])([%_]?[^%_uaiUAIYًٌٍ])", b="%1ْ%2"},
+ -- take out sukūn in cases of assimilation
+-- {a="(n)(ْ)(%s)(ر)", b="%1%3%4"},
+-- {a="(n)(ْ)(%s)(و)", b="%1%3%4"},
+-- {a="(n)(ْ)(%s)(ي)", b="%1%3%4"},
+-- {a="(n)(ْ)(%s)(ل)", b="%1%3%4"},
+-- {a="(n)(ْ)(%s)(م)", b="%1%3%4"},
+-- {a="(n)(ْ)(%s)(ن)", b="%1%3%4"},
+ {a="ْ\"", b="\""},
+ -- sukūn end
+ {a="_t", b="ث"},
+ {a="%^g", b="ج"},
+ {a="%.h", b="ح"},
+ {a="_h", b="خ"},
+ {a="_d", b="ذ"},
+ {a="%^s", b="ش"},
+ {a="%.s", b="ص"},
+ {a="%.d", b="ض"},
+ {a="%.t", b="ط"},
+ {a="%.z", b="ظ"},
+ {a="%.g", b="غ"},
+ {a="%.y", b="ى"},
+ -- additional characters (begin)
+ {a="%^c", b="چ"},
+ {a="%^z", b="ژ"},
+ {a="%^n", b="ڭ"},
+ -- additional characters (end)
+ {a="(U)(A)", b="%1ا"},
+ {a="WA", b="وْا"},
+ {a="(a)W\"", b="%1وا"},
+ {a="(a)W", b="%1وْا"},
+ {a="_A", b="aى"},
+ {a="_u", b="ٗ"},
+ {a="_a", b="ٰ"},
+ {a="_i", b="ٖ"},
+ {a="%.b", b="ٮ"},
+ {a="%.f", b="ڡ"},
+ {a="%.q", b="ٯ"},
+ {a="%.k", b="ک"},
+ {a="%.n", b="ں"},
+ {a="%^d", b="ڊ"}
+}
+
+digraphsfveasy = { -- see the differences under 'easy' marker below
+ -- ʾiʿrāb: straight double quote must be discarded
+ {a="(%-)(\"?[UI]na)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?[UI]na)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*)$", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?[uai])(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?[uai])(%p*)$", b="%2%3"},
+ -- ʾiʿrāb (end)
+ -- initial straight double quote gives a connective ʾalif
+ {a="^\"[uai]", b="ٱ"},
+ {a="([%(%[%|%<%s%-])\"[uai]", b="%1ٱ"}, --p
+ -- diphthongs to be resolved before ʾalif conjunctionis
+ {a="(aW)(O)(\"?[uai])([%S]-O)", b="awuا"},
+ {a="(aW)(%s)([%(%[%|%<]?)(\"?[uai])", b="awuا%2%3ٱ"}, --p
+ {a="(aw)(O)(\"?[uai])([%S]-O)", b="%1u"},
+ {a="(aw)(%s)([%(%[%|%<]?)(\"?[uai])", b="%1u%2%3ٱ"}, --p
+ {a="(ay)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(ay)(%s)([%(%[%|%<]?)(\"?[uai])", b="%1i%2%3ٱ"}, --p
+ -- hyphen + initial alif without hamza
+ -- {a="([uai]%-)(\"?[uai])", b="%1ٱ"},
+ {a="([uai]%-)(\"?[uai])([%^%_%.%`]?)([%aأإؤئ])", b="%1ٱ%3%4"},
+ -- initial alif without hamza (next 4 lines)
+ {a="(O[%S]-)([uaiUAIY])(O)(\"?[uai])", b="ٱ"},
+ {a="([%_]?[uaiUAIY])(%s[%(%[%|%<]?)(\"?[uai])", b="%1%2ٱ"}, --p
+ {a="^([%(%[%|%<]?)(\"?[uai])", b="%1ا%2"}, --p
+ {a="(%s)([%(%[%|%<]?)(\"?[uai])", b="%1%2ا%3"}, --p
+ {a="%-%-", b="ـ"},
+ {a="ؤؤ", b="ؤّ"},
+ {a="أأ", b="أّ"},
+ {a="ئئ", b="ئّ"},
+ {a="bb", b="بّ"},
+ {a="BB", b="ـّ"},
+ {a="([%_%^%.])([tghdsz])([tghdsz])", b="%1%2|%3"},
+ -- same as above for additional characters:
+ {a="([%_%^%.])([cn])([cn])", b="%1%2|%3"},
+ {a="tt", b="تّ"},
+ {a="%_t%_t", b="ثّ"},
+ {a="jj", b="جّ"},
+ {a="%^g%^g", b="جّ"},
+ {a="%.h%.h", b="حّ"},
+ {a="xx", b="خّ"},
+ {a="%_h%_h", b="خّ"},
+ {a="dd", b="دّ"},
+ {a="%_d%_d", b="ذّ"},
+ {a="rr", b="رّ"},
+ {a="zz", b="زّ"},
+ {a="ss", b="سّ"},
+ {a="%^s%^s", b="شّ"},
+ {a="%.s%.s", b="صّ"},
+ {a="%.d%.d", b="ضّ"},
+ {a="%.t%.t", b="طّ"},
+ {a="%.z%.z", b="ظّ"},
+ {a="%`%`", b="عّ"},
+ {a="%.g%.g", b="غّ"},
+ {a="ff", b="فّ"},
+ {a="qq", b="قّ"},
+ {a="kk", b="كّ"},
+ {a="ll", b="لّ"},
+ {a="mm", b="مّ"},
+ {a="nn", b="نّ"},
+ {a="hh", b="هّ"},
+ {a="ww", b="وّ"},
+ {a="yy", b="يّ"},
+ {a="%.y%.y", b="ىّ"},
+ -- additional characters + šaddah (begin)
+ {a="pp", b="پّ"},
+ {a="vv", b="ڤّ"},
+ {a="gg", b="گّ"},
+ {a="%^c%^c", b="چّ"},
+ {a="%^z%^z", b="ژّ"},
+ {a="%^n%^n", b="ڭّ"},
+ -- additional characters + šaddah (end)
+ -- sukūn begin ('easy' needs these rules to be taken out); but
+ -- first take out every previously generated sukūn by hamza rules,
+ -- so there be no need to edit them:
+ {a="ْ", b=""},
+ -- first, take out hyphen if any (next two lines):
+-- {a="([ai]Y)%-([uaiUAI])", b="%1%2"},
+-- {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])%-([uaiUAI])", b="%1%2"},
+-- {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])(%p*)$", b="%1ْ%2"},
+-- {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])(%p*%s)", b="%1ْ%2"},
+-- {a="([ai]Y)([%_]?[^%_uaiUAIYًٌٍ])", b="%1ْ%2"},
+-- {a="([%_%^%.]?[Bbtjghxdrzs%`fqklmnwy])([%_]?[^%_uaiUAIYًٌٍ])", b="%1ْ%2"},
+ -- take out sukūn in cases of assimilation
+-- {a="(n)(ْ)(%s)(ر)", b="%1%3%4"},
+-- {a="(n)(ْ)(%s)(و)", b="%1%3%4"},
+-- {a="(n)(ْ)(%s)(ي)", b="%1%3%4"},
+-- {a="(n)(ْ)(%s)([ل])", b="%1%3%4"},
+-- {a="(n)(ْ)(%s)([م])", b="%1%3%4"},
+-- {a="(n)(ْ)(%s)([ن])", b="%1%3%4"},
+-- {a="ْ\"", b="\""},
+ -- sukūn end
+ {a="_t", b="ث"},
+ {a="%^g", b="ج"},
+ {a="%.h", b="ح"},
+ {a="_h", b="خ"},
+ {a="_d", b="ذ"},
+ {a="%^s", b="ش"},
+ {a="%.s", b="ص"},
+ {a="%.d", b="ض"},
+ {a="%.t", b="ط"},
+ {a="%.z", b="ظ"},
+ {a="%.g", b="غ"},
+ {a="%.y", b="ى"},
+ -- additional characters (begin)
+ {a="%^c", b="چ"},
+ {a="%^z", b="ژ"},
+ {a="%^n", b="ڭ"},
+ -- additional characters (end)
+ {a="(U)(A)", b="%1ا"},
+ {a="WA", b="وْا"},
+ {a="(a)W\"", b="%1وا"},
+ {a="(a)W", b="%1وْا"},
+ {a="_A", b="aى"},
+ {a="_u", b="ٗ"},
+ {a="_a", b="ٰ"},
+ {a="_i", b="ٖ"},
+ {a="%.b", b="ٮ"},
+ {a="%.f", b="ڡ"},
+ {a="%.q", b="ٯ"},
+ {a="%.k", b="ک"},
+ {a="%.n", b="ں"},
+ {a="%^d", b="ڊ"}
+}
+
+singlefv = {
+ {a="b", b="ب"},
+ {a="t", b="ت"},
+ {a="j", b="ج"},
+ {a="x", b="خ"},
+ {a="d", b="د"},
+ {a="r", b="ر"},
+ {a="z", b="ز"},
+ {a="s", b="س"},
+ {a="f", b="ف"},
+ {a="`", b="ع"},
+ {a="f", b="ف"},
+ {a="q", b="ق"},
+ {a="k", b="ك"},
+ {a="l", b="ل"},
+ {a="m", b="م"},
+ {a="n", b="ن"},
+ {a="h", b="ه"},
+ {a="w", b="و"},
+ {a="y", b="ي"},
+ {a="T", b="ة"},
+ -- additional characters (begin)
+ {a="p", b="پ"},
+ {a="v", b="ڤ"},
+ {a="g", b="گ"},
+ -- additional characters (end)
+ {a="\"$", b=""},
+ {a="\"(%W)", b="%1"},
+ {a="\"([^uaiUAI])", b="%1"},
+ {a="o", b="ْ"}, -- hard-coded sukūn
+ {a="([^0-9])%-([^0-9])", b="%1%2"},
+ {a="B", b="ـ"},
+}
+
+singlefveasy = { -- see the differences under 'easy' tag below
+ {a="b", b="ب"},
+ {a="t", b="ت"},
+ {a="j", b="ج"},
+ {a="x", b="خ"},
+ {a="d", b="د"},
+ {a="r", b="ر"},
+ {a="z", b="ز"},
+ {a="s", b="س"},
+ {a="f", b="ف"},
+ {a="`", b="ع"},
+ {a="f", b="ف"},
+ {a="q", b="ق"},
+ {a="k", b="ك"},
+ {a="l", b="ل"},
+ {a="m", b="م"},
+ {a="n", b="ن"},
+ {a="h", b="ه"},
+ {a="w", b="و"},
+ {a="y", b="ي"},
+ {a="T", b="ة"},
+ -- additional characters (begin)
+ {a="p", b="پ"},
+ {a="v", b="ڤ"},
+ {a="g", b="گ"},
+ -- additional characters (end)
+ -- easy (begin): \" needs to put back the sukūn
+ {a="\"$", b="ْ"},
+ {a="\"(%W)", b="ْ%1"},
+ {a="\"([^uaiUAI])", b="ْ%1"},
+ -- easy (end)
+ {a="([^0-9])%-([^0-9])", b="%1%2"},
+ {a="B", b="ـ"},
+}
diff --git a/macros/luatex/latex/arabluatex/arabluatex_novoc.lua b/macros/luatex/latex/arabluatex/arabluatex_novoc.lua
new file mode 100644
index 0000000000..51418617b7
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/arabluatex_novoc.lua
@@ -0,0 +1,166 @@
+--[[
+This file is part of the `arabluatex' package
+
+ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
+Copyright (C) 2016--2019 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/>.
+--]]
+
+tanwinnv = {
+ -- assimilations (begin). These are good but may not apply here.
+-- {a="(O[%S]-)(%-?[uai]N[UI]?)(O)([rlmnwy])", b="%4%4"},
+-- {a="(%-?[uai]NU)(%s)([rlmnwy])", b="%1%2%3%3"},
+ -- assimilations (end)
+ {a="%-?uNU", b="و"},
+ {a="%-?aNU", b="وا"},
+ {a="%-?iNU", b="و"},
+ -- assimilations (begin). These are good but may not apply here.
+-- {a="%-?(uN)(%s)([rlmnwy])", b="|%2%3%3"},
+-- {a="(O[%S]-)(%-?aN)(_A)(O)([rlmnwy])", b="%5%5"},
+-- {a="(O[%S]-)(%-?aN)(Y)(O)([rlmnwy])", b="%5%5"},
+-- {a="%-?(aN)(_A)(%s)([rlmnwy])", b="ى%3%4%4"},
+-- {a="%-?(aN)(Y)(%s)([rlmnwy])", b="ى%3%4%4"},
+-- {a="(T)%-?(aN)(%s)([rlmnwy])", b="%1%3%4%4"},
+-- {a="(ء)%-?(aN)(%s)([rlmnwy])", b="%1%3%4%4"},
+-- {a="([^TA])%-?(aN)(%s)([rlmnwy])", b="%1ا%3%4%4"},
+-- {a="%-?(iNI?)(%s)([rlmnwy])", b="|%2%3%3"},
+ -- assimilations (end)
+ -- "quoted" tanwīn (begin)
+ {a="%-?(\"uN)", b="ٌ"},
+ {a="(B)%-?(\"aN)", b="%1ً"},
+ {a="%-?(\"aN)(_A)", b="ًى"},
+ {a="%-?(\"aN)(Y)", b="ًى"},
+ {a="(T)%-?(\"aN)", b="%1ً"},
+ {a="([اآ])(ء)%-?(\"aN)", b="%1%2ً"}, --new
+ {a="([^TA])%-?(\"aN)", b="%1ًا"},
+ {a="%-?(\"iNI?)", b="ٍ"},
+ -- "quoted" tanwīn (end)
+ {a="%-?(uN)", b=""},
+ {a="(B)%-?(aN)", b="%1"},
+ -- needed by \arbcolor:
+ {a="%-?(aN)(O[%S]-%_AO)", b=""},
+ {a="%-?(aN)(O[%S]-YO)", b=""},
+ {a="(O[%S]-TO)%-?(aN)", b=""},
+ {a="(O[%S]-)([اآ])(ء)(O)%-?(aN)", b=""}, --new
+ {a="(O[%S]-[^TA]O)%-?(aN)", b=""},
+ --
+ {a="%-?(aN)(_A)", b="ى"},
+ {a="%-?(aN)(Y)", b="ى"},
+ {a="(T)%-?(aN)", b="%1"},
+ {a="([اآ])(ء)%-?(aN)", b="%1%2"}, --new
+ {a="([^TA])%-?(aN)", b="%1ا"},
+ {a="%-?(iNI?)", b=""},
+ -- ʾalif al-waṣl: put it back on with \arbnull
+ {a="(O[%S]-)([%'a]l%-)(O)(\"?[uai])", b="%4"},
+ -- initial straight double quote gives a connective ʾalif. This has
+ -- nothing to do with the tanwīn, but I put it here for time being.
+ {a="^\"", b="ٱ"},
+ {a="([%s%-])\"", b="%1ٱ"}
+}
+
+trigraphsnv = { -- trigraphs or more
+ -- Allah
+ {a="l%-l_ah", b="l-ll_ah"},
+ -- 'llatI / 'llad_I
+ {a="^'ll(a)([%_]?[dt])", b="ال%1%2"},
+ {a="([%(%[%|%<%s%-])'ll(a)([%_]?[dt])", b="%1ال%2%3"}, --p
+ -- al- + lām
+ {a="^(a)l%-(l)", b="ا%1ل%2"},
+ {a="([%(%[%|%<%s%-])(a)l%-(l)", b="%1ا%2ل%3"}, --p
+ -- al- + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)l%-(%^n)", b="ا%1ل%2"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-])(a)l%-(%^n)", b="%1ا%2ل%3"}, -- ^n is lunar --p
+ {a="^(a)l%-([%_%^%.]?[tdrzsnc])", b="ا%1ل%2"},
+ {a="([%(%[%|%<%s%-])(a)l%-([%_%^%.]?[tdrzsnc])", b="%1ا%2ل%3"}, --p
+ -- assim. art. + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)(%^n)%-", b="ا%1ل"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-])(a)(%^n)%-", b="%1ا%2ل"}, -- ^n is lunar --p
+ {a="^(a)([%_%^%.]?[tdrzsnc])%-", b="ا%1ل"},
+ {a="([%(%[%|%<%s%-])(a)([%_%^%.]?[tdrzsnc])%-", b="%1ا%2ل"}, --p
+ -- al- + initial unstable hamza
+ {a="^(a)l%-(\")([uai])", b="ا%1لٱ%3"},
+ {a="([%(%[%|%<%s%-])(a)l%-(\")([uai])", b="%1ا%2لٱ%4"}, --p
+ {a="^(a)l%-([uai])", b="ا%1لا%2"},
+ {a="([%(%[%|%<%s%-])(a)l%-([uai])", b="%1ا%2لا%3"}, --p
+ -- li-/la- + art. + initial unstable hamza is a special orthography
+ {a="l([ai])%-l%-(\")([uai])", b="ل%1لٱ%3"},
+ {a="l([ai])%-l%-([uai])", b="ل%1لا%2"},
+ -- al- + lunar consonant (i.e. what remains)
+ {a="^(a)l%-", b="ا%1ل"},
+ {a="([%(%[%|%<%s%-])(a)l%-", b="%1ا%2ل"}, --p
+ -- art. with waṣla + lām
+ {a="'l%-(l)", b="ال%1"},
+ -- art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'l%-(%^n)", b="ال%1"}, -- ^n is lunar
+ {a="'l%-([%_%^%.]?[tdrzsnc])", b="ال%1"},
+ -- li-/la- + art. + lām
+ {a="l([ai])%-l%-(l)", b="ل%1%2"},
+ -- assim. art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'(%^n)%-", b="ال"}, -- ^n is lunar
+ {a="'([%_%^%.]?[tdrzsnc])%-", b="ال"},
+ -- li-/la- + art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-l%-(%^n)", b="ل%1ل%2"}, -- ^n is lunar
+ {a="l([ai])%-l%-([%_%^%.]?[tdrzsnc])", b="ل%1ل%2"},
+ -- li-/la + assim. art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-(%^n)%-(%^n)", b="ل%1ل%3"}, -- ^n is lunar
+ {a="l([ai])%-([%_%^%.]?[tdrzsnc])%-([%_%^%.]?[tdrzsnc])", b="ل%1ل%3"},
+ -- art. with waṣla + initial unstable hamza
+ {a="'l%-(\")([uai])", b="الٱ%2"},
+ {a="'l%-([uai])", b="الا%1"},
+ -- art. with waṣla + lunar consonant (i.e. what remains)
+ {a="'l%-", b="ال"},
+ -- the silent wāw
+ {a="uU(%p*)$", b="uو%1"},
+ {a="uU(%p*%s)", b="uو%1"},
+ {a="aU(%p*)$", b="aو%1"},
+ {a="aU(%p*%s)", b="aو%1"},
+ {a="iU(%p*)$", b="iو%1"},
+ {a="iU(%p*%s)", b="iو%1"},
+ -- words ending in -āT with silent wāw/yāʾ
+ {a="(_a)UA", b="%1وا"},
+ {a="(_a)U", b="%1و"},
+ {a="(_a)I", b="%1ي"}
+}
+
+longvnv = {
+ {a="\"A", b="َا"},
+ {a="\"U", b="ُو"},
+ {a="\"I", b="ِي"},
+ {a="\"Y", b="aى"},
+ {a="A", b="ا"},
+ {a="U", b="و"},
+ {a="I", b="ي"},
+ {a="Y", b="ى"},
+}
+
+shortvnv = {
+ {a="\"u", b="ُ"},
+ {a="\"a", b="َ"},
+ {a="\"i", b="ِ"},
+ {a="%-?%.u", b="ُ"},
+ {a="%-?%.a", b="َ"},
+ {a="%-?%.i", b="ِ"},
+ {a="u", b=""},
+ {a="a", b=""},
+ {a="i", b=""}
+}
diff --git a/macros/luatex/latex/arabluatex/arabluatex_trans.lua b/macros/luatex/latex/arabluatex/arabluatex_trans.lua
new file mode 100644
index 0000000000..63a1956345
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/arabluatex_trans.lua
@@ -0,0 +1,1018 @@
+--[[
+This file is part of the `arabluatex' package
+
+ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
+Copyright (C) 2016--2019 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/>.
+--]]
+
+-- common
+
+punctuationtr = {
+ {a="%(%(", b="("},
+ {a="%)%)", b=")"}
+}
+
+nulltr = {
+ {a="%|", b=""},
+ {a="o", b=""},
+ {a="O[%S]-O", b=""},
+ {a="[%^%_](.)", b="<??>%1"}
+}
+
+-- cap (legacy)
+captr = {
+ -- dmg (defaut); loc as well
+ {a="ā", b="Ā"},
+ {a="b", b="B"},
+ {a="t", b="T"},
+ {a="ṯ", b="Ṯ"},
+ {a="ǧ", b="Ǧ"},
+ {a="ḥ", b="Ḥ"},
+ {a="ḫ", b="Ḫ"},
+ {a="d", b="D"},
+ {a="ḏ", b="Ḏ"},
+ {a="r", b="R"},
+ {a="z", b="Z"},
+ {a="s", b="S"},
+ {a="š", b="Š"},
+ {a="ṣ", b="Ṣ"},
+ {a="ḍ", b="Ḍ"},
+ {a="ṭ", b="Ṭ"},
+ {a="ẓ", b="Ẓ"},
+ {a="ġ", b="Ġ"},
+ {a="f", b="F"},
+ {a="q", b="Q"},
+ {a="k", b="K"},
+ {a="l", b="L"},
+ {a="m", b="M"},
+ {a="n", b="N"},
+ {a="h", b="H"},
+ {a="w", b="W"},
+ {a="ū", b="Ū"},
+ {a="y", b="Y"},
+ {a="ī", b="Ī"}
+}
+
+-- uc
+lcuc = {
+ {a="b", b="B"},
+ {a="t", b="T"},
+ {a="ṯ", b="Ṯ"},
+ {a="ǧ", b="Ǧ"},
+ {a="j", b="J"},
+ {a="ḥ", b="Ḥ"},
+ {a="ḫ", b="Ḫ"},
+ {a="d", b="D"},
+ {a="ḏ", b="Ḏ"},
+ {a="r", b="R"},
+ {a="z", b="Z"},
+ {a="s", b="S"},
+ {a="š", b="Š"},
+ {a="ṣ", b="Ṣ"},
+ {a="ḍ", b="Ḍ"},
+ {a="ṭ", b="Ṭ"},
+ {a="ẓ", b="Ẓ"},
+ {a="ġ", b="Ġ"},
+ {a="f", b="F"},
+ {a="q", b="Q"},
+ {a="k", b="K"},
+ {a="l", b="L"},
+ {a="m", b="M"},
+ {a="n", b="N"},
+ {a="h", b="H"},
+ {a="w", b="W"},
+ {a="y", b="Y"},
+ {a="u", b="U"},
+ {a="a", b="A"},
+ {a="i", b="I"},
+ {a="ū", b="Ū"},
+ {a="ā", b="Ā"},
+ {a="ī", b="Ī"},
+ -- additional characters
+ {a="p", b="P"},
+ {a="č", b="Č"},
+ {a="ž", b="Ž"},
+ {a="v", b="V"},
+ {a="g", b="G"},
+ {a="ñ", b="Ñ"},
+ {a="ch", b="Ch"}, -- loc
+}
+
+-- dmg
+
+hamzatrdmg = {
+ -- next lines for ʾalif alone
+ {a="(%.A)l%-(%^n)", b=".|l-%2"}, --additional (^n is lunar)
+ {a="([%(%[%|%<%s%-O])(%.A)l%-(%^n)", b="%1.|l-%3"}, --additional (^n is lunar) --p
+ {a="(%.A)l%-([%_%^%.]?[tdrzsnc])", b=".|%2-%2"},
+ {a="([%(%[%|%<%s%-O])(%.A)l%-([%_%^%.]?[tdrzsnc])", b="%1.|%3-%3"}, --p
+ {a="(%.A)([uai])l%-(%^n)", b="||%2l-%3"}, --additional (^n is lunar)
+ {a="([%(%[%|%<%s%-O])(%.A)([uai])l%-(%^n)", b="%1||%3l-%4"}, --additional (^n is lunar) --p
+ {a="(%.A)([uai])l%-([%_%^%.]?[tdrzsnc])", b="||%2%3-%3"},
+ {a="([%(%[%|%<%s%-O])(%.A)([uai])l%-([%_%^%.]?[tdrzsnc])", b="%1||%3%4-%4"}, --p
+ {a="(%.A)([^uai])", b=".|%2"},
+ {a="(%.A)([uai])", b="||%2"},
+ -- hard coded hamza
+ {a="|\"'", b="ʾ"},
+ {a="A\"'", b="ʾA"},
+ {a="[au]\"'", b="ʾ"},
+ {a="w\"'", b="ʾ"},
+ {a="i\"'", b="ʾ"},
+ {a="y\"'", b="ʾ"},
+ -- hamza takes tašdīd too
+ {a="''([Uu])", b="ʾʾ%1"},
+ {a="''([Aa])", b="ʾʾ%1"},
+ {a="''([Ii])", b="ʾʾ%1"},
+ -- initial long u and i (for a, see below)
+ {a="%'%_U", b="ʾU"},
+ {a="%'%_I", b="ʾI"},
+ -- taḫfīfu 'l-hamza
+ {a="'u'([^uaiUAI])", b="ʾU%1"},
+ {a="'i'([^uaiUAI])", b="ʾI%1"},
+ {a="^u'([^uaiUAI])", b="U%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])u'([^uaiUAI])", b="%1U%2"},
+ {a="^i'([^uaiUAI])", b="I%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])i'([^uaiUAI])", b="%1I%2"},
+ -- madda (historic writing below)
+ {a="'a'([^uaiUAI])", b="ʾA%1"},
+ {a="'a?A", b="ʾA"},
+ {a="(A)(')(i)$", b="%1ʾ%3"},
+ {a="(A)(')(i)(%W)", b="%1ʾ%3%4"},
+ {a="(A)(')(i)", b="%1ʾ%3"}, -- historic madda
+ {a="(A)(')", b="%1ʾ"}, -- historic madda
+ -- initial (needs both ^ and %W patterns)
+ -- 'aw: the diphthong is to be resolved into 'awi' (next 8 lines)
+ {a="^('aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(%W)('aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1%2i"},
+ {a="^('aw)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(%W)('aw)(O)(\"?[uai])([%S]-O)", b="%1%2i"},
+ {a="^('aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ {a="(%W)('aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1%2i%3%4"},
+ {a="^('aw)(%s)([%(%[%|%<]?\"?[uai])", b="%1i%2%3"}, --p
+ {a="(%W)('aw)(%s)([%(%[%|%<]?\"?[uai])", b="%1%2i%3%4"}, --p
+ -- then the 'initial' rules for the remaining cases
+ {a="^(')([ua])", b="ʾ%2"},
+ {a="^(')(i)", b="ʾ%2"},
+ -- consider replacing initial %W with [%s%(%[%<%-]:
+ -- {a="(%W)(')([ua])", b="%1ʾ%3"},
+ -- {a="(%W)(')(i)", b="%1ʾ%3"},
+ {a="([%s%(%[%<%-])(')([ua])", b="%1ʾ%3"},
+ {a="([%s%(%[%<%-])(')(i)", b="%1ʾ%3"},
+ -- final
+ {a="([Iy])(')(aN)$", b="%1ʾ%3"},
+ {a="([Iy])(')(aN)(%W)", b="%1ʾ%3%4"},
+ {a="([^uai])(')([uai]N?)$", b="%1ʾ%3"},
+ {a="([^uai])(')([uai]N?)(%W)", b="%1ʾ%3%4"},
+ {a="([UI])(')([uai])$", b="%1ʾ%3"},
+ {a="([UI])(')([uai])(%W)", b="%1ʾ%3%4"},
+ -- middle
+ {a="(U)(')", b="%1ʾ"},
+ {a="([Iy])(')", b="%1ʾ"},
+ {a="([^uai])(')([uU])", b="%1ʾ%3"},
+ {a="([^uai])(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="([^uai])(')([iI])", b="%1ʾ%3"},
+ {a="(u)(')([uU])", b="%1ʾ%3"},
+ {a="(u)(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="(u)(')([iI])", b="%1ʾ%3"},
+ {a="(a)(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="(a)(')([uU])", b="%1ʾ%3"},
+ {a="(a)(')([iI])", b="%1ʾ%3"},
+ {a="(i)(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="(i)(')([uU])", b="%1ʾ%3"},
+ {a="(i)(')([iI])", b="%1ʾ%3"},
+ {a="(a)(')([^uaiUAI])", b="%1ʾ%3"},
+ {a="(u)(')([^uaiUAI])", b="%1ʾ%3"},
+ {a="(i)(')([^uaiUAI])", b="%1ʾ%3"}
+}
+
+tanwintrdmg = {
+ {a="%-?([uai]NU)(O)([ui])([%S]-O)", b="\\arbup{un%3}"},
+ {a="%-?([uai]NU)(%s)([ui])", b="\\arbup{un%3}%2'"},
+ {a="%-?(iNI)(O)([ui])([%S]-O)", b="i\\arbup{n%3}"},
+ {a="%-?(iNI)(%s)([ui])", b="i\\arbup{n%3}%2'"},
+ {a="(O[%S]-)([uai]N[UI])(O)(\"?[ui])", b="'"},
+ {a="%-?uNU", b="\\arbup{un}"},
+ {a="%-?aNU", b="\\arbup{an}"},
+ {a="%-?iNU", b="\\arbup{in}"},
+ {a="%-?iNI", b="i\\arbup{n}"},
+ -- tanwīn preceding ʾalif conjunctionis
+ {a="%-?(uN)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="\\arbup{uni}"},
+ {a="%-?(aN)(_A)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="ạ\\arbup{ni}"},
+ {a="%-?(aN)(Y)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="ạ\\arbup{ni}"},
+ {a="(T)%-?(aN)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="t\\arbup{ani}"},
+ {a="([^TA])%-?(aN)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1\\arbup{ani}"},
+ {a="%-?(iN)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="\\arbup{ini}"},
+ {a="%-?(uN)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="\\arbup{uni}%2%3"},
+ {a="%-?(aN)(_A)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="ạ\\arbup{ni}%3%4"},
+ {a="%-?(aN)(Y)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="ạ\\arbup{ni}%3%4"},
+ {a="(T)%-?(aN)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="t\\arbup{ani}%3%4"},
+ {a="([^TA])%-?(aN)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1\\arbup{ani}%3%4"},
+ {a="%-?(iN)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="\\arbup{ini}%2%3"},
+ -- tanwīn preceding 'lla_dI/'llatI
+ {a="%-?(uN)(O)('lla[%_]?[dt])([%S]-O)", b="\\arbup{uni}"},
+ {a="%-?(aN)(_A)(O)('lla[%_]?[dt])([%S]-O)", b="ạ\\arbup{ni}"},
+ {a="%-?(aN)(Y)(O)('lla[%_]?[dt])([%S]-O)", b="ạ\\arbup{ni}"},
+ {a="(T)%-?(aN)(O)('lla[%_]?[dt])([%S]-O)", b="t\\arbup{ani}"},
+ {a="([^TA])%-?(aN)(O)('lla[%_]?[dt])([%S]-O)", b="%1\\arbup{ani}"},
+ {a="%-?(iN)(O)('lla[%_]?[dt])([%S]-O)", b="\\arbup{ini}"},
+ {a="%-?(uN)(%s)('lla[%_]?[dt])", b="\\arbup{uni}%2%3"},
+ {a="%-?(aN)(_A)(%s)('lla[%_]?[dt])", b="ạ\\arbup{ni}%3%4"},
+ {a="%-?(aN)(Y)(%s)('lla[%_]?[dt])", b="ạ\\arbup{ni}%3%4"},
+ {a="(T)%-?(aN)(%s)('lla[%_]?[dt])", b="t\\arbup{ani}%3%4"},
+ {a="([^TA])%-?(aN)(%s)('lla[%_]?[dt])", b="%1\\arbup{ani}%3%4"},
+ {a="%-?(iN)(%s)('lla[%_]?[dt])", b="\\arbup{ini}%2%3"},
+ -- tanwīn + alif without hamza and kasra (ibn) or dhamma (uhrub)
+ {a="%-?(uN)(O)([ui])([%S]-O)", b="\\arbup{un%3}"},
+ {a="%-?(aN)(_A)(O)([ui])([%S]-O)", b="ạ\\arbup{n%4}"},
+ {a="%-?(aN)(Y)(O)([ui])([%S]-O)", b="ạ\\arbup{n%4}"},
+ {a="(T)%-?(aN)(O)([ui])([%S]-O)", b="t\\arbup{an%4}"},
+ {a="([^TA])%-?(aN)(O)([ui])([%S]-O)", b="%1\\arbup{an%4}"},
+ {a="%-?(iN)(O)([ui])([%S]-O)", b="\\arbup{in%3}"},
+ {a="(O[%S]-)([uai]N)(O)(\"?[ui])", b="'"},
+ {a="%-?(uN)(%s)([ui])", b="\\arbup{un%3}%2'"},
+ {a="%-?(aN)(_A)(%s)([ui])", b="ạ\\arbup{n%4}%3'"},
+ {a="%-?(aN)(Y)(%s)([ui])", b="ạ\\arbup{n%4}%3'"},
+ {a="(T)%-?(aN)(%s)([ui])", b="t\\arbup{an%4}%3'"},
+ {a="([^TA])%-?(aN)(%s)([ui])", b="%1\\arbup{an%4}%3'"},
+ {a="%-?(iN)(%s)([ui])", b="\\arbup{in%3}%2'"},
+ --
+-- {a="uN", b="\\arbup{un}"}, (now included in the last line of this table)
+ {a="%-?(\"?At)%-?([ui])N", b="\\arbup{%1%2n}"},
+ -- needed by \arbcolor:
+ {a="%-?(aN)(O[%S]-%_AO)", b="ạ\\arbup{n}"},
+ {a="%-?(aN)(O[%S]-YO)", b="ạ\\arbup{n}"},
+ {a="(O[%S]-TO)%-?(\"?aN)", b="\\arbup{an}"},
+ {a="(O[%S]-[^TA]O)%-?(\"?aN)", b="\\arbup{an}"},
+ --
+ {a="%-?(aN)(_A)", b="ạ\\arbup{n}"},
+ {a="%-?(aN)(Y)", b="ạ\\arbup{n}"},
+ {a="(T)%-?(\"?aN)", b="t\\arbup{an}"},
+ {a="([^TA])%-?(\"?aN)", b="%1\\arbup{an}"},
+ {a="%-?([ui])N", b="\\arbup{%1n}"}
+}
+
+trigraphstrdmg = { -- trigraphs or more
+ -- 'llatI / 'llad_I
+ {a="^'ll(a)([%_]?[dt])", b="'ll%1%2"},
+ {a="([%(%[%|%<%s])'ll(a)([%_]?[dt])", b="%1'll%2%3"}, --p
+ -- law: the diphthong is to be resolved into 'awi' (next 8 lines)
+ {a="^(law)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(%W)(law)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1%2i"},
+ {a="^(law)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(%W)(law)(O)(\"?[uai])([%S]-O)", b="%1%2i"},
+ {a="^(law)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ {a="(%W)(law)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1%2i%3%4"},
+ {a="^(law)(%s)([%(%[%|%<]?\"?[uai])", b="%1i%2%3"}, --p
+ {a="(%W)(law)(%s)([%(%[%|%<]?\"?[uai])", b="%1%2i%3%4"}, --p
+ -- al- + lām
+ {a="^(a)l%-(l)", b="%1l-%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-(l)", b="%1%2l-%3"}, --p
+ -- al- + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)l%-(%^n)", b="%1l-%2"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-O])(a)l%-(%^n)", b="%1%2l-%3"}, --^n is lunar --p
+ {a="^(a)l%-([%_%^%.]?[tdrzsnc])", b="%1%2-%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-([%_%^%.]?[tdrzsnc])", b="%1%2%3-%3"}, --p
+ -- assim. art. + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)(%^n)%-", b="%1l-"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-O])(a)(%^n)%-", b="%1%2l-"}, --^n is lunar --p
+ {a="^(a)([%_%^%.]?[tdrzsnc])%-", b="%1%2-"},
+ {a="([%(%[%|%<%s%-O])(a)([%_%^%.]?[tdrzsnc])%-", b="%1%2%3-"}, --p
+ -- al- + initial unstable hamza
+ {a="^(a)l%-(\"?[uai])", b="%1l-%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-(\"?[uai])", b="%1%2l-%3"}, --p
+ -- li-/la- + art. + initial unstable hamza is a special orthography
+ {a="l([ai])%-l%-([uai])", b="l%1-l-%2"},
+ -- al- + lunar consonant (i.e. what remains)
+ {a="^(a)l%-", b="%1l-"},
+ {a="([%(%[%|%<%s%-O])(a)l%-", b="%1%2l-"}, --p
+ -- diphthongs to be resolved before ʾalif conjunctionis
+ {a="(aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1u"},
+ {a="(ay)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1u%2%3"},
+ {a="(ay)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ -- art. with waṣla + lām
+ {a="'l%-(l)", b="'l-%1"},
+ -- art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'l%-(%^n)", b="'l-%1"}, -- ^n is lunar
+ {a="'l%-([%_%^%.]?[tdrzsnc])", b="'%1-%1"},
+ -- li-/la- + art. + lām
+ {a="l([ai])%-l%-(l)", b="l%1-%2-%2"},
+ -- assim. art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'(%^n)%-", b="'l-"}, -- ^n is lunar
+ {a="'([%_%^%.]?[tdrzsnc])%-", b="'%1-"},
+ -- li-/la- + art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-l%-(%^n)", b="l%1-l-%2"}, -- ^n is lunar
+ {a="l([ai])%-l%-([%_%^%.]?[tdrzsnc])", b="l%1-%2-%2"},
+ -- li-/la- + assim. art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-(%^n)%-(%^n)", b="l%1-l-%3"}, -- ^n is lunar
+ {a="l([ai])%-([%_%^%.]?[tdrzsnc])%-([%_%^%.]?[tdrzsnc])", b="l%1-%2-%3"},
+ -- art. with waṣla + initial unstable hamza
+ {a="'l%-(\"?[uai])", b="'l-%1"},
+ -- art. with waṣla + lunar consonant (i.e. what remains)
+ {a="'l%-", b="'l-"},
+ -- the silent wāw
+ {a="uU$", b="u"},
+ {a="uU(%W)", b="u%1"},
+ {a="aU$", b="a"},
+ {a="aU(%W)", b="a%1"},
+ {a="iU$", b="i"},
+ {a="iU(%W)", b="i%1"},
+ -- words ending in -āT with silent wāw/yāʾ
+ {a="(_a)UA", b="A"},
+ {a="(_a)U", b="A"},
+ {a="(_a)I", b="A"}
+}
+
+idghamtrdmg = {
+ -- assimilations
+ {a="(n)(}?)(%s)([rlmnwy])", b="%4%2%3%4"},
+ {a="(n)(}?)(O)([rlmnwy])([%S]-O)", b="%4%2"}
+}
+
+digraphstrdmg = {
+ {a="([uai]%-)(\"?[uai])", b="%1'"}, -- hyphen + initial alif without hamza
+ -- the following two are replaced with the 4 lines next for now
+-- {a="^(\"?[uai])", b="%1"}, -- initial alif without hamza
+-- {a="(%W)(\"?[uai])", b="%1%2"}, -- initial alif without hamza
+-- {a="^(\"[uai])", b="'"}, -- initial alif without hamza
+-- {a="(%W)(\"[uai])", b="%1'"}, -- initial alif without hamza
+ {a="^(\"?[uai])", b="%1"}, -- initial alif without hamza
+ {a="(%W)(\"?[uai])", b="%1%2"}, -- initial alif without hamza
+ -- this is not necessary, take out for now:
+-- {a="([%_]?[uaiUAIY])(%s)([uai])", b="%1%2'"}, -- initial alif without hamza
+ {a="(aw)(O)(\"?[uai])([%S]-O)", b="%1u"},
+ {a="(aw)(%s)([%(%[%|%<]?)(\"?[uai])", b="%1u%2%3'"}, --p
+ {a="(ay)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(ay)(%s)([%(%[%|%<]?)(\"?[uai])", b="%1i%2%3'"}, --p
+ {a="(aW)(O)(\"?[uai])([%S]-O)", b="awu"},
+ {a="(UA)(O)(\"?[uai])([%S]-O)", b="u"},
+ {a="(%_A)(O)(\"?[uai])([%S]-O)", b="ạ"},
+ {a="(Y)(O)(\"?[uai])([%S]-O)", b="ạ"},
+ {a="(%_a)(O)(\"?[uai])([%S]-O)", b="a"},
+ {a="(A)(O)(\"?[uai])([%S]-O)", b="a"},
+ {a="([%_]?[Uu])(O)(\"?[uai])([%S]-O)", b="u"},
+ {a="([%_]?[Ii])(O)(\"?[uai])([%S]-O)", b="i"},
+ {a="(O[%S]-)([%'a]l%-)(O)(\"?[uai])", b="'"},
+ {a="(O[%S]-)([UAIYWuaiyw])(O)(\"?[uai])", b="'"},
+ {a="(aW)(%s)([%(%[%|%<]?)(\"?[uai])", b="awu%2%3%4"}, --p
+ {a="(UA)(%s)([%(%[%|%<]?)(\"?[uai])", b="u%2%3'"}, --p
+ {a="([^%_][uai])(%s)([%(%[%|%<]?)(\"?[uai])", b="%1%2%3'"}, --p
+ {a="(%_A)(%s)([%(%[%|%<]?)(\"?[uai])", b="ạ%2%3'"}, --p
+ {a="(Y)(%s)([%(%[%|%<]?)(\"?[uai])", b="ạ%2%3'"}, --p
+ {a="(%_a)(%s)([%(%[%|%<]?)(\"?[uai])", b="a%2%3'"}, --p
+ {a="(A)(%s)([%(%[%|%<]?)(\"?[uai])", b="a%2%3'"}, --p
+ {a="([%_]?[Uu])(%s)([%(%[%|%<]?)(\"?[uai])", b="u%2%3'"}, --p
+ {a="([%_]?[Ii])(%s)([%(%[%|%<]?)(\"?[uai])", b="i%2%3'"}, --p
+ -- ʾiʿrāb hyphen (begin)
+ {a="(%-)(\"?[UI]na)(%p*%s)", b="\\arbup{%2}%3"},
+ {a="(%-)(\"?[UI]na)(%p*)$", b="\\arbup{%2}%3"},
+ {a="(%-)(\"?At%.?[ui])(%p*%s)", b="\\arbup{%2}%3"},
+ {a="(%-)(\"?At%.?[ui])(%p*)$", b="\\arbup{%2}%3"},
+ {a="(%-)(\"?Ani)(%p*%s)", b="\\arbup{%2}%3"},
+ {a="(%-)(\"?Ani)(%p*)$", b="\\arbup{%2}%3"},
+ {a="(%-)(\"?%.?ayni)(%p*%s)", b="\\arbup{%2}%3"},
+ {a="(%-)(\"?%.?ayni)(%p*)$", b="\\arbup{%2}%3"},
+ {a="(%-)(\"?%.?[uai])(%p*%s)", b="\\arbup{%2}%3"},
+ {a="(%-)(\"?%.?[uai])(%p*)$", b="\\arbup{%2}%3"},
+ -- ʾiʿrāb hyphen (end) shorten long vowels preceding ʾalif
+ -- conjunctionis—without forgetting 'lla_dI
+ {a="(U)(A)", b="U"},
+ {a="(aW)(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])([%S]-O)", b="awu"},
+ {a="(%_a)(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])([%S]-O)", b="a"},
+ {a="(%_A)(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])([%S]-O)", b="ạ"},
+ {a="(A)(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])([%S]-O)", b="a"},
+ {a="(Y)(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])([%S]-O)", b="ạ"},
+ {a="([%_]?[Uu])(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])([%S]-O)", b="u"},
+ {a="([%_]?[Ii])(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])([%S]-O)", b="i"},
+ --p (next 7 lines, just after %s)
+ {a="(aW)(%s)([%(%[%|%<]?['][%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])", b="awu%2%3"},
+ {a="(%_a)(%s)([%(%[%|%<]?['][%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])", b="a%2%3"},
+ {a="(%_A)(%s)([%(%[%|%<]?['][%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])", b="ạ%2%3"},
+ {a="(A)(%s)([%(%[%|%<]?['][%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])", b="a%2%3"},
+ {a="(Y)(%s)([%(%[%|%<]?['][%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])", b="ạ%2%3"},
+ {a="([%_]?[Uu])(%s)([%(%[%|%<]?['][%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])", b="u%2%3"},
+ {a="([%_]?[Ii])(%s)([%(%[%|%<]?['][%_%^%.]?[l'btjghxdrzs`fqkmnwy][%-l])", b="i%2%3"},
+ {a="%-%-", b=""},
+ {a="iyyaT(%p*)$", b="īyaT%1"},
+ {a="iyyaT(%p*%s)", b="īyaT%1"},
+ {a="iyy(%p*)$", b="ī%1"},
+ {a="iyy(%p*%s)", b="ī%1"},
+ -- {a="T([^uai])", b="%1"},
+ {a="T(\\arbup)", b="t%1"},
+ {a="([a%'][%_%^%.]?[tdrzsln]%-)(%S-)T([%(%[%|%<%s])(a[%_%^%.]?[tdrzsln]%-)", b="%1%2h%3%4"}, --p
+ {a="T([%(%[%|%<%s])(a[%_%^%.]?[tdrzsln]%-)", b="t%1%2"}, --p
+ {a="T([%|\"])", b="t%1"},
+ {a="T(%p*%s)", b="h%1"},
+ {a="T(%p*)$", b="h%1"},
+ {a="T(%p*)(%W)", b="h%1%2"},
+ {a="_t", b="ṯ"},
+ {a="%^g", b="ǧ"},
+ {a="%.h", b="ḥ"},
+ {a="_h", b="ḫ"},
+ {a="_d", b="ḏ"},
+ {a="%^s", b="š"},
+ {a="%.s", b="ṣ"},
+ {a="%.d", b="ḍ"},
+ {a="%.t", b="ṭ"},
+ {a="%.z", b="ẓ"},
+ {a="%.g", b="ġ"},
+ {a="%.y", b="y"},
+ -- additional characters (begin)
+ {a="%^c", b="č"},
+ {a="%^z", b="ž"},
+ {a="%^n", b="ñ"},
+ -- additional characters (end)
+ -- the following needs to be moved above shortening rules
+-- {a="(U)(A)", b="ū"},
+ {a="WA", b="w"},
+ {a="(a)W", b="%1w"},
+ {a="_A", b="ạ̄"},
+ {a="_u", b="ū"},
+ {a="_a", b="ā"},
+ {a="_i", b="ī"},
+ {a="%.b", b="ḅ"},
+ {a="%.f", b="f̣"},
+ {a="%.q", b="q̣"},
+ {a="%.k", b="k"},
+ {a="%.n", b="ṇ"},
+ {a="%^d", b="d́"}
+}
+
+singletrdmg = {
+ {a="b", b="b"},
+ {a="t", b="t"},
+ {a="j", b="ǧ"},
+ {a="x", b="ḫ"},
+ {a="d", b="d"},
+ {a="r", b="r"},
+ {a="z", b="z"},
+ {a="s", b="s"},
+ {a="`", b="ʿ"},
+ {a="f", b="f"},
+ {a="q", b="q"},
+ {a="k", b="k"},
+ {a="l", b="l"},
+ {a="m", b="m"},
+ {a="n", b="n"},
+ {a="h", b="h"},
+ {a="w", b="w"},
+ {a="y", b="y"},
+ {a="T", b="t"},
+ -- additional characters (begin)
+ {a="p", b="p"},
+ {a="v", b="v"},
+ {a="g", b="g"},
+ -- additional characters (end)
+ {a="\"", b=""},
+ {a="B", b=""}
+}
+
+longvtrdmg = {
+ {a="A", b="ā"},
+ {a="U", b="ū"},
+ {a="I", b="ī"},
+ {a="aY", b="ay"},
+ {a="iY", b="ī"},
+ {a="Y", b="ạ̄"}
+}
+
+shortvtrdmg = {
+ {a="([uai])([uai])([uai])", b="/%1,%2,%3/"},
+ {a="([uai])([uai])", b="/%1,%2/"},
+ {a="%.u", b="u"},
+ {a="%.a", b="a"},
+ {a="%.i", b="i"},
+ {a="u", b="u"},
+ {a="a", b="a"},
+ {a="i", b="i"}
+}
+
+-- loc
+
+hamzatrloc = {
+ -- next lines for ʾalif alone
+ {a="(%.A)([^uai])", b=".|%2"},
+ {a="(%.A)([uai])", b="||%2"},
+ -- hard coded hamza
+ {a="|\"'", b="ʾ"},
+ {a="A\"'", b="ʾA"},
+ {a="[au]\"'", b="ʾ"},
+ {a="w\"'", b="ʾ"},
+ {a="i\"'", b="ʾ"},
+ {a="y\"'", b="ʾ"},
+ -- hamza takes tašdīd too
+ {a="''([Uu])", b="ʾʾ%1"},
+ {a="''([Aa])", b="ʾʾ%1"},
+ {a="''([Ii])", b="ʾʾ%1"},
+ -- initial long u and i (for a, see below)
+ {a="%'%_U", b="U"},
+ {a="%'%_I", b="I"},
+ -- taḫfīfu 'l-hamza
+ {a="^'u'([^uaiUAI])", b="U%1"},
+ {a="([%s%(%[%<%-])'u'([^uaiUAI])", b="%1U%2"},
+ {a="^'i'([^uaiUAI])", b="I%1"},
+ {a="([%s%(%[%<%-])'i'([^uaiUAI])", b="%1I%2"},
+ {a="^u'([^uaiUAI])", b="U%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])u'([^uaiUAI])", b="%1U%2"},
+ {a="^i'([^uaiUAI])", b="I%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])i'([^uaiUAI])", b="%1I%2"},
+ -- madda (historic writing below)
+ {a="^(')(A)", b="%2"},
+ {a="(%W)(')(A)", b="%1%3"},
+ {a="^'a'([^uaiUAI])", b="A%1"},
+ {a="(%W)'a'([^uaiUAI])", b="%1A%2"},
+ {a="'a'([^uaiUAI])", b="A%1"},
+ {a="^'a?A", b="A"},
+ {a="(%W)'a?A", b="%1A"},
+ {a="'a?A", b="ʾA"},
+ {a="(A)(')(i)$", b="%1ʾ%3"},
+ {a="(A)(')(i)(%W)", b="%1ʾ%3%4"},
+ {a="(A)(')(i)", b="%1ʾ%3"}, -- historic madda
+ {a="(A)(')", b="%1ʾ"}, -- historic madda
+ -- initial (needs both ^ and %W patterns)
+ {a="^(')([ua])", b="%2"},
+ {a="^(')(i)", b="%2"},
+ -- consider replacing initial %W with [%s%(%[%<%-]:
+ -- {a="(%W)(')([ua])", b="%1%3"},
+ -- {a="(%W)(')(i)", b="%1%3"},
+ {a="([%s%(%[%<%-])(')([ua])", b="%1%3"},
+ {a="([%s%(%[%<%-])(')(i)", b="%1%3"},
+ -- final
+ {a="([Iy])(')(aN)$", b="%1ʾ%3"},
+ {a="([Iy])(')(aN)(%W)", b="%1ʾ%3%4"},
+ {a="([^uai])(')([uai]N?)$", b="%1ʾ%3"},
+ {a="([^uai])(')([uai]N?)(%W)", b="%1ʾ%3%4"},
+ {a="([UI])(')([uai])$", b="%1ʾ%3"},
+ {a="([UI])(')([uai])(%W)", b="%1ʾ%3%4"},
+ -- middle
+ {a="(U)(')", b="%1ʾ"},
+ {a="([Iy])(')", b="%1ʾ"},
+ {a="([^uai])(')([uU])", b="%1ʾ%3"},
+ {a="([^uai])(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="([^uai])(')([iI])", b="%1ʾ%3"},
+ {a="(u)(')([uU])", b="%1ʾ%3"},
+ {a="(u)(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="(u)(')([iI])", b="%1ʾ%3"},
+ {a="(a)(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="(a)(')([uU])", b="%1ʾ%3"},
+ {a="(a)(')([iI])", b="%1ʾ%3"},
+ {a="(i)(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="(i)(')([uU])", b="%1ʾ%3"},
+ {a="(i)(')([iI])", b="%1ʾ%3"},
+ {a="(a)(')([^uaiUAI])", b="%1ʾ%3"},
+ {a="(u)(')([^uaiUAI])", b="%1ʾ%3"},
+ {a="(i)(')([^uaiUAI])", b="%1ʾ%3"}
+}
+
+tanwintrloc = {
+ {a="%-?uNU", b="un"},
+ {a="%-?aNU", b="an"},
+ {a="%-?iNU", b="in"},
+ {a="%-?iNI", b="in"},
+ {a="%-?(\"?At)%-?([ui])N", b="%1%2n"},
+ {a="%-?([ui])N", b="%1n"},
+ -- needed by \arbcolor:
+ {a="%-?(aN)(O[%S]-%_AO)", b="an"},
+ {a="%-?(aN)(O[%S]-YO)", b="an"},
+ {a="(O[%S]-TO)%-?(\"?aN)", b="an"},
+ {a="(O[%S]-[^TA]O)%-?(\"?aN)", b="an"},
+ --
+ {a="%-?(aN)(_A)", b="an"},
+ {a="%-?(aN)(Y)", b="an"},
+ {a="(T)%-?(\"?aN)", b="tan"},
+ {a="([^TA])%-?(\"?aN)", b="%1an"}
+}
+
+trigraphstrloc = { -- trigraphs or more
+ -- 'llatI / 'llad_I
+ {a="^'ll(a)([%_]?[dt])", b="all%1%2"},
+ {a="([%(%[%|%<%s])'ll(a)([%_]?[dt])", b="%1all%2%3"}, --p
+ -- al- + lām
+ {a="^(a)l%-(l)", b="%1l-%2"},
+ {a="(%s)(a)l%-(l)", b="%1%2l-%3"},
+ -- al- + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)l%-(%^n)", b="%1l-%2"}, -- ^n is lunar
+ {a="(%s)(a)l%-(%^n)", b="%1%2l-%3"}, -- ^n is lunar
+ {a="^(a)l%-([%_%^%.]?[tdrzsnc])", b="%1l-%2"},
+ {a="(%s)(a)l%-([%_%^%.]?[tdrzsnc])", b="%1%2l-%3"},
+ -- assim. art. + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)(%^n)%-", b="%1l-"}, -- ^n is lunar
+ {a="(%s)(a)(%^n)%-", b="%1%2l-"}, -- ^n is lunar
+ {a="^(a)([%_%^%.]?[tdrzsnc])%-", b="%1l-"},
+ {a="(%s)(a)([%_%^%.]?[tdrzsnc])%-", b="%1%2l-"},
+ -- al- + initial unstable hamza
+ {a="^(a)l%-([uai])", b="%1l-%2"},
+ {a="(%s)(a)l%-([uai])", b="%1%2l-%3"},
+ -- li-/la- + art. + initial unstable hamza is a special orthography
+ {a="l([ai])%-l%-([uai])", b="l%1-l-%2"},
+ -- al- + lunar consonant (i.e. what remains)
+ {a="^(a)l%-", b="%1l-"},
+ {a="(%s)(a)l%-", b="%1%2l-"},
+ -- art. with waṣla + lām
+ {a="'l%-(l)", b="al-%1"},
+ -- art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'l%-(%^n)", b="al-%1"}, -- ^n is lunar
+ {a="'l%-([%_%^%.]?[tdrzsnc])", b="al-%1"},
+ -- li-/la- + art. + lām
+ {a="l([ai])%-l%-(l)", b="l%1-l-%2"},
+ -- assim. art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'(%^n)%-", b="al-"}, -- ^n is lunar
+ {a="'([%_%^%.]?[tdrzsnc])%-", b="al-"},
+ -- li-/la- + art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-l%-(%^n)", b="l%1-l-%2"}, -- ^n is lunar
+ {a="l([ai])%-l%-([%_%^%.]?[tdrzsnc])", b="l%1-l-%2"},
+ -- li-/la- + assim. art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-(%^n)%-(%^n)", b="l%1-l-%3"}, -- ^n is lunar
+ {a="l([ai])%-([%_%^%.]?[tdrzsnc])%-([%_%^%.]?[tdrzsnc])", b="l%1-l-%3"},
+ -- art. with waṣla + initial unstable hamza
+ {a="'l%-([uai])", b="al-%1"},
+ -- art. with waṣla + lunar consonant (i.e. what remains)
+ {a="'l%-", b="al-"},
+ -- the silent wāw
+ {a="uU$", b="u"},
+ {a="uU(%W)", b="u%1"},
+ {a="aU$", b="a"},
+ {a="aU(%W)", b="a%1"},
+ {a="iU$", b="i"},
+ {a="iU(%W)", b="i%1"},
+ -- words ending in -āT with silent wāw/yāʾ
+ {a="(_a)UA", b="A"},
+ {a="(_a)U", b="A"},
+ {a="(_a)I", b="A"}
+}
+
+digraphstrloc = {
+ -- discard the ʾiʿrāb hyphen (begin)
+ {a="(%-)(\"?[UI]na)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?[UI]na)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*)$", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*)$", b="%2%3"},
+ {a="(%-)([uai])(%p*%s)", b="%2%3"},
+ {a="(%-)([uai])(%p*)$", b="%2%3"},
+ -- discard the ʾiʿrāb hyphen (end)
+ {a="(%-)(\"?[uai])", b="%1%2"}, -- hyphen + initial alif without hamza
+ {a="^(\"?[uai])", b="%1"}, -- initial alif without hamza
+ {a="(%s)([uai])", b="%1%2"}, -- initial alif without hamza
+ {a="%-%-", b=""},
+ {a="uww", b="ūw"},
+ {a="iyy(%p*)$", b="ī%1"},
+ {a="iyy(%p*%s)", b="ī%1"},
+ {a="iyy", b="īy"},
+ {a="([tkdsg])(h)", b="%1'%2"},
+ -- {a="T([^uai])", b="h%1"},
+ {a="([a%']l%-)(%S-)T([%(%[%|%<%s])(al%-)", b="%1%2h%3%4"}, --p
+ {a="T([%(%[%|%<%s])(al%-)", b="t%1%2"}, --p
+ {a="T([%|\"])", b="t%1"},
+ {a="T(%p*)$", b="h%1"},
+ {a="T(%p*%s)", b="h%1"},
+ {a="_t", b="th"},
+ {a="%^g", b="j"},
+ {a="%.h", b="ḥ"},
+ {a="_h", b="kh"},
+ {a="_d", b="dh"},
+ {a="%^s", b="sh"},
+ {a="%.s", b="ṣ"},
+ {a="%.d", b="ḍ"},
+ {a="%.t", b="ṭ"},
+ {a="%.z", b="ẓ"},
+ {a="%.g", b="gh"},
+ {a="%.y", b="y"},
+ -- additional characters (begin)
+ {a="%^c", b="ch"},
+ {a="%^z", b="zh"},
+ {a="%^n", b="ñ"},
+ -- additional characters (end)
+ {a="(U)(A)", b="ū"},
+ {a="WA", b="w"},
+ {a="(a)W", b="%1w"},
+ {a="_A", b="á"},
+ {a="_u", b="ū"},
+ {a="_a", b="ā"},
+ {a="_i", b="ī"},
+ {a="%.b", b="b"},
+ {a="%.f", b="f"},
+ {a="%.q", b="q"},
+ {a="%.k", b="k"},
+ {a="%.n", b="n"},
+ {a="%^d", b="d"}
+}
+
+singletrloc = {
+ {a="b", b="b"},
+ {a="t", b="t"},
+ {a="j", b="j"},
+ {a="x", b="kh"},
+ {a="d", b="d"},
+ {a="r", b="r"},
+ {a="z", b="z"},
+ {a="s", b="s"},
+ {a="`", b="`"},
+ {a="f", b="f"},
+ {a="q", b="q"},
+ {a="k", b="k"},
+ {a="l", b="l"},
+ {a="m", b="m"},
+ {a="n", b="n"},
+ {a="h", b="h"},
+ {a="w", b="w"},
+ {a="y", b="y"},
+ {a="T", b="t"},
+ -- additional characters (begin)
+ {a="p", b="p"},
+ {a="v", b="v"},
+ {a="g", b="g"},
+ -- additional characters (end)
+ {a="\"", b=""},
+ {a="B", b=""}
+}
+
+longvtrloc = {
+ {a="A", b="ā"},
+ {a="U", b="ū"},
+ {a="I", b="ī"},
+ {a="aY", b="ay"},
+ {a="iY", b="ī"},
+ {a="Y", b="á"},
+}
+
+shortvtrloc = {
+ {a="([uai])([uai])([uai])", b="/%1,%2,%3/"},
+ {a="([uai])([uai])", b="/%1,%2/"},
+ {a="%.u", b="u"},
+ {a="%.a", b="a"},
+ {a="%.i", b="i"},
+ {a="u", b="u"},
+ {a="a", b="a"},
+ {a="i", b="i"}
+}
+
+finaltrloc = {
+ {a="ʾ", b="'"},
+}
+
+-- arabica
+
+hamzatrarabica = { -- ≠ from hamzatrloc: initial hamza has to be held
+ -- next lines for ʾalif alone
+ {a="(%.A)([^uai])", b=".|%2"},
+ {a="(%.A)([uai])", b="||%2"},
+ -- hard coded hamza
+ {a="|\"'", b="ʾ"},
+ {a="A\"'", b="ʾA"},
+ {a="[au]\"'", b="ʾ"},
+ {a="w\"'", b="ʾ"},
+ {a="i\"'", b="ʾ"},
+ {a="y\"'", b="ʾ"},
+ -- hamza takes tašdīd too
+ {a="''([Uu])", b="ʾʾ%1"},
+ {a="''([Aa])", b="ʾʾ%1"},
+ {a="''([Ii])", b="ʾʾ%1"},
+ -- initial long u and i (for a, see below)
+ {a="%'%_U", b="U"},
+ {a="%'%_I", b="I"},
+ -- taḫfīfu 'l-hamza
+ {a="^'u'([^uaiUAI])", b="U%1"},
+ {a="([%s%(%[%<%-])'u'([^uaiUAI])", b="%1U%2"},
+ {a="^'i'([^uaiUAI])", b="I%1"},
+ {a="([%s%(%[%<%-])'i'([^uaiUAI])", b="%1I%2"},
+ {a="^u'([^uaiUAI])", b="U%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])u'([^uaiUAI])", b="%1U%2"},
+ {a="^i'([^uaiUAI])", b="I%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])i'([^uaiUAI])", b="%1I%2"},
+ -- madda (historic writing below)
+ {a="^(')(A)", b="%2"},
+ {a="(%W)(')(A)", b="%1%3"},
+ {a="^'a'([^uaiUAI])", b="A%1"},
+ {a="(%W)'a'([^uaiUAI])", b="%1A%2"},
+ {a="'a'([^uaiUAI])", b="A%1"},
+ {a="^'a?A", b="A"},
+ {a="(%W)'a?A", b="%1A"},
+ {a="'a?A", b="ʾA"},
+ {a="(A)(')(i)$", b="%1ʾ%3"},
+ {a="(A)(')(i)(%W)", b="%1ʾ%3%4"},
+ {a="(A)(')(i)", b="%1ʾ%3"}, -- historic madda
+ {a="(A)(')", b="%1ʾ"}, -- historic madda
+ -- initial (needs both ^ and %W patterns):
+ -- hold it for now (see below, beginning of digraphs table)
+ {a="^(')([ua])", b="@%2"},
+ {a="^(')(i)", b="@%2"},
+ -- consider replacing initial %W with [%s%(%[%<%-]:
+ -- {a="(%W)(')([ua])", b="%1@%3"},
+ -- {a="(%W)(')(i)", b="%1@%3"},
+ {a="([%s%(%[%<%-])(')([ua])", b="%1@%3"},
+ {a="([%s%(%[%<%-])(')(i)", b="%1@%3"},
+ -- final
+ {a="([Iy])(')(aN)$", b="%1ʾ%3"},
+ {a="([Iy])(')(aN)(%W)", b="%1ʾ%3%4"},
+ {a="([^uai])(')([uai]N?)$", b="%1ʾ%3"},
+ {a="([^uai])(')([uai]N?)(%W)", b="%1ʾ%3%4"},
+ {a="([UI])(')([uai])$", b="%1ʾ%3"},
+ {a="([UI])(')([uai])(%W)", b="%1ʾ%3%4"},
+ -- middle
+ {a="(U)(')", b="%1ʾ"},
+ {a="([Iy])(')", b="%1ʾ"},
+ {a="([^uai])(')([uU])", b="%1ʾ%3"},
+ {a="([^uai])(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="([^uai])(')([iI])", b="%1ʾ%3"},
+ {a="(u)(')([uU])", b="%1ʾ%3"},
+ {a="(u)(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="(u)(')([iI])", b="%1ʾ%3"},
+ {a="(a)(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="(a)(')([uU])", b="%1ʾ%3"},
+ {a="(a)(')([iI])", b="%1ʾ%3"},
+ {a="(i)(')(%_?[aAY])", b="%1ʾ%3"},
+ {a="(i)(')([uU])", b="%1ʾ%3"},
+ {a="(i)(')([iI])", b="%1ʾ%3"},
+ {a="(a)(')([^uaiUAI])", b="%1ʾ%3"},
+ {a="(u)(')([^uaiUAI])", b="%1ʾ%3"},
+ {a="(i)(')([^uaiUAI])", b="%1ʾ%3"}
+}
+
+trigraphstrarabica = { -- trigraphs or more
+ -- 'llatI / 'llad_I
+ {a="^'ll(a)([%_]?[dt])", b="ll%1%2"},
+ {a="([%-%(%[%|%<%s])'ll(a)([%_]?[dt])", b="%1ll%2%3"}, --p
+ -- al- + lām
+ {a="^(a)l%-(l)", b="%1l-%2"},
+ {a="(%s)(a)l%-(l)", b="%1%2l-%3"},
+ -- al- + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)l%-(%^n)", b="%1l-%2"}, -- ^n is lunar
+ {a="(%s)(a)l%-(%^n)", b="%1%2l-%3"}, -- ^n is lunar
+ {a="^(a)l%-([%_%^%.]?[tdrzsnc])", b="%1l-%2"},
+ {a="(%s)(a)l%-([%_%^%.]?[tdrzsnc])", b="%1%2l-%3"},
+ -- assim. art. + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)(%^n)%-", b="%1l-"}, -- ^n is lunar
+ {a="(%s)(a)(%^n)%-", b="%1%2l-"}, -- ^n is lunar
+ {a="^(a)([%_%^%.]?[tdrzsnc])%-", b="%1l-"},
+ {a="(%s)(a)([%_%^%.]?[tdrzsnc])%-", b="%1%2l-"},
+ -- al- + initial unstable hamza
+ {a="^(a)l%-([uai])", b="%1l-%2"},
+ {a="(%s)(a)l%-([uai])", b="%1%2l-%3"},
+ -- li-/la- + art. + initial unstable hamza is a special orthography
+ {a="l([ai])%-l%-([uai])", b="l%1-l-%2"},
+ -- al- + lunar consonant (i.e. what remains)
+ {a="^(a)l%-", b="%1l-"},
+ {a="(%s)(a)l%-", b="%1%2l-"},
+ -- art. with waṣla + lām
+ {a="'l%-(l)", b="l-%1"},
+ -- art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'l%-(%^n)", b="l-%1"}, -- ^n is lunar
+ {a="'l%-([%_%^%.]?[tdrzsnc])", b="l-%1"},
+ -- li-/la- + art. + lām
+ {a="l([ai])%-l%-(l)", b="l%1-l-%2"},
+ -- assim. art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'(%^n)%-", b="l-"}, -- ^n is lunar
+ {a="'([%_%^%.]?[tdrzsnc])%-", b="l-"},
+ -- li-/la- + art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-l%-(%^n)", b="l%1-l-%2"}, -- ^n is lunar
+ {a="l([ai])%-l%-([%_%^%.]?[tdrzsnc])", b="l%1-l-%2"},
+ -- li-/la- + assim. art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-(%^n)%-(%^n)", b="l%1-l-%3"}, -- ^n is lunar
+ {a="l([ai])%-([%_%^%.]?[tdrzsnc])%-([%_%^%.]?[tdrzsnc])", b="l%1-l-%3"},
+ -- art. with waṣla + initial unstable hamza
+ {a="'l%-([uai])", b="l-%1"},
+ -- art. with waṣla + lunar consonant (i.e. what remains)
+ {a="'l%-", b="l-"},
+ -- the silent wāw
+ {a="uU$", b="u"},
+ {a="uU(%W)", b="u%1"},
+ {a="aU$", b="a"},
+ {a="aU(%W)", b="a%1"},
+ {a="iU$", b="i"},
+ {a="iU(%W)", b="i%1"},
+ -- words ending in -āT with silent wāw/yāʾ
+ {a="(_a)UA", b="A"},
+ {a="(_a)U", b="A"},
+ {a="(_a)I", b="A"}
+}
+
+digraphstrarabica = {
+ {a="([uai]%-)(\"?[uai])", b="%1"}, -- hyphen + initial alif without hamza
+ {a="([UAIYuai])(%s)([%(%[%|%<]?)(\"?[uai])", b="%1%2%3"}, --p
+ {a="(O[%S]-)([UAIuai])(O)(\"?[uai])", b=""},
+ {a="@", b=""}, -- remove the tag before the former hamza
+ -- discard the ʾiʿrāb hyphen (begin)
+ {a="(%-)(\"?[UI]na)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?[UI]na)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*)$", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*)$", b="%2%3"},
+ {a="(%-)([uai])(%p*%s)", b="%2%3"},
+ {a="(%-)([uai])(%p*)$", b="%2%3"},
+ -- discard the ʾiʿrāb hyphen (end)
+ {a="(%-)(\"?[uai])", b="%1%2"}, -- hyphen + initial alif without hamza
+ {a="^(\"?[uai])", b="%1"}, -- initial alif without hamza
+ {a="(%s)([uai])", b="%1%2"}, -- initial alif without hamza
+ {a="%-%-", b=""},
+ {a="iyy(%p*)$", b="ī%1"},
+ {a="iyy(%p*%s)", b="ī%1"},
+ -- {a="T([^uai])", b="h%1"},
+ {a="([a%']l%-)(%S-)aT([%(%[%|%<%s])(al%-)", b="%1%2a%3%4"}, --p
+ {a="aT([%(%[%|%<%s])(al%-)", b="at%1%2"}, --p
+ {a="T([%|\"])", b="t%1"},
+ {a="aT(%p*)$", b="a%1"},
+ {a="aT(%p*%s)", b="a%1"},
+ {a="_t", b="ṯ"},
+ {a="%^g", b="ǧ"},
+ {a="%.h", b="ḥ"},
+ {a="_h", b="ḫ"},
+ {a="_d", b="ḏ"},
+ {a="%^s", b="š"},
+ {a="%.s", b="ṣ"},
+ {a="%.d", b="ḍ"},
+ {a="%.t", b="ṭ"},
+ {a="%.z", b="ẓ"},
+ {a="%.g", b="ġ"},
+ {a="%.y", b="y"},
+ -- additional characters (begin)
+ {a="%^c", b="č"},
+ {a="%^z", b="ž"},
+ {a="%^n", b="ñ"},
+ -- additional characters (end)
+ {a="(U)(A)", b="ū"},
+ {a="WA", b="w"},
+ {a="(a)W", b="%1w"},
+ {a="_A", b="ā"},
+ {a="_u", b="ū"},
+ {a="_a", b="ā"},
+ {a="_i", b="ī"},
+ {a="%.b", b="b"},
+ {a="%.f", b="f"},
+ {a="%.q", b="q"},
+ {a="%.k", b="k"},
+ {a="%.n", b="n"},
+ {a="%^d", b="d"}
+}
+
+singletrarabica = {
+ {a="b", b="b"},
+ {a="t", b="t"},
+ {a="j", b="ǧ"},
+ {a="x", b="ḫ"},
+ {a="d", b="d"},
+ {a="r", b="r"},
+ {a="z", b="z"},
+ {a="s", b="s"},
+ {a="`", b="ʿ"},
+ {a="f", b="f"},
+ {a="q", b="q"},
+ {a="k", b="k"},
+ {a="l", b="l"},
+ {a="m", b="m"},
+ {a="n", b="n"},
+ {a="h", b="h"},
+ {a="w", b="w"},
+ {a="y", b="y"},
+ {a="T", b="t"},
+ -- additional characters (begin)
+ {a="p", b="p"},
+ {a="v", b="v"},
+ {a="g", b="g"},
+ -- additional characters (end)
+ {a="\"", b=""},
+ {a="B", b=""}
+}
+
+longvtrarabica = {
+ {a="aY", b="ay"},
+ {a="iY", b="ī"},
+ {a="[AY]", b="ā"},
+ {a="U", b="ū"},
+ {a="I", b="ī"}
+}
diff --git a/macros/luatex/latex/arabluatex/arabluatex_voc.lua b/macros/luatex/latex/arabluatex/arabluatex_voc.lua
new file mode 100644
index 0000000000..54c324c428
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/arabluatex_voc.lua
@@ -0,0 +1,903 @@
+--[[
+This file is part of the `arabluatex' package
+
+ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
+Copyright (C) 2016--2019 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/>.
+--]]
+
+arbmarks = {
+ {a="@bismillah", b="\\arabicfont{}^^^^fdfd", c="\\arb[trans]{bi-ismi \\uc{'l-l_ahi} 'l-ra.hm_ani 'l-ra.hImi}"},
+ {a="@salam", b="\\arabicfont{}^^^^fdf5", c="\\arb[trans]{.sall_A\\arbnull{'l-l_ahu} \\uc{'l-l_ahu} `alay-hi wa-sallama}"},
+ {a="@jalla", b="\\arabicfont{}^^^^fdfb", c="\\arb[trans]{^galla ^galAla-hu}"},
+ {a="@slm", b="\\arabicfont{}^^^^fdfa", c="\\arb[trans]{.sall_A\\arbnull{'l-l_ahu} \\uc{'l-l_ahu} `alay-hi wa-sallama}"}
+}
+
+abjad = {
+{"a\"'", "b", "j", "d", "h", "w", "z", ".h", ".t"},
+{"y", "k", "l", "m", "n", "s", "`", "f", ".s", },
+{"q", "r", "^s", "t", "_t", "x", "_d", ".d", ".z", },
+{".g"}
+}
+
+numbers = {
+ {a="0", b="٠"},
+ {a="1", b="١"},
+ {a="2", b="٢"},
+ {a="3", b="٣"},
+ {a="4", b="٤"},
+ {a="5", b="٥"},
+ {a="6", b="٦"},
+ {a="7", b="٧"},
+ {a="8", b="٨"},
+ {a="9", b="٩"}
+}
+
+raw = {
+ {a="A", b="َا"},
+ {a="U", b="ُو"},
+ {a="I", b="ِي"},
+ {a="b", b="ب"},
+ {a="t", b="ت"},
+ {a="j", b="ج"},
+ {a="x", b="خ"},
+ {a="d", b="د"},
+ {a="r", b="ر"},
+ {a="z", b="ز"},
+ {a="s", b="س"},
+ {a="f", b="ف"},
+ {a="`", b="ع"},
+ {a="f", b="ف"},
+ {a="q", b="ق"},
+ {a="k", b="ك"},
+ {a="l", b="ل"},
+ {a="m", b="م"},
+ {a="n", b="ن"},
+ {a="h", b="ه"},
+ {a="w", b="و"},
+ {a="y", b="ي"},
+ {a="T", b="ة"},
+ {a="u", b="ُ"},
+ {a="a", b="َ"},
+ {a="i", b="ِ"}
+}
+
+buckwalter = {
+ --- hard coded madda: hold it for now
+ {a="%|", b="@"},
+ {a="M", b="@"}, -- BW safe
+ {a="%_", b="--"}, -- taṭwīl
+ -- prevent any unwanted šadda from being generated
+ {a="bb", b="b|b"},
+ {a="tt", b="t|t"},
+ {a="vv", b="v|v"},
+ {a="jj", b="j|j"},
+ {a="HH", b="H|H"},
+ {a="xx", b="x|x"},
+ {a="dd", b="d|d"},
+ {a="%*%*", b="*|*"},
+ {a="VV", b="V|V"}, -- BW safe
+ {a="rr", b="r|r"},
+ {a="ss", b="s|s"},
+ {a="%$%$", b="$|$"},
+ {a="cc", b="c|c"}, -- BW safe
+ {a="SS", b="S|S"},
+ {a="DD", b="D|D"},
+ {a="TT", b="T|T"},
+ {a="ZZ", b="Z|Z"},
+ {a="EE", b="E|E"},
+ {a="gg", b="g|g"},
+ {a="ff", b="f|f"},
+ {a="qq", b="q|q"},
+ {a="kk", b="k|k"},
+ {a="ll", b="l|l"},
+ {a="mm", b="m|m"},
+ {a="nn", b="n|n"},
+ {a="hh", b="h|h"},
+ {a="ww", b="w|w"},
+ {a="yy", b="y|y"},
+ -- hamza begin
+ -- look into this later on:
+-- {a="%>a?A", b="@@@"}, -- hold this (madda)
+-- {a="%>a\'([^uai])", b="@@@%1"}, -- hold this (madda)
+ {a="a?A\'", b="@@"}, -- hold this (classic madda)
+ {a="\'", b="|\"\'"},
+ {a="C", b="|\"\'"}, -- BW safe
+ {a="%>", b="a\"\'"},
+ {a="O", b="a\"\'"}, -- BW safe
+ {a="%&", b="w\"\'"},
+ {a="W", b="w\"\'"}, -- BW safe
+ {a="%<", b="i\"\'"},
+ {a="I", b="i\"\'"}, -- BW safe
+ {a="%]", b="y\"\'"},
+ {a="Q", b="y\"\'"},
+ -- hamza end
+ -- trigraphs
+ {a="^Aal%-?", b="al-"},
+ {a="(%W)Aal%-?", b="%1al-"},
+ {a="(%s)Aal%-?", b="%1al-"},
+ {a="([%-%s])Al%-?", b="%1\'l-"},
+ {a="^A", b="a"},
+ {a="(%W)A", b="%1a"},
+ {a="(%s)A", b="%1a"},
+ {a="(al%-[%g])(%~)", b="%1"},
+ {a="(\'l%-[%g])(%~)", b="%1"},
+ -- digraphs begin
+ {a="aA", b="A"},
+ {a="uw([^%~])", b="U%1"},
+ {a="iy([^%~])", b="I%1"},
+ -- digraphs end
+ -- madda: get it back now
+-- {a="%@%@%@", b="\'A"},
+ {a="%@%@", b="A\'"}, -- give back classic madda
+ {a="%@", b="A\"\'"}, -- hard coded madda
+ -- šadda:
+ {a="([%g])(%~)", b="%1%1"},
+ {a="%`", b="_a"},
+ {a="e", b="_a"}, -- BW safe
+ {a="v", b="_t"},
+ {a="H", b=".h"},
+ {a="%*", b="_d"},
+ {a="V", b="_d"}, -- BW safe
+ {a="%$", b="^s"},
+ {a="c", b="^s"}, -- BW safe
+ {a="S", b=".s"},
+ {a="D", b=".d"},
+ {a="T", b=".t"},
+ {a="Z", b=".z"},
+ {a="E", b="`"},
+ {a="g", b=".g"},
+ {a="p", b="T"},
+ {a="N", b="uN"},
+ {a="F", b="aN"},
+ {a="K", b="iN"},
+ {a="o", b="\""},
+ {a="P", b="O"}, -- pass on to \arbnull
+ -- hard-coded connective alif
+ {a="%[", b="ٱ"},
+ {a="L", b="ٱ"} -- BW safe
+}
+
+hamza = {
+ -- next line for ʾiʿrāb hyphen
+ {a="(')(%-)([uaiUAI])", b="%1%3"},
+ -- next lines for ʾalif alone
+ {a="(%.A)([uai]?)l%-(%^n)", b="ا%2ل%3"}, --additional (^n is lunar)
+ {a="([%(%[%|%<%s%-O])(%.A)([uai]?)l%-(%^n)", b="%1ا%3%4"}, --additional (^n is lunar) --p
+ {a="(%.A)([uai]?)l%-([%_%^%.]?[tdrzsnc])", b="ا%2ل%3%3"},
+ {a="([%(%[%|%<%s%-O])(%.A)([uai]?)l%-([%_%^%.]?[tdrzsnc])", b="%1ا%3ل%4%4"}, --p
+ {a="%.A", b="ا"},
+ -- hard coded hamza
+ {a="|\"'", b="ء"},
+ {a="A\"'", b="آ"},
+ {a="[au]\"'", b="أ"},
+ {a="w\"'", b="ؤ"},
+ {a="i\"'", b="إ"},
+ {a="y\"'", b="ئ"},
+ -- hamza takes tašdīd too
+ {a="''([Uu])", b="ؤؤ%1"},
+ {a="''([Aa])", b="أأ%1"},
+ {a="''([Ii])", b="ئئ%1"},
+ -- inseparable adverbial particle 'a- + 'a
+ {a="\'(a)%-\'(a)", b="أ%1اأ%2"},
+ -- initial long u and i (for a, see below)
+ {a="%'%_U", b="أU"},
+ {a="%'%_I", b="إI"},
+ -- taḫfīfu 'l-hamza
+ {a="'u'([^uaiUAI])", b="أU%1"},
+ {a="'i'([^uaiUAI])", b="إI%1"},
+ {a="([wf]a)%-\'([^uaiUAIl][^%-])", b="%1أْ%2"},
+ {a="^u'([^uaiUAI])", b="اU%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])u'([^uaiUAI])", b="%1اU%2"},
+ {a="^i'([^uaiUAI])", b="اI%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])i'([^uaiUAI])", b="%1اI%2"},
+ -- madda (historic writing below)
+ {a="'a'([^uaiUAI])", b="آ%1"},
+ {a="([^uiyUI])\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="%1آ%2"},
+ {a="^\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="آ%1"},
+ {a="\'a?A(O[%_%^%.]?[%`%'btjghxdrzsfqklmnywAY]-O)", b="آ"},
+ {a="(%W)\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="%1آ%2"},
+ {a="(A)(O%'[%S]-O)", b="آ"},
+ {a="(A)(')(uN?%p*)$", b="aآء%3"},
+ {a="(A)(')(uN?)(%p*%s)", b="aآء%3%4"},
+ {a="(A)(')(iN?%p*)$", b="aآء%3"},
+ {a="(A)(')(iN?)(%p*%s)", b="aآء%3%4"},
+ {a="(A)(')([iI])", b="aآئ%3"}, -- historic madda
+ {a="(A)(')(u)", b="aآؤ%3"}, -- historic madda
+ {a="(A)(')", b="aآء"}, -- historic madda
+ -- initial (needs both ^ and %W patterns)
+ -- 'aw: the diphthong is to be resolved into 'awi' (next 8 lines)
+ {a="^('aw)(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(%W)('aw)(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1%2i"},
+ {a="^('aw)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(%W)('aw)(O)(\"?[uai])([%S]-O)", b="%1%2i"},
+ {a="^('aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ {a="(%W)('aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1%2i%3%4"},
+ {a="^('aw)(%s)([%(%[%|%<]?\"?[uai])", b="%1i%2%3"}, --p
+ {a="(%W)('aw)(%s)([%(%[%|%<]?\"?[uai])", b="%1%2i%3%4"}, --p
+ -- then the 'initial' rules for the remaining cases
+ {a="^(')([ua])", b="أ%2"},
+ {a="^(')(i)", b="إ%2"},
+ -- consider replacing initial %W with [%s%(%[%<%-]:
+ -- {a="(%W)(')([ua])", b="%1أ%3"},
+ -- {a="(%W)(')(i)", b="%1إ%3"},
+ {a="([%s%(%[%<%-])(')([ua])", b="%1أ%3"},
+ {a="([%s%(%[%<%-])(')(i)", b="%1إ%3"},
+ -- final
+ -- mi'aT is special orthography (unlike ^say'aN and .zim'aN):
+ -- {a="(%^sa%.?[yY])(\"?%|?)(%')(aN)", b="%1%2ئ%4"}, --new
+ -- {a="(.zi?m)(%')(aN)", b="%1ئ%3"}, --new
+ {a="(mi)(%')(a[Tt])", b="%1ائ%3"},
+ {a="(mi)(%')(aN%_?[AY])", b="%1أ%3"},
+ -- final hamzah is on the line after a letter of prolongation or a
+ -- consonant with sukūn
+ {a="([^Auai])(')(\"?[uai]N?)(%p*)$", b="%1ء%3%4"}, --new
+ {a="([^Auai])(')(\"?[uai]N?)(%p*%s)", b="%1ء%3%4"},
+-- u
+ {a="(u)(')([uai]N?%p*)$", b="%1ؤ%3"},
+ {a="(u)(')([uai]N?)(%p*%s)", b="%1ؤ%3%4"},
+ {a="(u)(')(%p*)$", b="%1ؤ%3"},
+ {a="(u)(')(%p*%s)", b="%1ؤ%3"},
+-- a
+ {a="(a)(')(A%p*)$", b="%1آ"},
+ {a="(a)(')(A)(%p*%s)", b="%1آ%4"},
+ {a="(a)(')([u]N?%p*)$", b="%1أ%3"},
+ {a="(a)(')([u]N?)(%p*%s)", b="%1أ%3%4"},
+ {a="(a)(')(a%p*)$", b="%1أ%3"},
+ {a="(a)(')(a)(%p*%s)", b="%1أ%3%4"},
+ {a="(a)(')(aN%p*)$", b="%1أً"},
+ {a="(a)(')(aN)(%p*%s)", b="%1أً%4"},
+ {a="(a)(')([i]N?%p*)$", b="%1إ%3"},
+ {a="(a)(')([i]N?)(%p*%s)", b="%1إ%3%4"},
+ {a="(a)(')(%p*)$", b="%1أ%3"},
+ {a="(a)(')(%p*%s)", b="%1أ%3"},
+-- i
+ {a="(i)(')([uai]N?%p*)$", b="%1ئ%3"},
+ {a="(i)(')([uai]N?)(%p*%s)", b="%1ئ%3%4"},
+ {a="(i)(')(%p*)$", b="%1ئ%3"},
+ {a="(i)(')(%p*%s)", b="%1ئ%3"},
+--
+ -- middle
+ {a="([UIwy])(')", b="%1ء"}, --new
+ -- {a="([Iy])(')", b="%1ئ"}, -- included in the above line
+ {a="([^uai])(')([uU])", b="%1ؤ%3"},
+ {a="([^uai])(')(%_?[aAY])", b="%1أ%3"},
+ {a="([^uai])(')([iI])", b="%1ئ%3"},
+ {a="(u)(')([uU])", b="%1ؤ%3"},
+ {a="(u)(')(%_?[aAY])", b="%1ؤ%3"},
+ {a="(u)(')([iI])", b="%1ئ%3"},
+ {a="(a)(')(%_?[aAY])", b="%1أ%3"},
+ {a="(a)(')([uU])", b="%1ؤ%3"},
+ {a="(a)(')([iI])", b="%1ئ%3"},
+ {a="(i)(')(%_?[aAY])", b="%1ئ%3"},
+ {a="(i)(')([uU])", b="%1ئ%3"},
+ {a="(i)(')([iI])", b="%1ئ%3"},
+ {a="(a)(')([^uaiUAI])", b="%1أ%3"},
+ {a="(u)(')([^uaiUAI])", b="%1ؤ%3"},
+ {a="(i)(')([^uaiUAI])", b="%1ئ%3"}
+}
+
+hamzaeasy = { -- differences marked below with 'easy'
+ -- next line for ʾiʿrāb hyphen
+ {a="(')(%-)([uaiUAI])", b="%1%3"},
+ -- next lines for ʾalif alone (easy)
+ {a="(%.A)([uai]?)l%-(%^n)", b="ا%2ل%3"}, --additional (^n is lunar)
+ {a="([%(%[%|%<%s%-O])(%.A)([uai]?)l%-(%^n)", b="%1ا%3%4"}, --additional (^n is lunar) --p
+ {a="(%.A)([uai]?)l%-([%_%^%.]?[tdrzsnc])", b="ا%2ل%3"},
+ {a="([%(%[%|%<%s%-O])(%.A)([uai]?)l%-([%_%^%.]?[tdrzsnc])", b="%1ا%3ل%4"}, --p
+ {a="%.A", b="ا"},
+ -- hard coded hamza
+ {a="|\"'", b="ء"},
+ {a="A\"'", b="آ"},
+ {a="[au]\"'", b="أ"},
+ {a="w\"'", b="ؤ"},
+ {a="i\"'", b="إ"},
+ {a="y\"'", b="ئ"},
+ -- hamza takes tašdīd too
+ {a="''([Uu])", b="ؤؤ%1"},
+ {a="''([Aa])", b="أأ%1"},
+ {a="''([Ii])", b="ئئ%1"},
+ -- inseparable adverbial particle 'a- + 'a
+ {a="\'(a)%-\'(a)", b="أ%1اأ%2"},
+ -- initial long u and i (for a, see below)
+ {a="%'%_U", b="أU"},
+ {a="%'%_I", b="إI"},
+ -- taḫfīfu 'l-hamza
+ {a="'u'([^uaiUAI])", b="أU%1"},
+ {a="'i'([^uaiUAI])", b="إI%1"},
+ {a="([wf]a)%-\'([^uaiUAIl][^%-])", b="%1أْ%2"},
+ {a="^u'([^uaiUAI])", b="اU%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])u'([^uaiUAI])", b="%1اU%2"},
+ {a="^i'([^uaiUAI])", b="اI%1"},
+ {a="([^uaiUAIYN][%s%(%[%<])i'([^uaiUAI])", b="%1اI%2"},
+ -- madda (historic writing below)
+ {a="'a'([^uaiUAI])", b="آ%1"},
+ {a="([^uiyUI])\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="%1آ%2"},
+ {a="^\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="آ%1"},
+ {a="\'a?A(O[%_%^%.]?[%`%'btjghxdrzsfqklmnywAY]-O)", b="آ"},
+ {a="(%W)\'a?A([%_%^%.]?[%`%'btjghxdrzsfqklmnywAY])", b="%1آ%2"},
+ --easy (begin)
+ {a="(A)(O%'[%S]-O)", b="ا"},
+ {a="(A)(')(uN?%p*)$", b="aاء%3"},
+ {a="(A)(')(uN?)(%p*%s)", b="aاء%3%4"},
+ {a="(A)(')(iN?%p*)$", b="aاء%3"},
+ {a="(A)(')(iN?)(%p*%s)", b="aاء%3%4"},
+ {a="(A)(')([iI])", b="aائ%3"}, -- historic madda
+ {a="(A)(')(u)", b="aاؤ%3"}, -- historic madda
+ {a="(A)(')", b="aاء"}, -- historic madda
+ --easy (end)
+ -- initial (needs both ^ and %W patterns)
+ -- 'aw: the diphthong is to be resolved into 'awi' (next 8 lines)
+ {a="^('aw)(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(%W)('aw)(O)('[%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1%2i"},
+ {a="^('aw)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(%W)('aw)(O)(\"?[uai])([%S]-O)", b="%1%2i"},
+ {a="^('aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ {a="(%W)('aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1%2i%3%4"},
+ {a="^('aw)(%s)([%(%[%|%<]?\"?[uai])", b="%1i%2%3"},
+ {a="(%W)('aw)(%s)([%(%[%|%<]?\"?[uai])", b="%1%2i%3%4"},
+ -- then the 'initial' rules for the remaining cases
+ {a="^(')([ua])", b="أ%2"},
+ {a="^(')(i)", b="إ%2"},
+ -- consider replacing initial %W with [%s%(%[%<%-]:
+ -- {a="(%W)(')([ua])", b="%1أ%3"},
+ -- {a="(%W)(')(i)", b="%1إ%3"},
+ {a="([%s%(%[%<%-])(')([ua])", b="%1أ%3"},
+ {a="([%s%(%[%<%-])(')(i)", b="%1إ%3"},
+ -- final
+ -- mi'aT is special orthography (unlike ^say'aN and .zim'aN)
+ -- {a="(%^sa%.?[yY])(\"?%|?)(%')(aN)", b="%1%2ئ%4"}, --new
+ -- {a="(.zi?m)(%')(aN)", b="%1ئ%3"}, --new
+ {a="(mi)(%')(a[Tt])", b="%1ائ%3"},
+ {a="(mi)(%')(aN%_?[AY])", b="%1أ%3"},
+ -- easy (begin)
+ -- The Munjid says that such words as radI'aN do not have the
+ -- hamzah alone on the line, so take out the following two lines
+ -- (final hamzah is on the line after a letter of prolongation or a
+ -- consonant with sukūn)
+ -- {a="([^Auai])(')(\"?[uai]N?)(%p*)$", b="%1ء%3%4"}, --new
+ -- {a="([^Auai])(')(\"?[uai]N?)(%p*%s)", b="%1ء%3%4"},
+ {a="([^Auai])(')(\"?aN)(%p*)$", b="%1ئ%3%4"}, --new
+ {a="([^Auai])(')(\"?aN)(%p*%s)", b="%1ئ%3%4"}, --new
+ {a="([^uai])(')(\"?a)(%p*)$", b="%1ء%3%4"}, --new
+ {a="([^uai])(')(\"?a)(%p*%s)", b="%1ء%3%4"}, --new
+ {a="([^uai])(')(\"?[ui]N?)(%p*)$", b="%1ء%3%4"}, --new
+ {a="([^uai])(')(\"?[ui]N?)(%p*%s)", b="%1ء%3%4"}, --new
+ --easy (end)
+-- u
+ {a="(u)(')([uai]N?%p*)$", b="%1ؤ%3"},
+ {a="(u)(')([uai]N?)(%p*%s)", b="%1ؤ%3%4"},
+ {a="(u)(')(%p*)$", b="%1ؤ%3"},
+ {a="(u)(')(%p*%s)", b="%1ؤ%3"},
+-- a
+ {a="(a)(')(A%p*)$", b="%1آ"},
+ {a="(a)(')(A)(%p*%s)", b="%1آ%4"},
+ {a="(a)(')([u]N?%p*)$", b="%1أ%3"},
+ {a="(a)(')([u]N?)(%p*%s)", b="%1أ%3%4"},
+ {a="(a)(')(a%p*)$", b="%1أ%3"},
+ {a="(a)(')(a)(%p*%s)", b="%1أ%3%4"},
+ {a="(a)(')(aN%p*)$", b="%1أً"},
+ {a="(a)(')(aN)(%p*%s)", b="%1أً%4"},
+ {a="(a)(')([i]N?%p*)$", b="%1إ%3"},
+ {a="(a)(')([i]N?)(%p*%s)", b="%1إ%3%4"},
+ {a="(a)(')(%p*)$", b="%1أ%3"},
+ {a="(a)(')(%p*%s)", b="%1أ%3"},
+-- i
+ {a="(i)(')([uai]N?%p*)$", b="%1ئ%3"},
+ {a="(i)(')([uai]N?)(%p*%s)", b="%1ئ%3%4"},
+ {a="(i)(')(%p*)$", b="%1ئ%3"},
+ {a="(i)(')(%p*%s)", b="%1ئ%3"},
+--
+ -- middle
+ {a="([Uw])(')", b="%1ء"}, --new
+ {a="([Iy])(')", b="%1ئ"}, --easy
+ {a="([^uai])(')([uU])", b="%1ؤ%3"},
+ {a="([^uai])(')(%_?[aAY])", b="%1أ%3"},
+ {a="([^uai])(')([iI])", b="%1ئ%3"},
+ {a="(u)(')([uU])", b="%1ؤ%3"},
+ {a="(u)(')(%_?[aAY])", b="%1ؤ%3"},
+ {a="(u)(')([iI])", b="%1ئ%3"},
+ {a="(a)(')(%_?[aAY])", b="%1أ%3"},
+ {a="(a)(')([uU])", b="%1ؤ%3"},
+ {a="(a)(')([iI])", b="%1ئ%3"},
+ {a="(i)(')(%_?[aAY])", b="%1ئ%3"},
+ {a="(i)(')([uU])", b="%1ئ%3"},
+ {a="(i)(')([iI])", b="%1ئ%3"},
+ {a="(a)(')([^uaiUAI])", b="%1أ%3"},
+ {a="(u)(')([^uaiUAI])", b="%1ؤ%3"},
+ {a="(i)(')([^uaiUAI])", b="%1ئ%3"}
+}
+
+tanwin = {
+ -- assimilations (begin)
+ {a="(O[%S]-)(%-?[uai]N[UI]?)(O)([rlmnwy])", b="%4%4"},
+ {a="(%-?[uai]NU)(%s)([rlmnwy])", b="%1%2%3%3"},
+ -- assimilations (end)
+ {a="(O[%S]-)(%-?[uai]N[UI]?)(O)([uai])", b="%4"},
+ {a="%-?uNU", b="ٌو"},
+ {a="%-?aNU", b="ًوا"},
+ {a="%-?iNU", b="ٍو"},
+ -- assimilations (begin)
+ {a="%-?(uN)(%s)([rlmnwy])", b="ٌ%2%3%3"},
+ {a="(O[%S]-)(%-?aN)(_A)(O)([rlmnwy])", b="%5%5"},
+ {a="(O[%S]-)(%-?aN)(Y)(O)([rlmnwy])", b="%5%5"},
+ {a="%-?(aN)(_A)(%s)([rlmnwy])", b="ًى%3%4%4"},
+ {a="%-?(aN)(Y)(%s)([rlmnwy])", b="ًى%3%4%4"},
+ {a="(T)%-?(aN)(%s)([rlmnwy])", b="%1ً%3%4%4"},
+ {a="(ء)%-?(aN)(%s)([rlmnwy])", b="%1%2%3%4%4"}, --new
+ {a="([^TA])%-?(aN)(%s)([rlmnwy])", b="%1ًا%3%4%4"},
+ {a="%-?(iNI?)(%s)([rlmnwy])", b="ٍ%2%3%3"},
+ -- assimilations (end)
+ {a="(O[%S]-)(%-?aN)(_A)(O)([uai])", b="%5"},
+ {a="(O[%S]-)(%-?aN)(Y)(O)([uai])", b="%5"},
+ -- quoted tanwīn (begin)
+ {a="%-?(\"uN)", b=""},
+ {a="(B)%-?(\"aN)", b="%1"},
+ {a="%-?(\"aN)(_A)", b="ى"},
+ {a="%-?(\"aN)(Y)", b="ى"},
+ {a="(T)%-?(\"aN)", b="%1"},
+ {a="([اآ])(ء)%-?(\"aN)", b="%1%2"}, --new
+ {a="([^TA])%-?(\"aN)", b="%1ا"},
+ {a="%-?(\"iNI?)", b=""},
+ -- quoted tanwīn (end)
+ {a="%-?(uN)", b="ٌ"},
+ {a="(B)%-?(aN)", b="%1ً"},
+ -- needed by \arbcolor:
+ {a="%-?(aN)(O[%S]-%_AO)", b="ً"},
+ {a="%-?(aN)(O[%S]-YO)", b="ً"},
+ {a="(O[%S]-TO)%-?(aN)", b="ً"},
+ {a="(O[%S]-)([اآ])(ء)(O)%-?(aN)", b="ً"}, --new
+ {a="(O[%S]-[^TA]O)%-?(aN)", b="ًا"},
+ --
+ {a="%-?(aN)(_A)", b="ًى"},
+ {a="%-?(aN)(Y)", b="ًى"},
+ {a="(T)%-?(aN)", b="%1ً"},
+ {a="([اآ])(ء)%-?(aN)", b="%1%2ً"}, --new
+ {a="([^TA])%-?(aN)", b="%1ًا"},
+ {a="%-?(iNI?)", b="ٍ"}
+}
+
+tanwineasy = { -- 'easy' requires some lines to be taken out:
+ -- assimilations (begin)
+-- {a="(O[%S]-)(%-?[uai]N[UI]?)(O)([rlmnwy])", b="%4%4"},
+-- {a="(%-?[uai]NU)(%s)([rlmnwy])", b="%1%2%3%3"},
+ -- assimilations (end)
+ {a="(O[%S]-)(%-?[uai]N[UI]?)(O)([uai])", b="%4"},
+ {a="%-?uNU", b="ٌو"},
+ {a="%-?aNU", b="ًوا"},
+ {a="%-?iNU", b="ٍو"},
+ -- assimilations (begin)
+-- {a="%-?(uN)(%s)([rlmnwy])", b="ٌ%2%3%3"},
+-- {a="(O[%S]-)(%-?aN)(_A)(O)([rlmnwy])", b="%5%5"},
+-- {a="(O[%S]-)(%-?aN)(Y)(O)([rlmnwy])", b="%5%5"},
+-- {a="%-?(aN)(_A)(%s)([rlmnwy])", b="ًى%3%4%4"},
+-- {a="%-?(aN)(Y)(%s)([rlmnwy])", b="ًى%3%4%4"},
+-- {a="(T)%-?(aN)(%s)([rlmnwy])", b="%1ً%3%4%4"},
+-- {a="(ء)%-?(aN)(%s)([rlmnwy])", b="%1%2%3%4%4"}, --new
+-- {a="([^TA])%-?(aN)(%s)([rlmnwy])", b="%1ًا%3%4%4"},
+-- {a="%-?(iNI?)(%s)([rlmnwy])", b="ٍ%2%3%3"},
+ -- assimilations (end)
+ {a="(O[%S]-)(%-?aN)(_A)(O)([uai])", b="%5"},
+ {a="(O[%S]-)(%-?aN)(Y)(O)([uai])", b="%5"},
+ -- quoted tanwīn (begin)
+ {a="%-?(\"uN)", b=""},
+ {a="(B)%-?(\"aN)", b="%1"},
+ {a="%-?(\"aN)(_A)", b="ى"},
+ {a="%-?(\"aN)(Y)", b="ى"},
+ {a="(T)%-?(\"aN)", b="%1"},
+ {a="([اآ])(ء)%-?(\"aN)", b="%1%2"}, --new
+ {a="([^TA])%-?(\"aN)", b="%1ا"},
+ {a="%-?(\"iNI?)", b=""},
+ -- quoted tanwīn (end)
+ {a="%-?(uN)", b="ٌ"},
+ {a="(B)%-?(aN)", b="%1ً"},
+ -- needed by \arbcolor:
+ {a="%-?(aN)(O[%S]-%_AO)", b="ً"},
+ {a="%-?(aN)(O[%S]-YO)", b="ً"},
+ {a="(O[%S]-TO)%-?(aN)", b="ً"},
+ {a="(O[%S]-)([اآ])(ء)(O)%-?(aN)", b="ً"}, --new
+ {a="(O[%S]-[^TA]O)%-?(aN)", b="ًا"},
+ --
+ {a="%-?(aN)(_A)", b="ًى"},
+ {a="%-?(aN)(Y)", b="ًى"},
+ {a="(T)%-?(aN)", b="%1ً"},
+ {a="([اآ])(ء)%-?(aN)", b="%1%2ً"}, --new
+ {a="([^TA])%-?(aN)", b="%1ًا"},
+ {a="%-?(iNI?)", b="ٍ"}
+}
+
+trigraphs = { -- trigraphs or more
+ -- ʾalif al-waṣl: put it back on with \arbnull
+ {a="(O[%S]-)([%'a]l%-)(O)(\"[uai])", b="ٱ"},
+ {a="(O[%S]-)([%'a]l%-)(O)([uai])", b="ا"},
+ -- 'llatI / 'llad_I
+ {a="^'ll(a)([%_]?[dt])", b="الّ%1%2"},
+ {a="([%(%[%|%<%s%-])'ll(a)([%_]?[dt])", b="%1الّ%2%3"}, --p
+ -- law: the diphthong is to be resolved into 'awi' (next 8 lines)
+ {a="^(law)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(%W)(law)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1%2i"},
+ {a="^(law)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(%W)(law)(O)(\"?[uai])([%S]-O)", b="%1%2i"},
+ {a="^(law)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ {a="(%W)(law)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1%2i%3%4"},
+ {a="^(law)(%s)([%(%[%|%<]?\"?[uai])", b="%1i%2%3"}, --p
+ {a="(%W)(law)(%s)([%(%[%|%<]?\"?[uai])", b="%1%2i%3%4"}, --p
+ -- al- + lām
+ {a="^(a)l%-(l)", b="ا%1ل%2%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-(l)", b="%1ا%2ل%3%3"}, --p
+ -- al- + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)l%-(%^n)", b="ا%1ل%2"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-O])(a)l%-(%^n)", b="%1ا%2ل%3"},-- ^n is lunar --p
+ {a="^(a)l%-([%_%^%.]?[tdrzsnc])", b="ا%1ل%2%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-([%_%^%.]?[tdrzsnc])", b="%1ا%2ل%3%3"}, --p
+ -- assim. art. + solar consonant ('c' and '^n' are additional characters)
+ {a="^(a)(%^n)%-", b="ا%1ل"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-O])(a)(%^n)%-", b="%1ا%2ل"},-- ^n is lunar --p
+ {a="^(a)([%_%^%.]?[tdrzsnc])%-", b="ا%1ل%2"},
+ {a="([%(%[%|%<%s%-O])(a)([%_%^%.]?[tdrzsnc])%-", b="%1ا%2ل%3"}, --p
+ -- al- + initial unstable hamza
+ {a="^(a)l%-(\")([uai])", b="ا%1ل%3ٱ"},
+ {a="([%(%[%|%<%s%-O])(a)l%-(\")([uai])", b="%1ا%2ل%4ٱ"}, --p
+ {a="^(a)l%-([uai])", b="ا%1ل%2ا"},
+ {a="([%(%[%|%<%s%-O])(a)l%-([uai])", b="%1ا%2ل%3ا"}, --p
+ -- li-/la- + art. + initial unstable hamza is a special orthography
+ {a="l([ai])%-l%-(\")([uai])", b="ل%1ل%3ٱ"},
+ {a="l([ai])%-l%-([uai])", b="ل%1ل%2ا"},
+ -- al- + lunar consonant (i.e. what remains)
+ {a="^(a)l%-", b="ا%1ل"},
+ {a="([%(%[%|%<%s%-O])(a)l%-", b="%1ا%2ل"}, --p
+ -- diphthongs to be resolved before ʾalif conjunctionis
+ {a="(aW)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="awuا"},
+ {a="(aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1u"},
+ {a="(ay)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(aW)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="awuا%2%3"},
+ {a="(aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1u%2%3"},
+ {a="(ay)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ -- art. with waṣla + lām
+ {a="'l%-(l)", b="ال%1%1"},
+ -- art. with waṣla + solar consonant
+ -- ('c' and '^n' are additional characters)
+ {a="'l%-(%^n)", b="ال%1"}, -- ^n is lunar
+ {a="'l%-([%_%^%.]?[tdrzsnc])", b="ال%1%1"},
+ -- li-/la- + art. + lām
+ {a="l([ai])%-l%-(l)", b="ل%1%2%2"},
+ -- assim. art. with waṣla + solar consonant ('c' and '^n' are
+ -- additional characters)
+ {a="'(%^n)%-", b="ال"}, -- ^n is lunar
+ {a="'([%_%^%.]?[tdrzsnc])%-", b="ال%1"},
+ -- li-/la- + art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-l%-(%^n)", b="ل%1ل%2"}, -- '^n' is lunar
+ {a="l([ai])%-l%-([%_%^%.]?[tdrzsnc])", b="ل%1ل%2%2"},
+ -- li-/la + assim. art. + solar consonant is a special orthography
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-(%^n)%-(%^n)", b="ل%1ل%3"}, -- ^n is lunar
+ {a="l([ai])%-([%_%^%.]?[tdrzsnc])%-([%_%^%.]?[tdrzsnc])", b="ل%1ل%3%3"},
+ -- art. with waṣla + initial unstable hamza
+ {a="'l%-(\")([uai])", b="ال%2ٱ"},
+ {a="'l%-([uai])", b="ال%1ا"},
+ -- art. with waṣla + lunar consonant (i.e. what remains)
+ {a="'l%-", b="ال"},
+ -- the silent wāw
+ {a="uU(%p*)$", b="uو%1"},
+ {a="uU(%p*%s)", b="uو%1"},
+ {a="aU(%p*)$", b="aو%1"},
+ {a="aU(%p*%s)", b="aو%1"},
+ {a="iU(%p*)$", b="iو%1"},
+ {a="iU(%p*%s)", b="iو%1"},
+ -- words ending in -āT with silent wāw/yāʾ
+ {a="(_a)UA", b="%1وا"},
+ {a="(_a)U", b="%1و"},
+ {a="(_a)I", b="%1ي"}
+}
+
+idgham = {
+ -- assimilations
+ {a="(n)(%s)([rlmnwy])", b="%1%2%3%3"},
+ {a="(n)(O)([rlmnwy])([%S]-O)", b="%3"}
+}
+
+trigraphseasy = { -- differences marked below with 'easy'
+ -- ʾalif al-waṣl: put it back on with \arbnull
+ {a="(O[%S]-)([%'a]l%-)(O)(\"[uai])", b="ٱ"},
+ {a="(O[%S]-)([%'a]l%-)(O)([uai])", b="ا"},
+ -- Allah (easy)
+ {a="l%-l_ah", b="l-ll_ah"},
+ -- 'llatI / 'llad_I
+ {a="^'ll(a)([%_]?[dt])", b="الّ%1%2"},
+ {a="([%(%[%|%<%s%-])'ll(a)([%_]?[dt])", b="%1الّ%2%3"}, --p
+ -- law: the diphthong is to be resloved into 'awi' (next 8 lines)
+ {a="^(law)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(%W)(law)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1%2i"},
+ {a="^(law)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(%W)(law)(O)(\"?[uai])([%S]-O)", b="%1%2i"},
+ {a="^(law)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ {a="(%W)(law)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1%2i%3%4"},
+ {a="^(law)(%s)([%(%[%|%<]?\"?[uai])", b="%1i%2%3"}, --p
+ {a="(%W)(law)(%s)([%(%[%|%<]?\"?[uai])", b="%1%2i%3%4"}, --p
+ -- al- + lām (easy)
+ {a="^(a)l%-(l)", b="ا%1ل%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-(l)", b="%1ا%2ل%3"}, --p
+ -- al- + solar consonant (easy) ('c' and '^n' are additional characters)
+ {a="^(a)l%-(%^n)", b="ا%1ل%2"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-O])(a)l%-(%^n)", b="%1ا%2ل%3"}, -- ^n is lunar --p
+ {a="^(a)l%-([%_%^%.]?[tdrzsnc])", b="ا%1ل%2"},
+ {a="([%(%[%|%<%s%-O])(a)l%-([%_%^%.]?[tdrzsnc])", b="%1ا%2ل%3"}, --p
+ -- assim. art. + solar consonant (easy) ('c' and '^n' are
+ -- additional characters)
+ {a="^(a)(%^n)%-", b="ا%1ل"}, -- ^n is lunar
+ {a="([%(%[%|%<%s%-O])(a)(%^n)%-", b="%1ا%2ل"}, -- ^n is lunar --p
+ {a="^(a)([%_%^%.]?[tdrzsnc])%-", b="ا%1ل"},
+ {a="([%(%[%|%<%s%-O])(a)([%_%^%.]?[tdrzsnc])%-", b="%1ا%2ل"}, --p
+ -- al- + initial unstable hamza
+ {a="^(a)l%-(\")([uai])", b="ا%1ل%3ٱ"},
+ {a="([%(%[%|%<%s%-O])(a)l%-(\")([uai])", b="%1ا%2ل%4ٱ"}, --p
+ {a="^(a)l%-([uai])", b="ا%1ل%2ا"},
+ {a="([%(%[%|%<%s%-O])(a)l%-([uai])", b="%1ا%2ل%3ا"}, --p
+ -- li-/la- + art. + initial unstable hamza is a special orthography
+ {a="l([ai])%-l%-(\")([uai])", b="ل%1ل%3ٱ"},
+ {a="l([ai])%-l%-([uai])", b="ل%1ل%2ا"},
+ -- al- + lunar consonant (i.e. what remains)
+ {a="^(a)l%-", b="ا%1ل"},
+ {a="([%(%[%|%<%s%-O])(a)l%-", b="%1ا%2ل"}, --p
+ -- diphthongs to be resolved before ʾalif conjunctionis
+ {a="(aW)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="awuا"},
+ {a="(aw)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1u"},
+ {a="(ay)(O)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)([%S]-O)", b="%1i"},
+ {a="(aW)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="awuا%2%3"},
+ {a="(aw)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1u%2%3"},
+ {a="(ay)(%s)(['][%_%^%.]?[l'btjghxdrzs`fqkmnwy]%-)", b="%1i%2%3"},
+ -- art. with waṣla + lām (easy)
+ {a="'l%-(l)", b="ال%1"},
+ -- art. with waṣla + solar consonant (easy)
+ -- ('c' and '^n' are additional characters)
+ {a="'l%-(%^n)", b="ال%1"}, -- ^n is lunar
+ {a="'l%-([%_%^%.]?[tdrzsnc])", b="ال%1"},
+ -- li-/la- + art. + lām (easy)
+ {a="l([ai])%-l%-(l)", b="ل%1%2"},
+ -- assim. art. with waṣla + solar consonant (easy)
+ -- ('c' and '^n' are additional characters)
+ {a="'(%^n)%-", b="ال"}, -- ^n is lunar
+ {a="'([%_%^%.]?[tdrzsnc])%-", b="ال"},
+ -- li-/la- + art. + solar consonant is a special orthography (easy)
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-l%-(%^n)", b="ل%1ل%2"}, -- ^n is lunar
+ {a="l([ai])%-l%-([%_%^%.]?[tdrzsnc])", b="ل%1ل%2"},
+ -- li-/la + assim. art. + solar consonant is a special orthography (easy)
+ -- ('c' and '^n' are additional characters)
+ {a="l([ai])%-(%^n)%-(%^n)", b="ل%1ل%3"}, -- ^n is lunar
+ {a="l([ai])%-([%_%^%.]?[tdrzsnc])%-([%_%^%.]?[tdrzsnc])", b="ل%1ل%3"},
+ -- art. with waṣla + initial unstable hamza
+ {a="'l%-(\")([uai])", b="ال%2ٱ"},
+ {a="'l%-([uai])", b="ال%1ا"},
+ -- art. with waṣla + lunar consonant (i.e. what remains)
+ {a="'l%-", b="ال"},
+ -- the silent wāw
+ {a="uU(%p*)$", b="uو%1"},
+ {a="uU(%p*%s)", b="uو%1"},
+ {a="aU(%p*)$", b="aو%1"},
+ {a="aU(%p*%s)", b="aو%1"},
+ {a="iU(%p*)$", b="iو%1"},
+ {a="iU(%p*%s)", b="iو%1"},
+ -- words ending in -āT with silent wāw/yāʾ
+ {a="(_a)UA", b="%1وا"},
+ {a="(_a)U", b="%1و"},
+ {a="(_a)I", b="%1ي"}
+}
+
+digraphs = {
+ -- ʾiʿrāb: straight double quote must be discarded
+ {a="(%-)(\"?[UI]na)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?[UI]na)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?At[ui])(%p*)$", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?Ani)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?ayni)(%p*)$", b="%2%3"},
+ {a="(%-)(\"?[uai])(%p*%s)", b="%2%3"},
+ {a="(%-)(\"?[uai])(%p*)$", b="%2%3"},
+ -- ʾiʿrāb (end)
+ -- initial straight double quote gives a connective ʾalif
+ {a="^\"[uai]", b="ٱ"},
+ {a="([%(%[%|%<%s%-])\"[uai]", b="%1ٱ"}, --p
+ -- diphthongs to be resolved before ʾalif conjunctionis
+ {a="(aW)(O)(\"?[uai])([%S]-O)", b="awuا"},
+ {a="(aW)(%s)([%(%[%|%<]?)([uai])", b="awuا%2%3%4"}, --p
+ {a="(aw)(O)(\"?[uai])([%S]-O)", b="%1u"},
+ {a="(aw)(%s)([%(%[%|%<]?)(\"?[uai])", b="%1u%2%3ا"}, --p
+ {a="(ay)(O)(\"?[uai])([%S]-O)", b="%1i"},
+ {a="(ay)(%s)([%(%[%|%<]?)(\"?[uai])", b="%1i%2%3ا"}, --p
+ -- hyphen + initial alif without hamza:
+ {a="([uai]%-)(\"?[uai])([%^%_%.%`]?)([%aإأؤئ])", b="%1ا%3%4"},
+ -- initial alif without hamza
+ {a="^([%(%[%|%<]?)(\"?[uai])", b="%1ا%2"}, --p
+ -- initial alif without hamza
+ {a="(O[%S]-)([uaiUAIY])(O)(\"?[uai])", b="ا"},
+ {a="(%s)([%(%[%|%<]?)(\"?[uai])", b="%1%2ا"}, --p
+ {a="%-%-", b="ـ"},
+ {a="ؤؤ", b="ؤّ"},
+ {a="أأ", b="أّ"},
+ {a="ئئ", b="ئّ"},
+ {a="bb", b="بّ"},
+ {a="BB", b="ـّ"},
+ {a="([%_%^%.])([tghdsz])([tghdsz])", b="%1%2|%3"},
+ -- same as above for additional characters:
+ {a="([%_%^%.])([cn])([cn])", b="%1%2|%3"},
+ {a="tt", b="تّ"},
+ {a="%_t%_t", b="ثّ"},
+ {a="jj", b="جّ"},
+ {a="%^g%^g", b="جّ"},
+ {a="%.h%.h", b="حّ"},
+ {a="xx", b="خّ"},
+ {a="%_h%_h", b="خّ"},
+ {a="dd", b="دّ"},
+ {a="%_d%_d", b="ذّ"},
+ {a="rr", b="رّ"},
+ {a="zz", b="زّ"},
+ {a="ss", b="سّ"},
+ {a="%^s%^s", b="شّ"},
+ {a="%.s%.s", b="صّ"},
+ {a="%.d%.d", b="ضّ"},
+ {a="%.t%.t", b="طّ"},
+ {a="%.z%.z", b="ظّ"},
+ {a="%`%`", b="عّ"},
+ {a="%.g%.g", b="غّ"},
+ {a="ff", b="فّ"},
+ {a="qq", b="قّ"},
+ {a="kk", b="كّ"},
+ {a="ll", b="لّ"},
+ {a="mm", b="مّ"},
+ {a="nn", b="نّ"},
+ {a="hh", b="هّ"},
+ {a="ww", b="وّ"},
+ {a="yy", b="يّ"},
+ {a="%.y%.y", b="ىّ"},
+ -- additional characters + šaddah (begin)
+ {a="pp", b="پّ"},
+ {a="vv", b="ڤّ"},
+ {a="gg", b="گّ"},
+ {a="%^c%^c", b="چّ"},
+ {a="%^z%^z", b="ژّ"},
+ {a="%^n%^n", b="ڭّ"},
+ -- additional characters + šaddah (end)
+ {a="_t", b="ث"},
+ {a="%^g", b="ج"},
+ {a="%.h", b="ح"},
+ {a="_h", b="خ"},
+ {a="_d", b="ذ"},
+ {a="%^s", b="ش"},
+ {a="%.s", b="ص"},
+ {a="%.d", b="ض"},
+ {a="%.t", b="ط"},
+ {a="%.z", b="ظ"},
+ {a="%.g", b="غ"},
+ {a="%.y", b="ى"},
+ -- additional characters (begin)
+ {a="%^c", b="چ"},
+ {a="%^z", b="ژ"},
+ {a="%^n", b="ڭ"},
+ -- additional characters (end)
+ {a="(U)(A)", b="%1ا"},
+ {a="WA", b="وا"},
+ {a="(a)W\"", b="%1وْا"},
+ {a="(a)W", b="%1وا"},
+ {a="_A", b="aى"},
+ {a="_u", b="ٗ"},
+ {a="_a", b="ٰ"},
+ {a="_i", b="ٖ"},
+ {a="%.b", b="ٮ"},
+ {a="%.f", b="ڡ"},
+ {a="%.q", b="ٯ"},
+ {a="%.k", b="ک"},
+ {a="%.n", b="ں"},
+ {a="%^d", b="ڊ"}
+}
+
+single = {
+ {a="b", b="ب"},
+ {a="t", b="ت"},
+ {a="j", b="ج"},
+ {a="x", b="خ"},
+ {a="d", b="د"},
+ {a="r", b="ر"},
+ {a="z", b="ز"},
+ {a="s", b="س"},
+ {a="f", b="ف"},
+ {a="`", b="ع"},
+ {a="f", b="ف"},
+ {a="q", b="ق"},
+ {a="k", b="ك"},
+ {a="l", b="ل"},
+ {a="m", b="م"},
+ {a="n", b="ن"},
+ {a="h", b="ه"},
+ {a="w", b="و"},
+ {a="y", b="ي"},
+ {a="T", b="ة"},
+ -- additional characters (begin)
+ {a="p", b="پ"},
+ {a="v", b="ڤ"},
+ {a="g", b="گ"},
+ -- additional characters (end)
+ {a="\"$", b="ْ"},
+ {a="\"(%W)", b="ْ%1"},
+ {a="\"([^uaiUAI])", b="ْ%1"},
+ {a="o", b="ْ"}, -- hard-coded sukūn
+ {a="([^0-9])%-([^0-9])", b="%1%2"},
+ {a="B", b="ـ"}
+}
+
+longv = {
+ {a="\"A", b="ا"},
+ {a="\"U", b="و"},
+ {a="\"I", b="ي"},
+ {a="\"Y", b="ى"},
+ {a="A", b="َا"},
+ {a="U", b="ُو"},
+ {a="I", b="ِي"},
+ {a="aY", b="aى"},
+ {a="iY", b="iى"},
+ {a="Y", b="aى"}
+}
+
+shortv = {
+ {a="\"u", b=""},
+ {a="\"a", b=""},
+ {a="\"i", b=""},
+ {a="%-?%.u", b="ُ"},
+ {a="%-?%.a", b="َ"},
+ {a="%-?%.i", b="ِ"},
+ {a="u", b="ُ"},
+ {a="a", b="َ"},
+ {a="i", b="ِ"}
+}
+
+punctuation = {
+ {a="%(%(", b="﴿"},
+ {a="%)%)", b="﴾"},
+ {a="%(", b="+@("},
+ {a="%)", b="-@("},
+ {a="%+%@%(", b=")"},
+ {a="%-%@%(", b="("},
+ {a="%<", b="+@<"},
+ {a="%>", b="-@<"},
+ {a="%+%@%<", b=">"},
+ {a="%-%@%<", b="<"},
+ {a="%[", b="+@["},
+ {a="%]", b="-@["},
+ {a="%+%@%[", b="]"},
+ {a="%-%@%[", b="["},
+ {a="%.", b="."},
+ -- replaced with the next two rules to make the Arabic comma work
+ -- after \abraces{}
+-- {a="([^0-9])%,", b="%1،"},
+ {a="%,", b="،"},
+ {a="([%d])%،", b="%1,"},
+ {a="%?", b="؟"},
+ {a="%;", b="؛"},
+}
+
+null = {
+ {a="%|", b=""},
+ {a="^%-", b=""},
+ {a="([^0-9])(%-)", b="%1"},
+ {a="O[%S]-O", b=""},
+ {a="[%^%_](.)", b=">??<%1"}
+}
diff --git a/macros/luatex/latex/arabluatex/samples/al-Jahiz.pdf b/macros/luatex/latex/arabluatex/samples/al-Jahiz.pdf
new file mode 100644
index 0000000000..b12a86dd1c
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/samples/al-Jahiz.pdf
Binary files differ
diff --git a/macros/luatex/latex/arabluatex/samples/al-Jahiz.tex b/macros/luatex/latex/arabluatex/samples/al-Jahiz.tex
new file mode 100644
index 0000000000..e83b795cbd
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/samples/al-Jahiz.tex
@@ -0,0 +1,178 @@
+%
+% This file is public domain
+% To compile this document, do:
+% 'lualatex --shell-escape al-Jahiz'
+%
+\documentclass[fontsize=12pt, paper=letter, DIV=classic]{scrartcl}
+\usepackage{fontspec}
+\setmainfont{Old Standard}
+\usepackage{newunicodechar}
+\newunicodechar{ǧ}{ǧ} % Old Standard does include ǧ/Ǧ
+\newunicodechar{Ǧ}{Ǧ} %
+\usepackage{filecontents}
+
+\usepackage{xcolor}
+\usepackage[outputdir=TMP]{minted}
+\definecolor{bg}{rgb}{0.95,0.95,0.95}
+\usepackage{ccicons}
+
+\usepackage{lineno}
+\usepackage{setspace}
+\onehalfspacing
+
+\usepackage{csquotes}
+\DeclareQuoteStyle{arabic}
+{\rmfamily\textquotedblright}{\rmfamily\textquotedblleft}
+{\rmfamily\textquoteright}{\rmfamily\textquoteleft}
+
+\usepackage[fullvoc]{arabluatex}
+\SetArbEasy
+
+\PassOptionsToPackage{pdfa}{hyperref}
+\usepackage{hyperxmp}
+\usepackage{hyperref}
+\hypersetup{colorlinks, linkcolor=blue, pdfauthor={Robert Alessi}}
+
+\begin{document}
+\begin{filecontents*}{dajaja.tex}
+\begin{linenumbers*}
+ \begin{arab}
+ kAna \uc{'a}bU 'l-\uc{h}u_dayli 'ahd_A 'il_A \uc{m}uwaysiN
+ dajAjaTaN. wa-kAnat dajAjatu-hu 'llatI 'ahdA-hA dUna mA kAna
+ yuttaxa_du li-\uc{m}uwaysiN. wa-l_akinna-hu bi-karami-hi
+ wa-bi-.husni _hu\-luqi-hi 'a.zhara 'l-ta`ajjuba min simani-hA
+ wa-.tIbi la.hmi-hA. wa-kAna <\uc{'a}bU 'l-\uc{h}u_dayli>
+ yu`rafu bi-'l-'imsAki 'l-^sadIdi. fa-qAla: \enquote{wa-kayfa
+ ra'ayta yA \uc{'a}bA \uc{`i}mrAna tilka 'l-dajA\-jaTa?}
+ qAla: \enquote{kAnat `ajabaN mina 'l-`ajabi!} fa-yaqUlu:
+ \enquote{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?} 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 \uc{'a}bU
+ 'l-\uc{h}u_dayli.
+ \end{arab}
+
+\begin{arab}
+ wa-kAna \uc{'a}bU 'l-\uc{h}u_dayli 'aslama 'l-nAsi .sadraN
+ wa-'awsa`a-hum _huluqaN wa-'ashala-hum suhUlaTaN. fa-'in _dakarUA
+ dajAjaTaN, qAla: \enquote{'ayna kAnat yA \uc{'a}bA \uc{`i}mrAna
+ min tilka 'l-dajA\-jaTi?} fa-'in _dakarUA ba.t.taTaN 'aw `anAqaN
+ 'aw jazUraN 'aw baqaraTaN, qAla: \enquote{fa-'ayna kAnat h_a_dihi
+ 'l-jazUru fI 'l-juzuri min tilka 'l-dajAjaTi fI 'l-dajAji!}
+ wa-'ini istasmana \uc{'a}bU 'l-\uc{h}u_dayli ^say'aN mina
+ 'l-.tayri wa-'l-bahA'imi, qAla: \enquote{lA wa-'l-l_ahi wa-lA tilka
+ 'l-dajAjaTu!} wa-'in _dakarUA `u_dUbaTa 'l-^sa.hmi, qAla:
+ \enquote{`u_dUbaTu 'l-^sa.hmi fI 'l-baqari wa-'l-ba.t.ti wa-bu.tUni
+ 'l-samaki wa-'l-dajAji, wa-lA siyyamA _d_alika 'l-jinsu mina
+ 'l-dajAji.} wa-'in _dakarUA mIlAda ^say'iN 'aw qudUma
+ 'insAniN, qAla: \enquote{kAna _d_alika ba`da 'an 'ahdaytu-hA la-ka
+ bi-sanaTiN, wa-mA kAna bayna qudUmi fulAniN wa-bayna 'l-ba`_taTi
+ bi-tilka 'l-dajAjaTi 'illA yawmuN.} wa-kAnat ma_ta\-laN fI
+ kulli ^say'iN wa-tArI_haN fI kulli ^say'iN.
+\end{arab}
+\end{linenumbers*}
+
+\bigskip
+
+\begin{arab}
+ \uc{al-jA.hi.zu}, \aemph{\uc{k}itAbu 'l-\uc{b}u_halA'i}
+\end{arab}
+\end{filecontents*}
+
+\title{\large\arb{dajAjaTu \uc{'a}bI 'l-\uc{h}u_dayli
+ 'l-\uc{`a}llAfi}}
+\author{}
+\date{}
+
+\titlehead{\textbf{\textsf{arabluatex sample file}} --- \cczero\ This
+ file is public domain.\\
+ \textsf{arabluatex} mode: \texttt{fullvoc} with
+ \texttt{\textbackslash SetArbEasy}\\
+ Full vocalization, the \arb[trans]{sukUn} and the
+ \arb[trans]{wa.slaT} are expressed, the \arb[trans]{ta^sdId} is
+ generated, but the \enquote*{classic} \arb[trans]{maddaT} is
+ discarded (see source code on p.~\pageref{source}).}
+\maketitle
+\vspace{-1in}
+\doublespacing
+\setquotestyle{arabic}
+\input{dajaja}
+
+\makeatletter
+\def\al@mode{trans}
+\makeatother
+\SetTranslitConvention{dmg}
+\titlehead{\textsf{arabluatex} mode: \texttt{trans} with
+ \texttt{\textbackslash SetTranslitConvention\{dmg\}} and
+ \texttt{\textbackslash SetArbEasy}\\
+\emph{Deutsche Morgenländische Gesellschaft} (see source code on
+p.~\pageref{source})}
+\onehalfspacing
+\maketitle
+\vspace{-1in}
+\setquotestyle{english}
+\input{dajaja}
+
+\makeatletter
+\def\al@mode{trans}
+\makeatother
+\SetTranslitConvention{loc}
+\titlehead{\textsf{arabluatex} mode: \texttt{trans} with
+ \texttt{\textbackslash SetTranslitConvention\{loc\}}\\
+\emph{Library of Congress} (see source code on p.~\pageref{source})}
+\maketitle
+\vspace{-1in}
+\setquotestyle{english}
+\input{dajaja}
+
+\makeatletter
+\def\al@mode{trans}
+\makeatother
+\SetTranslitConvention{arabica}
+\titlehead{\textsf{arabluatex} mode: \texttt{trans} with
+ \texttt{\textbackslash SetTranslitConvention\{arabica\}}\\
+\emph{Journal of Arabic and Islamic Studies} (Arabica, see source code
+on p.~\pageref{source})}
+\maketitle
+\vspace{-1in}
+\setquotestyle{english}
+\input{dajaja}
+
+\makeatletter
+\def\al@mode{voc}
+\makeatother
+\singlespacing
+\SetTranslitConvention{dmg}
+\titlehead{}
+\title{\large Source code}
+\subtitle{}
+\maketitle
+\vspace{-1in}
+
+\phantomsection\label{source}
+Here follows the exact source code that has been used to produce the
+above presented outputs. Discretionary hyphens
+(\mintinline{latex}|\-|) may have been inserted at some points to
+prevent lines from overflowing into the right margin.
+
+\medskip
+
+\noindent\textbf{\texttt{preamble:}}
+\begin{minted}[linenos, bgcolor=bg]{latex}
+\usepackage{csquotes} % recommended for inline quotations
+\DeclareQuoteStyle{arabic} % then \setquotestyle{arabic} or
+ % \setquotestyle{english} may be used
+ {\rmfamily\textquotedblright}{\rmfamily\textquotedblleft}
+ {\rmfamily\textquoteright}{\rmfamily\textquoteleft}
+
+\usepackage[fullvoc]{arabluatex} % 'voc', 'fullvoc', 'novoc' or 'trans'
+\SetTranslitConvention{dmg} % 'dmg', 'loc' or 'arabica'
+\SetArbEasy % ie. discard 'classic' maddah
+
+\title{\arb{dajAjaTu \uc{'a}bI 'l-\uc{h}u_dayli 'l-\uc{`a}llAfi}}
+\end{minted}
+\textbf{\texttt{document:}}
+\inputminted[linenos, firstnumber=last, bgcolor=bg]{latex}{TMP/dajaja.tex}
+
+\end{document}
diff --git a/macros/luatex/latex/arabluatex/samples/exporting.pdf b/macros/luatex/latex/arabluatex/samples/exporting.pdf
new file mode 100644
index 0000000000..aff9bb76e2
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/samples/exporting.pdf
Binary files differ
diff --git a/macros/luatex/latex/arabluatex/samples/exporting.tex b/macros/luatex/latex/arabluatex/samples/exporting.tex
new file mode 100644
index 0000000000..7f22c2c098
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/samples/exporting.tex
@@ -0,0 +1,206 @@
+\RequirePackage{filecontents}
+%
+% This file is public domain
+%
+\begin{filecontents*}{exporting-preamble.tex}
+\documentclass[12pt]{article}
+
+\usepackage[fullvoc,export=false]{arabluatex}
+\SetArbEasy
+
+\usepackage{csquotes}
+\DeclareQuoteStyle{arabic}
+{\textquotedblright}{\textquotedblleft}
+{\textquoteright}{\textquoteleft}
+
+% \renewcommand{\txarb}[1]{#1}
+% \renewcommand{\txtrans}[1]{\emph{#1}}
+% \newcommand{\aemph}[1]{#1}
+% \renewcommand{\arbup}[1]{\textsuperscript{#1}}
+\end{filecontents*}
+\begin{filecontents*}{exporting-dajaja.tex}
+\begin{arabexport}
+\section*{Unicode Arabic}
+\setquotestyle{arabic}
+\begin{arab}
+ kAna \uc{'a}bU 'l-\uc{h}u_dayli 'ahd_A 'il_A
+ \uc{m}uwaysiN dajAjaTaN. wa-kAnat dajAjatu-hu 'llatI
+ 'ahdA-hA dUna mA kAna yuttaxa_du
+ li-\uc{m}uwaysiN. wa-l_akinna-hu bi-karami-hi
+ wa-bi-.husni _hu\-luqi-hi 'a.zhara 'l-ta`ajjuba min
+ simani-hA wa-.tIbi la.hmi-hA. wa-kAna <\uc{'a}bU
+ 'l-\uc{h}u_dayli> yu`rafu bi-'l-'imsAki
+ 'l-^sadIdi. fa-qAla: \enquote{wa-kayfa ra'ayta yA
+ \uc{'a}bA \uc{`i}mrAna tilka 'l-dajA\-jaTa?} qAla:
+ \enquote{kAnat `ajabaN mina 'l-`ajabi!} fa-yaqUlu:
+ \enquote{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?}
+ 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 \uc{'a}bU
+ 'l-\uc{h}u_dayli.
+\end{arab}
+
+\begin{arab}
+ wa-kAna \uc{'a}bU 'l-\uc{h}u_dayli 'aslama 'l-nAsi
+ .sadraN wa-'awsa`a-hum _huluqaN wa-'ashala-hum
+ suhUlaTaN. fa-'in _dakarUA dajAjaTaN, qAla:
+ \enquote{'ayna kAnat yA \uc{'a}bA \uc{`i}mrAna min
+ tilka 'l-dajA\-jaTi?} fa-'in _dakarUA ba.t.taTaN 'aw
+ `anAqaN 'aw jazUraN 'aw baqaraTaN, qAla:
+ \enquote{fa-'ayna kAnat h_a_dihi 'l-jazUru fI 'l-juzuri
+ min tilka 'l-dajAjaTi fI 'l-dajAji!} wa-'ini
+ istasmana \uc{'a}bU 'l-\uc{h}u_dayli ^say'aN mina
+ 'l-.tayri wa-'l-bahA'imi, qAla: \enquote{lA wa-'l-l_ahi
+ wa-lA tilka 'l-dajAjaTu!} wa-'in _dakarUA `u_dUbaTa
+ 'l-^sa.hmi, qAla: \enquote{`u_dUbaTu 'l-^sa.hmi fI
+ 'l-baqari wa-'l-ba.t.ti wa-bu.tUni 'l-samaki
+ wa-'l-dajAji, wa-lA siyyamA _d_alika 'l-jinsu mina
+ 'l-dajAji.} wa-'in _dakarUA mIlAda ^say'iN 'aw
+ qudUma 'insAniN, qAla: \enquote{kAna _d_alika ba`da 'an
+ 'ahdaytu-hA la-ka bi-sanaTiN, wa-mA kAna bayna qudUmi
+ fulAniN wa-bayna 'l-ba`_taTi bi-tilka 'l-dajAjaTi
+ 'illA yawmuN.} wa-kAnat ma_ta\-laN fI kulli ^say'iN
+ wa-tArI_haN fI kulli ^say'iN.
+\end{arab}
+
+\bigskip
+
+\begin{arab}
+ \uc{al-jA.hi.zu}, \aemph{\uc{k}itAbu 'l-\uc{b}u_halA'i}
+\end{arab}
+
+\section*{Romanized Arabic}
+\setquotestyle{english}
+\begin{arab}[trans]
+ kAna \uc{'a}bU 'l-\uc{h}u_dayli 'ahd_A 'il_A
+ \uc{m}uwaysiN dajAjaTaN. wa-kAnat dajAjatu-hu 'llatI
+ 'ahdA-hA dUna mA kAna yuttaxa_du
+ li-\uc{m}uwaysiN. wa-l_akinna-hu bi-karami-hi
+ wa-bi-.husni _hu\-luqi-hi 'a.zhara 'l-ta`ajjuba min
+ simani-hA wa-.tIbi la.hmi-hA. wa-kAna <\uc{'a}bU
+ 'l-\uc{h}u_dayli> yu`rafu bi-'l-'imsAki
+ 'l-^sadIdi. fa-qAla: \enquote{wa-kayfa ra'ayta yA
+ \uc{'a}bA \uc{`i}mrAna tilka 'l-dajA\-jaTa?} qAla:
+ \enquote{kAnat `ajabaN mina 'l-`ajabi!} fa-yaqUlu:
+ \enquote{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?}
+ 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 \uc{'a}bU
+ 'l-\uc{h}u_dayli.
+\end{arab}
+
+\begin{arab}[trans]
+ wa-kAna \uc{'a}bU 'l-\uc{h}u_dayli 'aslama 'l-nAsi
+ .sadraN wa-'awsa`a-hum _huluqaN wa-'ashala-hum
+ suhUlaTaN. fa-'in _dakarUA dajAjaTaN, qAla:
+ \enquote{'ayna kAnat yA \uc{'a}bA \uc{`i}mrAna min
+ tilka 'l-dajA\-jaTi?} fa-'in _dakarUA ba.t.taTaN 'aw
+ `anAqaN 'aw jazUraN 'aw baqaraTaN, qAla:
+ \enquote{fa-'ayna kAnat h_a_dihi 'l-jazUru fI 'l-juzuri
+ min tilka 'l-dajAjaTi fI 'l-dajAji!} wa-'ini
+ istasmana \uc{'a}bU 'l-\uc{h}u_dayli ^say'aN mina
+ 'l-.tayri wa-'l-bahA'imi, qAla: \enquote{lA wa-'l-l_ahi
+ wa-lA tilka 'l-dajAjaTu!} wa-'in _dakarUA `u_dUbaTa
+ 'l-^sa.hmi, qAla: \enquote{`u_dUbaTu 'l-^sa.hmi fI
+ 'l-baqari wa-'l-ba.t.ti wa-bu.tUni 'l-samaki
+ wa-'l-dajAji, wa-lA siyyamA _d_alika 'l-jinsu mina
+ 'l-dajAji.} wa-'in _dakarUA mIlAda ^say'iN 'aw qudUma
+ 'insAniN, qAla: \enquote{kAna _d_alika ba`da 'an
+ 'ahdaytu-hA la-ka bi-sanaTiN, wa-mA kAna bayna qudUmi
+ fulAniN wa-bayna 'l-ba`_taTi bi-tilka 'l-dajAjaTi
+ 'illA yawmuN.} wa-kAnat ma_ta\-laN fI kulli ^say'iN
+ wa-tArI_haN fI kulli ^say'iN.
+\end{arab}
+
+\bigskip
+
+\begin{arab}[trans]
+ \uc{al-jA.hi.zu}, \aemph{\uc{k}itAbu 'l-\uc{b}u_halA'i}
+\end{arab}
+\end{arabexport}
+\end{filecontents*}
+\documentclass[12pt]{article}
+
+\usepackage[fullvoc,export=false]{arabluatex}
+\SetArbEasy
+
+\usepackage{csquotes}
+\DeclareQuoteStyle{arabic}
+{\textquotedblright}{\textquotedblleft}
+{\textquoteright}{\textquoteleft}
+
+\PassOptionsToPackage{pdfa}{hyperref}
+\usepackage{hyperxmp}
+\usepackage{hyperref}
+\hypersetup{colorlinks, linkcolor=blue, pdfauthor={Robert
+ Alessi}}
+
+\title{\large Exporting Unicode Arabic to an external
+ .tex source file}
+\author{}
+\date{}
+
+\usepackage{xcolor}
+\usepackage[outputdir=TMP]{minted}
+\definecolor{bg}{rgb}{0.95,0.95,0.95}
+
+\usepackage{ccicons}
+\usepackage{paralist}
+
+% \renewcommand{\txarb}[1]{#1}
+% \renewcommand{\txtrans}[1]{\emph{#1}}
+% \renewcommand{\aemph}[1]{#1}
+% \renewcommand{\arbup}[1]{\textsuperscript{#1}}
+
+\begin{document}
+\vspace*{-.5in}
+\noindent
+\textbf{\textsf{arabluatex sample file}} --- \cczero\ This
+file is public domain
+
+\begin{compactenum}
+\item Copy the source code below, paste it into your
+ favorite tex editor and save it as
+ \verb|exporting.tex|.
+\item In the preamble, set \verb|export=true| in
+ \textsf{arabluatex} global options (line 3).
+\item Compile this file with Lua\LaTeX.
+\item Open \verb|exporting_out.tex| and compile it again
+ with Lua\LaTeX.
+\item Open \verb|exporting_out_out.tex|, then:
+ \begin{compactenum}
+ \item In the preamble, set \verb|export=false| in
+ \textsf{arabluatex} global options (line 3).
+ \item Compile this file and see the resulting
+ \verb|exporting_out_out.pdf|.
+ \end{compactenum}
+\item Finally, uncomment in the preamble the four lines
+ that are just above \verb|\begin{document}|.
+\item Open a terminal, then do:
+\begin{verbatim}
+pandoc exporting_out_out.tex -s -o exporting.odt
+\end{verbatim}
+ and open the resulting \verb|exporting.odt| file with LibreOffice.
+\end{compactenum}
+
+\phantomsection
+\section*{Source code}
+\label{ref:source-begin}
+\inputminted[firstnumber=last, bgcolor=bg]{latex}%
+ {TMP/exporting-preamble.tex}
+
+\begin{minted}[bgcolor=bg]{latex}
+\begin{document}
+\end{minted}
+\inputminted[firstnumber=last, bgcolor=bg]{latex}%
+ {TMP/exporting-dajaja.tex}
+\begin{minted}[bgcolor=bg]{latex}
+\end{document}
+\end{minted}
+\label{ref:source-end}
+
+\end{document}
diff --git a/macros/luatex/latex/arabluatex/samples/template-01.pdf b/macros/luatex/latex/arabluatex/samples/template-01.pdf
new file mode 100644
index 0000000000..b72fa71008
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/samples/template-01.pdf
Binary files differ
diff --git a/macros/luatex/latex/arabluatex/samples/template-01.tex b/macros/luatex/latex/arabluatex/samples/template-01.tex
new file mode 100644
index 0000000000..1a5ea4f8af
--- /dev/null
+++ b/macros/luatex/latex/arabluatex/samples/template-01.tex
@@ -0,0 +1,109 @@
+\documentclass[paper=letter, DIV=classic, headings=small]{scrartcl}
+
+\usepackage{ccicons}
+\usepackage{paralist}
+
+\usepackage{arabluatex}
+
+\usepackage{hyperref}
+\hypersetup{colorlinks, linkcolor=blue, breaklinks}
+
+\subject{\textsf{arabluatex} sample files}
+\title{The Basics}
+\author{Robert Alessi\thanks{\cczero\ This file is public domain.}}
+
+\begin{document}
+\maketitle
+
+\begin{abstract}
+ This file demonstrates the basic features of \texttt{arabluatex}.
+\end{abstract}
+
+\section{The less, the better}
+\label{sec:less-better}
+\textsf{arabluatex} is loaded by one single line in the preamble:
+\begin{verbatim}
+\usepackage{arabluatex}
+\end{verbatim}
+That said, there are two subsequent requirements:
+\begin{compactenum}
+\item An Arabic font: \textsf{arabluatex} tries to load the
+ \textsf{Amiri} Arabic font which is already part of
+ \textsf{texlive}.
+\item A Roman font that has all the characters that are needed for
+ the transliteration of the Arabic.
+\end{compactenum}
+
+Once these requirements are met, one may insert Arabic words in
+left-to-right paragraphs like so: \verb|\arb{da_hala mubtasimaN}|,
+\arb{da_hala mubtasimaN}. Or insert running paragraphs of Arabic text
+inside the \verb|arab| environment, like so:---
+\begin{verbatim}
+\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: sawfa 'u`Idu-hu 'ilay-ka fI
+ 'l-masA'-i wa-'adfa`u la-ka 'ujraTaN. fa-qAla ju.hA: '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: 'innI 'asma`u .himAra-ka yA ju.hA yanhaqu. fa-qAla la-hu
+ ju.hA: .garIbuN 'amru-ka yA .sadIqI 'a-tu.saddiqu 'l-.himAr-a
+ wa-tuka_d_diba-nI?
+\end{arab}
+\end{verbatim}
+\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: sawfa 'u`Idu-hu 'ilay-ka fI
+ 'l-masA'-i wa-'adfa`u la-ka 'ujraTaN. fa-qAla ju.hA: '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: 'innI 'asma`u .himAra-ka yA ju.hA yanhaqu. fa-qAla la-hu
+ ju.hA: .garIbuN 'amru-ka yA .sadIqI 'a-tu.saddiqu 'l-.himAr-a
+ wa-tuka_d_diba-nI?
+\end{arab}
+
+\section{Options}
+\label{sec:options}
+\textsf{arabluatex} may be loaded with four mutually exclusive options:---
+\begin{compactdesc}
+\item[voc] To have every short vowel written. This option is loaded by
+ default.
+\item[fullvoc] To have the \arb[trans]{sukUn} and the
+ \arb[trans]{wa.slaT} expressed in addition to what \verb|voc|
+ already does.
+\item[novoc] To have all the diacritics discarded.
+\item[trans] To have the Arabic transliterated into one of the
+ accepted standards.
+\end{compactdesc}
+\begin{verbatim}
+% <preamble>
+\usepackage{arabluatex} % this loads 'voc' by default
+\usepackage[voc]{arabluatex}
+\usepackage[fullvoc]{arabluatex}
+\usepackage[novoc]{arabluatex}
+\usepackage[trans]{arabluatex}
+\end{verbatim}
+
+At any point of the document, any mode can be set locally, like so:---
+\begin{verbatim}
+English paragraph: To have the \arb[trans]{sukUn} and the
+ \arb[trans]{wa.slaT} expressed...
+
+\begin{arab}[trans] % Arabic paragraph
+ 'at_A .sadIquN 'il_A \uc{j}u.hA ya.tlubu min-hu .himAra-hu
+ li-yarkaba-hu fI safraTiN qa.sIraTiN fa-qAla la-hu: sawfa 'u`Idu-hu
+ 'ilay-ka fI 'l-masA'-i wa-'adfa`u la-ka 'ujraTaN.
+\end{arab}
+\end{verbatim}
+
+English paragraph: To have the \arb[trans]{sukUn} and the
+ \arb[trans]{wa.slaT} expressed...
+
+\begin{arab}[trans] % Arabic paragraph
+ 'at_A .sadIquN 'il_A \uc{j}u.hA ya.tlubu min-hu .himAra-hu
+ li-yarkaba-hu fI safraTiN qa.sIraTiN fa-qAla la-hu: sawfa 'u`Idu-hu
+ 'ilay-ka fI 'l-masA'-i wa-'adfa`u la-ka 'ujraTaN.
+\end{arab}
+
+\end{document}