done implementing and documenting \arbup

2 files changed, 76 insertions, 9 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 2e3dc7e..4396804 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -27,7 +27,7 @@
 %<package-info>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package-info>\ProvidesPackage{arabluatex}
 %<*package-info>
-    [2016/05/09 v1.2 This is ArabTeX for LuaLaTeX]
+    [2016/05/19 v1.3 This is ArabTeX for LuaLaTeX]
 %</package-info>
 %
 %<*driver>
@@ -136,7 +136,7 @@
 \setmainfont{Libertinus Serif}
 \setsansfont{Libertinus Sans}
 \setmonofont[Scale=.9]{Libertinus Mono}
-\usepackage{arabluatex}[2016/05/09]
+\usepackage{arabluatex}[2016/05/19]
 \usepackage{varioref}
 \usepackage{hypdoc}
 \hypersetup{unicode=true, colorlinks, allcolors=blue,
@@ -189,7 +189,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{316}
+% \CheckSum{0}
 %
 % \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
@@ -903,6 +903,17 @@ consonants, though three of them are also used as vowels
 %   \arb[voc]{^say'iN} \arb[trans]{^say'iN}.
 % \end{quote}
 %
+% In some cases, it may be useful to mark the root form of defective
+% words so as to produce a more accurate transliteration of ending
+% \arb[trans]{tanwIn}. As seen above, \arb[trans]{tanwIn} preceding
+% \arb[novoc]{_A} is written \meta{aN\_A} or \meta{aNY}. Such forms as
+% \arb[voc]{qA.diNI} may likewise be written \meta{iNI}:---
+% \begin{quote}
+%   |al-qA.dI| \arb[voc]{al-qA.dI} \arb[trans]{al-qA.dI}, |qA.diyaN|
+%   \arb[voc]{qA.diyaN} \arb[trans]{qA.diyaN}, |qA.diNI|
+%   \arb[voc]{qA.diNI} \arb[trans]{qA.diNI}.
+% \end{quote}
+% 
 % \subsection{Other orthographic signs}
 % \paragraph{\arb[trans]{tA' marbU.taT}}
 % It is written \meta{T}:
@@ -1759,6 +1770,50 @@ consonants, though three of them are also used as vowels
 % argument of \cs{cap} vz. up to the first letter that is to be
 % uppercased, like so: |\cap{m}u.hammaduN|.
 %
+% \subsection{Additional note on \texttt{dmg} convention}
+% \label{sec:additional-note-dmg}
+% \NEWfeature{v1.3} According to \textcite[6]{dmg}, Arabic
+% \arb[trans]{'i`rAb} may be rendered into |dmg| in three different
+% ways:
+% \begin{compactenum}[(a)]
+% \item \label{ref:dmg-full-rend}In full:
+%   \NoArbUp\arb[trans]{\cap{`amruNU}}\ArbUpDflt\,;
+% \item \label{ref:dmg-up-rend}As superscript text:
+%   \arb[trans]{\cap{`amruNU}}\,;
+% \item Discarded: \arb[trans]{\cap{`amr}}.
+% \end{compactenum}
+% \DescribeMacro{\arbup} By default, \package{arabluatex} applies rule
+% \ref{ref:dmg-up-rend}. Once delimited by a set of Lua functions,
+% every \arb[trans]{tanwIn} is passed as an argument on to a
+% \cs{arbup} command which is set to \cs{textsuperscript}.
+%
+% \DescribeMacro{\NoArbUp} \DescribeMacro{\ArbUpDflt} \cs{NoArbUp} may
+% be used either in the preamble or at any point of the document in
+% case one wishes to apply rule \ref{ref:dmg-full-rend}. The default
+% rule \ref{ref:dmg-up-rend} can be set back with \cs{ArbUpDflt} at
+% any point of the document.
+%
+% \DescribeMacro{\SetArbUp} Finally, \cs{SetArbUp}\marg{formatting
+% directives} may be used to customize the way \arb[trans]{tanwIn} is
+% displayed. To take one example, here is how Arabic
+% \arb[trans]{'i`rAb} may be rendered as subscript text:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+\SetArbUp{\textsubscript{#1}}
+Arabic |dmg| transliteration for \arb{ra'aytu ^gAmi`aN
+muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu
+^gAmi`aN muhaddamaTaN mi'_danatu-hu.}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
+% As shown in the above example, |#1| is the token that is replaced
+% with the actual \arb[trans]{tanwIn} in the formatting directives of
+% the \cs{SetArbUp} command.
+% 
 % \subsection{Examples}
 % \label{sec:examples-translit}
 % Here follows in transliteration the story of
@@ -2029,7 +2084,7 @@ wa-ya.sIru ta.hta 'l-jildi
 %    \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{arabluatex}%
-[2016/05/09 v1.2 ArabTeX-like interface for LuaLaTeX]
+[2016/05/19 v1.3 ArabTeX-like interface for LuaLaTeX]
 \RequirePackage{ifluatex}
 %    \end{macrocode}
 % \package{arabluatex} requires \LuaLaTeX\ of course. Issue a warning
@@ -2160,21 +2215,33 @@ wa-ya.sIru ta.hta 'l-jildi
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\arbup}
+% \changes{v1.3}{2016/05/19}{\arb[trans]{tanwIn} is now written as
+% superscript text in \texttt{dmg} mode by default.}
+% \begin{macro}{\NoArbUp}
+% \begin{macro}{\ArbUpDflt}
 % \begin{macro}{\SetArbUp}
 %   By default, \cs{arbup} is set to \cs{textsuperscript}. This is how
 %   the \arb[trans]{tanwIn} that takes place at the end of a word
-%   should be displayed in |dmg| mode. \cs{SetArbUp} may be used
-%   either in the preamble or at any point of the document to change
-%   the default definition.
+%   should be displayed in |dmg| mode. \cs{NoArbUp} may be used
+%   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
+%   \arb[trans]{tanwIn} is displayed: this command takes the
+%   formatting directives as argument, like so:
+%   \cs{SetArbUp}\marg{code}.
 %    \begin{macrocode}
-\NewDocumentCommand{\al@arbup@dflt}{m}{\textsuperscript{\thinspace#1}}%
+\NewDocumentCommand{\al@arbup@dflt}{m}{\textsuperscript{#1}}%
 \NewDocumentCommand{\al@arbup}{m}{\al@arbup@dflt{#1}}
 \NewDocumentCommand{\arbup}{m}{\al@arbup{#1}}
 \NewDocumentCommand{\ArbUpDflt}{}{\let\al@arbup=\al@arbup@dflt}
 \NewDocumentCommand{\NoArbUp}{}{\RenewDocumentCommand{\al@arbup}{m}{##1}}
+\NewDocumentCommand{\SetArbUp}{m}{\RenewDocumentCommand{\al@arbup}{m}{#1}}
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
 % \begin{macro}{\cap} Proper Arabic names or book titles should be
 % passed to the command \cs{cap} so that they have their first letters
 % uppercased. \cs{cap} is actually coded in Lua.
diff --git a/arabluatex_trans.lua b/arabluatex_trans.lua
index fbea94b..838bccc 100644
--- a/arabluatex_trans.lua
+++ b/arabluatex_trans.lua
@@ -199,7 +199,7 @@ trigraphstrdmg = { -- trigraphs or more
    {a="(_a)U", b="A"},
    {a="(_a)I", b="A"},
    -- assimilations
-   {a="(n)(})(%s)([rlmnwy])", b="%4%2%3%4"}
+   {a="(n)(}?)(%s)([rlmnwy])", b="%4%2%3%4"}
 }
 
 trigraphstrdmgeasy = { -- see the differences below under 'easy' tag