From 34a5e851cadb113c3a9baaf341033f30083555d5 Mon Sep 17 00:00:00 2001
From: Robert Alessi <alessi@robertalessi.net>
Date: Thu, 10 Jun 2021 21:49:54 +0200
Subject: wrote documentation about \ekdsetup

---
 ekdosis.dtx | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 61 insertions(+), 3 deletions(-)

diff --git a/ekdosis.dtx b/ekdosis.dtx
index faf4d04..48d8551 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -1208,6 +1208,53 @@ along with this program.  If not, see
 %</example>
 % \fi
 %
+% \subsection{Setup}
+% \label{sec:setup}
+% \DescribeMacro{\ekdsetup} \newfeature[v1.3] Starting from v1.3,
+% \cs{ekdsetup} can be used to specify options that affect the general
+% behavior of \pkg{ekdosis}. \cs{ekdsetup} is a preamble-only
+% command. It accepts the following |key=value| options the number of
+% which is expected to increase as \pkg{ekdosis} grows:\\
+% \DescribeOption{showpagebreaks}\phts\label{ref:showpagebreaks-opt}
+% \unskip|showpagebreaks|$=$\verb+true|false+
+% \hfill \tcboxverb{Initially: false; Default: true}\\
+% This named argument, which defaults to |true| if used without value,
+% has specific marks printed in the margins so as to spot with a rapid
+% cast of the eye the locations of conditional page breaks generated
+% by the \cs{ekdpb} command described below \vpageref{ref:ekdpb}. By
+% default, page breaks generated by \cs{ekdpb} are identified by the
+% string |spb|\===for \enquote{soft} page break\=== whereas those
+% generated by \cs{ekdpb*} are identified by |hpb|\===for
+% \enquote{hard} page break. Furthermore, when \cs{ekdpb} triggers no
+% page break, the marker is printed between square brackets, like so:
+% |[spb]|. In this
+% way, inoperative \cs{ekdpb} can be easily spotted and removed.\\
+% \DescribeOption{spbmk} |spbmk|$=$\meta{string}
+% \hfill\tcboxverb{Default: spb}\\
+% |spbmk| is used to change the string associated to \enquote{soft}
+% page breaks.\\
+% \DescribeOption{hpbmk} |hpbmk|$=$\meta{string}
+% \hfill\tcboxverb{Default: hpb}\\
+% |hpbmk| is used to change the string associated to \enquote{hard}
+% page breaks.
+%
+% As an example, what follows has \enquote{soft} page breaks printed
+% in blue and \enquote{hard} page breaks printed in red:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\ekdsetup{
+  showpagebreaks,
+  spbmk = \textcolor{blue}{spb},
+  hpbmk = \textcolor{red}{hpb}
+}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
 % \subsection{Using a Configuration File}
 % \label{sec:using-conf-file}
 % Complex editions may use a large number of witnesses, sources and
@@ -5280,7 +5327,7 @@ subtype="arabtex">'inna 'abI kAna mina
 % pages may result in pages that break just after they begin.
 %
 % \paragraph{Conditional page breaks}
-% \DescribeMacro{\ekdpb}\DescribeMacro{\ekdpb*}
+% \phts\label{ref:ekdpb} \DescribeMacro{\ekdpb}\DescribeMacro{\ekdpb*}
 % \cs{ekdpb}\oarg{page no}\marg{line no}
 % \newfeature[v1.2]\\
 % One way to avoid this inconvenience is to use \cs{ekdpb} instead of
@@ -5293,7 +5340,15 @@ subtype="arabtex">'inna 'abI kAna mina
 % Roman or alphanumeric number. If the specified conditions be not
 % met, then the page break is not triggered.  Finally, the
 % \enquote{starred} version of this command forces the page break,
-% irrespective of the values specified as page or line numbers.
+% irrespective of the values specified as page or line numbers. Unlike
+% \cs{ekdpb}, which requires the lines to be numbered, \cs{ekdpb*} is
+% allowed at any point of the document: as \cs{ekdpb*} disregards the
+% number given as argument, it is equivalent to the standard \LaTeX\
+% \cs{pagebreak} command. Yet it can be used instead of the latter to
+% have marks further printed in the margins so as to spot with a
+% fleeting glance the locations where induced page breaks
+% occur.\footnote{This requires the |showpagebreaks| option to be set
+% to |true| as described above \vpageref{ref:showpagebreaks-opt}.}
 %
 % \paragraph{Using \texttt{maxentries}}
 % Another way\---should the edition text fall into the vicious circle
@@ -7295,8 +7350,11 @@ Sample text with a \textcolor{red}{word} in red.
   \luadirect{ekdosis.closestream()}
 }
 %    \end{macrocode}
+% \paragraph{Setup}
 % \begin{macro}{\ekdsetup}
 % \changes{v1.3}{2021/06/08}{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}
 \ekvdefinekeys{ekd@setup}{
   bool showpagebreaks = \ifekd@showpb,
@@ -7696,7 +7754,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \cs{ekdpk}\oarg{page no}\marg{line no} is used to insert conditional
 % page breaks by specifying that the page break should occur only on a
 % given line and optionally a given page. If the specified conditions
-% are met then this command triggers \cs{pagebreak}.
+% be met then this command triggers \cs{pagebreak}.
 %    \begin{macrocode}
 \newcounter{ekd@pb}
 \globalcounter{ekd@pb}
-- 
cgit v1.2.3