done documenting the new features

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
 %</example>
 % \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
 %</example>
 % \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
 %</example>
 % \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 <jobname><suffix>.tex and compile
+  it one more time.
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \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)