added 'quoted' connective alif in fullvoc mode; done documenting!

2 files changed, 231 insertions, 21 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 833b0e8..fce7f45 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/01/26 v1.0 This is ArabTeX for LuaLaTeX]
+    [2016/03/29 v1.0 This is ArabTeX for LuaLaTeX]
 %</package-info>
 %
 %<*driver>
@@ -40,7 +40,7 @@
 \setmainfont{Libertinus Serif}
 \setsansfont{Libertinus Sans}
 \setmonofont[Scale=.9]{Libertinus Mono}
-\usepackage{arabluatex}[2016/01/26]
+\usepackage{arabluatex}[2016/03/29]
 \usepackage{polyglossia}
 \setdefaultlanguage{english}
 \setotherlanguage{arabic}
@@ -72,6 +72,7 @@
 \DeclareTotalTCBox{\arabluabox}{m}{left=0mm, right=0mm, top=0mm,
     bottom=0mm, colback=white, boxrule=.15mm,
     colframe=red!50!white}{#1}
+\usepackage{xcolor}
 \newcommand{\package}[1]{\textsf{#1}\index{#1=#1 (package)}}
 \usepackage{csquotes}
 \DeclareQuoteStyle{arabic}
@@ -112,7 +113,7 @@
 %   Right brace   \}     Tilde         \~}
 %
 %
-% \changes{1.0}{2016/01/26}{Converted to DTX file}
+% \changes{1.0}{2016/03/29}{Initial release}
 %
 % \DoNotIndex{\newcommand,\newenvironment,\renewcommand}
 %
@@ -122,7 +123,7 @@
 % \title{\tcbox[enhanced, tikznode, drop lifted shadow, colback=white,
 % boxrule=.25mm]%
 % {The \textsf{arabluatex} package\\
-% \fileversion~from \filedate}}
+% \fileversion\ -- \filedate}}
 % 
 % \newcommand*{\NEWfeature}[1]{%
 %     \hskip 1sp \marginpar{\small\sffamily\raggedright
@@ -382,7 +383,7 @@ consonants, though three of them are also used as vowels
 % \iffalse
 %</example>
 % \fi
-% like so:---
+% like so:---\label{ref:juha-code}
 % \setquotestyle{arabic}
 % \iffalse
 %<*example>
@@ -978,7 +979,7 @@ consonants, though three of them are also used as vowels
 %   \arb[fullvoc]{\cap{z}ayduN ibnu \cap{`amriNU}}
 %   \arb[trans]{\cap{z}ayduN ibnu
 %   \cap{`amriNU}},\footnote{\enquote{Zayd is the son of ʿAmr}: the
-%   second noun is not in apposition to the first, but form part of
+%   second noun is not in apposition to the first, but forms part of
 %   the predicate. Hence \arb[voc]{zayduN ibnu `amriNU} and not
 %   \arb[voc]{zaydu bnu `amriNU}, \enquote{Zayd, son of ʿAmr}.}
 %   |imru'u| |'l-qaysi| \arb[fullvoc]{imru'u 'l-qaysi}
@@ -1032,6 +1033,7 @@ consonants, though three of them are also used as vowels
 %   \arb[fullvoc]{qatalati 'l-rUmu} \arb[trans]{qatalati
 %   \cap{'l-rUmu}}.
 % \end{quote}
+% \label{ref:muhammaduni}
 % However, the Arabic script does not shows the \arb[trans]{kasraT}
 % which is taken by the nouns having \arb[trans]{tanwIn} although it
 % is explicit in pronunciation and must appear in some transliteration
@@ -1064,7 +1066,7 @@ consonants, though three of them are also used as vowels
 %   vowel at the commencement of a word preceded by a word that ends
 %   with a vowel, either short or long, is absorbed by this vowel
 %   viz. \arb[trans]{`al_A 'l-.tarIqi}. See \vref{sec:pipe} on the
-%   \enquote{pipe} and **td on |dmg| mode.}
+%   \enquote{pipe} and \vref{sec:transliteration} on |dmg| mode.}
 %   |al-l_ahu| \arb[fullvoc]{yA| al-l_ahu} \arb[trans]{yA| al-l_ahu},
 %   \verb+'a-fa|+\footnote{\label{fn:pipe-allah-02}See
 %   \cref{fn:pipe-allah-01}.}|-al-l_ahi| |la-ta.g`alanna|
@@ -1465,7 +1467,7 @@ consonants, though three of them are also used as vowels
 % the \enquote{transliteration mode} may be selected globally or locally.
 %
 % This mode transliterates the Arab\TeX\ input into one of the
-% accepted standards. At said above \vpageref{ref:describe-trans}, two
+% accepted standards. As said above \vpageref{ref:describe-trans}, two
 % standards are supported at present:
 % \begin{compactdesc}
 % \item[dmg] \emph{Deutsche Morgenländische Gesellschaft}, which was
@@ -1512,18 +1514,221 @@ consonants, though three of them are also used as vowels
 % \paragraph{Proper names} \DescribeMacro{cap} Proper names or book
 % titles that must have their first letters uppercased may be passed
 % as arguments to the command \cs{cap}\marg{word}. \cs{cap} is a
-% clever command, as it will give the definite article
+% clever command, for it will give the definite article
 % \arb[trans]{al-} in lower case in all positions. Moreover, if the
 % inital letter, apart from the article, cannot be uppercased,
-% viz. \arb[trans]{'} or \arb[trans]{`}, the letter next to it will be
+% viz. \arb[trans]{|"'} or \arb[trans]{`}, the letter next to it will be
 % uppercased:---
 % \begin{quote}
 %   |\cap{.hunaynu}| |bnu| |\cap{'is.h_aqa}| \arb[voc]{\cap{.hunaynu}
 %   bnu \cap{'is.h_aqa}} \arb[trans]{\cap{.hunaynu} bnu
 %   \cap{'is.h_aqa}}, |\cap{`u_tm_anu}| \arb[voc]{\cap{`u_tm_anu}}
-%   \arb[trans]{\cap{`u_tm_anu}}.
+%   \arb[trans]{\cap{`u_tm_anu}}, |.daraba| |\cap{zaydu}| |bnu|
+%   |\cap{_h_alidiN}| |\cap{sa`da}| |bna| |\cap{`awfi}| |bni|
+%   |\cap{`abdi}| |\cap{'l-l_ahi}| \arb[fullvoc]{.daraba \cap{zaydu}
+%   bnu \cap{_h_alidiN} \cap{sa`da} bna \cap{`awfi} bni \cap{`abdi}
+%   \cap{'l-l_ahi}} \arb[trans]{.daraba \cap{zaydu} bnu
+%   \cap{_h_alidiN} \cap{sa`da} bna \cap{`awfi} bni \cap{`abdi}
+%   \cap{'l-l_ahi}}.
+% \end{quote}
+% However, \cs{cap} must be used cautiously in some very particular
+% cases, for the closing brace of its argument may prevent a rule from
+% being applied. To take an example, as seen above
+% \vpageref{ref:muhammaduni}, the transliteration of
+% \arb[fullvoc]{\cap{m}u.hammaduN 'l-nabI} must be
+% \arb[trans]{\cap{m}u.hammaduN 'l-nabI}, as nouns having the
+% \arb[trans]{tanwIn} take a \arb[trans]{kasraT} in pronunciation
+% before \arb[trans]{'alifu 'l-wa.sli}. In this case, encoding
+% \arb[fullvoc]{mu.hammaduN} like so: |\cap{mu.hammaduN}| is wrong,
+% because the closing brace would prevent \package{arabluatex} from
+% detecting the sequence \meta{-uN} immediately followed by
+% \meta{'-l}. Fortunately, this can be circumvented in a
+% straightforward way by inserting only part of the noun in the
+% argument of \cs{cap} vz. up to the first letter that is to be
+% uppercased, like so: |\cap{m}u.hammaduN|.
+%
+% \subsection{Examples}
+% \label{sec:examples-translit}
+% Here follows in transliteration the story of
+% \arb[trans]{\cap{ju.hA}} and his donkey (\arb[voc]{\cap{ju.hA
+% wa-.himAru-hu}}). See the code \vpageref{ref:juha-code}:---
+%
+% \SetTranslitConvention{dmg}
+% \begin{arab}[trans]
+%   \LR{\textbf{\emph{\enquote*{dmg}} standard}:} 'at_A .sadIquN 'il_A
+%   \cap{ju.hA} ya.tlubu min-hu .himAra-hu li-yarkaba-hu fI safraTiN
+%   qa.sIraTiN. wa-qAla la-hu: \enquote{sawfa 'u`Idu-hu 'ilay-ka fI
+%   'l-masA'i wa-'adfa`u la-ka 'ujraTaN.} fa-qAla \cap{ju.hA}:
+%   \enquote{'anA 'AsifuN jiddaN 'annI lA 'asta.tI`u 'an 'u.haqqiqa
+%   la-ka .garbata-ka fa-'l-.himAru laysa hunA 'l-yawma.}  wa-qabla
+%   'an yutimma \cap{ju.hA} kalAma-hu bada'a 'l-.himAru yanhaqu fI
+%   'i.s.tabili-hi. fa-qAla la-hu .sadIqu-hu: \enquote{'innI 'asma`u
+%   .himAra-ka yA \cap{ju.hA} yanhaqu.} fa-qAla la-hu \cap{ju.hA}:
+%   \enquote{.garIbuN 'amru-ka yA .sadIqI 'a-tu.saddiqu 'l-.himAra
+%   wa-tuka_d_dibu-nI?}
+% \end{arab}
+% 
+% \SetTranslitConvention{loc}
+% \begin{arab}[trans]
+%   \LR{\textbf{\emph{\enquote*{loc}} standard}:} 'at_A .sadIquN 'il_A
+%   \cap{ju.hA} ya.tlubu min-hu .himAra-hu li-yarkaba-hu fI safraTiN
+%   qa.sIraTiN. wa-qAla la-hu: \enquote{sawfa 'u`Idu-hu 'ilay-ka fI
+%   'l-masA'i wa-'adfa`u la-ka 'ujraTaN.} fa-qAla \cap{ju.hA}:
+%   \enquote{'anA 'AsifuN jiddaN 'annI lA 'asta.tI`u 'an 'u.haqqiqa
+%   la-ka .garbata-ka fa-'l-.himAru laysa hunA 'l-yawma.}  wa-qabla
+%   'an yutimma \cap{ju.hA} kalAma-hu bada'a 'l-.himAru yanhaqu fI
+%   'i.s.tabili-hi. fa-qAla la-hu .sadIqu-hu: \enquote{'innI 'asma`u
+%   .himAra-ka yA \cap{ju.hA} yanhaqu.} fa-qAla la-hu \cap{ju.hA}:
+%   \enquote{.garIbuN 'amru-ka yA .sadIqI 'a-tu.saddiqu 'l-.himAra
+%   wa-tuka_d_dibu-nI?}
+% \end{arab}
+% \SetTranslitConvention{dmg}
+%
+% \section{\LaTeX\ Commands in Arabic environments}
+% \label{sec:commands-in-arb}
+% \paragraph{General principle} \LaTeX\ commands are accepted in
+% Arabic environments. The general principle which applies is that
+% single-argument commands (\cs{command}\marg{arg}) such as
+% \cs{emph}\marg{text}, \cs{textbf}\marg{text} and the like, are
+% assumed to have Arabic text as their arguments:---
+% \begin{quote}
+%   |\abjad{45}| |kitAbu-hu| |\emph{fI| |'l-\cap{`AdAti}}|
+%   \arb[voc]{\abjad{45} kitAbu-hu \emph{fI l-\cap{`AdAti}}}
+%   \arb[trans]{45 kitAbu-hu \emph{fI 'l-\cap{`AdAti}}}.\footnote{This
+%   is odd in Arabic script, but using such features as \cs{emph} or
+%   \cs{textbf} is a matter of personal taste.}
 % \end{quote}
 % 
+% The same applies to footnotes:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+\renewcommand{\footnoterule}%
+   {\hfill\noindent\rule[1mm]{.4\textwidth}{.15mm}}
+\begin{arab}
+'inna 'abI kAna mina 'l-muqAtilaTi\footnote{al-muqAtilaTi:
+al-muqAtilIna.}, wa-kAnat 'ummI min `u.zamA'i buyUti
+'l-zamAzimaTi\footnote{al-zamAzimaTu: .tA'ifaTu mina
+'l-fursi.}.
+\end{arab}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
+% Some commands, however, do not expect running text in their
+% arguments, or one may wish to insert English text eg. in footnotes
+% or in marginal notes. \package{arabluatex} provides a set of
+% commands to handle such cases.
+%
+% \DescribeMacro{LR} \cs{LR}\marg{arg} is designed to typeset its
+% argument from left to right. It may be used in an Arabic
+% environment, either \cs{arb}\marg{Arabic text} or \cs{begin}|{arab}|
+% \meta{Arabic text} \cs{end}|{arab}|, for short insertions of left to
+% right text, or to insert any \LaTeX\ command that would otherwise be
+% rejected by \package{arabluatex}, such as commands the argument of
+% which is expected to be a dimension or a unit of measurement.
+%
+% \DescribeMacro{RL} \cs{RL}\marg{arg} does the same as
+% \cs{LR}\marg{arg}, but typesets its argument from left to right. Even
+% in an Arabic environment, this command may be useful. For example, to
+% distinguish words with a different color, one may proceed like
+% so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+\begin{arab}
+wa-'at_A _dU 'l-qarnayni 'ummaTaN 'llatI hiya fI
+\LR{\textcolor{red}{\arb[fullvoc]{((ma.gribi 'l-^samsi))}}}
+wa-lA binA'a la-hum yu'amminu-hum mina 'l-^samsi.
+\end{arab}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
+% \DescribeMacro{LRfootnote} \DescribeMacro{RLfootnote}
+% \cs{LRfootnote}\marg{text} and \cs{RLfootnote}\marg{text} typeset
+% 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
+% footnotes in running Arabic text:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+\arb[fullvoc]{\cap{z}ayduN\LRfootnote{\enquote{Zayd
+is the son of ʿAmr}: the second noun is not in
+apposition to the first, but forms part of
+the predicate\ldots} "ibnu \cap{`amriNU}}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
+% When footnotes are typeset from right to left, it may happen that
+% the numbers of the footnotes that are at the bottom of the page be
+% typeset in the wrong direction. For example, instead of an expected
+% number 18, one may get 81. \package{arabluatex} is not responsible
+% for this, but should it happen, it may be necessary to redefine in
+% the preamble the \LaTeX\ macro \cs{thefootnote} like so:---\\
+% \arabluaverb{\renewcommand*{\thefootnote}{\textsuperscript{\LR{\arabic{footnote}}}}}
+% \DescribeMacro{FixArbFtnmk} Another solution is to put in the
+% preamble, below the line that loads \package{arabluatex}, the
+% command \cs{FixArbFtnmk}. However, for more control over the layout
+% of footnotes marks, it is advisable to use the package
+% \package{scrextend}.\footnote{See
+% \url{http://ctan.org/pkg/koma-script}; read the documentation of
+% \package{KOMA-script} for details about the \cs{deffootnotemark} and
+% \cs{deffootnote} commands.}
+%
+% \DescribeMacro{setRL} \DescribeMacro{setLR} \cs{setRL} and
+% \cs{setLR} may 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
+%<*example>
+% \fi
+\begin{arabluacode}
+\setRL
+\section*{\arb{barzawayhi li-buzurjumihra bni 'l-buxtikAni}}
+\setLR
+\begin{arab}
+qAla barzawayhi bnu 'azhara, ra'su 'a.tibbA'i fArisa...
+\end{arab}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{\package{reledmac}} The two-arguments command
+% \cs{edtext}\marg{lemma}\marg{commands} is supported inside
+% \cs{begin}|{arab}| \ldots\ \cs{end}|{arab}|. As an example, one may
+% get \package{arabluatex} and \package{reledmac} to work together
+% like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+\beginnumbering
+\pstart
+\begin{arab}
+wa-ya.sIru ta.hta 'l-jildi
+\edtext{\arb{.sadIduN}}{\Afootnote{M: \arb{.sadIdaN} E1}}
+\end{arab}
+\pend
+\endnumbering
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi
+% 
+% \section{Future work}
+% \label{sec:future-work}
+%
 %
 % \StopEventually{}
 %
@@ -1536,7 +1741,7 @@ consonants, though three of them are also used as vowels
 %    \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{arabluatex}%
-[2016/01/26 v1.0 ArabTeX-like interface for LuaLaTeX]
+[2016/03/29 v1.0 ArabTeX-like interface for LuaLaTeX]
 \RequirePackage{ifluatex}
 %    \end{macrocode}
 % \package{arabluatex} requires \LuaLaTeX\ of course.
@@ -1654,6 +1859,8 @@ consonants, though three of them are also used as vowels
 \DeclareDocumentCommand{\Marginpar}{m}{\marginpar{\textdir TLT #1}}
 \DeclareDocumentCommand{\LRfootnote}{m}{\bgroup\pardir
   TLT\LR{\footnote{#1}}\egroup}
+\DeclareDocumentCommand{\RLfootnote}{m}{\bgroup\pardir
+  TRT\LR{\footnote{#1}}\egroup}
 \NewDocumentCommand{\FixArbFtnmk}{}{%
   \@ifpackageloaded{scrextend}%
   {\AtBeginDocument{\deffootnote{2em}{1.6em}{\LR{\thefootnotemark}.\enskip}}}%
diff --git a/arabluatex_fullvoc.lua b/arabluatex_fullvoc.lua
index d1f4bdc..505ac4e 100644
--- a/arabluatex_fullvoc.lua
+++ b/arabluatex_fullvoc.lua
@@ -132,10 +132,10 @@ trigraphsfv = { -- trigraphs or more
    {a="^(a)([%_%^%.]?[tdrzsn])%-", b="ا%1ل%2"},
    {a="([%s%-])(a)([%_%^%.]?[tdrzsn])%-", b="%1ا%2ل%3"},
    -- al- + initial unstable hamza
-   {a="^(a)l%-([uai])", b="ا%1لٱ%2"},
-   {a="([%s%-])(a)l%-([uai])", b="%1ا%2لٱ%3"},
+   {a="^(a)l%-(\"?[uai])", b="ا%1لٱ%2"},
+   {a="([%s%-])(a)l%-(\"?[uai])", b="%1ا%2لٱ%3"},
    -- li-/la + art. + initial unstable hamza is a special orthography
-   {a="l([ai])%-l%-([uai])", b="ل%1لٱ%2"},
+   {a="l([ai])%-l%-(\"?[uai])", b="ل%1لٱ%2"},
    -- al- + lunar consonant (i.e. what remains)
    {a="^(a)l%-", b="ا%1لْ"},
    {a="([%s%-])(a)l%-", b="%1ا%2لْ"},
@@ -156,7 +156,7 @@ trigraphsfv = { -- trigraphs or more
    -- li-/la- + assim. art. + solar consonant is a special orthography
    {a="l([ai])%-([%_%^%.]?[tdrzsn])%-([%_%^%.]?[tdrzsn])", b="ل%1ل%3%3"},
    -- art. with waṣla + initial unstable hamza
-   {a="'l%-([uai])", b="ٱلٱ%1"},   
+   {a="'l%-(\"?[uai])", b="ٱلٱ%1"},   
    -- art. with waṣla + lunar consonant (i.e. what remains)
    {a="'l%-", b="ٱلْ"},
    -- the silent wāw
@@ -211,12 +211,15 @@ tanwinfv = {
 
 -- this is new
 digraphsfv = {
+   -- initial straight double quote gives a connective ʾalif
+   {a="^\"[uai]", b="ٱ"},
+   {a="([%s%-])\"[uai]", b="%1ٱ"},
    -- diphthongs to be resolved before ʾalif conjunctionis
-   {a="(aW)(%s)([uai])", b="awuا%2ٱ"},
-   {a="(aw)(%s)([uai])", b="%1u%2ٱ"},
-   {a="(ay)(%s)([uai])", b="%1i%2ٱ"},
-   {a="([uai]%-)([uai])", b="%1ٱ"}, -- hyphen + initial alif without hamza
-   {a="([%_]?[uaiUAIY])(%s)([uai])", b="%1%2ٱ"}, -- initial alif without hamza
+   {a="(aW)(%s)(\"?[uai])", b="awuا%2ٱ"},
+   {a="(aw)(%s)(\"?[uai])", b="%1u%2ٱ"},
+   {a="(ay)(%s)(\"?[uai])", b="%1i%2ٱ"},
+   {a="([uai]%-)(\"?[uai])", b="%1ٱ"}, -- hyphen + initial alif without hamza
+   {a="([%_]?[uaiUAIY])(%s)(\"?[uai])", b="%1%2ٱ"}, -- initial alif without hamza
    {a="^([uai])", b="ا%1"},      -- initial alif without hamza
    {a="(%s)([uai])", b="%1ا%2"}, -- initial alif without hamza
    {a="%-%-", b="ـ"},