summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2024-06-13 20:16:23 +0000
committerKarl Berry <karl@freefriends.org>2024-06-13 20:16:23 +0000
commit5012f9d54f190e7605b49e1f626abc8c54fd19b0 (patch)
tree2e985de70892225d7b5d955f15533bd9b664296b /Master/texmf-dist/source
parent95e8a1f4641bd5dbb0a14bf499ddb18ef5efa6f8 (diff)
spelatex (13jun24)
git-svn-id: svn://tug.org/texlive/trunk@71514 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r--Master/texmf-dist/source/latex/spelatex/spelatex.dtx2238
-rw-r--r--Master/texmf-dist/source/latex/spelatex/spelatex.ins58
2 files changed, 2296 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/spelatex/spelatex.dtx b/Master/texmf-dist/source/latex/spelatex/spelatex.dtx
new file mode 100644
index 00000000000..b906fd628b8
--- /dev/null
+++ b/Master/texmf-dist/source/latex/spelatex/spelatex.dtx
@@ -0,0 +1,2238 @@
+% \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/12 v0.9 SpeLaTeX - Speech-enabled LaTeX (DMW and LVP)]
+%</package>
+\def\fileversion{0.9}
+\def\filedate{2024/06/12}
+%<*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.9}{2024/06/12}{. Birth}
+%
+% \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}
+% \newrobustcmd\spelwizardmodule{\texttt{SpeL::Wizard}}
+% \spelmacad{spelwizardmodule}{spel double colon wizard}
+%
+% \maketitle
+% \fvset{gobble=2}
+%
+% \section{Preface}
+%
+% \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}
+%
+% \begin{spelchunk}
+% Therefore, reverting to readily available text-to-speech software
+% os an obvious choice. Nowadays, special software exists that
+% provides the functionality of reading out loud the contents of
+% electronic documents. 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}
+% \LaTeX{} is one of the better choices when it comes to typesetting
+% technical subjects, so why not extend \LaTeX{} to provide
+% mathematics-capable text-to-speech facilities? Our \spelatex{}
+% prototype does exactly that. Admittedly, using it 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 AI take over the role of this package in the future?
+% Undoubtedly so. But for the time being, and also to avoid wasting
+% the enormous amount of energy AI costs us, 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.
+% \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. I'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 my 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, I often use \spelatex{} to proofread texts as I
+% hear language errors more easily than I 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-spelatex} \cite{OXSPELATEX}}
+% \spelitem{This \LaTeX{}-package \spelatex{} \cite{SPEL}}
+% \spelitem{A script embeded in the Perl module \spelwizardmodule~\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 |spelatex.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(\texttt{ox-spelatex})};
+% \node [doc] (text) at (0,3) {text.tex\\\footnotesize(prepped source)};
+% \draw[->] (utext) -- (instrument);
+% \draw[->] (instrument) -- (text);
+% \node [doc] (R) at (-3,0) {spelatex.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(\spelwizardmodule{} 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
+% equipped \LaTeX{} file of your text. We call this the prepped source. You can
+% also start by composing this file yourself.
+% If your prepped source file uses the \spelatex{} style file, then
+% 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 tech files containing the text chunks to be processed by
+% \spelpl. 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}
+%
+% \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 I 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 I'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, I 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. I 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? I think there are many
+% selling points. I 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, I 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}
+% Most \LaTeX{} distributions use \CTAN{} as their main package source
+% and therefore will include \spelatex.
+% \end{spelchunk}
+%
+% %\begin{spelchunk}
+% If this is not the case, contact me. I'll be glad to provide you
+% with TDS file that you can unpack in your local TDS tree.
+% \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
+% \spelwizardmodule~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|\\
+% When using Strawberry perl: |$ cpan SpeL::Wizard|\\
+% When using 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 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}
+% 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}
+% Be aware that you need to install your text-to-speech tool yourself
+% according to the documentation provided by the tool provider. 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 does not \cite{XPDF}, evince
+% complains about security risks \cite{EVINCE}, 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).\\
+% On windows, I'd 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 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{Treating 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}
+% I 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{Treating the explicit spelchunks}
+%
+% \begin{spelchunk}
+% \DescribeEnv{spelchunk}
+% Use this environment to embed the chunks of text in that you want
+% to generate audio for.
+% \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!
+% \end{spelchunk}
+%
+% \begin{spelchunk}
+% \begin{align}
+% E &= m c^2\\
+% e^{j\pi} &= -1
+% \end{align}
+% \end{spelchunk}
+% \end{Verbatim}
+%
+%
+% \subsubsection{Manually providing 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 also
+% 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 also)}
+% \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{Verbatim}
+% \begin{equation}
+% P = \setenum{ 2, 3, 5, 7, 11, 13, \ldots }
+% \end{equation}
+% \end{Verbatim}
+%
+% \DescribeMacro{\setdesc}
+% \begin{spelchunk}
+% This macro typesets a descriptive 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}
+% \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}
+% \[
+% 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}
+% \[
+% y-9+\frac{t^2}{4} = -(x-t) \cdot \frac{4t}{4-t^2}
+% \]
+% \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}{99}
+%
+% \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}
+% \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}
+% \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}
+% \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}
+% \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}
+% \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}
+% \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}
+% \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?
+% \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, I 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}
+% \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{Boxed material}
+% by redefining the makebox, mbox and usebox commands, we can create
+%
+% \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!50}{\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}%
+ \spel@@fntext{%
+ \href{run:\audiodir/footnote-\thespel@footnote.\spel@format}{#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}%
+ \spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
+ \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1}%
+ \item \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{#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}%
+ \spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
+ \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1 . #2}%
+ \item[#1] \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{#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}
+\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%
+ \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}\leavevmode}%
+}%
+\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]{\fvset{#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{Provideing an explicit audiodescription for a spelchunk}
+%
+% \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-laytech}
+\spelmacad{spelbox}{spel-box}
+\spelmacad{spelpl}{spel wizzard dot pl}
+\spelmacad{LaTeX}{laytech}
+\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{Implementing the 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
+
+%
+% \bibliographystyle{alpha}
+%
+% \begin{thebibliography}{99}
+%
+% \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{ORGMODE}
+% Org Mode --- your life in plain text.
+% \newblock \url{https://orgmode.org/}.
+% \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{ADOBEREADER}
+% Adobe Reader, a PDF reader from Adobe.
+% \newblock \url{https://get.adobe.com/}
+% \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
diff --git a/Master/texmf-dist/source/latex/spelatex/spelatex.ins b/Master/texmf-dist/source/latex/spelatex/spelatex.ins
new file mode 100644
index 00000000000..dfe1cbf39ec
--- /dev/null
+++ b/Master/texmf-dist/source/latex/spelatex/spelatex.ins
@@ -0,0 +1,58 @@
+%% 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 lts.dtx and lts.ins
+%% and all derived files.
+
+\input docstrip.tex
+\keepsilent
+
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2024 by Walter Daems <walter.daems@ieee.org>
+ and Paul Levrie
+
+This file 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.
+
+\endpreamble
+
+\usedir{tex/latex/spelatex}
+\generate{\file{spelatex.sty}{\from{spelatex.dtx}{package}}}
+
+\obeyspaces
+\Msg{***************************************************************}
+\Msg{* *}
+\Msg{* To finish the installation you have to merge the TDS tree *}
+\Msg{* into your TEXMFLOCAL tree. *}
+\Msg{* *}
+\Msg{* Good luck! *}
+\Msg{* *}
+\Msg{* Walter *}
+\Msg{* *}
+\Msg{***************************************************************}
+
+\endbatchfile