arabtex2utf: documenting the new features

1 files changed, 81 insertions, 9 deletions

diff --git a/arabluatex.dtx b/arabluatex.dtx
index aa46115..27f26ae 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -156,7 +156,7 @@
 \setmainfont{Old Standard}[SmallCapsFont={Latin Modern Roman Caps},
   RawFeature={+mark;+ccmp;+ss05;+ss06}]
 \usepackage{newunicodechar}
-\newunicodechar{ǧ}{ǧ} % Old Standard does include ǧ/Ǧ
+\newunicodechar{ǧ}{ǧ} % Old Standard does not include ǧ/Ǧ
 \newunicodechar{Ǧ}{Ǧ} %
 \usepackage{arabluatex}[2018/06/24]
 \usepackage[nopar]{quran}
@@ -542,9 +542,9 @@
 %
 % \subsection{Options}
 % \label{sec:options}
-% \package{arabluatex} may be loaded with four mutually exclusive
-% global options, each of which may be overriden at any point of the
-% document (see below \vref{sec:local-options}):
+% \package{arabluatex} may be loaded with five global options, the
+% 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,
 % which is the one selected by default, every short vowel written
@@ -579,6 +579,15 @@
 % \end{description}
 % More standards will be included in future releases of
 % \package{arabluatex}.
+%
+% \DescribeOption{export} |export|$=$|true|\verb+|+|false|
+% \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|
+% source file in which all \textsc{ascii} strings are replaced with
+% Unicode equivalents. See below \vref{sec:arabtex2utf} for more
+% information.
 % 
 % \subsubsection{Classic contrasted with modern typesetting of Arabic}
 % \label{sec:classic-modern-typesetting}
@@ -2212,6 +2221,14 @@ 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.
 %
+% \DescribeOption{export} |export|$=$|true|\verb+|+|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
+% will be converted to Unicode and exported to the external selected
+% file. See below \vref{sec:arabtex2utf} for more details.
+% 
 % \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
@@ -3997,6 +4014,59 @@ wa-ya.sIru ta.hta 'l-jild-i
 % \iffalse
 %</example>
 % \fi
+%
+% \section{Exporting Unicode Arabic to an external file}
+% \label{sec:arabtex2utf}
+% \NEWfeature{v.1.13}\package{arabluatex} is able to produce a
+% duplicate of the original |.tex| source file in which all |arabtex|
+% or |buckwalter| strings will have been replaced with Unicode
+% equivalents, either in Arabic script or in any accepted standard of
+% transliteration. Exporting \textsc{ascii} strings to Unicode while
+% preserving the exact selected global or local options is a fairly
+% complex operation which may require \hologo{LuaLaTeX} to be run
+% several times as will be explained below.
+%
+% \paragraph{\texttt{export} global option}
+% \DescribeOption{export}
+% First, \package{arabluatex} must be loaded with the |export| global
+% option enabled, like so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+  % preamble
+  \usepackage[export]{arabluatex}
+  % or:
+  \usepackage[export=true]{arabluatex}
+\end{arabluaverbatim}
+% \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.
+%
+% \DescribeMacro{\SetArbOutSuffix} By default, |_out| is appended as a
+% suffix to the external file name. Any other suffix may be set with
+% the command \cs{SetArbOutSuffix}\marg{suffix}.
+%
+% \paragraph{Exporting running paragraphs}
+% \DescribeEnv{arabexport} Then, the |arabexport| environment is
+% provided to actually exporting running paragraphs with or without
+% Arabic environments to the external selected file, like so:--- %
+% \iffalse
+%<*example>
+% \fi
+\begin{arabluaverbatim}
+  \begin{arabexport}
+    <Running paragraphs of either Arabic or non-Arabic text>
+  \end{arabexport}
+\end{arabluaverbatim}
+% \iffalse
+%</example>
+% \fi
+% \package{arabluatex} will leave untouched non-Arabic text, but
+% will write in Unicode every Arabic environment to the external
+% file.
 % 
 % \section{Future work}
 % \label{sec:future-work}
@@ -4393,11 +4463,13 @@ wa-ya.sIru ta.hta 'l-jild-i
 % \end{macro}
 % \begin{macro}{\arbmark}
 %   \changes{v1.11}{2018/03/31}{New command for inserting additional
-%   marks in Arabic environments} \cs{arbmark} takes one argument from
-%   a list of defined elements. \changes{v1.13}{2018/08/23}{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.
+%   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
+%   \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.
 %    \begin{macrocode}
 \NewDocumentCommand{\arbmark}{O{} m}{%
   \bgroup%