new option maxentries to \DeclareApparatus so that ekdosis may take the right set of page decisions

1 files changed, 107 insertions, 38 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index c85aec8..bd829b0 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -331,7 +331,7 @@ along with this program.  If not, see
   \def\oasymbol{\faUnlock}
   \usepackage{biblatex-ext-oa}
 }
-{\usepackage[symbolpackage=l3draw]{biblatex-ext-oa}}
+{\usepackage[symbolpackage=tikz]{biblatex-ext-oa}}
 \DeclareDelimFormat[bib,biblist]{nametitledelim}{\addcomma\space}
 \DeclareDelimFormat[bib,biblist]{innametitledelim}{\addcomma\space}
 \renewcommand*\newunitpunct{\addcomma\space}
@@ -2175,6 +2175,22 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % \iffalse
 %</example>
 % \fi
+% 
+% \paragraph{Limiting the Number of Entries per Page}
+% In some instances, it can be useful to set a limit to the number of
+% entries per page that a given layer of critical notes may accept,
+% notably when entries are so abundant in number that \pkg{ekdosis}
+% may oscillate indefinitely between different sets of page decisions
+% without being able to settle down.\\
+% \DescribeOption{maxentries} |maxentries|=\meta{n} (where $n \geq
+% 10$) \hfill\tcboxverb{Default: not set}\\
+% If |maxentries|$=$\meta{n} be set, then \pkg{ekdosis} will issue
+% \cs{pagebreak} (namely \cs{penalty}|-10000|) just after the
+% \emph{n\textsuperscript{th}} entry has been inserted in the layer of
+% the apparatus criticus this option is related to. As a result, the
+% page will actually break at the end of the current line. The
+% particulars of this technique will be discussed below in
+% \vref{sec:tricks-of-trade}.
 %
 % \section{Inserting Notes in Multiple-Layer Apparatus}
 % \label{sec:notes-in-multilayer-app}
@@ -2904,6 +2920,15 @@ subtype="arabtex">'inna 'abI kAna mina
 % must be set to |latex| explicitly\---viz. |divs=latex|\---as
 % described above \vpageref{ref:divs-opt}.
 %
+% \danger As the \env{alignment} environment that is provided by
+% \pkg{ekdosis} places all aligned texts within \texttt{TEI xml}
+% un-numbered |<div>| elements and \LaTeX\ textual divisions are
+% converted into numbered |<div|\textsubscript{\emph{n}}|>| elements,
+% inserting such divisions in texts to be aligned will result in an
+% invalid \texttt{TEI xml} output. Instead, un-numbered divisions
+% through \cs{ekddiv} must be used as described below in
+% \vref{sec:ekddiv}.
+%
 % Once |divs| has been set to |latex|, \pkg{ekdosis} converts
 % \cs{book}, \cs{part}, \cs{chapter}, \cs{section}, \cs{subsection}
 % and \cs{subsubsection} into corresponding \texttt{TEI}
@@ -3082,6 +3107,7 @@ subtype="arabtex">'inna 'abI kAna mina
 %</example>
 % \fi
 %
+% \needspace{5\baselineskip}
 % PDF output:---
 % \medskip
 % 
@@ -3138,6 +3164,10 @@ subtype="arabtex">'inna 'abI kAna mina
 %</example>
 % \fi
 %
+% \section{The Tricks of the Trade}
+% \label{sec:tricks-of-trade}
+%
+%
 % \section{\texttt{TEI xml} Output}
 % \label{sec:teixml-output}
 % Several examples of \texttt{TEI xml} output have been provided
@@ -3150,31 +3180,31 @@ subtype="arabtex">'inna 'abI kAna mina
 % \texttt{TEI xml} (l.~11), the preamble of this file shows how to set
 % languages and fonts to be used in the document (ll.~2--6), format
 % the titles (l.~16) and lay out the alignment of an edition text
-% associated with two translations (ll.~18--25). Furthermore, it shows
-% how information related to each language (Latin, English and French)
-% is to be found in two different places, namely for \texttt{TEI xml}
-% output (ll.~21--3) and for PDF output through \LaTeX\
-% (ll.~27--9). Finally, it provides examples of declaring witnesses,
-% hands, scholars and shorthands (ll.~31--60). As to the document
-% itself, it shows how to lay out a conspectus siglorum in a table
-% (ll.~64--80), before giving detailed examples of how the edition
-% text is entered (ll~85--101) and sectional commands provided by
-% \pkg{ekdosis} are used (ll.~86, 103 and 110).\footnote{The PDF
-% output is available as \href{samples/Caesar_BG-6-13-1.pdf}{a
-% separate file}.}
+% associated with two translations (ll.~18--25) in modern
+% languages. Furthermore, it shows how information related to each
+% language (Latin, English and French) is to be found in two different
+% places, namely for \texttt{TEI xml} output (ll.~21--3) and for PDF
+% output through \LaTeX\ (ll.~27--9). Finally, it provides examples of
+% declaring witnesses, hands, scholars and shorthands (ll.~31--60). As
+% to the document itself, it shows how to lay out a conspectus
+% siglorum in a table (ll.~64--80), before giving detailed examples of
+% how the edition text is entered (ll.~85--101) and sectional commands
+% provided by \pkg{ekdosis} are used (ll.~86, 103 and
+% 110).\footnote{The PDF output is available as
+% \href{samples/Caesar_BG-6-13-1.pdf}{a separate file}.}
 %
 % \subsection{Requesting \texttt{TEI xml} Output}
 % \label{sec:request-tei-output}
 % \texttt{TEI xml} output is requested by means of the |teiexport|
 % global option as described above
 % \vpageref{ref:teiexport-option}. Once instructed to output
-% \texttt{TEI}, \pkg{ekdosis} converts in sequence the contents of
-% \env{ekdosis} environments (see above
+% \texttt{TEI}, \pkg{ekdosis} converts and exports in sequence the
+% contents of \env{ekdosis} environments (see above
 % \vref{sec:single-text-editing}). As regards the contents of
 % \env{alignment} environments (see above \vref{sec:alignment-basic}),
 % \pkg{ekdosis} first collates the contents of the environments that
-% have been declared with the |texts| optional argument of
-% \env{alignment} or with \cs{SetAlignment},\footnote{See above
+% have been declared as values of the |texts| optional argument of
+% \env{alignment} or \cs{SetAlignment},\footnote{See above
 % \vref{sec:multiple-alignment}.} then places each of the
 % corresponding \texttt{TEI xml} outputs within distinct |<div>|
 % elements named after the declared environments themselves. For
@@ -3183,10 +3213,17 @@ subtype="arabtex">'inna 'abI kAna mina
 % (see the |.tex| source file, \vref{sec:caesar-gw-tex}, ll.~85--101)
 % which is declared at l.~21. Then, the corresponding \texttt{xml}
 % output is found within a |<div>| element, the |xml:id| of which has
-% been called by \pkg{ekdosis} |div-latin_1| (see
+% been given by \pkg{ekdosis} the value |div-latin_1| (see
 % \vref{sec:caesar-gw-tei}, ll.~176--200).
 %
+% \paragraph{\texttt{TEI} File Name} \DescribeMacro{\SetTEIFilename}
+% \cs{SetTEIFilename}\marg{basename} is a preamble-only command. It
+% can be used to set the base name of the \texttt{TEI xml} output
+% file, to which the suffix |.xml| is appended. By default, the base
+% name is \cs{jobname}|-tei|.
 %
+% \subsection{General Principles}
+% \label{sec:totei-general-principles}
 % \paragraph{Validation of the \texttt{TEI xml} Structure}
 % The reference tool that the author relies on is that provided by the
 % \emph{\texttt{TEI} by Example Project}.\footnote{\cite{TBE}.
@@ -3197,14 +3234,13 @@ subtype="arabtex">'inna 'abI kAna mina
 % said, one must keep in mind that the \LaTeX\ packages that are part
 % of {\TeX}Live can be counted in thousands, and the commands they
 % provide in tens of thousands. There may even be grounds in asserting
-% that the possibilities offered by \TeX\ and \LaTeX\ exceed what can
-% be afforded by \texttt{TEI xml}. On another hand, many \LaTeX\
-% commands make no sense in \texttt{TEI}. Therefore, a sensible choice
-% is to keep them out of the environments the contents of which are to
-% be translated into \texttt{xml} elements.
-%
-% \subsection{General Principles}
-% \label{sec:totei-general-principles}
+% that the possibilities offered by \TeX\ and \LaTeX\ quite exceed
+% what can be afforded by \texttt{TEI xml}. On another hand, many
+% \LaTeX\ commands make no sense in \texttt{TEI}. Therefore, a
+% sensible choice is to keep them out of the environments the contents
+% of which are to be translated into \texttt{xml} elements, as will be
+% illustrated by the following.
+% 
 % Converting a \LaTeX\ document into \texttt{TEI xml} is quite an
 % intricate business. In many cases, \LaTeX\ strings are found within
 % environments or groups: whether such groups are delimited by opening
@@ -4149,6 +4185,7 @@ subtype="arabtex">'inna 'abI kAna mina
   store sep = \sep@val,
   store bhook = \bhook@val,
   store ehook = \ehook@val,
+  store maxentries = \limit@val,
   initial direction = LR,
   initial delim = {},
   initial ehook = {\csname ekd@end@apparatus\endcsname}
@@ -4158,11 +4195,13 @@ subtype="arabtex">'inna 'abI kAna mina
 % \cs{DeclareApparatus}\marg{apparatus name}\oarg{options} is a
 % preamble-only command. As a mandatory argument, it takes the name of
 % the new layer of notes to be inserted in the apparatus block. Then,
-% the following six key-value options can be used to lay out the
+% the following seven key-value options can be used to lay out the
 % layer: \verb+direction=LR|RL+, |rule|, |delim| (the delimiter between
 % entries), |sep| (the separator between lemma part and readings or
 % notes), |bhook| (\LaTeX{} code inserted as the layer begins),
-% |ehook| (\LaTeX{} code inserted as the layer ends):---
+% |ehook| (\LaTeX{} code inserted as the layer ends), |maxentries|
+% (if set and |maxentries >= 10|, the number of entries at which a
+% \cs{pagebreak} is issued):---
 %    \begin{macrocode}
 \NewDocumentCommand{\DeclareApparatus}{m O{}}{
   \newbool{subsq@unit@#1}
@@ -4177,7 +4216,8 @@ subtype="arabtex">'inna 'abI kAna mina
     \luastringO{\delim@val},
     \luastringO{\sep@val},
     \luastringO{\bhook@val},
-    \luastringO{\ehook@val}
+    \luastringO{\ehook@val},
+    \luastringO{\limit@val}
     )}
   \egroup
 }
@@ -4726,6 +4766,7 @@ subtype="arabtex">'inna 'abI kAna mina
     \luadirect{ekdosis.increment_bagunits(\luastringO{\ekdan@type})}%
     \def\ekd@munit@delim{%
       \luadirect{tex.sprint(ekdosis.getappdelim(\luastringO{\ekdan@type}))}}%
+    \luadirect{tex.sprint(ekdosis.limit_bagunits(\luastringO{\ekdan@type}))}%
   \fi%
   \ifekdl@nolem\edef\lem@app{%
     % \hskip .75em
@@ -4934,6 +4975,7 @@ subtype="arabtex">'inna 'abI kAna mina
   \luadirect{ekdosis.increment_bagunits(\luastringO{\ekdan@type})}%
     \def\ekd@munit@delim{%
       \luadirect{tex.sprint(ekdosis.getappdelim(\luastringO{\ekdan@type}))}}%
+    \luadirect{tex.sprint(ekdosis.limit_bagunits(\luastringO{\ekdan@type}))}%
   \fi%  
   \ifdefined\ekdn@labelb%
     \luadirect{tex.sprint(ekdosis.setnotelab(\luastringO{\ekdn@labelb}))}%
@@ -5663,13 +5705,6 @@ local cmdtotags = {
 
 local texpatttotags = {
    {a="\\altrfont%s+", b=""},
-   -- {a="\\icite%s?%[(.-)%]%[(.-)%]{(.-)}", b="%1 <ref target=\"#%3\">%2</ref>"},
-   -- {a="\\icite%s?%[(.-)%]{(.-)}", b="<ref target=\"#%2\">%1</ref>"},
-   -- {a="\\icite%s?{(.-)}", b="<ptr target=\"#%1\"/>"},
-   -- {a="\\linelabel%s?{(.-)}", b="<anchor xml:id=\"%1\"/>"},
-   -- {a="\\label%s?{(.-)}", b="<anchor xml:id=\"%1\"/>"},
-   -- {a="\\v?pageref%s?{(.-)}", b="<ptr target=\"#%1\"/>"},
-   -- {a="\\v?ref%s?{(.-)}", b="<ptr target=\"#%1\"/>"},
    {a="\\LR%s+{(.-)}", b="%1"},
    {a="\\RL%s+{(.-)}", b="%1"}
 }
@@ -6879,7 +6914,8 @@ function ekdosis.newapparatus(teitype,
                               appdelim,
                               appsep,
                               appbhook,
-                              appehook)
+                              appehook,
+                              applimit)
    if isintable(apparatuses, teitype)
    then
       tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
@@ -6892,7 +6928,8 @@ function ekdosis.newapparatus(teitype,
                                  delim = appdelim,
                                  sep = appsep,
                                  bhook = appbhook,
-                                 ehook = appehook})
+                                 ehook = appehook,
+                                 limit = applimit})
    end
    bagunits[teitype] = 1
    return true
@@ -6913,6 +6950,38 @@ function ekdosis.get_bagunits(teitype)
    return bagunits[teitype]
 end
 
+local function getapplimit(str)
+   for i = 1,#apparatuses
+   do
+      if apparatuses[i].a == str then
+         limitfound = apparatuses[i].limit
+         break
+      end
+   end
+   if tonumber(limitfound) ~= nil
+   then
+      if tonumber(limitfound) < 10
+      then
+         return 0
+      else
+         return limitfound
+      end
+   else
+      return 0
+   end
+end
+
+function ekdosis.limit_bagunits(teitype)
+   local limit = tonumber(getapplimit(teitype))
+   if limit >= 10 and bagunits[teitype] > limit
+   then
+      bagunits[teitype] = 2
+      return "\\pagebreak"
+   else
+      return ""
+   end
+end
+
 function ekdosis.increment_bagunits(teitype)
    bagunits[teitype] = (bagunits[teitype] or 0) + 1
 end