From d6fa410da467eb6c030e89341840e8d16c151d80 Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Sat, 25 Aug 2018 17:48:07 +0200 Subject: done documenting the new features --- arabluatex.dtx | 138 +++++++++++++++++++++++++++++++++++++++++++++++---------- arabluatex.lua | 2 +- 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 @@ \setlist[enumabjad]{label={\abjad{\arabic*}}} \usepackage{multicol} \usepackage{cleveref} +\crefname{footnote}{note}{notes} \usepackage{quoting} \quotingsetup{noorphans, rightmargin=0pt} \renewcommand*{\quotingfont}{\footnotesize} @@ -546,7 +547,7 @@ % first four of which are mutually exclusive and may be overriden at % any point of the document (see below \vref{sec:local-options}): % -% \DescribeOption{voc}\hfill\arabluaverb{default}\\ In this mode, +% \DescribeOption{voc}\hfill\arabluaverb{Default}\\ In this mode, % which is the one selected by default, every short vowel written % generates its corresponding diacritical mark: \arb[trans]{.dammaT} % (\arb{Bu}), \arb[trans]{fat.haT} (\arb{Ba}) and \arb[trans]{kasraT} @@ -581,7 +582,7 @@ % \package{arabluatex}. % % \DescribeOption{export} |export|$=$|true|\verb+|+|false| -% \hfill\arabluaverb{default: false}\\ \label{export-mode} +% \hfill\arabluaverb{Default: false}\\ \label{export-mode} % \NEWfeature{v.1.13} This option acts as a named argument and does % not need a value as it defaults to |true| if it is used. It enables % \package{arabluatex} to produce a duplicate of the original |.tex| @@ -2221,8 +2222,9 @@ word that \cs{arbnull} is applied to. % environment instead of \textsc{ascii} Arab\TeX\ or Buckwalter input % schemes. See \vref{sec:unicode-input} for more details. % +% \label{ref:poetry-export} % \DescribeOption{export} |export|$=$|true|\verb+|+|false| -% \hfill\arabluaverb{default: false}\\ +% \hfill\arabluaverb{Default: false}\\ % \NEWfeature{v.1.13} This named argument does not need a value as it % defaults to |true| if it is used. If |export| is set as a global % option as well (see above \vpageref{export-mode}), all the lines @@ -2231,8 +2233,14 @@ word that \cs{arbnull} is applied to. % % \DescribeMacro{\bayt} Inside the |arabverse| environment, each line % is typeset by the \cs{bayt} command which takes two mandatory -% arguments and may accept one optional argument. Additionally, every -% \cs{bayt} command \emph{must} be followed with |\\| like so:---% +% arguments and may accept one optional +% argument.\footnote{\label{ref:bayt-star}A \enquote*{starred} version +% \cs{bayt*} is also defined. \package{arabluatex} uses it internally +% when \texttt{export} is set to \texttt{true} to instruct some Lua +% functions that lines of poetry have already been processed. That +% aside, \cs{bayt} and \cs{bayt*} do the same, and only \cs{bayt} +% should be used.} Additionally, every \cs{bayt} command \emph{must} +% be followed with |\\| like so:---% % \iffalse %<*example> % \fi @@ -2507,10 +2515,10 @@ word that \cs{arbnull} is applied to. % \arb[trans]{\uc{qur'An}} or in classical poetry. % % \DescribeMacro{\arbmark} -% \NEWfeature{v1.11}\cs{arbmark}\marg{shorthand} can be used to insert -% such characters either in Unicode or in romanized Arabic -% environments. It takes as argument a shorthand defined beforehand in -% a default list which consists of the following +% \NEWfeature{v1.11}\cs{arbmark}\oarg{rl\textbar{}lr}\marg{shorthand} +% can be used to insert such characters either in Unicode or in +% romanized Arabic environments. It takes as argument a shorthand +% defined beforehand in a default list which consists of the following % at the time of writing:---\\ % \begin{longtable}{llp{.3\linewidth}p{.3\linewidth}} % \bottomrule @@ -2530,6 +2538,11 @@ word that \cs{arbnull} is applied to. % |FDFA| & |slm| & \arb{\arbmark{slm}} & \arbmark{slm} \\ % |FDFB| & |jalla| & \arb{\arbmark{jalla}} & \arbmark{jalla} \\ % \end{longtable} +% +% \NEWfeature{v1.13} +% The mark to be inserted is determined by contextual analysis, or by +% an optional argument, either |rl| to have the Arabic glyph printed, +% or |lr| to print the tranliterated equivalent. % % \DescribeMacro{\newarbmark} \NEWfeature{v1.11} \cs{newarbmark} is % also provided should one wish to define new marks in addition to the @@ -3106,7 +3119,16 @@ Then as \Hunayn, \Razi. % \iffalse % % \fi -% +% +% \begin{quoting}\label{ref:prname-star} +% \textsc{Rem.} \DescribeMacro{\prname*} \package{arabluatex} also +% provides \cs{prname*} which only renders in upright roman style +% already transliterated proper names without applying any further +% processing. It is mostly used internally and applied to proper +% names exported in Unicode to an external selected +% file.\footnote{See below \vref{sec:arabtex2utf} for more details.} +% \end{quoting} +% % \subsection{Additional note on \texttt{dmg} convention} % \label{sec:additional-note-dmg} % \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 % other single-argument command inserted in Arabic environments. The % general principle laid \vpageref{ref:cmd-inside-arabic} applies. % +% \label{ref:setrl-setlr} % \DescribeMacro{\setRL} \DescribeMacro{\setLR} \cs{setRL} and % \cs{setLR} can be used to change the direction of paragraphs, either % 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 % complex operation which may require \hologo{LuaLaTeX} to be run % several times as will be explained below. % +% \subsection{Commands and environments} % \paragraph{\texttt{export} global option} % \DescribeOption{export} % First, \package{arabluatex} must be loaded with the |export| global @@ -4042,8 +4066,10 @@ wa-ya.sIru ta.hta 'l-jild-i % \iffalse % % \fi -% Once that is done, compiling the current file will produce an empty -% external |.tex| file with the same preamble as the original file. +% +% Once that is done, compiling the current file will produce a new +% empty external |.tex| file with the same preamble as the original +% file. % % \DescribeMacro{\SetArbOutSuffix} By default, |_out| is appended as a % 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 % \iffalse % % \fi -% \package{arabluatex} will leave untouched non-Arabic text, but -% will write in Unicode every Arabic environment to the external -% file. % +% \package{arabluatex} converts to Unicode and writes to the external +% file what is found inside Arabic environments. As to non-Arabic +% text, it is appended untouched to this file, which is formatted as +% follows:--- +% \begin{enumerate} +% \item Unicode Arabic text, either in Arabic script or in +% transliteration, is inserted as argument of +% \cs{txarb}\footnote{See above \vref{sec:unicode-input}.} or +% \cs{txtrans}\footnote{\cs{txtrans} is used internally by several +% Lua functions to format transliterated Arabic. Therefore, it is +% not documented.} accordingly. +% \item \DescribeMacro{\arbpardir}Additionally, Arabic paragraphs may +% receive \cs{arbpardir}, which \package{arabluatex} uses to +% determine the direction of Arabic paragraphs to be set by default, +% or either \cs{setRL} or \cs{setLR} depending on what may have been +% set locally.\footnote{See above \vpageref{ref:setrl-setlr}.} +% \item \DescribeMacro{\prname*}Proper names are inserted as arguments +% of \cs{prname*}.\footnote{See above \vpageref{ref:prname-star}.} +% \end{enumerate} +% +% \paragraph{Appending words or commands to the external file only} +% \DescribeMacro{\ArbOutFile}\DescribeMacro{\ArbOutFile*} +% \cs{ArbOutFile}\oarg{newline}\allowbreak\marg{argument} silently +% exports its argument to the external file. It may take the string +% |newline| as an optional argument, in which case a carriage return +% is appended to the contents of the +% argument. \cs{ArbOutFile*}\oarg{newline}\marg{argument} does the +% same as \cs{ArbOutFile}, but also inserts its argument into the +% current |.tex| source file. +% +% \paragraph{Exporting Arabic poetry} +% Lines of Arabic poetry are exported as described above +% \vpageref{ref:poetry-export} when the |export| option that is +% specific to the |arabverse| environment is set to |true|. As a +% result of this particular feature, |arabverse| environments must be +% left outside |\begin{arabexport}| \ldots\ |\end{arabexport}|. +% +% Please note that inside |arabverse| environments \cs{bayt} is +% replaced with \cs{bayt*}.\footnote{See above \vref{ref:bayt-star} for +% more information.} +% +% \subsection{Nested Arabic environments} +% The exporting mechanism described above converts only the outermost +% level of nested Arabic environments. This may be sufficient in some +% cases, but if nested Arabic environments be found in the original +% |.tex| source file, then the Unicode converted file must be opened +% and compiled in turn, and so on until the innermost Arabic +% environment be converted and exported. In such cases, +% \package{arabluatex} issues a warning, so that authors do not have +% to check the entire file that just has been exported:--- % +% \iffalse +%<*example> +% \fi +\begin{arabluaverbatim} + Package arabluatex Warning: There are still 'arabtex' strings + to be converted. Please open .tex and compile + it one more time. +\end{arabluaverbatim} +% \iffalse +% +% \fi +% Where \meta{jobname} is the name of the original |.tex| source file, +% and \meta{suffix} the suffix appended to the file that is to be +% opened and compiled again. +% % \section{Future work} % \label{sec:future-work} % A short, uncommented, list of what is planned in the versions of @@ -4384,7 +4472,7 @@ wa-ya.sIru ta.hta 'l-jild-i % to be used outside Arabic environments for proper names. It takes as % argument one or more Arabic words, each of which will be rendered in % upright roman style with its first letter uppercased. -% \begin{macro}{\prname*}\changes{v1.13}{2018/08/22}{Renders proper +% \begin{macro}{\prname*}\changes{v1.13}{2018/08/26}{Renders proper % names already converted to Unicode in upright roman style} % Unlike \cs{prname}, \cs{prname*} does not take |arabtex| or % |buckwalter| input as argument, but already Unicode converted @@ -4466,7 +4554,7 @@ wa-ya.sIru ta.hta 'l-jild-i % marks in Arabic environments} % \cs{arbmark}\oarg{rl\textbar{}lr}\marg{shorthand} takes one % argument from a list of defined elements. -% \changes{v1.13}{2018/08/23}{New optional argument: either +% \changes{v1.13}{2018/08/26}{New optional argument: either % \texttt{rl} or \texttt{lr}} The mark to be inserted is determined % by contextual analysis or by an optional argument, either |rl| or % |lr|. This command is coded in Lua. @@ -4528,9 +4616,11 @@ wa-ya.sIru ta.hta 'l-jild-i % \changes{v1.6}{2016/12/17}{New environment \texttt{arabverse} for % typesetting Arabic poetry} The |arabverse| environment may receive % different options: |mode|, |width|, |gutter|, |metre|, |color|, -% |utf| and |delim|; all of them are defined here just before the -% |arabverse| environment. \changes{v1.13}{2018/08/06}{New option -% \texttt{color} to \texttt{arabverse} environment.} +% |utf|, |delim| and |export|; all of them are defined here just +% before the |arabverse| +% environment. \changes{v1.13}{2018/08/26}{New options +% \texttt{color} and \texttt{export} to \texttt{arabverse} +% environment.} % \begin{macrocode} \newlength{\al@bayt@width} \newlength{\al@gutter@width} @@ -4717,7 +4807,7 @@ wa-ya.sIru ta.hta 'l-jild-i % % \paragraph*{Exporting Unicode Arabic to external file} % \begin{macro}{\SetArbOutSuffix} -% \changes{v1.13}{2018/08/13}{Sets a suffix to be appended to the +% \changes{v1.13}{2018/08/26}{Sets a suffix to be appended to the % filename of the external Unicode file.}By default, |_out| is the % suffix to be appended to the external file in which % \package{arabluatex} exports Unicode in place of @@ -4729,7 +4819,7 @@ wa-ya.sIru ta.hta 'l-jild-i % \end{macrocode} % \end{macro} % \begin{macro}{\ArbOutFile} -% \changes{v1.13}{2018/08/13}{Silently exports its argument in the +% \changes{v1.13}{2018/08/26}{Silently exports its argument in the % selected external file.} % \cs{ArbOutFile}\oarg{newline}\marg{string} silently exports % \meta{string} to the external selected file. It may take |newline| @@ -4750,7 +4840,7 @@ wa-ya.sIru ta.hta 'l-jild-i % \end{macro} % \end{macro} % \begin{environment}{arabexport} -% \changes{v1.13}{2018/08/13}{Processes and print its argument in +% \changes{v1.13}{2018/08/26}{Processes and print its argument in % the current file and exports it in full Unicode in the external % selected \texttt{.tex} file.} The |arabexport| environment % processes and prints its argument unchanged to the current |.pdf| @@ -4788,7 +4878,7 @@ wa-ya.sIru ta.hta 'l-jild-i % \end{macrocode} % \end{environment} % \begin{macro}{\arbpardir} -% \changes{v1.13}{2018/08/13}{Sets the direction of Arabic paragraphs +% \changes{v1.13}{2018/08/26}{Sets the direction of Arabic paragraphs % once they are converted to Unicode.} \cs{arbpardir} is automatically % inserted by \package{arabluatex} at the beginning of Arabic % 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() if string.find(t, "\\begin%s?{document}.-\\arb%s?[%[%{]") or string.find(t, "\\begin%s?{document}.-\\[Uu]c%s?%b{}") then - tex.print([[\unexpanded{\PackageWarningNoLine{arabluatex}{There are still 'arabtex' strings to be converted. Open ]]..tex.jobname..utffilesuffix..".tex"..[[ and compile it one more time}}]]) + 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}}]]) else end t = t.."\n\\end{document}" io.write(t) -- cgit v1.2.3