done documenting on headers and footers

1 files 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
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\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]
 %</package>
 %<*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
 %</example>
 % \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
+%</example>
+% \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
+%</example>
+% \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
+%</example>
+% \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}