added 'maxlines' functions and new commands to change 'appheight' locally

1 files changed, 213 insertions, 19 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 56bd0d5..f6571f6 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/09/01 v1.5-dev Typesetting TEI xml-compliant critical editions]
+    [2022/10/25 v1.5-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -5110,9 +5110,15 @@ substantiall fewell,}
 % \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.\\
-% \textbf{Options Specific to the |poetry=verse| Global
-% Setting}\footnote{See above
+% already provided by the \pkg{lineno} package.
+% 
+% \medskip\noindent\textbf{Limiting the Number of Lines per Page}
+% \phts\label{ref:gmaxlines}\\
+% \DescribeOption{maxlines} \newfeature[v1.5] |maxlines|=\meta{n}
+% \hfill\tcboxverb{Default: not set}\\
+% 
+% \medskip\noindent\textbf{Options Specific to the |poetry=verse|
+% Global Setting}\footnote{See above
 % \vref{sec:verse-package}.}\phts\label{ref:verse-lineation}\\
 % \DescribeOption{vlineation} |vlineation|$=$\verb+page|document+
 % \hfill\tcboxverb{Default: document}\\
@@ -8403,7 +8409,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \paragraph{\textsf{ekdosis} Symbol}
 % \begin{macro}{\eKd}
-% \changes{v1.5}{2022/09/01}{Prints \textsf{ekdosis} indentifying
+% \changes{v1.5}{2022/10/25}{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.
@@ -8425,7 +8431,7 @@ Sample text with a \textcolor{red}{word} in red.
   store spbmk = \ekd@spbmk,
   initial spbmk = spb,
   store hpbmk = \ekd@hpbmk,
-  initial hpbmk = hpb,
+  initial hpbmk = hpb
 }
 \NewDocumentCommand{\ekdsetup}{m}{\ekvset{ekd@setup}{#1}}
 \@onlypreamble\ekdsetup
@@ -8666,7 +8672,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/09/01}{direct insertion of empty elements in the
+% \changes{v1.5}{2022/10/25}{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
@@ -8681,7 +8687,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\getTEIxmlid}
-% \changes{v1.5}{2022/09/01}{returns \texttt{TEI xml:ids} from a
+% \changes{v1.5}{2022/10/25}{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
@@ -8853,7 +8859,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \begin{macro}{\ekdpb}
 % \changes{v1.2}{2021/04/02}{conditional page breaks}
-% \cs{ekdpk}\oarg{page no}\marg{line no} is used to insert conditional
+% \cs{ekdpb}\oarg{page no}\marg{line no} is used to insert conditional
 % page breaks by specifying that the page break should occur only on a
 % given line and optionally a given page. If the specified conditions
 % be met then this command triggers \cs{pagebreak}.
@@ -9151,6 +9157,49 @@ Sample text with a \textcolor{red}{word} in red.
 \newif\ifekd@inside@app
 \newif\ifekd@keepinapp
 %    \end{macrocode}
+% \cs{ekd@app@localheight} is used to set the maximum height of the
+% apparatus block locally:---
+%    \begin{macrocode}
+\newlength{\ekd@app@localheight}
+%    \end{macrocode}
+% \begin{macro}{\localappheight}
+% \changes{v1.5}{2022/10/25}{changes the height of the apparatus
+% criticus}
+% \cs{localappheight}\marg{dimen} can be used to change locally the
+% length of \cs{\ekd@app@height} set by the |appheight| option of
+% \cs{SetHooks}, namely the height up to which the apparatus block is
+% allowed to grow. \meta{dimen} must be a number followed by a unit
+% length. This command operates only on the apparatus block that
+% follows it.
+%    \begin{macrocode}
+\def\localappheight#1{%
+  \if@pkg@fitapp
+    \luadirect{ekdosis.changeappheight()}%
+    \setlength{\ekd@app@localheight}{#1}%
+  \fi
+  \ignorespaces
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\addtoappheight}
+% \changes{v1.5}{2022/10/25}{increases or decreases the height of the
+% apparatus criticus}
+% As the name suggests, in contrast to \cs{localappheight},
+% \cs{addtoappheight}\marg{dimen} is used to increase or decrease
+% locally the length of \cs{\ekd@app@height}. \meta{dimen} must be a
+% number followed by a unit length. This command operates only on the
+% apparatus block that follows it.
+%    \begin{macrocode}
+\def\addtoappheight#1{%
+  \if@pkg@fitapp
+    \luadirect{ekdosis.changeappheight()}%
+    \setlength{\ekd@app@localheight}{\ekd@app@height}%
+    \addtolength{\ekd@app@localheight}{#1}%
+  \fi
+  \ignorespaces
+}
+%    \end{macrocode}
+% \end{macro}
 % Then \cs{ekd@fitapp} is defined for |layout=fitapp|:---
 %    \begin{macrocode}
 \if@pkg@fitapp
@@ -9195,7 +9244,21 @@ Sample text with a \textcolor{red}{word} in red.
   \apparatus\unless\ifekd@mapps\ekd@end@apparatus\fi
   \ekd@inside@appfalse
   \if@pkg@parnotes\parnotes\parnotereset\fi    
-}%
+}
+%    \end{macrocode}
+% Depending on what is instructed, either of the following two
+% commands is inserted by the Lua function
+% |ekdosis.setheightandprintapparatus()| that is used in
+% \cs{add@apparatus} below:---
+%    \begin{macrocode}
+\def\ekd@insert@fitapparatus@tmpheight{%
+  \let\ekd@app@savedheight\ekd@app@height
+  \let\ekd@app@height\ekd@app@localheight
+  \ekd@fitapp{\ekd@insert@apparatus}%
+  \let\ekd@app@height\ekd@app@savedheight}
+\def\ekd@insert@fitapparatus{%
+  \ekd@fitapp{\ekd@insert@apparatus}%
+}
 \def\add@@apparatus{%
   \if@pkg@parnotes\parnotes\else\fi
   \if@pkg@footins
@@ -9231,7 +9294,7 @@ Sample text with a \textcolor{red}{word} in red.
     \ekd@insert@keyparapp
   \fi
   \if@pkg@fitapp
-    \ekd@fitapp{\ekd@insert@apparatus}%
+    \luadirect{tex.sprint(ekdosis.setheightandprintapparatus())}%
   \fi
   % \if@pkg@breakable
   %   \ekd@breakable{\ekd@insert@apparatus}%
@@ -9317,8 +9380,16 @@ Sample text with a \textcolor{red}{word} in red.
 %    \begin{macrocode}
 \newif\ifekd@pagelineation
 \newif\ifekd@pagevlineation
+%    \end{macrocode}
+% Two counters (|ekd@lnperpage| and |ekd@locallnperpage|) are defined
+% here and will be used below to allow \pkg{ekdosis} to have control
+% over the maximum number of lines to be printed per page.
+%    \begin{macrocode}
+\newcounter{ekd@lnperpage}
+\newcounter{ekd@locallnperpage}
 \NewDocumentCommand{\ekdatbegshihook}{}{%
   \ifekd@pagelineation\resetlinenumber\fi
+  \setcounter{ekd@lnperpage}{0}%
 }
 \AddToHook{shipout/before}{\ekdatbegshihook}
 \newif\ifekd@elidednumbers
@@ -9357,7 +9428,9 @@ Sample text with a \textcolor{red}{word} in red.
     right = \if@pkg@poetry@verse\verselinenumbersright\fi,
     left = \if@pkg@poetry@verse\verselinenumbersleft\fi},
   unknown-choice vmargin = \PackageError{ekdosis}{unknown
-    vmargin=#1}{`margin' must be either `left' ot `right'}
+    vmargin=#1}{`margin' must be either `left' ot `right'},
+  code maxlines = \def\maxlines@value{#1},
+  code nomaxlines = \undef\maxlines@value
 }
 %    \end{macrocode}
 % \begin{macro}{\SetLineation}
@@ -9391,6 +9464,73 @@ Sample text with a \textcolor{red}{word} in red.
 %    \begin{macrocode}
 \renewcommand\linenumberfont{\normalfont\footnotesize}
 %    \end{macrocode}
+% \paragraph{Limiting the Number of Lines per Page}
+% The following commands are provided to set and control the maximum
+% number of lines printed on each page.
+% \begin{macro}{\setmaxlines}
+% \changes{v1.5}{2022/10/25}{limits the number of lines per page}
+% \cs{setmaxlines}\marg{n}, where \meta{n} is a positive integer
+% $\geq 1$, can be used either in the preamble or at any point of the
+% document to set the maximum number of lines to be printed on each
+% page.  This command has the same effect as the |maxlines| option
+% of \cs{SetLineation}.
+%    \begin{macrocode}
+\def\setmaxlines#1{\def\maxlines@value{#1}}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\localmaxlines}
+% \changes{v1.5}{2022/10/25}{changes the maximum number of lines
+% locally}
+% Once a maximum number of lines per page has been set,
+% \cs{localmaxlines}\marg{n} can be used to adjust this number on a
+% given page.  As for \cs{setmaxlines}, \meta{n} must be a positive
+% integer $\geq 1$.
+%    \begin{macrocode}
+\def\localmaxlines#1{%
+  \luadirect{tex.sprint(ekdosis.setlocalmaxlines(\luastringN{#1}))}%
+  \ignorespaces}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\addtomaxlines}
+% \changes{v1.5}{2022/10/25}{adds or subtracts lines from a given page}
+% Unlike \cs{localmaxlines}, \cs{addtomaxlines}\meta{n} takes as
+% argument the number of lines one wishes to add or substract from the
+% number that has been set by \cs{setmaxlines}. As a result, \meta{n}
+% can be a positive or negative integer.
+%    \begin{macrocode}
+\def\addtomaxlines#1{%
+  \luadirect{tex.sprint(ekdosis.addtomaxlines(
+    \luastringO{\maxlines@value}, \luastringN{#1}))}%
+  \ignorespaces}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\nomaxlines}
+% \changes{v1.5}{2022/10/25}{unsets \cs{setmaxlines}}
+% \cs{nomaxlines} unsets any limit previously set by \cs{setmaxlines}.
+%    \begin{macrocode}
+\def\nomaxlines{\luadirect{tex.sprint(ekdosis.resetlocalmaxlines())}}
+%    \end{macrocode}
+% \end{macro}
+% Finally, the \cs{MakeLineNo} command provided by the \pkg{lineno}
+% package is patched so as to trigger the insertion of \cs{pagebreak}
+% when the number of lines set by \cs{setmaxlines} has been
+% reached:---
+%    \begin{macrocode}
+\AddToHook{cmd/MakeLineNo/after}{%
+  \ifdefined\maxlines@value
+    \stepcounter{ekd@lnperpage}%
+    \ifnum\value{ekd@locallnperpage} = 1
+      \ifnumcomp{\theekd@lnperpage}{=}{%
+        \luadirect{tex.sprint(ekdosis.getlocalmaxlines())}}{%
+        \setcounter{ekd@locallnperpage}{0}%
+        \setcounter{ekd@lnperpage}{0}\pagebreak}{}%
+    \else
+      \ifnumcomp{\theekd@lnperpage}{=}{\maxlines@value}{%
+        \setcounter{ekd@lnperpage}{0}\pagebreak}{}%
+    \fi
+  \fi
+}
+%    \end{macrocode}
 % \begin{macro}{\SetDefaultApparatus}
 % By default, \pkg{ekdosis} defines one layer of critical notes which
 % is called |default|. This name can be changed at any point of the
@@ -9429,7 +9569,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\App}
-% \changes{v1.5}{2022/09/01}{To be used conjointly with
+% \changes{v1.5}{2022/10/25}{To be used conjointly with
 % \texttt{ekdosis.el}}
 % In contrast to \cs{app}, \cs{App} takes two mandatory arguments and
 % accepts one optional argument like so:
@@ -10313,7 +10453,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \paragraph{Lacunae}
 % \begin{macro}{\ilabel}
-% \changes{v1.5}{2022/09/01}{recalls and sets the ending label of
+% \changes{v1.5}{2022/10/25}{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
@@ -10629,7 +10769,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\ekdEOprint}
-% \changes{v1.5}{2022/09/01}{Sets headers and footers on
+% \changes{v1.5}{2022/10/25}{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
@@ -10669,7 +10809,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/09/01}{A counter incremented every two pages}
+% \changes{v1.5}{2022/10/25}{A counter incremented every two pages}
 % |pairedpage| is first set as a global counter:---
 %    \begin{macrocode}
 \newcounter{pairedpage}
@@ -10677,19 +10817,19 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{counter}
 % \begin{macro}{\setpairedpagenum}
-%   \changes{v1.5}{2022/09/01}{sets the same page number on paired
+%   \changes{v1.5}{2022/10/25}{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/09/01}{sets the page number of the first paired
+%   \changes{v1.5}{2022/10/25}{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/09/01}{resets normal running page numbers}
+%   \changes{v1.5}{2022/10/25}{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
@@ -13047,6 +13187,60 @@ function ekdosis.export_coldata_totei()
    end
 end
 
+-- maxlines
+--
+
+local localmaxlines = nil
+
+function ekdosis.resetlocalmaxlines()
+   localmaxlines = nil
+   return "\\setcounter{ekd@locallnperpage}{0}"
+end
+
+function ekdosis.setlocalmaxlines(n)
+   n = tonumber(n)
+   if math.type(n) == "integer"
+   then
+      localmaxlines = n
+   end
+   return "\\setcounter{ekd@locallnperpage}{1}"
+end
+
+function ekdosis.addtomaxlines(ni, nii)
+   ni = tonumber(ni)
+   nii = tonumber(nii)
+   if math.type(ni) == "integer" and math.type(nii) == "integer" 
+   then
+      localmaxlines = ni + nii
+   end
+   return "\\setcounter{ekd@locallnperpage}{1}"
+end
+
+function ekdosis.getlocalmaxlines()
+   if localmaxlines
+   then
+      return localmaxlines
+   end
+end
+
+-- apparatus height
+--
+local appheightchanged = false
+
+function ekdosis.changeappheight()
+   appheightchanged = true
+end
+   
+function ekdosis.setheightandprintapparatus()
+   if appheightchanged == true
+   then
+      appheightchanged = false
+      return "\\csname ekd@insert@fitapparatus@tmpheight\\endcsname"
+   else
+      return "\\csname ekd@insert@fitapparatus\\endcsname"
+   end
+end
+
 -- handle multiple layers in apparatuses
 --
 local apparatuses = {}