new commands for “mirrored” paired facing pages

2 files changed, 153 insertions, 9 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 5faf7fa..e7594ac 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>
-    [2022/04/20 v1.5-dev Typesetting TEI xml-compliant critical editions]
+    [2022/04/28 v1.5-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -605,9 +605,11 @@ along with this program.  If not, see
 %^^A dox does not work with the latest latex-dev:
 \ifdefined\SpecialMacroIndex
   \NewDocElement{Option}{option}
+  \NewDocElement[printtype=\textit{cnt.}]{Counter}{counter}
 \else
   \usepackage{dox}
   \doxitem{Option}{option}{options}
+  \doxitem{Counter}{counter}{counter}
 \fi
 \usepackage{fontspec}
 \defaultfontfeatures{Renderer=Harfbuzz}
@@ -3330,7 +3332,8 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % pages. The |paired| option leaves every right-hand page number
 % unchanged, so that both facing pages hold the same page
 % number.\footnote{For setting headers and footers in this arrangement
-% of text, see \vpageref{sec:header-paired-pages}.}\\
+% of text, but also for the current limitations attached to this
+% option, see \vpageref{sec:header-paired-pages}.}\\
 % \DescribeOption{lineation} |lineation|$=$\verb+page|document+
 % \hfill\tcboxverb{Default: document}\\
 % This option applies to edition texts initially set to receive an
@@ -5951,6 +5954,99 @@ subtype="arabtex">'inna 'abI kAna mina
 %</example>
 % \fi
 %
+% \paragraph{\enquote{Mirrored} paired facing pages}
+% \newfeature[v1.5] The \textooquote|paired|\textcoquote\ option just
+% described can give surprising results at first sight, in which
+% facing pages are arranged by succeeding pairs of left- or right-hand
+% pages. This is certainly not the desired layout for duplex
+% printing. However, this is not a redhibitory inconvenience for
+% professional printers can easily carry out the necessary corrections
+% by applying offsets to the horizontal margins. That being said, one
+% may also wish to have these horizontal offsets applied from the
+% outset in the PDF output that is produced by \LaTeX.
+%
+% \danger What follows assumes that the critical edition is printed on
+% facing pages and starts on a left-hand page. Furthermore, it must be
+% noted that the |paired| option must be either unset or set to
+% |false|.
+%
+% \DescribeMacro{\setpairedpage} \cs{setpairedpage} is provided to set
+% mirrored paired facing pages. This command takes no argument and is
+% meant to be issued in commands used to set headers and footers on
+% both sides, \emph{before} \cs{thepage} is called, like so:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false,highlightlines={4,9}]{latex}
+% Preamble:
+\usepackage{titleps}
+\newpagestyle{edition}{
+  \sethead[\setpairedpage\ekdprintmark{HEL}{\thepage}]
+          [\ekdprintmark{HEC}{Hippocratis}]
+          []
+          {}
+          {\ekdprintmark{HOC}{Epidemiarum liber II, \ekdmark}}
+          {\setpairedpage\ekdprintmark{HOR}{\thepage}}
+}
+% Apply the page style:
+\pagestyle{edition}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \begin{remarks}
+% \item As can be seen, \cs{setpairedpage} must be issued
+%   \emph{before} \cs{ekdprintmark} so that it can be processed on
+%   pages where headers and footers are removed by \cs{ekdnohfmarks}
+%   described below.
+% \item If there be no \cs{thepage} in headers or footers,
+%   \cs{setpairedpage} must still be issued once on each side.
+% \end{remarks}
+%
+% \DescribeMacro{\setpairedpagenum} \cs{setpairedpagenum}\marg{number}
+% can be used just ahead of the alignment environment to set the
+% number of the first left-hand paired page to follow. The first
+% paired page number is initially set to |1|.
+%
+% \DescribeMacro{\resetpagenumber} Finally, \cs{resetpagenumber}
+% \emph{must} be used right out of the alignment environment so that
+% any numbering error on the page that follows the edition text can be
+% corrected. See below \vref{lst:mirrored-fp},
+% l.~\lnref{ln:mirrored:fp:resetpn}.
+%
+% A schematic illustration of this technique follows:---
+%
+% \captof{\enquote{Mirrored} paired facing
+% pages}[\label{lst:mirrored-fp}]
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[escapeinside=++,highlightlines={16}]{latex}
+\mainmatter
+\part{Edition text}
+\cleartoevenpage     % this needs the 'nextpage' package.
+\pagestyle{edition}  % apply the style where 'mirrored' paired facing
+                     % pages are defined as illustrated above.
+\begin{alignment}
+  \begin{edition}
+    ...
+  \end{edition}
+  \begin{translation}
+    ...
+  \end{translation}
+\end{alignment}
+\backmatter          % or \cleartooddpage provided by the 'nextpage'
+                     % package.
+\resetpagenumber     % this command is always required.+\label{ln:mirrored:fp:resetpn}+
+\pagestyle{back}     % apply a new page style.
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{Removing or Resetting Headers and Footers}
 % \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
@@ -8110,7 +8206,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \paragraph{\textsf{ekdosis} Symbol}
 % \begin{macro}{\eKd}
-% \changes{v1.5}{2022/04/20}{Prints \textsf{ekdosis} indentifying
+% \changes{v1.5}{2022/04/28}{Prints \textsf{ekdosis} indentifying
 % symbol} As of v1.5, \pkg{ekdosis} has its own identifying
 % symbol. It is produced by \cs{eKd} and best printed with the Old
 % Standard Greek font.
@@ -8371,7 +8467,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \begin{macro}{\teidirectE}
 % \changes{v1.3}{2021/08/18}{direct insertion of elements in the
 % \texttt{TEI xml} file}
-% \changes{v1.5}{2022/04/20}{direct insertion of empty elements in the
+% \changes{v1.5}{2022/04/28}{direct insertion of empty elements in the
 % \texttt{TEI xml} file}
 % \cs{teidirect}\oarg{xml attributes}\marg{xml element}\marg{code}
 % does nothing in \LaTeX. It is only used to insert elements in the
@@ -8386,7 +8482,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\getTEIxmlid}
-% \changes{v1.5}{2022/04/20}{returns \texttt{TEI xml:ids} from a
+% \changes{v1.5}{2022/04/28}{returns \texttt{TEI xml:ids} from a
 % csv-list of ids} This command returns from a csv-list of unique
 % identifiers declared in commands such as \cs{DeclareWitness} and the
 % like a space-separated list of their corresponding |xml:id|s, each
@@ -8621,7 +8717,7 @@ Sample text with a \textcolor{red}{word} in red.
 }
 \protected\def\LRnum#1{\bgroup\textdir TLT#1\egroup}
 %    \end{macrocode}
-% Set counter referring to line numbers and make it global. 
+% Set a counter referring to line numbers and make it global. 
 %    \begin{macrocode}
 \newcounter{ekd@lab}
 \globalcounter{ekd@lab}
@@ -9962,7 +10058,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \paragraph{Lacunae}
 % \begin{macro}{\ilabel}
-% \changes{v1.5}{2022/04/20}{recalls and sets the ending label of
+% \changes{v1.5}{2022/04/28}{recalls and sets the ending label of
 % lemmas used to mark lacunae in witnesses} When \cs{lem} has been
 % used with the optional argument |ilabel=<label>|,
 % \cs{ilabel}\marg{label} must be used to mark the point where the
@@ -10277,7 +10373,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\ekdEOprint}
-% \changes{v1.5}{2022/04/20}{Sets headers and footers on
+% \changes{v1.5}{2022/04/28}{Sets headers and footers on
 % \enquote{paired} facing pages}
 % To set headers and footers on \enquote{paired} facing pages,
 % \cs{ekdEOprint} accepts two mandatory, self-evident arguments, like
@@ -10312,6 +10408,51 @@ Sample text with a \textcolor{red}{word} in red.
 }
 %    \end{macrocode}
 % \end{macro}
+% \paragraph{\enquote{Mirrored} paired pages}
+% An easy way to have mirrored paired pages is to use a dedicaded
+% counter to set the value of the page numbers. This counter should be
+% incremented every two pages.
+% \begin{counter}{pairedpage}
+% \changes{v1.5}{2022/04/28}{A counter incremented every two pages}
+% |pairedpage| is first set as a global counter:---
+%    \begin{macrocode}
+\newcounter{pairedpage}
+\globalcounter{pairedpage}
+%    \end{macrocode}
+% \end{counter}
+% \begin{macro}{\setpairedpagenum}
+%   \changes{v1.5}{2022/04/28}{sets the same page number on paired
+%   pages} \cs{setpairedpagenum}\marg{number} is used just ahead of
+%   the alignment environment to set the number of the first left-hand
+%   paired page.
+% \begin{macro}{\setpairedpage}
+%   \changes{v1.5}{2022/04/28}{sets the page number of the first paired
+%   page} \cs{setpairedpage} is an argument-less command meant to be
+%   issued in commands used to set headers or footers before
+%   \cs{thepage}. This command has the counter |pairedpage|
+%   incremented on right-hand pages only, and sets |page| $\leftarrow$
+%   |pairedpage| on every page.
+% \begin{macro}{\resetpagenumber}
+%   \changes{v1.5}{2022/04/28}{resets normal running page numbers}
+%   \cs{resetpagenumber} must be used right out of \enquote{mirrored}
+%   paired pages alignment environments. This argument-less command
+%   corrects any numbering error on the page following the edition
+%   text and resumes normal page numbering.
+%    \begin{macrocode}
+\NewDocumentCommand{\setpairedpagenum}{m}{%
+  \setcounter{pairedpage}{\number\numexpr#1-1}%
+}
+\NewDocumentCommand{\setpairedpage}{}{%
+  \ifnumodd{\thepage}{\setcounter{page}{\thepairedpage}}
+  {\refstepcounter{pairedpage}\setcounter{page}{\thepairedpage}}%
+}
+\def\resetpagenumber{%
+  \ifnumodd{\thepairedpage}{}{\addtocounter{page}{-1}}
+}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \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}
diff --git a/ekdosis.el b/ekdosis.el
index f2fa1e7..3bd1ade 100644
--- a/ekdosis.el
+++ b/ekdosis.el
@@ -390,7 +390,10 @@
                       "HL" "HC" "HR" "FL" "FC" "FR"))
       "signpost" 0 )
     '("ekdEOprint" "even page" "odd page" 0)
-    '("ekdnohfmark" 0)
+    '("setpairedpagenum" "page number" 0)
+    '("setpairedpage" 0)
+    '("resetpagenumber" 0)
+    '("ekdnohfmarks" 0)
     '("ekdresethfmarks" 0)
     '("ekdpb" [ "page number" ] "line number" 0)
     '("ekdpb*")