summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/spelatex/spelatex.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/spelatex/spelatex.dtx')
-rw-r--r--macros/latex/contrib/spelatex/spelatex.dtx898
1 files changed, 470 insertions, 428 deletions
diff --git a/macros/latex/contrib/spelatex/spelatex.dtx b/macros/latex/contrib/spelatex/spelatex.dtx
index bdedc84d70..564abba5a2 100644
--- a/macros/latex/contrib/spelatex/spelatex.dtx
+++ b/macros/latex/contrib/spelatex/spelatex.dtx
@@ -20,7 +20,6 @@
% This work consists of the files spelatex.dtx, spelatex.ins,
% and any derivative file, generated from the dtx file using
% the ins driver file.
-%
% \fi
%
% \iffalse
@@ -33,17 +32,20 @@
\ProvidesFile{spelatex.dtx}
%</driver>
%<*package>
- [2024/06/21 v0.91 SpeLaTeX - Speech-enabled LaTeX (DMW and LVP)]
+ [2024/09/09 v0.92 SpeLaTeX - Speech-enabled LaTeX (DMW and LVP)]
%</package>
-\def\fileversion{0.91}
-\def\filedate{2024/06/21}
+\def\fileversion{0.92}
+\def\filedate{2024/09/09}
%<*driver>
\documentclass[10pt]{ltxdoc}
\usepackage{makeidx}
\usepackage{alltt}
\usepackage[english]{babel}
-\usepackage[extramath]{spelatex}
+\usepackage[extramath,
+ server=https://ctan.org/tex-archive/macros/latex/contrib/spelatex
+ ]{spelatex}
\usepackage{amsmath}
+\usepackage{amsfonts}
\usepackage{graphicx}
\usepackage{tikz}
\IfFileExists{tocbibind.sty}{\usepackage{tocbibind}}{}
@@ -83,6 +85,11 @@
% - avoided big active link areas\\
% - sketched bigger picture, leading to
% the three project phases.}
+% \changes{v0.92}{2024/09/09}{. Second overhaul:\\
+% - dumped orgmode export idea (too small of an audience)\\
+% - introduced markers for non-area-links\\
+% - implemented audio on server\\
+% - implemented <\kern-0.5ex<\kern-0.5ex<-macro as a shorthand}
%
% \GetFileInfo{spelatex.dtx}
%
@@ -111,41 +118,49 @@
% \maketitle
% \fvset{gobble=2}
%
+% \section*{Disclaimer}
+% \<<<{
+% Note that this is an experimental package. Its interface may change
+% considerably over subsequent versions (until v1.0).
+% }
+%
% \section{Preface}
%
% \subsection{Background}
%
-% \begin{spelchunk}
+% \<<<{
% At our institute, the University of Antwerp in Belgium, the number
% of students with reading and/or writing disorders (or at least
% aware of these disorders) is increasing. Approximately 5\% of the
-% students are registered with such a disorder. Probably there's an
-% additional number of people opting not to register their disorder.
-% \end{spelchunk}
-%
-% \begin{spelchunk}
+% students are registered with such a disorder and the number is rising
+% steadily over the past 10 years. Probably this number is an
+% underestimation as a number of people opti not to register their
+% disorder.
+% }
+
+% \<<<{
% A large portion of the study materials we offer to students is
% still written material. The authors believe that this will keep on
% being so, even given the multimedia and AI options that have
% become mainstream. Let's not go into this debate for now.\\
% However, written course texts cannot be but suboptimal for
% students with reading disorders.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% For small texts, reading them out loud and recording them using a
% voice recorder to create an aid for our target group, is still
-% feasible. We have taken that route at our institute for exam
+% feasible. We have taken that in the past for exam
% assignments. However, for bigger texts (like course syllabi) this
-% is beyond the time a teacher can afford spending on this small a
+% is beyond the time a professor can afford spending on this small a
% group of students. Yes, economic laws also govern teaching!
-% \end{spelchunk}
+% }
%
% \subsection{State of the art}
%
% \subsubsection{In general}
%
-% \begin{spelchunk}
+% \<<<{
% Therefore, reverting to readily available text-to-speech software
% is an obvious choice. Nowadays, special software exists that
% provides the functionality of reading out loud the contents of
@@ -158,40 +173,40 @@
% loaded with non-trivial mathematics, the standard text-to-speech
% packages fail to meet our expectations. In addition, they cannot
% read a sensible textual description of figures or tables.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% The issue with reading mathematics will be solved in the future,
% by enforcing mathematical equations to follow a specific standard
% that can be parsed and converted, not only into a visual
% representation, but also into proper text. MathML will be one of
% the candidates for that format.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% The issue with figures and tables can be solved by using the tag
% infrastructure of PDF. The format provides a system of tags that
% allow you to provide extra information about the content of a
% document, in much the same way as you can specify an 'alt' key for
% an image in HTML. This tag could contain a proper textual
% description of the figure or the table.
-% \end{spelchunk}
+% }
%
% \subsubsection{For \LaTeX}
%
-% \begin{spelchunk}
-% Currently, the \LaTeX project is investing in enabling \LaTeX{} to
+% \<<<{
+% Currently, the \LaTeX{} project is investing in enabling \LaTeX{} to
% partially automate the tagging of PDFs with the \texttt{tagpdf}
% package~\cite{TAGPDF}, such that the user only has to do a minimal
% job (adding tags for figures and tables). The goal is to maximize
% the accessibility of \LaTeX-produced documents.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
-% So all is well? Not quite. Though I'm confident that with enough
-% time the community will solve the issue completely, there are
+% \<<<{
+% So all is well? Not quite. Though we are confident that --- with enough
+% time --- the community will solve the issue completely, there are
% still some gaps:
-% \end{spelchunk}
+% }
% \begin{itemize}
% \spelitem{The tagpdf package is still not a part of the mainstream
% \LaTeX{}-kernel.}
@@ -202,13 +217,13 @@
%
% \subsection{This package}
%
-% \begin{spelchunk}
+% \<<<{
% This package aims to overcome these problems in the meantime and
% also to contribute to the longterm goal: making perfectly tagged
% PDFs that are read by any PDF-reader.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% In the \emph{first phase} of this package (i.e. the version you are
% looking at right now), this package reads your \LaTeX{} source,
% converts the text and the formulas to audio files and equips your
@@ -217,58 +232,49 @@
% The audio files are external files that should be packaged with
% your PDF to allow a reader to use the document with the available
% audio.
-% How does it read the formulas? It parses your \LaTeX{} constructs and
+% You have the choice to use local files or files that are made available on a
+% server (as holds for this text; the audio files are on the CTAN servers).\\
+% How does \spelatex{} read the formulas? It parses your \LaTeX{} constructs and
% makes the best of it. This will probably be the part that might
% survive up until the very last phase of this package.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% In a \emph{second phase} of this package, the audio files will be embedded
% into the PDF. Currently, there are not enough PDF readers that
% support this feature. Therefore, we decided to keep using the
% external audio files for now.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% In a \emph{third phase}, the audio files \emph{may be} abandoned
% alltogether, fully switching to tags. And we do think that this
% should be the end goal. The reasons why we say
% \emph{'may be'}, are:
-% \end{spelchunk}
+% }
% \begin{itemize}
% \spelitem{The voices of the current PDF-readers are still not of the
% same quality as the ones available online. And quality does matter.}
% \spelitem{The better voices may require cloud access, and probably
-% will not be free, therefore (me) paying for them at document creation
-% time, makes more sense to me than having my students pay
+% will not be free, therefore (us) paying for them at document creation
+% time, makes more sense to us than having our students pay
% for these voices whenever they read the document.}
% \spelitem{The industry standard Adobe reader is not easily available
% on open-source operating systems (like UNIX/BSD/Linux-derived
% platforms). You might consider using emulation using
% wine~\cite{WINE}, but in that case you can forget about audio. Free
% access to software is something we consider to be a must-have,
-% rather than a nice-to-have. In addition, Walter feels miserable when
-% he's forced to use anything else than GNU/Linux, because then he
-% keeps moaning that his productivity is ruined.}
+% rather than a nice-to-have.}
% \end{itemize}
%
-% \begin{spelchunk}
-% Admittedly, in this first phase, using the \spelatex{} package
-% causes a significant overhead in writing your text. Therefore we
-% also provide you the \spelbox{} extension for the Org-mode
-% \cite{ORGMODE} of \GNU{} Emacs \cite{EMACS}. To satisfy your
-% curiosity: \spelbox{} stands for ``Speech-Enabled \LaTeX{} By
-% Org-mode eXport''.
-% \end{spelchunk}
-%
-% \begin{spelchunk}
+% \<<<{
% Will \spelatex{} become obsolete in the future?
% Undoubtedly so. But for the time being, it answers our desire to
% provide our students with good audio support when studying their
% engineering courses. That is now, not only in five years time.
-% \end{spelchunk}
+% }
-% \begin{spelchunk}
+% \<<<{
% We hope that you enjoy
% using our software, or that --- if you are not pleased with it ---
% it triggers you to give us feedback or to come up with a better
@@ -278,32 +284,34 @@
% One of her suggestions (not to use big hyperlink-areas) was almost
% instantly implemented and has been adopted as the standard way of
% linking.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% You are free to use our software but kindly ask you to provide a
% mention ``The audio materials of this text have been prepared with
-% \spelatex{}/\spelbox{}'' in the section treating copyrights,
-% bibliographic data or any other spot that is suited. We'd also
-% welcome a short mail of yours telling that you make use of the
-% package. The pleasure of receiving such an e-mail makes our day.
-% \end{spelchunk}
-%
-% \begin{spelchunk}
+% \spelatex{}'' in the section treating copyrights,
+% bibliographic data or any other spot of your text that is
+% suited. We'd also welcome a short mail of yours telling that you
+% make use of the package. The pleasure of receiving such an e-mail
+% makes our day.
+% }
+%
+% \<<<{
% You are free to modify this \LaTeX-package, keeping a reference to
% our original package intact, provided that your package is subject
% to the LPPL license, as is \spelatex{}. However, contributing to our
-% package might be a better way to go, in order to bundle the efforts
+% package or to the \LaTeX{} project in general, might be a better
+% way to go, in order to bundle the efforts
% for a better speech-enabled \LaTeX{}.
-% \end{spelchunk}
-%
+% }
+% \clearpage
% \section{Introduction}
%
% \subsection{Target audience}
-% \begin{spelchunk}
+% \<<<{
% \spelatex{} is primarily intended for persons with a reading
% disorder. This may be:
-% \end{spelchunk}
+% }
% \begin{itemize}
% \spelitem{persons suffering dyslexia}
% \spelitem{visually impaired persons}
@@ -318,177 +326,153 @@
% \end{itemize}
% \end{itemize}
%
-% \begin{spelchunk}
+% \<<<{
% But also people who want to multitask, e.g., gardening while
% listening to a technical book, can benefit from
% \spelatex{}.\footnote{Note that multitasking is not reserved for persons
% without visual impairment. Also visually impaired persons can
% benefit from listening to an audiobook while doing other
-% things.} Personally, we often use \spelatex{} to proofread texts as we
-% hear language errors more easily than we spot them while reading.
-% \end{spelchunk}
+% things.}\\ We often use \spelatex{} to proofread the texts we've
+% written ourselves as we hear language errors more easily than we
+% spot them while reading.
+% }
%
% \subsection{The magic under the hood}
%
-% \subsubsection{The \spelbox{}-ecosystem}
-%
-% \begin{spelchunk}
-% The \spelatex{}-package is one of the parts of the \spelbox{}
-% ecosystem. It consists of three components:
-% \end{spelchunk}
-% \begin{itemize}
-% \spelitem{An Org-mode exporter called \texttt{ox-spel} \cite{OXSPELATEX}}
-% \spelitem{This \LaTeX{}-package \spelatex{} \cite{SPEL}}
-% \spelitem{A script embeded in the Perl module \texttt{SpeL::Wizard} \cite{SPELWIZARD}}
-% \end{itemize}
-%
% \subsubsection{The overall picture}
%
-% \begin{spelchunk}
-% \spelatex{} equips the PDF that is generated by \LaTeX{}
-% with hyperlinks to audio files that contain the spoken
-% equivalent of the original text, equations, figures and tables
-% \end{spelchunk}
-%
-% \begin{spelchunk}
-% Let's look at this in detail in Fig.~\ref{fig:setup}.
-% For now, ignore the two top boxes, and let's assume you are
-% composing the file |text.tex| as your document. We will return
-% to the two top boxes later.
-% \end{spelchunk}
-%
-% \begin{spelchunk}
+% \<<<{
+% \spelatex{} equips the PDF that is generated by \LaTeX{}
+% with hyperlinks to audio files that contain the spoken
+% equivalent of the original text, equations, figures and tables.
+% }
+%
+% \<<<{
+% Let's start by considering the flow depicted in
+% Fig.~\ref{fig:setup} at the top of the diagram.
% By loading the |spel.sty| package in your source
-% document, \LaTeX{} will produce a PDF file that references audio
+% document (|text.tex|), \LaTeX{} will produce a PDF file that references audio
% files that will be generated later (see below). In
% addition, it generates text chunks (i.e. small portions of
% your text) in separate files (|.tex|) and a spel index file
% (|.spelidx|) referencing them in sequence.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% Together with the |.aux|-file (needed by \spelatex{} for labels and
% citations), these are the inputs to the \spelatex-engine (|spel-wizard.pl|)
% that parses the text chunks, writes a full text version of them as
% spel files (with extension |.spel|) and
-% controls the text-to-speech engine to generate audio files of
+% controls the text-to-speech engine to generate audio versions of
% them.\footnote{In the figure, Ogg Vorbis has been chosen as
% format, but this can be any audio format.}
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% To avoid excessive text to speech conversion (i.e. an expensive step)
-% the \spelatex{} engine derives a finger print of them and compares it
+% the \spelatex{} engine derives an MD5 fingerprint of them and compares it
% to previously generated fingerprints for the chunk. If the
-% finger print has changed, the audio file is overwritten (or
+% fingerprint has changed, the audio file is overwritten (or
% created the first time), otherwise it is left untouched.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
-% As a cherry on top, the \spelatex-engine also creates a playlist,
+% \<<<{
+% As a cherry on top, the \spelatex-engine also creates a top-level playlist,
% such that you may use the audio files for a \POD{}cast-like
% listening experience.\\
% Something that has not been indicated on the figure, is that for
% reading out loud entire (sub)sections, the PDF-file also references
% m3u playlists that gather all chunks belonging to the (sub)section.
-% \end{spelchunk}
+% }
%
-% \begin{figure}[p]
+% \begin{figure}
% \begin{spelchunk}
% \begin{center}
% \begin{tikzpicture}
-% [scale=0.8,>=latex,
-% doc/.style={rectangle,fill=black!10,align=center,minimum
-% width=2cm,minimum height=2cm},
-% tool/.style={rectangle,draw,align=center}]
-% \node [doc] (utext) at (0,9) {text.org\\\footnotesize(unprepped
-% source)};
-% \node [tool] (instrument) at (0,6) {Org-mode exporter\\\footnotesize(\spelbox)};
-% \node [doc] (text) at (0,3) {text.tex\\\footnotesize(prepped source)};
-% \draw[->] (utext) -- (instrument);
-% \draw[->] (instrument) -- (text);
-% \node [doc] (R) at (-3,0) {spel.sty\\\footnotesize(package)};
-% \node [tool] (latex) at (0,0) {\LaTeX\\\footnotesize(compiler)};
-% \node [doc] (pdf) at (0,-3) {text.pdf\\\footnotesize(PDF with\\\footnotesize hyperlinks)};
-% \node [doc] (spelidx) at (6,-3) {text.spelidx\\\footnotesize(index file)};
-% \node [doc] (aux) at (9,-3) {text.aux\\\footnotesize(auxiliary file)};
-% \node [doc] (files) at (3,-3) {*.tex\\\footnotesize(text chunks)};
-% \draw[->] (text) -- (latex);
-% \draw[->,dotted] (text) -- (R);
-% \draw[->,dotted] (spelidx) -- (files);
-% \draw[->] (R) -- (latex);
-% \draw[->] (latex) -- (pdf);
-% \draw[->] (latex) edge[out=0,in=90] (spelidx);
-% \draw[->] (latex) edge[out=10,in=90] (aux);
-% \draw[->] (latex) edge[out=-10,in=90] (files);
-% \node [tool] (engine) at (6,-6) {\spelpl{}\\
-% \footnotesize(\spelatex{} engine)};
-% \node [tool] (t2s) at (1.5,-6) {text-to-speech\\engine};
-% \draw[->] (files) -- (engine);
-% \draw[->] (spelidx) -- (engine);
-% \draw[->] (aux) -- (engine);
-% \node[doc] (ogg) at (0,-9) {*.ogg\\\footnotesize(audio files)};
-% \node[doc] (spel) at (3,-9) {*.spel\\\footnotesize(spel files)};
-% \node[doc] (m3u) at (6,-9) {text.m3u\\\footnotesize(playlist)};
-% \node[doc] (md5) at (9,-9) {*.md5\\\footnotesize(fingerprints)};
-% \draw[->] (engine) -- (spel);
-% \draw[->] (engine) -- (m3u);
-% \draw[<->] (engine) -- (md5);
-% \draw[->,dotted] (pdf) edge[out=-115,in=115] (ogg);
-% \draw[->,dotted] (m3u) edge[out=-125,in=-55] (ogg);
-% \draw[->,dashed] (engine) -- (t2s);
-% \draw[->] (spel) -- (t2s);
-% \draw[->] (t2s) -- (ogg);
+% [scale=0.8,>=latex,
+% doc/.style={rectangle,fill=black!10,align=center,minimum
+% width=2cm,minimum height=2cm},
+% tool/.style={rectangle,draw,align=center}]
+% \node [doc] (text) at (0,3) {text.tex\\\footnotesize(source file)};
+% \node [doc] (R) at (-3,0) {spel.sty\\\footnotesize(package)};
+% \node [tool] (latex) at (0,0) {\LaTeX\\\footnotesize(compiler)};
+% \node [doc] (pdf) at (0,-3) {text.pdf\\\footnotesize(PDF with\\\footnotesize hyperlinks)};
+% \node [doc] (spelidx) at (6,-3) {text.spelidx\\\footnotesize(index file)};
+% \node [doc] (aux) at (9,-3) {text.aux\\\footnotesize(auxiliary file)};
+% \node [doc] (files) at (3,-3) {*.tex\\\footnotesize(text chunks)};
+% \draw[->] (text) -- (latex);
+% \draw[->,dotted] (text) -- (R);
+% \draw[->,dotted] (spelidx) -- (files);
+% \draw[->] (R) -- (latex);
+% \draw[->] (latex) -- (pdf);
+% \draw[->] (latex) edge[out=0,in=90] (spelidx);
+% \draw[->] (latex) edge[out=10,in=90] (aux);
+% \draw[->] (latex) edge[out=-10,in=90] (files);
+% \node [tool] (engine) at (6,-6) {\spelpl{}\\
+% \footnotesize(\spelatex{} engine)};
+% \node [tool] (t2s) at (1.5,-6) {text-to-speech\\engine};
+% \draw[->] (files) -- (engine);
+% \draw[->] (spelidx) -- (engine);
+% \draw[->] (aux) -- (engine);
+% \node[doc] (ogg) at (0,-9) {*.ogg\\\footnotesize(audio files)};
+% \node[doc] (spel) at (3,-9) {*.spel\\\footnotesize(spel files)};
+% \node[doc] (m3u) at (6,-9) {text.m3u\\\footnotesize(playlist)};
+% \node[doc] (md5) at (9,-9) {*.md5\\\footnotesize(fingerprints)};
+% \draw[->] (engine) -- (spel);
+% \draw[->] (engine) -- (m3u);
+% \draw[<->] (engine) -- (md5);
+% \draw[->,dotted] (pdf) edge[out=-115,in=115] (ogg);
+% \draw[->,dotted] (m3u) edge[out=-125,in=-55] (ogg);
+% \draw[->,dashed] (engine) -- (t2s);
+% \draw[->] (spel) -- (t2s);
+% \draw[->] (t2s) -- (ogg);
% \end{tikzpicture}
-% \end{center}
-% \end{spelchunk}
-% \begin{spelchunkad}
-% The easiest flow is to start from the top box, which represents
-% an org file that describes your text. We call this the
-% unprepped source. Read the Orgmode
-% documentation on \LaTeX{} and \spelatex{}-exporting to get to know
-% the format. The Orgmode \spelatex{} exporter, creates a fully
-% equiped \LaTeX{} file of your text. We call this the prepped source. You can
-% also start by composing this file yourself.
-% If you prepped source file uses the \spelatex{} style file, than
-% your compiler will generate a PDF file with hyperlinks, a
-% dot aawks-file and a dot spellindex-file together with a directory full of
-% dot tex files containing the text chunks to be processed by the
-% \spelpl-engine. This is a perl script that converts the chunks into
-% plain text readable spel files. The script is called spel dash
-% wizard dot pl. It also creates a playlist and audio files using a
-% text-to-speech engine. In this case, these are
-% Ogg-Vorbis files. To avoid having to call the text-to-speech
-% engine too frequently (which may incur costs), MD5-fingerprints
-% are used such that chunks that have been generated before and
-% are unchanged, can be reused. The end result is a PDF file that
-% references the audio files.
-% \end{spelchunkad}
-% \caption{Basic tool setup of \spelbox{} of which the \spelatex{} package
-% is an integral part; filled boxes indicate files,
-% outlined boxes indicate tools; solid lines indicates use or
-% creation of files, dotted lines indicate references, dashed lines
-% indicate a control relationship.}
-% \label{fig:setup}
+% \end{center}
+% \end{spelchunk}
+% \begin{spelchunkad}
+% If you load the \spelatex{} style file in your source file (at the
+% top of the figure) and prepare your source file according to the
+% instructions in this manual, than
+% your compiler will generate a PDF file with hyperlinks, a
+% dot aawks-file and a dot spellindex-file together with a directory full of
+% dot tex files containing the text chunks to be processed by the
+% \spelpl-engine. This is a perl script that converts the chunks into
+% plain text readable spel files. The script is called spel dash
+% wizard dot pl. It also creates a playlist and audio files using a
+% text-to-speech engine. In this case, these are
+% Ogg-Vorbis files. To avoid having to call the text-to-speech
+% engine too frequently (which may incur costs), MD5 fingerprints
+% are used such that chunks that have been generated before and
+% are unchanged, can be reused. The end result is a PDF file that
+% references the audio files.
+% \end{spelchunkad}
+% \caption{Basic tool setup of the \spelatex{} package; filled boxes indicate
+% files, outlined boxes indicate tools; solid lines indicates use or
+% creation of files, dotted lines indicate references, dashed lines
+% indicate a control relationship.}
+% \label{fig:setup}
% \end{figure}
%
-% \begin{spelchunk}
+% \<<<{
% You might wonder: where are the links? Well, there are three
% variants:
-% \end{spelchunk}
+% }
% \begin{itemize}
% \spelitem{\emph{area links}, which are almost exclusively
% used for equations, tables or figures. These links make an entire
% rectangle active, linking to the corresponding audio file.}
% \spelitem{\emph{group links}, indicated by small right-pointing
-% triangles next to section headers. These cause all blocks in the
-% section to be read one by one.}
-% \spelitem{\emph{hidden links}, wich are, as the name suggests,
-% hidden to avoid visual disturbance of the text; every
-% paragraph, footnote and list is activated by a link on the
-% whitespace before the first line of the chunk. Try it! Once you
+% triangles next to section headers (on the far right). These cause all
+% blocks in the section to be read one by one.\\
+% In case you specify the
+% package option \texttt{markervisibility=none} these triangles will become
+% invisible. However, the clickable areay still exists. Try!}
+% \spelitem{\emph{chunk links}, before every
+% paragraph, footnote or list, a small triangle indicates a clickable link.\\
+% If you activate the package option \texttt{markervisibility=onlygroups}, they will
+% become invisible, but still clickable. Try it! Once you
% are aware that these regions are active, you'll find them
-% easily. In addition, not using the full paragraph as an active
+% easily. Not using the full paragraph as an active
% region, allows existing hyperlinks (like for citations, references
% or URLs) to still function.}
% \end{itemize}
@@ -504,7 +488,7 @@
% \spelmacad{thanks}{the thanks macro}
% \spelmacad{item}{the item macro}
% \spelmacad{spelitem}{the spelitem macro}
-% \begin{spelchunk}
+% \<<<{
% Generating the text chunks to be read out loud requires us to use
% special \LaTeX-macros. For all pieces of text that are within
% an existing macro (e.g. |\title|, |\author|, |\section|,
@@ -512,9 +496,9 @@
% redefined by the \spelatex{}-package to
% execute the magic without any further hassle.\\
% We call these \LaTeX-fragments \emph{implicit spelchunks}.%
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% However, not all \LaTeX-constructs can be dealt with in an
% automatic way. This is true for any |\item| you put inside a list.
% You need to replace that with a |\spelitem| that takes the text
@@ -524,10 +508,10 @@
% spelchunks}. They should have been implicit, but we could not get
% that to work without problems. Therefore you need to mark them
% explicitly as |\spelitem| constructs.
-% \end{spelchunk}
+% }
%
% \subsubsection{Explicit spelchunks}
-% \begin{spelchunk}
+% \<<<{
% One would hope that displaymath environments are also implicit
% spelchunks. However, overriding environments in \LaTeX{} is a tricky
% business. In view of this, the \spelatex{} package keeps away from
@@ -540,12 +524,12 @@
% will have to provide a text description for tables and figures
% manually, using a subsequence |spelchunkad|
% environment (the suffix ad stands for \emph{audio description}).
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% To keep the terminology clear, we label them as automatic
-% and manual spelchunks respectively:
-% \end{spelchunk}
+% and manual explicit spelchunks respectively:
+% }
% \begin{itemize}
% \spelitem{automatic: \texttt{equation}, \texttt{eqnarray},
% \texttt{gather}, \texttt{align}, \texttt{alignat}, \ldots}
@@ -553,25 +537,26 @@
% \texttt{tikzpicture}, \ldots}
% \end{itemize}
%
-% \begin{spelchunk}
+% \<<<{
% The similarity between both categories is that you both embed them
% in a |spelchunk| environment, but that you provide the manual
% textual description using a |spelchunkad| environment right after
-% the chunk: in this way, the |spelchunkad| environment provides an
+% the chunk for the manual ones: in this way, the |spelchunkad| environment provides an
% alternative text for the chunk. Note that this way of working also
-% enables you to provide an overriding text for an equation, if you
-% think that \spelpl{} is doing a bad job. You do me a favor if
-% you submit this subpar behavior as a bug report to me!
-% \end{spelchunk}
+% enables you to provide an overriding text for an automatic spelchunk,
+% e.g., an equation, if you
+% think that \spelpl{} is doing a bad job. You do us a favor if
+% you submit this subpar behavior as a bug report to us!
+% }
%
-% \begin{spelchunk}
+% \<<<{
% It is worthwile to make good descriptions for a figure or a
% table. It's here that you can create true added value to your
% manuscript, even for readers without impairment!
-% \end{spelchunk}
+% }
%
% \subsubsection{Paragraphs}
-% \begin{spelchunk}
+% \<<<{
% However, there is the elephant in the room that we did not yet
% talk about, the paragraph. Indeed, it is desirable to split plain
% text according to the paragraphs in the document. Alas, paragraphs
@@ -581,63 +566,40 @@
% explicit spelchunks and need to be embedded
% in |spelchunk| environments. This environment will cause its
% contents to be hyperlinked to a separate piece of audio.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% Encasing all your paragraphs with |spelchunk| environments
% manually is a pain. There is a reason why in \LaTeX{}
% paragraphs can be created by a double newline: convenience.
% The |spelchunk|-environment encasing ruins this totally!
-% \end{spelchunk}
-%
-% \subsubsection{Emacs Orgmode to the rescue!}
-% \begin{spelchunk}
-% However, we provide an exporter for the Org-mode \cite{ORGMODE} of
-% Emacs \cite{EMACS}, such
-% that you can prepare your manuscript in Org-mode and not worry
-% about all these exlicit tricks with |spelchunk| and |spelitem|
-% constructs.
-% \end{spelchunk}
-%
-% \begin{spelchunk}
-% This brings us to the two top boxes in the diagram of
-% Fig.~\ref{fig:setup}. If you prepare your manuscript in Org-mode,
-% and use the Org-mode exporter, you don't have to worry about explicit
-% spelchunks, or defunct implicit spelchunks. Therefore, we encourage
-% you to use Emacs as your editor. The learning
-% curve is steep, but the rewards regarding ease-of-use are huge.
-% In that way, you can focus on providing textual descriptions for
-% the non textual portions of your manuscript, e.g. giving a good
-% description of a graph.
-% \end{spelchunk}
-%
-% \begin{spelchunk}
-% Note that this very document has been prepared manually to make it
-% independent of Org-mode. It also shows that if you don't
-% want to use Emacs and Org-mode, you will suffer some considerable
-% pain in equipping your manuscript with an overload of |spelchunk|
-% environments. We have only one advice: don't use the \spelatex{}
-% outside \spelbox{}. Outside a proper boxed confinement,
-% spells easily become curses\ldots
-% \end{spelchunk}
+% }
+% \spelmacad{<<<}{the shorthand macro}
+% \<<<{
+% To ease the pain and in order to avoid the visual intrusiveness of the
+% spelchunk environments, you can also use the \texttt{\textbackslash{}<<<\{\}} command to
+% encase your paragraphs. In some cases the \texttt{\textbackslash{}<<<\{\}}
+% command will not work, e.g., if there is a |Verbatim| environment
+% inside. In that case you must use the |spelchunk| environment directly.
+% }
%
% \subsection{Extra math commands}
%
-% \begin{spelchunk}
+% \<<<{
% Some of the ways to specify mathematical expressions in \LaTeX{} is
% very liberal, what makes converting them to text quite
% difficult. Therefore, we also provide some
% extra constructs that make life easier for both parties: you as a
% user and \spelpl{} as a parser.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% An example of this are sets. We provide two commands to define a
% set. As we want these commands to blend in with general \LaTeX{},
% we did not equip them with a prefix |spel|. Therefore, we made
% activating them conditional to specifying the package option
% |extramath|.
-% \end{spelchunk}
+% }
% \begin{description}
% \spelitem[\texttt{\textbackslash{}setenum}]{a command to define a set
% that consists of comma or semicolon separated elements}
@@ -648,14 +610,11 @@
%
% \subsection{Added value}
%
-% \begin{spelchunk}
+% \<<<{
% Why would it make sense to use \spelatex? We think there are many
% selling points. We can mention a few:
-% \end{spelchunk}
+% }
% \begin{description}
-% \spelitem[Minimal overhead]{
-% Preparing a \LaTeX{} manuscript for use with \spelatex{} requires a
-% minimal amount of work, if you are using Org-mode in Emacs.}
% \spelitem[Free for the content provider]{
% If you are using a freeware text-to-speech engine (like for
% example festival \cite{FESTIVAL} or balabolka \cite{BALABOLKA})
@@ -664,8 +623,9 @@
% the effort of preparing your manuscript. There are no license
% costs involved.\\
% You could also consider to use an online paying text-to-speech
-% service. As an example, We incorporated a connection to Amazon's
-% Polly \cite{AWSPOLLY}.\\
+% service. As an example, we incorporated a connection to Amazon's
+% Polly \cite{AWSPOLLY}. We admit, it's not free, but it doesn't
+% cost an arm and a leg either.\\
% In addition, if your user has a better-quality (maybe
% commercial) text-to-speech system, he/she can reconvert the text
% files him-/herself, equiping your document with a voice they
@@ -675,72 +635,71 @@
% \spelitem[Free for your audience]{
% In addition, the user of your audio-enabled document doesn't
% need to buy a license for text-to-speech software. Only a PDF-viewer
-% and standard audio-player program are required.}
+% and a standard audio-player program are required.}
% \spelitem[Math capable]{
-% Try some of the equations in this manuscript. We are quite
-% confident you'll be convinced fairly soon.}
+% Try some of the equations in this manuscript in
+% section~\ref{sec:demo}. We are quite confident you'll be
+% convinced fairly soon.}
% \end{description}
%
% \section{Installation}
%
% \subsection{The \spelatex{} package}
-% \begin{spelchunk}
+% \<<<{
% If you are a package manager then you'll know how to
% prepare an installation package for \spelatex.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
-% If you are a normal user then you have two options. First,
-% check if there is a package that your favorite \LaTeX{}
-% distributor has prepared for you. Most of the major distributions
-% (like e.g. \TexLive{} or \MikTeX{}) do so.\\
-% Second, grab the TDS package
-% from \CTAN{} \cite{CTAN} (spel.TDS.zip) and unzip it somewhere in your
-% own TDS tree, regenerate your filename database and off you go.
-% In any case, make sure that \LaTeX{} finds the file |spel.sty|.
-% \end{spelchunk}
+% \<<<{
+% If you are a normal user, check if there is a package that your
+% favorite \LaTeX{} distributor has prepared for you. Most of the
+% major distributions (like e.g. \TexLive{} or \MikTeX{}) do so.\\
+% The fallback option is to grab the |spelatex.sty| file from CTAN
+% and put it in our \TeX{} search path.
+% }
%
-% \begin{spelchunk}
+% \<<<{
% The \spelatex{} package uses a number of auxiliary packages, fetch them
% from \CTAN{} \cite{CTAN} if your \TeX{} distributor does not provide
-% them. The ones used are: |expl3|, |hyperref|, |ifthen|,
-% |fancyvrb|, |newfile|, |rotating|, |babel|, |kvoptions|.
-% \end{spelchunk}
+% them. The ones used are: |expl3|, |hyperref|, |xcolor|, |ifthen|, |verbatim|,
+% |fancyvrb|, |newfile|, |rotating|, |babel|, |kvoptions| and |xkeyval|.
+% }
%
% \subsection{The \spelpl{} speech generator}
%
% \subsubsection{The script}
-% \begin{spelchunk}
+% \<<<{
% You can install the wizard assuming you have a working Perl
% interpreter installed. Assuming you're on \GNU/Linux or MAC, you
% should be able to find an installation package using the package
% manager for your distribution. If you are on MS-Windows, look for
% Strawberry perl or ActiveState perl.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% The only thing to do is to install the |SpeL::Wizard|
% module. You can do this with the perl pacakge manager for your
% interpreter.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% Open a terminal or command window, and then enter on the
% command line (the dollar represents your prompt):
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% On \GNU/Linux and MAC: |$ cpanm SpeL::Wizard|\\
-% On Strawberry perl: |$ cpan SpeL::Wizard|\\
-% On ActiveState perl: |$ ppm install SpeL-Wizard|
-% \end{spelchunk}
+% For Strawberry perl: |$ cpan SpeL::Wizard|\\
+% For ActiveState perl: |$ ppm install SpeL-Wizard|
+% }
%
-% \begin{spelchunk}
+% \<<<{
% The script \spelpl{} will be installed on your system. Make sure
% it is on your search path.
-% \end{spelchunk}
+% }
%
% \subsubsection{The configuration file}
+%
% \begin{spelchunk}
% Finally, you need to provide \spelpl{} with an appropriate
% config-file, named |tts.conf| that sets up the text-to-speech conversion.
@@ -773,12 +732,12 @@
% \end{Verbatim}
% \end{spelchunk}
%
-% \begin{spelchunk}
+% \<<<{
% The tts configuration parameter defines the speech engine to use.
% The languagetags section defines how the babel languages are mapped to
% internationalization codes (also known as locales).
% The voices section specifies what voice to use for a specific language.
-% \end{spelchunk}
+% }
%
% \begin{spelchunk}
% An environment variable can specify where your config file is
@@ -789,12 +748,12 @@
% \end{spelchunk}
% \begin{spelchunk}
% If that variable is not set, the script will look in a subdirectory
-% |.spel_wizard| of your home-folder (or |%userprofile%| in
+% |.spel_wizard| of your home-folder (or |%userprofile%| on
% MS-Windows), or it will take the default that came with the
% |SpeL::Wizard| module.
% \end{spelchunk}
%
-% \begin{spelchunk}
+% \<<<{
% Be aware that you need to install your text-to-speech tool yourself
% according to the documentation provided by the tool provider.
% In addition, make sure it the executable is in your search path. In
@@ -802,79 +761,78 @@
% will need to get an account on their cloud platform and setup
% credentials and whatever is needed to get going. Providing
% assistance for this is beyond the aim of this manual.
-% \end{spelchunk}
+% }
%
% \subsection{The PDF viewer}
%
-% \begin{spelchunk}
-% You need to make sure you have a PDF-viewer that supports links
-% containing 'run' tags. E.g., xpdf \cite{XPDF} does not, evince
-% \cite{EVINCE} complains about security risks, but okular
-% \cite{OKULAR} and Adobe Reader \cite{ADOBEREADER} do. So does
-% PDF-XChange Viewer \cite{PDFXCHANGE}.
-% \end{spelchunk}
+% \<<<{
+% You need to make sure you have a PDF-viewer that supports file links
+% E.g., xpdf \cite{XPDF} does not, but evince \cite{EVINCE}, okular
+% \cite{OKULAR} and Adobe Reader \cite{ADOBEREADER} do.
+% }
%
% \subsection{The media player}
-% \begin{spelchunk}
+% \<<<{
% When clicking a \spelatex-enabled item in your PDF-file, your media
% player is started to play the |.ogg| or |.m3u|-file. On GNU/Linux
% most media players work fine (SoX, totem, vlc, \ldots).
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% On windows, we recommend using vlc. It works out of the box.
% When usign the stock Windows Media Player, you will need to add
% every folder that contains a PDF you'd like to have read, to your
% Media Player library. Search the internet to find instructions on
% that and be prepared: in line with Microsoft's standard practice it
% is well hidden in the interface.
-% \end{spelchunk}
+% }
+%
+% \<<<{
+% If you gave the |server| option to the \spelatex{} package, then your
+% favorite webbrowser will be started to download and play the file.
+% If you move it out of your way, you can avoid that it jumps in front of
+% your text every time again.
+% }
%
% \section{Usage}
%
% \subsection{Preparing your document source}
% \begin{spelchunk}
% Using the \spelatex{} package is very simple. Just load the package's
-% style file using an appropriate |\usepackage{spel}|.
+% style file using an appropriate |\usepackage{spelatex}|.
% \end{spelchunk}
%
-% \begin{spelchunk}
-% In case you are not using Org-mode, there are $5$ things to do:
-% \end{spelchunk}
+% \<<<{
+% There are $5$ things to do:
+% }
% \begin{enumerate}
-% \spelitem{Treat the defunct implicit spelchunks}
-% \spelitem{Treat the explicit spelchunks}
-% \spelitem{Manually provide text to read when needed}
+% \spelitem{Treat the defunct implicit spelchunks.}
+% \spelitem{Treat the explicit spelchunks.}
+% \spelitem{Manually provide text to read when needed.}
% \spelitem{Provide audiodescriptions or preprocessing instructions
-% for your typesetting macros}
+% for your typesetting macros.}
% \spelitem{Provide audiodescriptions or preprocessing instructions
-% for your typesetting environments}
+% for your typesetting environments.}
% \end{enumerate}
%
-% \begin{spelchunk}
-% Steps 1 and 2 can be done automatically for you by using Org-mode in
-% Emacs and using the proper |spel| exporter.
-% Steps 3, 4 and 5 are up to you. In this section, we assume you are
-% executing all 5 steps manually and therefore, we will explain all
-% required macros.
-% \end{spelchunk}
+% We will now explain all required macros.
%
% \subsubsection{Treat the implicit spelchunks}
-% \begin{spelchunk}
+% \<<<{
% The texts of chapter, (sub)section titles, a.s.o. will be formatted
% automatically such that they are hyperlinked to the appropriate
% audio file. Therefore, this step was not mentioned above. It is done
% automatically for you by using the \spelatex{} package.
-% \end{spelchunk}
+% }
%
-% \begin{spelchunk}
+% \<<<{
% You only need to cover your \emph{defunct implicit spelchunks}:\\
% \DescribeMacro{\spelitem}
% Use this macro instead of the \texttt{\textbackslash{}item} macro to make
% sure your list environments are converted to speech chunks
% appropriately.
-% \end{spelchunk}
+% }
%
% \begin{spelchunk}
% Example:
@@ -897,35 +855,36 @@
% \spelitem[orange]{an orange round fruit}
% \end{description}
% \end{Verbatim}
-% Note that the spel exporter in Org-mode takes care of all this
-% boilerplate work.
% \end{spelchunk}
%
% \subsubsection{Treat the explicit spelchunks}
-%
-% \begin{spelchunk}
+% \label{sec:explicitspelchunks}
+% \<<<{
% \DescribeEnv{spelchunk}
% Use this environment to embed the chunks of text in that you want
% to generate audio for. In case the content is an equation, a
% figure or a table, we recommend specifying |arealink| as the
% optional argument to the |spelchunk| environment. It makes the
% entire equation an active hyperlink.
-% \end{spelchunk}
+% Note that you cannot specify an |arealink| when the area to be covered is
+% vertical-mode object. In common language: put your |arealink| |spelchunk|
+% environments inside a |center| environment and not the other way around.
+% }
%
-% \begin{spelchunk}
+% \<<<{
% Example:\\
-% {\footnotesize (note: the example below is not \spelatex{}-enabled because it
-% generates internal package problems)}
-% \end{spelchunk}
+% {\footnotesize (note: the example below is not \spelatex{}-enabled
+% in this manual because it generates internal package problems)}
+% }
% \begin{Verbatim}
% \begin{spelchunk}
-% An orderinary paragraph must be embedded in this environment.
+% An ordinary paragraph must be embedded in this environment.
% The same holds for equations! However, then we recommend using
% the |arealink| option, as that makes the full area of the
% equation clickable and avoids an empty white line before the
% equation.
% \end{spelchunk}
-% \begin{spelchunk}[arealink]
+% \begin{spelchunk[arealink]
% \begin{align}
% E &= m c^2\\
% e^{j\pi} &= -1
@@ -952,12 +911,12 @@
%
% \begin{spelchunk}
% Example:\\
-% {\footnotesize (note: the example below is not \spelatex{}-enabled because it
+% {\footnotesize (note: the example below is again not \spelatex{}-enabled because it
% generates internal package problems)}
% \end{spelchunk}
% \begin{Verbatim}
% \begin{spelchunk}
-% An orderinary paragraph must be embedded in this environment.
+% An ordinary paragraph must be embedded in this environment.
% \end{spelchunk}
% \begin{spelchunkad}
% Do not forget to embed ordinary paragraphs in this environment.
@@ -975,7 +934,7 @@
%
% \begin{spelchunk}
% Example:\\
-% {\footnotesize (note: the example below is not \spelatex{}-enabled because it
+% {\footnotesize (note: the example below is for a third time not \spelatex{}-enabled because it
% generates internal package problems)}
% \end{spelchunk}
% \begin{Verbatim}
@@ -989,6 +948,39 @@
% \end{spelchunkad}
% \end{Verbatim}
%
+% \subsubsection{Use the shorthand \texttt{\textbackslash <<<}-macro}
+%
+% \<<<{
+% \DescribeMacro{\<<<}
+% This macro takes the text to be read-out loud as an
+% argument. It is a shorthand for the |spelchunk|
+% environment. Options you would have given to the |spelchunk|
+% environment can be given as an optional argument to this macro.
+% }
+%
+% \<<<{
+% Retaking the example of section~\ref{sec:explicitspelchunks},
+% using the shorthand, we obtain:\\
+% {\footnotesize (note: the example below is once again not \spelatex{}-enabled
+% in this manual because it generates internal package problems)}
+% }
+% \begin{Verbatim}
+% \<<<{
+% An ordinary paragraph must be embedded in this macro.
+% The same holds for equations! However, then we recommend using
+% the |arealink| option, as that makes the full area of the
+% equation clickable and avoids an empty white line before the
+% equation.
+% }
+% \<<<[arealink]{
+% \begin{align}
+% E &= m c^2\\
+% e^{j\pi} &= -1
+% \end{align}
+% }
+% \end{Verbatim}
+%
+%
% \subsubsection{Provide descriptions for typesetting macros}
%
% \DescribeMacro{\spelmacad}
@@ -1127,13 +1119,13 @@
%
% \DescribeMacro{\setdesc}
% \begin{spelchunk}
-% This macro typesets an enumeration set and makes sure \spelpl{}
+% This macro typesets a definition set and makes sure \spelpl{}
% can read it properly.
% \end{spelchunk}
% \begin{spelchunk}
% \begin{Verbatim}
% \begin{equation}
-% P = \setdesc{ n \in N \mid n \text{~is prime} }
+% P = \setdesc{ n \in \mathbb{N} \mid n \text{~is prime} }
% \end{equation}
% \end{Verbatim}
% \end{spelchunk}
@@ -1181,10 +1173,13 @@
% \begin{VerbatimOut}[gobble=4]{Example/example.tex}
% \documentclass{article}
%
-% \usepackage[dutch,english]{babel} % load babel before spel to avoid
+% \usepackage[dutch,english]{babel} % load babel before spelatex to avoid
% % option clash!
% \selectlanguage{english}
-% \usepackage[format=ogg]{spelatex}
+% \usepackage[format=ogg,
+% server=https://ctan.org/tex-archive/macros/latex/contrib/spelatex/Example
+% ]
+% {spelatex}
%
% \newrobustcmd\CTAN{CTAN}
% \spelmacad{CTAN}{see-tan}
@@ -1193,7 +1188,7 @@
%
% \title{\spelatex{} Example}
% \author{Walter Daems and Paul Levrie}
-% \date{2011/04/12}
+% \date{2024/09/09}
% \setlength\parindent{0em}
% \setlength\parskip{1ex}
%
@@ -1203,10 +1198,10 @@
%
% \section{Introduction}
%
-% \begin{spelchunk}
-% This file is just a simple showcase of the features of \spelatex.
+% \<<<{
+% This file is just a simple showcase of the features of \spelatex{}.
% Below, you'll find examples of:
-% \end{spelchunk}
+% }
%
% \begin{itemize}
% \spelitem{a simple equation}
@@ -1215,20 +1210,25 @@
%
% \section{A simple equation}
% \label{eqn:simple}
-% \begin{spelchunk}
+% \<<<{
% Consider the following simple definition of a polynomial function and
% check its spoken version by clicking on it.
-% \end{spelchunk}
-% \begin{spelchunk}[arealink]
+% }
+% \<<<[arealink]{
% \begin{equation}
-% f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 23
+% f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 25
% \end{equation}
-% \end{spelchunk}
-% \begin{spelchunk}
+% }
+% \<<<{
% This seems a simple equation, however, it is not so straightforward
% for an automated reader, to read it correctly.
-% \end{spelchunk}
+% }
%
+% \section{Remark}
+% \<<<{
+% Instead of the \texttt{\textbackslash{}<<<} macro, one can also use the
+% spelchunk environment. We did this in the next sections.
+% }
% \section{A more complex equation}
% \newcommand\xx[2]{\ensuremath{#1_{#2}}}
% \spelmacad{xx}[2]{#1 #2}
@@ -1259,8 +1259,9 @@
% y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t)
% \]
% \end{spelchunk}
-
+%
% \selectlanguage{english}
+%
% \section{And some extras}
% \subsection{Citations}
% \begin{spelchunk}
@@ -1274,6 +1275,8 @@
% section~\ref{eqn:complex}.
% \end{spelchunk}
%
+% \selectlanguage{dutch}
+%
% \bibliographystyle{alpha}
%
% \begin{thebibliography}{99}
@@ -1292,10 +1295,11 @@
%
% \end{document}
% \end{VerbatimOut}
+% \footnotesize
% \VerbatimInput[frame=lines,numbers=left,gobble=0]{Example/example.tex}
-%
+% \normalsize
% \section{Demo}
-%
+% \label{sec:demo}
% \newcommand\rd[1]{\ensuremath{\mathrm{d}#1}}
% \spelmacad{rd}[1]{d of #1}
% \newcommand\xx[2]{\ensuremath{#1_{#2}}}
@@ -1369,14 +1373,14 @@
% \begin{spelchunk}
% Euler's identity:
% \end{spelchunk}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{equation}
% e^{j \pi} + 1 = 0
% \end{equation}
% \end{spelchunk}
%
% \subsubsection{A rather well-known definite integral}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{equation}
% \int_{-\infty}^\infty e^{-x^2}\,\rd{x} = \sqrt{\pi}
% \end{equation}
@@ -1391,7 +1395,7 @@
% \begin{spelchunk}[arealink]
% \begin{align}
% P &= \setenum{ 2, 3, 5, 7, 11, 13, \ldots }\\
-% P &= \setdesc{ n \in N \mid n \text{~is prime}}
+% P &= \setdesc{ n \in \mathbb{N} \mid n \text{~is prime}}
% \end{align}
% \end{spelchunk}
%
@@ -1429,43 +1433,44 @@
% \end{spelchunk}
% \begin{figure}[h]
% \setlength{\unitlength}{4mm}
-% \begin{spelchunk}
% \begin{center}
+% \begin{spelchunk}[arealink]
% \begin{picture}(24,2)
% \put(0,0.8){$x[n]$}
% \put(2,1){\vector(1,0){3}}
% \put(5,0){\framebox(5,2){$H(z)$}}
% \put(10,1){\vector(1,0){3}}
-% \put(13,0){\framebox(5,2){$G(z) \ast F(z)$}}
+% \put(13,0){\framebox(5,2){$G(z) \cdot F(z)$}}
% \put(18,1){\vector(1,0){3}}
% \put(22,0.8){$y[n]$}
% \end{picture}
+% \end{spelchunk}
% \end{center}
-% \end{spelchunk}
% \begin{spelchunkad}
% The discrete-time input signal x is fed through a filter H of
% z. The intermediate output signal of the filter H of z is fed into
-% another filter whose transfer function is the convolution of G of
-% z and F of z. This resuspel in the discrete-time output signal y.
+% another filter whose transfer function is the product of G of
+% z and F of z. This results in the discrete-time output signal y.
% \end{spelchunkad}
% \caption{A block diagram of the filter system}
% \label{fig:blockdiagram}
% \end{figure}
%
% \subsubsection{Tables}
-% \begin{spelchunk}
-% \begin{center}
+% \<<<{Tables can also be equiped with a sensible description:}
+% \begin{center}
+% \begin{spelchunk}[arealink]
% \begin{tabular}{lcc}
% Food & Sweet & Bitter \\
% \hline
-% apple & $\bullet$ & \\
+% apples & $\bullet$ & \\
% unsweetened coffee & & $\bullet$\\
% cake & $\bullet$ & \\
% chocolate & $\bullet$ & $\bullet$ \\
% \hline
% \end{tabular}
-% \end{center}
-% \end{spelchunk}
+% \end{spelchunk}
+% \end{center}
% \begin{spelchunkad}
% This table indicates the sweetness and bitterness for several food
% products.
@@ -1481,50 +1486,46 @@
% to $\tan \alpha = -\frac{t}{2}$, the equation of the reflected
% ray is given by
% \end{spelchunk}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{equation}
% y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t)
% \end{equation}
% \end{spelchunk}
-%
% \begin{spelchunk}
% The $x$-coordinate of the point of intersection of the reflected ray
% with a fixed line $y=u$ satisfies:
% \end{spelchunk}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{equation}
% u-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t)
% \label{eqn:refray}
% \end{equation}
% \end{spelchunk}
-%
% \begin{spelchunk}
% We calculate the minimal value of this $x$ for varying $t$, by
% differentiating (\ref{eqn:refray}) with respect to $t$ and assuming
% that $\frac{\rd{x}}{\rd{t}}=0$:
% \end{spelchunk}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \[
% \frac{t}{2} = -\frac{4(4+t^2)}{(4-t^2)^2} (x-t) -
% \frac{4t}{4-t^2} \cdot (-1) \ \ \ \Leftrightarrow \ \ \ x=
% 3\frac{t}{2}-\frac{t^3}{8}
% \]
% \end{spelchunk}
-%
% \begin{spelchunk}
% Inserting in the equation containing $u$ gives us the relation
% between $t$ and $u$:
% \end{spelchunk}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \[
% u = 9- 3 \frac{t^2}{4}
% \]
% \end{spelchunk}
-%
-% \begin{spelchunk}
+%% \begin{spelchunk}
% This leads to a system of parametric equations for the caustic:
% \end{spelchunk}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \[
% \left\{\begin{array}{l}
% x = 3\frac{t}{2}-\frac{t^3}{8} \\[0.3cm]
@@ -1537,7 +1538,6 @@
% \end{array} \right.
% \]
% \end{spelchunk}
-%
% \begin{spelchunk}
% It is now easy to eliminate the parameter $t$. As you can see, $t
% = \frac{6 x}{y}$. Inserting into the equation for $y$ gives us the
@@ -1583,6 +1583,7 @@
\RequirePackage{hyperref}
\RequirePackage{xcolor}
\RequirePackage{ifthen}
+\RequirePackage{verbatim}
\RequirePackage{fancyvrb}
\RequirePackage{newfile}
\RequirePackage{rotating}
@@ -1602,7 +1603,6 @@
urlcolor=black}
\RequirePackage{kvoptions}
\RequirePackage{xkeyval}
-\RequirePackage{marginnote}
% \end{macrocode}
%
% \subsection{Options}
@@ -1613,9 +1613,10 @@
prefix=spel@
}
\DeclareStringOption[ogg]{format}
+\DeclareStringOption[local]{server}
+\DeclareStringOption[full]{markervisibility}
\DeclareBoolOption[false]{disabled}
\DeclareBoolOption[false]{extramath}
-\DeclareBoolOption[false]{propermath}
\ProcessKeyvalOptions*
% \end{macrocode}
%
@@ -1627,12 +1628,6 @@
\DeclareRobustCommand{\spelatex}{S\kern-0.3ex\raisebox{-0.1ex}{\rotatebox{-15}{p}}\kern-0.25ex\raisebox{0.1ex}{\rotatebox{10}{e}}\kern-0.1ex\LaTeX}
% \end{macrocode}
% \end{macro}
-% \begin{macro}{\spelbox}
-% This is the official \spelbox{} logo.
-% \begin{macrocode}
-\DeclareRobustCommand{\spelbox}{S\kern-0.3ex\raisebox{-0.1ex}{\rotatebox{-15}{p}}\kern-0.25ex\raisebox{0.1ex}{\rotatebox{10}{e}}\kern-0.1exLbo\raisebox{-0.2ex}{x}}
-% \end{macrocode}
-% \end{macro}
% \begin{macro}{\spelpl}
% This is the official \spelpl{} logo.
% \begin{macrocode}
@@ -1674,6 +1669,10 @@
\addtostream{spelidx}{format|\spel@format}
\addtostream{spelidx}{audiodir|\audiodir}
\addtostream{spelidx}{chunkdir|\chunkdir}
+\addtostream{spelidx}{server|\spel@server}
+\ExplSyntaxOn
+\newcommand\linksdir{\str_if_eq:VnTF{\spel@server}{local}{./\audiodir}{\spel@server/\audiodir}}
+\ExplSyntaxOff
% \end{macrocode}
%
% To ease writing to the speech index stream, we define a |\spelidxwrite|
@@ -1774,7 +1773,29 @@
\AddBabelHook{informspel}{write}{\spel@idxwrite{language}{\languagename}}
\EnableBabelHook{informspel}
% \end{macrocode}
-%
+%
+% \subsection{Setting up the visibility}
+%
+% \begin{macrocode}
+\ExplSyntaxOn
+\definecolor{faintgray}{rgb}{0.9,0.9,0.9}
+\str_if_eq:VnTF{\spel@markervisibility}{none}{
+ \colorlet{spel@color@right}{white}
+ \colorlet{spel@color@left}{white}
+}{}
+\str_if_eq:VnTF{\spel@markervisibility}{onlygroups}{
+ \colorlet{spel@color@right}{black!25}
+ \colorlet{spel@color@left}{white}
+}{}
+\str_if_eq:VnTF{\spel@markervisibility}{full}{
+ \colorlet{spel@color@right}{black!25}
+ \colorlet{spel@color@left}{black!25}
+}{}
+\ExplSyntaxOff
+% \end{macrocode}
+%
+%
+%
% \subsection{Generating speech chunks --- implicitly}
% \subsubsection{Auxiliary macros}
% We define a macro to generate wrappers for single-line text elements.
@@ -1789,7 +1810,7 @@
\expandafter\let\csname spel@@#1\expandafter\endcsname\csname #1\endcsname
\expandafter\gdef\csname #1\endcsname##1{%
\spel@chunkwrite{#1}{##1}
- \csname spel@@#1\endcsname{\href{run:\audiodir/#1.\spel@format}{##1}}
+ \csname spel@@#1\endcsname{\href{\linksdir/#1.\spel@format}{##1}}
}
\expandafter\AtBeginDocument{
\spel@idxwrite{#1}{#1}
@@ -1846,7 +1867,7 @@
\let\spel@@part\@part
\def\@part[#1]#2{%
\setcounter{spel@chunk}{0}% need this because counter resetting fails
- \spel@@part[#1]{\href{run:\audiodir/\spel@@optpart.\spel@format}{#2}}%
+ \spel@@part[#1]{\href{\linksdir/\spel@@optpart.\spel@format}{#2}}%
\spel@idxwrite{part \thepart}{\spel@@optpart}%
\spel@chunkwrite{\spel@@optpart}{#2}%
}
@@ -1863,7 +1884,7 @@
\stepcounter{spel@spart}%
\setcounter{spel@chunk}{0}% need this because counter resetting fails
\spel@@spart{%
- \href{run:\audiodir/\spel@@optpart star-\thespel@spart.\spel@format}{#1}}%
+ \href{\linksdir/\spel@@optpart star-\thespel@spart.\spel@format}{#1}}%
\spel@idxwrite{part}{\spel@@optpart star-\thespel@spart}%
\spel@chunkwrite{\spel@@optpart star-\thespel@spart}{#1}%
}
@@ -1881,7 +1902,7 @@
\def\@chapter[#1]#2{%
\setcounter{spel@chunk}{0}% need this because counter resetting fails
\spel@@chapter[#1]{%
- \href{run:\audiodir/\spel@@optpart\thechapter.\spel@format}{#2}}%
+ \href{\linksdir/\spel@@optpart\thechapter.\spel@format}{#2}}%
\spel@idxwrite{chapter \thechapter}{\spel@@optpart\thechapter}%
\spel@chunkwrite{\spel@@optpart\thechapter}{#2}%
}
@@ -1901,7 +1922,7 @@
\stepcounter{spel@schapter}%
\setcounter{spel@chunk}{0}% need this because counter resetting fails
\spel@@schapter{%
- \href{run:\audiodir/\spel@@optpart star-\thespel@schapter.\spel@format}{#1}}%
+ \href{\linksdir/\spel@@optpart star-\thespel@schapter.\spel@format}{#1}}%
\spel@idxwrite{chapter}{\spel@@optpart star-\thespel@schapter}%
\spel@chunkwrite{\spel@@optpart star-\thespel@schapter}{#1}%
}
@@ -1922,8 +1943,8 @@
\fi%
\setcounter{spel@chunk}{0}% need this because counter resetting fails
\spel@@sect{#1}{#2}{#3}{#4}{#5}{#6}[#7]{%
- \href{run:\audiodir/\spel@@optpart\thesubparagraph.\spel@format}{#8}\hfill%
- \href{run:\audiodir/\spel@@optpart\thesubparagraph.m3u}{\textcolor{black!25}{$\triangleright$}}}%
+ \href{\linksdir/\spel@@optpart\thesubparagraph.\spel@format}{#8}\hfill%
+ \href{\linksdir/\spel@@optpart\thesubparagraph.m3u}{\textcolor{spel@color@right}{$\triangleright$}}}%
\def\spel@@label{\ifnum #2>\c@secnumdepth\else#1 \csname the#1\endcsname\fi}
\spel@idxwrite{\spel@@label}{\spel@@optpart\thesubparagraph}%
\spel@chunkwrite{\spel@@optpart\thesubparagraph}{#8}%
@@ -1941,7 +1962,7 @@
\stepcounter{spel@ssect}%
%\setcounter{spel@chunk}{0}% need this because counter resetting fails
\spel@@ssect{#1}{#2}{#3}{#4}{%
- \href{run:\audiodir/\spel@@optpart\thesubparagraph-star-\thespel@ssect.\spel@format}%
+ \href{\linksdir/\spel@@optpart\thesubparagraph-star-\thespel@ssect.\spel@format}%
{#5}}%
\spel@idxwrite{section}{\spel@@optpart\thesubparagraph-star-\thespel@ssect}%
\spel@chunkwrite{\spel@@optpart\thesubparagraph-star-\thespel@ssect}{#5}%
@@ -1963,7 +1984,7 @@
\stepcounter{spel@footnote}%
\settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
\spel@@fntext{%
- \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/footnote-\thespel@footnote.\spel@format}{\usebox\spel@mptbox}#1}%
+ \hspace*{-\spel@mptboxwidth}\href{\linksdir/footnote-\thespel@footnote.\spel@format}{\usebox\spel@mptbox}#1}%
\spel@idxwrite{footnote}{footnote-\thespel@footnote}%
\spel@chunkwrite{footnote-\thespel@footnote}{#1}%
}
@@ -2004,7 +2025,7 @@
\settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
\spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
\spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1}%
- \item \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#1}
+ \item \hspace*{-\spel@mptboxwidth}\href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#1}
% \end{macrocode}
% \end{macro}
%
@@ -2017,7 +2038,7 @@
\settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
\spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
\spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1 . #2}%
-\item[#1] \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#2}
+\item[#1] \hspace*{-\spel@mptboxwidth}\href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#2}
% \end{macrocode}
% \end{macro}
%
@@ -2031,7 +2052,7 @@
\stepcounter{spel@chunk}%
\spel@idxwrite{caption}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
\spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#2}%
- \spel@@caption[#1]{\protect\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{#2}}
+ \spel@@caption[#1]{\protect\href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{#2}}
}
\fi
% \end{macrocode}
@@ -2046,7 +2067,7 @@
% \begin{macrocode}
\newlength\spel@mptboxwidth
\newsavebox\spel@mptbox
-\savebox\spel@mptbox{\textcolor{black!25}{$\qquad$}}
+\savebox\spel@mptbox{\textcolor{spel@color@left}{\quad\strut\tiny\raisebox{0.4ex}{$\triangleright$}\,}}
\newif\ifspel@chunkarealink
\define@key{spelchunk}{arealink}[]{\spel@chunkarealinktrue}
\ifspel@disabled\def\spelchunk{}\else
@@ -2061,10 +2082,10 @@
\end{VerbatimOut}%
\catcode`\^^M=5\relax%
\ifspel@chunkarealink%
- \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}}%
+ \href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}}%
\else%
\settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
- \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}%
+ \hspace*{-\spel@mptboxwidth}\href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}%
\fi%
\spel@chunkarealinkfalse%
}%
@@ -2092,6 +2113,47 @@
% \end{macrocode}
% \end{macro}
%
+% \begin{macrocode}
+\ExplSyntaxOn
+\NewDocumentCommand{\spelchunkatom}{O{}m}{
+ \stepcounter{spel@chunk}%
+ \spel@idxwrite{chunk}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
+ \setkeys{spelchunk}{#1}
+ \scantokens{
+ \makeatletter
+ \begin{spelverbatimwrite}{\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk.tex}
+ #2
+ \end{spelverbatimwrite}
+ \makeatother
+ }
+ \ifspel@chunkarealink%
+ \href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}}%
+ \else%
+ \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
+ \hspace*{-\spel@mptboxwidth}\href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}%
+ \fi%
+ \spel@chunkarealinkfalse%
+}
+
+\def\spelverbatimwrite#1{%
+ \@bsphack
+ \openoutputfile{#1}{chunk}%
+ \def\verbatim@processline{\addtostream{chunk}{\the\verbatim@line}}%
+ \let\do\@makeother\dospecials
+ \catcode`\^^M\active \catcode`\^^I=12
+ \verbatim@start}%
+\def\endspelverbatimwrite{%
+ \closeoutputstream{chunk}%
+ \@esphack%
+}
+\ifspel@disabled
+ \newcommand\<<<[2][]{#2}
+\else
+ \def\<<<{\spelchunkatom}
+\fi
+\ExplSyntaxOff
+% \end{macrocode}
+%
% \subsubsection{Explicit spelchunks}
%
% \begin{environment}{spelchunkad}
@@ -2117,6 +2179,7 @@
% \subsection{Helping the wizard to read our chunks}
%
% \subsubsection{Listing macros that are to be preprocessed}
+% \begin{macro}{\spelmacpp}
% Some \LaTeX{} or \TeX commands are only for layout purposes and are
% totally not content related. They do not contribute to what must be
% read. On the contrary, they make it hard for the \spelpl{} parser to
@@ -2130,7 +2193,6 @@
% oriented, it makes sense to provide a macro that registers them as
% pure type-setting macros and use that macro to cover the examples
% mentioned above.
-% \begin{macro}{\spelmacpp}
% \begin{macrocode}
\ExplSyntaxOn
\NewDocumentCommand{\spelmacpp}{moom}
@@ -2163,6 +2225,8 @@
\spelmacpp{textit}[1]{keep}
\spelmacpp{texttt}[1]{keep}
\spelmacpp{textbf}[1]{keep}
+\spelmacpp{mathbb}[1]{keep}
+\spelmacpp{mathcal}[1]{keep}
\spelmacpp{quad}{}
\spelmacpp{qquad}{}
\spelmacpp{displaystyle}{}
@@ -2179,6 +2243,7 @@
% \end{macrocode}
%
% \subsubsection{Listing environments that are to be ignored}
+% \begin{macro}{\spelenvpp}
% Some \LaTeX{} or \TeX environments are only for layout purposes and are
% totally not content related. They do not contribute to what must be
% read. On the contrary, they make it hard for the \spelpl{} parser to
@@ -2191,7 +2256,6 @@
% oriented, it makes sense to provide a macro that registers them as
% pure type-setting macros and use that macro to cover the examples
% mentioned above.
-% \begin{macro}{\spelenvpp}
% \begin{macrocode}
\ExplSyntaxOn
\NewDocumentCommand{\spelenvpp}{moom}
@@ -2240,7 +2304,6 @@
% ignored:
% \begin{macrocode}
\spelmacad{spelatex}{spee-lay-tech}
-\spelmacad{spelbox}{spel-box}
\spelmacad{spelpl}{spel wizzard dot pl}
\spelmacad{LaTeX}{lay-tech}
\spelmacad{TeX}{tech}
@@ -2335,7 +2398,7 @@
%
% \section{TODO}
% \begin{spelchunk}[arealink]
-% As long as there are things on my todo list, We have a reason to
+% As long as there are things on our todo list, we have a reason to
% live.
% \end{spelchunk}
% \begin{itemize}
@@ -2374,22 +2437,6 @@
% \newblock \url{https://www.winehq.org}
% \newblock online, accessed in June 2024.
%
-% \bibitem{ORGMODE}
-% Org Mode --- your life in plain text.
-% \newblock \url{https://orgmode.org/}.
-% \newblock online, accessed in May 2024.
-%
-% \bibitem{EMACS}
-% The Emacs An extensible, customizable, free text editor --- and
-% more.
-% \newblock \url{https://www.gnu.org/software/emacs/}.
-% \newblock online, accessed in May 2024.
-%
-% \bibitem{OXSPELATEX}
-% Org Mode SpeLaTeX Exporter --- SpeLaTeX made easy.
-% \newblock \url{https://www.melpa.org/#/ox-spelatex}
-% \newblock (not yet online)
-%
% \bibitem{SPEL}
% SpeL --- Speech-enabled \LaTeX.
% \newblock \url{https://ctan.org/pkg/spel}
@@ -2445,11 +2492,6 @@
% \newblock \url{https://okular.kde.org}.
% \newblock online, accessed in May 2024.
%
-% \bibitem{PDFXCHANGE}
-% PDF XChange Viewer, a PDF reader from Tracker Software.
-% \newblock \url{https://www.pdf-xchange.com/}
-% \newblock online, accessed in May 2024.
-%
% \end{thebibliography}
%
% \Finale