a bit of literate programming on \current@ref

1 files changed, 108 insertions, 42 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index af71c7d..d701f5d 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -59,7 +59,7 @@ Alessi <alessi@robertalessi.net>
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{ekdosis}
 %<*package>
-    [2023/07/05 v1.5-dev Typesetting TEI xml-compliant critical editions]
+    [2023/07/29 v1.5-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -8517,7 +8517,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \paragraph{\textsf{ekdosis} Symbol}
 % \begin{macro}{\eKd}
-% \changes{v1.5}{2023/07/05}{Prints \textsf{ekdosis} indentifying
+% \changes{v1.5}{2023/07/29}{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.
@@ -8780,7 +8780,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}{2023/07/05}{direct insertion of empty elements in the
+% \changes{v1.5}{2023/07/29}{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
@@ -8795,7 +8795,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\getTEIxmlid}
-% \changes{v1.5}{2023/07/05}{returns \texttt{TEI xml:ids} from a
+% \changes{v1.5}{2023/07/29}{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
@@ -9271,7 +9271,7 @@ Sample text with a \textcolor{red}{word} in red.
 \newlength{\ekd@app@localheight}
 %    \end{macrocode}
 % \begin{macro}{\localappheight}
-% \changes{v1.5}{2023/07/05}{changes the height of the apparatus
+% \changes{v1.5}{2023/07/29}{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
@@ -9290,7 +9290,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\addtoappheight}
-% \changes{v1.5}{2023/07/05}{increases or decreases the height of the
+% \changes{v1.5}{2023/07/29}{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
@@ -9577,7 +9577,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}{2023/07/05}{limits the number of lines per page}
+% \changes{v1.5}{2023/07/29}{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
@@ -9588,7 +9588,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\localmaxlines}
-% \changes{v1.5}{2023/07/05}{changes the maximum number of lines
+% \changes{v1.5}{2023/07/29}{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
@@ -9601,7 +9601,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\addtomaxlines}
-% \changes{v1.5}{2023/07/05}{adds or subtracts lines from a given page}
+% \changes{v1.5}{2023/07/29}{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}
@@ -9614,7 +9614,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\nomaxlines}
-% \changes{v1.5}{2023/07/05}{unsets \cs{setmaxlines}}
+% \changes{v1.5}{2023/07/29}{unsets \cs{setmaxlines}}
 % \cs{nomaxlines} unsets any limit previously set by \cs{setmaxlines}.
 %    \begin{macrocode}
 \def\nomaxlines{\luadirect{tex.sprint(ekdosis.resetlocalmaxlines())}}
@@ -9678,7 +9678,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\App}
-% \changes{v1.5}{2023/07/05}{To be used conjointly with
+% \changes{v1.5}{2023/07/29}{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:
@@ -9793,38 +9793,54 @@ Sample text with a \textcolor{red}{word} in red.
 %    \begin{macrocode}
 \def\current@ref{{%\textdir TLT%
     \unexpanded\expandafter{\ekd@refnumstyle}%
-    \ifnum % if the whole lemma falls on the same page...
+%    \end{macrocode}
+% If the whole lemma falls on the same page...
+%    \begin{macrocode}
+    \ifnum
       \pdf@strcmp{%
         \getpagerefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}%
       {\getpagerefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}}
       =
       0
-      \ifnum % ... and on the same line
+%    \end{macrocode}
+%  ... and on the same line,
+%    \begin{macrocode}
+      \ifnum
         \pdf@strcmp{%
           \getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}%
         {\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}}
         =
         0
-        % 
-        \ifekd@mapps % then, if multiple layers have been defined:
-          \ifbool{subsq@unit@\ekdan@type}{% given a subsequent entry ...
-              \ifnum %  ... when it begins on the same line as the
-                % previous one ...
+%    \end{macrocode}
+% then, if multiple layers have been defined,
+%    \begin{macrocode}
+        \ifekd@mapps
+%    \end{macrocode}
+% and the entry is a subsequent one, when it begins on the same line
+% as the previous one...
+%    \begin{macrocode}
+          \ifbool{subsq@unit@\ekdan@type}{%
+              \ifnum
                 \pdf@strcmp{\getrefnumber{\luadirect{tex.sprint(
                       ekdosis.getlnlab())}-b}}%
                 {\getrefnumber{\luadirect{tex.sprint(
                       ekdosis.getprevlnlab())}-b}}
                 =
                 0
-                %%% begin
-                \ifnum % ... and ends likewise, then do nothing,
+%    \end{macrocode}
+% and ends likewise, then do nothing:---
+%    \begin{macrocode}
+                \ifnum
                   \pdf@strcmp{\getrefnumber{\luadirect{tex.sprint(
                         ekdosis.getlnlab())}-e}}%
                   {\getrefnumber{\luadirect{tex.sprint(
                         ekdosis.getprevlnlab())}-e}}
                   =
                   0
-                  \ifekd@appinapp % (this is for nested \app entries.)
+%    \end{macrocode}
+% (What follows is for nested \cs{app} entries.)
+%    \begin{macrocode}
+                  \ifekd@appinapp
                     \ifnum
                       \pdf@strcmp{\getrefnumber{\luadirect{tex.sprint(
                             ekdosis.getlnlab())}-b}}%
@@ -9836,28 +9852,43 @@ Sample text with a \textcolor{red}{word} in red.
                       \LRnum{\getrefnumber{\luadirect{tex.sprint(
                             ekdosis.getlnlab())}-b}}%
                       \unexpanded\expandafter{\ekd@postrefnum}% issue
-                      % the no
+                                                              % the no
                     \fi
                   \fi
-                \else % otherwise, print the line number:
+%    \end{macrocode}
+% Otherwise, print the line number:---
+%    \begin{macrocode}
+                \else
                   \LRnum{\getrefnumber{\luadirect{tex.sprint(
                         ekdosis.getlnlab())}-b}}%
                   \unexpanded\expandafter{\ekd@postrefnum}% issue the no
                 \fi
-                %%% end
-              \else % if the entry begins on a new line, print the
-                % number:
+%    \end{macrocode}
+% If the entry begins on a new line, print the number:---
+%    \begin{macrocode}
+              \else
                 \LRnum{\getrefnumber{\luadirect{tex.sprint(
                       ekdosis.getlnlab())}-b}}%
                 \unexpanded\expandafter{\ekd@postrefnum}% issue the no
               \fi
-            }% and always print the line number ahead of first entries:
-            {\LRnum{\getrefnumber{\luadirect{tex.sprint(
+%    \end{macrocode}
+% And always print the line number ahead of first entries:---
+%    \begin{macrocode}
+            }{\LRnum{\getrefnumber{\luadirect{tex.sprint(
                     ekdosis.getlnlab())}-b}}%
               \unexpanded\expandafter{\ekd@postrefnum}}% issue the no
-        \else % now if there is only one default layer
+%    \end{macrocode}
+% Now if there is only one default layer:---
+%    \begin{macrocode}
+        \else
+%    \end{macrocode}
+% On subsequent entries...
+%    \begin{macrocode}
           \ifsubsq@unit
-            % 
+%    \end{macrocode}
+% ... if the whole lemma text begins on the same line as the preceding
+% one...
+%    \begin{macrocode}
             \ifnum
               \pdf@strcmp{\getrefnumber{\luadirect{tex.sprint(
                     ekdosis.getlnlab())}-b}}%
@@ -9865,7 +9896,9 @@ Sample text with a \textcolor{red}{word} in red.
                     ekdosis.getprevlnlab())}-b}}
               =
               0
-              %%% begin
+%    \end{macrocode}
+% ... and ends likewise...
+%    \begin{macrocode}
               \ifnum
                 \pdf@strcmp{\getrefnumber{\luadirect{tex.sprint(
                       ekdosis.getlnlab())}-e}}%
@@ -9873,6 +9906,9 @@ Sample text with a \textcolor{red}{word} in red.
                       ekdosis.getprevlnlab())}-e}}
                 =
                 0
+%    \end{macrocode}
+% (What follows is for nested \cs{app} entries.)
+%    \begin{macrocode}
                 \ifekd@appinapp
                   \ifnum
                     \pdf@strcmp{\getrefnumber{\luadirect{tex.sprint(
@@ -9887,26 +9923,39 @@ Sample text with a \textcolor{red}{word} in red.
                     \unexpanded\expandafter{\ekd@postrefnum}% issue the no
                   \fi
                 \fi
+%    \end{macrocode}
+% ... then do nothing.  Otherwise, print the line number:---
+%    \begin{macrocode}
               \else
                 \LRnum{\getrefnumber{\luadirect{tex.sprint(
                       ekdosis.getlnlab())}-b}}%
                 \unexpanded\expandafter{\ekd@postrefnum}% issue the no
               \fi
-              %%% end
+%    \end{macrocode}
+% If the entry begins on a new line, print the number as well:---
+%    \begin{macrocode}
             \else
               \LRnum{\getrefnumber{\luadirect{tex.sprint(
                     ekdosis.getlnlab())}-b}}%
               \unexpanded\expandafter{\ekd@postrefnum}% issue the no
             \fi
-            % 
+%    \end{macrocode}
+% And always print the line number ahead of first entries:---
+%    \begin{macrocode}
           \else
             \LRnum{\getrefnumber{\luadirect{tex.sprint(
                   ekdosis.getlnlab())}-b}}%
             \unexpanded\expandafter{\ekd@postrefnum}% issue the no
           \fi
         \fi
-        % 
+%    \end{macrocode}
+% Now if the lemma text breaks across lines ...
+%    \begin{macrocode}
       \else
+%    \end{macrocode}
+% ... then, depending on what has been instructed, either print the
+% last number of a range elided:---
+%    \begin{macrocode}
         \ifekd@elidednumbers
           \luadirect{tex.sprint(ekdosis.numrange(
             \luastring{\getrefnumber{\luadirect{tex.sprint(
@@ -9914,6 +9963,9 @@ Sample text with a \textcolor{red}{word} in red.
             \luastring{\getrefnumber{\luadirect{tex.sprint(
                   ekdosis.getlnlab())}-e}}))}%
           \unexpanded\expandafter{\ekd@postrefnum}% issue the nos
+%    \end{macrocode}
+% ... or in full:---
+%    \begin{macrocode}
         \else
           \LRnum{\getrefnumber{\luadirect{tex.sprint(
                 ekdosis.getlnlab())}-b}}--%
@@ -9922,7 +9974,14 @@ Sample text with a \textcolor{red}{word} in red.
           \unexpanded\expandafter{\ekd@postrefnum}% issue the nos
         \fi
       \fi
-    \else % now if the lemma breaks across pages
+%    \end{macrocode}
+% When the lemma breaks across pages:---
+%    \begin{macrocode}
+    \else
+%    \end{macrocode}
+% Print the page number and the line number when the numbering starts
+% afresh at the top of each page:---
+%    \begin{macrocode}
       \ifboolexpr{bool {ekd@pagelineation} or bool {ekd@pagevlineation}}
           {\LRnum{\getrefnumber{\luadirect{tex.sprint(
                   ekdosis.getlnlab())}-b}}--%
@@ -9931,12 +9990,19 @@ Sample text with a \textcolor{red}{word} in red.
             \LRnum{\getrefnumber{\luadirect{tex.sprint(
                   ekdosis.getlnlab())}-e}}%
             \unexpanded\expandafter{\ekd@postrefnum}}% issue pg and ln nos
+%    \end{macrocode}
+% Or just the line number if the lines are continuously numbered
+% throughout the book:---
+%    \begin{macrocode}
           {\LRnum{\getrefnumber{\luadirect{tex.sprint(
                   ekdosis.getlnlab())}-b}}--%
             \LRnum{\getrefnumber{\luadirect{tex.sprint(
                   ekdosis.getlnlab())}-e}}%
             \unexpanded\expandafter{\ekd@postrefnum}}% issue the nos
     \fi
+%    \end{macrocode}
+% Finally, print the number when instructed to do so:---
+%    \begin{macrocode}
     \ifekdl@forcenum
       \LRnum{\getrefnumber{\luadirect{tex.sprint(
             ekdosis.getlnlab())}-b}}%
@@ -10541,7 +10607,7 @@ Sample text with a \textcolor{red}{word} in red.
 }
 %    \end{macrocode}
 % \begin{macro}{\SetFootnotes}
-%   \changes{v1.5}{2023/07/05}{footnotes combined into a single
+%   \changes{v1.5}{2023/07/29}{footnotes combined into a single
 %   paragraph} \cs{SetFootnotes}\marg{options} can be used in the
 %   preamble or at any point of the document. |layout=paragraph|
 %   instructs \pkg{ekdosis} to combine all footnotes into a single
@@ -10772,7 +10838,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \paragraph{Lacunae}
 % \begin{macro}{\ilabel}
-% \changes{v1.5}{2023/07/05}{recalls and sets the ending label of
+% \changes{v1.5}{2023/07/29}{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
@@ -11107,7 +11173,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\ekdEOprint}
-% \changes{v1.5}{2023/07/05}{Sets headers and footers on
+% \changes{v1.5}{2023/07/29}{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
@@ -11147,7 +11213,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}{2023/07/05}{A counter incremented every two pages}
+% \changes{v1.5}{2023/07/29}{A counter incremented every two pages}
 % |pairedpage| is first set as a global counter:---
 %    \begin{macrocode}
 \newcounter{pairedpage}
@@ -11155,19 +11221,19 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{counter}
 % \begin{macro}{\setpairedpagenum}
-%   \changes{v1.5}{2023/07/05}{sets the same page number on paired
+%   \changes{v1.5}{2023/07/29}{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}{2023/07/05}{sets the page number of the first paired
+%   \changes{v1.5}{2023/07/29}{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}{2023/07/05}{resets normal running page numbers}
+%   \changes{v1.5}{2023/07/29}{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