done documenting the Buckwalter input scheme; getting close to v1.4

2 files changed, 154 insertions, 2 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 736c44d..7f5246c 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -1932,6 +1932,153 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu
 % \end{arab}
 % \SetTranslitConvention{dmg}
 %
+% \section{Buckwalter input scheme}
+% \label{sec:buckwalter-scheme}
+% \NEWfeature{v1.4} Even though \package{arabluatex} is primarily
+% designed to process the Arab\TeX\ notation, it can also process the
+% Buckwalter input scheme to a large extent.\footnote{See
+% \url{http://www.qamus.org/transliteration.htm}} The Buckwalter
+% scheme is actually processed in two steps, as it is first converted
+% into Arab\TeX. Then, once this is accomplished, the Arab\TeX\ scheme
+% is processed through the above described functions. In this way, the
+% Buckwalter input scheme can make the most of the
+% \package{arabluatex} special features that are presented in
+% \vref{sec:options}.
+%
+% \DescribeMacro{\SetInputScheme} The input scheme, which is set to
+% |arabtex| by default, may be changed at any point of the document by
+% the command \cs{SetInputScheme}\marg{scheme}, where \meta{scheme}
+% may be either |arabtex| or |buckwalter|. This command is also
+% accepted in the preamble should one wish to set the input scheme
+% globally, like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+\usepackage{arabluatex}
+\SetInputScheme{buckwalter}
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Limitations}
+% To date, the following two limitations apply:
+% \begin{compactenum}[(a)]
+% \item The braces |{| and |}|, which are used in Buckwalter scheme to
+%   encode \arb[novoc]{"a} and \arb[novoc]{y"'}, must be replaced with
+%   square brackets viz. |[| and |]| respectively.
+% \item The underscore character |_|, which is used in Buckwalter
+% scheme to encode the Arabic \arb[trans]{ta.twIl} must be replaced
+% with a double hyphen |--| (see above \vref{sec:tatwil}).
+% \end{compactenum}
+%
+% \Cref{tab:buckwalter-scheme} gives the Buckwalter equivalents that
+% are currently used by \package{arabluatex}. The additional
+% characters that are defined in \vref{tab:additional-arabic-codings}
+% are also available.
+% \begin{longtable}{llll}
+% \captionlistentry{Buckwalter scheme}\\[-1em]
+% \toprule
+% Letter & \multicolumn{2}{l}{Transliteration\footnotemark}
+% & Buckwalter notation \\
+%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \endfirsthead
+% \toprule
+% Letter & \multicolumn{2}{l}{Transliteration}
+% & Buckwalter notation \\
+%        & \texttt{dmg} & \texttt{loc} & \\ \midrule
+% \endhead \footnotetext{See \vref{sec:transliteration}.}
+% \label{tab:buckwalter-scheme}
+% \arb[novoc]{a} & \dmg{a} & \loc{a} & \verb|A| \\
+% \arb[novoc]{b} & \dmg{b} & \loc{b} & |b| \\
+% \arb[novoc]{t} & \dmg{t} & \loc{t} & |t| \\
+% \arb[novoc]{_t} & \dmg{_t} & \loc{_t} & |v|\\
+% \arb[novoc]{j} & \dmg{j} & \loc{j} & |j| \\
+% \arb[novoc]{.h} & \dmg{.h} & \loc{.h} & |H| \\
+% \arb[novoc]{x} & \dmg{x} & \loc{x} & |x|\\
+% \arb[novoc]{d} & \dmg{d} & \loc{d} & |d| \\
+% \arb[novoc]{_d} & \dmg{_d} & \loc{_d} & |*| \\
+% \arb[novoc]{r} & \dmg{r} & \loc{r} & |r| \\
+% \arb[novoc]{z} & \dmg{z} & \loc{z} & |z| \\
+% \arb[novoc]{s} & \dmg{s} & \loc{s} & |s| \\
+% \arb[novoc]{^s} & \dmg{^s} & \loc{^s} & |$| \\
+% \arb[novoc]{.s} & \dmg{.s} & \loc{.s} & |S| \\
+% \arb[novoc]{.d} & \dmg{.d} & \loc{.d} & |D| \\
+% \arb[novoc]{.t} & \dmg{.t} & \loc{.t} & |T| \\
+% \arb[novoc]{.z} & \dmg{.z} & \loc{.z} & |Z| \\
+% \arb[novoc]{`} & \dmg{`} & \loc{`} & |E| \\
+% \arb[novoc]{.g} & \dmg{.g} & \loc{.g} & |g| \\
+% \arb[novoc]{f} & \dmg{f} & \loc{f} & |f| \\
+% \arb[novoc]{q} & \dmg{q} & \loc{q} & |q| \\
+% \arb[novoc]{k} & \dmg{k} & \loc{k} & |k| \\
+% \arb[novoc]{l} & \dmg{l} & \loc{l} & |l| \\
+% \arb[novoc]{m} & \dmg{m} & \loc{m} & |m| \\
+% \arb[novoc]{n} & \dmg{n} & \loc{n} & |n| \\
+% \arb[novoc]{h} & \dmg{h} & \loc{h} & |h| \\
+% \arb[novoc]{w} & \dmg{w} & \loc{w} & |w| \\
+% \arb[novoc]{y} & \dmg{y} & \loc{y} & |y| \\
+% \arb[novoc]{T} & \dmg{aT} & \loc{aT} & |p| \\
+% \midrule
+% \arb[novoc]{|"'} & \dmg{|"'} & \loc{|"'} & \verb|'| \\
+% \arb[novoc]{A"'} & \dmg{A"'} & \loc{A"'} & \verb+|+ \\
+% \arb[novoc]{a"'} & \dmg{a"'} & \loc{a"'} & \verb|>| \\
+% \arb[novoc]{w"'} & \dmg{w"'} & \loc{w"'} & \verb|&| \\
+% \arb[novoc]{i"'} & \dmg{i"'} & \loc{i"'} & \verb|<| \\
+% \arb[novoc]{y"'} & \dmg{y"'} & \loc{y"'} & \verb|]| \\
+% \midrule
+% \arb[novoc]{BB} & --- & --- & \verb|~| \\
+% \arb[novoc]{"a} & ' & ' & |[| \\
+% \midrule
+% \arb[voc]{Ba} & \dmg{Ba} & \loc{Ba} & \verb|a| \\
+% \arb[voc]{Bu} & \dmg{Bu} & \loc{Bu} & \verb|u| \\
+% \arb[voc]{Bi} & \dmg{Bi} & \loc{Bi} & \verb|i| \\
+% \arb[voc]{BaN} & \dmg{BaN} & \loc{BaN} & \verb|F| \\
+% \arb[voc]{BuN} & \dmg{BuN} & \loc{BuN} & \verb|N| \\
+% \arb[voc]{BiN} & \dmg{BiN} & \loc{BiN} & \verb|K| \\
+% \arb[voc]{B"} & --- & --- & \verb|o| \\
+% \midrule
+% \arb[novoc]{B_a} & \dmg{B_a} & \loc{B_a} & |`| \\
+% \midrule
+% \arb[novoc]{--} & --- & --- & |--| (\arb[trans]{ta.twIl})\\
+% \bottomrule
+% \caption*{\Cref*{tab:buckwalter-scheme}: Buckwalter scheme}
+% \end{longtable}
+%
+% \paragraph{Transliteration}
+% The Buckwalter notation can also be transliterated into any accepted
+% romanization standard of Arabic. See above
+% \vref{sec:transliteration} for more information. However, it should
+% be pointed out again that only accurate coding produces accurate
+% transliteration. It is therefore at the very least highly advisable
+% to use the hyphen for tying the definite article and the inseparable
+% particles (viz. prepositions, adverbs and conjunctions) to words,
+% like so:--- \SetInputScheme{buckwalter}
+% \begin{quote}
+%   |Al-EaAlamu| \arb{Al-EaAlam-u} \arb[trans]{Al-EaAlam-u},
+%   |Al-$~amsu| \arb{Al-$~ams-u} \arb[trans]{Al-$~ams-u},
+%   |bi-SinaAEapi| |Al-T~ib~i|, \arb{bi-SinaAEap-i Al-T~ib~-i}
+%   \arb[trans]{bi-SinaAEap-i Al-T~ib~-i}.
+%
+%   |wa-Al-l~`hi| \arb{wa-Al-l~`h-i} \arb[trans]{wa-Al-l~`h-i},
+%   |Al-Hamdu| |li-l~`hi| \arb{Al-Hamd-u li-l~`h-i}
+%   \arb[trans]{Al-Hamd-u li-l~`h-i}.
+% \end{quote}
+% \SetInputScheme{arabtex}
+%
+% Similary, it is not advisable to use \verb+|+ and |[| to encode the
+% \arb[trans]{'alif-u 'l-mamdUdaT-i} and the \arb[trans]{'alif-u
+% 'l-wa.sl-i} for such signs can be generated by \package{arabluatex}.
+% Besides, as they do not \emph{per se} convey any morphological
+% information on what they are derived from, they cannot be
+% transliterated accurately. To take one example, %
+% \SetInputScheme{buckwalter}%
+% |<ilY Al-[ntiqaADi| gives \arb{>ilY Al-[ntiqaADi} as expected, but
+% only |<ilY Al-intiqADi| can be transliterated as \arb[trans]{<ilY
+% Al-intiqaADi} with the correct vowel \meta{i} in place of the %
+% \SetInputScheme{arabtex}%
+% \arb[trans]{'alif-u 'l-wa.sl-i}.
+% 
 % \section{\LaTeX\ Commands in Arabic environments}
 % \label{sec:commands-in-arb}
 % \paragraph{General principle} \label{ref:cmd-inside-arabic}\LaTeX\
@@ -1942,7 +2089,7 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu
 % as their arguments:---
 % \begin{quote}
 %   |\abjad{45}| |kitAbu-hu| |\emph{fI| |'l-\cap{`AdAt-i}}|
-%   \arb[voc]{\abjad{45} kitAbu-hu \emph{fI l-\cap{`AdAt-i}}}
+%   \arb[voc]{\abjad{45} kitAbu-hu \emph{fI 'l-\cap{`AdAt-i}}}
 %   \arb[trans]{\abjad{45} kitAbu-hu \emph{fI
 %   'l-\cap{`AdAt-i}}}.\footnote{This is odd in Arabic script, but
 %   using such features as \cs{emph} or \cs{textbf} is a matter of
@@ -2263,7 +2410,7 @@ wa-ya.sIru ta.hta 'l-jild-i
   {\NewDocumentCommand{\aemph}{m}{$\overline{\text{#1}}$}}}
 %    \end{macrocode}
 % \begin{macro}{\SetInputScheme}
-%   \changes{v1.4}{2016/06/30}{\cs{SetInputScheme} may be used to
+%   \changes{v1.4}{2016/07/04}{\cs{SetInputScheme} may 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
diff --git a/arabluatex_voc.lua b/arabluatex_voc.lua
index 59e861f..f83aa5c 100644
--- a/arabluatex_voc.lua
+++ b/arabluatex_voc.lua
@@ -113,7 +113,12 @@ buckwalter = {
    -- trigraphs
    {a="^Aal%-?", b="al-"},
    {a="(%W)Aal%-?", b="%1al-"},
+   {a="(%s)Aal%-?", b="%1al-"},
    {a="([%-%s])Al%-?", b="%1\'l-"},
+   {a="^A", b="a"},
+   {a="(%W)A", b="%1a"},
+   {a="(%s)A", b="%1a"},
+   {a="(al%-[%g])(%~)", b="%1"},
    {a="(\'l%-[%g])(%~)", b="%1"},
    -- digraphs begin
    {a="aA", b="A"},