a few additions in the documentation

1 files changed, 39 insertions, 32 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 041620c..e1fda64 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -516,18 +516,20 @@
 % \DescribeMacro{\SetArbEasy} \NEWfeature{v1.4.4}
 % \DescribeMacro{\SetArbEasy*} \DescribeMacro{\SetArbDflt} Such
 % refinements as \enquote*{classic} \arb[trans]{maddaT} may be
-% discarded by the command \cs{SetArb\allowbreak{}Easy}, either globally in the
-% preamble or locally at any point of the document. The difference
-% between \cs{SetArbEasy} and its \enquote*{starred} version
-% \cs{SetArbEasy*} is that the former keeps the \arb[trans]{sukUn}
-% that is generated by the |fullvoc| mode, while the latter further
-% takes it away. Default \enquote*{classic} rules may be set back at
-% any point of the document with the command
+% discarded by the command \cs{SetArb\allowbreak{}Easy}, either
+% globally in the preamble or locally at any point of the
+% document. The difference between \cs{SetArbEasy} and its
+% \enquote*{starred} version \cs{SetArbEasy*} is that the former keeps
+% the \arb[trans]{sukUn} that is generated by the |fullvoc| mode,
+% while the latter further takes it away. Default \enquote*{classic}
+% rules may be set back at any point of the document with the command
 % \cs{SetArbDflt}. \NEWfeature{v1.6}
 % \DescribeMacro{\SetArbDflt*}Assimilation rules laid on
 % \vref{ref:assimilation} may also be applied by the
 % \enquote*{starred} version of this command \cs{SetArbDflt*} either
-% in the preamble or at any point of the document. Examples follow:---
+% in the preamble or at any point of the document.\footnote{For an
+% example, see \vref{sec:poetry-example}.} Examples
+% follow:---
 % \begin{compactenum}[(a)]
 % \item \cs{SetArbDflt}:
 %   \begin{compactenum}[i.]
@@ -1804,7 +1806,7 @@ vowels (see §~3).
 % The description of the optional arguments follows:---
 %
 % \DescribeOption{mode} |mode|$=$\meta{mode}, either |voc|, |fullvoc|,
-% |novoc| or |trans|. The default mode is the one which is set at load
+% |novoc| or |trans|. The default mode is the one that is set at load
 % time as already seen \vref{sec:options}.
 %
 % \DescribeOption{width} |width|$=$\meta{length}
@@ -1891,10 +1893,10 @@ vowels (see §~3).
 % 'l-wa.sl-i},\footnote{See \vref{ref:definite-article}} while the
 % following two select the figure of the letter \arb[trans]{lAm}
 % connected with a following letter. In the \arb[trans]{`a^guz}, the
-% first two hyphens select the letter \arb[trans]{yA'} connected with
-% a preceding letter, while the last one is simply discarded in this
-% mode, but may appear as it should, if the |trans| mode be
-% selected:---
+% last two hyphens select the letter \arb[trans]{yA'} connected with a
+% preceding letter, while the first one is simply discarded in this
+% mode, but still may appear as it should, if the |trans| mode be
+% selected:---%
 % \iffalse
 %<*example>
 % \fi
@@ -1930,7 +1932,7 @@ vowels (see §~3).
 % \arb[trans]{.sadr} and the second to the \arb[trans]{`a^guz}. One
 % solution to avoid splitting this word in such a way is to write
 % inside the \arb[trans]{tadwIr} the part of it that belongs to either
-% hemistichs, without omitting to add a space after it. In the second
+% hemistich, without omitting to add a space after it. In the second
 % line, the word \arb{'ummu} should be split into \arb{'um"-- --mu},
 % so that the only way to avoid splitting it into two parts is to
 % write it all inside the \arb[trans]{tadwIr}. In that case, as the
@@ -1952,9 +1954,9 @@ vowels (see §~3).
 % there are two easy ways to have them printed.
 %
 % If they are little in number, each footnote may be split into pairs
-% of |\footnotemark{}| (please mind the braces) in either argument of
-% the \cs{bayt} command and |\footnotetext{}| outside the \cs{bayt}
-% command.
+% of \cs{footnote\allowbreak{}mark}|{}| (please mind the braces) in
+% either argument of the \cs{bayt} command and \cs{footnotetext}
+% outside the \cs{bayt} command.
 %
 % If the footnotes are abundant in number, it is advised to load the
 % \package{footnote} package which \package{arabluatex} will then use
@@ -1970,17 +1972,22 @@ vowels (see §~3).
 %
 % \subsection{Example}
 % \label{sec:poetry-example}
-% Here follows the first lines of \arb[trans]{\upshape{}\cap{i}mru'u
-% 'l-\cap{q}aysi}'s \arb[trans]{\cap{m}u`allaqaT}:---%
+% Here follow the first lines of \arb[trans]{\upshape{}\cap{i}mru'u
+% 'l-\cap{q}aysi}'s \arb[trans]{\cap{m}u`allaqaT}. In this example,
+% \cs{SetArbDflt*} has been selected so as to mark the
+% \arb[trans]{'id.gAm} that is fit to this declamatory
+% poetry:---\footnote{See \vref{sec:classic-modern-typesetting} for
+% more information.}%
 % \iffalse
 %<*example>
 % \fi
 \begin{arabluaverbatim}
 \begin{arab}[fullvoc]
-  qAla \cap{i}mru'u 'l-\cap{q}aysi fI ^si`ri-hi 'l-\cap{m}u`allaqaTi:
+  qAla \cap{i}mru'u 'l-\cap{q}aysi fI mu`allaqati-hi:
 \end{arab}
 
-\begin{arabverse}[mode=fullvoc, metre=(al-.tawIlu)]
+\begin{arabverse}[mode=fullvoc, metre={(al-.darbu 'l-_tAnI mina
+  'l-`arU.di 'l-'_Ul_A mina 'l-.tawIli)}]
   \SetArbDflt*
   \begin{linenumbers*}
     \bayt{qifA nabki min _dikr_A .habibiN wa-manzili}{bi-saq.ti
@@ -1989,7 +1996,7 @@ vowels (see §~3).
       rasmu-hA}{limA nasa^gat-hA min ^ganUbiN wa-^sam'ali}\\
     \bayt{tar_A ba`ara 'l-'ar'Ami fI `ara.sAti-hA}{wa-qI`Ani-hA
       ka-'anna-hu .habbu fulfuli}\\
-    \bayt{ka-'annI .gadATa 'l-bayni yawma ta.hammalUA}{lad_A
+    \bayt{ka-'annI .gadATa 'l-bayni yawma ta.hammalUA}{laday
       samurAti 'l-.hayyi nAqifu .han.zali}\\
     \bayt{wuqUfaN bi-hA .sa.hbI `alayya ma.tiyya-hum}{yaqUlUna lA
       tahlik 'asaN_A wa-ta^gammali}\\
@@ -2002,12 +2009,12 @@ vowels (see §~3).
 %</example>
 % \fi%
 % \begin{arab}[fullvoc]
-%   qAla \cap{i}mru'u 'l-\cap{q}aysi fI ^si`ri-hi
-%   'l-\cap{m}u`allaqaTi:
+%   qAla \cap{i}mru'u 'l-\cap{q}aysi fI mu`allaqati-hi:
 % \end{arab}
 % 
-% \begin{arabverse}[mode=fullvoc, metre=(al-.tawIlu), width=.25\linewidth]
-%   \SetArbDflt*
+% \begin{arabverse}[mode=fullvoc, metre={(al-.darbu 'l-_tAnI mina
+%  'l-`arU.di 'l-'_Ul_A mina 'l-.tawIli)}, width=.25\linewidth]
+%  \SetArbDflt*
 %   \begin{linenumbers*}
 %     \bayt{qifA nabki min _dikr_A .habibiN wa-manzili}{bi-saq.ti
 %     'l-liw_A bayna \cap{'l-da_hUl}i wa-\cap{.h}awmali}\\
@@ -2015,7 +2022,7 @@ vowels (see §~3).
 %     rasmu-hA}{limA nasa^gat-hA min ^ganUbiN wa-^sam'ali}\\
 %     \bayt{tar_A ba`ara 'l-'ar'Ami fI `ara.sAti-hA}{wa-qI`Ani-hA
 %     ka-'anna-hu .habbu fulfuli}\\
-%     \bayt{ka-'annI .gadATa 'l-bayni yawma ta.hammalUA}{lad_A
+%     \bayt{ka-'annI .gadATa 'l-bayni yawma ta.hammalUA}{laday
 %     samurAti
 %     'l-.hayyi nAqifu .han.zali}\\
 %     \bayt{wuqUfaN bi-hA .sa.hbI `alayya ma.tiyya-hum}{yaqUlUna lA
@@ -2026,12 +2033,12 @@ vowels (see §~3).
 % \end{arabverse}
 % 
 % \begin{arab}[trans]
-%   qAla \cap{i}mru'u 'l-\cap{q}aysi fI ^si`ri-hi
-%   'l-\cap{m}u`allaqaTi:
+%   qAla \cap{i}mru'u 'l-\cap{q}aysi fI mu`allaqati-hi:
 % \end{arab}
 % 
-% \begin{arabverse}[mode=trans, metre=(al-.tawIlu), width=.4\linewidth]
-%   \SetArbDflt*
+% \begin{arabverse}[mode=trans, metre={(al-.darbu 'l-_tAnI mina
+%  'l-`arU.di 'l-'_Ul_A mina 'l-.tawIli)}, width=.4\linewidth]
+%  \SetArbDflt*
 %   \begin{linenumbers*}
 %     \bayt{qifA nabki min _dikr_A .habibiN wa-manzili}{bi-saq.ti
 %     'l-liw_A bayna \cap{'l-da_hUl}i wa-\cap{.h}awmali}\\
@@ -2039,7 +2046,7 @@ vowels (see §~3).
 %     rasmu-hA}{limA nasa^gat-hA min ^ganUbiN wa-^sam'ali}\\
 %     \bayt{tar_A ba`ara 'l-'ar'Ami fI `ara.sAti-hA}{wa-qI`Ani-hA
 %     ka-'anna-hu .habbu fulfuli}\\
-%     \bayt{ka-'annI .gadATa 'l-bayni yawma ta.hammalUA}{lad_A
+%     \bayt{ka-'annI .gadATa 'l-bayni yawma ta.hammalUA}{laday
 %     samurAti
 %     'l-.hayyi nAqifu .han.zali}\\
 %     \bayt{wuqUfaN bi-hA .sa.hbI `alayya ma.tiyya-hum}{yaqUlUna lA