started documenting \arbmark{}; one superfluous rule (hamza + aN + ʾidġām) had to go

2 files changed, 57 insertions, 21 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 09b38e4..7bb8c5a 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -1295,7 +1295,7 @@ vowels (see §~3).
 %   \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 may be used to prevent this rule from
+%   \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}
@@ -1787,7 +1787,7 @@ vowels (see §~3).
 % \end{compactenum}
 %
 % \paragraph{\texttt{fullvoc}}
-% In this mode, \enquote{quoting} may be used to take away any short
+% 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}
@@ -1949,7 +1949,7 @@ word that \cs{arbnull} is applied to.
 % \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 may be used to a modest extent,
+% 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}
@@ -2263,12 +2263,12 @@ word that \cs{arbnull} is applied to.
 % \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 may also be used for the same effect. However, it must be
+% 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 may be used to have the lines 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.
@@ -2411,6 +2411,36 @@ word that \cs{arbnull} is applied to.
 %</example>
 % \fi
 %
+% \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
+% \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
+% 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}}
+% \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} \\
+% \bottomrule
+% \caption*{\Cref*{tab:arabtex-additional-marks}: Additional Arabic
+% marks}
+% \end{longtable}
+% 
 % \section{Transliteration}
 % \label{sec:transliteration}
 % It may be more appropriate to speak of \enquote{romanization} than
@@ -2475,7 +2505,7 @@ word that \cs{arbnull} is applied to.
 % 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 may be used for rendering transliterated text:---
+% Plus} font can be used for rendering transliterated text:---
 % \iffalse
 %<*example>
 % \fi
@@ -2618,7 +2648,7 @@ Then as \Hunayn, \Razi.
 % any point of the document.
 %
 % \DescribeMacro{\SetArbUp} Finally, \cs{SetArbUp}\marg{formatting
-% directives} may be used to customize the way \arb[trans]{'i`rAb} is
+% 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
@@ -3019,7 +3049,7 @@ al-muqAtil-Ina.}, wa-kAnat 'ummI min `u.zamA'-i buyUt-i
 % 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} may be used to insert English
+% text. For example, \cs{LRfootnote} can be used to insert English
 % footnotes in running Arabic text:---
 % \iffalse
 %<*example>
@@ -3058,7 +3088,7 @@ part of the predicate\ldots} "ibn-u \uc{`a}mr-iNU}
 % general principle laid \vpageref{ref:cmd-inside-arabic} applies.
 %
 % \DescribeMacro{\setRL} \DescribeMacro{\setLR} \cs{setRL} and
-% \cs{setLR} may be used to change the direction of paragraphs, either
+% \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
@@ -3093,7 +3123,7 @@ qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a...
 % command |\fvarabic| itself can see it.
 %
 % \DescribeMacro{\MkArbBreak} The \cs{MkArbBreak}\marg{csv list of
-% commands} command may be used in the preamble to give any
+% commands} command can be used in the preamble to give any
 % \emph{single-argument} command---either new or already
 % existing---the precedence over \package{arabluatex} inside Arabic
 % environments. It takes as argument a comma-separated list of
@@ -3181,7 +3211,7 @@ qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a...
 % \package{paralist}.
 %
 % To take a first example, should one wish to typeset a list of
-% manuscripts, the |description| environment may be used like so:---
+% manuscripts, the |description| environment can be used like so:---
 % \iffalse
 %<*example>
 % \fi
@@ -3245,7 +3275,7 @@ qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a...
 % \fi%
 % This option will prevent \package{babel-french} from interfering
 % with the layout of the document. Then the package \package{paralist}
-% may be used to make the lists \enquote*{compact} as
+% can be used to make the lists \enquote*{compact} as
 % \package{babel-french} do.
 %
 % \subsection{\package{csquotes}}
@@ -3517,7 +3547,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 % \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 may be used
+% 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.
@@ -3546,7 +3576,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\SetInputScheme}
-%   \changes{v1.4}{2016/07/05}{\cs{SetInputScheme} may be used to
+%   \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
@@ -3616,7 +3646,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\SetTranslitConvention}
-%   \cs{SetTranslitConvention}\marg{convention} may be used to change
+%   \cs{SetTranslitConvention}\marg{convention} can be used to change
 %   the transliteration convention, which is |dmg| by default:
 %    \begin{macrocode}
 \def\al@trans@convention{dmg}
@@ -3635,7 +3665,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 %   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} may be used to customize the way
+%   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}.
@@ -3659,7 +3689,7 @@ wa-ya.sIru ta.hta 'l-jild-i
   {\luadirect{tex.sprint(uc(\luastringN{#1}))}}
 %    \end{macrocode}
 % \end{macro}
-% \begin{macro}{\Uc} \cs{uc} may be used safely in all of the modes
+% \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
@@ -3744,9 +3774,9 @@ wa-ya.sIru ta.hta 'l-jild-i
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\arbmark}
-% \changes{v1.10.4}{2018/03/29}{New command for inserting additional
+% \changes{v1.11}{2018/03/29}{New command for inserting additional
 % marks in Arabic environments} \cs{arbmark} takes one argument from a
-% list of defined elements. 
+% list of defined elements. This command is coded in Lua.
 %    \begin{macrocode}
 \NewDocumentCommand{\arbmark}{m}{%
   \bgroup%
@@ -3756,6 +3786,12 @@ 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
+% 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{newarbmark(\luastringN{#1}, \luastringN{#2}, \luastringN{#3})}}
@@ -3839,7 +3875,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 %   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 may be used at any
+%   \cs{SetHemistichDelim}\marg{delimiter} command can be used at any
 %   point of the document to change this default setting.
 % \end{macro}
 %    \begin{macrocode}
diff --git a/arabluatex_fullvoc.lua b/arabluatex_fullvoc.lua
index 77d95e3..7b8d410 100644
--- a/arabluatex_fullvoc.lua
+++ b/arabluatex_fullvoc.lua
@@ -307,7 +307,7 @@ tanwinfv = { -- with assimilations (\SetArbDflt*)
    {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="(ء)%-?(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)