From 722784102ab24e627277441331314c9d49810aa7 Mon Sep 17 00:00:00 2001
From: Robert Alessi <alessi@robertalessi.net>
Date: Thu, 13 Aug 2020 19:14:04 +0200
Subject: done documenting. getting close to 1.0

---
 Makefile    |    4 +-
 ekdosis.dtx | 1233 +++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 1171 insertions(+), 66 deletions(-)

diff --git a/Makefile b/Makefile
index 8a9009c..7d4e583 100644
--- a/Makefile
+++ b/Makefile
@@ -17,9 +17,9 @@ sty: clean
 	$(CMP) $(NAME).ins >/dev/null
 
 $(NAME).pdf: $(NAME).dtx
-	@ echo "Make the sample files first..."
+	@ echo "Making the sample files first..."
 	$(MAKE) --directory=$(SAMPLES)
-	@ echo "Build the documentation of $(NAME)..."
+	@ echo "Building the documentation of $(NAME)..."
 	$(CMP) --shell-escape --recorder --interaction=batchmode $(NAME).dtx >/dev/null
 	biber $(NAME) >/dev/null
 	$(CMP) --shell-escape --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
diff --git a/ekdosis.dtx b/ekdosis.dtx
index bd829b0..66aab79 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -64,6 +64,30 @@ along with this program.  If not, see
     [2020/07/08 v0.99a Typesetting TEI xml compliant critical editions]
 %</package>
 %<*driver>
+\begin{filecontents}[noheader,overwrite]{bibdata.xml}
+<?xml version="1.0" encoding="UTF-8"?>
+<listBibl xmlns="http://www.tei-c.org/ns/1.0">
+  <biblStruct type="book" xml:id="ReynoldsWilson1991">
+    <monogr>
+      <title level="m">Scribes and Scholars</title>
+      <author>
+        <forename>L. D.</forename>
+        <surname>Reynolds</surname>
+      </author>
+      <author>
+        <forename>N. G.</forename>
+        <surname>Wilson</surname>
+      </author>
+      <edition>3</edition>
+      <imprint>
+        <pubPlace>Oxford</pubPlace>
+        <publisher>Clarendon Press</publisher>
+        <date>1991</date>
+      </imprint>
+    </monogr>
+  </biblStruct>
+</listBibl>
+\end{filecontents}
 \begin{filecontents}[overwrite]{\jobname.bib}
 @Article{Alessi2020,
   author =	 {Alessi, Robert},
@@ -104,6 +128,17 @@ along with this program.  If not, see
   publisher =	 {Harper \& Brothers},
   location =	 {New York}}
 
+@Book{ReynoldsWilson1991,
+  author =	 {Reynolds, L. D. and Wilson, N. G},
+  title =	 {Scribes and Scholars},
+  year =	 {1991},
+  subtitle =	 {A Guide to the Translation of Greek and Latin
+                  Literature},
+  edition =	 {3},
+  publisher =	 {Clarendon Press},
+  location =	 {Oxford}
+}
+
 @Online{DLL-TC,
   author =	 {{Digital Latin Library}},
   title =	 {Textual Criticism},
@@ -166,6 +201,15 @@ along with this program.  If not, see
   version =	 {1.20}
 }
 
+@Software{icite,
+  title =	 {The Icite package},
+  subtitle =	 {Indices locorum citatorum},
+  author =	 {Alessi, Robert},
+  url =		 {http://ctan.org/pkg/icite},
+  date =	 {2020-03-05},
+  version =	 {1.3a}
+}
+
 @Software{arabtex,
   title =	 {The Arabtex package},
   titleaddon =	 {Macros and fonts for typesetting Arabic},
@@ -238,6 +282,16 @@ 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}
+% Silius Italicus' Punica, IX, 30--2:
+\DeclareWitness{sL}{L}{Laurentianus, plut, XXXVII, cod. 16}[
+                      origDate=s. XV]
+\DeclareWitness{sF}{F}{Florentianus, Bibl. Aed. Fl. Eccl. CXCVI}[
+                      origDate=s. XV]                      
+\DeclareWitness{sO}{O}{Oxoniensis Collegii Reginensis CCCXIV}[
+                      origDate=s. XV]                      
+\DeclareWitness{sV}{V}{Vaticanus lat. 1652}[
+                      origDate=s. XV]
+\DeclareScholar{sDrak}{\emph{Drakenborch}}
 \end{filecontents}
 \documentclass{ltxdoc}
  %\usepackage[letterpaper,margin=25mm,left=50mm,nohead]{geometry}
@@ -268,6 +322,8 @@ along with this program.  If not, see
 \usepackage{arabluatex}
 \usepackage[parnotes=roman,teiexport=tidy]{ekdosis}
 \input{ekdosis-cfg}
+\SetxmlBibResource{bibdata}
+\usepackage{booktabs}
 \usepackage{xltabular}
 \usepackage[prevent-all]{widows-and-orphans}
 \usepackage[shortcuts,nospacearound]{extdash}
@@ -315,6 +371,8 @@ along with this program.  If not, see
 \labelformat{figure}{fig.~#1}
 \newcounter{dummy}
 \newcommand{\dummy}{\refstepcounter{dummy}}
+\usepackage[defaultindex=none,citecmd=autocite]{icite}
+\bibinput{ekdosis}
 \usepackage[nospace,american]{varioref}
 \usepackage[style=oxnotes-inote,dashed]{biblatex}
 \DeclareSourcemap{
@@ -758,7 +816,8 @@ along with this program.  If not, see
 %</example>
 % \fi
 %
-% \needspace{4\baselineskip}PDF output:---
+% \needspace{5\baselineskip}
+% PDF output:---
 % \medskip
 % \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
 %   \begin{specimen}
@@ -1103,6 +1162,7 @@ along with this program.  If not, see
 % place of manuscripts that belong to either family.
 %
 % \paragraph{Scholars}
+% \label{ref:declare-scholar}
 % \DescribeMacro{\DeclareScholar} \cs{DeclareScholar}\marg{unique
 % label}\marg{rendition}\\
 % The \emph{Conspectus Siglorum} that is placed ahead of the edition
@@ -1119,10 +1179,13 @@ along with this program.  If not, see
 % \end{enumerate}
 %
 % As \pkg{ekdosis} can include and use \texttt{TEI xml} compliant
-% lists of references, it is avisable to use Bib\hologo{(La)TeX}
-% labels in the first argument of \cs{DeclareScholar}. Likewise,
-% shorthands fields from the bibliographical database can be recalled
-% from within the second argument of \cs{DeclareScholar}:---
+% lists of references,\footnote{See below
+% \vref{sec:references-cited-works}.} it is avisable to use
+% Bib\hologo{(La)TeX} labels in the first argument of
+% \cs{DeclareScholar}. Likewise, shorthands fields from the
+% bibliographical database can be recalled from within the second
+% argument of \cs{DeclareScholar}:---
+% 
 % \iffalse
 %<*example>
 % \fi
@@ -1322,6 +1385,7 @@ yesterday.
 % convenient typology. Categories such as lexical, morphological,
 % orthographical and the like may apply.
 %
+% \needspace{11\baselineskip}
 % Finally, four named arguments can be used to insert words at the
 % following specific places in the lemma text:\\
 % \noindent
@@ -2177,6 +2241,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % \fi
 % 
 % \paragraph{Limiting the Number of Entries per Page}
+% \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}
@@ -2367,6 +2432,7 @@ Some \app[type=rec2]{
 %</example>
 % \fi
 %
+% \needspace{5\baselineskip}
 % PDF output:---
 % \medskip
 % \resetlinenumber
@@ -2436,6 +2502,7 @@ text to demonstrate how to insert a note in the argument of the
 %</example>
 % \fi
 %
+% \needspace{5\baselineskip}
 % PDF output:---
 % \medskip
 % \resetlinenumber
@@ -2746,6 +2813,7 @@ argument of the
 % \vref{sec:multilayer-apparatus} (multiple-layer apparatus
 % criticus).}
 %
+% \needspace{5\baselineskip}
 % The PDF output with left-to-right apparatus criticus follows:---
 % \medskip
 % \resetlinenumber
@@ -2760,6 +2828,7 @@ argument of the
 %   \end{specimen}
 % \end{alignment}
 %
+% \needspace{5\baselineskip}
 % And here follows the PDF output with right-to-left apparatus
 % criticus:---
 % \medskip \resetlinenumber
@@ -2774,7 +2843,6 @@ argument of the
 %   \end{specimen}
 % \end{alignment}
 %
-%
 % \subsection{Using \pkg{arabluatex}}
 % \label{sec:using-arabluatex}
 % \pkg{arabluatex} is a \hologo{LuaLaTeX} package that provides
@@ -2825,6 +2893,7 @@ argument of the
 %</example>
 % \fi
 %
+% \needspace{7\baselineskip}
 % The PDF output with left-to-right apparatus criticus is of course
 % the same as above:---
 % \resetlinenumber
@@ -3166,7 +3235,69 @@ subtype="arabtex">'inna 'abI kAna mina
 %
 % \section{The Tricks of the Trade}
 % \label{sec:tricks-of-trade}
-%
+% As the |.tex| source file is compiled, \pkg{ekdosis} has to compute
+% a tremendous amount of data. Most of this work is performed by
+% \textsf{Lua} functions. An edition text narrowed down to a single
+% page needs to be compiled at least three times. On the first run,
+% the apparatus criticus does not show. Instead, \pkg{ekdosis}
+% produces an auxiliary file named \cs{jobname}|.ekd| in which all the
+% entries of the apparatus criticus are collected. Then, on the second
+% run a test is performed on this auxliary file to determine whether
+% there are entries\---and if so, which ones\---to be printed on the
+% current page. At the same time, references to the line numbers are
+% updated if necessary. Then, on the third run, the apparatus criticus
+% is printed.
+%
+% Of course, every change made to the input may similarly require
+% \hologo{LuaLaTeX} to be run three more times to get everything to
+% the right place with the right numbers.
+%
+% In some instances, notably when on a given page entries are very
+% abundant in number, specifically when the edition text is getting
+% close to the bottom of the page, \pkg{ekdosis} may oscillate
+% indefinitely between different sets of page decisions without being
+% able to settle down. The condition may be typically illustrated as
+% follows: after Lua\LaTeX\ has been run, an entry is attached to the
+% last line of the page. As said above, this entry does not show
+% yet. But when it does, if it results in an additional line being
+% printed in the apparatus criticus, the last line of the edition
+% text\---the one the entry was previously attached to\---goes to the
+% next page. As a result, this entry also moves to the next page with
+% the line it belongs to. This point is literally critical, because
+% unless a \cs{pagebreak} is inserted just here so as to keep the
+% contentious line on the next page, \pkg{ekdosis} enters a vicious
+% circle from which it cannot escape, not to mention that right
+% entries with right line numbers cannot come on pages that follow a
+% wrong page either.
+%
+% An alert reader may have guessed that inserting a \cs{pagebreak} is
+% a good way to get out of the vicious circle. And surely, if only a
+% few pages are at stake, this is the way to go. However,
+% \cs{pagebreak} commands should only be inserted when the whole
+% edition text is ready for any subtantial change in the preceding
+% pages may result in pages that break just after they begin.
+%
+% Another way\---should the edition text fall into the vicious circle
+% too often\---is to limit the number of entries per page that a given
+% layer of apparatus criticus may accept as described above
+% \vpageref{ref:maxentries}. As a result, \pkg{ekdosis} will take care
+% of inserting automatic breakpoints between pages whenever the number
+% of entries on a given page reaches the value set as |maxnumber|.
+%
+% |maxnumber| must not be too small: otherwise offensive to look at
+% vertical spaces may come between the edition text and the apparatus
+% criticus. Conversely, |maxnumber| must not be too big: otherwise,
+% should entries overflow on a given page, the edition text and the
+% apparatus criticus may clash. As said above, a couple of clashes can
+% be managed with a couple of manually inserted page breaks. But if
+% there are too many ot them, it is a good indication that the
+% selected value of |maxentries| is too to high.
+%
+% Complex edition texts do have a magic number. An advisable way to
+% figure it out would be to start from a sample of only a few pages,
+% selected as evidence for the complexity of the whole. As only a few
+% pages would need to be compiled, the magic number should emerge
+% quite rapidly.
 %
 % \section{\texttt{TEI xml} Output}
 % \label{sec:teixml-output}
@@ -3227,7 +3358,7 @@ subtype="arabtex">'inna 'abI kAna mina
 % \paragraph{Validation of the \texttt{TEI xml} Structure}
 % The reference tool that the author relies on is that provided by the
 % \emph{\texttt{TEI} by Example Project}.\footnote{\cite{TBE}.
-% \texttt{TEI} validator:
+% The \texttt{TEI} validator is here:
 % \url{http://teibyexample.com/xquery/TBEvalidator.xq}.} As for
 % \pkg{ekdosis}, it is designed to produce on request, in addition to
 % an edition in print, a \texttt{TEI xml} compliant output file. That
@@ -3241,18 +3372,947 @@ subtype="arabtex">'inna 'abI kAna mina
 % of which are to be translated into \texttt{xml} elements, as will be
 % illustrated by the following.
 % 
-% Converting a \LaTeX\ document into \texttt{TEI xml} is quite an
-% intricate business. In many cases, \LaTeX\ strings are found within
-% environments or groups: whether such groups are delimited by opening
-% and closing braces or by explicit \cs{begin} \dots\ \cs{end}
-% commands, 
+% Converting a \LaTeX\ document into \texttt{TEI xml} can be quite an
+% intricate business. In many cases, however, \LaTeX\ strings are
+% found within environments or groups that are easy to convert into
+% \texttt{TEI} equivalents: unless instructed otherwise, whether such
+% groups are delimited by opening and closing braces or by explicit
+% \cs{begin} \dots\ \cs{end} commands, \pkg{ekdosis} translates them
+% into |xml| so that for example \cs{emph}|{word}| and
+% \cs{begin}|{quote}| \meta{quoted words} \cs{end}|{quote}| become
+% |<emph>| \meta{word} |</emph>| and |<quote>| \meta{quoted words}
+% |</quote>| respectively.
+%
+% But \LaTeX\ does not place everything into groups or
+% environments. To take here but a few examples, sectional divisions
+% are marked in \LaTeX\ with \enquote{open} commands such as
+% \cs{chapter} or \cs{section} with no clear indication where the
+% closure of divisions occurs, contrary to \texttt{TEI xml} markup
+% with numered or un-numbered |<div>| elements allowed to nest
+% recursively. As regards running paragraphs of text, the situation is
+% even worse than in the latter case, as the following simple example
+% shows:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+\begin{document}
+\begin{ekdosis}
+  ...
+
+  ... These are the final words of some section in the body text.
+
+  \section{New Section}
+
+  Here is how some new section begins...
+
+  ... Final words.
+  \section{Other Section}
+  Opening words of the section...
+  
+  ... Final words
+  
+  \section{Other Section}
+  Opening words...
+  
+  ... Final words.
+\end{ekdosis}
+\end{document}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% Obviously, construing this \LaTeX\ source file into \texttt{TEI xml}
+% is a fairly complex task. For example, line~6 only closes a
+% paragraph for line~7 opens a division (hence |</p><div1>|), line~8
+% only opens a paragraph just after the heading of the section (hence
+% |</head><p>|) while line~14 both closes the foregoing paragraph and
+% opens a new one (hence |</p><p>|), contrary to line~16 which both
+% closes a paragraph and a sectional division (hence |</p></div1>|),
+% not to mention lines~20--1, where notwithstanding the absence of
+% blank line or any other indication,
+% |</p></div1></body></text></TEI>| is needed.
+%
+% \pkg{ekdosis} has been designed to implement this task through
+% \textsf{Lua} functions which involve string matching (both forward
+% and reverse matching) and recursions.
+%
+% \paragraph{The \texttt{xml:id} Attribute}
+% As a general rule, the |xml:id| global attribute must be unique for
+% the element that bears the attribute. Furthermore, it must begin
+% with a letter or an underscore and contain no characters other that
+% letters, digits, hyphens underscores and full stops. \pkg{ekdosis}
+% issues a warning when it finds that any \meta{unique id} of
+% \meta{unique label} expected in the first argument of
+% \cs{DeclareWitness}, \cs{DeclareHand} or \cs{DeclareScholar} is not
+% unique or breaks the rules just described, but does not prevent the
+% |.tex| source file from compiling. Instead, it prints the string
+% |<??>| in place of the expected formatted siglum so that the error
+% in the |.tex| source file can be easily spotted and corrected.
+%
+% \danger As the \meta{unique id} declared with \cs{DeclareShorthand}
+% is not to be exported in the \texttt{TEI xml} outputfile,
+% \pkg{ekdosis} checks neither its uniqueness nor its validness.
+%
+% \danger It must be noted that \LaTeX\ labels that are provided in
+% commands such as \cs{label}, \cs{cite} and the like must also be
+% unique in the document. As \LaTeX\ will issue warnings if it finds
+% duplicates, \cs{ekdosis} does not check their uniqueness but will
+% issue warnings if such labels contain invalid strings.
+%
+% \paragraph{\texttt{TEI xml} Export Settings}
+% \DescribeMacro{\SetTEIxmlExport} \cs{SetTEIxmlExport}\marg{csv list
+% of options} can be used in the preamble or at any point of the
+% document, except inside environments set to receive an apparatus
+% criticus, namely the \env{ekdosis} environment or any other similar
+% environment declared by means of \cs{DeclareApparatus}.\footnote{See
+% above \vref{sec:declaring-layers}.} At the time of writing, there is
+% only one option, as follows:---\\
+% \DescribeOption{autopar} |autopar|$=$\verb+true|false+
+% \hfill\tcboxverb{Default: true}\\
+% The algorithm described above applies for edition texts composed in
+% running paragraphs or in lines of poetry, but it may fail to produce
+% a valid \texttt{TEI xml} output with other arrangements, such as
+% performance texts or transcriptions of speech for which the
+% \texttt{TEI} Guidelines define specific rules.  |autopar=false|
+% instructs \pkg{ekdosis} to ignore blank lines in the |.tex| source
+% file as markers for paragraph boundaries. As a result, each
+% paragraph of the edition text must be found within an environment
+% associated with the \texttt{xml} |<p>| element, such as \env{ekdpar}
+% or any other environment declared as such by means of \cs{EnvtoTEI}
+% described below in \vref{sec:new-cmds-envs}. A typical use case of
+% |autopar=false| is provided below in
+% \vref{sec:specific-tei-modules}.
+%
+% \DescribeEnv{ekdpar} \cs{begin}|{ekdpar}| \dots\ \cs{end}|{ekdpar}|
+% is a simple environment that does nothing but insert \cs{par}
+% primitives. It can be used to instruct \pkg{ekdosis} to place
+% paragraphs within |<p>| elements when |autopar| has been set to
+% |false| by means of \cs{SetTEIxmlExport} described above.
+%
+% \subsection{Routine \LaTeX\ Commands and Environments}
+% \label{sec:routine-cmds}
+% The list of \LaTeX\ commands known by \pkg{ekdosis} at the time of
+% writing follows. To this list must be added the \LaTeX\ standard
+% commands that are used for sectional divisions as described above in
+% \vref{sec:latex-divs} and most of the commands provided by the
+% \pkg{arabluatex} and \pkg{icite}\footcite{icite} packages. Standard
+% citation commands are also supported as will be described below in
+% \vref{sec:citation-cmds}:---
+% 
+% \begin{xltabular}{0.825\linewidth}{XX}
+%     \toprule
+%     \LaTeX\ command & \texttt{TEI xml} element\\
+%     \midrule\endhead
+%     \cs{textsuperscript}|{}| & |<hi rend="sup"></hi>| \\
+%     \cs{textsubscript}|{}| & |<hi rend="sub"></hi>| \\
+%     \cs{textbf}|{}| & |<hi rend="bold"></hi>| \\
+%     \cs{textit}|{}| & |<hi rend="italic"></hi>| \\
+%     \cs{textsc}|{}| & |<hi rend="smallcaps"></hi>| \\
+%     \cs{textsf}|{}| & |<hi rend="sf"></hi>| \\
+%     \cs{footnote}|{}| & |<note place="bottom"></note>| \\
+%     \cs{enquote}\meta{*}|{}| & |<quote></quote>| \\
+%     \cs{label}|{label}| & |<anchor xml:id="label"/>| \\
+%     \cs{linelabel}|{label}| & |<anchor xml:id="label"/>| \\
+%     \cs{ref}|{label}| & |<ptr ="#label"/>| \\
+%     \cs{pageref}|{label}| & |<ptr ="#label"/>| \\
+%     \cs{vref}|{label}| & |<ptr ="#label"/>| \\
+%     \cs{vpageref}|{label}| & |<ptr ="#label"/>| \\
+%     \cs{pagebreak}\meta{\oarg{1-4}} & no output \\
+%     \cs{mbox}|{}| & no output \\
+%     \bottomrule
+% \end{xltabular}
+%
+% As for environments:---
+% 
+% \begin{xltabular}{0.825\linewidth}{XX}
+%     \toprule
+%     \LaTeX\ environment & \texttt{TEI xml} element\\
+%     \midrule\endhead
+%     |flushright| & |<p rend="align(right)"></p>| \\
+%     |flushleft| & |<p rend="align(left)"></p>| \\
+%     |center| & |<p rend="align(center)"></p>| \\
+%     |quotation| & |<quote></quote>| \\
+%     |quoting| & |<quote></quote>| \\
+%     |ekdpar| & |<p></p>| \\
+%     |ekdverse| & |<lg></lg>| \\
+%     |verse| & |<lg></lg>| \\
+%     \bottomrule
+% \end{xltabular}
+%
+% Regarding other, very frequently used commands or environments, some
+% do not need to be inserted in the translation tables: as already
+% said above, \pkg{ekdosis} converts by default the original names of
+% these into \texttt{xml} elements. For instance, \cs{emph}|{}| and
+% \cs{begin}|{quote}| \dots\ \cs{end}|{quote}| will result in
+% |<emph></emph>| and |<quote></quote>| respectively.
+%
+% For the same simple reason, if one wishes to have words within a
+% \texttt{TEI xml} element that does not have any \LaTeX\ equivalent,
+% all is needed is to define an inoperative \LaTeX\ command named
+% after the \texttt{TEI} element, like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Preamble:
+\newcommand{\mentioned}[1]{#1}
+
+% Document:
+
+Our usage corresponds to the \mentioned{aggregate} of many
+mathematical writings and to the sense of \mentioned{class} found in
+older logical writings.
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<p>Our usage corresponds to the <mentioned>aggregate</mentioned> of
+many mathematical writings and to the sense of
+<mentioned>class</mentioned> found in older logical writings.</p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% Of course, it is also possible to have the \enquote{mentioned} words
+% printed in a different font family:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\newcommand{\mentioned}[1]{\textsf{#1}}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% This command will print them in a sans serif font family, with the
+% exact same \texttt{TEI xml} output as above.
+%
+% \subsection{Processing New Commands or Environments}
+% \label{sec:new-cmds-envs}
+% The following three commands are provided to instruct \pkg{ekdosis}
+% how to convert unknown or unusual \hologo{(La)TeX} commands or
+% environments into \texttt{TEI xml} equivalents.
+%
+% \DescribeMacro{\TeXtoTEI} \cs{TeXtoTEI}\marg{csname}\marg{TEI
+% element}\oarg{TEI attribute(s)}\\
+% \cs{TeXtoTEI} takes two mandatory arguments and one optional
+% argument, namely: the control sequence name to be converted, the
+% \texttt{TEI} element it is to be converted into and any additional
+% \texttt{xml} attributes to be appended to the opening \texttt{TEI}
+% element. For example, the \cs{sidenote} command that is provided by
+% the \cs{sidenotes} package can be processed like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Preamble:
+\TeXtoTEI{sidenote}{note}[place="margin"]
+
+% Document:
+\begin{ekdosis}
+  \begin{ekdverse}
+    The self-same moment I could pray;\sidenote{The spell begins to
+      break}\footnote{The turning point of the poem...}
+  \end{ekdverse}
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<lg>
+  <l>The self-same moment I could pray;
+  <note place="margin">The spell begins to break</note>
+  <note place="bottom">The turning point of the
+  poem...</note></l>
+</lg>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% Even more subtly, provided that the code |#STC| points to some more
+% information identifying the agency concerned:\footnote{At the time
+% of writing, \enquote*{scholars} can be declared with
+% \cs{DeclareScholar} as described above
+% \vpageref{ref:declare-scholar}. Then the unique ID used in the first
+% argument of this command can point to the list of references
+% inserted by \pkg{ekdosis} in the back matter section of the
+% \texttt{TEI} ouput file. See below \vref{sec:references-cited-works}
+% for more information on how to do this.}---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Preamble:
+\usepackage{sidenotes}
+\usepackage[teiexport=tidy]{ekdosis}
+
+\TeXtoTEI{sidenote}{note}[place="margin"]
+
+\newcommand{\STCsnote}[1]{\sidenote{#1}}
+\TeXtoTEI{STCsnote}{note}[place="margin" resp="#STC"]
+
+% Document:
+\begin{ekdosis}
+  \begin{ekdverse}
+    The self-same moment I could pray;\STCsnote{The spell begins to
+      break}\footnote{The turning point of the poem...}
+  \end{ekdverse}
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<lg>
+  <l>The self-same moment I could pray;
+  <note place="margin" resp="#STC">The spell begins to
+  break</note>
+  <note place="bottom">The turning point of the
+  poem...</note></l>
+</lg>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \DescribeMacro{\EnvtoTEI} \DescribeMacro{\EnvtoTEI*}
+% \cs{EnvtoTEI}\meta{*}\marg{env name}\marg{TEI element}\oarg{TEI
+% attribute(s)}\\
+% \cs{EnvtoTEI} instructs \pkg{ekdosis} how to convert \LaTeX\
+% environments into \texttt{TEI xml} equivalents. It takes two
+% mandatory arguments and one optional argument, namely the name of
+% the \LaTeX\ environment to be converted, the \texttt{TEI} element it
+% is to be converted into and any additional attributes to be appended
+% to the \texttt{TEI} opening element. \cs{EnvtoTEI*} is restricted to
+% \texttt{TEI} elements that must never appear within |<p>| elements,
+% such as |<p>| itself, |<div>|, |<lg>| and the like. The following
+% example illustrates how \cs{EnvtoTEI} can be used conjointly with
+% \pkg{babel} to convey information about the languages used from
+% \LaTeX\ to \texttt{TEI}:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Preamble:
+% Use babel and babeltags:
+\usepackage[greek.ancient, english]{babel}
+\babeltags{ancientgreek = greek}
+
+\EnvtoTEI{ancientgreek}{p}[xml:lang="grc"]
+
+% Document:
+\begin{ekdosis}
+  \begin{ancientgreek}
+    περὶ πολλοῦ ἂν ποιησαίμην, ὦ ἄνδρες, τὸ τοιούτους ὑμᾶς ἐμοὶ
+    δικαστὰς περὶ τούτου τοῦ πράγματος γενέσθαι, οἷοίπερ ἂν ὑμῖν
+    αὐτοῖς εἴητε τοιαῦτα πεπονθότες...
+  \end{ancientgreek}
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<p xml:lang="grc">περὶ πολλοῦ ἂν ποιησαίμην, ὦ ἄνδρες, τὸ
+τοιούτους ὑμᾶς ἐμοὶ δικαστὰς περὶ τούτου τοῦ πράγματος
+γενέσθαι, οἷοίπερ ἂν ὑμῖν αὐτοῖς εἴητε τοιαῦτα πεπονθότες...</p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \DescribeMacro{\TeXtoTEIPatt}
+% \cs{TeXtoTEIPatt}\marg{\TeX\ pattern}\marg{TEI pattern}\\
+% Finally, this more flexible\---and more delicate to
+% handle\---command uses pattern matching to instruct \pkg{ekdosis}
+% how to convert \hologo{(La)TeX} commands into \texttt{TEI}
+% equivalents. In the first mandatory argument, strings to be captured
+% are marked in sequence with numbers prefixed by |#|, like so: |#1|,
+% |#2|, |#3| and so forth. Then, in the second mandatory argument, the
+% strings captured are inserted where each of them is expected in
+% the \texttt{TEI} element.
+%
+% \danger Strings must be entered exactly as \pkg{ekdosis} will find
+% them as the |.tex| source file is compiled. Specifically,
+% \emph{control sequences}, namely the coded commands immediately
+% preceded by `\verb+\+' are always found followed by a space. For
+% instance, |\emph{}| will be seen and processed by \pkg{ekdosis} as
+% \verb*|\emph {}|.
+%
+% The following example illustrates how \pkg{ekdosis} can be
+% instructed to process the
+% \cs{textcolor}\allowbreak\marg{color}\marg{text} command:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\TeXtoTEIPatt{\textcolor {#1}{#2}}{<hi rend="#1">#2</hi>}
+
+Sample text with a \textcolor{red}{word} in red.
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<p>Sample text with a 
+<hi rend="red">word</hi>in red.</p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \subsection{Specific \texttt{TEI} Modules}
+% \label{sec:specific-tei-modules}
+% The following example illustrates how \pkg{ekdosis} can be adapted
+% in a straightforward way to modules provided by the \texttt{TEI} for
+% encoding specific texts such as transcriptions of
+% speech.\footnote{See
+% \url{https://tei-c.org/release/doc/tei-p5-doc/en/html/TS.html}.} The
+% technique applied below uses \cs{EnvtoTEI} conjointly with
+% \cs{SetTEIxmlExport}|{autopar=|\allowbreak|false}|:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+% Preamble:
+\newenvironment{speech}{\par}{\par}
+\newcommand{\speaker}[1]{\textbf{#1}\par}
+\EnvtoTEI{speech}{sp}
+
+\SetTEIxmlExport{autopar=false}
+
+% Document:
+\begin{ekdosis}
+  \begin{speech}
+    \speaker{Σωκράτης}
+    \begin{ekdpar}
+      κατέβην χθὲς εἰς Πειραιᾶ μετὰ Γλαύκωνος τοῦ Ἀρίστωνος
+      προσευξόμενός τε τῇ θεῷ καὶ ἅμα τὴν ἑορτὴν βουλόμενος θεάσασθαι
+      τίνα τρόπον ποιήσουσιν ἅτε νῦν πρῶτον ἄγοντες. καλὴ μὲν οὖν μοι
+      καὶ ἡ τῶν ἐπιχωρίων πομπὴ ἔδοξεν εἶναι, οὐ μέντοι ἧττον ἐφαίνετο
+      πρέπειν ἣν οἱ Θρᾷκες ἔπεμπον.
+    \end{ekdpar}
+  \end{speech}
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \begin{remarks}
+% \item Lines~2--3 define a basic environment meant to contain
+% indivivual speeches and a command to hold the name of the
+% speaker. This name is printed in bold face and followed by a new
+% paragraph in the PDF output.
+% \item Line~4 instructs \pkg{ekdosis} to convert \env{speech} \LaTeX\
+%   environments into |<sp>| \texttt{TEI xml} elements.
+% \item Line~6 disables the |autopar| algorithm that \cs{ekdosis}
+%   provides by default for running paragraphs of text. As a
+%   consequence, \env{ekdpar} is used to mark the paragraphs.
+% \end{remarks}
+% 
+% PDF output:---
+% \medskip
+%
+% \SetTEIxmlExport{autopar=false}
+% \begingroup
+% \newenvironment{speech}{\par\selectlanguage{greek}}{\par}
+% \newcommand{\speaker}[1]{\textbf{#1}\par}
+% \EnvtoTEI{speech}{sp}
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+%   \begin{specimen}
+%  \begin{speech}
+%    \speaker{Σωκράτης}
+%    \begin{ekdpar}
+%      κατέβην χθὲς εἰς Πειραιᾶ μετὰ Γλαύκωνος τοῦ Ἀρίστωνος
+%      προσευξόμενός τε τῇ θεῷ καὶ ἅμα τὴν ἑορτὴν βουλόμενος θεάσασθαι
+%      τίνα τρόπον ποιήσουσιν ἅτε νῦν πρῶτον ἄγοντες. καλὴ μὲν οὖν μοι
+%      καὶ ἡ τῶν ἐπιχωρίων πομπὴ ἔδοξεν εἶναι, οὐ μέντοι ἧττον ἐφαίνετο
+%      πρέπειν ἣν οἱ Θρᾷκες ἔπεμπον.
+%    \end{ekdpar}
+%  \end{speech}     
+%   \end{specimen}
+% \end{alignment}
+% \endgroup
+% \SetTEIxmlExport{autopar=true}
+%
+% \texttt{TEI xml} output:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<sp>
+  <speaker>Σωκράτης</speaker>
+  <p>κατέβην χθὲς εἰς Πειραιᾶ μετὰ Γλαύκωνος τοῦ Ἀρίστωνος
+  προσευξόμενός τε τῇ θεῷ καὶ ἅμα τὴν ἑορτὴν βουλόμενος
+  θεάσασθαι τίνα τρόπον ποιήσουσιν ἅτε νῦν πρῶτον ἄγοντες.
+  καλὴ μὲν οὖν μοι καὶ ἡ τῶν ἐπιχωρίων πομπὴ ἔδοξεν εἶναι, οὐ
+  μέντοι ἧττον ἐφαίνετο πρέπειν ἣν οἱ Θρᾷκες ἔπεμπον.</p>
+</sp>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \subsection{References to Cited Works}
+% \label{sec:references-cited-works}
+% A full example of what is technically called a \emph{Conspectus
+% Siglorum} can be found above in \vref{sec:print-witnesses}. Such a
+% list of manuscript sigla should be found immediately before the
+% edition text. Traditionally, this section is followed by a list of
+% other sources used to establish the text, so that the edited text is
+% in the end established both from manuscript evidence (the
+% \enquote{witnesses}) and other works based on a scholarly approach
+% of the text (the \enquote{sources}) which are called in Latin
+% \emph{Editiones uel Studia}. As a consequence of this classification
+% as \enquote{witness} or \enquote{source}, the former must go within
+% the |<listWit>| element of the \texttt{TEI} header, whereas the
+% latter is to be found within the |<listBibl>| element.
+%
+% \DescribeMacro{\SetxmlBibResource}
+% \cs{SetxmlBibResource}\marg{basename} is a preamble-only command. If
+% a base name for a \texttt{TEI xml} compliant bibliographical
+% database be provided, \pkg{ekdosis} will use it and insert formatted
+% data in the back matter section of its own \texttt{TEI xml} output
+% file, as |<biblStruct>| elements within a |listBibl| section.
+%
+% As an example, the following Bib\hologo{(La)TeX} entry and its
+% \texttt{TEI} equivalent follow:\footnote{\label{fn:zotero}To the
+% author's knowledge, \textsf{Zotero} (\url{https://www.zotero.org})
+% provides excellent \texttt{TEI xml} output from Bib\hologo{(La)TeX}
+% input files.}---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{bibtex}
+@Book{Drak,
+  title = {Punicorum Libri Septemdecim},
+  author = {Silius Italicus, Tiberius Catius},
+  editor = {Drakenborch, Arnold},
+  date = {1717},
+  publisher = {Trajecti ad Rhenum},
+  location = {Utrecht}
+}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{xml}
+<?xml version="1.0" encoding="UTF-8"?>
+<listBibl xmlns="http://www.tei-c.org/ns/1.0">
+  <biblStruct type="book" xml:id="Drak">
+    <monogr>
+      <title level="m">Punicorum libri septemdecim</title>
+      <author>
+        <forename>Tiberius Catius</forename>
+        <surname>Silius Italicus</surname>
+      </author>
+      <editor>
+        <forename>Arnold</forename>
+        <surname>Drakenborch</surname>
+      </editor>
+      <imprint>
+        <pubPlace>Utrecht</pubPlace>
+        <publisher>Trajecti ad Rhenum</publisher>
+        <date>1717</date>
+      </imprint>
+    </monogr>
+  </biblStruct>
+</listBibl>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \danger As can be seen, the same string |Drak| is used as a label in
+% the Bib\hologo{(La)TeX} file (l.~1) and an |xml:id| in the
+% \texttt{TEI} file (l.~3). This same label must be used again in the
+% preamble of the |.tex| source file to declare Arnold Drakenborch as a
+% scholar,\footnote{See above \vpageref{ref:declare-scholar}.} like
+% so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+% Use 'bibl.xml' as a TEI xml bibliographical database:
+\SetxmlBibResource{bibl} % 'bibl' is the basename of 'bibl.xml'
+
+% Declare A. Drakenborch as scholar:
+\DeclareScholar{Drak}{\emph{Drakenborch}}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \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):---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+% Preamble:
+\usepackage[teiexport=tidy]{ekdosis}
+
+% Witnesses:
+\DeclareWitness{L}{L}{Laurentianus, plut, XXXVII, cod. 16}[
+                      origDate=s. XV]
+% Other witnesses [...]
+
+% Scholars:
+\DeclareScholar{Drak}{\emph{Drakenborch}}
+% Other scholars [...]
+
+% basename of the .xml bibliographical database:
+\SetxmlBibResource{bibl}
+
+% Document:
+\begin{ekdosis}
+  \begin{ekdverse}
+    Sed uos, quorum oculos atque ora humentia uidi,\\
+    uertere cum consul terga et remeare iuberet,\\
+    \app{
+      \lem[wit=Drak]{ne morem}
+      \rdg[wit={L, F}]{me morem}
+      \rdg[wit={O, V}]{memorem}
+    } et pugnae signum exspectate petendae:
+  \end{ekdverse}
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \needspace{7\baselineskip}
+% PDF output:---
+% \medskip
+%
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+% \resetlinenumber[30]\rightlinenumbers
+% \setlength{\linenumbersep}{-1.5in}
+%   \begin{specimen}
+%     \begin{ekdverse}
+%       Sed uos, quorum oculos atque ora humentia uidi,\\
+%       uertere cum consul terga et remeare iuberet,\\
+%       \app{
+%         \lem[wit=sDrak]{ne morem}
+%         \rdg[wit={sL, sF}]{me morem}
+%         \rdg[wit={sO, sV}]{memorem}
+%       } et pugnae signum exspectate petendae:
+%     \end{ekdverse}
+%   \end{specimen}
+% \end{alignment}
+%
+% \texttt{TEI xml} output file produced by \pkg{ekdosis} (narrowed
+% down to the |<text>| element):---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{xml}
+<text>
+  <body>
+    <lg>
+      <l>Sed uos, quorum oculos atque ora humentia uidi,</l>
+      <l>uertere cum consul terga et remeare iuberet,</l>
+      <l>
+      <app>
+        <lem wit="#Drak">ne morem</lem>
+        <rdg wit="#L #F">me morem</rdg>
+        <rdg wit="#O #V">memorem</rdg>
+      </app>et pugnae signum exspectate petendae:</l>
+    </lg>
+  </body>
+  <back>
+    <listBibl>
+      <biblStruct type="book" xml:id="Drak">
+        <monogr>
+          <title level="m">Punicorum libri septemdecim</title>
+          <author>
+            <forename>Tiberius Catius</forename>
+            <surname>Silius Italicus</surname>
+          </author>
+          <editor>
+            <forename>Arnold</forename>
+            <surname>Drakenborch</surname>
+          </editor>
+          <imprint>
+            <pubPlace>Utrecht</pubPlace>
+            <publisher>Trajecti ad Rhenum</publisher>
+            <date>1717</date>
+          </imprint>
+        </monogr>
+      </biblStruct>
+    </listBibl>
+  </back>
+</text>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \subsection{Citation Commands}
+% \label{sec:citation-cmds}
+% \pkg{ekdosis} can also convert into \texttt{TEI xml} references to
+% cited works. Depending on the optional arguments used in the
+% citation command, references will be converted into |<ptr>| or
+% |<ref>| elements with the appropriate ID supplied by means of the
+% |target| attribute.
+%
+% Of course, for this mechanism to work, Bib\TeX\ or Bib\LaTeX\ must
+% be used and connected to some |.bib| bibliographical database
+% file. Additionally, this |.bib| file must have been converted into a
+% \texttt{TEI xml} compliant file where all the Bib\hologo{(La)TeX}
+% entries that are used in the document are found within
+% |<biblStruct>| elements.\footnote{See above n.~\vref{fn:zotero} for
+% information on how to do this.} Finally, this |.xml| bibliographical
+% database must have been connected to the |.tex| source file by means
+% of \cs{SetxmlBibResource} described above in
+% \vref{sec:references-cited-works}.
+%
+% As an example, the following |sample.bib| file is used:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{bibtex}
+@Book{ReynoldsWilson1991,
+  author =	 {Reynolds, L. D. and Wilson, N. G},
+  title =	 {Scribes and Scholars},
+  year =	 {1991},
+  subtitle =	 {A Guide to the Translation of Greek and Latin
+                  Literature},
+  edition =	 {3},
+  publisher =	 {Clarendon Press},
+  location =	 {Oxford}
+}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% It has been converted into |sample.xml| as follows:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<?xml version="1.0" encoding="UTF-8"?>
+<listBibl xmlns="http://www.tei-c.org/ns/1.0">
+  <biblStruct type="book" xml:id="ReynoldsWilson1991">
+    <monogr>
+      <title level="m">Scribes and Scholars</title>
+      <author>
+        <forename>L. D.</forename>
+        <surname>Reynolds</surname>
+      </author>
+      <author>
+        <forename>N. G.</forename>
+        <surname>Wilson</surname>
+      </author>
+      <edition>3</edition>
+      <imprint>
+        <pubPlace>Oxford</pubPlace>
+        <publisher>Clarendon Press</publisher>
+        <date>1991</date>
+      </imprint>
+    </monogr>
+  </biblStruct>
+</listBibl>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
 %
+% Once both files have been prepared, inserting references and
+% exporting them into the \texttt{TEI xml} ouput file can be achieved
+% in a straightforward way. (The full |sample.tex| is provided
+% below.)---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\documentclass{article}
+
+\usepackage[teiexport=tidy]{ekdosis}
+\SetxmlBibResource{sample} % base name supplied here, without the
+                           % extension
+
+\usepackage[style=oxnotes]{biblatex}
+\addbibresource{sample.bib}
+
+\begin{document}
+\begin{ekdosis}
+  On textual criticism, see \cite[207--241]{ReynoldsWilson1991}.
+\end{ekdosis}
+\end{document}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
 %
-% \section{To Be Continued...}
-% v1.0 of \pkg{ekdosis}, which should be available by the end of July
-% 2020, will include a full documentation. At the time of writing, the
-% author is working on this part of the package.
+% PDF output:---
+% \medskip
 %
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+%   \begin{specimen}
+%   On textual criticism, see \cite[207--241]{ReynoldsWilson1991}.
+%   \end{specimen}
+% \end{alignment}
+%
+% \medskip
+% \texttt{TEI xml} ouput narrowed down to the contents of the |<text>|
+% element:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<text>
+  <body>
+    <p>On textual criticism, see 
+    <ref target="#ReynoldsWilson1991">207--241</ref>.</p>
+  </body>
+  <back>
+    <listBibl>
+      <biblStruct type="book" xml:id="ReynoldsWilson1991">
+        <monogr>
+          <title level="m">Scribes and Scholars</title>
+          <author>
+            <forename>L. D.</forename>
+            <surname>Reynolds</surname>
+          </author>
+          <author>
+            <forename>N. G.</forename>
+            <surname>Wilson</surname>
+          </author>
+          <edition>3</edition>
+          <imprint>
+            <pubPlace>Oxford</pubPlace>
+            <publisher>Clarendon Press</publisher>
+            <date>1991</date>
+          </imprint>
+        </monogr>
+      </biblStruct>
+    </listBibl>
+  </back>
+</text>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% At the time of writing, the following citation commands are
+% converted into \texttt{TEI xml} by \pkg{ekdosis}:---
+% \begin{enumerate}
+% \item
+% \cs{icite}\oarg{prenote}\oarg{postnote}\marg{key}\footnote{From the
+% \pkg{icite} package. \cs{icite} can be used in place of almost any
+% standard citation command. See \cite{icite}.}
+% \item \cs{cite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{Cite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{cite*}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{parencite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{Parencite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{parencite*}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{footcite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{footcitetext}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{textcite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{Textcite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{smartcite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{Smartcite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{autocite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{Autocite}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{autocite*}\oarg{prenote}\oarg{postnote}\marg{key}
+% \item \cs{Autocite*}\oarg{prenote}\oarg{postnote}\marg{key}
+% \end{enumerate}
+%
+% The next release of \pkg{ekdosis} will include all citation commands
+% with the exception of so-called \enquote{qualified citation lists}.
+% 
+% \section{Future Work}
+% \label{sec:future-work}
+% A short, uncommented list of what is planned in the versions of
+% \pkg{ekdosis} to come follows:---
+% \begin{enumerate}
+% \item Very short-term (weeks):---
+%   \begin{enumerate}
+%   \item Editorial changes, for inserting corrections and
+%   conjectures.
+%   \item Text structure: milestone elements.
+%   \end{enumerate}
+% \item Short-term (months):---
+%   \begin{enumerate}
+%   \item Poetry: The standard \env{verse} environment is supported by
+%     the current version of \pkg{ekdosis}, in addition to
+%     \env{ekdverse} an example of which has been provided above
+%     \vpageref{ref:ekdverse-ex}. \env{ekdverse} will provide refined
+%     options, such as metrical analysis, stanzaic forms, \emph{\&c.}
+%     Arabic poetry through the environments and commands provided by
+%     the \pkg{arabluatex} package will also be supported.
+%   \item Correspondence and alignment, segmentation: The functions
+%     are being tested at the time of writing and will be included
+%     shortly in \pkg{ekdosis}.
+%   \end{enumerate}
+% \item Medium-term: Indexing, commands and environments for specific
+%   modules of the \texttt{TEI}.
+% \end{enumerate}
+% 
 % \begin{comment}
 %   \section{Correspondence and Alignment}
 % \end{comment}
@@ -4084,6 +5144,28 @@ subtype="arabtex">'inna 'abI kAna mina
 %    \end{macrocode}
 % \end{macro}
 % \paragraph{\TeX\ to \texttt{TEI xml}}
+% Here follow the |key-value| options to be used by \cs{SetTEIxmlExport}
+% below:---
+%    \begin{macrocode}
+\ekvdefinekeys{tei@settings}{
+  choice autopar = {true = \luadirect{ekdosis.setteiautopar("yes")},
+    false = {\luadirect{ekdosis.setteiautopar("no")}}},
+  initial autopar = true,
+  unknown-choice autopar = \PackageError{ekdosis}{unknown
+    autopar=#1}{`autopar' must be either `true' or `false'.}
+}
+%    \end{macrocode}
+% \begin{macro}{\SetTEIxmlExport}
+% \cs{SetTEIxmlExport} collects the settings to be applied
+% to \texttt{TEI xml} export. For now, there is only one option. This
+% command can be used at any point of the document, except inside
+% environments meant to receive an apparatus criticus.
+%    \begin{macrocode}
+\NewDocumentCommand{\SetTEIxmlExport}{m}{
+  \unless\ifekd@state\ekvset{tei@settings}{#1}\fi
+}
+%    \end{macrocode}
+% \end{macro}
 % The following three commands can be used to instruct \pkg{ekdosis}
 % how to convert unknown or unusual \hologo{(La)TeX} commands into
 % \texttt{TEI xml} equivalents.
@@ -4154,8 +5236,8 @@ subtype="arabtex">'inna 'abI kAna mina
 % \begin{macro}{\SetxmlBibResource} This is a preamble-only command.
 %   If a base name for a \texttt{TEI xml} compliant bibliographical
 %   database file is provided with
-%   \cs{SetxmlBibResource}\marg{basename}, \pkg{ekdosis} will use
-%   insert formatted data in the back matter section of its own
+%   \cs{SetxmlBibResource}\marg{basename}, \pkg{ekdosis} will use it
+%   and insert formatted data in the back matter section of its own
 %   \texttt{TEI xml} output file, as |<biblStruct>| elements within a
 %   |<listBibl>| section.
 %    \begin{macrocode}
@@ -5393,7 +6475,16 @@ subtype="arabtex">'inna 'abI kAna mina
   \item[]
   }{\end{list}}
 %    \end{macrocode}
-% 
+% \begin{environment}{ekdpar}
+%   When |autopar| is set to |false| by means of \cs{SetTEIxmlExport},
+%   \env{ekdpar}\---or any other environment set to be inserted within
+%   |<p>| elements\---must be used so that \pkg{ekdosis} can be
+%   informed of paragraph boundaries.
+%    \begin{macrocode}
+\NewDocumentEnvironment{ekdpar}{}{\par}{\par}
+%    \end{macrocode}
+% \end{environment}
+%
 % \iffalse
 %</package>
 % \fi
@@ -5439,9 +6530,9 @@ local endpoem = lpeg.Cs(lnbrk * lpeg.S("*!") * bsqbrackets^-1)
 local sections = lpeg.Cs(lpeg.P("book") + lpeg.P("part") + lpeg.P("chapter")
 			    + lpeg.P("section") + lpeg.P("subsection")
 			    + lpeg.P("subsubsection"))
-local par =  lpeg.P(lpeg.P("\\par") * spce^1)
-local parb = lpeg.P(lpeg.Cs("\\p@rb") * spce^1)
-local para = lpeg.P(lpeg.Cs("\\p@ra") * spce^1)
+local par =  lpeg.P(lpeg.P("\\par") * spce^0)
+local parb = lpeg.P(lpeg.Cs("\\p@rb") * spce^0)
+local para = lpeg.P(lpeg.Cs("\\p@ra") * spce^0)
 local labelrefcmds = lpeg.Cs(lpeg.P("label")
 			       + lpeg.P("linelabel")
 			       + lpeg.P("lineref")
@@ -5449,7 +6540,25 @@ local labelrefcmds = lpeg.Cs(lpeg.P("label")
 			       + lpeg.P("pageref")
 			       + lpeg.P("vref")
 			       + lpeg.P("vpageref"))
-
+local citecmds = lpeg.Cs(lpeg.P("icite")
+			    + lpeg.P("cite")
+			    + lpeg.P("Cite")
+			    + lpeg.P("cite *")
+			    + lpeg.P("parencite")
+			    + lpeg.P("Parencite")
+			    + lpeg.P("parencite *")
+			    + lpeg.P("footcite")
+			    + lpeg.P("footcitetext")
+			    + lpeg.P("textcite")
+			    + lpeg.P("Textcite")
+			    + lpeg.P("smartcite")
+			    + lpeg.P("Smartcite")
+			    + lpeg.P("autocite")
+			    + lpeg.P("Autocite")
+			    + lpeg.P("autocite *")
+			    + lpeg.P("Autocite *")
+)
+--
 -- Bind to local variables
 local next = next
 
@@ -5699,11 +6808,14 @@ local cmdtotags = {
    {a="textsf", b="hi", c=" rend=\"sf\""},
    {a="arbup", b="hi", c=" rend=\"sup\""},
    {a="txarb", b="s", c=" xml:lang=\"arb\""},
+   {a="mbox", b="", c=""},
    {a="arb", b="foreign",
     c=" xml:lang=\"ar-Latn\" type=\"transliterated\" subtype=\"arabtex\""}
 }
 
 local texpatttotags = {
+   {a="\\pagebreak%s+%[[1-4]%]", b=""},
+   {a="\\pagebreak%s+", b=""},
    {a="\\altrfont%s+", b=""},
    {a="\\LR%s+{(.-)}", b="%1"},
    {a="\\RL%s+{(.-)}", b="%1"}
@@ -5716,6 +6828,7 @@ local envtotags = {
    {a="ekdverse", b="lg", c=""},
    {a="txarabtr", b="p", c=" xml:lang=\"ar-Latn\" type=\"transliterated\""},
    {a="quoting", b="quote", c=""},
+   {a="ekdpar", b="p", c=""},
    {a="txarab", b="p", c=" xml:lang=\"arb\""},
    {a="center", b="p", c=" rend=\"align(center)\""},
    {a="verse", b="lg", c=""},
@@ -5972,7 +7085,7 @@ end
 
 local function icitetotei(str)
    str = gsub(str, lpeg.P("\\")
-		 * lpeg.Cs("icite")
+		 * citecmds
 		 * spcenc^-1
 		 * bsqbrackets
 		 * bsqbrackets
@@ -5994,7 +7107,7 @@ local function icitetotei(str)
 		 return string.format("%s <ref target=\"#%s\">%s</ref>", pre, body, post)
    end)
    str = gsub(str, lpeg.P("\\")
-		 * lpeg.Cs("icite")
+		 * citecmds
 		 * spcenc^-1
 		 * bsqbrackets
 		 * bcbraces
@@ -6014,7 +7127,7 @@ local function icitetotei(str)
 		 return string.format("<ref target=\"#%s\">%s</ref>", body, post)
    end)
    str = gsub(str, lpeg.P("\\")
-		 * lpeg.Cs("icite")
+		 * citecmds
 		 * spcenc^-1
 		 * bcbraces
 		 * bsqbrackets^-1,
@@ -6104,19 +7217,36 @@ local function cmdtotei(str)
    return str
 end
 
+local teiautopar = true
+
+function ekdosis.setteiautopar(choice)
+   if choice == "yes"
+   then
+      teiautopar = true
+   else
+      teiautopar = false
+   end
+   return true
+end
+
 local function partotei(str)
-   str = gsub(str, lpeg.P(lpeg.P("\\par") * spcenc^1)^1, "\\par ")
-   str = gsub(str, ((para + parb) * par^-1)^2, "\\p@r ")
-   str = string.gsub(str, "\\p@ra%s+", "<p>")
-   str = string.gsub(str, "\\p@rb%s+", "</p>")
-   str = string.gsub(str, "\\p@r%s+", "")   
-   str = string.gsub(str, "%s?\\par%s?", "<p>", 1)
-   str = string.gsub(str, "(%<p%>)(%s-)(%<%/?div%d?)", "%3")
-   str = string.gsub(str, "%s?\\par%s?", "</p><p>")
-   str = string.gsub(str, "<p>%s?</p>", "")
-   str = string.gsub(str, "(%<p%>)%s?(%</div%>)$", "%2")
-   str = string.gsub(str, "(%<p%>)%s?$", "")
-   str = string.gsub(str, "(<p>)%s?(<div.->)", "%2%1")
+   if teiautopar
+   then
+      str = gsub(str, lpeg.P(lpeg.P("\\par") * spcenc^1)^1, "\\par ")
+      str = gsub(str, ((para + parb) * par^-1)^2, "\\p@r ")
+      str = string.gsub(str, "\\p@ra%s+", "<p>")
+      str = string.gsub(str, "\\p@rb%s+", "</p>")
+      str = string.gsub(str, "\\p@r%s+", "")   
+      str = string.gsub(str, "%s?\\par%s?", "<p>", 1)
+      str = string.gsub(str, "(%<p%>)(%s-)(%<%/?div%d?)", "%3")
+      str = string.gsub(str, "%s?\\par%s?", "</p><p>")
+      str = string.gsub(str, "<p>%s?</p>", "")
+      str = string.gsub(str, "(%<p%>)%s?(%</div%>)$", "%2")
+      str = string.gsub(str, "(%<p%>)%s?$", "")
+      str = string.gsub(str, "(<p>)%s?(<div.->)", "%2%1")
+   else
+      str = gsub(str, par + para + parb, "")
+   end
    return str
 end
 
@@ -6768,31 +7898,6 @@ end
 
 local environment_div = {}
 
-function ekdosis.newscholar(id, siglum)
-   if xmlidfound(id)
-   then
-      tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
-	    ..id..
-	    "\" already exists as an xml:id. " 
-	    ..
-	    "Please pick another id.}}")
-   elseif not checkxmlid(id)
-   then
-      tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
-      	 ..id..
-      	 "\" is not a valid xml:id. \\MessageBreak "
-      	 ..
-      	 "Please pick another id.}}")
-   else
-      table.insert(xmlids, {xmlid = id})
-      table.sort(xmlids, function(a ,b) return(#a.xmlid > #b.xmlid) end)
-      table.insert(idsRend, {xmlid = id, abbr = siglum})
-      table.sort(idsRend, function(a ,b) return(#a.xmlid > #b.xmlid) end)
-   end
-   return true
-end
-
-
 local function build_envdiv(str)
    if not environment_div[str]
    then
-- 
cgit v1.2.3