From c0ed19154a1435e3a90b79f869d6c5440375f379 Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Mon, 28 Jun 2021 18:43:31 +0200 Subject: done documenting on headers and footers --- ekdosis.dtx | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 150 insertions(+), 16 deletions(-) diff --git a/ekdosis.dtx b/ekdosis.dtx index 820e9a8..716870c 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> - [2021/06/27 v1.3-dev Typesetting TEI xml-compliant critical editions] + [2021/06/28 v1.3-dev Typesetting TEI xml-compliant critical editions] % %<*driver> \begin{filecontents}[noheader,overwrite]{bibdata.xml} @@ -374,6 +374,15 @@ along with this program. If not, see version = {3.47} } +@Software{titleps, + title = {The Titleps package}, + titleaddon = {Page style control}, + author = {Bezos López, Javier}, + url = {https://ctan.org/pkg/titleps}, + date = {2019-10-16}, + version = {2.13} +} + @Software{verse, title = {The Verse package}, titleaddon = {Aids for typesetting simple verse}, @@ -3603,6 +3612,7 @@ Some \app[type=rec2]{ % they are related to. As a result of this rule, all spaces subsequent % to \cs{note} are ignored. % +% \needspace{2\baselineskip} % \DescribeMacro{\note} \cs{note}\oarg{options}\marg{text}\\ % As said above, \cs{note}, when found outside \cs{app}|{}|, is used % to insert in additional layers of the apparatus short comments or @@ -5139,7 +5149,12 @@ subtype="arabtex">'inna 'abI kAna mina % |toc|$=$\verb+book|part|chapter|section|subsection|subsubsection|paragraph|+\\ % |subparagraph|\hfill\tcboxverb{Default: not set}\\ % If |toc| be set, the title of the division goes into the table of -% contents at the hierarchic level that is specified as value. +% contents at the hierarchic level that is specified as value.\\ +% \DescribeOption{mark} \newfeature[v1.3] |mark|$=$\meta{signpost} +% \hfill\tcboxverb{Default: none}\\ +% |mark| holds the signpost to be emitted as marker for headers and +% footers. Its value is recalled by \cs{ekdmark} as described below in +% \vref{sec:headers-footers}. % % \paragraph{Formatting the Titles} % \DescribeMacro{\FormatDiv} By design, \pkg{ekdosis} does @@ -5167,10 +5182,11 @@ subtype="arabtex">'inna 'abI kAna mina % here follows how the first three hierarchical levels could be % formatted as un-numbered divisions:--- % +% \captof{Divisions of the body text}[\label{lst:ekddiv-ex}] % \iffalse %<*example> % \fi -\begin{minted}[linenos=false]{latex} +\begin{minted}{latex} % Preamble: \FormatDiv{1}{\begin{center}\Large}{\end{center}} \FormatDiv{2}{\begin{center}\large}{\end{center}} @@ -5280,6 +5296,126 @@ subtype="arabtex">'inna 'abI kAna mina % % \fi % +% \subsection{Headers and Footers} +% \label{sec:headers-footers} +% \newfeature[v1.3] \pkg{ekdosis} provides a mechanism of its own for +% emitting header and footer marks. The first operation consists in +% recording the information to be printed as signpost by means of the +% |mark| optional argument of the \cs{ekddiv} command described above +% in \vref{sec:ekddiv}. +% +% \DescribeMacro{\ekdmark} Once this is done, \cs{ekdmark} can be +% inserted in commands used to make headers and footers where the mark +% is to be printed. +% +% A common layout is that of headers in which one finds printed in +% sequence on even pages the page number, then the author's name, and +% on odd pages the title of the edited text, then the current +% division, then the page number, like so:--- +% +% \needspace{4\baselineskip} +% \begin{xltabular}{1.0\linewidth}{|XcX|} +% \multicolumn{3}{l}{Even pages:}\\ +% \hline +% \cs{thepage} & Hippocratis & \\ +% \hline +% \multicolumn{3}{l}{Odd pages:}\\ +% \hline +% & Epidemiarum liber II, \cs{ekdmark} & \hfill\cs{thepage}\\ +% \hline +% \end{xltabular} +% +% To return to the example provided by \vref{lst:ekddiv-ex}, the mark +% of the current division would be inserted in the third-level +% \cs{ekddiv} command printed at line~28 like so:--- +% +% \iffalse +%<*example> +% \fi +\begin{minted}[firstnumber=28,linenos]{latex} + \ekddiv{head=1, type=paragraph, depth=3, n=II.1.1, mark={1, 1}} +\end{minted} +% \iffalse +% +% \fi +% +% The following example illustrates how the corresponding headers and +% footers could be prepared in a straightforward way with the help of +% the \pkg{titleps} package:\footcite{titleps}--- +% +% \iffalse +%<*example> +% \fi +\begin{minted}[linenos=false]{latex} +% Preamble: +\usepackage{titleps} +\newpagestyle{edition}{ + \sethead[\thepage][Hippocratis][] + {}{Epidemiarum liber II, \ekdmark}{\thepage} +} +% Apply the page style: +\pagestyle{edition} +\end{minted} +% \iffalse +% +% \fi +% +% \DescribeMacro{\endmark} It must be noted that \cs{ekdmark} is +% designed to print the first mark that is emitted on a given page and +% ignore the mark corresponding to any portion of text that may be +% printed between the top of the page and the point where the first +% mark is called. \cs{endmark} is an argument-less command that can be +% used just at the end of that portion of text to instruct +% \pkg{ekdosis} to print the last-emitted mark of the preceding page +% instead of the first-emitted mark of the current page. +% +% \paragraph{Removing Headers and Footers} +% Pages such as title pages must be printed with empty headers and +% footers. \pkg{ekdosis} must be given control over every item of +% information inserted in these areas beforehand. +% +% \DescribeMacro{\ekdprintmark} +% \cs{ekdprintmark}\marg{selector}\marg{signpost} The signposts +% printed in headers and footers must be passed as second argument of +% \cs{ekdprintmark} so that \pkg{ekdosis} can remove them on pages +% where printing them is not desirable. \meta{selector} refers to +% three symbolic letters where the first can be either |H| or +% |F|\===for \underLine{h}eader or \underLine{f}ooter\===, the second +% |E| or |O|\===for \underLine{o}dd or \underLine{e}ven\===and the +% third |L|, |C| or |R|\===for \underLine{l}eft, \underLine{c}enter or +% \underLine{r}ight. The example provided above would then read as +% follows:--- +% +% \iffalse +%<*example> +% \fi +\begin{minted}[linenos=false]{latex} +% Preamble: +\usepackage{titleps} +\newpagestyle{edition}{ + \sethead[\ekdprintmark{HEL}{\thepage}] + [\ekdprintmark{HEC}{Hippocratis}] + [] + {} + {\ekdprintmark{HOC}{Epidemiarum liber II, \ekdmark}} + {\ekdprintmark{HOR}{\thepage}} +} +% Apply the page style: +\pagestyle{edition} +\end{minted} +% \iffalse +% +% \fi +% +% \DescribeMacro{\ekdnohfmarks} Once all signposts are marked with +% \cs{ekdprintmark}, \cs{ekdnohfmarks} can be used at any point of the +% document with the same effect as the \LaTeX\ standard command +% \cs{thispagestyle}|{empty}|. +% +% \DescribeMacro{\ekdresethfmarks} Finally, \cs{ekdresethfmarks} is +% provided in rare cases when it is needed to reset headers and +% footers to their original, viz.\ printable state. +% % \section{The Tricks of the Trade} % \label{sec:tricks-of-trade} % As the |.tex| source file is compiled, \pkg{ekdosis} has to compute @@ -6613,8 +6749,6 @@ Sample text with a \textcolor{red}{word} in red. % \item Marginal edition texts: It may happen that the marginalia of % manuscripts contain texts worth editing in addition to and along % the main text to which they are linked by reference signs. -% \item Headers and footers: \cs{ekddiv} will provide top and bottom -% marks to be used in headers and footers. % \end{enumerate} % \item Short-term (months):--- % \begin{enumerate} @@ -7353,7 +7487,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \paragraph{Setup} % \begin{macro}{\ekdsetup} -% \changes{v1.3}{2021/06/27}{new command for global options} +% \changes{v1.3}{2021/06/28}{new command for global options} % \cs{ekdsetup} is used to specify options that affect the general % behavior of \pkg{ekdosis}. It is a preamble-only command. % \begin{macrocode} @@ -7584,7 +7718,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\teidirect} -% \changes{v1.3}{2021/06/27}{direct insertion of elements in the +% \changes{v1.3}{2021/06/28}{direct insertion of elements in the % \texttt{TEI xml} file} % \cs{teidirect}\oarg{xml attributes}\marg{xml element}\marg{code} % does nothing in \LaTeX. Its only use is to insert elements in the @@ -7951,7 +8085,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\SetApparatusNoteLanguage} -% \changes{v1.3}{2021/06/27}{defines an alternate language to be +% \changes{v1.3}{2021/06/28}{defines an alternate language to be % applied in note apparatus entries} % \cs{SetApparatusNoteLang}\marg{languagename} can be used when % it is needed to apply in entries introduced by the \cs{note} command @@ -9198,11 +9332,11 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\endmark} -% \changes{v1.3}{2021/06/27}{prints the last-emitted mark of the +% \changes{v1.3}{2021/06/28}{prints the last-emitted mark of the % preceding page} % By default, \cs{ekdmark} described below prints the first mark % that is emitted on a given page and ignores the mark corresponding -% to the portion of text that may be printed between the top of the +% to any portion of text that may be printed between the top of the % page and the point where the first mark is called. \cs{endmark} is % an argument-less command that can be used just at the end of that % portion of text to instruct \pkg{ekdosis} to print the last-emitted @@ -9220,7 +9354,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\edkmark} -% \changes{v1.3}{2021/06/27}{prints marks in headers or footers} +% \changes{v1.3}{2021/06/28}{prints marks in headers or footers} % \cs{ekdmark} is an argument-less command called in commands used to % make headers and footers where the marks stored by means of the % |mark| optional argument of \cs{ekddiv} are to be printed. @@ -9231,13 +9365,13 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\ekdprintmark} -% \changes{v1.3}{2021/06/27}{prints or removes the marks in headers +% \changes{v1.3}{2021/06/28}{prints or removes the marks in headers % and footers} \cs{ekdprintmark}\marg{selector}\marg{signpost} The % signposts printed in headers and footers must be % passed as second argument of \cs{ekdprintmark} so that \pkg{ekdosis} % can remove them on pages where printing them is not % desirable. \meta{selector} refers to three symbolic letters where -% the first can be |H| or |F|\===for \underLine{h}eader or +% the first can be either |H| or |F|\===for \underLine{h}eader or % \underLine{f}ooter\===, the second |E| or |O|\===for \underLine{o}dd % or \underLine{e}ven\===and the third |L|, |C| or |R|\===for % \underLine{l}eft, \underLine{c}enter or \underLine{r}ight:--- @@ -9269,10 +9403,10 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\ekdnofhmarks} -% \changes{v1.3}{2021/06/27}{removes headers and footers on specific +% \changes{v1.3}{2021/06/28}{removes headers and footers on specific % pages} Once the signposts are marked with \cs{ekdprintmark}, % \cs{ekdnohfmarks} has the same effect as the \LaTeX\ standard -% command \cs{thispagestyle}|{empty}|. +% command \cs{thispagestyle}|{empty}|. % \begin{macrocode} \NewDocumentCommand{\ekdnohfmark}{}{% \luadirect{ekdosis.nohfmark()}% @@ -9280,7 +9414,7 @@ Sample text with a \textcolor{red}{word} in red. % \end{macrocode} % \end{macro} % \begin{macro}{\ekdresethfmarks} -% \changes{v1.3}{2021/06/27}{marks headers and footers as printable} +% \changes{v1.3}{2021/06/28}{marks headers and footers as printable} % \cs{ekdresethfmarks} can be used in rare cases when it is needed to % reset headers and footers to their original, viz.\ printable state. % \begin{macrocode} -- cgit v1.2.3