another 200 lines or so to comment on

1 files changed, 181 insertions, 80 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 29919e1..b9cfbaf 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -2345,7 +2345,8 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
       \AtEndDocument{\luadirect{ekdosis.closeteistream("tidy")}}}},
   default teiexport = true,
   unknown-choice teiexport = \PackageError{ekdosis}{unknown
-    teiexport=#1}{`teiexport' must be either `true', `false' or `tidy'},
+    teiexport=#1}{`teiexport' must be either `true', `false' or
+    `tidy'.}
 }
 \ekvoProcessLocalOptions{ekdosis}
 %    \end{macrocode}
@@ -2490,13 +2491,36 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   \luadirect{tex.sprint(ekdosis.basic_cs(\luastringN{#1}))}
 }
 %    \end{macrocode}
-% Add a \hologo{(La)TeX} command to be processed as a |TEI xml| tag:
+% \paragraph{\TeX\ to \texttt{TEI xml}}
+% The following three commands can be used to instruct \pkg{ekdosis}
+% how to convert unknown or unusual \hologo{(La)TeX} commands into
+% \texttt{TEI xml} equivalents.
+% \begin{macro}{\TeXtoTEI}
+% \cs{TeXtoTEI}\marg{csname}\marg{TEI element}\oarg{TEI attribute(s)}
+% takes two mandatory arguments and one optional argument, namely: the
+% control sequence name to be converted, the \texttt{TEI} element it
+% is to be converted into and any additional \texttt{xml} attributes
+% to be appended to the opening \texttt{TEI} element:---
 %    \begin{macrocode}
 \NewDocumentCommand{\TeXtoTEI}{m m O{}}{%
   \luadirect{ekdosis.newcmdtotag(\luastringN{#1},
     \luastringN{#2},
     \luastringN{#3})}
 }
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\EnvtoTEI}
+% \begin{macro}{\EnvtoTEI*}
+% \cs{EnvtoTEI}\meta{*}\marg{env name}\marg{TEI element}\oarg{TEI
+% attribute(s)} instructs how to convert \LaTeX{} environments into
+% \texttt{TEI xml} equivalents. It takes two mandatory arguments and
+% one optional argument, namely the name of the \LaTeX{} environment
+% to be converted, the \texttt{TEI} element it is to be converted into
+% and any additional attributes to be appended to the \texttt{TEI}
+% opening element. \cs{EnvtoTEI*} is restricted to \texttt{TEI}
+% elements that must never appear within |<p>| elements, such as
+% |<div>|, |<lg>| and the like.
+%    \begin{macrocode}
 \NewDocumentCommand{\EnvtoTEI}{s m m O{}}{%
   \IfBooleanTF{#1}{%
   \luadirect{ekdosis.newenvtotag(\luastringN{#2},
@@ -2509,10 +2533,21 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
     \luastringN{#4})}
   }
 }
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\TeXtoTEIPatt}
+% Finally, the more flexible\---and more delicate to
+% handle\---\cs{TeXtoTEIPatt}\marg{\TeX\
+% pattern}\allowbreak\marg{\texttt{TEI} pattern} uses pattern matching
+% to instruct \pkg{ekdosis} how to convert \hologo{(La)TeX} commands
+% into \texttt{TEI} equivalents.
+%    \begin{macrocode}
 \NewDocumentCommand{\TeXtoTEIPatt}{m m}{%
   \luadirect{ekdosis.newpatttotag(\luastringN{#1}, \luastringN{#2})}
 }
 %    \end{macrocode}
+% \end{macro}
 % \begin{macro}{\SetTEIFilename} \cs{SetTEIFilename}\marg{basename} is
 %   a preamble-only command. It is used to set the base name of the
 %   |TEI xml| output file, to which the suffix |.xml| is appended. By
@@ -2836,7 +2871,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % mandatory argument and accepts one optional argument. |type=| refers
 % to the layer the note must go into and \meta{apparatus entries}
 % contains command used to insert the entries, either \cs{lem},
-% \cs{rdg} or \cs{note}:---
+% \cs{rdg} or \cs{note}\meta{*}:---
 %    \begin{macrocode}
 \NewDocumentCommand{\app}{O{} > { \TrimSpaces } +m}{%
   \begingroup
@@ -2852,6 +2887,10 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   \endgroup}
 %    \end{macrocode}
 % \end{macro}
+% \cs{current@ref@arg} is used outside \cs{app} by \cs{note}. It takes
+% two mandatory arguments: the beginning line label and the ending
+% line label\---which are manually inserted---and returns the formatted
+% reference to be inserted in the apparatus criticus.
 %    \begin{macrocode}
 \def\current@ref@arg#1#2{{%\textdir TLT%
     \unexpanded\expandafter{\ekd@refnumstyle}%
@@ -2859,97 +2898,106 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
     \getpagerefnumber{#1}
     =
     \getpagerefnumber{#2}
-      \ifnum%
-      \getrefnumber{#1}
-      =
-      \getrefnumber{#2}
-      %
-      \ifekd@mapps%
-      \ifbool{subsq@unit@\ekdan@type}{%
-        \ifnum%
-        \getrefnumber{#1}
-        =
-        \getrefnumber{\luadirect{tex.sprint(ekdosis.getprevnotelab())}}
-        \else
-        \LRnum{\getrefnumber{#1}}% issue the no
-        \fi%
-      }%
-      {\LRnum{\getrefnumber{#1}}}% issue the no
-      \else
-      \ifsubsq@unit%
-      %
+    \ifnum%
+    \getrefnumber{#1}
+    =
+    \getrefnumber{#2}
+    % 
+    \ifekd@mapps%
+    \ifbool{subsq@unit@\ekdan@type}{%
       \ifnum%
       \getrefnumber{#1}
       =
       \getrefnumber{\luadirect{tex.sprint(ekdosis.getprevnotelab())}}
       \else
       \LRnum{\getrefnumber{#1}}% issue the no
-      \fi
-      %
-      \else
-      \LRnum{\getrefnumber{#1}}% issue the no
-      \fi
-      \fi
-      %
-      \else
-      \LRnum{\getrefnumber{#1}}--%
-      \LRnum{\getrefnumber{#2}}% issue the nos
-      \fi%
-      \else
-      \LRnum{\getrefnumber{#1}}--%
-      \LRnum{\getpagerefnumber{#2}}.%
-      \LRnum{\getrefnumber{#2}}% issue pg and ln nos
       \fi%
-    }\unexpanded\expandafter{\ekd@postrefnum}%
-  }%
-  \def\current@ref{{%\textdir TLT%
-      \unexpanded\expandafter{\ekd@refnumstyle}%
+    }%
+    {\LRnum{\getrefnumber{#1}}}% issue the no
+    \else
+    \ifsubsq@unit%
+    % 
+    \ifnum%
+    \getrefnumber{#1}
+    =
+    \getrefnumber{\luadirect{tex.sprint(ekdosis.getprevnotelab())}}
+    \else
+    \LRnum{\getrefnumber{#1}}% issue the no
+    \fi
+    % 
+    \else
+    \LRnum{\getrefnumber{#1}}% issue the no
+    \fi
+    \fi
+    % 
+    \else
+    \LRnum{\getrefnumber{#1}}--%
+    \LRnum{\getrefnumber{#2}}% issue the nos
+    \fi%
+    \else
+    \LRnum{\getrefnumber{#1}}--%
+    \LRnum{\getpagerefnumber{#2}}.%
+    \LRnum{\getrefnumber{#2}}% issue pg and ln nos
+    \fi%
+  }\unexpanded\expandafter{\ekd@postrefnum}%
+}
+%    \end{macrocode}
+% \cs{current@ref} is pretty much the same as \cs{current@reg@arg},
+% but takes no argument. It is used by commands such as \cs{lem} when
+% references to page and line numbers can be returned by \textsf{Lua}.
+%    \begin{macrocode}
+\def\current@ref{{%\textdir TLT%
+    \unexpanded\expandafter{\ekd@refnumstyle}%
     \ifnum%
     \getpagerefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}
     =
     \getpagerefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}
-      \ifnum%
-      \getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}
-      =
-      \getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}
-      %
-      \ifekd@mapps%
-      \ifbool{subsq@unit@\ekdan@type}{%
-        \ifnum%
-        \getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}
-        =
-        \getrefnumber{\luadirect{tex.sprint(ekdosis.getprevlnlab())}-b}
-        \else
-        \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}% issue the no
-        \fi%
-      }{\LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}}% issue the no
-      \else
-      \ifsubsq@unit%
-      %
+    \ifnum%
+    \getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}
+    =
+    \getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}
+    % 
+    \ifekd@mapps%
+    \ifbool{subsq@unit@\ekdan@type}{%
       \ifnum%
       \getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}
       =
       \getrefnumber{\luadirect{tex.sprint(ekdosis.getprevlnlab())}-b}
       \else
       \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}% issue the no
-      \fi
-      %
-      \else
-      \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}% issue the no
-      \fi
-      \fi
-      %
-      \else
-      \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}--%
-      \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}}% issue the nos
       \fi%
-      \else
-      \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}--%
-      \LRnum{\getpagerefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}}.%
-      \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}}% issue pg and ln nos
-      \fi%
-    }\unexpanded\expandafter{\ekd@postrefnum}%
-  }%
+    }{\LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}}% issue the no
+    \else
+    \ifsubsq@unit%
+    % 
+    \ifnum%
+    \getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}
+    =
+    \getrefnumber{\luadirect{tex.sprint(ekdosis.getprevlnlab())}-b}
+    \else
+    \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}% issue the no
+    \fi
+    % 
+    \else
+    \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}% issue the no
+    \fi
+    \fi
+    % 
+    \else
+    \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}--%
+    \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}}% issue the nos
+    \fi%
+    \else
+    \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}--%
+    \LRnum{\getpagerefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}}.%
+    \LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}}% issue pg and ln nos
+    \fi%
+  }\unexpanded\expandafter{\ekd@postrefnum}%
+}
+%    \end{macrocode}
+% Define keys to be used by the optional arguments of \cs{lem} and
+% \cs{rdg}:---
+%    \begin{macrocode}
 \ekvdefinekeys{lem}{
   code wit = \def\ekdlr@wit{#1},
   code alt  = \def\ekdlr@alt{#1},
@@ -2962,7 +3010,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   bool nolem = \ifekdl@nolem,
   bool nosep = \ifekdl@nosep,
   initial sep = \ekdsep
- }
+}
 \ekvdefinekeys{rdg}{
   code wit = \def\ekdlr@wit{#1},
   code alt  = \def\ekdlr@alt{#1},
@@ -2972,7 +3020,15 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   code postwit = \def\ekdlr@postwit{#1},
   store type = \ekdlr@type,
   bool nordg = \ifekdr@nordg
- }
+}
+%    \end{macrocode}
+% \begin{macro}{\lem}
+% \cs{lem}\oarg{options}\marg{lemma text} inserts \meta{lemma text}
+% both in the edition text and in the apparatus criticus by default,
+% preceded by the reference to the line number or a space if it is the
+% same number as the one of the previous entry. This command accepts
+% the optional key-value arguments just defined above.
+%    \begin{macrocode}
 \NewDocumentCommand{\lem}{O{} m}{%
   \ekd@isinlemtrue%
   \luadirect{ekdosis.dolnlab(\luastringN{#2})}%
@@ -3075,6 +3131,14 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   \ekd@isinlemfalse%
   \subsq@unittrue%
 }
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\rdg}
+% \cs{rdg}\oarg{options}\marg{variant reading} inserts \meta{variant
+% reading} in the second part of the entry, after the lemma text and
+% the separator, in the apparatus criticus. This command accepts the
+% optional key-value arguments defined above.
+%    \begin{macrocode}
 \NewDocumentCommand{\rdg}{O{} m}{%
   \bgroup%
   \ekvset{rdg}{#1}%
@@ -3145,6 +3209,11 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   \fi%
   \egroup%
 }
+%    \end{macrocode}
+% \end{macro}
+% Define keys to be used by the optional argument of \cs{note} when
+% this command is found outside \cs{app}:---
+%    \begin{macrocode}
 \ekvdefinekeys{note}{
   store type = \ekdan@type,
   store lem = \ekdn@lem,
@@ -3153,10 +3222,19 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   store sep = \ekdn@sep,
   initial type = default,
   initial sep = \ekdsep
- }
+}
+%    \end{macrocode}
+% \cs{note@noapp} is used internally when a \cs{note} command is found
+% outside \cs{app}. This command is mostly used to insert short
+% comments or references to texts quoted or cited in the edition text
+% to go into additional layers of the apparatus criticus, e.g.\ the
+% \emph{apparatus testium}. It accepts the optional key-value
+% arguments just defined above. It must be noted that |labelb| must be
+% specified; otherwise \pkg{ekdosis} will issue an error message.
+%    \begin{macrocode}
 \NewDocumentCommand{\note@noapp}{O{} +m}{%
   \bgroup%
-  \ekvset{note}{#1}
+  \ekvset{note}{#1}%
   \stepcounter{ekd@lab}%
   \zlabel{ekd:\theekd@lab}%
   \luadirect{ekdosis.storeabspg(
@@ -3218,10 +3296,23 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   \egroup%
   \subsq@unittrue%
 }
+%    \end{macrocode}
+% Define keys to be used by the optional argument of \cs{note} when
+% this command is found inside \cs{app}:---
+%    \begin{macrocode}
 \ekvdefinekeys{ekd@note}{
   store pre = \pre@value,
   store post = \post@value
 }
+%    \end{macrocode}
+% The following three commands, \cs{note@app}, \cs{ekd@note} and
+% \cs{ekd@note@star} are used internally when a \cs{note} command is
+% found inside \cs{app}. These commands are used to insert short
+% comments after the lemma text or after any variant reading in the
+% apparatus criticus. \cs{note@app} and subsequently \cs{ekd@note} and
+% \cs{ekd@note@star} accept the optional key-value arguments just
+% defined above.
+%    \begin{macrocode}
 \NewDocumentCommand{\ekd@note}{O{} m}{%
   \bgroup%
   \ekvset{ekd@note}{#1}%
@@ -3262,6 +3353,13 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
     {\ekd@note[#2]{#3}}%
   }%
 }
+%    \end{macrocode}
+% \begin{macro}{\note}
+% Finally, \cs{note} is a simple command designed to check if it is
+% found inside or outside \cs{app}. Then, unless it is found inside
+% \cs{lem}, it calls \cs{note@app} in the former case and
+% \cs{note@noapp} in the latter case:---
+%    \begin{macrocode}
 \NewDocumentCommand{\note}{s O{} +m}{%
   \ifekd@state%
     \ifekd@isinapp%
@@ -3275,6 +3373,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
       \fi%
   \fi%
 }
+%    \end{macrocode}
+% \end{macro}
+%    \begin{macrocode}
 \NewDocumentCommand{\apparatus}{}{%
   \luadirect{tex.sprint(ekdosis.appout())}}
 \NewDocumentCommand{\test@apparatus}{}{%