documentation updated. a few arbnull rules were needed in voc and fullvoc

3 files changed, 303 insertions, 4 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 6fb2993..89d0e51 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -2467,6 +2467,7 @@ word that \cs{arbnull} is applied to.
 % \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
@@ -2560,10 +2561,298 @@ word that \cs{arbnull} is applied to.
 %</example>
 % \fi
 %
-% \paragraph{Color}\NEWfeature{v1.12} this:
-% \begin{arab}[trans]
-%   daxal\arbcolor[red]{tu} mub\arbcolor[blue]{ta}si\arbcolor[green]{maN}
-% \end{arab}
+% \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{arabluacode}
+  \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{arabluacode}
+% \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 rendered inside or just after \cs{arbcolor}.
+% 
+% \begin{longtable}{lllll}
+% \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| \\
+% \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| \\
+% \bottomrule
+% \caption*{\Cref*{tab:arbcolor-diacritics}: Arab\TeX\ diacritics
+% for \cs{arbcolor}}
+% \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}|
+%   |'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{arabluacode}
+  \newarbmark{Y}{^^^^0649}{}
+  \arb{hud\arbcolor[red]{aN\arbnull{_A}}\arbmark{Y}}
+  \arb[trans]{hud\arbcolor[red]{aN\arbnull{_A}}\arbmark{Y}}
+\end{arabluacode}
+% \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.}.
+%   
+%   |\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{arabluacode}
+  \newarbmark{alifmaddahred}{^^^^0627\arbcolor[red]{^^^^0653}}%
+  {\arb[trans]{\arbcolor[red]{'a'\arbnull{k}}}}
+  \arb{\arbmark{alifmaddahred}kulu}
+  \arb[trans]{\arbmark{alifmaddahred}kulu}.
+\end{arabluacode}
+% \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{arabluacode}
+\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{arabluacode}
+% \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
@@ -2842,6 +3131,7 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu
 % 
 % \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
diff --git a/arabluatex_fullvoc.lua b/arabluatex_fullvoc.lua
index 6353f30..fb823fa 100644
--- a/arabluatex_fullvoc.lua
+++ b/arabluatex_fullvoc.lua
@@ -68,7 +68,9 @@ hamzafv = {
    {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"},
@@ -194,8 +196,10 @@ hamzafveasy = { -- differences marked below with 'easy'
    {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"},
diff --git a/arabluatex_voc.lua b/arabluatex_voc.lua
index e547f6b..16ddd55 100644
--- a/arabluatex_voc.lua
+++ b/arabluatex_voc.lua
@@ -211,7 +211,9 @@ hamza = {
    {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"},
@@ -328,8 +330,10 @@ hamzaeasy = { -- differences marked below with 'easy'
    {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"},
@@ -886,6 +890,7 @@ punctuation = {
 
 null = {
    {a="%|", b=""},
+   {a="^%-", b=""},
    {a="([^0-9])(%-)", b="%1"},
    {a="O[%S]-O", b=""},
    {a="[%^%_](.)", b=">??<%1"}