bugfix: 'flush' could generate duplicate apparatuses unexpectedly. documenting the section on languages

1 files changed, 277 insertions, 11 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index dab30cc..09c1503 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -130,6 +130,24 @@ along with this program.  If not, see
   date =         {2005-11-02},
   version =      {4.41}
 }
+
+@Software{polyglossia,
+  title =        {The Polyglossia package},
+  titleaddon =   {An alternative to babel for XeLaTeX and LuaLaTeX},
+  author =       {Charette, François and Reutenauer, Arthur},
+  url =          {http://www.ctan.org/pkg/polyglossia},
+  date =         {2020-04-08},
+  version =      {1.49}
+}
+
+@Software{babel,
+  title =        {The Babel package},
+  titleaddon =   {Multilingual support for Plain TeX or LaTeX},
+  author =       {Bezos López, Javier and Braams, Johannes L.},
+  url =          {http://www.ctan.org/pkg/babel},
+  date =         {2020-07-13},
+  version =      {3.47}
+}
 \end{filecontents}
 \begin{filecontents}[overwrite]{\jobname-cfg.tex}
 \footnotelayout{m}
@@ -140,6 +158,12 @@ along with this program.  If not, see
 \DeclareApparatus{default}[
         delim=\hskip0.75em,
         ehook=.]
+\DeclareApparatus{ltr}[
+        delim=\hskip0.75em]
+\DeclareApparatus{rtl}[
+        direction=RL,
+        sep={[ },
+        delim=\hskip0.75em]
 \DeclareWitness{M}{M}{\emph{Marcianus Gr.} 269}[
         settlement=Venice,
         institution=Marciana Library,
@@ -702,7 +726,7 @@ along with this program.  If not, see
 %
 % \needspace{4\baselineskip}PDF output:---
 % \medskip
-% \begin{alignment}[tcols=1,texts=specimen,apparatus=specimen]
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
 %   \begin{specimen}
 %   I 
 %   \app{
@@ -1377,7 +1401,7 @@ yesterday.
 %</example> 
 % \fi
 % \resetlinenumber
-% \begin{alignment}[tcols=1,texts=specimen,apparatus=specimen]
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
 %   \begin{specimen}
 %     I \app{\lem[wit=pjA]{saw}\rdg[wit=pjB]{met}} my friend
 %     \app{
@@ -1578,7 +1602,7 @@ yesterday.
 %
 % \resetlinenumber
 % \ekdfmtdiv{2}{}{.}
-% \begin{alignment}[lcols=2,
+% \begin{alignment}[flush,lcols=2,
 %                   texts=edition[xml:lang="la"];
 %                   translation[xml:lang="en"]]
 % \AtBeginEnvironment{edition}{\selectlanguage{latin}}
@@ -1772,11 +1796,11 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % \DescribeOption{flush} |flush|$=$\verb+true|false+
 % \hfill\tcboxverb{Default: false}\\
 % This named argument does not need a value as it defaults to |true|
-% if it is used. This option applies on rare occasions only, when two
-% or more distinct \env{alignment} environments are started on the same
-% page. Should this happen, any subsequent \env{alignment} environment
-% must be set with the |flush| option so that every one of them
-% carry its own apparatus criticus.
+% if it is used. This option applies when two or more distinct
+% \env{alignment} environments are started on the same page. Should
+% this happen, any subsequent \env{alignment} environment must be set
+% with the |flush| option so that every one of them carry its own
+% apparatus criticus.
 %
 % As an example, the alignment of the Latin edition text of Caesar's
 % \emph{Gallic War}, printed on left-hand pages, along with two
@@ -1841,6 +1865,28 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % \cs{SetEkdosisAlignment} can be used either in the preamble or at
 % any point of the document to set or to modify alignment settings.
 %
+% \subsubsection{Appending Hooks to Environments}
+% \label{sec:alignment-hooks}
+% \DescribeMacro{\AtBeginEnvironment} Once environments corresponding
+% to texts to be aligned have been defined, it is advisable to use the
+% \cs{AtBeginEnvironment}\marg{environment}\marg{code} command that is
+% provided by the \pkg{etoolbox} package\footnote{This package is
+% loaded by \pkg{ekdosis}.} to further adjust languages, hyphenation
+% rules, and/or fonts to be applied in each environment. To return to
+% the example provided above, once \cs{SetEkdosisAlignment} has been
+% used, the languages can be set as follows:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\AtBeginEnvironment{latin}{\selectlanguage{latin}}
+\AtBeginEnvironment{english}{\selectlanguage{english}}
+\AtBeginEnvironment{french}{\selectlanguage{french}}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
 %
 % \section{Laying Out the Apparatus Criticus }
 % \label{sec:apparatus-layout}
@@ -2173,7 +2219,7 @@ Some \app[type=rec2]{
 % been chosen, must be used if the editor wishes to retain that
 % information in the \texttt{TEI xml} output file.
 %
-% \subsection{Other Notes, Comments, Sources, Testimonia}
+% \subsection{Other Notes for Comments, Sources or Testimonia}
 % \label{ref:type-note}
 % Additional layers of notes can be used to print short comments or to
 % record references to texts quoted by the author of the edited text
@@ -2268,7 +2314,7 @@ Some \app[type=rec2]{
 % PDF output:---
 % \medskip
 % \resetlinenumber
-% \begin{alignment}[tcols=1,texts=specimen,apparatus=specimen]
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
 %   \begin{specimen}
 %     The oldest monument of the Germans is their language, which,
 %     before untold centuries, was the companion of their travels from
@@ -2424,6 +2470,13 @@ argument of the
 % digits in the group 10 to 19 in each hundred\---viz. 17--19, 115--18
 % \emph{\&c.} |numbers=full| leaves the numbers untouched.
 %
+% \DescribeMacro{\innerlinenumbers} \DescribeMacro{\outerlinenumbers}
+% \cs{innerlinenumbers} and \cs{outerlinenumbers} are equivalent to
+% \cs{SetLineation}|{numb|\allowbreak|ers=outer}| and
+% \cs{SetLineation}|{numbers=inner}| respectively. Both commands are
+% complementary to \cs{rightlinenumbers} and \cs{leftlinenumbers}
+% already provided by the \pkg{lineno} package.
+%
 % \paragraph{Useful Lineation Commands}
 % As implied above, pretty much all commands that are provided by the
 % \enquote{running} mode of operation of the \pkg{lineno} package will
@@ -2456,7 +2509,219 @@ argument of the
 % \iffalse
 %</example>
 % \fi
+%
+% \section{Languages}
+% \label{sec:languages}
+% \danger \pkg{ekdosis} is fully compatible with \pkg{babel}.
+% \enquote{Fully compatible} means that all features provided by
+% \pkg{babel}, including language switching commands, are supported by
+% \pkg{ekdosis}. \pkg{ekdosis} is also compatible with
+% \pkg{polyglossia} with one notable exception: \pkg{luabidi}, which
+% \pkg{polyglossia} loads for languages written from right to left, is
+% not supported by \pkg{ekdosis}, and most probably never will
+% be. That said, as far as the author could see, single-layer
+% apparatus, as described in \vref{sec:single-layer-app}, can be
+% typeset within the Arabic environment that is provided by
+% \pkg{polyglossia}. Unfortunately, the same cannot be said for
+% multi-layer apparatus.
+%
+% Whether \pkg{babel} or \pkg{polyglossia} is used, \pkg{ekdosis}
+% automatically applies the current language to the entries of the
+% apparatus criticus, including the fonts that may have been
+% associated to the languages in the preamble. In this respect, as
+% \pkg{polyglossia} can use the same language switching commands as
+% \pkg{babel},\footcite[See][3.2 \pno~14]{polyglossia} the general
+% advice given above in \vref{sec:alignment-hooks} applies in all
+% cases.
+%
+% \subsection{Languages Written From Right to Left}
+% \label{sec:rtl-languages}
+% As said above, \pkg{polyglossia} is not supported by \pkg{ekdosis}
+% for languages that are written and read from right to left, like
+% Arabic, Hebrew or Syriac. However, as \pkg{babel} is supported and
+% can be loaded concurrently with \pkg{polyglossia}, an easy way is to
+% always use \pkg{babel} to print such languages.
+%
+% \danger The reader is invited to refer to and become acquainted with
+% the relevant parts of the documentation of the \pkg{babel}
+% package.\footcite{babel}
+%
+% \paragraph{\pkg{babel} Only}
+% In the following example, \pkg{babel} is used exclusively to set
+% three different languages: Arabic, ancient Greek and English:---
+%
+% \captof{Multilingual editions with \pkg{babel} only}
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+\usepackage{fontspec}
+
+\usepackage[greek.ancient,english]{babel}
+\babelprovide[onchar=fonts]{arabic}
+
+\babelfont{rm}{Old Standard}
+\babelfont[greek]{rm}[RawFeature={+ss05;+ss06}]{Old Standard}
+\babelfont[*arabic]{rm}{Amiri}
+
+\babeltags{ancientgreek = greek}
+\newcommand{\sg}[1]{\textancientgreek{#1}}
+
+\newcommand{\RL}[1]{\bgroup\textdir TRT#1\egroup}
+\newenvironment{Arabic}{\par\pardir TRT\textdir TRT}{\par}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \begin{remarks}
+% \item As can be seen, \pkg{fontspec} has been loaded before
+%   \pkg{babel}. To the author's knowledge, this gives better results
+%   when \cs{babelfont} is used.
+% \item Line~3 loads \pkg{babel} and instructs it to use English as
+%   the default language and ancient Greek as a second optional
+%   language. As can be seen, the built-in |bidi| mechanism provided
+%   by \pkg{babel} is not enabled. As a result, specific language
+%   switching commands for Arabic must be defined just as it must be
+%   for every other language.
+% \item Line~4 does not load any Arabic, but instructs \pkg{babel}
+%   that it should use the Arabic font that is set with \cs{babelfont}
+%   whenever an Arabic letter is encountered.
+% \item Lines~6--8 select the fonts: |Old Standard| is the default
+%   font to be used for Roman shape (l.~6); the same font is used for
+%   Greek, with some additional Open Type features enabled; finally,
+%   the |Amiri| font is used for Arabic.
+% \item Lines~10--11 define so-called \enquote{tags} for easier access
+%   to ancient Greek through \cs{begin}|{ancient|\allowbreak|greek}|
+%   \dots\ \cs{end}|{ancientgreek}| for running paragraphs and
+%   \cs{textancientgreek}\marg{text} for short insertions of Greek in
+%   English text. \cs{sg}\marg{text} is just a shorthand for this
+%   latter command.
+% \item Finally, lines~13--14 define simple language switching
+%   commands for Arabic. As can be seen, no commands other than the
+%   \LuaTeX\ primitives \cs{pardir} and \cs{textdir} have been used
+%   for \pkg{babel} takes care of selecting the Arabic font. \cs{RL}
+%   is for short insertions of Arabic words in English paragraphs
+%   while \cs{begin}|{Arabic}| \dots\ \cs{end}|{Arabic}| is for
+%   running paragraphs of Arabic text.
+% \end{remarks}
+%
+% \paragraph{Changing the Writing Direction}
+% \DescribeMacro{\setRL} \DescribeMacro{\setLR} \cs{setRL} and
+% \cs{setLR} are two argument-less commands provided by \pkg{ekdosis}
+% that can be used to change the writing direction of running
+% paragraphs. The former sets the direction from right to left and the
+% latter form left to right. If \pkg{babel} has been set as above,
+% \cs{setRL} \dots\ \cs{setLR} can be used in place of
+% \cs{begin}|{Arabic}| \dots\ \cs{end}|{Arabic}|.
 % 
+% \paragraph{\pkg{polyglossia} Associated With \cs{babelprovide}}
+% What follows illustrates how \pkg{babel} can be used conjointly with
+% \pkg{polyglossia} for the same three languages as above without
+% having to load \pkg{luabidi}:---
+%
+% \captof{Multilingual editions with \pkg{babel} and
+% \pkg{polyglossia}}
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+\usepackage{fontspec}
+
+\usepackage{babel}
+\babelprovide[onchar=fonts]{arabic}
+
+\setmainfont{Old Standard}
+\newfontfamily\greekfont{Old Standard}[RawFeature={+ss05;+ss06}]
+\babelfont[*arabic]{rm}{Amiri}
+
+\usepackage{polyglossia}
+\setdefaultlanguage{english}
+\setotherlanguage[variant=ancient]{greek}
+
+\newcommand{\textarabic}[1]{\bgroup\textdir TRT#1\egroup}
+\newenvironment{Arabic}{\par\pardir TRT\textdir TRT}{\par}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \begin{remarks}
+% \item Line~3 just loads \pkg{babel} with no default language.
+% \item Lines~4 and 8 are used to have the Arabic font automatically
+%   selected as above.
+% \item Lines~14--15 define the exact language switching commands that
+%   would have been defined if \pkg{polyglossia} and \pkg{luabidi} had
+%   been used for Arabic.
+% \end{remarks}
+%
+% As one can see, the important point about languages written from
+% right to left is to use \pkg{babel} only to select the Arabic fonts,
+% avoid using the bidirectional mechanism it provides and define
+% commands and environments that use \LuaTeX\ primitives to set the
+% writing direction. Then, an Arabic edition text\---to continue with
+% this example\---can be entered as follows:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false,escapeinside=++]{latex}
+\begin{ekdosis}
+  \begin{Arabic}
+    +\txarb{إِنَّ أَبِي كَانَ مِنَ}+ \app{
+      \lem{+\txarb{ٱلْمُقَاتِلَةِ}+}
+      \rdg{+\txarb{ٱلْمُقَاتِلِينَ}+}
+      } +\txarb{وَ كَانَتْ أُمِّي مِنْ عُظَمَآءِ بُيُوتِ ٱلزَّمَازِمَةِ۔}+
+  \end{Arabic}
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% It should be reminded that the writing direction of the apparatus
+% criticus itself is independent of that of the edition text and must
+% be set either with \cs{Set(LTR{\textbar}RTL)app}, with the
+% |direction| optional argument of \cs{SetApparatus} for single-layer
+% apparatus criticus, or by means of \cs{DeclareApparatus} for
+% multiple-layer apparatus criticus.\footnote{See above
+% \vref{sec:single-layer-app} (single-layer apparatus criticus) and
+% \vref{sec:multilayer-apparatus} (multiple-layer apparatus
+% criticus).}
+%
+% PDF output with left-to-right apparatus criticus:---
+% \medskip
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+%   \begin{specimen}
+%     \begin{arab}[fullvoc]
+%       'inna 'abI kAna mina \app[type=ltr]{
+%       \lem{'l-muqAtilaTi}
+%       \rdg{'l-muqAtilIna}}
+%       wa-kAnat 'ummI min `u.zamA'i buyUti 'l-zamAzimaTi.
+%     \end{arab}
+%   \end{specimen}
+% \end{alignment}
+%
+% PDF output with right-to-left apparatus criticus:---
+% \medskip
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+%   \begin{specimen}
+%     \begin{arab}[fullvoc]
+%       'inna 'abI kAna mina \app[type=rtl]{
+%       \lem{'l-muqAtilaTi}
+%       \rdg{'l-muqAtilIna}}
+%       wa-kAnat 'ummI min `u.zamA'i buyUti 'l-zamAzimaTi.
+%     \end{arab}
+%   \end{specimen}
+% \end{alignment}
+%
+%
+% \subsection{Using \pkg{arabluatex}}
+% \label{sec:using-arabluatex}
+% 
+%
 % \section{To Be Continued...}
 % v1.0 of \pkg{ekdosis}, which should be available by the end of July
 % 2020, will include a full documentation. At the time of writing, the
@@ -5706,7 +5971,7 @@ function ekdosis.newalignment(str)
    then
       newalignment = false
       cur_alignment = "-"
-      cur_alignment_patt = "-"
+      cur_alignment_patt = "%-"
    end
    return true
 end
@@ -6132,6 +6397,7 @@ function ekdosis.testapparatus()
       if next(apparatuses) ~= nil then
          reset_bagunits()
       end
+      newalignment = false
       return "\\booltrue{do@app}"
    end
 end