updated documentation on the new \abjad command

2 files changed, 60 insertions, 55 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 62adc75..27e970e 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/03/31 v1.0.1 This is ArabTeX for LuaLaTeX]
+    [2016/04/26 v1.1 This is ArabTeX for LuaLaTeX]
 %</package-info>
 %
 %<*driver>
@@ -130,12 +130,13 @@
 \usepackage[english]{babel}
 \usepackage{dox}
 \doxitem{Option}{option}{options}
+\def\actualchar{ =}
 \usepackage{fontspec,luatextra,realscripts}
 \defaultfontfeatures{RawFeature={+liga;+onum;+hlig}}
 \setmainfont{Libertinus Serif}
 \setsansfont{Libertinus Sans}
 \setmonofont[Scale=.9]{Libertinus Mono}
-\usepackage{arabluatex}[2016/03/31]
+\usepackage{arabluatex}[2016/04/26]
 \usepackage{varioref}
 \usepackage{hypdoc}
 \hypersetup{unicode=true, colorlinks, allcolors=blue,
@@ -176,8 +177,8 @@
 \DeclareIndexFieldFormat{indextitle}{\index{#1=\emph{#1}}}
 \addbibresource{arabluatex.bib}
 \EnableCrossrefs
-\CodelineIndex
 \RecordChanges
+\CodelineIndex
 \begin{document}
   \DocInput{arabluatex.dtx}
   \addcontentsline{toc}{section}{Change History}
@@ -207,8 +208,8 @@
 %   Right brace   \}     Tilde         \~}
 %
 %
-% \changes{1.0}{2016/03/29}{Initial release}
-% \changes{1.0.1}{2016/03/31}{Minor update of the documentation}
+% \changes{v1.0}{2016/03/29}{Initial release}
+% \changes{v1.0.1}{2016/03/31}{Minor update of the documentation}
 %
 % \DoNotIndex{\newcommand,\newenvironment,\renewcommand}
 % \DoNotIndex{\~,\AtBeginDocument,\bgroup,\csname}
@@ -216,7 +217,7 @@
 % \DoNotIndex{\else,\endcsname,\endinput,\expandafter,\fi}
 % \DoNotIndex{\ifdef,\ifdefined,\ifx,\MessageBreak,\NeedsTeXFormat}
 % \DoNotIndex{\NewDocumentCommand,\newif,\PackageError,\PackageWarning}
-% \DoNotIndex{\relax,\RenewDocumentCommand,\string}
+% \DoNotIndex{\relax,\RenewDocumentCommand,\string,\verb}
 % 
 % \providecommand*{\url}{\texttt}
 % \GetFileInfo{arabluatex.dtx}
@@ -404,8 +405,7 @@
 % complain if you try to compile your document with another
 % engine. That aside, \package{arabluatex} does not load packages such
 % as \package{polyglossia} or \package{luabidi}. It can work with
-% \package{polyglossia} though, but does not require it.\footnote{With
-% one exception: see \vref{sec:abjad}.}
+% \package{polyglossia} though, but does not require it.
 %
 % \paragraph{Font setup}
 % If you wish to use your own Arabic font, you can define it before
@@ -1502,42 +1502,37 @@ consonants, though three of them are also used as vowels
 % \arb[trans]{'abjad} numbers are usually distinguished from the
 % surrounding words by a stroke placed over them.
 %
-% For the time being, \package{arabluatex} inserts those numbers with the
-% help of \package{polyglossia}. If one wishes to use the
-% \arb[trans]{abjad} system, he may put in his preamble:---
-% \iffalse
-%<*example>
-% \fi
-\begin{arabluaverbatim}
-\usepackage{polyglossia}
-\setdefaultlanguage{english} % please adapt
-\setotherlanguage{arabic} % to enable the 'abjad' numbers
-\end{arabluaverbatim}
-% \iffalse
-%</example>
-% \fi %
-% \DescribeMacro{\abjad} Then one 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:---
+% \DescribeMacro{\abjad} \NEWfeature{v.1.1} \arb[trans]{'abjad}
+% numbers are inserted with 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:---
 % \begin{quote}
 %   |\abjad{45}| |kitAbu-hu| |fI| |'l-`AdAti| \arb[voc]{\abjad{45}
 %   kitAbu-hu fI 'l-`AdAti} \arb[trans]{\abjad{45} kitAbu-hu fI
 %   'l-`AdAti}.
 % \end{quote}
+% \begin{quoting}
+%   \textsc{Rem.}~\emph{a.} As can be seen in the above given example,
+%   \package{arabluatex} expresses the \arb[trans]{'abjad} numbers in
+%   Roman numerals if it finds the command \cs{abjad} in any of the
+%   transliteration modes.
+%
+%   \textsc{Rem.}~\emph{b.} \cs{abjad} may also be found outside
+%   Arabic environments. In that case, \package{arabluatex} does not
+%   print the stroke as a distinctive mark over the number for it is
+%   not surrounded by other Arabic words. In case one nonetheless
+%   wishes to print the stroke, he can use the \cs{aemph} command that
+%   is described below in \vref{sec:emphasis}:---
+%   \begin{quote}
+%     |The| |\arb[trans]{'abjad}| |number| |for| |1874| |is|
+%     |\abjad{1874}| The \arb[trans]{'abjad} number for 1874 is
+%     \abjad{1874}.
 %
-% \iffalse
-%<*example>
-% \fi
-\begin{arabluacode}[text only]
-  Apart from this case, \package{arabluatex} makes no use of
-  \package{polyglossia}. The support for the \arb[trans]{'abjad}
-  numbering system is planned for inclusion in a future version of
-  \package{arabluatex}.
-\end{arabluacode}
-% \iffalse
-%</example>
-% \fi
+%     |The| |\arb[trans]{'abjad}| |number| |for| |1874| |is|
+%     |\aemph{\abjad{1874}}| The \arb[trans]{'abjad} number for 1874
+%     is \aemph{\abjad{1874}}.
+%   \end{quote}
+% \end{quoting}
 %
 % \subsection{Additional characters}
 % \label{sec:additional-characters}
@@ -1596,7 +1591,7 @@ consonants, though three of them are also used as vowels
 % \begin{quote}
 %   |\abjad{45}:| |kitAbu-hu| |\aemph{fI| |'l-`AdAti}|
 %   \arb[voc]{\abjad{45}: kitAbu-hu \aemph{fI 'l-`AdAti}}
-%   \arb[trans]{45: kitAbu-hu fI 'l-\cap{`AdAti}}.
+%   \arb[trans]{\abjad{45}: kitAbu-hu fI 'l-\cap{`AdAti}}.
 % \end{quote}
 %
 % \section{Special applications}
@@ -1741,17 +1736,18 @@ consonants, though three of them are also used as vowels
 % \section{\LaTeX\ Commands in Arabic environments}
 % \label{sec:commands-in-arb}
 % \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
-% assumed to have Arabic text as their arguments:---
+% 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.}
+%   \arb[trans]{\abjad{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:---
@@ -1970,7 +1966,7 @@ wa-ya.sIru ta.hta 'l-jildi
 %    \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{arabluatex}%
-[2016/03/31 v1.0.1 ArabTeX-like interface for LuaLaTeX]
+[2016/04/26 v1.1 ArabTeX-like interface for LuaLaTeX]
 \RequirePackage{ifluatex}
 %    \end{macrocode}
 % \package{arabluatex} requires \LuaLaTeX\ of course. Issue a warning
@@ -2156,7 +2152,13 @@ wa-ya.sIru ta.hta 'l-jildi
   \else \fi\fi\fi\fi}[\par]
 %    \end{macrocode}
 % \end{environment}
-% \begin{macro}{\abjad} \cs{abjad}
+% \begin{macro}{\abjad} \cs{abjad}\marg{number} expresses its argument
+%   in Arabic letters in accordance with the \arb[trans]{'abjad}
+%   arrangement of the alphabet. \meta{number} must be between 1 and
+%   1999. It is now coded in Lua so that \package{polyglossia} is no
+%   longer needed. See |arabluatex.lua| for more information.
+%   \changes{v1.1}{2016/04/26}{New and more flexible \protect\cs{abjad}
+%   command.}
 %    \begin{macrocode}
 \NewDocumentCommand{\abjad}{m}%
   {\luadirect{tex.sprint(abjadify(#1))}}
diff --git a/arabluatex.lua b/arabluatex.lua
index 102974a..0f3984b 100644
--- a/arabluatex.lua
+++ b/arabluatex.lua
@@ -388,24 +388,27 @@ local abjad = {
 {".g"}
 }
 
+-- this function is adapted from an 'obsolete project' of Khaled
+-- Hosny's that dates back to 2010. Thanks to him.
+-- See https://github.com/khaledhosny/lualatex-arabic
 function abjadify(n)
-    local result = ""
+    local abjadnum = ""
     if n >= 1000 then
         for i=1,math.floor(n/1000) do
-            result = result .. abjad[4][1]
+            abjadnum = abjadnum .. abjad[4][1]
         end
         n = math.fmod(n,1000)
     end
     if n >= 100 then
-        result = result .. abjad[3][math.floor(n/100)]
+        abjadnum = abjadnum .. abjad[3][math.floor(n/100)]
         n = math.fmod(n, 100)
     end
     if n >= 10 then
-        result = result .. abjad[2][math.floor(n/10)]
+        abjadnum = abjadnum .. abjad[2][math.floor(n/10)]
         n = math.fmod(n, 10)
     end
     if n >= 1 then
-        result = result .. abjad[1][math.floor(n/1)]
+        abjadnum = abjadnum .. abjad[1][math.floor(n/1)]
     end
-    return "\\arb{"..result.."}"
+    return "\\arb{"..abjadnum.."}"
 end