documentation and .el style file updated

1 files changed, 192 insertions, 53 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index f6571f6..bfce8bc 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/10/25 v1.5-dev Typesetting TEI xml-compliant critical editions]
+    [2022/10/26 v1.5-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -356,6 +356,15 @@ along with this program.  If not, see
   version =      {1.3}
 }
 
+@Software{fgruler,
+  title =        {The Fgruler package},
+  titleaddon =   {Draw rulers on the foreground or in the text},
+  author =       {Tómács, Tibor},
+  url =          {https://ctan.org/pkg/fgruler},
+  date =         {2022-06-25},
+  version =      {1.5},
+}
+
 @Software{fnpos,
   title =        {The Fnpos package},
   titleaddon =   {Control the position of footnotes on the page},
@@ -3447,7 +3456,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % further adjust languages, hyphenation rules, and/or fonts to be
 % applied in each environment. To return to the example provided
 % above, once \cs{SetAlignment} has been used, the languages can be
-% set as follows:---
+% set as follows:\footnote{The \cs{setmaxlines} command provides a
+% further example of applying this technique. See below
+% \vpageref{ref:setmaxlines-hook}.}---
 % 
 % \iffalse
 %<*example>
@@ -3716,7 +3727,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % up to which the apparatus block is allowed to grow before the size
 % of the characters is reduced to allow for more entries. The value
 % must be a dimension, namely a number followed by a length unit, such
-% as |0.65\textheight|, |18cm| or |6in|.\\
+% as |0.65\textheight|, |18cm| or |6in|. \mansee To learn how this
+% value can be adjusted on given pages, see below
+% \vpageref{ref:fitapp-trick}.\\
 % \DescribeOption{fitalgorithm}%
 % \phts\label{ref:fitalgorithm}
 % \unskip|fitalgorithm|$=$\verb+fontsize|hybrid|areasize|squeeze+
@@ -5114,9 +5127,53 @@ substantiall fewell,}
 % 
 % \medskip\noindent\textbf{Limiting the Number of Lines per Page}
 % \phts\label{ref:gmaxlines}\\
-% \DescribeOption{maxlines} \newfeature[v1.5] |maxlines|=\meta{n}
+% \DescribeOption{maxlines} |maxlines|$=$\emph{n} (where \emph{n} is
+% an integer $\geq 1$)\newfeature[v1.5]
 % \hfill\tcboxverb{Default: not set}\\
+% |maxlines|$=$\emph{n} instructs \pkg{ekdosis} to break the pages of
+% numbered text every \emph{n} lines.  This option is very useful for
+% building editions equipped with long and complex apparatus
+% criticus. The rationale is to start with a number of lines that will
+% allow all pages to pass just after a few runs of \LuaLaTeX, even at
+% the cost of showing blanks between the edition text and the
+% apparatus criticus. Adjusting further the number of lines will then
+% leave fewer blanks on display. Combined with the |fitapp| global
+% option\footnote{See above \vpageref{ref:fitapp-opt}.} or with
+% |maxentries|,\footnote{Se above \vpageref{ref:maxentries}.}
+% |maxlines| can achieve excellent results. For more details on this
+% technique, see below \ref{sec:oscillating-problem},
+% \enquote{\nameref{sec:oscillating-problem}}
+% \vpageref{ref:maxlines-trick}.\\
+% \DescribeOption{nomaxlines} \newfeature[v1.5]
+% \hfill\tcboxverb{Default: not set}\\
+% This no-value option unsets any limit previously set by |maxlines|
+% or \cs{setmaxlines}\\
+% \DescribeMacro{\setmaxlines} \cs{setmaxlines}\marg{n} (where
+% \meta{n} $\geq 1$) has the same effect as the |maxlines| option just
+% described. This command can be used either in the preamble or at any
+% point of the document. \mansee \phts\label{ref:setmaxlines-hook} The
+% |maxlines| option operates globally, on any pages or columns of text
+% that are set to receive at least one layer of apparatus
+% criticus. The way of applying the limit to only one out of several
+% edition texts is therefore to append \cs{setmaxlines} as a hook to
+% the environment corresponding to this edition text as described
+% above \vpageref{sec:alignment-hooks}, like so:---
 % 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\AtBeginEnvironment{latin}{\setmaxlines{<n>}}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+% 
+% \DescribeMacro{\nomaxlines} \noindent\cs{nomaxlines} is an
+% argument-less command that operates as the |nomaxlines| option just
+% described. This command can be used either in the preamble or at any
+% point of the document.
+%
 % \medskip\noindent\textbf{Options Specific to the |poetry=verse|
 % Global Setting}\footnote{See above
 % \vref{sec:verse-package}.}\phts\label{ref:verse-lineation}\\
@@ -6168,37 +6225,92 @@ subtype="arabtex">'inna 'abI kAna mina
 % entries with right line numbers cannot come on pages that follow a
 % wrong page either.
 %
-% An alert reader may have guessed that inserting a \cs{pagebreak} is
+% The alert reader may have guessed that inserting a \cs{pagebreak} is
 % a good way to get out of the vicious circle. And surely, if only a
 % few pages be at stake, this is the way to go. However,
 % \cs{pagebreak} commands should only be inserted when the whole
 % edition text is ready for any substantial change in the preceding
 % pages may result in pages that break just after they begin.
 %
+% \paragraph{Limiting the Number of Lines per Page}
+% \phts\label{ref:maxlines-trick} One way to avoid this inconvenience
+% is to use the |maxlines| option of \cs{SetLineation} as described
+% above \vpageref{ref:gmaxlines}. Depending on the abundance of
+% critical footnotes to be printed, the editor may start with a number
+% that will allow most, if not all, pages to pass.
+%
+% Furthermore, this technique can be combined with the |fitapp| global
+% option described below \vpageref{ref:fitapp-trick}. Once |maxlines|
+% has been applied, the \pkg{fgruler} package\footcite{fgruler} can be
+% used to gauge the respective heights of the edition text and the
+% apparatus criticus like so:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Preamble
+\usepackage[type=lowerleftT]{fgruler}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% Based on the height corresponding to the last line of the edition
+% text limited by the value of |maxlines|, the height from which the
+% apparatus criticus block should stop growing and the characters
+% should be scaled down to allow for more entries can be
+% estimated.\footnote{To learn how the maximum height of the apparatus
+% criticus can be set, see \vpageref{ref:appheight}. The |fitapp|
+% global option is described \vpageref{ref:fitapp-opt}.} This ensures
+% that any contentious entries are included in the apparatus criticus
+% when the last line of text has been reached.
+%
+% In addition to the |maxlines| option of \cs{SetLineation} and the
+% \cs{setmaxlines} command,\footnote{See above
+% \vpageref{ref:gmaxlines}.} the following commands are provided:---
+%
+% \DescribeMacro{\localmaxlines} \cs{localmaxlines}\marg{n}, where
+% \meta{n} $\geq 1$, can be used in the edition text to adjust the
+% number of lines on a given page.  Of course, this command must be
+% issued before the line number corresponding to |maxlines| is
+% reached. \mansee \cs{localmaxlines}|{0}| can therefore be used to
+% remove the limit set by |maxlines| or \cs{setmaxlines} on a given
+% page.
+%
+% \DescribeMacro{\addtomaxlines} Unlike \cs{localmaxlines},
+% \cs{addtomaxlines}\marg{n} takes as argument the number of lines one
+% wishes to add or substract from the number that has been set by
+% |maxlines| or \cs{setmaxlines}. As a result, \meta{n} can be a
+% positive or negative integer.
+%
+% \DescribeMacro{\nomaxlines} \cs{nomaxlines} is an argument-less
+% command that unsets any limit previously set by |maxlines| or
+% \cs{setmaxlines}.
+%
 % \paragraph{Conditional page breaks}
 % \phts\label{ref:ekdpb} \DescribeMacro{\ekdpb}\DescribeMacro{\ekdpb*}
-% \cs{ekdpb}\oarg{page no}\marg{line no}
-% \cs{ekdpb*}|{}| \cs{ekdpb*}
+% \cs{ekdpb}\oarg{page no}\marg{line no} \cs{ekdpb*}|{}| \cs{ekdpb*}
 % \newfeature[v1.2]\\
-% One way to avoid this inconvenience is to use \cs{ekdpb} instead of
-% the standard \cs{pagebreak} command provided by \LaTeX\ to insert
-% conditional page breaks. \cs{ekdpb} takes as mandatory argument the
-% line number, as it is printed in the margin, where the page break
-% should take place. An optional argument allows to further specify
-% the page number where the page break should occur. The value that is
-% expected is the page number as it is printed\===e.g.\ an Arabic,
-% Roman or alphanumeric number. If the specified conditions be not
-% met, then the page break is not triggered.  Finally, the
-% \enquote{starred} version of this command forces the page break,
-% irrespective of the values specified as page or line numbers. Unlike
-% \cs{ekdpb}, which requires the lines to be numbered, \cs{ekdpb*} is
-% allowed at any point of the document: as \cs{ekdpb*} disregards the
-% number given as argument, it is equivalent to the standard \LaTeX\
-% \cs{pagebreak} command. Yet it can be used instead of the latter to
-% have marks further printed in the margins so as to spot with a
-% fleeting glance the locations where induced page breaks
-% occur.\footnote{This requires the |showpagebreaks| option to be set
-% to |true| as described above \vpageref{ref:showpagebreaks-opt}.}
+% One other way is to use \cs{ekdpb} instead of the standard
+% \cs{pagebreak} command provided by \LaTeX\ to insert conditional
+% page breaks. \cs{ekdpb} takes as mandatory argument the line number,
+% as it is printed in the margin, where the page break should take
+% place. An optional argument allows to further specify the page
+% number where the page break should occur. The value that is expected
+% is the page number as it is printed\===e.g.\ an Arabic, Roman or
+% alphanumeric number. If the specified conditions be not met, then
+% the page break is not triggered.  Finally, the \enquote{starred}
+% version of this command forces the page break, irrespective of the
+% values specified as page or line numbers. Unlike \cs{ekdpb}, which
+% requires the lines to be numbered, \cs{ekdpb*} is allowed at any
+% point of the document: as \cs{ekdpb*} disregards the number given as
+% argument, it is equivalent to the standard \LaTeX\ \cs{pagebreak}
+% command. Yet it can be used instead of the latter to have marks
+% further printed in the margins so as to spot with a fleeting glance
+% the locations where induced page breaks occur.\footnote{This
+% requires the |showpagebreaks| option to be set to |true| as
+% described above \vpageref{ref:showpagebreaks-opt}.}
 %
 % \paragraph{Using \texttt{maxentries}}
 % Another way\---should the edition text fall into the vicious circle
@@ -6249,15 +6361,42 @@ subtype="arabtex">'inna 'abI kAna mina
 % sets of page decisions.
 %
 % \paragraph{The \texttt{fitapp} Global Option}
-% \newfeature[v1.3] The rationale of this option is discussed above
-% (see \vref{ref:fitapp-opt}). As this mechanism has the characters of
-% the apparatus block scaled down to allow for more entries once a
-% predefined height has been reached, \pkg{ekdosis} should settle down
-% in most of the contentious cases.\footnote{That is, cases that arise
-% \emph{after} the predefined height has been reached.} However, it is
-% advisable to use |fitapp| conjointly with |maxentries| to prevent
-% the number of allowed entries from being too high, which would
-% result in the characters being too small or even illegible.
+% \phts\label{ref:fitapp-trick} \newfeature[v1.3] The rationale of
+% this option is discussed above (see \vref{ref:fitapp-opt}). As this
+% mechanism has the characters of the apparatus block scaled down to
+% allow for more entries once a predefined height has been reached,
+% \pkg{ekdosis} should settle down in most of the contentious
+% cases.\footnote{That is, cases that arise \emph{after} the
+% predefined height has been reached.} However, it is advisable to use
+% |fitapp| conjointly with |maxlines| or |maxentries| to prevent the
+% number of allowed entries from being too high, which would result in
+% the characters being too small or even illegible.
+%
+% \newfeature[v1.5] As already seen \vpageref{ref:appheight}, once the
+% global option |layout=fitapp| has been set,\footnote{See above
+% \vpageref{ref:fitapp-opt}.} the default maximum height of the
+% apparatus criticus block is |0.5\textheight|, which can be changed
+% by assigning a new length to the |appheight| option of
+% \cs{SetHooks}. To more finely adjust this height on given pages,
+% \pkg{ekdosis} provides additional commands to be used in the edition
+% text:---
+%
+% \DescribeMacro{\localappheight} 
+% \cs{localappheight}\marg{dimen} can be used to change locally the
+% height up to which the apparatus block is allowed to
+% grow. \meta{dimen} must be a number followed by a unit
+% length. \danger This command operates only on the apparatus block
+% that follows it. Therefore, it must be issued \emph{before} the
+% first entry of the apparatus block on which it is intended to
+% operate, either on the current page or in the last lines of the
+% preceding page.
+%
+% \DescribeMacro{\addtoappheight}
+% As the name suggests, in contrast to \cs{localappheight},
+% \cs{addtoappheight}\marg{dimen} is used to increase or decrease
+% locally the height of the apparatus typeblock. \meta{dimen} must be
+% a number followed by a unit length. Just as \cs{localappheight},
+% this command operates only on the apparatus block that follows it.
 %
 % \subsection{Using \textsf{emacs}}
 % \label{sec:using-emacs}
@@ -8409,7 +8548,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \paragraph{\textsf{ekdosis} Symbol}
 % \begin{macro}{\eKd}
-% \changes{v1.5}{2022/10/25}{Prints \textsf{ekdosis} indentifying
+% \changes{v1.5}{2022/10/26}{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.
@@ -8672,7 +8811,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/10/25}{direct insertion of empty elements in the
+% \changes{v1.5}{2022/10/26}{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
@@ -8687,7 +8826,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\getTEIxmlid}
-% \changes{v1.5}{2022/10/25}{returns \texttt{TEI xml:ids} from a
+% \changes{v1.5}{2022/10/26}{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
@@ -9163,10 +9302,10 @@ Sample text with a \textcolor{red}{word} in red.
 \newlength{\ekd@app@localheight}
 %    \end{macrocode}
 % \begin{macro}{\localappheight}
-% \changes{v1.5}{2022/10/25}{changes the height of the apparatus
+% \changes{v1.5}{2022/10/26}{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
+% 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
@@ -9182,11 +9321,11 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\addtoappheight}
-% \changes{v1.5}{2022/10/25}{increases or decreases the height of the
+% \changes{v1.5}{2022/10/26}{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
+% 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}
@@ -9468,7 +9607,7 @@ Sample text with a \textcolor{red}{word} in red.
 % 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}
+% \changes{v1.5}{2022/10/26}{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
@@ -9479,7 +9618,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\localmaxlines}
-% \changes{v1.5}{2022/10/25}{changes the maximum number of lines
+% \changes{v1.5}{2022/10/26}{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
@@ -9492,7 +9631,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\addtomaxlines}
-% \changes{v1.5}{2022/10/25}{adds or subtracts lines from a given page}
+% \changes{v1.5}{2022/10/26}{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}
@@ -9505,7 +9644,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\nomaxlines}
-% \changes{v1.5}{2022/10/25}{unsets \cs{setmaxlines}}
+% \changes{v1.5}{2022/10/26}{unsets \cs{setmaxlines}}
 % \cs{nomaxlines} unsets any limit previously set by \cs{setmaxlines}.
 %    \begin{macrocode}
 \def\nomaxlines{\luadirect{tex.sprint(ekdosis.resetlocalmaxlines())}}
@@ -9569,7 +9708,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\App}
-% \changes{v1.5}{2022/10/25}{To be used conjointly with
+% \changes{v1.5}{2022/10/26}{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:
@@ -10453,7 +10592,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \paragraph{Lacunae}
 % \begin{macro}{\ilabel}
-% \changes{v1.5}{2022/10/25}{recalls and sets the ending label of
+% \changes{v1.5}{2022/10/26}{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
@@ -10769,7 +10908,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\ekdEOprint}
-% \changes{v1.5}{2022/10/25}{Sets headers and footers on
+% \changes{v1.5}{2022/10/26}{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
@@ -10809,7 +10948,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/10/25}{A counter incremented every two pages}
+% \changes{v1.5}{2022/10/26}{A counter incremented every two pages}
 % |pairedpage| is first set as a global counter:---
 %    \begin{macrocode}
 \newcounter{pairedpage}
@@ -10817,19 +10956,19 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{counter}
 % \begin{macro}{\setpairedpagenum}
-%   \changes{v1.5}{2022/10/25}{sets the same page number on paired
+%   \changes{v1.5}{2022/10/26}{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/10/25}{sets the page number of the first paired
+%   \changes{v1.5}{2022/10/26}{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/10/25}{resets normal running page numbers}
+%   \changes{v1.5}{2022/10/26}{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