done documenting alignment environment

1 files changed, 175 insertions, 2 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 40ed894..0bccdfe 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -340,6 +340,7 @@ along with this program.  If not, see
 \metawritepdfcontact
 \metawritepdfrights
 \usepackage{multicol}
+\setlength\IndexMin{100pt}
 \usepackage{tocloft}
 \newlistof{listing}{lol}{List of listings}
 \renewcommand\cfttocprehook{\begin{multicols}{2}}
@@ -375,7 +376,7 @@ along with this program.  If not, see
   ([shift={(-0.5em,0.5ex)}]pic cs:#1) ellipse [x radius=45pt, y
   radius=6pt];}
 \usepackage[breakable, skins, xparse]{tcolorbox}
-\tcbset{colback=white, boxrule=.15mm, colframe=cinnamon,
+\tcbset{colback=white, boxrule=0.4pt, colframe=cinnamon,
   breakable}
 \usepackage[newfloat]{minted}
 \labelformat{listing}{listing~#1}
@@ -1382,7 +1383,7 @@ yesterday.
 %
 % \paragraph{The \env{alignment} Environment}
 % \DescribeEnv{alignment} \cs{begin}|{alignment}|\oarg{options}\dots
-% \cs{end}|{alignment}|\\
+% \cs{end}|{alignment}|\dummy\label{ref:alignment-syntax}\\
 % 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
@@ -1573,6 +1574,178 @@ yesterday.
 %</example>
 % \fi
 %
+% \subsection{Alignment of Several Texts}
+% \label{sec:multiple-alignment}
+% As described above \vpageref{ref:alignment-syntax}, the
+% \env{aligment} environment may receive an optional argument in which
+% the following \enquote{name$=$value} arguments are accepted:---\\
+% \DescribeOption{tcols}
+% |tcols|$=$\meta{number}\hfill\tcboxverb{Default: 2}\\
+% |tcols| stores the \underLine{t}otal number of
+% \underLine{col}umn\underLine{s} of text to be aligned.\\
+% \DescribeOption{lcols}
+% |lcols|$=$\meta{number}\hfill\tcboxverb{Default: 1}\\
+% |lcols| stores the number of \underLine{col}umn\underLine{s} to be
+% printed on the \underLine{l}eft-hand page, \emph{out of the total
+% number} of columns specified with |tcols|. As can be seen from the
+% preceding two default values, \env{alignment} initially sets two
+% columns of text on facing pages. Of course, for this setting to work
+% properly, one must ensure that the \env{alignment} environment is
+% started on a
+% left page.\\
+% \DescribeOption{texts}
+% |texts|$=$\meta{\underLine{semicolon}-separated
+% values}\hfill\tcboxverb{Default: edition;translation}\\
+% Depending on the total number of columns that has been specified
+% with |tcols| above, |texts| is then used to define the names of the
+% environments that shall receive edition texts, translations,
+% \emph{\&c.} Some very important points need to be emphasized in this
+% respect:---
+% \begin{enumerate}
+% \item Only unaccented letters of the alphabet (whatever the case)
+%   are allowed to compose the names of \LaTeX{} environments.
+% \item These names must be separated from one another by
+%   \emph{semicolons}, as shown in red in the listing below at the end
+%   of lines~1 and 2.
+%   \begin{enumerate}
+%   \item[\dbend] The colon at the end of line~3 closes the whole
+%     value of |text| and acts as a higher level separator.
+%   \end{enumerate}
+% \item Each name may be followed by a \enquote*{suboptional} argument
+%   between square brackets which will then be used to insert
+%   \texttt{TEI xml} attributes in the corresponding |<div>|
+%   element. For example,
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[escapeinside=++]{latex}
+texts=latin[xml:lang="la"]+\textcolor{red}{;}+
+      english[xml:lang="en"]+\textcolor{red}{;}+
+      french[xml:lang="fr"]+\textcolor{red}{,}+
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+% will be converted into \texttt{TEI xml} as follows:---
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<div xml:id="div-latin_1" xml:lang="la">
+...
+</div>
+<div xml:id="div-english_1" xml:lang="en">
+...
+</div>
+<div xml:id="div-french_1" xml:lang="fr">
+...
+</div>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%   \begin{enumerate}
+%   \item[\dbend] As can be seen, \pkg{ekdosis} takes care of
+%     computing and inserting the |xml:id| attributes which are
+%     therefore not accepted in the \enquote*{suboptional} arguments
+%     of |texts|.
+%   \end{enumerate}
+% \item The names of the environments must be specified in exactly the
+%   same order as they are supposed to appear in the print edition,
+%   from left to right.
+% \end{enumerate}
+% \DescribeOption{apparatus}
+% |apparatus|$=$\meta{\underLine{semicolon}-separated
+% values}\hfill\tcboxverb{Default: edition}\\
+% Then, the |apparatus| option, just as |texts|, takes a
+% \underLine{semicolon}-separated list of previously defined
+% environments that shall receive at least one layer of apparatus
+% criticus.\\
+% \DescribeOption{paired} |paired|$=$\verb+true|false+%
+% \hfill\tcboxverb{Default: true (initially not set)}\\
+% This named argument does not need a value as it defaults to |true|
+% if it is used. By default, \pkg{ekdosis} follows the \LaTeX{} page
+% numbering scheme when multiple texts are arranged on facing
+% pages. The |paired| option leaves every right-hand page number
+% unchanged, so that both facing pages hold the same page number.\\
+% \DescribeOption{lineation} |lineation|$=$\verb+page|document+
+% \hfill\tcboxverb{Default: document}\\
+% This option applies to edition texts initially set to receive an
+% apparatus criticus. By default, lines are continuously numbered
+% throughout the document. |lineation=page| sets the numbering to
+% start afresh at the top of each page.\\
+% \DescribeOption{flush} |flush|$=$\verb+true|false+
+% \hfill\tcboxverb{Default: false}\\
+% This named argument does not need a value as it defaults to |true|
+% if it is used. This option applies on rare occasions only, when two
+% or more distinct \env{aligment} environments are started on the same
+% page. Should this happen, any subsequent \env{alignment} environment
+% must be set with the |flush| option so that every one of them carry
+% its own apparatus criticus.
+%
+% As an example, the alignment of the Latin edition text of Caesar's
+% \emph{Gallic War}, printed on left-hand pages, along with two
+% translations into English and French, printed on right-hand pages,
+% can be set as follows:---
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\begin{alignment}[tcols=3,
+                  lcols=1,
+                  texts=latin[xml:lang="la"];
+                        english[xml:lang="en"];
+                        french[xml:lang="fr"],
+                  apparatus=latin,
+                  lineation=page]
+  \begin{latin}
+    Gallia est omnis divisa in partes tres quarum unam incolunt
+    Belgae, [...]
+  \end{latin}
+  \begin{english}
+    All Gaul is divided into three parts, one of which the Belgae
+    inhabit, [...]
+  \end{english}
+  \begin{french}
+    L'ensemble de la Gaule est divisé en trois parties: l'une est
+    habitée par les Belges, [...]
+  \end{french}
+\end{alignment}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \DescribeMacro{\SetEkdosisAlignment}
+% \cs{SetEkdosisAlignment}\marg{alignment settings}\\
+% If the same aligment settings are to be shared by several
+% \env{alignment} environments, common settings can be collected in
+% the argument of \cs{SetEkdosisEnvironment}, like
+% so:---\\
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\SetEkdosisAlignment{
+  tcols=3,
+  lcols=1,
+  texts=latin[xml:lang="la"];
+        english[xml:lang="en"];
+        french[xml:lang="fr"],
+  apparatus=latin,
+  lineation=page
+}
+\begin{alignment}
+  ...
+\end{alignment}
+\end{minted}
+% \iffalse
+%<æxample>
+% \fi
+%
+% \cs{SetEkdosisAlignment} can be used either in the preamble or at
+% any point of the document to set or to modify alignment settings.
+%
 % \section{Multiple-Layer Apparatus Criticus}
 % \label{sec:multilayer-apparatus}
 %