From 5bd9eac901f39afa94b7cf57ac43f3faf223fb77 Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Sat, 23 Jun 2018 16:00:13 +0200 Subject: documentation updated. a few arbnull rules were needed in voc and fullvoc --- arabluatex.dtx | 298 ++++++++++++++++++++++++++++++++++++++++++++++++- arabluatex_fullvoc.lua | 4 + arabluatex_voc.lua | 5 + 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. % % \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 +% +% \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 +% +% \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 +% +% \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 +% +% \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"} -- cgit v1.2.3