still documenting (now on alignment)

1 files changed, 491 insertions, 39 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 3713787..c801a59 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -93,6 +93,30 @@ along with this program.  If not, see
   eprint =       {hal-02779803}
 }
 
+@Book{Caesar-BG-v2,
+  author =       {{Caesar}},
+  title =        {Gallic War},
+  origtitle =    {Guerre des Gaules},
+  date =         1987,
+  origdate =     1926,
+  editor =       {Constans, L.-A.},
+  volume =       2,
+  pagination =   {none},
+  series =       {Collection des Universités de France},
+  publisher =    {Les Belles Lettres},
+  location =     {Paris}
+}
+
+@Book{CaesarTr,
+  author =       {{Caesar}},
+  title =        {Gallic War},
+  date =         1869,
+  editor =       {McDevitte, W. A., and Bohn, W. S.},
+  edition =      1,
+  series =       {Harper's New Classical Library},
+  publisher =    {Harper \& Brothers},
+  location =     {New York}}
+
 @Online{DLL-TC,
   author =       {{Digital Latin Library}},
   title =        {Textual Criticism},
@@ -125,8 +149,41 @@ along with this program.  If not, see
         origDate=s. X]
 \DeclareHand{M1}{M}{M\textsuperscript{1}}[Emendatio scribae ipsius]
 \DeclareHand{M2}{M}{M\textsuperscript{2}}[Manus posterior]
+% Peter and John Story:
 \DeclareWitness{pjA}{A}{Manuscript A Call No 123}
 \DeclareWitness{pjB}{B}{Manuscript B Call No 456}
+% Caesar's Gallic War:
+\DeclareWitness{cA}{A}{\emph{Bongarsianus} 81}[
+               msName=\emph{Bongarsianus},
+               settlement=Amsterdam,
+               idno=81,
+               repository=University Library,
+               origDate=s. IX--X]
+\DeclareHand{cA1}{cA}{A\textsuperscript{1}}[\emph{Emendationes
+               scribae ipsius}]
+\DeclareWitness{cM}{M}{\emph{Parisinus Lat.} 5056}[
+               origDate={s. XII}]
+\DeclareWitness{cB}{B}{\emph{Parisinus Lat.} 5763}[
+               origDate={s. IX--X}]
+\DeclareWitness{cR}{R}{\emph{Vaticanus Lat.} 3864}[
+               origDate={s. X}]
+\DeclareWitness{cS}{S}{\emph{Laurentianus} R 33}[
+               origDate={s. X}]
+\DeclareWitness{cL}{L}{\emph{Londinensis} Br. Mus. 10084}[
+               origDate={s. XI}]
+\DeclareWitness{cN}{N}{\emph{Neapolitanus} IV, c. 11}[
+               origDate={s. XII}]
+\DeclareWitness{cT}{T}{\emph{Parisinus Lat.} 5764}[
+               origDate={s. XI}]
+\DeclareWitness{cf}{\emph{f}}{\emph{Vindobonensis} 95}[
+               origDate={s. XII}]
+\DeclareWitness{cU}{U}{\emph{Vaticanus Lat.} 3324}[
+               origDate={s. XI}]
+\DeclareWitness{cl}{\emph{l}}{\emph{Laurentianus} Riccard. 541}[
+               origDate={s. XI--XII}]
+
+\DeclareShorthand{ca}{α}{cA,cM,cB,cR,cS,cL,cN}
+\DeclareShorthand{cb}{β}{cT,cf,cU,cl}
 \end{filecontents}
 \documentclass{ltxdoc}
 \usepackage[letterpaper,margin=25mm,left=50mm,nohead]{geometry}
@@ -134,7 +191,7 @@ along with this program.  If not, see
 \doxitem{Option}{option}{options}
 \usepackage{microtype}
 \usepackage[no-math]{fontspec}
-\usepackage[greek.ancient,american]{babel}
+\usepackage[latin.classic,greek.ancient,american]{babel}
 \babelfont{rm}[
    SlantedFont={Old Standard},
    SlantedFeatures={FakeSlant=0.25},
@@ -154,17 +211,25 @@ along with this program.  If not, see
 \def\sg#1{\textancientgreek{#1}}
 \usepackage[Old Standard]{mathfont}
 \usepackage{arabluatex}
-\usepackage[teiexport=tidy]{ekdosis}
+\usepackage[parnotes=roman,teiexport=tidy]{ekdosis}
 \input{ekdosis-cfg}
 \usepackage{xltabular}
 \usepackage[prevent-all]{widows-and-orphans}
 \usepackage[shortcuts,nospacearound]{extdash}
 \usepackage[american]{isodate}
+\usepackage{nextpage}
+\usepackage{spacingtricks}
 \usepackage{csquotes}
+\usepackage{relsize}
 \usepackage{enumitem}
 \setlist{nosep}
 \setlist[itemize]{label=\textendash}
 \setlist[enumerate,1]{label=(\alph*)}
+\newlist{remarks}{enumerate}{10}
+\setlist[remarks]{
+  label*=\textsc{Rem.} \arabic*,
+  left=0.25in,
+  before=\smaller}
 \usepackage{manfnt}
 \usepackage{lettrine}
 \newcommand\danger{\lettrine[loversize=-.5]{\textdbend}{\hskip6pt}}
@@ -189,6 +254,8 @@ along with this program.  If not, see
 \labelformat{subsection}{sect.~#1}
 \labelformat{subsubsection}{sect.~#1}
 \labelformat{figure}{fig.~#1}
+\newcounter{dummy}
+\newcommand{\dummy}{\refstepcounter{dummy}}
 \usepackage[nospace,american]{varioref}
 \usepackage[style=ext-verbose-inote]{biblatex}
 \usepackage[symbolpackage=tikz]{biblatex-ext-oa}
@@ -263,28 +330,28 @@ along with this program.  If not, see
 \renewcommand\cftlolprehook{\begin{multicols}{2}}
 \renewcommand\cftlolposthook{\end{multicols}}
 \renewcommand\cftloltitlefont{\Large\bfseries}
-\usepackage{relsize}
 \usepackage{units}
+\newcommand*\tred[1]{\textcolor{red}{#1}}
 \usepackage{fbox}
 \usepackage{tikz}
 \usetikzlibrary{tikzmark}
 \NewDocumentCommand{\pointto}{m}{%
-  \tikz[remember picture] \draw[>->,color=blue,overlay] (1em,0.5ex) to
+  \tikz[remember picture] \draw[>->,color=blue,overlay] (0em,0.5ex) to
   ([shift={(0.5em,0pt)}]pic cs:#1);%
   \tikz[remember picture] \draw[color=gray, overlay]
   ([shift={(0.5em,0.5ex)}]pic cs:#1) circle [radius=8pt];}
-\NewDocumentCommand{\pointtor}{m}{%
-  \tikz[remember picture] \draw[>->,color=blue,overlay] (1em,0.5ex) to
+\NewDocumentCommand{\pointtol}{m}{%
+  \tikz[remember picture] \draw[>->,color=blue,overlay] (0em,0.5ex) to
   [bend left] ([shift={(0.5em,0pt)}]pic cs:#1);%
   \tikz[remember picture] \draw[color=gray, overlay]
   ([shift={(0.5em,0.5ex)}]pic cs:#1) circle [radius=8pt];}
-\NewDocumentCommand{\pointtol}{m}{%
-  \tikz[remember picture] \draw[>->,color=blue,overlay] (1em,0.5ex) to
+\NewDocumentCommand{\pointtor}{m}{%
+  \tikz[remember picture] \draw[>->,color=blue,overlay] (0em,0.5ex) to
   [bend right] ([shift={(0.5em,0pt)}]pic cs:#1);%
   \tikz[remember picture] \draw[color=gray, overlay]
   ([shift={(0.5em,0.5ex)}]pic cs:#1) circle [radius=8pt];}
-\NewDocumentCommand{\pointtoel}{m}{%
-  \tikz[remember picture] \draw[>->,color=blue,overlay] (1em,0.5ex) to
+\NewDocumentCommand{\pointtoer}{m}{%
+  \tikz[remember picture] \draw[>->,color=blue,overlay] (0em,0.5ex) to
   [bend right] ([shift={(0em,0pt)}]pic cs:#1);%
   \tikz[remember picture] \draw[color=gray, overlay]
   ([shift={(-0.5em,0.5ex)}]pic cs:#1) ellipse [x radius=45pt, y
@@ -547,14 +614,14 @@ along with this program.  If not, see
 % \label{sec:features}
 % A list of the main features of \pkg{ekdosis} follows:---
 % \begin{enumerate}
-% \item \emph{Multilingual critical editions\/}: \pkg{ekdosis} can
-%   be used to typeset any number of texts in any direction accepted
-%   by \hologo{LuaTeX}. Running paragraphs of text can be arranged in
-%   any number of columns, either on single or facing pages, which in
-%   turn can be synchronized or not. \pkg{ekdosis} is also
-%   suitable for complex layouts as in the case of Arabic poetry or
-%   images where three-way alignment is required, or diagrams,
-%   \emph{\&c}.
+% \item \label{it:multicol-feature}\emph{Multilingual critical
+%   editions\/}: \pkg{ekdosis} can be used to typeset any number of
+%   texts in any direction accepted by \hologo{LuaTeX}. Running
+%   paragraphs of text can be arranged in any number of columns,
+%   either on single or facing pages, which in turn can be
+%   synchronized or not. \pkg{ekdosis} is also suitable for complex
+%   layouts as in the case of Arabic poetry or images where three-way
+%   alignment is required, or diagrams, \emph{\&c}.
 % \item \emph{Apparatus criticus\/}: Edited texts can receive multiple
 % layers of apparatus, e.g.\ apparatus criticus (to record variant
 % readings), apparatus fontium (to collect references to texts quoted
@@ -642,11 +709,11 @@ along with this program.  If not, see
 % the page, above the line, and naturally shows the accepted
 % readings. The margins are used for numeration. In the apparatus
 % criticus, below the line, reference to the text is made by
-% specifying the number of the line and if several items refer to the
-% same line, numbers are not repeated. Instead, items are separated
-% from one another by a broad horizontal space. Finally, a square
-% bracket is used inside items to distinguish the lemma from the
-% variant readings.
+% specifying the number of the line and if several entries refer to
+% the same line, numbers are not repeated. Instead, entries are
+% separated from one another by a broad horizontal space. Finally, a
+% square bracket is used inside entries to distinguish the lemma from
+% the variant readings.
 %
 % Furthermore, as said above, if a \texttt{TEI xml} output is
 % required, \pkg{ekdosis} compiles an additional |.xml| file an
@@ -702,7 +769,7 @@ along with this program.  If not, see
 % \danger It must be noted that the two styles are mutually exclusive.
 % \vskip\baselineskip
 % 
-% \DescribeOption{parnotes}\label{ref:parnotes-opt}
+% \DescribeOption{parnotes}\dummy\label{ref:parnotes-opt}
 % |parnotes|$=$\verb+true|false|roman+%
 % \hfill\tcboxverb{Default: not set}\\
 % This named argument does not need a value as it defaults to |true|
@@ -919,7 +986,10 @@ along with this program.  If not, see
 % 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 theses witnesses have been already declared, here
-% is how the two families α  and β could be declared:---
+% is how the two families α  and β could be
+% declared:---\footnote{These witnesses are used in the example
+% provided below in \vref{lst:caesar-bg}.}
+% \dummy\label{ref:caesar-bg-sigla}
 % \iffalse
 %<*example>
 % \fi
@@ -995,7 +1065,7 @@ along with this program.  If not, see
 % \ref{sec:declarations}
 % \vpagerefrange{sec:declarations}{sec:declarations-end}, the \cs{app}
 % command is used for inserting entries in the apparatus criticus,
-% either, lemmas, readings or notes, like so:---
+% either lemmata, readings or notes, like so:---
 % \iffalse
 %<*example>
 % \fi
@@ -1023,22 +1093,138 @@ yesterday.
 % quoted or cited in the text of the edition (\emph{apparatus
 % fontium}), references to testimonia, or quotations of the edited
 % text by other authors (\emph{apparatus testium}), explanatory notes,
-% and so forth.\footnote{See below, \vpageref{ref:type-app}.} Once
+% and so forth.\footnote{See below, \vref{ref:type-app}.} Once
 % additional layers have been defined and assigned to new
 % \enquote*{types}, such as \enquote*{testium} and the like, these
 % types can be used as values appended to the |type| \enquote*{named
 % option}.
 %
-% \paragraph{Readings} As can be seen in the example above, there are
-% two kinds of individual readings: the \emph{lemma}, which contains
-% the base text accepted by the editor, and the \emph{reading}, which
-% contains deviant readings rejected by the editor.
+% \paragraph{Base text and variants} As can be seen in the example
+% above, there are two kinds of individual readings: the \emph{lemma},
+% which contains the base text accepted by the editor, and the
+% \emph{reading}, which contains deviant readings rejected by the
+% editor.
 %
-% \paragraph{Lemmas} \DescribeMacro{\lem}
-% \cs{lem}\oarg{options}\marg{lemma text}
+% \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
+% be authentic or authoritative, \cs{lem} prints it by default both in
+% the edition text and as the first part of a new entry in the
+% apparatus criticus, preceded by the line number where it occurs or a
+% broad space if the entry refers to the same line as the preceding
+% entry. The optional argument of \cs{lem} accepts the following
+% comma-separated list of \enquote{name$=$value} arguments:---\\
+% \DescribeOption{wit} |wit|$=$\meta{csv list of witnesses}\\
+% While a single witness may be recorded as in |wit=A|,
+% comma-separated lists of multiple witnesses must obviously be
+% enclosed in curly braces, like so:
+% |wit={A,B,C}|. \dummy\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}|.\\
+% \label{ref:lem-opts-b}
+% \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,
+% \meta{alternate lemma}, if specified, supersedes what is printed in
+% the related unit of the apparatus criticus. This mechanism is useful
+% in more than one respect. For instance, it can be used to insert
+% abbreviated lemmata in the apparatus criticus, or to introduce an
+% alternate way of writing entries with Latin technical terms in the
+% apparatus criticus as will be demonstrated below in the example
+% provided by \vref{lst:pj2}.\\
+% \DescribeOption{sep} |sep|$=$\meta{separator}\\
+% |sep| allows to change the symbol used to separate the lemma text
+% from deviant readings, which is by default the closing square
+% bracket (|]|)\\
+% \DescribeOption{nosep} |nosep|$=$\verb+true|false+\\
+% This named argument does not need a value as it defaults to |true|
+% if it is used. Obviously, |nosep| removes the separator mentioned
+% above.\\
+% \DescribeOption{nolem} |nolem|$=$\verb+true|false+\\
+% This named argument does not need a value as it defaults to |true|
+% if it is used. |nolem| completely removes the lemma text from the
+% related
+% entry in the apparatus criticus.\\
+% \DescribeOption{type} |type|$=$\meta{value}\\
+% This named argument has no effect on the apparatus criticus of the
+% 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.
 %
-% \begin{comment}
-% \captof{The \enquote{Peter/John} full example}
+% Finally, four named arguments can be used to insert words at the
+% following specific places in the lemma text:\\
+% \noindent
+% \fparbox*{\centered{\textbf{1} \tikzmark{pre}\tred{pre} Peter
+% \tikzmark{post}\tred{post} \tikzmark{prewit}\tred{prewit}
+% \getsiglum{pjA}
+% \tikzmark{postwit}\tred{postwit}] John \getsiglum{pjB}}}\\
+% \DescribeOption{pre} |pre|$=$\meta{words}\pointtol{pre}\\
+% |pre| inserts \meta{words} \emph{before} the lemma text.\\
+% \DescribeOption{post} |post|$=$\meta{words}\pointto{post}\\
+% |post| inserts \meta{words} \emph{after} the lemma text.\\
+% \DescribeOption{prewit} |prewit|$=$\meta{words}\pointto{prewit}\\
+% |prewit| inserts \meta{words} \emph{before} the list of witnesses.\\
+% \DescribeOption{postwit} |postwit|$=$\meta{words}\pointtor{postwit}\\
+% |postwit| inserts \meta{words} \emph{after} the list of witnesses.
+% \label{ref:lem-opts-e}
+%
+% \paragraph{Readings} \DescribeMacro{\rdg}
+% \cs{rdg}\oarg{options}\marg{variant reading}\\
+% As \meta{reading} is a word or a phrase judged by the editor to be
+% unsatisfactory or corrupted, \cs{rdg} prints it by default in the
+% last part of the corresponding entry in the apparatus criticus,
+% after the symbol that is used to separate words of the base text
+% (the lemma text) from words rejected by the editor.  The optional
+% argument of \cs{rdg} accepts a comma-separated list of
+% \enquote{name$=$value} arguments that is almost identical to
+% \cs{app}. Therefore, emphasis will be placed here only on the
+% differences. The reader is invited to refer to the description
+% provided above \vpagerefrange{ref:lem-opts-b}{ref:lem-opts-e} for
+% more detailed information:---\\
+% \DescribeOption{wit} |wit|$=$\meta{csv list of witnesses}\\
+% \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}\\
+% \DescribeOption{pre} |pre|$=$\meta{words}\\
+% \DescribeOption{post} |post|$=$\meta{words}\\
+% \DescribeOption{prewit} |prewit|$=$\meta{words}\\
+% \DescribeOption{postwit} |postwit|$=$\meta{words}\\
+%
+% \paragraph{Notes}
+% \DescribeMacro{\note}\DescribeMacro{\note*}
+% \cs{note}\oarg{options}\marg{text} or
+% \cs{note*}\oarg{options}\marg{text}\\
+% It may happen that editorial notes be needed to record short
+% comments of general nature \emph{between} lemmata and
+% readings. \cs{note} inserts inline comments while \cs{note*} places
+% comments below the entire apparatus block. Furthermore, if
+% \pkg{ekdosis} has been loaded with the |parnotes| option as
+% described above \vpageref{ref:parnotes-opt}, \cs{note*} will use the
+% \pkg{parnotes} package to lay out the notes as an additional
+% paragraph below the apparatus criticus. The optional argument of
+% \cs{note}/\cs{note*} accepts the following comma-separated list of
+% \enquote{name$=$value}
+% arguments:---\\
+% \DescribeOption{pre} |pre|$=$\meta{words}\\
+% |pre| inserts \meta{words} immediately before the note.\\
+% \DescribeOption{post} |post|$=$\meta{words}\\
+% |post| inserts \meta{words} immediately after the note.\\
+%
+% \danger Under no circumstances is it permitted to insert the command
+% \cs{note} or \cs{note*} inside the argument of \cs{lem} or
+% \cs{rdg}. \cs{note}/\cs{note*} must go \emph{between} these
+% commands. As a general rule, within \cs{app}|{}| elements, notes
+% are inserted immediately \emph{after} the lemma or the variant
+% reading they are related to.
+%
+% \Vref{lst:pj2} provides an illustration of some of the possibilities
+% afforded by the commands just described:---
+%
+% \captof{The \enquote{Peter/John} full example}[\label{lst:pj2}]
 % \iffalse
 %<*example>
 % \fi
@@ -1061,18 +1247,20 @@ yesterday.
   \app{
     \lem[wit=A, alt={How nice... said}]{\enquote{How nice to find
         you here!} he said.}
+    \note*{There are no quotation marks in the mss.}
     \rdg[wit=B, alt=\emph{om.}]{}}
   I chuckled to myself, recalling the last time we
   \app{
     \lem[wit=A,nolem]{met}
     \rdg[wit=B, alt={\emph{post} met \emph{add.} there}]{met
-      there}}.
+      there}
+    \note*{Ms. B provides other additions of this kind.}}.
 \end{ekdosis}
 \end{minted}
 % \iffalse
 %</example> 
 % \fi
-% 
+% \resetlinenumber
 % \begin{alignment}[tcols=1,texts=specimen,apparatus=specimen]
 %   \begin{specimen}
 %     I \app{\lem[wit=pjA]{saw}\rdg[wit=pjB]{met}} my friend
@@ -1088,18 +1276,282 @@ yesterday.
 %     \app{
 %     \lem[wit=pjA, alt={\textooquote How nice... said}]{\enquote{How
 %     nice to find you here!} he said.}
+%     \note*{There are no quotation marks in the mss.}
 %     \rdg[wit=pjB, alt=\emph{om.}]{}}
 %     I chuckled to myself, recalling the last time we
 %     \app{
 %     \lem[wit=pjA,nolem]{met}
 %     \rdg[wit=pjB, alt={\emph{post} met \emph{add.} there}]{met
-%     there}}.
+%     there}
+%     \note*{Ms. B provides other additions of this kind.}}.
 %   \end{specimen}
 % \end{alignment}
-% \end{comment}
+%
+% \begin{remarks}
+% \item Close examination of lines~17--8 from \vref{lst:pj2} shows how
+%   |alt| has been used to insert an abbridged lemma text in the
+%   apparatus criticus in print while keeping safe what is to be found
+%   in the \texttt{TEI xml} output.
+% \item The same technique has been used at line~24 to insert
+%   alternate words, including Latin technical terms, in place of the
+%   variant reading. Hence the use of |nolem| at line~23 to remove the
+%   lemma text from the apparatus criticus in print.
+% \item \cs{note*} has been used to insert short annotations in two
+%   places (ll.~19 and 26).
+% \item For an example of the use of |nordg|, see below
+% \vref{lst:caesar-bg}, l.~11.
+% \end{remarks}
+%
+% The corresponding \texttt{TEI xml} output produced by \pkg{ekdosis}
+% from the \LaTeX{} source file follows:---
 % 
+% \captof{The \enquote{Peter/John} full example: \texttt{TEI xml}
+% output}[\label{lst:pj2-tei}]
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<p>I 
+<app>
+  <lem wit="#A">saw</lem>
+  <rdg wit="#B">met</rdg>
+</app>my friend 
+<app>
+  <lem>Peter</lem>
+  <rdg>John</rdg>
+</app>at the station yesterday. We were both in a 
+<app>
+  <lem wit="#A">great</lem>
+  <rdg wit="#B">good</rdg>
+</app>mood. 
+<app>
+  <lem wit="#A">
+  <quote>How nice to find you here!</quote> he said.</lem>
+  <note>There are no quotation marks in the mss.</note>
+  <rdg wit="#B" />
+</app>I chuckled to myself, recalling the last time we 
+<app>
+  <lem wit="#A">met</lem>
+  <rdg wit="#B">met there</rdg>
+  <note>Ms. B provides some further additions of this
+  kind.</note>
+</app>.</p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \section{Alignment of Parallel Texts}
+% \label{sec:alignment-basic}
+% As already said above,\footnote{See point
+% \vref{it:multicol-feature}.} \pkg{ekdosis} can arrange sundry texts
+% in parallel columns\---synchronized or not\---either on the same
+% page or on facing pages. Depending on what is needed, any text can
+% be equipped with an apparatus criticus. The most common example is
+% that of an edition of a classical text with an apparatus criticus
+% accompanied by a translation into a modern language on the facing
+% page. One can also imagine an edition of two classical texts or two
+% different recensions of the same text, each of which provides
+% variants recorded in separate apparatus crititus, laid out on the
+% left-hand pages, with one or more translations on the corresponding
+% right-hand pages, and so forth.
+%
+% \paragraph{The \env{alignment} Environment}
+% \DescribeEnv{alignment} \cs{begin}|{alignment}|\oarg{options}\dots
+% \cs{end}|{alignment}|\\
+% This environment can be used as it is provided to typeset a standard
+% critical edition, namely an edition text, equipped with an apparatus
+% criticus and laid out on the left-hand pages, accompanied by a
+% translation into a modern language on the facing pages.
+%
+% \DescribeEnv{edition}\DescribeEnv{translation} Within
+% \env{alignment}, two environments are available by default:
+% \cs{begin}|{edition}|\dots \cs{end}|{ed|\allowbreak|ition}| and
+% \cs{begin}|{translation}|\dots \cs{end}|{translation}|. Obviously,
+% the former is used to typeset the edition text with an apparatus
+% criticus on the left, while the latter is used to typeset the
+% translation on the right, like so:---
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\begin{alignment}
+  \begin{edition}
+    First § of the edition text.
+  \end{edition}
+  \begin{translation}
+    First § of the translation.
+  \end{translation}
+  \begin{edition}
+    Second § of the edition text.
+  \end{edition}
+  \begin{translation}
+    Second § of the translation.
+  \end{translation}
+\end{alignment}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \DescribeEnv{edition*}\DescribeEnv{translation*} Furthermore,
+% so-called \enquote{starred} versions of these environments can be
+% used at any point to synchronize texts, that is to print them in
+% such a way that the tops of all paragraphs are vertically
+% aligned. To that effect, it must be noted that merely applying this
+% command on a single environment\---for instance the leftmost
+% one\---will have all other associated paragraphs printed aligned.
+%
+% \danger While the whole edition text and the whole translation can
+% be inserted in a single \env{edition}/\env{translation} environment
+% respectively, it is recommended to enter both texts paragraph by
+% paragraph as shown in the example above. Not only this method of
+% encoding allows not to lose sight of paragraphs that are meant to be
+% read together, but it is also the only way to align paragraphs in
+% print, and it is much more suitable to mark up correspondence
+% between spans of texts as will be demonstrated below in
+% \vref{ref:segmentation}.
+%
+% As an illustration, a short extract of Caesar's \emph{Gallic War},
+% VI, XIII.1 follows.\footnote{Latin text: \cite{Caesar-BG-v2};
+% English translation: \cite{CaesarTr}.} See the list of sigla for
+% manuscripts and manuscript families above
+% \vpageref{ref:caesar-bg-sigla}. As this document is not set for
+% duplex printing, both texts have been put together on the same
+% page:---
+%
+% \captof{Caesar's \emph{Gallic War}, VI, 13.1}[\label{lst:caesar-bg}]
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+\begin{alignment}
+  \begin{edition}
+    \ekddiv{head=XIII, depth=2, n=6.13, type=section}
+    In omni Gallia eorum hominum qui \app{
+      \lem[wit=a]{aliquo}
+      \rdg[wit=b, alt=in al-]{in aliquo}}
+    sunt numero atque honore genera sunt duo. Nam plebes paene
+    seruorum habetur loco, quae \app{
+      \lem[wit={A,M}, alt={nihil audet (aut et \getsiglum{A1})
+        per se}]{nihil audet per se}
+      \rdg[wit=A1,nordg]{nihil aut et per se}
+      \rdg[wit={R,S,L,N}]{nihil habet per se}
+      \rdg[wit=b]{per se nihil audet}}, \app{
+      \lem[wit=a]{nullo}
+      \rdg[wit=b]{nulli}} adhibetur \app{
+      \lem{consilio}
+      \rdg[wit={T, U}, alt=conc-]{concilio}}.
+  \end{edition}
+  \begin{translation}
+    \ekddiv{head=XIII, depth=2, n=6.13, type=section}
+      Throughout all Gaul there are two orders of those men who are of
+      any rank and dignity: for the commonality is held almost in the
+      condition of slaves, and dares to undertake nothing of itself,
+      and is admitted to no deliberation.
+  \end{translation}
+\end{alignment}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \resetlinenumber
+% \ekdfmtdiv{2}{}{.}
+% \begin{alignment}[lcols=2,
+%                   texts=edition[xml:lang="la"];
+%                   translation[xml:lang="en"]]
+% \AtBeginEnvironment{edition}{\selectlanguage{latin}}
+% \AtBeginEnvironment{translation}{\selectlanguage{american}}
+%   \begin{edition}
+%     \ekddiv{head=XIII, depth=2, n=6.13, type=section}
+%     In omni Gallia eorum hominum qui \app{
+%       \lem[wit=ca]{aliquo}
+%       \rdg[wit=cb, alt=in al-]{in aliquo}}
+%     sunt numero atque honore genera sunt duo. Nam plebes paene
+%     seruorum habetur loco, quae \app{
+%       \lem[wit={cA,cM}, alt={nihil audet (aut et \getsiglum{cA1})
+%         per se}]{nihil audet per se}
+%       \rdg[wit=cA1,nordg]{nihil aut et per se}
+%       \rdg[wit={cR,cS,cL,cN}]{nihil habet per se}
+%       \rdg[wit=cb]{per se nihil audet}}, \app{
+%       \lem[wit=ca]{nullo}
+%       \rdg[wit=cb]{nulli}} adhibetur \app{
+%       \lem{consilio}
+%       \rdg[wit={cT, cU}, alt=conc-]{concilio}}.
+%   \end{edition}
+%   \begin{translation}
+%     \ekddiv{head=XIII, depth=2, n=6.13, type=section}
+%       Throughout all Gaul there are two orders of those men who are of
+%       any rank and dignity: for the commonality is held almost in the
+%       condition of slaves, and dares to undertake nothing of itself,
+%       and is admitted to no deliberation.
+%   \end{translation}
+% \end{alignment}
+%
+% \begin{remarks}
+% \item As can be seen from the apparatus entry related to l.~4 above,
+%   a subvariant has been inserted in the lemma part: \enquote{(aut et
+%   \getsiglum{cA1})}. This was done by using |alt| in
+%   \vref{lst:caesar-bg}, l.~9. But as this variant is already
+%   recorded\---and printed\---in the lemma part, it was necessary to
+%   remove the entire otherwise redundant variant from the apparatus
+%   criticus in print. Hence the use of |nordg| at l.~11.
+% \item For examples of abbreviations, see ll.~6 and 17.
+% \item Line~17 shows how mss.\ T and U (which belong to two distinct
+%   subfamilies) have been separated from one another: %
+%   \verb*+wit={T, U}+. See above \vpageref{ref:mss-sep-families} for
+%   more information on this technique.
+% \end{remarks}
+%
+% Finally, the corresponding \texttt{TEI xml} output follows:---
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<div xml:id="div-edition_1" xml:lang="la">
+  <div type="section" n="6.13">
+    <head>XIII</head>
+    <p>In omni Gallia eorum hominum qui 
+    <app>
+      <lem wit="#A #M #B #R #S #L #N">aliquo</lem>
+      <rdg wit="#T #f #U #l">in aliquo</rdg>
+    </app>sunt numero atque honore genera sunt duo. Nam
+    plebes paene seruorum habetur loco, quae 
+    <app>
+      <lem wit="#A #M">nihil audet per se</lem>
+      <rdg wit="#A1">nihil aut et per se</rdg>
+      <rdg wit="#R #S #L #N">nihil habet per se</rdg>
+      <rdg wit="#T #f #U #l">per se nihil audet</rdg>
+    </app>, 
+    <app>
+      <lem wit="#A #M #B #R #S #L #N">nullo</lem>
+      <rdg wit="#T #f #U #l">nulli</rdg>
+    </app>adhibetur 
+    <app>
+      <lem>consilio</lem>
+      <rdg wit="#T #U">concilio</rdg>
+    </app>.</p>
+  </div>
+</div>
+<div xml:id="div-translation_1" xml:lang="en">
+  <div type="section" n="6.13">
+    <head>XIII</head>
+    <p>Throughout all Gaul there are two orders of those men
+    who are of any rank and dignity: for the commonality is
+    held almost in the condition of slaves, and dares to
+    undertake nothing of itself, and is admitted to no
+    deliberation.</p>
+  </div>
+</div>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
 % \section{To be continued...}
 % \label{ref:type-app}
+% \label{ref:segmentation}
 % 
 % \section{GNU Free Documentation License}
 % \label{sec:fdl}