done documenting \arbmark{} and \newarbmark{}; updated to v1.11

1 files changed, 83 insertions, 19 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 7bb8c5a..4b88bf9 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -27,7 +27,7 @@
 %<package-info>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package-info>\ProvidesPackage{arabluatex}
 %<*package-info>
-    [2018/02/12 v1.10.3 An ArabTeX-like interface for LuaLaTeX]
+    [2018/03/31 v1.11 An ArabTeX-like interface for LuaLaTeX]
 %</package-info>
 %
 %<*driver>
@@ -155,7 +155,7 @@
 \defaultfontfeatures{RawFeature={+liga}}
 \setmainfont{Old Standard}[SmallCapsFont={Latin Modern Roman Caps},
   RawFeature={+mark;+ccmp;+ss05;+ss06}]
-\usepackage{arabluatex}[2018/02/12]
+\usepackage{arabluatex}[2018/03/31]
 \usepackage[nopar]{quran}
 \usepackage[noindex]{nameauth}
 \usepackage{varioref}
@@ -229,7 +229,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{0}
+% \CheckSum{728}
 %
 % \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
@@ -2141,7 +2141,7 @@ word that \cs{arbnull} is applied to.
 % \DescribeOption{utf} |utf|$=$|true|\verb+|+|false|
 % \hfill\arabluaverb{Default: false}\\ As the preceding one, this
 % named argument does not need a value as it defaults to |true| if it
-% is used. If so, unicode Arabic input is expected in the |arabverse|
+% 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.
 %
@@ -2413,16 +2413,16 @@ word that \cs{arbnull} is applied to.
 %
 % \paragraph{Additional Arabic marks}
 % In addition to common letters, many symbols and ligatures are
-% encoded in the Arabic Unicode standard, such as honorifics
-% consisting of complex ligatures, and annotation signs used in the
+% 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}\marg{shorthand} can be used to insert
-% such characters either in unicode or in romanized Arabic
+% 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:\\
+% at the time of writing:---\\
 % \begin{longtable}{llp{.3\linewidth}p{.3\linewidth}}
 % \captionlistentry{Additional Arabic marks}\\[-1em]
 % \toprule
@@ -2441,6 +2441,70 @@ word that \cs{arbnull} is applied to.
 % marks}
 % \end{longtable}
 % 
+% \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 \arabluaverb{\symbol{"XYZT}} or its plain \TeX\ variant
+% \arabluaverb{\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:
+% \arabluaverb{^^^^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{arabluacode}[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{arabluacode}
+% \iffalse
+%</example>
+% \fi%
+% 
+% The example below provides an implementation of this technique. It
+% may be observed that \cs{textcolor} is used so as to have the marks
+% printed in red:---%
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+  \SetArbDflt*
+  \newarbmark{sly}{\textcolor{red}{^^^^06d6}}{}
+  \newarbmark{jim}{\textcolor{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{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
 % \section{Transliteration}
 % \label{sec:transliteration}
 % It may be more appropriate to speak of \enquote{romanization} than
@@ -2966,16 +3030,16 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu
 % \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
+% 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.
+% have any effect on plain Unicode Arabic for the time being.
 %
-% That said, there are two ways of inserting unicode
+% That said, there are two ways of inserting Unicode
 % Arabic:
 % \begin{compactenum}[(a)] 
-% \item \DescribeMacro{\txarb} The \cs{txarb}\marg{unicode Arabic}
-%   command for inserting unicode Arabic text in paragraphs;
+% \item \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
@@ -3379,7 +3443,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 % 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
+% 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|
@@ -3453,7 +3517,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 %    \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{arabluatex}%
-[2018/02/12 v1.10.3 An ArabTeX-like interface for LuaLaTeX]
+[2018/03/31 v1.11 An ArabTeX-like interface for LuaLaTeX]
 \RequirePackage{ifluatex}
 %    \end{macrocode}
 % \package{arabluatex} requires \LuaLaTeX\ of course. Issue a warning
@@ -3731,7 +3795,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 % \end{macro}
 % \begin{environment}{txarab}
 %   \changes{v1.5}{2016/11/14}{New \texttt{txarab} environment for
-%   typesetting running paragraphs in unicode Arabic} The |txarab|
+%   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}
@@ -3774,7 +3838,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\arbmark}
-% \changes{v1.11}{2018/03/29}{New command for inserting additional
+% \changes{v1.11}{2018/03/31}{New command for inserting additional
 % marks in Arabic environments} \cs{arbmark} takes one argument from a
 % list of defined elements. This command is coded in Lua.
 %    \begin{macrocode}
@@ -3786,7 +3850,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\newarbmark}
-% \changes{v1.11}{2018/03/29}{Allows defining additional sets of Arabic
+% \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