improved documentation on \App

1 files changed, 40 insertions, 23 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index db99e5c..fa5f338 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/26 v1.5-dev Typesetting TEI xml-compliant critical editions]
+    [2022/08/27 v1.5-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -1929,10 +1929,20 @@ yesterday.
 % option}. For more information about inserting notes in
 % multiple-layer apparatus, see \vref{sec:notes-in-multilayer-app}.
 %
-% \paragraph{Alternate Command}
+% \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:---
@@ -1940,23 +1950,29 @@ yesterday.
 % \iffalse
 %<*example>
 % \fi
-\begin{minted}[linenos=false]{latex}
+\begin{minted}[escapeinside=++]{latex}
 I saw my friend \App{\lem{Peter}}{\rdg{John}} yesterday.
 or:
-I saw my friend \App{\lem{Peter}}{
+I saw my friend \App{\lem{Peter}}{+\label{ln:App:1}+
     \rdg{John}
-  } yesterday.
+  } yesterday.+\label{ln:App:2}+
 \end{minted}
 % \iffalse
 %</example>
 % \fi
 %
-% Used in the \textsf{emacs} editor conjointly with the AUC\TeX\ style
-% file that is provided by \pkg{ekdosis}, this command allows for much
-% more flexible code folding where notes and variants are hidden to
-% let only the base text appear on the screen.  Code folding, once
-% applied, results in a clean source text with no clutter as
-% follows:---
+% \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>
@@ -1968,8 +1984,9 @@ I saw my friend +\textcolor{lavender}{Peter}+ yesterday.
 %</example>
 % \fi
 % 
-% \danger There is no point in using this command for anything other
-% than this specific purpose.
+% \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
@@ -8314,7 +8331,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \paragraph{\textsf{ekdosis} Symbol}
 % \begin{macro}{\eKd}
-% \changes{v1.5}{2022/08/26}{Prints \textsf{ekdosis} indentifying
+% \changes{v1.5}{2022/08/27}{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.
@@ -8577,7 +8594,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/26}{direct insertion of empty elements in the
+% \changes{v1.5}{2022/08/27}{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
@@ -8592,7 +8609,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\getTEIxmlid}
-% \changes{v1.5}{2022/08/26}{returns \texttt{TEI xml:ids} from a
+% \changes{v1.5}{2022/08/27}{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
@@ -9340,7 +9357,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\App}
-% \changes{v1.5}{2022/08/26}{To be used conjointly with
+% \changes{v1.5}{2022/08/27}{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:
@@ -10213,7 +10230,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \paragraph{Lacunae}
 % \begin{macro}{\ilabel}
-% \changes{v1.5}{2022/08/26}{recalls and sets the ending label of
+% \changes{v1.5}{2022/08/27}{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
@@ -10529,7 +10546,7 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{macro}
 % \begin{macro}{\ekdEOprint}
-% \changes{v1.5}{2022/08/26}{Sets headers and footers on
+% \changes{v1.5}{2022/08/27}{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
@@ -10569,7 +10586,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/26}{A counter incremented every two pages}
+% \changes{v1.5}{2022/08/27}{A counter incremented every two pages}
 % |pairedpage| is first set as a global counter:---
 %    \begin{macrocode}
 \newcounter{pairedpage}
@@ -10577,19 +10594,19 @@ Sample text with a \textcolor{red}{word} in red.
 %    \end{macrocode}
 % \end{counter}
 % \begin{macro}{\setpairedpagenum}
-%   \changes{v1.5}{2022/08/26}{sets the same page number on paired
+%   \changes{v1.5}{2022/08/27}{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/26}{sets the page number of the first paired
+%   \changes{v1.5}{2022/08/27}{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/26}{resets normal running page numbers}
+%   \changes{v1.5}{2022/08/27}{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