aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRobert Alessi <alessi@robertalessi.net>2018-08-25 17:48:07 +0200
committerRobert Alessi <alessi@robertalessi.net>2018-08-25 17:48:07 +0200
commitd6fa410da467eb6c030e89341840e8d16c151d80 (patch)
treee565b901ff33fcb0d153b80f2a2a80396ea47934
parent9c348b0f9021afebbbdf67351f68d3d1d60697ab (diff)
downloadarabluatex-d6fa410da467eb6c030e89341840e8d16c151d80.tar.gz
done documenting the new features
-rw-r--r--arabluatex.dtx138
-rw-r--r--arabluatex.lua2
2 files changed, 115 insertions, 25 deletions
diff --git a/arabluatex.dtx b/arabluatex.dtx
index 27f26ae..bdb5a99 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -191,6 +191,7 @@
191\setlist[enumabjad]{label={\abjad{\arabic*}}} 191\setlist[enumabjad]{label={\abjad{\arabic*}}}
192\usepackage{multicol} 192\usepackage{multicol}
193\usepackage{cleveref} 193\usepackage{cleveref}
194\crefname{footnote}{note}{notes}
194\usepackage{quoting} 195\usepackage{quoting}
195\quotingsetup{noorphans, rightmargin=0pt} 196\quotingsetup{noorphans, rightmargin=0pt}
196\renewcommand*{\quotingfont}{\footnotesize} 197\renewcommand*{\quotingfont}{\footnotesize}
@@ -546,7 +547,7 @@
546% first four of which are mutually exclusive and may be overriden at 547% first four of which are mutually exclusive and may be overriden at
547% any point of the document (see below \vref{sec:local-options}): 548% any point of the document (see below \vref{sec:local-options}):
548% 549%
549% \DescribeOption{voc}\hfill\arabluaverb{default}\\ In this mode, 550% \DescribeOption{voc}\hfill\arabluaverb{Default}\\ In this mode,
550% which is the one selected by default, every short vowel written 551% which is the one selected by default, every short vowel written
551% generates its corresponding diacritical mark: \arb[trans]{.dammaT} 552% generates its corresponding diacritical mark: \arb[trans]{.dammaT}
552% (\arb{Bu}), \arb[trans]{fat.haT} (\arb{Ba}) and \arb[trans]{kasraT} 553% (\arb{Bu}), \arb[trans]{fat.haT} (\arb{Ba}) and \arb[trans]{kasraT}
@@ -581,7 +582,7 @@
581% \package{arabluatex}. 582% \package{arabluatex}.
582% 583%
583% \DescribeOption{export} |export|$=$|true|\verb+|+|false| 584% \DescribeOption{export} |export|$=$|true|\verb+|+|false|
584% \hfill\arabluaverb{default: false}\\ \label{export-mode} 585% \hfill\arabluaverb{Default: false}\\ \label{export-mode}
585% \NEWfeature{v.1.13} This option acts as a named argument and does 586% \NEWfeature{v.1.13} This option acts as a named argument and does
586% not need a value as it defaults to |true| if it is used. It enables 587% not need a value as it defaults to |true| if it is used. It enables
587% \package{arabluatex} to produce a duplicate of the original |.tex| 588% \package{arabluatex} to produce a duplicate of the original |.tex|
@@ -2221,8 +2222,9 @@ word that \cs{arbnull} is applied to.
2221% environment instead of \textsc{ascii} Arab\TeX\ or Buckwalter input 2222% environment instead of \textsc{ascii} Arab\TeX\ or Buckwalter input
2222% schemes. See \vref{sec:unicode-input} for more details. 2223% schemes. See \vref{sec:unicode-input} for more details.
2223% 2224%
2225% \label{ref:poetry-export}
2224% \DescribeOption{export} |export|$=$|true|\verb+|+|false| 2226% \DescribeOption{export} |export|$=$|true|\verb+|+|false|
2225% \hfill\arabluaverb{default: false}\\ 2227% \hfill\arabluaverb{Default: false}\\
2226% \NEWfeature{v.1.13} This named argument does not need a value as it 2228% \NEWfeature{v.1.13} This named argument does not need a value as it
2227% defaults to |true| if it is used. If |export| is set as a global 2229% defaults to |true| if it is used. If |export| is set as a global
2228% option as well (see above \vpageref{export-mode}), all the lines 2230% option as well (see above \vpageref{export-mode}), all the lines
@@ -2231,8 +2233,14 @@ word that \cs{arbnull} is applied to.
2231% 2233%
2232% \DescribeMacro{\bayt} Inside the |arabverse| environment, each line 2234% \DescribeMacro{\bayt} Inside the |arabverse| environment, each line
2233% is typeset by the \cs{bayt} command which takes two mandatory 2235% is typeset by the \cs{bayt} command which takes two mandatory
2234% arguments and may accept one optional argument. Additionally, every 2236% arguments and may accept one optional
2235% \cs{bayt} command \emph{must} be followed with |\\| like so:---% 2237% argument.\footnote{\label{ref:bayt-star}A \enquote*{starred} version
2238% \cs{bayt*} is also defined. \package{arabluatex} uses it internally
2239% when \texttt{export} is set to \texttt{true} to instruct some Lua
2240% functions that lines of poetry have already been processed. That
2241% aside, \cs{bayt} and \cs{bayt*} do the same, and only \cs{bayt}
2242% should be used.} Additionally, every \cs{bayt} command \emph{must}
2243% be followed with |\\| like so:---%
2236% \iffalse 2244% \iffalse
2237%<*example> 2245%<*example>
2238% \fi 2246% \fi
@@ -2507,10 +2515,10 @@ word that \cs{arbnull} is applied to.
2507% \arb[trans]{\uc{qur'An}} or in classical poetry. 2515% \arb[trans]{\uc{qur'An}} or in classical poetry.
2508% 2516%
2509% \DescribeMacro{\arbmark} 2517% \DescribeMacro{\arbmark}
2510% \NEWfeature{v1.11}\cs{arbmark}\marg{shorthand} can be used to insert 2518% \NEWfeature{v1.11}\cs{arbmark}\oarg{rl\textbar{}lr}\marg{shorthand}
2511% such characters either in Unicode or in romanized Arabic 2519% can be used to insert such characters either in Unicode or in
2512% environments. It takes as argument a shorthand defined beforehand in 2520% romanized Arabic environments. It takes as argument a shorthand
2513% a default list which consists of the following 2521% defined beforehand in a default list which consists of the following
2514% at the time of writing:---\\ 2522% at the time of writing:---\\
2515% \begin{longtable}{llp{.3\linewidth}p{.3\linewidth}} 2523% \begin{longtable}{llp{.3\linewidth}p{.3\linewidth}}
2516% \bottomrule 2524% \bottomrule
@@ -2530,6 +2538,11 @@ word that \cs{arbnull} is applied to.
2530% |FDFA| & |slm| & \arb{\arbmark{slm}} & \arbmark{slm} \\ 2538% |FDFA| & |slm| & \arb{\arbmark{slm}} & \arbmark{slm} \\
2531% |FDFB| & |jalla| & \arb{\arbmark{jalla}} & \arbmark{jalla} \\ 2539% |FDFB| & |jalla| & \arb{\arbmark{jalla}} & \arbmark{jalla} \\
2532% \end{longtable} 2540% \end{longtable}
2541%
2542% \NEWfeature{v1.13}
2543% The mark to be inserted is determined by contextual analysis, or by
2544% an optional argument, either |rl| to have the Arabic glyph printed,
2545% or |lr| to print the tranliterated equivalent.
2533% 2546%
2534% \DescribeMacro{\newarbmark} \NEWfeature{v1.11} \cs{newarbmark} is 2547% \DescribeMacro{\newarbmark} \NEWfeature{v1.11} \cs{newarbmark} is
2535% also provided should one wish to define new marks in addition to the 2548% also provided should one wish to define new marks in addition to the
@@ -3106,7 +3119,16 @@ Then as \Hunayn, \Razi.
3106% \iffalse 3119% \iffalse
3107%</example> 3120%</example>
3108% \fi 3121% \fi
3109% 3122%
3123% \begin{quoting}\label{ref:prname-star}
3124% \textsc{Rem.} \DescribeMacro{\prname*} \package{arabluatex} also
3125% provides \cs{prname*} which only renders in upright roman style
3126% already transliterated proper names without applying any further
3127% processing. It is mostly used internally and applied to proper
3128% names exported in Unicode to an external selected
3129% file.\footnote{See below \vref{sec:arabtex2utf} for more details.}
3130% \end{quoting}
3131%
3110% \subsection{Additional note on \texttt{dmg} convention} 3132% \subsection{Additional note on \texttt{dmg} convention}
3111% \label{sec:additional-note-dmg} 3133% \label{sec:additional-note-dmg}
3112% \NEWfeature{v1.3} According to \textcite[6]{dmg}, Arabic 3134% \NEWfeature{v1.3} According to \textcite[6]{dmg}, Arabic
@@ -3591,6 +3613,7 @@ al-muqAtil-Ina.}, wa-kAnat 'ummI min `u.zamA'-i buyUt-i
3591% other single-argument command inserted in Arabic environments. The 3613% other single-argument command inserted in Arabic environments. The
3592% general principle laid \vpageref{ref:cmd-inside-arabic} applies. 3614% general principle laid \vpageref{ref:cmd-inside-arabic} applies.
3593% 3615%
3616% \label{ref:setrl-setlr}
3594% \DescribeMacro{\setRL} \DescribeMacro{\setLR} \cs{setRL} and 3617% \DescribeMacro{\setRL} \DescribeMacro{\setLR} \cs{setRL} and
3595% \cs{setLR} can be used to change the direction of paragraphs, either 3618% \cs{setLR} can be used to change the direction of paragraphs, either
3596% form left to right or from right to left. As an example, an 3619% form left to right or from right to left. As an example, an
@@ -4026,6 +4049,7 @@ wa-ya.sIru ta.hta 'l-jild-i
4026% complex operation which may require \hologo{LuaLaTeX} to be run 4049% complex operation which may require \hologo{LuaLaTeX} to be run
4027% several times as will be explained below. 4050% several times as will be explained below.
4028% 4051%
4052% \subsection{Commands and environments}
4029% \paragraph{\texttt{export} global option} 4053% \paragraph{\texttt{export} global option}
4030% \DescribeOption{export} 4054% \DescribeOption{export}
4031% First, \package{arabluatex} must be loaded with the |export| global 4055% First, \package{arabluatex} must be loaded with the |export| global
@@ -4042,8 +4066,10 @@ wa-ya.sIru ta.hta 'l-jild-i
4042% \iffalse 4066% \iffalse
4043%</example> 4067%</example>
4044% \fi 4068% \fi
4045% Once that is done, compiling the current file will produce an empty 4069%
4046% external |.tex| file with the same preamble as the original file. 4070% Once that is done, compiling the current file will produce a new
4071% empty external |.tex| file with the same preamble as the original
4072% file.
4047% 4073%
4048% \DescribeMacro{\SetArbOutSuffix} By default, |_out| is appended as a 4074% \DescribeMacro{\SetArbOutSuffix} By default, |_out| is appended as a
4049% suffix to the external file name. Any other suffix may be set with 4075% suffix to the external file name. Any other suffix may be set with
@@ -4064,10 +4090,72 @@ wa-ya.sIru ta.hta 'l-jild-i
4064% \iffalse 4090% \iffalse
4065%</example> 4091%</example>
4066% \fi 4092% \fi
4067% \package{arabluatex} will leave untouched non-Arabic text, but
4068% will write in Unicode every Arabic environment to the external
4069% file.
4070% 4093%
4094% \package{arabluatex} converts to Unicode and writes to the external
4095% file what is found inside Arabic environments. As to non-Arabic
4096% text, it is appended untouched to this file, which is formatted as
4097% follows:---
4098% \begin{enumerate}
4099% \item Unicode Arabic text, either in Arabic script or in
4100% transliteration, is inserted as argument of
4101% \cs{txarb}\footnote{See above \vref{sec:unicode-input}.} or
4102% \cs{txtrans}\footnote{\cs{txtrans} is used internally by several
4103% Lua functions to format transliterated Arabic. Therefore, it is
4104% not documented.} accordingly.
4105% \item \DescribeMacro{\arbpardir}Additionally, Arabic paragraphs may
4106% receive \cs{arbpardir}, which \package{arabluatex} uses to
4107% determine the direction of Arabic paragraphs to be set by default,
4108% or either \cs{setRL} or \cs{setLR} depending on what may have been
4109% set locally.\footnote{See above \vpageref{ref:setrl-setlr}.}
4110% \item \DescribeMacro{\prname*}Proper names are inserted as arguments
4111% of \cs{prname*}.\footnote{See above \vpageref{ref:prname-star}.}
4112% \end{enumerate}
4113%
4114% \paragraph{Appending words or commands to the external file only}
4115% \DescribeMacro{\ArbOutFile}\DescribeMacro{\ArbOutFile*}
4116% \cs{ArbOutFile}\oarg{newline}\allowbreak\marg{argument} silently
4117% exports its argument to the external file. It may take the string
4118% |newline| as an optional argument, in which case a carriage return
4119% is appended to the contents of the
4120% argument. \cs{ArbOutFile*}\oarg{newline}\marg{argument} does the
4121% same as \cs{ArbOutFile}, but also inserts its argument into the
4122% current |.tex| source file.
4123%
4124% \paragraph{Exporting Arabic poetry}
4125% Lines of Arabic poetry are exported as described above
4126% \vpageref{ref:poetry-export} when the |export| option that is
4127% specific to the |arabverse| environment is set to |true|. As a
4128% result of this particular feature, |arabverse| environments must be
4129% left outside |\begin{arabexport}| \ldots\ |\end{arabexport}|.
4130%
4131% Please note that inside |arabverse| environments \cs{bayt} is
4132% replaced with \cs{bayt*}.\footnote{See above \vref{ref:bayt-star} for
4133% more information.}
4134%
4135% \subsection{Nested Arabic environments}
4136% The exporting mechanism described above converts only the outermost
4137% level of nested Arabic environments. This may be sufficient in some
4138% cases, but if nested Arabic environments be found in the original
4139% |.tex| source file, then the Unicode converted file must be opened
4140% and compiled in turn, and so on until the innermost Arabic
4141% environment be converted and exported. In such cases,
4142% \package{arabluatex} issues a warning, so that authors do not have
4143% to check the entire file that just has been exported:--- %
4144% \iffalse
4145%<*example>
4146% \fi
4147\begin{arabluaverbatim}
4148 Package arabluatex Warning: There are still 'arabtex' strings
4149 to be converted. Please open <jobname><suffix>.tex and compile
4150 it one more time.
4151\end{arabluaverbatim}
4152% \iffalse
4153%</example>
4154% \fi
4155% Where \meta{jobname} is the name of the original |.tex| source file,
4156% and \meta{suffix} the suffix appended to the file that is to be
4157% opened and compiled again.
4158%
4071% \section{Future work} 4159% \section{Future work}
4072% \label{sec:future-work} 4160% \label{sec:future-work}
4073% A short, uncommented, list of what is planned in the versions of 4161% A short, uncommented, list of what is planned in the versions of
@@ -4384,7 +4472,7 @@ wa-ya.sIru ta.hta 'l-jild-i
4384% to be used outside Arabic environments for proper names. It takes as 4472% to be used outside Arabic environments for proper names. It takes as
4385% argument one or more Arabic words, each of which will be rendered in 4473% argument one or more Arabic words, each of which will be rendered in
4386% upright roman style with its first letter uppercased. 4474% upright roman style with its first letter uppercased.
4387% \begin{macro}{\prname*}\changes{v1.13}{2018/08/22}{Renders proper 4475% \begin{macro}{\prname*}\changes{v1.13}{2018/08/26}{Renders proper
4388% names already converted to Unicode in upright roman style} 4476% names already converted to Unicode in upright roman style}
4389% Unlike \cs{prname}, \cs{prname*} does not take |arabtex| or 4477% Unlike \cs{prname}, \cs{prname*} does not take |arabtex| or
4390% |buckwalter| input as argument, but already Unicode converted 4478% |buckwalter| input as argument, but already Unicode converted
@@ -4466,7 +4554,7 @@ wa-ya.sIru ta.hta 'l-jild-i
4466% marks in Arabic environments} 4554% marks in Arabic environments}
4467% \cs{arbmark}\oarg{rl\textbar{}lr}\marg{shorthand} takes one 4555% \cs{arbmark}\oarg{rl\textbar{}lr}\marg{shorthand} takes one
4468% argument from a list of defined elements. 4556% argument from a list of defined elements.
4469% \changes{v1.13}{2018/08/23}{New optional argument: either 4557% \changes{v1.13}{2018/08/26}{New optional argument: either
4470% \texttt{rl} or \texttt{lr}} The mark to be inserted is determined 4558% \texttt{rl} or \texttt{lr}} The mark to be inserted is determined
4471% by contextual analysis or by an optional argument, either |rl| or 4559% by contextual analysis or by an optional argument, either |rl| or
4472% |lr|. This command is coded in Lua. 4560% |lr|. This command is coded in Lua.
@@ -4528,9 +4616,11 @@ wa-ya.sIru ta.hta 'l-jild-i
4528% \changes{v1.6}{2016/12/17}{New environment \texttt{arabverse} for 4616% \changes{v1.6}{2016/12/17}{New environment \texttt{arabverse} for
4529% typesetting Arabic poetry} The |arabverse| environment may receive 4617% typesetting Arabic poetry} The |arabverse| environment may receive
4530% different options: |mode|, |width|, |gutter|, |metre|, |color|, 4618% different options: |mode|, |width|, |gutter|, |metre|, |color|,
4531% |utf| and |delim|; all of them are defined here just before the 4619% |utf|, |delim| and |export|; all of them are defined here just
4532% |arabverse| environment. \changes{v1.13}{2018/08/06}{New option 4620% before the |arabverse|
4533% \texttt{color} to \texttt{arabverse} environment.} 4621% environment. \changes{v1.13}{2018/08/26}{New options
4622% \texttt{color} and \texttt{export} to \texttt{arabverse}
4623% environment.}
4534% \begin{macrocode} 4624% \begin{macrocode}
4535\newlength{\al@bayt@width} 4625\newlength{\al@bayt@width}
4536\newlength{\al@gutter@width} 4626\newlength{\al@gutter@width}
@@ -4717,7 +4807,7 @@ wa-ya.sIru ta.hta 'l-jild-i
4717% 4807%
4718% \paragraph*{Exporting Unicode Arabic to external file} 4808% \paragraph*{Exporting Unicode Arabic to external file}
4719% \begin{macro}{\SetArbOutSuffix} 4809% \begin{macro}{\SetArbOutSuffix}
4720% \changes{v1.13}{2018/08/13}{Sets a suffix to be appended to the 4810% \changes{v1.13}{2018/08/26}{Sets a suffix to be appended to the
4721% filename of the external Unicode file.}By default, |_out| is the 4811% filename of the external Unicode file.}By default, |_out| is the
4722% suffix to be appended to the external file in which 4812% suffix to be appended to the external file in which
4723% \package{arabluatex} exports Unicode in place of 4813% \package{arabluatex} exports Unicode in place of
@@ -4729,7 +4819,7 @@ wa-ya.sIru ta.hta 'l-jild-i
4729% \end{macrocode} 4819% \end{macrocode}
4730% \end{macro} 4820% \end{macro}
4731% \begin{macro}{\ArbOutFile} 4821% \begin{macro}{\ArbOutFile}
4732% \changes{v1.13}{2018/08/13}{Silently exports its argument in the 4822% \changes{v1.13}{2018/08/26}{Silently exports its argument in the
4733% selected external file.} 4823% selected external file.}
4734% \cs{ArbOutFile}\oarg{newline}\marg{string} silently exports 4824% \cs{ArbOutFile}\oarg{newline}\marg{string} silently exports
4735% \meta{string} to the external selected file. It may take |newline| 4825% \meta{string} to the external selected file. It may take |newline|
@@ -4750,7 +4840,7 @@ wa-ya.sIru ta.hta 'l-jild-i
4750% \end{macro} 4840% \end{macro}
4751% \end{macro} 4841% \end{macro}
4752% \begin{environment}{arabexport} 4842% \begin{environment}{arabexport}
4753% \changes{v1.13}{2018/08/13}{Processes and print its argument in 4843% \changes{v1.13}{2018/08/26}{Processes and print its argument in
4754% the current file and exports it in full Unicode in the external 4844% the current file and exports it in full Unicode in the external
4755% selected \texttt{.tex} file.} The |arabexport| environment 4845% selected \texttt{.tex} file.} The |arabexport| environment
4756% processes and prints its argument unchanged to the current |.pdf| 4846% processes and prints its argument unchanged to the current |.pdf|
@@ -4788,7 +4878,7 @@ wa-ya.sIru ta.hta 'l-jild-i
4788% \end{macrocode} 4878% \end{macrocode}
4789% \end{environment} 4879% \end{environment}
4790% \begin{macro}{\arbpardir} 4880% \begin{macro}{\arbpardir}
4791% \changes{v1.13}{2018/08/13}{Sets the direction of Arabic paragraphs 4881% \changes{v1.13}{2018/08/26}{Sets the direction of Arabic paragraphs
4792% once they are converted to Unicode.} \cs{arbpardir} is automatically 4882% once they are converted to Unicode.} \cs{arbpardir} is automatically
4793% inserted by \package{arabluatex} at the beginning of Arabic 4883% inserted by \package{arabluatex} at the beginning of Arabic
4794% paragraphs converted to Unicode so that they are printed in the 4884% paragraphs converted to Unicode so that they are printed in the
diff --git a/arabluatex.lua b/arabluatex.lua
index f717cb4..8fc04d6 100644
--- a/arabluatex.lua
+++ b/arabluatex.lua
@@ -821,7 +821,7 @@ function al_closestream()
821 if string.find(t, "\\begin%s?{document}.-\\arb%s?[%[%{]") or 821 if string.find(t, "\\begin%s?{document}.-\\arb%s?[%[%{]") or
822 string.find(t, "\\begin%s?{document}.-\\[Uu]c%s?%b{}") 822 string.find(t, "\\begin%s?{document}.-\\[Uu]c%s?%b{}")
823 then 823 then
824 tex.print([[\unexpanded{\PackageWarningNoLine{arabluatex}{There are still 'arabtex' strings to be converted. Open ]]..tex.jobname..utffilesuffix..".tex"..[[ and compile it one more time}}]]) 824 tex.print([[\unexpanded{\PackageWarningNoLine{arabluatex}{There are still 'arabtex' strings to be converted. Please open ]]..tex.jobname..utffilesuffix..".tex"..[[ and compile it one more time}}]])
825 else end 825 else end
826 t = t.."\n\\end{document}" 826 t = t.."\n\\end{document}"
827 io.write(t) 827 io.write(t)