started documenting the functions related to headers and footers

1 files changed, 115 insertions, 53 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index bb042f3..820e9a8 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/26 v1.3-dev Typesetting TEI xml-compliant critical editions]
+    [2021/06/27 v1.3-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -5092,7 +5092,7 @@ subtype="arabtex">'inna 'abI kAna mina
 %</example>
 % \fi
 %
-% \subsection{Using \texttt{TEI} Un-numbered Divisions}
+% \subsection{\texttt{TEI} Un-numbered Divisions}
 % \label{sec:ekddiv}
 % \danger As already described \vpageref{ref:divs-opt}, the
 % un-numbered style of division is the one that is set by default. It
@@ -7353,7 +7353,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \paragraph{Setup}
 % \begin{macro}{\ekdsetup}
-% \changes{v1.3}{2021/06/26}{new command for global options}
+% \changes{v1.3}{2021/06/27}{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 +7584,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\teidirect}
-% \changes{v1.3}{2021/06/26}{direct insertion of elements in the
+% \changes{v1.3}{2021/06/27}{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 +7951,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\SetApparatusNoteLanguage}
-% \changes{v1.3}{2021/06/26}{defines an alternate language to be
+% \changes{v1.3}{2021/06/27}{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
@@ -9180,6 +9180,13 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{environment}
 % \paragraph{Headers and Footers}
+% \pkg{ekdosis} provides a mechanism of its own for headers and
+% footers as follows. Most of it is handled by \textsf{Lua}
+% functions.
+% \begin{macro}{\ekd@storemark}
+% \cs{ekd@storemark} is used internally by the |mark| optional
+% argument of \cs{ekddiv} described below to store marks to be
+% printed at specific places in headers or footers.
 %    \begin{macrocode}
 \NewDocumentCommand{\ekd@storemark}{m}{%
   \stepcounter{ekd@lab}%
@@ -9188,6 +9195,20 @@ Sample text with a \textcolor{red}{word} in red.
     \luastring{\getpagerefnumber{ekd:\theekd@lab}},
     \luastringN{#1})}%
 }
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\endmark}
+% \changes{v1.3}{2021/06/27}{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
+% 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.
+%    \begin{macrocode}
 \NewDocumentCommand{\endmark}{}{%
   \stepcounter{ekd@lab}%
   \label{ekd:\theekd@lab}%
@@ -9196,22 +9217,47 @@ Sample text with a \textcolor{red}{word} in red.
     "", "endmk")}%
   \ifdefined\xspace\xspace\fi
 }
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\edkmark}
+% \changes{v1.3}{2021/06/27}{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.
+%    \begin{macrocode}
 \NewDocumentCommand{\ekdmark}{}{%
   \luadirect{tex.sprint(ekdosis.gethfmark(\luastring{\thepage}))}%
 }
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ekdprintmark}
+% \changes{v1.3}{2021/06/27}{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
+% \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:---
+%    \begin{macrocode}
 \ekvdefinekeys{ekd@marks}{
-  choice mark = {hel = \def\ekd@mk{hel},
-    hec = \def\ekd@mk{hec},
-    her = \def\ekd@mk{her},
-    hol = \def\ekd@mk{hol},
-    hoc = \def\ekd@mk{hoc},
-    hor = \def\ekd@mk{hor},
-    fol = \def\ekd@mk{fol},
-    foc = \def\ekd@mk{foc},
-    fol = \def\ekd@mk{fol},
-    fel = \def\ekd@mk{fel},
-    fec = \def\ekd@mk{fec},
-    fel = \def\ekd@mk{fel}}
+  choice mark = {HEL = \def\ekd@mk{HEL},
+    HEC = \def\ekd@mk{HEC},
+    HER = \def\ekd@mk{HER},
+    HOL = \def\ekd@mk{HOL},
+    HOC = \def\ekd@mk{HOC},
+    HOR = \def\ekd@mk{HOR},
+    FEL = \def\ekd@mk{FEL},
+    FEC = \def\ekd@mk{FEC},
+    FEL = \def\ekd@mk{FER},
+    FOL = \def\ekd@mk{FOL},
+    FOC = \def\ekd@mk{FOC},
+    FOL = \def\ekd@mk{FOR}},
+  unknown-choice mark = \PackageError{ekdosis}{unknown mark=#1}{`mark'
+    must be either `HEL', `HEC', `HER', `HOL', `HOC', `HOR', `FEL', 
+    \MessageBreak `FEC', `FER', `FOL', `FOC' or `FOR'.}
 }
 \NewDocumentCommand{\ekdprintmark}{m m}{%
   \bgroup
@@ -9220,13 +9266,29 @@ Sample text with a \textcolor{red}{word} in red.
     \luastringO{\ekd@mk}))}%
   \egroup
 }
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ekdnofhmarks}
+% \changes{v1.3}{2021/06/27}{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}|. 
+%    \begin{macrocode}
 \NewDocumentCommand{\ekdnohfmark}{}{%
   \luadirect{ekdosis.nohfmark()}%
 }
+%    \end{macrocode}
+% \end{macro}
+% \begin{macro}{\ekdresethfmarks}
+% \changes{v1.3}{2021/06/27}{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}
 \NewDocumentCommand{\ekdresethfmarks}{}{%
   \luadirect{ekdosis.resethfmark()}%
 }
 %    \end{macrocode}
+% \end{macro}
 % \paragraph{Divisions of the Body}
 % \pkg{ekdosis} can convert \cs{book}, \cs{part}, \cs{chapter},
 % \cs{section}, \cs{subsec{\allowbreak}tion} and \cs{subsubsection}
@@ -10503,48 +10565,48 @@ function ekdosis.storehfmark(page, mk, opt)
 end
 
 local printhfmarks = {
-   hel = true,
-   hec = true,
-   her = true,
-   hol = true,
-   hoc = true,
-   hor = true,
-   fol = true,
-   foc = true,
-   fol = true,
-   fel = true,
-   fec = true,
-   fel = true,
+   HEL = true,
+   HEC = true,
+   HER = true,
+   HOL = true,
+   HOC = true,
+   HOR = true,
+   FOL = true,
+   FOC = true,
+   FOR = true,
+   FEL = true,
+   FEC = true,
+   FER = true,
 }
 
 function ekdosis.nohfmark()
-   printhfmarks.hel = false
-   printhfmarks.hec = false
-   printhfmarks.her = false
-   printhfmarks.hol = false
-   printhfmarks.hoc = false
-   printhfmarks.hor = false
-   printhfmarks.fol = false
-   printhfmarks.foc = false
-   printhfmarks.fol = false
-   printhfmarks.fel = false
-   printhfmarks.fec = false
-   printhfmarks.fel = false
+   printhfmarks.HEL = false
+   printhfmarks.HEC = false
+   printhfmarks.HER = false
+   printhfmarks.HOL = false
+   printhfmarks.HOC = false
+   printhfmarks.HOR = false
+   printhfmarks.FOL = false
+   printhfmarks.FOC = false
+   printhfmarks.FOR = false
+   printhfmarks.FEL = false
+   printhfmarks.FEC = false
+   printhfmarks.FER = false
 end
 
 function ekdosis.resethfmark()
-   printhfmarks.hel = true
-   printhfmarks.hec = true
-   printhfmarks.her = true
-   printhfmarks.hol = true
-   printhfmarks.hoc = true
-   printhfmarks.hor = true
-   printhfmarks.fol = true
-   printhfmarks.foc = true
-   printhfmarks.fol = true
-   printhfmarks.fel = true
-   printhfmarks.fec = true
-   printhfmarks.fel = true
+   printhfmarks.HEL = true
+   printhfmarks.HEC = true
+   printhfmarks.HER = true
+   printhfmarks.HOL = true
+   printhfmarks.HOC = true
+   printhfmarks.HOR = true
+   printhfmarks.FOL = true
+   printhfmarks.FOC = true
+   printhfmarks.FOR = true
+   printhfmarks.FEL = true
+   printhfmarks.FEC = true
+   printhfmarks.FER = true
 end
 
 function ekdosis.printmark(str, mk)