reshaped documentation on footnotes

2 files changed, 119 insertions, 76 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 7364f5f..111a1b9 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -59,7 +59,7 @@ Alessi <alessi@robertalessi.net>
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{ekdosis}
 %<*package>
-    [2023/06/24 v1.5-dev Typesetting TEI xml-compliant critical editions]
+    [2023/06/29 v1.5-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -714,6 +714,7 @@ Alessi <alessi@robertalessi.net>
 \setlist{nosep}
 \setlist[itemize]{label=\textendash}
 \setlist[enumerate,1]{label=(\alph*)}
+\setlist[enumerate,2]{label=\roman*.}
 \newlist{remarks}{enumerate}{10}
 \setlist[remarks]{
   label*=\textsc{Rem.} \arabic*,
@@ -3636,34 +3637,6 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % \cs{marginparthreshold}\allowbreak\marg{n}\oarg{n'}, that can be
 % used to set the threshold for columns printed in right-hand pages.
 %
-% \subsubsection{Regular Footnotes}
-% \label{sec:regular-footnotes}
-% \DescribeMacro{\footnotelayout} By default, regular footnotes are
-% printed at the bottom of the column on which they are
-% called. \cs{footnotelayout}\marg{key-letter} can be used to change
-% this setting. This command accepts as mandatory argument a
-% key-letter which can be either |c|, |p| or |m|. |c| means
-% \emph{column-wise} footnotes, which is the default value. |p| means
-% \emph{page-wise}: footnotes from all columns are gathered in a
-% single spanning block at the bottom of the page. Finally, |m| stands
-% for \emph{merge}, which means that all footnotes that are called on
-% a given page, including notes that are called outside the
-% \env{alignment} environment, are printed in a single spanning block
-% at the bottom of the page.
-%
-% \danger Regular footnotes are printed above the block of critical
-% notes. The respective places of these blocks can be interchanged by
-% just loading the \pkg{fnpos} package in the
-% preamble.\footcite{fnpos}
-%
-% \danger \phts\label{ref:footmisc} The \pkg{footmisc}
-% package\footcite{footmisc} is not compatible with
-% \pkg{ekdosis}. More precisely, \pkg{footmisc} is incompatible with
-% the way the \cs{footnote} command is defined inside the |alignment|
-% environment. Therefore, \pkg{footmisc} can only be used on the
-% condition that no regular \cs{footnote} be inserted in the
-% |alignment| environment.
-% 
 % \section{Laying Out the Apparatus Criticus}
 % \label{sec:apparatus-layout}
 %
@@ -4438,25 +4411,85 @@ argument of the
 % element (ll.~5--7). Otherwise, the \texttt{TEI} output would not be
 % valid.
 %
-% \subsection{Footnotes Combined Into a Single Paragraph}
+% \section{Footnotes}
 % \label{sec:footnotes}
-% \newfeature[v1.5] As already said \vpageref{ref:footmisc}, the
-% \pkg{footmisc} package is not compatible with
-% \pkg{ekdosis}. Therefore, it cannot be used to reformat short
-% footnotes so as to combine them all into a single paragraph.  This
-% is why \pkg{ekdosis} provides a mechanism of its own to insert such
-% footnotes in a specific layer of the apparatus criticus.
-%
-% \DescribeMacro{\SetFootnotes} \cs{SetFootnotes}\marg{csv list of
-% footnote settings} can be used either in the preamble or at any
-% point of the document to cause a new ouput routine to reformat the
-% notes into a single paragraph. This command accepts the following
-% list of |key-value| optional arguments:---
-% \DescribeOption{layout}|layout|$=$\verb+default|paragraph+
+%
+% \subsection{Regular Footnotes}
+% \label{sec:regular-footnotes}
+%
+% Regular footnotes are inserted by the standard \cs{footnote}
+% command. When the texts are arranged in parallel columns or on
+% facing pages as described in \vref{sec:alignment-basic}, further
+% options are available to specify how the notes should be printed on
+% the pages.
+%
+% \danger Regular footnotes are printed above the block of critical
+% notes. The respective places of these blocks can be interchanged by
+% just loading the \pkg{fnpos} package in the
+% preamble.\footcite{fnpos}
+%
+% \danger \phts\label{ref:footmisc} The \pkg{footmisc}
+% package\footcite{footmisc} is not compatible with
+% \pkg{ekdosis}. More precisely, \pkg{footmisc} is incompatible with
+% the way the \cs{footnote} command is defined inside the |alignment|
+% environment. Therefore, \pkg{footmisc} can only be used on the
+% condition that no regular \cs{footnote} be inserted in the
+% |alignment| environment.
+%
+% \DescribeMacro{\SetFootnotes} \newfeature[v1.5]
+% \cs{SetFootnotes}\marg{csv list of footnote settings} can be used
+% either in the preamble or at any point of the document \emph{as long
+% it is inserted outside the \env{alignment} environment}. This
+% command accepts the following list of |key-value| optional
+% arguments:---\\
+% \DescribeOption{layout} \phts\label{ref:setfootnotes-layout}
+% |layout|$=$\verb+default|column|page|merge+
+% \hfill\tcboxverb{Default: not set}
+% \begin{enumerate}
+% \item |layout=default| or |layout=column| Either |default| or
+%   |column| can be used to have regular footnotes printed at the
+%   bottom of the column in which they are
+%   called. \textoiquote|column|\textciquote\ means
+%   \emph{column-wise}; this option is equivalent to
+%   \cs{footnotelayout}|{c}| in the syntax used by the \pkg{paracol}
+%   package.\footnote{See \cite[20]{paracol} for
+%   details.}\saveFN\fnpcol
+% \item |layout=page| \textoiquote|page|\textciquote\ means
+%   \emph{page-wise}. Footnotes from all columns are gathered in a
+%   single spanning block at the bottom of all columns on the
+%   page. This option is equivalent to \cs{footnotelayout}|{p}| in the
+%   syntax used by the \pkg{paracol} package.\useFN\fnpcol
+% \item |layout=merge| \emph{merge} means that all footnotes that are
+%   called on a given page, including notes that are called outside
+%   the \env{alignment} environment, are printed in a single spanning
+%   block at the bottom of the page. This option is equivalent to
+%   \cs{footnotelayout}|{m}| in the syntax used by the \pkg{paracol}
+%   package.\useFN\fnpcol
+% \end{enumerate}
+%
+% \subsection{Footnotes Combined Into a Single Paragraph}
+% \label{sec:footn-comb-into}
+%
+% As already said \vpageref[above]{ref:footmisc}, the \pkg{footmisc}
+% package is not compatible with \pkg{ekdosis}. Therefore, it cannot
+% be used to reformat short footnotes so as to combine them all into a
+% single paragraph.  This is why \pkg{ekdosis} provides a mechanism of
+% its own to insert such footnotes in a specific layer of the
+% apparatus criticus.
+%
+% \danger Unlike the three possible values that can be passed to
+% |layout| just described, which apply only to regular footnotes
+% inserted in the \env{alignment} environment, the following options
+% apply to both the \env{alignment} and \env{ekdosis} environments.
+%
+% \DescribeMacro{\SetFootnotes} (\emph{Continued from above})\\
+% \DescribeOption{layout}|layout=paragraph|
 % \hfill\tcboxverb{Default: not set}\\
-% |layout=paragraph| instructs \pkg{ekdosis} to reformat the notes
-% into a single paragraph, while |layout=default| reverts to the
-% standard output routine.\\
+% |layout=paragraph| comes in addition to the other three values
+% \vpageref[just described][described]{ref:setfootnotes-layout}. This
+% option instructs \pkg{ekdosis} to reformat the notes into a single
+% paragraph, while |layout=default| reverts to the standard output
+% routine.\\
 % \DescribeOption{type}|type|$=$\meta{type}
 % \hfill\tcboxverb{Initially set as 'default'}\\
 % The keyword |type| is used here in the exact same meaning as
@@ -4482,9 +4515,9 @@ argument of the
 % mark superscripted.
 %
 % \DescribeMacro{\footnote} \cs{footnote}\oarg{options}\marg{text}
-% When the mechanism described above is set in motion, the optional
-% argument of \cs{footnote} accepts the following list of optional
-% arguments:---\\
+% When the mechanism described in this section is set in motion, the
+% \cs{footnote} command is redefined so as to accept the following
+% list of optional arguments:---\\
 % \DescribeOption{layout}|type|$=$\meta{type}
 % \hfill\tcboxverb{Default: as defined in \SetFoonotes}\\
 % |type| allows to specify any layer of critical notes in which the
@@ -8480,7 +8513,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \paragraph{\textsf{ekdosis} Symbol}
 % \begin{macro}{\eKd}
-% \changes{v1.5}{2023/06/24}{Prints \textsf{ekdosis} indentifying
+% \changes{v1.5}{2023/06/29}{Prints \textsf{ekdosis} indentifying
 % symbol} As of v1.5, \pkg{ekdosis} has its own identifying
 % symbol. It is produced by \cs{eKd} and best printed with the Old
 % Standard Greek font.
@@ -8743,7 +8776,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \begin{macro}{\teidirectE}
 % \changes{v1.3}{2021/08/18}{direct insertion of elements in the
 % \texttt{TEI xml} file}
-% \changes{v1.5}{2023/06/24}{direct insertion of empty elements in the
+% \changes{v1.5}{2023/06/29}{direct insertion of empty elements in the
 % \texttt{TEI xml} file}
 % \cs{teidirect}\oarg{xml attributes}\marg{xml element}\marg{code}
 % does nothing in \LaTeX. It is only used to insert elements in the
@@ -8758,7 +8791,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\getTEIxmlid}
-% \changes{v1.5}{2023/06/24}{returns \texttt{TEI xml:ids} from a
+% \changes{v1.5}{2023/06/29}{returns \texttt{TEI xml:ids} from a
 % csv-list of ids} This command returns from a csv-list of unique
 % identifiers declared in commands such as \cs{DeclareWitness} and the
 % like a space-separated list of their corresponding |xml:id|s, each
@@ -9234,7 +9267,7 @@ Sample text with a \textcolor{red}{word} in red.
 \newlength{\ekd@app@localheight}
 %    \end{macrocode}
 % \begin{macro}{\localappheight}
-% \changes{v1.5}{2023/06/24}{changes the height of the apparatus
+% \changes{v1.5}{2023/06/29}{changes the height of the apparatus
 % criticus}
 % \cs{localappheight}\marg{dimen} can be used to change locally the
 % length of \cs{ekd@app@height} set by the |appheight| option of
@@ -9253,7 +9286,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\addtoappheight}
-% \changes{v1.5}{2023/06/24}{increases or decreases the height of the
+% \changes{v1.5}{2023/06/29}{increases or decreases the height of the
 % apparatus criticus}
 % As the name suggests, in contrast to \cs{localappheight},
 % \cs{addtoappheight}\marg{dimen} is used to increase or decrease
@@ -9540,7 +9573,7 @@ Sample text with a \textcolor{red}{word} in red.
 % The following commands are provided to set and control the maximum
 % number of lines printed on each page.
 % \begin{macro}{\setmaxlines}
-% \changes{v1.5}{2023/06/24}{limits the number of lines per page}
+% \changes{v1.5}{2023/06/29}{limits the number of lines per page}
 % \cs{setmaxlines}\marg{n}, where \meta{n} is a positive integer
 % $\geq 1$, can be used either in the preamble or at any point of the
 % document to set the maximum number of lines to be printed on each
@@ -9551,7 +9584,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\localmaxlines}
-% \changes{v1.5}{2023/06/24}{changes the maximum number of lines
+% \changes{v1.5}{2023/06/29}{changes the maximum number of lines
 % locally}
 % Once a maximum number of lines per page has been set,
 % \cs{localmaxlines}\marg{n} can be used to adjust this number on a
@@ -9564,7 +9597,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\addtomaxlines}
-% \changes{v1.5}{2023/06/24}{adds or subtracts lines from a given page}
+% \changes{v1.5}{2023/06/29}{adds or subtracts lines from a given page}
 % Unlike \cs{localmaxlines}, \cs{addtomaxlines}\meta{n} takes as
 % argument the number of lines one wishes to add or substract from the
 % number that has been set by \cs{setmaxlines}. As a result, \meta{n}
@@ -9577,7 +9610,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\nomaxlines}
-% \changes{v1.5}{2023/06/24}{unsets \cs{setmaxlines}}
+% \changes{v1.5}{2023/06/29}{unsets \cs{setmaxlines}}
 % \cs{nomaxlines} unsets any limit previously set by \cs{setmaxlines}.
 %    \begin{macrocode}
 \def\nomaxlines{\luadirect{tex.sprint(ekdosis.resetlocalmaxlines())}}
@@ -9641,7 +9674,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\App}
-% \changes{v1.5}{2023/06/24}{To be used conjointly with
+% \changes{v1.5}{2023/06/29}{To be used conjointly with
 % \texttt{ekdosis.el}}
 % In contrast to \cs{app}, \cs{App} takes two mandatory arguments and
 % accepts one optional argument like so:
@@ -10425,12 +10458,20 @@ Sample text with a \textcolor{red}{word} in red.
 %    \begin{macrocode}
 \ekvdefinekeys{ekd@footnotes}{
   choice layout = {
-    default = \relax,
-    paragraph = \ekd@parafootnotestrue
+    default = \ekd@parafootnotesfalse
+              \unless\ifekd@alignmentstarted
+              \footnotelayout{c}\fi,
+    paragraph = \ekd@parafootnotestrue,
+    column = \unless\ifekd@alignmentstarted
+             \footnotelayout{c}\fi,
+    page = \unless\ifekd@alignmentstarted
+             \footnotelayout{p}\fi,
+    merge = \unless\ifekd@alignmentstarted
+             \footnotelayout{p}\fi
   },
-  initial layout = default,
   unknown-choice layout = \PackageError{ekdosis}{unknown
-    layout=#1}{`layout' must be either `default' or `paragraph'.},
+    layout=#1}{`layout' must be either `default', `paragraph',
+    `column', `page' or `merge'.},
   store type = \ekdfn@type,
   initial type = default,
   code textfnmark = \protected\def\ekd@around@fnmark##1{#1},
@@ -10455,7 +10496,7 @@ Sample text with a \textcolor{red}{word} in red.
 }
 %    \end{macrocode}
 % \begin{macro}{\SetFootnotes}
-%   \changes{v1.5}{2023/06/24}{footnotes combined into a single
+%   \changes{v1.5}{2023/06/29}{footnotes combined into a single
 %   paragraph} \cs{SetFootnotes}\marg{options} can be used in the
 %   preamble or at any point of the document. |layout=paragraph|
 %   instructs \pkg{ekdosis} to combine all footnotes into a single
@@ -10686,7 +10727,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \paragraph{Lacunae}
 % \begin{macro}{\ilabel}
-% \changes{v1.5}{2023/06/24}{recalls and sets the ending label of
+% \changes{v1.5}{2023/06/29}{recalls and sets the ending label of
 % lemmas used to mark lacunae in witnesses} When \cs{lem} has been
 % used with the optional argument |ilabel=<label>|,
 % \cs{ilabel}\marg{label} must be used to mark the point where the
@@ -10862,8 +10903,10 @@ Sample text with a \textcolor{red}{word} in red.
 % described above. One may contrast these options with those accepted
 % by \cs{SetAlignment} as \enquote{local settings}.
 %    \begin{macrocode}
+\newif\ifekd@alignmentstarted
 \NewDocumentEnvironment{alignment}{O{}}
 {%
+  \ekd@alignmentstartedtrue
   \ekvset{ekd@align}{#1}%
   \luadirect{ekdosis.mkenvdata(
     \luastring{\texts@value},
@@ -10878,11 +10921,11 @@ Sample text with a \textcolor{red}{word} in red.
   \setrunninglinenumbers
   \luadirect{tex.sprint(ekdosis.mkenv())}
   \ifekd@paired
-  \begin{paracol}[\lcols@num]{\tcols@num}
-  \else
-  \begin{paracol}[\lcols@num]*{\tcols@num}
-  \fi
-  }
+    \begin{paracol}[\lcols@num]{\tcols@num}
+    \else
+      \begin{paracol}[\lcols@num]*{\tcols@num}
+    \fi
+    }
   {\if@pkg@breakable\flushpage\fi
   \end{paracol}
   \iftei@export\luadirect{ekdosis.export_coldata_totei()}\fi
@@ -11019,7 +11062,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\ekdEOprint}
-% \changes{v1.5}{2023/06/24}{Sets headers and footers on
+% \changes{v1.5}{2023/06/29}{Sets headers and footers on
 % \enquote{paired} facing pages}
 % To set headers and footers on \enquote{paired} facing pages,
 % \cs{ekdEOprint} accepts two mandatory, self-evident arguments, like
@@ -11059,7 +11102,7 @@ Sample text with a \textcolor{red}{word} in red.
 % counter to set the value of the page numbers. This counter should be
 % incremented every two pages.
 % \begin{counter}{pairedpage}
-% \changes{v1.5}{2023/06/24}{A counter incremented every two pages}
+% \changes{v1.5}{2023/06/29}{A counter incremented every two pages}
 % |pairedpage| is first set as a global counter:---
 %    \begin{macrocode}
 \newcounter{pairedpage}
@@ -11067,19 +11110,19 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{counter}
 % \begin{macro}{\setpairedpagenum}
-%   \changes{v1.5}{2023/06/24}{sets the same page number on paired
+%   \changes{v1.5}{2023/06/29}{sets the same page number on paired
 %   pages} \cs{setpairedpagenum}\marg{number} is used just ahead of
 %   the alignment environment to set the number of the first left-hand
 %   paired page.
 % \begin{macro}{\setpairedpage}
-%   \changes{v1.5}{2023/06/24}{sets the page number of the first paired
+%   \changes{v1.5}{2023/06/29}{sets the page number of the first paired
 %   page} \cs{setpairedpage} is an argument-less command meant to be
 %   issued in commands used to set headers or footers before
 %   \cs{thepage}. This command has the counter |pairedpage|
 %   incremented on right-hand pages only, and sets |page| $\leftarrow$
 %   |pairedpage| on every page.
 % \begin{macro}{\resetpagenumber}
-%   \changes{v1.5}{2023/06/24}{resets normal running page numbers}
+%   \changes{v1.5}{2023/06/29}{resets normal running page numbers}
 %   \cs{resetpagenumber} must be used right out of \enquote{mirrored}
 %   paired pages alignment environments. This argument-less command
 %   corrects any numbering error on the page following the edition
diff --git a/ekdosis.el b/ekdosis.el
index ccc1853..7eb6dfa 100644
--- a/ekdosis.el
+++ b/ekdosis.el
@@ -243,7 +243,7 @@
   "Local options for alignment env.")
 
 (defvar LaTeX-ekdosis-footnotes-key-val-options
-  '(("layout" ("default" "paragraph"))
+  '(("layout" ("default" "column" "page" "merge" "paragraph"))
     ("type")
     ("textfnmark")
     ("appfnmark"))