From caec0014c841cdf0c867a4eb731876b55080708b Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Wed, 26 Oct 2022 12:07:27 +0200 Subject: documentation and .el style file updated --- ekdosis.dtx | 245 +++++++++++++++++++++++++++++++++++++++++++++++------------- ekdosis.el | 20 +++++ 2 files changed, 212 insertions(+), 53 deletions(-) diff --git a/ekdosis.dtx b/ekdosis.dtx index f6571f6..bfce8bc 100644 --- a/ekdosis.dtx +++ b/ekdosis.dtx @@ -61,7 +61,7 @@ along with this program. If not, see %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\ProvidesPackage{ekdosis} %<*package> - [2022/10/25 v1.5-dev Typesetting TEI xml-compliant critical editions] + [2022/10/26 v1.5-dev Typesetting TEI xml-compliant critical editions] % %<*driver> \begin{filecontents}[noheader,overwrite]{bibdata.xml} @@ -356,6 +356,15 @@ along with this program. If not, see version = {1.3} } +@Software{fgruler, + title = {The Fgruler package}, + titleaddon = {Draw rulers on the foreground or in the text}, + author = {Tómács, Tibor}, + url = {https://ctan.org/pkg/fgruler}, + date = {2022-06-25}, + version = {1.5}, +} + @Software{fnpos, title = {The Fnpos package}, titleaddon = {Control the position of footnotes on the page}, @@ -3447,7 +3456,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+ % 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:--- +% set as follows:\footnote{The \cs{setmaxlines} command provides a +% further example of applying this technique. See below +% \vpageref{ref:setmaxlines-hook}.}--- % % \iffalse %<*example> @@ -3716,7 +3727,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+ % up to which the apparatus block is allowed to grow before the size % of the characters is reduced to allow for more entries. The value % must be a dimension, namely a number followed by a length unit, such -% as |0.65\textheight|, |18cm| or |6in|.\\ +% as |0.65\textheight|, |18cm| or |6in|. \mansee To learn how this +% value can be adjusted on given pages, see below +% \vpageref{ref:fitapp-trick}.\\ % \DescribeOption{fitalgorithm}% % \phts\label{ref:fitalgorithm} % \unskip|fitalgorithm|$=$\verb+fontsize|hybrid|areasize|squeeze+ @@ -5114,9 +5127,53 @@ substantiall fewell,} % % \medskip\noindent\textbf{Limiting the Number of Lines per Page} % \phts\label{ref:gmaxlines}\\ -% \DescribeOption{maxlines} \newfeature[v1.5] |maxlines|=\meta{n} +% \DescribeOption{maxlines} |maxlines|$=$\emph{n} (where \emph{n} is +% an integer $\geq 1$)\newfeature[v1.5] % \hfill\tcboxverb{Default: not set}\\ +% |maxlines|$=$\emph{n} instructs \pkg{ekdosis} to break the pages of +% numbered text every \emph{n} lines. This option is very useful for +% building editions equipped with long and complex apparatus +% criticus. The rationale is to start with a number of lines that will +% allow all pages to pass just after a few runs of \LuaLaTeX, even at +% the cost of showing blanks between the edition text and the +% apparatus criticus. Adjusting further the number of lines will then +% leave fewer blanks on display. Combined with the |fitapp| global +% option\footnote{See above \vpageref{ref:fitapp-opt}.} or with +% |maxentries|,\footnote{Se above \vpageref{ref:maxentries}.} +% |maxlines| can achieve excellent results. For more details on this +% technique, see below \ref{sec:oscillating-problem}, +% \enquote{\nameref{sec:oscillating-problem}} +% \vpageref{ref:maxlines-trick}.\\ +% \DescribeOption{nomaxlines} \newfeature[v1.5] +% \hfill\tcboxverb{Default: not set}\\ +% This no-value option unsets any limit previously set by |maxlines| +% or \cs{setmaxlines}\\ +% \DescribeMacro{\setmaxlines} \cs{setmaxlines}\marg{n} (where +% \meta{n} $\geq 1$) has the same effect as the |maxlines| option just +% described. This command can be used either in the preamble or at any +% point of the document. \mansee \phts\label{ref:setmaxlines-hook} The +% |maxlines| option operates globally, on any pages or columns of text +% that are set to receive at least one layer of apparatus +% criticus. The way of applying the limit to only one out of several +% edition texts is therefore to append \cs{setmaxlines} as a hook to +% the environment corresponding to this edition text as described +% above \vpageref{sec:alignment-hooks}, like so:--- % +% \iffalse +%<*example> +% \fi +\begin{minted}[linenos=false]{latex} +\AtBeginEnvironment{latin}{\setmaxlines{}} +\end{minted} +% \iffalse +% +% \fi +% +% \DescribeMacro{\nomaxlines} \noindent\cs{nomaxlines} is an +% argument-less command that operates as the |nomaxlines| option just +% described. This command can be used either in the preamble or at any +% point of the document. +% % \medskip\noindent\textbf{Options Specific to the |poetry=verse| % Global Setting}\footnote{See above % \vref{sec:verse-package}.}\phts\label{ref:verse-lineation}\\ @@ -6168,37 +6225,92 @@ subtype="arabtex">'inna 'abI kAna mina % 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 +% The 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 be 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 substantial change in the preceding % pages may result in pages that break just after they begin. % +% \paragraph{Limiting the Number of Lines per Page} +% \phts\label{ref:maxlines-trick} One way to avoid this inconvenience +% is to use the |maxlines| option of \cs{SetLineation} as described +% above \vpageref{ref:gmaxlines}. Depending on the abundance of +% critical footnotes to be printed, the editor may start with a number +% that will allow most, if not all, pages to pass. +% +% Furthermore, this technique can be combined with the |fitapp| global +% option described below \vpageref{ref:fitapp-trick}. Once |maxlines| +% has been applied, the \pkg{fgruler} package\footcite{fgruler} can be +% used to gauge the respective heights of the edition text and the +% apparatus criticus like so:--- +% +% \iffalse +%<*example> +% \fi +\begin{minted}[linenos=false]{latex} +% Preamble +\usepackage[type=lowerleftT]{fgruler} +\end{minted} +% \iffalse +% +% \fi +% +% Based on the height corresponding to the last line of the edition +% text limited by the value of |maxlines|, the height from which the +% apparatus criticus block should stop growing and the characters +% should be scaled down to allow for more entries can be +% estimated.\footnote{To learn how the maximum height of the apparatus +% criticus can be set, see \vpageref{ref:appheight}. The |fitapp| +% global option is described \vpageref{ref:fitapp-opt}.} This ensures +% that any contentious entries are included in the apparatus criticus +% when the last line of text has been reached. +% +% In addition to the |maxlines| option of \cs{SetLineation} and the +% \cs{setmaxlines} command,\footnote{See above +% \vpageref{ref:gmaxlines}.} the following commands are provided:--- +% +% \DescribeMacro{\localmaxlines} \cs{localmaxlines}\marg{n}, where +% \meta{n} $\geq 1$, can be used in the edition text to adjust the +% number of lines on a given page. Of course, this command must be +% issued before the line number corresponding to |maxlines| is +% reached. \mansee \cs{localmaxlines}|{0}| can therefore be used to +% remove the limit set by |maxlines| or \cs{setmaxlines} on a given +% page. +% +% \DescribeMacro{\addtomaxlines} Unlike \cs{localmaxlines}, +% \cs{addtomaxlines}\marg{n} takes as argument the number of lines one +% wishes to add or substract from the number that has been set by +% |maxlines| or \cs{setmaxlines}. As a result, \meta{n} can be a +% positive or negative integer. +% +% \DescribeMacro{\nomaxlines} \cs{nomaxlines} is an argument-less +% command that unsets any limit previously set by |maxlines| or +% \cs{setmaxlines}. +% % \paragraph{Conditional page breaks} % \phts\label{ref:ekdpb} \DescribeMacro{\ekdpb}\DescribeMacro{\ekdpb*} -% \cs{ekdpb}\oarg{page no}\marg{line no} -% \cs{ekdpb*}|{}| \cs{ekdpb*} +% \cs{ekdpb}\oarg{page no}\marg{line no} \cs{ekdpb*}|{}| \cs{ekdpb*} % \newfeature[v1.2]\\ -% One way to avoid this inconvenience is to use \cs{ekdpb} instead of -% the standard \cs{pagebreak} command provided by \LaTeX\ to insert -% conditional page breaks. \cs{ekdpb} takes as mandatory argument the -% line number, as it is printed in the margin, where the page break -% should take place. An optional argument allows to further specify -% the page number where the page break should occur. The value that is -% expected is the page number as it is printed\===e.g.\ an Arabic, -% Roman or alphanumeric number. If the specified conditions be not -% met, then the page break is not triggered. Finally, the -% \enquote{starred} version of this command forces the page break, -% irrespective of the values specified as page or line numbers. Unlike -% \cs{ekdpb}, which requires the lines to be numbered, \cs{ekdpb*} is -% allowed at any point of the document: as \cs{ekdpb*} disregards the -% number given as argument, it is equivalent to the standard \LaTeX\ -% \cs{pagebreak} command. Yet it can be used instead of the latter to -% have marks further printed in the margins so as to spot with a -% fleeting glance the locations where induced page breaks -% occur.\footnote{This requires the |showpagebreaks| option to be set -% to |true| as described above \vpageref{ref:showpagebreaks-opt}.} +% One other way is to use \cs{ekdpb} instead of the standard +% \cs{pagebreak} command provided by \LaTeX\ to insert conditional +% page breaks. \cs{ekdpb} takes as mandatory argument the line number, +% as it is printed in the margin, where the page break should take +% place. An optional argument allows to further specify the page +% number where the page break should occur. The value that is expected +% is the page number as it is printed\===e.g.\ an Arabic, Roman or +% alphanumeric number. If the specified conditions be not met, then +% the page break is not triggered. Finally, the \enquote{starred} +% version of this command forces the page break, irrespective of the +% values specified as page or line numbers. Unlike \cs{ekdpb}, which +% requires the lines to be numbered, \cs{ekdpb*} is allowed at any +% point of the document: as \cs{ekdpb*} disregards the number given as +% argument, it is equivalent to the standard \LaTeX\ \cs{pagebreak} +% command. Yet it can be used instead of the latter to have marks +% further printed in the margins so as to spot with a fleeting glance +% the locations where induced page breaks occur.\footnote{This +% requires the |showpagebreaks| option to be set to |true| as +% described above \vpageref{ref:showpagebreaks-opt}.} % % \paragraph{Using \texttt{maxentries}} % Another way\---should the edition text fall into the vicious circle @@ -6249,15 +6361,42 @@ subtype="arabtex">'inna 'abI kAna mina % sets of page decisions. % % \paragraph{The \texttt{fitapp} Global Option} -% \newfeature[v1.3] The rationale of this option is discussed above -% (see \vref{ref:fitapp-opt}). As this mechanism has the characters of -% the apparatus block scaled down to allow for more entries once a -% predefined height has been reached, \pkg{ekdosis} should settle down -% in most of the contentious cases.\footnote{That is, cases that arise -% \emph{after} the predefined height has been reached.} However, it is -% advisable to use |fitapp| conjointly with |maxentries| to prevent -% the number of allowed entries from being too high, which would -% result in the characters being too small or even illegible. +% \phts\label{ref:fitapp-trick} \newfeature[v1.3] The rationale of +% this option is discussed above (see \vref{ref:fitapp-opt}). As this +% mechanism has the characters of the apparatus block scaled down to +% allow for more entries once a predefined height has been reached, +% \pkg{ekdosis} should settle down in most of the contentious +% cases.\footnote{That is, cases that arise \emph{after} the +% predefined height has been reached.} However, it is advisable to use +% |fitapp| conjointly with |maxlines| or |maxentries| to prevent the +% number of allowed entries from being too high, which would result in +% the characters being too small or even illegible. +% +% \newfeature[v1.5] As already seen \vpageref{ref:appheight}, once the +% global option |layout=fitapp| has been set,\footnote{See above +% \vpageref{ref:fitapp-opt}.} the default maximum height of the +% apparatus criticus block is |0.5\textheight|, which can be changed +% by assigning a new length to the |appheight| option of +% \cs{SetHooks}. To more finely adjust this height on given pages, +% \pkg{ekdosis} provides additional commands to be used in the edition +% text:--- +% +% \DescribeMacro{\localappheight} +% \cs{localappheight}\marg{dimen} can be used to change locally the +% height up to which the apparatus block is allowed to +% grow. \meta{dimen} must be a number followed by a unit +% length. \danger This command operates only on the apparatus block +% that follows it. Therefore, it must be issued \emph{before} the +% first entry of the apparatus block on which it is intended to +% operate, either on the current page or in the last lines of the +% preceding page. +% +% \DescribeMacro{\addtoappheight} +% As the name suggests, in contrast to \cs{localappheight}, +% \cs{addtoappheight}\marg{dimen} is used to increase or decrease +% locally the height of the apparatus typeblock. \meta{dimen} must be +% a number followed by a unit length. Just as \cs{localappheight}, +% this command operates only on the apparatus block that follows it. % % \subsection{Using \textsf{emacs}} % \label{sec:using-emacs} @@ -8409,7 +8548,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \paragraph{\textsf{ekdosis} Symbol} % \begin{macro}{\eKd} -% \changes{v1.5}{2022/10/25}{Prints \textsf{ekdosis} indentifying +% \changes{v1.5}{2022/10/26}{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. @@ -8672,7 +8811,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}{2022/10/25}{direct insertion of empty elements in the +% \changes{v1.5}{2022/10/26}{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 @@ -8687,7 +8826,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macro} % \end{macro} % \begin{macro}{\getTEIxmlid} -% \changes{v1.5}{2022/10/25}{returns \texttt{TEI xml:ids} from a +% \changes{v1.5}{2022/10/26}{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 @@ -9163,10 +9302,10 @@ Sample text with a \textcolor{red}{word} in red. \newlength{\ekd@app@localheight} % \end{macrocode} % \begin{macro}{\localappheight} -% \changes{v1.5}{2022/10/25}{changes the height of the apparatus +% \changes{v1.5}{2022/10/26}{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 +% length of \cs{ekd@app@height} set by the |appheight| option of % \cs{SetHooks}, namely the height up to which the apparatus block is % allowed to grow. \meta{dimen} must be a number followed by a unit % length. This command operates only on the apparatus block that @@ -9182,11 +9321,11 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\addtoappheight} -% \changes{v1.5}{2022/10/25}{increases or decreases the height of the +% \changes{v1.5}{2022/10/26}{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 -% locally the length of \cs{\ekd@app@height}. \meta{dimen} must be a +% locally the length of \cs{ekd@app@height}. \meta{dimen} must be a % number followed by a unit length. This command operates only on the % apparatus block that follows it. % \begin{macrocode} @@ -9468,7 +9607,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}{2022/10/25}{limits the number of lines per page} +% \changes{v1.5}{2022/10/26}{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 @@ -9479,7 +9618,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\localmaxlines} -% \changes{v1.5}{2022/10/25}{changes the maximum number of lines +% \changes{v1.5}{2022/10/26}{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 @@ -9492,7 +9631,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\addtomaxlines} -% \changes{v1.5}{2022/10/25}{adds or subtracts lines from a given page} +% \changes{v1.5}{2022/10/26}{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} @@ -9505,7 +9644,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\nomaxlines} -% \changes{v1.5}{2022/10/25}{unsets \cs{setmaxlines}} +% \changes{v1.5}{2022/10/26}{unsets \cs{setmaxlines}} % \cs{nomaxlines} unsets any limit previously set by \cs{setmaxlines}. % \begin{macrocode} \def\nomaxlines{\luadirect{tex.sprint(ekdosis.resetlocalmaxlines())}} @@ -9569,7 +9708,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\App} -% \changes{v1.5}{2022/10/25}{To be used conjointly with +% \changes{v1.5}{2022/10/26}{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: @@ -10453,7 +10592,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macro} % \paragraph{Lacunae} % \begin{macro}{\ilabel} -% \changes{v1.5}{2022/10/25}{recalls and sets the ending label of +% \changes{v1.5}{2022/10/26}{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=