1 files changed, 95 insertions, 39 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 435e905..d0fe36f 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -149,36 +149,95 @@
 % \url{http://ctan.org/pkg/arabtex}} Arab\LuaTeX\ is at present
 % nothing more than a modest piece of software. Hopefully---if I may
 % say so---it will eventually provide all of its valuable qualities to
-% the \LuaLaTeX\ users. \package{arabtex} dates back to 1992. As far
-% as I know, it was then the first and only way to typeset Arabic
-% texts with \TeX\ and \LaTeX. To achieve this, \package{arabtex}
-% provided---and still does---an Arabic font in \emph{Nasḫī} style and
-% a macro package that defined its own input notation which was, as
-% the author stated, \enquote{both machine, and human, readable, and
-% suited for electronic transmission and e-mail
-% communication}.\footcite[2]{Lagally2004} Even if the same can be
-% said about Unicode, Arab\TeX\ \textsc{ASCII} input notation still
-% surpasses Unicode input, in my opinion, when it comes to typesetting
-% complex documents, such as scientific documents or critical editions
-% where footnotes and other kind of annotations can be particulary
-% abundant. It must also be said that most text editors have trouble
-% in displaying Arabic script connected with preceding or following
-% \LaTeX\ commands: it often happens that commands seem misplaced, not
-% to mention punctuation marks, or opening or closing braces, brackets
-% or parentheses that are unexpectedly displayed in the wrong
-% direction. Of course, some text editors provide ways to get around
-% such difficulties by inserting invisible Unicode characters, such as
-% LEFT-TO-RIGHT or RIGHT-TO-LEFT MARKS (\texttt{U+200E},
-% \texttt{U+200F}), RTL/LTR \enquote{embed} characters
-% (\texttt{U+202B}, \texttt{U+202A}) and RLO/LRO
+% the \LuaLaTeX\ users.
+%
+% \package{arabtex} dates back to 1992. As far as I know, it was then
+% the first and only way to typeset Arabic texts with \TeX\ and
+% \LaTeX. To achieve this, \package{arabtex} provided---and still
+% does---an Arabic font in \emph{Nasḫī} style and a macro package that
+% defined its own input notation which was, as the author stated,
+% \enquote{both machine, and human, readable, and suited for
+% electronic transmission and e-mail
+% communication}.\footnote{\textcite[2]{Lagally2004}.} Even if the
+% same can be said about Unicode, Arab\TeX\ \textsc{ASCII} input
+% notation still surpasses Unicode input, in my opinion, when it comes
+% to typesetting complex documents, such as scientific documents or
+% critical editions where footnotes and other kind of annotations can
+% be particulary abundant. It must also be said that most text editors
+% have trouble in displaying Arabic script connected with preceding or
+% following \LaTeX\ commands: it often happens that commands seem
+% misplaced, not to mention punctuation marks, or opening or closing
+% braces, brackets or parentheses that are unexpectedly displayed in
+% the wrong direction. Of course, some text editors provide ways to
+% get around such difficulties by inserting invisible Unicode
+% characters, such as LEFT-TO-RIGHT or RIGHT-TO-LEFT MARKS
+% (\texttt{U+200E}, \texttt{U+200F}), RTL/LTR \enquote{embed}
+% characters (\texttt{U+202B}, \texttt{U+202A}) and RLO/LRO
 % \enquote{bidi-override} characters (\texttt{U+202E},
-% \texttt{U+202D}).\footnote{Yudit probably has the best Unicode
-% support. See \url{www.yudit.org}.} Nonetheless, it remains that
-% inserting all the time these invisible characters in complex
-% documents rapidly becomes confusing and cumbersome.
+% \texttt{U+202D}).\footnote{Gáspár Sinai's Yudit probably has the
+% best Unicode support. See \url{www.yudit.org}.} Nonetheless, it
+% remains that inserting all the time these invisible characters in
+% complex documents rapidly becomes confusing and cumbersome.
+%
+% The great advantage of Arab\TeX\ notation is that it is immune from
+% all these difficulties, let alone its being clear and
+% straightforward. One also must remember that computers are designed
+% to process code. Arab\TeX\ notation is a way of encoding Arabic
+% language, just as \TeX\ \enquote{mathematics mode} is a way of
+% processing code to display mathematics. As such, not only does it
+% allow greater control over typographical features, but it also can
+% be processed in several different ways: so without going into
+% details, depending on one's wishes, Arab\TeX\ input can be full
+% vocalized Arabic (\emph{scriptio plena}), vocalized Arabic or
+% non-vocalized Arabic (\emph{scriptio defectiva}); it further can be
+% transliterated into whichever romanization standard the user may
+% choose.
+%
+% But there may be more to be said on this point, as encoding Arabic
+% also naturally encourages the coder to vocalize the texts---without
+% compelling him to do so, of course. Accurate coding may even have
+% other virtuous effects. For instance, hyphens may be used for tying
+% particles or prefixes to words, or to mark inflectional endings, and
+% so forth. In other words, accurate coding produces accurate texts
+% that can stand to close grammatical scrutiny and to complex textual
+% searches as well.
+%
+% Having that in mind, I started \package{arabluatex}. With the help
+% of Lua, it will eventually interact with some other packages yet to
+% come to produce from \verb|.tex| source files, in addition to
+% printed books, \texttt{TEI xml} compliant critical editions and/or
+% lexicons that can be searched, analyzed and correlated in various
+% ways.
+%
+%
+%\subsection{\package{arabluatex} is for \LuaLaTeX}
+% It goes without saying that \package{arabluatex} requires
+% \LuaLaTeX. \TeX\ and \LaTeX\ have \package{arabtex}, and \XeLaTeX\
+% has \package{arabxetex}. Both of them are much more advanced than
+% \package{arabluatex}, as they can process a number of different
+% languages,\footnote{To date, both packages support Arabic, Maghribi,
+% Urdu, Pashto, Sindhi, Kashmiri, Uighuric and Old Malay; in addition
+% to these, \package{arabtex} also has a Hebrew mode, including
+% Judeo-Arabic and Yiddish.} whereas \package{arabluatex} can process
+% only Arabic for the time being. More languages will be included in
+% future releases of \package{arabluatex}.
+%
+% In comparison to \package{arabxetex}, \package{arabluatex} works in
+% a very different way. The former relies on the
+% \href{http://scripts.sil.org/TECkitIntro}{\texttt{TECkit}} engine
+% which converts Arab\TeX\ input on the fly into Unicode Arabic
+% script, whereas the latter passes Arab\TeX\ input on to a set of Lua
+% functions. At first, \LaTeX\ commands are taken care of in different
+% ways: some, as \cs{emph}, \cs{textbf} and the like are expected to
+% have Arabic text as arguments, while others, as \cs{LR}, for
+% \enquote{left-to-right text}, are not. Then, once what is Arabic is
+% carefully separated form what is not, it is processed by other Lua
+% functions which rely on different sets of correpondence tables to do
+% the actual conversion in accordance with one's wishes. Finally, Lua
+% returns to \TeX\ the converted strings---which may in turn contain
+% some other Arab\TeX\ input yet to be processed---for further
+% processing.
 %
-% 
-% 
 % \section{Usage}
 % \newcommand{\dmg}[1]{%
 %   \SetTranslitConvention{dmg}%
@@ -192,13 +251,16 @@
 % & Arab\TeX\ notation \\
 %        & \texttt{dmg} & \texttt{loc} & \\ \midrule
 % \endhead \footnotetext{See below **}
-% \arb[novoc]{a} & \dmg{A} & \loc{A} & \verb|a| \\
+% \arb[novoc]{a} & \dmg{A} & \loc{A} & \verb|A| \\
 % \arb[novoc]{b} & \dmg{b} & \loc{b} & \verb|b| \\
 % \arb[novoc]{t} & \dmg{t} & \loc{t} & \verb|t| \\
 % \arb[novoc]{_t} & \dmg{_t} & \loc{_t} & \verb|_t| \\
 % \arb[novoc]{j} & \dmg{j} & \loc{j} & \verb|^g| or \verb|j| \\
 % \arb[novoc]{.h} & \dmg{.h} & \loc{.h} & \verb|.h| \\
 % \arb[novoc]{x} & \dmg{x} & \loc{x} & \verb|_h| or \verb|x|\\
+% \arb[novoc]{d} & \dmg{d} & \loc{d} & \verb|d| \\
+% \arb[novoc]{_d} & \dmg{_d} & \loc{_d} & \verb|_d| \\
+% \arb[novoc]{r} & \dmg{r} & \loc{r} & \verb|r| \\
 % \bottomrule
 % \caption{Standard notation for Arabic}
 % \end{longtable}
@@ -221,10 +283,10 @@
 % \package{arabluatex} requires \LuaLaTeX\ of course.
 %    \begin{macrocode}
 \ifluatex\else
-  \PackageError{arabluatex}{lualatex needed}{%
-    Package `arabluatex' needs LuaTeX.\MessageBreak
-    So you should use `lualatex' to process you document!\MessageBreak
-    See documentation of `arabluatex' for further information.}%
+ \PackageError{arabluatex}{lualatex needed}{%
+  Package `arabluatex' needs LuaTeX.\MessageBreak
+  So you should use `lualatex' to process your document!\MessageBreak
+  See documentation of `arabluatex' for further information.}%
   \expandafter\expandafter\expandafter\csname endinput\endcsname
 \fi
 %    \end{macrocode}
@@ -319,17 +381,11 @@
         \luastringO{\al@trans@convention}))}\egroup%
     \else
     \fi\fi\fi\fi}[\par]
-% \robustify{\textbf}
-% \robustify{\emph}
-% \robustify{\footnote}
-% \robustify{\marginpar}
 \DeclareDocumentCommand{\Marginpar}{m}{\marginpar{\textdir TLT #1}}
 \RenewDocumentCommand{\thefootnote}{}{\bgroup\textdir
   TLT\arabic{footnote}\egroup}
 \DeclareDocumentCommand{\LRfootnote}{m}{\bgroup\pardir
   TLT\LR{\footnote{#1}}\egroup}
-% \AtBeginDocument{\ifdef{\abjad}{\robustify{\abjad}}{}}
-% \AtBeginDocument{\ifdef{\Footnote}{\robustify{\Footnote}}{}}
 \endinput
 %    \end{macrocode}
 %