added 'source' and 'resp' as optional arguments of \lem and \rdg. documenting accordingly

1 files changed, 147 insertions, 64 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 54293c5..736b7b9 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -961,13 +961,27 @@ along with this program.  If not, see
 %</example>
 % \fi
 %
-% \subsection{Witnesses, Hands, Shorthands, Scholars \& Sources}
+% \subsection{Witnesses, Hands, Sources, Scholars \& Shorthands}
 % \label{sec:declarations}
+% \paragraph{Terminology}
+% \label{sec:terminology}
+% Strictly speaking, the term \enquote{witness} should apply to any
+% manuscript evidence dating back to the Middle Ages used by the
+% editor to establish the edition text. That said, editors often
+% consult many other types of documents, such as modern editions,
+% articles, notes, correspondence and the like, all of which fall into
+% the category of \enquote{sources}. Furthermore, unpublished
+% conjectures are also taken into account, not to mention the
+% corrections and emendations that are proposed in many places by the
+% editor of the text. As it is necessary to refer to scholars as
+% individuals, \enquote{scholars} naturally emerges as a third
+% category.
+%
 % Any reference that is to be used in the apparatus criticus must be
 % \enquote{declared} in the preamble beforehand, namely: manuscript
 % sigla (either for single manuscripts or manuscript families, primary
-% or later hands, \emph{\&c.}), abbreviated last names of scholars
-% and sources.  To that effect, \pkg{ekdosis} provides the following
+% or later hands, \emph{\&c.}), abbreviated last names of sources
+% and scholars.  To that effect, \pkg{ekdosis} provides the following
 % preamble-only commands:---
 % 
 % \paragraph{Witnesses}
@@ -1117,40 +1131,45 @@ along with this program.  If not, see
 % \fi
 % \label{ref:marcianus-e}
 %
-% \paragraph{Shorthands}
-% \DescribeMacro{\DeclareShorthand} \cs{DeclareShorthand}\marg{unique
-% id}\marg{rendition}\marg{csv list of witnesses}\\
-% This command provides a convenient way to declare \emph{families} of
-% witnesses. It takes three mandatory arguments used to specify
-% consecutively:---
+% \paragraph{Sources}
+% \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
+% text is traditionally divided into two parts: a)~\emph{Codices},
+% which provides the list of sigla used in the apparatus,
+% b)~\emph{Editiones uel Studia}, which provides references to
+% sources, either published or unpublished, which contain conjectures
+% used in the apparatus criticus. \cs{DeclareSource} takes two
+% mandatory arguments used to specify consecutively:---
 % \begin{enumerate}
-% \item The unique identifier of the family to be used in the |.tex|
-%   source file.
+% \item A unique label used in the |.tex| source file to refer to the
+%   work where the conjecture is found.
 % \item The rendition to be used in the printed apparatus criticus.
-% \item A comma-separated list of previously declared witnesses.
 % \end{enumerate}
 %
-% As an example, the manuscripts of Caesar's \emph{Gallic War} are
-% divided into two families: α, which includes mss.\ A, M, B, R, S, L
-% and N, and β, which includes mss.\ T, f, U and l. Therefore,
-% provided that all these witnesses have been already declared, here
-% 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}
+% \danger As \pkg{ekdosis} can include and use \texttt{TEI xml}
+% compliant lists of references,\footnote{See below
+% \vref{sec:references-cited-works}.} it is advisable to use
+% Bib\hologo{(La)TeX} labels in the first argument of
+% \cs{DeclareSource}. Otherwise, the unique label used to declare the
+% source would point to no |xml:id| and the \texttt{TEI xml} would not
+% be valid. Likewise, shorthands fields from the bibliographical
+% database can be recalled from within the second argument of
+% \cs{DeclareSource}:---
+% 
 % \iffalse
 %<*example>
 % \fi
 \begin{minted}[linenos=false]{latex}
-\DeclareShorthand{a}{α}{A,M,B,R,S,L,N}
-\DeclareShorthand{b}{β}{T,f,U,l}
+\DeclareSource{Wil}{Wilamowitz}
+% or for example:
+\DeclareSource{Wil}{\citename{Wil}{shorteditor}}
 \end{minted}
 % \iffalse
 %</example>
 % \fi
-%
-% Then, symbols |a| and |b| can be used in the |.tex| source file in
-% place of manuscripts that belong to either family.
+% \label{sec:declarations-end}
 %
 % \paragraph{Scholars}
 % \label{ref:declare-scholar}
@@ -1194,45 +1213,67 @@ along with this program.  If not, see
 % been found as marginal notes by the hand of the scholar in some
 % edition in print.
 %
-% \paragraph{Sources}
-% \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
-% text is traditionally divided into two parts: a)~\emph{Codices},
-% which provides the list of sigla used in the apparatus,
-% b)~\emph{Editiones uel Studia}, which provides references to
-% sources, either published or unpublished, which contain conjectures
-% used in the apparatus criticus. \cs{DeclareSource} takes two
-% mandatory arguments used to specify consecutively:---
+% \paragraph{Shorthands}
+% \DescribeMacro{\DeclareShorthand} \cs{DeclareShorthand}\marg{unique
+% id}\marg{rendition}\marg{csv list of identifiers}\\
+% This command provides a convenient way to declare \emph{families} of
+% witnesses. It takes three mandatory arguments used to specify
+% consecutively:---
 % \begin{enumerate}
-% \item A unique label used in the |.tex| source file to refer to the
-%   work where the conjecture is found.
+% \item The unique identifier of the family to be used in the |.tex|
+%   source file.
 % \item The rendition to be used in the printed apparatus criticus.
+% \item A comma-separated list of previously declared witnesses.
 % \end{enumerate}
 %
-% \danger As \pkg{ekdosis} can include and use \texttt{TEI xml}
-% compliant lists of references,\footnote{See below
-% \vref{sec:references-cited-works}.} it is advisable to use
-% Bib\hologo{(La)TeX} labels in the first argument of
-% \cs{DeclareSource}. Otherwise, the unique label used to declare the
-% source would point to no |xml:id| and the \texttt{TEI xml} would not
-% be valid. Likewise, shorthands fields from the bibliographical
-% database can be recalled from within the second argument of
-% \cs{DeclareSource}:---
-% 
+% As an example, the manuscripts of Caesar's \emph{Gallic War} are
+% divided into two families: α, which includes mss.\ A, M, B, R, S, L
+% and N, and β, which includes mss.\ T, f, U and l. Therefore,
+% provided that all these witnesses have been already declared, here
+% 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}
 % \iffalse
 %<*example>
 % \fi
 \begin{minted}[linenos=false]{latex}
-\DeclareSource{Wil}{Wilamowitz}
-% or for example:
-\DeclareSource{Wil}{\citename{Wil}{shorteditor}}
+\DeclareShorthand{a}{α}{A,M,B,R,S,L,N}
+\DeclareShorthand{b}{β}{T,f,U,l}
 \end{minted}
 % \iffalse
 %</example>
 % \fi
-% \label{sec:declarations-end}
+%
+% Then, symbols |a| and |b| can be used in the |.tex| source file in
+% place of manuscripts that belong to either family.
+%
+% That said, \cs{DeclareShorthand} is not meant to be restricted to
+% declared witnesses. On the contrary, it also applies to any declared
+% sources and scholars by means of \cs{DeclareSource} and
+% \cs{DeclareScholar}. As an example, assuming that a self-reference
+% to the person responsible for the edition has been set in the
+% preamble, an associated shorthand can be defined like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+\DeclareScholar{ego}{ego}[
+     forename=John,
+     surname=Smith,
+     note=Main editor of the text]
+\DeclareShorthand{egoscr}{ego}{\emph{scripsi}}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% Then, the shorthand |egoscr| (l.~5) can be used to print in the
+% apparatus criticus the technical term \emph{scripsi} and use at the
+% same time the pointer |#ego| that is expected in the \texttt{TEI
+% xml} output file. Detailed examples of this technique will be
+% provided below in \vref{sec:emendations-conjectures}.
 %
 % \subsubsection{Printing Formatted Witnesses
 % --- Conspectus Siglorum}
@@ -1372,6 +1413,10 @@ yesterday.
 % \emph{reading}, which contains deviant readings rejected by the
 % editor.
 %
+% \danger What follows refers to the notions of \enquote{witness},
+% \enquote{source} and \enquote{scholar} as defined above
+% \vpageref{sec:terminology}.
+%
 % \paragraph{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
@@ -1389,12 +1434,24 @@ yesterday.
 % enclosed in curly braces, like so:
 % |wit={A,B,C}|. \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}|. Of course, any unique identifiers or
-% labels used to \enquote{declare} scholars and sources as described
+% \verb*|wit={A,B,C, D,E,F}|. Although any unique identifiers or
+% labels used to \enquote{declare} sources and scholars as described
 % above \vpagerefrange{ref:declare-scholar}{ref:declare-source} can
-% also be used as values of the |wit| optional argument.\footnote{For
-% an example of an edition text used as a witness,
-% see below in \vref{sec:references-cited-works}.}\\
+% also be used as values of the |wit| optional argument, it is
+% 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]\\
+% 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
+% criticus.\footnote{For an example of an edition text used as a
+% source, see below in \vref{sec:references-cited-works}.}\\
+% \DescribeOption{resp} |resp|$=$\meta{csv list of
+% scholars}\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.\\
 % \DescribeOption{alt} |alt|$=$\meta{alternate lemma}\\
 % While the mandatory argument of \cs{lem}, \meta{lemma text}, is
 % always used to print the edition text in the upper part of the page,
@@ -1424,7 +1481,9 @@ yesterday.
 % edition in print, but it is used in the \texttt{TEI xml} ouput to
 % classify the variation recorded in the entry according to some
 % convenient typology. Categories such as lexical, morphological,
-% orthographical and the like may apply.
+% orthographical and the like may apply. Obviously, |type=emendation|
+% should be restricted to lemma texts and |type=conjecture| to variant
+% readings recorded by means of \cs{rdg} described below.
 %
 % \needspace{11\baselineskip}
 % Finally, four named arguments can be used to insert words at the
@@ -1459,12 +1518,17 @@ yesterday.
 % more detailed information:---\\
 % \DescribeOption{wit} |wit|$=$\meta{csv list of
 % witnesses}\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}\\
 % \DescribeOption{nordg} |nordg|$=$\verb+true|false+\\
 % This named argument does not need a value as it defaults to |true|
 % if it is used. |nordg| completely removes the variant reading from
 % the related entry in the apparatus criticus.\\
 % \DescribeOption{type} |type|$=$\meta{value}\\
+% Obviously, |type=conjecture| should be restricted to variant
+% readings and |type=emendation| to lemma texts recorded by means of
+% \cs{lem} described above.\\
 % \DescribeOption{pre} |pre|$=$\meta{words}\\
 % \DescribeOption{post} |post|$=$\meta{words}\\
 % \DescribeOption{prewit} |prewit|$=$\meta{words}\\
@@ -2033,6 +2097,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 %</example>
 % \fi
 %
+% \section{Emendations and Conjectures}
+% \label{sec:emendations-conjectures}
+%
 % \section{Laying Out the Apparatus Criticus }
 % \label{sec:apparatus-layout}
 %
@@ -4042,7 +4109,7 @@ Sample text with a \textcolor{red}{word} in red.
 % Use 'bibl.xml' as a TEI xml bibliographical database:
 \SetxmlBibResource{bibl} % 'bibl' is the basename of 'bibl.xml'
 
-% Declare A. Drakenborch as scholar:
+% Declare A. Drakenborch as source:
 \DeclareSource{Drak}{\emph{Drakenborch}}
 \end{minted}
 % \iffalse
@@ -4084,7 +4151,7 @@ Sample text with a \textcolor{red}{word} in red.
     Sed uos, quorum oculos atque ora humentia uidi,\\
     uertere cum consul terga et remeare iuberet,\\
     \app{
-      \lem[wit=Drak]{ne morem}
+      \lem[source=Drak, type=emendation]{ne morem}
       \rdg[wit={L, F}]{me morem}
       \rdg[wit={O, V}]{memorem}
     } et pugnae signum exspectate petendae:
@@ -4107,7 +4174,7 @@ Sample text with a \textcolor{red}{word} in red.
 %       Sed uos, quorum oculos atque ora humentia uidi,\\
 %       uertere cum consul terga et remeare iuberet,\\
 %       \app{
-%         \lem[wit=sDrak]{ne morem}
+%         \lem[source=sDrak, type=emendation]{ne morem}
 %         \rdg[wit={sL, sF}]{me morem}
 %         \rdg[wit={sO, sV}]{memorem}
 %       } et pugnae signum exspectate petendae:
@@ -4129,7 +4196,7 @@ Sample text with a \textcolor{red}{word} in red.
       <l>uertere cum consul terga et remeare iuberet,</l>
       <l>
       <app>
-        <lem wit="#Drak">ne morem</lem>
+        <lem source="#Drak" type="emendation">ne morem</lem>
         <rdg wit="#L #F">me morem</rdg>
         <rdg wit="#O #V">memorem</rdg>
       </app>et pugnae signum exspectate petendae:</l>
@@ -5900,6 +5967,8 @@ Sample text with a \textcolor{red}{word} in red.
 %    \begin{macrocode}
 \ekvdefinekeys{lem}{
   code wit = \def\ekdlr@wit{#1},
+  code source = \def\ekdlr@source{#1},
+  code resp = \def\ekdlr@resp{#1},
   code alt  = \def\ekdlr@alt{#1},
   code pre = \def\ekdlr@pre{#1},
   code post = \def\ekdlr@post{#1},
@@ -5913,6 +5982,8 @@ Sample text with a \textcolor{red}{word} in red.
 }
 \ekvdefinekeys{rdg}{
   code wit = \def\ekdlr@wit{#1},
+  code source = \def\ekdlr@source{#1},
+  code resp = \def\ekdlr@resp{#1},
   code alt  = \def\ekdlr@alt{#1},
   code pre = \def\ekdlr@pre{#1},
   code post = \def\ekdlr@post{#1},
@@ -5981,6 +6052,8 @@ Sample text with a \textcolor{red}{word} in red.
       \fi
       \ifdefined\ekdlr@postwit%
         \space\unexpanded\expandafter{\ekdlr@postwit}\else\fi
+      \ifdefined\ekdlr@resp\space\getsiglum{\ekdlr@resp}\else\fi
+      \ifdefined\ekdlr@source\space\getsiglum{\ekdlr@source}\else\fi
       \ifdefined\ekdlr@wit\space\getsiglum{\ekdlr@wit}\else\fi
       \ifdefined\ekdlr@prewit%
         \space\unexpanded\expandafter{\ekdlr@prewit}\space\else\fi
@@ -6018,6 +6091,8 @@ Sample text with a \textcolor{red}{word} in red.
       \ifdefined\ekdlr@prewit%
         \space\unexpanded\expandafter{\ekdlr@prewit}\space\else\fi
       \ifdefined\ekdlr@wit\space\getsiglum{\ekdlr@wit}\else\fi
+      \ifdefined\ekdlr@source\space\getsiglum{\ekdlr@source}\else\fi
+      \ifdefined\ekdlr@resp\space\getsiglum{\ekdlr@resp}\else\fi
       \ifdefined\ekdlr@postwit%
         \space\unexpanded\expandafter{\ekdlr@postwit}\else\fi
       \ifekdl@nosep\else\unexpanded\expandafter{\ekdl@sep}\fi
@@ -6071,6 +6146,8 @@ Sample text with a \textcolor{red}{word} in red.
       \fi
       \ifdefined\ekdlr@postwit%
         \space\unexpanded\expandafter{\ekdlr@postwit}\else\fi
+      \ifdefined\ekdlr@resp\space\getsiglum{\ekdlr@resp}\else\fi
+      \ifdefined\ekdlr@source\space\getsiglum{\ekdlr@source}\else\fi
       \ifdefined\ekdlr@wit\space\getsiglum{\ekdlr@wit}\else\fi
       \ifdefined\ekdlr@prewit%
         \space\unexpanded\expandafter{\ekdlr@prewit}\space\else\fi
@@ -6099,6 +6176,8 @@ Sample text with a \textcolor{red}{word} in red.
       \ifdefined\ekdlr@prewit%
         \space\unexpanded\expandafter{\ekdlr@prewit}\space\else\fi
       \ifdefined\ekdlr@wit\space\getsiglum{\ekdlr@wit}\else\fi
+      \ifdefined\ekdlr@source\space\getsiglum{\ekdlr@source}\else\fi
+      \ifdefined\ekdlr@resp\space\getsiglum{\ekdlr@resp}\else\fi
       \ifdefined\ekdlr@postwit%
         \space\unexpanded\expandafter{\ekdlr@postwit}\else\fi
     }%
@@ -7123,6 +7202,10 @@ local function lem_rdg_totei(str)
                  --
                  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
                  --
@@ -7132,8 +7215,8 @@ local function lem_rdg_totei(str)
                                                        cmd, arg, cmd))
                  else
                     -- opt = ekdosis.getsiglum(opt, "tei")
-                    return lem_rdg_totei(string.format("<%s%s%s>%s</%s>",
-                                                       cmd, teiwit, teitype, arg, cmd))
+                    return lem_rdg_totei(string.format("<%s%s%s%s%s>%s</%s>",
+                                                       cmd, teiwit, teisource, teiresp, teitype, arg, cmd))
                  end
    end)
    str = gsub(str, spcenc^-0 * dblbkslash * lemrdg * spcenc^-1 * bcbraces * spcenc^-1,