done documenting the 'easy' feature

1 files changed, 94 insertions, 28 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 2661ad4..c696f80 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/04/27 v1.1.1 This is ArabTeX for LuaLaTeX]
+    [2016/05/08 v1.2 This is ArabTeX for LuaLaTeX]
 %</package-info>
 %
 %<*driver>
@@ -136,7 +136,7 @@
 \setmainfont{Libertinus Serif}
 \setsansfont{Libertinus Sans}
 \setmonofont[Scale=.9]{Libertinus Mono}
-\usepackage{arabluatex}[2016/04/27]
+\usepackage{arabluatex}[2016/05/08]
 \usepackage{varioref}
 \usepackage{hypdoc}
 \hypersetup{unicode=true, colorlinks, allcolors=blue,
@@ -309,7 +309,7 @@
 %
 % \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
+% \LaTeX. To achieve that, \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
@@ -350,7 +350,7 @@
 % choose.
 %
 % \label{ref:tei-to-come}
-% But there may be more to be said on this point, as encoding Arabic
+% But there may be more to be said on that 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
@@ -421,7 +421,7 @@
 % \begin{quoting}
 %   \textsc{Rem.} By default Amiri places the \arb[trans]{kasraT} in
 %   combination with the \arb[trans]{ta^sdId} below the consonant,
-%   like so: \arb{BBi}\,. This is correct, as at least in the oldest
+%   like so: \arb{BBi}\,. That is correct, as at least in the oldest
 %   manuscripts {\newfontfamily\arabicfont[Script=Arabic,
 %   RawFeature={+ss05}]{Amiri}\arb{BBi}} may stand for \arb{BBa} as
 %   well as \arb{BBi}\,. See \textcite[i.14.C--D]{Wright}. The placement
@@ -471,6 +471,70 @@
 % \end{compactdesc}
 % More standards will be included in future releases of
 % \package{arabluatex}.
+% 
+% \subsubsection{Classic contrasted with modern typesetting of Arabic}
+% \label{sec:classic-modern-typesetting}
+% \NEWfeature{v.1.2} By default, \package{arabluatex} typesets Arabic
+% in a classic, traditional style the most prominent features of which
+% are the following:
+% \begin{compactitem}
+% \item \enquote*{Classic} \arb[trans]{maddaT}: when
+% \arb[trans]{'alif} and \arb[trans]{hamzaT} accompanied by a simple
+% vowel or \arb[trans]{tanwIn} is preceded by an \arb[trans]{'alif} of
+% prolongation (\arb[voc]{BA}), then a mere \arb[trans]{hamzaT} is
+% written on the line, and a \arb[trans]{maddaT} is placed over the
+% \arb[trans]{'alif}, like so:---
+% \begin{quote}
+%   |samA'uN| \arb[voc]{samA'uN} \arb[trans]{samA'uN}, |jA'a|
+%   \arb[voc]{jA'a} \arb[trans]{jA'a}, |yatasA'alUna|
+%   \arb[voc]{yatasA'alUna} \arb[trans]{yatasA'alUna}\footnote{Note
+%   that in old mss. such forms as \arb[voc]{samA"'a"'a},
+%   \arb[voc]{jA"'a"'a} are also found; see \textcite[i. 24
+%   D]{Wright}.} (see \vpageref{ref:madda} for further details).
+% \end{quote}
+% \item The euphonic \arb[trans]{ta^sdId} is generated (see
+%   \vpageref{ref:euphonic-tashdid}).
+% \item Assimilation rules laid on \vref{ref:assimilation} are
+%   applied.
+% \item In |fullvoc| mode, the \arb[trans]{sukUn} is expressed.
+% \end{compactitem}
+% 
+% \DescribeMacro{\SetArbEasy} \DescribeMacro{\SetArbDflt} Such
+% refinements may be discarded by the command \cs{SetArbEasy}, either
+% globally in the preamble or locally at any point of the
+% document. Default \enquote*{classic} rules may be set back at any
+% point of the document with the command \cs{SetArbDflt}. Examples
+% follow:---
+% \begin{compactenum}[(a)]
+% \item \cs{SetArbDflt}:
+%   \begin{compactenum}[i.]
+%   \item |voc| \arb[voc]{wa-mAta istisqA'aN qabla 'an yutimma
+%     kitAba-hu fI nujUmi 'l-samA'i}
+%   \item |fullvoc| \arb[fullvoc]{wa-mAta istisqA'aN qabla 'an yutimma
+%     kitAba-hu fI nujUmi 'l-samA'i}
+%   \item |trans| \arb[trans]{wa-mAta istisqA'aN qabla 'an yutimma
+%     kitAba-hu fI nujUmi 'l-samA'i}
+%   \end{compactenum}
+% \item \cs{SetArbEasy}:
+%   \begin{compactenum}[i.]\SetArbEasy
+%   \item |voc| \arb[voc]{wa-mAta istisqA'aN qabla 'an yutimma
+%     kitAba-hu fI nujUmi 'l-samA'i}
+%   \item |fullvoc| \arb[fullvoc]{wa-mAta istisqA'aN qabla 'an yutimma
+%     kitAba-hu fI nujUmi 'l-samA'i}
+%   \item |trans| \arb[trans]{wa-mAta istisqA'aN qabla 'an yutimma
+%     kitAba-hu fI nujUmi 'l-samA'i}\SetArbDflt
+%   \end{compactenum}   
+% \end{compactenum}
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}[text only]
+Please note that this document is typeset with \cs{SetArbDflt} throughout.
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
 %
 %\subsection{Typing Arabic}
 % \DescribeMacro{\arb} Once \package{arabluatex} is loaded, a command
@@ -781,7 +845,7 @@ consonants, though three of them are also used as vowels
 % \paragraph{Silent \arb[novoc]{U}/\arb[novoc]{I}}
 % Some words ending with \arb[voc]{BAT} are usually written
 % \arb[voc]{BawT} or \arb[voc]{B_aUT} instead of \arb[voc]{BAT}: see
-% \textcite[i. 12 A]{Wright}. \package{arabluatex} preserves this
+% \textcite[i. 12 A]{Wright}. \package{arabluatex} preserves that
 % particular writing; the same applies to words ending in
 % \arb[voc]{BayT} for \arb[voc]{BAT}\,. Long vowels \meta{U, I} shall
 % receive no \arb[trans]{sukUn} after a \arb[trans]{'alif ma.h_dUfaT}
@@ -797,7 +861,7 @@ consonants, though three of them are also used as vowels
 % \end{quote}
 %
 % \paragraph{\arb[trans]{\cap{`amruNU}}, and the silent
-% \arb[novoc]{U}} To this name a silent \arb[novoc]{U} is added to
+% \arb[novoc]{U}} To that name a silent \arb[novoc]{U} is added to
 % distinguish it from \arb[trans]{\cap{`umaruN}}: see \textcite[i. 12
 % C]{Wright}. In no way this affects the sound of the
 % \arb[trans]{tanwIn}, so it has to be discarded in |trans| mode:
@@ -983,9 +1047,9 @@ consonants, though three of them are also used as vowels
 % \end{quote}
 % 
 % \subparagraph{The euphonic \arb[trans]{ta^sdId}}
-% always follows a vowelless consonant which is passed over in
-% pronunciation and assimilated to a following consonant. It may be
-% found \parencite[i. 15 B--16 C]{Wright}:---
+% \label{ref:euphonic-tashdid} always follows a vowelless consonant
+% which is passed over in pronunciation and assimilated to a following
+% consonant. It may be found \parencite[i. 15 B--16 C]{Wright}:---
 % \begin{compactenum}[(a)]
 % \item With the \emph{solar} letters \arb[novoc]{t}, \arb[novoc]{_t},
 %   \arb[novoc]{d}, \arb[novoc]{_d}, \arb[novoc]{r}, \arb[novoc]{z},
@@ -995,7 +1059,7 @@ consonants, though three of them are also used as vowels
 % \iffalse
 %<*example>
 % \fi
-\begin{arabluacode}[text only]\label{euphonic-tashdid}
+\begin{arabluacode}[text only]
   Unlike \package{arabtex} and \package{arabxetex},
   \package{arabluatex} \emph{never requires the solar letter to be
     written twice}, as it automatically generates the euphonic
@@ -1013,13 +1077,14 @@ consonants, though three of them are also used as vowels
 %   |al-.zulmu| \arb[voc]{al-.zulmu} \arb[trans]{al-.zulmu},
 %   |al-lu.gaTu| \arb[voc]{al-lu.gaTu} \arb[trans]{al-lu.gaTu}.
 % \end{quote}
-% \item With the letters \arb[novoc]{r}, \arb[novoc]{l}, \arb[novoc]{m},
-% \arb[novoc]{w}, \arb[novoc]{y} after \arb[voc]{n} with
-% \arb[trans]{jazmaT}, and also after the \arb[trans]{tanwIn}:---
+% \item \label{ref:assimilation} With the letters \arb[novoc]{r},
+%   \arb[novoc]{l}, \arb[novoc]{m}, \arb[novoc]{w}, \arb[novoc]{y}
+%   after \arb[voc]{n} with \arb[trans]{jazmaT}, and also after the
+%   \arb[trans]{tanwIn}:---
 % \begin{quote}
 %   Note the absence of \arb[trans]{sukUn} above the passed over
 %   \arb[novoc]{n} in the following examples, each of which is
-%   accompanied with a consistent transliteration: |min rabbi-hi|
+%   accompanied by a consistent transliteration: |min rabbi-hi|
 %   \arb[fullvoc]{min rabbi-hi}, \arb[trans]{min rabbi-hi},
 %   |min| |layliN| \arb[fullvoc]{min layliN} \arb[trans]{min layliN},
 %   |'an| |yaqtula| \arb[fullvoc]{'an yaqtula} \arb[trans]{'an yaqtula}.
@@ -1049,7 +1114,7 @@ consonants, though three of them are also used as vowels
 % As said above on \cpageref{fullvoc-mode}, |fullvoc| is the mode
 % in which \package{arabluatex} expresses the \arb[trans]{sukUn} and
 % the \arb[trans]{wa.slaT}. \package{arabluatex} will take care of
-% doing this automatically provided that the vowel which is to be
+% doing that automatically provided that the vowel which is to be
 % absorbed by the final vowel of the preceding word is properly
 % encoded, like so:---
 % \begin{compactenum}[(a)]
@@ -1128,9 +1193,9 @@ consonants, though three of them are also used as vowels
 %
 % \subparagraph{\arb[trans]{'alifu 'l-wa.sli} preceded by a long
 % vowel} The long vowel preceding the connective \arb[trans]{'alif} is
-% shortened in pronunciation \parencite[i. 21 B--D]{Wright}. This is
-% does not appear in the Arabic script, but \package{arabluatex} takes
-% it into account in some transliteration standards:---
+% shortened in pronunciation \parencite[i. 21 B--D]{Wright}. This does
+% not appear in the Arabic script, but \package{arabluatex} takes it
+% into account in some transliteration standards:---
 % \begin{quote}
 %   |fI| |'l-nAsi| \arb[fullvoc]{fI 'l-nAsi} \arb[trans]{fI 'l-nAsi},
 %   |'abU| |'l-wazIri| \arb[fullvoc]{'abU 'l-wazIri} \arb[trans]{'abU
@@ -1176,7 +1241,7 @@ consonants, though three of them are also used as vowels
 % 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
-% standards. \package{arabluatex} takes care of this automatically:---
+% standards. \package{arabluatex} takes care of that automatically:---
 % \begin{quote}
 %   |mu.hammaduN| |'l-nabI| \arb[fullvoc]{mu.hammaduN 'l-nabI}
 %   \arb[trans]{\cap{m}u.hammaduN 'l-nabI}.
@@ -1194,7 +1259,7 @@ consonants, though three of them are also used as vowels
 % col. 1]{Lane}. Finally, the first \arb[novoc]{l} is made quiescent
 % and incorporated into the other, hence the \arb[trans]{ta^sdId}
 % above it. As \package{arabluatex} never requires a solar letter to
-% be written twice (see above, \vpageref{euphonic-tashdid}), the
+% be written twice (see above, \vpageref{ref:euphonic-tashdid}), the
 % name of God is therefore encoded |al-l_ahu| or |'l-l_ahu|:---
 % \begin{quote}
 %   |al-l_ahu| \arb[fullvoc]{al-l_ahu} \arb[trans]{al-l_ahu},
@@ -1395,7 +1460,7 @@ consonants, though three of them are also used as vowels
 % \label{sec:quoting-hamza}
 % As said above in \vref{ref:hamza}, the \arb[trans]{hamzaT} is always
 % written \meta{\texttt{'}}, its carrier being determined by contextual
-% analysis. \enquote{Quoting} this straight single quote character
+% analysis. \enquote{Quoting} that straight single quote character
 % like so: \meta{\texttt{"'}} allows to determine the carrier of the
 % \arb[trans]{hamzaT} freely, without any consideration for the
 % context. \Cref{tab:quoted-hamza} gives the equivalents for all the
@@ -1455,7 +1520,7 @@ consonants, though three of them are also used as vowels
 % Aside from that usage, the \enquote{pipe} character is used to
 % prevent almost any of the contextual analysis rules that are
 % described above from being applied. Two examples have already been
-% given to demonstrate how this particular mechanism works in
+% given to demonstrate how that particular mechanism works in
 % \vref{fn:pipe-allah-01} and in \vref{fn:pipe-madda}. One more example
 % follows:---
 % \begin{quote}
@@ -1685,7 +1750,7 @@ consonants, though three of them are also used as vowels
 % \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
+% before \arb[trans]{'alifu 'l-wa.sli}. In that 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
@@ -1824,7 +1889,7 @@ the predicate\ldots} "ibnu \cap{`amriNU}}
 % 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
+% for that, 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
@@ -1964,7 +2029,7 @@ wa-ya.sIru ta.hta 'l-jildi
 %    \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{arabluatex}%
-[2016/04/27 v1.1.1 ArabTeX-like interface for LuaLaTeX]
+[2016/05/08 v1.2 ArabTeX-like interface for LuaLaTeX]
 \RequirePackage{ifluatex}
 %    \end{macrocode}
 % \package{arabluatex} requires \LuaLaTeX\ of course. Issue a warning
@@ -2061,6 +2126,8 @@ wa-ya.sIru ta.hta 'l-jildi
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\SetArbEasy}
+%   \changes{v1.2}{2016/05/08}{New \cs{SetArbEasy}/\cs{SetArbDflt} for
+%   \enquote*{modern} or \enquote*{classic} Arabic styles.}
 % \begin{macro}{\SetArbDflt}
 %   By default, \package{arabluatex} applies complex rules to generate
 %   euphonic \arb[trans]{ta^sdId}, \arb[trans]{'alif mamdUdaT}
@@ -2068,8 +2135,7 @@ wa-ya.sIru ta.hta 'l-jildi
 %   selected, either |voc|, |fullvoc| or |trans|. Such refinements can
 %   be discarded with \cs{SetArbEasy}, either globally in the preamble
 %   or at any point of the document. Default complex rules can be set
-%   back at any point of the document with \cs{\SetArbDflt}
-%   \changes{}{}{}
+%   back at any point of the document with \cs{SetArbDflt}.
 %    \begin{macrocode}
 \def\al@arb@rules{dflt}
 \NewDocumentCommand{\SetArbEasy}{}{\def\al@arb@rules{easy}}