From 579a84be553eca41dedc54e2906ee0356dc8ee99 Mon Sep 17 00:00:00 2001
From: Robert Alessi <alessi@robertalessi.net>
Date: Sat, 17 Oct 2020 12:18:53 +0200
Subject: tricks of the trade: new section on backuping essential files

---
 README.md   |  4 ++--
 about.html  |  4 ++--
 ekdosis.dtx | 70 ++++++++++++++++++++++++++++++++++++++++++++++++-------------
 3 files changed, 60 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 34cce3f..9d9e5d0 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ critical notes in any direction accepted by LuaTeX. Texts can be
 arranged in running paragraphs or on facing pages, in any number of
 columns which in turn can be synchronized or not. In addition to
 printed texts, `ekdosis` can convert `.tex` source files so as to
-produce `TEI xml` compliant critical editions. Database-driven
+produce `TEI xml`-compliant critical editions. Database-driven
 encoding under LaTeX then allows extraction of texts entered segment
 by segment according to various criteria: main edited text, variant
 readings, translations or annotated borrowings between texts. It is
@@ -21,7 +21,7 @@ version 3.
 
 License and Disclamer
 =====================
-ekdosis – Typesetting TEI xml Compliant Critical Editions
+ekdosis – Typesetting TEI xml-Compliant Critical Editions
 
 Copyright ⓒ 2020 Robert Alessi
 
diff --git a/about.html b/about.html
index 4c359c6..8b21663 100644
--- a/about.html
+++ b/about.html
@@ -19,9 +19,9 @@
 <p class="author">Robert Alessi</p>
 </header>
 <h1 id="overview">Overview</h1>
-<p><code>ekdosis</code> is a LuaLaTeX package designed for multilingual critical editions. It can be used to typeset texts and different layers of critical notes in any direction accepted by LuaTeX. Texts can be arranged in running paragraphs or on facing pages, in any number of columns which in turn can be synchronized or not. In addition to printed texts, <code>ekdosis</code> can convert <code>.tex</code> source files so as to produce <code>TEI xml</code> compliant critical editions. Database-driven encoding under LaTeX then allows extraction of texts entered segment by segment according to various criteria: main edited text, variant readings, translations or annotated borrowings between texts. It is published under the terms of the GNU General Public License (GPL) version 3.</p>
+<p><code>ekdosis</code> is a LuaLaTeX package designed for multilingual critical editions. It can be used to typeset texts and different layers of critical notes in any direction accepted by LuaTeX. Texts can be arranged in running paragraphs or on facing pages, in any number of columns which in turn can be synchronized or not. In addition to printed texts, <code>ekdosis</code> can convert <code>.tex</code> source files so as to produce <code>TEI xml</code>-compliant critical editions. Database-driven encoding under LaTeX then allows extraction of texts entered segment by segment according to various criteria: main edited text, variant readings, translations or annotated borrowings between texts. It is published under the terms of the GNU General Public License (GPL) version 3.</p>
 <h1 id="license-and-disclamer">License and Disclamer</h1>
-<p>ekdosis – Typesetting TEI xml Compliant Critical Editions</p>
+<p>ekdosis – Typesetting TEI xml-Compliant Critical Editions</p>
 <p>Copyright ⓒ 2020 Robert Alessi</p>
 <p>Please send error reports and suggestions for improvements to Robert Alessi:</p>
 <ul>
diff --git a/ekdosis.dtx b/ekdosis.dtx
index f8c2dc8..1908456 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -1,6 +1,6 @@
 % \iffalse meta-comment
 % 
-% ekdosis -- Typesetting TEI xml compliant critical editions
+% ekdosis -- Typesetting TEI xml-compliant critical editions
 % Copyright (C) 2020  Robert Alessi
 % 
 % Please send error reports and suggestions for improvements to Robert
@@ -27,7 +27,7 @@
 --[[
 This file is part of the `ekdosis' package
 
-ekdosis -- Typesetting TEI xml compliant critical editions
+ekdosis -- Typesetting TEI xml-compliant critical editions
 Copyright (C) 2020  Robert Alessi
 
 Please send error reports and suggestions for improvements to Robert
@@ -61,7 +61,7 @@ along with this program.  If not, see
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{ekdosis}
 %<*package>
-    [2020/10/14 v1.1-dev Typesetting TEI xml compliant critical editions]
+    [2020/10/14 v1.1-dev Typesetting TEI xml-compliant critical editions]
 %</package>
 %<*driver>
 \begin{filecontents}[noheader,overwrite]{bibdata.xml}
@@ -110,7 +110,7 @@ along with this program.  If not, see
 @Article{Alessi2020,
   author =	 {Alessi, Robert},
   title =	 {ekdosis: Using Lua\LaTeX{} for Producing \texttt{TEI
-                  xml} Compliant Critical Editions and Highlighting
+                  xml}-Compliant Critical Editions and Highlighting
                   Parallel Writings},
   journaltitle = {Journal of Data Mining and Digital Humanities},
   date =	 2020,
@@ -478,9 +478,9 @@ along with this program.  If not, see
 \metaset{title}{ἔκδοσις}
 \metaset{date}{\filedate}
 \metaset{draft}{\fileversion}
-\metaset{subject}{TEI xml compliant critical editions}
-\metaset{subtitle}{Typesetting TEI xml Compliant Critical Editions}
-\metaset[print]{subtitle}{Typesetting \texttt{TEI xml} Compliant
+\metaset{subject}{TEI xml-compliant critical editions}
+\metaset{subtitle}{Typesetting TEI xml-Compliant Critical Editions}
+\metaset[print]{subtitle}{Typesetting \texttt{TEI xml}-Compliant
   Critical Editions}
 \metaset{author}{Robert Alessi}
 \metaset{keywords}{LaTeX, Lua, TEI xml, multilingual critical
@@ -659,7 +659,7 @@ along with this program.  If not, see
 %   facing pages, in any number of columns which in turn can be
 %   synchronized or not. In addition to printed texts,
 %   \pkg{ekdosis} can convert \texttt{.tex} source files so as to
-%   produce \texttt{TEI xml} compliant critical
+%   produce \texttt{TEI xml}-compliant critical
 %   editions. Database-driven encoding under \LaTeX{} then allows
 %   extraction of texts entered segment by segment according to
 %   various criteria: main edited text, variant readings, translations
@@ -1209,8 +1209,8 @@ along with this program.  If not, see
 % \item The rendition to be used in the printed apparatus criticus.
 % \end{enumerate}
 %
-% \danger As \pkg{ekdosis} can include and use \texttt{TEI xml}
-% compliant lists of references,\footnote{See below
+% \danger As \pkg{ekdosis} can include and use \texttt{TEI
+% xml}-compliant lists of references,\footnote{See below
 % \vref{sec:references-cited-works}.} it is advisable to use
 % Bib\hologo{(La)TeX} labels in the first argument of
 % \cs{DeclareSource}. Otherwise, the unique label used to declare the
@@ -4297,6 +4297,47 @@ subtype="arabtex">'inna 'abI kAna mina
 %   must be used even if only one layer of critical notes is needed.
 % \end{remarks}
 %
+% \paragraph{Backup of Essential Files}
+% Each time the |.tex| source file is compiled, \pkg{ekdosis} reads
+% the |.aux| corresponding \LaTeX\ auxiliary file and its own |.ekd|
+% auxiliary file so as to process labels and collect entries of the
+% apparatus criticus. If for whatever reason\---e.g.\ some unknown
+% command has been inserted\---the compilation freezes and so must be
+% aborted, it may happen that most of the edition text has to be
+% reconstructed page after page. For large and complex editions, this
+% makes advisable to have current versions of those files backed up
+% each time a new compilation begins, which can be achieved by
+% inserting the following lines before the line that loads the
+% document class:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\RequirePackage{verbatimcopy}
+\IfFileExists{\jobname.aux}{%
+  \OldVerbatimCopy{\jobname.aux}{\jobname.aux.bak}}{}
+\IfFileExists{\jobname.ekd}{%
+  \OldVerbatimCopy{\jobname.ekd}{\jobname.ekd.bak}}{}
+\documentclass{book}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% This way, both |.aux| and |.ekd| files can be recovered from
+% |.aux.bak| and |.ekd.bak| just after the compilation has been
+% aborted. Should this be needed, one must proceed carefully as
+% follows:---
+% \begin{enumerate}
+% \item Just after the compilation has been aborted, move both
+%   |aux.bak| and |ekd.bak| files to a safe place.
+% \item Remove or correct the offending command or lines that broke
+%   the compilation and make sure that the issue is solved.
+% \item Restore the |.aux| and |.ekd| files from |aux.bak| and
+% |.ekd.bak| and resume work where it was left off.
+% \end{enumerate}
+%
 % \section{\texttt{TEI xml} Output}
 % \label{sec:teixml-output}
 % Several examples of \texttt{TEI xml} output have been provided
@@ -4359,7 +4400,7 @@ subtype="arabtex">'inna 'abI kAna mina
 % The \texttt{TEI} validator is here:
 % \url{http://teibyexample.com/xquery/TBEvalidator.xq}.} As for
 % \pkg{ekdosis}, it is designed to produce on request, in addition to
-% an edition in print, a \texttt{TEI xml} compliant output file. That
+% an edition in print, a \texttt{TEI xml}-compliant output file. That
 % said, one must keep in mind that the \LaTeX\ packages that are part
 % of {\TeX}Live can be counted in thousands, and the commands they
 % provide in tens of thousands. There may even be grounds in asserting
@@ -4923,7 +4964,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \DescribeMacro{\AddxmlBibResource}
 % \cs{AddxmlBibResource}\marg{basename or name.xml} is a preamble-only
 % command. If a base name (either suffixed with |.xml| or not) for a
-% \texttt{TEI xml} compliant bibliographical database be provided,
+% \texttt{TEI xml}-compliant bibliographical database be provided,
 % \pkg{ekdosis} will use it and insert formatted data in the back
 % matter section of its own \texttt{TEI xml} output file, as
 % |<biblStruct>| elements within a |listBibl| section.
@@ -5127,7 +5168,7 @@ Sample text with a \textcolor{red}{word} in red.
 % Of course, for this mechanism to work, Bib\TeX\ or Bib\LaTeX\ must
 % be used and connected to some |.bib| bibliographical database
 % file. Additionally, this |.bib| file must have been converted into a
-% \texttt{TEI xml} compliant file where all the Bib\hologo{(La)TeX}
+% \texttt{TEI xml}-compliant file where all the Bib\hologo{(La)TeX}
 % entries that are used in the document are found within
 % |<biblStruct>| elements.\footnote{See above n.~\vref{fn:zotero} for
 % information on how to do this.} Finally, this |.xml| bibliographical
@@ -6261,6 +6302,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \end{macro}
 % \begin{macro}{\TeXtoTEIPat}
+% \changes{v1.1}{2020/10/16}{renamed, formerly \cs{TeXtoTEIPatt}}
 % Finally, the more flexible\---and more delicate to
 % handle\---\cs{TeXtoTEIPat}\marg{\TeX\
 % pattern}\allowbreak\marg{\texttt{TEI} pattern} uses pattern matching
@@ -6285,7 +6327,7 @@ Sample text with a \textcolor{red}{word} in red.
 % \end{macro}
 % \begin{macro}{\AddxmlBibResource} This is a preamble-only command.
 %   If a base name (either suffixed with |.xml| or not) for a
-%   \texttt{TEI xml} compliant bibliographical database file be
+%   \texttt{TEI xml}-compliant bibliographical database file be
 %   provided with \cs{AddxmlBibResource}\marg{basename or name.xml},
 %   \pkg{ekdosis} will use it and insert formatted data in the back
 %   matter section of its own \texttt{TEI xml} output file, as
-- 
cgit v1.2.3