Debian Codegraph @

texmf-dist/source/latex/spelatex/spelatex.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2025-2026 by Walter Daems <[email protected]>
4 % and Paul Levrie
5 %
6 % This work may be distributed and/or modified under the conditions of
7 % the LaTeX Project Public License, either version 1.3 of this license
8 % or (at your option) any later version. The latest version of this
9 % license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3 or later is part of all distributions of LaTeX version
14 % 2005/12/01 or later.
15 %
16 % This work has the LPPL maintenance status `maintained'.
17 %
18 % The Current Maintainer of this work is Walter Daems.
19 %
20 % This work consists of the files spelatex.dtx, spelatex.ins,
21 % and any derivative file, generated from the dtx file using
22 % the ins driver file.
23 % \fi
24 %
25 % \iffalse
26 %<*package>
27 \NeedsTeXFormat{LaTeX2e}
28 \ProvidesPackage{spelatex}
29 %</package>
30 %<*driver>
31 \NeedsTeXFormat{LaTeX2e}
32 \ProvidesFile{spelatex.dtx}
33 %</driver>
34 %<*package>
35 [2026-04-09 v0.96 SpeLaTeX]
36 %</package>
37 \def\fileversion{v0.96}
38 \def\filedate{2026-04-09}
39 %<*driver>
40 \documentclass[11pt,a4paper]{ltxdoc}
41 \usepackage[margin=1in,left=2in]{geometry}
42 \usepackage{makeidx}
43 \usepackage{alltt}
44 \usepackage[english]{babel}
45 \usepackage[extramath,
46 server=https://ctan.org/tex-archive/macros/latex/contrib/spelatex
47 ]{spelatex}
48 \usepackage[overload]{empheq}
49 \usepackage{amsmath}
50 \usepackage{amsfonts}
51 \usepackage{graphicx}
52 \usepackage{tikz}
53 \IfFileExists{tocbibind.sty}{\usepackage{tocbibind}}{}
54 \EnableCrossrefs
55 \CodelineIndex
56 \RecordChanges
57 \StopEventually{\PrintChanges\PrintIndex}
58 \spelmacad{DescribeEnv}[1]{#1}
59 \spelmacad{DescribeMacro}[1]{#1}
60 \def\MacroFont{\footnotesize
61 \usefont\encodingdefault
62 \ttdefault
63 \mddefault
64 \shapedefault
65 }%
66 \begin{document}
67 \DocInput{spelatex.dtx}
68 \end{document}
69 %</driver>
70 % \fi
71 %
72 % \CheckSum{0}
73 %
74 % \CharacterTable
75 % {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
76 % 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
77 % Digits \0\1\2\3\4\5\6\7\8\9
78 % Exclamation \! Double quote \" Hash (number) \#
79 % Dollar \$ Percent \% Ampersand \&
80 % Acute accent \' Left paren \( Right paren \)
81 % Asterisk \* Plus \+ Comma \,
82 % Minus \- Point \. Solidus \/
83 % Colon \: Semicolon \; Less than \<
84 % Equals \= Greater than \> Question mark \?
85 % Commercial at \@ Left bracket \[ Backslash \\
86 % Right bracket \] Circumflex \^ Underscore \_
87 % Grave accent \` Left brace \{ Vertical bar \|
88 % Right brace \} Tilde \~}
89 %
90 %
91 % \changes{v0.90}{2024/05/31}{. Birth}
92 % \changes{v0.91}{2024/06/21}{. First overhaul:\\
93 % - avoided big active link areas\\
94 % - sketched bigger picture, leading to
95 % the three project phases.}
96 % \changes{v0.92}{2024/09/09}{. Second overhaul:\\
97 % - dumped orgmode export idea (too small of an audience)\\
98 % - introduced markers for non-area-links\\
99 % - implemented audio on server\\
100 % - implemented <\kern-0.5ex<\kern-0.5ex<-macro as a shorthand}
101 % \changes{v0.93}{2024/10/23}{. Major overhaul:\\
102 % - improvements to allow for TeX-ing of full course of Walter\\
103 % - introduced shorthand macro \textbackslash<<<\\
104 % - switching between math and text mode fixed}
105 % \changes{v0.94}{2024/11/01}{. Bug fixes for TUGboat article\\
106 % - removed all 'dropped character warnings'\\
107 % - the logo now has a hyphenation point\\
108 % - increased font size of documentation}
109 % \changes{v0.94b}{2024/11/04}{. Fixed bug that resulted in duplicate text}
110 % \changes{v0.95}{2025/01/31}{. Fine tuning of some details as suggested by Karl Berry\\
111 % - now preserving user's hyperlink formatting\\
112 % - corrected various spacing/alignment details\\
113 % - explored using existing hook infrastructure (not succesful)}
114 % \changes{v0.96}{2026/04/09}{. Adding some missing features\\
115 % - spelitemcont to allow for continuation of itemization
116 % after intermission by a display item}
117 %
118 % \GetFileInfo{spelatex.dtx}
119 %
120 % \DoNotIndex{\newcommand,\newenvironment}
121 % \setlength{\parindent}{0em}
122 % \addtolength{\parskip}{0.5\baselineskip}
123 % \setlength\IndexMin{200pt}
124 %
125 % \title{\sf \spelatex{} --- Speech-enabled \LaTeX{}}
126 % \author{Walter Daems (\texttt{[email protected]})
127 % and Paul Levrie}
128 % \date{\fileversion --- \filedate}
129 %
130 % \newrobustcmd\GNU{GNU}
131 % \spelmacad{GNU}{gnew}
132 % \newrobustcmd\TexLive{Tex Live}
133 % \spelmacad{TexLive}{tech-laaiv}
134 % \newrobustcmd\MikTeX{MikTeX}
135 % \spelmacad{MikTeX}{miktech}
136 % \newrobustcmd\CTAN{CTAN}
137 % \spelmacad{CTAN}{see-tan}
138 % \newrobustcmd\CPAN{CPAN}
139 % \spelmacad{CPAN}{see-pan}
140 % \newrobustcmd\POD{POD}
141 % \spelmacad{POD}{pod}
142 %
143 % \maketitle
144 % \fvset{gobble=2}
145 %
146 % \section*{Disclaimer}
147 % \<<<{
148 % Note that this is an experimental package. Its interface may change
149 % considerably over subsequent versions (until v1.0).
150 % }
151 %
152 % \section{Preface}
153 %
154 % \subsection{Background}
155 %
156 % \<<<{
157 % At our institute, the University of Antwerp in Belgium, the number
158 % of students with reading and/or writing disorders (or at least
159 % aware of these disorders) is increasing. Approximately 5\% of the
160 % students are registered with such a disorder and the number is rising
161 % steadily over the past 10 years. Probably this number is an
162 % underestimation as a number of people opt not to register their
163 % disorder.
164 % }
165
166 % \<<<{
167 % A large portion of the study materials we offer to students is
168 % still written material. The authors believe that this will keep on
169 % being so, even given the multimedia and AI options that have
170 % become mainstream. Let's not go into this debate for now.\\
171 % However, written course texts cannot be but suboptimal for
172 % students with reading disorders.
173 % }
174 %
175 % \<<<{
176 % For small texts, reading them out loud and recording them using a
177 % voice recorder to create an aid for our target group, is still
178 % feasible. We have taken that in the past for exam
179 % assignments. However, for bigger texts (like course syllabi) this
180 % is beyond the time a professor can afford spending on this small a
181 % group of students. Yes, economic laws also govern teaching!
182 % }
183 %
184 % \subsection{State of the art}
185 %
186 % \subsubsection{In general}
187 %
188 % \<<<{
189 % Therefore, reverting to readily available text-to-speech software
190 % is an obvious choice. Nowadays, special software exists that
191 % provides the functionality of reading out loud the contents of
192 % electronic documents, e.g. NVDA \cite{NVDA} or
193 % SprintPlus~\cite{SPRINT}. Moreover, more and more standard PDF
194 % readers (such
195 % as Acrobat Reader~\cite{ADOBEREADER} have the facility of
196 % performing text-to-speech). For nontechnical subjects, this works
197 % fine. However, when it comes to technical course syllabi that are
198 % loaded with non-trivial mathematics, the standard text-to-speech
199 % packages fail to meet our expectations. In addition, they cannot
200 % read a sensible textual description of figures or tables.
201 % }
202 %
203 % \<<<{
204 % The issue with reading mathematics will be solved in the future,
205 % by enforcing mathematical equations to follow a specific standard
206 % that can be parsed and converted, not only into a visual
207 % representation, but also into proper text. MathML will be one of
208 % the candidates for that format.
209 % }
210 %
211 % \<<<{
212 % The issue with figures and tables can be solved by using the tag
213 % infrastructure of PDF. The format provides a system of tags that
214 % allow you to provide extra information about the content of a
215 % document, in much the same way as you can specify an 'alt' key for
216 % an image in HTML. This tag could contain a proper textual
217 % description of the figure or the table.
218 % }
219 %
220 % \subsubsection{For \LaTeX}
221 %
222 % \<<<{
223 % Currently, the \LaTeX{} project is investing in enabling \LaTeX{} to
224 % partially automate the tagging of PDFs with the \texttt{tagpdf}
225 % package~\cite{TAGPDF}, such that the user only has to do a minimal
226 % job (adding tags for figures and tables). The goal is to maximize
227 % the accessibility of \LaTeX-produced documents.
228 % }
229 %
230 % \<<<{
231 % So all is well? Not quite. Though we are confident that --- with enough
232 % time --- the community will solve the issue completely, there are
233 % still some gaps:
234 % }
235 % \begin{itemize}
236 % \spelitem{The tagpdf package is still not a part of the mainstream
237 % \LaTeX{}-kernel.}
238 % \spelitem{MathML reading support in PDF readers is still in its
239 % infancy.}
240 % \spelitem{Many PDF readers do not fully support tags yet.}
241 % \end{itemize}
242 %
243 % \subsection{This package}
244 %
245 % \<<<{
246 % This package aims to overcome these problems in the meantime and
247 % also to contribute to the longterm goal: making perfectly tagged
248 % PDFs that are read by any PDF-reader.
249 % }
250 %
251 % \<<<{
252 % In the \emph{first phase} of this package (i.e. the version you are
253 % looking at right now), this package reads your \LaTeX{} source,
254 % converts the text and the formulas to audio files and equips your
255 % PDF with hyperlinks to these files, such that with a few clicks
256 % you can listen to your document.
257 % The audio files are external files that should be packaged with
258 % your PDF to allow a reader to use the document with the available
259 % audio.
260 % You have the choice to use local files or files that are made available on a
261 % server (as holds for this text; the audio files are on the CTAN servers).\\
262 % How does \spelatex{} read the formulas? It parses your \LaTeX{} constructs and
263 % makes the best of it. This will probably be the part that might
264 % survive up until the very last phase of this package.
265 % }
266 %
267 % \<<<{
268 % In a \emph{second phase} of this package, the audio files will be embedded
269 % into the PDF. Currently, there are not enough PDF readers that
270 % support this feature. Therefore, we decided to keep using the
271 % external audio files for now.
272 % }
273 %
274 % \<<<{
275 % In a \emph{third phase}, the audio files \emph{may be} abandoned
276 % alltogether, fully switching to tags. And we do think that this
277 % should be the end goal. The reasons why we say
278 % \emph{'may be'}, are:
279 % }
280 % \begin{itemize}
281 % \spelitem{The voices of the current PDF-readers are still not of the
282 % same quality as the ones available online. And quality does matter.}
283 % \spelitem{The better voices may require cloud access, and probably
284 % will not be free, therefore (us) paying for them at document creation
285 % time, makes more sense to us than having our students pay
286 % for these voices whenever they read the document.}
287 % \spelitem{The industry standard Adobe reader is not easily available
288 % on open-source operating systems (like UNIX/BSD/Linux-derived
289 % platforms). You might consider using emulation using
290 % wine~\cite{WINE}, but in that case you can forget about audio. Free
291 % access to software is something we consider to be a must-have,
292 % rather than a nice-to-have.}
293 % \end{itemize}
294 %
295 % \<<<{
296 % Will \spelatex{} become obsolete in the future?
297 % Undoubtedly so. But for the time being, it answers our desire to
298 % provide our students with good audio support when studying their
299 % engineering courses. That is now, not only in five years time.
300 % }
301
302 % \<<<{
303 % We hope that you enjoy
304 % using our software, or that --- if you are not pleased with it ---
305 % it triggers you to give us feedback or to come up with a better
306 % solution. We especially would like to thank Ulrike Fischer (of the
307 % \LaTeX-project and the maintainer of the tagpdf package) for
308 % trying to use this package and reaching out to give us feedback.
309 % One of her suggestions (not to use big hyperlink-areas) was almost
310 % instantly implemented and has been adopted as the standard way of
311 % linking.
312 % }
313 %
314 % \<<<{
315 % You are free to use our software but kindly ask you to provide a
316 % mention ``The audio materials of this text have been prepared with
317 % \spelatex{}'' in the section treating copyrights,
318 % bibliographic data or any other spot of your text that is
319 % suited. We'd also welcome a short mail of yours telling that you
320 % make use of the package. The pleasure of receiving such an e-mail
321 % makes our day.
322 % }
323 %
324 % \<<<{
325 % You are free to modify this \LaTeX-package, keeping a reference to
326 % our original package intact, provided that your package is subject
327 % to the LPPL license, as is \spelatex{}. However, contributing to our
328 % package or to the \LaTeX{} project in general, might be a better
329 % way to go, in order to bundle the efforts
330 % for a better speech-enabled \LaTeX{}.
331 % }
332 %
333 % \section{Introduction}
334 %
335 % \subsection{Target audience}
336 % \<<<{
337 % \spelatex{} is primarily intended for persons with a reading
338 % disorder. This may be:
339 % }
340 % \begin{itemize}
341 % \spelitem{persons suffering dyslexia}
342 % \spelitem{visually impaired persons}
343 % \begin{itemize}
344 % \spelitem{persons who still can recognize the basic
345 % parts of a book,
346 % i.e. are able to operate a PDF viewer and click on the
347 % individual parts.}
348 % \spelitem{persons who can't recognize the basic parts of a book
349 % (e.g., blind persons): they can listen to the automatic
350 % playback of the ordered chain of audio fragments.}
351 % \end{itemize}
352 % \end{itemize}
353 %
354 % \<<<{
355 % But also people who want to multitask, e.g., gardening while
356 % listening to a technical book, can benefit from
357 % \spelatex{}.\footnote{Note that multitasking is not reserved for persons
358 % without visual impairment. Also visually impaired persons can
359 % benefit from listening to an audiobook while doing other
360 % things.}\\ We often use \spelatex{} to proofread the texts we've
361 % written ourselves as we hear language errors more easily than we
362 % spot them while reading.
363 % }
364 %
365 % \subsection{The magic under the hood}
366 %
367 % \subsubsection{The overall picture}
368 %
369 % \<<<{
370 % \spelatex{} equips the PDF that is generated by \LaTeX{}
371 % with hyperlinks to audio files that contain the spoken
372 % equivalent of the original text, equations, figures and tables.
373 % }
374 % \spelmacpp{figref}[1]{Fig.~\ref{#1}}
375 % \newcommand\figref[1]{Fig.~\ref{#1}}
376 % \begin{spelchunk}
377 % Let's start by considering the flow depicted in
378 % Fig.~\ref{fig:setup} at the top of the diagram. \figref{fig:setup}
379 % By loading the |spel.sty| package in your source
380 % document (|text.tex|), \LaTeX{} will produce a PDF file that references audio
381 % files that will be generated later (see below). In
382 % addition, it generates text chunks (i.e. small portions of
383 % your text) in separate files (|.tex|) and a spel index file
384 % (|.spelidx|) referencing them in sequence.
385 % \end{spelchunk}
386 %
387 % \<<<{
388 % Together with the |.aux|-file (needed by \spelatex{} for labels and
389 % citations), these are the inputs to the \spelatex-engine (|spel-wizard.pl|)
390 % that parses the text chunks, writes a full text version of them as
391 % spel files (with extension |.spel|) and
392 % controls the text-to-speech engine to generate audio versions of
393 % them.\footnote{In the figure, Ogg Vorbis has been chosen as
394 % format, but this can be any audio format.}
395 % }
396 %
397 % \<<<{
398 % To avoid excessive text to speech conversion (i.e. an expensive step)
399 % the \spelatex{} engine derives an MD5 fingerprint of them and compares it
400 % to previously generated fingerprints for the chunk. If the
401 % fingerprint has changed, the audio file is overwritten (or
402 % created the first time), otherwise it is left untouched.
403 % }
404 %
405 % \<<<{
406 % As a cherry on top, the \spelatex-engine also creates a top-level playlist,
407 % such that you may use the audio files for a \POD{}cast-like
408 % listening experience.\\
409 % Something that has not been indicated on the figure, is that for
410 % reading out loud entire (sub)sections, the PDF-file also references
411 % m3u playlists that gather all chunks belonging to the (sub)section.
412 % }
413 %
414 % \begin{figure}
415 % \begin{spelchunk}
416 % \begin{center}
417 % \begin{tikzpicture}
418 % [scale=0.8,>=latex,
419 % doc/.style={rectangle,fill=black!10,align=center,minimum
420 % width=2cm,minimum height=2cm},
421 % tool/.style={rectangle,draw,align=center}]
422 % \node [doc] (text) at (0,3) {text.tex\\\footnotesize(source file)};
423 % \node [doc] (R) at (-3,0) {spel.sty\\\footnotesize(package)};
424 % \node [tool] (latex) at (0,0) {\LaTeX\\\footnotesize(compiler)};
425 % \node [doc] (pdf) at (0,-3) {text.pdf\\\footnotesize(PDF with\\\footnotesize hyperlinks)};
426 % \node [doc] (spelidx) at (6,-3) {text.spelidx\\\footnotesize(index file)};
427 % \node [doc] (aux) at (9,-3) {text.aux\\\footnotesize(auxiliary file)};
428 % \node [doc] (files) at (3,-3) {*.tex\\\footnotesize(text chunks)};
429 % \draw[->] (text) -- (latex);
430 % \draw[->,dotted] (text) -- (R);
431 % \draw[->,dotted] (spelidx) -- (files);
432 % \draw[->] (R) -- (latex);
433 % \draw[->] (latex) -- (pdf);
434 % \draw[->] (latex) edge[out=0,in=90] (spelidx);
435 % \draw[->] (latex) edge[out=10,in=90] (aux);
436 % \draw[->] (latex) edge[out=-10,in=90] (files);
437 % \node [tool] (engine) at (6,-6) {\spelpl{}\\
438 % \footnotesize(\spelatex{} engine)};
439 % \node [tool] (t2s) at (1.5,-6) {text-to-speech\\engine};
440 % \draw[->] (files) -- (engine);
441 % \draw[->] (spelidx) -- (engine);
442 % \draw[->] (aux) -- (engine);
443 % \node[doc] (ogg) at (0,-9) {*.ogg\\\footnotesize(audio files)};
444 % \node[doc] (spel) at (3,-9) {*.spel\\\footnotesize(spel files)};
445 % \node[doc] (m3u) at (6,-9) {text.m3u\\\footnotesize(playlist)};
446 % \node[doc] (md5) at (9,-9) {*.md5\\\footnotesize(fingerprints)};
447 % \draw[->] (engine) -- (spel);
448 % \draw[->] (engine) -- (m3u);
449 % \draw[<->] (engine) -- (md5);
450 % \draw[->,dotted] (pdf) edge[out=-115,in=115] (ogg);
451 % \draw[->,dotted] (m3u) edge[out=-125,in=-55] (ogg);
452 % \draw[->,dashed] (engine) -- (t2s);
453 % \draw[->] (spel) -- (t2s);
454 % \draw[->] (t2s) -- (ogg);
455 % \end{tikzpicture}
456 % \end{center}
457 % \end{spelchunk}
458 % \begin{spelchunkad}
459 % If you load the \spelatex{} style file in your source file (at the
460 % top of the figure) and prepare your source file according to the
461 % instructions in this manual, than
462 % your compiler will generate a PDF file with hyperlinks, a
463 % dot aawks-file and a dot spellindex-file together with a directory full of
464 % dot tex files containing the text chunks to be processed by the
465 % \spelpl-engine. This is a perl script that converts the chunks into
466 % plain text readable spel files. The script is called spel dash
467 % wizard dot pl. It also creates a playlist and audio files using a
468 % text-to-speech engine. In this case, these are
469 % Ogg-Vorbis files. To avoid having to call the text-to-speech
470 % engine too frequently (which may incur costs), MD5 fingerprints
471 % are used such that chunks that have been generated before and
472 % are unchanged, can be reused. The end result is a PDF file that
473 % references the audio files.
474 % \end{spelchunkad}
475 % \spelcaption{Basic tool setup of the \spelatex{} package; filled boxes indicate
476 % files, outlined boxes indicate tools; solid lines indicates use or
477 % creation of files, dotted lines indicate references, dashed lines
478 % indicate a control relationship.}
479 % \label{fig:setup}
480 % \end{figure}
481 %
482 % \<<<{
483 % You might wonder: where are the links? Well, there are three
484 % variants:
485 % }
486 % \begin{itemize}
487 % \spelitem{\emph{area links}, which are almost exclusively
488 % used for equations, tables or figures. These links make an entire
489 % rectangle active, linking to the corresponding audio file.}
490 % \spelitem{\emph{group links}, indicated by small right-pointing
491 % triangles next to section headers (on the far right). These cause all
492 % blocks in the section to be read one by one.\\
493 % In case you specify the
494 % package option \texttt{markervisibility=none} these triangles will become
495 % invisible. However, the clickable areay still exists. Try!}
496 % \spelitem{\emph{chunk links}, before every
497 % paragraph, footnote or list, a small triangle indicates a clickable link.\\
498 % If you activate the package option \texttt{markervisibility=onlygroups}, they will
499 % become invisible, but still clickable. Try it! Once you
500 % are aware that these regions are active, you'll find them
501 % easily. Not using the full paragraph as an active
502 % region, allows existing hyperlinks (like for citations, references
503 % or URLs) to still function.}
504 % \end{itemize}
505 %
506 %
507 % \subsubsection{Implicit spelchunks}
508 % \spelmacad{usepackage}[1]{the usepackage #1 macro}
509 % \spelmacad{title}{the title macro}
510 % \spelmacad{author}{the author macro}
511 % \spelmacad{section}{the section macro}
512 % \spelmacad{caption}{the caption macro}
513 % \spelmacad{footnote}{the footnote macro}
514 % \spelmacad{thanks}{the thanks macro}
515 % \spelmacad{item}{the item macro}
516 % \spelmacad{spelitem}{the spelitem macro}
517 % \<<<{
518 % Generating the text chunks to be read out loud requires us to use
519 % special \LaTeX-macros. For all pieces of text that are within
520 % an existing macro (e.g. |\title|, |\author|, |\section|,
521 % |\footnote|, |\thanks|), these macros have been
522 % redefined by the \spelatex{}-package to
523 % execute the magic without any further hassle.\\
524 % We call these \LaTeX-fragments \emph{implicit spelchunks}.%
525 % }
526 %
527 % \<<<{
528 % However, not all \LaTeX-constructs can be dealt with in an
529 % automatic way. This is true for any |\item| you put inside a list.
530 % You need to replace that with a |\spelitem| that takes the text
531 % that follows as a first explicit argument, i.e. |\item blabla|
532 % should be replaced by |\spelitem{blabla}|.
533 % The same holds for any |\caption|. Too many packages (like
534 % subcaption/subfigure) redefine captions, so I chose to stay out of
535 % their way. Therefore every |\caption| must be replaced by a
536 % |\spelcaption|.
537 % }
538 % \<<<{
539 % We call these \LaTeX-fragments \emph{defunct implicit
540 % spelchunks}. They should have been implicit, but we could not get
541 % that to work without problems. Therefore you need to mark them
542 % explicitly as |\spelitem| constructs.
543 % }
544 %
545 % \subsubsection{Explicit spelchunks}
546 % \<<<{
547 % One would hope that displaymath environments are also implicit
548 % spelchunks. However, overriding environments in \LaTeX{} is a tricky
549 % business. In view of this, the \spelatex{} package keeps away from
550 % this, and we've chosen to treat displaymath environments (like
551 % |equation|, |eqnarray|, |gather|, |align|, |alignat|) the same way
552 % as tables or figures, i.e. you need to embed the in a |spelchunk|
553 % environment. The only difference between math environments and
554 % figures an tables is that displaymath environments can be
555 % automatically read out loud by the \spelpl{} script, while you
556 % will have to provide a text description for tables and figures
557 % manually, using a subsequence |spelchunkad|
558 % environment (the suffix ad stands for \emph{audio description}).
559 % }
560 %
561 % \<<<{
562 % To keep the terminology clear, we label them as automatic
563 % and manual explicit spelchunks respectively:
564 % }
565 % \begin{itemize}
566 % \spelitem{automatic: \texttt{equation}, \texttt{eqnarray},
567 % \texttt{gather}, \texttt{align}, \texttt{alignat}, \ldots}
568 % \spelitem{manual: \texttt{figure}, \texttt{table},
569 % \texttt{tikzpicture}, \ldots}
570 % \end{itemize}
571 %
572 % \<<<{
573 % The similarity between both categories is that you both embed them
574 % in a |spelchunk| environment, but that you provide the manual
575 % textual description using a |spelchunkad| environment right after
576 % the chunk for the manual ones: in this way, the |spelchunkad| environment provides an
577 % alternative text for the chunk. Note that this way of working also
578 % enables you to provide an overriding text for an automatic spelchunk,
579 % e.g., an equation, if you
580 % think that \spelpl{} is doing a bad job. You do us a favor if
581 % you submit this subpar behavior as a bug report to us!
582 % }
583 %
584 % \<<<{
585 % It is worthwile to make good descriptions for a figure or a
586 % table. It's here that you can create true added value to your
587 % manuscript, even for readers without impairment!
588 % }
589 %
590 % \subsubsection{Paragraphs}
591 % \<<<{
592 % However, there is the elephant in the room that we did not yet
593 % talk about, the paragraph. Indeed, it is desirable to split plain
594 % text according to the paragraphs in the document. Alas, paragraphs
595 % are one of the silent features that are
596 % not easily accessible from within a \LaTeX-package.
597 % Therefore paragraphs (or smaller text chunks) are considered to be
598 % explicit spelchunks and need to be embedded
599 % in |spelchunk| environments. This environment will cause its
600 % contents to be hyperlinked to a separate piece of audio.
601 % }
602 %
603 % \<<<{
604 % Encasing all your paragraphs with |spelchunk| environments
605 % manually is a pain. There is a reason why in \LaTeX{}
606 % paragraphs can be created by a double newline: convenience.
607 % The |spelchunk|-environment encasing ruins this totally!
608 % }
609 % \spelmacad{<<<}{the shorthand macro}
610 % \<<<{
611 % To ease the pain and in order to avoid the visual intrusiveness of the
612 % spelchunk environments, you can also use the \texttt{\textbackslash{}<<<\{\}} command to
613 % encase your paragraphs. In some cases the \texttt{\textbackslash{}<<<\{\}}
614 % command will not work, e.g., if there is a |Verbatim| environment
615 % inside. In that case you must use the |spelchunk| environment directly.
616 % }
617 %
618 % \subsection{Extra math commands}
619 %
620 % \<<<{
621 % Some of the ways to specify mathematical expressions in \LaTeX{} is
622 % very liberal, what makes converting them to text quite
623 % difficult. Therefore, we also provide some
624 % extra constructs that make life easier for both parties: you as a
625 % user and \spelpl{} as a parser.
626 % }
627 %
628 % \<<<{
629 % An example of this are sets. We provide two commands to define a
630 % set. As we want these commands to blend in with general \LaTeX{},
631 % we did not equip them with a prefix |spel|. Therefore, we made
632 % activating them conditional to specifying the package option
633 % |extramath|.
634 % }
635 % \begin{description}
636 % \spelitem[\texttt{\textbackslash{}setenum}]{a command to define a set
637 % that consists of comma or semicolon separated elements}
638 % \spelitem[\texttt{\textbackslash{}setdesc}]{a command to define a
639 % set that is specified using a description}
640 % \end{description}
641 %
642 %
643 % \subsection{Added value}
644 %
645 % \<<<{
646 % Why would it make sense to use \spelatex? We think there are many
647 % selling points. We can mention a few:
648 % }
649 % \begin{description}
650 % \spelitem[Free for the content provider]{
651 % If you are using a freeware text-to-speech engine (like for
652 % example festival \cite{FESTIVAL} or balabolka \cite{BALABOLKA})
653 % and a royalty-free audio format and player (like for example
654 % ogg-vorbis), generating audio-enabled documents only requires
655 % the effort of preparing your manuscript. There are no license
656 % costs involved.\\
657 % You could also consider to use an online paying text-to-speech
658 % service. As an example, we incorporated a connection to Amazon's
659 % Polly \cite{AWSPOLLY}. We admit, it's not free, but it doesn't
660 % cost an arm and a leg either.\\
661 % In addition, if your user has a better-quality (maybe
662 % commercial) text-to-speech system, he/she can reconvert the text
663 % files him-/herself, equiping your document with a voice they
664 % like and are used to, without you having to worry about license
665 % costs. They might even use an AI-generated copy of their own
666 % voice!}
667 % \spelitem[Free for your audience]{
668 % In addition, the user of your audio-enabled document doesn't
669 % need to buy a license for text-to-speech software. Only a PDF-viewer
670 % and a standard audio-player program are required.}
671 % \spelitem[Math capable]{
672 % Try some of the equations in this manuscript in
673 % section~\ref{sec:demo}. We are quite confident you'll be
674 % convinced fairly soon.}
675 % \end{description}
676 %
677 % \section{Installation}
678 %
679 % \subsection{The \spelatex{} package}
680 % \<<<{
681 % If you are a package manager then you'll know how to
682 % prepare an installation package for \spelatex.
683 % }
684 %
685 % \<<<{
686 % If you are a normal user, check if there is a package that your
687 % favorite \LaTeX{} distributor has prepared for you. Most of the
688 % major distributions (like e.g. \TexLive{} or \MikTeX{}) do so.\\
689 % The fallback option is to grab the |spelatex.sty| file from CTAN
690 % and put it in our \TeX{} search path.
691 % }
692 %
693 % \<<<{
694 % The \spelatex{} package uses a number of auxiliary packages, fetch them
695 % from \CTAN{} \cite{CTAN} if your \TeX{} distributor does not provide
696 % them. The ones used are: |expl3|, |hyperref|, |xcolor|, |ifthen|, |verbatim|,
697 % |fancyvrb|, |newfile|, |rotating|, |babel|, |kvoptions| and |xkeyval|.
698 % }
699 %
700 % \subsection{The \spelpl{} speech generator}
701 %
702 % \subsubsection{The script}
703 % \<<<{
704 % You can install the wizard assuming you have a working Perl
705 % interpreter installed. Assuming you're on \GNU/Linux or MAC, you
706 % should be able to find an installation package using the package
707 % manager for your distribution. If you are on MS-Windows, look for
708 % Strawberry perl or ActiveState perl.
709 % }
710 %
711 % \<<<{
712 % The only thing to do is to install the |SpeL::Wizard|
713 % module. You can do this with the perl pacakge manager for your
714 % interpreter.
715 % }
716 %
717 % \<<<{
718 % Open a terminal or command window, and then enter on the
719 % command line (the dollar represents your prompt):
720 % }
721 %
722 % \<<<{
723 % On \GNU/Linux and MAC: |$ cpanm SpeL::Wizard|\\
724 % For Strawberry perl: |$ cpan SpeL::Wizard|\\
725 % For ActiveState perl: |$ ppm install SpeL-Wizard|
726 % }
727 %
728 % \<<<{
729 % The script \spelpl{} will be installed on your system. Make sure
730 % it is on your search path.
731 % }
732 %
733 % \subsubsection{The configuration file}
734 %
735 % \begin{spelchunk}
736 % Finally, you need to provide \spelpl{} with an appropriate
737 % config-file, named |tts.conf| that sets up the text-to-speech conversion.
738 % Below you can find a setup for Festival \cite{FESTIVAL}:
739 % \begin{Verbatim}
740 % [engine]
741 % tts=festival
742 %
743 % [languagetags]
744 % dutch=nl
745 % english=en-gb
746 %
747 % [voices]
748 % dutch=nl1_mbrola
749 % english=en1_mbrola
750 % \end{Verbatim}
751 % \end{spelchunk}
752 %
753 % \begin{spelchunk}
754 % And additionally, for the Microsoft users a setup for Balabolka \cite{BALABOLKA}:
755 % \begin{Verbatim}
756 % [engine]
757 % tts=balabolka
758 %
759 % [languagetags]
760 % english=en-us
761 %
762 % [voices]
763 % english=Zira
764 % \end{Verbatim}
765 % \end{spelchunk}
766 %
767 % \<<<{
768 % The tts configuration parameter defines the speech engine to use.
769 % The languagetags section defines how the babel languages are mapped to
770 % internationalization codes (also known as locales).
771 % The voices section specifies what voice to use for a specific language.
772 % }
773 %
774 % \begin{spelchunk}
775 % An environment variable can specify where your config file is
776 % located, e.g., on \GNU/Linux:
777 % \begin{Verbatim}
778 % $ export SPELWIZARD_CONFIG=/home/wdaems/.config/tts.conf
779 % \end{Verbatim}
780 % \end{spelchunk}
781 % \begin{spelchunk}
782 % If that variable is not set, the script will look in a subdirectory
783 % |.spel_wizard| of your home-folder (or |%userprofile%| on
784 % MS-Windows), or it will take the default that came with the
785 % |SpeL::Wizard| module.
786 % \end{spelchunk}
787 %
788 % \<<<{
789 % Be aware that you need to install your text-to-speech tool yourself
790 % according to the documentation provided by the tool provider.
791 % In addition, make sure it the executable is in your search path. In
792 % case you are using an online text-to-speech service provider you
793 % will need to get an account on their cloud platform and setup
794 % credentials and whatever is needed to get going. Providing
795 % assistance for this is beyond the aim of this manual.
796 % }
797 %
798 % \subsection{The PDF viewer}
799 %
800 % \<<<{
801 % You need to make sure you have a PDF-viewer that supports file links
802 % E.g., xpdf \cite{XPDF} does not, but evince \cite{EVINCE}, okular
803 % \cite{OKULAR} and Adobe Reader \cite{ADOBEREADER} do.
804 % }
805 %
806 % \subsection{The media player}
807 %
808 % \<<<{
809 % When clicking a \spelatex-enabled item in your PDF-file, your media
810 % player is started to play the |.ogg| or |.m3u|-file. On GNU/Linux
811 % most media players work fine (SoX, totem, vlc, \ldots).
812 % }
813 %
814 % \<<<{
815 % On windows, we recommend using vlc. It works out of the box.
816 % When using the stock Windows Media Player, you will need to add
817 % every folder that contains a PDF you'd like to have read, to your
818 % Media Player library. Search the internet to find instructions on
819 % that and be prepared: in line with Microsoft's standard practice it
820 % is well hidden in the interface.
821 % }
822 %
823 % \<<<{
824 % If you gave the |server| option to the \spelatex{} package, then your
825 % favorite webbrowser will be started to download and play the file.
826 % If you move it out of your way, you can avoid that it jumps in front of
827 % your text every time again.
828 % }
829 %
830 % \section{Usage}
831 %
832 % \subsection{Preparing your document source}
833 % \begin{spelchunk}
834 % Using the \spelatex{} package is very simple. Just load the package's
835 % style file using an appropriate |\usepackage{spelatex}|.
836 % \end{spelchunk}
837 %
838 % \<<<{
839 % There are $5$ things to do:
840 % }
841 % \begin{enumerate}
842 % \spelitem{Treat the defunct implicit spelchunks.}
843 % \spelitem{Treat the explicit spelchunks.}
844 % \spelitem{Manually provide text to read when needed.}
845 % \spelitem{Provide audiodescriptions or preprocessing instructions
846 % for your typesetting macros.}
847 % \spelitem{Provide audiodescriptions or preprocessing instructions
848 % for your typesetting environments.}
849 % \end{enumerate}
850 %
851 % We will now explain all required macros.
852 %
853 % \subsubsection{Treat the implicit spelchunks}
854 % \<<<{
855 % The texts of chapter, (sub)section titles, a.s.o. will be formatted
856 % automatically such that they are hyperlinked to the appropriate
857 % audio file. Therefore, this step was not mentioned above. It is done
858 % automatically for you by using the \spelatex{} package.
859 % }
860 %
861 % \<<<{
862 % You only need to cover your \emph{defunct implicit spelchunks}:\\
863 % \DescribeMacro{\spelitem}
864 % Use this macro instead of the \texttt{\textbackslash{}item} macro to make
865 % sure your list environments are converted to speech chunks
866 % appropriately.
867 % }
868 %
869 % \begin{spelchunk}
870 % Example:
871 % \begin{Verbatim}
872 % We like
873 % \begin{itemize}
874 % \spelitem{apples,}
875 % \spelitem{pears, and}
876 % \spelitem{oranges.}
877 % \end{itemize}
878 % \end{Verbatim}
879 % \end{spelchunk}
880 % \begin{spelchunk}
881 % Another example:
882 % \begin{Verbatim}
883 % If you don't know these fruits:
884 % \begin{description}
885 % \spelitem[apple]{a green round fruit}
886 % \spelitem[pears]{a green pointy-shaped fruit}
887 % \spelitem[orange]{an orange round fruit}
888 % \end{description}
889 % \end{Verbatim}
890 % \end{spelchunk}
891 %
892 % \subsubsection{Treat the explicit spelchunks}
893 % \label{sec:explicitspelchunks}
894 % \<<<{
895 % \DescribeEnv{spelchunk}
896 % Use this environment to embed the chunks of text in that you want
897 % to generate audio for. In case the content is an equation, a
898 % figure or a table, we recommend specifying |arealink| as the
899 % optional argument to the |spelchunk| environment. It makes the
900 % entire equation an active hyperlink.
901 % Note that you cannot specify an |arealink| when the area to be covered is
902 % vertical-mode object. In common language: put your |arealink| |spelchunk|
903 % environments inside a |center| environment and not the other way around.
904 % }
905 %
906 % \<<<{
907 % Example:\\
908 % {\footnotesize (note: the example below is not \spelatex{}-enabled
909 % in this manual because it generates internal package problems)}
910 % }
911 % \begin{Verbatim}
912 % \begin{spelchunk}
913 % An ordinary paragraph must be embedded in this environment.
914 % The same holds for equations! However, then we recommend using
915 % the |arealink| option, as that makes the full area of the
916 % equation clickable and avoids an empty white line before the
917 % equation.
918 % \end{spelchunk}
919 % \begin{spelchunk[arealink]
920 % \begin{align}
921 % E &= m c^2\\
922 % e^{j\pi} &= -1
923 % \end{align}
924 % \end{spelchunk}
925 % \end{Verbatim}
926 %
927 %
928 % \subsubsection{Manually provide text to read when needed}
929 % \begin{spelchunk}
930 % \DescribeEnv{spelchunkad}
931 % If you want a different text to be used for the previous
932 % spelchunk environment, this environment allows you to specify it.
933 % For plain text or math environments, this is also your generic escape
934 % route in case the \spelpl{} parser does not work as you'd like
935 % it to.\\
936 % \end{spelchunk}
937 % \begin{spelchunk}
938 % Just have your |spelchunk| environment followed by a
939 % |spelchunkad| environment that specifies the correct text to read
940 % out loud. However, please, file a bug report, such that we can
941 % improve the tool.
942 % \end{spelchunk}
943 %
944 % \begin{spelchunk}
945 % Example:\\
946 % {\footnotesize (note: the example below is again not \spelatex{}-enabled because it
947 % generates internal package problems)}
948 % \end{spelchunk}
949 % \begin{Verbatim}
950 % \begin{spelchunk}
951 % An ordinary paragraph must be embedded in this environment.
952 % \end{spelchunk}
953 % \begin{spelchunkad}
954 % Do not forget to embed ordinary paragraphs in this environment.
955 % \end{spelchunkad}
956 % \end{Verbatim}
957 %
958 % \begin{spelchunk}
959 % For non-textual material such as figures or tables, this allows you
960 % to specify a sensible text that acts as an audio description for
961 % that material.\\
962 % Just have your |spelchunk| environment that surrounds your figure
963 % or table, followed by a |spelchunkad| environment that provides
964 % the audio description for the non-textual material.
965 % \end{spelchunk}
966 %
967 % \begin{spelchunk}
968 % Example:\\
969 % {\footnotesize (note: the example below is for a third time not \spelatex{}-enabled because it
970 % generates internal package problems)}
971 % \end{spelchunk}
972 % \begin{Verbatim}
973 % \begin{spelchunk}
974 % \includegraphics{engine.jpg}
975 % \end{spelchunk}
976 % \begin{spelchunkad}
977 % The image shows a turbo-fan engine of an aircraft. One can
978 % clearly see the silver blades of the fan, and the housing. Note
979 % how little spacing there is between the blades and the housing.
980 % \end{spelchunkad}
981 % \end{Verbatim}
982 %
983 % \subsubsection{Use the shorthand \texttt{\textbackslash <<<}-macro}
984 %
985 % \DescribeMacro{\<<<}
986 % \<<<{
987 % This macro takes the text to be read-out loud as an
988 % argument. It is a shorthand for the |spelchunk|
989 % environment. Options you would have given to the |spelchunk|
990 % environment can be given as an optional argument to this macro.
991 % }
992 %
993 % \<<<{
994 % Retaking the example of section~\ref{sec:explicitspelchunks},
995 % using the shorthand, we obtain:\\
996 % {\footnotesize (note: the example below is once again not \spelatex{}-enabled
997 % in this manual because it generates internal package problems)}
998 % }
999 % \begin{Verbatim}
1000 % \<<<{
1001 % An ordinary paragraph must be embedded in this macro.
1002 % The same holds for equations! However, then we recommend using
1003 % the |arealink| option, as that makes the full area of the
1004 % equation clickable and avoids an empty white line before the
1005 % equation.
1006 % }
1007 % \<<<[arealink]{
1008 % \begin{align}
1009 % E &= m c^2\\
1010 % e^{j\pi} &= -1
1011 % \end{align}
1012 % }
1013 % \end{Verbatim}
1014 %
1015 %
1016 % \subsubsection{Provide descriptions for typesetting macros}
1017 %
1018 % \DescribeMacro{\spelmacad}
1019 % \begin{spelchunk}
1020 % Often, recurring constructs are being typeset using a dedicated
1021 % macro, defined by the user.
1022 % For example, to consistently typeset input voltages for arbitrary pins,
1023 % one might have defined the macro:
1024 % \begin{Verbatim}
1025 % \newcommand\vin[2][IN]{\ensuremath{v_{\mathit{#1},#2}}}
1026 % \end{Verbatim}
1027 % \end{spelchunk}
1028 % \newcommand\vin[2][IN]{\ensuremath{v_{\mathit{#1},#2}}}%
1029 % \spelmacad{vin}[2][IN]{the #1put voltage at pin #2}%
1030 % \begin{spelchunk}
1031 % This allows easy specification of
1032 % \begin{Verbatim}
1033 % \vin{1} = \sin 20 t
1034 % \end{Verbatim}
1035 % resulting in $\vin{1} = \sin 20 t$.
1036 % \end{spelchunk}
1037 %
1038 % \begin{spelchunk}
1039 % However one might want this line to be read as 'the input voltage
1040 % at pin 1 equals sine 20 t'.\\
1041 % To this end, one can provide an description for this macro
1042 % using the |spelmacad| macro.
1043 % \end{spelchunk}
1044 %
1045 % \begin{spelchunk}
1046 % Example:
1047 % \begin{Verbatim}
1048 % \spelmacad{vin}[1][IN]{the #1put voltage at pin #2}
1049 % \end{Verbatim}
1050 % Note that the audio description in this case will only be
1051 % acceptable, for arguments IN and OUT. One clearly has to take the
1052 % audio description into account when defining \LaTeX{}-macros.
1053 % \end{spelchunk}
1054 %
1055 % \subsubsection{Descriptions for typesetting environments}
1056 %
1057 % \DescribeMacro{\spelenvad}
1058 % \begin{spelchunk}
1059 % Often, recurring constructs are being typeset using a dedicated
1060 % environment, defined by the user.
1061 % For example, to consistently typeset a proof or illustration one might
1062 % have defined the environment:
1063 % \begin{Verbatim}
1064 % \newenvironment{proof}[2][Proof]{
1065 % \textbf{#1: #2}\\
1066 % }
1067 % {
1068 % \hfill$\blacksquare$\\
1069 % }
1070 % \end{Verbatim}
1071 % \end{spelchunk}
1072 % \begin{spelchunk}
1073 % This allows easy specification of an illustration as:
1074 % \begin{Verbatim}
1075 % \begin{proof}[Illustration]{solving a quadratic equation}
1076 % blabla
1077 % \end{proof}
1078 % \end{Verbatim}
1079 % \end{spelchunk}
1080 % \begin{spelchunk}
1081 % However one might want this environment to be read as
1082 % 'Illustration of solving a quadratic equation: blabla. This
1083 % concludes this illustration.'\\
1084 % To this end, one can provide an description for this macro
1085 % using the |spelenvad| macro.
1086 % \end{spelchunk}
1087 %
1088 %
1089 % \begin{spelchunk}
1090 % Example:
1091 % \begin{Verbatim}
1092 % \spelenvad{proof}[1][Illustration]
1093 % {#1 of #2:}
1094 % {This concludes this #1.}
1095 % \end{Verbatim}
1096 % \end{spelchunk}
1097 %
1098 % \subsubsection{Inline descriptions}
1099 % \DescribeMacro{\spelinlad}
1100 % \<<<{
1101 % Sometimes a spel chunk contains a subblock that cannot be treated by the
1102 % wizard. E.g., een tikzpicture that is included in an align environment.
1103 % Nesting spelchunks is unfortunately not possible.
1104 % In that case, one can use the |\spelinlad| macro. This takes two arguments,
1105 % the first being the part that needs to end up in your written manuscript,
1106 % the second argument is the audio description.}
1107 %
1108 % \<<<{The following equation illustrates its use:}
1109 % \begin{Verbatim}
1110 % \begin{spelchunk}[arealink]
1111 % \begin{align}
1112 % \phi &= \arctan \frac{\sqrt{1-\zeta^2}}{\zeta}\\
1113 % &~~\spelinlad{
1114 % \begin{tikzpicture}
1115 % \draw[->] (-0.5,1) -- (-0.5,-0.5);
1116 % \draw(0,0) -- node[below] {$\zeta$} (2,0)
1117 % -- node[right] {$\sqrt{1-\zeta^2}$} (2,1)
1118 % -- node[above left] {$1$} cycle;
1119 % \draw (0:0.5) arc (0:28:0.5);
1120 % \end{tikzpicture}
1121 % }{\text{Given the trigonometric relations in the triangle,
1122 % we can deduce}}\\
1123 % &= \arccos \zeta
1124 % \end{align}
1125 % \end{spelchunk}
1126 % \end{Verbatim}
1127 %
1128 % \<<<{When you run this code through \LaTeX{} you obtain:}
1129 % \begin{spelchunk}[arealink]
1130 % \begin{align}
1131 % \phi &= \arctan \frac{\sqrt{1-\zeta^2}}{\zeta}\\
1132 % &~~\spelinlad{
1133 % \begin{tikzpicture}
1134 % \draw[->] (-0.5,1) -- (-0.5,-0.5);
1135 % \draw(0,0) -- node[below] {$\zeta$} (2,0)
1136 % -- node[right] {$\sqrt{1-\zeta^2}$} (2,1)
1137 % -- node[above left] {$1$} cycle;
1138 % \draw (0:0.5) arc (0:28:0.5);
1139 % \end{tikzpicture}
1140 % }{\text{Given the trigonometric relations in the triangle,
1141 % we can deduce}}\\
1142 % &= \arccos \zeta
1143 % \end{align}
1144 % \end{spelchunk}
1145 %
1146 % \subsubsection{Using the i18n features of \spelpl when describing
1147 % your macros and environments}
1148 % \begin{spelchunk}
1149 % Sooner rather than later you will feel the need to provide reading
1150 % alternatives for your constructs that are language dependent. In
1151 % that case you can call the i18n features that are built into
1152 % \spelpl. We illustrate this with an example.
1153 % \end{spelchunk}
1154 %
1155 % \begin{spelchunk}
1156 % Assume you've made your own command to raise numbers to a power,
1157 % and you provide and description for your macro.
1158 % \end{spelchunk}
1159 % \begin{Verbatim}
1160 % \newcommand\numtopower[2]{#1^{#2}}
1161 % \spelmacad{numtopower}[2]{#1 to the power of #2}
1162 % \end{Verbatim}
1163 %
1164 % \begin{spelchunk}
1165 % The problem with this solution is, that it only works for one
1166 % language. The solution is to use an i18n expression in your
1167 % description:
1168 % \end{spelchunk}
1169 % \begin{Verbatim}
1170 % \spelmacad{numtopower}[2]{#1 @{i18n(Power,#2)}}
1171 % \end{Verbatim}
1172 % \begin{spelchunk}
1173 % This will call the maketext function (See Locale::Maketext) on
1174 % the Lexicon provided in SpeL::Wizard::I18n, as:
1175 % \end{spelchunk}
1176 % \begin{Verbatim}
1177 % $SpeL::Wizzard::I18n::lh->maketext( 'Power', "#2")
1178 % \end{Verbatim}
1179 % \begin{spelchunk}
1180 % to read your macro.
1181 % \end{spelchunk}
1182 %
1183 % \subsubsection{The extra math commands}
1184 % Note that these commands are only available if you provide the
1185 % package option |extramath|.
1186 %
1187 % \DescribeMacro{\setenum}
1188 % \begin{spelchunk}
1189 % This macro typesets an enumeration set and makes sure \spelpl{}
1190 % can read it properly.
1191 % \end{spelchunk}
1192 % \begin{spelchunk}
1193 % \begin{Verbatim}
1194 % \begin{equation}
1195 % P = \setenum{ 2, 3, 5, 7, 11, 13, \ldots }
1196 % \end{equation}
1197 % \end{Verbatim}
1198 % \end{spelchunk}
1199 %
1200 % \DescribeMacro{\setdesc}
1201 % \begin{spelchunk}
1202 % This macro typesets a definition set and makes sure \spelpl{}
1203 % can read it properly.
1204 % \end{spelchunk}
1205 % \begin{spelchunk}
1206 % \begin{Verbatim}
1207 % \begin{equation}
1208 % P = \setdesc{ n \in \mathbb{N} \mid n \text{~is prime} }
1209 % \end{equation}
1210 % \end{Verbatim}
1211 % \end{spelchunk}
1212 %
1213 % \subsection{Going through the flow}
1214 % \begin{spelchunk}
1215 % Once your document source has been prepared, you are ready for the
1216 % regular \spelatex-flow. It consists of 3 steps.
1217 % \end{spelchunk}
1218 %
1219 % \begin{enumerate}
1220 % \spelitem{Create a \texttt{jobname-spel} subdirectory in the
1221 % working directory your \LaTeX{} source document is in (replace
1222 % jobname with the basename of your latex file, the final
1223 % \texttt{-spel} is a literal).}
1224 % \spelitem{Run your document
1225 % 3-times through your \{pdf,Xe,Lua\}\LaTeX{}-compiler to get all
1226 % the references right.}
1227 % \spelitem{Run the \spelpl{} speech
1228 % generator (see scripts directory or the wrapper provided by the
1229 % package manager), by launching it with the base name of your
1230 % document as command-line
1231 % argument.\\
1232 % E.g.: \texttt{\spelpl{} -v example}}\\
1233 % The |-v| argument causes the script to be somewhat more verbose.
1234 % \end{enumerate}
1235 %
1236 % \begin{spelchunk}
1237 % The result of this will be a PDF file equipped with links to audio
1238 % files in the 'speech' subdirectory. Alas your PDF file has been
1239 % become a little less portable, as it now requires the 'speech'
1240 % subdirectory to be complete. You might want to package the
1241 % ensemble into a tar-file or zip-archive.
1242 % \end{spelchunk}
1243 %
1244 %%
1245 % \section{Example}
1246 %
1247 % \begin{spelchunk}
1248 % Below, you can find a simple example to give you a head-start.
1249 % In order not to spoil the fun for you, the embedded version here
1250 % is not speech-enabled.
1251 % \end{spelchunk}
1252 %
1253 % \begin{VerbatimOut}[gobble=4]{Example/example.tex}
1254 % \documentclass{report}
1255 %
1256 % \usepackage[dutch,english]{babel} % load babel before spelatex to avoid
1257 % % option clash!
1258 % \selectlanguage{english}
1259 % \usepackage[format=ogg,
1260 % server=https://ctan.org/tex-archive/macros/latex/contrib/spelatex/Example
1261 % ]
1262 % {spelatex}
1263 %
1264 % \newrobustcmd\CTAN{CTAN}
1265 % \spelmacad{CTAN}{see-tan}
1266 % \newrobustcmd\CPAN{CPAN}
1267 % \spelmacad{CPAN}{see-pan}
1268 %
1269 % \title{\spelatex{} Example}
1270 % \author{Walter Daems and Paul Levrie}
1271 % \date{2025/06/15}
1272 % \setlength\parindent{0em}
1273 % \setlength\parskip{1ex}
1274 %
1275 % \begin{document}
1276 %
1277 % \maketitle
1278 %
1279 % \chapter{Introduction}
1280 %
1281 % \<<<{
1282 % This file is just a simple showcase of the features of \spelatex{}.
1283 % Below, you'll find examples of:
1284 % }
1285 %
1286 % \begin{itemize}
1287 % \spelitem{a simple equation}
1288 % \spelitem{a more complex equation}
1289 % \end{itemize}
1290 %
1291 % \chapter{Examples}
1292 % \section{A simple equation}
1293 % \label{eqn:simple}
1294 % \<<<{
1295 % Consider the following simple definition of a polynomial function and
1296 % check its spoken version by clicking on it.
1297 % }
1298 % \<<<[arealink]{
1299 % \begin{equation}
1300 % f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 25
1301 % \end{equation}
1302 % }
1303 % \<<<{
1304 % This seems a simple equation, however, it is not so straightforward
1305 % for an automated reader, to read it correctly.
1306 % }
1307 %
1308 % \section{A more complex equation}
1309 % \newcommand\xx[2]{\ensuremath{#1_{#2}}}
1310 % \spelmacad{xx}[2]{#1 #2}
1311 %
1312 % \label{eqn:complex}
1313 % \begin{spelchunk}
1314 % For a lightray that hits the parabola at the point
1315 % $P(t,9-\frac{t^2}{4})$, the reflected ray has slope $\tan 2\alpha$.
1316 % Since the slope of the tangent to the parabola at $P$ is
1317 % equal to $\tan\alpha = -\frac{t}{2}$, the equation of the
1318 % reflected ray is given by
1319 % \end{spelchunk}
1320 % \begin{spelchunk}[arealink]
1321 % \[
1322 % y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t)
1323 % \]
1324 % \end{spelchunk}
1325
1326 % \section{Remark}
1327 % \<<<{
1328 % Instead of the \texttt{\textbackslash{}<<<} macro, one can also use the
1329 % spelchunk environment. We did this in the next sections.
1330 % }
1331 %
1332 % \chapter{More advanced topics}
1333 %
1334 % \selectlanguage{dutch}
1335 % \section{Een andere taal}
1336 % \begin{spelchunk}
1337 % \spelatex{} is ook volledig babel-actief, wat wil zeggen dat de
1338 % voorleesstem de geselecteerde taal zal volgen.
1339 % \end{spelchunk}
1340 %
1341 % \begin{spelchunk}[arealink]
1342 % \[
1343 % y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t)
1344 % \]
1345 % \end{spelchunk}
1346 %
1347 % \selectlanguage{english}
1348 %
1349 % \section{And some extras}
1350 % \subsection{Citations}
1351 % \begin{spelchunk}
1352 % Two excellent repositories are \CPAN{} \cite{CPAN} and \CTAN{} \cite{CTAN}.
1353 % \end{spelchunk}
1354 %
1355 % \subsection{References to labels}
1356 % \begin{spelchunk}
1357 % Section~\ref{eqn:simple} contains an illustration of a simple
1358 % equation. For a more complex equation, we refer the user to
1359 % section~\ref{eqn:complex}.
1360 % \end{spelchunk}
1361 %
1362 % \selectlanguage{dutch}
1363 %
1364 % \bibliographystyle{alpha}
1365 %
1366 % \begin{thebibliography}{99}
1367 %
1368 % \bibitem{CTAN}
1369 % The Comprehensive \TeX{} Archive Network.
1370 % \newblock \url{http://www.ctan.org}.
1371 % \newblock online, accessed in August 2021.
1372 %
1373 % \bibitem{CPAN}
1374 % The Comprehensive Perl Archive Network.
1375 % \newblock \url{http://www.cpan.org}.
1376 % \newblock online, accessed in August 2021.
1377 %
1378 % \end{thebibliography}
1379 %
1380 % \end{document}
1381 % \end{VerbatimOut}
1382 % \footnotesize
1383 % \VerbatimInput[frame=lines,numbers=left,gobble=0]{Example/example.tex}
1384 % \normalsize
1385 % \section{Demo}
1386 % \label{sec:demo}
1387 % \newcommand\rd[1]{\ensuremath{\mathrm{d}#1}}
1388 % \spelmacad{rd}[1]{d of #1}
1389 % \newcommand\xx[2]{\ensuremath{#1_{#2}}}
1390 %
1391 % \begin{spelchunk}
1392 % The examples below have been composed and used to test the math
1393 % reading capabilities of \spelatex{} and \spelpl. The source code has not
1394 % been made visible in this document. If you'd like to see the
1395 % source code, check the original |.dtx|-file that was used to
1396 % generate this PDF-file.
1397 % \end{spelchunk}
1398 %
1399 % \subsection{Numbers}
1400 % \begin{spelchunk}[arealink]
1401 % \begin{align}
1402 % \pi\\
1403 % -31415\\
1404 % 1.25\\
1405 % -0.34 \times 10^{4}\\
1406 % 12 - j 3\\
1407 % -31415.23 + .45i
1408 % \end{align}
1409 % \end{spelchunk}
1410 %
1411 %
1412 % \subsection{Fractions}
1413 % \subsubsection{A fraction only containing numbers}
1414 % \<<<{You will probably have seen more complex numbers in your life.}
1415 % \begin{spelalign}
1416 % x &= - \frac{1}{2} \\
1417 % y &= - \sqrt{\frac{\pi}{2}}
1418 % \end{spelalign}
1419 % \begin{spelchunk}
1420 % Or should I say real numbers?
1421 % \end{spelchunk}
1422 %
1423 % \subsubsection{A fraction with a little more under the hood}
1424 % \begin{spelchunk}[arealink]
1425 % \begin{align}
1426 % u &= - \frac{x^2+35}{\sqrt{12}} \\
1427 % v &= - \frac{\sqrt{\frac{\pi}{2}}}{-3x^2+3}
1428 % \end{align}
1429 % \end{spelchunk}
1430 %
1431 %
1432 % \subsection{Simple expressions}
1433 % \subsubsection{A polynomial function}%
1434 % \begin{spelchunk}[arealink]
1435 % \begin{equation}
1436 % f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 23
1437 % \end{equation}
1438 % \end{spelchunk}
1439 %
1440 % \subsubsection{Some more complex equations}
1441 % \begin{spelchunk}
1442 % Here's de Moivre's formula:
1443 % \end{spelchunk}
1444 % \begin{spelchunk}[arealink]
1445 % \begin{equation}
1446 % \left(\cos x+j\sin x\right)^n=\cos(nx)+j\sin(nx)
1447 % \end{equation}
1448 % \end{spelchunk}
1449 %
1450 % \begin{spelchunk}
1451 % Euler's relationship:
1452 % \end{spelchunk}
1453 % \begin{spelchunk}[arealink]
1454 % \begin{equation}
1455 % e^{j \phi} = \cos \phi + j \sin \phi
1456 % \end{equation}
1457 % \end{spelchunk}
1458 %
1459 % \begin{spelchunk}
1460 % Euler's identity:
1461 % \end{spelchunk}
1462 % \begin{spelchunk}[arealink]
1463 % \begin{equation}
1464 % e^{j \pi} + 1 = 0
1465 % \end{equation}
1466 % \end{spelchunk}
1467 %
1468 % \subsubsection{A rather well-known definite integral}
1469 % \begin{spelchunk}[arealink]
1470 % \begin{equation}
1471 % \int_{-\infty}^\infty e^{-x^2}\,\rd{x} = \sqrt{\pi}
1472 % \end{equation}
1473 % \end{spelchunk}
1474 %
1475 % \subsection{Sets}
1476 % \begin{spelchunk}
1477 % Let's check the two set commands this package provides:
1478 % \texttt{\textbackslash{}setenum} and
1479 % \texttt{\textbackslash{}setdesc}:
1480 % \end{spelchunk}
1481 % \begin{spelchunk}[arealink]
1482 % \begin{align}
1483 % P &= \setenum{ 2, 3, 5, 7, 11, 13, \ldots }\\
1484 % P &= \setdesc{ n \in \mathbb{N} \mid n \text{~is prime}}
1485 % \end{align}
1486 % \end{spelchunk}
1487 %
1488 % \subsection{Matrices}
1489 % \begin{spelchunk}
1490 % How about some linear algebra?
1491 % \end{spelchunk}
1492 % \begin{spelchunk}[arealink]
1493 % \begin{align}
1494 % \begin{bmatrix}
1495 % 3 & 4 \\
1496 % 7 & 2
1497 % \end{bmatrix}
1498 % \cdot
1499 % \begin{bmatrix}
1500 % x \\ y
1501 % \end{bmatrix}
1502 % &=
1503 % \begin{bmatrix}
1504 % 1 \\ 0
1505 % \end{bmatrix}\\
1506 % \begin{vmatrix}
1507 % 3 & 4 \\
1508 % 7 & 2
1509 % \end{vmatrix}
1510 % &= -22
1511 % \end{align}
1512 % \end{spelchunk}
1513 %
1514 % \subsection{Figures and Tables}
1515 % \subsubsection{Figures}
1516 % \begin{spelchunk}
1517 % The example Fig.~\ref{fig:blockdiagram} illustrates the voice-aid
1518 % that can be added to figures.
1519 % \end{spelchunk}
1520 % \begin{figure}[h]
1521 % \setlength{\unitlength}{4mm}
1522 % \begin{center}
1523 % \begin{spelchunk}[arealink]
1524 % \begin{picture}(24,2)
1525 % \put(0,0.8){$x[n]$}
1526 % \put(2,1){\vector(1,0){3}}
1527 % \put(5,0){\framebox(5,2){$H(z)$}}
1528 % \put(10,1){\vector(1,0){3}}
1529 % \put(13,0){\framebox(5,2){$G(z) \cdot F(z)$}}
1530 % \put(18,1){\vector(1,0){3}}
1531 % \put(22,0.8){$y[n]$}
1532 % \end{picture}
1533 % \end{spelchunk}
1534 % \end{center}
1535 % \begin{spelchunkad}
1536 % The discrete-time input signal x is fed through a filter H of
1537 % z. The intermediate output signal of the filter H of z is fed into
1538 % another filter whose transfer function is the product of G of
1539 % z and F of z. This results in the discrete-time output signal y.
1540 % \end{spelchunkad}
1541 % \spelcaption{A block diagram of the filter system}
1542 % \label{fig:blockdiagram}
1543 % \end{figure}
1544 %
1545 % \subsubsection{Tables}
1546 % \<<<{Tables can also be equiped with a sensible description:}
1547 % \begin{center}
1548 % \begin{spelchunk}[arealink]
1549 % \begin{tabular}{lcc}
1550 % Food & Sweet & Bitter \\
1551 % \hline
1552 % apples & $\bullet$ & \\
1553 % unsweetened coffee & & $\bullet$\\
1554 % cake & $\bullet$ & \\
1555 % chocolate & $\bullet$ & $\bullet$ \\
1556 % \hline
1557 % \end{tabular}
1558 % \end{spelchunk}
1559 % \end{center}
1560 % \begin{spelchunkad}
1561 % This table indicates the sweetness and bitterness for several food
1562 % products.
1563 % It lists apples that are (sweet); unsweetened coffee which is
1564 % bitter; cake which is sweet and chocolate that is both sweet and bitter.
1565 % \end{spelchunkad}
1566 % \subsection{A parabola tale}
1567 %
1568 % \begin{spelchunk}
1569 % For a lightray that hits the parabola at the point
1570 % $P(t,9-\frac{t^2}{4})$, the reflected ray has slope $\tan 2\alpha$.
1571 % Since the slope of the tangent to the parabola at $P$ is equal
1572 % to $\tan \alpha = -\frac{t}{2}$, the equation of the reflected
1573 % ray is given by
1574 % \end{spelchunk}
1575 % \begin{spelchunk}[arealink]
1576 % \begin{equation}
1577 % y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t)
1578 % \end{equation}
1579 % \end{spelchunk}
1580 % \begin{spelchunk}
1581 % The $x$-coordinate of the point of intersection of the reflected ray
1582 % with a fixed line $y=u$ satisfies:
1583 % \end{spelchunk}
1584 % \begin{spelchunk}[arealink]
1585 % \begin{equation}
1586 % u-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t)
1587 % \label{eqn:refray}
1588 % \end{equation}
1589 % \end{spelchunk}
1590 % \begin{spelchunk}
1591 % We calculate the minimal value of this $x$ for varying $t$, by
1592 % differentiating (\ref{eqn:refray}) with respect to $t$ and assuming
1593 % that $\frac{\rd{x}}{\rd{t}}=0$:
1594 % \end{spelchunk}
1595 % \begin{spelchunk}[arealink]
1596 % \[
1597 % \frac{t}{2} = -\frac{4(4+t^2)}{(4-t^2)^2} (x-t) -
1598 % \frac{4t}{4-t^2} \cdot (-1) \ \ \ \Leftrightarrow \ \ \ x=
1599 % 3\frac{t}{2}-\frac{t^3}{8}
1600 % \]
1601 % \end{spelchunk}
1602 % \begin{spelchunk}
1603 % Inserting in the equation containing $u$ gives us the relation
1604 % between $t$ and $u$:
1605 % \end{spelchunk}
1606 % \begin{spelchunk}[arealink]
1607 % \[
1608 % u = 9- 3 \frac{t^2}{4}
1609 % \]
1610 % \end{spelchunk}
1611 %% \begin{spelchunk}
1612 % This leads to a system of parametric equations for the caustic:
1613 % \end{spelchunk}
1614 % \begin{spelchunk}[arealink]
1615 % \[
1616 % \left\{\begin{array}{l}
1617 % x = 3\frac{t}{2}-\frac{t^3}{8} \\[0.3cm]
1618 % y = 9- 3 \frac{t^2}{4}
1619 % \end{array} \right.
1620 % \quad \Leftrightarrow \quad
1621 % \left\{\begin{array}{l}
1622 % x = \frac{t}{2} \cdot (3 -\frac{t^2}{4}) \\
1623 % y = 3(3- \frac{t^2}{4})
1624 % \end{array} \right.
1625 % \]
1626 % \end{spelchunk}
1627 % \begin{spelchunk}
1628 % It is now easy to eliminate the parameter $t$. As you can see, $t
1629 % = \frac{6 x}{y}$. Inserting into the equation for $y$ gives us the
1630 % equation of Tschirnhausen's cubic.
1631 % \end{spelchunk}
1632 %
1633 %
1634 % \section{Implementation}
1635 % \begin{spelchunk}
1636 % To ease the implementation work and because raw \LaTeX{} code is
1637 % difficult to read on itself, We took the liberty of not providing
1638 % this section with speech chunks (except for this introduction
1639 % text).
1640 % \end{spelchunk}
1641 %
1642 %
1643 % \iffalse
1644 % \begin{macrocode}
1645 %<*package>
1646 % \end{macrocode}
1647 % \fi
1648 %
1649 % \subsection{Design principles}
1650 %
1651 % \spelatex{} has been developed using the following main targets in
1652 % mind. Some of them are common sense design principles, some of them
1653 % are specific for this application.
1654 % \begin{itemize}
1655 % \item minimal effort in preparing a \LaTeX{} manuscript for use with
1656 % \spelatex{}
1657 % \item maximal compatibility with existing \LaTeX{} packages
1658 % \item no (or minimal) compromise mathematical reading capabilities
1659 % for mathematical constructs
1660 % \item user extensible audio preprocessor
1661 % \item minimal use of processing power for text to speech conversion
1662 % \end{itemize}
1663 %
1664 %
1665 % \subsection{Auxiliary Packages}
1666 % The \spelatex{} package uses some basic auxiliary packages to make life
1667 % easy.
1668 % \begin{macrocode}
1669 \RequirePackage{expl3}
1670 \RequirePackage{hyperref}
1671 \RequirePackage{xcolor}
1672 \RequirePackage{ifthen}
1673 \RequirePackage{verbatim}
1674 \RequirePackage{fancyvrb}
1675 \RequirePackage{newfile}
1676 \RequirePackage{rotating}
1677 \RequirePackage{babel}
1678 \RequirePackage{kvoptions}
1679 \RequirePackage{xkeyval}
1680 % \end{macrocode}
1681 %
1682 % \subsection{Options}
1683 %
1684 % \begin{macrocode}
1685 \SetupKeyvalOptions{
1686 family=spel,
1687 prefix=spel@
1688 }
1689 \DeclareStringOption[ogg]{format}
1690 \DeclareStringOption[local]{server}
1691 \DeclareStringOption[full]{markervisibility}
1692 \DeclareBoolOption[false]{disabled}
1693 \DeclareBoolOption[false]{extramath}
1694 \DeclareStringOption[{}]{elements}
1695 \ProcessKeyvalOptions*
1696 % \end{macrocode}
1697 %
1698 % \subsection{Logos}
1699 % Vanity is everything, so let's make some logoware.
1700 % \begin{macro}{\spelatex}
1701 % This is the official \spelatex{} logo.
1702 % \begin{macrocode}
1703 \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}
1704 % \end{macrocode}
1705 % \end{macro}
1706 % \begin{macro}{\spelpl}
1707 % This is the official \spelpl{} logo.
1708 % \begin{macrocode}
1709 \DeclareRobustCommand{\spelpl}{\texttt{spel-wizard.pl}}
1710 % \end{macrocode}
1711 % \end{macro}
1712 %
1713 % \subsection{The speech stream}
1714 % The basic structural elements of a document (title, chapters,
1715 % sections, \ldots) are written to the speech index stream. This is a
1716 % textfile that has the same base name as your \LaTeX{} job and has
1717 % extension |.spelidx|.
1718 %
1719 % It is the index to the chunks of text that are written to the speech
1720 % directory.
1721 %
1722 % The |.spelidx| file requires postprocessing by the \spelpl{}
1723 % script in order to obtain the required audio files.
1724 %
1725 % The speech stream needs to be open before the preamble's title,
1726 % author and date.
1727 % \begin{macrocode}
1728 \newoutputstream{chunk}
1729 \newoutputstream{spelidx}
1730 \openoutputfile{\jobname.spelidx}{spelidx}
1731 % \end{macrocode}
1732 % The stream needs to be closed upon termination of the document.
1733 % \begin{macrocode}
1734 \AtEndDocument{
1735 \closeoutputstream{spelidx}%
1736 }
1737 % \end{macrocode}
1738 %
1739 % To begin with, we write the standard locations for audio and chunk
1740 % data to the |.spelidx| file.
1741 % \begin{macrocode}
1742 \newcommand\audiodir{\jobname-spel}
1743 \newcommand\chunkdir{\jobname-spel}
1744 \addtostream{spelidx}{format|\spel@format}
1745 \addtostream{spelidx}{audiodir|\audiodir}
1746 \addtostream{spelidx}{chunkdir|\chunkdir}
1747 \addtostream{spelidx}{server|\spel@server}
1748 \ExplSyntaxOn
1749 \newcommand\linksdir{
1750 \str_if_eq:VnTF{\spel@server}{local}{./\audiodir}{\spel@server/\audiodir}
1751 }
1752 \ExplSyntaxOff
1753 % \end{macrocode}
1754 %
1755 % To ease writing to the speech index stream, we define a |\spelidxwrite|
1756 % function to take care of appropriate formatting.
1757 % \begin{macro}{\spel@idxwrite}
1758 % This is an internal macro, used to write information to the |.spelidx|
1759 % file and to a correspondig chunk file.
1760 % \begin{macrocode}
1761 \ifspel@disabled\newcommand{\spel@idxwrite}[2]{}\else
1762 \newcommand{\spel@idxwrite}[2]{%
1763 \typeout{SpeLaTeX: Generating #1 - #2}%
1764 \addtostream{spelidx}{#1|#2}%
1765 }
1766 \fi
1767 % \end{macrocode}
1768 % \end{macro}
1769 %
1770 % To ease writing speech chunk, we define a |\spel@chunkwrite|
1771 % function.
1772 % \begin{macro}{\spel@chunkwrite}
1773 % This is an internal macro, used to write information to the speech chunk
1774 % files.
1775 % \begin{macrocode}
1776 \ifspel@disabled\newcommand{\spel@chunkwrite}[2]{}\else
1777 \newcommand{\spel@chunkwrite}[2]{%
1778 \openoutputfile{\audiodir/#1.tex}{chunk}%
1779 \addtostream{chunk}{#2}%
1780 \closeoutputstream{chunk}%
1781 }
1782 \fi
1783 % \end{macrocode}
1784 % \end{macro}
1785 %
1786 % \subsection{Create missing counters}
1787 % As we need to be able to fully identify every speech chunk, we need
1788 % to provide some missing counters for the starred versions of the
1789 % sectioning commands.
1790 %
1791 % \begin{macro}{spel@spart} counter
1792 % \begin{macrocode}
1793 \newcounter{spel@spart}
1794 \renewcommand\thespel@spart{\@arabic\c@spel@spart}
1795 \setcounter{spel@spart}{0}
1796 % \end{macrocode}
1797 % \end{macro}
1798 %
1799 % \begin{macro}{spel@schapter} counter
1800 % \begin{macrocode}
1801 \ifx\c@chapter\@undefined
1802 \else
1803 \ifx\c@part\@undefined
1804 \newcounter{spel@schapter}
1805 \else
1806 \newcounter{spel@schapter}[part]
1807 \fi
1808 \renewcommand\thespel@schapter{\@arabic\c@spel@schapter}
1809 \setcounter{spel@schapter}{0}
1810 \fi
1811 % \end{macrocode}
1812 % \end{macro}
1813 %
1814 % \begin{macro}{spel@ssect} counter
1815 % \begin{macrocode}
1816 \ifx\c@chapter\@undefined
1817 \newcounter{spel@ssect}
1818 \else
1819 \newcounter{spel@ssect}[chapter]
1820 \fi
1821 \renewcommand\thespel@ssect{\@arabic\c@spel@ssect}
1822 \setcounter{spel@ssect}{0}
1823 % \end{macrocode}
1824 % \end{macro}
1825 %
1826 % In addition, some elements that are not canonically numbered require
1827 % a unique and monotonous numbering.
1828 % \begin{macro}{spel@footnote} counter
1829 % \begin{macrocode}
1830 \newcounter{spel@footnote}
1831 \renewcommand\thespel@footnote{\@arabic\c@spel@footnote}
1832 \setcounter{spel@footnote}{0}
1833 % \end{macrocode}
1834 % \end{macro}
1835 %
1836 % \begin{macro}{spel@chunk} counter
1837 % \begin{macrocode}
1838 \newcounter{spel@chunk}[subparagraph]
1839 \renewcommand\thespel@chunk{\@arabic\c@spel@chunk}
1840 \setcounter{spel@chunk}{0}
1841 % \end{macrocode}
1842 % \end{macro}
1843 %
1844 % \subsection{Setting up the language}
1845 % We want to make sure that babel communicates the switching of
1846 % langauges to spel, such that it can take not of it. This allows the
1847 % spel engine to select an appropriate language-capable voice when
1848 % generating the spoken text.
1849 % \begin{macrocode}
1850 \AddBabelHook{informspel}{write}{\spel@idxwrite{language}{\languagename}}
1851 \EnableBabelHook{informspel}
1852 % \end{macrocode}
1853 %
1854 % \subsection{Setting up the visibility}
1855 %
1856 % \begin{macrocode}
1857 \ExplSyntaxOn
1858 \definecolor{faintgray}{rgb}{0.9,0.9,0.9}
1859 \str_if_eq:VnTF{\spel@markervisibility}{none}{
1860 \colorlet{spel@color@right}{white}
1861 \colorlet{spel@color@left}{white}
1862 }{}
1863 \str_if_eq:VnTF{\spel@markervisibility}{onlygroups}{
1864 \colorlet{spel@color@right}{black!25}
1865 \colorlet{spel@color@left}{white}
1866 }{}
1867 \str_if_eq:VnTF{\spel@markervisibility}{full}{
1868 \colorlet{spel@color@right}{black!25}
1869 \colorlet{spel@color@left}{black!25}
1870 }{}
1871 \ExplSyntaxOff
1872 % \end{macrocode}
1873 %
1874 %
1875 %
1876 % \subsection{Generating speech chunks --- implicitly}
1877 % \subsubsection{Auxiliary macros}
1878 % We define a macro to generate wrappers for single-line text elements.
1879 % The |\spel@registerelement| macro does
1880 % the job. The user can even use the macro for his own custom
1881 % single-line text elements (e.g., for a subtitle, a version string).
1882 % \begin{macro}{\spel@registerelement}
1883 % generic macro to register single-line text elements
1884 % \begin{macrocode}
1885 \ifspel@disabled
1886 \newcommand{\spel@registerelement}[1]{}
1887 \def\processelementlist#1{}
1888 \else
1889 \newcommand{\spel@registerelement}[1]{%
1890 \expandafter\let\csname spel@@#1\expandafter\endcsname\csname #1\endcsname
1891 \expandafter\gdef\csname #1\endcsname##1{%
1892 \spel@chunkwrite{#1}{##1}
1893 \csname spel@@#1\endcsname{\href{\linksdir/#1.\spel@format}{##1}}
1894 \spel@idxwrite{#1}{#1}
1895 }
1896 }
1897 \def\processelementlist#1{%
1898 \def\do##1{\spel@registerelement{##1}}%
1899 \edef\@tempa{#1}%
1900 \expandafter\docsvlist\expandafter{\@tempa}%
1901 }
1902 \def\docsvlist#1{%CSV-list-processor
1903 \@for\@tempa:=#1\do{\expandafter\do\expandafter{\@tempa}}%
1904 }
1905 \fi
1906 % \end{macrocode}
1907 % \end{macro}
1908 %
1909 % \subsubsection{Title elements}
1910 % By redefining the title elements, |\title|, |\author| and |\date| we
1911 % avoid having to chunk them.
1912 %
1913 % Using this macro, we can easily take care of all title-like
1914 % elements, including the ones specified through the elements option:
1915 % \begin{macrocode}
1916 \spel@idxwrite{language}{\languagename}
1917 \spel@registerelement{title}
1918 \spel@registerelement{date}
1919 \spel@registerelement{author}
1920 \processelementlist{\spel@elements}
1921 \let\spel@@maketitle\maketitle
1922 \gdef\maketitle{{\hypersetup{hidelinks}\spel@@maketitle}}
1923 % \end{macrocode}
1924 % We registered the initial language in advance, to make sure the
1925 % wizard knows what language to use for these elements.
1926 %
1927 % \subsubsection{Table of contents}
1928 % \begin{macrocode}
1929 \ifspel@disabled\else
1930 \let\spel@@addcontentsline\addcontentsline
1931 \renewcommand\addcontentsline[3]{%
1932 \let\spel@@href\href%
1933 \renewcommand\href[2]{#2}%
1934 \spel@@addcontentsline{#1}{#2}{#3}%
1935 \let\href\spel@@href%
1936 }
1937 \providecommand{\tableofcontents}{}
1938 \renewcommand\tableofcontents{%
1939 \if@twocolumn
1940 \@restonecoltrue\onecolumn
1941 \else
1942 \@restonecolfalse
1943 \fi
1944 \@ifclassloaded{article}{\section*{\contentsname}}{\chapter*{\contentsname}}
1945 \@mkboth{%
1946 \MakeUppercase\contentsname}{\MakeUppercase\contentsname}%
1947 \@starttoc{toc}%
1948 \if@restonecol\twocolumn\fi
1949 }
1950 \fi
1951 % \end{macrocode}
1952 %
1953 % \subsubsection{Sectioning commands}
1954 %
1955 % \begin{macro}{\@part}
1956 % This is a simple wrapper around the regular |\@part| macro.
1957 % \begin{macrocode}
1958 \ifspel@disabled\else
1959 \let\spel@@part\@part
1960 \def\@part[#1]#2{%
1961 \setcounter{spel@chunk}{0}% need this because counter resetting fails
1962 \spel@@part[#1]{\href{\linksdir/\spel@@optpart.\spel@format}{#2}}%
1963 \spel@idxwrite{part \thepart}{\spel@@optpart}%
1964 \spel@chunkwrite{\spel@@optpart}{#2}%
1965 }
1966 \fi
1967 % \end{macrocode}
1968 % \end{macro}
1969 %
1970 % \begin{macro}{\@spart}
1971 % This is a simple wrapper around the regular |\@spart| macro.
1972 % \begin{macrocode}
1973 \ifspel@disabled\else
1974 \let\spel@@spart\@spart
1975 \def\@spart#1{%
1976 \stepcounter{spel@spart}%
1977 \setcounter{spel@chunk}{0}% need this because counter resetting fails
1978 \spel@@spart{%
1979 \href{\linksdir/\spel@@optpart star-\thespel@spart.\spel@format}{#1}}%
1980 \spel@idxwrite{part}{\spel@@optpart star-\thespel@spart}%
1981 \spel@chunkwrite{\spel@@optpart star-\thespel@spart}{#1}%
1982 }
1983 \fi
1984 % \end{macrocode}
1985 % \end{macro}
1986 %
1987 % \begin{macro}{\@chapter}
1988 % This is a simple wrapper around the regular |\@chapter| macro.
1989 % It is defined conditionally on the existence of the |\chapter| macro.
1990 % \begin{macrocode}
1991 \newcommand\hideref[2]{\protect\hypersetup{hidelinks}\href{#1}{#2}}
1992 \newif\ifspel@inschapter
1993 \spel@inschapterfalse
1994 \ifspel@disabled\else
1995 \ifx\thechapter\@undefined\else%
1996 \renewcommand\thechapter{%
1997 \ifspel@inschapter star-\thespel@schapter\else\@arabic\c@chapter\fi%
1998 }
1999 \fi
2000 \ifx\chapter\@undefined\else
2001 \let\spel@@chapter\@chapter
2002 \def\@chapter[#1]#2{%
2003 \spel@inschapterfalse%
2004 \setcounter{spel@chunk}{0}% need this because counter resetting fails
2005 \spel@@chapter[#1]{%
2006 \hideref{\linksdir/\spel@@optpart\thechapter.\spel@format}{#2}}%
2007 \spel@idxwrite{chapter \thechapter}{\spel@@optpart\thechapter}%
2008 \spel@chunkwrite{\spel@@optpart\thechapter}{#2}%
2009 }
2010 \fi
2011 \fi
2012 % \end{macrocode}
2013 % \end{macro}
2014 %
2015 % \begin{macro}{\@schapter}
2016 % This is a simple wrapper around the regular |\@schapter| macro.
2017 % It is defined condionally on the existence of the |\schapter| macro.
2018 % \begin{macrocode}
2019 \ifspel@disabled\else
2020 \ifx\chapter\@undefined\else
2021 \let\spel@@schapter\@schapter
2022 \def\@schapter#1{%
2023 \spel@inschaptertrue%
2024 \stepcounter{spel@schapter}%
2025 \setcounter{spel@chunk}{0}% need this because counter resetting fails
2026 \spel@@schapter{%
2027 \hideref{\linksdir/\spel@@optpart star-\thespel@schapter.\spel@format}{#1}}%
2028 \spel@idxwrite{chapter}{\spel@@optpart star-\thespel@schapter}%
2029 \spel@chunkwrite{\spel@@optpart star-\thespel@schapter}{#1}%
2030 }
2031 \fi
2032 \fi
2033 % \end{macrocode}
2034 % \end{macro}
2035 %
2036 % \begin{macro}{\@sect}
2037 % This is a simple wrapper around the regular |\@sect| macro.
2038 % \begin{macrocode}
2039 \ifspel@disabled\else
2040 \let\spel@@sect\@sect
2041 \def\@sect#1#2#3#4#5#6[#7]#8{%
2042 % correct default tex behavior
2043 \ifnum #2>\c@secnumdepth%
2044 \stepcounter{#1}%
2045 \fi%
2046 \setcounter{spel@chunk}{0}% need this because counter resetting fails
2047 \spel@@sect{#1}{#2}{#3}{#4}{#5}{#6}[#7]{%
2048 \hideref{\linksdir/\spel@@optpart\thesubparagraph.\spel@format}{#8}\hfill%
2049 \hideref{\linksdir/\spel@@optpart\thesubparagraph.m3u}
2050 {\textcolor{spel@color@right}{$\triangleright$}}}%
2051 \def\spel@@label{%
2052 \ifnum #2>\c@secnumdepth paragraph\else#1 \csname the#1\endcsname\fi}
2053 \spel@idxwrite{\spel@@label}{\spel@@optpart\thesubparagraph}%
2054 \spel@chunkwrite{\spel@@optpart\thesubparagraph}{#8}%
2055 }
2056 \fi
2057 % \end{macrocode}
2058 % \end{macro}
2059 %
2060 % \begin{macro}{\@sect}
2061 % This is a simple wrapper around the regular |\@ssect| macro.
2062 % \begin{macrocode}
2063 \ifspel@disabled\else
2064 \let\spel@@ssect\@ssect
2065 \def\@ssect#1#2#3#4#5{%
2066 \stepcounter{spel@ssect}%
2067 %\setcounter{spel@chunk}{0}% need this because counter resetting fails
2068 \spel@@ssect{#1}{#2}{#3}{#4}{%
2069 \hideref{\linksdir/\spel@@optpart\thesubparagraph-star-\thespel@ssect.\spel@format}%
2070 {#5}}%
2071 \spel@idxwrite{section}{\spel@@optpart\thesubparagraph-star-\thespel@ssect}%
2072 \spel@chunkwrite{\spel@@optpart\thesubparagraph-star-\thespel@ssect}{#5}%
2073 }
2074 \fi
2075 % \end{macrocode}
2076 % \end{macro}
2077 %
2078 % \subsubsection{Notes}
2079 %
2080 % \begin{macro}{\@footnotetext}
2081 % This is a simple wrapper around the regular |\$footnotetext|
2082 % macro. We use a |spelfootnote| counter to keep track of the
2083 % individual footnotes.
2084 % \begin{macrocode}
2085 \ifspel@disabled\else
2086 \let\spel@@fntext\@footnotetext
2087 \long\def\@footnotetext#1{%
2088 \stepcounter{spel@footnote}%
2089 \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
2090 \spel@@fntext{%
2091 \hspace*{-\spel@mptboxwidth}%
2092 \hideref{\linksdir/footnote-\thespel@footnote.\spel@format}
2093 {\usebox\spel@mptbox}#1}%
2094 \spel@idxwrite{footnote}{footnote-\thespel@footnote}%
2095 \spel@chunkwrite{footnote-\thespel@footnote}{#1}%
2096 }
2097 \fi
2098 % \end{macrocode}
2099 % \end{macro}
2100 %
2101 % \subsubsection{Itemizations/Enumerations}
2102
2103 % \begin{macro}{\spelitem}
2104 % This macro is to be used inside an enumerate, itemize, description
2105 % environment to automatically cause the generation of a speech
2106 % chunk.
2107 % \begin{macrocode}
2108 \ifspel@disabled\newcommand{\spelitem}{\item}\else
2109 \newcommand{\spelitem}{%
2110 \@ifnextchar[{\spelitem@opt}{\spelitem@intone}
2111 }
2112 \fi
2113 % \end{macrocode}
2114 % \end{macro}
2115 %
2116 % This macro uses a number of auxiliary macros.
2117 % \begin{macro}{\spelitem@opt}
2118 % This is an internal macro intended to deal with the |\item|'s
2119 % options.
2120 % \begin{macrocode}
2121 \def\spelitem@opt[#1]{\spelitem@inttwo{#1}}
2122 % \end{macrocode}
2123 % \end{macro}
2124 %
2125 % \begin{macro}{\spelitem@opt}
2126 % This is an internal macro intended to deal with an |\spelitem| without
2127 % options.
2128 % \begin{macrocode}
2129 \def\spelitem@intone#1{%
2130 \stepcounter{spel@chunk}%
2131 \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
2132 \spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
2133 \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1}%
2134 \item \hspace*{-\spel@mptboxwidth}%
2135 \hideref{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}
2136 {\usebox\spel@mptbox}#1}
2137 % \end{macrocode}
2138 % \end{macro}
2139 %
2140 % \begin{macro}{\spelitem@inttwo}
2141 % This is an internal macro intended to deal with an |\spelitem| with
2142 % options.
2143 % \begin{macrocode}
2144 \def\spelitem@inttwo#1#2{%
2145 \stepcounter{spel@chunk}%
2146 \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
2147 \spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
2148 \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1 . #2}%
2149 \item[#1] \hspace*{-\spel@mptboxwidth}%
2150 \hideref{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}
2151 {\usebox\spel@mptbox}#2}
2152 % \end{macrocode}
2153 % \end{macro}
2154 %
2155 % \begin{macro}{\spelitemcont}
2156 % This is a macro to continue an item after it has been interleaved
2157 % with a display item (e.g. a display math environment or another
2158 % itemization).
2159 % \begin{macrocode}
2160 \def\spelitemcont#1{%
2161 \stepcounter{spel@chunk}%
2162 \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
2163 \spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
2164 \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1}%
2165 \hspace*{-\spel@mptboxwidth}{\hypersetup{hidelinks}%
2166 \href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}
2167 {\usebox\spel@mptbox}#1}%
2168 }
2169 % \end{macrocode}
2170 % \end{macro}
2171 %
2172 % \begin{macro}{\spelcaption}
2173 % This is a wrapper for the |\caption| macro, such that it is
2174 % \spelatex{} enabled.
2175 % \begin{macrocode}
2176 \ifspel@disabled
2177 \newcommand\spelcaption[2][]{\caption[#1]{#2}}
2178 \else
2179 \newcommand\spelcaption[2][]{%
2180 \stepcounter{spel@chunk}%
2181 \spel@idxwrite{caption}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
2182 \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#2}%
2183 \caption[#1]{%
2184 \protect\href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}
2185 {#2}}
2186 }
2187 \fi
2188 % \end{macrocode}
2189 % \end{macro}
2190 %
2191 % \subsubsection{Math environments}
2192 %
2193 % \begin{environment}{spelwrapenvironment}
2194 % This are all variants of a wrapper around a math environment
2195 % such that it is \spelatex{} enabled with an arealink.
2196 % \begin{macrocode}
2197 \newcommand\spelwrapenvironment@b[1]{
2198 \NewDocumentEnvironment{spel#1}{+b}{
2199 \<<<[arealink]{%
2200 \begin{#1}
2201 ##1
2202 \end{#1}%
2203 }\hspace*{-0.75ex}%
2204 }{}%
2205 }
2206 \newcommand\spelwrapenvironment@ob[1]{
2207 \NewDocumentEnvironment{spel#1}{O{}+b}{
2208 \<<<[arealink]{
2209 \begin{#1}[##1]
2210 ##2
2211 \end{#1}
2212 }\hspace*{-0.75ex}%
2213 }{}
2214 }
2215 \newcommand\spelwrapenvironment@mb[1]{
2216 \NewDocumentEnvironment{spel#1}{m+b}{
2217 \<<<[arealink]{
2218 \begin{#1}{##1}
2219 ##2
2220 \end{#1}
2221 }\hspace*{-0.75ex}%
2222 }{}
2223 }
2224 \newcommand\spelwrapenvironment@mob[1]{
2225 \NewDocumentEnvironment{spel#1}{mO{}+b}{
2226 \<<<[arealink]{
2227 \begin{#1}{##1}[##2]
2228 ##3
2229 \end{#1}
2230 }\hspace*{-0.75ex}%
2231 }{}
2232 }
2233 \newcommand\spelwrapenvironment@omb[1]{
2234 \NewDocumentEnvironment{spel#1}{O{}m+b}{
2235 \<<<[arealink]{
2236 \begin{#1}[##1]{##2}
2237 ##3
2238 \end{#1}
2239 }\hspace*{-0.75ex}%
2240 }{}
2241 }
2242 % \end{macrocode}
2243 % \end{environment}
2244 % Depending on the loading of amsmath, empheq and its overload option,
2245 % we perform appropriate wrappings:
2246 % \begin{macrocode}
2247 \AtBeginDocument{
2248 \@ifpackageloaded{amsmath}{
2249 \message{SpeLaTeX: detected amsmath package}
2250 \spelmacpp{ensuremath}[1]{#1}
2251 \@ifpackageloaded{empheq}{
2252 \message{SpeLaTeX: detected package empheq}
2253 \spelwrapenvironment@omb{empheq}}{}
2254 \@ifpackagewith{empheq}{overload}{
2255 \message{..........with overload option}
2256 \spelwrapenvironment@ob{gather}
2257 \spelwrapenvironment@ob{align}
2258 \spelwrapenvironment@mob{alignat}
2259 }
2260 {
2261 \message{..........without overload option}
2262 \spelwrapenvironment@b{gather}
2263 \spelwrapenvironment@b{align}
2264 \spelwrapenvironment@mb{alignat}
2265 }
2266 }
2267 {}
2268 }
2269 % \end{macrocode}
2270 %
2271 % \subsection{Generating speech chunks --- explicitly}
2272 %
2273 % \subsubsection{Spel chunks to be parsed by \spelpl}
2274 % \begin{environment}{spelchunk}
2275 % The |spelchunk| environment is used to define explicit speech chunks.
2276 % \begin{macrocode}
2277 \newlength\spel@mptboxwidth
2278 \newsavebox\spel@mptbox
2279 \savebox\spel@mptbox{%
2280 \textcolor{spel@color@left}
2281 {\quad\strut\tiny\raisebox{0.4ex}{$\triangleright$}\,}%
2282 }
2283 \newif\ifspel@chunkarealink
2284 \define@key{spelchunk}{arealink}[]{\spel@chunkarealinktrue}
2285 \ifspel@disabled
2286 \def\spelchunk{\@ifnextchar[{\spelchunk@optdisabled}{}}%
2287 \else
2288 \def\spelchunk{%
2289 \catcode`\^^M=\active%
2290 \stepcounter{spel@chunk}%
2291 \spel@idxwrite{chunk}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
2292 \@ifnextchar[{\catcode`\^^M=5\spelchunk@opt}{\catcode`\^^M=5\spelchunk@int}}%
2293 \fi
2294 \ifspel@disabled\def\endspelchunk{}\else
2295 \def\endspelchunk{
2296 \end{VerbatimOut}
2297 \catcode`\^^M=5\relax%
2298 \ifspel@chunkarealink%
2299 \hideref{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}
2300 {\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}}%
2301 \else%
2302 \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
2303 \hspace*{-\spel@mptboxwidth}%
2304 \hideref{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}
2305 {\usebox\spel@mptbox}%
2306 \input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}%
2307 \fi%
2308 \spel@chunkarealinkfalse%
2309 }%
2310 \fi
2311 % \end{macrocode}
2312 % \end{environment}
2313 %
2314 % The environment above checks if it is called with optional arguments
2315 % or not.
2316 % \begin{macro}{\spelchunk@opt}
2317 % This is macro that deals with the oatptional arguments of the
2318 % |spelchunk| envronment.
2319 % \begin{macrocode}
2320 \def\spelchunk@opt[#1]{\setkeys{spelchunk}{#1}\spelchunk@int}
2321 \def\spelchunk@optdisabled[#1]{}
2322 % \end{macrocode}
2323 % \end{macro}
2324 %
2325 % \begin{macro}{\spelchunk@int}
2326 % This is an internal macro to start the |VerbatimOut| environment
2327 % embedded in the |spelchunk| environment.
2328 % \begin{macrocode}
2329 \def\spelchunk@int{%
2330 \VerbatimEnvironment
2331 \begin{VerbatimOut}{\chunkdir/\spel@@optpart\thesubparagraph-\[email protected]}}
2332 \def\spelchunk@intdisabled{}
2333 % \end{macrocode}
2334 % \end{macro}
2335 %
2336 % \begin{macrocode}
2337 \NewDocumentCommand{\spelchunkatom}{O{}+m}{%
2338 \ifspel@disabled #2\else%
2339 \stepcounter{spel@chunk}%
2340 \spel@idxwrite{chunk}{\spel@@optpart\thesubparagraph-\thespel@chunk}%
2341 \setkeys{spelchunk}{#1}%
2342 \makeatletter%
2343 \scantokens{%
2344 \begin{spelverbatimwrite}{\chunkdir/\spel@@optpart\thesubparagraph-\[email protected]}
2345 #2
2346 \end{spelverbatimwrite}
2347 }%
2348 \makeatother%
2349 \ifspel@chunkarealink%
2350 \hideref{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}
2351 {\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}}%
2352 \else%
2353 \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}%
2354 \hspace*{-\spel@mptboxwidth}%
2355 \hideref{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}
2356 {\usebox\spel@mptbox}\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}%
2357 \fi%
2358 \spel@chunkarealinkfalse%
2359 \fi%
2360 }
2361
2362 \def\spelverbatimwrite#1{%
2363 \@bsphack%
2364 \openoutputfile{#1}{chunk}%
2365 \def\verbatim@processline{\addtostream{chunk}{\the\verbatim@line}}%
2366 \let\do\@makeother\dospecials
2367 \catcode`\^^M\active \catcode`\^^I=12
2368 \verbatim@start}%
2369 \def\endspelverbatimwrite{
2370 \closeoutputstream{chunk}
2371 \@esphack
2372 }
2373 \def\<<<{\spelchunkatom}
2374 % \end{macrocode}
2375 %
2376 % \subsubsection{Explicit spelchunks}
2377 %
2378 % \begin{environment}{spelchunkad}
2379 % The |spelchunkad| environment is used to override a previous speech
2380 % chunk. In this way you can provide your own text.
2381 % \begin{macrocode}
2382 \def\spelchunkad{%
2383 \catcode`\^^M=\active
2384 \@ifnextchar[{\catcode`\^^M=5\spelchunk@opt}{\catcode`\^^M=5\spelchunk@int}}
2385 \def\endspelchunkad{%
2386 \end{VerbatimOut}
2387 \catcode`\^^M=5\relax
2388 }
2389 % \end{macrocode}
2390 % \end{environment}
2391 %
2392 % \begin{macrocode}
2393 \AtBeginDocument{
2394 \newcommand\spel@@optpart{}
2395 }
2396 % \end{macrocode}
2397 %
2398 % \subsection{Helping the wizard to read our chunks}
2399 %
2400 % \subsubsection{Listing macros that are to be preprocessed}
2401 % \begin{macro}{\spelmacpp}
2402 % Some \LaTeX{} or \TeX commands are only for layout purposes and are
2403 % totally not content related. They do not contribute to what must be
2404 % read. On the contrary, they make it hard for the \spelpl{} parser to
2405 % convert the texts flawlessly to what can be read by the
2406 % text-to-speech engines.
2407 % Examples of these layout-only commands are |\sf|, |\it|, |\tt|,
2408 % |\bf| and |\displaystyle| that are to be discarded, but also macro's
2409 % like e.g. |\fbox| for which only the content is to be retained.
2410 %
2411 % As you might also make your own macros that are pure typesetting
2412 % oriented, it makes sense to provide a macro that registers them as
2413 % pure type-setting macros and use that macro to cover the examples
2414 % mentioned above.
2415 % The command takes four arguments of wich the two middle ones are optional:
2416 % \begin{enumerate}
2417 % \item The name of the macro without leading backslash
2418 % \item The number of arguments of the macro (omit if no arguments, because this is the default value)
2419 % \item The value of the optional first argument (if any, otherwise omit)
2420 % \item The replacement text, using parameter references \#1,
2421 % \#2, a.s.o. as stamps for where the arguments need to be
2422 % inserted.
2423 % \end{enumerate}
2424 % \begin{macrocode}
2425 \ExplSyntaxOn
2426 \NewDocumentCommand{\spelmacpp}{moom}
2427 {
2428 \addtostream{spelidx}{macpp|#1|#2|#3|#4}
2429 }
2430 \ExplSyntaxOff
2431 % \end{macrocode}
2432 % \end{macro}
2433 %
2434 % Now let's register some standard macros that are to be ignored.
2435 % \begin{macrocode}
2436 \spelmacpp{sf}{}
2437 \spelmacpp{it}{}
2438 \spelmacpp{tt}{}
2439 \spelmacpp{bf}{}
2440 \spelmacpp{HUGE}{}
2441 \spelmacpp{Huge}{}
2442 \spelmacpp{huge}{}
2443 \spelmacpp{LARGE}{}
2444 \spelmacpp{Large}{}
2445 \spelmacpp{large}{}
2446 \spelmacpp{normalsize}{}
2447 \spelmacpp{small}{}
2448 \spelmacpp{footnotesize}{}
2449 \spelmacpp{scriptsize}{}
2450 \spelmacpp{tiny}{}
2451 \spelmacpp{minuscule}{}
2452 \spelmacpp{textsf}[1]{#1}
2453 \spelmacpp{textit}[1]{#1}
2454 \spelmacpp{texttt}[1]{#1}
2455 \spelmacpp{textbf}[1]{#1}
2456 \spelmacpp{mathbb}[1]{#1}
2457 \spelmacpp{mathcal}[1]{#1}
2458 \spelmacpp{url}[1]{#1}
2459 \spelmacpp{phantom}[1]{}
2460 \spelmacpp{quad}{}
2461 \spelmacpp{qquad}{}
2462 \spelmacpp{displaystyle}{}
2463 \spelmacpp{relax}{}
2464 \spelmacpp{strut}{}
2465 \spelmacpp{mathstrut}{}
2466 \spelmacpp{label}[1]{}
2467 \spelmacpp{-}{}
2468 \spelmacpp{vspace}[1]{}
2469 \spelmacpp{vspace*}[1]{}
2470 \spelmacpp{hspace}[1]{ }
2471 \spelmacpp{hspace*}[1]{ }
2472 % \end{macrocode}
2473 %
2474 % And let's register a macro for which only the contents is to be
2475 % preserved:
2476 % \begin{macrocode}
2477 \spelmacpp{fbox}[1]{#1}
2478 % \end{macrocode}
2479 %
2480 % \subsubsection{Listing environments that are to be ignored}
2481 % \begin{macro}{\spelenvpp}
2482 % Some \LaTeX{} or \TeX environments are only for layout purposes and are
2483 % totally not content related. They do not contribute to what must be
2484 % read. On the contrary, they make it hard for the \spelpl{} parser to
2485 % convert the texts flawlessly to what can be read by the
2486 % text-to-speech engines.
2487 % An examples of such a layout-only environment is the |center|
2488 % environment.
2489 %
2490 % As you might also make your own environments that are pure typesetting
2491 % oriented, it makes sense to provide a macro that registers them as
2492 % pure type-setting macros and use that macro to cover the examples
2493 % mentioned above.
2494 %
2495 % The command takes four arguments of wich the two middle ones are optional:
2496 % \begin{enumerate}
2497 % \item The name of the environment
2498 % \item The number of arguments of the environments (omit if no
2499 % arguments, because this is the default value)
2500 % \item The value of the optional first argument (if any, otherwise omit)
2501 % \item The replacement text, using parameter references \#1,
2502 % \#2, a.s.o. as stamps for where the arguments need to be
2503 % inserted. The highest parameter number (one higher than the number
2504 % of arguments) is for the body of the environment.
2505 % \end{enumerate}
2506 %
2507 % \begin{macrocode}
2508 \ExplSyntaxOn
2509 \NewDocumentCommand{\spelenvpp}{moom}
2510 {
2511 \addtostream{spelidx}{envpp|#1|#2|#3|#4}
2512 }
2513 \ExplSyntaxOff
2514 % \end{macrocode}
2515 % \end{macro}
2516 %
2517 % Now let's register some standard macros that are to be ignored:
2518 % \begin{macrocode}
2519 \spelenvpp{center}{#1}
2520 % \end{macrocode}
2521 %
2522 % \subsubsection{Audio descriptions for typesetting macros}
2523 % \begin{macro}{\spelmacad}
2524 % This macro allows specifying how to treat macros (with arguments)
2525 % that appear in the chunks to read out loud. The arguments are in
2526 % order:
2527 % \begin{enumerate}
2528 % \item (mandatory) name of the macro (without leading backslash)
2529 % \item (optional) number of arguments of the macro
2530 % \item (optional) default for optional (first) argument
2531 % \item (mandatory) text to read (with macro parameters in them)
2532 % You can use the special syntax
2533 % |@{i18n(keyword,#1,#2)}|
2534 % to trigger a call to the internationalization (i18n) features built
2535 % in the \spelpl{} script. This will help to read your commands in an
2536 % appropriate way. If you miss some features in the i18n list of
2537 % \spelpl{}, please contact the author to help you out.
2538 % If you are fluent in Perl, you might also want to change the i18n
2539 % list of \spelpl{} yourself. It's not that hard.
2540 % \end{enumerate}
2541 % \begin{macrocode}
2542 \ExplSyntaxOn
2543 \NewDocumentCommand{\spelmacad}{moom}
2544 {
2545 \addtostream{spelidx}{macad|#1|#2|#3|#4}
2546 }
2547 \ExplSyntaxOff
2548 % \end{macrocode}
2549 % \end{macro}
2550 %
2551 % We immediately provide some standard constructs, which are to be
2552 % ignored:
2553 % \begin{macrocode}
2554 \spelmacad{spelatex}{spee-lay-tech}
2555 \spelmacad{spelpl}{spel wizzard dot pl}
2556 \spelmacad{LaTeX}{lay-tech}
2557 \spelmacad{LuaLaTeX}{lua lay-tech}
2558 \spelmacad{TeX}{tech}
2559 \spelmacpp{textsf}[1]{#1}
2560 \spelmacpp{texttt}[1]{#1}
2561 \spelmacpp{textit}[1]{#1}
2562 \spelmacpp{mathit}[1]{\string\text{#1}}
2563 \spelmacpp{emph}[1]{#1}
2564 \spelmacpp{underline}[1]{#1}
2565 \spelmacad{mbox}[1]{#1}
2566 \spelmacad{text}[1]{#1}
2567 \spelmacpp{nobreakspace}{#1}
2568 \spelmacpp{textasciitilde}[1]{ }
2569 \spelmacad{textbackslash}{backslash}
2570 \spelmacad{textsuperscript}[1]{#1}
2571 \spelmacad{footnote}[1]{}
2572 \spelmacad{pm}{@{i18n(plusminus)}}
2573 \spelmacad{ldots}{...}
2574 % \end{macrocode}
2575 %
2576 % Some more that don't seem ignorable - and they are not indeed - they
2577 % are treated differently by \spelpl{}. However, by registering them
2578 % here, \spelpl{} knows there signature:
2579 % \begin{macrocode}
2580 \spelmacad{cite}[1]{}
2581 \spelmacad{ref}[1]{}
2582 \spelmacad{pageref}[1]{}
2583 % \end{macrocode}
2584 %
2585 % \subsubsection{Audio descriptions for typesetting environments}
2586 % \begin{macro}{\spelenvad}
2587 % This macro allows specifying how to treat environments (with arguments)
2588 % that appear in the chunks to read out loud. The arguments are in order:
2589 % \begin{enumerate}
2590 % \item (mandatory) name of the macro (without leading backslash)
2591 % \item (optional) number of arguments of the macro
2592 % \item (optional) default for optional (first) argument
2593 % \item (mandatory) text to read (with macro parameters in them)
2594 % \end{enumerate}
2595 % \begin{macrocode}
2596 \ExplSyntaxOn
2597 \NewDocumentCommand{\spelenvad}{moomm}
2598 {
2599 \addtostream{spelidx}{envad|#1|#2|#3|#4|#5}
2600 }
2601 \ExplSyntaxOff
2602 % \end{macrocode}
2603 % \end{macro}
2604 %
2605 % We immediately provide some standard constructs, which are to be
2606 % ignored:
2607 % \begin{macrocode}
2608 \spelenvad{center}{}{}
2609 % \end{macrocode}
2610 %
2611 % \subsubsection{Inline descriptions for nesting}
2612 % \begin{macro}{\spelinlad}
2613 % This macro incorporates the first argument in the text file, but
2614 % sends the replacement using a macro preprocessing instruction to the
2615 % wizard.
2616 % \begin{macrocode}
2617 \ExplSyntaxOn
2618 \NewDocumentCommand{\spelinlad}{mm}{#1}
2619 \spelmacpp{spelinlad}[2]{#2}
2620 \ExplSyntaxOff
2621 % \end{macrocode}
2622 % \end{macro}
2623 %
2624 % \subsection{Support for third-party packages}
2625 % We will load the support after the preamble, such that all
2626 % packages have been loaded.
2627 %
2628 % \subsubsection{physics}
2629 %
2630 % \begin{macrocode}
2631 \AtBeginDocument{
2632 \@ifpackageloaded{physics}{
2633 \spelmacad{div}[1]{@{i18n(divergence,#1)}}
2634 \spelmacad{vec}[1]{@{i18n(vector,#1)}}
2635 \spelmacad{curl}[1]{@{i18n(curl,#1)}}
2636 \spelmacad{grad}[1]{@{i18n(gradient,#1)}}
2637 \spelmacad{dv}[2]{@{i18n(derivative,#1,#2)}}
2638 \spelmacad{pdv}[2]{@{i18n(partialderivative,#1,#2)}}
2639 }
2640 {}
2641 }
2642 % \end{macrocode}
2643 %
2644 % \subsection{Extra math commands}
2645 %
2646 % The commands are only loaded if the package option |extramath| is
2647 % provided:
2648 %
2649 % \begin{macrocode}
2650 \ifspel@extramath
2651 % \end{macrocode}
2652 %
2653 % \begin{macro}{\setenum}
2654 % This macro typesets a set defined by enumeration:
2655 % \begin{macrocode}
2656 \DeclareRobustCommand{\setenum}[1]{\left\{#1\right\}}
2657 \spelmacad{setenum}[1]{@{i18n(Setenum,#1)}}
2658 % \end{macrocode}
2659 % \end{macro}
2660 %
2661 % \begin{macro}{\setdesc}
2662 % This macro typesets a set defined by description:
2663 % \begin{macrocode}
2664 \DeclareRobustCommand{\setdesc}[1]{\left\{#1\right\}}
2665 \spelmacad{setdesc}[1]{@{i18n(Setdesc,#1)}}
2666 % \end{macrocode}
2667 % \end{macro}
2668 %
2669 % Note that these two macro's are identical! However, the fact that
2670 % they have a different name is of great value to \spelpl{}.
2671 %
2672 % \begin{macro}{\unitof}
2673 % This macro typeets its argument between square brackets, meaning
2674 % 'the unit of'. The corresponding audiodescription takes care of
2675 % proper reading out loud this construct.
2676 % \begin{macrocode}
2677 \DeclareRobustCommand{\unitof}[1]{\left[#1\right]}
2678 \spelmacad{unitof}[1]{@{i18n(Unitof,#1)}}
2679 % \end{macrocode}
2680 % \end{macro}
2681 %
2682 % The conditional loading ends here:
2683 % \begin{macrocode}
2684 \fi
2685 % \end{macrocode}
2686 %
2687 % \iffalse
2688 % \begin{macrocode}
2689 %</package>
2690 % \end{macrocode}
2691 % \fi
2692 %
2693 % \section{TODO}
2694 % \begin{spelchunk}[arealink]
2695 % As long as there are things on our todo list, we have a reason to
2696 % live.
2697 % \end{spelchunk}
2698 % \begin{itemize}
2699 % \spelitem{provide enable/disable switch to disable certain ranges in
2700 % text, e.g. the implementation range in this document}
2701 % \spelitem{enable bibliography and citation stuff}
2702 % \end{itemize}
2703 %
2704 % \bibliographystyle{alpha}
2705 %
2706 % \begin{thebibliography}{99}
2707 %
2708 % \bibitem{NVDA}
2709 % NVDA from NV Access, empowering lives through non-visual access to technology
2710 % \newblock \url{https://www.nvaccess.org}
2711 % \newblock online, accessed in June 2024.
2712 %
2713 % \bibitem{SPRINT}
2714 % SprintPlus, helping people with dyslexia
2715 % \newblock \url{https://www.sprintplus.be/en}
2716 % \newblock online, accessed in June 2024.
2717 %
2718 % \bibitem{ADOBEREADER}
2719 % Adobe Reader, a PDF reader from Adobe.
2720 % \newblock \url{https://get.adobe.com/}
2721 % \newblock online, accessed in May 2024.
2722 %
2723 % \bibitem{TAGPDF}
2724 % TagPDF - Tools for experimenting with tagging using pdfLaTeX and
2725 % LuaLaTeX.
2726 % \newblock \url{https://ctan.org/pkg/tagpdf}
2727 % \newblock online, accessed in June 2024.
2728 %
2729 % \bibitem{WINE}
2730 % Wine - Wine Is Not an Emulator - running windows applications on POSIX-compliant systems.
2731 % \newblock \url{https://www.winehq.org}
2732 % \newblock online, accessed in June 2024.
2733 %
2734 % \bibitem{SPEL}
2735 % SpeL --- Speech-enabled \LaTeX.
2736 % \newblock \url{https://ctan.org/pkg/spel}
2737 % \newblock online, accessed in June 2024.
2738 %
2739 % \bibitem{SPELWIZARD}
2740 % SpeL::Wizard --- Incantating \LaTeX{} into natural lanuage
2741 % \newblock \url{https://metacpan.org/pod/SpeL::Wizard}
2742 % \newblock online, accessed in June 2024.
2743 %
2744 % \bibitem{FESTIVAL}
2745 % The Festival TTS-program.
2746 % \newblock \url{http://www.cstr.ed.ac.uk/projects/festival}.
2747 % \newblock online, accessed in May 2024.
2748 %
2749 % \bibitem{BALABOLKA}
2750 % The Balabolka TTS-program.
2751 % \newblock \url{http://www.cross-plus-a.com/balabolka.htm}.
2752 % \newblock online, accessed in May 2024.
2753 %
2754 % \bibitem{FREETTS}
2755 % FreeTTS --- A speech synthesizer in Java.
2756 % \newblock \url{https://freetts.sourceforge.io/docs/index.php}.
2757 % \newblock online, accessed in May 2024.
2758 %
2759 % \bibitem{AWSPOLLY}
2760 % Amazon Polly --- An online text-to-speech engine.
2761 % \newblock \url{https://aws.amazon.com/polly}
2762 % \newblock online, accessed in May 2024.
2763 %
2764 % \bibitem{CTAN}
2765 % The Comprehensive \TeX{} Archive Network.
2766 % \newblock \url{http://www.ctan.org}.
2767 % \newblock online, accessed in May 2024.
2768 %
2769 % \bibitem{CPAN}
2770 % The Comprehensive Perl Archive Network.
2771 % \newblock \url{http://www.cpan.org}.
2772 % \newblock online, accessed in May 2024.
2773 %
2774 % \bibitem{XPDF}
2775 % xpdf, a simple and very fast PDF reader on \GNU/Linux.
2776 % \newblock \url{http://www.xpdfreader.com/}.
2777 % \newblock online, accessed in May 2024.
2778 %
2779 % \bibitem{EVINCE}
2780 % evince, a PDF reader, part of the Gnome environment.
2781 % \newblock \url{https://help.gnome.org/users/evince/stable/}.
2782 % \newblock online, accessed in May 2024.
2783 %
2784 % \bibitem{OKULAR}
2785 % okular, a PDF reader, part of the KDE environment.
2786 % \newblock \url{https://okular.kde.org}.
2787 % \newblock online, accessed in May 2024.
2788 %
2789 % \end{thebibliography}
2790 %
2791 % \Finale
2792 \endinput