ekdosis.dtx should be ready: documenting ekdosis has officially begun!

1 files changed, 80 insertions, 140 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index e0ad014..1a184f7 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -1,5 +1,25 @@
 % \iffalse meta-comment
-% vim: textwidth=75
+% 
+% ekdosis -- Typesetting TEI xml compliant critical editions
+% Copyright (C) 2020  Robert Alessi
+% 
+% Please send error reports and suggestions for improvements to Robert
+% Alessi <alessi@robertalessi.net>
+% 
+% This program is free software: you can redistribute it and/or modify
+% it under the terms of the GNU General Public License as published by
+% the Free Software Foundation, either version 3 of the License, or
+% (at your option) any later version.
+% 
+% This program is distributed in the hope that it will be useful, but
+% WITHOUT ANY WARRANTY; without even the implied warranty of
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+% General Public License for more details.
+% 
+% You should have received a copy of the GNU General Public License
+% along with this program.  If not, see
+% <http://www.gnu.org/licenses/>.
+% 
 %<*internal>
 \iffalse
 %</internal>
@@ -44,93 +64,6 @@ along with this program.  If not, see
 %</luapre>
 %<*internal>
 \fi
-\def\nameofplainTeX{plain}
-\ifx\fmtname\nameofplainTeX\else
-  \expandafter\begingroup
-\fi
-%</internal>
-%<*install>
-\input docstrip.tex
-\keepsilent
-\askforoverwritefalse
-\preamble
--------:| -----------------------------------------------------------------
-ekdosis:| Typesetting TEI xml compliant critical editions
- Author:| Robert Alessi
- E-mail:| alessi@robertalessi.net
-License:| Released under the GNU General Public License v3 or later
-    See:| http://www.gnu.org/licenses/
-
-This file is part of the `ekdosis' package
-
-ekdosis -- Typesetting TEI xml compliant critical editions
-Copyright (C) 2020  Robert Alessi
-
-Please send error reports and suggestions for improvements to Robert
-Alessi <alessi@robertalessi.net>
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see
-<http://www.gnu.org/licenses/>.
-
-This work consists of the file ekdosis.dtx and a Makefile.
-Running "make" generates the derived files README, ekdosis.pdf and ekdosis.sty.
-Running "make inst" installs the files in the user's TeX tree.
-Running "make install" installs the files in the local TeX tree.
-\endpreamble
-
-\usedir{tex/lualatex/ekdosis}
-\generate{
-  \file{\jobname.sty}{\from{\jobname.dtx}{package}}
-}
-\nopreamble\nopostamble
-\usedir{tex/lualatex/ekdosis}
-\bgroup
-\catcode9=12
-\generate{
-  \file{\jobname.lua}{
-  \from{\jobname.dtx}{luapre}
-  \from{\jobname.dtx}{lua}
-  }
-}
-\egroup
-\usedir{doc/lualatex/ekdosis}
-\generate{
-  \file{ekdosis-ex.tex}{
-    \from{\jobname.dtx}{examples}
-  }
-}
-\usedir{doc/lualatex/ekdosis}
-\generate{
-  \file{README.txt}{\from{\jobname.dtx}{readme}}
-}
-%</install>
-%<install>\endbatchfile
-%<*internal>
-\usedir{source/lualatex/ekdosis}
-\generate{
-  \file{\jobname.ins}{\from{\jobname.dtx}{install}}
-}
-\nopreamble\nopostamble
-\usedir{doc/lualatex/ekdosis}
-\generate{
-  \file{README.txt}{\from{\jobname.dtx}{readme}}
-}
-\ifx\fmtname\nameofplainTeX
-  \expandafter\endbatchfile
-\else
-  \expandafter\endgroup
-\fi
 %</internal>
 % \fi
 %
@@ -158,13 +91,19 @@ Running "make install" installs the files in the local TeX tree.
 \usepackage{hologo}
 \usepackage{xcolor}
 \definecolor{ekdcolor}{RGB}{243,241,235}
-\usepackage{latexcolors}
+\definecolor{cinnamon}{rgb}{0.82, 0.41, 0.12}
 \usepackage{hyperxmp}
-\usepackage{uri}
+\usepackage{xurl}
 \usepackage[numbered]{hypdoc}
-\hypersetup{unicode=true, colorlinks, allcolors=cinnamon, keeppdfinfo,
-  linktocpage=true, pdfauthor={Robert Alessi}, pdftitle={The ekdosis
-    package}, pdfcontactemail={alessi@robertalessi.net},
+\hypersetup{
+  unicode=true,
+  colorlinks,
+  allcolors=cinnamon,
+  keeppdfinfo,
+  linktocpage=true,
+  pdfauthor={Robert Alessi},
+  pdftitle={The ekdosis package},
+  pdfcontactemail={alessi@robertalessi.net},
   pdfcontacturl={http://www.robertalessi.net/ekdosis},
   pdfcopyright={Copyright (C) 2018 Robert Alessi
     <alessi@robertalessi.net>. This document is licensed under the
@@ -173,43 +112,36 @@ Running "make install" installs the files in the local TeX tree.
     http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to
     Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.},
   pdflicenseurl={https://creativecommons.org/licenses/by-sa/4.0/legalcode},
-  pdfmetalang={en-US}, pdftype={Text}, pdfkeywords={Arabic language,
-    arabtex, luatex}}
+  pdfmetalang={en-US},
+  pdftype={Text},
+  pdfkeywords={Arabic language, arabtex, luatex}}
+\usepackage{uri}
 \usepackage[lot]{multitoc}
 \usepackage{ekdosis}
 \usepackage{arabluatex}
 \usepackage{relsize}
 \usepackage{units}
-\PassOptionsToPackage{newfloat}{minted}
 \usepackage{tikz}
-\usepackage[breakable, skins, xparse, minted]{tcolorbox}
-\usepackage{minted}
+\usepackage[breakable, skins, xparse]{tcolorbox}
+\usepackage[newfloat]{minted}
 \setminted{bgcolor=ekdcolor,linenos, fontsize=\small}
-\newminted[ekdlua]{lua}{
-  bgcolor={},
-  linenos,
-  fontsize=\relsize{-0.5},
-  xleftmargin=12pt,
-  breaklines,
-  numberblanklines=false,
-  numbersep=3pt,
+\newminted[ekdlua]{lua}{bgcolor={}, linenos, fontsize=\relsize{-0.5},
+  xleftmargin=12pt, breaklines, numberblanklines=false, numbersep=3pt,
   firstnumber=last}
 \renewcommand{\theFancyVerbLine}{\rmfamily\smaller\arabic{FancyVerbLine}}
 \usepackage[contents]{colordoc}
 \newcommand{\package}[1]{\textsf{#1}\index{#1=#1 (package)}}
-%
 \backgroundcolor{c}{ekdcolor}
 \usepackage{caption}
 \captionsetup[listing]{position=above,skip=-1ex}
 \usepackage{needspace}
 \NewDocumentCommand{\captof}{O{listing} m O{}}{%
   \bgroup
-  \needspace{2\baselineskip}%
+  \needspace{5\baselineskip}%
   \vskip 1ex plus 2pt minus 2pt%
   \captionof{#1}{#2}%
   #3%
   \egroup}
-%
 \usepackage{etoc}
 \etocsettocdepth{paragraph}
 \newcommand{\ekdtableofcontents}{%
@@ -270,9 +202,7 @@ Running "make install" installs the files in the local TeX tree.
 % \fileversion\ --- \filedate}}
 %  
 % \author{Robert Alessi \\
-% \href{mailto:alessi@robertalessi.net?Subject=ekdosis package}%
-% {\texttt{alessi@robertalessi.net}}}
-% 
+% \mailto[ekdosis package]{alessi@robertalessi.net}}
 % \date{}
 %
 % \maketitle
@@ -282,29 +212,24 @@ Running "make install" installs the files in the local TeX tree.
 %
 %\changes{v1.00}{2020/07/01}{First public release}
 %
-% \begin{abstract}
-% ==== Put abstract text here. ====
+% \begin{abstract}%
+%   \package{ekdosis} is a Lua\LaTeX{} package designed for
+%   multilingual critical editions. It can be used to typeset texts
+%   and different layers of critical notes in any direction accepted
+%   by Lua\TeX. 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,
+%   \package{ekdosis} can convert \texttt{.tex} source files so as to
+%   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
+%   or annotated borrowings between texts. It is published under the
+%   terms of the GNU General Public License (GPL) version 3.
 % \end{abstract}
 %
-% \section{Usage}
-%
-% ==== Put descriptive text here. ====
-% 
-% \DescribeMacro{\dummyMacro}
-% This macro does nothing.\index{doing nothing|usage} It is merely an
-% example.  If this were a real macro, you would put a paragraph here
-% describing what the macro is supposed to do, what its mandatory and
-% optional arguments are, and so forth.
-% 
-% \DescribeEnv{dummyEnv}
-% This environment does nothing.  It is merely an example.
-% If this were a real environment, you would put a paragraph here
-% describing what the environment is supposed to do, what its
-% mandatory and optional arguments are, and so forth.
-%
-% \section{Grid}
-% \begin{keyfigure}[H]{c={Grid
-%   typesetting},l={fig:grid-typesetting},t={Each square in the grid
+% \section{Introduction}
+% \begin{keyfigure}[H]{c={Grid Typesetting}, t={Each square in the grid
 %   has a side length of \unit[10]{pt}. Therefore, the distance
 %   between the last line of the text and the first line of the
 %   apparatus is here approximately \unit[25]{pt}.}}
@@ -323,18 +248,33 @@ Running "make install" installs the files in the local TeX tree.
 %   \end{tikzpicture}
 % \end{keyfigure}
 %
-% %***
-% \captof{Peter and John example}
-% \inputminted[firstline=17,lastline=24]{latex}{ekdosis-ex.tex}
+% \captof{The Peter and John example}
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+\begin{ekdosis}
+  I saw my friend
+  \app{
+    \lem{Peter}
+    \rdg{John}
+  }
+  at the station yesterday.
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
 % \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
 %   \begin{specimen}
-%     I saw my friend \app{
-%       \lem{Peter}
-%       \rdg{John}}
+%     I saw my friend
+%     \app{
+%     \lem{Peter}
+%     \rdg{John}
+%     }
 %     at the station yesterday.
 %   \end{specimen}
 % \end{alignment}
-% \inputminted[firstline=35,lastline=39]{xml}{ekdosis-ex-tei.xml}
 % 
 % \section{Implementation}
 %