new commands \supplied, \surplus, \sic and \gap for editorial changes. documenting the new features

1 files changed, 245 insertions, 14 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 0433df9..b30f7c0 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -222,13 +222,12 @@ along with this program.  If not, see
 \end{filecontents}
 \begin{filecontents}[overwrite]{\jobname-cfg.tex}
 \footnotelayout{m}
+\EnvtoTEI{ancientgreek}{p}[xml:lang="grc"]
 \DeclareApparatus{fontium}[
         delim=\hskip0.75em,
-        bhook=\textbf{Sources:},
-        ehook=.]
+        bhook=\textbf{Sources:}]
 \DeclareApparatus{default}[
-        delim=\hskip0.75em,
-        ehook=.]
+        delim=\hskip0.75em]
 \DeclareApparatus{ltr}[
         delim=\hskip0.75em]
 \DeclareApparatus{rtl}[
@@ -282,6 +281,15 @@ along with this program.  If not, see
 \DeclareWitness{hI}{I}{\emph{Parisinus Gr.} 2140}
 \DeclareWitness{hR}{R}{\emph{Vaticanus Gr.} 277}
 \DeclareWitness{hH}{H}{\emph{Parisinus Gr.} 2142}
+\DeclareSource{Lit}{Littré}
+\DeclareSource{Erm}{Ermerins}
+\DeclareSource{Sm}{Smith}
+\DeclareScholar{ego}{ego}[
+                forename=Robert,
+                surname=Alessi]
+\DeclareShorthand{hcodd}{codd.}{hV,hI,hR,hH}
+\DeclareShorthand{hedd}{edd.}{Lit,Erm,Sm}
+\DeclareShorthand{hegoscr}{\emph{scripsi}}{ego}
 % Silius Italicus' Punica, IX, 30--2:
 \DeclareWitness{sL}{L}{Laurentianus, plut, XXXVII, cod. 16}[
                       origDate=s. XV]
@@ -592,6 +600,7 @@ along with this program.  If not, see
 %
 % \changes{v0.99a}{2020/07/08}{First public release (documentation in
 % progress)}
+% \changes{v1.0}{2020/08/14}{Documentation complete}
 %
 % \begin{abstract}
 %   \pkg{ekdosis} is a Lua\LaTeX{} package designed for
@@ -2099,6 +2108,113 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 %
 % \section{Emendations and Conjectures}
 % \label{sec:emendations-conjectures}
+% From a technical standpoint, \enquote{conjectures} are readings that
+% are not supported by manuscript evidence, but are instead proposed
+% by scholars to be taken into consideration for establishing the
+% edition text. A conjecture is called an \enquote{emendation} if it
+% is adopted in place of what is provided by or missing from the text
+% provided by the manuscripts. Emendations and conjectures are
+% therefore readings and as such expected to be found within |<lem>|
+% or |<rdg>| elements. However, as both come from editions or
+% scholars, not from manuscripts, they are naturally associated with
+% |source| or |resp| attributes as described above
+% \vpagerefrange{ref:lem-source}{ref:lem-resp},\footnote{See also
+% \vpagerefrange{ref:declare-scholar}{ref:declare-source}.} and can be
+% distinguished from one another by the |type| attribute, eg.\ either
+% |emendation| or |conjecture|.
+%
+% As an example, the representation of witnesses, editors and
+% shorthands of Hippocrates' \emph{Epidemics}, Book~2 could be
+% summarized as follows:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+% Witnesses:
+\DeclareWitness{V}{V}{\emph{Vaticanus Gr.} 276}
+\DeclareWitness{I}{I}{\emph{Parisinus Gr.} 2140}
+\DeclareWitness{R}{R}{\emph{Vaticanus Gr.} 277}
+\DeclareWitness{H}{H}{\emph{Parisinus Gr.} 2142}
+% Sources (the first arguments below must refer to biblatex labels and
+% an xml bibliographical database must be supplied):
+\DeclareSource{Lit}{Littré}
+\DeclareSource{Erm}{Ermerins}
+\DeclareSource{Sm}{Smith}
+% Persons:
+\DeclareScholar{ego}{ego}[
+                forename=Robert,
+                surname=Alessi]
+% Useful shorthands:
+\DeclareShorthand{codd}{codd.}{V,I,R,H}
+\DeclareShorthand{edd}{edd.}{Lit,Erm,Sm}
+\DeclareShorthand{egoscr}{\emph{scripsi}}{ego}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% As can be seen from lines~16--18, three useful shorthands have been
+% defined: |codd| prints \enquote{codd.} for Latin pl.\ \emph{codices}
+% viz.\ \enquote{all manuscripts} and refers to the three \texttt{xml}
+% identifiers |V|, |I|, |R| and |H| declared at ll.~2--5; |edd| prints
+% \enquote{edd.} for Latin pl.\ \emph{editores} viz.\ \enquote{all
+% editors} and refers to the three \texttt{xml} identifiers |Lit|,
+% |Erm| and |Sm| declared at ll.~8--10;\footnote{For detailed
+% information on how to use \cs{DeclareSource} and insert references
+% to cited works, the reader is invited to refer to
+% \vref{sec:references-cited-works}.} finally, |egoscr| (l.~18) is
+% used to print the technical Latin term \enquote{\emph{scripsi}},
+% \enquote{I wrote}, to denote a personal conjecture. Then, the |.tex|
+% source file can be structured as follows:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\begin{ekdosis}
+  εἰ
+  \app{
+    \lem[resp=egoscr, type=emendation]{μὲν}
+    \rdg[wit=codd, source=edd]{μὴ}
+  } εἴη διὰ ταῦτα [...]
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% PDF output:---
+% \medskip
+%
+% \needspace{7\baselineskip}
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+%   \begin{specimen}
+%     \begin{ancientgreek}
+%       εἰ \app{
+%       \lem[resp=hegoscr, type=emendation]{μὲν}
+%       \rdg[wit=hcodd, source=hedd]{μὴ}
+%     } εἴη διὰ ταῦτα [...]
+%     \end{ancientgreek}
+%   \end{specimen}
+% \end{alignment}
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<p xml:lang="grc">εἰ 
+<app>
+  <lem resp="#ego" type="emendation">μὲν</lem>
+  <rdg wit="#V #I #R #H" source="#Lit #Erm #Sm">μὴ</rdg>
+</app>εἴη διὰ ταῦτα [...]</p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
 %
 % \section{Laying Out the Apparatus Criticus }
 % \label{sec:apparatus-layout}
@@ -3256,7 +3372,7 @@ subtype="arabtex">'inna 'abI kAna mina
 % To elaborate on the example provided above in \vref{sec:latex-divs},
 % here follows how the first three hierarchical levels could be
 % formatted as un-numbered divisions:---
-% 
+%
 % \iffalse
 %<*example>
 % \fi
@@ -5252,13 +5368,13 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\DeclareSource}
-%   \changes{v1.1}{2020/08/20}{new command}There is also a table in
-%   which are collected data related to sources to be used in the
-%   apparatus criticus. \cs{DeclareSource} is a preamble-only 
-%   command and takes two mandatory arguments: a unique id and a
-%   shorthand (preferably a Bib\hologo{(La)TeX} label) to be used in
-%   the apparatus criticus which can be extracted from a bibliographic
-%   database.
+% \changes{v1.1}{2020/08/20}{new command added}There is also a table in
+% which are collected data related to sources to be used in the
+% apparatus criticus. \cs{DeclareSource} is a preamble-only 
+% command and takes two mandatory arguments: a unique id and a
+% shorthand (preferably a Bib\hologo{(La)TeX} label) to be used in
+% the apparatus criticus which can be extracted from a bibliographic
+% database.
 %    \begin{macrocode}
 \NewDocumentCommand{\DeclareSource}{m m}{
   \luadirect{ekdosis.newsource(\luastringN{#1},
@@ -5673,8 +5789,11 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \cs{add@@apparatus} inserts the apparatus block on a given page
 % either in the footnote floating block or in a float of its own,
-% depending on the value set in the |layout| global option.
+% depending on the value set in the |layout| global option. As some
+% commands need to know whether they are called from inside the
+% apparatus criticus, a conditional is first defined.
 %    \begin{macrocode}
+\newif\ifekd@inside@app
 \def\add@@apparatus{%
   \if@pkg@parnotes\parnotes\else\fi%
   \if@pkg@footins%
@@ -5685,8 +5804,10 @@ Sample text with a \textcolor{red}{word} in red.
     \if@parnotesroman%
     \renewcommand*{\theparnotemark}{\roman{parnotemark}}\else\fi%
     \parnoteclear\else\fi%
+    \ekd@inside@apptrue
     \footnotesize\apparatus\unless\ifekd@mapps\ekd@end@apparatus\fi%
-    \if@pkg@parnotes\parnotes\parnotereset\else\fi%
+    \ekd@inside@appfalse
+    \if@pkg@parnotes\parnotes\parnotereset\else\fi
   }%
   \egroup%
   \fi%
@@ -5696,7 +5817,9 @@ Sample text with a \textcolor{red}{word} in red.
     \if@parnotesroman%
     \renewcommand*{\theparnotemark}{\roman{parnotemark}}\else\fi%
     \parnoteclear\else\fi%
+    \ekd@inside@apptrue
     \ekd@appfontsize\apparatus\unless\ifekd@mapps\ekd@end@apparatus\fi%
+    \ekd@inside@appfalse
     \if@pkg@parnotes\parnotes\parnotereset\else\fi%
   }%
   \fi%
@@ -6366,6 +6489,101 @@ Sample text with a \textcolor{red}{word} in red.
 }
 %    \end{macrocode}
 % \end{macro}
+% \paragraph{Emendations and Conjectures}
+% Here follows the |key-value| options to be used by
+% \cs{SetCritSymbols} below:---
+%    \begin{macrocode}
+\ekvdefinekeys{ekd@corr}{
+  store suppbegin = \suppb@value,
+  store suppend = \suppe@value,
+  store delbegin = \delb@value,
+  store delend = \dele@value,
+  store sicbegin = \sicb@value,
+  store sicend = \sice@value,
+  store gapmark = \gapm@value,
+  initial suppbegin = \ifbool{al@rlmode}{>}{<},
+  initial suppend = \ifbool{al@rlmode}{<}{>},
+  initial delbegin = \ifbool{al@rlmode}{\}}{\{},
+  initial delend = \ifbool{al@rlmode}{\{}{\}},
+  initial sicbegin = \dag,
+  initial sicend = \dag,
+  initial gapmark = ***
+}
+%    \end{macrocode}
+% \begin{macro}{\supplied}
+% \changes{v1.1}{2020/08/21}{new macro for editorial additions}
+% \cs{supplied}\marg{text} takes as mandatory argument the text added
+% or supplied by conjecture.
+%    \begin{macrocode}
+\NewDocumentCommand{\supplied}{m}{%
+  \ifekd@inside@app
+  #1%
+  \else
+  \suppb@value #1\suppe@value
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\surplus}
+% \changes{v1.1}{2020/08/21}{new macro for editorial deletions}
+% \cs{surplus}\marg{text} takes as mandatory argument the text
+% considered by the editor to be inauthentic, but nevertheless
+% retained between braces in the edition text as it is transmitted by
+% all witnesses.
+%    \begin{macrocode}
+\NewDocumentCommand{\surplus}{m}{%
+  \ifekd@inside@app
+  #1%
+  \else
+  \delb@value #1\dele@value
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\sic}
+% \changes{v1.1}{2020/08/21}{new macro for text deemed to be not
+% understandable}
+% \cs{sic}\marg{text} takes as mandatory argument the text deemed by
+% the editor to be readable but not understandable. \cs{sic} insert
+% \meta{text} between cruces while \cs{sic*} prints only one crux
+% before \meta{text}.
+%    \begin{macrocode}
+\NewDocumentCommand{\sic}{s m}{%
+  \ifekd@inside@app
+  #2%
+  \else
+  \IfBooleanTF{#1}
+    {\sicb@value #2}
+    {\sicb@value #2\sice@value}%
+  \fi
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\gap}
+% \changes{v1.1}{2020/08/21}{new macro for lacunae}
+% \cs{gap}\marg{options} indicates that some amount of text has fallen
+% away from the entire tradition. It takes as mandatory argument a
+% comma-separated list of options that can be used to further specify
+% the reason for omission, the unit of measurement, the quantity and
+% extent.
+%    \begin{macrocode}
+\NewDocumentCommand{\gap}{m}{%
+  \gapm@value
+}
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\SetCritSymbols}
+% \changes{v1.1}{2020/08/21}{new macro to set the symbols to be
+% used to mark the corrections} \cs{SetCritSymbols}\marg{csv list of
+% options} is used to change the symbols that \pkg{ekdosis} uses by
+% default for representing emendations, lacunae, omissions, gaps and
+% editorial deletions.
+%    \begin{macrocode}
+\NewDocumentCommand{\SetCritSymbols}{m}{
+  \ekvset{ekd@corr}{#1}
+}
+%    \end{macrocode}
+% \end{macro}
 % \cs{apparatus} is used internally by \pkg{ekdosis} to print the
 % apparatus at the bottom of pages. Therefore, it is not documented,
 % but this may change in the future for it will be possible to have
@@ -7415,6 +7633,19 @@ local function cmdtotei(str)
                         return string.format("<ref target=\"%s\">%s</ref>",
                                              teisiglum, printsiglum)
    end)
+   str = string.gsub(str, "\\(gap)%s?(%b{})",
+                     function(cmd, body)
+                        body = string.sub(body, 2, -2)
+                        teireason = get_attr_value(body, "reason")
+                        if teireason ~= "" then teireason = " reason=\""..teireason.."\"" else end
+                        teiunit = get_attr_value(body, "unit")
+                        if teiunit ~= "" then teiunit = " unit=\""..teiunit.."\"" else end
+                        teiquantity = get_attr_value(body, "quantity")
+                        if teiquantity ~= "" then teiquantity = " quantity=\""..teiquantity.."\"" else end
+                        teiextent = get_attr_value(body, "extent")
+                        if teiextent ~= "" then teiextent = " extent=\""..teiextent.."\"" else end
+                        return string.format("<gap%s%s%s%s/>", teireason, teiunit, teiquantity, teiextent)
+   end)
    str = gsub(str, lpeg.P("\\") * labelrefcmds * spcenc^-1 * bcbraces,
               function(cmd, body)
                  body = string.sub(body, 2, -2)