done documenting \addentries

1 files changed, 50 insertions, 19 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 2ab754a..0fc51ae 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -2202,10 +2202,12 @@ yesterday.
 % manuscripts and manuscript families above
 % \vpageref{ref:caesar-bg-sigla}. As this document is not set for
 % duplex printing, both texts have been put together on the same
-% page. However, the reader will find the full |.tex| source file
-% in \vref{sec:caesar-gw-tex} and \texttt{TEI xml} output in
+% page. However, the reader will find the full |.tex| source file in
+% \vref{sec:caesar-gw-tex} and \texttt{TEI xml} output in
 % \vref{sec:caesar-gw-tei}. The corresponding PDF output is available
-% in \href{samples/Caesar_BG-6-13-1.pdf}{a separate file}:---
+% in \href{samples/Caesar_BG-6-13-1.pdf}{a separate file}:\footnote{On
+% the use of \cs{ekddiv} (ll.~3 and 20), see below
+% \vref{sec:ekddiv}.}---
 %
 % \captof{Caesar's \emph{Gallic War}, VI, 13.1}[\label{lst:caesar-bg}]
 % \iffalse
@@ -2701,8 +2703,8 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % preamble, this |default| layer must be included in the list of
 % declared layers.\\
 % \DescribeMacro{\SetDefaultApparatus}\label{ref:ekd-default-app}
-% \cs{SetDefaultApparatus}\marg{name} can be used at any point of
-% the document to change the default name that is used by
+% \cs{SetDefaultApparatus}\marg{name} can be used at any point of the
+% document to change the name to be used as the default one by
 % \pkg{ekdosis}.
 %
 % \subsubsection{Declaring Additional Layers}
@@ -2878,9 +2880,9 @@ Some \app[type=rec2]{
 %</example>
 % \fi
 %
-% At any rate, |type=default| or |type=rec1|, depending on what has
-% been chosen, must be used if the editor wishes to retain that
-% information in the \texttt{TEI xml} output file.
+% \danger At any rate, |type=default| or |type=rec1|, depending on
+% what has been chosen, must be used if the editor wishes to retain
+% that information in the \texttt{TEI xml} output file.
 %
 % \subsection{Other Notes for Comments, Sources or Testimonia}
 % \label{ref:type-note}
@@ -3008,11 +3010,11 @@ travels from central Asia; a language, copious, elastic,
 inviting self-explaining combinations and independent
 development; lending itself alike to daily life and
 imagination, to description and abstract thought. 
-<note type="fontium" target="#range(right(61e),left(62a))">Waitz, 
+<note type="fontium" target="#range(right(B61e),left(B62a))">Waitz, 
 <emph>Deutsche Verfassungs Geschichte</emph>, i. 86</note>
-<anchor xml:id="61e" />They had a class of nobles, but
+<anchor xml:id="B61e" />They had a class of nobles, but
 their tongue knew no word for slave.
-<anchor xml:id="#62a" />
+<anchor xml:id="B62a" />
 <note place="bottom">George Bancroft, 
 <emph>History of the United States from the Discovery of
 the American Continent</emph>, II.61--2.</note></p>
@@ -3888,6 +3890,29 @@ subtype="arabtex">'inna 'abI kAna mina
 % pages would need to be compiled, the magic number should emerge
 % quite rapidly.
 %
+% \paragraph{Adding and Removing Entries}
+% \DescribeMacro{\addentries} \cs{addentries}\oarg{layer}\marg{n}
+% \newfeature[v1.1]\\
+% If |maxentries| be set for a given layer of critical notes,
+% \cs{addentries}\oarg{layer}\marg{n}, where \meta{n} is an integer,
+% can be used to add \meta{n} to\---or remove it from if \meta{n} be
+% negative\---the number of accepted entries on the current
+% page. \cs{addentries} operates on the default layer of notes, but
+% any other declared layer can be specified in the optional argument
+% of the command.
+%
+% \danger Of course, \cs{addentries} must be issued before the
+% number of entries on a given page has reached the value set as
+% |maxentries|.
+%
+% Once a sensible value for |maxentries| has been found,
+% \cs{addentries} can further be used with a positive integer to allow
+% for more entries and more lines on some pages so that offending
+% vertical spaces are decreased. Conversely, \cs{addentries} with a
+% negative integer will remove entries on pages where there are too
+% many of them and \pkg{ekdosis} still oscillates between different
+% sets of page decisions.
+%
 % \section{\texttt{TEI xml} Output}
 % \label{sec:teixml-output}
 % Several examples of \texttt{TEI xml} output have been provided
@@ -5947,10 +5972,11 @@ Sample text with a \textcolor{red}{word} in red.
 % on the current page.}
 % If |maxentries| be set for a given layer of critical notes,
 % \cs{addentries}\oarg{layer}\marg{n}, where \meta{n} is an integer,
-% can be used to add \meta{n}\---or remove it if it be negative\---to
-% the number of accepted entries on the current page. \cs{addentries}
-% operates on the default layer of notes, but any other declared layer
-% can be specified in the optional argument of the command.
+% can be used to add \meta{n} to\---or remove it from if \meta{n} be
+% negative\---the number of accepted entries on the current
+% page. \cs{addentries} operates on the default layer of notes, but
+% any other declared layer can be specified in the optional argument
+% of the command.
 %    \begin{macrocode}
 \NewDocumentCommand{\addentries}{O{\ekdan@type} m}{%
   \luadirect{ekdosis.addto_bagunits(\luastringO{#1}, \luastringN{#2})}%
@@ -7638,6 +7664,8 @@ local cmdtotags = {
 }
 
 local texpatttotags = {
+   {a="\\addentries%s+%[(.-)%]{(.-)}", b=""},
+   {a="\\addentries%s+{(.-)}", b=""},
    {a="\\pagebreak%s+%[[1-4]%]", b=""},
    {a="\\pagebreak%s+", b=""},
    {a="\\altrfont%s+", b=""},
@@ -8941,10 +8969,10 @@ function ekdosis.get_bagunits(teitype)
    return bagunits[teitype]
 end
 
-local function getapplimit(str)
+local function getapplimit(teitype)
    for i = 1,#apparatuses
    do
-      if apparatuses[i].a == str then
+      if apparatuses[i].a == teitype then
          limitfound = apparatuses[i].limit
          break
       end
@@ -8974,8 +9002,11 @@ function ekdosis.limit_bagunits(teitype)
 end
 
 function ekdosis.addto_bagunits(teitype, n)
-   n = tonumber(n)
-   bagunits[teitype] = bagunits[teitype] - n
+   if tonumber(getapplimit(teitype)) ~= 0
+   then
+      n = tonumber(n)
+      bagunits[teitype] = bagunits[teitype] - n
+   end
 end
 
 function ekdosis.increment_bagunits(teitype)