1 files changed, 128 insertions, 19 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index bb02250..c27eab2 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -1138,13 +1138,14 @@ along with this program.  If not, see
 % \vskip\baselineskip
 %
 % \DescribeOption{poetry}\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
 % the \env{verse} environment that is provided by the \pkg{verse}
-% package as described below in \vref{sec:poetry}.
+% package as described below in \vref{sec:verse-package}.
 %
 % \DescribeOption{parnotes}\label{ref:parnotes-opt}
 % |parnotes|$=$\verb+true|false|roman+%
@@ -3657,19 +3658,31 @@ argument of the
 %
 % \section{Poetry}
 % \label{sec:poetry}
+% \subsection[The Standard \textsf{verse} Environment]{The Standard
+% \env{verse} Environment}
+% \label{sec:stand-verse-env}
+%
 % For typesetting verse texts or poems, \LaTeX\ provides the standard
-% \env{verse} environment. Usually, within this environment, |\\| is
-% used to end lines, with the exception of the last line. Likewise,
-% stanzas are separated from one another by a blank line. However,
-% \pkg{ekdosis} deviates a little from this usage for it needs all
-% lines of poetry to be ended by |\\| as a distinct marker, like
-% so:---
+% \env{verse} environment. Within this environment, |\\| is normally
+% used to end lines, with the exception of the last line. As a result,
+% stanzas are separated from one another by a blank line.
+%
+% \pkg{ekdosis} provides \env{ekdverse} which is recommended for use
+% in place of the standard \env{verse} environment. By default,
+% \env{ekdverse} produces the same result as \env{verse}.  However,
+% \pkg{ekdosis} deviates a little from the standard usage for it needs
+% all lines of poetry to be ended by |\\| as a distinct marker. In the
+% following listing, stanzas are visually separated from one another
+% by an additional vertical space of \unit[2]{ex} (l.~5). Between
+% stanzas, |%| is used to prevent \TeX\ from
+% introducing a blank line. But a blank line\===or even no blank
+% line\===would produce the exact same result:---
 % 
 % \iffalse
 %<*example>
 % \fi
 \begin{minted}{latex}
-\begin{verse}
+\begin{ekdverse}
   It is an ancient Mariner,\\
   And he stoppeth one of three.\\
   ‘By thy long grey beard and glittering eye,\\
@@ -3678,16 +3691,68 @@ argument of the
   The Bridegroom's doors are opened wide,\\
   And I am next of kin;\\
   The guests are met, the feast is set:\\
-  May'st hear the merry din.’
-\end{verse}
+  May'st hear the merry din.’\\
+\end{ekdverse}
 \end{minted}
 % \iffalse
 %</example>
 % \fi
 %
-% As can be seen, stanzas are visually separated from one another by
-% an additional vertical space of \unit[2]{ex} (l.~5), while the
-% subsequent line is rendered inert.
+% PDF output:---
+% \medskip
+% \begingroup
+% \needspace{7\baselineskip}
+% \resetlinenumber\resetvlinenumber
+% \poemlines{0}
+% \begin{alignment}[flush,tcols=1,texts=coleridge,apparatus=coleridge]
+%   \begin{coleridge}
+%     \begin{verse}
+%       It is an ancient Mariner,\\
+%       And he stoppeth one of three.\\
+%       ‘By thy long grey beard and glittering eye,\\
+%       Now wherefore stopp'st thou me?\\[2ex]
+%
+%       The Bridegroom's doors are opened wide,\\
+%       And I am next of kin;\\
+%       The guests are met, the feast is set:\\
+%       May'st hear the merry din.’\\
+%     \end{verse}
+%   \end{coleridge}
+% \end{alignment}
+% \endgroup
+% \medskip
+% 
+% \indent\texttt{TEI xml} output:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<lg>
+  <l>It is an ancient Mariner,</l>
+  <l>And he stoppeth one of three.</l>
+  <l>‘By thy long grey beard and glittering eye,</l>
+  <l>Now wherefore stopp'st thou me?</l>
+  <l>The Bridegroom's doors are opened wide,</l>
+  <l>And I am next of kin;</l>
+  <l>The guests are met, the feast is set:</l>
+  <l>May'st hear the merry din.’</l>
+</lg>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% One would have expected here the |<lg>| element to be used as
+% delimiter to encode the stanzaic verse forms. But as can be seen,
+% only the outermost level of line group has been converted into
+% \texttt{TEI xml}, let alone the vertical spacing between stanzas
+% which has been ignored.  This is because it is about as much as the
+% standard \env{verse} environment provides.
+%
+% \subsection[The \textsf{verse} Package]{The \pkg{verse} Package}
+% \label{sec:verse-package}
+% 
 %
 % \begingroup
 % \setcolumnwidth{0.6\textwidth}
@@ -7224,6 +7289,7 @@ Sample text with a \textcolor{red}{word} in red.
 % numbering should start afresh at the top of each page.
 %    \begin{macrocode}
 \newif\ifekd@pagelineation
+\newif\ifekd@pagevlineation
 \NewDocumentCommand{\ekdatbegshihook}{}{%
   \ifekd@pagelineation\resetlinenumber\fi
 }
@@ -7234,6 +7300,10 @@ Sample text with a \textcolor{red}{word} in red.
     document = \ekd@pagelineationfalse},
   unknown-choice lineation = \PackageError{ekdosis}{unknown
     lineation=#1}{`lineation' must be either `page' or `document'.},
+  choice vlineation = {page = \ekd@pagevlineationtrue,
+    document = \ekd@pagevlineationfalse},
+  unknown-choice vlineation = \PackageError{ekdosis}{unknown
+    vlineation=#1}{`vlineation' must be either `page' or `document'.},
   code modulonum = \chardef\c@linenumbermodulo#1\relax,
   noval modulo = \modulolinenumbers,
   code vmodulo = \if@pkg@poetry@verse\poemlines{#1}\fi,
@@ -8256,13 +8326,46 @@ Sample text with a \textcolor{red}{word} in red.
 }
 %    \end{macrocode}
 % \end{macro}
+% \paragraph{Poetry Settings}
 % \begin{environment}{ekdverse}
 %   \env{ekdverse} provides an implementation of poetry lines. It is
 %   set to use either the \pkg{lineno} or the \pkg{verse} package
 %   depending on the value that is passed to the global option
-%   |verse|:---
+%   |poetry|.
+% \begin{macro}{\test@vpnum}
+% \cs{test@vpnum} is used internally when |ekdosis| needs to know
+% whether two subsequent lines are printed on the same page or not.
+%    \begin{macrocode}
+\newif\ifekd@test@vpnum
+\newcounter{ekd@vpnum}
+\globalcounter{ekd@vpnum}
+\NewDocumentCommand{\test@vpnum}{}{%
+  \ifekd@test@vpnum
+    \edef\@tempa{\theekd@vpnum}%
+    \stepcounter{ekd@vpnum}%
+    \label{vpnum:\theekd@vpnum}%
+    \ifnum
+      \pdf@strcmp{\getpagerefnumber{vpnum:\@tempa}}%
+        {\getpagerefnumber{vpnum:\theekd@vpnum}}
+        = 0
+      \else
+        \resetvlinenumber
+    \fi
+  \else
+  \label{vpnum:\theekd@vpnum}%
+  \global\ekd@test@vpnumtrue
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+% A small patch is applied to the \pkg{verse} package, then
+% \env{ekdverse} is defined:---
 %    \begin{macrocode}
 \if@pkg@poetry@verse
+\patchcmd{\start@vsline}{%
+  \ifaltindent}{%
+  \ifekd@pagevlineation\test@vpnum\fi
+  \ifaltindent}{}{}
 \ekvdefinekeys{ekd@verse}{
   dimen width = \vwidth@val,
   initial width = \linewidth,
@@ -8295,10 +8398,13 @@ Sample text with a \textcolor{red}{word} in red.
             \rightmargin        \leftmargin
           \fi
           \addtolength{\leftmargin}{\vindent}}%
-  \item[]%
+  \item[]\ifekd@pagevlineation\test@vpnum\fi%
 }
 {\endlist
-\if@continuous@vnum\resetlinenumber[\thepoemline]\fi}
+  \if@continuous@vnum\resetlinenumber[\thepoemline]\fi}
+%    \end{macrocode}
+% Finally, this is the standard \env{verse} environment:---
+%    \begin{macrocode}
 \else
 \newlength{\ekdverseindentlength}
 \setlength{\ekdverseindentlength}{\parindent}
@@ -8317,8 +8423,8 @@ Sample text with a \textcolor{red}{word} in red.
 % \begin{macro}{\resetvlinenumber}
 % \changes{v1.2}{2021/03/06}{resets line numbers in poetry environments}
 % This command is the equivalent of \cs{resetlinenumber} for lines of
-% poetry. It takes an integer (which is |1| by default) as optional
-% argument. 
+% poetry. It takes an integer as optional argument, which is |1| by
+% default.
 %    \begin{macrocode}
 \NewDocumentCommand{\resetvlinenumber}{O{1}}{%
   \if@pkg@poetry@verse
@@ -8329,6 +8435,9 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \begin{environment}{ekdstanza}
 %   \changes{v1.2}{2021/03/08}{new environment for stanzas}
+%   \env{ekdstanza} is needed when lines are grouped into stanzas,
+%   which can be further named by means of the |type| optional
+%   argument:---
 %    \begin{macrocode}
 \ekvdefinekeys{ekd@stanza}{
   code type = \def\type@value{#1}
@@ -8994,7 +9103,7 @@ local function linestotei(str)
       str = "\n<l>"..str
    end
    str = gsub(str, poemline * spcenc^0 * bclinegroup, "</l>\n%2")
-   str = gsub(str, linegroup * -(spcenc^0 * bclinegroup), "%1\n<l>a")
+   str = gsub(str, linegroup * -(spcenc^0 * bclinegroup), "%1\n<l>")
    str = gsub(str, lpeg.Cs("</lg>") * -(spcenc^0 * (bclinegroup + -1)), "%1\n<l>")
    -- str = gsub(str, poemline * spcenc^-1 * -1, "</l>\n")
    str = gsub(str, poemlinebreak, "<lb/> ")