1 files changed, 262 insertions, 33 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 76e3fc4..8b79b24 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -625,11 +625,11 @@ along with this program.  If not, see
 % not as compact paragraphs that require special and painful training
 % to be \enquote*{decoded}. On the other hand, what editions in print
 % do not provide are what \citename{Mastronarde.Tarrant2017}{author}
-% have called \enquote{actionable texts for use in digital
-% research},\footcite{Mastronarde.Tarrant2017} namely database-driven
-% texts allowing the reader to select annotations and display or
-% arrange translations, parallel passages or borrowings in a variety
-% of ways.
+% have called \enquote{actionable texts for use in digital research},%
+% {\interfootnotelinepenalty=10000\footcite{Mastronarde.Tarrant2017}}
+% namely database-driven texts allowing the reader to select
+% annotations and display or arrange translations, parallel passages
+% or borrowings in a variety of ways.
 % 
 % \pkg{ekdosis} can be seen as an attempt at combining the two
 % approaches.
@@ -650,17 +650,18 @@ along with this program.  If not, see
 %   synchronized or not. \pkg{ekdosis} is also suitable for complex
 %   layouts as in the case of Arabic poetry or images where three-way
 %   alignment is required, or diagrams, \emph{\&c}.
-% \item \emph{Apparatus criticus\/}: Edited texts can receive multiple
-% layers of apparatus, e.g.\ apparatus criticus (to record variant
-% readings), apparatus fontium (to collect references to texts quoted
-% or cited in the edited text), apparatus testium (to collect
-% testimonia or parallel passages), or any kind of short notes to be
-% printed on the same page as the edited text, \emph{\&c}.
-% \item \texttt{TEI xml} output: \pkg{ekdosis} can be instructed
-% to output both PDF and \texttt{TEI xml} files at the same time.
+% \item \label{it:multilayer-feature}\emph{Apparatus criticus\/}:
+%   Edited texts can receive multiple layers of apparatus, e.g.\
+%   apparatus criticus (to record variant readings), apparatus fontium
+%   (to collect references to texts quoted or cited in the edited
+%   text), apparatus testium (to collect testimonia or parallel
+%   passages), or any kind of short notes to be printed on the same
+%   page as the edited text, \emph{\&c}.
+% \item \texttt{TEI xml} output: \pkg{ekdosis} can be instructed to
+%   output both PDF and \texttt{TEI xml} files at the same time.
 % \item \emph{Database-driven encoding} under \LaTeX{} of texts
-% entered segment by segment allows for alignment of parallel texts
-% from multilingual corpora.
+%   entered segment by segment allows for alignment of parallel texts
+%   from multilingual corpora.
 % \end{enumerate}
 %
 % Before going into detail, the following simple example will give the
@@ -1086,7 +1087,7 @@ along with this program.  If not, see
 % 
 % \paragraph{Apparatus Entries}
 % \DescribeMacro{\app} \cs{app}|[type=|\meta{type}|]|\marg{apparatus
-% entries}\\
+% entries}\label{ref:app-cmd}\\
 % This command takes one mandatory argument and accepts one optional
 % argument.  Once references to be used as witnesses in the apparatus
 % criticus have been declared in the preamble as described in
@@ -1111,9 +1112,10 @@ yesterday.
 %</example>
 % \fi
 % \cs{app} accepts one further optional argument:---\\
-% \DescribeOption{type} |type|$=$\meta{type}\hfill%
-% \tcboxverb{Default: default}\\
-% By default, \pkg{ekdosis} sets one layer of notes\--- the |default|
+% \DescribeOption{type} |type|$=$\meta{type}\label{ref:app-type}
+% \hfill\tcboxverb{Default: default}\\
+% As will be described below in \vref{sec:multilayer-apparatus},
+% \pkg{ekdosis} initially sets one layer of notes\--- the |default|
 % layer\---in the apparatus criticus. This layer is fit to receive
 % notes related to variant readings from witnesses and sources used by
 % the editor to establish the edition text. Additional layers can be
@@ -1125,7 +1127,8 @@ yesterday.
 % additional layers have been defined and assigned to new
 % \enquote*{types}, such as \enquote*{testium} and the like, these
 % types can be used as values appended to the |type| \enquote*{named
-% option}.
+% option}. For more information about inserting notes in
+% multiple-layer apparatus, see \vref{sec:notes-in-multilayer-app}.
 %
 % \paragraph{Base text and variants} As can be seen in the example
 % above, there are two kinds of individual readings: the \emph{lemma},
@@ -1756,9 +1759,45 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 %
 % \section{Laying Out the Apparatus Criticus }
 % \label{sec:apparatus-layout}
+%
+% \subsection{General Hooks}
+% \label{sec:general-hooks}
+% Some hooks are shared by all layers of notes that are inserted in
+% the apparatus criticus (e.g. sources, testimonia, variant readings
+% \emph{\&c.})
+%
+% \DescribeMacro{\SetEkdosisHooks}
+% \cs{SetEkdosisHooks}\marg{csv list of hooks} can be used either in
+% the preamble or at any point of the document. The list of accepted
+% hooks at the time of writing follows:---\\
+% \DescribeOption{appfontsize} |appfontsize|$=$\meta{csname}
+% \hfill\tcboxverb{Default: \footnotesize}\\
+% This option sets the size of the font to be used in the whole
+% apparatus criticus. By default, it is the same as the size used for
+% footnotes.\\
+% \DescribeOption{refnumstyle} |refnumstyle|$=$\meta{csname}
+% \hfill\tcboxverb{Default: \bfseries}\\
+% |refnumstyle| can be used to set the family, series or shape of the
+% font used to print references to line numbers in the apparatus
+% criticus. By default, numbers are printed in bold face. As an
+% example, |refnumstyle=\normalfont| will have them printed in the
+% font and shape selected by default for the
+% document, while |refnumstyle=\bfseries\itshape| will have them
+% printed in bold and italic.\\
+% \DescribeOption{postrefnum} |postrefnum|$=$\meta{csname \textbar\
+% chars}\hfill\tcboxverb{Default: ~}\\
+% |postrefnum| can be used to set what immediately follows the
+% reference to line numbers. By default, it is |~|, namely an
+% unbreakable space. As an example, |postrefnum=\hskip 0.5em| will
+% insert a \unit[0.5]{em} space between the numerals and the beginning
+% of all subsequent notes.
+%
+% \subsection{Single-Layer Apparatus Criticus}
+% \label{sec:single-layer-app}
+% \paragraph{Specific Commands}
 % Single-layer apparatus criticus can be laid out in a variety of
 % ways with the following specialized commands, all of which can be
-% used in the preamble or at any point of the document.
+% used in the preamble or at any point of the document:---
 %
 % \DescribeMacro{\SetLTRapp}
 % \DescribeMacro{\SetRTLapp}
@@ -1772,9 +1811,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % followed by a space (\verb*+] +).
 %
 % \DescribeMacro{\SetBeginApparatus}
-% \cs{SetBeginApparatus}\marg{characters/commands} can be used to
-% append \meta{characters} or \meta{commands} at the beginning of the
-% apparatus block. By default, nothing is appended. For instance,
+% \cs{SetBeginApparatus}\marg{characters\textbar commands} can be used
+% to append \meta{characters} or \meta{commands} at the beginning of
+% the apparatus block. By default, nothing is appended. For instance,
 % \mintinline{latex}|\SetBeginApparatus{\textbf{Apparatus:}}| will
 % append \enquote{\textbf{Apparatus:}} at the beginning of the
 % apparatus block, while %
@@ -1789,17 +1828,189 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % at the end of the apparatus as it is customary in some editions.
 %
 % \DescribeMacro{\SetUnitDelimiter}
-% \cs{SetUnitDelimiter}
+% \cs{SetUnitDelimiter}\marg{delimiter} can be used to set the
+% delimiter between entries in the apparatus criticus. By default,
+% there is no delimiter except a simple space. \meta{delimiter} can be
+% a broad space (such as |\hskip 0.75em| for instance as in the OCT
+% series) or the divider-sign (‖, as in the Budé series).
+%
+% \DescribeMacro{\SetDefaultRule}
+% By default, \pkg{ekdosis} draws a separating line between the
+% edition text and the apparatus criticus. This line is initially
+% defined as
+% |\rule{0.4\columnwidth}{0.4pt}|. \cs{SetDefaultRule}\marg{line
+% definition} can be used in the preamble or at any point of the
+% document to change the default setting. Leaving this argument empty
+% as in \cs{SetDefaultRule}|{}| removes the line.
+%
+% \paragraph{General Command}
+% \DescribeMacro{\SetApparatus} \cs{SetApparatus}\marg{csv list of
+% apparatus settings}\label{ref:apparatus-settings-b}\\
+% Finally, all the settings described above can also be collected in
+% the argument of \cs{SetApparatus}. \cs{SetApparatus} accepts the
+% following list of comma-separated |key=value| options:---\\
+% \DescribeOption{direction} |direction|$=$\verb+LR|RL+
+% \hfill\tcboxverb{Default: LR}\\
+% The writing direction of the apparatus criticus, either
+% left-to-right (|LR|) or right-to-left (|LR|).\\
+% \DescribeOption{sep} |sep|$=$\meta{csname \textbar\ chars}
+% \hfill\tcboxverb{Default: ]␣}\\
+% The separator between lemma texts and variant readings.\\
+% \DescribeOption{delim} |delim|$=$\meta{delimiter}
+% \hfill\tcboxverb{Default: not set}\\
+% The delimiter between entries in the apparatus criticus. As said
+% above, there is no default delimiter except a simple space.\\
+% \DescribeOption{bhook} |bhook|$=$\meta{characters\textbar commands}
+% \hfill\tcboxverb{Default: empty}\\
+% The characters or commands to be appended at the beginning of the
+% apparatus block.\\
+% \DescribeOption{ehook} |ehook|$=$\meta{characters}
+% \hfill\tcboxverb{Default: empty}\\
+% The characters to be appended at the end of the apparatus block.\\
+% \DescribeOption{rule} |rule|$=$\meta{command}\verb+|+|none|
+% \hfill\tcboxverb{Default: \rule{0.4\columnwidth}{0.4pt}}\\
+% As described above, |rule| is used to draw the separating line
+% between the edition text and the apparatus criticus. |rule=none| can
+% also be used to remove the line.\\
+% \DescribeOption{norule}\hfill\tcboxverb{Default: not set}\\
+% |norule| does not accept any value and has the same effect as
+% |rule=none|.\label{ref:apparatus-settings-e}
+%
+% As an example, an apparatus criticus with references to line numbers
+% printed in normal font, a colon as a separator between lemma texts
+% and variant readings, a broad space as a delimiter between entries
+% and a \unit[0.7]{in} line above could be laid out as follows:---
+%
+% \label{ex:single-layer-app-layout}
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\SetEkdosisHooks{
+  refnumstyle=\normalfont
+}
+\SetApparatus{
+  sep={: },
+  delim=\hskip 1em,
+  rule=\rule{0.7in}{0.4pt}
+}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Footnote Separator}
+% \DescribeMacro{\footnoteruletrue} \DescribeMacro{\footnoterulefalse}
+% As already seen above, \pkg{ekdosis} takes care of drawing a
+% separating line between the edition text and the apparatus
+% criticus. Therefore, it may be not desirable to have the standard
+% \LaTeX\ \enquote{footnoterule} printed on every page where regular
+% footnotes are found. \cs{footnoterulefalse} removes it while
+% \cs{footnoteruletrue} leaves it untouched. The latter is set by
+% default.
+%
+% \subsection{Multiple-Layer Apparatus Criticus}
+% \label{sec:multilayer-apparatus}
+% As said above in \vref{it:multilayer-feature}, \pkg{ekdosis} can
+% print edition texts equipped with multiple-layer apparatus
+% criticus. To take an example, most classical editions provide at
+% least two layers of notes: one to collect references to testimonia
+% or parallel passages (apparatus testium) and the other to record
+% variant readings (the apparatus criticus \emph{stricto sensu}). The
+% former is always printed above the latter.
+%
+% \danger The default single-layer apparatus criticus that is
+% described above in \vref{sec:single-layer-app} is called |default|
+% internally. If any additional layer of notes be declared in the
+% preamble, this |default| layer must be included in the list of
+% declared layers.\\
+% \DescribeMacro{\EkdosisDefaultApparatus}
+% \cs{EkdosisDefaultApparatus}\marg{name} can be used at any point of
+% the document to change the default name that is used by
+% \pkg{ekdosis}.
+%
+% \subsubsection{Declaring Additional Layers}
+% \label{sec:declaring-layers}
+% \DescribeMacro{\DeclareApparatus}
+% \cs{DeclareApparatus}\marg{name}\oarg{csv list of apparatus
+% settings} is a preamble-only command. As a mandatory argument, it
+% takes the name of the new layer of notes to be inserted in the
+% apparatus block. Declared layers are then printed one below the
+% other in the exact same order as they are declared in the
+% preamble. Therefore, one additional layer meant to print the
+% testimonia above the variant readings (apparatus testium) can be
+% declared as follows:---
 % 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+% preamble:
+\DeclareApparatus{testium}
+\DeclareApparatus{default}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% In this example, |testium| is a new name for |default|, as said
+% just above, is already known to \pkg{ekdosis} and used as the
+% default layer of notes. Furthermore, as |testium| is declared before
+% |default|, \pkg{ekdosis} will print the testimonia at the top of the
+% apparatus block.
+%
+% \subsubsection{Laying Out Layers}
+% \label{sec:layout-layers}
+% With regard to layout, any declared layer inherits the defaut values
+% described above in \vref{sec:single-layer-app}. That said, as the
+% optional argument of \cs{DeclareApparatus} accepts the exact same
+% |key-value| options as \cs{SetApparatus} described
+% \vpagerefrange{ref:apparatus-settings-b}{ref:apparatus-settings-e},
+% \pkg{ekdosis} provides a straightforward mechanism to have any layer
+% printed in a distinct layout.
+%
+% To return to the example provided
+% \vpageref[above]{ex:single-layer-app-layout}, one could keep the
+% same settings as above for the variant readings, declare an
+% apparatus testium with a closing square bracket as a separator and
+% finally remove the line between the testimonia and the variant
+% readings like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\SetEkdosisHooks{
+  refnumstyle=\normalfont
+}
+\DeclareApparatus{testium}[
+  sep={] },
+  delim=\hskip 1em,
+  rule=\rule{0.7in}{0.4pt}
+]
+\DeclareApparatus{default}[
+  sep={: },
+  delim=\hskip 1em,
+  norule
+]
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \section{Inserting Notes in Multiple-Layer Apparatus}
+% \label{sec:notes-in-multilayer-app}
+% As said above in \vref{sec:multilayer-apparatus}, \pkg{ekdosis}
+% initially sets one layer of notes that is called the
+% \textooquote|default|\textcoquote\ layer. As a result, any new note
+% inserted within the argument of \cs{app}|{}| as described
+% \vpageref{ref:app-cmd} will go into that layer of the apparatus.
+%
 % \section{To Be Continued...}
 % v1.0 of \pkg{ekdosis}, which should be available by the end of July
 % 2020, will include a full documentation. At the time of writing, the
 % author is working on this part of the package.
 % 
-% \begin{comment}
-%   \section{Multiple-Layer Apparatus Criticus}
-% \end{comment}
-% \label{sec:multilayer-apparatus}
 %
 % \label{ref:type-app}
 % \begin{comment}
@@ -2443,10 +2654,6 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   \luadirect{ekdosis.closestream()}
 }
 %    \end{macrocode}
-% Use |\normalfont| for line numbers:---
-%    \begin{macrocode}
-\renewcommand\linenumberfont{\normalfont\footnotesize}
-%    \end{macrocode}
 % \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
@@ -2547,14 +2754,31 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 \@onlypreamble\DeclareShorthand
 %    \end{macrocode}
 % \end{macro}
+% \begin{macro}{\getsiglum}
+% \cs{getsiglum}\marg{csv list} takes a comma-separated list of
+% declared ids by means of \cs{DeclareWitness}, \cs{DeclareHand},
+% \cs{DeclareShorthand} or \cs{DeclareScholar} and returns their
+% respective renditions.
 %    \begin{macrocode}
 \NewDocumentCommand{\getsiglum}{m}{%
   \luadirect{tex.sprint(ekdosis.getsiglum(\luastringN{#1}))}%
 }
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\SigLine}
+% \cs{Sigline}\marg{unique id} takes the unique id of any declared
+% witness by means of \cs{DeclareWitness} as argument and returns a
+% line ready to be inserted in a table set to print a Conspectus
+% Siglorum. \cs{SigLine} returns three fields separated by the symbol
+% |&| that is used in tables as follows: the siglum referring to the
+% witness, the contents of the |description| field and the contents of
+% the optional |origDate| field.
+%    \begin{macrocode}
 \NewDocumentCommand{\SigLine}{m}{%
   \luadirect{tex.sprint(ekdosis.basic_cs(\luastringN{#1}))}
 }
 %    \end{macrocode}
+% \end{macro}
 % \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
@@ -2658,6 +2882,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
   store bhook = \bhook@val,
   store ehook = \ehook@val,
   initial direction = LR,
+  initial delim = {},
   initial ehook = {\csname ekd@end@apparatus\endcsname}
 }
 %    \end{macrocode}
@@ -2987,6 +3212,10 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 }
 %    \end{macrocode}
 % \end{macro}
+% Use |\normalfont| for line numbers:---
+%    \begin{macrocode}
+\renewcommand\linenumberfont{\normalfont\footnotesize}
+%    \end{macrocode}
 % \begin{macro}{\EkdosisDefaultApparatus}
 % By default, \pkg{ekdosis} defines one layer of critical notes which
 % is called |default|. This name can be changed at any point of the