aboutsummaryrefslogtreecommitdiff
path: root/ekdosis.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'ekdosis.dtx')
-rw-r--r--ekdosis.dtx295
1 files changed, 262 insertions, 33 deletions
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
625% not as compact paragraphs that require special and painful training 625% not as compact paragraphs that require special and painful training
626% to be \enquote*{decoded}. On the other hand, what editions in print 626% to be \enquote*{decoded}. On the other hand, what editions in print
627% do not provide are what \citename{Mastronarde.Tarrant2017}{author} 627% do not provide are what \citename{Mastronarde.Tarrant2017}{author}
628% have called \enquote{actionable texts for use in digital 628% have called \enquote{actionable texts for use in digital research},%
629% research},\footcite{Mastronarde.Tarrant2017} namely database-driven 629% {\interfootnotelinepenalty=10000\footcite{Mastronarde.Tarrant2017}}
630% texts allowing the reader to select annotations and display or 630% namely database-driven texts allowing the reader to select
631% arrange translations, parallel passages or borrowings in a variety 631% annotations and display or arrange translations, parallel passages
632% of ways. 632% or borrowings in a variety of ways.
633% 633%
634% \pkg{ekdosis} can be seen as an attempt at combining the two 634% \pkg{ekdosis} can be seen as an attempt at combining the two
635% approaches. 635% approaches.
@@ -650,17 +650,18 @@ along with this program. If not, see
650% synchronized or not. \pkg{ekdosis} is also suitable for complex 650% synchronized or not. \pkg{ekdosis} is also suitable for complex
651% layouts as in the case of Arabic poetry or images where three-way 651% layouts as in the case of Arabic poetry or images where three-way
652% alignment is required, or diagrams, \emph{\&c}. 652% alignment is required, or diagrams, \emph{\&c}.
653% \item \emph{Apparatus criticus\/}: Edited texts can receive multiple 653% \item \label{it:multilayer-feature}\emph{Apparatus criticus\/}:
654% layers of apparatus, e.g.\ apparatus criticus (to record variant 654% Edited texts can receive multiple layers of apparatus, e.g.\
655% readings), apparatus fontium (to collect references to texts quoted 655% apparatus criticus (to record variant readings), apparatus fontium
656% or cited in the edited text), apparatus testium (to collect 656% (to collect references to texts quoted or cited in the edited
657% testimonia or parallel passages), or any kind of short notes to be 657% text), apparatus testium (to collect testimonia or parallel
658% printed on the same page as the edited text, \emph{\&c}. 658% passages), or any kind of short notes to be printed on the same
659% \item \texttt{TEI xml} output: \pkg{ekdosis} can be instructed 659% page as the edited text, \emph{\&c}.
660% to output both PDF and \texttt{TEI xml} files at the same time. 660% \item \texttt{TEI xml} output: \pkg{ekdosis} can be instructed to
661% output both PDF and \texttt{TEI xml} files at the same time.
661% \item \emph{Database-driven encoding} under \LaTeX{} of texts 662% \item \emph{Database-driven encoding} under \LaTeX{} of texts
662% entered segment by segment allows for alignment of parallel texts 663% entered segment by segment allows for alignment of parallel texts
663% from multilingual corpora. 664% from multilingual corpora.
664% \end{enumerate} 665% \end{enumerate}
665% 666%
666% Before going into detail, the following simple example will give the 667% Before going into detail, the following simple example will give the
@@ -1086,7 +1087,7 @@ along with this program. If not, see
1086% 1087%
1087% \paragraph{Apparatus Entries} 1088% \paragraph{Apparatus Entries}
1088% \DescribeMacro{\app} \cs{app}|[type=|\meta{type}|]|\marg{apparatus 1089% \DescribeMacro{\app} \cs{app}|[type=|\meta{type}|]|\marg{apparatus
1089% entries}\\ 1090% entries}\label{ref:app-cmd}\\
1090% This command takes one mandatory argument and accepts one optional 1091% This command takes one mandatory argument and accepts one optional
1091% argument. Once references to be used as witnesses in the apparatus 1092% argument. Once references to be used as witnesses in the apparatus
1092% criticus have been declared in the preamble as described in 1093% criticus have been declared in the preamble as described in
@@ -1111,9 +1112,10 @@ yesterday.
1111%</example> 1112%</example>
1112% \fi 1113% \fi
1113% \cs{app} accepts one further optional argument:---\\ 1114% \cs{app} accepts one further optional argument:---\\
1114% \DescribeOption{type} |type|$=$\meta{type}\hfill% 1115% \DescribeOption{type} |type|$=$\meta{type}\label{ref:app-type}
1115% \tcboxverb{Default: default}\\ 1116% \hfill\tcboxverb{Default: default}\\
1116% By default, \pkg{ekdosis} sets one layer of notes\--- the |default| 1117% As will be described below in \vref{sec:multilayer-apparatus},
1118% \pkg{ekdosis} initially sets one layer of notes\--- the |default|
1117% layer\---in the apparatus criticus. This layer is fit to receive 1119% layer\---in the apparatus criticus. This layer is fit to receive
1118% notes related to variant readings from witnesses and sources used by 1120% notes related to variant readings from witnesses and sources used by
1119% the editor to establish the edition text. Additional layers can be 1121% the editor to establish the edition text. Additional layers can be
@@ -1125,7 +1127,8 @@ yesterday.
1125% additional layers have been defined and assigned to new 1127% additional layers have been defined and assigned to new
1126% \enquote*{types}, such as \enquote*{testium} and the like, these 1128% \enquote*{types}, such as \enquote*{testium} and the like, these
1127% types can be used as values appended to the |type| \enquote*{named 1129% types can be used as values appended to the |type| \enquote*{named
1128% option}. 1130% option}. For more information about inserting notes in
1131% multiple-layer apparatus, see \vref{sec:notes-in-multilayer-app}.
1129% 1132%
1130% \paragraph{Base text and variants} As can be seen in the example 1133% \paragraph{Base text and variants} As can be seen in the example
1131% above, there are two kinds of individual readings: the \emph{lemma}, 1134% above, there are two kinds of individual readings: the \emph{lemma},
@@ -1756,9 +1759,45 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
1756% 1759%
1757% \section{Laying Out the Apparatus Criticus } 1760% \section{Laying Out the Apparatus Criticus }
1758% \label{sec:apparatus-layout} 1761% \label{sec:apparatus-layout}
1762%
1763% \subsection{General Hooks}
1764% \label{sec:general-hooks}
1765% Some hooks are shared by all layers of notes that are inserted in
1766% the apparatus criticus (e.g. sources, testimonia, variant readings
1767% \emph{\&c.})
1768%
1769% \DescribeMacro{\SetEkdosisHooks}
1770% \cs{SetEkdosisHooks}\marg{csv list of hooks} can be used either in
1771% the preamble or at any point of the document. The list of accepted
1772% hooks at the time of writing follows:---\\
1773% \DescribeOption{appfontsize} |appfontsize|$=$\meta{csname}
1774% \hfill\tcboxverb{Default: \footnotesize}\\
1775% This option sets the size of the font to be used in the whole
1776% apparatus criticus. By default, it is the same as the size used for
1777% footnotes.\\
1778% \DescribeOption{refnumstyle} |refnumstyle|$=$\meta{csname}
1779% \hfill\tcboxverb{Default: \bfseries}\\
1780% |refnumstyle| can be used to set the family, series or shape of the
1781% font used to print references to line numbers in the apparatus
1782% criticus. By default, numbers are printed in bold face. As an
1783% example, |refnumstyle=\normalfont| will have them printed in the
1784% font and shape selected by default for the
1785% document, while |refnumstyle=\bfseries\itshape| will have them
1786% printed in bold and italic.\\
1787% \DescribeOption{postrefnum} |postrefnum|$=$\meta{csname \textbar\
1788% chars}\hfill\tcboxverb{Default: ~}\\
1789% |postrefnum| can be used to set what immediately follows the
1790% reference to line numbers. By default, it is |~|, namely an
1791% unbreakable space. As an example, |postrefnum=\hskip 0.5em| will
1792% insert a \unit[0.5]{em} space between the numerals and the beginning
1793% of all subsequent notes.
1794%
1795% \subsection{Single-Layer Apparatus Criticus}
1796% \label{sec:single-layer-app}
1797% \paragraph{Specific Commands}
1759% Single-layer apparatus criticus can be laid out in a variety of 1798% Single-layer apparatus criticus can be laid out in a variety of
1760% ways with the following specialized commands, all of which can be 1799% ways with the following specialized commands, all of which can be
1761% used in the preamble or at any point of the document. 1800% used in the preamble or at any point of the document:---
1762% 1801%
1763% \DescribeMacro{\SetLTRapp} 1802% \DescribeMacro{\SetLTRapp}
1764% \DescribeMacro{\SetRTLapp} 1803% \DescribeMacro{\SetRTLapp}
@@ -1772,9 +1811,9 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
1772% followed by a space (\verb*+] +). 1811% followed by a space (\verb*+] +).
1773% 1812%
1774% \DescribeMacro{\SetBeginApparatus} 1813% \DescribeMacro{\SetBeginApparatus}
1775% \cs{SetBeginApparatus}\marg{characters/commands} can be used to 1814% \cs{SetBeginApparatus}\marg{characters\textbar commands} can be used
1776% append \meta{characters} or \meta{commands} at the beginning of the 1815% to append \meta{characters} or \meta{commands} at the beginning of
1777% apparatus block. By default, nothing is appended. For instance, 1816% the apparatus block. By default, nothing is appended. For instance,
1778% \mintinline{latex}|\SetBeginApparatus{\textbf{Apparatus:}}| will 1817% \mintinline{latex}|\SetBeginApparatus{\textbf{Apparatus:}}| will
1779% append \enquote{\textbf{Apparatus:}} at the beginning of the 1818% append \enquote{\textbf{Apparatus:}} at the beginning of the
1780% apparatus block, while % 1819% apparatus block, while %
@@ -1789,17 +1828,189 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
1789% at the end of the apparatus as it is customary in some editions. 1828% at the end of the apparatus as it is customary in some editions.
1790% 1829%
1791% \DescribeMacro{\SetUnitDelimiter} 1830% \DescribeMacro{\SetUnitDelimiter}
1792% \cs{SetUnitDelimiter} 1831% \cs{SetUnitDelimiter}\marg{delimiter} can be used to set the
1832% delimiter between entries in the apparatus criticus. By default,
1833% there is no delimiter except a simple space. \meta{delimiter} can be
1834% a broad space (such as |\hskip 0.75em| for instance as in the OCT
1835% series) or the divider-sign (‖, as in the Budé series).
1836%
1837% \DescribeMacro{\SetDefaultRule}
1838% By default, \pkg{ekdosis} draws a separating line between the
1839% edition text and the apparatus criticus. This line is initially
1840% defined as
1841% |\rule{0.4\columnwidth}{0.4pt}|. \cs{SetDefaultRule}\marg{line
1842% definition} can be used in the preamble or at any point of the
1843% document to change the default setting. Leaving this argument empty
1844% as in \cs{SetDefaultRule}|{}| removes the line.
1845%
1846% \paragraph{General Command}
1847% \DescribeMacro{\SetApparatus} \cs{SetApparatus}\marg{csv list of
1848% apparatus settings}\label{ref:apparatus-settings-b}\\
1849% Finally, all the settings described above can also be collected in
1850% the argument of \cs{SetApparatus}. \cs{SetApparatus} accepts the
1851% following list of comma-separated |key=value| options:---\\
1852% \DescribeOption{direction} |direction|$=$\verb+LR|RL+
1853% \hfill\tcboxverb{Default: LR}\\
1854% The writing direction of the apparatus criticus, either
1855% left-to-right (|LR|) or right-to-left (|LR|).\\
1856% \DescribeOption{sep} |sep|$=$\meta{csname \textbar\ chars}
1857% \hfill\tcboxverb{Default: ]␣}\\
1858% The separator between lemma texts and variant readings.\\
1859% \DescribeOption{delim} |delim|$=$\meta{delimiter}
1860% \hfill\tcboxverb{Default: not set}\\
1861% The delimiter between entries in the apparatus criticus. As said
1862% above, there is no default delimiter except a simple space.\\
1863% \DescribeOption{bhook} |bhook|$=$\meta{characters\textbar commands}
1864% \hfill\tcboxverb{Default: empty}\\
1865% The characters or commands to be appended at the beginning of the
1866% apparatus block.\\
1867% \DescribeOption{ehook} |ehook|$=$\meta{characters}
1868% \hfill\tcboxverb{Default: empty}\\
1869% The characters to be appended at the end of the apparatus block.\\
1870% \DescribeOption{rule} |rule|$=$\meta{command}\verb+|+|none|
1871% \hfill\tcboxverb{Default: \rule{0.4\columnwidth}{0.4pt}}\\
1872% As described above, |rule| is used to draw the separating line
1873% between the edition text and the apparatus criticus. |rule=none| can
1874% also be used to remove the line.\\
1875% \DescribeOption{norule}\hfill\tcboxverb{Default: not set}\\
1876% |norule| does not accept any value and has the same effect as
1877% |rule=none|.\label{ref:apparatus-settings-e}
1878%
1879% As an example, an apparatus criticus with references to line numbers
1880% printed in normal font, a colon as a separator between lemma texts
1881% and variant readings, a broad space as a delimiter between entries
1882% and a \unit[0.7]{in} line above could be laid out as follows:---
1883%
1884% \label{ex:single-layer-app-layout}
1885% \iffalse
1886%<*example>
1887% \fi
1888\begin{minted}[linenos=false]{latex}
1889\SetEkdosisHooks{
1890 refnumstyle=\normalfont
1891}
1892\SetApparatus{
1893 sep={: },
1894 delim=\hskip 1em,
1895 rule=\rule{0.7in}{0.4pt}
1896}
1897\end{minted}
1898% \iffalse
1899%</example>
1900% \fi
1901%
1902% \paragraph{Footnote Separator}
1903% \DescribeMacro{\footnoteruletrue} \DescribeMacro{\footnoterulefalse}
1904% As already seen above, \pkg{ekdosis} takes care of drawing a
1905% separating line between the edition text and the apparatus
1906% criticus. Therefore, it may be not desirable to have the standard
1907% \LaTeX\ \enquote{footnoterule} printed on every page where regular
1908% footnotes are found. \cs{footnoterulefalse} removes it while
1909% \cs{footnoteruletrue} leaves it untouched. The latter is set by
1910% default.
1911%
1912% \subsection{Multiple-Layer Apparatus Criticus}
1913% \label{sec:multilayer-apparatus}
1914% As said above in \vref{it:multilayer-feature}, \pkg{ekdosis} can
1915% print edition texts equipped with multiple-layer apparatus
1916% criticus. To take an example, most classical editions provide at
1917% least two layers of notes: one to collect references to testimonia
1918% or parallel passages (apparatus testium) and the other to record
1919% variant readings (the apparatus criticus \emph{stricto sensu}). The
1920% former is always printed above the latter.
1921%
1922% \danger The default single-layer apparatus criticus that is
1923% described above in \vref{sec:single-layer-app} is called |default|
1924% internally. If any additional layer of notes be declared in the
1925% preamble, this |default| layer must be included in the list of
1926% declared layers.\\
1927% \DescribeMacro{\EkdosisDefaultApparatus}
1928% \cs{EkdosisDefaultApparatus}\marg{name} can be used at any point of
1929% the document to change the default name that is used by
1930% \pkg{ekdosis}.
1931%
1932% \subsubsection{Declaring Additional Layers}
1933% \label{sec:declaring-layers}
1934% \DescribeMacro{\DeclareApparatus}
1935% \cs{DeclareApparatus}\marg{name}\oarg{csv list of apparatus
1936% settings} is a preamble-only command. As a mandatory argument, it
1937% takes the name of the new layer of notes to be inserted in the
1938% apparatus block. Declared layers are then printed one below the
1939% other in the exact same order as they are declared in the
1940% preamble. Therefore, one additional layer meant to print the
1941% testimonia above the variant readings (apparatus testium) can be
1942% declared as follows:---
1793% 1943%
1944% \iffalse
1945%<*example>
1946% \fi
1947\begin{minted}{latex}
1948% preamble:
1949\DeclareApparatus{testium}
1950\DeclareApparatus{default}
1951\end{minted}
1952% \iffalse
1953%</example>
1954% \fi
1955%
1956% In this example, |testium| is a new name for |default|, as said
1957% just above, is already known to \pkg{ekdosis} and used as the
1958% default layer of notes. Furthermore, as |testium| is declared before
1959% |default|, \pkg{ekdosis} will print the testimonia at the top of the
1960% apparatus block.
1961%
1962% \subsubsection{Laying Out Layers}
1963% \label{sec:layout-layers}
1964% With regard to layout, any declared layer inherits the defaut values
1965% described above in \vref{sec:single-layer-app}. That said, as the
1966% optional argument of \cs{DeclareApparatus} accepts the exact same
1967% |key-value| options as \cs{SetApparatus} described
1968% \vpagerefrange{ref:apparatus-settings-b}{ref:apparatus-settings-e},
1969% \pkg{ekdosis} provides a straightforward mechanism to have any layer
1970% printed in a distinct layout.
1971%
1972% To return to the example provided
1973% \vpageref[above]{ex:single-layer-app-layout}, one could keep the
1974% same settings as above for the variant readings, declare an
1975% apparatus testium with a closing square bracket as a separator and
1976% finally remove the line between the testimonia and the variant
1977% readings like so:---
1978%
1979% \iffalse
1980%<*example>
1981% \fi
1982\begin{minted}[linenos=false]{latex}
1983\SetEkdosisHooks{
1984 refnumstyle=\normalfont
1985}
1986\DeclareApparatus{testium}[
1987 sep={] },
1988 delim=\hskip 1em,
1989 rule=\rule{0.7in}{0.4pt}
1990]
1991\DeclareApparatus{default}[
1992 sep={: },
1993 delim=\hskip 1em,
1994 norule
1995]
1996\end{minted}
1997% \iffalse
1998%</example>
1999% \fi
2000%
2001% \section{Inserting Notes in Multiple-Layer Apparatus}
2002% \label{sec:notes-in-multilayer-app}
2003% As said above in \vref{sec:multilayer-apparatus}, \pkg{ekdosis}
2004% initially sets one layer of notes that is called the
2005% \textooquote|default|\textcoquote\ layer. As a result, any new note
2006% inserted within the argument of \cs{app}|{}| as described
2007% \vpageref{ref:app-cmd} will go into that layer of the apparatus.
2008%
1794% \section{To Be Continued...} 2009% \section{To Be Continued...}
1795% v1.0 of \pkg{ekdosis}, which should be available by the end of July 2010% v1.0 of \pkg{ekdosis}, which should be available by the end of July
1796% 2020, will include a full documentation. At the time of writing, the 2011% 2020, will include a full documentation. At the time of writing, the
1797% author is working on this part of the package. 2012% author is working on this part of the package.
1798% 2013%
1799% \begin{comment}
1800% \section{Multiple-Layer Apparatus Criticus}
1801% \end{comment}
1802% \label{sec:multilayer-apparatus}
1803% 2014%
1804% \label{ref:type-app} 2015% \label{ref:type-app}
1805% \begin{comment} 2016% \begin{comment}
@@ -2443,10 +2654,6 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
2443 \luadirect{ekdosis.closestream()} 2654 \luadirect{ekdosis.closestream()}
2444} 2655}
2445% \end{macrocode} 2656% \end{macrocode}
2446% Use |\normalfont| for line numbers:---
2447% \begin{macrocode}
2448\renewcommand\linenumberfont{\normalfont\footnotesize}
2449% \end{macrocode}
2450% \begin{macro}{\SetEkdosisHooks} \cs{SetEkdosisHooks} is used to set 2657% \begin{macro}{\SetEkdosisHooks} \cs{SetEkdosisHooks} is used to set
2451% hooks meant to be shared by all declared apparatuses, such as the 2658% hooks meant to be shared by all declared apparatuses, such as the
2452% font size, the format of numerals, \emph{\&c.} This command can be 2659% font size, the format of numerals, \emph{\&c.} This command can be
@@ -2547,14 +2754,31 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
2547\@onlypreamble\DeclareShorthand 2754\@onlypreamble\DeclareShorthand
2548% \end{macrocode} 2755% \end{macrocode}
2549% \end{macro} 2756% \end{macro}
2757% \begin{macro}{\getsiglum}
2758% \cs{getsiglum}\marg{csv list} takes a comma-separated list of
2759% declared ids by means of \cs{DeclareWitness}, \cs{DeclareHand},
2760% \cs{DeclareShorthand} or \cs{DeclareScholar} and returns their
2761% respective renditions.
2550% \begin{macrocode} 2762% \begin{macrocode}
2551\NewDocumentCommand{\getsiglum}{m}{% 2763\NewDocumentCommand{\getsiglum}{m}{%
2552 \luadirect{tex.sprint(ekdosis.getsiglum(\luastringN{#1}))}% 2764 \luadirect{tex.sprint(ekdosis.getsiglum(\luastringN{#1}))}%
2553} 2765}
2766% \end{macrocode}
2767% \end{macro}
2768% \begin{macro}{\SigLine}
2769% \cs{Sigline}\marg{unique id} takes the unique id of any declared
2770% witness by means of \cs{DeclareWitness} as argument and returns a
2771% line ready to be inserted in a table set to print a Conspectus
2772% Siglorum. \cs{SigLine} returns three fields separated by the symbol
2773% |&| that is used in tables as follows: the siglum referring to the
2774% witness, the contents of the |description| field and the contents of
2775% the optional |origDate| field.
2776% \begin{macrocode}
2554\NewDocumentCommand{\SigLine}{m}{% 2777\NewDocumentCommand{\SigLine}{m}{%
2555 \luadirect{tex.sprint(ekdosis.basic_cs(\luastringN{#1}))} 2778 \luadirect{tex.sprint(ekdosis.basic_cs(\luastringN{#1}))}
2556} 2779}
2557% \end{macrocode} 2780% \end{macrocode}
2781% \end{macro}
2558% \paragraph{\TeX\ to \texttt{TEI xml}} 2782% \paragraph{\TeX\ to \texttt{TEI xml}}
2559% The following three commands can be used to instruct \pkg{ekdosis} 2783% The following three commands can be used to instruct \pkg{ekdosis}
2560% how to convert unknown or unusual \hologo{(La)TeX} commands into 2784% how to convert unknown or unusual \hologo{(La)TeX} commands into
@@ -2658,6 +2882,7 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
2658 store bhook = \bhook@val, 2882 store bhook = \bhook@val,
2659 store ehook = \ehook@val, 2883 store ehook = \ehook@val,
2660 initial direction = LR, 2884 initial direction = LR,
2885 initial delim = {},
2661 initial ehook = {\csname ekd@end@apparatus\endcsname} 2886 initial ehook = {\csname ekd@end@apparatus\endcsname}
2662} 2887}
2663% \end{macrocode} 2888% \end{macrocode}
@@ -2987,6 +3212,10 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
2987} 3212}
2988% \end{macrocode} 3213% \end{macrocode}
2989% \end{macro} 3214% \end{macro}
3215% Use |\normalfont| for line numbers:---
3216% \begin{macrocode}
3217\renewcommand\linenumberfont{\normalfont\footnotesize}
3218% \end{macrocode}
2990% \begin{macro}{\EkdosisDefaultApparatus} 3219% \begin{macro}{\EkdosisDefaultApparatus}
2991% By default, \pkg{ekdosis} defines one layer of critical notes which 3220% By default, \pkg{ekdosis} defines one layer of critical notes which
2992% is called |default|. This name can be changed at any point of the 3221% is called |default|. This name can be changed at any point of the