done documenting subvariation

1 files changed, 91 insertions, 18 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 7531487..bdc87a5 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -1442,7 +1442,7 @@ yesterday.
 % \enquote{source} and \enquote{scholar} as defined above
 % \vpageref{sec:terminology}.
 %
-% \paragraph{Lemmata} \DescribeMacro{\lem}
+% \paragraph{Lemmata} \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
@@ -1571,7 +1571,7 @@ yesterday.
 % \DescribeOption{postwit} |postwit|$=$\meta{words}\\
 %
 % \paragraph{Notes}
-% \DescribeMacro{\note}\DescribeMacro{\note*}
+% \DescribeMacro{\note}\label{ref:notes-b}\DescribeMacro{\note*}
 % \cs{note}\oarg{options}\marg{text} or
 % \cs{note*}\oarg{options}\marg{text}\label{ref:editorial-notes}\\
 % It may happen that editorial notes be needed to record short
@@ -1723,6 +1723,7 @@ yesterday.
 % \iffalse
 %</example>
 % \fi
+% \label{ref:notes-e}
 %
 % \subsection{Indicating Subvariation in Apparatus Entries}
 % \label{sec:indic-subv-appar}
@@ -1735,8 +1736,8 @@ yesterday.
 % apparatus. \pkg{ekdosis} provides two ways of expressing
 % subvariation.
 %
-% \subsubsection{Implicit Grouping by Nesting Entries}
-% \label{sec:impl-group-nest}
+% \subsubsection{Implicit Grouping}
+% \label{sec:implicit-grouping}
 % Because apparatus entries may nest recursively, the \cs{app} command
 % may be used to group similar readings.
 %
@@ -1754,10 +1755,11 @@ As I was walking home through Times Square, I saw my friend
   \lem[wit={A,B}, alt={Peter\---yesterday}]{Peter at the
     \app{
       \lem[wit=A, alt=station]{station}
-      \rdg[wit=B, alt=pub]{bookstore}}
+      \rdg[wit=B, alt=bookstore]{bookstore}
+    }
     yesterday}
-  \rdg[wit=C, alt={John at the bookstore this evening}]{John at the
-    bookstore this evening}}.
+  \rdg[wit=C, alt={John this evening}]{John this evening}
+}.
 \end{minted}
 % \iffalse
 %</example>
@@ -1775,10 +1777,9 @@ As I was walking home through Times Square, I saw my friend
 %      \lem[wit={pjA,pjB}, alt={Peter\---yesterday}]{Peter at the
 %        \app{
 %          \lem[wit=pjA, alt=station]{station}
-%          \rdg[wit=pjB, alt=pub]{bookstore}}
+%          \rdg[wit=pjB, alt=bookstore]{bookstore}}
 %        yesterday}
-%      \rdg[wit=pjC, alt={John at the bookstore this evening}]{John at
-%      the bookstore this evening}}.
+%      \rdg[wit=pjC, alt={John this evening}]{John this evening}}.
 %   \end{specimen}
 % \end{alignment}
 %
@@ -1796,12 +1797,90 @@ friend
     <lem wit="#A">station</lem>
     <rdg wit="#B">bookstore</rdg>
   </app>yesterday</lem>
-  <rdg wit="#C">John at the bookstore this evening</rdg>
+  <rdg wit="#C">John this evening</rdg>
+</app>.</p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \subsubsection{Explicit Grouping}
+% \label{sec:explicit-grouping}
+% \DescribeMacro{\rdgGrp} \cs{rdgGrp}\oarg{options}\marg{lemma text
+% \textbar\ readings}\newfeature[v1.1]\\
+% Explicit grouping of readings can be achieved by means of the
+% \cs{rdgGrp} command. It takes as mandatory argument the commands
+% used for inserting lemma texts, readings and notes that are
+% described \vpagerefrange{ref:lemmata}{ref:notes-e}, viz.\ \cs{lem},
+% \cs{rdg} and \cs{note}. \cs{rdgGrp} accepts one further optional
+% argument:---\\
+% \DescribeOption{type} |type|$=$\meta{value}\\
+% This named argument is used in the \texttt{TEI xml} output to
+% define an attribute common to all elements representing the
+% variation.
+%
+% Here follows how the technique of explicit grouping would apply to
+% the same passage as above:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+As I was walking home through Times Square, I saw my friend
+\app{
+  \rdgGrp[type=subvariation]{
+    \lem[wit=A, alt={Peter\---yesterday}]{Peter at the station
+      yesterday}
+    \rdg[wit=B, alt={bookstore \emph{pro} station}]{Peter at the
+      bookstore yesterday}
+  }
+  \rdg[wit=C]{John this evening}
+}.
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+% 
+% PDF output:---
+% \medskip
+% 
+% \needspace{7\baselineskip}
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+%   \begin{specimen}
+% As I was walking home through Times Square, I saw my friend
+% \app{
+%   \rdgGrp[type=subvariation]{
+%     \lem[wit=pjA, alt={Peter\---yesterday}]{Peter at the station
+%       yesterday}
+%     \rdg[wit=pjB, alt={bookstore \emph{pro} station}]{Peter at the
+%       bookstore yesterday}
+%   }
+%   \rdg[wit=pjC]{John this evening}
+% }.
+%   \end{specimen}
+% \end{alignment}
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<p>As I was walking home through Times Square, I saw my
+friend 
+<app>
+  <rdgGrp type="subvariation">
+    <lem wit="#A">Peter at the station yesterday</lem>
+    <rdg wit="#B">Peter at the bookstore yesterday</rdg>
+  </rdgGrp>
+  <rdg wit="#C">John this evening</rdg>
 </app>.</p>
 \end{minted}
 % \iffalse
 %</example>
 % \fi
+%
 % \section{Emendations and Conjectures}
 % \label{sec:emendations-conjectures}
 % From a technical standpoint, \enquote{conjectures} are readings that
@@ -7987,12 +8066,6 @@ local function rdgGrp_totei(str)
               function(bkslash, cmd, opt, arg)
                  opt = string.sub(opt, 2, -2)
                  arg = string.sub(arg, 2, -2)
-                 teiwit = get_attr_value(opt, "wit")
-                 if teiwit ~= "" then teiwit = " wit=\""..ekdosis.getsiglum(teiwit, "tei").."\"" else end
-                 teisource = get_attr_value(opt, "source")
-                 if teisource ~= "" then teisource = " source=\""..ekdosis.getsiglum(teisource, "tei").."\"" else end
-                 teiresp = get_attr_value(opt, "resp")
-                 if teiresp ~= "" then teiresp = " resp=\""..ekdosis.getsiglum(teiresp, "tei").."\"" else end
                  teitype = get_attr_value(opt, "type")
                  if teitype ~= "" then teitype = " type=\""..teitype.."\"" else end
                  if opt == ""
@@ -8001,7 +8074,7 @@ local function rdgGrp_totei(str)
                                                        cmd, arg, cmd))
                  else
                     return rdgGrp_totei(string.format("<%s%s%s%s%s>%s</%s>",
-                                                       cmd, teiwit, teisource, teiresp, teitype, arg, cmd))
+                                                       cmd, teitype, arg, cmd))
                  end
    end)
    return str