From 429eb1e3b9149985e8fdef15e066b02ca8dfa24a Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Fri, 15 Jun 2018 12:01:43 +0200 Subject: documenting the new features. added \arbcolor[]{} in .el style file --- arabluatex.dtx | 161 ++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 102 insertions(+), 59 deletions(-) (limited to 'arabluatex.dtx') diff --git a/arabluatex.dtx b/arabluatex.dtx index 790b13c..3b74ab6 100644 --- a/arabluatex.dtx +++ b/arabluatex.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % ArabLuaTeX -- Processing ArabTeX notation under LuaLaTeX -% Copyright (C) 2016--2018 Robert Alessi +% Copyright (C) 2016--2018 Robert Alesssi % % Please send error reports and suggestions for improvements to Robert % Alessi @@ -74,7 +74,7 @@ maintainer = {Hosny, Khaled}, title = {Amiri}, indextitle = {Amiri}, - date = {2015-09-20}, + date = {2017-12-13}, url = {http://www.amirifont.org/} } @@ -163,6 +163,7 @@ \usepackage{hyperxmp} \PassOptionsToPackage{pdfa}{hyperref} \usepackage{hypdoc} +\usepackage{bookmark} \usepackage{authblk} \hypersetup{unicode=true, colorlinks, allcolors=blue, linktocpage=true, pdfauthor={Robert Alessi}, pdftitle={The @@ -533,7 +534,7 @@ % of the \arb[trans]{kasraT} above the consonant may be obtained by % selecting the |ss05| feature of the Amiri font, like % so:---\footnote{See the documentation of \package{amiri}, -% \textcite[5]{pkg:amiri}.}\\ +% \textcite[6]{pkg:amiri}.}\\ % \arabluaverb{\newfontfamily\arabicfont{Amiri}[Script=Arabic,RawFeature={+ss05}]} % % Other Arabic fonts may behave differently. @@ -1081,19 +1082,19 @@ vowels (see §~3). % \arb[voc]{murU'aTuN} \arb[trans]{murU'aTuN}. % \end{quote} % -% \paragraph{\arb[trans]{'alif maq.sUraT}} It is written \meta{\_A} or -% \meta{Y}: +% \paragraph{\texorpdfstring{\arb[trans]{'alif maq.sUraT}}{ʾalif +% maqṣūrah}} It is written \meta{\_A} or \meta{Y}: % \begin{quote} % |al-fat_A| \arb[voc]{al-fat_A} \arb[trans]{al-fat_A}, |al-maqh_A| % \arb[voc]{al-maqh_A} \arb[trans]{al-maqh_A}, |'il_A| % \arb[voc]{'il_A} \arb[trans]{'il_A}. % \end{quote} % -% \paragraph{\arb[trans]{'alif} \emph{otiosum}} Said -% \arb[trans]{'alif-u 'l-wiqAyaT-i}, \enquote{the guarding -% \arb[trans]{'alif}}\,, after \arb[novoc]{U} at the end of a word, both -% when preceded by \arb[trans]{.dammaT} and by \arb[trans]{fat.haT} is -% written \meta{UA} or \meta{aW, aWA}: +% \paragraph{\texorpdfstring{\arb[trans]{'alif} \emph{otiosum}}{ʾalif +% otiosum}} Said \arb[trans]{'alif-u 'l-wiqAyaT-i}, \enquote{the +% guarding \arb[trans]{'alif}}\,, after \arb[novoc]{U} at the end of a +% word, both when preceded by \arb[trans]{.dammaT} and by +% \arb[trans]{fat.haT} is written \meta{UA} or \meta{aW, aWA}: % \begin{quote} % |na.sarUA| \arb[voc]{na.sarUA} \arb[trans]{na.sarUA}, |katabUA| % \arb[voc]{katabUA} \arb[trans]{katabUA}, |ya.gzUA| @@ -1102,8 +1103,9 @@ vowels (see §~3). % \arb[fullvoc]{banaWA}, \arb[trans]{banaWA}. % \end{quote} % -% \paragraph{\arb[trans]{'alif ma.h_dUfaT} and defective \arb[trans]{U, -% I}} They are written \meta{\_a, \_i \_u}: +% \paragraph{\texorpdfstring{\arb[trans]{'alif ma.h_dUfaT} and +% defective \arb[trans]{U, I}}{ʾalif maḥḏūfah and defective ū, ī}} +% They are written \meta{\_a, \_i \_u}: % \begin{quote} % |al-l_ah-u| \arb[voc]{al-l_ah-u} \arb[trans]{al-l_ah-u}, % |'il_ahuN| \arb[voc]{'il_ahuN} \arb[trans]{'il_ahuN}. @@ -1118,7 +1120,8 @@ vowels (see §~3). % \arb[trans]{al-\uc{`A.s_i}}. % \end{quote} % -% \paragraph{Silent \arb[novoc]{U}/\arb[novoc]{I}} +% \paragraph{\texorpdfstring{Silent +% \arb[novoc]{U}/\arb[novoc]{I}}{Silent ي/و}} % 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 that @@ -1136,11 +1139,12 @@ vowels (see §~3). % \arb[trans]{al-rib_aIT-u}. % \end{quote} % -% \paragraph{\arb[trans]{\uc{`amruNU}}, and the silent -% \arb[novoc]{U}} To that name a silent \arb[novoc]{U} is added to -% distinguish it from \arb[trans]{\uc{`umar-u}}: 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: +% \paragraph{\texorpdfstring{\arb[trans]{\uc{`amruNU}}, and the silent +% \arb[novoc]{U}}{ʿAmrun, and the silent و}} To that name a silent +% \arb[novoc]{U} is added to distinguish it from +% \arb[trans]{\uc{`umar-u}}: 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: % \begin{quote} % |`amruNU| \arb[voc]{`amruNU} \arb[trans]{`amruNU}, |`amraNU| % \arb[voc]{`amraNU} \arb[trans]{`amraNU}, |`amriNU| @@ -1159,7 +1163,7 @@ vowels (see §~3). % \arb[trans]{ribaNU}. % \end{quote} % -%\paragraph{\arb[trans]{tanwIn}} +% \paragraph{\texorpdfstring{\arb[trans]{tanwIn}}{tanwīn}} % The marks of doubled short vowels, \arb{BuN}, \arb{BaN}, \arb{BiN}, % are written \meta{uN, aN, iN} respectively. \package{arabluatex} % deals with special cases, such as \arb{BaN} taking an \arb[novoc]{A} @@ -1192,7 +1196,7 @@ vowels (see §~3). % \end{quote} % % \subsection{Other orthographic signs} -% \paragraph{\arb[trans]{tA' marbU.taT}} +% \paragraph{\texorpdfstring{\arb[trans]{tA' marbU.taT}}{tāʾ marbūṭah}} % It is written \meta{T}: % \begin{quote} % |madInaTuN| \arb[voc]{madInaTuN} \arb[trans]{madInaTuN}, @@ -1200,11 +1204,11 @@ vowels (see §~3). % |madInaTiN| \arb[voc]{madInaTiN} \arb[trans]{madInaTiN}. % \end{quote} % -% \paragraph{\arb[trans]{hamzaT}} \label{ref:hamza}It is written -% \meta{\texttt{'}}, its carrier being determined by contextual -% analysis. In case one wishes to bypass this mechanism, he can use -% the \enquote{quoting} feature that is described below in -% \vref{sec:quoting}. +% \paragraph{\texorpdfstring{\arb[trans]{hamzaT}}{hamzah}} +% \label{ref:hamza}It is written \meta{\texttt{'}}, its carrier being +% determined by contextual analysis. In case one wishes to bypass this +% mechanism, he can use the \enquote{quoting} feature that is +% described below in \vref{sec:quoting}. % \begin{quote} % \textbf{Initial \arb[trans]{hamzaT}}: |'asaduN| \arb[voc]{'asaduN} % \arb[trans]{'asaduN}, |'u_htuN| \arb[voc]{'u_htuN} @@ -1326,14 +1330,14 @@ vowels (see §~3). % \arb[voc]{mi'a|TuN} \arb[trans]{mi'a|TuN}. % \end{quote} % -% \paragraph{\arb[trans]{maddaT}} \label{ref:madda}At the beginning of -% a syllabe, \arb[trans]{'alif} with \arb[trans]{hamzaT} and -% \arb[trans]{fat.haT} (\arb[voc]{'a}) followed by \arb[trans]{'alifu -% 'l-maddi} (\arb[trans]{'alif} of prolongation) or \arb[trans]{'alif} -% with \arb[trans]{hamzaT} and \arb[trans]{jazmaT} (\arb[voc]{a"'"}) -% are both represented in writing \arb[trans]{'alif} with -% \arb[trans]{maddaT}: \arb[voc]{A"'} \parencite[see][i. 25 -% A--B]{Wright}. +% \paragraph{\texorpdfstring{\arb[trans]{maddaT}}{maddah}} +% \label{ref:madda}At the beginning of a syllabe, \arb[trans]{'alif} +% with \arb[trans]{hamzaT} and \arb[trans]{fat.haT} (\arb[voc]{'a}) +% followed by \arb[trans]{'alifu 'l-maddi} (\arb[trans]{'alif} of +% prolongation) or \arb[trans]{'alif} with \arb[trans]{hamzaT} and +% \arb[trans]{jazmaT} (\arb[voc]{a"'"}) are both represented in +% writing \arb[trans]{'alif} with \arb[trans]{maddaT}: \arb[voc]{A"'} +% \parencite[see][i. 25 A--B]{Wright}. % % \iffalse %<*example> @@ -1363,13 +1367,13 @@ vowels (see §~3). % \arb[voc]{yaxba'Ani} \arb[trans]{yaxba'Ani}. % \end{quote} % -% \paragraph{\arb[trans]{^saddaT}} +% \paragraph{\texorpdfstring{\arb[trans]{^saddaT}}{šaddah}} % \arb[trans]{ta^sdId} is either \emph{necessary} or \emph{euphonic}. % -% \subparagraph{The necessary -% \arb[trans]{ta^sdId}} \label{ref:necessary-tashdid}always follows a -% vowel, whether short or long \parencite[see][i. 15 A--B]{Wright}. It -% is encoded in writing the consonant that carries it twice: +% \subparagraph{The necessary \arb[trans]{ta^sdId}} +% \label{ref:necessary-tashdid}always follows a vowel, whether short +% or long \parencite[see][i. 15 A--B]{Wright}. It is encoded in +% writing the consonant that carries it twice: % \begin{quote} % |`allaqa| \arb[voc]{`allaqa} \arb[trans]{`allaqa}, |mAdduN| % \arb[voc]{mAdduN} \arb[trans]{mAdduN}, |'ammara| @@ -1447,7 +1451,9 @@ vowels (see §~3). % grammarians \parencite[see][i. 16 B--C]{Wright}. % \end{enumerate} % -% \paragraph{The definite article and the \arb[trans]{'alif-u 'l-wa.sl-i}} +% \paragraph{\texorpdfstring{The definite article and the +% \arb[trans]{'alif-u 'l-wa.sl-i}}{The definite article and the ʾalifu +% 'l-waṣli}} % \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 @@ -1653,7 +1659,8 @@ vowels (see §~3). % \arb[trans]{li-l-l_ah-i 'l-qA'il-u}. % \end{quote} % -% \paragraph{The conjunctive \arb[voc]{alla_dI}} +% \paragraph{\texorpdfstring{The conjunctive \arb[voc]{alla_dI}}{The +% conjunctive اَلَّذِي}} % Although it is compounded of the article \arb[fullvoc]{al}, the % demonstrative letter \arb[novoc]{l} and the demonstrative pronoun % \arb[voc]{_dA}, both masculine and feminine forms that are written @@ -2414,6 +2421,7 @@ word that \cs{arbnull} is applied to. % % \section{Special applications} % \label{sec:special-applications} +% \phantomsection % \paragraph{Linguistics} % The same horizontal stroke as the \arb[trans]{ta.twIl} (see % \vref{sec:tatwil}) may be encoded \meta{B}; \meta{BB} will receive @@ -2427,6 +2435,7 @@ word that \cs{arbnull} is applied to. % \end{quote} % % \paragraph{Brackets} +% \phantomsection % \NEWfeature{v1.4.3} The various bracket symbols are useful in % technical documents such as critical editions for indicating that % some words or some letters must be added or @@ -2551,6 +2560,12 @@ word that \cs{arbnull} is applied to. % % \fi % +% \paragraph{Color}\NEWfeature{v1.12} this: +% \begingroup \newfontfamily\arabicfont{FreeSerif}[Script=Arabic] +% \arb{da_hal"+\arbcolor[red]{+t\arbcolor[blue]{+u}} +% mub"t+\arbcolor[brown]{+a}s+\arbcolor[blue]{+i\arbcolor[brown]{+maN}}} +% \endgroup +% % \section{Transliteration} % \label{sec:transliteration} % It may be more appropriate to speak of \enquote{romanization} than @@ -2679,7 +2694,7 @@ word that \cs{arbnull} is applied to. % \uc{'l-rAziyyu}}. % \end{quote} % -% \paragraph{\enquote*{Long} proper names} +% \paragraph{\enquote*{Long} pro\-per names} % \NEWfeature{v1.10} \cs{uc} is also able to process proper names % consisting of several subsequent words:--- % \begin{quote} @@ -2778,7 +2793,8 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu % with the actual \arb[trans]{tanwIn} in the formatting directives of % the \cs{SetArbUp} command. % -% \paragraph{\arb[trans]{'i`rAb} boundaries} +% \paragraph{\texorpdfstring{\arb[trans]{'i`rAb} boundaries}{ʾiʿrāb +% boundaries}} % Every declinable noun (\arb[trans]{mu`rab}) may be declined either % with or without \arb[trans]{tanwIn}, viz. \arb[trans]{mun.sarifuN} % or \arb[trans]{.gayr-u mun.sarifiN}. The former is automatically @@ -2826,7 +2842,8 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu % 'l-nAs-a kAffaT-aN min mu_hA.tabati-hi 'a.had-uN bi-sayyidi-nA}. % \end{quoting} % -% \paragraph{Discarding the \arb[trans]{'i`rAb}} +% \paragraph{\texorpdfstring{Discar\-ding the +% \arb[trans]{'i`rAb}}{Discarding the ʾiʿrāb}} % As said above (\vref{ref:irab-discarded}), the \arb[trans]{'i`rAb} % may be discarded in some cases, as in transliterated proper names or % book titles. \package{arabluatex} is able to render words ending @@ -3106,8 +3123,8 @@ muhaddamaTaN mi'_danatu-hu}: \arb[trans]{ra'aytu % \paragraph{General principle} \label{ref:cmd-inside-arabic}\LaTeX\ % commands are accepted in Arabic environments. The general principle % which applies is that any single-argument command with up to -% \emph{two optional arguments} -% (\cs{command}\oarg{opt1}\oarg{opt2}\marg{arg}) such as +% \emph{two optional arguments}---that is: +% \cs{command}\oarg{opt1}\oarg{opt2}\marg{arg}---such as % \cs{emph}\marg{text}, \cs{textbf}\marg{text} and the like, is % assumed to have Arabic text in its mandatory argument:--- % \begin{quote} @@ -3169,11 +3186,13 @@ al-muqAtil-Ina.}, wa-kAnat 'ummI min `u.zamA'-i buyUt-i %<*example> % \fi \begin{arabluacode} -\arb[fullvoc]{\uc{z}ayd-uN\LRfootnote{% -\enquote{\arb[trans]{\uc{z}ayd} is the son of -\arb[trans]{\uc{`a}mr}}: the second -noun is not in apposition to the first, but forms -part of the predicate\ldots} "ibn-u \uc{`a}mr-iNU} + \begin{arab}[fullvoc] + \uc{z}ayd-uN\LRfootnote{% + \enquote{\arb[trans]{\uc{z}ayd} is the son of + \arb[trans]{\uc{`a}mr}}: the second noun is not in + apposition to the first, but forms part of the + predicate\ldots} "ibn-u \uc{`a}mr-iNU + \end{arab} \end{arabluacode} % \iffalse % @@ -3194,9 +3213,10 @@ part of the predicate\ldots} "ibn-u \uc{`a}mr-iNU} % the documentation of \package{KOMA-script} for details about the % \cs{deffootnotemark} and \cs{deffootnote} commands.} % -% \DescribeMacro{\LRmarginpar} The \cs{LRmarginpar} command does for -% marginal notes the same as \cs{LRfootnote} does for footnotes. Of -% course, it is supposed to be used in Arabic environments. Note that +% \DescribeMacro{\LRmarginpar} The +% \cs{LRmarginpar}\oarg{left}\marg{right} command does for marginal +% notes the same as \cs{LRfootnote} does for footnotes. Of course, it +% is supposed to be used in Arabic environments. Note that % \cs{marginpar} also works in Arabic environments, but it acts as any % other single-argument command inserted in Arabic environments. The % general principle laid \vpageref{ref:cmd-inside-arabic} applies. @@ -3247,8 +3267,7 @@ qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a... % % For example, here follows a way to define a new command |\fvred| to % distinguish words with a different color and always print them in -% fully vocalized Arabic:---\footnote{See below \vref{sec:textcolor} for -% more information on two-argument commands.} % +% fully vocalized Arabic:--- % % \iffalse %<*example> % \fi @@ -3286,7 +3305,28 @@ qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a... % \end{enumerate} % % \DescribeMacro{\MkArbBreak*}\NEWfeature{v1.12} As said above, -% \cs{MkArbBreak} +% \cs{MkArbBreak} prevents \package{arabluatex} from processing the +% arguments of \enquote*{declared} commands as Arabic text. This +% technique proves sufficient in most cases. However, a +% \enquote*{starred} version of this +% command---\cs{MkArbBreak*}\marg{csv list of commands}---is also +% provided. It goes a step further, as it directs \package{arabluatex} +% to \emph{close} the current Arabic environment before any of the +% \enquote*{declared} commands, then \emph{resume} it just after. +% +% \iffalse +%<*example> +% \fi +\begin{arabluacode}[text only] + It must be noted that \cs{MkArbBreak*} must be used with the utmost + care and \emph{should never be used} if \cs{MkArbBreak} gives + satisfaction. At any rate, the latter must always be tested before + the former. +\end{arabluacode} +% \iffalse +% +% \fi% +% % % \subsection{Environments} % \label{sec:environments} @@ -3505,10 +3545,10 @@ qAla barzawayhi bn-u 'azhar-a, ra's-u 'a.tibbA'-i fAris-a... % \subsection{Two-argument special commands} % \label{sec:two-arg-cmds} % -% \paragraph{Color} +% \paragraph{textcolor} % \label{sec:textcolor} % The two-argument command -% \cs{textcolor}\marg{color}\marg{\cs{arb}\oarg{opt}\marg{Arabic +% \cs{textcolor}\marg{color}\marg{\cs{arb}\oarg{opt}\marg{Ara\-bic % text}} is supported inside \cs{begin}|{arab}| \ldots\ % \cs{end}|{arab}|. One simple example follows:--- % % \iffalse @@ -4170,7 +4210,10 @@ wa-ya.sIru ta.hta 'l-jild-i % inserted in an Arabic environment. It typsets his argument in a % marginal note from left to right. % \begin{macrocode} -\DeclareDocumentCommand{\LRmarginpar}{m}{\marginpar{\textdir TLT #1}} +\DeclareDocumentCommand{\LRmarginpar}{o m}{% + \IfNoValueTF{#1} + {\marginpar{\textdir TLT #2}} + {\marginpar[\textdir TLT #1]{\textdir TLT #2}}} % \end{macrocode} % \end{macro} % \begin{macro}{\LRfootnote} \cs{LRfootnote} and \cs{RLfootnote} are -- cgit v1.2.3