From c9d393cefb1046142a9fe57b0227ee8d3f5395c4 Mon Sep 17 00:00:00 2001
From: Robert Alessi <alessi@robertalessi.net>
Date: Wed, 5 Aug 2020 12:03:40 +0200
Subject: \label and \linelabel generated wrong xml:ids. documenting on TEI
 output

---
 ekdosis.dtx | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 86 insertions(+), 4 deletions(-)

(limited to 'ekdosis.dtx')

diff --git a/ekdosis.dtx b/ekdosis.dtx
index ff37d86..29c3626 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -122,6 +122,14 @@ along with this program.  If not, see
   organization = {Society for Classical Studies}
 }
 
+@Online{TBE,
+  author =	 {Van den Branden, Ron and Terras, Melissa and
+                  Vanhoutte, Edward},
+  title =	 {TEI by Example},
+  urldate =	 {2020-08-04},
+  url =		 {http://www.teibyexample.org}
+}
+
 @Software{lineno,
   title =	 {The Lineno package},
   titleaddon =	 {Line numbers on paragraphs},
@@ -3130,11 +3138,84 @@ subtype="arabtex">'inna 'abI kAna mina
 %</example>
 % \fi
 %
+% \section{\texttt{TEI xml} Output}
+% \label{sec:teixml-output}
+% Several examples of \texttt{TEI xml} output have been provided
+% hitherto. Before proceeding, the reader is invited to return to
+% every one of them. In this respect, it may be of interest to review
+% carefully the excerpt of Caesar's \emph{Gallic War} of which the
+% \LaTeX\ source file and its corresponding \texttt{TEI xml} output
+% are printed in full below in \vref{sec:caesar-gw-6-1-13}. Once
+% \pkg{ekdosis} has been instructed to convert the edition text into
+% \texttt{TEI xml} (l.~11), the preamble of this file shows how to set
+% languages and fonts to be used in the document (ll.~2--6), format
+% the titles (l.~16) and lay out the alignment of an edition text
+% associated with two translations (ll.~18--25). Furthermore, it shows
+% how information related to each language (Latin, English and French)
+% is to be found in two different places, namely for \texttt{TEI xml}
+% output (ll.~21--3) and for PDF output through \LaTeX\
+% (ll.~27--9). Finally, it provides examples of declaring witnesses,
+% hands, scholars and shorthands (ll.~31--60). As to the document
+% itself, it shows how to lay out a conspectus siglorum in a table
+% (ll.~64--80), before giving detailed examples of how the edition
+% text is entered (ll~85--101) and sectional commands provided by
+% \pkg{ekdosis} are used (ll.~86, 103 and 110).\footnote{The PDF
+% output is available as \href{samples/Caesar_BG-6-13-1.pdf}{a
+% separate file}.}
+%
+% \subsection{Requesting \texttt{TEI xml} Output}
+% \label{sec:request-tei-output}
+% \texttt{TEI xml} output is requested by means of the |teiexport|
+% global option as described above
+% \vpageref{ref:teiexport-option}. Once instructed to output
+% \texttt{TEI}, \pkg{ekdosis} converts in sequence the contents of
+% \env{ekdosis} environments (see above
+% \vref{sec:single-text-editing}). As regards the contents of
+% \env{alignment} environments (see above \vref{sec:alignment-basic}),
+% \pkg{ekdosis} first collates the contents of the environments that
+% have been declared with the |texts| optional argument of
+% \env{alignment} or with \cs{SetAlignment},\footnote{See above
+% \vref{sec:multiple-alignment}.} then places each of the
+% corresponding \texttt{TEI xml} outputs within distinct |<div>|
+% elements named after the declared environments themselves. For
+% example, to return to Caesar's text, the Latin edition text is found
+% between a \cs{begin}|{latin}| \dots\ \cs{end}|{latin}| environment
+% (see the |.tex| source file, \vref{sec:caesar-gw-tex}, ll.~85--101)
+% which is declared at l.~21. Then, the corresponding \texttt{xml}
+% output is found within a |<div>| element, the |xml:id| of which has
+% been called by \pkg{ekdosis} |div-latin_1| (see
+% \vref{sec:caesar-gw-tei}, ll.~176--200).
+%
+%
+% \paragraph{Validation of the \texttt{TEI xml} Structure}
+% The reference tool that the author relies on is that provided by the
+% \emph{\texttt{TEI} by Example Project}.\footnote{\cite{TBE}.
+% \texttt{TEI} validator:
+% \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
+% 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
+% that the possibilities offered by \TeX\ and \LaTeX\ exceed what can
+% be afforded by \texttt{TEI xml}. On another hand, many \LaTeX\
+% commands make no sense in \texttt{TEI}. Therefore, a sensible choice
+% is to keep them out of the environments the contents of which are to
+% be translated into \texttt{xml} elements.
+%
+% \subsection{General Principles}
+% \label{sec:totei-general-principles}
+% Converting a \LaTeX\ document into \texttt{TEI xml} is quite an
+% intricate business. In many cases, \LaTeX\ strings are found within
+% environments or groups: whether such groups are delimited by opening
+% and closing braces or by explicit \cs{begin} \dots\ \cs{end}
+% commands, 
+%
+%
 % \section{To Be Continued...}
 % v1.0 of \pkg{ekdosis}, which should be available by the end of July
 % 2020, will include a full documentation. At the time of writing, the
 % author is working on this part of the package.
-% 
 %
 % \begin{comment}
 %   \section{Correspondence and Alignment}
@@ -3694,7 +3775,7 @@ subtype="arabtex">'inna 'abI kAna mina
 % \inputminted[linenos=true]{latex}{samples/Caesar_BG-6-13-1.tex}
 % \subsection{\texttt{TEI xml} Output}
 % \label{sec:caesar-gw-tei}
-% \inputminted[linenos=false]{xml}{samples/Caesar_BG-6-13-1-tei.xml}
+% \inputminted[linenos=true]{xml}{samples/Caesar_BG-6-13-1-tei.xml}
 % 
 % \section{Arabic Sample File}
 % \label{sec:arabic-sample}
@@ -5547,8 +5628,8 @@ local texpatttotags = {
    {a="\\icite%s?%[(.-)%]%[(.-)%]{(.-)}", b="%1 <ref target=\"#%3\">%2</ref>"},
    {a="\\icite%s?%[(.-)%]{(.-)}", b="<ref target=\"#%2\">%1</ref>"},
    {a="\\icite%s?{(.-)}", b="<ptr target=\"#%1\"/>"},
-   {a="\\linelabel%s?{(.-)}", b="<anchor xml:id=\"#%1\"/>"},
-   {a="\\label%s?{(.-)}", b="<anchor xml:id=\"#%1\"/>"},
+   {a="\\linelabel%s?{(.-)}", b="<anchor xml:id=\"%1\"/>"},
+   {a="\\label%s?{(.-)}", b="<anchor xml:id=\"%1\"/>"},
    {a="\\v?pageref%s?{(.-)}", b="<ptr target=\"#%1\"/>"},
    {a="\\v?ref%s?{(.-)}", b="<ptr target=\"#%1\"/>"},
    {a="\\LR%s+{(.-)}", b="%1"},
@@ -5561,6 +5642,7 @@ local envtotags = {
    {a="quotation", b="quote", c=""},
    {a="ekdverse", b="lg", c=""},
    {a="txarabtr", b="p", c=" xml:lang=\"ar-Latn\" type=\"transliterated\""},
+   {a="quoting", b="quote", c=""},
    {a="txarab", b="p", c=" xml:lang=\"arb\""},
    {a="center", b="p", c=" rend=\"align(center)\""},
    {a="verse", b="lg", c=""},
-- 
cgit v1.2.3

