summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/spelatex/spelatex.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/spelatex/spelatex.dtx')
-rw-r--r--Master/texmf-dist/source/latex/spelatex/spelatex.dtx462
1 files changed, 340 insertions, 122 deletions
diff --git a/Master/texmf-dist/source/latex/spelatex/spelatex.dtx b/Master/texmf-dist/source/latex/spelatex/spelatex.dtx
index b906fd628b8..bdedc84d70b 100644
--- a/Master/texmf-dist/source/latex/spelatex/spelatex.dtx
+++ b/Master/texmf-dist/source/latex/spelatex/spelatex.dtx
@@ -1,6 +1,5 @@
% \iffalse meta-comment
%
-%
% Copyright (C) 2024 by Walter Daems <walter.daems@uantwerpen.be>
% and Paul Levrie
%
@@ -34,10 +33,10 @@
\ProvidesFile{spelatex.dtx}
%</driver>
%<*package>
- [2024/06/12 v0.9 SpeLaTeX - Speech-enabled LaTeX (DMW and LVP)]
+ [2024/06/21 v0.91 SpeLaTeX - Speech-enabled LaTeX (DMW and LVP)]
%</package>
-\def\fileversion{0.9}
-\def\filedate{2024/06/12}
+\def\fileversion{0.91}
+\def\filedate{2024/06/21}
%<*driver>
\documentclass[10pt]{ltxdoc}
\usepackage{makeidx}
@@ -79,7 +78,11 @@
% Right brace \} Tilde \~}
%
%
-% \changes{v0.9}{2024/06/12}{. Birth}
+% \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}
%
@@ -104,14 +107,14 @@
% \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}
%
+% \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
@@ -138,46 +141,152 @@
% 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
-% os an obvious choice. Nowadays, special software exists that
+% is 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.
+% 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}
-% \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
+% 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 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
+% 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.
+% 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. I'd also
+% 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 my day.
+% package. The pleasure of receiving such an e-mail makes our day.
% \end{spelchunk}
%
% \begin{spelchunk}
@@ -215,8 +324,8 @@
% \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.
+% 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}
@@ -228,9 +337,9 @@
% ecosystem. It consists of three components:
% \end{spelchunk}
% \begin{itemize}
-% \spelitem{An Org-mode exporter called \texttt{ox-spelatex} \cite{OXSPELATEX}}
+% \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 \spelwizardmodule~\cite{SPELWIZARD}}
+% \spelitem{A script embeded in the Perl module \texttt{SpeL::Wizard} \cite{SPELWIZARD}}
% \end{itemize}
%
% \subsubsection{The overall picture}
@@ -249,7 +358,7 @@
% \end{spelchunk}
%
% \begin{spelchunk}
-% By loading the |spelatex.sty| package in your source
+% 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
@@ -294,11 +403,11 @@
% 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 [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) {spelatex.sty\\\footnotesize(package)};
+% \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)};
@@ -313,7 +422,7 @@
% \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)};
+% \footnotesize(\spelatex{} engine)};
% \node [tool] (t2s) at (1.5,-6) {text-to-speech\\engine};
% \draw[->] (files) -- (engine);
% \draw[->] (spelidx) -- (engine);
@@ -339,13 +448,13 @@
% 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
+% equiped \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
+% 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 tech files containing the text chunks to be processed by
-% \spelpl. This is a perl script that converts the chunks into
+% 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
@@ -363,6 +472,28 @@
% \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}
@@ -390,7 +521,7 @@
% 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
+% 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}
@@ -400,7 +531,7 @@
% 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
+% 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
@@ -472,7 +603,7 @@
% 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
+% 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
@@ -485,7 +616,7 @@
% 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{}
+% 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}
@@ -518,8 +649,8 @@
% \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:
+% 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]{
@@ -533,7 +664,7 @@
% 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
+% 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
@@ -553,15 +684,27 @@
% \section{Installation}
%
% \subsection{The \spelatex{} package}
-
% \begin{spelchunk}
-% Most \LaTeX{} distributions use \CTAN{} as their main package source
-% and therefore will include \spelatex.
+% 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}
-% 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.
+% \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}
@@ -576,9 +719,9 @@
% \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.
+% 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}
@@ -588,8 +731,8 @@
%
% \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|
+% On Strawberry perl: |$ cpan SpeL::Wizard|\\
+% On ActiveState perl: |$ ppm install SpeL-Wizard|
% \end{spelchunk}
%
% \begin{spelchunk}
@@ -600,7 +743,7 @@
% \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.
+% 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]
@@ -615,6 +758,21 @@
% 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
@@ -630,20 +788,28 @@
% \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
+% 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.%
+% 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
+% 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}
@@ -652,13 +818,16 @@
% \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.
+% 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 standard practice it
+% that and be prepared: in line with Microsoft's standard practice it
% is well hidden in the interface.
% \end{spelchunk}
%
@@ -691,7 +860,7 @@
% required macros.
% \end{spelchunk}
%
-% \subsubsection{Treating the implicit spelchunks}
+% \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
@@ -710,7 +879,7 @@
% \begin{spelchunk}
% Example:
% \begin{Verbatim}
-% I like
+% We like
% \begin{itemize}
% \spelitem{apples,}
% \spelitem{pears, and}
@@ -732,12 +901,15 @@
% boilerplate work.
% \end{spelchunk}
%
-% \subsubsection{Treating the explicit spelchunks}
+% \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.
+% 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}
@@ -748,10 +920,12 @@
% \begin{Verbatim}
% \begin{spelchunk}
% An orderinary paragraph must be embedded in this environment.
-% The same holds for equations!
+% 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}
+% \begin{spelchunk}[arealink]
% \begin{align}
% E &= m c^2\\
% e^{j\pi} &= -1
@@ -760,7 +934,7 @@
% \end{Verbatim}
%
%
-% \subsubsection{Manually providing text to read when needed}
+% \subsubsection{Manually provide text to read when needed}
% \begin{spelchunk}
% \DescribeEnv{spelchunkad}
% If you want a different text to be used for the previous
@@ -778,7 +952,7 @@
%
% \begin{spelchunk}
% Example:\\
-% {\footnotesize (note: the example below is not \spelatex{}-enabled because it also
+% {\footnotesize (note: the example below is not \spelatex{}-enabled because it
% generates internal package problems)}
% \end{spelchunk}
% \begin{Verbatim}
@@ -802,7 +976,7 @@
% \begin{spelchunk}
% Example:\\
% {\footnotesize (note: the example below is not \spelatex{}-enabled because it
-% generates internal package problems also)}
+% generates internal package problems)}
% \end{spelchunk}
% \begin{Verbatim}
% \begin{spelchunk}
@@ -874,9 +1048,9 @@
% \begin{spelchunk}
% This allows easy specification of an illustration as:
% \begin{Verbatim}
-% \begin{proof}[Illustration]{solving a quadratic equation}
-% blabla
-% \end{proof}
+% \begin{proof}[Illustration]{solving a quadratic equation}
+% blabla
+% \end{proof}
% \end{Verbatim}
% \end{spelchunk}
% \begin{spelchunk}
@@ -943,15 +1117,17 @@
% 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 a descriptive set and makes sure \spelpl{}
+% This macro typesets an enumeration set and makes sure \spelpl{}
% can read it properly.
% \end{spelchunk}
% \begin{spelchunk}
@@ -1043,8 +1219,7 @@
% Consider the following simple definition of a polynomial function and
% check its spoken version by clicking on it.
% \end{spelchunk}
-%
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{equation}
% f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 23
% \end{equation}
@@ -1066,7 +1241,7 @@
% equal to $\tan\alpha = -\frac{t}{2}$, the equation of the
% reflected ray is given by
% \end{spelchunk}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \[
% y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t)
% \]
@@ -1079,9 +1254,9 @@
% voorleesstem de geselecteerde taal zal volgen.
% \end{spelchunk}
%
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \[
-% y-9+\frac{t^2}{4} = -(x-t) \cdot \frac{4t}{4-t^2}
+% y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t)
% \]
% \end{spelchunk}
@@ -1113,7 +1288,7 @@
% \newblock \url{http://www.cpan.org}.
% \newblock online, accessed in August 2021.
%
-% \end{thebibliography}{99}
+% \end{thebibliography}
%
% \end{document}
% \end{VerbatimOut}
@@ -1134,8 +1309,7 @@
% \end{spelchunk}
%
% \subsection{Numbers}
-%
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{align}
% \pi\\
% -31415\\
@@ -1149,7 +1323,7 @@
%
% \subsection{Fractions}
% \subsubsection{A fraction only containg numbers}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{align}
% x &= - \frac{1}{2} \\
% y &= - \sqrt{\frac{\pi}{2}}
@@ -1157,7 +1331,7 @@
% \end{spelchunk}
%
% \subsubsection{A fraction with a little more under the hood}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{align}
% u &= - \frac{x^2+35}{\sqrt{12}} \\
% v &= - \frac{\sqrt{\frac{\pi}{2}}}{-3x^2+3}
@@ -1166,8 +1340,8 @@
%
%
% \subsection{Simple expressions}
-% \subsubsection{A polynomial function}
-% \begin{spelchunk}
+% \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}
@@ -1177,7 +1351,7 @@
% \begin{spelchunk}
% Here's de Moivre's formula:
% \end{spelchunk}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{equation}
% \left(\cos x+j\sin x\right)^n=\cos(nx)+j\sin(nx)
% \end{equation}
@@ -1186,7 +1360,7 @@
% \begin{spelchunk}
% Euler's relationship:
% \end{spelchunk}
-% \begin{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{equation}
% e^{j \phi} = \cos \phi + j \sin \phi
% \end{equation}
@@ -1214,7 +1388,7 @@
% \texttt{\textbackslash{}setenum} and
% \texttt{\textbackslash{}setdesc}:
% \end{spelchunk}
-% \begin{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}}
@@ -1224,6 +1398,8 @@
% \subsection{Matrices}
% \begin{spelchunk}
% How about some linear algebra?
+% \end{spelchunk}
+% \begin{spelchunk}[arealink]
% \begin{align}
% \begin{bmatrix}
% 3 & 4 \\
@@ -1372,7 +1548,7 @@
% \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
+% difficult to read on itself, We took the liberty of not providing
% this section with speech chunks (except for this introduction
% text).
% \end{spelchunk}
@@ -1425,6 +1601,8 @@
bookmarksopen=true,
urlcolor=black}
\RequirePackage{kvoptions}
+\RequirePackage{xkeyval}
+\RequirePackage{marginnote}
% \end{macrocode}
%
% \subsection{Options}
@@ -1633,9 +1811,6 @@
\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
@@ -1748,7 +1923,7 @@
\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}}}%
+ \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}%
@@ -1786,8 +1961,9 @@
\let\spel@@fntext\@footnotetext
\long\def\@footnotetext#1{%
\stepcounter{spel@footnote}%
+ \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
\spel@@fntext{%
- \href{run:\audiodir/footnote-\thespel@footnote.\spel@format}{#1}}
+ \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}%
}
@@ -1825,10 +2001,10 @@
% \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 \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{#1}
-}
+ \item \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#1}
% \end{macrocode}
% \end{macro}
%
@@ -1838,10 +2014,10 @@
% \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] \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{#2}
-}
+\item[#1] \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#2}
% \end{macrocode}
% \end{macro}
%
@@ -1868,6 +2044,11 @@
% \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%
@@ -1879,7 +2060,13 @@
\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}%
+ \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}
@@ -1891,7 +2078,7 @@
% This is macro that deals with the optional arguments of the
% |spelchunk| envronment.
% \begin{macrocode}
-\def\spelchunk@opt[#1]{\fvset{#1}\spelchunk@int}
+\def\spelchunk@opt[#1]{\setkeys{spelchunk}{#1}\spelchunk@int}
% \end{macrocode}
% \end{macro}
%
@@ -1905,7 +2092,7 @@
% \end{macrocode}
% \end{macro}
%
-% \subsubsection{Provideing an explicit audiodescription for a spelchunk}
+% \subsubsection{Explicit spelchunks}
%
% \begin{environment}{spelchunkad}
% The |spelchunkad| environment is used to override a previous speech
@@ -2052,10 +2239,10 @@
% We immediately provide some standard constructs, which are to be
% ignored:
% \begin{macrocode}
-\spelmacad{spelatex}{spee-laytech}
+\spelmacad{spelatex}{spee-lay-tech}
\spelmacad{spelbox}{spel-box}
\spelmacad{spelpl}{spel wizzard dot pl}
-\spelmacad{LaTeX}{laytech}
+\spelmacad{LaTeX}{lay-tech}
\spelmacad{TeX}{tech}
\spelmacad{textsf}[1]{#1}
\spelmacad{texttt}[1]{#1}
@@ -2107,7 +2294,7 @@
\spelenvad{center}{}{}
% \end{macrocode}
%
-% \subsection{Implementing the extra math commands}
+% \subsection{Extra math commands}
%
% The commands are only loaded if the package option |extramath| is
% provided:
@@ -2145,35 +2332,71 @@
%</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{EMACS}
-% The Emacs An extensible, customizable, free text editor --- and
-% more.
-% \newblock \url{https://www.gnu.org/software/emacs/}.
+% \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.
+% 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
+% SpeL::Wizard --- Incantating \LaTeX{} into natural lanuage
% \newblock \url{https://metacpan.org/pod/SpeL::Wizard}
% \newblock online, accessed in June 2024.
%
@@ -2222,11 +2445,6 @@
% \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/}