From db278dc6dc66de26dcc07a78af0bfc5c673e4af9 Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Wed, 5 Jul 2023 18:46:13 +0200 Subject: hopefully clearer commands and options for footnotes --- ekdosis.dtx | 130 +++++++++++++++++++++++++++++------------------------------- ekdosis.el | 4 +- 2 files changed, 65 insertions(+), 69 deletions(-) diff --git a/ekdosis.dtx b/ekdosis.dtx index 5118a4c..a086a3e 100644 --- a/ekdosis.dtx +++ b/ekdosis.dtx @@ -59,7 +59,7 @@ Alessi %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\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] % %<*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=