From 78211b6125b3253a6949d5ec37d6968ccef212a1 Mon Sep 17 00:00:00 2001 From: Robert Alessi Date: Sun, 28 Aug 2022 18:30:52 +0200 Subject: yet improved documentation on code folding --- Makefile | 3 +- ekdosis.dtx | 208 ++++++++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 140 insertions(+), 71 deletions(-) diff --git a/Makefile b/Makefile index a7e1910..5046e12 100644 --- a/Makefile +++ b/Makefile @@ -64,10 +64,11 @@ pandoc: pandoc README.md -o about.html auctex: + emacs --batch -f batch-byte-compile ekdosis.el &>/dev/null if [ ! -d "$(HOMEDIR)/.emacs.d/auctex/auto" ]; then \ mkdir -p $(HOMEDIR)/.emacs.d/auctex/auto; \ fi - cp $(NAME)*.el $(HOMEDIR)/.emacs.d/auctex/auto + cp $(NAME)*.{el,elc} $(HOMEDIR)/.emacs.d/auctex/auto distclean: clean uninst 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 %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\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] % %<*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 } % \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 -% -% \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 -% -% \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 +% +% \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 +% +% \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 +% +% \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=