From 06f82a8158874e49c5ff6c0045e3fdf1250a287a Mon Sep 17 00:00:00 2001
From: Robert Alessi <alessi@robertalessi.net>
Date: Mon, 29 Mar 2021 08:25:38 +0200
Subject: done documenting the new features. getting close to v1.2

---
 ekdosis.dtx | 545 ++++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 454 insertions(+), 91 deletions(-)

diff --git a/ekdosis.dtx b/ekdosis.dtx
index c7f6592..64b2cff 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -254,13 +254,15 @@ along with this program.  If not, see
 
 @Book{McDonald1916,
   editor =	 {MacDonald Alden, Raymond},
+  shorteditor =	 {MacDonald},
   title =	 {The Sonnets of Shakespeare},
   date =	 1916,
   titleaddon =	 {From the Quarto of 1609 with Variorum Readings and
                   Commentary},
-  publisher =	 {Houghton Mifflin Co.},
-  options = 	 {useauthor=false, useeditor=true},
-  location =	 {Boston}
+  organization = {Houghton Mifflin Co.},
+  publisher =	 {The Riverside Press Cambridge},
+  options =	 {useauthor=false, useeditor=true},
+  location =	 {Boston \& New York}
 }
 
 @Book{ReynoldsWilson1991,
@@ -336,6 +338,15 @@ along with this program.  If not, see
   version =	 {4.41}
 }
 
+@Software{memoir,
+  title =	 {The Memoir package},
+  titleaddon =	 {Typeset fiction, non-fiction and mathematical books},
+  author =	 {Madsen, Lars and Wilson, Peter R.},
+  url =		 {http://www.ctan.org/pkg/memoir},
+  date =	 {2021-03-23},
+  version =	 {3.7o}
+}
+
 @Software{paracol,
   title =	 {The Paracol package},
   titleaddon =	 {Multiple columns with texts “in parallel”},
@@ -580,6 +591,7 @@ along with this program.  If not, see
 \usepackage[defaultindex=none,citecmd=autocite]{icite}
 \bibinput{ekdosis}
 \usepackage[nospace,american]{varioref}
+\newcommand\phts{\phantomsection}
 \usepackage[style=oxnotes-inote,dashed]{biblatex}
 \DeclareSourcemap{
     \maps[datatype=bibtex]{
@@ -714,6 +726,7 @@ along with this program.  If not, see
   xleftmargin=12pt, breaklines, numberblanklines=false, numbersep=3pt}
 \renewcommand{\theFancyVerbLine}{\normalfont\smaller\arabic{FancyVerbLine}}
 \usepackage[contents]{colordoc}
+\newcommand{\cls}[1]{\textsf{#1}\index{#1=#1 (class)}}
 \newcommand{\pkg}[1]{\textsf{#1}\index{#1=#1 (package)}}
 \newcommand{\env}[1]{\texttt{#1}\index{#1=#1 (environment)}}
 \backgroundcolor{c}{ekdcolor}
@@ -978,7 +991,7 @@ along with this program.  If not, see
 % \label{sec:features}
 % A list of the main features of \pkg{ekdosis} follows:---
 % \begin{enumerate}
-% \item \label{it:multicol-feature}\emph{Multilingual critical
+% \item \phts\label{it:multicol-feature}\emph{Multilingual critical
 %   editions\/}: \pkg{ekdosis} can be used to typeset any number of
 %   texts in any direction accepted by \hologo{LuaTeX}. Running
 %   paragraphs of text can be arranged in any number of columns,
@@ -986,7 +999,7 @@ 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 \label{it:multilayer-feature}\emph{Apparatus criticus\/}:
+% \item \phts\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
@@ -1111,7 +1124,7 @@ along with this program.  If not, see
 % \danger The reader is invited to refer to the relevant sections of
 % this documentation for more information on how to use them.
 % 
-% \DescribeOption{layout}\label{ref:layout-opt}
+% \DescribeOption{layout}\phts\label{ref:layout-opt}
 % |layout|$=$\verb+float|footins+\hfill\tcboxverb{Default: float}\\
 % By default, layers of critical notes are inserted as a floating
 % environment to be printed at the bottom of pages. |layout=footins|
@@ -1121,7 +1134,7 @@ along with this program.  If not, see
 % will be inserted between regular numbered footnotes, but will carry
 % no footnote mark of its own.
 %
-% \DescribeOption{divs}\label{ref:divs-opt}
+% \DescribeOption{divs}\phts\label{ref:divs-opt}
 % |divs|$=$\verb+ekdosis|latex+\hfill\tcboxverb{Default: ekdosis}\\
 % In many occasions, \LaTeX{} standard textual divisions do not meet
 % the specific requirements of classical and literary texts, the
@@ -1137,17 +1150,18 @@ along with this program.  If not, see
 % \danger It must be noted that the two styles are mutually exclusive.
 % \vskip\baselineskip
 %
-% \DescribeOption{poetry}\label{ref:poetry-opt}
-% \newfeature[v1.2]
-% |poetry|$=$\verb+verse+
+% \DescribeOption{poetry}\phts\label{ref:poetry-opt}
+% \newfeature[v1.2] |poetry|$=$\verb+verse+
 % \hfill\tcboxverb{Default: not set}\\
 % |poetry=verse| instructs \pkg{ekdosis} to load and use the facilites
-% supplied by the \pkg{verse} package for typesetting lines of
-% poetry. The \env{ekdverse} environment must then be used instead of
+% supplied by the \pkg{verse} package for the typesetting of lines of
+% poetry.\footnote{\texttt{verse} does not need to be set if the
+% \cls{memoir} class is used. See \vref{sec:verse-package} for more
+% detail.} The \env{ekdverse} environment must then be used instead of
 % the \env{verse} environment that is provided by the \pkg{verse}
 % package as described below in \vref{sec:verse-package}.
 %
-% \DescribeOption{parnotes}\label{ref:parnotes-opt}
+% \DescribeOption{parnotes}\phts\label{ref:parnotes-opt}
 % |parnotes|$=$\verb+true|false|roman+%
 % \hfill\tcboxverb{Default: not set}\\
 % This named argument does not need a value as it defaults to |true|
@@ -1157,7 +1171,7 @@ along with this program.  If not, see
 % \pkg{parnotes} package. Additionally, |parnotes=roman| prints these
 % footnotes numbered with Roman numerals.
 %
-% \DescribeOption{teiexport}\label{ref:teiexport-option}
+% \DescribeOption{teiexport}\phts\label{ref:teiexport-option}
 % |teiexport|$=$\verb+true|false|tidy+%
 % \hfill\tcboxverb{Default: not set}\\
 % This named argument does not need a value as it defaults to |true|
@@ -1214,7 +1228,7 @@ along with this program.  If not, see
 % \paragraph{Witnesses}
 % \DescribeMacro{\DeclareWitness} \cs{DeclareWitness}\marg{unique
 % id}\marg{rendition}\marg{description}\oarg{options}
-% \label{ref:declarewitness}\\
+% \phts\label{ref:declarewitness}\\
 % This command requires three mandatory arguments enclosed between
 % curly braces used to specify consecutively:
 % \begin{enumerate}
@@ -1251,7 +1265,7 @@ along with this program.  If not, see
 % \DescribeOption{origDate} |origDate|$=$\meta{date}: Any form of date
 % used to identify the date of origin for the witness.
 %
-% \label{ref:marcianus-b}
+% \phts\label{ref:marcianus-b}
 % To take here one example, a witness such as the \emph{Marcianus
 % Graecus}~269, referred to as manuscript \enquote*{M} in the
 % editions, which contains sixty treatises transmitted under the name
@@ -1358,10 +1372,10 @@ along with this program.  If not, see
 % \iffalse
 %</example>
 % \fi
-% \label{ref:marcianus-e}
+% \phts\label{ref:marcianus-e}
 %
 % \paragraph{Sources}
-% \label{ref:declare-source}
+% \phts\label{ref:declare-source}
 % \DescribeMacro{\DeclareSource} \cs{DeclareSource}\marg{unique
 % label}\marg{rendition}\newfeature[v1.1]\\
 % The \emph{Conspectus Siglorum} that is placed ahead of the edition
@@ -1398,10 +1412,10 @@ along with this program.  If not, see
 % \iffalse
 %</example>
 % \fi
-% \label{sec:declarations-end}
+% \phts\label{sec:declarations-end}
 %
 % \paragraph{Scholars}
-% \label{ref:declare-scholar}
+% \phts\label{ref:declare-scholar}
 % \DescribeMacro{\DeclareScholar}\cs{DeclareScholar}\marg{unique
 % id}\marg{rendition}\oarg{options}\newfeature[v1.1]\\
 % Occasionally, it is necessary to refer to a scholar as a person. For
@@ -1462,7 +1476,7 @@ along with this program.  If not, see
 % is how the two families α  and β could be
 % declared:\footnote{These witnesses are used in the example
 % provided below in \vref{lst:caesar-bg}.}---
-% \label{ref:caesar-bg-sigla}
+% \phts\label{ref:caesar-bg-sigla}
 % \iffalse
 %<*example>
 % \fi
@@ -1593,7 +1607,7 @@ along with this program.  If not, see
 % 
 % \paragraph{Apparatus Entries}
 % \DescribeMacro{\app} \cs{app}|[type=|\meta{type}|]|\marg{apparatus
-% entries}\label{ref:app-cmd}\\
+% entries}\phts\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
@@ -1618,7 +1632,7 @@ yesterday.
 %</example>
 % \fi
 % \cs{app} accepts one further optional argument:---\\
-% \DescribeOption{type} |type|$=$\meta{type}\label{ref:app-type}
+% \DescribeOption{type} |type|$=$\meta{type}\phts\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|
@@ -1646,22 +1660,22 @@ yesterday.
 % \enquote{source} and \enquote{scholar} as defined above
 % \vpageref{sec:terminology}.
 %
-% \paragraph{Lemmata} \label{ref:lemmata}\DescribeMacro{\lem}
+% \paragraph{Lemmata} \phts\label{ref:lemmata}\DescribeMacro{\lem}
 % \cs{lem}\oarg{options}\marg{lemma text}\\
 % As \meta{lemma text} is a word or a phrase judged by the editor to
 % be authentic or authoritative, \cs{lem} prints it by default both in
 % 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. \label{ref:lem-opts-b}The optional argument of \cs{lem}
+% entry. \phts\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}\label{ref:lem-wit}\\
+% witnesses}\phts\label{ref:lem-wit}\\
 % While a single witness may be recorded as in |wit=A|,
 % comma-separated lists of multiple witnesses must obviously be
 % enclosed in curly braces, like so:
-% |wit={A,B,C}|. \label{ref:mss-sep-families}It must be noted that
+% |wit={A,B,C}|. \phts\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}|. Although any unique identifiers or
 % labels used to \enquote{declare} sources and scholars as described
@@ -1670,7 +1684,7 @@ yesterday.
 % recommended to use |sources| and |resp| to refer to either category
 % respectively as described below.\\
 % \DescribeOption{source} |source|$=$\meta{csv list of
-% sources}\label{ref:lem-source}\newfeature[v1.1]\\
+% sources}\phts\label{ref:lem-source}\newfeature[v1.1]\\
 % A \enquote{source} refers to any type of document consulted by the
 % editor to establish the edition text. Most commonly, corrections and
 % emendations from previous editions are cited in the apparatus
@@ -1678,7 +1692,7 @@ yesterday.
 % below in \vref{sec:emendations-conjectures} and
 % \vref{sec:references-cited-works}.}\\
 % \DescribeOption{resp} |resp|$=$\meta{csv list of
-% scholars}\label{ref:lem-resp}\newfeature[v1.1]\\
+% scholars}\phts\label{ref:lem-resp}\newfeature[v1.1]\\
 % |resp| refers to scholars responsible for the emendations,
 % conjectures and corrections that are cited in the apparatus
 % criticus.\footnote{See detailed examples in
@@ -1741,7 +1755,7 @@ yesterday.
 % |prewit| inserts \meta{words} \emph{before} the list of witnesses.\\
 % \DescribeOption{postwit} |postwit|$=$\meta{words}\pointtor{postwit}\\
 % |postwit| inserts \meta{words} \emph{after} the list of witnesses.
-% \label{ref:lem-opts-e}
+% \phts\label{ref:lem-opts-e}
 %
 % \paragraph{Readings} \DescribeMacro{\rdg}
 % \cs{rdg}\oarg{options}\marg{variant reading}\\
@@ -1757,7 +1771,7 @@ yesterday.
 % provided above \vpagerefrange{ref:lem-opts-b}{ref:lem-opts-e} for
 % more detailed information:---\\
 % \DescribeOption{wit} |wit|$=$\meta{csv list of
-% witnesses}\label{ref:rdg-wit}\\
+% witnesses}\phts\label{ref:rdg-wit}\\
 % \DescribeOption{source} |source|$=$\meta{csv list of sources}\\
 % \DescribeOption{resp} |resp|$=$\meta{csv list of scholars}\\
 % \DescribeOption{alt} |alt|$=$\meta{alternate reading}\\
@@ -1775,9 +1789,9 @@ yesterday.
 % \DescribeOption{postwit} |postwit|$=$\meta{words}\\
 %
 % \paragraph{Notes}
-% \DescribeMacro{\note}\label{ref:notes-b}\DescribeMacro{\note*}
+% \DescribeMacro{\note}\phts\label{ref:notes-b}\DescribeMacro{\note*}
 % \cs{note}\oarg{options}\marg{text} or
-% \cs{note*}\oarg{options}\marg{text}\label{ref:editorial-notes}\\
+% \cs{note*}\oarg{options}\marg{text}\phts\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
@@ -1927,7 +1941,7 @@ yesterday.
 % \iffalse
 %</example>
 % \fi
-% \label{ref:notes-e}
+% \phts\label{ref:notes-e}
 %
 % \subsection{Indicating Subvariation in Apparatus Entries}
 % \label{sec:indic-subv-appar}
@@ -2193,7 +2207,7 @@ friend
 %   |prewit=|\texttt{coni.} or |prewit=|\texttt{falso coni.}, to print
 %   explanatory words in the apparatus criticus before the abridged
 %   name of the scholar.
-% \item \label{it:egomute}Conversely, line~9 introduces an
+% \item \phts\label{it:egomute}Conversely, line~9 introduces an
 %   \emph{emendation} for which the shorthand |egoscr| has been used
 %   to print the exact term \emph{scripsi} in the apparatus criticus
 %   while keeping |ego| as an |xml:id| for the \texttt{TEI xml} output
@@ -2519,7 +2533,7 @@ friend
 %
 % \paragraph{The \env{alignment} Environment}
 % \DescribeEnv{alignment} \cs{begin}|{alignment}|\oarg{options}\dots
-% \cs{end}|{alignment}|\label{ref:alignment-syntax}\\
+% \cs{end}|{alignment}|\phts\label{ref:alignment-syntax}\\
 % This environment can be used as it is provided to typeset a standard
 % critical edition, namely an edition text, equipped with an apparatus
 % criticus and laid out on the left-hand pages, accompanied by a
@@ -2555,12 +2569,13 @@ friend
 %</example>
 % \fi
 %
-% \DescribeEnv{edition*}\DescribeEnv{translation*}
-% \label{ref:starred-envs} Furthermore, so-called \enquote{starred}
-% versions of these environments can be used at any point to
-% synchronize texts, that is to print them in such a way that the tops
-% of all paragraphs are vertically aligned. To that effect, it must be
-% noted that merely applying this command on a single
+% \DescribeEnv{edition*}
+% \DescribeEnv{translation*}
+% \phts\label{ref:starred-envs} Furthermore, so-called
+% \enquote{starred} versions of these environments can be used at any
+% point to synchronize texts, that is to print them in such a way that
+% the tops of all paragraphs are vertically aligned. To that effect,
+% it must be noted that merely applying this command on a single
 % environment\---for instance the leftmost one\---will have all other
 % associated paragraphs printed aligned.
 %
@@ -2761,7 +2776,7 @@ friend
 %   \item[\dbend] The colon at the end of line~3 closes the whole
 %     value of |text| and acts as a higher level separator.
 %   \end{enumerate}
-% \item \label{it:lang-subopt} Each name may be followed by a
+% \item \phts\label{it:lang-subopt} Each name may be followed by a
 %   \enquote*{suboptional} argument between square brackets which will
 %   then be used to insert \texttt{TEI xml} attributes in the
 %   corresponding |<div>| element. For example, \iffalse
@@ -3054,9 +3069,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % the apparatus criticus (e.g. sources, testimonia, variant readings
 % \emph{\&c.})
 %
-% \DescribeMacro{\SetHooks}
-% \cs{SetHooks}\marg{csv list of hooks} can be used either in
-% the preamble or at any point of the document. The list of accepted
+% \DescribeMacro{\SetHooks} \cs{SetHooks}\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{command}
 % \hfill\tcboxverb{Default: \footnotesize}\\
@@ -3069,8 +3084,8 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % 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
+% 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{command \textbar\
 % chars}\hfill\tcboxverb{Default: ~}\\
@@ -3091,7 +3106,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % \newfeature[v1.2] |readingstyle| operates in the same way as
 % |lemmastyle| but applies to variant readings.\\
 % \DescribeOption{initialrule} |initialrule|$=$\meta{command}
-% \label{ref:initialrule}\hfill\bgroup\footnotesize
+% \phts\label{ref:initialrule}\hfill\bgroup\footnotesize
 % \tcboxverb{Default: \rule{0.4\columnwidth}{0.4pt} (initially not set)}%
 % \egroup
 % \newfeature[v1.2] |initialrule| draws a separating rule between the
@@ -3102,7 +3117,10 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % \DescribeOption{noinitialrule}\hfill\tcboxverb{Default: not set}\\
 % This is a no-value option. It removes any previously set
 % |initialrule|.
-% 
+%
+% An example of the way these hooks may be used is provided below in
+% \vref{lst:shak-sonnet1}.
+%
 % \subsection{Single-Layer Apparatus Criticus}
 % \label{sec:single-layer-app}
 % \paragraph{Specific Commands}
@@ -3130,13 +3148,12 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % block, while |\SetBeginApparatus{\hskip 1em}| will set an
 % indentation of one em.
 %
-% \DescribeMacro{\SetEndApparatus}
-% \label{ref:setendapparatus}
+% \DescribeMacro{\SetEndApparatus}\phts\label{ref:setendapparatus}
 % \cs{SetEndApparatus}\marg{characters} can be used to append
 % \meta{characters} at the end of the apparatus block. By default,
-% nothing is appended. \label{ref:ending-dot}As an example of use,
-% |\SetEndApparatus{.}| will have a period printed at the end of the
-% apparatus as it is customary in some
+% nothing is appended. \phts\label{ref:ending-dot}As an example of
+% use, |\SetEndApparatus{.}| will have a period printed at the end of
+% the apparatus as it is customary in some
 % editions.\footnote{\label{fn:rm-dots}See also below
 % \vpageref{sec:superfluous-dots} on how to remove superfluous dots.}
 %
@@ -3157,14 +3174,14 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % as in \cs{SetDefaultRule}|{}| removes the line.
 %
 % \DescribeMacro{\SetApparatusLanguage}
-% \label{ref:app-lang}\newfeature[v1.2]
+% \phts\label{ref:app-lang}\newfeature[v1.2]
 % \cs{SetApparatusLanguage}\marg{languagename} can be used when it is
 % needed to apply in the apparatus criticus a language different from
 % the one that is selected in the edition text.
 % 
 % \paragraph{General Command}
 % \DescribeMacro{\SetApparatus} \cs{SetApparatus}\marg{csv list of
-% apparatus settings}\label{ref:apparatus-settings-b}\\
+% apparatus settings}\phts\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:---\\
@@ -3194,9 +3211,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % 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}\\
+% |rule=none|.\phts\label{ref:apparatus-settings-e}\\
 % \DescribeOption{lang} |lang|$=$\meta{languagename}
-% \newfeature[v1.2]\label{ref:app-lang-opt}
+% \newfeature[v1.2]\phts\label{ref:app-lang-opt}
 % \hfill\tcboxverb{Default: not set}\\
 % |lang=<languagename>| is used as described
 % \vpageref[above]{ref:app-lang} when it is needed to apply in the
@@ -3209,7 +3226,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % 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}
+% \phts\label{ex:single-layer-app-layout}
 % \iffalse
 %<*example>
 % \fi
@@ -3252,7 +3269,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{\SetDefaultApparatus}\label{ref:ekd-default-app}
+% \DescribeMacro{\SetDefaultApparatus}\phts\label{ref:ekd-default-app}
 % \cs{SetDefaultApparatus}\marg{name} can be used at any point of the
 % document to change the name to be used as the default one by
 % \pkg{ekdosis}.
@@ -3297,7 +3314,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % \DescribeOption{ehook}
 % \DescribeOption{rule}
 % \DescribeOption{norule}
-% \DescribeOption{lang}\label{ref:apps-lang-opt}
+% \DescribeOption{lang}\phts\label{ref:apps-lang-opt}
 % With regard to layout, any declared layer inherits the default values
 % described above in \vref{sec:single-layer-app}. That said, as the
 % optional argument of \cs{DeclareApparatus} accepts the exact same
@@ -3348,7 +3365,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % \end{remarks}
 %
 % \paragraph{Limiting the Number of Entries per Page}
-% \label{ref:maxentries}
+% \phts\label{ref:maxentries}
 % In some instances, it can be useful to set a limit to the number of
 % entries per page that a given layer of critical notes may accept,
 % notably when entries are so abundant in number that \pkg{ekdosis}
@@ -3754,18 +3771,25 @@ argument of the
 %
 % \subsection[The \textsf{verse} Package]{The \pkg{verse} Package}
 % \label{sec:verse-package}
+% \newfeature[v1.2]
 % \pkg{ekdosis} can use the facilities offered by the excellent
 % \pkg{verse} package\footcite{verse} to which it adds a specific
 % environment for the encoding of line groups such as
 % stanzas. Furthermore, as the \pkg{verse} package provides its own
 % numbering mechanism, the lines can be numbered independently of
-% prose text.
+% prose text.\footnote{See \vpageref{ref:verse-lineation} for
+% details.}
 %
 % \danger For what is described in this section to operate,
 % \pkg{ekdosis} must be loaded with the global option |poetry=verse|
 % as explained above \vpageref{ref:poetry-opt}. Simply loading the
 % \pkg{verse} package by means of \cs{usepackage} will have no effect.
 %
+% \danger The foregoing does not apply if the \cls{memoir} class is
+% used.\footcite{memoir} In this case, \pkg{ekdosis} automatically
+% uses the code provided by this class without the need to set
+% the global option |poetry=verse|.
+%
 % \paragraph{Compatible Verse Commands}
 % The reader is invited to refer to the documentation of the
 % \env{verse} package for detailed information.  Within the
@@ -3787,13 +3811,14 @@ argument of the
 % specified is added between lines, whereas |\\>[...]| adds an
 % horizontal space after the line break.
 %
-% \DescribeMacro{\vin} \cs{vin} indents a verse line by a length which
-% is by default \unit[1.5]{em}. This length is stored as \cs{vgap} and
-% can be changed by \cs{setlength} or \cs{addtolength}.
+% \DescribeMacro{\vin} \phts\label{ref:verse-vin}\cs{vin} indents a
+% verse line by a length which is by default \unit[1.5]{em}. This
+% length is stored as \cs{vgap} and can be changed by \cs{setlength}
+% or \cs{addtolength}.
 %
 % \paragraph{The \env{ekdverse} Environment}
 % \DescribeEnv{ekdverse} \cs{begin}|{ekdverse}|\oarg{options} \dots\
-% \cs{end}|{ekdverse}|\label{ref:ekdverse-syntax}\newfeature[v1.2]\\
+% \cs{end}|{ekdverse}|\phts\label{ref:ekdverse-syntax}\\
 % This environment is used to hold verse lines as described above and
 % may receive an optional argument in which the following
 % \enquote{name$=$value} arguments are accepted:---\\
@@ -3818,15 +3843,20 @@ argument of the
 % \fi %
 % \begin{remarks}
 % \item[\textsc{Rem.}] \cs{versewidth} is provided by the \env{verse}
-% package as a convenience and can be used by \env{ekdosis}.
+%   package as a convenience and can be used by \env{ekdosis}.
 % \end{remarks}
-% \DescribeOption{type} |width|$=$\meta{type}
+% \DescribeOption{type} |type|$=$\meta{type}
 % \hfill\tcboxverb{Default: not set}\\
 % This named argument is used in the \texttt{TEI xml} output to
 % name the type of unit encoded within the |<lg>| element, viz.\
 % \enquote{sonnet}, \enquote{quatrain}, \enquote{couplet} and the
 % like.
 %
+% \danger Unlike the \texttt{TEI xml} element |<lg>|, \env{ekdverse}
+% may not nest hiearchichally. Within this environment,
+% \env{ekdstanza} must be used instead to encode stanzas as described
+% \vpageref[below][below]{ref:ekdstanza}.
+%
 % As an example, the first five lines of Homer's \emph{Odyssey} could
 % be encoded like so:\footcite{HomerMurray}---
 % 
@@ -3933,6 +3963,208 @@ argument of the
 %</example>
 % \fi
 %
+% \paragraph{Stanzas}
+% As can be seen above, the \LaTeX\ \env{ekdverse} environment is
+% translated into the \texttt{TEI xml} |<lg>| element. The |type|
+% attribute may then be used to name the type of unit encoded by this
+% element.
+%
+% \DescribeEnv{ekdstanza} \cs{begin}|{ekdstanza}|\oarg{options} \dots\
+% \cs{end}|{ekdstanza}| \phts\label{ref:ekdstanza}\\
+% This environment is used within \env{ekdverse} to encode succeeding
+% stanzaic forms. Within \env{ekdstanza}, the last line is ended by
+% |\\!| or |\\| depending on whether an additional vertical space is
+% required between stanzas. This environment may receive an optional
+% argument in which the following \enquote{name$=$value} argument is
+% accepted:---\\
+% \DescribeOption{type} |type|$=$\meta{type}
+% \hfill\tcboxverb{Default: not set}\\
+% As in the case of \env{ekdverse}, this named argument is used in the
+% \texttt{TEI xml} output to name the type of unit encoded within the
+% |<lg>| element, viz.\ \enquote{quatrain}, \enquote{couplet} and the
+% like.
+%
+% \paragraph{Indentation Patterns}
+% \pkg{ekdosis} can use the \env{patverse} environment and its
+% associated command \cs{indentpattern} that are provided by the
+% \pkg{verse} package. As described in the documentation of this
+% package,\footcite[6]{verse} the indentation pattern consists of an
+% array of digits, \emph{d\textsubscript{1}} to
+% \emph{d\textsubscript{n}}, where the \emph{n\textsuperscript{th}}
+% line is indented by \emph{d\textsubscript{n}} times the amount of
+% \cs{vgap} described above \vpageref{ref:verse-vin}.
+%
+% The overall structure of lines grouped into stanzas may look as
+% follows:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[escapeinside=++]{latex}
+\begin{ekdverse}[type={+\emph{overall type}+}]
+  \identpattern{+\emph{digits}+}
+  \begin{patverse}
+    \begin{ekdstanza}[type={+\emph{stanza 1 type}+}]
+      line 1 \\
+      line 2 \\
+      [...]
+      final line \\!
+    \end{ekdstanza}
+  \end{patverse}
+\end{ekdverse}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% Of course, if no indentation pattern be required or be only required
+% occasionally, \env{patverse} (ll.~3 and 10) and \cs{indentpattern}
+% (l.~2) are of no use:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[escapeinside=++]{latex}
+\begin{ekdverse}[type={+\emph{overall type}+}]
+  \begin{ekdstanza}[type={+\emph{stanza 1 type}+}]
+    line 1 \\
+    line 2 \\
+    \vin indented line 3 \\
+    [...]
+    final line \\!
+  \end{ekdstanza}
+\end{ekdverse}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% A detailed example follows. It is taken from
+% \citename{McDonald1916}{editor}'s edition of Shakespeare's
+% \emph{Sonnets} from the Quarto of 1609 with variorum
+% readings.\footcite[Sonnet~1, \pno~15]{McDonald1916} Compared to
+% \citename{McDonald1916}{shorteditor}'s edition, an effort has been
+% made to use the typography and punctuation of the original edition
+% which can be consulted online at the British Library's
+% website.\footnote{Shake-speares \emph{Sonnets}. Neuer before
+% Imprinted. (A Louers Complaint. By William
+% Shake-speare.). \url{https://www.bl.uk/collection-items/first-edition-of-shakespeares-sonnets-1609}.
+% Call number \texttt{C.21.c.44}, fol.~B.} However, this typographical
+% refinement has been retained for the sonnet only. For the sake of
+% clarity, the line numbers and the apparatus criticus use modern
+% typography. The references to line numbers in the apparatus criticus
+% have been made consistent with
+% \citename{McDonald1916}{shorteditor}'s edition, as have the entries
+% in the apparatus criticus, namely the bare line number followed by a
+% dot, then the lemma text in bold face, then the variant in italic
+% shape:---
+%
+% \captof{Poetry: Shakespeare's Sonnet~1}[\label{lst:shak-sonnet1}]
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+\junicode % Use the Junicode font with 'hist' feature enabled for
+          % long-s
+% MacDonald's style for numbers and entries in the apparatus
+% criticus:
+\SetHooks{
+  refnumstyle=\normalfont,
+  postrefnum=.~,
+  lemmastyle=\bfseries,
+  readingstyle=\itshape
+}
+% The lines are to be centered horizontally:
+\settowidth{\versewidth}{Feed'st thy lights flame with selfe
+substantiall fewell,}
+% Format of the outermost <div> element:
+\NewDocumentEnvironment{ekdcenter}{}{\par\centering}{\nobreak\par}
+\FormatDiv{1}{\begin{ekdcenter}}{\end{ekdcenter}}
+\begin{ekdosis}
+  \ekddiv{type=sonnets, n=1, head=1}
+  \begin{ekdverse}[type=sonnet, width=\versewidth]
+    \indentpattern{00000000000011}
+    \begin{patverse}
+      \begin{ekdstanza}[type=quatrain]
+        \ekdlettrine{F}{r}om fairest creatures we desire
+        increase,\\
+        That thereby beauties \emph{Rose}
+        \app{
+          \lem{might}
+          \rdg[source={Gildon1710, Sewell1725, Ewing1771}]{may}
+        } neuer die,\\
+        But as the riper should by time
+        \app{
+          \lem{decease}
+          \rdg[source=Hudson1856]{decrease}
+        },\\
+        His tender heire might beare his memory:\\
+      \end{ekdstanza}
+      \begin{ekdstanza}[type=quatrain]
+        But thou contracted to thine owne bright eyes,\\
+        Feed'st thy
+        \app{
+          \lem{lights}
+          \rdg[source={Butler1899, Walsh1908}]{life's}
+        } flame with
+        \app{
+          \lem{selfe substantiall}
+          \rdg[source=Gildon1714,
+          alt={\textnormal{Hyphened by}}]{selfe-substantiall}
+          \note{etc.}} fewell,\\
+        Making a famine where aboundance lies,\\
+        Thy selfe thy foe,to thy sweet selfe too cruell:\\
+      \end{ekdstanza}
+      \begin{ekdstanza}[type=quatrain]
+        Thou that art now the worlds fresh ornament,\\
+        And
+        \app{
+          \lem{only}
+          \rdg[resp=God, type=conjecture]{early}
+          \note{conj.}
+        } herauld to the gaudy spring,\\
+        Within thine owne bud buriest thy content,\\
+        And tender
+        \app{
+          \lem{chorle}
+          \rdg[source=Gildon1710]{churl}
+          \note{etc.}
+        } makst wast in niggarding:\\
+      \end{ekdstanza}
+      \begin{ekdstanza}[type=couplet]
+        Pitty the world,or else this glutton be,\\
+        To eate the worlds due,\app{
+          \lem{by the}
+          \rdg[resp=Stee, type=conjecture]{be thy}
+          \note{conj.}
+          \rdg[resp=God, type=conjecture]{by thy}
+          \note{conj.}
+        } graue
+        \app{
+          \lem{and}
+          \rdg[resp=God, type=conjecture]{as}
+          \note{conj.}
+        } thee.\\!
+      \end{ekdstanza}
+    \end{patverse}
+  \end{ekdverse}
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+% 
+% \begin{remarks}
+% \item[\textsc{Rem.}] \cs{ekdlettrine} (l.~23) is a specific command
+% for the \pkg{lettrine} package does not work in list
+% environments. \cs{TeXtoTEIPat} has been used as described below
+% \vpageref{ref:textoteipat} to instruct \pkg{ekdosis} to convert this
+% command into an acceptable \texttt{TEI} equivalent.
+% \end{remarks}
+%
+% PDF output:---
+% \medskip
+%
 % \begingroup
 % \junicode
 % \SetHooks{
@@ -4024,7 +4256,90 @@ argument of the
 % \end{alignment}
 % \endgroup
 %
-% \url{https://www.bl.uk/collection-items/first-edition-of-shakespeares-sonnets-1609}
+% \texttt{TEI xml} output:---
+% \medskip
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<div type="sonnets" n="1">
+  <head>1</head>
+  <lg type="sonnet">
+    <lg type="quatrain">
+      <l>
+      <hi rend="smallcaps">Fr</hi>om fairest creatures we
+      desire increase,</l>
+      <l>That thereby beauties 
+      <emph>Rose</emph>
+      <app>
+        <lem>might</lem>
+        <rdg source="#Gildon1710 #Sewell1725 #Ewing1771">
+        may</rdg>
+      </app>neuer die,</l>
+      <l>But as the riper should by time 
+      <app>
+        <lem>decease</lem>
+        <rdg source="#Hudson1856">decrease</rdg>
+      </app>,</l>
+      <l>His tender heire might beare his memory:</l>
+    </lg>
+    <lg type="quatrain">
+      <l>But thou contracted to thine owne bright eyes,</l>
+      <l>Feed'st thy 
+      <app>
+        <lem>lights</lem>
+        <rdg source="#Butler1899 #Walsh1908">
+        life's</rdg>
+      </app>flame with 
+      <app>
+        <lem>selfe substantiall</lem>
+        <rdg source="#Gildon1714">
+        selfe-substantiall</rdg>
+        <note>etc.</note>
+      </app>fewell,</l>
+      <l>Making a famine where aboundance lies,</l>
+      <l>Thy selfe thy foe,to thy sweet selfe too
+      cruell:</l>
+    </lg>
+    <lg type="quatrain">
+      <l>Thou that art now the worlds fresh ornament,</l>
+      <l>And 
+      <app>
+        <lem>only</lem>
+        <rdg resp="#God" type="conjecture">early</rdg>
+        <note>conj.</note>
+      </app>herauld to the gaudy spring,</l>
+      <l>Within thine owne bud buriest thy content,</l>
+      <l>And tender 
+      <app>
+        <lem>chorle</lem>
+        <rdg source="#Gildon1710">churl</rdg>
+        <note>etc.</note>
+      </app>makst wast in niggarding:</l>
+    </lg>
+    <lg type="couplet">
+      <l>Pitty the world,or else this glutton be,</l>
+      <l>To eate the worlds due,
+      <app>
+        <lem>by the</lem>
+        <rdg resp="#Stee" type="conjecture">be thy</rdg>
+        <note>conj.</note>
+        <rdg resp="#God" type="conjecture">by thy</rdg>
+        <note>conj.</note>
+      </app>graue 
+      <app>
+        <lem>and</lem>
+        <rdg resp="#God" type="conjecture">as</rdg>
+        <note>conj.</note>
+      </app>thee.</l>
+    </lg>
+  </lg>
+</div>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
 %
 % \section{Lineation Settings}
 % \label{sec:lineation}
@@ -4044,6 +4359,7 @@ argument of the
 % options} may be used in the preamble or at any point of the document
 % to set lineation preferences. Its argument processes the |key=value|
 % options that follow:---\\
+% \textbf{General Options}\\
 % \DescribeOption{lineation} |lineation|$=$\verb+page|document+
 % \hfill\tcboxverb{Default: document}\\
 % |lineation=document| has the lines numbered continuously throughout
@@ -4069,14 +4385,36 @@ argument of the
 % elides the last number of a range to the fewest number of figures
 % possible\---viz. 35--7, 129--31 \emph{\&c.}\---without eliding
 % digits in the group 10 to 19 in each hundred\---viz. 17--19, 115--18
-% \emph{\&c.} |numbers=full| leaves the numbers untouched.
-%
+% \emph{\&c.} |numbers=full| leaves the numbers untouched.\\
 % \DescribeMacro{\innerlinenumbers} \DescribeMacro{\outerlinenumbers}
 % \cs{innerlinenumbers} and \cs{outerlinenumbers} are equivalent to
 % \cs{SetLineation}|{numb|\allowbreak|ers=outer}| and
 % \cs{SetLineation}|{numbers=inner}| respectively. Both commands are
 % complementary to \cs{rightlinenumbers} and \cs{leftlinenumbers}
-% already provided by the \pkg{lineno} package.
+% already provided by the \pkg{lineno} package.\\
+% \textbf{Options Specific to the |poetry=verse| Global
+% Setting}\footnote{See above
+% \vref{sec:verse-package}.}\phts\label{ref:verse-lineation}\\
+% \DescribeOption{vlineation} |vlineation|$=$\verb+page|document+
+% \hfill\tcboxverb{Default: document}\\
+% |vlineation| operates on verse texts in the same way as |lineation|
+% on prose texts.\\
+% \DescribeOption{vmodulo} |vmodulo|$=$\emph{n} (where \emph{n} is
+% an integer)\hfill\tcboxverb{Initially: 1, Default: 5}\\
+% |vmodulo|$=$\emph{n} has every \emph{n\textsuperscript{th}} lines of
+% verse printed in the margin. If used without value, this option is
+% equivalent to |vmodulo=5|. |vmodulo=0| prevents the
+% numbers from being printed.\\
+% \DescribeOption{vmargin} |vmargin|$=$\verb+right|left+
+% \hfill\tcboxverb{Initially: right}\\
+% |vmargin| sets the margin in which the verse line numbers are to be
+% printed.\\
+% \DescribeOption{continuousvnum}\hfill\tcboxverb{Default: not set}\\
+% The |poetry=verse| global option has the succeeding lines of verse
+% numbered independently of prose text. |continuousvnum| has all lines
+% numbered continuously, irrespective of whether they are lines of
+% prose or poetry text.
+%
 %
 % \paragraph{Useful Lineation Commands}
 % As implied above, pretty much all commands that are provided by the
@@ -4094,13 +4432,32 @@ argument of the
 % \DescribeMacro{\linenumbersep} \cs{linenumbersep} is the distance
 % between the numbers and the margin. By default, this distance is set
 % to \unit[10]{pt}. It can be redefined like so:
-% \cs{setlength}\cs{linenumbersep}\marg{length}.\\
-% \DescribeMacro{\linelabel} \DescribeMacro{\lineref}
-% \cs{linelabel}\marg{label} sets a line label that can be referred to
-% with \cs{lineref}\marg{label}.
+% \cs{setlength}\cs{linenumbersep}\marg{length}.
+%
+% \paragraph{Poetry Lineation Commands}
+% In addition to these commands, if \pkg{ekdosis} be loaded with the
+% global option |poetry=verse| as described above in
+% \vref{sec:verse-package}, the commands dedicated to line numbering
+% that are provided by the \pkg{verse} package can be used.\\
+% \DescribeMacro{\resetvlinenumber} \cs{resetvlinenumber}\oarg{n} has
+% for lines of verse the same effect as \cs{resetlinenumber} for
+% lines of prose text.\\
+% \DescribeMacro{\verselinenumfont}
+% \cs{verselinenumfont}\marg{commands} can be used to set the font
+% used for lines of verse. By default, the definition is
+% |\normalfont\footnotesize|. \danger If the \cls{memoir} class be
+% loaded, this command is replaced with \cs{linenumberfont} described
+% above.\\
+% \DescribeMacro{\vrightskip} The \pkg{verse} package prints the
+% numbers at the distance \cs{vrightskip} into the right margin. This
+% distance can be redefined by means of \cs{setlength} like so:
+% \cs{setlength}\cs{vrightskip}\allowbreak\marg{length}.
 %
-% The reader is invited to refer to the documentation of the
-% \pkg{lineno} package for more information.
+%
+% \paragraph{Labels}
+% \DescribeMacro{\linelabel} \DescribeMacro{\ref} In prose as well
+% as in poetry texts, \cs{linelabel}\marg{label} sets a line label
+% that can be referred to with \cs{ref}\marg{label}.
 %
 % As an example, what follows has every fifth line number printed in
 % the inner margins. Additionally, the numbering shall start afresh at
@@ -4876,7 +5233,7 @@ subtype="arabtex">'inna 'abI kAna mina
 % circumstantially arise.
 %
 % \paragraph{Superfluous Dots}
-% \label{sec:superfluous-dots}
+% \phts\label{sec:superfluous-dots}
 % As said above \vpageref{ref:ending-dot}, it is customary in some
 % editions to have a full stop printed at the end of the apparatus
 % criticus. \pkg{ekdosis} provides specific commands to achieve this
@@ -5437,6 +5794,7 @@ many mathematical writings and to the sense of
 % \fi
 %
 % \DescribeMacro{\TeXtoTEIPat}
+% \phts\label{ref:textoteipat}
 % \cs{TeXtoTEIPat}\marg{\TeX\ pattern}\marg{TEI pattern}\\
 % Finally, this more flexible\---and more delicate to
 % handle\---command uses pattern matching to instruct \pkg{ekdosis}
@@ -5676,7 +6034,7 @@ Sample text with a \textcolor{red}{word} in red.
 %</example>
 % \fi
 %
-% \label{ref:ekdverse-ex}
+% \phts\label{ref:ekdverse-ex}
 % Finally, an extract of Silius Italicus' \emph{Punica}, Book~9,
 % ll.~30-2 follows (|.tex| source file, PDF output and \texttt{TEI}
 % output files):---
@@ -7413,8 +7771,8 @@ Sample text with a \textcolor{red}{word} in red.
 % addition to \cs{rightlinenum{\allowbreak}bers} and
 % \cs{leftlinenumbers}.
 %    \begin{macrocode}
-\def\outerlinenumbers{
-  \def\makeLineNumberRunning{
+\def\outerlinenumbers{%
+  \def\makeLineNumberRunning{%
     \checkoddpage
     \ifoddpage
     \linenumberfont\hskip\linenumbersep\hskip\textwidth
@@ -7422,10 +7780,10 @@ Sample text with a \textcolor{red}{word} in red.
     \else
     \hss\linenumberfont\LineNumber\hskip\linenumbersep
     \fi
-  }
+  }%
 }
-\def\innerlinenumbers{
-  \def\makeLineNumberRunning{
+\def\innerlinenumbers{%
+  \def\makeLineNumberRunning{%
     \checkoddpage
     \ifoddpage
     \hss\linenumberfont\LineNumber\hskip\linenumbersep
@@ -7433,7 +7791,7 @@ Sample text with a \textcolor{red}{word} in red.
     \linenumberfont\hskip\linenumbersep\hskip\textwidth
     \hbox to\linenumberwidth{\hss\LineNumber}\hss
     \fi
-  }
+  }%
 }
 %    \end{macrocode}
 % \end{macro}
@@ -7476,7 +7834,12 @@ Sample text with a \textcolor{red}{word} in red.
     outer = \outerlinenumbers},
   unknown-choice margin = \PackageError{ekdosis}{unknown
     margin=#1}{`margin' must be either `left', `right', \MessageBreak
-    `inner' or `outer'}
+    `inner' or `outer'},
+  choice vmargin = {
+    right = \if@pkg@poetry@verse\verselinenumbersright\fi,
+    left = \if@pkg@poetry@verse\verselinenumbersleft\fi},
+  unknown-choice vmargin = \PackageError{ekdosis}{unknown
+    vmargin=#1}{`margin' must be either `left' ot `right'}
 }
 %    \end{macrocode}
 % \begin{macro}{\SetLineation}
@@ -9301,8 +9664,8 @@ end
 local function versetotei(str)
    str = string.gsub(str, "\\begin%s?%{ekdverse%}(%b[])(.-)\\end%s?%{ekdverse%}", function(opt, arg)
 			arg = string.gsub(arg, "\\par%s?", "")
-			arg = string.gsub(arg, "\\begin%s?%{patverse%}", "")
-			arg = string.gsub(arg, "\\end%s?%{patverse%}", "")
+			arg = string.gsub(arg, "\\begin%s?%{patverse%*?%}", "")
+			arg = string.gsub(arg, "\\end%s?%{patverse%*?%}", "")
 			arg = string.gsub(arg, "\\indentpattern%s?%b{}", "")
 			opt = string.sub(opt, 2, -2)
 			teitype = get_attr_value(opt, "type")
-- 
cgit v1.2.3