\StretchBayt[true|false]: added option to remove stretching from lines of Arabic poetryv1.20

1 files changed, 123 insertions, 15 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 4d3fb48..735c95b 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 % ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX
-% Copyright (C) 2016--2020  Robert Alesssi
+% Copyright (C) 2016--2020  Robert Alessi
 %
 % Please send error reports and suggestions for improvements to Robert
 % Alessi <alessi@robertalessi.net>
@@ -27,7 +27,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{arabluatex}
 %<*package>
-    [2020/03/15 v1.19 ArabTeX for LuaLaTeX]
+    [2020/03/23 v1.20 ArabTeX for LuaLaTeX]
 %</package>
 %
 %<*driver>
@@ -166,7 +166,7 @@
 \babelfont{sf}{NewComputerModern Sans}
 \babelfont{tt}{NewComputerModern Mono}
 \usepackage{metalogox}
-\usepackage{arabluatex}[2020/03/15]
+\usepackage{arabluatex}[2020/03/23]
 \SetArbUp{\textsuperscript{\thinspace#1}} % Old Standard needs this
 \usepackage[nopar]{quran}
 \usepackage[noindex]{nameauth}
@@ -269,7 +269,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{1014}
+% \CheckSum{1059}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -2187,7 +2187,7 @@
 % environment must end with |\\|.
 %
 % \DescribeEnv{arabverse} The |arabverse| environment may take up to
-% six optional \enquote*{named arguments} each of which is set using
+% eight optional \enquote*{named arguments} each of which is set using
 % the syntax \meta{key}$=$\meta{value}, like so:---%
 % \iffalse
 %<*example>
@@ -2369,6 +2369,20 @@
 % warping may be even more perceptible in Roman than in Arabic
 % characters.
 %
+% \DescribeMacro{\StretchBayt} \cs{StretchBayt}\verb+[true|false]+
+% \hfill\tcboxverb{Default: true}\\
+% \NEWfeature{v1.20} \cs{StretchBayt} takes one optional argument,
+% either |true| or |false| and can be used to remove the stretching
+% form lines of Arabic poetry. As a side effect, there will be more
+% space between words, but this can be compensated by inserting double
+% hyphens between letters (on this technique, see
+% \vref{sec:tatwil}). Should it be desired to extend further the
+% strokes, four hyphens may be inserted (|----|), viz. a multiple of
+% two. \cs{StretchBayt} may be used at any point of the document, even
+% between two subsequent lines of poetry. Note that
+% \cs{StretchBayt}|[false]| may require to carefuly adjust the width
+% of the hemistichs to avoid overlapping.
+%
 % \paragraph{Footnotes}
 % Footnotes are not set by default inside the \cs{bayt} command, but
 % there are two easy ways to have them printed.
@@ -2429,13 +2443,16 @@
       \bayt{wuqUfaN bi-hA .sa.hbI `alayya ma.tiyya-hum}{yaqUlUna
         lA tahlik 'asaN_A wa-ta^gammali}\\
       \bayt{wa-'inna ^sifA'I `abraTuN muharAqaTuN}{fa-hal `inda
-        rasmiN dAsiriN min mu`awwali}\\
+        rasmiN dArisiN min mu`awwali}\\
     \end{linenumbers*}
   \end{arabverse}
 \end{code}
 % \iffalse
 %</example>
 % \fi%
+%
+% \medskip
+% \noindent\textbf{\cs{StretchBayt}|[true]| (Default)}:---
 % \begin{arab}[fullvoc]
 %   qAla imru'u 'l-\uc{q}aysi fI mu`allaqati-hi:
 % \end{arab}
@@ -2451,12 +2468,11 @@
 %     \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}\\
+%     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 muharAqaTuN}{fa-hal `inda rasmiN
-%     dAsiriN min mu`awwali}\\
+%     dArisiN min mu`awwali}\\
 %   \end{linenumbers*}
 % \end{arabverse}
 %
@@ -2477,14 +2493,71 @@
 %     \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}\\
+%     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 muharAqaTuN}{fa-hal `inda rasmiN
+%     dArisiN min mu`awwali}\\
+%   \end{linenumbers*}
+% \end{arabverse}
+% 
+% \medskip
+% \noindent\textbf{\cs{StretchBayt}|[false]|}:---
+% \StretchBayt[false]\\
+% In what follows, |width| has been set to |0.3\linewidth| and double
+% hyphens have been inserted between some letters to prolong their
+% horizontal strokes.
+% \begin{arab}[fullvoc]
+%   qAla imru'u 'l-\uc{q}aysi fI mu`allaqati-hi:
+% \end{arab}
+% 
+% \begin{arabverse}[mode=fullvoc, metre={(al-.darbu 'l-_tAnI mina
+%  'l-`arU.di 'l-'_Ul_A mina 'l-.tawIli)}, width=.3\linewidth]
+%  \SetArbDflt*
+%   \begin{linenumbers*}
+%     \bayt{qifA nabki min _dikr_A .habIbiN wa-manzili}{bi-saq.ti
+%     'l-liw_A bayna \uc{'l-d}a_hUli fa-\uc{.h}awmali}\\
+%     \bayt{fa-\uc{t}U.di.ha fa-'l-\uc{m}iqrATi lam ya`--fu
+%     rasmu---hA}{limA nasa^gat-hA mi--n ^gan----UbiN wa-^sam'ali}\\
+%     \bayt{ta--r_A ba--`ara 'l-'ar'Ami fI `ara.sAti-hA}{wa-qI--`Ani-hA
+%     ka-'anna---hu .ha----bbu fu--{l}--fu----li}\\
+%     \bayt{ka-'annI .ga--dATa 'l-bay--ni ya--wma ta.hammalUA}{lad_A
+%     samurAti 'l-.hayyi nAqifu .han.zali}\\
+%     \bayt{wuq--UfaN bi-hA .sa.hbI `a--layya ma--.tiyya---hu--m}
+%     {ya--q--Ul--Una lA tahli--k 'asaN_A wa-ta^gamma----li}\\
+%     \bayt{wa-'inna ^si----f----A'I `a--{b}----raTuN muharAqa----TuN}
+%     {fa---ha--l `inda rasmiN dArisiN min mu`awwali}\\
+%   \end{linenumbers*}
+% \end{arabverse}
+%
+% \medskip
+%
+% In what follows, |width| has been set to |0.375\linewidth| and
+% |\scriptsize| has been used so as to avoid overlapping.
+% \begin{arab}[trans]
+%   qAla imru'u 'l-\uc{q}aysi fI mu`allaqati-hi:
+% \end{arab}
+% 
+% \begin{arabverse}[mode=trans, metre={(al-.darbu 'l-_tAnI mina
+%  'l-`arU.di 'l-'_Ul_A mina 'l-.tawIli)}, width=.375\linewidth]
+%  \SetArbDflt*
+%  \scriptsize
+%   \begin{linenumbers*}
+%     \bayt{qifA nabki min _dikr_A .habIbiN wa-manzili}{bi-saq.ti
+%     'l-liw_A bayna \uc{'l-d}a_hUli fa-\uc{.h}awmali}\\
+%     \bayt{fa-\uc{t}U.di.ha fa-'l-\uc{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 muharAqaTuN}{fa-hal `inda rasmiN
-%     dAsiriN min mu`awwali}\\
+%     dArisiN min mu`awwali}\\
 %   \end{linenumbers*}
 % \end{arabverse}
+% \StretchBayt[true]
 % 
 % \section{Special applications}
 % \label{sec:special-applications}
@@ -4883,6 +4956,14 @@
 %   \arb[trans]{tadwIr}. In some of these cases, the hemistichs may be
 %   connected by a prominent horizontal flexible stroke which is drawn
 %   by the \cs{al@verse@stroke} command.
+% \begin{macro}{\StretchBayt}
+% \changes{v1.20}{2020/03/23}{Optionally removes stretching from lines
+% of poetry} \cs{StretchBayt}\oarg{true\textbar false} Allows to
+% remove stretching and undesirable warping effect from Arabic lines of
+% poetry. This command accepts one fixed optional argument, either
+% |true| or |false|, and may be used either in the preamble or at any
+% point of the document. By default, it is set to |true|.
+% \end{macro}
 % \begin{macro}{\SetHemistichDelim}
 %   \changes{v1.6}{2016/12/17}{New \cs{SetHemistichDelim} command for
 %   changing the default delimiter between hemistichs} A hemistich
@@ -4892,6 +4973,21 @@
 %   point of the document to change this default setting.
 % \end{macro}
 %    \begin{macrocode}
+\newif\ifal@warp@bayt
+\al@warp@bayttrue
+\NewDocumentCommand{\StretchBayt}{O{true}}{
+  \edef\oarg@true{true}
+  \edef\oarg@false{false}
+  \edef\@tempa{#1}
+  \ifx\@tempa\oarg@true\al@warp@bayttrue
+  \else
+  \ifx\@tempa\oarg@false\al@warp@baytfalse
+  \else
+  \PackageError{arabluatex}{\string\StretchBayt\space must be
+    either 'true' or 'false'}{}
+  \fi
+  \fi
+}
 \NewDocumentCommand{\arb@utf}{m}{%
   \ifal@verse@utf\txarb{#1}\else\arb{#1}\fi}
 \def\al@hemistich@delim{*}
@@ -4901,7 +4997,11 @@
   \IfBooleanTF{#1}{\relax}{\relax}%
   \ifdefined\savenotes\savenotes\else\fi%
   \edef\al@tatweel{--}%
-  \adjustbox{width=\al@bayt@width, height=\Height}{\arb@utf{#2}}%
+  \ifal@warp@bayt%
+    \adjustbox{width=\al@bayt@width, height=\Height}{\arb@utf{#2}}%
+  \else%
+    \makebox[\al@bayt@width][s]{\arb@utf{#2}}%
+  \fi%
   \IfNoValueTF{#3}{%
     \ifal@verse@delim\makebox[\al@gutter@width][c]{\al@hemistich@delim}%
     \else%
@@ -4917,11 +5017,19 @@
     \fi%
     \else%
     \ifx\al@mode\al@mode@trans%
-    \adjustbox{width=\al@gutter@width, height=\Height}{\arb@utf{#3}}%
+    \ifal@warp@bayt%
+      \adjustbox{width=\al@gutter@width, height=\Height}{\arb@utf{#3}}%
+    \else%
+      \makebox[\al@gutter@width][s]{\arb@utf{#3}}%
+    \fi%
     \else%
     \makebox[\al@gutter@width][s]{\arb@utf{#3}}%
     \fi\fi}%
-  \adjustbox{width=\al@bayt@width, height=\Height}{\arb@utf{#4}}%
+  \ifal@warp@bayt%
+    \adjustbox{width=\al@bayt@width, height=\Height}{\arb@utf{#4}}%
+  \else%
+    \makebox[\al@bayt@width][s]{\arb@utf{#4}}%
+  \fi%
   \ifdefined\spewnotes\spewnotes\else\fi%
 }
 %    \end{macrocode}