added nosep option to \note. done documenting \note

1 files changed, 202 insertions, 13 deletions

diff --git a/ekdosis.dtx b/ekdosis.dtx
index 030fd8c..0d3ce2b 100644
--- a/ekdosis.dtx
+++ b/ekdosis.dtx
@@ -124,6 +124,10 @@ along with this program.  If not, see
 \end{filecontents}
 \begin{filecontents}[overwrite]{\jobname-cfg.tex}
 \footnotelayout{m}
+\DeclareApparatus{fontium}[
+        delim=\hskip0.75em,
+        bhook=\textbf{Sources:},
+        ehook=.]
 \DeclareApparatus{default}[
         delim=\hskip0.75em,
         ehook=.]
@@ -1818,18 +1822,17 @@ texts=latin[xml:lang="la"]+\textcolor{red}{;}+
 % \cs{SetBeginApparatus}\marg{characters\textbar commands} can be used
 % to append \meta{characters} or \meta{commands} at the beginning of
 % the apparatus block. By default, nothing is appended. For instance,
-% \mintinline{latex}|\SetBeginApparatus{\textbf{Apparatus:}}| will
-% append \enquote{\textbf{Apparatus:}} at the beginning of the
-% apparatus block, while %
-% \mintinline{latex}|\SetBeginApparatus{\hskip 1em}| will set an
+% |\SetBeginApparatus{\textbf{Apparatus:}}| will append
+% \enquote{\textbf{Apparatus:}} at the beginning of the apparatus
+% block, while |\SetBeginApparatus{\hskip 1em}| will set an
 % indentation of one em.
 %
 % \DescribeMacro{\SetEndApparatus}
 % \cs{SetEndApparatus}\marg{characters} can be used to append
 % \meta{characters} at the end of the apparatus block. By default,
-% nothing is appended. As an example of use,
-% \mintinline{latex}|\SetEndApparatus{.}| will have a period printed
-% at the end of the apparatus as it is customary in some editions.
+% nothing is appended. As an example of use, |\SetEndApparatus{.}|
+% will have a period printed at the end of the apparatus as it is
+% customary in some editions.
 %
 % \DescribeMacro{\SetUnitDelimiter}
 % \cs{SetUnitDelimiter}\marg{delimiter} can be used to set the
@@ -2095,11 +2098,11 @@ Some \app[type=rec2]{
 %
 % \subsection{Other Notes, Comments, Sources, Testimonia}
 % \label{ref:type-note}
-% Additional layers of notes may be used to print short comments or to
+% Additional layers of notes can be used to print short comments or to
 % record references to texts quoted by the author of the edited text
 % or references to the edited text by other authors or
-% translators. The former is called an \emph{apparatus fontium} while
-% the latter is called an \emph{apparatus testium}.
+% translators. The former set is called an \emph{apparatus fontium}
+% while the latter is called an \emph{apparatus testium}.
 %
 % \danger From a technical standpoint, these notes are very different
 % from the short editorial notes inserted between lemma texts and
@@ -2116,7 +2119,188 @@ Some \app[type=rec2]{
 % to \cs{note} are ignored.
 %
 % \DescribeMacro{\note} \cs{note}\oarg{options}\marg{text}\\
-% As said above, \cs{note} when found outside \cs{app}|{}|, 
+% As said above, \cs{note}, when found outside \cs{app}|{}|, is used
+% to insert in additional layers of the apparatus short comments or
+% references to texts quoted or cited in the edition text. It accepts
+% the following comma-separated list of |key-value| optional
+% arguments:---\\
+% \DescribeOption{type} |type|$=$\meta{type}\\
+% |type| is used to specify the name of the layer where the note is to
+% be printed.\footnote{See \vref{sec:declaring-layers} to learn how to
+% declare and lay out new layers of notes.}\\
+% \DescribeOption{sep} |sep|$=$\meta{csname \textbar\ chars}\\
+% The separator between the lemma text and the contents of the note.\\
+% \DescribeOption{nosep} |nosep|$=$\verb+true|false+\\
+% This named argument does not need a value as it defaults to |true|
+% if it is used. Obviously, |nosep| removes the separator mentioned
+% above.\\
+% \DescribeOption{lem} |lem|$=$\meta{lemma text}\\
+% |lem| is the span of text the note is about. It may consist of one
+% or more words, or of an abbreviated lemma text.\\
+% \DescribeOption{labelb} |labelb|$=$\meta{label}
+% \hfill\tcboxverb{Mandatory}\\
+% |labelb| is the unique label to serve as a reference for the point
+% immediately preceding the lemma text.  \danger |labelb| is used by
+% \pkg{ekdosis} to print the line numbers in the apparatus criticus
+% and to set the |left()| XPointer should \texttt{TEI} output be
+% required. Therefore, it must be
+% specified. Otherwise, \pkg{ekdosis} will issue an error message.\\
+% \DescribeOption{labele} |labele|$=$\meta{label}\\
+% |labele| is the unique label to serve as a reference for the point
+% immediately following the lemma text. Contrary to |labelb|, |labele|
+% may be left unspecified if the note is only about one word. If it is
+% about a span, then |labele| ought to be specified.\\
+% \DescribeMacro{\linelabel} \cs{linelabel}\marg{label}\\
+% If |labele|$=$\meta{some\_label} be specified in the optional
+% argument of \cs{note}, \cs{linelabel}\marg{some\allowbreak\_label}
+% must be inserted immediately after the lemma text so that
+% \pkg{ekdosis} can locate the exact point where the lemma text
+% addressed by the note ends, like so:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+% Preamble:
+% \DeclareApparatus{fontium}[
+%         delim=\hskip0.75em,
+%         bhook=\textbf{Sources:},
+%         ehook=.]
+% \DeclareApparatus{default}[
+%         delim=\hskip0.75em,
+%         ehook=.]
+% Document:
+\begin{ekdosis}
+  The oldest monument of the Germans is their language, which, before
+  untold centuries, was the companion of their travels from central
+  Asia; a language, copious, elastic, inviting self-explaining
+  combinations and independent development; lending itself alike to
+  daily life and imagination, to description and abstract thought.
+  \note[type=fontium, labelb=61e, labele=62a, lem={They
+    had... slave}]{Waitz, \emph{Deutsche Verfassungs Geschichte},
+    i. 86} They had a class of nobles, but their tongue knew no word
+  for slave.\linelabel{62a}\footnote{George Bancroft, \emph{History of
+      the United States from the Discovery of the American Continent},
+    II.61--2.}
+\end{ekdosis}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% PDF output:---
+% \medskip
+% \resetlinenumber
+% \begin{alignment}[tcols=1,texts=specimen,apparatus=specimen]
+%   \begin{specimen}
+%     The oldest monument of the Germans is their language, which,
+%     before untold centuries, was the companion of their travels from
+%     central Asia; a language, copious, elastic, inviting
+%     self-explaining combinations and independent development;
+%     lending itself alike to daily life and imagination, to
+%     description and abstract thought.  \note[type=fontium,
+%     labelb=61e, labele=62a, lem={They had... slave}]{Waitz,
+%     \emph{Deutsche Verfassungs Geschichte}, i. 86} They had a class
+%     of nobles, but their tongue knew no word for
+%     slave.\linelabel{62a}\footnote{George Bancroft, \emph{History of
+%     the United States from the Discovery of the American Continent},
+%     II.61--2.}
+%   \end{specimen}
+% \end{alignment}
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{xml}
+<p>The oldest monument of the Germans is their language,
+which, before untold centuries, was the companion of their
+travels from central Asia; a language, copious, elastic,
+inviting self-explaining combinations and independent
+development; lending itself alike to daily life and
+imagination, to description and abstract thought. 
+<note type="fontium" target="#range(right(61e),left(62a))">Waitz, 
+<emph>Deutsche Verfassungs Geschichte</emph>, i. 86</note>
+<anchor xml:id="61e" />They had a class of nobles, but
+their tongue knew no word for slave.
+<anchor xml:id="#62a" />
+<note place="bottom">George Bancroft, 
+<emph>History of the United States from the Discovery of
+the American Continent</emph>, II.61--2.</note></p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% \paragraph{\cs{note} or \cs{linelabel} inside \cs{lem}}
+% It may happen that \cs{note} or \cs{linelabel} commands be found
+% inside the argument of \cs{lem}. Obviously, inserting such commands
+% in the apparatus criticus in print makes no sense and will lead to
+% an error. The solution is to insert in the value of the |alt|
+% optional argument of \cs{lem} a duplicate of the lemma text devoid
+% of those commands, like so:---
+% 
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}[linenos=false]{latex}
+This is some \app{
+  \lem[alt=dummy]{\note[type=fontium, labelb=bnote, labele=enote,
+    lem=dummy... command]{Text of the note}
+    dummy}
+  \rdg{pseudo}}
+text to demonstrate how to insert a note in the argument of the
+\emph{lem} command.\linelabel{enote}
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% PDF output:---
+% \medskip
+% \resetlinenumber
+% \begin{alignment}[flush,tcols=1,texts=specimen,apparatus=specimen]
+%   \begin{specimen}
+% This is some \app{
+%   \lem[alt=dummy]{\note[type=fontium, labelb=bnote, labele=enote,
+%     lem=dummy... command]{Text of the note}
+%     dummy}
+%   \rdg{pseudo}}
+% text to demonstrate how to insert a note in the argument of the
+% \emph{lem} command.\linelabel{enote}
+%   \end{specimen}
+% \end{alignment}
+%
+% \texttt{TEI xml} output:---
+%
+% \iffalse
+%<*example>
+% \fi
+\begin{minted}{xml}
+<p>This is some 
+<app>
+  <lem>
+  <anchor xml:id="bnote" />dummy</lem>
+  <note type="fontium"
+  target="#range(right(bnote),left(enote))">Text of the
+  note</note>
+  <rdg>pseudo</rdg>
+</app>text to demonstrate how to insert a note in the
+argument of the 
+<emph>lem</emph>command.
+<anchor xml:id="#enote" /></p>
+\end{minted}
+% \iffalse
+%</example>
+% \fi
+%
+% As can be seen from the \texttt{TEI xml} output above, the span of
+% text the note is about has been carefully delimited by two anchors
+% (ll.~4 and 12), the first of which falls within |<lem>| (l.~4), but
+% \pkg{ekdosis} has taken care of moving the note itself out of this
+% element (ll.~5--7). Otherwise, the \texttt{TEI} output would not be
+% valid.
 %
 % \section{To Be Continued...}
 % v1.0 of \pkg{ekdosis}, which should be available by the end of July
@@ -3707,6 +3891,7 @@ Some \app[type=rec2]{
   code labelb = \def\ekdn@labelb{#1},
   code labele = \def\ekdn@labele{#1},
   store sep = \ekdn@sep,
+  bool nosep = \ifekdn@nosep,
   initial type = default,
   initial sep = \ekdsep
 }
@@ -3755,7 +3940,9 @@ Some \app[type=rec2]{
       \current@ref@arg{\ekdn@labelb}{\ekdn@labele}%\hskip .25em
       \ifdefined\ekdn@lem%
           {\textdir TRT\unexpanded\expandafter{\ekdn@lem}}%
-          \unexpanded\expandafter{\ekdn@sep}\else\fi%
+          \unless\ifekdn@nosep
+          \unexpanded\expandafter{\ekdn@sep}\fi
+          \else\fi%
             {\textdir TRT\unexpanded{#2}}}}%
   {\edef\note@contents{%
       % \hskip .75em
@@ -3771,7 +3958,9 @@ Some \app[type=rec2]{
           {\noexpand\selectlanguage{\languagename}%
             \unexpanded\expandafter{\ekdn@lem}}%
           {\unexpanded\expandafter{\ekdn@lem}}%
-          \unexpanded\expandafter{\ekdn@sep}\else\fi%
+          \unless\ifekdn@nosep
+          \unexpanded\expandafter{\ekdn@sep}\fi
+          \else\fi%
           \ltx@ifpackageloaded{babel}%
           {{\noexpand\selectlanguage{\languagename}\unexpanded{#2}}}{%
             {\unexpanded{#2}}}}}%