hopefully clearer commands and options for footnotes

1 files changed, 62 insertions, 68 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 5118a4c..a086a3e 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/29 v1.5-dev Typesetting TEI xml-compliant critical editions]
+    [2023/07/05 v1.5-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -4443,30 +4443,27 @@ argument of 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+
+% \DescribeOption{arrangement}
+% \phts\label{ref:setfootnotes-arrangement}
+% |arrangement|$=$\verb+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
+% \item |arrangement=column| can be used to have regular footnotes
+%   printed at the bottom of the column in which they are
+%   called.
+% \item |arrangement=page| Footnotes from all columns are gathered in
+%   a single spanning block at the bottom of all columns on the page.
+% \item |arrangement=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.
 % \end{enumerate}
+% \DescribeOption{reset} (no-value argument)\\
+% If used, this option reverts the footnotes to the default
+% arrangement which is to have them printed as regular footnotes at
+% the bottom of each column of text. |reset| also reverts footnotes
+% combined into a single paragraph\===as described below\===to regular
+% footnotes.
 %
 % \subsection{Footnotes Combined Into a Single Paragraph}
 % \label{sec:footn-comb-into}
@@ -4479,26 +4476,24 @@ argument of the
 % apparatus criticus.
 %
 % \danger Unlike the three possible values that can be passed to
-% |layout| just described, which apply only to regular footnotes
+% |arrangement| 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}) Unlike
-% the options for regular footnotes, those for footnotes combined into
-% a single paragraph can be set at any point of the
-% document.
+% apply to both the \env{alignment} and \env{ekdosis} environments and
+% can be set at any point of the document.
 % \danger It is however not recommended to use \cs{SetFoonotes} in
 % environments to be transcribed into \texttt{TEI xml}. The way to
 % restrict the effect of this command to one of the defined
 % environments is to use \cs{AtBeginEnvironment} as described in
-% \vref{sec:alignment-hooks}.\\
-% \DescribeOption{layout}|layout=paragraph|
-% \hfill\tcboxverb{Default: not set}\\
-% |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.\\
+% \vref{sec:alignment-hooks}.
+%
+% \noindent
+% \DescribeMacro{\SetFootnotes} (\emph{Continued from above.})\\
+% \DescribeOption{paragraph}\verb+paragraph=true|false+
+% \hfill\tcboxverb{Default: true, initially false}\\
+% This named argument does not need a value as it defaults to |true|
+% if used. |paragraph| instructs \pkg{ekdosis} to reformat the notes
+% into a single paragraph, itself inserted as a layer in the apparatus
+% block. (See \textoiquote|type|\textciquote\ below.)\\
 % \DescribeOption{type}|type|$=$\meta{type}
 % \hfill\tcboxverb{Initially set as 'default'}\\
 % The keyword |type| is used here in the exact same meaning as
@@ -4527,7 +4522,7 @@ argument of the
 % 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}
+% \DescribeOption{type}|type|$=$\meta{type}
 % \hfill\tcboxverb{Default: as defined in \SetFoonotes}\\
 % |type| allows to specify any layer of critical notes in which the
 % contents of the footnote is to be printed.\\
@@ -4559,7 +4554,7 @@ argument of the
 % Preamble:
 \DeclareApparatus{notes}[bhook=\textbf{Notes:}]
 \SetFootnotes{
-  layout = paragraph,
+  paragraph,
   type = notes,
   textfnmark = \textsuperscript{#1},
   appfnmark = \unskip\hskip 1em\textsuperscript{#1}
@@ -4593,7 +4588,7 @@ argument of the
 % PDF output:---
 % \medskip
 % \SetFootnotes{
-% layout = paragraph,
+% paragraph,
 % type = notes,
 % textfnmark = \textsuperscript{#1},
 % appfnmark = \unskip\hskip 1em\textsuperscript{#1}
@@ -4621,7 +4616,7 @@ argument of the
 %     them.}
 %   \end{specimen}
 % \end{alignment}
-% \SetFootnotes{layout = default}
+% \SetFootnotes{reset}
 % 
 % \texttt{TEI xml} output:---
 %
@@ -8522,7 +8517,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \paragraph{\textsf{ekdosis} Symbol}
 % \begin{macro}{\eKd}
-% \changes{v1.5}{2023/06/29}{Prints \textsf{ekdosis} indentifying
+% \changes{v1.5}{2023/07/05}{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.
@@ -8785,7 +8780,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/29}{direct insertion of empty elements in the
+% \changes{v1.5}{2023/07/05}{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
@@ -8800,7 +8795,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\getTEIxmlid}
-% \changes{v1.5}{2023/06/29}{returns \texttt{TEI xml:ids} from a
+% \changes{v1.5}{2023/07/05}{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
@@ -9276,7 +9271,7 @@ Sample text with a \textcolor{red}{word} in red.
 \newlength{\ekd@app@localheight}
 %    \end{macrocode}
 % \begin{macro}{\localappheight}
-% \changes{v1.5}{2023/06/29}{changes the height of the apparatus
+% \changes{v1.5}{2023/07/05}{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
@@ -9295,7 +9290,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\addtoappheight}
-% \changes{v1.5}{2023/06/29}{increases or decreases the height of the
+% \changes{v1.5}{2023/07/05}{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
@@ -9582,7 +9577,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/29}{limits the number of lines per page}
+% \changes{v1.5}{2023/07/05}{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
@@ -9593,7 +9588,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\localmaxlines}
-% \changes{v1.5}{2023/06/29}{changes the maximum number of lines
+% \changes{v1.5}{2023/07/05}{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
@@ -9606,7 +9601,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\addtomaxlines}
-% \changes{v1.5}{2023/06/29}{adds or subtracts lines from a given page}
+% \changes{v1.5}{2023/07/05}{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}
@@ -9619,7 +9614,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\nomaxlines}
-% \changes{v1.5}{2023/06/29}{unsets \cs{setmaxlines}}
+% \changes{v1.5}{2023/07/05}{unsets \cs{setmaxlines}}
 % \cs{nomaxlines} unsets any limit previously set by \cs{setmaxlines}.
 %    \begin{macrocode}
 \def\nomaxlines{\luadirect{tex.sprint(ekdosis.resetlocalmaxlines())}}
@@ -9683,7 +9678,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\App}
-% \changes{v1.5}{2023/06/29}{To be used conjointly with
+% \changes{v1.5}{2023/07/05}{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:
@@ -10466,21 +10461,20 @@ Sample text with a \textcolor{red}{word} in red.
 % The keys to be used by \cs{SetFootnotes} are defined below:---
 %    \begin{macrocode}
 \ekvdefinekeys{ekd@footnotes}{
-  choice layout = {
-    default = \ekd@parafootnotesfalse
-              \unless\ifekd@alignmentstarted
-              \footnotelayout{c}\fi,
-    paragraph = \ekd@parafootnotestrue,
+  choice arrangement = {
     column = \unless\ifekd@alignmentstarted
              \footnotelayout{c}\fi,
     page = \unless\ifekd@alignmentstarted
              \footnotelayout{p}\fi,
     merge = \unless\ifekd@alignmentstarted
-             \footnotelayout{m}\fi
-  },
-  unknown-choice layout = \PackageError{ekdosis}{unknown
-    layout=#1}{`layout' must be either `default', `paragraph',
-    `column', `page' or `merge'.},
+              \footnotelayout{m}\fi},
+  unknown-choice arrangement = \PackageError{ekdosis}{unknown
+    arrangement=#1}{`arrangement' must be either `column',
+    `page' or `merge'.},
+  noval reset = \ekd@parafootnotesfalse
+                \unless\ifekd@alignmentstarted
+                \footnotelayout{c}\fi,
+  bool paragraph = \ifekd@parafootnotes,
   store type = \ekdfn@type,
   initial type = default,
   code textfnmark = \protected\def\ekd@around@fnmark##1{#1},
@@ -10505,7 +10499,7 @@ Sample text with a \textcolor{red}{word} in red.
 }
 %    \end{macrocode}
 % \begin{macro}{\SetFootnotes}
-%   \changes{v1.5}{2023/06/29}{footnotes combined into a single
+%   \changes{v1.5}{2023/07/05}{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
@@ -10736,7 +10730,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \paragraph{Lacunae}
 % \begin{macro}{\ilabel}
-% \changes{v1.5}{2023/06/29}{recalls and sets the ending label of
+% \changes{v1.5}{2023/07/05}{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
@@ -11071,7 +11065,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\ekdEOprint}
-% \changes{v1.5}{2023/06/29}{Sets headers and footers on
+% \changes{v1.5}{2023/07/05}{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
@@ -11111,7 +11105,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/29}{A counter incremented every two pages}
+% \changes{v1.5}{2023/07/05}{A counter incremented every two pages}
 % |pairedpage| is first set as a global counter:---
 %    \begin{macrocode}
 \newcounter{pairedpage}
@@ -11119,19 +11113,19 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{counter}
 % \begin{macro}{\setpairedpagenum}
-%   \changes{v1.5}{2023/06/29}{sets the same page number on paired
+%   \changes{v1.5}{2023/07/05}{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/29}{sets the page number of the first paired
+%   \changes{v1.5}{2023/07/05}{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/29}{resets normal running page numbers}
+%   \changes{v1.5}{2023/07/05}{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