yet improved documentation on code folding

1 files changed, 138 insertions, 70 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 53fe906..c8e5080 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/08/27 v1.5-dev Typesetting TEI xml-compliant critical editions]
+    [2022/08/28 v1.5-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -643,6 +643,7 @@ along with this program.  If not, see
 \newcommand\phts{\phantomsection}
 \usepackage{chifoot}
 \usepackage{savefnmark}
+\usepackage{menukeys}
 \usepackage{nameref}
 \usepackage{arabluatex}
 \usepackage[parnotes=roman, teiexport=tidy, poetry=verse]{ekdosis}
@@ -1009,7 +1010,8 @@ along with this program.  If not, see
 % \item email:
 % \mailto[ekdosis package]{Robert Alessi <alessi@robertalessi.net>}
 % \item website: \url{http://www.ekdosis.org}
-% \item development: \url{http://git.robertalessi.net/ekdosis}
+% \item development: \url{http://git.robertalessi.net/ekdosis} or\\
+%   \phantom{development:} \url{https://sr.ht/~ralessi/ekdosis}
 % \item comments, feature requests, bug reports:
 % \url{http://www.ekdosis.org/issues}
 % \end{itemize}
@@ -1929,65 +1931,14 @@ yesterday.
 % option}. For more information about inserting notes in
 % multiple-layer apparatus, see \vref{sec:notes-in-multilayer-app}.
 %
-% \paragraph{Code Folding}
-% The variant readings and the critical notes can grow in number to a
-% point where they may clutter the source text. As a result, the
-% edition text can become illegible. One way around this difficulty is
-% to use the \textsf{emacs} editor with |ekdosis.el|, the AUC\TeX\
-% style file that is provided with \pkg{ekdosis}, to fold the code so
-% that only the edition text, exclusive of variants and notes, is
-% displayed on the screen.
-% 
-% \DescribeMacro{\App}
-% \newfeature[v1.5]\cs{App}|[type=|\meta{type}|]|\marg{lemma
-% text}\marg{readings and notes}\phts\label{ref:App-cmd}\\
-% \cs{App} allows for much more flexible code folding where notes and
-% variants are hidden to let only the base text appear on the screen.
-% \cs{App} is strictly equivalent to \cs{app}, except that the
-% apparatus entries are meant to be distributed in two different
-% arguments, like so:---
-% 
-% \iffalse
-%<*example>
-% \fi
-\begin{minted}[escapeinside=++]{latex}
-I saw my friend \App{\lem{Peter}}{\rdg{John}} yesterday.
-or:
-I saw my friend \App{\lem{Peter}}{+\label{ln:App:1}+
-    \rdg{John}
-  } yesterday.+\label{ln:App:2}+
-\end{minted}
-% \iffalse
-%</example>
-% \fi
+% \mansee \pkg{ekdosis} also provides a two-argument \cs{App} command
+% which is strictly equivalent to \cs{app} but allows for much more
+% flexible code folding in the \textsf{emacs} text editor. Code
+% folding may be needed when readings and critical notes grow in
+% number to a point where the edition text becomes illegible. This
+% command is described below in \vnref{sec:using-emacs}. (See
+% \vpageref{ref:App-cmd}.)
 %
-% \begin{remarks}
-% \item As can be seen, the first argument of \cs{App} is meant to
-%   receive the lemma text while \cs{rdg}, \cs{note} and the like are
-%   inserted in the second one.
-% \item As the second argument of \cs{App} is the foldable item, a
-%   good practice is to keep the lemma text on the same line as the
-%   opening brace (l.~\lnref{ln:App:1}) and to write the continuation
-%   of the text just after the closing brace (l.~\lnref{ln:App:2}).
-% \end{remarks}
-% 
-% Code folding, once applied, results in a clean source text with no
-% clutter as follows:---
-% 
-% \iffalse
-%<*example>
-% \fi
-\begin{minted}[escapeinside=++]{latex}
-I saw my friend +\textcolor{lavender}{Peter}+ yesterday.
-\end{minted}
-% \iffalse
-%</example>
-% \fi
-% 
-% \danger As there is no point in using this command for anything
-% other than this specific purpose, \cs{app} is used in the examples
-% throughout this document.
-% 
 % \paragraph{Base text and variants} As can be seen in \vref{lst:pj1}
 % and the examples provided above, there are two kinds of individual
 % readings: the \emph{lemma}, which contains the base text accepted by
@@ -6298,6 +6249,123 @@ subtype="arabtex">'inna 'abI kAna mina
 % the number of allowed entries from being too high, which would
 % result in the characters being too small or even illegible.
 %
+% \subsection{Using \textsf{emacs}}
+% \label{sec:using-emacs}
+% \pkg{ekdosis} includes an AUC\TeX\ style file that can be used to
+% facilitate the insertion of the many commands it provides.
+%
+% \paragraph{Installation}
+% In what follows, it is assumed that both the \textsf{emacs} text
+% editor\footnote{\url{https://www.gnu.org/software/emacs}} and
+% AUC\TeX%^^A
+% \footnote{\url{https://www.gnu.org/software/auctex/download.html}}
+% have already been installed.
+% \begin{description}
+% \item[\pkg{ekdosis} Stable]
+%   \begin{enumerate}
+%   \item Download |ekdosis.el| from
+%     CTAN:
+%     \url{https://ctan.org/tex-archive/macros/luatex/latex/ekdosis}
+%   \item Copy this file to
+%     |$HOME/.emacs.d/auctex/auto/|\footnote{This directory must be
+%     created if need be.}\saveFN\fnAUCTeX\ where |$HOME| stands
+%     for the directory of the current user.
+%   \end{enumerate}
+% \item[\pkg{ekdosis} Development Version]
+%   \begin{enumerate}
+%   \item Download |ekdosis.el| from either
+%     |git.robertaless|\allowbreak|i.net|
+%     (\url{http://git.robertalessi.net/ekdosis/plain/ekdosis.el})
+%     or the |sourcehut| git
+%     repository
+%     (\url{https://git.sr.ht/~ralessi/ekdosis/blob/master/ekdosis.el}).
+%   \item Copy this file to
+%     |$HOME/.emacs.d/auctex/auto/|\useFN\fnAUCTeX\ where |$HOME|
+%     stands for the directory of the current user.
+%   \end{enumerate}
+% \end{description}
+%
+% If desired, |ekdosis.el| can be compiled like so:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{bash}
+emacs --batch -f batch-byte-compile ekdosis.el &>/dev/null
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% This will produce |ekdosis.elc| which can be copied to the same
+% directory as |ekdosis.el|.
+%
+% \paragraph{Code Folding}
+% \phts\label{ref:code-folding}
+% The variant readings and the critical notes can grow in number to a
+% point where they may clutter the source text. As a result, the
+% edition text can become illegible. One way around this difficulty is
+% to use the \textsf{emacs} editor with |ekdosis.el|, the AUC\TeX\
+% style file that is provided with \pkg{ekdosis}, to fold the code so
+% that only the edition text, exclusive of variants and notes, is
+% displayed on the screen.
+%
+% In order to hide all foldable items, |TeX-fold-mode| must first be
+% activated, like so: |C-c| |C-o| |C-f|.\footnote{Menu sequence:
+% \menu{LaTeX>Show/Hide>Fold Mode}} Then |C-c| |C-f| |C-b| can be used
+% to fold the code.\footnote{Menu sequence: \menu{LaTeX>Show/Hide>Hide
+% All in Current Buffer}}
+%
+% \DescribeMacro{\App}
+% \newfeature[v1.5]\cs{App}|[type=|\meta{type}|]|\marg{lemma
+% text}\marg{readings and notes}\phts\label{ref:App-cmd}\\
+% \cs{App} allows for much more flexible code folding where notes and
+% variants are hidden to let only the base text appear on the screen.
+% \cs{App} is strictly equivalent to \cs{app}, except that the
+% apparatus entries are meant to be distributed in two different
+% arguments, like so:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[escapeinside=++]{latex}
+I saw my friend \App{\lem{Peter}}{\rdg{John}} yesterday.
+or:
+I saw my friend \App{\lem{Peter}}{+\label{ln:App:1}+
+    \rdg{John}
+  } yesterday.+\label{ln:App:2}+
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \begin{remarks}
+% \item As can be seen, the first argument of \cs{App} is meant to
+%   receive the lemma text while \cs{rdg}, \cs{note} and the like are
+%   inserted in the second one.
+% \item As the second argument of \cs{App} is the foldable item, a
+%   good practice is to keep the lemma text on the same line as the
+%   opening brace (l.~\lnref{ln:App:1}) and to write the continuation
+%   of the text just after the closing brace (l.~\lnref{ln:App:2}).
+% \end{remarks}
+% 
+% Code folding, once applied, results in a clean source text with no
+% clutter as follows:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[escapeinside=++]{latex}
+I saw my friend +\textcolor{lavender}{Peter}+ yesterday.
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+% 
+% \danger As there is no point in using this command for anything
+% other than this specific purpose, \cs{app} is used in the examples
+% throughout this document.
+% 
 % \subsection{Variae Quaestiones}
 % \label{sec:variae-quaestiones}
 % This section is about issues that are not strictly speaking part of
@@ -8331,7 +8399,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \paragraph{\textsf{ekdosis} Symbol}
 % \begin{macro}{\eKd}
-% \changes{v1.5}{2022/08/27}{Prints \textsf{ekdosis} indentifying
+% \changes{v1.5}{2022/08/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.
@@ -8594,7 +8662,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/08/27}{direct insertion of empty elements in the
+% \changes{v1.5}{2022/08/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
@@ -8609,7 +8677,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\getTEIxmlid}
-% \changes{v1.5}{2022/08/27}{returns \texttt{TEI xml:ids} from a
+% \changes{v1.5}{2022/08/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
@@ -9357,7 +9425,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\App}
-% \changes{v1.5}{2022/08/27}{To be used conjointly with
+% \changes{v1.5}{2022/08/28}{To be used conjointly with
 % \texttt{ekdosis.el}}
 % In contrast to \cs{app}, \cs{App} takes two mandatory arguments and
 % accepts one optional argument like so:
@@ -10230,7 +10298,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \paragraph{Lacunae}
 % \begin{macro}{\ilabel}
-% \changes{v1.5}{2022/08/27}{recalls and sets the ending label of
+% \changes{v1.5}{2022/08/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
@@ -10546,7 +10614,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\ekdEOprint}
-% \changes{v1.5}{2022/08/27}{Sets headers and footers on
+% \changes{v1.5}{2022/08/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
@@ -10586,7 +10654,7 @@ Sample text with a \textcolor{red}{word} in red.
 % counter to set the value of the page numbers. This counter should be
 % incremented every two pages.
 % \begin{counter}{pairedpage}
-% \changes{v1.5}{2022/08/27}{A counter incremented every two pages}
+% \changes{v1.5}{2022/08/28}{A counter incremented every two pages}
 % |pairedpage| is first set as a global counter:---
 %    \begin{macrocode}
 \newcounter{pairedpage}
@@ -10594,19 +10662,19 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{counter}
 % \begin{macro}{\setpairedpagenum}
-%   \changes{v1.5}{2022/08/27}{sets the same page number on paired
+%   \changes{v1.5}{2022/08/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/08/27}{sets the page number of the first paired
+%   \changes{v1.5}{2022/08/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/08/27}{resets normal running page numbers}
+%   \changes{v1.5}{2022/08/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