From d9a33e8e6a5ea95d4c9ddc7633542e179355cadc Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Thu, 29 Jun 2023 17:11:02 +0200 Subject: reshaped documentation on footnotes --- ekdosis.dtx | 193 +++++++++++++++++++++++++++++++++++++----------------------- ekdosis.el | 2 +- 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 %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\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] % %<*driver> \begin{filecontents}[noheader,overwrite]{bibdata.xml} @@ -714,6 +714,7 @@ Alessi \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=