From a1dda7ced5ee7891dcb1ef0e193859551b88082d Mon Sep 17 00:00:00 2001
From: Robert Alessi <alessi@robertalessi.net>
Date: Mon, 3 Aug 2020 19:17:01 +0200
Subject: done documenting on the Divisions

---
 ekdosis.dtx                  | 306 ++++++++++++++++++++++++++++++++++++++++---
 samples/Caesar_BG-6-13-1.tex |   2 +-
 samples/Makefile             |   3 +-
 3 files changed, 292 insertions(+), 19 deletions(-)

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 63ac19d..a1acf5b 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -225,6 +225,11 @@ along with this program.  If not, see
                origDate={s. XI--XII}]
 \DeclareShorthand{ca}{α}{cA,cM,cB,cR,cS,cL,cN}
 \DeclareShorthand{cb}{β}{cT,cf,cU,cl}
+% Hippocrates Epidemics, Book 2:
+\DeclareWitness{hV}{V}{\emph{Vaticanus Gr.} 276}
+\DeclareWitness{hI}{I}{\emph{Parisinus Gr.} 2140}
+\DeclareWitness{hR}{R}{\emph{Vaticanus Gr.} 277}
+\DeclareWitness{hH}{H}{\emph{Parisinus Gr.} 2142}
 \end{filecontents}
 \documentclass{ltxdoc}
  %\usepackage[letterpaper,margin=25mm,left=50mm,nohead]{geometry}
@@ -849,7 +854,8 @@ along with this program.  If not, see
 % traditions. \pkg{ekdosis} provides a flexible mechanism in which
 % format and presentation have been carefully separated from
 % content. It is designed to build un-numbered \texttt{TEI} divisions
-% allowed to nest recursively. However, if |divs| be set to |latex|,
+% allowed to nest recursively.\footnote{See below,
+% \vref{sec:body-divisions}.} However, if |divs| be set to |latex|,
 % \LaTeX{} standard textual divisions can be used and will be
 % translated into \texttt{TEI} numbered |<div>| elements.
 %
@@ -1622,7 +1628,7 @@ yesterday.
 % \fi
 %
 % \resetlinenumber
-% \ekdfmtdiv{2}{}{.}
+% \EkdosisFormatDivision{2}{}{.}
 % \begin{alignment}[flush,lcols=2,
 %                   texts=edition[xml:lang="la"];
 %                   translation[xml:lang="en"]]
@@ -2452,7 +2458,7 @@ argument of the
 % numbering.\footcite{lineno} But it must be noted that \pkg{ekdosis}
 % strictly prohibits the \enquote{pagewise} mode of operation that is
 % provided by \pkg{lineno}. As a result of this hinderance, all
-% \enquote{margin switching} features of \pkg{lineno} are disabled
+% \enquote{margin switching} functions of \pkg{lineno} are disabled
 % within the environments that are specific to \pkg{ekdosis},
 % viz. \env{ekdosis} and \env{alignment}.
 %
@@ -2753,7 +2759,7 @@ argument of the
 % produce a duplicate of the original |.tex| source file in which all
 % |arabtex| or |buckwalter| strings are replaced with Unicode
 % equivalents, either in Arabic script or in any accepted standard of
-% transliteration.\footcite[See][\mkbibquote{Exporting Unicode Arabic
+% transliteration.\footcite[\mkbibquote{Exporting Unicode Arabic
 % to an External File}]{arabluatex}
 %
 % \pkg{arabluatex} is fully supported by \pkg{ekdosis}. The following
@@ -2829,7 +2835,7 @@ subtype="arabtex">'inna 'abI kAna mina
 % which all |arabtex| strings found within \cs{begin}|{arabexport}|
 % \dots\ \cs{end}|{arabexport}| (see \vref{lst:arabluatex-ekd},
 % ll.~9--19) are replaced with full-vocalized Arabic Unicode
-% strings. Finally, compiling this latter file produces the following
+% script. Finally, compiling this latter file produces the following
 % |sample-arabic_out-tei.xml| an extract of which follows:---
 % 
 % \iffalse
@@ -2850,8 +2856,274 @@ subtype="arabtex">'inna 'abI kAna mina
 % The reader will find the full |arabic-sample.tex| source file with
 % instructions in \vref{sec:arabic-sample}, and is invited to refer to
 % the documentation of the \pkg{arabluatex} package for more
-% information on the way to use its Arabic environments and exporting
-% features.\footcite{arabluatex}
+% information on the way to use its Arabic environments and built-in
+% functions dedicated to export |arabtex| ASCII strings to
+% Unicode.\footcite{arabluatex}
+%
+% \section{Divisions of the Body}
+% \label{sec:body-divisions}
+% The features that are described in this section call for one general
+% remark.  \pkg{ekdosis} is designed to figure out where any \LaTeX\
+% command that is converted to a \texttt{TEI} opening element allowed
+% to nest recursively, such as |<div>|, |<lg>| and the like, is to be
+% closed, even though there is no explicit indication of the point
+% where the closure occurs. Thoroughly scanning \LaTeX\ source files
+% with \textsf{Lua} functions which involve complex string matching
+% and recursions was required, as \LaTeX\ \enquote*{open} commands
+% such as \cs{chapter} or \cs{section} only act as milestones,
+% contrary to \texttt{TEI} elements.
+% 
+% \danger It must be noted that the two styles described hereinafter
+% are mutually exclusive. \texttt{TEI xml} forbids that both be
+% combined within a single |<body>| element.\footnote{See
+% \url{https://tei-c.org/release/doc/tei-p5-doc/en/html/DS.html\#DSDIV}.}
+% As a result, \pkg{ekdosis} will disregard whichever one is not
+% selected.
+% \vskip\baselineskip
+%
+% \subsection{\LaTeX\ Standard Divisions}
+% \label{sec:latex-divs}
+% \pkg{ekdosis} can use the \LaTeX\ standard textual divisions, such
+% as \cs{book}, \cs{chapter}, \cs{section} and the like.
+%
+% \danger However, to have these divisions properly translated into
+% \texttt{TEI} numbered |<div>| elements, the |divs| general option
+% must be set to |latex| explicitly\---viz. |divs=latex|\---as
+% described above \vpageref{ref:divs-opt}.
+%
+% Once |divs| has been set to |latex|, \pkg{ekdosis} converts
+% \cs{book}, \cs{part}, \cs{chapter}, \cs{section}, \cs{subsection}
+% and \cs{subsubsection} into corresponding \texttt{TEI}
+% \enquote*{numbered} |<div|\textsubscript{\emph{n}}|>| elements,
+% where $1\leq n\leq 6$.
+%
+% \paragraph{Adjusting the Levels of Textual Subdivisions}
+% \DescribeMacro{\MkBodyDivs}
+% \cs{MkBodyDivs}\marg{div1}\marg{div2}\marg{div3}\allowbreak\marg{div4}\marg{div5}\marg{div6}
+% takes six mandatory arguments. This command can be used in the
+% preamble or at any point of the document to make the number of the
+% first-level subdivision of the edition text, viz.\ |<div1>|, match
+% to any \LaTeX\ command other than \cs{book}. For example, if
+% \cs{section} be the highest-level sectional command used, then
+% \cs{MkBodyDivs}|{section}{subsection}{subsubsection}{}{}|\allowbreak|{}|
+% will have \cs{section}, \cs{subsection} and \cs{subsubsection}
+% converted into |<div1>|, |<div2>| and |<div3>| respectively.
+%
+% \paragraph{Inserting Variants in Headings}
+% Variant readings can be inserted in headings. In this case, the
+% optional argument of the \LaTeX\ sectional command must naturally be
+% used to prevent variants from going into headers, footers or the
+% table of contents, like so:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Preamble:
+\usepackage[teiexport=tidy, divs=latex]{ekdosis}
+\MkBodyDivs{chapter}{section}{}{}{}{}
+
+% Document:
+\chapter[Ἱπποκράτους ἐπιδημιῶν βιβλίον δεύτερον]{Ἱπποκράτους ἐπιδημιῶν
+  \app{
+    \lem[wit={I,R,H}]{βιβλίον δεύτερον}
+    \rdg[wit=V]{λόγος β’}}}
+
+\section{<Τμῆμα πρῶτον>}
+Ἄνθρακες θερινοὶ ἐν Κραννῶνι· [...]
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<div1 type="chapter">
+  <head>Ἱπποκράτους ἐπιδημιῶν 
+  <app>
+    <lem wit="#I #R #H">βιβλίον δεύτερον</lem>
+    <rdg wit="#V">λόγος β’</rdg>
+  </app></head>
+  <div2 type="section">
+    <head>&lt;Τμῆμα πρῶτον&gt;</head>
+    <p>Ἄνθρακες θερινοὶ ἐν Κραννῶνι· [...]</p>
+  </div2>
+</div1>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \subsection{Using \texttt{TEI} Un-numbered Divisions}
+% \label{sec:ekddiv}
+% \danger As already described \vpageref{ref:divs-opt}, the
+% un-numbered style of division is the one that is set by default. It
+% is congruous to the general option |divs=ekdosis|.
+%
+% This style provides a flexible mechanism in which format and
+% presentation are separated from content. It is designed to meet the
+% requirements of classical and literary texts the divisions of which
+% may depend on many different received traditions.
+%
+% \DescribeMacro{\ekddiv} \cs{ekddiv}\marg{key-value arguments} is the
+% unique sectional command provided by \pkg{ekdosis}. This command
+% converts the divisions into un-numbered \texttt{TEI} |<div>|
+% elements allowed to nest recursively and takes one mandatory
+% argument in which the following |key-value| arguments are
+% accepted:---\\
+% \DescribeOption{type} |type|$=$\meta{name}
+% \hfill\tcboxverb{Default: none}\\
+% |type| corresponds to the \texttt{TEI} class |att.typed| and can be
+% used to classify the element in which it is found in any
+% way. Suitable values here can be |book|, |chapter|, |section| and
+% the like.\\
+% \DescribeOption{n} |n|$=$\meta{value} \hfill
+% \tcboxverb{Default: none}\\
+% |n| is meant to provide a number or any kind of label for the
+% division and does not have to be unique in the document.\\
+% \DescribeOption{head} |head|$=$\meta{name}
+% \hfill\tcboxverb{Default: none}\\
+% |head| holds the title of the division and may further contain
+% variant readings.\\
+% \DescribeOption{barehead} |barehead|$=$\meta{name}
+% \hfill\tcboxverb{Default: none}\\
+% |barehead| is supposed to be used to prevent unwanted commands from
+% going into such places as headers, footers and the table of
+% contents.\\
+% \DescribeOption{depth} |depth|$=$\meta{n} where $1\leq n\leq 9$
+% \hfill\tcboxverb{Default: 1}\\
+% As \texttt{TEI} un-numbered divisions are simply |<div>| elements
+% allowed to nest recursively to indicate their hierarchic depth and
+% \cs{ekddiv} is an \enquote*{open} \LaTeX\ command, |n| is needed to
+% indicate the depth of the division within the hierarchy, the largest
+% being |1| and the smallest being |9|.\\
+% \DescribeOption{toc}
+% |toc|$=$\verb+|book|part|chapter|section|subsection|subsubsection|paragraph+\\
+% |subparagraph|\hfill\tcboxverb{Default: not set}\\
+% If |toc| be set, the title of the division goes into the table of
+% contents at the hierarchic level that is specified as value.
+%
+% \paragraph{Formatting the Titles}
+% \DescribeMacro{\EkdosisFormatDivision} By design, \pkg{ekdosis} does
+% not format the titles. Instead, depending on what is needed for the
+% edition text, \cs{EkdosisFormatDivision}\marg{n}\marg{code
+% before}\marg{code after} is provided to lay out the titles of any
+% hierarchic depth of division. This command takes three mandatory
+% arguments as follows: \meta{n}, which is the number referring to the
+% particular depth of division to be formatted and some \LaTeX\
+% commands to go before and after the title itself. The following
+% example illustrates how the titles of the largest division can be
+% printed horizontally centered in a larger size:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\EkdosisFormatDivision{1}{\begin{center}\Large}{\end{center}}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% To elaborate on the example provided above in \vref{sec:latex-divs},
+% here follows how the first three hierarchical levels could be
+% formatted as un-numbered divisions:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Preamble:
+\EkdosisFormatDivision{1}{\begin{center}\Large}{\end{center}}
+\EkdosisFormatDivision{2}{\begin{center}\large}{\end{center}}
+\EkdosisFormatDivision{3}{\bfseries}{.}
+
+% Document:
+\begin{ekdosis}
+  \ekddiv{
+    head={Ἱπποκράτους ἐπιδημιῶν
+      \app{
+        \lem[wit={I,R,H}]{βιβλίον δεύτερον}
+        \rdg[wit=V]{λόγος β’}}},
+    type=book,
+    depth=1,
+    n=II
+  }
+
+  \ekddiv{
+    head={<Τμῆμα πρῶτον>},
+    type=section,
+    depth=2,
+    n=II.1
+  }
+
+  \ekddiv{head=1, type=paragraph, depth=3, n=II.1.1}
+  Ἄνθρακες θερινοὶ ἐν Κραννῶνι· [...]
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% PDF output:---
+% \medskip
+% 
+% \resetlinenumber
+% \EkdosisFormatDivision{1}{\begin{center}\Large}{\end{center}}
+% \EkdosisFormatDivision{2}{\begin{center}\large}{\end{center}}
+% \EkdosisFormatDivision{3}{\bfseries}{.}
+% \begin{alignment}[flush,
+%   tcols=1,
+%   texts=hippocrates[xml:lang="grc"],
+%   apparatus=hippocrates]
+%   \AtBeginEnvironment{hippocrates}{\selectlanguage{greek}}
+%   \begin{hippocrates}
+%       \ekddiv{
+%         head={Ἱπποκράτους ἐπιδημιῶν
+%           \app{
+%           \lem[wit={hI,hR,hH}]{βιβλίον δεύτερον}
+%           \rdg[wit=hV]{λόγος β’}}},
+%         type=book,
+%         depth=1,
+%         n=II}
+% 
+%       \ekddiv{head={<Τμῆμα πρῶτον>}, type=section, depth=2, n=II.1}
+% 
+%       \ekddiv{head=1, type=paragraph, depth=3, n=II.1.1} Ἄνθρακες
+%       θερινοὶ ἐν Κραννῶνι· [...]
+%     \end{hippocrates}
+% \end{alignment}
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<div xml:id="div-hippocrates_1" xml:lang="grc">
+  <div type="book" n="II">
+    <head>Ἱπποκράτους ἐπιδημιῶν 
+    <app>
+      <lem wit="#I #R #H">βιβλίον δεύτερον</lem>
+      <rdg wit="#V">λόγος β’</rdg>
+    </app></head>
+    <div type="section" n="II.1">
+      <head>&lt;Τμῆμα πρῶτον&gt;</head>
+      <div type="paragraph" n="II.1.1">
+        <head>1</head>
+        <p>Ἄνθρακες θερινοὶ ἐν Κραννῶνι· [...]</p>
+      </div>
+    </div>
+  </div>
+</div>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
 %
 % \section{To Be Continued...}
 % v1.0 of \pkg{ekdosis}, which should be available by the end of July
@@ -2862,7 +3134,7 @@ subtype="arabtex">'inna 'abI kAna mina
 % \begin{comment}
 %   \section{Correspondence and Alignment}
 % \end{comment}
-% \label{sec:correspondance-alignment}
+% \label{sec:correspondence-alignment}
 %
 % \label{ref:segmentation}
 % 
@@ -4925,14 +5197,14 @@ subtype="arabtex">'inna 'abI kAna mina
   initial depth = 1
 }
 %    \end{macrocode}
-% \begin{macro}{\ekdfmtdiv}
-% \cs{ekdfmtdiv}\marg{n}\marg{code before}\marg{code after} is
-% used to lay out the heading of the title. It takes three mandatory
-% arguments: \emph{n}, namely the number referring to the particular
-% depth of the division, and then some \LaTeX{} formatting commands
-% to go before and after the heading itself:---
+% \begin{macro}{\EkdosisFormatDivision}
+% \cs{EkdosisFormatDivision}\marg{n}\marg{code before}\marg{code
+% after} is used to lay out the heading of the title. It takes three
+% mandatory arguments: \emph{n}, namely the number referring to the
+% particular depth of the division, and then some \LaTeX{} formatting
+% commands to go before and after the heading itself:---
 %    \begin{macrocode}
-\NewDocumentCommand{\ekdfmtdiv}{m m m}{
+\NewDocumentCommand{\EkdosisFormatDivision}{m m m}{
   \luadirect{ekdosis.fmtdiv(\luastring{#1},
     \luastringN{#2},
     \luastringN{#3})}
@@ -4940,7 +5212,7 @@ subtype="arabtex">'inna 'abI kAna mina
 %    \end{macrocode}
 % \end{macro}
 % \cs{ekd@getfmtdiv} gets the formatting commands that have been
-% stored by \cs{ekdfmtdiv}.
+% stored by \cs{EkdosisFormatDivision}.
 %    \begin{macrocode}
 \NewDocumentCommand{\ekd@getfmtdiv}{m m}{%
   \luadirect{tex.sprint(ekdosis.getfmtdiv(\luastringO{#1},
@@ -4951,7 +5223,7 @@ subtype="arabtex">'inna 'abI kAna mina
 % \cs{ekddiv}\marg{key-value arguments} is the standard command
 % provided by \pkg{ekdosis} to meet the requirements of classical and
 % literary texts the divisions of which depend on many different
-% received traditions. It takes one optional argument in which the
+% received traditions. It takes one mandatory argument in which the
 % key-value arguments defined above are accepted, and converts the
 % divisions into \texttt{TEI} \enquote*{un-numbered} |<div>|
 % elements.
diff --git a/samples/Caesar_BG-6-13-1.tex b/samples/Caesar_BG-6-13-1.tex
index 8002aec..ff793a6 100644
--- a/samples/Caesar_BG-6-13-1.tex
+++ b/samples/Caesar_BG-6-13-1.tex
@@ -13,7 +13,7 @@
         delim=\hskip0.75em,
         ehook=.]
 
-\ekdfmtdiv{2}{}{.}
+\EkdosisFormatDivision{2}{}{.}
 
 \SetEkdosisAlignment{
   tcols=3,
diff --git a/samples/Makefile b/samples/Makefile
index 518ec87..49bb11b 100644
--- a/samples/Makefile
+++ b/samples/Makefile
@@ -13,7 +13,6 @@ define dosamples
 	$(CMP) --shell-escape $1 >/dev/null
 endef
 
-
 all:
 	cp ../ekdosis.{lua,sty} .
 	$(foreach file,$(texsamples), $(call dosamples, $(file)))
@@ -24,3 +23,5 @@ all:
 	rm -rf *
 	cp -p -r .backup/* .
 	rm -rf .backup
+
+.PHONY: all
-- 
cgit v1.2.3