diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/spelatex/spelatex.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/spelatex/spelatex.dtx | 462 |
1 files changed, 340 insertions, 122 deletions
diff --git a/Master/texmf-dist/source/latex/spelatex/spelatex.dtx b/Master/texmf-dist/source/latex/spelatex/spelatex.dtx index b906fd628b8..bdedc84d70b 100644 --- a/Master/texmf-dist/source/latex/spelatex/spelatex.dtx +++ b/Master/texmf-dist/source/latex/spelatex/spelatex.dtx @@ -1,6 +1,5 @@ % \iffalse meta-comment % -% % Copyright (C) 2024 by Walter Daems <walter.daems@uantwerpen.be> % and Paul Levrie % @@ -34,10 +33,10 @@ \ProvidesFile{spelatex.dtx} %</driver> %<*package> - [2024/06/12 v0.9 SpeLaTeX - Speech-enabled LaTeX (DMW and LVP)] + [2024/06/21 v0.91 SpeLaTeX - Speech-enabled LaTeX (DMW and LVP)] %</package> -\def\fileversion{0.9} -\def\filedate{2024/06/12} +\def\fileversion{0.91} +\def\filedate{2024/06/21} %<*driver> \documentclass[10pt]{ltxdoc} \usepackage{makeidx} @@ -79,7 +78,11 @@ % Right brace \} Tilde \~} % % -% \changes{v0.9}{2024/06/12}{. Birth} +% \changes{v0.90}{2024/05/31}{. Birth} +% \changes{v0.91}{2024/06/21}{. First overhaul:\\ +% - avoided big active link areas\\ +% - sketched bigger picture, leading to +% the three project phases.} % % \GetFileInfo{spelatex.dtx} % @@ -104,14 +107,14 @@ % \spelmacad{CPAN}{see-pan} % \newrobustcmd\POD{POD} % \spelmacad{POD}{pod} -% \newrobustcmd\spelwizardmodule{\texttt{SpeL::Wizard}} -% \spelmacad{spelwizardmodule}{spel double colon wizard} % % \maketitle % \fvset{gobble=2} % % \section{Preface} % +% \subsection{Background} +% % \begin{spelchunk} % At our institute, the University of Antwerp in Belgium, the number % of students with reading and/or writing disorders (or at least @@ -138,46 +141,152 @@ % group of students. Yes, economic laws also govern teaching! % \end{spelchunk} % +% \subsection{State of the art} +% +% \subsubsection{In general} +% % \begin{spelchunk} % Therefore, reverting to readily available text-to-speech software -% os an obvious choice. Nowadays, special software exists that +% is an obvious choice. Nowadays, special software exists that % provides the functionality of reading out loud the contents of -% electronic documents. For nontechnical subjects, -% this works fine. However, when it comes to technical course -% syllabi that are loaded with non-trivial mathematics, the standard -% text-to-speech packages fail to meet our expectations. In -% addition, they cannot read a sensible textual description of -% figures or tables. +% electronic documents, e.g. NVDA \cite{NVDA} or +% SprintPlus~\cite{SPRINT}. Moreover, more and more standard PDF +% readers (such +% as Acrobat Reader~\cite{ADOBEREADER} have the facility of +% performing text-to-speech). For nontechnical subjects, this works +% fine. However, when it comes to technical course syllabi that are +% loaded with non-trivial mathematics, the standard text-to-speech +% packages fail to meet our expectations. In addition, they cannot +% read a sensible textual description of figures or tables. +% \end{spelchunk} +% +% \begin{spelchunk} +% The issue with reading mathematics will be solved in the future, +% by enforcing mathematical equations to follow a specific standard +% that can be parsed and converted, not only into a visual +% representation, but also into proper text. MathML will be one of +% the candidates for that format. +% \end{spelchunk} +% +% \begin{spelchunk} +% The issue with figures and tables can be solved by using the tag +% infrastructure of PDF. The format provides a system of tags that +% allow you to provide extra information about the content of a +% document, in much the same way as you can specify an 'alt' key for +% an image in HTML. This tag could contain a proper textual +% description of the figure or the table. % \end{spelchunk} % +% \subsubsection{For \LaTeX} +% +% \begin{spelchunk} +% Currently, the \LaTeX project is investing in enabling \LaTeX{} to +% partially automate the tagging of PDFs with the \texttt{tagpdf} +% package~\cite{TAGPDF}, such that the user only has to do a minimal +% job (adding tags for figures and tables). The goal is to maximize +% the accessibility of \LaTeX-produced documents. +% \end{spelchunk} +% % \begin{spelchunk} -% \LaTeX{} is one of the better choices when it comes to typesetting -% technical subjects, so why not extend \LaTeX{} to provide -% mathematics-capable text-to-speech facilities? Our \spelatex{} -% prototype does exactly that. Admittedly, using it causes a -% significant overhead in writing your text. Therefore we also -% provide you the \spelbox{} extension for the Org-mode +% So all is well? Not quite. Though I'm confident that with enough +% time the community will solve the issue completely, there are +% still some gaps: +% \end{spelchunk} +% \begin{itemize} +% \spelitem{The tagpdf package is still not a part of the mainstream +% \LaTeX{}-kernel.} +% \spelitem{MathML reading support in PDF readers is still in its +% infancy.} +% \spelitem{Many PDF readers do not fully support tags yet.} +% \end{itemize} +% +% \subsection{This package} +% +% \begin{spelchunk} +% This package aims to overcome these problems in the meantime and +% also to contribute to the longterm goal: making perfectly tagged +% PDFs that are read by any PDF-reader. +% \end{spelchunk} +% +% \begin{spelchunk} +% In the \emph{first phase} of this package (i.e. the version you are +% looking at right now), this package reads your \LaTeX{} source, +% converts the text and the formulas to audio files and equips your +% PDF with hyperlinks to these files, such that with a few clicks +% you can listen to your document. +% The audio files are external files that should be packaged with +% your PDF to allow a reader to use the document with the available +% audio. +% How does it read the formulas? It parses your \LaTeX{} constructs and +% makes the best of it. This will probably be the part that might +% survive up until the very last phase of this package. +% \end{spelchunk} +% +% \begin{spelchunk} +% In a \emph{second phase} of this package, the audio files will be embedded +% into the PDF. Currently, there are not enough PDF readers that +% support this feature. Therefore, we decided to keep using the +% external audio files for now. +% \end{spelchunk} +% +% \begin{spelchunk} +% In a \emph{third phase}, the audio files \emph{may be} abandoned +% alltogether, fully switching to tags. And we do think that this +% should be the end goal. The reasons why we say +% \emph{'may be'}, are: +% \end{spelchunk} +% \begin{itemize} +% \spelitem{The voices of the current PDF-readers are still not of the +% same quality as the ones available online. And quality does matter.} +% \spelitem{The better voices may require cloud access, and probably +% will not be free, therefore (me) paying for them at document creation +% time, makes more sense to me than having my students pay +% for these voices whenever they read the document.} +% \spelitem{The industry standard Adobe reader is not easily available +% on open-source operating systems (like UNIX/BSD/Linux-derived +% platforms). You might consider using emulation using +% wine~\cite{WINE}, but in that case you can forget about audio. Free +% access to software is something we consider to be a must-have, +% rather than a nice-to-have. In addition, Walter feels miserable when +% he's forced to use anything else than GNU/Linux, because then he +% keeps moaning that his productivity is ruined.} +% \end{itemize} +% +% \begin{spelchunk} +% Admittedly, in this first phase, using the \spelatex{} package +% causes a significant overhead in writing your text. Therefore we +% also provide you the \spelbox{} extension for the Org-mode % \cite{ORGMODE} of \GNU{} Emacs \cite{EMACS}. To satisfy your % curiosity: \spelbox{} stands for ``Speech-Enabled \LaTeX{} By % Org-mode eXport''. % \end{spelchunk} % % \begin{spelchunk} -% Will AI take over the role of this package in the future? -% Undoubtedly so. But for the time being, and also to avoid wasting -% the enormous amount of energy AI costs us, we hope that you enjoy +% Will \spelatex{} become obsolete in the future? +% Undoubtedly so. But for the time being, it answers our desire to +% provide our students with good audio support when studying their +% engineering courses. That is now, not only in five years time. +% \end{spelchunk} + +% \begin{spelchunk} +% We hope that you enjoy % using our software, or that --- if you are not pleased with it --- % it triggers you to give us feedback or to come up with a better -% solution. +% solution. We especially would like to thank Ulrike Fischer (of the +% \LaTeX-project and the maintainer of the tagpdf package) for +% trying to use this package and reaching out to give us feedback. +% One of her suggestions (not to use big hyperlink-areas) was almost +% instantly implemented and has been adopted as the standard way of +% linking. % \end{spelchunk} % % \begin{spelchunk} % You are free to use our software but kindly ask you to provide a % mention ``The audio materials of this text have been prepared with % \spelatex{}/\spelbox{}'' in the section treating copyrights, -% bibliographic data or any other spot that is suited. I'd also +% bibliographic data or any other spot that is suited. We'd also % welcome a short mail of yours telling that you make use of the -% package. The pleasure of receiving such an e-mail makes my day. +% package. The pleasure of receiving such an e-mail makes our day. % \end{spelchunk} % % \begin{spelchunk} @@ -215,8 +324,8 @@ % \spelatex{}.\footnote{Note that multitasking is not reserved for persons % without visual impairment. Also visually impaired persons can % benefit from listening to an audiobook while doing other -% things.} Personally, I often use \spelatex{} to proofread texts as I -% hear language errors more easily than I spot them while reading. +% things.} Personally, we often use \spelatex{} to proofread texts as we +% hear language errors more easily than we spot them while reading. % \end{spelchunk} % % \subsection{The magic under the hood} @@ -228,9 +337,9 @@ % ecosystem. It consists of three components: % \end{spelchunk} % \begin{itemize} -% \spelitem{An Org-mode exporter called \texttt{ox-spelatex} \cite{OXSPELATEX}} +% \spelitem{An Org-mode exporter called \texttt{ox-spel} \cite{OXSPELATEX}} % \spelitem{This \LaTeX{}-package \spelatex{} \cite{SPEL}} -% \spelitem{A script embeded in the Perl module \spelwizardmodule~\cite{SPELWIZARD}} +% \spelitem{A script embeded in the Perl module \texttt{SpeL::Wizard} \cite{SPELWIZARD}} % \end{itemize} % % \subsubsection{The overall picture} @@ -249,7 +358,7 @@ % \end{spelchunk} % % \begin{spelchunk} -% By loading the |spelatex.sty| package in your source +% By loading the |spel.sty| package in your source % document, \LaTeX{} will produce a PDF file that references audio % files that will be generated later (see below). In % addition, it generates text chunks (i.e. small portions of @@ -294,11 +403,11 @@ % tool/.style={rectangle,draw,align=center}] % \node [doc] (utext) at (0,9) {text.org\\\footnotesize(unprepped % source)}; -% \node [tool] (instrument) at (0,6) {Org-mode exporter\\\footnotesize(\texttt{ox-spelatex})}; +% \node [tool] (instrument) at (0,6) {Org-mode exporter\\\footnotesize(\spelbox)}; % \node [doc] (text) at (0,3) {text.tex\\\footnotesize(prepped source)}; % \draw[->] (utext) -- (instrument); % \draw[->] (instrument) -- (text); -% \node [doc] (R) at (-3,0) {spelatex.sty\\\footnotesize(package)}; +% \node [doc] (R) at (-3,0) {spel.sty\\\footnotesize(package)}; % \node [tool] (latex) at (0,0) {\LaTeX\\\footnotesize(compiler)}; % \node [doc] (pdf) at (0,-3) {text.pdf\\\footnotesize(PDF with\\\footnotesize hyperlinks)}; % \node [doc] (spelidx) at (6,-3) {text.spelidx\\\footnotesize(index file)}; @@ -313,7 +422,7 @@ % \draw[->] (latex) edge[out=10,in=90] (aux); % \draw[->] (latex) edge[out=-10,in=90] (files); % \node [tool] (engine) at (6,-6) {\spelpl{}\\ -% \footnotesize(\spelwizardmodule{} engine)}; +% \footnotesize(\spelatex{} engine)}; % \node [tool] (t2s) at (1.5,-6) {text-to-speech\\engine}; % \draw[->] (files) -- (engine); % \draw[->] (spelidx) -- (engine); @@ -339,13 +448,13 @@ % unprepped source. Read the Orgmode % documentation on \LaTeX{} and \spelatex{}-exporting to get to know % the format. The Orgmode \spelatex{} exporter, creates a fully -% equipped \LaTeX{} file of your text. We call this the prepped source. You can +% equiped \LaTeX{} file of your text. We call this the prepped source. You can % also start by composing this file yourself. -% If your prepped source file uses the \spelatex{} style file, then +% If you prepped source file uses the \spelatex{} style file, than % your compiler will generate a PDF file with hyperlinks, a % dot aawks-file and a dot spellindex-file together with a directory full of -% dot tech files containing the text chunks to be processed by -% \spelpl. This is a perl script that converts the chunks into +% dot tex files containing the text chunks to be processed by the +% \spelpl-engine. This is a perl script that converts the chunks into % plain text readable spel files. The script is called spel dash % wizard dot pl. It also creates a playlist and audio files using a % text-to-speech engine. In this case, these are @@ -363,6 +472,28 @@ % \label{fig:setup} % \end{figure} % +% \begin{spelchunk} +% You might wonder: where are the links? Well, there are three +% variants: +% \end{spelchunk} +% \begin{itemize} +% \spelitem{\emph{area links}, which are almost exclusively +% used for equations, tables or figures. These links make an entire +% rectangle active, linking to the corresponding audio file.} +% \spelitem{\emph{group links}, indicated by small right-pointing +% triangles next to section headers. These cause all blocks in the +% section to be read one by one.} +% \spelitem{\emph{hidden links}, wich are, as the name suggests, +% hidden to avoid visual disturbance of the text; every +% paragraph, footnote and list is activated by a link on the +% whitespace before the first line of the chunk. Try it! Once you +% are aware that these regions are active, you'll find them +% easily. In addition, not using the full paragraph as an active +% region, allows existing hyperlinks (like for citations, references +% or URLs) to still function.} +% \end{itemize} +% +% % \subsubsection{Implicit spelchunks} % \spelmacad{usepackage}[1]{the usepackage #1 macro} % \spelmacad{title}{the title macro} @@ -390,7 +521,7 @@ % that follows as a first explicit argument, i.e. |\item blabla| % should be replaced by |\spelitem{blabla}|. % We call these \LaTeX-fragments \emph{defunct implicit -% spelchunks}. They should have been implicit, but I could not get +% spelchunks}. They should have been implicit, but we could not get % that to work without problems. Therefore you need to mark them % explicitly as |\spelitem| constructs. % \end{spelchunk} @@ -400,7 +531,7 @@ % One would hope that displaymath environments are also implicit % spelchunks. However, overriding environments in \LaTeX{} is a tricky % business. In view of this, the \spelatex{} package keeps away from -% this, and I've chosen to treat displaymath environments (like +% this, and we've chosen to treat displaymath environments (like % |equation|, |eqnarray|, |gather|, |align|, |alignat|) the same way % as tables or figures, i.e. you need to embed the in a |spelchunk| % environment. The only difference between math environments and @@ -472,7 +603,7 @@ % This brings us to the two top boxes in the diagram of % Fig.~\ref{fig:setup}. If you prepare your manuscript in Org-mode, % and use the Org-mode exporter, you don't have to worry about explicit -% spelchunks, or defunct implicit spelchunks. Therefore, I encourage +% spelchunks, or defunct implicit spelchunks. Therefore, we encourage % you to use Emacs as your editor. The learning % curve is steep, but the rewards regarding ease-of-use are huge. % In that way, you can focus on providing textual descriptions for @@ -485,7 +616,7 @@ % independent of Org-mode. It also shows that if you don't % want to use Emacs and Org-mode, you will suffer some considerable % pain in equipping your manuscript with an overload of |spelchunk| -% environments. I have only one advice: don't use the \spelatex{} +% environments. We have only one advice: don't use the \spelatex{} % outside \spelbox{}. Outside a proper boxed confinement, % spells easily become curses\ldots % \end{spelchunk} @@ -518,8 +649,8 @@ % \subsection{Added value} % % \begin{spelchunk} -% Why would it make sense to use \spelatex? I think there are many -% selling points. I can mention a few: +% Why would it make sense to use \spelatex? We think there are many +% selling points. We can mention a few: % \end{spelchunk} % \begin{description} % \spelitem[Minimal overhead]{ @@ -533,7 +664,7 @@ % the effort of preparing your manuscript. There are no license % costs involved.\\ % You could also consider to use an online paying text-to-speech -% service. As an example, I incorporated a connection to Amazon's +% service. As an example, We incorporated a connection to Amazon's % Polly \cite{AWSPOLLY}.\\ % In addition, if your user has a better-quality (maybe % commercial) text-to-speech system, he/she can reconvert the text @@ -553,15 +684,27 @@ % \section{Installation} % % \subsection{The \spelatex{} package} - % \begin{spelchunk} -% Most \LaTeX{} distributions use \CTAN{} as their main package source -% and therefore will include \spelatex. +% If you are a package manager then you'll know how to +% prepare an installation package for \spelatex. +% \end{spelchunk} +% +% \begin{spelchunk} +% If you are a normal user then you have two options. First, +% check if there is a package that your favorite \LaTeX{} +% distributor has prepared for you. Most of the major distributions +% (like e.g. \TexLive{} or \MikTeX{}) do so.\\ +% Second, grab the TDS package +% from \CTAN{} \cite{CTAN} (spel.TDS.zip) and unzip it somewhere in your +% own TDS tree, regenerate your filename database and off you go. +% In any case, make sure that \LaTeX{} finds the file |spel.sty|. % \end{spelchunk} % -% %\begin{spelchunk} -% If this is not the case, contact me. I'll be glad to provide you -% with TDS file that you can unpack in your local TDS tree. +% \begin{spelchunk} +% The \spelatex{} package uses a number of auxiliary packages, fetch them +% from \CTAN{} \cite{CTAN} if your \TeX{} distributor does not provide +% them. The ones used are: |expl3|, |hyperref|, |ifthen|, +% |fancyvrb|, |newfile|, |rotating|, |babel|, |kvoptions|. % \end{spelchunk} % % \subsection{The \spelpl{} speech generator} @@ -576,9 +719,9 @@ % \end{spelchunk} % % \begin{spelchunk} -% The only thing to do is to install the -% \spelwizardmodule~module. You can do this with the perl pacakge -% manager for your interpreter. +% The only thing to do is to install the |SpeL::Wizard| +% module. You can do this with the perl pacakge manager for your +% interpreter. % \end{spelchunk} % % \begin{spelchunk} @@ -588,8 +731,8 @@ % % \begin{spelchunk} % On \GNU/Linux and MAC: |$ cpanm SpeL::Wizard|\\ -% When using Strawberry perl: |$ cpan SpeL::Wizard|\\ -% When using ActiveState perl: |$ ppm install SpeL-Wizard| +% On Strawberry perl: |$ cpan SpeL::Wizard|\\ +% On ActiveState perl: |$ ppm install SpeL-Wizard| % \end{spelchunk} % % \begin{spelchunk} @@ -600,7 +743,7 @@ % \subsubsection{The configuration file} % \begin{spelchunk} % Finally, you need to provide \spelpl{} with an appropriate -% config-file that sets up the text-to-speech conversion. +% config-file, named |tts.conf| that sets up the text-to-speech conversion. % Below you can find a setup for Festival \cite{FESTIVAL}: % \begin{Verbatim} % [engine] @@ -615,6 +758,21 @@ % english=en1_mbrola % \end{Verbatim} % \end{spelchunk} +% +% \begin{spelchunk} +% And additionally, for the Microsoft users a setup for Balabolka \cite{BALABOLKA}: +% \begin{Verbatim} +% [engine] +% tts=balabolka +% +% [languagetags] +% english=en-us +% +% [voices] +% english=Zira +% \end{Verbatim} +% \end{spelchunk} +% % \begin{spelchunk} % The tts configuration parameter defines the speech engine to use. % The languagetags section defines how the babel languages are mapped to @@ -630,20 +788,28 @@ % \end{Verbatim} % \end{spelchunk} % \begin{spelchunk} +% If that variable is not set, the script will look in a subdirectory +% |.spel_wizard| of your home-folder (or |%userprofile%| in +% MS-Windows), or it will take the default that came with the +% |SpeL::Wizard| module. +% \end{spelchunk} +% +% \begin{spelchunk} % Be aware that you need to install your text-to-speech tool yourself -% according to the documentation provided by the tool provider. In +% according to the documentation provided by the tool provider. +% In addition, make sure it the executable is in your search path. In % case you are using an online text-to-speech service provider you % will need to get an account on their cloud platform and setup % credentials and whatever is needed to get going. Providing -% assistance for this is beyond the aim of this manual.% +% assistance for this is beyond the aim of this manual. % \end{spelchunk} % % \subsection{The PDF viewer} % % \begin{spelchunk} % You need to make sure you have a PDF-viewer that supports links -% containing 'run:' tags. E.g., xpdf does not \cite{XPDF}, evince -% complains about security risks \cite{EVINCE}, but okular +% containing 'run' tags. E.g., xpdf \cite{XPDF} does not, evince +% \cite{EVINCE} complains about security risks, but okular % \cite{OKULAR} and Adobe Reader \cite{ADOBEREADER} do. So does % PDF-XChange Viewer \cite{PDFXCHANGE}. % \end{spelchunk} @@ -652,13 +818,16 @@ % \begin{spelchunk} % When clicking a \spelatex-enabled item in your PDF-file, your media -% player is started to play the |.ogg| or |.m3u|-file. On \GNU/Linux -% most media players work fine (SoX, totem, vlc, \ldots).\\ -% On windows, I'd recommend using vlc. It works out of the box. +% player is started to play the |.ogg| or |.m3u|-file. On GNU/Linux +% most media players work fine (SoX, totem, vlc, \ldots). +% \end{spelchunk} +% +% \begin{spelchunk} +% On windows, we recommend using vlc. It works out of the box. % When usign the stock Windows Media Player, you will need to add % every folder that contains a PDF you'd like to have read, to your % Media Player library. Search the internet to find instructions on -% that and be prepared: in line with Microsoft standard practice it +% that and be prepared: in line with Microsoft's standard practice it % is well hidden in the interface. % \end{spelchunk} % @@ -691,7 +860,7 @@ % required macros. % \end{spelchunk} % -% \subsubsection{Treating the implicit spelchunks} +% \subsubsection{Treat the implicit spelchunks} % \begin{spelchunk} % The texts of chapter, (sub)section titles, a.s.o. will be formatted % automatically such that they are hyperlinked to the appropriate @@ -710,7 +879,7 @@ % \begin{spelchunk} % Example: % \begin{Verbatim} -% I like +% We like % \begin{itemize} % \spelitem{apples,} % \spelitem{pears, and} @@ -732,12 +901,15 @@ % boilerplate work. % \end{spelchunk} % -% \subsubsection{Treating the explicit spelchunks} +% \subsubsection{Treat the explicit spelchunks} % % \begin{spelchunk} % \DescribeEnv{spelchunk} % Use this environment to embed the chunks of text in that you want -% to generate audio for. +% to generate audio for. In case the content is an equation, a +% figure or a table, we recommend specifying |arealink| as the +% optional argument to the |spelchunk| environment. It makes the +% entire equation an active hyperlink. % \end{spelchunk} % % \begin{spelchunk} @@ -748,10 +920,12 @@ % \begin{Verbatim} % \begin{spelchunk} % An orderinary paragraph must be embedded in this environment. -% The same holds for equations! +% The same holds for equations! However, then we recommend using +% the |arealink| option, as that makes the full area of the +% equation clickable and avoids an empty white line before the +% equation. % \end{spelchunk} -% -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{align} % E &= m c^2\\ % e^{j\pi} &= -1 @@ -760,7 +934,7 @@ % \end{Verbatim} % % -% \subsubsection{Manually providing text to read when needed} +% \subsubsection{Manually provide text to read when needed} % \begin{spelchunk} % \DescribeEnv{spelchunkad} % If you want a different text to be used for the previous @@ -778,7 +952,7 @@ % % \begin{spelchunk} % Example:\\ -% {\footnotesize (note: the example below is not \spelatex{}-enabled because it also +% {\footnotesize (note: the example below is not \spelatex{}-enabled because it % generates internal package problems)} % \end{spelchunk} % \begin{Verbatim} @@ -802,7 +976,7 @@ % \begin{spelchunk} % Example:\\ % {\footnotesize (note: the example below is not \spelatex{}-enabled because it -% generates internal package problems also)} +% generates internal package problems)} % \end{spelchunk} % \begin{Verbatim} % \begin{spelchunk} @@ -874,9 +1048,9 @@ % \begin{spelchunk} % This allows easy specification of an illustration as: % \begin{Verbatim} -% \begin{proof}[Illustration]{solving a quadratic equation} -% blabla -% \end{proof} +% \begin{proof}[Illustration]{solving a quadratic equation} +% blabla +% \end{proof} % \end{Verbatim} % \end{spelchunk} % \begin{spelchunk} @@ -943,15 +1117,17 @@ % This macro typesets an enumeration set and makes sure \spelpl{} % can read it properly. % \end{spelchunk} +% \begin{spelchunk} % \begin{Verbatim} % \begin{equation} % P = \setenum{ 2, 3, 5, 7, 11, 13, \ldots } % \end{equation} % \end{Verbatim} +% \end{spelchunk} % % \DescribeMacro{\setdesc} % \begin{spelchunk} -% This macro typesets a descriptive set and makes sure \spelpl{} +% This macro typesets an enumeration set and makes sure \spelpl{} % can read it properly. % \end{spelchunk} % \begin{spelchunk} @@ -1043,8 +1219,7 @@ % Consider the following simple definition of a polynomial function and % check its spoken version by clicking on it. % \end{spelchunk} -% -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{equation} % f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 23 % \end{equation} @@ -1066,7 +1241,7 @@ % equal to $\tan\alpha = -\frac{t}{2}$, the equation of the % reflected ray is given by % \end{spelchunk} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \[ % y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t) % \] @@ -1079,9 +1254,9 @@ % voorleesstem de geselecteerde taal zal volgen. % \end{spelchunk} % -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \[ -% y-9+\frac{t^2}{4} = -(x-t) \cdot \frac{4t}{4-t^2} +% y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t) % \] % \end{spelchunk} @@ -1113,7 +1288,7 @@ % \newblock \url{http://www.cpan.org}. % \newblock online, accessed in August 2021. % -% \end{thebibliography}{99} +% \end{thebibliography} % % \end{document} % \end{VerbatimOut} @@ -1134,8 +1309,7 @@ % \end{spelchunk} % % \subsection{Numbers} -% -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{align} % \pi\\ % -31415\\ @@ -1149,7 +1323,7 @@ % % \subsection{Fractions} % \subsubsection{A fraction only containg numbers} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{align} % x &= - \frac{1}{2} \\ % y &= - \sqrt{\frac{\pi}{2}} @@ -1157,7 +1331,7 @@ % \end{spelchunk} % % \subsubsection{A fraction with a little more under the hood} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{align} % u &= - \frac{x^2+35}{\sqrt{12}} \\ % v &= - \frac{\sqrt{\frac{\pi}{2}}}{-3x^2+3} @@ -1166,8 +1340,8 @@ % % % \subsection{Simple expressions} -% \subsubsection{A polynomial function} -% \begin{spelchunk} +% \subsubsection{A polynomial function}% +% \begin{spelchunk}[arealink] % \begin{equation} % f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 23 % \end{equation} @@ -1177,7 +1351,7 @@ % \begin{spelchunk} % Here's de Moivre's formula: % \end{spelchunk} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{equation} % \left(\cos x+j\sin x\right)^n=\cos(nx)+j\sin(nx) % \end{equation} @@ -1186,7 +1360,7 @@ % \begin{spelchunk} % Euler's relationship: % \end{spelchunk} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{equation} % e^{j \phi} = \cos \phi + j \sin \phi % \end{equation} @@ -1214,7 +1388,7 @@ % \texttt{\textbackslash{}setenum} and % \texttt{\textbackslash{}setdesc}: % \end{spelchunk} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{align} % P &= \setenum{ 2, 3, 5, 7, 11, 13, \ldots }\\ % P &= \setdesc{ n \in N \mid n \text{~is prime}} @@ -1224,6 +1398,8 @@ % \subsection{Matrices} % \begin{spelchunk} % How about some linear algebra? +% \end{spelchunk} +% \begin{spelchunk}[arealink] % \begin{align} % \begin{bmatrix} % 3 & 4 \\ @@ -1372,7 +1548,7 @@ % \section{Implementation} % \begin{spelchunk} % To ease the implementation work and because raw \LaTeX{} code is -% difficult to read on itself, I took the liberty of not providing +% difficult to read on itself, We took the liberty of not providing % this section with speech chunks (except for this introduction % text). % \end{spelchunk} @@ -1425,6 +1601,8 @@ bookmarksopen=true, urlcolor=black} \RequirePackage{kvoptions} +\RequirePackage{xkeyval} +\RequirePackage{marginnote} % \end{macrocode} % % \subsection{Options} @@ -1633,9 +1811,6 @@ \spel@registerelement{author} % \end{macrocode} % -% \subsubsection{Boxed material} -% by redefining the makebox, mbox and usebox commands, we can create -% % \subsubsection{Table of contents} % \begin{macrocode} \ifspel@disabled\else @@ -1748,7 +1923,7 @@ \setcounter{spel@chunk}{0}% need this because counter resetting fails \spel@@sect{#1}{#2}{#3}{#4}{#5}{#6}[#7]{% \href{run:\audiodir/\spel@@optpart\thesubparagraph.\spel@format}{#8}\hfill% - \href{run:\audiodir/\spel@@optpart\thesubparagraph.m3u}{\textcolor{black!50}{\triangleright}}}% + \href{run:\audiodir/\spel@@optpart\thesubparagraph.m3u}{\textcolor{black!25}{$\triangleright$}}}% \def\spel@@label{\ifnum #2>\c@secnumdepth\else#1 \csname the#1\endcsname\fi} \spel@idxwrite{\spel@@label}{\spel@@optpart\thesubparagraph}% \spel@chunkwrite{\spel@@optpart\thesubparagraph}{#8}% @@ -1786,8 +1961,9 @@ \let\spel@@fntext\@footnotetext \long\def\@footnotetext#1{% \stepcounter{spel@footnote}% + \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}% \spel@@fntext{% - \href{run:\audiodir/footnote-\thespel@footnote.\spel@format}{#1}} + \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/footnote-\thespel@footnote.\spel@format}{\usebox\spel@mptbox}#1}% \spel@idxwrite{footnote}{footnote-\thespel@footnote}% \spel@chunkwrite{footnote-\thespel@footnote}{#1}% } @@ -1825,10 +2001,10 @@ % \begin{macrocode} \def\spelitem@intone#1{% \stepcounter{spel@chunk}% + \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}% \spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}% \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1}% - \item \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{#1} -} + \item \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#1} % \end{macrocode} % \end{macro} % @@ -1838,10 +2014,10 @@ % \begin{macrocode} \def\spelitem@inttwo#1#2{% \stepcounter{spel@chunk}% + \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}% \spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}% \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1 . #2}% - \item[#1] \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{#2} -} +\item[#1] \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#2} % \end{macrocode} % \end{macro} % @@ -1868,6 +2044,11 @@ % \begin{environment}{spelchunk} % The |spelchunk| environment is used to define explicit speech chunks. % \begin{macrocode} +\newlength\spel@mptboxwidth +\newsavebox\spel@mptbox +\savebox\spel@mptbox{\textcolor{black!25}{$\qquad$}} +\newif\ifspel@chunkarealink +\define@key{spelchunk}{arealink}[]{\spel@chunkarealinktrue} \ifspel@disabled\def\spelchunk{}\else \def\spelchunk{% \catcode`\^^M=\active% @@ -1879,7 +2060,13 @@ \def\endspelchunk{% \end{VerbatimOut}% \catcode`\^^M=5\relax% - \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}\leavevmode}% + \ifspel@chunkarealink% + \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}}% + \else% + \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}% + \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}% + \fi% + \spel@chunkarealinkfalse% }% \fi % \end{macrocode} @@ -1891,7 +2078,7 @@ % This is macro that deals with the optional arguments of the % |spelchunk| envronment. % \begin{macrocode} -\def\spelchunk@opt[#1]{\fvset{#1}\spelchunk@int} +\def\spelchunk@opt[#1]{\setkeys{spelchunk}{#1}\spelchunk@int} % \end{macrocode} % \end{macro} % @@ -1905,7 +2092,7 @@ % \end{macrocode} % \end{macro} % -% \subsubsection{Provideing an explicit audiodescription for a spelchunk} +% \subsubsection{Explicit spelchunks} % % \begin{environment}{spelchunkad} % The |spelchunkad| environment is used to override a previous speech @@ -2052,10 +2239,10 @@ % We immediately provide some standard constructs, which are to be % ignored: % \begin{macrocode} -\spelmacad{spelatex}{spee-laytech} +\spelmacad{spelatex}{spee-lay-tech} \spelmacad{spelbox}{spel-box} \spelmacad{spelpl}{spel wizzard dot pl} -\spelmacad{LaTeX}{laytech} +\spelmacad{LaTeX}{lay-tech} \spelmacad{TeX}{tech} \spelmacad{textsf}[1]{#1} \spelmacad{texttt}[1]{#1} @@ -2107,7 +2294,7 @@ \spelenvad{center}{}{} % \end{macrocode} % -% \subsection{Implementing the extra math commands} +% \subsection{Extra math commands} % % The commands are only loaded if the package option |extramath| is % provided: @@ -2145,35 +2332,71 @@ %</package> % \end{macrocode} % \fi - +% +% \section{TODO} +% \begin{spelchunk}[arealink] +% As long as there are things on my todo list, We have a reason to +% live. +% \end{spelchunk} +% \begin{itemize} +% \spelitem{provide enable/disable switch to disable certain ranges in +% text, e.g. the implementation range in this document} +% \spelitem{enable bibliography and citation stuff} +% \end{itemize} % % \bibliographystyle{alpha} % % \begin{thebibliography}{99} % -% \bibitem{EMACS} -% The Emacs An extensible, customizable, free text editor --- and -% more. -% \newblock \url{https://www.gnu.org/software/emacs/}. +% \bibitem{NVDA} +% NVDA from NV Access, empowering lives through non-visual access to technology +% \newblock \url{https://www.nvaccess.org} +% \newblock online, accessed in June 2024. +% +% \bibitem{SPRINT} +% SprintPlus, helping people with dyslexia +% \newblock \url{https://www.sprintplus.be/en} +% \newblock online, accessed in June 2024. +% +% \bibitem{ADOBEREADER} +% Adobe Reader, a PDF reader from Adobe. +% \newblock \url{https://get.adobe.com/} % \newblock online, accessed in May 2024. % +% \bibitem{TAGPDF} +% TagPDF - Tools for experimenting with tagging using pdfLaTeX and +% LuaLaTeX. +% \newblock \url{https://ctan.org/pkg/tagpdf} +% \newblock online, accessed in June 2024. +% +% \bibitem{WINE} +% Wine - Wine Is Not an Emulator - running windows applications on POSIX-compliant systems. +% \newblock \url{https://www.winehq.org} +% \newblock online, accessed in June 2024. +% % \bibitem{ORGMODE} % Org Mode --- your life in plain text. % \newblock \url{https://orgmode.org/}. % \newblock online, accessed in May 2024. % +% \bibitem{EMACS} +% The Emacs An extensible, customizable, free text editor --- and +% more. +% \newblock \url{https://www.gnu.org/software/emacs/}. +% \newblock online, accessed in May 2024. +% % \bibitem{OXSPELATEX} % Org Mode SpeLaTeX Exporter --- SpeLaTeX made easy. % \newblock \url{https://www.melpa.org/#/ox-spelatex} % \newblock (not yet online) % % \bibitem{SPEL} -% SpeL --- Speech-enabled LaTeX. +% SpeL --- Speech-enabled \LaTeX. % \newblock \url{https://ctan.org/pkg/spel} % \newblock online, accessed in June 2024. % % \bibitem{SPELWIZARD} -% SpeL::Wizard --- Incantating LaTeX into natural lanuage +% SpeL::Wizard --- Incantating \LaTeX{} into natural lanuage % \newblock \url{https://metacpan.org/pod/SpeL::Wizard} % \newblock online, accessed in June 2024. % @@ -2222,11 +2445,6 @@ % \newblock \url{https://okular.kde.org}. % \newblock online, accessed in May 2024. % -% \bibitem{ADOBEREADER} -% Adobe Reader, a PDF reader from Adobe. -% \newblock \url{https://get.adobe.com/} -% \newblock online, accessed in May 2024. -% % \bibitem{PDFXCHANGE} % PDF XChange Viewer, a PDF reader from Tracker Software. % \newblock \url{https://www.pdf-xchange.com/} |