verse: done documenting; getting close to v1.6

1 files changed, 297 insertions, 24 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index e1a5d29..041620c 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/11/14 v1.5 An ArabTeX-like interface for LuaLaTeX]
+    [2016/12/15 v1.6 An ArabTeX-like interface for LuaLaTeX]
 %</package-info>
 %
 %<*driver>
@@ -145,7 +145,7 @@
 \defaultfontfeatures{RawFeature={+liga}}
 \setmainfont{Old Standard}[SmallCapsFont={Latin Modern Roman Caps},
   RawFeature={+mark;+ccmp;+ss05;+ss06}]
-\usepackage{arabluatex}[2016/11/14]
+\usepackage{arabluatex}[2016/12/15]
 \usepackage[nopar]{quran}
 \usepackage{varioref}
 \usepackage{hypdoc}
@@ -160,6 +160,7 @@
 \quotingsetup{noorphans, rightmargin=0pt}
 \renewcommand*{\quotingfont}{\footnotesize}
 \usepackage[position=below]{caption}
+\usepackage{lineno}
 \usepackage{longtable}
 \usepackage{booktabs}
 \usepackage[defaultlines=3,all]{nowidow}
@@ -1203,6 +1204,7 @@ vowels (see §~3).
 % \end{compactenum}
 %
 % \paragraph{The definite article and the \arb[trans]{'alif-u 'l-wa.sl-i}}
+% \label{ref:definite-article}
 % At the beginning of a sentence, \arb[fullvoc]{"a} is never written,
 % as \arb[fullvoc]{'l-.hamd-u li-ll_ah-i}; instead, to indicate that
 % the \arb[trans]{'alif} is a connective \arb[trans]{'alif}
@@ -1778,6 +1780,275 @@ vowels (see §~3).
 %   \arb[trans]{\abjad{45}: kitAbu-hu fI 'l-\cap{`AdAt-i}}.
 % \end{quote}
 %
+% \section{Arabic poetry}
+% \label{sec:poetry}
+% \NEWfeature{v1.6} \package{arabluatex} provides a special
+% environment for typesetting Arabic poetry. Every line in this
+% environment must end with |\\|.
+%
+% \DescribeEnv{arabverse} The |arabverse| environment may take up to
+% six optional \enquote*{named arguments} each of which is set using
+% the syntax \meta{key}$=$\meta{value}, like so:---%
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+  \begin{arabverse}[key1=value1, key2=value2, ...]
+    <verses>
+  \end{arabverse}
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi
+%
+% 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
+% time as already seen \vref{sec:options}.
+%
+% \DescribeOption{width} |width|$=$\meta{length}
+% \hfill\arabluaverb{Default: 0.3\linewidth}\\ The default width of
+% each hemistich that the verse consists of. It may be expressed in
+% any accepted unit of measurement, such as |4cm| or |2in|. However,
+% one must keep in mind that the total length of the two hemistichs
+% added to the one of the gutter that separates them must not exceed
+% the length of the base line, unless one wishes to have the
+% hemistichs distributed on subsequent lines.
+%
+% \DescribeOption{gutter} |gutter|$=$\meta{width}
+% \hfill\arabluaverb{Default: 0.15 x (hemistich width)}\\ The gutter
+% consists of the blank space that is between the two hemistichs. By
+% default, it is commensurate with the width of the hemistich, but it
+% may be expressed in any accepted unit of measurement as well.
+%
+% \DescribeOption{metre} |metre|$=$\meta{name}
+% \hfill\arabluaverb{Default: none}\\ If the name of the metre is
+% expressed, it is printed after the lines and set flush left in
+% |voc|, |fullvoc| and |novoc| modes or flush right in |trans| mode.
+%
+% \DescribeOption{delim} |delim|$=$|true|\verb+|+|false|
+% \hfill\arabluaverb{Default: false}\\ This named argument does not
+% need a value as it defaults to |true| if it is used. If so, a
+% delimiter is printed between each of the hemistichs. By default, it
+% is set to the \enquote*{star} character \enquote*{*}. The command
+% \DescribeMacro{\SetHemistichDelim}\cs{SetHemistichDelim}\marg{delimiter}
+% may be used at any point of the document to change this default
+% setting.
+%
+% \DescribeOption{utf} |utf|$=$|true|\verb+|+|false|
+% \hfill\arabluaverb{Default: false}\\ As the preceding one, this
+% named argument does not need a value as it defaults to |true| if it
+% is used. If so, unicode Arabic input is expected in the |arabverse|
+% environment instead of \textsc{ascii} Arab\TeX\ or Buckwalter input
+% schemes. See \vref{sec:unicode-input} for more details.
+%
+% \DescribeMacro{\bayt} Inside the |arabverse| environment, each line
+% is typeset by the command \cs{bayt} which takes two mandatory
+% arguments and may accept one optional argument. Additionally, every
+% \cs{bayt} command \emph{must} be followed with |\\| like so:---%
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}[text only]
+  \cs{bayt}\marg{\arb[trans]{.sadr}}\oarg{\arb[trans]{tadwIr}}%
+  \marg{\arb[trans]{`ajuz}}|\\|
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi
+%
+% That two subsequent hemistichs should be connected with one another
+% is technically named \arb[trans]{tadwIr}. Should that happen, either
+% the \arb[trans]{.sadr} or the \arb[trans]{`ajuz} or both of them,
+% may be connected to one another by letters that are naturally bound
+% to the following or the preceding ones over the
+% \arb[trans]{tadwIr}. The optional argument of the \cs{bayt} command
+% is designed to deal with the various situations that may arise:---
+% \begin{compactenum}[(a)]
+% \item If the two hemistichs be connected with one another by a
+% prominent horizontal flexible stroke, the \arb[trans]{tatwIl} should
+% be used, like so: |[--]| (see \vref{sec:tatwil}). Of course, the
+% ending word of the \arb[trans]{.sadr} and the word at the
+% commencement of the \arb[trans]{`a^guz} must have the
+% \arb[trans]{ta.twIl} too so that the proper shapes of the letters be
+% selected. Consider for example the following:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+\begin{arabverse}[mode=fullvoc, width=.3\linewidth]
+  \bayt{lA 'ar_A man `ahidtu fI-hA fa-'abkI 'l---}[--]{---yawma
+    dalhaN wa-mA yu.hIru 'l-bukA'u}\\
+\end{arabverse}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi%
+% As one can see, \emph{triple hyphens} have been used. In the
+% \arb[trans]{.sadr}, the first hyphen triggers the rules that are
+% related to the definite article and the \arb[trans]{'alif-u
+% '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:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+\begin{arabverse}[mode=trans, width=.4\linewidth]
+  \bayt{lA 'ar_A man `ahidtu fI-hA fa-'abkI 'l---}[--]{---yawma
+    dalhaN wa-mA yu.hIru 'l-bukA'u}\\
+\end{arabverse}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi%
+% \item In some other cases, it may seem difficult, if not fairly
+%   impossible, to split a given word into two parts. This happens
+%   mostly because of the \arb[trans]{^saddaT}. Consider for example
+%   the following:---
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluacode}
+\begin{arabverse}[mode=fullvoc, width=.25\linewidth, gutter=1cm]
+  \bayt{.gayra 'annI qad 'asta`Inu `al_A 'l-ha--}[--mmi ]{'i_dA
+  _haffa bi-'l-_tawiyyi 'l-na^gA'u}\\
+  \bayt{bi-zaf--UfiN ka-'anna-hA hiq--laTuN}[ 'ummu ]{ri'AliN
+  dawwiyyaTuN saqfA'u}\\
+\end{arabverse}
+\end{arabluacode}
+% \iffalse
+%</example>
+% \fi%
+% In the first line, the word \arb{al-hammi} should be split into
+% \arb{al-ham"-- --mi} as the first part of it belongs to the
+% \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
+% 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
+% word is to be placed in the middle, it has been surrounded by
+% spaces.
+% \end{compactenum}
+%
+% \paragraph{Scaling and distortion of characters}
+% The |arabverse| environment and the \cs{bayt} command are designed
+% to typeset the verses in a two-column, fixed width layout. This may
+% result in somewhat distorted text. Should that happen, one may adapt
+% the layout by modifying the values of the above described |width|
+% and |gutter| named arguments until the visual aspect of the layout
+% be satisfactory. It has to be noted that distortion and warping may
+% be even more perceptible in Roman than in Arabic characters.
+%
+% \paragraph{Footnotes}
+% Footnotes are not set by default inside the \cs{bayt} command, but
+% 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.
+%
+% If the footnotes are abundant in number, it is advised to load the
+% \package{footnote} package which \package{arabluatex} will then use
+% to typeset any kind of footnote that is called from the arguments of
+% the \cs{bayt} command.
+%
+% \paragraph{Line numbering}
+% Inside the |arabverse| environment, the |linenumbers| environment of
+% the \package{lineno} package may be used to have the lines of
+% succeeding verses numbered. Please refer to the documentation of
+% this package for more information or to the example below for a
+% basic implementation of this technique.
+%
+% \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}:---%
+% \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:
+\end{arab}
+
+\begin{arabverse}[mode=fullvoc, metre=(al-.tawIlu)]
+  \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}\\
+    \bayt{fa-\cap{t}Udi.ha fa-'l-\cap{m}iqrATi lam ya`fu
+      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
+      samurAti 'l-.hayyi nAqifu .han.zali}\\
+    \bayt{wuqUfaN bi-hA .sa.hbI `alayya ma.tiyya-hum}{yaqUlUna lA
+      tahlik 'asaN_A wa-ta^gammali}\\
+    \bayt{wa-'inna ^sifA'I `abraTuN muhrAqaTuN}{fa-hal `inda rasmiN
+      dAsiriN min mu`awwali}\\
+  \end{linenumbers*}
+\end{arabverse}
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi%
+% \begin{arab}[fullvoc]
+%   qAla \cap{i}mru'u 'l-\cap{q}aysi fI ^si`ri-hi
+%   'l-\cap{m}u`allaqaTi:
+% \end{arab}
+% 
+% \begin{arabverse}[mode=fullvoc, metre=(al-.tawIlu), 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}\\
+%     \bayt{fa-\cap{t}Udi.ha fa-'l-\cap{m}iqrATi lam ya`fu
+%     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
+%     samurAti
+%     'l-.hayyi nAqifu .han.zali}\\
+%     \bayt{wuqUfaN bi-hA .sa.hbI `alayya ma.tiyya-hum}{yaqUlUna lA
+%     tahlik 'asaN_A wa-ta^gammali}\\
+%     \bayt{wa-'inna ^sifA'I `abraTuN muhrAqaTuN}{fa-hal `inda rasmiN
+%     dAsiriN min mu`awwali}\\
+%   \end{linenumbers*}
+% \end{arabverse}
+% 
+% \begin{arab}[trans]
+%   qAla \cap{i}mru'u 'l-\cap{q}aysi fI ^si`ri-hi
+%   'l-\cap{m}u`allaqaTi:
+% \end{arab}
+% 
+% \begin{arabverse}[mode=trans, metre=(al-.tawIlu), 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}\\
+%     \bayt{fa-\cap{t}Udi.ha fa-'l-\cap{m}iqrATi lam ya`fu
+%     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
+%     samurAti
+%     'l-.hayyi nAqifu .han.zali}\\
+%     \bayt{wuqUfaN bi-hA .sa.hbI `alayya ma.tiyya-hum}{yaqUlUna lA
+%     tahlik 'asaN_A wa-ta^gammali}\\
+%     \bayt{wa-'inna ^sifA'I `abraTuN muhrAqaTuN}{fa-hal `inda rasmiN
+%     dAsiriN min mu`awwali}\\
+%   \end{linenumbers*}
+% \end{arabverse}
+% 
 % \section{Special applications}
 % \label{sec:special-applications}
 % \paragraph{Linguistics}
@@ -2662,7 +2933,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 %    \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{arabluatex}%
-[2016/11/14 v1.5 An ArabTeX-like interface for LuaLaTeX]
+[2016/12/15 v1.6 An ArabTeX-like interface for LuaLaTeX]
 \RequirePackage{ifluatex}
 %    \end{macrocode}
 % \package{arabluatex} requires \LuaLaTeX\ of course. Issue a warning
@@ -2790,7 +3061,7 @@ wa-ya.sIru ta.hta 'l-jild-i
 %   \cs{SetArbEasy*} takes it away. Default complex rules can be set
 %   back at any point of the document with \cs{SetArbDflt}.
 % \begin{macro}{\SetArbDflt*}
-%   \changes{v1.6}{2016/11/30}{This starred version applies the
+%   \changes{v1.6}{2016/12/15}{This starred version applies the
 %   assimilation rules in addition to what \cs{SetArbDflt} already
 %   does.} As of v1.6, \package{arabluatex} does not applies any more
 %   the assimilation rules that are laid on \vref{ref:assimilation}; a
@@ -2967,18 +3238,18 @@ wa-ya.sIru ta.hta 'l-jild-i
 %    \end{macrocode}
 % \end{environment}
 % \begin{environment}{arabverse}
-%   \changes{v1.6}{2016/11/30}{New environment \texttt{arabverse} for
+%   \changes{v1.6}{2016/12/15}{New environment \texttt{arabverse} for
 %   typesetting Arabic poetry} The |arabverse| environment may receive
-%   different options: |width|, |tadwirwidth|, |metre|, |utf| and
-%   |mode|; all of them are defined here just before the |arabverse|
-%   environment:
+%   different options: |mode|, |width|, |gutter|, |metre|, |utf|
+%   and |delim|; all of them are defined here just before the
+%   |arabverse| environment:
 %    \begin{macrocode}
 \newlength{\al@bayt@width}
-\newlength{\al@tadwir@width}
+\newlength{\al@gutter@width}
 \setlength{\al@bayt@width}{.3\textwidth}
-\setlength{\al@tadwir@width}{.15\al@bayt@width}
+\setlength{\al@gutter@width}{.15\al@bayt@width}
 \define@key[al]{verse}{width}{\setlength{\al@bayt@width}{#1}}
-\define@key[al]{verse}{tadwirwidth}{\setlength{\al@tadwir@width}{#1}}
+\define@key[al]{verse}{gutter}{\setlength{\al@gutter@width}{#1}}
 \define@key[al]{verse}{metre}{\arb{#1}}
 \define@boolkey[al]{verse}{utf}[true]{}
 \define@boolkey[al]{verse}{delim}[true]{}
@@ -2994,23 +3265,22 @@ wa-ya.sIru ta.hta 'l-jild-i
   \ifx\al@mode\al@mode@trans%
   \ifal@verse@utf\setRL\else\setLR\fi%
   \else\setRL\fi}%
-{\hfill\setkeys[al]{verse}[width,tadwirwidth,utf,mode]{#1}\egroup}
+{\hfill\setkeys[al]{verse}[width,gutter,utf,mode]{#1}\egroup}
 %    \end{macrocode}
 % \begin{macro}{\bayt}
-%   \changes{v1.6}{2016/11/30}{New macro \cs{bayt} for typesetting
+%   \changes{v1.6}{2016/12/15}{New macro \cs{bayt} for typesetting
 %   each verse inside the \texttt{arabverse} environment} Each verse
 %   consists of two hemistichs; therefore the command \cs{bayt} takes
 %   two arguments, the first receives the \arb[trans]{.sadr} and the
-%   second the \arb[trans]{`ajuz}. That two subsequent hemistishs
+%   second the \arb[trans]{`ajuz}. That two subsequent hemistichs
 %   should be connected with one another is technically named
-%   \arb[trans]{tadwIr}. In some of these cases, the hemistishs may be
+%   \arb[trans]{tadwIr}. In some of these cases, the hemistichs may be
 %   connected by a prominent horizontal flexible stroke which is drawn
 %   by the command \cs{al@verse@stroke}.
 % \begin{macro}{\SetHemistichDelim}
-%   \changes{v1.6}{2016/11/30}{New command \cs{SetHemistichDelim} for
+%   \changes{v1.6}{2016/12/15}{New command \cs{SetHemistichDelim} for
 %   changing the default delimiter between hemistichs} A hemistich
-%   delimiter also must be defined for there is no gutter between
-%   hemistichs in |trans| mode. By default, it is set to the
+%   delimiter also may be defined. By default, it is set to the
 %   \enquote*{star} character: |*|. The command
 %   \cs{SetHemistichDelim}\marg{delimiter} may be used at any point of
 %   the document to change this default setting.
@@ -3026,21 +3296,24 @@ wa-ya.sIru ta.hta 'l-jild-i
   \edef\al@tatweel{--}%
   \adjustbox{width=\al@bayt@width, height=\Height}{\arb@utf{#1}}%
   \IfNoValueTF{#2}{%
-    \ifal@verse@delim\makebox[\al@tadwir@width][c]{\al@hemistich@delim}%
+    \ifal@verse@delim\makebox[\al@gutter@width][c]{\al@hemistich@delim}%
     \else%
-    \hspace{\al@tadwir@width}%
+    \hspace{\al@gutter@width}%
     \fi
   }{%
     \edef\@tempa{#2}%
     \ifx\@tempa\al@tatweel%
     \ifx\al@mode\al@mode@trans%
-    \hspace{\al@tadwir@width}%
+    \hspace{\al@gutter@width}%
     \else%
-    \makebox[\al@tadwir@width][s]{\al@verse@stroke}%
+    \makebox[\al@gutter@width][s]{\al@verse@stroke}%
     \fi%
     \else%
-    \adjustbox{center=\al@tadwir@width, height=\Height}{\arb@utf{#2}}%
-    \fi}%
+    \ifx\al@mode\al@mode@trans%
+    \adjustbox{width=\al@gutter@width, height=\Height}{\arb@utf{#2}}%
+    \else%
+    \makebox[\al@gutter@width][s]{\arb@utf{#2}}%
+    \fi\fi}%
   \adjustbox{width=\al@bayt@width, height=\Height}{\arb@utf{#3}}%
   \ifdefined\spewnotes\spewnotes\else\fi%
 }