1 files changed, 120 insertions, 12 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 4e55f57..030fd8c 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -1123,7 +1123,7 @@ yesterday.
 % quoted or cited in the text of the edition (\emph{apparatus
 % fontium}), references to testimonia, or quotations of the edited
 % text by other authors (\emph{apparatus testium}), explanatory notes,
-% and so forth.\footnote{See below, \vref{ref:type-app}.} Once
+% and so forth.\footnote{See below, \vref{ref:type-note}.} Once
 % 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
@@ -1228,7 +1228,7 @@ yesterday.
 % \paragraph{Notes}
 % \DescribeMacro{\note}\DescribeMacro{\note*}
 % \cs{note}\oarg{options}\marg{text} or
-% \cs{note*}\oarg{options}\marg{text}\\
+% \cs{note*}\oarg{options}\marg{text}\label{ref:editorial-notes}\\
 % It may happen that editorial notes be needed to record short
 % comments of general nature \emph{between} lemmata and
 % readings. \cs{note} inserts inline comments while \cs{note*} places
@@ -1245,12 +1245,16 @@ yesterday.
 % \DescribeOption{post} |post|$=$\meta{words}\\
 % |post| inserts \meta{words} immediately after the note.\\
 %
-% \danger Under no circumstances is it permitted to insert the command
-% \cs{note} or \cs{note*} inside the argument of \cs{lem} or
+% \danger Under no circumstances is it permitted to insert this
+% command \cs{note} or \cs{note*} inside the argument of \cs{lem} or
 % \cs{rdg}. \cs{note}/\cs{note*} must go \emph{between} these
-% commands. As a general rule, within \cs{app}|{}| elements, notes
-% are inserted immediately \emph{after} the lemma or the variant
-% reading they are related to.
+% commands. As a general rule, within \cs{app}|{}| elements, notes are
+% inserted immediately \emph{after} the lemma or the variant reading
+% they are related to. However, as will be described below in
+% \vref{ref:type-note}, the command \cs{note}\---with no star
+% appended\---that is used to insert explanatory notes or references
+% to sources or testimonia is permitted within the mandatory argument
+% of \cs{lem}|{}|, although it is subject to a very strict syntax.
 %
 % \Vref{lst:pj2} provides an illustration of some of the possibilities
 % afforded by the commands just described:---
@@ -1924,7 +1928,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % 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}
+% \DescribeMacro{\EkdosisDefaultApparatus}\label{ref:ekd-default-app}
 % \cs{EkdosisDefaultApparatus}\marg{name} can be used at any point of
 % the document to change the default name that is used by
 % \pkg{ekdosis}.
@@ -1959,8 +1963,16 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % |default|, \pkg{ekdosis} will print the testimonia at the top of the
 % apparatus block.
 %
-% \subsubsection{Laying Out Layers}
+% \subsubsection{Laying Out Layers With The Optional Argument
+% of \cs{DeclareApparatus}}
 % \label{sec:layout-layers}
+% \DescribeOption{direction}
+% \DescribeOption{sep}
+% \DescribeOption{delim}
+% \DescribeOption{bhook}
+% \DescribeOption{ehook}
+% \DescribeOption{rule}
+% \DescribeOption{norule}
 % 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
@@ -2006,9 +2018,105 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % inserted within the argument of \cs{app}|{}| as described
 % \vpageref{ref:app-cmd} will go into that layer of the apparatus,
 % unless \cs{EkdosisDefaultApparatus} has been used to set another
-% name for the default layer.
+% name for the default layer (see above
+% \vpageref{ref:ekd-default-app}).
 %
+% \subsection{Variant Readings}
+% \label{sec:variant-readings}
+% In most cases, all variant readings go into the
+% \textooquote|default|\textcoquote\ layer of the apparatus
+% criticus. But in some other cases, for example when the manuscripts
+% used refer to different recensions, it may happen that one wishes to
+% record the related variants in separate layers. As already described
+% \vpageref{ref:app-type}, the |type| optional argument of the
+% \cs{app} command can be used to insert lemma texts and associated
+% variants in any other \enquote*{declared} layer of the apparatus
+% criticus.
+%
+% The following example assumes that some edition text is received in
+% two different recensions and the variant readings that belong to the
+% first recension are recorded in the default layer of notes while
+% those of the second recension are to be printed in a second layer,
+% below the default one. First, both layers must be declared in the
+% preamble in sequence, like so:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\DeclareApparatus{default} % default layer
+\DeclareApparatus{rec2} % additional layer below the default one
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% If one wishes to refer to |rec1| as the default layer, then
+% \cs{EkdosisDefaultApparatus} must be used, like so:---
 % 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\EkdosisDefaultApparatus{rec1}
+\DeclareApparatus{rec1} % new layer set as default
+\DeclareApparatus{rec2} % additional layer below the default one
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% Then, whatever option has been chosen, lemma texts and variants
+% inserted with \cs{app}|{}| will go into the upper, default layer of
+% notes, while those inserted with \cs{app}|[type=rec2]{}| will go
+% into the lower one:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+Some \app{
+  \lem{word}
+  \rdg{reading}
+} to go into the default layer of notes.
+
+Some \app[type=rec2]{
+  \lem{note}
+  \rdg{comment}
+} to be recorded as part of the second recension.
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% At any rate, |type=default| or |type=rec1|, depending on what has
+% been chosen, must be used if the editor wishes to retain that
+% information in the \texttt{TEI xml} output file.
+%
+% \subsection{Other Notes, Comments, Sources, Testimonia}
+% \label{ref:type-note}
+% Additional layers of notes may be used to print short comments or to
+% record references to texts quoted by the author of the edited text
+% or references to the edited text by other authors or
+% translators. The former is called an \emph{apparatus fontium} while
+% the latter is called an \emph{apparatus testium}.
+%
+% \danger From a technical standpoint, these notes are very different
+% from the short editorial notes inserted between lemma texts and
+% variant readings that have been described above
+% \vpageref{ref:editorial-notes}. However, for the sake of consistency
+% with \texttt{TEI xml} encoding, \pkg{ekdosis} uses the same command
+% \cs{note} to insert both kinds of notes.
+%
+% \danger One must also keep in mind that the notes that are described
+% in this section refer either to a single word or to a span of
+% text. By consequence, as boundaries must always be set outside spans
+% of text, notes must be inserted immediately before the word or words
+% they are related to. As a result of this rule, all spaces subsequent
+% to \cs{note} are ignored.
+%
+% \DescribeMacro{\note} \cs{note}\oarg{options}\marg{text}\\
+% As said above, \cs{note} when found outside \cs{app}|{}|, 
 %
 % \section{To Be Continued...}
 % v1.0 of \pkg{ekdosis}, which should be available by the end of July
@@ -2016,7 +2124,6 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % author is working on this part of the package.
 % 
 %
-% \label{ref:type-app}
 % \begin{comment}
 %   \section{Correspondence and Alignment}
 % \end{comment}
@@ -2642,7 +2749,8 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 \RequirePackage{lineno}
 \RequirePackage{keyfloat}
 \RequirePackage{refcount}
-\RequirePackage[user,abspage]{zref}
+\RequirePackage{zref-user}
+\RequirePackage{zref-abspage}
 \RequirePackage{ltxcmds}
 \RequirePackage{atbegshi}
 \if@pkg@parnotes