started inserting comments in the Implementation part

1 files changed, 56 insertions, 10 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 6b3d97d..f0dc576 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -1111,7 +1111,8 @@ yesterday.
 % the edition text and as the first part of a new entry in the
 % apparatus criticus, preceded by the line number where it occurs or a
 % broad space if the entry refers to the same line as the preceding
-% entry. The optional argument of \cs{lem} accepts the following
+% entry. \dummy\label{ref:lem-opts-b}The optional argument of \cs{lem}
+% accepts the following
 % comma-separated list of \enquote{name$=$value} arguments:---\\
 % \DescribeOption{wit} |wit|$=$\meta{csv list of witnesses}\\
 % While a single witness may be recorded as in |wit=A|,
@@ -1120,12 +1121,11 @@ yesterday.
 % |wit={A,B,C}|. \dummy\label{ref:mss-sep-families}It must be noted
 % that witnesses can be grouped by using spaces as separators, like
 % so: \verb*|wit={A,B,C, D,E,F}|.\\
-% \label{ref:lem-opts-b}
 % \DescribeOption{alt} |alt|$=$\meta{alternate lemma}\\
 % While the mandatory argument of \cs{lem}, \meta{lemma text}, is
 % always used to print the edition text in the upper part of the page,
 % \meta{alternate lemma}, if specified, supersedes what is printed in
-% the related unit of the apparatus criticus. This mechanism is useful
+% the related entry of the apparatus criticus. This mechanism is useful
 % in more than one respect. For instance, it can be used to insert
 % abbreviated lemmata in the apparatus criticus, or to introduce an
 % alternate way of writing entries with Latin technical terms in the
@@ -2114,12 +2114,12 @@ yesterday.
 %    \begin{macrocode}
 \RequirePackage{iftex}
 %    \end{macrocode}
-% \pkg{ekdosis} requires {\LuaLaTeX} of course. Issue an error
+% Of course, \pkg{ekdosis} requires {\LuaLaTeX}. Issue an error
 % if the document is processed with another engine.
 %    \begin{macrocode}
 \RequireLuaTeX
 %    \end{macrocode}
-% Packages that are required by \pkg{ekdosis}:
+% Set global options:---
 %    \begin{macrocode}
 \RequirePackage{xkeyval}
 \newif\if@pkg@float
@@ -2173,6 +2173,9 @@ yesterday.
   \else\fi\fi\fi}
 \ExecuteOptionsX{layout,divs}
 \ProcessOptionsX\relax
+%    \end{macrocode}
+% Packages that are required by \pkg{ekdosis}:---
+%    \begin{macrocode}
 \RequirePackage{luacode}
 \RequirePackage{paracol}
 \RequirePackage{expkv-def}
@@ -2187,7 +2190,7 @@ yesterday.
   \RequirePackage{parnotes}
 \fi
 %    \end{macrocode}
-% Here begins the real work: load |ekdosis.lua|:
+% Here begins the real work: load |ekdosis.lua|:---
 %    \begin{macrocode}
 \luadirect{dofile(kpse.find_file("ekdosis.lua"))}
 %    \end{macrocode}
@@ -2196,11 +2199,14 @@ yesterday.
   \luadirect{ekdosis.closestream()}
 }
 %    \end{macrocode}
-% General settings
+% General settings:---
 %    \begin{macrocode}
 \renewcommand\linenumberfont{\normalfont\footnotesize}
 %    \end{macrocode}
-% Hooks
+% \begin{macro}{\SetEkdosisHooks} \cs{SetEkdosisHooks} is used to set
+%   hooks meant to be shared by all declared apparatuses, such as the
+%   font size, the format of numerals, \emph{\&c.} This command can be
+%   used in the preamble or at any point of the document.
 %    \begin{macrocode}
 \ekvdefinekeys{ekd@hooks}{
   store appfontsize = \ekd@appfontsize,
@@ -2212,7 +2218,8 @@ yesterday.
 }
 \NewDocumentCommand{\SetEkdosisHooks}{m}{\ekvset{ekd@hooks}{#1}}
 %    \end{macrocode}
-% Build and process the list of witnesses and hands.
+% \end{macro}
+% Build and process the list of witnesses and hands:---
 %    \begin{macrocode}
 \ekvdefinekeys{ekd@witness}{
   store settlement = \settlement@value,
@@ -2223,6 +2230,14 @@ yesterday.
   store msName = \msName@value,
   store origDate = \origDate@value
 }
+%    \end{macrocode}
+% \begin{macro}{\DeclareWitness} \cs{DeclareWitness} is a
+%   preamble-only command. It takes three mandatory arguments and one
+%   optional argument. It is meant to collect data related to
+%   witnesses to be used in the edition text. Data are stored in |Lua|
+%   tables and are used to encode the |<listWit>| part of the |TEI|
+%   header as well as the Conspectus Siglorum in the edition in print.
+%    \begin{macrocode}
 \NewDocumentCommand{\DeclareWitness}{m m m O{}}{%
   \bgroup
   \ekvset{ekd@witness}{#4}
@@ -2240,6 +2255,15 @@ yesterday.
     \egroup
   }
 \@onlypreamble\DeclareWitness
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\DeclareHand} As \cs{DeclareWitness}, \cs{DeclareHand}
+%   is a preamble-only command meant to collect data and store them in
+%   |Lua| tables. It takes three mandatory arguments and one optional
+%   argument. The second argument is used to connect the hand to a
+%   declared witness it is related to. Then the table in which this
+%   witness is recorded can be fed with new data.
+%    \begin{macrocode}
 \NewDocumentCommand{\DeclareHand}{m m m +O{}}{
   \luadirect{ekdosis.newhand(\luastringN{#1},
     \luastringN{#2},
@@ -2247,17 +2271,39 @@ yesterday.
     \luastringN{#4})}
 }
 \@onlypreamble\DeclareHand
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\DeclareScholar} There is also a table in which are
+%   collected data related to scholars' names to be used in the
+%   apparatus criticus. \cs{DeclareScholar} is a preamble-only command
+%   and takes two mandatory arguments: a unique id and a shorthand to
+%   be used in the apparatus criticus which can be extracted from a
+%   bibliographic database.
+%    \begin{macrocode}
 \NewDocumentCommand{\DeclareScholar}{m m}{
   \luadirect{ekdosis.newscholar(\luastringN{#1},
     \luastringN{#2})}
 }
 \@onlypreamble\DeclareScholar
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\DeclareShorthand} \cs{DeclareShorthand} is a
+%   preamble-only command that can be used to record manuscript
+%   families or any kind of shorthand to be used to refer to
+%   previously declared ids, for example the shorthand |codd| can be
+%   used to point to all declared witnesses. This command takes three
+%   mandatory arguments: a unique id, its rendition in print and a
+%   csv-list of previously declared ids.
+%    \begin{macrocode}
 \NewDocumentCommand{\DeclareShorthand}{m m m}{
   \luadirect{ekdosis.newshorthand(\luastringN{#1},
     \luastringN{#2},
     \luastringN{#3})}
 }
 \@onlypreamble\DeclareShorthand
+%    \end{macrocode}
+% \end{macro}
+%    \begin{macrocode}
 \NewDocumentCommand{\getsiglum}{m}{%
   \luadirect{tex.sprint(ekdosis.getsiglum(\luastringN{#1}))}%
 }
@@ -4729,7 +4775,7 @@ end
 % \iffalse
 %<*examples>
 % \fi
-% \begin{minted}[firstnumber=last]{latex}
+% \begin{minted}{latex}
 \documentclass[12pt]{article}
 \usepackage{fontspec}
 \usepackage[english]{babel}