new option to set 'maxentries' globally in \SetHooks

2 files changed, 106 insertions, 30 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 1b794b6..e285197 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -61,7 +61,7 @@ along with this program.  If not, see
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{ekdosis}
 %<*package>
-    [2022/05/04 v1.5-dev Typesetting TEI xml-compliant critical editions]
+    [2022/05/09 v1.5-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -638,7 +638,7 @@ along with this program.  If not, see
 \babeltags{ancientgreek = greek}
 \def\sg#1{\textancientgreek{#1}}
 \usepackage[biblatex=true]{embrac}
-\usepackage[nospace,american]{varioref}
+\usepackage[nospace,american,draft]{varioref}
 \usepackage{addlines}
 \newcommand\phts{\phantomsection}
 \usepackage{chifoot}
@@ -1327,8 +1327,9 @@ along with this program.  If not, see
 %   characters is reduced to allow for additional entries. As a
 %   consequence of this rationale, the total number of entries on a
 %   given page must not be too high. It is therefore advisable to use
-%   |layout=fitapp| conjointly with |maxentries| as described below
-%   \vpageref{ref:maxentries} and in \vref{sec:oscillating-problem}. %
+%   |layout=fitapp| conjointly with |maxentries| as described below on
+%   pages~\pageref{ref:glimit} and~\pageref{ref:maxentries} and in
+%   \vref{sec:oscillating-problem}.
 %   \danger If used appropriately, this mechanism gives excellent
 %   typographical results, notably with complex edition texts of which
 %   the entries in the associated apparatus can be quite abundant in
@@ -3647,6 +3648,29 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % An example of the way these hooks may be used is provided below in
 % \vref{lst:shak-sonnet1}.
 %
+% \medskip\noindent\textbf{Limiting the Number of Entries per Page}
+% \phts\label{ref:glimit}\\
+% \DescribeOption{maxentries} |maxentries|=\meta{n} (where
+% $n \geq 10$) \hfill\tcboxverb{Default: not set}\\
+% \newfeature[v1.5] This option may be used to set a limit to the
+% number of entries per page that \emph{all layers of critical notes
+% taken together} 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.
+% \danger It is also possible to restrict this option to a given layer
+% of the apparatus criticus as described below
+% \vpageref{ref:maxentries}. If |maxentries| be set both globally in
+% \cs{SetHooks} and in \cs{DeclareApparatus} for specific layers, then
+% the page will break when \emph{any} of the values defined as
+% |maxentries| has been reached.
+% 
+% 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 whichever
+% layer of the apparatus criticus. 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:oscillating-problem}.
+% 
 % \medskip
 % \noindent\textbf{Option Specific to the |layout=keyfloat| Global
 % Setting}\footnote{See above \vref{ref:keyfloat-opt}.}\\
@@ -3991,14 +4015,24 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % 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}\\
+% 10$) \hfill\tcboxverb{Default: not set}
+% \danger It is also possible to set a maximum number of entries for
+% all layers of critical notes taken together as described above 
+% \vpageref{ref:glimit}. If |maxentries| be set both globally in
+% \cs{SetHooks} and in \cs{DeclareApparatus} for specific layers, then
+% the page will break when \emph{any} of the values defined as
+% |maxentries| has been reached.
+% 
 % 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:oscillating-problem}.
+% \vref{sec:oscillating-problem}.\\
+% \DescribeOption{nomaxentries}\hfill\tcboxverb{Default: not set}\\
+% |nomaxentries| does not accept any value and is equivalent to
+% |maxentries=none|.\\
 %
 % \section{Inserting Notes in Multiple-Layer Apparatus}
 % \label{sec:notes-in-multilayer-app}
@@ -6145,11 +6179,13 @@ subtype="arabtex">'inna 'abI kAna mina
 %
 % \paragraph{Using \texttt{maxentries}}
 % Another way\---should the edition text fall into the vicious circle
-% too often\---is to limit the number of entries per page that a given
-% layer of apparatus criticus may accept as described above
-% \vpageref{ref:maxentries}. As a result, \pkg{ekdosis} will take care
-% of inserting automatic breakpoints between pages whenever the number
-% of entries on a given page reaches the value set as |maxentries|.
+% too often\---is to limit the number of entries per page that all
+% layers of critical notes taken together or a given layer of
+% apparatus criticus may accept as described above on
+% pages~\pageref{ref:glimit} and~\pageref{ref:maxentries}. As a result,
+% \pkg{ekdosis} will take care of inserting automatic breakpoints
+% between pages whenever the number of entries on a given page reaches
+% the value set as |maxentries|.
 %
 % |maxentries| must not be too small: otherwise offensive to look at
 % vertical spaces may come between the edition text and the apparatus
@@ -8200,7 +8236,7 @@ Sample text with a \textcolor{red}{word} in red.
 \fi
 \if@pkg@fitapp
   \RequirePackage{tcolorbox}
-  \tcbuselibrary{fitting,skins}
+  \tcbuselibrary{fitting,skins} %,breakable}
 \fi
 \RequirePackage{refcount}
 \RequirePackage{zref-user}
@@ -8226,7 +8262,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \paragraph{\textsf{ekdosis} Symbol}
 % \begin{macro}{\eKd}
-% \changes{v1.5}{2022/05/04}{Prints \textsf{ekdosis} indentifying
+% \changes{v1.5}{2022/05/09}{Prints \textsf{ekdosis} indentifying
 % symbol} As of v1.5, \pkg{ekdosis} has its own identifying
 % symbol. It is produced by \cs{eKd} and best printed with the Old
 % Standard Greek font.
@@ -8272,6 +8308,11 @@ Sample text with a \textcolor{red}{word} in red.
   code familysep = \luadirect{ekdosis.setfamilysep(\luastringN{#1})},
   store lemmastyle = \ekd@lemmastyle,
   store readingstyle = \ekd@readingstyle,
+  code initialrule = \def\ekd@initial@rule{#1\NLS},
+  default initialrule = \rule{0.4\columnwidth}{0.4pt},
+  noval noinitialrule = \undef\ekd@initial@rule,
+  code maxentries = \luadirect{ekdosis.setglimit(\luastringN{#1})},
+  nmeta nomaxentries = {maxentries=none},
   code keyparopts = \if@pkg@keyfloat\ekd@keyparopts{#1}\fi,
   dimen appheight = \ekd@app@height,
   initial appheight = .5\textheight,
@@ -8283,9 +8324,6 @@ Sample text with a \textcolor{red}{word} in red.
   unknown-choice fitalgorithm = \PackageError{ekdosis}{unknown
     fitalgorithm=#1}{`fitalgorithm' must be either `fontsize',
     `hybrid', `areasize' or `squeeze'.},
-  code initialrule = \def\ekd@initial@rule{#1\NLS},
-  default initialrule = \rule{0.4\columnwidth}{0.4pt},
-  noval noinitialrule = \undef\ekd@initial@rule,
   initial appfontsize = \footnotesize,
   initial refnumstyle = \bfseries,
   initial postrefnum = ~,
@@ -8487,7 +8525,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \begin{macro}{\teidirectE}
 % \changes{v1.3}{2021/08/18}{direct insertion of elements in the
 % \texttt{TEI xml} file}
-% \changes{v1.5}{2022/05/04}{direct insertion of empty elements in the
+% \changes{v1.5}{2022/05/09}{direct insertion of empty elements in the
 % \texttt{TEI xml} file}
 % \cs{teidirect}\oarg{xml attributes}\marg{xml element}\marg{code}
 % does nothing in \LaTeX. It is only used to insert elements in the
@@ -8502,7 +8540,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\getTEIxmlid}
-% \changes{v1.5}{2022/05/04}{returns \texttt{TEI xml:ids} from a
+% \changes{v1.5}{2022/05/09}{returns \texttt{TEI xml:ids} from a
 % csv-list of ids} This command returns from a csv-list of unique
 % identifiers declared in commands such as \cs{DeclareWitness} and the
 % like a space-separated list of their corresponding |xml:id|s, each
@@ -8975,6 +9013,7 @@ Sample text with a \textcolor{red}{word} in red.
 \if@pkg@fitapp
   \newtcboxfit{\ekd@fitapp}{%
     blankest,
+    % breakable,
     fit basedim = \f@size pt,
     fit fontsize macros,
     fit height from=0pt to \ekd@app@height,
@@ -10078,7 +10117,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \paragraph{Lacunae}
 % \begin{macro}{\ilabel}
-% \changes{v1.5}{2022/05/04}{recalls and sets the ending label of
+% \changes{v1.5}{2022/05/09}{recalls and sets the ending label of
 % lemmas used to mark lacunae in witnesses} When \cs{lem} has been
 % used with the optional argument |ilabel=<label>|,
 % \cs{ilabel}\marg{label} must be used to mark the point where the
@@ -10393,7 +10432,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\ekdEOprint}
-% \changes{v1.5}{2022/05/04}{Sets headers and footers on
+% \changes{v1.5}{2022/05/09}{Sets headers and footers on
 % \enquote{paired} facing pages}
 % To set headers and footers on \enquote{paired} facing pages,
 % \cs{ekdEOprint} accepts two mandatory, self-evident arguments, like
@@ -10433,7 +10472,7 @@ Sample text with a \textcolor{red}{word} in red.
 % counter to set the value of the page numbers. This counter should be
 % incremented every two pages.
 % \begin{counter}{pairedpage}
-% \changes{v1.5}{2022/05/04}{A counter incremented every two pages}
+% \changes{v1.5}{2022/05/09}{A counter incremented every two pages}
 % |pairedpage| is first set as a global counter:---
 %    \begin{macrocode}
 \newcounter{pairedpage}
@@ -10441,19 +10480,19 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{counter}
 % \begin{macro}{\setpairedpagenum}
-%   \changes{v1.5}{2022/05/04}{sets the same page number on paired
+%   \changes{v1.5}{2022/05/09}{sets the same page number on paired
 %   pages} \cs{setpairedpagenum}\marg{number} is used just ahead of
 %   the alignment environment to set the number of the first left-hand
 %   paired page.
 % \begin{macro}{\setpairedpage}
-%   \changes{v1.5}{2022/05/04}{sets the page number of the first paired
+%   \changes{v1.5}{2022/05/09}{sets the page number of the first paired
 %   page} \cs{setpairedpage} is an argument-less command meant to be
 %   issued in commands used to set headers or footers before
 %   \cs{thepage}. This command has the counter |pairedpage|
 %   incremented on right-hand pages only, and sets |page| $\leftarrow$
 %   |pairedpage| on every page.
 % \begin{macro}{\resetpagenumber}
-%   \changes{v1.5}{2022/05/04}{resets normal running page numbers}
+%   \changes{v1.5}{2022/05/09}{resets normal running page numbers}
 %   \cs{resetpagenumber} must be used right out of \enquote{mirrored}
 %   paired pages alignment environments. This argument-less command
 %   corrects any numbering error on the page following the edition
@@ -12785,6 +12824,8 @@ end
 --
 local apparatuses = {}
 local bagunits = {}
+local glimit = nil
+local gunits = 0
 
 function ekdosis.newapparatus(teitype,
                               appdir,
@@ -12877,28 +12918,61 @@ end
 
 function ekdosis.limit_bagunits(teitype)
    local limit = tonumber(getapplimit(teitype))
-   if limit >= 10 and bagunits[teitype] >= limit
-   then
-      bagunits[teitype] = 2
-      return "\\pagebreak"
+   if glimit then
+      glimit = tonumber(glimit)
+      gunits = tonumber(gunits)
+      if glimit >= 10 and gunits >= glimit
+      then
+         bagunits[teitype] = 2
+         gunits = 0
+         return "\\pagebreak"
+      else
+         if limit >= 10 and bagunits[teitype] >= limit
+         then
+            bagunits[teitype] = 2
+            gunits = 0
+            return "\\pagebreak"
+         else
+            return ""
+         end
+      end
    else
-      return ""
+      if limit >= 10 and bagunits[teitype] >= limit
+      then
+         bagunits[teitype] = 2
+         gunits = 1
+         return "\\pagebreak"
+      else
+         return ""
+      end
    end
 end
 
 function ekdosis.addto_bagunits(teitype, n)
+   n = tonumber(n)
+   if glimit then gunits = gunits - n end
    if tonumber(getapplimit(teitype)) ~= 0
    then
-      n = tonumber(n)
       bagunits[teitype] = bagunits[teitype] - n
    end
 end
 
 function ekdosis.increment_bagunits(teitype)
+   if glimit then gunits = gunits + 1 end
    bagunits[teitype] = (bagunits[teitype] or 0) + 1
 end
 
+function ekdosis.setglimit(n)
+   if math.tointeger(n)
+   then
+      glimit = math.tointeger(math.abs(n))
+   else
+      glimit = nil
+   end
+end
+
 local function reset_bagunits()
+   if glimit then gunits = 0 end
    for i = 1,#apparatuses
    do
       bagunits[apparatuses[i].a] = 1
diff --git a/ekdosis.el b/ekdosis.el
index 95af33e..322d552 100644
--- a/ekdosis.el
+++ b/ekdosis.el
@@ -157,6 +157,8 @@
     ("familysep")
     ("initialrule")
     ("noinitialrule")
+    ("maxentries")
+    ("nomaxentries")
     ("keyparopts")
     ("appheight")
     ("fitalgorithm" ("fontsize" "hybrid" "areasize" "squeeze")))