1 files changed, 111 insertions, 12 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index b9cfbaf..70b30ad 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -3355,10 +3355,10 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 }
 %    \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:---
+% Finally, \cs{note} is a simple command designed to check whether
+% \cs{note} itself is called 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%
@@ -3375,19 +3375,35 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 }
 %    \end{macrocode}
 % \end{macro}
+% \cs{apparatus} is used internally by \pkg{ekdosis} to print the
+% apparatus at the bottom of pages. Therefore, it is not documented,
+% but this may change in the future for it will be possible to have
+% apparatuses printed at other places.
 %    \begin{macrocode}
 \NewDocumentCommand{\apparatus}{}{%
   \luadirect{tex.sprint(ekdosis.appout())}}
+%    \end{macrocode}
+% The following two commands call \textsf{Lua} functions to check
+% whether an apparatus should be printed on a given page and to store
+% the current column id.
+%    \begin{macrocode}
 \NewDocumentCommand{\test@apparatus}{}{%
   \luadirect{tex.sprint(ekdosis.testapparatus())}}
 \NewDocumentCommand{\ekd@storecol}{}{%
   \luadirect{ekdosis.storecurcol(\luastring{\thecolumn})}%
 }
+%    \end{macrocode}
+% Start and stop |ekdosis|:
+%    \begin{macrocode}
 \NewDocumentCommand{\EkdosisOn}{}{%
   \ekd@statetrue}
 \NewDocumentCommand{\EkdosisOff}{}{%
   \ekd@statefalse%
 }
+%    \end{macrocode}
+% Neutralize unwanted commands provided by \pkg{lineno} within the
+% \env{ekdosis} environment:---
+%    \begin{macrocode}
 \def\ekd@setlineno{%
   \let\setpagewiselinenumbers\relax%
   \let\pagewiselinenumbers\relax%
@@ -3395,15 +3411,27 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   \let\runningpagewiselinenumbers\relax%
   \let\realpagewiselinenumbers\relax%
 }
+%    \end{macrocode}
+% \begin{environment}{ekdosis}
+% Finally comes the \env{ekdosis} environment meant to receive the
+% edition text equipped with an apparatus criticus. This environment
+% collects its contents and delivers it to \textsf{Lua} functions if a
+% \texttt{TEI xml} output file be desired.
+%    \begin{macrocode}
 \NewDocumentEnvironment{ekdosis}{+b}{%
   \ekd@setlineno%
   \runninglinenumbers
     \EkdosisOn#1}{%
     \EkdosisOff
   \endrunninglinenumbers%
-  \iftei@export\luadirect{ekdosis.exporttei(\luastringN{\par #1\par })}\else\fi}
+  \iftei@export
+  \luadirect{ekdosis.exporttei(\luastringN{\par #1\par })}\fi}
 %    \end{macrocode}
-% Alignment:---
+% \end{environment}
+% \paragraph{Alignment} What follows isto arrange texts in parallel
+% columns either on single pages or on facing pages.
+%
+% Define keys to be used by the \env{alignment} environment:---
 %    \begin{macrocode}
 \newif\ifekd@pagelineation
 \ekvdefinekeys{ekd@align}{
@@ -3428,13 +3456,29 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   initial apparatus = edition,
   default segmentation = auto
 }
+%    \end{macrocode}
+% \begin{macro}{\SetEkdosisAlignment}
+% \cs{SetEkdosisAlignment}\marg{settings} can be used either in the
+% preamble or at any point of the document to set or modify the
+% keys-value settings just defined above.
+%    \begin{macrocode}
 \NewDocumentCommand{\SetEkdosisAlignment}{m}{
   \ekvset{ekd@align}{#1}
 }
+%    \end{macrocode}
+% \end{macro}
+% Patch \pkg{paracol} to insert a hook in \cs{pcol@nextpage}. This
+% hook is used to reset line numbers on new pages.
+%    \begin{macrocode}
 \patchcmd{\pcol@nextpage}{%
   \endgroup}{%
   \ifekd@pagelineation\resetlinenumber\fi
   \endgroup}{}{}
+%    \end{macrocode}
+% \cs{EkdosisColStart} and \cs{EkdosisColStop} initialize columns
+% meant to receive edition texts. These commands are used internally
+% by \pkg{ekdosis}.
+%    \begin{macrocode}
 \NewDocumentCommand{\EkdosisColStart}{}{%
   \ekd@setlineno%
   \runninglinenumbers
@@ -3456,6 +3500,19 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
     "pg_ii")}%
   \endrunninglinenumbers%
 }
+%    \end{macrocode}
+% \begin{environment}{alignment}
+% \cs{begin}|{alignment}|\oarg{options}\dots\cs{end}|{alignment}| can
+% be used as it is provided to typeset a standard critical edition
+% text on the left-hand pages accompanied with a translation on the
+% right-hand pages. To that effect, it provides by default two new
+% environments, \env{edition} and \env{translation}, to be used to
+% typeset both texts. (Either whole texts or texts entered by
+% paragraphs alternately.) The optional argument of \env{aligment}
+% accepts the exact same key-value options as \cs{SetEkdosisAlignment}
+% described above. One may contrast these options with those accepted
+% by \cs{SetEkdosisAlignment} as \enquote{local settings}.
+%    \begin{macrocode}
 \NewDocumentEnvironment{alignment}{O{}}
 {%
   \ekvset{ekd@align}{#1}%
@@ -3486,7 +3543,20 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   \luadirect{ekdosis.flushcolnums()}
   }
 %    \end{macrocode}
-% Divisions of the Body
+% \end{environment}
+% \paragraph{Divisions of the Body}
+% \pkg{ekdosis} can convert \cs{book}, \cs{part}, \cs{chapter},
+% \cs{section}, \cs{subsec{\allowbreak}tion} and \cs{subsubsection}
+% into corresponding \texttt{TEI} \enquote*{numbered}
+% |<div|\textsubscript{\emph{n}}|>| elements, where $1\leq n\leq 6$.
+% \begin{macro}{\MkBodyDivs}
+% \cs{MkBodyDivs} is used to let \pkg{ekdosis} know which sectional
+% commands are actually being used in an edition text. This command
+% takes six mandatory arguments. For example, if \cs{section} and
+% \cs{subsection} are the only sectional commands being used,
+% |\MkBodyDivs{section}{subsection}{}{}{}{}| will have \cs{section}
+% and \cs{subsection} converted into |<div1>| and |<div2>|
+% respectively.
 %    \begin{macrocode}
 \NewDocumentCommand{\MkBodyDivs}{mmmmmm}{
   \luadirect{ekdosis.mkdivdepths(
@@ -3500,7 +3570,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   }
 }
 %    \end{macrocode}
-% Divisions specific to ekdosis:---
+% \end{macro}
+% Divisions specific to \pkg{ekdosis}. Define keys to be used by
+% \cs{ekddiv}:---
 %    \begin{macrocode}
 \ekvdefinekeys{ekd@div}{
   code type = \def\type@value{#1},
@@ -3521,13 +3593,38 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
     \MessageBreak `subsubsection', `paragraph' or `subparagraph'.},
   initial depth = 1
 }
-
+%    \end{macrocode}
+% \begin{macro}{\ekdfmtdiv}
+% \cs{ekdfmtdiv}\marg{n}\marg{code before}\marg{code after} is
+% used to lay out the heading of the title. It takes three mandatory
+% arguments: \emph{n}, namely the number referring to the particular
+% depth of the division, and then some \LaTeX{} formatting commands
+% to go before and after the heading itself:---
+%    \begin{macrocode}
 \NewDocumentCommand{\ekdfmtdiv}{m m m}{
-  \luadirect{ekdosis.fmtdiv(\luastring{#1}, \luastringN{#2}, \luastringN{#3})}
+  \luadirect{ekdosis.fmtdiv(\luastring{#1},
+    \luastringN{#2},
+    \luastringN{#3})}
 }
+%    \end{macrocode}
+% \end{macro}
+% \cs{ekd@getfmtdiv} gets the formatting commands that have been
+% stored by \cs{ekdfmtdiv}.
+%    \begin{macrocode}
 \NewDocumentCommand{\ekd@getfmtdiv}{m m}{%
-  \luadirect{tex.sprint(ekdosis.getfmtdiv(\luastringO{#1}, \luastringN{#2}))}%
+  \luadirect{tex.sprint(ekdosis.getfmtdiv(\luastringO{#1},
+    \luastringN{#2}))}%
 }
+%    \end{macrocode}
+% \begin{macro}{\ekddiv}
+% \cs{ekddiv}\marg{key-value arguments} is the standard command
+% provided by \pkg{ekdosis} to meet the requirements of classical and
+% literary texts the divisions of which depend on many different
+% received traditions. It takes one optional argument in which the
+% key-value arguments defined above are accepted, and converts the
+% divisions into \texttt{TEI} \enquote*{un-numbered} |<div>|
+% elements.
+%    \begin{macrocode}
 \NewDocumentCommand{\ekddiv}{m}{
   \begingroup
   \ekvset{ekd@div}{#1}%
@@ -3549,7 +3646,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   \endgroup
 }
 %    \end{macrocode}
-% Very basic implementation of poetry lines:---
+% \end{macro}
+% A very basic and provisional implementation of poetry lines
+% follows:---
 %    \begin{macrocode}
 \newlength{\ekdverseindentlength}
 \setlength{\ekdverseindentlength}{\parindent}