From c4bb186ab38a68a4f44028848d3bfbecb9ee84bb Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Fri, 16 Dec 2016 21:21:44 +0100 Subject: verse: done documenting; getting close to v1.6 --- arabluatex.dtx | 321 ++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file 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 @@ %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\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] % % %<*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, ...] + + \end{arabverse} +\end{arabluaverbatim} +% \iffalse +% +% \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 +% +% \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 +% +% \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 +% +% \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 +% +% \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 +% +% \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% } -- cgit v1.2.3