aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRobert Alessi <alessi@robertalessi.net>2022-08-28 18:30:52 +0200
committerRobert Alessi <alessi@robertalessi.net>2022-08-28 18:30:52 +0200
commit78211b6125b3253a6949d5ec37d6968ccef212a1 (patch)
treec814e4f6702989c09a4f1a86b62492cafd26d7e9
parent1a463923246448082df92fc543038aee5688f219 (diff)
downloadekdosis-78211b6125b3253a6949d5ec37d6968ccef212a1.tar.gz
yet improved documentation on code folding
-rw-r--r--Makefile3
-rw-r--r--ekdosis.dtx208
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:
64 pandoc README.md -o about.html 64 pandoc README.md -o about.html
65 65
66auctex: 66auctex:
67 emacs --batch -f batch-byte-compile ekdosis.el &>/dev/null
67 if [ ! -d "$(HOMEDIR)/.emacs.d/auctex/auto" ]; then \ 68 if [ ! -d "$(HOMEDIR)/.emacs.d/auctex/auto" ]; then \
68 mkdir -p $(HOMEDIR)/.emacs.d/auctex/auto; \ 69 mkdir -p $(HOMEDIR)/.emacs.d/auctex/auto; \
69 fi 70 fi
70 cp $(NAME)*.el $(HOMEDIR)/.emacs.d/auctex/auto 71 cp $(NAME)*.{el,elc} $(HOMEDIR)/.emacs.d/auctex/auto
71 72
72distclean: clean uninst 73distclean: clean uninst
73 74
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
61%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01] 61%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
62%<package>\ProvidesPackage{ekdosis} 62%<package>\ProvidesPackage{ekdosis}
63%<*package> 63%<*package>
64 [2022/08/27 v1.5-dev Typesetting TEI xml-compliant critical editions] 64 [2022/08/28 v1.5-dev Typesetting TEI xml-compliant critical editions]
65%</package> 65%</package>
66%<*driver> 66%<*driver>
67\begin{filecontents}[noheader,overwrite]{bibdata.xml} 67\begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -643,6 +643,7 @@ along with this program. If not, see
643\newcommand\phts{\phantomsection} 643\newcommand\phts{\phantomsection}
644\usepackage{chifoot} 644\usepackage{chifoot}
645\usepackage{savefnmark} 645\usepackage{savefnmark}
646\usepackage{menukeys}
646\usepackage{nameref} 647\usepackage{nameref}
647\usepackage{arabluatex} 648\usepackage{arabluatex}
648\usepackage[parnotes=roman, teiexport=tidy, poetry=verse]{ekdosis} 649\usepackage[parnotes=roman, teiexport=tidy, poetry=verse]{ekdosis}
@@ -1009,7 +1010,8 @@ along with this program. If not, see
1009% \item email: 1010% \item email:
1010% \mailto[ekdosis package]{Robert Alessi <alessi@robertalessi.net>} 1011% \mailto[ekdosis package]{Robert Alessi <alessi@robertalessi.net>}
1011% \item website: \url{http://www.ekdosis.org} 1012% \item website: \url{http://www.ekdosis.org}
1012% \item development: \url{http://git.robertalessi.net/ekdosis} 1013% \item development: \url{http://git.robertalessi.net/ekdosis} or\\
1014% \phantom{development:} \url{https://sr.ht/~ralessi/ekdosis}
1013% \item comments, feature requests, bug reports: 1015% \item comments, feature requests, bug reports:
1014% \url{http://www.ekdosis.org/issues} 1016% \url{http://www.ekdosis.org/issues}
1015% \end{itemize} 1017% \end{itemize}
@@ -1929,65 +1931,14 @@ yesterday.
1929% option}. For more information about inserting notes in 1931% option}. For more information about inserting notes in
1930% multiple-layer apparatus, see \vref{sec:notes-in-multilayer-app}. 1932% multiple-layer apparatus, see \vref{sec:notes-in-multilayer-app}.
1931% 1933%
1932% \paragraph{Code Folding} 1934% \mansee \pkg{ekdosis} also provides a two-argument \cs{App} command
1933% The variant readings and the critical notes can grow in number to a 1935% which is strictly equivalent to \cs{app} but allows for much more
1934% point where they may clutter the source text. As a result, the 1936% flexible code folding in the \textsf{emacs} text editor. Code
1935% edition text can become illegible. One way around this difficulty is 1937% folding may be needed when readings and critical notes grow in
1936% to use the \textsf{emacs} editor with |ekdosis.el|, the AUC\TeX\ 1938% number to a point where the edition text becomes illegible. This
1937% style file that is provided with \pkg{ekdosis}, to fold the code so 1939% command is described below in \vnref{sec:using-emacs}. (See
1938% that only the edition text, exclusive of variants and notes, is 1940% \vpageref{ref:App-cmd}.)
1939% displayed on the screen.
1940%
1941% \DescribeMacro{\App}
1942% \newfeature[v1.5]\cs{App}|[type=|\meta{type}|]|\marg{lemma
1943% text}\marg{readings and notes}\phts\label{ref:App-cmd}\\
1944% \cs{App} allows for much more flexible code folding where notes and
1945% variants are hidden to let only the base text appear on the screen.
1946% \cs{App} is strictly equivalent to \cs{app}, except that the
1947% apparatus entries are meant to be distributed in two different
1948% arguments, like so:---
1949%
1950% \iffalse
1951%<*example>
1952% \fi
1953\begin{minted}[escapeinside=++]{latex}
1954I saw my friend \App{\lem{Peter}}{\rdg{John}} yesterday.
1955or:
1956I saw my friend \App{\lem{Peter}}{+\label{ln:App:1}+
1957 \rdg{John}
1958 } yesterday.+\label{ln:App:2}+
1959\end{minted}
1960% \iffalse
1961%</example>
1962% \fi
1963% 1941%
1964% \begin{remarks}
1965% \item As can be seen, the first argument of \cs{App} is meant to
1966% receive the lemma text while \cs{rdg}, \cs{note} and the like are
1967% inserted in the second one.
1968% \item As the second argument of \cs{App} is the foldable item, a
1969% good practice is to keep the lemma text on the same line as the
1970% opening brace (l.~\lnref{ln:App:1}) and to write the continuation
1971% of the text just after the closing brace (l.~\lnref{ln:App:2}).
1972% \end{remarks}
1973%
1974% Code folding, once applied, results in a clean source text with no
1975% clutter as follows:---
1976%
1977% \iffalse
1978%<*example>
1979% \fi
1980\begin{minted}[escapeinside=++]{latex}
1981I saw my friend +\textcolor{lavender}{Peter}+ yesterday.
1982\end{minted}
1983% \iffalse
1984%</example>
1985% \fi
1986%
1987% \danger As there is no point in using this command for anything
1988% other than this specific purpose, \cs{app} is used in the examples
1989% throughout this document.
1990%
1991% \paragraph{Base text and variants} As can be seen in \vref{lst:pj1} 1942% \paragraph{Base text and variants} As can be seen in \vref{lst:pj1}
1992% and the examples provided above, there are two kinds of individual 1943% and the examples provided above, there are two kinds of individual
1993% readings: the \emph{lemma}, which contains the base text accepted by 1944% readings: the \emph{lemma}, which contains the base text accepted by
@@ -6298,6 +6249,123 @@ subtype="arabtex">'inna 'abI kAna mina
6298% the number of allowed entries from being too high, which would 6249% the number of allowed entries from being too high, which would
6299% result in the characters being too small or even illegible. 6250% result in the characters being too small or even illegible.
6300% 6251%
6252% \subsection{Using \textsf{emacs}}
6253% \label{sec:using-emacs}
6254% \pkg{ekdosis} includes an AUC\TeX\ style file that can be used to
6255% facilitate the insertion of the many commands it provides.
6256%
6257% \paragraph{Installation}
6258% In what follows, it is assumed that both the \textsf{emacs} text
6259% editor\footnote{\url{https://www.gnu.org/software/emacs}} and
6260% AUC\TeX%^^A
6261% \footnote{\url{https://www.gnu.org/software/auctex/download.html}}
6262% have already been installed.
6263% \begin{description}
6264% \item[\pkg{ekdosis} Stable]
6265% \begin{enumerate}
6266% \item Download |ekdosis.el| from
6267% CTAN:
6268% \url{https://ctan.org/tex-archive/macros/luatex/latex/ekdosis}
6269% \item Copy this file to
6270% |$HOME/.emacs.d/auctex/auto/|\footnote{This directory must be
6271% created if need be.}\saveFN\fnAUCTeX\ where |$HOME| stands
6272% for the directory of the current user.
6273% \end{enumerate}
6274% \item[\pkg{ekdosis} Development Version]
6275% \begin{enumerate}
6276% \item Download |ekdosis.el| from either
6277% |git.robertaless|\allowbreak|i.net|
6278% (\url{http://git.robertalessi.net/ekdosis/plain/ekdosis.el})
6279% or the |sourcehut| git
6280% repository
6281% (\url{https://git.sr.ht/~ralessi/ekdosis/blob/master/ekdosis.el}).
6282% \item Copy this file to
6283% |$HOME/.emacs.d/auctex/auto/|\useFN\fnAUCTeX\ where |$HOME|
6284% stands for the directory of the current user.
6285% \end{enumerate}
6286% \end{description}
6287%
6288% If desired, |ekdosis.el| can be compiled like so:---
6289%
6290% \iffalse
6291%<*example>
6292% \fi
6293\begin{minted}[linenos=false]{bash}
6294emacs --batch -f batch-byte-compile ekdosis.el &>/dev/null
6295\end{minted}
6296% \iffalse
6297%</example>
6298% \fi
6299%
6300% This will produce |ekdosis.elc| which can be copied to the same
6301% directory as |ekdosis.el|.
6302%
6303% \paragraph{Code Folding}
6304% \phts\label{ref:code-folding}
6305% The variant readings and the critical notes can grow in number to a
6306% point where they may clutter the source text. As a result, the
6307% edition text can become illegible. One way around this difficulty is
6308% to use the \textsf{emacs} editor with |ekdosis.el|, the AUC\TeX\
6309% style file that is provided with \pkg{ekdosis}, to fold the code so
6310% that only the edition text, exclusive of variants and notes, is
6311% displayed on the screen.
6312%
6313% In order to hide all foldable items, |TeX-fold-mode| must first be
6314% activated, like so: |C-c| |C-o| |C-f|.\footnote{Menu sequence:
6315% \menu{LaTeX>Show/Hide>Fold Mode}} Then |C-c| |C-f| |C-b| can be used
6316% to fold the code.\footnote{Menu sequence: \menu{LaTeX>Show/Hide>Hide
6317% All in Current Buffer}}
6318%
6319% \DescribeMacro{\App}
6320% \newfeature[v1.5]\cs{App}|[type=|\meta{type}|]|\marg{lemma
6321% text}\marg{readings and notes}\phts\label{ref:App-cmd}\\
6322% \cs{App} allows for much more flexible code folding where notes and
6323% variants are hidden to let only the base text appear on the screen.
6324% \cs{App} is strictly equivalent to \cs{app}, except that the
6325% apparatus entries are meant to be distributed in two different
6326% arguments, like so:---
6327%
6328% \iffalse
6329%<*example>
6330% \fi
6331\begin{minted}[escapeinside=++]{latex}
6332I saw my friend \App{\lem{Peter}}{\rdg{John}} yesterday.
6333or:
6334I saw my friend \App{\lem{Peter}}{+\label{ln:App:1}+
6335 \rdg{John}
6336 } yesterday.+\label{ln:App:2}+
6337\end{minted}
6338% \iffalse
6339%</example>
6340% \fi
6341%
6342% \begin{remarks}
6343% \item As can be seen, the first argument of \cs{App} is meant to
6344% receive the lemma text while \cs{rdg}, \cs{note} and the like are
6345% inserted in the second one.
6346% \item As the second argument of \cs{App} is the foldable item, a
6347% good practice is to keep the lemma text on the same line as the
6348% opening brace (l.~\lnref{ln:App:1}) and to write the continuation
6349% of the text just after the closing brace (l.~\lnref{ln:App:2}).
6350% \end{remarks}
6351%
6352% Code folding, once applied, results in a clean source text with no
6353% clutter as follows:---
6354%
6355% \iffalse
6356%<*example>
6357% \fi
6358\begin{minted}[escapeinside=++]{latex}
6359I saw my friend +\textcolor{lavender}{Peter}+ yesterday.
6360\end{minted}
6361% \iffalse
6362%</example>
6363% \fi
6364%
6365% \danger As there is no point in using this command for anything
6366% other than this specific purpose, \cs{app} is used in the examples
6367% throughout this document.
6368%
6301% \subsection{Variae Quaestiones} 6369% \subsection{Variae Quaestiones}
6302% \label{sec:variae-quaestiones} 6370% \label{sec:variae-quaestiones}
6303% This section is about issues that are not strictly speaking part of 6371% 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.
8331% \end{macrocode} 8399% \end{macrocode}
8332% \paragraph{\textsf{ekdosis} Symbol} 8400% \paragraph{\textsf{ekdosis} Symbol}
8333% \begin{macro}{\eKd} 8401% \begin{macro}{\eKd}
8334% \changes{v1.5}{2022/08/27}{Prints \textsf{ekdosis} indentifying 8402% \changes{v1.5}{2022/08/28}{Prints \textsf{ekdosis} indentifying
8335% symbol} As of v1.5, \pkg{ekdosis} has its own identifying 8403% symbol} As of v1.5, \pkg{ekdosis} has its own identifying
8336% symbol. It is produced by \cs{eKd} and best printed with the Old 8404% symbol. It is produced by \cs{eKd} and best printed with the Old
8337% Standard Greek font. 8405% Standard Greek font.
@@ -8594,7 +8662,7 @@ Sample text with a \textcolor{red}{word} in red.
8594% \begin{macro}{\teidirectE} 8662% \begin{macro}{\teidirectE}
8595% \changes{v1.3}{2021/08/18}{direct insertion of elements in the 8663% \changes{v1.3}{2021/08/18}{direct insertion of elements in the
8596% \texttt{TEI xml} file} 8664% \texttt{TEI xml} file}
8597% \changes{v1.5}{2022/08/27}{direct insertion of empty elements in the 8665% \changes{v1.5}{2022/08/28}{direct insertion of empty elements in the
8598% \texttt{TEI xml} file} 8666% \texttt{TEI xml} file}
8599% \cs{teidirect}\oarg{xml attributes}\marg{xml element}\marg{code} 8667% \cs{teidirect}\oarg{xml attributes}\marg{xml element}\marg{code}
8600% does nothing in \LaTeX. It is only used to insert elements in the 8668% 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.
8609% \end{macro} 8677% \end{macro}
8610% \end{macro} 8678% \end{macro}
8611% \begin{macro}{\getTEIxmlid} 8679% \begin{macro}{\getTEIxmlid}
8612% \changes{v1.5}{2022/08/27}{returns \texttt{TEI xml:ids} from a 8680% \changes{v1.5}{2022/08/28}{returns \texttt{TEI xml:ids} from a
8613% csv-list of ids} This command returns from a csv-list of unique 8681% csv-list of ids} This command returns from a csv-list of unique
8614% identifiers declared in commands such as \cs{DeclareWitness} and the 8682% identifiers declared in commands such as \cs{DeclareWitness} and the
8615% like a space-separated list of their corresponding |xml:id|s, each 8683% 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.
9357% \end{macrocode} 9425% \end{macrocode}
9358% \end{macro} 9426% \end{macro}
9359% \begin{macro}{\App} 9427% \begin{macro}{\App}
9360% \changes{v1.5}{2022/08/27}{To be used conjointly with 9428% \changes{v1.5}{2022/08/28}{To be used conjointly with
9361% \texttt{ekdosis.el}} 9429% \texttt{ekdosis.el}}
9362% In contrast to \cs{app}, \cs{App} takes two mandatory arguments and 9430% In contrast to \cs{app}, \cs{App} takes two mandatory arguments and
9363% accepts one optional argument like so: 9431% accepts one optional argument like so:
@@ -10230,7 +10298,7 @@ Sample text with a \textcolor{red}{word} in red.
10230% \end{macro} 10298% \end{macro}
10231% \paragraph{Lacunae} 10299% \paragraph{Lacunae}
10232% \begin{macro}{\ilabel} 10300% \begin{macro}{\ilabel}
10233% \changes{v1.5}{2022/08/27}{recalls and sets the ending label of 10301% \changes{v1.5}{2022/08/28}{recalls and sets the ending label of
10234% lemmas used to mark lacunae in witnesses} When \cs{lem} has been 10302% lemmas used to mark lacunae in witnesses} When \cs{lem} has been
10235% used with the optional argument |ilabel=<label>|, 10303% used with the optional argument |ilabel=<label>|,
10236% \cs{ilabel}\marg{label} must be used to mark the point where the 10304% \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.
10546% \end{macrocode} 10614% \end{macrocode}
10547% \end{macro} 10615% \end{macro}
10548% \begin{macro}{\ekdEOprint} 10616% \begin{macro}{\ekdEOprint}
10549% \changes{v1.5}{2022/08/27}{Sets headers and footers on 10617% \changes{v1.5}{2022/08/28}{Sets headers and footers on
10550% \enquote{paired} facing pages} 10618% \enquote{paired} facing pages}
10551% To set headers and footers on \enquote{paired} facing pages, 10619% To set headers and footers on \enquote{paired} facing pages,
10552% \cs{ekdEOprint} accepts two mandatory, self-evident arguments, like 10620% \cs{ekdEOprint} accepts two mandatory, self-evident arguments, like
@@ -10586,7 +10654,7 @@ Sample text with a \textcolor{red}{word} in red.
10586% counter to set the value of the page numbers. This counter should be 10654% counter to set the value of the page numbers. This counter should be
10587% incremented every two pages. 10655% incremented every two pages.
10588% \begin{counter}{pairedpage} 10656% \begin{counter}{pairedpage}
10589% \changes{v1.5}{2022/08/27}{A counter incremented every two pages} 10657% \changes{v1.5}{2022/08/28}{A counter incremented every two pages}
10590% |pairedpage| is first set as a global counter:--- 10658% |pairedpage| is first set as a global counter:---
10591% \begin{macrocode} 10659% \begin{macrocode}
10592\newcounter{pairedpage} 10660\newcounter{pairedpage}
@@ -10594,19 +10662,19 @@ Sample text with a \textcolor{red}{word} in red.
10594% \end{macrocode} 10662% \end{macrocode}
10595% \end{counter} 10663% \end{counter}
10596% \begin{macro}{\setpairedpagenum} 10664% \begin{macro}{\setpairedpagenum}
10597% \changes{v1.5}{2022/08/27}{sets the same page number on paired 10665% \changes{v1.5}{2022/08/28}{sets the same page number on paired
10598% pages} \cs{setpairedpagenum}\marg{number} is used just ahead of 10666% pages} \cs{setpairedpagenum}\marg{number} is used just ahead of
10599% the alignment environment to set the number of the first left-hand 10667% the alignment environment to set the number of the first left-hand
10600% paired page. 10668% paired page.
10601% \begin{macro}{\setpairedpage} 10669% \begin{macro}{\setpairedpage}
10602% \changes{v1.5}{2022/08/27}{sets the page number of the first paired 10670% \changes{v1.5}{2022/08/28}{sets the page number of the first paired
10603% page} \cs{setpairedpage} is an argument-less command meant to be 10671% page} \cs{setpairedpage} is an argument-less command meant to be
10604% issued in commands used to set headers or footers before 10672% issued in commands used to set headers or footers before
10605% \cs{thepage}. This command has the counter |pairedpage| 10673% \cs{thepage}. This command has the counter |pairedpage|
10606% incremented on right-hand pages only, and sets |page| $\leftarrow$ 10674% incremented on right-hand pages only, and sets |page| $\leftarrow$
10607% |pairedpage| on every page. 10675% |pairedpage| on every page.
10608% \begin{macro}{\resetpagenumber} 10676% \begin{macro}{\resetpagenumber}
10609% \changes{v1.5}{2022/08/27}{resets normal running page numbers} 10677% \changes{v1.5}{2022/08/28}{resets normal running page numbers}
10610% \cs{resetpagenumber} must be used right out of \enquote{mirrored} 10678% \cs{resetpagenumber} must be used right out of \enquote{mirrored}
10611% paired pages alignment environments. This argument-less command 10679% paired pages alignment environments. This argument-less command
10612% corrects any numbering error on the page following the edition 10680% corrects any numbering error on the page following the edition