documenting the new features. added \arbcolor[]{} in .el style file

2 files changed, 104 insertions, 59 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 790b13c..3b74ab6 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 % ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
-% Copyright (C) 2016--2018  Robert Alessi
+% Copyright (C) 2016--2018  Robert Alesssi
 %
 % Please send error reports and suggestions for improvements to Robert
 % Alessi <alessi@robertalessi.net>
@@ -74,7 +74,7 @@
   maintainer =   {Hosny, Khaled},
   title =        {Amiri},
   indextitle =   {Amiri},
-  date =         {2015-09-20},
+  date =         {2017-12-13},
   url =          {http://www.amirifont.org/}
 }
 
@@ -163,6 +163,7 @@
 \usepackage{hyperxmp}
 \PassOptionsToPackage{pdfa}{hyperref}
 \usepackage{hypdoc}
+\usepackage{bookmark}
 \usepackage{authblk}
 \hypersetup{unicode=true, colorlinks, allcolors=blue,
   linktocpage=true, pdfauthor={Robert Alessi}, pdftitle={The
@@ -533,7 +534,7 @@
 %   of the \arb[trans]{kasraT} above the consonant may be obtained by
 %   selecting the |ss05| feature of the Amiri font, like
 %   so:---\footnote{See the documentation of \package{amiri},
-%   \textcite[5]{pkg:amiri}.}\\
+%   \textcite[6]{pkg:amiri}.}\\
 %   \arabluaverb{\newfontfamily\arabicfont{Amiri}[Script=Arabic,RawFeature={+ss05}]}
 %
 %   Other Arabic fonts may behave differently.
@@ -1081,19 +1082,19 @@ vowels (see §~3).
 %   \arb[voc]{murU'aTuN} \arb[trans]{murU'aTuN}.
 % \end{quote}
 %
-% \paragraph{\arb[trans]{'alif maq.sUraT}} It is written \meta{\_A} or
-% \meta{Y}:
+% \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{\arb[trans]{'alif} \emph{otiosum}} Said
-% \arb[trans]{'alif-u 'l-wiqAyaT-i}, \enquote{the guarding
-% \arb[trans]{'alif}}\,, after \arb[novoc]{U} at the end of a word, both
-% when preceded by \arb[trans]{.dammaT} and by \arb[trans]{fat.haT} is
-% written \meta{UA} or \meta{aW, aWA}:
+% \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|
@@ -1102,8 +1103,9 @@ vowels (see §~3).
 %   \arb[fullvoc]{banaWA}, \arb[trans]{banaWA}.
 % \end{quote}
 % 
-% \paragraph{\arb[trans]{'alif ma.h_dUfaT} and defective \arb[trans]{U,
-% I}} They are written \meta{\_a, \_i \_u}:
+% \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}.
@@ -1118,7 +1120,8 @@ vowels (see §~3).
 %   \arb[trans]{al-\uc{`A.s_i}}.
 % \end{quote}
 % 
-% \paragraph{Silent \arb[novoc]{U}/\arb[novoc]{I}}
+% \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
@@ -1136,11 +1139,12 @@ vowels (see §~3).
 %   \arb[trans]{al-rib_aIT-u}.
 % \end{quote}
 %
-% \paragraph{\arb[trans]{\uc{`amruNU}}, and the silent
-% \arb[novoc]{U}} 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:
+% \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|
@@ -1159,7 +1163,7 @@ vowels (see §~3).
 %   \arb[trans]{ribaNU}.
 % \end{quote}
 %
-%\paragraph{\arb[trans]{tanwIn}}
+% \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}
@@ -1192,7 +1196,7 @@ vowels (see §~3).
 % \end{quote}
 % 
 % \subsection{Other orthographic signs}
-% \paragraph{\arb[trans]{tA' marbU.taT}}
+% \paragraph{\texorpdfstring{\arb[trans]{tA' marbU.taT}}{tāʾ marbūṭah}}
 % It is written \meta{T}:
 % \begin{quote}
 %   |madInaTuN| \arb[voc]{madInaTuN} \arb[trans]{madInaTuN},
@@ -1200,11 +1204,11 @@ vowels (see §~3).
 %   |madInaTiN| \arb[voc]{madInaTiN} \arb[trans]{madInaTiN}.
 % \end{quote}
 %
-% \paragraph{\arb[trans]{hamzaT}} \label{ref:hamza}It is written
-% \meta{\texttt{'}}, its carrier being determined by contextual
-% analysis. In case one wishes to bypass this mechanism, he can use
-% the \enquote{quoting} feature that is described below in
-% \vref{sec:quoting}.
+% \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}
@@ -1326,14 +1330,14 @@ vowels (see §~3).
 %   \arb[voc]{mi'a|TuN} \arb[trans]{mi'a|TuN}.
 % \end{quote}
 %
-% \paragraph{\arb[trans]{maddaT}} \label{ref:madda}At the beginning of
-% a syllabe, \arb[trans]{'alif} with \arb[trans]{hamzaT} and
-% \arb[trans]{fat.haT} (\arb[voc]{'a}) followed by \arb[trans]{'alifu
-% 'l-maddi} (\arb[trans]{'alif} of prolongation) or \arb[trans]{'alif}
-% with \arb[trans]{hamzaT} and \arb[trans]{jazmaT} (\arb[voc]{a"'"})
-% are both represented in writing \arb[trans]{'alif} with
-% \arb[trans]{maddaT}: \arb[voc]{A"'} \parencite[see][i. 25
-% A--B]{Wright}.
+% \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>
@@ -1363,13 +1367,13 @@ vowels (see §~3).
 %   \arb[voc]{yaxba'Ani} \arb[trans]{yaxba'Ani}.
 % \end{quote}
 %
-% \paragraph{\arb[trans]{^saddaT}}
+% \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:
+% \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|
@@ -1447,7 +1451,9 @@ vowels (see §~3).
 %   grammarians \parencite[see][i. 16 B--C]{Wright}.
 % \end{enumerate}
 %
-% \paragraph{The definite article and the \arb[trans]{'alif-u 'l-wa.sl-i}}
+% \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
@@ -1653,7 +1659,8 @@ vowels (see §~3).
 %   \arb[trans]{li-l-l_ah-i 'l-qA'il-u}.
 % \end{quote}
 %
-% \paragraph{The conjunctive \arb[voc]{alla_dI}}
+% \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
@@ -2414,6 +2421,7 @@ word that \cs{arbnull} is applied to.
 % 
 % \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
@@ -2427,6 +2435,7 @@ word that \cs{arbnull} is applied to.
 % \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
@@ -2551,6 +2560,12 @@ word that \cs{arbnull} is applied to.
 %</example>
 % \fi
 %
+% \paragraph{Color}\NEWfeature{v1.12} this:
+% \begingroup \newfontfamily\arabicfont{FreeSerif}[Script=Arabic]
+% \arb{da_hal"+\arbcolor[red]{+t\arbcolor[blue]{+u}}
+% mub"t+\arbcolor[brown]{+a}s+\arbcolor[blue]{+i\arbcolor[brown]{+maN}}}
+% \endgroup
+%
 % \section{Transliteration}
 % \label{sec:transliteration}
 % It may be more appropriate to speak of \enquote{romanization} than
@@ -2679,7 +2694,7 @@ word that \cs{arbnull} is applied to.
 %   \uc{'l-rAziyyu}}.
 % \end{quote}
 %
-% \paragraph{\enquote*{Long} proper names}
+% \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}
@@ -2778,7 +2793,8 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu
 % with the actual \arb[trans]{tanwIn} in the formatting directives of
 % the \cs{SetArbUp} command.
 %
-% \paragraph{\arb[trans]{'i`rAb} boundaries}
+% \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
@@ -2826,7 +2842,8 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu
 %   'l-nAs-a kAffaT-aN min mu_hA.tabati-hi 'a.had-uN bi-sayyidi-nA}.
 % \end{quoting}
 % 
-% \paragraph{Discarding the \arb[trans]{'i`rAb}}
+% \paragraph{\texorpdfstring{Discar\-ding the
+% \arb[trans]{'i`rAb}}{Discarding the ʾiʿrāb}}
 % 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
@@ -3106,8 +3123,8 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu
 % \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}
-% (\cs{command}\oarg{opt1}\oarg{opt2}\marg{arg}) such as
+% \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}
@@ -3169,11 +3186,13 @@ al-muqAtil-Ina.}, wa-kAnat 'ummI min `u.zamA'-i buyUt-i
 %<*example>
 % \fi
 \begin{arabluacode}
-\arb[fullvoc]{\uc{z}ayd-uN\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} "ibn-u \uc{`a}mr-iNU}
+  \begin{arab}[fullvoc]
+    \uc{z}ayd-uN\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} "ibn-u \uc{`a}mr-iNU
+  \end{arab}
 \end{arabluacode}
 % \iffalse
 %</example>
@@ -3194,9 +3213,10 @@ part of the predicate\ldots} "ibn-u \uc{`a}mr-iNU}
 % the documentation of \package{KOMA-script} for details about the
 % \cs{deffootnotemark} and \cs{deffootnote} commands.}
 %
-% \DescribeMacro{\LRmarginpar} The \cs{LRmarginpar} command does for
-% marginal notes the same as \cs{LRfootnote} does for footnotes. Of
-% course, it is supposed to be used in Arabic environments. Note that
+% \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.
@@ -3247,8 +3267,7 @@ qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a...
 % 
 % 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:---\footnote{See below \vref{sec:textcolor} for
-% more information on two-argument commands.} %
+% fully vocalized Arabic:--- %
 % \iffalse
 %<*example>
 % \fi
@@ -3286,7 +3305,28 @@ qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a...
 % \end{enumerate}
 %
 % \DescribeMacro{\MkArbBreak*}\NEWfeature{v1.12} As said above,
-% \cs{MkArbBreak}
+% \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{arabluacode}[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{arabluacode}
+% \iffalse
+%</example>
+% \fi%
+% 
 %
 % \subsection{Environments}
 % \label{sec:environments}
@@ -3505,10 +3545,10 @@ qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a...
 % \subsection{Two-argument special commands}
 % \label{sec:two-arg-cmds}
 %
-% \paragraph{Color}
+% \paragraph{textcolor}
 % \label{sec:textcolor}
 % The two-argument command
-% \cs{textcolor}\marg{color}\marg{\cs{arb}\oarg{opt}\marg{Arabic
+% \cs{textcolor}\marg{color}\marg{\cs{arb}\oarg{opt}\marg{Ara\-bic
 % text}} is supported inside \cs{begin}|{arab}| \ldots\
 % \cs{end}|{arab}|. One simple example follows:--- %
 % \iffalse
@@ -4170,7 +4210,10 @@ wa-ya.sIru ta.hta 'l-jild-i
 %   inserted in an Arabic environment. It typsets his argument in a
 %   marginal note from left to right.
 %    \begin{macrocode}
-\DeclareDocumentCommand{\LRmarginpar}{m}{\marginpar{\textdir TLT #1}}
+\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
diff --git a/arabluatex.el b/arabluatex.el
index 7325872..4ce1e25 100644
--- a/arabluatex.el
+++ b/arabluatex.el
@@ -69,6 +69,8 @@
     '("arb" [ (TeX-arg-eval completing-read "Mode: "
                             LaTeX-arabluatex-mode-options) ]
       t)
+    '("arbcolor" [ (TeX-arg-eval completing-read "Color: ") ]
+      t)
     "SetHemistichDelim"
     '("bayt" 2)
     "abjad"