almost done. now tidy up things

3 files changed, 103 insertions, 16 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index c4e6388..89501d9 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -374,7 +374,7 @@
 % \package{arabluatex}.
 %
 %\subsection{Typing Arabic}
-% \DescribeMacro{arb} Once \package{arabluatex} is loaded, a command
+% \DescribeMacro{\arb} Once \package{arabluatex} is loaded, a command
 % \cs{arb}\marg{Arabic text} is available for inserting Arabic text in
 % paragraphs, like so:---
 % \iffalse
@@ -1399,7 +1399,7 @@ consonants, though three of them are also used as vowels
 % \iffalse
 %</example>
 % \fi %
-% \DescribeMacro{abjad} Then you may use the command
+% \DescribeMacro{\abjad} Then you may use the command
 % \cs{abjad}\marg{number} in any of the |voc|, |fullvoc| and |novoc|
 % modes, where \meta{number} may be any number between 1 and 1999,
 % like so:---
@@ -1474,7 +1474,7 @@ consonants, though three of them are also used as vowels
 % over them. This technique is used to distinguish further words that
 % are proper names or book titles.
 %
-% \DescribeMacro{aemph} One may use the command \cs{aemph}\marg{Arabic
+% \DescribeMacro{\aemph} One may use the command \cs{aemph}\marg{Arabic
 % text} to use the same technique to emphasize words, like so:---
 % \begin{quote}
 %   |\abjad{45}:| |kitAbu-hu| |\aemph{fI| |'l-`AdAti}|
@@ -1522,7 +1522,7 @@ consonants, though three of them are also used as vowels
 % More standards will be included in future releases of
 % \package{arabluatex}.
 %
-% \paragraph{Convention} \DescribeMacro{SetTranslitConvention} The
+% \paragraph{Convention} \DescribeMacro{\SetTranslitConvention} The
 % transliteration mode, which is set to |dmg| by default, may be
 % changed at any point of the document by the command
 % \cs{SetTranslitConvention}\marg{mode}, where \meta{mode} may be
@@ -1539,7 +1539,7 @@ consonants, though three of them are also used as vowels
 %</example>
 % \fi
 %
-% \paragraph{Style} \DescribeMacro{SetTranslitStyle} Any
+% \paragraph{Style} \DescribeMacro{\SetTranslitStyle} Any
 % transliterated Arabic text is printed in italics by default. This
 % also can be changed either globally in the preamble or locally at
 % any point of the document by the command
@@ -1548,7 +1548,7 @@ consonants, though three of them are also used as vowels
 % \cs{slshape}, and so forth. Any specific font may also be selected
 % using the font-selecting commands of the \package{fontspec} package.
 %
-% \paragraph{Proper names} \DescribeMacro{cap} Proper names or book
+% \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, for it will give the definite article
@@ -1623,7 +1623,8 @@ consonants, though three of them are also used as vowels
 %
 % \section{\LaTeX\ Commands in Arabic environments}
 % \label{sec:commands-in-arb}
-% \paragraph{General principle} \LaTeX\ commands are accepted in
+% \paragraph{General principle} \label{ref:cmd-inside-arabic}\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
@@ -1659,7 +1660,7 @@ al-muqAtilIna.}, wa-kAnat 'ummI min `u.zamA'i buyUti
 % 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
+% \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
@@ -1667,7 +1668,7 @@ al-muqAtilIna.}, wa-kAnat 'ummI min `u.zamA'i buyUti
 % 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
+% \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
@@ -1686,7 +1687,7 @@ wa-lA binA'a la-hum yu'amminu-hum mina 'l-^samsi.
 %</example>
 % \fi
 %
-% \DescribeMacro{LRfootnote} \DescribeMacro{RLfootnote}
+% \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
@@ -1713,7 +1714,7 @@ the predicate\ldots} "ibnu \cap{`amriNU}}
 % 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
+% \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
@@ -1722,7 +1723,14 @@ the predicate\ldots} "ibnu \cap{`amriNU}}
 % \package{KOMA-script} for details about the \cs{deffootnotemark} and
 % \cs{deffootnote} commands.}
 %
-% \DescribeMacro{setRL} \DescribeMacro{setLR} \cs{setRL} and
+% \DescribeMacro{\LRmarginpar} The command \cs{LRmarginpar} does for
+% marginal notes the same as \cs{LRfootnote} does for footnotes. Of
+% course, it is supposed to be used in Arabic environments. Note that
+% \cs{marginpar} also works in Arabic environments, but it acts as any
+% other single-argument command inserted in Arabic environments. The
+% 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
 % form left to right or from right to left. As an example, an
 % easy way to typeset a right-to-left sectional title follows:---
@@ -1900,20 +1908,49 @@ wa-ya.sIru ta.hta 'l-jildi
   {\NewDocumentCommand{\aemph}{m}{$\overline{\text{#1}}$}}}
 %    \end{macrocode}
 % \end{macro}
+% \begin{macro}{\SetTranslitStyle} By default any transliterated
+% Arabic text is printed in italics. This can be changed globally in
+% the preamble or at any point of the document:
 %    \begin{macrocode}
 \def\al@trans@style{\itshape}%
 \NewDocumentCommand{\SetTranslitStyle}{m}{\def\al@trans@style{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\SetTranslitConvention}
+% \cs{SetTranslitConvention}\marg{convention} may be used to change
+% the convention, which is |dmg| by default:
+%    \begin{macrocode}
 \def\al@trans@convention{dmg}
 \NewDocumentCommand{\SetTranslitConvention}{m}{\def\al@trans@convention{#1}}
+%    \end{macrocode}
+% \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.
+%    \begin{macrocode}
 \DeclareDocumentCommand{\cap}{m}%
   {\luadirect{tex.sprint(cap(\luastringN{#1}))}}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\txarb} \cs{txarb} sets the direction to right-to-left
+%   and selects the Arabic font. As it is supposed to be used
+%   internally by several Lua functions, this command is not
+%   documented, but available to the user should he wish to insert
+%   |utf8| Arabic text in his document.
+% \begin{macro}{\txtrans} \cs{txtrans} is used internally by several
+% Lua functions to insert transliterated Arabic text.
+%    \begin{macrocode}
 \DeclareDocumentCommand{\txarb}{+m}{\bgroup\textdir
   TRT\arabicfont#1\egroup}
 \DeclareDocumentCommand{\txtrans}{+m}{\bgroup\textdir
   TLT\rmfamily#1\egroup}
 %    \end{macrocode}
+% \end{macro}
+% \end{macro}
 % \begin{macro}{\arb}
-% Here begins the description of \cs{arb}
+%   The \cs{arb} command detects which Arabic mode is to be used,
+%   either globally if no option is set, or locally, then passes its
+%   argument to the appropriate Lua function.
 %    \begin{macrocode}
 \DeclareDocumentCommand{\arb}{O{\al@mode} +m}%
 {\edef\@tempa{#1}%
@@ -1938,7 +1975,8 @@ wa-ya.sIru ta.hta 'l-jildi
 %    \end{macrocode}
 % \end{macro}
 % \begin{environment}{arab}
-% Here comes the description of the environment |arab|
+% The |arab| environment does for paragraphs the same as \cs{arb} does
+% for short insertions of Arabic text.
 %    \begin{macrocode}
 \NewEnviron{arab}[1][\al@mode]%
 {\par\edef\@tempa{#1}%
@@ -1960,17 +1998,41 @@ wa-ya.sIru ta.hta 'l-jildi
   \else \fi\fi\fi\fi}[\par]
 %    \end{macrocode}
 % \end{environment}
+% \begin{macro}{\LRmarginpar} \cs{LRmarginpar} is supposed to be
+%   inserted in an Arabic environment. It typsets his argument in a
+%   marginal note from left to right.
+%    \begin{macrocode}
+\DeclareDocumentCommand{\LRmarginpar}{m}{\marginpar{\textdir TLT #1}}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\LRfootnote} \cs{LRfootnote} and \cs{RLfootnote} are
+%   supposed to be used in Arabic environments for insertions of non
+%   Arabic text. \cs{LRfootnote} typesets its argument left-to-right\ldots
+%   \begin{macro}{\RLfootnote} while \cs{RLfootnote} typesets its
+%   argument left-to-right.
 %    \begin{macrocode}
-\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}
+%    \end{macrocode}
+%   \end{macro}
+% \end{macro}
+% \begin{macro}{\FixArbFtnmk} In the preamble, just below
+%   \cs{usepackage}|{arabluatex}|, \cs{FixArbFtnmk} may be of some
+%   help in case the footnote numbers at the bottom of the page are
+%   printed in the wrong direction. This quick fix uses and loads
+%   \package{scrextend} if it is not already loaded.
+%    \begin{macrocode}
 \NewDocumentCommand{\FixArbFtnmk}{}{%
   \@ifpackageloaded{scrextend}%
   {\AtBeginDocument{\deffootnote{2em}{1.6em}{\LR{\thefootnotemark}.\enskip}}}%
   {\RequirePackage{scrextend}
   \AtBeginDocument{\deffootnote{2em}{1.6em}{\LR{\thefootnotemark}.\enskip}}}}
+%    \end{macrocode}
+% \end{macro}
+% That is it. Say goodbye before leaving.
+%    \begin{macrocode}
 \endinput
 %    \end{macrocode}
 %
diff --git a/arabluatex.ins b/arabluatex.ins
index 8e90665..614184f 100644
--- a/arabluatex.ins
+++ b/arabluatex.ins
@@ -17,6 +17,17 @@
 %% along with this program; if not, write to the Free Software
 %% Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 %%
+%% This release of 'arabluatex' consists of the following source files:
+%% - arabluatex.ins
+%% - arabluatex.dtx
+%% - arabluatex.lua
+%% - arabluatex_voc.lua
+%% - arabluatex_fullvoc.lua
+%% - arabluatex_novoc.lua
+%% - arabluatex_trans.lua
+%% - arabluatex.bib
+%% 
+
 
 \input docstrip.tex
 \keepsilent
@@ -47,6 +58,16 @@ along with this program; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
 USA.
 
+This release of 'arabluatex' consists of the following source files:
+- arabluatex.ins
+- arabluatex.dtx
+- arabluatex.lua
+- arabluatex_voc.lua
+- arabluatex_fullvoc.lua
+- arabluatex_novoc.lua
+- arabluatex_trans.lua
+- arabluatex.bib
+
 \endpreamble
 
 \generate{\file{arabluatex.sty}{\from{arabluatex.dtx}{package}}}
@@ -59,6 +80,10 @@ USA.
 \Msg{*}
 \Msg{* \space\space arabluatex.sty}
 \Msg{* \space\space arabluatex.lua}
+\Msg{* \space\space arabluatex_voc.lua}
+\Msg{* \space\space arabluatex_fullvoc.lua}
+\Msg{* \space\space arabluatex_novoc.lua}
+\Msg{* \space\space arabluatex_trans.lua}
 \Msg{*}
 \Msg{* To produce the documentation run the files ending with}
 \Msg{* `.dtx' through LuaLaTeX.}
diff --git a/arabluatex.lua b/arabluatex.lua
index c14e396..15ddeef 100644
--- a/arabluatex.lua
+++ b/arabluatex.lua
@@ -66,7 +66,7 @@ local function breakcmd(str)
                 body = string.sub(body, 2, -2)
                 return string.format("}\\%s{%s}\\arb{", tag, body)
                 end)
-        -- Marginpar
+   -- Marginpar
    str = string.gsub(str, "\\(Marginpar.-)(%b{})",
                 function(tag, body)
                 body = string.sub(body, 2, -2)