From 1c0cf6b55a3d5865de031eec347a770bbda52bbe Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Wed, 22 Jul 2020 10:41:15 +0200 Subject: \DeclareApparatus: delim was missing an initial value. still documenting. --- ekdosis.dtx | 295 +++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 262 insertions(+), 33 deletions(-) (limited to 'ekdosis.dtx') diff --git a/ekdosis.dtx b/ekdosis.dtx index 76e3fc4..8b79b24 100644 --- a/ekdosis.dtx +++ b/ekdosis.dtx @@ -625,11 +625,11 @@ along with this program. If not, see % not as compact paragraphs that require special and painful training % to be \enquote*{decoded}. On the other hand, what editions in print % do not provide are what \citename{Mastronarde.Tarrant2017}{author} -% have called \enquote{actionable texts for use in digital -% research},\footcite{Mastronarde.Tarrant2017} namely database-driven -% texts allowing the reader to select annotations and display or -% arrange translations, parallel passages or borrowings in a variety -% of ways. +% have called \enquote{actionable texts for use in digital research},% +% {\interfootnotelinepenalty=10000\footcite{Mastronarde.Tarrant2017}} +% namely database-driven texts allowing the reader to select +% annotations and display or arrange translations, parallel passages +% or borrowings in a variety of ways. % % \pkg{ekdosis} can be seen as an attempt at combining the two % approaches. @@ -650,17 +650,18 @@ along with this program. If not, see % synchronized or not. \pkg{ekdosis} is also suitable for complex % layouts as in the case of Arabic poetry or images where three-way % alignment is required, or diagrams, \emph{\&c}. -% \item \emph{Apparatus criticus\/}: Edited texts can receive multiple -% layers of apparatus, e.g.\ apparatus criticus (to record variant -% readings), apparatus fontium (to collect references to texts quoted -% or cited in the edited text), apparatus testium (to collect -% testimonia or parallel passages), or any kind of short notes to be -% printed on the same page as the edited text, \emph{\&c}. -% \item \texttt{TEI xml} output: \pkg{ekdosis} can be instructed -% to output both PDF and \texttt{TEI xml} files at the same time. +% \item \label{it:multilayer-feature}\emph{Apparatus criticus\/}: +% Edited texts can receive multiple layers of apparatus, e.g.\ +% apparatus criticus (to record variant readings), apparatus fontium +% (to collect references to texts quoted or cited in the edited +% text), apparatus testium (to collect testimonia or parallel +% passages), or any kind of short notes to be printed on the same +% page as the edited text, \emph{\&c}. +% \item \texttt{TEI xml} output: \pkg{ekdosis} can be instructed to +% output both PDF and \texttt{TEI xml} files at the same time. % \item \emph{Database-driven encoding} under \LaTeX{} of texts -% entered segment by segment allows for alignment of parallel texts -% from multilingual corpora. +% entered segment by segment allows for alignment of parallel texts +% from multilingual corpora. % \end{enumerate} % % Before going into detail, the following simple example will give the @@ -1086,7 +1087,7 @@ along with this program. If not, see % % \paragraph{Apparatus Entries} % \DescribeMacro{\app} \cs{app}|[type=|\meta{type}|]|\marg{apparatus -% entries}\\ +% entries}\label{ref:app-cmd}\\ % This command takes one mandatory argument and accepts one optional % argument. Once references to be used as witnesses in the apparatus % criticus have been declared in the preamble as described in @@ -1111,9 +1112,10 @@ yesterday. % % \fi % \cs{app} accepts one further optional argument:---\\ -% \DescribeOption{type} |type|$=$\meta{type}\hfill% -% \tcboxverb{Default: default}\\ -% By default, \pkg{ekdosis} sets one layer of notes\--- the |default| +% \DescribeOption{type} |type|$=$\meta{type}\label{ref:app-type} +% \hfill\tcboxverb{Default: default}\\ +% As will be described below in \vref{sec:multilayer-apparatus}, +% \pkg{ekdosis} initially sets one layer of notes\--- the |default| % layer\---in the apparatus criticus. This layer is fit to receive % notes related to variant readings from witnesses and sources used by % the editor to establish the edition text. Additional layers can be @@ -1125,7 +1127,8 @@ yesterday. % additional layers have been defined and assigned to new % \enquote*{types}, such as \enquote*{testium} and the like, these % types can be used as values appended to the |type| \enquote*{named -% option}. +% option}. For more information about inserting notes in +% multiple-layer apparatus, see \vref{sec:notes-in-multilayer-app}. % % \paragraph{Base text and variants} As can be seen in the example % above, there are two kinds of individual readings: the \emph{lemma}, @@ -1756,9 +1759,45 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+ % % \section{Laying Out the Apparatus Criticus } % \label{sec:apparatus-layout} +% +% \subsection{General Hooks} +% \label{sec:general-hooks} +% Some hooks are shared by all layers of notes that are inserted in +% the apparatus criticus (e.g. sources, testimonia, variant readings +% \emph{\&c.}) +% +% \DescribeMacro{\SetEkdosisHooks} +% \cs{SetEkdosisHooks}\marg{csv list of hooks} can be used either in +% the preamble or at any point of the document. The list of accepted +% hooks at the time of writing follows:---\\ +% \DescribeOption{appfontsize} |appfontsize|$=$\meta{csname} +% \hfill\tcboxverb{Default: \footnotesize}\\ +% This option sets the size of the font to be used in the whole +% apparatus criticus. By default, it is the same as the size used for +% footnotes.\\ +% \DescribeOption{refnumstyle} |refnumstyle|$=$\meta{csname} +% \hfill\tcboxverb{Default: \bfseries}\\ +% |refnumstyle| can be used to set the family, series or shape of the +% font used to print references to line numbers in the apparatus +% criticus. By default, numbers are printed in bold face. As an +% example, |refnumstyle=\normalfont| will have them printed in the +% font and shape selected by default for the +% document, while |refnumstyle=\bfseries\itshape| will have them +% printed in bold and italic.\\ +% \DescribeOption{postrefnum} |postrefnum|$=$\meta{csname \textbar\ +% chars}\hfill\tcboxverb{Default: ~}\\ +% |postrefnum| can be used to set what immediately follows the +% reference to line numbers. By default, it is |~|, namely an +% unbreakable space. As an example, |postrefnum=\hskip 0.5em| will +% insert a \unit[0.5]{em} space between the numerals and the beginning +% of all subsequent notes. +% +% \subsection{Single-Layer Apparatus Criticus} +% \label{sec:single-layer-app} +% \paragraph{Specific Commands} % Single-layer apparatus criticus can be laid out in a variety of % ways with the following specialized commands, all of which can be -% used in the preamble or at any point of the document. +% used in the preamble or at any point of the document:--- % % \DescribeMacro{\SetLTRapp} % \DescribeMacro{\SetRTLapp} @@ -1772,9 +1811,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+ % followed by a space (\verb*+] +). % % \DescribeMacro{\SetBeginApparatus} -% \cs{SetBeginApparatus}\marg{characters/commands} can be used to -% append \meta{characters} or \meta{commands} at the beginning of the -% apparatus block. By default, nothing is appended. For instance, +% \cs{SetBeginApparatus}\marg{characters\textbar commands} can be used +% to append \meta{characters} or \meta{commands} at the beginning of +% the apparatus block. By default, nothing is appended. For instance, % \mintinline{latex}|\SetBeginApparatus{\textbf{Apparatus:}}| will % append \enquote{\textbf{Apparatus:}} at the beginning of the % apparatus block, while % @@ -1789,17 +1828,189 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+ % at the end of the apparatus as it is customary in some editions. % % \DescribeMacro{\SetUnitDelimiter} -% \cs{SetUnitDelimiter} +% \cs{SetUnitDelimiter}\marg{delimiter} can be used to set the +% delimiter between entries in the apparatus criticus. By default, +% there is no delimiter except a simple space. \meta{delimiter} can be +% a broad space (such as |\hskip 0.75em| for instance as in the OCT +% series) or the divider-sign (‖, as in the Budé series). +% +% \DescribeMacro{\SetDefaultRule} +% By default, \pkg{ekdosis} draws a separating line between the +% edition text and the apparatus criticus. This line is initially +% defined as +% |\rule{0.4\columnwidth}{0.4pt}|. \cs{SetDefaultRule}\marg{line +% definition} can be used in the preamble or at any point of the +% document to change the default setting. Leaving this argument empty +% as in \cs{SetDefaultRule}|{}| removes the line. +% +% \paragraph{General Command} +% \DescribeMacro{\SetApparatus} \cs{SetApparatus}\marg{csv list of +% apparatus settings}\label{ref:apparatus-settings-b}\\ +% Finally, all the settings described above can also be collected in +% the argument of \cs{SetApparatus}. \cs{SetApparatus} accepts the +% following list of comma-separated |key=value| options:---\\ +% \DescribeOption{direction} |direction|$=$\verb+LR|RL+ +% \hfill\tcboxverb{Default: LR}\\ +% The writing direction of the apparatus criticus, either +% left-to-right (|LR|) or right-to-left (|LR|).\\ +% \DescribeOption{sep} |sep|$=$\meta{csname \textbar\ chars} +% \hfill\tcboxverb{Default: ]␣}\\ +% The separator between lemma texts and variant readings.\\ +% \DescribeOption{delim} |delim|$=$\meta{delimiter} +% \hfill\tcboxverb{Default: not set}\\ +% The delimiter between entries in the apparatus criticus. As said +% above, there is no default delimiter except a simple space.\\ +% \DescribeOption{bhook} |bhook|$=$\meta{characters\textbar commands} +% \hfill\tcboxverb{Default: empty}\\ +% The characters or commands to be appended at the beginning of the +% apparatus block.\\ +% \DescribeOption{ehook} |ehook|$=$\meta{characters} +% \hfill\tcboxverb{Default: empty}\\ +% The characters to be appended at the end of the apparatus block.\\ +% \DescribeOption{rule} |rule|$=$\meta{command}\verb+|+|none| +% \hfill\tcboxverb{Default: \rule{0.4\columnwidth}{0.4pt}}\\ +% As described above, |rule| is used to draw the separating line +% between the edition text and the apparatus criticus. |rule=none| can +% also be used to remove the line.\\ +% \DescribeOption{norule}\hfill\tcboxverb{Default: not set}\\ +% |norule| does not accept any value and has the same effect as +% |rule=none|.\label{ref:apparatus-settings-e} +% +% As an example, an apparatus criticus with references to line numbers +% printed in normal font, a colon as a separator between lemma texts +% and variant readings, a broad space as a delimiter between entries +% and a \unit[0.7]{in} line above could be laid out as follows:--- +% +% \label{ex:single-layer-app-layout} +% \iffalse +%<*example> +% \fi +\begin{minted}[linenos=false]{latex} +\SetEkdosisHooks{ + refnumstyle=\normalfont +} +\SetApparatus{ + sep={: }, + delim=\hskip 1em, + rule=\rule{0.7in}{0.4pt} +} +\end{minted} +% \iffalse +% +% \fi +% +% \paragraph{Footnote Separator} +% \DescribeMacro{\footnoteruletrue} \DescribeMacro{\footnoterulefalse} +% As already seen above, \pkg{ekdosis} takes care of drawing a +% separating line between the edition text and the apparatus +% criticus. Therefore, it may be not desirable to have the standard +% \LaTeX\ \enquote{footnoterule} printed on every page where regular +% footnotes are found. \cs{footnoterulefalse} removes it while +% \cs{footnoteruletrue} leaves it untouched. The latter is set by +% default. +% +% \subsection{Multiple-Layer Apparatus Criticus} +% \label{sec:multilayer-apparatus} +% As said above in \vref{it:multilayer-feature}, \pkg{ekdosis} can +% print edition texts equipped with multiple-layer apparatus +% criticus. To take an example, most classical editions provide at +% least two layers of notes: one to collect references to testimonia +% or parallel passages (apparatus testium) and the other to record +% variant readings (the apparatus criticus \emph{stricto sensu}). The +% former is always printed above the latter. +% +% \danger The default single-layer apparatus criticus that is +% described above in \vref{sec:single-layer-app} is called |default| +% internally. If any additional layer of notes be declared in the +% preamble, this |default| layer must be included in the list of +% declared layers.\\ +% \DescribeMacro{\EkdosisDefaultApparatus} +% \cs{EkdosisDefaultApparatus}\marg{name} can be used at any point of +% the document to change the default name that is used by +% \pkg{ekdosis}. +% +% \subsubsection{Declaring Additional Layers} +% \label{sec:declaring-layers} +% \DescribeMacro{\DeclareApparatus} +% \cs{DeclareApparatus}\marg{name}\oarg{csv list of apparatus +% settings} is a preamble-only command. As a mandatory argument, it +% takes the name of the new layer of notes to be inserted in the +% apparatus block. Declared layers are then printed one below the +% other in the exact same order as they are declared in the +% preamble. Therefore, one additional layer meant to print the +% testimonia above the variant readings (apparatus testium) can be +% declared as follows:--- % +% \iffalse +%<*example> +% \fi +\begin{minted}{latex} +% preamble: +\DeclareApparatus{testium} +\DeclareApparatus{default} +\end{minted} +% \iffalse +% +% \fi +% +% In this example, |testium| is a new name for |default|, as said +% just above, is already known to \pkg{ekdosis} and used as the +% default layer of notes. Furthermore, as |testium| is declared before +% |default|, \pkg{ekdosis} will print the testimonia at the top of the +% apparatus block. +% +% \subsubsection{Laying Out Layers} +% \label{sec:layout-layers} +% With regard to layout, any declared layer inherits the defaut values +% described above in \vref{sec:single-layer-app}. That said, as the +% optional argument of \cs{DeclareApparatus} accepts the exact same +% |key-value| options as \cs{SetApparatus} described +% \vpagerefrange{ref:apparatus-settings-b}{ref:apparatus-settings-e}, +% \pkg{ekdosis} provides a straightforward mechanism to have any layer +% printed in a distinct layout. +% +% To return to the example provided +% \vpageref[above]{ex:single-layer-app-layout}, one could keep the +% same settings as above for the variant readings, declare an +% apparatus testium with a closing square bracket as a separator and +% finally remove the line between the testimonia and the variant +% readings like so:--- +% +% \iffalse +%<*example> +% \fi +\begin{minted}[linenos=false]{latex} +\SetEkdosisHooks{ + refnumstyle=\normalfont +} +\DeclareApparatus{testium}[ + sep={] }, + delim=\hskip 1em, + rule=\rule{0.7in}{0.4pt} +] +\DeclareApparatus{default}[ + sep={: }, + delim=\hskip 1em, + norule +] +\end{minted} +% \iffalse +% +% \fi +% +% \section{Inserting Notes in Multiple-Layer Apparatus} +% \label{sec:notes-in-multilayer-app} +% As said above in \vref{sec:multilayer-apparatus}, \pkg{ekdosis} +% initially sets one layer of notes that is called the +% \textooquote|default|\textcoquote\ layer. As a result, any new note +% inserted within the argument of \cs{app}|{}| as described +% \vpageref{ref:app-cmd} will go into that layer of the apparatus. +% % \section{To Be Continued...} % v1.0 of \pkg{ekdosis}, which should be available by the end of July % 2020, will include a full documentation. At the time of writing, the % author is working on this part of the package. % -% \begin{comment} -% \section{Multiple-Layer Apparatus Criticus} -% \end{comment} -% \label{sec:multilayer-apparatus} % % \label{ref:type-app} % \begin{comment} @@ -2443,10 +2654,6 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+ \luadirect{ekdosis.closestream()} } % \end{macrocode} -% Use |\normalfont| for line numbers:--- -% \begin{macrocode} -\renewcommand\linenumberfont{\normalfont\footnotesize} -% \end{macrocode} % \begin{macro}{\SetEkdosisHooks} \cs{SetEkdosisHooks} is used to set % hooks meant to be shared by all declared apparatuses, such as the % font size, the format of numerals, \emph{\&c.} This command can be @@ -2547,14 +2754,31 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+ \@onlypreamble\DeclareShorthand % \end{macrocode} % \end{macro} +% \begin{macro}{\getsiglum} +% \cs{getsiglum}\marg{csv list} takes a comma-separated list of +% declared ids by means of \cs{DeclareWitness}, \cs{DeclareHand}, +% \cs{DeclareShorthand} or \cs{DeclareScholar} and returns their +% respective renditions. % \begin{macrocode} \NewDocumentCommand{\getsiglum}{m}{% \luadirect{tex.sprint(ekdosis.getsiglum(\luastringN{#1}))}% } +% \end{macrocode} +% \end{macro} +% \begin{macro}{\SigLine} +% \cs{Sigline}\marg{unique id} takes the unique id of any declared +% witness by means of \cs{DeclareWitness} as argument and returns a +% line ready to be inserted in a table set to print a Conspectus +% Siglorum. \cs{SigLine} returns three fields separated by the symbol +% |&| that is used in tables as follows: the siglum referring to the +% witness, the contents of the |description| field and the contents of +% the optional |origDate| field. +% \begin{macrocode} \NewDocumentCommand{\SigLine}{m}{% \luadirect{tex.sprint(ekdosis.basic_cs(\luastringN{#1}))} } % \end{macrocode} +% \end{macro} % \paragraph{\TeX\ to \texttt{TEI xml}} % The following three commands can be used to instruct \pkg{ekdosis} % how to convert unknown or unusual \hologo{(La)TeX} commands into @@ -2658,6 +2882,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+ store bhook = \bhook@val, store ehook = \ehook@val, initial direction = LR, + initial delim = {}, initial ehook = {\csname ekd@end@apparatus\endcsname} } % \end{macrocode} @@ -2987,6 +3212,10 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+ } % \end{macrocode} % \end{macro} +% Use |\normalfont| for line numbers:--- +% \begin{macrocode} +\renewcommand\linenumberfont{\normalfont\footnotesize} +% \end{macrocode} % \begin{macro}{\EkdosisDefaultApparatus} % By default, \pkg{ekdosis} defines one layer of critical notes which % is called |default|. This name can be changed at any point of the -- cgit v1.2.3