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

---
 ekdosis.dtx | 70 ++++++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 56 insertions(+), 14 deletions(-)

(limited to 'ekdosis.dtx')

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

