% \iffalse meta-comment
%
% Copyright (C) 2024 by Walter Daems <walter.daems@uantwerpen.be>
%                   and Paul Levrie
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.3 of this license
% or (at your option) any later version.  The latest version of this
% license is in:
% 
%    http://www.latex-project.org/lppl.txt
% 
% and version 1.3 or later is part of all distributions of LaTeX version
% 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
% 
% The Current Maintainer of this work is Walter Daems.
%
% 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
%<*package>
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{spelatex}
%</package>
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\ProvidesFile{spelatex.dtx}
%</driver>
%<*package>
   [2024/06/21 v0.91 SpeLaTeX - Speech-enabled LaTeX (DMW and LVP)]
%</package>
\def\fileversion{0.91}
\def\filedate{2024/06/21}
%<*driver> 
\documentclass[10pt]{ltxdoc}
\usepackage{makeidx}
\usepackage{alltt}
\usepackage[english]{babel}
\usepackage[extramath]{spelatex}
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{tikz}
\IfFileExists{tocbibind.sty}{\usepackage{tocbibind}}{}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\StopEventually{\PrintChanges\PrintIndex}
\spelmacad{DescribeEnv}[1]{#1}
\spelmacad{DescribeMacro}[1]{#1}
\begin{document}
 \DocInput{spelatex.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v0.90}{2024/05/31}{. Birth}
% \changes{v0.91}{2024/06/21}{. First overhaul:\\
%                               - avoided big active link areas\\
%                               - sketched bigger picture, leading to
%                               the three project phases.}
% 
% \GetFileInfo{spelatex.dtx}
%
% \DoNotIndex{\newcommand,\newenvironment}
% \setlength{\parindent}{0em}
% \addtolength{\parskip}{0.5\baselineskip}
%
% \title{\sf \spelatex{} --- Speech-enabled \LaTeX{}}
% \author{Walter Daems (\texttt{walter.daems@uantwerpen.be})
%         and Paul Levrie}
% \date{\fileversion --- \filedate}
%
% \newrobustcmd\GNU{GNU}
% \spelmacad{GNU}{gnew}
% \newrobustcmd\TexLive{Tex Live}
% \spelmacad{TexLive}{tech-laaiv}
% \newrobustcmd\MikTeX{MikTeX}
% \spelmacad{MikTeX}{miktech}
% \newrobustcmd\CTAN{CTAN}
% \spelmacad{CTAN}{see-tan}
% \newrobustcmd\CPAN{CPAN}
% \spelmacad{CPAN}{see-pan}
% \newrobustcmd\POD{POD}
% \spelmacad{POD}{pod}
%
% \maketitle
% \fvset{gobble=2}
%
% \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}
%   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
%   assignments. However, for bigger texts (like course syllabi) this
%   is beyond the time a teacher 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
%   electronic documents, e.g. NVDA \cite{NVDA} or
%   SprintPlus~\cite{SPRINT}. Moreover, more and more standard PDF
%   readers (such  
%   as Acrobat Reader~\cite{ADOBEREADER} have the facility of
%   performing text-to-speech). For nontechnical subjects, this works
%   fine. However, when it comes to technical course syllabi that are
%   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
%   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
%   still some gaps:
% \end{spelchunk}
% \begin{itemize}
% \spelitem{The tagpdf package is still not a part of the mainstream
% \LaTeX{}-kernel.}
% \spelitem{MathML reading support in PDF readers is still in its
% infancy.}
% \spelitem{Many PDF readers do not fully support tags yet.}
% \end{itemize}
%
% \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
%   PDF with hyperlinks to these files, such that with a few clicks
%   you can listen to your document.
%   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
%   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
% 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.}
% \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
%   solution. We especially would like to thank Ulrike Fischer (of the
%   \LaTeX-project and the maintainer of the tagpdf package) for
%   trying to use this package and reaching out to give us feedback.
%   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}
%   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
%   for a better speech-enabled \LaTeX{}.
% \end{spelchunk}
%
% \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}
%    \begin{itemize}
%      \spelitem{persons who still can recognize the basic
%      parts of a book,
%        i.e. are able to operate a PDF viewer and click on the
%        individual parts.}
%      \spelitem{persons who can't recognize the basic parts of a book
%      (e.g., blind persons): they can listen to the automatic
%      playback of the ordered chain of audio fragments.}
%    \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}
% 
% \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}
%   By loading the |spel.sty| package in  your source
%   document, \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
%   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
%   to previously generated fingerprints for the chunk. If the
%   finger print 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,
%   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{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);
%       \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{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
%   are aware that these regions are active, you'll find them
%   easily. In addition, not using the full paragraph as an active
%   region, allows existing hyperlinks (like for citations, references
%   or URLs) to still function.}
% \end{itemize}
%
%
% \subsubsection{Implicit spelchunks}
% \spelmacad{usepackage}[1]{the usepackage #1 macro}
% \spelmacad{title}{the title macro}
% \spelmacad{author}{the author macro}
% \spelmacad{section}{the section macro}
% \spelmacad{caption}{the caption macro}
% \spelmacad{footnote}{the footnote macro}
% \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|,
%   |\caption|, |\footnote|, |\thanks|), these macros have been
%   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
%   that follows as a first explicit argument, i.e. |\item blabla|
%   should be replaced by |\spelitem{blabla}|.
%   We call these \LaTeX-fragments \emph{defunct implicit
%   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
%   this, and we've chosen to treat displaymath environments (like
%   |equation|, |eqnarray|, |gather|, |align|, |alignat|) the same way
%   as tables or figures, i.e. you need to embed the in a |spelchunk|
%   environment. The only difference between math environments and
%   figures an tables is that displaymath environments can be
%   automatically read out loud by the \spelpl{} script, while you
%   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}
% \begin{itemize}
% \spelitem{automatic: \texttt{equation}, \texttt{eqnarray},
% \texttt{gather}, \texttt{align}, \texttt{alignat}, \ldots} 
% \spelitem{manual: \texttt{figure}, \texttt{table},
% \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
%   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}
%
% \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
%   are one of the silent features that are 
%   not easily accessible from within a \LaTeX-package.
%   Therefore paragraphs (or smaller text chunks) are considered to be
%   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}
%
% \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}
% \spelitem[\texttt{\textbackslash{}setdesc}]{a command to define a
% set that is specified using a description}
% \end{description}
%
%
% \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})
%     and a royalty-free audio format and player (like for example
%     ogg-vorbis), generating audio-enabled documents only requires
%     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}.\\
%     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
%     like and are used to, without you having to worry about license
%     costs. They might even use an AI-generated copy of their own
%     voice!}
%   \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.}
%   \spelitem[Math capable]{
%     Try some of the equations in this manuscript. 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}
%
% \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}
%
% \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}
%
% \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.
% Below you can find a setup for Festival \cite{FESTIVAL}:
% \begin{Verbatim}
%   [engine]
%   tts=festival
%   
%   [languagetags]
%   dutch=nl
%   english=en-gb
%
%   [voices]
%   dutch=nl1_mbrola
%   english=en1_mbrola
% \end{Verbatim}
% \end{spelchunk}
%
% \begin{spelchunk}
% And additionally, for the Microsoft users a setup for Balabolka \cite{BALABOLKA}:
% \begin{Verbatim}
%   [engine]
%   tts=balabolka
%   
%   [languagetags]
%   english=en-us
%
%   [voices]
%   english=Zira
% \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
% located, e.g., on \GNU/Linux:
% \begin{Verbatim}
%   $ export SPELWIZARD_CONFIG=/home/wdaems/.config/tts.conf
% \end{Verbatim}
% \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
%   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
%   case you are using an online text-to-speech service provider you
%   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}
%
% \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}
%
% \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}|.
% \end{spelchunk}
%
% \begin{spelchunk}
%   In case you are not using Org-mode, there are $5$ things to do:
% \end{spelchunk}
% \begin{enumerate}
%   \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} 
%   \spelitem{Provide audiodescriptions or preprocessing instructions
%   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}
%
% \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:
% \begin{Verbatim}
%   We like
%   \begin{itemize}
%     \spelitem{apples,}
%     \spelitem{pears, and}
%     \spelitem{oranges.}
%   \end{itemize}
% \end{Verbatim}
% \end{spelchunk}
% \begin{spelchunk}
%   Another example:
% \begin{Verbatim}
%   If you don't know these fruits:
%   \begin{description}
%     \spelitem[apple]{a green round fruit}
%     \spelitem[pears]{a green pointy-shaped fruit}
%     \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}
%   \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}
%
% \begin{spelchunk}
%   Example:\\
%   {\footnotesize (note: the example below is not \spelatex{}-enabled because it
%   generates internal package problems)}
% \end{spelchunk}
% \begin{Verbatim}
%   \begin{spelchunk}
%     An orderinary 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{align}
%       E &= m c^2\\
%       e^{j\pi} &= -1
%     \end{align}
%   \end{spelchunk}
% \end{Verbatim}
%
%
% \subsubsection{Manually provide text to read when needed}
% \begin{spelchunk}
%   \DescribeEnv{spelchunkad}
%   If you want a different text to be used for the previous
%   spelchunk environment, this environment allows you to specify it.
%   For plain text or math environments, this is also your generic escape
%   route in case the \spelpl{} parser does not work as you'd like
%   it to.\\
% \end{spelchunk}
% \begin{spelchunk}
%   Just have your |spelchunk| environment followed by a
%   |spelchunkad| environment that specifies the correct text to read
%   out loud. However, please, file a bug report, such that we can
%   improve the tool.
% \end{spelchunk}
%
% \begin{spelchunk}
%   Example:\\
%   {\footnotesize (note: the example below is not \spelatex{}-enabled because it
%   generates internal package problems)}
% \end{spelchunk}
% \begin{Verbatim}
%   \begin{spelchunk}
%     An orderinary paragraph must be embedded in this environment.
%   \end{spelchunk}
%   \begin{spelchunkad}
%     Do not forget to embed ordinary paragraphs in this environment.
%   \end{spelchunkad}
% \end{Verbatim}
%
% \begin{spelchunk}
%   For non-textual material such as figures or tables, this allows you
%   to specify a sensible text that acts as an audio description for
%   that material.\\
%   Just have your |spelchunk| environment that surrounds your figure
%   or table, followed by a |spelchunkad| environment that provides
%   the audio description for the non-textual material.
% \end{spelchunk}
% 
% \begin{spelchunk}
%   Example:\\
%   {\footnotesize (note: the example below is not \spelatex{}-enabled because it
%   generates internal package problems)}
% \end{spelchunk}
% \begin{Verbatim}
%   \begin{spelchunk}
%     \includegraphics{engine.jpg}  
%   \end{spelchunk}
%   \begin{spelchunkad}
%     The image shows a turbo-fan engine of an aircraft. One can
%     clearly see the silver blades of the fan, and the housing. Note
%     how little spacing there is between the blades and the housing.
%   \end{spelchunkad}
% \end{Verbatim}
%
% \subsubsection{Provide descriptions for typesetting macros}
%
% \DescribeMacro{\spelmacad}
% \begin{spelchunk}
%   Often, recurring constructs are being typeset using a dedicated
%   macro, defined by the user.
%   For example, to consistently typeset input voltages for arbitrary pins,
%   one might have defined the macro:
% \begin{Verbatim}
%   \newcommand\vin[2][IN]{\ensuremath{v_{\mathit{#1},#2}}}
% \end{Verbatim}
% \end{spelchunk}
% \newcommand\vin[2][IN]{\ensuremath{v_{\mathit{#1},#2}}}%
% \spelmacad{vin}[2][IN]{the #1put voltage at pin #2}%
% \begin{spelchunk}
%   This allows easy specification of
% \begin{Verbatim}
%   \vin{1} = \sin 20 t
% \end{Verbatim}
% resulting in $\vin{1} = \sin 20 t$.
% \end{spelchunk}
%
% \begin{spelchunk}
%   However one might want this line to be read as 'the input voltage
%   at pin 1 equals sine 20 t'.\\
%   To this end, one can provide an description for this macro
%   using the |spelmacad| macro.
% \end{spelchunk}
%
% \begin{spelchunk}
%   Example:
% \begin{Verbatim}
%   \spelmacad{vin}[1][IN]{the #1put voltage at pin #2}
% \end{Verbatim}
%   Note that the audio description in this case will only be
%   acceptable, for arguments IN and OUT. One clearly has to take the
%   audio description into account when defining \LaTeX{}-macros.
% \end{spelchunk}
%
% \subsubsection{Descriptions for typesetting environments}
%
% \DescribeMacro{\spelenvad}
% \begin{spelchunk}
%   Often, recurring constructs are being typeset using a dedicated
%   environment, defined by the user.
%   For example, to consistently typeset a proof or illustration one might
%   have defined the environment: 
% \begin{Verbatim}
%   \newenvironment{proof}[2][Proof]{
%     \textbf{#1: #2}\\
%   }
%   {
%     \hfill$\blacksquare$\\
%   }
% \end{Verbatim}
% \end{spelchunk}
% \begin{spelchunk}
%   This allows easy specification of an illustration as:
% \begin{Verbatim}
%   \begin{proof}[Illustration]{solving a quadratic equation}
%     blabla
%   \end{proof}
% \end{Verbatim}
% \end{spelchunk}
% \begin{spelchunk}
%   However one might want this environment to be read as
%   'Illustration of solving a quadratic equation: blabla. This
%   concludes this illustration.'\\
%   To this end, one can provide an description for this macro
%   using the |spelenvad| macro.
% \end{spelchunk}
%
%
% \begin{spelchunk}
%   Example:
% \begin{Verbatim}
%   \spelenvad{proof}[1][Illustration]
%   {#1 of #2:}
%   {This concludes this #1.}
% \end{Verbatim}
% \end{spelchunk}
%
% \subsubsection{Using the i18n features of \spelpl when describing
% your macros and environments}
% \begin{spelchunk}
%   Sooner rather than later you will feel the need to provide reading
%   alternatives for your constructs that are language dependent. In
%   that case you can call the i18n features that are built into
%   \spelpl. We illustrate this with an example.
% \end{spelchunk}
%
% \begin{spelchunk}
%   Assume you've made your own command to raise numbers to a power,
%   and you provide and description for your macro.
% \end{spelchunk}
% \begin{Verbatim}
%   \newcommand\numtopower[2]{#1^{#2}}
%   \spelmacad{numtopower}[2]{#1 to the power of #2}
% \end{Verbatim}
% 
% \begin{spelchunk}
%   The problem with this solution is, that it only works for one
%   language. The solution is to use an i18n expression in your
%   description: 
% \end{spelchunk}
% \begin{Verbatim}
%   \spelmacad{numtopower}[2]{#1 @{i18n(Power,#2)}}
% \end{Verbatim}
% \begin{spelchunk}
%    This will call the maketext function (See Locale::Maketext) on
%    the Lexicon provided in SpeL::Wizard::I18n, as:
% \end{spelchunk}
% \begin{Verbatim}
%   $SpeL::Wizzard::I18n::lh->maketext( 'Power', "#2")
% \end{Verbatim}
% \begin{spelchunk}
%   to read your macro.
% \end{spelchunk}
%
% \subsubsection{The extra math commands}
% Note that these commands are only available if you provide the
% package option |extramath|.
%
% \DescribeMacro{\setenum}
% \begin{spelchunk}
%   This macro typesets an enumeration set and makes sure \spelpl{}
%   can read it properly.
% \end{spelchunk}
% \begin{spelchunk}
% \begin{Verbatim}
%   \begin{equation}
%     P = \setenum{ 2, 3, 5, 7, 11, 13, \ldots }
%   \end{equation}
% \end{Verbatim}
% \end{spelchunk}
%
% \DescribeMacro{\setdesc}
% \begin{spelchunk}
%   This macro typesets an enumeration 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} }
%   \end{equation}
% \end{Verbatim}
% \end{spelchunk}
%
% \subsection{Going through the flow}
% \begin{spelchunk}
%   Once your document source has been prepared, you are ready for the
%   regular \spelatex-flow. It consists of 3 steps.
% \end{spelchunk}
%
% \begin{enumerate}
%   \spelitem{Create a \texttt{jobname-spel} subdirectory in the
%   working directory your \LaTeX{} source document is in (replace
%   jobname with the basename of your latex file, the final
%   \texttt{-spel} is a literal).}
%   \spelitem{Run your document
%   3-times through your \{pdf,Xe,Lua\}\LaTeX{}-compiler to get all
%   the references right.}
%   \spelitem{Run the \spelpl{} speech
%   generator (see scripts directory or the wrapper provided by the
%   package manager), by launching it with the base name of your
%   document as command-line
%   argument.\\
%   E.g.: \texttt{\spelpl{} -v example}}\\
%   The |-v| argument causes the script to be somewhat more verbose.
% \end{enumerate}
% 
% \begin{spelchunk}
%   The result of this will be a PDF file equipped with links to audio
%   files in the 'speech' subdirectory. Alas your PDF file has been
%   become a little less portable, as it now requires the 'speech'
%   subdirectory to be complete. You might want to package the
%   ensemble into a tar-file or zip-archive.
% \end{spelchunk}
%
%%
% \section{Example}
%
% \begin{spelchunk}
%   Below, you can find a simple example to give you a head-start.
%   In order not to spoil the fun for you, the embedded version here
%   is not speech-enabled.
% \end{spelchunk}
%
% \begin{VerbatimOut}[gobble=4]{Example/example.tex}
%   \documentclass{article}
%   
%   \usepackage[dutch,english]{babel}   % load babel before spel to avoid
%                                       % option clash!
%   \selectlanguage{english}
%   \usepackage[format=ogg]{spelatex}
%
%   \newrobustcmd\CTAN{CTAN}
%   \spelmacad{CTAN}{see-tan}
%   \newrobustcmd\CPAN{CPAN}
%   \spelmacad{CPAN}{see-pan}
%
%   \title{\spelatex{} Example}
%   \author{Walter Daems and Paul Levrie}
%   \date{2011/04/12}
%   \setlength\parindent{0em}
%   \setlength\parskip{1ex}
%
%   \begin{document}
%   
%   \maketitle
%   
%   \section{Introduction}
%
%   \begin{spelchunk}
%     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}
%     \spelitem{a more complex equation}
%   \end{itemize}
%
%   \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]
%     \begin{equation}
%       f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 23
%     \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{A more complex equation}
%   \newcommand\xx[2]{\ensuremath{#1_{#2}}}
%   \spelmacad{xx}[2]{#1 #2}
%
%   \label{eqn:complex}
%   \begin{spelchunk}
%     For a lightray that hits the parabola at the point
%     $P(t,9-\frac{t^2}{4})$, the reflected ray has slope $\tan 2\alpha$.
%     Since the slope of the tangent to the parabola at $P$ is
%     equal to $\tan\alpha = -\frac{t}{2}$, the equation of the
%     reflected ray is given by
%   \end{spelchunk}
%   \begin{spelchunk}[arealink]
%     \[
%     y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t)
%     \]
%   \end{spelchunk}
%
%   \selectlanguage{dutch}
%   \section{Een andere taal}
%   \begin{spelchunk}
%   \spelatex{} is ook volledig babel-actief, wat wil zeggen dat de
%   voorleesstem de geselecteerde taal zal volgen.
%   \end{spelchunk}
%
%   \begin{spelchunk}[arealink]
%     \[
%     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}
%   Two excellent repositories are \CPAN{} \cite{CPAN} and \CTAN{} \cite{CTAN}.
%   \end{spelchunk}
% 
%   \subsection{References to labels}
%   \begin{spelchunk}
%   Section~\ref{eqn:simple} contains an illustration of a simple
%   equation. For a more complex equation, we refer the user to
%   section~\ref{eqn:complex}.
%   \end{spelchunk}
%
%   \bibliographystyle{alpha}
%
%   \begin{thebibliography}{99}
%
%   \bibitem{CTAN}
%   The Comprehensive \TeX{} Archive Network.
%   \newblock \url{http://www.ctan.org}.
%   \newblock online, accessed in August 2021.
%
%   \bibitem{CPAN} 
%   The Comprehensive Perl Archive Network.
%   \newblock \url{http://www.cpan.org}.
%   \newblock online, accessed in August 2021.
%
%   \end{thebibliography}
%
%   \end{document}
% \end{VerbatimOut}
% \VerbatimInput[frame=lines,numbers=left,gobble=0]{Example/example.tex}
%
% \section{Demo}
%
% \newcommand\rd[1]{\ensuremath{\mathrm{d}#1}}
% \spelmacad{rd}[1]{d of #1}
% \newcommand\xx[2]{\ensuremath{#1_{#2}}}
%
% \begin{spelchunk}
%   The examples below have been composed and used to test the math
%   reading capabilities of \spelatex{} and \spelpl. The source code has not
%   been made visible in this document. If you'd like to see the
%   source code, check the original |.dtx|-file that was used to
%   generate this PDF-file.
% \end{spelchunk}
% 
% \subsection{Numbers}
% \begin{spelchunk}[arealink]
%   \begin{align}
%     \pi\\
%     -31415\\
%     1.25\\
%     -0.34 \times 10^{4}\\
%     12 - j 3\\
%     -31415.23 + .45i
%   \end{align}
% \end{spelchunk}
% 
%
% \subsection{Fractions}
% \subsubsection{A fraction only containg numbers}
% \begin{spelchunk}[arealink]
%   \begin{align}
%     x &= - \frac{1}{2} \\
%     y &= - \sqrt{\frac{\pi}{2}}
%   \end{align}
% \end{spelchunk}
%
% \subsubsection{A fraction with a little more under the hood}
% \begin{spelchunk}[arealink]
%   \begin{align}
%     u &= - \frac{x^2+35}{\sqrt{12}} \\
%     v &= - \frac{\sqrt{\frac{\pi}{2}}}{-3x^2+3}
%   \end{align}
% \end{spelchunk}
%
%
% \subsection{Simple expressions}
% \subsubsection{A polynomial function}%
% \begin{spelchunk}[arealink]
%   \begin{equation}
%     f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 23
%   \end{equation}
% \end{spelchunk}
%
% \subsubsection{Some more complex equations}
% \begin{spelchunk}
%   Here's de Moivre's formula:
% \end{spelchunk}
% \begin{spelchunk}[arealink]
%   \begin{equation}
%     \left(\cos x+j\sin x\right)^n=\cos(nx)+j\sin(nx)
%   \end{equation}
% \end{spelchunk}
%
% \begin{spelchunk}
% Euler's relationship:
% \end{spelchunk}
% \begin{spelchunk}[arealink]
%   \begin{equation}
%     e^{j \phi} = \cos \phi + j \sin \phi
%   \end{equation}
% \end{spelchunk}
%
% \begin{spelchunk}
% Euler's identity:
% \end{spelchunk}
% \begin{spelchunk}
%   \begin{equation}
%     e^{j \pi} + 1 = 0
%   \end{equation}
% \end{spelchunk}
%
% \subsubsection{A rather well-known definite integral}
% \begin{spelchunk}
%   \begin{equation}
%     \int_{-\infty}^\infty e^{-x^2}\,\rd{x} = \sqrt{\pi}
%   \end{equation}
% \end{spelchunk}
%
% \subsection{Sets}
% \begin{spelchunk}
%   Let's check the two set commands this package provides:
%   \texttt{\textbackslash{}setenum} and
%   \texttt{\textbackslash{}setdesc}: 
% \end{spelchunk}
% \begin{spelchunk}[arealink]
% \begin{align}
%     P &= \setenum{ 2, 3, 5, 7, 11, 13, \ldots }\\
%     P &= \setdesc{ n \in N \mid n \text{~is prime}}
% \end{align}
% \end{spelchunk}
%
% \subsection{Matrices}
% \begin{spelchunk}
%   How about some linear algebra?
% \end{spelchunk}
% \begin{spelchunk}[arealink]
%   \begin{align}
%     \begin{bmatrix}
%        3 & 4 \\
%        7 & 2
%     \end{bmatrix}
%     \cdot
%     \begin{bmatrix}
%        x \\ y
%     \end{bmatrix}
%     &= 
%     \begin{bmatrix}
%        1 \\ 0
%     \end{bmatrix}\\
%     \begin{vmatrix}
%        3 & 4 \\
%        7 & 2
%     \end{vmatrix}
%     &= -22
%   \end{align}
% \end{spelchunk}
% 
% \subsection{Figures and Tables}
% \subsubsection{Figures}
% \begin{spelchunk}
%   The example Fig.~\ref{fig:blockdiagram} illustrates the voice-aid
%   that can be added to figures.
% \end{spelchunk}
% \begin{figure}[h]
% \setlength{\unitlength}{4mm}
% \begin{spelchunk}
% \begin{center}
%   \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(18,1){\vector(1,0){3}}
%     \put(22,0.8){$y[n]$}
%   \end{picture}
% \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.
% \end{spelchunkad}
% \caption{A block diagram of the filter system}
% \label{fig:blockdiagram}
% \end{figure}
%
% \subsubsection{Tables}
% \begin{spelchunk}
%   \begin{center}
%     \begin{tabular}{lcc}
%       Food                   & Sweet     & Bitter \\
%       \hline
%       apple                  & $\bullet$ & \\ 
%       unsweetened coffee     &           & $\bullet$\\
%       cake                   & $\bullet$ & \\
%       chocolate              & $\bullet$ & $\bullet$ \\
%       \hline
%     \end{tabular}
%   \end{center}
% \end{spelchunk}
% \begin{spelchunkad}
%   This table indicates the sweetness and bitterness for several food
%   products.
%   It lists apples that are (sweet); unsweetened coffee which is
%   bitter; cake which is sweet and chocolate that is both sweet and bitter.
% \end{spelchunkad}
% \subsection{A parabola tale}
%
% \begin{spelchunk}
%   For a lightray that hits the parabola at the point
%   $P(t,9-\frac{t^2}{4})$, the reflected ray has slope $\tan 2\alpha$.
%   Since the slope of the tangent to the parabola at $P$ is equal
%   to $\tan \alpha = -\frac{t}{2}$, the equation of the reflected
%   ray is given by
% \end{spelchunk}
% \begin{spelchunk}
%   \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{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}
%   \[
%   \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}
%   \[
%   u = 9- 3 \frac{t^2}{4}
%   \]
% \end{spelchunk}
%
% \begin{spelchunk}
%   This leads to a system of parametric equations for the caustic:
% \end{spelchunk}
% \begin{spelchunk}
%   \[
%   \left\{\begin{array}{l}
%       x = 3\frac{t}{2}-\frac{t^3}{8} \\[0.3cm]
%       y = 9- 3 \frac{t^2}{4}
%     \end{array} \right.
%   \quad \Leftrightarrow \quad
%   \left\{\begin{array}{l}
%       x = \frac{t}{2} \cdot (3 -\frac{t^2}{4}) \\
%       y = 3(3- \frac{t^2}{4})
%     \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
%   equation of Tschirnhausen's cubic.
% \end{spelchunk}
%
%
% \section{Implementation}
% \begin{spelchunk}
%   To ease the implementation work and because raw \LaTeX{} code is
%   difficult to read on itself, We took the liberty of not providing
%   this section with speech chunks (except for this introduction
%   text).
% \end{spelchunk}
%
% \iffalse
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
% \fi
%
% \subsection{Design principles}
%
% \spelatex{} has been developed using the following main targets in
% mind. Some of them are common sense design principles, some of them
% are specific for this application.
% \begin{itemize}
%   \item minimal effort in preparing a \LaTeX{} manuscript for use with
%     \spelatex{}
%   \item maximal compatibility with existing \LaTeX{} packages
%   \item no (or minimal) compromise mathematical reading capabilities
%     for mathematical constructs
%   \item user extensible audio preprocessor
%   \item minimal use of processing power for text to speech conversion
% \end{itemize}
% 
% 
% \subsection{Auxiliary Packages}
% The \spelatex{} package uses some basic auxiliary packages to make life
% easy.
%    \begin{macrocode}
\RequirePackage{expl3}
\RequirePackage{hyperref}
\RequirePackage{xcolor}
\RequirePackage{ifthen}
\RequirePackage{fancyvrb}
\RequirePackage{newfile}
\RequirePackage{rotating}
\RequirePackage{babel}
\hypersetup{backref=true,
            breaklinks=true,
            colorlinks=true,
            citecolor=black,
            filecolor=black,
            hyperindex=true,
            linkcolor=black,
            pageanchor=true, 
            pagebackref=true,
            pagecolor=black,
            pdfpagemode=UseOutlines,
            bookmarksopen=true,
            urlcolor=black}
\RequirePackage{kvoptions}
\RequirePackage{xkeyval}
\RequirePackage{marginnote}
%    \end{macrocode}
%
% \subsection{Options}
%
%    \begin{macrocode}
\SetupKeyvalOptions{
  family=spel,
  prefix=spel@
}
\DeclareStringOption[ogg]{format}
\DeclareBoolOption[false]{disabled}
\DeclareBoolOption[false]{extramath}
\DeclareBoolOption[false]{propermath}
\ProcessKeyvalOptions*
%    \end{macrocode}
%
% \subsection{Logos}
% Vanity is everything, so let's make some logoware.
% \begin{macro}{\spelatex}
%   This is the official \spelatex{} logo.
%    \begin{macrocode}
\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}
\DeclareRobustCommand{\spelpl}{\texttt{spel-wizard.pl}}
%    \end{macrocode}
% \end{macro}
% 
% \subsection{The speech stream}
% The basic structural elements of a document (title, chapters,
% sections, \ldots) are written to the speech index stream. This is a
% textfile that has the same base name as your \LaTeX{} job and has
% extension |.spelidx|. 
% 
% It is the index to the chunks of text that are written to the speech
% directory.
%
% The |.spelidx| file requires postprocessing by the \spelpl{}
% script in order to obtain the required audio files.
% 
% The speech stream needs to be open before the preamble's title,
% author and date.
%    \begin{macrocode}
\newoutputstream{chunk}
\newoutputstream{spelidx}
\openoutputfile{\jobname.spelidx}{spelidx}
%    \end{macrocode}
% The stream needs to be closed upon termination of the document.
%    \begin{macrocode}
\AtEndDocument{
  \closeoutputstream{spelidx}%
}
%    \end{macrocode}
%
% To begin with, we write the standard locations for audio and chunk
% data to the |.spelidx| file.
%    \begin{macrocode}
\newcommand\audiodir{\jobname-spel}
\newcommand\chunkdir{\jobname-spel}
\addtostream{spelidx}{format|\spel@format}
\addtostream{spelidx}{audiodir|\audiodir}
\addtostream{spelidx}{chunkdir|\chunkdir}
%    \end{macrocode}
% 
% To ease writing to the speech index stream, we define a |\spelidxwrite|
% function to take care of appropriate formatting.
% \begin{macro}{\spel@idxwrite}
%   This is an internal macro, used to write information to the |.spelidx|
%   file and to a correspondig chunk file.
%    \begin{macrocode}
\ifspel@disabled\newcommand{\spel@idxwrite}[2]{}\else
\newcommand{\spel@idxwrite}[2]{%
  \typeout{spel: Generating #1 - #2}%
  \addtostream{spelidx}{#1|#2}%
}
\fi
%    \end{macrocode}
% \end{macro}
%
% To ease writing speech chunk, we define a |\spel@chunkwrite|
% function.
% \begin{macro}{\spel@chunkwrite}
%   This is an internal macro, used to write information to the speech chunk
%   files.
%    \begin{macrocode}
\ifspel@disabled\newcommand{\spel@chunkwrite}[2]{}\else
\newcommand{\spel@chunkwrite}[2]{%
  \openoutputfile{\audiodir/#1.tex}{chunk}%
  \addtostream{chunk}{#2}%
  \closeoutputstream{chunk}%
}
\fi
%    \end{macrocode}
% \end{macro}
%
% \subsection{Create missing counters}
% As we need to be able to fully identify every speech chunk, we need
% to provide some missing counters for the starred versions of the
% sectioning commands.
%
% \begin{macro}{spel@spart} counter
%    \begin{macrocode}
\newcounter{spel@spart}
\renewcommand\thespel@spart{\@arabic\c@spel@spart}
\setcounter{spel@spart}{0}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{spel@schapter} counter
%    \begin{macrocode}
\ifx\c@chapter\@undefined
\else
\ifx\c@part\@undefined
\newcounter{spel@schapter}
\else
\newcounter{spel@schapter}[part]
\fi
\renewcommand\thespel@schapter{\@arabic\c@spel@schapter}
\setcounter{spel@schapter}{0}
\fi
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{spel@ssect} counter
%    \begin{macrocode} 
\ifx\c@chapter\@undefined
\newcounter{spel@ssect}
\else
\newcounter{spel@ssect}[chapter]
\fi
\renewcommand\thespel@ssect{\@arabic\c@spel@ssect}
\setcounter{spel@ssect}{0}
%    \end{macrocode}
% \end{macro}
%
% In addition, some elements that are not canonically numbered require
% a unique and monotonous numbering.
% \begin{macro}{spel@footnote} counter
%    \begin{macrocode}
\newcounter{spel@footnote}
\renewcommand\thespel@footnote{\@arabic\c@spel@footnote}
\setcounter{spel@footnote}{0}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{spel@chunk} counter
%    \begin{macrocode}
\newcounter{spel@chunk}[subparagraph]
\renewcommand\thespel@chunk{\@arabic\c@spel@chunk}
\setcounter{spel@chunk}{0}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Setting up the language}
% We want to make sure that babel communicates the switching of
% langauges to spel, such that it can take not of it. This allows the
% spel engine to select an appropriate language-capable voice when
% generating the spoken text.
%    \begin{macrocode}
\AddBabelHook{informspel}{write}{\spel@idxwrite{language}{\languagename}}
\EnableBabelHook{informspel}
%    \end{macrocode}
% 
% \subsection{Generating speech chunks --- implicitly}
% \subsubsection{Auxiliary macros}
% We define a macro to generate wrappers for single-line text elements.
% The |\spel@registerelement| macro does
% the job. The user can even use the macro for his own custom
% single-line text elements (e.g., for a subtitle, a version string).
% \begin{macro}{\spel@registerelement}
% generic macro to register single-line text elements
%    \begin{macrocode}
\ifspel@disabled\newcommand{\spel@registerelement}[1]{}\else
\newcommand{\spel@registerelement}[1]{%
  \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}}
  }
  \expandafter\AtBeginDocument{
    \spel@idxwrite{#1}{#1}
  }
}
\fi
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Title elements}
% By redefining the title elements, |\title|, |\author| and |\date| we
% avoid having to chunk them.
%
% Using this macro, we can easily take care of all title-like
% elements, using:
%    \begin{macrocode}
\spel@registerelement{title}
\spel@registerelement{date}
\spel@registerelement{author}
%    \end{macrocode}
%
% \subsubsection{Table of contents}
%    \begin{macrocode}
\ifspel@disabled\else
\let\spel@@addcontentsline\addcontentsline
\renewcommand\addcontentsline[3]{%
  \let\spel@@href\href%
  \renewcommand\href[2]{#2}%
  \spel@@addcontentsline{#1}{#2}{#3}%
  \let\href\spel@@href%
}
\providecommand{\tableofcontents}{}
\renewcommand\tableofcontents{%
    \if@twocolumn
      \@restonecoltrue\onecolumn
    \else
      \@restonecolfalse
    \fi
    \@ifclassloaded{article}{\section*{\contentsname}}{\chapter*{\contentsname}}
        \@mkboth{%
           \MakeUppercase\contentsname}{\MakeUppercase\contentsname}%
    \@starttoc{toc}%
    \if@restonecol\twocolumn\fi
    }
\fi
%    \end{macrocode}
%
% \subsubsection{Sectioning commands}
%
% \begin{macro}{\@part}
%   This is a simple wrapper around the regular |\@part| macro.
%    \begin{macrocode}
\ifspel@disabled\else
\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@idxwrite{part \thepart}{\spel@@optpart}%
  \spel@chunkwrite{\spel@@optpart}{#2}%
}
\fi
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@spart}
%   This is a simple wrapper around the regular |\@spart| macro.
%    \begin{macrocode}
\ifspel@disabled\else
\let\spel@@spart\@spart
\def\@spart#1{%
  \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}}%
  \spel@idxwrite{part}{\spel@@optpart star-\thespel@spart}%
  \spel@chunkwrite{\spel@@optpart star-\thespel@spart}{#1}%
}
\fi
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@chapter}
%   This is a simple wrapper around the regular |\@chapter| macro.
%   It is defined conditionally on the existence of the |\chapter| macro.
%    \begin{macrocode}
\ifspel@disabled\else
\ifx\chapter\@undefined\else
\let\spel@@chapter\@chapter
\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}}%
  \spel@idxwrite{chapter \thechapter}{\spel@@optpart\thechapter}%
  \spel@chunkwrite{\spel@@optpart\thechapter}{#2}%
}
\fi
\fi
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@schapter}
%   This is a simple wrapper around the regular |\@schapter| macro.
%   It is defined condionally on the existence of the |\schapter| macro.
%    \begin{macrocode}
\ifspel@disabled\else
\ifx\schapter\@undefined\else
\let\spel@@schapter\@schapter
\def\@schapter#1{%
  \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}}%
  \spel@idxwrite{chapter}{\spel@@optpart star-\thespel@schapter}%
  \spel@chunkwrite{\spel@@optpart star-\thespel@schapter}{#1}%
}
\fi
\fi
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@sect}
%   This is a simple wrapper around the regular |\@sect| macro.
%    \begin{macrocode}
\ifspel@disabled\else
\let\spel@@sect\@sect
\def\@sect#1#2#3#4#5#6[#7]#8{%
  % correct default tex behavior
  \ifnum #2>\c@secnumdepth%
  \stepcounter{#1}%
  \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$}}}%
  \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}%
}
\fi
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@sect}
%   This is a simple wrapper around the regular |\@ssect| macro.
%    \begin{macrocode}
\ifspel@disabled\else
\let\spel@@ssect\@ssect
\def\@ssect#1#2#3#4#5{%
  \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}%
         {#5}}%
  \spel@idxwrite{section}{\spel@@optpart\thesubparagraph-star-\thespel@ssect}%
  \spel@chunkwrite{\spel@@optpart\thesubparagraph-star-\thespel@ssect}{#5}%
}
\fi
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Notes}
%
% \begin{macro}{\@footnotetext}
%   This is a simple wrapper around the regular |\$footnotetext|
%   macro. We use a |spelfootnote| counter to keep track of the
%   individual footnotes.
%    \begin{macrocode}
\ifspel@disabled\else
\let\spel@@fntext\@footnotetext
\long\def\@footnotetext#1{%
  \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}%
  \spel@idxwrite{footnote}{footnote-\thespel@footnote}%
  \spel@chunkwrite{footnote-\thespel@footnote}{#1}%
}
\fi
%    \end{macrocode}
% \end{macro}
% 
% \subsubsection{Itemizations/Enumerations}

% \begin{macro}{\spelitem}
%   This macro is to be used inside an enumerate, itemize, description
%   environment to automatically cause the generation of a speech
%   chunk.
%    \begin{macrocode}
\ifspel@disabled\newcommand{\spelitem}{\item}\else
\newcommand{\spelitem}{%
  \@ifnextchar[{\spelitem@opt}{\spelitem@intone}
}
\fi
%    \end{macrocode}
% \end{macro}
%
% This macro uses a number of auxiliary macros.
% \begin{macro}{\spelitem@opt}
%   This is an internal macro intended to deal with the |\item|'s
%   options.
%    \begin{macrocode}
\def\spelitem@opt[#1]{\spelitem@inttwo{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\spelitem@opt}
%   This is an internal macro intended to deal with an |\spelitem| without
%   options.
%    \begin{macrocode}
\def\spelitem@intone#1{%
  \stepcounter{spel@chunk}%
  \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}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\spelitem@inttwo}
%   This is an internal macro intended to deal with an |\spelitem| with
%   options.
%    \begin{macrocode}
\def\spelitem@inttwo#1#2{%
  \stepcounter{spel@chunk}%
  \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}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\caption}
%   This is a redefinition of the |\caption| macro such that it
%   becomes alive.
%    \begin{macrocode}
\ifspel@disabled\else
\let\spel@@caption\caption
\renewcommand\caption[2][]{%
  \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}}
}
\fi
%    \end{macrocode}
% \end{macro}
% 
%
% \subsection{Generating speech chunks --- explicitly}
%
% \subsubsection{Spel chunks to be parsed by \spelpl}
% \begin{environment}{spelchunk}
% The |spelchunk| environment is used to define explicit speech chunks.
%    \begin{macrocode}
\newlength\spel@mptboxwidth
\newsavebox\spel@mptbox
\savebox\spel@mptbox{\textcolor{black!25}{$\qquad$}}
\newif\ifspel@chunkarealink
\define@key{spelchunk}{arealink}[]{\spel@chunkarealinktrue}
\ifspel@disabled\def\spelchunk{}\else
\def\spelchunk{%
  \catcode`\^^M=\active%
  \stepcounter{spel@chunk}%
  \spel@idxwrite{chunk}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
  \@ifnextchar[{\catcode`\^^M=5\spelchunk@opt}{\catcode`\^^M=5\spelchunk@int}}%
\fi
\ifspel@disabled\def\endspelchunk{}\else
\def\endspelchunk{%
  \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}}%
  \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}%
  \fi%
  \spel@chunkarealinkfalse%
}%
\fi
%    \end{macrocode}
% \end{environment}
%
% The environment above checks if it is called with optional arguments
% or not.
% \begin{macro}{\spelchunk@opt}
%   This is macro that deals with the optional arguments of the
%   |spelchunk| envronment.
%    \begin{macrocode}
\def\spelchunk@opt[#1]{\setkeys{spelchunk}{#1}\spelchunk@int}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\spelchunk@int}
%   This is an internal macro to start the |VerbatimOut| environment
%   embedded in the |spelchunk| environment.
%    \begin{macrocode}
\def\spelchunk@int{%
  \VerbatimEnvironment
  \begin{VerbatimOut}{\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk.tex}}
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Explicit spelchunks}
%
% \begin{environment}{spelchunkad}
% The |spelchunkad| environment is used to override a previous speech
% chunk. In this way you can provide your own text.
%    \begin{macrocode}
\def\spelchunkad{%
  \catcode`\^^M=\active
  \@ifnextchar[{\catcode`\^^M=5\spelchunk@opt}{\catcode`\^^M=5\spelchunk@int}}
\def\endspelchunkad{%
  \end{VerbatimOut}
  \catcode`\^^M=5\relax
}
%    \end{macrocode}
% \end{environment}
%
%    \begin{macrocode}
\AtBeginDocument{
  \newcommand\spel@@optpart{}
}
%    \end{macrocode}
%
% \subsection{Helping the wizard to read our chunks}
%
% \subsubsection{Listing macros that are to be preprocessed}
% 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
% convert the texts flawlessly to what can be read by the
% text-to-speech engines.
% Examples of these layout-only commands are |\sf|, |\it|, |\tt|,
% |\bf| and |\displaystyle| that are to be discarded, but also macro's
% like e.g. |\fbox| for which only the content is to be retained.
%
% As you might also make your own macros that are pure typesetting
% 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}
{
  \addtostream{spelidx}{macpp|#1|#2|#3|#4}
}
\ExplSyntaxOff
%    \end{macrocode}
% \end{macro}
%
% Now let's register some standard macros that are to be ignored.
%    \begin{macrocode}
\spelmacpp{sf}{}
\spelmacpp{it}{}
\spelmacpp{tt}{}
\spelmacpp{bf}{}
\spelmacpp{HUGE}{}
\spelmacpp{Huge}{}
\spelmacpp{huge}{}
\spelmacpp{LARGE}{}
\spelmacpp{Large}{}
\spelmacpp{large}{}
\spelmacpp{normalsize}{}
\spelmacpp{small}{}
\spelmacpp{footnotesize}{}
\spelmacpp{scriptsize}{}
\spelmacpp{tiny}{}
\spelmacpp{minuscule}{}
\spelmacpp{textsf}[1]{keep}
\spelmacpp{textit}[1]{keep}
\spelmacpp{texttt}[1]{keep}
\spelmacpp{textbf}[1]{keep}
\spelmacpp{quad}{}
\spelmacpp{qquad}{}
\spelmacpp{displaystyle}{}
\spelmacpp{relax}{}
\spelmacpp{strut}{}
\spelmacpp{mathstrut}{}
\spelmacpp{label}[1]{}
%    \end{macrocode}
%
% And let's register a macro for which only the contents is to be
% preserved: 
%    \begin{macrocode}
\spelmacpp{fbox}[1]{keep}
%    \end{macrocode}
%
% \subsubsection{Listing environments that are to be ignored}
% 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
% convert the texts flawlessly to what can be read by the
% text-to-speech engines.
% An examples of such a layout-only environment is the |center|
% environment. 
%
% As you might also make your own environments that are pure typesetting
% 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}
{
  \addtostream{spelidx}{envpp|#1|#2|#3|#4}
}
\ExplSyntaxOff
%    \end{macrocode}
% \end{macro}
%
% Now let's register some standard macros that are to be ignored:
%    \begin{macrocode}
\spelenvpp{center}{keep}
%    \end{macrocode}
%
% \subsubsection{Audio descriptions for typesetting macros}
% \begin{macro}{\spelmacad}
%   This macro allows specifying how to treat macros (with arguments)
%   that appear in the chunks to read out loud. The arguments are in
%   order: 
%   \begin{enumerate}
%   \item (mandatory) name of the macro (without leading backslash)
%   \item (optional) number of arguments of the macro
%   \item (optional) default for optional (first) argument
%   \item (mandatory) text to read  (with macro parameters in them)
%   You can use the special syntax
%    |@{i18n(keyword,#1,#2)}|
%   to trigger a call to the internationalization (i18n) features built
%   in the \spelpl{} script. This will help to read your commands in an
%   appropriate way. If you miss some features in the i18n list of
%   \spelpl{}, please contact the author to help you out.
%   If you are fluent in Perl, you might also want to change the i18n
%   list of \spelpl{} yourself. It's not that hard.
%   \end{enumerate}
%    \begin{macrocode}
\ExplSyntaxOn
\NewDocumentCommand{\spelmacad}{moom}
{
  \addtostream{spelidx}{macad|#1|#2|#3|#4}
}
\ExplSyntaxOff
%    \end{macrocode}
% \end{macro}
%
% We immediately provide some standard constructs, which are to be
% 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}
\spelmacad{textsf}[1]{#1}
\spelmacad{texttt}[1]{#1}
\spelmacad{textit}[1]{#1}
\spelmacad{emph}[1]{#1}
\spelmacad{underline}[1]{#1}
\spelmacad{mbox}[1]{#1}
\spelmacad{text}[1]{#1}
\spelmacad{nobreakspace}{#1}
\spelmacad{textasciitilde}[1]{ }
\spelmacad{textbackslash}{backslash}
\spelmacad{footnote}[1]{}
\spelmacad{pm}{@{i18n(plusminus)}}
\spelmacad{ldots}{...}
%    \end{macrocode}
%
% Some more that don't seem ignorable - and they are not indeed - they
% are treated differently by \spelpl{}. However, by registering them
% here, \spelpl{} knows there signature:
%    \begin{macrocode}
\spelmacad{cite}[1]{}
\spelmacad{ref}[1]{}
\spelmacad{pageref}[1]{}
%    \end{macrocode}
%
% \subsubsection{Audio descriptions for typesetting environments}
% \begin{macro}{\spelenvad}
% This macro allows specifying how to treat environments (with arguments)
% that appear in the chunks to read out loud. The arguments are in order:
% \begin{enumerate}
% \item (mandatory) name of the macro (without leading backslash)
% \item (optional) number of arguments of the macro
% \item (optional) default for optional (first) argument
% \item (mandatory) text to read  (with macro parameters in them)
% \end{enumerate}
%    \begin{macrocode}
\ExplSyntaxOn
\NewDocumentCommand{\spelenvad}{moomm}
{
  \addtostream{spelidx}{envad|#1|#2|#3|#4|#5}
}
\ExplSyntaxOff
%    \end{macrocode}
% \end{macro}
%
% We immediately provide some standard constructs, which are to be
% ignored:
%    \begin{macrocode}
\spelenvad{center}{}{}
%    \end{macrocode}
%
% \subsection{Extra math commands}
%
% The commands are only loaded if the package option |extramath| is
% provided: 
%
%    \begin{macrocode}
\ifspel@extramath
%    \end{macrocode}
%
% \begin{macro}{\setenum}
% This macro typesets a set defined by enumeration:
%    \begin{macrocode}
\DeclareRobustCommand{\setenum}[1]{\left\{#1\right\}}
\spelmacad{setenum}[1]{@{i18n(Setenum,#1)}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\setdesc}
% This macro typesets a set defined by description:
%    \begin{macrocode}
\DeclareRobustCommand{\setdesc}[1]{\left\{#1\right\}}
\spelmacad{setdesc}[1]{@{i18n(Setdesc,#1)}}
%    \end{macrocode}
% \end{macro}
%
% Note that these two macro's are identical! However, the fact that
% they have a different name is of great value to \spelpl{}.
%
% The conditional loading ends here:
%    \begin{macrocode}
\fi
%    \end{macrocode}
% 
% \iffalse
%    \begin{macrocode}
%</package>
%    \end{macrocode}
% \fi
%
% \section{TODO}
% \begin{spelchunk}[arealink]
%   As long as there are things on my todo list, We have a reason to
%   live.
% \end{spelchunk}
% \begin{itemize}
%   \spelitem{provide enable/disable switch to disable certain ranges in
%   text, e.g. the implementation range in this document}
%   \spelitem{enable bibliography and citation stuff}
% \end{itemize}
%
% \bibliographystyle{alpha}
%
% \begin{thebibliography}{99}
%
% \bibitem{NVDA}
% NVDA from NV Access, empowering lives through non-visual access to technology
% \newblock \url{https://www.nvaccess.org}
% \newblock online, accessed in June 2024.
%
% \bibitem{SPRINT}
% SprintPlus, helping people with dyslexia
% \newblock \url{https://www.sprintplus.be/en}
% \newblock online, accessed in June 2024.
%
% \bibitem{ADOBEREADER}
% Adobe Reader, a PDF reader from Adobe.
% \newblock \url{https://get.adobe.com/}
% \newblock online, accessed in May 2024.
%
% \bibitem{TAGPDF}
% TagPDF - Tools for experimenting with tagging using pdfLaTeX and
% LuaLaTeX.
% \newblock \url{https://ctan.org/pkg/tagpdf}
% \newblock online, accessed in June 2024.
%
% \bibitem{WINE}
% Wine - Wine Is Not an Emulator - running windows applications on POSIX-compliant systems.
% \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}
% \newblock online, accessed in June 2024.
%
% \bibitem{SPELWIZARD}
% SpeL::Wizard --- Incantating \LaTeX{} into natural lanuage
% \newblock \url{https://metacpan.org/pod/SpeL::Wizard}
% \newblock online, accessed in June 2024.
%
% \bibitem{FESTIVAL} 
% The Festival TTS-program.
% \newblock \url{http://www.cstr.ed.ac.uk/projects/festival}.
% \newblock online, accessed in May 2024.
%
% \bibitem{BALABOLKA} 
% The Balabolka TTS-program.
% \newblock \url{http://www.cross-plus-a.com/balabolka.htm}.
% \newblock online, accessed in May 2024.
%
% \bibitem{FREETTS}
% FreeTTS --- A speech synthesizer in Java.
% \newblock \url{https://freetts.sourceforge.io/docs/index.php}.
% \newblock online, accessed in May 2024.
%
% \bibitem{AWSPOLLY}
% Amazon Polly --- An online text-to-speech engine.
% \newblock \url{https://aws.amazon.com/polly}
% \newblock online, accessed in May 2024.
%
% \bibitem{CTAN} 
% The Comprehensive \TeX{} Archive Network.
% \newblock \url{http://www.ctan.org}.
% \newblock online, accessed in May 2024.
%
% \bibitem{CPAN} 
% The Comprehensive Perl Archive Network.
% \newblock \url{http://www.cpan.org}.
% \newblock online, accessed in May 2024.
%
% \bibitem{XPDF}
% xpdf, a simple and very fast PDF reader on \GNU/Linux.
% \newblock \url{http://www.xpdfreader.com/}.
% \newblock online, accessed in May 2024.
%
% \bibitem{EVINCE}
% evince, a PDF reader, part of the Gnome environment.
% \newblock \url{https://help.gnome.org/users/evince/stable/}.
% \newblock online, accessed in May 2024.
%
% \bibitem{OKULAR}
% okular, a PDF reader, part of the KDE environment.
% \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
\endinput