summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/lualatex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2020-08-14 20:27:05 +0000
committerKarl Berry <karl@freefriends.org>2020-08-14 20:27:05 +0000
commit5362413c4d74031afac3641a2d24f6861d526603 (patch)
tree4e722daf3556d6a5fddb279145eafe35e51bd84e /Master/texmf-dist/source/lualatex
parent5b313a5debf8920a9aa91d9f332d49245bc5e7cf (diff)
ekdosis (14aug20)
git-svn-id: svn://tug.org/texlive/trunk@56112 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/lualatex')
-rw-r--r--Master/texmf-dist/source/lualatex/ekdosis/Makefile45
-rw-r--r--Master/texmf-dist/source/lualatex/ekdosis/ekdosis.dtx3452
2 files changed, 3250 insertions, 247 deletions
diff --git a/Master/texmf-dist/source/lualatex/ekdosis/Makefile b/Master/texmf-dist/source/lualatex/ekdosis/Makefile
index b57cb54116f..550ae95d129 100644
--- a/Master/texmf-dist/source/lualatex/ekdosis/Makefile
+++ b/Master/texmf-dist/source/lualatex/ekdosis/Makefile
@@ -6,51 +6,43 @@ VERS = $(shell ltxfileinfo -v $(NAME).dtx|sed -e 's/^v//')
LOCAL = $(shell kpsewhich --var-value TEXMFLOCAL)
UTREE = $(shell kpsewhich --var-value TEXMFHOME)
HOMEDIR := $$HOME
+SAMPLES := samples
exts := md html ins dtx el
-texsamples := $(basename $(wildcard $(PWD)/samples/*.tex))
-texsamplesout := $(notdir $(basename $(wildcard $(PWD)/samples/*.tex)))
findopts := $(foreach ext,$(exts),-or -iname "*.$(ext)")
-define dosamples
- $(CMP) --output-dir=$(PWD)/TMP --shell-escape $1 >/dev/null
- $(CMP) --output-dir=$(PWD)/TMP --shell-escape $1 >/dev/null
- $(CMP) --output-dir=$(PWD)/TMP --shell-escape $1 >/dev/null
- $(CMP) --output-dir=$(PWD)/TMP --shell-escape $1 >/dev/null
-endef
-
all: sty $(NAME).pdf
+testsamples:
+ if [ ! -d $(SAMPLES) ] ; \
+ then echo "$(SAMPLES)/ directory is needed. Aborting." && exit 1 ; \
+ fi
+
sty: clean
$(CMP) $(NAME).ins >/dev/null
-$(NAME).pdf: $(NAME).dtx
- @ echo "Make the sample files first..."
- if [ ! -d $(PWD)/TMP ]; then mkdir $(PWD)/TMP; fi
- $(foreach file,$(texsamples), $(call dosamples, $(file)))
- mv TMP/*.pdf samples/
- mv $(texsamplesout)-tei.xml samples/
- @ echo "Build the documentation of $(NAME)..."
- $(CMP) --shell-escape -recorder -interaction=batchmode $(NAME).dtx >/dev/null
+$(NAME).pdf: testsamples $(NAME).dtx
+ @ echo "Making the sample files first..."
+ $(MAKE) --directory=$(SAMPLES)
+ @ echo "Building the documentation of $(NAME)..."
+ $(CMP) --shell-escape --recorder --interaction=batchmode $(NAME).dtx >/dev/null
biber $(NAME) >/dev/null
- if [ -f $(NAME).glo ]; then makeindex -q -s gglo.ist -o $(NAME).gls $(NAME).glo; fi
- if [ -f $(NAME).idx ]; then makeindex -q -s gind.ist -o $(NAME).ind $(NAME).idx; fi
$(CMP) --shell-escape --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
$(CMP) --shell-escape --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
$(CMP) --shell-escape --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
$(CMP) --shell-escape --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
+ if [ -f $(NAME).glo ]; then makeindex -q -s gglo.ist -o $(NAME).gls $(NAME).glo; fi
+ if [ -f $(NAME).idx ]; then makeindex -q -s gind.ist -o $(NAME).ind $(NAME).idx; fi
$(CMP) --shell-escape --recorder --interaction=nonstopmode $(NAME).dtx > /dev/null
samples: clean sty
- if [ ! -d $(PWD)/TMP ]; then mkdir $(PWD)/TMP; fi
- $(foreach file,$(texsamples), $(call dosamples, $(file)))
- mv TMP/*{\.pdf,-tei\.xml} samples/
+ $(MAKE) --directory=$(SAMPLES)
-clean:
+clean: testsamples
rm -rf auto
rm -f $(NAME).bib $(PWD)/TMP/*.bib
rm -rf .backup
- find -iname "*~" -or -iname "*.pdf" | xargs rm -rf
+ find -iname "*~" -or -iname "*.pdf" -or -iname "*_out*.tex" | xargs rm -rf
find ./* -type f -iname "Makefile" $(findopts) > ls-R
find ./* -type f -iname "*.tex" | grep '/samples/' >> ls-R
rsync -aPr --files-from=ls-R . .backup
@@ -92,7 +84,7 @@ zip: all
package: distclean all
mkdir $(NAME)/
- cp Makefile README.md $(NAME).{ins,dtx,pdf} $(NAME)/
+ cp Makefile README.md $(NAME).{ins,dtx,pdf,el} $(NAME)/
cp -r samples/ $(NAME)/
mkdir -p tex/lualatex/$(NAME)/
cp *.lua *.sty tex/lualatex/$(NAME)/
@@ -106,4 +98,5 @@ package: distclean all
tar czf $(NAME)-$(VERS).tar.gz $(NAME).tds.zip $(NAME)/
rm -rf $(NAME)/
-.PHONY: all clean distclean inst local uninst install uninstall zip package samples
+.SILENT: testsamples
+.PHONY: all clean distclean inst local uninst install uninstall zip package samples testsamples
diff --git a/Master/texmf-dist/source/lualatex/ekdosis/ekdosis.dtx b/Master/texmf-dist/source/lualatex/ekdosis/ekdosis.dtx
index f2700aa972a..5eb4844caa0 100644
--- a/Master/texmf-dist/source/lualatex/ekdosis/ekdosis.dtx
+++ b/Master/texmf-dist/source/lualatex/ekdosis/ekdosis.dtx
@@ -61,9 +61,33 @@ along with this program. If not, see
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{ekdosis}
%<*package>
- [2020/07/08 v0.99a Typesetting TEI xml compliant critical editions]
+ [2020/08/14 v1.0 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},
@@ -121,16 +156,89 @@ along with this program. If not, see
{https://classicalstudies.org/scs-blog/donald-j-mastronarde/review-guidelines-encoding-critical-editions-library-digital-latin},
organization = {Society for Classical Studies}
}
+
+@Online{TBE,
+ author = {Van den Branden, Ron and Terras, Melissa and
+ Vanhoutte, Edward},
+ title = {TEI by Example},
+ urldate = {2020-08-04},
+ url = {http://www.teibyexample.org}
+}
+
+@Software{lineno,
+ title = {The Lineno package},
+ titleaddon = {Line numbers on paragraphs},
+ author = {Lück, Uwe and Böttcher, Stephan},
+ url = {http://www.ctan.org/pkg/lineno},
+ date = {2005-11-02},
+ version = {4.41}
+}
+
+@Software{polyglossia,
+ title = {The Polyglossia package},
+ titleaddon = {An alternative to babel for XeLaTeX and LuaLaTeX},
+ author = {Charette, François and Reutenauer, Arthur},
+ url = {http://www.ctan.org/pkg/polyglossia},
+ date = {2020-04-08},
+ version = {1.49}
+}
+
+@Software{babel,
+ title = {The Babel package},
+ titleaddon = {Multilingual support for Plain TeX or LaTeX},
+ author = {Bezos López, Javier and Braams, Johannes L.},
+ url = {http://www.ctan.org/pkg/babel},
+ date = {2020-07-13},
+ version = {3.47}
+}
+
+@Software{arabluatex,
+ title = {The Arabluatex package},
+ titleaddon = {ArabTeX for LuaLaTeX},
+ author = {Alessi, Robert},
+ url = {http://ctan.org/pkg/arabluatex},
+ date = {2020-03-23},
+ 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},
+ author = {Lagally, Klaus},
+ url =
+ {http://baobab.informatik.uni-stuttgart.de/ifi/bs/research/arab_e.html},
+ date = {2004-03-11},
+ version = {4.00}
+}
\end{filecontents}
\begin{filecontents}[overwrite]{\jobname-cfg.tex}
\footnotelayout{m}
+\DeclareApparatus{fontium}[
+ delim=\hskip0.75em,
+ bhook=\textbf{Sources:},
+ ehook=.]
\DeclareApparatus{default}[
delim=\hskip0.75em,
ehook=.]
+\DeclareApparatus{ltr}[
+ delim=\hskip0.75em]
+\DeclareApparatus{rtl}[
+ direction=RL,
+ sep={[ },
+ delim=\hskip0.75em]
\DeclareWitness{M}{M}{\emph{Marcianus Gr.} 269}[
settlement=Venice,
institution=Marciana Library,
- msName=\emph{Marcianus Gr.},
+ msName=Marcianus Gr.,
idno=269,
origDate=s. X]
\DeclareHand{M1}{M}{M\textsuperscript{1}}[Emendatio scribae ipsius]
@@ -140,7 +248,7 @@ along with this program. If not, see
\DeclareWitness{pjB}{B}{Manuscript B Call No 456}
% Caesar's Gallic War:
\DeclareWitness{cA}{A}{\emph{Bongarsianus} 81}[
- msName=\emph{Bongarsianus},
+ msName=Bongarsianus,
settlement=Amsterdam,
idno=81,
institution=University Library,
@@ -169,6 +277,21 @@ along with this program. If not, see
origDate={s. XI--XII}]
\DeclareShorthand{ca}{α}{cA,cM,cB,cR,cS,cL,cN}
\DeclareShorthand{cb}{β}{cT,cf,cU,cl}
+% Hippocrates Epidemics, Book 2:
+\DeclareWitness{hV}{V}{\emph{Vaticanus Gr.} 276}
+\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}
@@ -199,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}
@@ -246,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{
@@ -262,7 +389,7 @@ along with this program. If not, see
\def\oasymbol{\faUnlock}
\usepackage{biblatex-ext-oa}
}
-{\usepackage[symbolpackage=l3draw]{biblatex-ext-oa}}
+{\usepackage[symbolpackage=tikz]{biblatex-ext-oa}}
\DeclareDelimFormat[bib,biblist]{nametitledelim}{\addcomma\space}
\DeclareDelimFormat[bib,biblist]{innametitledelim}{\addcomma\space}
\renewcommand*\newunitpunct{\addcomma\space}
@@ -371,7 +498,7 @@ along with this program. If not, see
\newminted[ekdlua]{lua}{bgcolor={}, linenos, fontsize=\relsize{-0.5},
xleftmargin=12pt, breaklines, numberblanklines=false, numbersep=3pt,
firstnumber=last}
-\renewcommand{\theFancyVerbLine}{\rmfamily\smaller\arabic{FancyVerbLine}}
+\renewcommand{\theFancyVerbLine}{\normalfont\smaller\arabic{FancyVerbLine}}
\usepackage[contents]{colordoc}
\newcommand{\pkg}[1]{\textsf{#1}\index{#1=#1 (package)}}
\newcommand{\env}[1]{\texttt{#1}\index{#1=#1 (environment)}}
@@ -418,7 +545,7 @@ along with this program. If not, see
%</driver>
% \fi
%
-% \CheckSum{1522}
+% \CheckSum{1669}
%
% \CharacterTable
% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -455,18 +582,6 @@ along with this program. If not, see
% \metapick[print]{titletext}
% \end{tcolorbox}
%
-% \begin{tcolorbox}[title=Notice to the Gentle Reader]
-% The current state of this documentation covers the basics of
-% \pkg{ekdosis}, namely what should be enough to start a new
-% document and see how it works. v1.0 with a full documentation
-% should be out by the end of July. Until then, there is a web page
-% that can be accessed,\footnote{%
-% \url{http://www.robertalessi.net/ekdosis}} with a mailing list
-% that one can subscribe to and a section entitled
-% \enquote{Literature} where one will find some slides and a paper
-% submitted to a journal.
-% \end{tcolorbox}
-%
% \tableofcontents
% \listoflistings
%
@@ -625,11 +740,11 @@ along with this program. If not, see
% not as compact paragraphs that require special and painful training
% to be \enquote*{decoded}. On the other hand, what editions in print
% do not provide are what \citename{Mastronarde.Tarrant2017}{author}
-% have called \enquote{actionable texts for use in digital
-% research},\footcite{Mastronarde.Tarrant2017} namely database-driven
-% texts allowing the reader to select annotations and display or
-% arrange translations, parallel passages or borrowings in a variety
-% of ways.
+% have called \enquote{actionable texts for use in digital research},%
+% {\interfootnotelinepenalty=10000\footcite{Mastronarde.Tarrant2017}}
+% namely database-driven texts allowing the reader to select
+% annotations and display or arrange translations, parallel passages
+% or borrowings in a variety of ways.
%
% \pkg{ekdosis} can be seen as an attempt at combining the two
% approaches.
@@ -650,17 +765,18 @@ along with this program. If not, see
% 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
-% or cited in the edited text), apparatus testium (to collect
-% testimonia or parallel passages), or any kind of short notes to be
-% printed on the same page as the edited text, \emph{\&c}.
-% \item \texttt{TEI xml} output: \pkg{ekdosis} can be instructed
-% to output both PDF and \texttt{TEI xml} files at the same time.
+% \item \label{it:multilayer-feature}\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 or cited in the edited
+% text), apparatus testium (to collect testimonia or parallel
+% passages), or any kind of short notes to be printed on the same
+% page as the edited text, \emph{\&c}.
+% \item \texttt{TEI xml} output: \pkg{ekdosis} can be instructed to
+% output both PDF and \texttt{TEI xml} files at the same time.
% \item \emph{Database-driven encoding} under \LaTeX{} of texts
-% entered segment by segment allows for alignment of parallel texts
-% from multilingual corpora.
+% entered segment by segment allows for alignment of parallel texts
+% from multilingual corpora.
% \end{enumerate}
%
% Before going into detail, the following simple example will give the
@@ -686,9 +802,10 @@ along with this program. If not, see
%</example>
% \fi
%
-% \needspace{4\baselineskip}PDF output:---
+% \needspace{5\baselineskip}
+% PDF output:---
% \medskip
-% \begin{alignment}[tcols=1,texts=specimen,apparatus=specimen]
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
% \begin{specimen}
% I
% \app{
@@ -790,7 +907,8 @@ along with this program. If not, see
% traditions. \pkg{ekdosis} provides a flexible mechanism in which
% format and presentation have been carefully separated from
% content. It is designed to build un-numbered \texttt{TEI} divisions
-% allowed to nest recursively. However, if |divs| be set to |latex|,
+% allowed to nest recursively.\footnote{See below,
+% \vref{sec:body-divisions}.} However, if |divs| be set to |latex|,
% \LaTeX{} standard textual divisions can be used and will be
% translated into \texttt{TEI} numbered |<div>| elements.
%
@@ -838,7 +956,7 @@ along with this program. If not, see
%</example>
% \fi
%
-% \subsection{Witnesses, Hands, Shorthands \& Scholars }
+% \subsection{Witnesses, Hands, Shorthands \& Scholars}
% \label{sec:declarations}
% Any reference that is to be used in the apparatus criticus must be
% \enquote{declared} in the preamble beforehand, namely: manuscript
@@ -846,16 +964,11 @@ along with this program. If not, see
% or later hands, \emph{\&c.}) or abbreviated last names of scholars.
% To that effect, \pkg{ekdosis} provides the following preamble-only
% commands:---
-% \begin{comment}
-% \begin{xltabular}[c]{0.4\linewidth}{lXr}
-% \caption*{\textbf{Conspectus Siglorum}}\\
-% \SigLine{M}\\
-% \end{xltabular}
-% \end{comment}
%
% \paragraph{Witnesses}
% \DescribeMacro{\DeclareWitness} \cs{DeclareWitness}\marg{unique
-% id}\marg{rendition}\marg{description}\oarg{options}\\
+% id}\marg{rendition}\marg{description}\oarg{options}
+% \label{ref:declarewitness}\\
% This command requires three mandatory arguments enclosed between
% curly braces used to specify consecutively:
% \begin{enumerate}
@@ -892,6 +1005,7 @@ along with this program. If not, see
% \DescribeOption{origDate} |origDate|$=$\meta{date}: Any form of date
% used to identify the date of origin for the witness.
%
+% \label{ref:marcianus-b}
% To take here one example, a witness such as the \emph{Marcianus
% Graecus}~269, referred to as manuscript \enquote*{M} in the
% editions, which contains sixty treatises from Hippocrates, could be
@@ -902,7 +1016,7 @@ along with this program. If not, see
\DeclareWitness{M}{M}{\emph{Marcianus Gr.} 269}[
settlement=Venice,
institution=Marciana Library,
- msName=\emph{Marcianus Gr.},
+ msName=Marcianus Gr.,
idno=269,
origDate=s. X]
\end{minted}
@@ -996,6 +1110,7 @@ along with this program. If not, see
% \iffalse
%</example>
% \fi
+% \label{ref:marcianus-e}
%
% \paragraph{Shorthands}
% \DescribeMacro{\DeclareShorthand} \cs{DeclareShorthand}\marg{unique
@@ -1033,6 +1148,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
@@ -1049,10 +1165,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
@@ -1065,7 +1184,76 @@ along with this program. If not, see
%</example>
% \fi
% \label{sec:declarations-end}
-%
+%
+% \subsubsection{Printing Formatted Witnesses
+% --- Conspectus Siglorum}
+% \label{sec:print-witnesses}
+% Once witnesses, hands and scholars have been declared, \pkg{ekdosis}
+% provides two commands to have them printed as declared from their
+% indentifiers.
+%
+% \DescribeMacro{\getsiglum} \cs{getsiglum}\marg{csv list of witnesses
+% or single witness} behaves exactly as the |wit| optional argument of
+% \cs{lem} and \cs{rdg} described below on pages~\pageref{ref:lem-wit}
+% and \pageref{ref:rdg-wit}. From a single identifier or from a
+% comma-separated list of identifiers, it returns their formatted
+% counterparts. To return to the example provided
+% \vpagerefrange{ref:marcianus-b}{ref:marcianus-e}, |\getsiglum{M}|
+% would return \getsiglum{M}, while |\getsiglum{M1}| would return
+% \getsiglum{M1}.
+%
+% \DescribeMacro{\SigLine} \cs{SigLine}\marg{unique id} returns from
+% \meta{unique id} used in the first argument of
+% \cs{DeclareWitness}\footnote{See above
+% \vpageref{ref:declarewitness}.} a line ready to be inserted in a
+% table set to print a Conspectus Siglorum with the following items of
+% information separated by the symbol |&|: the siglum referring to the
+% witness, the contents of the |description| field and the contents of
+% the |origDate| field. An example of how one could print the
+% Conspectus Siglorum of the manuscripts of Caesar's \emph{Gallic War}
+% from the list provided \vpageref{ref:caesar-bg-sigla} follows:---
+%
+% \captof{Conspectus Siglorum of Caesar's \emph{Gallic War}}
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\begin{xltabular}[c]{0.75\linewidth}{lXl}
+ \caption*{\textbf{Conspectus siglorum}}\\
+ \multicolumn{3}{c}{\emph{Familia} \getsiglum{a}}\\
+ \SigLine{A}\\
+ & \getsiglum{A1} \emph{Emendationes scribae ipsius} & \\
+ \SigLine{M}\\
+ [...]
+ \SigLine{N}\\
+ \multicolumn{3}{c}{\emph{Familia} \getsiglum{b}}\\
+ \SigLine{T}\\
+ [...]
+ \SigLine{l}\\
+\end{xltabular}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \begin{xltabular}[c]{0.75\linewidth}{lXl}
+% \caption*{\textbf{Conspectus siglorum}}\\
+% \multicolumn{3}{c}{\emph{Familia} \getsiglum{ca}}\\
+% \SigLine{cA}\\
+% & \getsiglum{cA1} \emph{Emendationes scribae ipsius} & \\
+% \SigLine{cM}\\
+% \SigLine{cB}\\
+% \SigLine{cR}\\
+% \SigLine{cS}\\
+% \SigLine{cL}\\
+% \SigLine{cN}\\
+% \multicolumn{3}{c}{\emph{Familia} \getsiglum{cb}}\\
+% \SigLine{cT}\\
+% \SigLine{cf}\\
+% \SigLine{cU}\\
+% \SigLine{cl}\\
+% \end{xltabular}
+%
% \subsection{Editing a Single Text With No Translation}
% \label{sec:single-text-editing}
% \DescribeEnv{ekdosis}
@@ -1086,7 +1274,7 @@ along with this program. If not, see
%
% \paragraph{Apparatus Entries}
% \DescribeMacro{\app} \cs{app}|[type=|\meta{type}|]|\marg{apparatus
-% entries}\\
+% entries}\label{ref:app-cmd}\\
% This command takes one mandatory argument and accepts one optional
% argument. Once references to be used as witnesses in the apparatus
% criticus have been declared in the preamble as described in
@@ -1111,9 +1299,10 @@ yesterday.
%</example>
% \fi
% \cs{app} accepts one further optional argument:---\\
-% \DescribeOption{type} |type|$=$\meta{type}\hfill%
-% \tcboxverb{Default: default}\\
-% By default, \pkg{ekdosis} sets one layer of notes\--- the |default|
+% \DescribeOption{type} |type|$=$\meta{type}\label{ref:app-type}
+% \hfill\tcboxverb{Default: default}\\
+% As will be described below in \vref{sec:multilayer-apparatus},
+% \pkg{ekdosis} initially sets one layer of notes\--- the |default|
% layer\---in the apparatus criticus. This layer is fit to receive
% notes related to variant readings from witnesses and sources used by
% the editor to establish the edition text. Additional layers can be
@@ -1121,11 +1310,12 @@ 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, \vref{ref:type-app}.} Once
+% and so forth.\footnote{See below, \vref{ref:type-note}.} 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}.
+% option}. For more information about inserting notes in
+% multiple-layer apparatus, see \vref{sec:notes-in-multilayer-app}.
%
% \paragraph{Base text and variants} As can be seen in the example
% above, there are two kinds of individual readings: the \emph{lemma},
@@ -1143,7 +1333,8 @@ yesterday.
% entry. \label{ref:lem-opts-b}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}\\
+% \DescribeOption{wit} |wit|$=$\meta{csv list of
+% witnesses}\label{ref:lem-wit}\\
% 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:
@@ -1180,6 +1371,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
@@ -1210,7 +1402,8 @@ yesterday.
% 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{wit} |wit|$=$\meta{csv list of
+% witnesses}\label{ref:rdg-wit}\\
% \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|
@@ -1225,7 +1418,7 @@ yesterday.
% \paragraph{Notes}
% \DescribeMacro{\note}\DescribeMacro{\note*}
% \cs{note}\oarg{options}\marg{text} or
-% \cs{note*}\oarg{options}\marg{text}\\
+% \cs{note*}\oarg{options}\marg{text}\label{ref:editorial-notes}\\
% 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
@@ -1242,12 +1435,16 @@ yesterday.
% \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
+% \danger Under no circumstances is it permitted to insert this
+% 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.
+% 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. However, as will be described below in
+% \vref{ref:type-note}, the command \cs{note}\---with no star
+% appended\---that is used to insert explanatory notes or references
+% to sources or testimonia is permitted within the mandatory argument
+% of \cs{lem}|{}|, although it is subject to a very strict syntax.
%
% \Vref{lst:pj2} provides an illustration of some of the possibilities
% afforded by the commands just described:---
@@ -1289,7 +1486,7 @@ yesterday.
%</example>
% \fi
% \resetlinenumber
-% \begin{alignment}[tcols=1,texts=specimen,apparatus=specimen]
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
% \begin{specimen}
% I \app{\lem[wit=pjA]{saw}\rdg[wit=pjB]{met}} my friend
% \app{
@@ -1317,7 +1514,7 @@ yesterday.
%
% \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
+% |alt| has been used to insert an abridged 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
@@ -1347,7 +1544,7 @@ yesterday.
<app>
<lem>Peter</lem>
<rdg>John</rdg>
-</app>at the station yesterday. We were both in a
+</app>at the station yesterday. We were both in a
<app>
<lem wit="#A">great</lem>
<rdg wit="#B">good</rdg>
@@ -1423,13 +1620,14 @@ yesterday.
%</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.
+% \DescribeEnv{edition*}\DescribeEnv{translation*}
+% \label{ref:starred-envs} 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
@@ -1489,8 +1687,8 @@ yesterday.
% \fi
%
% \resetlinenumber
-% \ekdfmtdiv{2}{}{.}
-% \begin{alignment}[lcols=2,
+% \FormatDiv{2}{}{.}
+% \begin{alignment}[flush,lcols=2,
% texts=edition[xml:lang="la"];
% translation[xml:lang="en"]]
% \AtBeginEnvironment{edition}{\selectlanguage{latin}}
@@ -1584,7 +1782,8 @@ yesterday.
% \subsection{Alignment of Several Texts}
% \label{sec:multiple-alignment}
% As described above \vpageref{ref:alignment-syntax}, the
-% \env{alignment} environment may receive an optional argument in which
+% \env{alignment} 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}\\
@@ -1606,8 +1805,11 @@ yesterday.
% 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:---
+% \emph{\&c.} Furthermore, as described \vpageref{ref:starred-envs},
+% \pkg{ekdosis} also defines \enquote{starred} versions of these
+% environments to be used to synchronize columns so that corresponding
+% paragraphs are printed vertically aligned. 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.
@@ -1684,11 +1886,11 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% \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{alignment} 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.
+% if it is used. This option applies when two or more distinct
+% \env{alignment} 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
@@ -1723,17 +1925,17 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
%</example>
% \fi
%
-% \DescribeMacro{\SetEkdosisAlignment}
-% \cs{SetEkdosisAlignment}\marg{alignment settings}\\
+% \DescribeMacro{\SetAlignment}
+% \cs{SetAlignment}\marg{alignment settings}\\
% If the same alignment settings are to be shared by several
% \env{alignment} environments, common settings can be collected in
-% the argument of \cs{SetEkdosisEnvironment}, like
+% the argument of \cs{SetAlignment}, like
% so:---\\
% \iffalse
%<*example>
% \fi
\begin{minted}[linenos=false]{latex}
-\SetEkdosisAlignment{
+\SetAlignment{
tcols=3,
lcols=1,
texts=latin[xml:lang="la"];
@@ -1750,24 +1952,2368 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
%</example>
% \fi
%
-% \cs{SetEkdosisAlignment} can be used either in the preamble or at
+% \cs{SetAlignment} can be used either in the preamble or at
% any point of the document to set or to modify alignment settings.
%
-% \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.
+% \subsubsection{Appending Hooks to Environments}
+% \label{sec:alignment-hooks}
+% \DescribeMacro{\AtBeginEnvironment} Once environments corresponding
+% to texts to be aligned have been defined, it is advisable to use the
+% \cs{AtBeginEnvironment}\marg{environment}\marg{code} command that is
+% provided by the \pkg{etoolbox} package\footnote{This package is
+% loaded by \pkg{ekdosis}.} to further adjust languages, hyphenation
+% rules, and/or fonts to be applied in each environment. To return to
+% the example provided above, once \cs{SetAlignment} has been
+% used, the languages can be set as follows:---
%
-% \begin{comment}
-% \section{Multiple-Layer Apparatus Criticus}
-% \end{comment}
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\AtBeginEnvironment{latin}{\selectlanguage{latin}}
+\AtBeginEnvironment{english}{\selectlanguage{english}}
+\AtBeginEnvironment{french}{\selectlanguage{french}}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \section{Laying Out the Apparatus Criticus }
+% \label{sec:apparatus-layout}
+%
+% \subsection{General Hooks}
+% \label{sec:general-hooks}
+% Some hooks are shared by all layers of notes that are inserted in
+% the apparatus criticus (e.g. sources, testimonia, variant readings
+% \emph{\&c.})
+%
+% \DescribeMacro{\SetHooks}
+% \cs{SetHooks}\marg{csv list of hooks} can be used either in
+% the preamble or at any point of the document. The list of accepted
+% hooks at the time of writing follows:---\\
+% \DescribeOption{appfontsize} |appfontsize|$=$\meta{command}
+% \hfill\tcboxverb{Default: \footnotesize}\\
+% This option sets the size of the font to be used in the whole
+% apparatus criticus. By default, it is the same as the size used for
+% footnotes.\\
+% \DescribeOption{refnumstyle} |refnumstyle|$=$\meta{command}
+% \hfill\tcboxverb{Default: \bfseries}\\
+% |refnumstyle| can be used to set the family, series or shape of the
+% font used to print references to line numbers in the apparatus
+% criticus. By default, numbers are printed in bold face. As an
+% example, |refnumstyle=\normalfont| will have them printed in the
+% font and shape selected by default for the
+% document, while |refnumstyle=\bfseries\itshape| will have them
+% printed in bold and italic.\\
+% \DescribeOption{postrefnum} |postrefnum|$=$\meta{command \textbar\
+% chars}\hfill\tcboxverb{Default: ~}\\
+% |postrefnum| can be used to set what immediately follows the
+% reference to line numbers. By default, it is |~|, namely an
+% unbreakable space. As an example, |postrefnum=\hskip 0.5em| will
+% insert a \unit[0.5]{em} space between the numerals and the beginning
+% of all subsequent notes.
+%
+% \subsection{Single-Layer Apparatus Criticus}
+% \label{sec:single-layer-app}
+% \paragraph{Specific Commands}
+% Single-layer apparatus criticus can be laid out in a variety of
+% ways with the following specialized commands, all of which can be
+% used in the preamble or at any point of the document:---
+%
+% \DescribeMacro{\SetLTRapp}
+% \DescribeMacro{\SetRTLapp}
+% \cs{SetLTRapp} and \cs{SetRTLapp} are two argument-less commands to
+% set the direction of the apparatus criticus, either left-to-right or
+% right-to-left.
+%
+% \DescribeMacro{\SetSeparator} \cs{SetSeparator}\marg{separator} is
+% used to change the separator between lemma texts and variants
+% readings. By default, the separator is a closing square bracket
+% followed by a space (\verb*+] +).
+%
+% \DescribeMacro{\SetBeginApparatus}
+% \cs{SetBeginApparatus}\marg{characters\textbar commands} can be used
+% to append \meta{characters} or \meta{commands} at the beginning of
+% the apparatus block. By default, nothing is appended. For instance,
+% |\SetBeginApparatus{\textbf{Apparatus:}}| will append
+% \enquote{\textbf{Apparatus:}} at the beginning of the apparatus
+% block, while |\SetBeginApparatus{\hskip 1em}| will set an
+% indentation of one em.
+%
+% \DescribeMacro{\SetEndApparatus}
+% \cs{SetEndApparatus}\marg{characters} can be used to append
+% \meta{characters} at the end of the apparatus block. By default,
+% nothing is appended. As an example of use, |\SetEndApparatus{.}|
+% will have a period printed at the end of the apparatus as it is
+% customary in some editions.
+%
+% \DescribeMacro{\SetUnitDelimiter}
+% \cs{SetUnitDelimiter}\marg{delimiter} can be used to set the
+% delimiter between entries in the apparatus criticus. By default,
+% there is no delimiter except a simple space. \meta{delimiter} can be
+% a broad space (such as |\hskip 0.75em| for instance as in the OCT
+% series) or the divider-sign (‖, as in the Budé series).
+%
+% \DescribeMacro{\SetDefaultRule}
+% By default, \pkg{ekdosis} draws a separating line between the
+% edition text and the apparatus criticus. This line is initially
+% defined as
+% |\rule{0.4\columnwidth}{0.4pt}|. \cs{SetDefaultRule}\marg{line
+% definition} can be used in the preamble or at any point of the
+% document to change the default setting. Leaving this argument empty
+% as in \cs{SetDefaultRule}|{}| removes the line.
+%
+% \paragraph{General Command}
+% \DescribeMacro{\SetApparatus} \cs{SetApparatus}\marg{csv list of
+% apparatus settings}\label{ref:apparatus-settings-b}\\
+% Finally, all the settings described above can also be collected in
+% the argument of \cs{SetApparatus}. \cs{SetApparatus} accepts the
+% following list of comma-separated |key=value| options:---\\
+% \DescribeOption{direction} |direction|$=$\verb+LR|RL+
+% \hfill\tcboxverb{Default: LR}\\
+% The writing direction of the apparatus criticus, either
+% left-to-right (|LR|) or right-to-left (|LR|).\\
+% \DescribeOption{sep} |sep|$=$\meta{command \textbar\ chars}
+% \hfill\tcboxverb{Default: ]␣}\\
+% The separator between lemma texts and variant readings.\\
+% \DescribeOption{delim} |delim|$=$\meta{delimiter}
+% \hfill\tcboxverb{Default: not set}\\
+% The delimiter between entries in the apparatus criticus. As said
+% above, there is no default delimiter except a simple space.\\
+% \DescribeOption{bhook} |bhook|$=$\meta{characters\textbar commands}
+% \hfill\tcboxverb{Default: empty}\\
+% The characters or commands to be appended at the beginning of the
+% apparatus block.\\
+% \DescribeOption{ehook} |ehook|$=$\meta{characters}
+% \hfill\tcboxverb{Default: empty}\\
+% The characters to be appended at the end of the apparatus block.\\
+% \DescribeOption{rule} |rule|$=$\meta{command}\verb+|+|none|
+% \hfill\tcboxverb{Default: \rule{0.4\columnwidth}{0.4pt}}\\
+% As described above, |rule| is used to draw the separating line
+% between the edition text and the apparatus criticus. |rule=none| can
+% also be used to remove the line.\\
+% \DescribeOption{norule}\hfill\tcboxverb{Default: not set}\\
+% |norule| does not accept any value and has the same effect as
+% |rule=none|.\label{ref:apparatus-settings-e}
+%
+% As an example, an apparatus criticus with references to line numbers
+% printed in normal font, a colon as a separator between lemma texts
+% and variant readings, a broad space as a delimiter between entries
+% and a \unit[0.7]{in} line above could be laid out as follows:---
+%
+% \label{ex:single-layer-app-layout}
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\SetHooks{
+ refnumstyle=\normalfont
+}
+\SetApparatus{
+ sep={: },
+ delim=\hskip 1em,
+ rule=\rule{0.7in}{0.4pt}
+}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Footnote Separator}
+% \DescribeMacro{\footnoteruletrue} \DescribeMacro{\footnoterulefalse}
+% As already seen above, \pkg{ekdosis} takes care of drawing a
+% separating line between the edition text and the apparatus
+% criticus. Therefore, it may be not desirable to have the standard
+% \LaTeX\ \enquote{footnoterule} printed on every page where regular
+% footnotes are found. \cs{footnoterulefalse} removes it while
+% \cs{footnoteruletrue} leaves it untouched. The latter is set by
+% default.
+%
+% \subsection{Multiple-Layer Apparatus Criticus}
% \label{sec:multilayer-apparatus}
+% As said above in \vref{it:multilayer-feature}, \pkg{ekdosis} can
+% print edition texts equipped with multiple-layer apparatus
+% criticus. To take an example, most classical editions provide at
+% least two layers of notes: one to collect references to testimonia
+% or parallel passages (apparatus testium) and the other to record
+% variant readings (the apparatus criticus \emph{stricto sensu}). The
+% former is always printed above the latter.
+%
+% \danger The default single-layer apparatus criticus that is
+% described above in \vref{sec:single-layer-app} is called |default|
+% internally. If any additional layer of notes be declared in the
+% preamble, this |default| layer must be included in the list of
+% declared layers.\\
+% \DescribeMacro{\SetDefaultApparatus}\label{ref:ekd-default-app}
+% \cs{SetDefaultApparatus}\marg{name} can be used at any point of
+% the document to change the default name that is used by
+% \pkg{ekdosis}.
+%
+% \subsubsection{Declaring Additional Layers}
+% \label{sec:declaring-layers}
+% \DescribeMacro{\DeclareApparatus}
+% \cs{DeclareApparatus}\marg{name}\oarg{csv list of apparatus
+% settings} is a preamble-only command. As a mandatory argument, it
+% takes the name of the new layer of notes to be inserted in the
+% apparatus block. Declared layers are then printed one below the
+% other in the exact same order as they are declared in the
+% preamble. Therefore, one additional layer meant to print the
+% testimonia above the variant readings (apparatus testium) can be
+% declared as follows:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+% preamble:
+\DeclareApparatus{testium}
+\DeclareApparatus{default}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% In this example, |testium| is a new name for |default|, as said
+% just above, is already known to \pkg{ekdosis} and used as the
+% default layer of notes. Furthermore, as |testium| is declared before
+% |default|, \pkg{ekdosis} will print the testimonia at the top of the
+% apparatus block.
+%
+% \subsubsection{Laying Out Layers With The Optional Argument
+% of \cs{DeclareApparatus}}
+% \label{sec:layout-layers}
+% \DescribeOption{direction}
+% \DescribeOption{sep}
+% \DescribeOption{delim}
+% \DescribeOption{bhook}
+% \DescribeOption{ehook}
+% \DescribeOption{rule}
+% \DescribeOption{norule}
+% With regard to layout, any declared layer inherits the defaut values
+% described above in \vref{sec:single-layer-app}. That said, as the
+% optional argument of \cs{DeclareApparatus} accepts the exact same
+% |key-value| options as \cs{SetApparatus} described
+% \vpagerefrange{ref:apparatus-settings-b}{ref:apparatus-settings-e},
+% \pkg{ekdosis} provides a straightforward mechanism to have any layer
+% printed in a distinct layout.
+%
+% To return to the example provided
+% \vpageref[above]{ex:single-layer-app-layout}, one could keep the
+% same settings as above for the variant readings, declare an
+% apparatus testium with a closing square bracket as a separator and
+% finally remove the line between the testimonia and the variant
+% readings like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\SetHooks{
+ refnumstyle=\normalfont
+}
+\DeclareApparatus{testium}[
+ sep={] },
+ delim=\hskip 1em,
+ rule=\rule{0.7in}{0.4pt}
+]
+\DeclareApparatus{default}[
+ sep={: },
+ delim=\hskip 1em,
+ norule
+]
+\end{minted}
+% \iffalse
+%</example>
+% \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}
+% may oscillate indefinitely between different sets of page decisions
+% without being able to settle down.\\
+% \DescribeOption{maxentries} |maxentries|=\meta{n} (where $n \geq
+% 10$) \hfill\tcboxverb{Default: not set}\\
+% If |maxentries|$=$\meta{n} be set, then \pkg{ekdosis} will issue
+% \cs{pagebreak} (namely \cs{penalty}|-10000|) just after the
+% \emph{n\textsuperscript{th}} entry has been inserted in the layer of
+% the apparatus criticus this option is related to. As a result, the
+% page will actually break at the end of the current line. The
+% particulars of this technique will be discussed below in
+% \vref{sec:tricks-of-trade}.
+%
+% \section{Inserting Notes in Multiple-Layer Apparatus}
+% \label{sec:notes-in-multilayer-app}
+% As said above in \vref{sec:multilayer-apparatus}, \pkg{ekdosis}
+% initially sets one layer of notes that is called the
+% \textooquote|default|\textcoquote\ layer. As a result, any note
+% inserted within the argument of \cs{app}|{}| as described
+% \vpageref{ref:app-cmd} will go into that layer of the apparatus,
+% unless \cs{SetDefaultApparatus} has been used to set another
+% name for the default layer (see above
+% \vpageref{ref:ekd-default-app}).
+%
+% \subsection{Variant Readings}
+% \label{sec:variant-readings}
+% In most cases, all variant readings go into the
+% \textooquote|default|\textcoquote\ layer of the apparatus
+% criticus. But in some other cases, for example when the manuscripts
+% used refer to different recensions, it may happen that one wishes to
+% record the related variants in separate layers. As already described
+% \vpageref{ref:app-type}, the |type| optional argument of the
+% \cs{app} command can be used to insert lemma texts and associated
+% variants in any other \enquote*{declared} layer of the apparatus
+% criticus.
+%
+% The following example assumes that some edition text is received in
+% two different recensions and the variant readings that belong to the
+% first recension are recorded in the default layer of notes while
+% those of the second recension are to be printed in a second layer,
+% below the default one. First, both layers must be declared in the
+% preamble in sequence, like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\DeclareApparatus{default} % default layer
+\DeclareApparatus{rec2} % additional layer below the default one
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% If one wishes to refer to |rec1| as the default layer, then
+% \cs{SetDefaultApparatus} must be used, like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\SetDefaultApparatus{rec1}
+\DeclareApparatus{rec1} % new layer set as default
+\DeclareApparatus{rec2} % additional layer below the default one
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% Then, whatever option has been chosen, lemma texts and variants
+% inserted with \cs{app}|{}| will go into the upper, default layer of
+% notes, while those inserted with \cs{app}|[type=rec2]{}| will go
+% into the lower one:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+Some \app{
+ \lem{word}
+ \rdg{reading}
+} to go into the default layer of notes.
+
+Some \app[type=rec2]{
+ \lem{note}
+ \rdg{comment}
+} to be recorded as part of the second recension.
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% At any rate, |type=default| or |type=rec1|, depending on what has
+% been chosen, must be used if the editor wishes to retain that
+% information in the \texttt{TEI xml} output file.
+%
+% \subsection{Other Notes for Comments, Sources or Testimonia}
+% \label{ref:type-note}
+% Additional layers of notes can be used to print short comments or to
+% record references to texts quoted by the author of the edited text
+% or references to the edited text by other authors or
+% translators. The former set is called an \emph{apparatus fontium}
+% while the latter is called an \emph{apparatus testium}.
+%
+% \danger From a technical standpoint, these notes are very different
+% from the short editorial notes inserted between lemma texts and
+% variant readings that have been described above
+% \vpageref{ref:editorial-notes}. However, for the sake of consistency
+% with \texttt{TEI xml} encoding, \pkg{ekdosis} uses the same command
+% \cs{note} to insert both kinds of notes.
+%
+% \danger One must also keep in mind that the notes that are described
+% in this section refer either to a single word or to a span of
+% text. By consequence, as boundaries must always be set outside spans
+% of text, notes must be inserted immediately before the word or words
+% they are related to. As a result of this rule, all spaces subsequent
+% to \cs{note} are ignored.
+%
+% \DescribeMacro{\note} \cs{note}\oarg{options}\marg{text}\\
+% As said above, \cs{note}, when found outside \cs{app}|{}|, is used
+% to insert in additional layers of the apparatus short comments or
+% references to texts quoted or cited in the edition text. It accepts
+% the following comma-separated list of |key-value| optional
+% arguments:---\\
+% \DescribeOption{type} |type|$=$\meta{type}\\
+% |type| is used to specify the name of the layer where the note is to
+% be printed.\footnote{See \vref{sec:declaring-layers} to learn how to
+% declare and lay out new layers of notes.}\\
+% \DescribeOption{sep} |sep|$=$\meta{command \textbar\ chars}\\
+% The separator between the lemma text and the contents of the note.\\
+% \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{lem} |lem|$=$\meta{lemma text}\\
+% |lem| is the span of text the note is about. It may consist of one
+% or more words, or of an abridged lemma text.\\
+% \DescribeOption{labelb} |labelb|$=$\meta{label}
+% \hfill\tcboxverb{Mandatory}\\
+% |labelb| is the unique label to serve as a reference for the point
+% immediately preceding the lemma text. \danger |labelb| is used by
+% \pkg{ekdosis} to print the line numbers in the apparatus criticus
+% and to set the |left()| XPointer should \texttt{TEI} output be
+% required. Therefore, it must be specified. Otherwise, \pkg{ekdosis}
+% will issue an error message.\\
+% \DescribeOption{labele} |labele|$=$\meta{label}\\
+% |labele| is the unique label to serve as a reference for the point
+% immediately following the lemma text. Contrary to |labelb|, |labele|
+% may be left unspecified if the note is only about one word. If it is
+% about a span, then |labele| ought to be specified.\\
+% \DescribeMacro{\linelabel} \cs{linelabel}\marg{label}\\
+% If |labele|$=$\meta{some\_label} be specified in the optional
+% argument of \cs{note}, \cs{linelabel}\marg{some\allowbreak\_label}
+% must be inserted immediately after the span of text that the note is
+% about so that \pkg{ekdosis} can locate the exact point where the
+% lemma text addressed by the note ends, like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Preamble:
+% \DeclareApparatus{fontium}[
+% delim=\hskip0.75em,
+% bhook=\textbf{Sources:},
+% ehook=.]
+% \DeclareApparatus{default}[
+% delim=\hskip0.75em,
+% ehook=.]
+% Document:
+\begin{ekdosis}
+ The oldest monument of the Germans is their language, which, before
+ untold centuries, was the companion of their travels from central
+ Asia; a language, copious, elastic, inviting self-explaining
+ combinations and independent development; lending itself alike to
+ daily life and imagination, to description and abstract thought.
+ \note[type=fontium, labelb=61e, labele=62a, lem={They
+ had... slave}]{Waitz, \emph{Deutsche Verfassungs Geschichte},
+ i. 86} They had a class of nobles, but their tongue knew no word
+ for slave.\linelabel{62a}\footnote{George Bancroft, \emph{History of
+ the United States from the Discovery of the American Continent},
+ II.61--2.}
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \needspace{5\baselineskip}
+% PDF output:---
+% \medskip
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+% \begin{specimen}
+% The oldest monument of the Germans is their language, which,
+% before untold centuries, was the companion of their travels from
+% central Asia; a language, copious, elastic, inviting
+% self-explaining combinations and independent development;
+% lending itself alike to daily life and imagination, to
+% description and abstract thought. \note[type=fontium,
+% labelb=61e, labele=62a, lem={They had... slave}]{Waitz,
+% \emph{Deutsche Verfassungs Geschichte}, i. 86} They had a class
+% of nobles, but their tongue knew no word for
+% slave.\linelabel{62a}\footnote{George Bancroft, \emph{History of
+% the United States from the Discovery of the American Continent},
+% II.61--2.}
+% \end{specimen}
+% \end{alignment}
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<p>The oldest monument of the Germans is their language,
+which, before untold centuries, was the companion of their
+travels from central Asia; a language, copious, elastic,
+inviting self-explaining combinations and independent
+development; lending itself alike to daily life and
+imagination, to description and abstract thought.
+<note type="fontium" target="#range(right(61e),left(62a))">Waitz,
+<emph>Deutsche Verfassungs Geschichte</emph>, i. 86</note>
+<anchor xml:id="61e" />They had a class of nobles, but
+their tongue knew no word for slave.
+<anchor xml:id="#62a" />
+<note place="bottom">George Bancroft,
+<emph>History of the United States from the Discovery of
+the American Continent</emph>, II.61--2.</note></p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
%
-% \label{ref:type-app}
+% \paragraph{\cs{note} or \cs{linelabel} inside \cs{lem}}
+% It may happen that \cs{note} or \cs{linelabel} commands be found
+% inside the argument of \cs{lem}. Obviously, inserting such commands
+% in the apparatus criticus in print makes no sense and will lead to
+% an error. The solution is to insert in the value of the |alt|
+% optional argument of \cs{lem} a duplicate of the lemma text devoid
+% of those commands, like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+This is some \app{
+ \lem[alt=dummy]{\note[type=fontium, labelb=bnote, labele=enote,
+ lem=dummy... command]{Text of the note}
+ dummy}
+ \rdg{pseudo}}
+text to demonstrate how to insert a note in the argument of the
+\emph{lem} command.\linelabel{enote}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \needspace{5\baselineskip}
+% PDF output:---
+% \medskip
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+% \begin{specimen}
+% This is some \app{
+% \lem[alt=dummy]{\note[type=fontium, labelb=bnote, labele=enote,
+% lem=dummy... command]{Text of the note}
+% dummy}
+% \rdg{pseudo}}
+% text to demonstrate how to insert a note in the argument of the
+% \emph{lem} command.\linelabel{enote}
+% \end{specimen}
+% \end{alignment}
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{xml}
+<p>This is some
+<app>
+ <lem>
+ <anchor xml:id="bnote" />dummy</lem>
+ <note type="fontium"
+ target="#range(right(bnote),left(enote))">Text of the
+ note</note>
+ <rdg>pseudo</rdg>
+</app>text to demonstrate how to insert a note in the
+argument of the
+<emph>lem</emph>command.
+<anchor xml:id="#enote" /></p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% As can be seen from the \texttt{TEI xml} output above, the span of
+% text the note is about has been carefully delimited by two anchors
+% (ll.~4 and 12), the first of which falls within |<lem>| (l.~4), but
+% \pkg{ekdosis} has taken care of moving the note itself out of this
+% element (ll.~5--7). Otherwise, the \texttt{TEI} output would not be
+% valid.
+%
+% \section{Lineation Settings}
+% \label{sec:lineation}
+% \danger \pkg{ekdosis} uses \pkg{lineno} internally for line
+% numbering.\footcite{lineno} But it must be noted that \pkg{ekdosis}
+% strictly prohibits the \enquote{pagewise} mode of operation that is
+% provided by \pkg{lineno}. As a result of this hinderance, all
+% \enquote{margin switching} functions of \pkg{lineno} are disabled
+% within the environments that are specific to \pkg{ekdosis},
+% viz. \env{ekdosis} and \env{alignment}.
+%
+% That said, \pkg{ekdosis} provides equivalents of its own to handle
+% the line numbers the same way as \pkg{lineno}'s \enquote{pagewise}
+% mode of operation does.
+%
+% \DescribeMacro{\SetLineation} \cs{SetLineation}\marg{csv list of
+% options} may be used in the preamble or at any point of the document
+% to set lineation preferences. Its argument processes the |key=value|
+% options that follow:---\\
+% \DescribeOption{lineation} |lineation|$=$\verb+page|document+
+% \hfill\tcboxverb{Default: document}\\
+% |lineation=document| has the lines numbered continuously throughout
+% the document while |lineation=page| instructs \pkg{ekdosis} that the
+% numbering should start afresh at the top of each page.\\
+% \DescribeOption{modulo} |modulo| \hfill\tcboxverb{Default: not set}\\
+% |modulo| does not accept any value. When this option is set, every
+% fifth line is numbered.\\
+% \DescribeOption{modulonum} |modulonum|$=$\emph{n} (where \emph{n} is
+% an integer)\hfill\tcboxverb{Default: not set}\\
+% |modulonum| allows to modify the interval between the numbers that
+% are printed. |modulo| must be set for this option to have effect. As
+% examples, |modulo, modulonum=3| has every third line numbered and
+% |modulonum=1| disables modulo numbering.\\
+% \DescribeOption{margin} |margin|$=$\verb+right|left|inner|outer+
+% \hfill\tcboxverb{Default: left}\\
+% |margin| sets the margin in which the line numbers are to be
+% printed.\\
+% \DescribeOption{numbers} |numbers|$=$\verb+elided|full+
+% \hfill\tcboxverb{Default: elided}\\
+% This option only has effect on the numbers that are printed in the
+% apparatus criticus. |numbers=elided| applies on spans of numbers and
+% elides the last number of a range to the fewest number of figures
+% possible\---viz. 35--7, 129--31 \emph{\&c.}\---without eliding
+% digits in the group 10 to 19 in each hundred\---viz. 17--19, 115--18
+% \emph{\&c.} |numbers=full| leaves the numbers untouched.
+%
+% \DescribeMacro{\innerlinenumbers} \DescribeMacro{\outerlinenumbers}
+% \cs{innerlinenumbers} and \cs{outerlinenumbers} are equivalent to
+% \cs{SetLineation}|{numb|\allowbreak|ers=outer}| and
+% \cs{SetLineation}|{numbers=inner}| respectively. Both commands are
+% complementary to \cs{rightlinenumbers} and \cs{leftlinenumbers}
+% already provided by the \pkg{lineno} package.
+%
+% \paragraph{Useful Lineation Commands}
+% As implied above, pretty much all commands that are provided by the
+% \enquote{running} mode of operation of the \pkg{lineno} package will
+% work with \pkg{ekdosis}, notably the following:---\\
+% \DescribeMacro{\modulolinenumbers} \cs{modulolinenumbers}\oarg{n}
+% can be used to enable modulo line numbering as described above.\\
+% \DescribeMacro{\resetlinenumber} \cs{resetlinenumber}\oarg{n} resets
+% the line number to one or to \emph{n} if specified.\\
+% \DescribeMacro{\linenumberfont}
+% \cs{renewcommand}|{\linenumberfont}|\marg{commands} can be used to
+% set the font used for the line numbers that are printed in the
+% margins. By default, the definition is
+% \cs{normalfont}\cs{footnotesize}.\\
+% \DescribeMacro{\linenumbersep} \cs{linenumbersep} is the distance
+% between the numbers and the margin. By default, this distance is set
+% to \unit[10]{pt}. It can be redefined like so:
+% \cs{setlength}\cs{linenumbersep}\marg{length}.\\
+% \DescribeMacro{\linelabel} \DescribeMacro{\lineref}
+% \cs{linelabel}\marg{label} sets a line label that can be referred to
+% with \cs{lineref}\marg{label}.
+%
+% The reader is invited to refer to the documentation of the
+% \pkg{lineno} package for more information.
+%
+% As an example, what follows has every fifth line number printed in
+% the inner margins. Additionally, the numbering shall start afresh at
+% the top of each page:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\SetLineation{
+ lineation=page,
+ modulo,
+ margin=inner
+}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \section{Languages}
+% \label{sec:languages}
+% \danger \pkg{ekdosis} is fully compatible with \pkg{babel}.
+% \enquote{Fully compatible} means that all features provided by
+% \pkg{babel}, including language switching commands, are supported by
+% \pkg{ekdosis}. \pkg{ekdosis} is also compatible with
+% \pkg{polyglossia} with one notable exception: \pkg{luabidi}, which
+% \pkg{polyglossia} loads for languages written from right to left, is
+% not supported by \pkg{ekdosis}, and most probably never will
+% be. That said, as far as the author could see, single-layer
+% apparatus, as described in \vref{sec:single-layer-app}, can be
+% typeset within the Arabic environment that is provided by
+% \pkg{polyglossia}. Unfortunately, the same cannot be said for
+% multi-layer apparatus.
+%
+% Whether \pkg{babel} or \pkg{polyglossia} is used, \pkg{ekdosis}
+% automatically applies the current language to the entries of the
+% apparatus criticus, including the fonts that may have been
+% associated to the languages in the preamble. In this respect, as
+% \pkg{polyglossia} can use the same language switching commands as
+% \pkg{babel},\footcite[See][3.2 \pno~14]{polyglossia} the general
+% advice given above in \vref{sec:alignment-hooks} applies in all
+% cases.
+%
+% \subsection{Languages Written From Right to Left}
+% \label{sec:rtl-languages}
+% As said above, \pkg{polyglossia} is not supported by \pkg{ekdosis}
+% for languages that are written and read from right to left, like
+% Arabic, Hebrew or Syriac. However, as \pkg{babel} is supported and
+% can be loaded concurrently with \pkg{polyglossia}, an easy way is to
+% use \pkg{babel} to print such languages.
+%
+% \danger The reader is invited to refer to and become acquainted with
+% the relevant parts of the documentation of the \pkg{babel}
+% package.\footcite{babel}
+%
+% \paragraph{\pkg{babel} Only}
+% In the following example, \pkg{babel} is used exclusively to set
+% three different languages: Arabic, ancient Greek and English:---
+%
+% \captof{Multilingual editions with \pkg{babel} only}
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+\usepackage{fontspec}
+
+\usepackage[greek.ancient,english]{babel}
+\babelprovide[onchar=fonts]{arabic}
+
+\babelfont{rm}{Old Standard}
+\babelfont[greek]{rm}[RawFeature={+ss05;+ss06}]{Old Standard}
+\babelfont[*arabic]{rm}{Amiri}
+
+\babeltags{ancientgreek = greek}
+\newcommand{\sg}[1]{\textancientgreek{#1}}
+
+\newcommand{\RL}[1]{\bgroup\textdir TRT#1\egroup}
+\newenvironment{Arabic}{\par\pardir TRT\textdir TRT}{\par}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \begin{remarks}
+% \item As can be seen, \pkg{fontspec} has been loaded before
+% \pkg{babel}. To the author's knowledge, this gives better results
+% when \cs{babelfont} is used.
+% \item Line~3 loads \pkg{babel} and instructs it to use English as
+% the default language and ancient Greek as a second optional
+% language. The built-in |bidi| mechanism provided by \pkg{babel} is
+% not enabled. As a result, specific language switching commands for
+% Arabic must be defined just as it must be for every other
+% language.
+% \item Line~4 does not load any Arabic, but instructs \pkg{babel}
+% that it should use the Arabic font that is set below with
+% \cs{babelfont} whenever an Arabic letter is encountered.
+% \item Lines~6--8 select the fonts: |Old Standard| is the default
+% font to be used for Roman shape (l.~6); the same font is used for
+% Greek, with some additional Open Type features enabled; finally,
+% the |Amiri| font is used for Arabic.
+% \item Lines~10--11 define so-called \enquote{tags} for easier access
+% to ancient Greek through \cs{begin}|{ancient|\allowbreak|greek}|
+% \dots\ \cs{end}|{ancientgreek}| for running paragraphs and
+% \cs{textancientgreek}\marg{text} for short insertions of Greek in
+% English text. \cs{sg}\marg{text} is just a shorthand for this
+% latter command.
+% \item Finally, lines~13--14 define simple language switching
+% commands for Arabic. As can be seen, no commands other than the
+% \LuaTeX\ primitives \cs{pardir} and \cs{textdir} have been used
+% for \pkg{babel} already takes care of selecting the Arabic
+% font. \cs{RL} is for short insertions of Arabic words in English
+% paragraphs while \cs{begin}|{Arabic}| \dots\ \cs{end}|{Arabic}| is
+% for running paragraphs of Arabic text.
+% \end{remarks}
+%
+% \paragraph{Changing the Writing Direction}
+% \DescribeMacro{\setRL} \DescribeMacro{\setLR} \cs{setRL} and
+% \cs{setLR} are two argument-less commands provided by \pkg{ekdosis}
+% that can be used to change the writing direction of running
+% paragraphs. The former sets the direction from right to left and the
+% latter form left to right. If \pkg{babel} has been set as above,
+% \cs{setRL} \dots\ \cs{setLR} can be used in place of
+% \cs{begin}|{Arabic}| \dots\ \cs{end}|{Arabic}|.
+%
+% \paragraph{\pkg{polyglossia} Associated With \cs{babelprovide}}
+% What follows illustrates how \pkg{babel} can be used conjointly with
+% \pkg{polyglossia} for the same three languages as above without
+% having to load \pkg{luabidi}:---
+%
+% \captof{Multilingual editions with \pkg{babel} and
+% \pkg{polyglossia}}
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+\usepackage{fontspec}
+
+\usepackage{babel}
+\babelprovide[onchar=fonts]{arabic}
+
+\setmainfont{Old Standard}
+\newfontfamily\greekfont{Old Standard}[RawFeature={+ss05;+ss06}]
+\babelfont[*arabic]{rm}{Amiri}
+
+\usepackage{polyglossia}
+\setdefaultlanguage{english}
+\setotherlanguage[variant=ancient]{greek}
+
+\newcommand{\textarabic}[1]{\bgroup\textdir TRT#1\egroup}
+\newenvironment{Arabic}{\par\pardir TRT\textdir TRT}{\par}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \begin{remarks}
+% \item Line~3 just loads \pkg{babel} with no default language.
+% \item Lines~4 and 8 are used to have the Arabic font automatically
+% selected as above.
+% \item Lines~14--15 define the exact language switching commands that
+% would have been defined if \pkg{polyglossia} and \pkg{luabidi} had
+% been used for Arabic.
+% \end{remarks}
+%
+% As one can see, the important points about languages written from
+% right to left are to use \pkg{babel} only to select the Arabic
+% fonts, avoid using the bidirectional mechanism it provides and
+% define commands and environments that use only \LuaTeX\ primitives
+% to set the writing direction. Then, an Arabic edition text\---to
+% continue with this example\---can be entered as plainly as
+% follows:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false,escapeinside=++]{latex}
+\begin{ekdosis}
+ \begin{Arabic}
+ +\txarb{إِنَّ أَبِي كَانَ مِنَ}+ \app{
+ \lem{+\txarb{ٱلْمُقَاتِلَةِ}+}
+ \rdg{+\txarb{ٱلْمُقَاتِلِينَ}+}
+ } +\txarb{وَ كَانَتْ أُمِّي مِنْ عُظَمَآءِ بُيُوتِ ٱلزَّمَازِمَةِ۔}+
+ \end{Arabic}
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% It should be reminded that the writing direction of the apparatus
+% criticus itself is independent of that of the edition text and must
+% be set either with \cs{Set(LTR{\textbar}RTL)app} or with the
+% |direction| optional argument of \cs{SetApparatus} for single-layer
+% apparatus criticus, or by means of \cs{DeclareApparatus} for
+% multiple-layer apparatus criticus.\footnote{See above
+% \vref{sec:single-layer-app} (single-layer apparatus criticus) and
+% \vref{sec:multilayer-apparatus} (multiple-layer apparatus
+% criticus).}
+%
+% \needspace{5\baselineskip}
+% The PDF output with left-to-right apparatus criticus follows:---
+% \medskip
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+% \begin{specimen}
+% \begin{arab}[fullvoc]
+% 'inna 'abI kAna mina \app[type=ltr]{
+% \lem{'l-muqAtilaTi}
+% \rdg{'l-muqAtilIna}}
+% wa-kAnat 'ummI min `u.zamA'i buyUti 'l-zamAzimaTi.
+% \end{arab}
+% \end{specimen}
+% \end{alignment}
+%
+% \needspace{5\baselineskip}
+% And here follows the PDF output with right-to-left apparatus
+% criticus:---
+% \medskip \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+% \begin{specimen}
+% \begin{arab}[fullvoc]
+% 'inna 'abI kAna mina \app[type=rtl]{
+% \lem{'l-muqAtilaTi}
+% \rdg{'l-muqAtilIna}}
+% wa-kAnat 'ummI min `u.zamA'i buyUti 'l-zamAzimaTi.
+% \end{arab}
+% \end{specimen}
+% \end{alignment}
+%
+% \subsection{Using \pkg{arabluatex}}
+% \label{sec:using-arabluatex}
+% \pkg{arabluatex} is a \hologo{LuaLaTeX} package that provides
+% commands and environments which return Arabic writing from an ASCII
+% transliteration (either Arab\TeX\ or Buckwalter
+% scheme).\footcite{arabluatex} It is particularly well-suited for
+% complex documents such as critical editions where a lot of commands
+% intertwine with Arabic writing. \pkg{arabluatex} can output Unicode
+% Arabic in the same modes as \pkg{arabtex}\footcite{arabtex} or in
+% different accepted standards of romanization. It is also able to
+% produce a duplicate of the original |.tex| source file in which all
+% |arabtex| or |buckwalter| strings are replaced with Unicode
+% equivalents, either in Arabic script or in any accepted standard of
+% transliteration.\footcite[\mkbibquote{Exporting Unicode Arabic
+% to an External File}]{arabluatex}
+%
+% \pkg{arabluatex} is fully supported by \pkg{ekdosis}. The following
+% example illustrates how \pkg{arabluatex} and \pkg{ekdosis} interact
+% with each other to produce distinct \texttt{TEI xml} outputs from a
+% single |.tex| source file:---
+%
+% \captof{\pkg{ekdosis} and \pkg{arabluatex}}[\label{lst:arabluatex-ekd}]
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{latex}
+% Preamble:
+% load ekdosis and ask for TEI xml output:
+\usepackage[teiexport]{ekdosis}
+% load arabluatex and request a LaTeX ouput with Unicode Arabic:
+\usepackage[export,fullvoc]{arabluatex}
+
+% document:
+\begin{arabexport} % export arabtex strings to Unicode Arabic
+ \begin{ekdosis}
+ \begin{arab}
+ 'inna 'abI kAna mina
+ \app{
+ \lem{'l-muqAtilaTi}
+ \rdg{'l-muqAtilIna}
+ }
+ wa-kAnat 'ummI min `u.zamA'i buyUti 'l-zamAzimaTi.
+ \end{arab}
+ \end{ekdosis}
+\end{arabexport}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \needspace{7\baselineskip}
+% The PDF output with left-to-right apparatus criticus is of course
+% the same as above:---
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+% \begin{specimen}
+% \begin{arab}[fullvoc]
+% 'inna 'abI kAna mina \app[type=ltr]{
+% \lem{'l-muqAtilaTi}
+% \rdg{'l-muqAtilIna}}
+% wa-kAnat 'ummI min `u.zamA'i buyUti 'l-zamAzimaTi.
+% \end{arab}
+% \end{specimen}
+% \end{alignment}
+%
+% However, assuming that the source file is called |source.tex|,
+% \pkg{ekdosis} produces as instructed from this file an additional
+% |source-tei.xml| as follows:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<p xml:lang="ar-Latn" type="transliterated"
+subtype="arabtex">'inna 'abI kAna mina
+<app>
+ <lem>'l-muqAtilaTi</lem>
+ <rdg>'l-muqAtilIna</rdg>
+</app>wa-kAnat 'ummI min `u.zamA'i buyUti
+'l-zamAzimaTi.</p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% At the same time, \pkg{arabluatex} is instructed to produce on its
+% own from the same |source.tex| an additional |source_out.tex| in
+% which all |arabtex| strings found within \cs{begin}|{arabexport}|
+% \dots\ \cs{end}|{arabexport}| (see \vref{lst:arabluatex-ekd},
+% ll.~9--19) are replaced with full-vocalized Arabic Unicode
+% script. Finally, compiling this latter file produces the following
+% |sample-arabic_out-tei.xml| an extract of which follows:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false,escapeinside=++]{xml}
+<p xml:lang="arb">+\txarb{إِنَّ أَبِي كَانَ مِنَ}+
+<app>
+ <lem>+\txarb{ٱلْمُقَاتِلَةِ}+</lem>
+ <rdg>+\txarb{ٱلْمُقَاتِلِينَ}+</rdg>
+</app>+\txarb{وَكَانَتْ أُمِّي مِنْ عُظَمَآءِ بُيُوتِ}+
++\txarb{ٱلزَّمَازِمَةِ.}+</p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% The reader will find the full |arabic-sample.tex| source file with
+% instructions in \vref{sec:arabic-sample}, and is invited to refer to
+% the documentation of the \pkg{arabluatex} package for more
+% information on the way to use its Arabic environments and built-in
+% functions dedicated to export |arabtex| ASCII strings to
+% Unicode.\footcite{arabluatex}
+%
+% \section{Divisions of the Body}
+% \label{sec:body-divisions}
+% The features that are described in this section call for one general
+% remark. \pkg{ekdosis} is designed to figure out where any \LaTeX\
+% command that is converted to a \texttt{TEI} opening element allowed
+% to nest recursively, such as |<div>|, |<lg>| and the like, is to be
+% closed, even though there is no explicit indication of the point
+% where the closure occurs. Thoroughly scanning \LaTeX\ source files
+% with \textsf{Lua} functions which involve complex string matching
+% and recursions was required, as \LaTeX\ \enquote*{open} commands
+% such as \cs{chapter} or \cs{section} only act as milestones,
+% contrary to \texttt{TEI} elements.
+%
+% \danger It must be noted that the two styles described hereinafter
+% are mutually exclusive. \texttt{TEI xml} forbids that both be
+% combined within a single |<body>| element.\footnote{See
+% \url{https://tei-c.org/release/doc/tei-p5-doc/en/html/DS.html\#DSDIV}.}
+% As a result, \pkg{ekdosis} will disregard whichever one is not
+% selected.
+% \vskip\baselineskip
+%
+% \subsection{\LaTeX\ Standard Divisions}
+% \label{sec:latex-divs}
+% \pkg{ekdosis} can use the \LaTeX\ standard textual divisions, such
+% as \cs{book}, \cs{chapter}, \cs{section} and the like.
+%
+% \danger However, to have these divisions properly translated into
+% \texttt{TEI} numbered |<div>| elements, the |divs| general option
+% must be set to |latex| explicitly\---viz. |divs=latex|\---as
+% described above \vpageref{ref:divs-opt}.
+%
+% \danger As the \env{alignment} environment that is provided by
+% \pkg{ekdosis} places all aligned texts within \texttt{TEI xml}
+% un-numbered |<div>| elements and \LaTeX\ textual divisions are
+% converted into numbered |<div|\textsubscript{\emph{n}}|>| elements,
+% inserting such divisions in texts to be aligned will result in an
+% invalid \texttt{TEI xml} output. Instead, un-numbered divisions
+% through \cs{ekddiv} must be used as described below in
+% \vref{sec:ekddiv}.
+%
+% Once |divs| has been set to |latex|, \pkg{ekdosis} converts
+% \cs{book}, \cs{part}, \cs{chapter}, \cs{section}, \cs{subsection}
+% and \cs{subsubsection} into corresponding \texttt{TEI}
+% \enquote*{numbered} |<div|\textsubscript{\emph{n}}|>| elements,
+% where $1\leq n\leq 6$.
+%
+% \paragraph{Adjusting the Levels of Textual Subdivisions}
+% \DescribeMacro{\MkBodyDivs}
+% \cs{MkBodyDivs}\marg{div1}\marg{div2}\marg{div3}\allowbreak\marg{div4}\marg{div5}\marg{div6}
+% takes six mandatory arguments. This command can be used in the
+% preamble or at any point of the document to make the number of the
+% first-level subdivision of the edition text, viz.\ |<div1>|, match
+% to any \LaTeX\ command other than \cs{book}. For example, if
+% \cs{section} be the highest-level sectional command used, then
+% \cs{MkBodyDivs}|{section}{subsection}{subsubsection}{}{}|\allowbreak|{}|
+% will have \cs{section}, \cs{subsection} and \cs{subsubsection}
+% converted into |<div1>|, |<div2>| and |<div3>| respectively.
+%
+% \paragraph{Inserting Variants in Headings}
+% Variant readings can be inserted in headings. In this case, the
+% optional argument of the \LaTeX\ sectional command must naturally be
+% used to prevent variants from going into headers, footers or the
+% table of contents, like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Preamble:
+\usepackage[teiexport=tidy, divs=latex]{ekdosis}
+\MkBodyDivs{chapter}{section}{}{}{}{}
+
+% Document:
+\chapter[Ἱπποκράτους ἐπιδημιῶν βιβλίον δεύτερον]{Ἱπποκράτους ἐπιδημιῶν
+ \app{
+ \lem[wit={I,R,H}]{βιβλίον δεύτερον}
+ \rdg[wit=V]{λόγος β’}}}
+
+\section{<Τμῆμα πρῶτον>}
+Ἄνθρακες θερινοὶ ἐν Κραννῶνι· [...]
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<div1 type="chapter">
+ <head>Ἱπποκράτους ἐπιδημιῶν
+ <app>
+ <lem wit="#I #R #H">βιβλίον δεύτερον</lem>
+ <rdg wit="#V">λόγος β’</rdg>
+ </app></head>
+ <div2 type="section">
+ <head>&lt;Τμῆμα πρῶτον&gt;</head>
+ <p>Ἄνθρακες θερινοὶ ἐν Κραννῶνι· [...]</p>
+ </div2>
+</div1>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \subsection{Using \texttt{TEI} Un-numbered Divisions}
+% \label{sec:ekddiv}
+% \danger As already described \vpageref{ref:divs-opt}, the
+% un-numbered style of division is the one that is set by default. It
+% is congruous to the general option |divs=ekdosis|.
+%
+% This style provides a flexible mechanism in which format and
+% presentation are separated from content. It is designed to meet the
+% requirements of classical and literary texts the divisions of which
+% may depend on many different received traditions.
+%
+% \DescribeMacro{\ekddiv} \cs{ekddiv}\marg{key-value arguments} is the
+% unique sectional command provided by \pkg{ekdosis}. This command
+% converts the divisions into un-numbered \texttt{TEI} |<div>|
+% elements allowed to nest recursively and takes one mandatory
+% argument in which the following |key-value| arguments are
+% accepted:---\\
+% \DescribeOption{type} |type|$=$\meta{name}
+% \hfill\tcboxverb{Default: none}\\
+% |type| corresponds to the \texttt{TEI} class |att.typed| and can be
+% used to classify the element in which it is found in any
+% way. Suitable values here can be |book|, |chapter|, |section| and
+% the like.\\
+% \DescribeOption{n} |n|$=$\meta{value} \hfill
+% \tcboxverb{Default: none}\\
+% |n| is meant to provide a number or any kind of label for the
+% division and does not have to be unique in the document.\\
+% \DescribeOption{head} |head|$=$\meta{name}
+% \hfill\tcboxverb{Default: none}\\
+% |head| holds the title of the division and may further contain
+% variant readings.\\
+% \DescribeOption{barehead} |barehead|$=$\meta{name}
+% \hfill\tcboxverb{Default: none}\\
+% |barehead| is supposed to be used to prevent unwanted commands from
+% going into such places as headers, footers and the table of
+% contents.\\
+% \DescribeOption{depth} |depth|$=$\meta{n} where $1\leq n\leq 9$
+% \hfill\tcboxverb{Default: 1}\\
+% As \texttt{TEI} un-numbered divisions are simply |<div>| elements
+% allowed to nest recursively to indicate their hierarchic depth and
+% \cs{ekddiv} is an \enquote*{open} \LaTeX\ command, |n| is needed to
+% indicate the depth of the division within the hierarchy, the largest
+% being |1| and the smallest being |9|.\\
+% \DescribeOption{toc}
+% |toc|$=$\verb+|book|part|chapter|section|subsection|subsubsection|paragraph+\\
+% |subparagraph|\hfill\tcboxverb{Default: not set}\\
+% If |toc| be set, the title of the division goes into the table of
+% contents at the hierarchic level that is specified as value.
+%
+% \paragraph{Formatting the Titles}
+% \DescribeMacro{\FormatDiv} By design, \pkg{ekdosis} does
+% not format the titles. Instead, depending on what is needed for the
+% edition text, \cs{FormatDiv}\marg{n}\marg{code
+% before}\marg{code after} is provided to lay out the titles of any
+% hierarchic depth of division. This command takes three mandatory
+% arguments as follows: \meta{n}, which is the number referring to the
+% particular depth of division to be formatted and some \LaTeX\
+% commands to go before and after the title itself. The following
+% example illustrates how the titles of the largest division can be
+% printed horizontally centered in a larger size:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\FormatDiv{1}{\begin{center}\Large}{\end{center}}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% 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
+\begin{minted}[linenos=false]{latex}
+% Preamble:
+\FormatDiv{1}{\begin{center}\Large}{\end{center}}
+\FormatDiv{2}{\begin{center}\large}{\end{center}}
+\FormatDiv{3}{\bfseries}{.}
+
+% Document:
+\begin{ekdosis}
+ \ekddiv{
+ head={Ἱπποκράτους ἐπιδημιῶν
+ \app{
+ \lem[wit={I,R,H}]{βιβλίον δεύτερον}
+ \rdg[wit=V]{λόγος β’}}},
+ type=book,
+ depth=1,
+ n=II
+ }
+
+ \ekddiv{
+ head={<Τμῆμα πρῶτον>},
+ type=section,
+ depth=2,
+ n=II.1
+ }
+
+ \ekddiv{head=1, type=paragraph, depth=3, n=II.1.1}
+ Ἄνθρακες θερινοὶ ἐν Κραννῶνι· [...]
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \needspace{5\baselineskip}
+% PDF output:---
+% \medskip
+%
+% \resetlinenumber
+% \FormatDiv{1}{\begin{center}\Large}{\end{center}}
+% \FormatDiv{2}{\begin{center}\large}{\end{center}}
+% \FormatDiv{3}{\bfseries}{.}
+% \begin{alignment}[flush,
+% tcols=1,
+% texts=hippocrates[xml:lang="grc"],
+% apparatus=hippocrates]
+% \AtBeginEnvironment{hippocrates}{\selectlanguage{greek}}
+% \begin{hippocrates}
+% \ekddiv{
+% head={Ἱπποκράτους ἐπιδημιῶν
+% \app{
+% \lem[wit={hI,hR,hH}]{βιβλίον δεύτερον}
+% \rdg[wit=hV]{λόγος β’}}},
+% type=book,
+% depth=1,
+% n=II}
+%
+% \ekddiv{head={<Τμῆμα πρῶτον>}, type=section, depth=2, n=II.1}
+%
+% \ekddiv{head=1, type=paragraph, depth=3, n=II.1.1} Ἄνθρακες
+% θερινοὶ ἐν Κραννῶνι· [...]
+% \end{hippocrates}
+% \end{alignment}
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<div xml:id="div-hippocrates_1" xml:lang="grc">
+ <div type="book" n="II">
+ <head>Ἱπποκράτους ἐπιδημιῶν
+ <app>
+ <lem wit="#I #R #H">βιβλίον δεύτερον</lem>
+ <rdg wit="#V">λόγος β’</rdg>
+ </app></head>
+ <div type="section" n="II.1">
+ <head>&lt;Τμῆμα πρῶτον&gt;</head>
+ <div type="paragraph" n="II.1.1">
+ <head>1</head>
+ <p>Ἄνθρακες θερινοὶ ἐν Κραννῶνι· [...]</p>
+ </div>
+ </div>
+ </div>
+</div>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \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}
+% Several examples of \texttt{TEI xml} output have been provided
+% hitherto. Before proceeding, the reader is invited to return to
+% every one of them. In this respect, it may be of interest to review
+% carefully the excerpt of Caesar's \emph{Gallic War} of which the
+% \LaTeX\ source file and its corresponding \texttt{TEI xml} output
+% are printed in full below in \vref{sec:caesar-gw-6-1-13}. Once
+% \pkg{ekdosis} has been instructed to convert the edition text into
+% \texttt{TEI xml} (l.~11), the preamble of this file shows how to set
+% languages and fonts to be used in the document (ll.~2--6), format
+% the titles (l.~16) and lay out the alignment of an edition text
+% associated with two translations (ll.~18--25) in modern
+% languages. Furthermore, it shows how information related to each
+% language (Latin, English and French) is to be found in two different
+% places, namely for \texttt{TEI xml} output (ll.~21--3) and for PDF
+% output through \LaTeX\ (ll.~27--9). Finally, it provides examples of
+% declaring witnesses, hands, scholars and shorthands (ll.~31--60). As
+% to the document itself, it shows how to lay out a conspectus
+% siglorum in a table (ll.~64--80), before giving detailed examples of
+% how the edition text is entered (ll.~85--101) and sectional commands
+% provided by \pkg{ekdosis} are used (ll.~86, 103 and
+% 110).\footnote{The PDF output is available as
+% \href{samples/Caesar_BG-6-13-1.pdf}{a separate file}.}
+%
+% \subsection{Requesting \texttt{TEI xml} Output}
+% \label{sec:request-tei-output}
+% \texttt{TEI xml} output is requested by means of the |teiexport|
+% global option as described above
+% \vpageref{ref:teiexport-option}. Once instructed to output
+% \texttt{TEI}, \pkg{ekdosis} converts and exports in sequence the
+% contents of \env{ekdosis} environments (see above
+% \vref{sec:single-text-editing}). As regards the contents of
+% \env{alignment} environments (see above \vref{sec:alignment-basic}),
+% \pkg{ekdosis} first collates the contents of the environments that
+% have been declared as values of the |texts| optional argument of
+% \env{alignment} or \cs{SetAlignment},\footnote{See above
+% \vref{sec:multiple-alignment}.} then places each of the
+% corresponding \texttt{TEI xml} outputs within distinct |<div>|
+% elements named after the declared environments themselves. For
+% example, to return to Caesar's text, the Latin edition text is found
+% between a \cs{begin}|{latin}| \dots\ \cs{end}|{latin}| environment
+% (see the |.tex| source file, \vref{sec:caesar-gw-tex}, ll.~85--101)
+% which is declared at l.~21. Then, the corresponding \texttt{xml}
+% output is found within a |<div>| element, the |xml:id| of which has
+% been given by \pkg{ekdosis} the value |div-latin_1| (see
+% \vref{sec:caesar-gw-tei}, ll.~176--200).
+%
+% \paragraph{\texttt{TEI} File Name} \DescribeMacro{\SetTEIFilename}
+% \cs{SetTEIFilename}\marg{basename} is a preamble-only command. It
+% can be used to set the base name of the \texttt{TEI xml} output
+% file, to which the suffix |.xml| is appended. By default, the base
+% name is \cs{jobname}|-tei|.
+%
+% \subsection{General Principles}
+% \label{sec:totei-general-principles}
+% \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}.
+% 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
+% said, one must keep in mind that the \LaTeX\ packages that are part
+% of {\TeX}Live can be counted in thousands, and the commands they
+% provide in tens of thousands. There may even be grounds in asserting
+% that the possibilities offered by \TeX\ and \LaTeX\ quite exceed
+% what can be afforded by \texttt{TEI xml}. On another hand, many
+% \LaTeX\ commands make no sense in \texttt{TEI}. Therefore, a
+% sensible choice is to keep them out of the environments the contents
+% 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} 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}
+% \label{ref:setteixmlexport}
+% \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}| described above
+% \vpageref{ref:setteixmlexport}:---
+%
+% \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
+%
+% 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}
-% \label{sec:correspondance-alignment}
+% \label{sec:correspondence-alignment}
%
% \label{ref:segmentation}
%
@@ -2309,8 +4855,70 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% recommend releasing these examples in parallel under your choice of
% free software license, such as the GNU General Public License,
% to permit their use in free software.
+%
+% \section{References}
+% \label{sec:references}
+% \printbibliography[heading=none]
+%
+% \section{Sample: C. J. Caesar, \emph{Gallic War},
+% VI, XIII.1}
+% \label{sec:caesar-gw-6-1-13}
+% \subsection{\texttt{.tex} Source File}
+% \label{sec:caesar-gw-tex}
+% \inputminted[linenos=true]{latex}{samples/Caesar_BG-6-13-1.tex}
+% \subsection{\texttt{TEI xml} Output}
+% \label{sec:caesar-gw-tei}
+% \inputminted[linenos=true]{xml}{samples/Caesar_BG-6-13-1-tei.xml}
%
-% \printbibliography[heading=bibintoc]
+% \section{Arabic Sample File}
+% \label{sec:arabic-sample}
+% |arabic-sample.tex|:---
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Instructions:
+% 1. Compile this file three times.
+% - Open arabic-sample.pdf and arabic-sample-tei.xml and see the
+% result.
+% 2. Compile arabic-sample_out.tex three times.
+% - Open arabic-sample_out.pdf and arabic-sample-out-tei.xml and
+% see the result.
+%
+\documentclass{article}
+
+% The following three lines are only needed by the
+% 'arabic-sample_out.tex' that arabluatex is instructed to produce:
+\usepackage{babel}
+\babelprovide[onchar=fonts]{arabic}
+\babelfont[*arabic]{rm}{Amiri}
+
+% instruct ekdosis to output TEI xml (arabic-sample-tei.xml):
+\usepackage[teiexport=tidy]{ekdosis}
+
+% instruct arabluatex to ouput sample-arabic_out.tex with Unicode
+% Arabic strings in place of arabtex ASCII scheme:
+\usepackage[fullvoc,export]{arabluatex}
+
+\begin{document}
+
+\begin{arabexport} % export arabtex strings to Unicode Arabic
+ \begin{ekdosis}
+ \begin{arab}
+ 'inna 'abI kAna mina
+ \app{
+ \lem{'l-muqAtilaTi}
+ \rdg{'l-muqAtilIna}
+ }
+ wa-kAnat 'ummI min `u.zamA'i buyUti 'l-zamAzimaTi.
+ \end{arab}
+ \end{ekdosis}
+\end{arabexport}
+\end{document}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
%
% \StopEventually{}
%
@@ -2344,7 +4952,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\newif\iftei@export
\ekvdefinekeys{ekdosis}{
choice layout = {float = {\@pkg@floattrue},
- footins = {\@pkg@footinstrue}},
+ footins = {\@pkg@floatfalse\@pkg@footinstrue}},
initial layout = float,
unknown-choice layout = \PackageError{ekdosis}{unknown
layout=#1}{`layout' must be either `float' or `footins'.},
@@ -2389,8 +4997,11 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\RequirePackage{lineno}
\RequirePackage{keyfloat}
\RequirePackage{refcount}
-\RequirePackage[user,abspage]{zref}
+\RequirePackage{zref-user}
+\RequirePackage{zref-abspage}
\RequirePackage{ltxcmds}
+\RequirePackage{atbegshi}
+\RequirePackage{ifoddpage}
\if@pkg@parnotes
\RequirePackage{parnotes}
\fi
@@ -2404,11 +5015,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\luadirect{ekdosis.closestream()}
}
% \end{macrocode}
-% Use |\normalfont| for line numbers:---
-% \begin{macrocode}
-\renewcommand\linenumberfont{\normalfont\footnotesize}
-% \end{macrocode}
-% \begin{macro}{\SetEkdosisHooks} \cs{SetEkdosisHooks} is used to set
+% \begin{macro}{\SetHooks} \cs{SetHooks} is used to set
% hooks meant to be shared by all declared apparatuses, such as the
% font size, the format of numerals, \emph{\&c.} This command can be
% used in the preamble or at any point of the document.
@@ -2421,7 +5028,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
initial refnumstyle = \bfseries,
initial postrefnum = ~
}
-\NewDocumentCommand{\SetEkdosisHooks}{m}{\ekvset{ekd@hooks}{#1}}
+\NewDocumentCommand{\SetHooks}{m}{\ekvset{ekd@hooks}{#1}}
% \end{macrocode}
% \end{macro}
% Build and process the list of witnesses and hands:---
@@ -2508,15 +5115,54 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\@onlypreamble\DeclareShorthand
% \end{macrocode}
% \end{macro}
+% \begin{macro}{\getsiglum}
+% \cs{getsiglum}\marg{csv list} takes a comma-separated list of
+% declared ids by means of \cs{DeclareWitness}, \cs{DeclareHand},
+% \cs{DeclareShorthand} or \cs{DeclareScholar} and returns their
+% respective renditions.
% \begin{macrocode}
\NewDocumentCommand{\getsiglum}{m}{%
\luadirect{tex.sprint(ekdosis.getsiglum(\luastringN{#1}))}%
}
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\SigLine}
+% \cs{Sigline}\marg{unique id} takes the unique id of any declared
+% witness by means of \cs{DeclareWitness} as argument and returns a
+% line ready to be inserted in a table set to print a Conspectus
+% Siglorum. \cs{SigLine} returns three fields separated by the symbol
+% |&| that is used in tables as follows: the siglum referring to the
+% witness, the contents of the |description| field and the contents of
+% the optional |origDate| field.
+% \begin{macrocode}
\NewDocumentCommand{\SigLine}{m}{%
\luadirect{tex.sprint(ekdosis.basic_cs(\luastringN{#1}))}
}
% \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.
@@ -2587,8 +5233,8 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% \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}
@@ -2600,7 +5246,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% \end{macro}
%
%\paragraph{Multi-layer apparatuses}
-% \pkg{ekdosis} must know is an entry is to be processed in a single-
+% \pkg{ekdosis} must know if an entry is to be processed in a single-
% or multiple-layer context:---
% \begin{macrocode}
\newif\ifekd@mapps
@@ -2613,11 +5259,14 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
unknown-choice direction = \PackageError{ekdosis}{unknown
direction=#1}{`direction' must be either `LR' or `RL'.},
store rule = \rule@val,
- store delim = \delim@val,
+ nmeta norule = {rule=none},
+ code delim = \def\delim@val{\unexpanded{#1}},
store sep = \sep@val,
store bhook = \bhook@val,
store ehook = \ehook@val,
+ store maxentries = \limit@val,
initial direction = LR,
+ initial delim = {},
initial ehook = {\csname ekd@end@apparatus\endcsname}
}
% \end{macrocode}
@@ -2625,11 +5274,13 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% \cs{DeclareApparatus}\marg{apparatus name}\oarg{options} is a
% preamble-only command. As a mandatory argument, it takes the name of
% the new layer of notes to be inserted in the apparatus block. Then,
-% the following six key-value options can be used to lay out the
+% the following seven key-value options can be used to lay out the
% layer: \verb+direction=LR|RL+, |rule|, |delim| (the delimiter between
% entries), |sep| (the separator between lemma part and readings or
% notes), |bhook| (\LaTeX{} code inserted as the layer begins),
-% |ehook| (\LaTeX{} code inserted as the layer ends):---
+% |ehook| (\LaTeX{} code inserted as the layer ends), |maxentries|
+% (if set and |maxentries >= 10|, the number of entries at which a
+% \cs{pagebreak} is issued):---
% \begin{macrocode}
\NewDocumentCommand{\DeclareApparatus}{m O{}}{
\newbool{subsq@unit@#1}
@@ -2644,7 +5295,8 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\luastringO{\delim@val},
\luastringO{\sep@val},
\luastringO{\bhook@val},
- \luastringO{\ehook@val}
+ \luastringO{\ehook@val},
+ \luastringO{\limit@val}
)}
\egroup
}
@@ -2712,14 +5364,42 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% \end{macro}
% \paragraph{Single-layer apparatus} The following commands are for
% general settings. All of them can be used in the preamble or at any
-% point of the document:---
+% point of the document. The keys to be used follow:---
+% \begin{macrocode}
+\newif\ifrtl@app
+\edef\ekdsep{] }
+\ekvdefinekeys{default@app}{
+ choice direction = {LR = \rtl@appfalse,
+ RL = \rtl@apptrue},
+ unknown-choice direction = \PackageError{ekdosis}{unknown
+ direction=#1}{`direction' must be either `LR' or `RL'.},
+ code sep = \edef\ekdsep{#1},
+ store bhook = \ekd@begin@apparatus,
+ initial bhook = {},
+ store ehook = \ekd@end@apparatus,
+ initial ehook = {},
+ store delim = \ekd@unit@delim,
+ initial delim = {},
+ store rule = \ekd@default@rule,
+ initial rule = \rule{0.4\columnwidth}{0.4pt},
+ noval norule = \def\ekd@default@rule{\mbox{}}
+}
+% \end{macrocode}
+% \begin{macro}{\SetApparatus}
+% All settings can also be defined as |key-value| options within the
+% argument of \cs{SetApparatus}:---
+% \begin{macrocode}
+\NewDocumentCommand{\SetApparatus}{m}{
+ \ekvset{default@app}{#1}
+}
+% \end{macrocode}
+% \end{macro}
% \begin{macro}{\SetLTRapp}
% \begin{macro}{\SetRTLapp}
% \cs{SetLTRapp} and \cs{SetRTLapp} are two argument-less commands to
% set the direction of single-layer apparatus criticus, either LTR or
% RTL:---
% \begin{macrocode}
-\newif\ifrtl@app
\NewDocumentCommand{\SetRTLapp}{}{\rtl@apptrue}
\NewDocumentCommand{\SetLTRapp}{}{\rtl@appfalse}
% \end{macrocode}
@@ -2730,17 +5410,23 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% between lemma texts and variant readings, which is by default
% a closing square bracket followed by a space (\verb*+] +):---
% \begin{macrocode}
-\edef\ekdsep{] }
\NewDocumentCommand{\SetSeparator}{m}{\edef\ekdsep{#1}}
% \end{macrocode}
% \end{macro}
+% \begin{macro}{\SetBeginApparatus}
+% \cs{SetBeginApparatus}\marg{characters} can be used to append
+% characters at the beginning of the apparatus block. By default,
+% nothing is appended:---
+% \begin{macrocode}
+\NewDocumentCommand{\SetBeginApparatus}{m}{\edef\ekd@begin@apparatus{#1}}
+% \end{macrocode}
+% \end{macro}
% \begin{macro}{\SetEndApparatus}
% \cs{SetEndApparatus}\marg{characters} can be used to append
-% characters at the end of the apparatus block\---such as a full stop,
+% characters at the end of the apparatus block\---such as a period,
% as it is customary in some editions. By default, nothing is
% appended:---
% \begin{macrocode}
-\edef\ekd@end@apparatus{}
\NewDocumentCommand{\SetEndApparatus}{m}{\edef\ekd@end@apparatus{#1}}
% \end{macrocode}
% \end{macro}
@@ -2751,7 +5437,6 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% can be used to insert a broad space (with |\hskip| for instance, as
% in the OCT series) or the divider-sign (‖, as in the Budé series):---
% \begin{macrocode}
-\def\ekd@unit@delim{}
\NewDocumentCommand{\SetUnitDelimiter}{m}{\def\ekd@unit@delim{#1}}
% \end{macrocode}
% \end{macro}
@@ -2765,7 +5450,6 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% \cs{footnoteruletrue} leaves it untouched. The latter is set by
% default.
% \begin{macrocode}
-\def\ekd@default@rule{\rule{2truein}{0.5pt}}
\newif\iffootnoterule
\footnoteruletrue
\let\dflt@footnoterule\footnoterule
@@ -2784,11 +5468,12 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% \end{macro}
% \end{macro}
% \begin{macro}{\SetDefaultRule}
-% By default, \pkg{ekdosis} draws separating rules the definition of
-% which is |\rule{2truein}{0.5pt}|. This can be changed in the
-% preamble or at any point of the document with
-% \cs{SetDefaultRule}\marg{\allowbreak{}rule definition}. Leaving this
-% argument empty as in \cs{SetDefaultRule}|{}| removes the rule.
+% By default, \pkg{ekdosis} draws separating rules the definition of
+% which is |\rule{0.4\columnwid|\allowbreak|th}{0.4pt}|. This can be
+% changed in the preamble or at any point of the document with
+% \cs{SetDefaultRule}\marg{\allowbreak{}rule definition}. Leaving
+% this argument empty as in \cs{SetDefaultRule}|{}| removes the
+% rule.
% \begin{macrocode}
\NewDocumentCommand{\SetDefaultRule}{m}{%
\def\@tempa{#1}
@@ -2849,7 +5534,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\fi%
}
% \end{macrocode}
-% Before inserting any new entry, \cs{add@apparatus} is called
+% Before inserting any new entry, \cs{add@apparatus} calls
% \cs{test@apparatus} to decide whether a new apparatus block must be
% created on a given page.
% \begin{macrocode}
@@ -2878,16 +5563,96 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
{\luadirect{tex.sprint(ekdosis.mdvappend(\luastringO{#2},
\luastringO{#1}))}}}
% \end{macrocode}
-% \begin{macro}{\EkdosisDefaultApparatus}
+% \paragraph{Lineation settings}
+% \begin{macro}{\outerlinenumbers}
+% \begin{macro}{\innerlinenumbers}
+% \pkg{ekdosis} does not use the \enquote{pagewise} numbering mode
+% that is provided by \pkg{lineno}. Therefore,
+% \cs{outerlinenumbers} and \cs{innerlinenumbers} are defined in
+% addition to \cs{rightlinenum{\allowbreak}bers} and
+% \cs{leftlinenumbers}.
+% \begin{macrocode}
+\def\outerlinenumbers{
+ \def\makeLineNumberRunning{
+ \checkoddpage
+ \ifoddpage
+ \linenumberfont\hskip\linenumbersep\hskip\textwidth
+ \hbox to\linenumberwidth{\hss\LineNumber}\hss
+ \else
+ \hss\linenumberfont\LineNumber\hskip\linenumbersep
+ \fi
+ }
+}
+\def\innerlinenumbers{
+ \def\makeLineNumberRunning{
+ \checkoddpage
+ \ifoddpage
+ \hss\linenumberfont\LineNumber\hskip\linenumbersep
+ \else
+ \linenumberfont\hskip\linenumbersep\hskip\textwidth
+ \hbox to\linenumberwidth{\hss\LineNumber}\hss
+ \fi
+ }
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% The keys to be used for lineation settings follow. A conditional is
+% defined beforehand so that \pkg{ekdosis} may know whether the
+% numbering should start afresh at the top of each page.
+% \begin{macrocode}
+\newif\ifekd@pagelineation
+\NewDocumentCommand{\ekdatbegshihook}{}{%
+ \ifekd@pagelineation\resetlinenumber\fi
+}
+\AtBeginShipout{\ekdatbegshihook}
+\newif\ifekd@elidednumbers
+\ekvdefinekeys{ekd@lineation}{
+ choice lineation = {page = \ekd@pagelineationtrue,
+ document = \ekd@pagelineationfalse},
+ unknown-choice lineation = \PackageError{ekdosis}{unknown
+ lineation=#1}{`lineation' must be either `page' or `document'.},
+ code modulonum = \chardef\c@linenumbermodulo#1\relax,
+ noval modulo = \modulolinenumbers,
+ choice numbers = {elided = \ekd@elidednumberstrue,
+ full = \ekd@elidednumbersfalse},
+ unknown-choice numbers = \PackageError{ekdosis}{unknown
+ numbers=#1}{`numbers' must be either `elided' or `full'.},
+ initial numbers = elided,
+ choice margin = {right = \rightlinenumbers,
+ left = \leftlinenumbers,
+ inner = \innerlinenumbers,
+ outer = \outerlinenumbers},
+ unknown-choice margin = \PackageError{ekdosis}{unknown
+ margin=#1}{`margin' must be either `left', `right', \MessageBreak
+ `inner' or `outer'}
+}
+% \end{macrocode}
+% \begin{macro}{\SetLineation}
+% Then \cs{SetLineation}\marg{options} can be used in the preamble or
+% at any point of the document to set lineation preferences. Its
+% argument processes the |key-value| options that are defined just
+% above.
+% \begin{macrocode}
+\NewDocumentCommand{\SetLineation}{m}{
+ \ekvset{ekd@lineation}{#1}
+}
+% \end{macrocode}
+% \end{macro}
+% Use |\normalfont| for line numbers:---
+% \begin{macrocode}
+\renewcommand\linenumberfont{\normalfont\footnotesize}
+% \end{macrocode}
+% \begin{macro}{\SetDefaultApparatus}
% By default, \pkg{ekdosis} defines one layer of critical notes which
% is called |default|. This name can be changed at any point of the
-% document with \cs{EkdosisDefaultApparatus}\marg{name}.
+% document with \cs{SetDefaultApparatus}\marg{name}.
% \begin{macrocode}
\ekvdefinekeys{appnote}{
store type = \ekdan@type,
initial type = default
}
-\NewDocumentCommand{\EkdosisDefaultApparatus}{m}{%
+\NewDocumentCommand{\SetDefaultApparatus}{m}{%
\ekvset{appnote}{type=#1}}
% \end{macrocode}
% \end{macro}
@@ -2956,8 +5721,13 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\fi
%
\else
+ \ifekd@elidednumbers
+ \luadirect{tex.sprint(ekdosis.numrange(\luastring{\getrefnumber{#1}},
+ \luastring{\getrefnumber{#2}}))}%
+ \else
\LRnum{\getrefnumber{#1}}--%
\LRnum{\getrefnumber{#2}}% issue the nos
+ \fi
\fi%
\else
\LRnum{\getrefnumber{#1}}--%
@@ -3009,8 +5779,14 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\fi
%
\else
+ \ifekd@elidednumbers
+ \luadirect{tex.sprint(ekdosis.numrange(
+ \luastring{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}},
+ \luastring{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}}))}% issue the nos
+ \else
\LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}--%
\LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-e}}% issue the nos
+ \fi
\fi%
\else
\LRnum{\getrefnumber{\luadirect{tex.sprint(ekdosis.getlnlab())}-b}}--%
@@ -3057,6 +5833,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\NewDocumentCommand{\lem}{O{} m}{%
\ekd@isinlemtrue%
\luadirect{ekdosis.dolnlab(\luastringN{#2})}%
+ \null
\bgroup%
\ekvset{lem}{#1}%
\ifekd@mapps%
@@ -3068,6 +5845,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\luadirect{ekdosis.increment_bagunits(\luastringO{\ekdan@type})}%
\def\ekd@munit@delim{%
\luadirect{tex.sprint(ekdosis.getappdelim(\luastringO{\ekdan@type}))}}%
+ \luadirect{tex.sprint(ekdosis.limit_bagunits(\luastringO{\ekdan@type}))}%
\fi%
\ifekdl@nolem\edef\lem@app{%
% \hskip .75em
@@ -3133,8 +5911,8 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\ifdefined\ekdlr@pre%
\space\unexpanded\expandafter{\ekdlr@pre}\space\else\fi
\ltx@ifpackageloaded{babel}%
- {\noexpand\selectlanguage{\languagename}\unexpanded{#2}}{%
- \unexpanded{#2}}%
+ {{\noexpand\selectlanguage{\languagename}\unexpanded{#2}}}{%
+ {\unexpanded{#2}}}%
\ifdefined\ekdlr@post%
\space\unexpanded\expandafter{\ekdlr@post}\space\else\fi
\fi
@@ -3214,8 +5992,8 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\ifdefined\ekdlr@pre%
\space\unexpanded\expandafter{\ekdlr@pre}\space\else\fi
\ltx@ifpackageloaded{babel}%
- {\noexpand\selectlanguage{\languagename}\unexpanded{#2}}{%
- \unexpanded{#2}}%
+ {{\noexpand\selectlanguage{\languagename}\unexpanded{#2}}}{%
+ {\unexpanded{#2}}}%
\ifdefined\ekdlr@post%
\space\unexpanded\expandafter{\ekdlr@post}\space\else\fi
\fi
@@ -3245,6 +6023,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
code labelb = \def\ekdn@labelb{#1},
code labele = \def\ekdn@labele{#1},
store sep = \ekdn@sep,
+ bool nosep = \ifekdn@nosep,
initial type = default,
initial sep = \ekdsep
}
@@ -3258,6 +6037,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% specified; otherwise \pkg{ekdosis} will issue an error message.
% \begin{macrocode}
\NewDocumentCommand{\note@noapp}{O{} +m}{%
+ \null
\bgroup%
\ekvset{note}{#1}%
\stepcounter{ekd@lab}%
@@ -3274,6 +6054,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\luadirect{ekdosis.increment_bagunits(\luastringO{\ekdan@type})}%
\def\ekd@munit@delim{%
\luadirect{tex.sprint(ekdosis.getappdelim(\luastringO{\ekdan@type}))}}%
+ \luadirect{tex.sprint(ekdosis.limit_bagunits(\luastringO{\ekdan@type}))}%
\fi%
\ifdefined\ekdn@labelb%
\luadirect{tex.sprint(ekdosis.setnotelab(\luastringO{\ekdn@labelb}))}%
@@ -3292,7 +6073,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\current@ref@arg{\ekdn@labelb}{\ekdn@labele}%\hskip .25em
\ifdefined\ekdn@lem%
{\textdir TRT\unexpanded\expandafter{\ekdn@lem}}%
- \unexpanded\expandafter{\ekdn@sep}\else\fi%
+ \unless\ifekdn@nosep
+ \unexpanded\expandafter{\ekdn@sep}\fi
+ \else\fi%
{\textdir TRT\unexpanded{#2}}}}%
{\edef\note@contents{%
% \hskip .75em
@@ -3308,18 +6091,21 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
{\noexpand\selectlanguage{\languagename}%
\unexpanded\expandafter{\ekdn@lem}}%
{\unexpanded\expandafter{\ekdn@lem}}%
- \unexpanded\expandafter{\ekdn@sep}\else\fi%
+ \unless\ifekdn@nosep
+ \unexpanded\expandafter{\ekdn@sep}\fi
+ \else\fi%
\ltx@ifpackageloaded{babel}%
- {\noexpand\selectlanguage{\languagename}\unexpanded{#2}}{%
- \unexpanded{#2}}}}%
+ {{\noexpand\selectlanguage{\languagename}\unexpanded{#2}}}{%
+ {\unexpanded{#2}}}}}%
\ifekd@mapps%
\unconditional@appin[\ekdan@type]{\note@contents}%
\else%
\unconditional@appin{\note@contents}%
\fi%
\luadirect{ekdosis.setprevnotelab(\luastringO{\ekdn@labelb})}%
- \egroup%
- \subsq@unittrue%
+ \egroup
+ \subsq@unittrue
+ \ignorespaces
}
% \end{macrocode}
% Define keys to be used by the optional argument of \cs{note} when
@@ -3344,7 +6130,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\edef\note@contents{%
\ekvifdefinedNoVal{note}{pre}{}{%
\unexpanded\expandafter{\pre@value}}%
- \unexpanded{#2}%
+ {\unexpanded{#2}}%
\ekvifdefinedNoVal{note}{post}{}{%
\unexpanded\expandafter{\post@value}}%
}%
@@ -3358,7 +6144,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\edef\note@contents{%
\ekvifdefinedNoVal{note}{pre}{}{%
\unexpanded\expandafter{\pre@value}}%
- \unskip\noexpand\parnote{#2}%
+ \unskip\noexpand\parnote{\unexpanded{#2}}%
\ekvifdefinedNoVal{note}{post}{}{%
\unexpanded\expandafter{\post@value}}%
}%
@@ -3453,12 +6239,11 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\luadirect{ekdosis.exporttei(\luastringN{\par #1\par })}\fi}
% \end{macrocode}
% \end{environment}
-% \paragraph{Alignment} What follows isto arrange texts in parallel
+% \paragraph{Alignment} What follows is to arrange texts in parallel
% columns either on single pages or on facing pages.
%
% Define keys to be used by the \env{alignment} environment:---
% \begin{macrocode}
-\newif\ifekd@pagelineation
\ekvdefinekeys{ekd@align}{
store tcols = \tcols@num,
store lcols = \lcols@num,
@@ -3482,12 +6267,12 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
default segmentation = auto
}
% \end{macrocode}
-% \begin{macro}{\SetEkdosisAlignment}
-% \cs{SetEkdosisAlignment}\marg{settings} can be used either in the
+% \begin{macro}{\SetAlignment}
+% \cs{SetAlignment}\marg{settings} can be used either in the
% preamble or at any point of the document to set or modify the
% keys-value settings just defined above.
% \begin{macrocode}
-\NewDocumentCommand{\SetEkdosisAlignment}{m}{
+\NewDocumentCommand{\SetAlignment}{m}{
\ekvset{ekd@align}{#1}
}
% \end{macrocode}
@@ -3533,10 +6318,10 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% right-hand pages. To that effect, it provides by default two new
% environments, \env{edition} and \env{translation}, to be used to
% typeset both texts. (Either whole texts or texts entered by
-% paragraphs alternately.) The optional argument of \env{aligment}
-% accepts the exact same key-value options as \cs{SetEkdosisAlignment}
+% paragraphs alternately.) The optional argument of \env{alignment}
+% accepts the exact same key-value options as \cs{SetAlignment}
% described above. One may contrast these options with those accepted
-% by \cs{SetEkdosisAlignment} as \enquote{local settings}.
+% by \cs{SetAlignment} as \enquote{local settings}.
% \begin{macrocode}
\NewDocumentEnvironment{alignment}{O{}}
{%
@@ -3619,14 +6404,14 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
initial depth = 1
}
% \end{macrocode}
-% \begin{macro}{\ekdfmtdiv}
-% \cs{ekdfmtdiv}\marg{n}\marg{code before}\marg{code after} is
-% used to lay out the heading of the title. It takes three mandatory
-% arguments: \emph{n}, namely the number referring to the particular
-% depth of the division, and then some \LaTeX{} formatting commands
-% to go before and after the heading itself:---
+% \begin{macro}{\FormatDiv}
+% \cs{FormatDiv}\marg{n}\marg{code before}\marg{code
+% after} is used to lay out the heading of the title. It takes three
+% mandatory arguments: \emph{n}, namely the number referring to the
+% particular depth of the division, and then some \LaTeX{} formatting
+% commands to go before and after the heading itself:---
% \begin{macrocode}
-\NewDocumentCommand{\ekdfmtdiv}{m m m}{
+\NewDocumentCommand{\FormatDiv}{m m m}{
\luadirect{ekdosis.fmtdiv(\luastring{#1},
\luastringN{#2},
\luastringN{#3})}
@@ -3634,7 +6419,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% \end{macrocode}
% \end{macro}
% \cs{ekd@getfmtdiv} gets the formatting commands that have been
-% stored by \cs{ekdfmtdiv}.
+% stored by \cs{FormatDiv}.
% \begin{macrocode}
\NewDocumentCommand{\ekd@getfmtdiv}{m m}{%
\luadirect{tex.sprint(ekdosis.getfmtdiv(\luastringO{#1},
@@ -3645,7 +6430,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
% \cs{ekddiv}\marg{key-value arguments} is the standard command
% provided by \pkg{ekdosis} to meet the requirements of classical and
% literary texts the divisions of which depend on many different
-% received traditions. It takes one optional argument in which the
+% received traditions. It takes one mandatory argument in which the
% key-value arguments defined above are accepted, and converts the
% divisions into \texttt{TEI} \enquote*{un-numbered} |<div>|
% elements.
@@ -3687,7 +6472,16 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
\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
@@ -3733,10 +6527,35 @@ 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")
+ + lpeg.P("ref")
+ + 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
@@ -3752,6 +6571,16 @@ local function xmlidfound(element)
return false
end
+local function checkxmlid(str)
+ if string.find(str, "^[0-9]")
+ or string.find(str, "[:; ]")
+ then
+ return false
+ else
+ return true
+ end
+end
+
-- Witnesses
listWit = {}
idsRend = {}
@@ -3813,7 +6642,14 @@ function ekdosis.newwitness(id,
then
tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
..id..
- "\" already exists as a xml: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
@@ -3846,7 +6682,14 @@ function ekdosis.newhand(id, witid, siglum, description)
then
tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
..id..
- "\" already exists as a xml: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
@@ -3896,9 +6739,16 @@ function ekdosis.newscholar(id, siglum)
then
tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
..id..
- "\" already exists as a xml: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)
@@ -3955,18 +6805,17 @@ 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="\\icite%s?%[(.-)%]%[(.-)%]{(.-)}", b="%1 <ref target=\"#%3\">%2</ref>"},
- {a="\\icite%s?%[(.-)%]{(.-)}", b="<ref target=\"#%2\">%1</ref>"},
- {a="\\icite%s?{(.-)}", b="<ptr target=\"#%1\"/>"},
- {a="\\linelabel%s?{(.-)}", b="<anchor xml:id=\"%1\"/>"},
- {a="\\label%s?{(.-)}", b="<anchor xml:id=\"%1\"/>"},
- {a="\\v?pageref%s?{(.-)}", b="<ptr target=\"#%1\"/>"},
- {a="\\v?ref%s?{(.-)}", b="<ptr target=\"#%1\"/>"}
+ {a="\\pagebreak%s+%[[1-4]%]", b=""},
+ {a="\\pagebreak%s+", b=""},
+ {a="\\altrfont%s+", b=""},
+ {a="\\LR%s+{(.-)}", b="%1"},
+ {a="\\RL%s+{(.-)}", b="%1"}
}
local envtotags = {
@@ -3975,6 +6824,8 @@ local envtotags = {
{a="quotation", b="quote", c=""},
{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=""},
@@ -4229,6 +7080,70 @@ local function texpatttotei(str)
return str
end
+local function icitetotei(str)
+ str = gsub(str, lpeg.P("\\")
+ * citecmds
+ * spcenc^-1
+ * bsqbrackets
+ * bsqbrackets
+ * bcbraces
+ * bsqbrackets^-1,
+ function(cmd, pre, post, body, opt)
+ pre = string.sub(pre, 2, -2)
+ post = string.sub(post, 2, -2)
+ body = string.sub(body, 2, -2)
+ if not checkxmlid(body)
+ then
+ tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
+ ..body..
+ "\" is not a valid xml:id. \\MessageBreak "
+ ..
+ "Please pick another id.}}")
+ else
+ end
+ return string.format("%s <ref target=\"#%s\">%s</ref>", pre, body, post)
+ end)
+ str = gsub(str, lpeg.P("\\")
+ * citecmds
+ * spcenc^-1
+ * bsqbrackets
+ * bcbraces
+ * bsqbrackets^-1,
+ function(cmd, post, body, opt)
+ post = string.sub(post, 2, -2)
+ body = string.sub(body, 2, -2)
+ if not checkxmlid(body)
+ then
+ tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
+ ..body..
+ "\" is not a valid xml:id. \\MessageBreak "
+ ..
+ "Please pick another id.}}")
+ else
+ end
+ return string.format("<ref target=\"#%s\">%s</ref>", body, post)
+ end)
+ str = gsub(str, lpeg.P("\\")
+ * citecmds
+ * spcenc^-1
+ * bcbraces
+ * bsqbrackets^-1,
+ function(cmd, body, opt)
+ body = string.sub(body, 2, -2)
+ if not checkxmlid(body)
+ then
+ tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
+ ..body..
+ "\" is not a valid xml:id. \\MessageBreak "
+ ..
+ "Please pick another id.}}")
+ else
+ end
+ return string.format("<ptr target=\"#%s\"/>", body)
+ end)
+ return str
+end
+
local function cmdtotei(str)
for i = 1,#cmdtotags
do
@@ -4264,6 +7179,25 @@ local function cmdtotei(str)
return string.format("<ref target=\"%s\">%s</ref>",
teisiglum, printsiglum)
end)
+ str = gsub(str, lpeg.P("\\") * labelrefcmds * spcenc^-1 * bcbraces,
+ function(cmd, body)
+ body = string.sub(body, 2, -2)
+ if not checkxmlid(body)
+ then
+ tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
+ ..body..
+ "\" is not a valid xml:id. \\MessageBreak "
+ ..
+ "Please pick another id.}}")
+ else
+ end
+ if string.find(cmd, "label")
+ then
+ return string.format("<anchor xml:id=\"%s\"/>", body)
+ else
+ return string.format("<ptr target=\"#%s\"/>", body)
+ end
+ end)
str = string.gsub(str, "\\(%a+)%s?%*?(%b[])(%b{})",
function(cmd, opt, body)
body = string.sub(body, 2, -2)
@@ -4280,19 +7214,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
@@ -4597,6 +7548,7 @@ local function textotei(str)
str = envtotei(str)
str = ekddivs_totei(str)
str = section_totei(str)
+ str = icitetotei(str)
str = cmdtotei(str)
str = self_close_tags(str)
str = partotei(str)
@@ -4855,7 +7807,7 @@ function ekdosis.newalignment(str)
then
newalignment = false
cur_alignment = "-"
- cur_alignment_patt = "-"
+ cur_alignment_patt = "%-"
end
return true
end
@@ -4943,24 +7895,6 @@ end
local environment_div = {}
-function ekdosis.newscholar(id, siglum)
- if xmlidfound(id)
- then
- tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
- ..id..
- "\" already exists as a xml:id. "
- ..
- "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
@@ -4973,10 +7907,17 @@ local function build_envdiv(str)
then
tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
..div..
- "\" already exists as a xml:id. "
+ "\" already exists as an xml:id. "
..
"ekdosis has generated some random id.}}")
return "div-"..math.random(1000,9999)
+ elseif not checkxmlid(div)
+ then
+ tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
+ ..div..
+ "\" is not a valid xml:id. \\MessageBreak "
+ ..
+ "Please pick another id.}}")
else
table.insert(xmlids, {xmlid = div})
table.sort(xmlids, function(a ,b) return(#a.xmlid > #b.xmlid) end)
@@ -5075,7 +8016,8 @@ function ekdosis.newapparatus(teitype,
appdelim,
appsep,
appbhook,
- appehook)
+ appehook,
+ applimit)
if isintable(apparatuses, teitype)
then
tex.print("\\unexpanded{\\PackageWarning{ekdosis}{\""
@@ -5088,7 +8030,8 @@ function ekdosis.newapparatus(teitype,
delim = appdelim,
sep = appsep,
bhook = appbhook,
- ehook = appehook})
+ ehook = appehook,
+ limit = applimit})
end
bagunits[teitype] = 1
return true
@@ -5109,6 +8052,38 @@ function ekdosis.get_bagunits(teitype)
return bagunits[teitype]
end
+local function getapplimit(str)
+ for i = 1,#apparatuses
+ do
+ if apparatuses[i].a == str then
+ limitfound = apparatuses[i].limit
+ break
+ end
+ end
+ if tonumber(limitfound) ~= nil
+ then
+ if tonumber(limitfound) < 10
+ then
+ return 0
+ else
+ return limitfound
+ end
+ else
+ return 0
+ end
+end
+
+function ekdosis.limit_bagunits(teitype)
+ local limit = tonumber(getapplimit(teitype))
+ if limit >= 10 and bagunits[teitype] > limit
+ then
+ bagunits[teitype] = 2
+ return "\\pagebreak"
+ else
+ return ""
+ end
+end
+
function ekdosis.increment_bagunits(teitype)
bagunits[teitype] = (bagunits[teitype] or 0) + 1
end
@@ -5149,7 +8124,8 @@ function ekdosis.appout()
local output = {}
if next(apparatuses) == nil then
-- table.insert(output, "BEGIN")
- table.insert(output, "\\noindent\\csname ekd@default@rule\\endcsname\\NLS{}")
+ table.insert(output, "\\noindent\\csname ekd@default@rule\\endcsname\\NLS")
+ table.insert(output, "\\csname ekd@begin@apparatus\\endcsname\\ignorespaces")
-- table.insert(output, "\\noindent ")
for i in string.gmatch(t,
"<"..cur_abs_pg
@@ -5166,8 +8142,8 @@ function ekdosis.appout()
local n = 1
while apparatuses[n]
do
- if string.match(t, "<"..cur_abs_pg..
- cur_alignment_patt
+ if string.match(t, "<"..cur_abs_pg
+ ..cur_alignment_patt
..curcol.."%-"..n..">.-</"
..cur_abs_pg
..cur_alignment_patt
@@ -5280,10 +8256,54 @@ function ekdosis.testapparatus()
if next(apparatuses) ~= nil then
reset_bagunits()
end
+ newalignment = false
return "\\booltrue{do@app}"
end
end
+local function get_ln_prefix(x, y)
+ for index = 1, string.len(x)
+ do
+ if string.sub(x, index, index) ~= string.sub(y, index, index)
+ then
+ return string.sub(x, 1, index - 1)
+ end
+ end
+end
+
+function ekdosis.numrange(x, y)
+ xstr = tostring(x)
+ ystr = tostring(y)
+ if x == y -- which will never apply
+ then
+ return "\\LRnum{" .. xstr .. "}"
+ elseif string.len(xstr) ~= string.len(ystr)
+ then
+ return "\\LRnum{" .. xstr .. "}--\\LRnum{" .. ystr .. "}"
+ else
+ common = get_ln_prefix(xstr, ystr)
+ if string.len(common) == 0
+ then
+ return "\\LRnum{" .. xstr .. "}--\\LRnum{" .. ystr .. "}"
+ elseif string.sub(xstr, -2, -2) == "1"
+ then
+ return "\\LRnum{"
+ .. string.sub(common, 1, -2)
+ .. string.sub(xstr, string.len(common), -1)
+ .. "}--\\LRnum{"
+ .. string.sub(ystr, string.len(common), -1)
+ .. "}"
+ else
+ return "\\LRnum{"
+ .. string.sub(common, 1, -1)
+ .. string.sub(xstr, string.len(common) + 1, -1)
+ .. "}--\\LRnum{"
+ .. string.sub(ystr, string.len(common) + 1, -1)
+ .. "}"
+ end
+ end
+end
+
local lnlabs = {}
local lnlab_salt = 0
local current_lnlab = nil
@@ -5374,15 +8394,5 @@ end
% \iffalse
%</lua>
% \fi
-%
-% \section{Sample: C. J. Caesar, \emph{Gallic War},
-% VI, XIII.1}
-% \label{sec:caesar-gw-6-1-13}
-% \subsection{\texttt{.tex} Source File}
-% \label{sec:caesar-gw-tex}
-% \inputminted[linenos=false]{latex}{samples/Caesar_BG-6-13-1.tex}
-% \subsection{\texttt{TEI xml} Output}
-% \label{sec:caesar-gw-tei}
-% \inputminted[linenos=false]{xml}{samples/Caesar_BG-6-13-1-tei.xml}
%
\endinput