diff options
Diffstat (limited to 'macros/latex/contrib/spelatex/spelatex.dtx')
-rw-r--r-- | macros/latex/contrib/spelatex/spelatex.dtx | 898 |
1 files changed, 470 insertions, 428 deletions
diff --git a/macros/latex/contrib/spelatex/spelatex.dtx b/macros/latex/contrib/spelatex/spelatex.dtx index bdedc84d70..564abba5a2 100644 --- a/macros/latex/contrib/spelatex/spelatex.dtx +++ b/macros/latex/contrib/spelatex/spelatex.dtx @@ -20,7 +20,6 @@ % This work consists of the files spelatex.dtx, spelatex.ins, % and any derivative file, generated from the dtx file using % the ins driver file. -% % \fi % % \iffalse @@ -33,17 +32,20 @@ \ProvidesFile{spelatex.dtx} %</driver> %<*package> - [2024/06/21 v0.91 SpeLaTeX - Speech-enabled LaTeX (DMW and LVP)] + [2024/09/09 v0.92 SpeLaTeX - Speech-enabled LaTeX (DMW and LVP)] %</package> -\def\fileversion{0.91} -\def\filedate{2024/06/21} +\def\fileversion{0.92} +\def\filedate{2024/09/09} %<*driver> \documentclass[10pt]{ltxdoc} \usepackage{makeidx} \usepackage{alltt} \usepackage[english]{babel} -\usepackage[extramath]{spelatex} +\usepackage[extramath, + server=https://ctan.org/tex-archive/macros/latex/contrib/spelatex + ]{spelatex} \usepackage{amsmath} +\usepackage{amsfonts} \usepackage{graphicx} \usepackage{tikz} \IfFileExists{tocbibind.sty}{\usepackage{tocbibind}}{} @@ -83,6 +85,11 @@ % - avoided big active link areas\\ % - sketched bigger picture, leading to % the three project phases.} +% \changes{v0.92}{2024/09/09}{. Second overhaul:\\ +% - dumped orgmode export idea (too small of an audience)\\ +% - introduced markers for non-area-links\\ +% - implemented audio on server\\ +% - implemented <\kern-0.5ex<\kern-0.5ex<-macro as a shorthand} % % \GetFileInfo{spelatex.dtx} % @@ -111,41 +118,49 @@ % \maketitle % \fvset{gobble=2} % +% \section*{Disclaimer} +% \<<<{ +% Note that this is an experimental package. Its interface may change +% considerably over subsequent versions (until v1.0). +% } +% % \section{Preface} % % \subsection{Background} % -% \begin{spelchunk} +% \<<<{ % At our institute, the University of Antwerp in Belgium, the number % of students with reading and/or writing disorders (or at least % aware of these disorders) is increasing. Approximately 5\% of the -% students are registered with such a disorder. Probably there's an -% additional number of people opting not to register their disorder. -% \end{spelchunk} -% -% \begin{spelchunk} +% students are registered with such a disorder and the number is rising +% steadily over the past 10 years. Probably this number is an +% underestimation as a number of people opti not to register their +% disorder. +% } + +% \<<<{ % A large portion of the study materials we offer to students is % still written material. The authors believe that this will keep on % being so, even given the multimedia and AI options that have % become mainstream. Let's not go into this debate for now.\\ % However, written course texts cannot be but suboptimal for % students with reading disorders. -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % For small texts, reading them out loud and recording them using a % voice recorder to create an aid for our target group, is still -% feasible. We have taken that route at our institute for exam +% feasible. We have taken that in the past for exam % assignments. However, for bigger texts (like course syllabi) this -% is beyond the time a teacher can afford spending on this small a +% is beyond the time a professor can afford spending on this small a % group of students. Yes, economic laws also govern teaching! -% \end{spelchunk} +% } % % \subsection{State of the art} % % \subsubsection{In general} % -% \begin{spelchunk} +% \<<<{ % Therefore, reverting to readily available text-to-speech software % is an obvious choice. Nowadays, special software exists that % provides the functionality of reading out loud the contents of @@ -158,40 +173,40 @@ % 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 +% \<<<{ +% Currently, the \LaTeX{} project is investing in enabling \LaTeX{} to % partially automate the tagging of PDFs with the \texttt{tagpdf} % package~\cite{TAGPDF}, such that the user only has to do a minimal % job (adding tags for figures and tables). The goal is to maximize % the accessibility of \LaTeX-produced documents. -% \end{spelchunk} +% } % -% \begin{spelchunk} -% So all is well? Not quite. Though I'm confident that with enough -% time the community will solve the issue completely, there are +% \<<<{ +% So all is well? Not quite. Though we are 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.} @@ -202,13 +217,13 @@ % % \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 @@ -217,58 +232,49 @@ % 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 +% You have the choice to use local files or files that are made available on a +% server (as holds for this text; the audio files are on the CTAN servers).\\ +% How does \spelatex{} 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 +% will not be free, therefore (us) paying for them at document creation +% time, makes more sense to us than having our 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.} +% rather than a nice-to-have.} % \end{itemize} % -% \begin{spelchunk} -% Admittedly, in this first phase, using the \spelatex{} package -% causes a significant overhead in writing your text. Therefore we -% also provide you the \spelbox{} extension for the Org-mode -% \cite{ORGMODE} of \GNU{} Emacs \cite{EMACS}. To satisfy your -% curiosity: \spelbox{} stands for ``Speech-Enabled \LaTeX{} By -% Org-mode eXport''. -% \end{spelchunk} -% -% \begin{spelchunk} +% \<<<{ % Will \spelatex{} become obsolete in the future? % Undoubtedly so. But for the time being, it answers our desire to % provide our students with good audio support when studying their % engineering courses. That is now, not only in five years time. -% \end{spelchunk} +% } -% \begin{spelchunk} +% \<<<{ % We hope that you enjoy % using our software, or that --- if you are not pleased with it --- % it triggers you to give us feedback or to come up with a better @@ -278,32 +284,34 @@ % One of her suggestions (not to use big hyperlink-areas) was almost % instantly implemented and has been adopted as the standard way of % linking. -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % You are free to use our software but kindly ask you to provide a % mention ``The audio materials of this text have been prepared with -% \spelatex{}/\spelbox{}'' in the section treating copyrights, -% bibliographic data or any other spot that is suited. We'd also -% welcome a short mail of yours telling that you make use of the -% package. The pleasure of receiving such an e-mail makes our day. -% \end{spelchunk} -% -% \begin{spelchunk} +% \spelatex{}'' in the section treating copyrights, +% bibliographic data or any other spot of your text that is +% suited. We'd also welcome a short mail of yours telling that you +% make use of the package. The pleasure of receiving such an e-mail +% makes our day. +% } +% +% \<<<{ % You are free to modify this \LaTeX-package, keeping a reference to % our original package intact, provided that your package is subject % to the LPPL license, as is \spelatex{}. However, contributing to our -% package might be a better way to go, in order to bundle the efforts +% package or to the \LaTeX{} project in general, might be a better +% way to go, in order to bundle the efforts % for a better speech-enabled \LaTeX{}. -% \end{spelchunk} -% +% } +% \clearpage % \section{Introduction} % % \subsection{Target audience} -% \begin{spelchunk} +% \<<<{ % \spelatex{} is primarily intended for persons with a reading % disorder. This may be: -% \end{spelchunk} +% } % \begin{itemize} % \spelitem{persons suffering dyslexia} % \spelitem{visually impaired persons} @@ -318,177 +326,153 @@ % \end{itemize} % \end{itemize} % -% \begin{spelchunk} +% \<<<{ % But also people who want to multitask, e.g., gardening while % listening to a technical book, can benefit from % \spelatex{}.\footnote{Note that multitasking is not reserved for persons % without visual impairment. Also visually impaired persons can % benefit from listening to an audiobook while doing other -% things.} Personally, we often use \spelatex{} to proofread texts as we -% hear language errors more easily than we spot them while reading. -% \end{spelchunk} +% things.}\\ We often use \spelatex{} to proofread the texts we've +% written ourselves as we hear language errors more easily than we +% spot them while reading. +% } % % \subsection{The magic under the hood} % -% \subsubsection{The \spelbox{}-ecosystem} -% -% \begin{spelchunk} -% The \spelatex{}-package is one of the parts of the \spelbox{} -% ecosystem. It consists of three components: -% \end{spelchunk} -% \begin{itemize} -% \spelitem{An Org-mode exporter called \texttt{ox-spel} \cite{OXSPELATEX}} -% \spelitem{This \LaTeX{}-package \spelatex{} \cite{SPEL}} -% \spelitem{A script embeded in the Perl module \texttt{SpeL::Wizard} \cite{SPELWIZARD}} -% \end{itemize} -% % \subsubsection{The overall picture} % -% \begin{spelchunk} -% \spelatex{} equips the PDF that is generated by \LaTeX{} -% with hyperlinks to audio files that contain the spoken -% equivalent of the original text, equations, figures and tables -% \end{spelchunk} -% -% \begin{spelchunk} -% Let's look at this in detail in Fig.~\ref{fig:setup}. -% For now, ignore the two top boxes, and let's assume you are -% composing the file |text.tex| as your document. We will return -% to the two top boxes later. -% \end{spelchunk} -% -% \begin{spelchunk} +% \<<<{ +% \spelatex{} equips the PDF that is generated by \LaTeX{} +% with hyperlinks to audio files that contain the spoken +% equivalent of the original text, equations, figures and tables. +% } +% +% \<<<{ +% Let's start by considering the flow depicted in +% Fig.~\ref{fig:setup} at the top of the diagram. % By loading the |spel.sty| package in your source -% document, \LaTeX{} will produce a PDF file that references audio +% document (|text.tex|), \LaTeX{} will produce a PDF file that references audio % files that will be generated later (see below). In % addition, it generates text chunks (i.e. small portions of % your text) in separate files (|.tex|) and a spel index file % (|.spelidx|) referencing them in sequence. -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % Together with the |.aux|-file (needed by \spelatex{} for labels and % citations), these are the inputs to the \spelatex-engine (|spel-wizard.pl|) % that parses the text chunks, writes a full text version of them as % spel files (with extension |.spel|) and -% controls the text-to-speech engine to generate audio files of +% controls the text-to-speech engine to generate audio versions of % them.\footnote{In the figure, Ogg Vorbis has been chosen as % format, but this can be any audio format.} -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % To avoid excessive text to speech conversion (i.e. an expensive step) -% the \spelatex{} engine derives a finger print of them and compares it +% the \spelatex{} engine derives an MD5 fingerprint of them and compares it % to previously generated fingerprints for the chunk. If the -% finger print has changed, the audio file is overwritten (or +% fingerprint has changed, the audio file is overwritten (or % created the first time), otherwise it is left untouched. -% \end{spelchunk} +% } % -% \begin{spelchunk} -% As a cherry on top, the \spelatex-engine also creates a playlist, +% \<<<{ +% As a cherry on top, the \spelatex-engine also creates a top-level playlist, % such that you may use the audio files for a \POD{}cast-like % listening experience.\\ % Something that has not been indicated on the figure, is that for % reading out loud entire (sub)sections, the PDF-file also references % m3u playlists that gather all chunks belonging to the (sub)section. -% \end{spelchunk} +% } % -% \begin{figure}[p] +% \begin{figure} % \begin{spelchunk} % \begin{center} % \begin{tikzpicture} -% [scale=0.8,>=latex, -% doc/.style={rectangle,fill=black!10,align=center,minimum -% width=2cm,minimum height=2cm}, -% tool/.style={rectangle,draw,align=center}] -% \node [doc] (utext) at (0,9) {text.org\\\footnotesize(unprepped -% source)}; -% \node [tool] (instrument) at (0,6) {Org-mode exporter\\\footnotesize(\spelbox)}; -% \node [doc] (text) at (0,3) {text.tex\\\footnotesize(prepped source)}; -% \draw[->] (utext) -- (instrument); -% \draw[->] (instrument) -- (text); -% \node [doc] (R) at (-3,0) {spel.sty\\\footnotesize(package)}; -% \node [tool] (latex) at (0,0) {\LaTeX\\\footnotesize(compiler)}; -% \node [doc] (pdf) at (0,-3) {text.pdf\\\footnotesize(PDF with\\\footnotesize hyperlinks)}; -% \node [doc] (spelidx) at (6,-3) {text.spelidx\\\footnotesize(index file)}; -% \node [doc] (aux) at (9,-3) {text.aux\\\footnotesize(auxiliary file)}; -% \node [doc] (files) at (3,-3) {*.tex\\\footnotesize(text chunks)}; -% \draw[->] (text) -- (latex); -% \draw[->,dotted] (text) -- (R); -% \draw[->,dotted] (spelidx) -- (files); -% \draw[->] (R) -- (latex); -% \draw[->] (latex) -- (pdf); -% \draw[->] (latex) edge[out=0,in=90] (spelidx); -% \draw[->] (latex) edge[out=10,in=90] (aux); -% \draw[->] (latex) edge[out=-10,in=90] (files); -% \node [tool] (engine) at (6,-6) {\spelpl{}\\ -% \footnotesize(\spelatex{} engine)}; -% \node [tool] (t2s) at (1.5,-6) {text-to-speech\\engine}; -% \draw[->] (files) -- (engine); -% \draw[->] (spelidx) -- (engine); -% \draw[->] (aux) -- (engine); -% \node[doc] (ogg) at (0,-9) {*.ogg\\\footnotesize(audio files)}; -% \node[doc] (spel) at (3,-9) {*.spel\\\footnotesize(spel files)}; -% \node[doc] (m3u) at (6,-9) {text.m3u\\\footnotesize(playlist)}; -% \node[doc] (md5) at (9,-9) {*.md5\\\footnotesize(fingerprints)}; -% \draw[->] (engine) -- (spel); -% \draw[->] (engine) -- (m3u); -% \draw[<->] (engine) -- (md5); -% \draw[->,dotted] (pdf) edge[out=-115,in=115] (ogg); -% \draw[->,dotted] (m3u) edge[out=-125,in=-55] (ogg); -% \draw[->,dashed] (engine) -- (t2s); -% \draw[->] (spel) -- (t2s); -% \draw[->] (t2s) -- (ogg); +% [scale=0.8,>=latex, +% doc/.style={rectangle,fill=black!10,align=center,minimum +% width=2cm,minimum height=2cm}, +% tool/.style={rectangle,draw,align=center}] +% \node [doc] (text) at (0,3) {text.tex\\\footnotesize(source file)}; +% \node [doc] (R) at (-3,0) {spel.sty\\\footnotesize(package)}; +% \node [tool] (latex) at (0,0) {\LaTeX\\\footnotesize(compiler)}; +% \node [doc] (pdf) at (0,-3) {text.pdf\\\footnotesize(PDF with\\\footnotesize hyperlinks)}; +% \node [doc] (spelidx) at (6,-3) {text.spelidx\\\footnotesize(index file)}; +% \node [doc] (aux) at (9,-3) {text.aux\\\footnotesize(auxiliary file)}; +% \node [doc] (files) at (3,-3) {*.tex\\\footnotesize(text chunks)}; +% \draw[->] (text) -- (latex); +% \draw[->,dotted] (text) -- (R); +% \draw[->,dotted] (spelidx) -- (files); +% \draw[->] (R) -- (latex); +% \draw[->] (latex) -- (pdf); +% \draw[->] (latex) edge[out=0,in=90] (spelidx); +% \draw[->] (latex) edge[out=10,in=90] (aux); +% \draw[->] (latex) edge[out=-10,in=90] (files); +% \node [tool] (engine) at (6,-6) {\spelpl{}\\ +% \footnotesize(\spelatex{} engine)}; +% \node [tool] (t2s) at (1.5,-6) {text-to-speech\\engine}; +% \draw[->] (files) -- (engine); +% \draw[->] (spelidx) -- (engine); +% \draw[->] (aux) -- (engine); +% \node[doc] (ogg) at (0,-9) {*.ogg\\\footnotesize(audio files)}; +% \node[doc] (spel) at (3,-9) {*.spel\\\footnotesize(spel files)}; +% \node[doc] (m3u) at (6,-9) {text.m3u\\\footnotesize(playlist)}; +% \node[doc] (md5) at (9,-9) {*.md5\\\footnotesize(fingerprints)}; +% \draw[->] (engine) -- (spel); +% \draw[->] (engine) -- (m3u); +% \draw[<->] (engine) -- (md5); +% \draw[->,dotted] (pdf) edge[out=-115,in=115] (ogg); +% \draw[->,dotted] (m3u) edge[out=-125,in=-55] (ogg); +% \draw[->,dashed] (engine) -- (t2s); +% \draw[->] (spel) -- (t2s); +% \draw[->] (t2s) -- (ogg); % \end{tikzpicture} -% \end{center} -% \end{spelchunk} -% \begin{spelchunkad} -% The easiest flow is to start from the top box, which represents -% an org file that describes your text. We call this the -% unprepped source. Read the Orgmode -% documentation on \LaTeX{} and \spelatex{}-exporting to get to know -% the format. The Orgmode \spelatex{} exporter, creates a fully -% equiped \LaTeX{} file of your text. We call this the prepped source. You can -% also start by composing this file yourself. -% If you prepped source file uses the \spelatex{} style file, than -% your compiler will generate a PDF file with hyperlinks, a -% dot aawks-file and a dot spellindex-file together with a directory full of -% dot tex files containing the text chunks to be processed by the -% \spelpl-engine. This is a perl script that converts the chunks into -% plain text readable spel files. The script is called spel dash -% wizard dot pl. It also creates a playlist and audio files using a -% text-to-speech engine. In this case, these are -% Ogg-Vorbis files. To avoid having to call the text-to-speech -% engine too frequently (which may incur costs), MD5-fingerprints -% are used such that chunks that have been generated before and -% are unchanged, can be reused. The end result is a PDF file that -% references the audio files. -% \end{spelchunkad} -% \caption{Basic tool setup of \spelbox{} of which the \spelatex{} package -% is an integral part; filled boxes indicate files, -% outlined boxes indicate tools; solid lines indicates use or -% creation of files, dotted lines indicate references, dashed lines -% indicate a control relationship.} -% \label{fig:setup} +% \end{center} +% \end{spelchunk} +% \begin{spelchunkad} +% If you load the \spelatex{} style file in your source file (at the +% top of the figure) and prepare your source file according to the +% instructions in this manual, than +% your compiler will generate a PDF file with hyperlinks, a +% dot aawks-file and a dot spellindex-file together with a directory full of +% dot tex files containing the text chunks to be processed by the +% \spelpl-engine. This is a perl script that converts the chunks into +% plain text readable spel files. The script is called spel dash +% wizard dot pl. It also creates a playlist and audio files using a +% text-to-speech engine. In this case, these are +% Ogg-Vorbis files. To avoid having to call the text-to-speech +% engine too frequently (which may incur costs), MD5 fingerprints +% are used such that chunks that have been generated before and +% are unchanged, can be reused. The end result is a PDF file that +% references the audio files. +% \end{spelchunkad} +% \caption{Basic tool setup of the \spelatex{} package; filled boxes indicate +% files, outlined boxes indicate tools; solid lines indicates use or +% creation of files, dotted lines indicate references, dashed lines +% indicate a control relationship.} +% \label{fig:setup} % \end{figure} % -% \begin{spelchunk} +% \<<<{ % You might wonder: where are the links? Well, there are three % variants: -% \end{spelchunk} +% } % \begin{itemize} % \spelitem{\emph{area links}, which are almost exclusively % used for equations, tables or figures. These links make an entire % rectangle active, linking to the corresponding audio file.} % \spelitem{\emph{group links}, indicated by small right-pointing -% triangles next to section headers. These cause all blocks in the -% section to be read one by one.} -% \spelitem{\emph{hidden links}, wich are, as the name suggests, -% hidden to avoid visual disturbance of the text; every -% paragraph, footnote and list is activated by a link on the -% whitespace before the first line of the chunk. Try it! Once you +% triangles next to section headers (on the far right). These cause all +% blocks in the section to be read one by one.\\ +% In case you specify the +% package option \texttt{markervisibility=none} these triangles will become +% invisible. However, the clickable areay still exists. Try!} +% \spelitem{\emph{chunk links}, before every +% paragraph, footnote or list, a small triangle indicates a clickable link.\\ +% If you activate the package option \texttt{markervisibility=onlygroups}, they will +% become invisible, but still clickable. 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 +% easily. Not using the full paragraph as an active % region, allows existing hyperlinks (like for citations, references % or URLs) to still function.} % \end{itemize} @@ -504,7 +488,7 @@ % \spelmacad{thanks}{the thanks macro} % \spelmacad{item}{the item macro} % \spelmacad{spelitem}{the spelitem macro} -% \begin{spelchunk} +% \<<<{ % Generating the text chunks to be read out loud requires us to use % special \LaTeX-macros. For all pieces of text that are within % an existing macro (e.g. |\title|, |\author|, |\section|, @@ -512,9 +496,9 @@ % redefined by the \spelatex{}-package to % execute the magic without any further hassle.\\ % We call these \LaTeX-fragments \emph{implicit spelchunks}.% -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % However, not all \LaTeX-constructs can be dealt with in an % automatic way. This is true for any |\item| you put inside a list. % You need to replace that with a |\spelitem| that takes the text @@ -524,10 +508,10 @@ % spelchunks}. They should have been implicit, but we could not get % that to work without problems. Therefore you need to mark them % explicitly as |\spelitem| constructs. -% \end{spelchunk} +% } % % \subsubsection{Explicit spelchunks} -% \begin{spelchunk} +% \<<<{ % One would hope that displaymath environments are also implicit % spelchunks. However, overriding environments in \LaTeX{} is a tricky % business. In view of this, the \spelatex{} package keeps away from @@ -540,12 +524,12 @@ % will have to provide a text description for tables and figures % manually, using a subsequence |spelchunkad| % environment (the suffix ad stands for \emph{audio description}). -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % To keep the terminology clear, we label them as automatic -% and manual spelchunks respectively: -% \end{spelchunk} +% and manual explicit spelchunks respectively: +% } % \begin{itemize} % \spelitem{automatic: \texttt{equation}, \texttt{eqnarray}, % \texttt{gather}, \texttt{align}, \texttt{alignat}, \ldots} @@ -553,25 +537,26 @@ % \texttt{tikzpicture}, \ldots} % \end{itemize} % -% \begin{spelchunk} +% \<<<{ % The similarity between both categories is that you both embed them % in a |spelchunk| environment, but that you provide the manual % textual description using a |spelchunkad| environment right after -% the chunk: in this way, the |spelchunkad| environment provides an +% the chunk for the manual ones: in this way, the |spelchunkad| environment provides an % alternative text for the chunk. Note that this way of working also -% enables you to provide an overriding text for an equation, if you -% think that \spelpl{} is doing a bad job. You do me a favor if -% you submit this subpar behavior as a bug report to me! -% \end{spelchunk} +% enables you to provide an overriding text for an automatic spelchunk, +% e.g., an equation, if you +% think that \spelpl{} is doing a bad job. You do us a favor if +% you submit this subpar behavior as a bug report to us! +% } % -% \begin{spelchunk} +% \<<<{ % It is worthwile to make good descriptions for a figure or a % table. It's here that you can create true added value to your % manuscript, even for readers without impairment! -% \end{spelchunk} +% } % % \subsubsection{Paragraphs} -% \begin{spelchunk} +% \<<<{ % However, there is the elephant in the room that we did not yet % talk about, the paragraph. Indeed, it is desirable to split plain % text according to the paragraphs in the document. Alas, paragraphs @@ -581,63 +566,40 @@ % explicit spelchunks and need to be embedded % in |spelchunk| environments. This environment will cause its % contents to be hyperlinked to a separate piece of audio. -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % Encasing all your paragraphs with |spelchunk| environments % manually is a pain. There is a reason why in \LaTeX{} % paragraphs can be created by a double newline: convenience. % The |spelchunk|-environment encasing ruins this totally! -% \end{spelchunk} -% -% \subsubsection{Emacs Orgmode to the rescue!} -% \begin{spelchunk} -% However, we provide an exporter for the Org-mode \cite{ORGMODE} of -% Emacs \cite{EMACS}, such -% that you can prepare your manuscript in Org-mode and not worry -% about all these exlicit tricks with |spelchunk| and |spelitem| -% constructs. -% \end{spelchunk} -% -% \begin{spelchunk} -% This brings us to the two top boxes in the diagram of -% Fig.~\ref{fig:setup}. If you prepare your manuscript in Org-mode, -% and use the Org-mode exporter, you don't have to worry about explicit -% spelchunks, or defunct implicit spelchunks. Therefore, we encourage -% you to use Emacs as your editor. The learning -% curve is steep, but the rewards regarding ease-of-use are huge. -% In that way, you can focus on providing textual descriptions for -% the non textual portions of your manuscript, e.g. giving a good -% description of a graph. -% \end{spelchunk} -% -% \begin{spelchunk} -% Note that this very document has been prepared manually to make it -% independent of Org-mode. It also shows that if you don't -% want to use Emacs and Org-mode, you will suffer some considerable -% pain in equipping your manuscript with an overload of |spelchunk| -% environments. We have only one advice: don't use the \spelatex{} -% outside \spelbox{}. Outside a proper boxed confinement, -% spells easily become curses\ldots -% \end{spelchunk} +% } +% \spelmacad{<<<}{the shorthand macro} +% \<<<{ +% To ease the pain and in order to avoid the visual intrusiveness of the +% spelchunk environments, you can also use the \texttt{\textbackslash{}<<<\{\}} command to +% encase your paragraphs. In some cases the \texttt{\textbackslash{}<<<\{\}} +% command will not work, e.g., if there is a |Verbatim| environment +% inside. In that case you must use the |spelchunk| environment directly. +% } % % \subsection{Extra math commands} % -% \begin{spelchunk} +% \<<<{ % Some of the ways to specify mathematical expressions in \LaTeX{} is % very liberal, what makes converting them to text quite % difficult. Therefore, we also provide some % extra constructs that make life easier for both parties: you as a % user and \spelpl{} as a parser. -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % An example of this are sets. We provide two commands to define a % set. As we want these commands to blend in with general \LaTeX{}, % we did not equip them with a prefix |spel|. Therefore, we made % activating them conditional to specifying the package option % |extramath|. -% \end{spelchunk} +% } % \begin{description} % \spelitem[\texttt{\textbackslash{}setenum}]{a command to define a set % that consists of comma or semicolon separated elements} @@ -648,14 +610,11 @@ % % \subsection{Added value} % -% \begin{spelchunk} +% \<<<{ % Why would it make sense to use \spelatex? We think there are many % selling points. We can mention a few: -% \end{spelchunk} +% } % \begin{description} -% \spelitem[Minimal overhead]{ -% Preparing a \LaTeX{} manuscript for use with \spelatex{} requires a -% minimal amount of work, if you are using Org-mode in Emacs.} % \spelitem[Free for the content provider]{ % If you are using a freeware text-to-speech engine (like for % example festival \cite{FESTIVAL} or balabolka \cite{BALABOLKA}) @@ -664,8 +623,9 @@ % the effort of preparing your manuscript. There are no license % costs involved.\\ % You could also consider to use an online paying text-to-speech -% service. As an example, We incorporated a connection to Amazon's -% Polly \cite{AWSPOLLY}.\\ +% service. As an example, we incorporated a connection to Amazon's +% Polly \cite{AWSPOLLY}. We admit, it's not free, but it doesn't +% cost an arm and a leg either.\\ % In addition, if your user has a better-quality (maybe % commercial) text-to-speech system, he/she can reconvert the text % files him-/herself, equiping your document with a voice they @@ -675,72 +635,71 @@ % \spelitem[Free for your audience]{ % In addition, the user of your audio-enabled document doesn't % need to buy a license for text-to-speech software. Only a PDF-viewer -% and standard audio-player program are required.} +% and a standard audio-player program are required.} % \spelitem[Math capable]{ -% Try some of the equations in this manuscript. We are quite -% confident you'll be convinced fairly soon.} +% Try some of the equations in this manuscript in +% section~\ref{sec:demo}. We are quite confident you'll be +% convinced fairly soon.} % \end{description} % % \section{Installation} % % \subsection{The \spelatex{} package} -% \begin{spelchunk} +% \<<<{ % If you are a package manager then you'll know how to % prepare an installation package for \spelatex. -% \end{spelchunk} +% } % -% \begin{spelchunk} -% If you are a normal user then you have two options. First, -% check if there is a package that your favorite \LaTeX{} -% distributor has prepared for you. Most of the major distributions -% (like e.g. \TexLive{} or \MikTeX{}) do so.\\ -% Second, grab the TDS package -% from \CTAN{} \cite{CTAN} (spel.TDS.zip) and unzip it somewhere in your -% own TDS tree, regenerate your filename database and off you go. -% In any case, make sure that \LaTeX{} finds the file |spel.sty|. -% \end{spelchunk} +% \<<<{ +% If you are a normal user, 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.\\ +% The fallback option is to grab the |spelatex.sty| file from CTAN +% and put it in our \TeX{} search path. +% } % -% \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} +% them. The ones used are: |expl3|, |hyperref|, |xcolor|, |ifthen|, |verbatim|, +% |fancyvrb|, |newfile|, |rotating|, |babel|, |kvoptions| and |xkeyval|. +% } % % \subsection{The \spelpl{} speech generator} % % \subsubsection{The script} -% \begin{spelchunk} +% \<<<{ % You can install the wizard assuming you have a working Perl % interpreter installed. Assuming you're on \GNU/Linux or MAC, you % should be able to find an installation package using the package % manager for your distribution. If you are on MS-Windows, look for % Strawberry perl or ActiveState perl. -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % The only thing to do is to install the |SpeL::Wizard| % module. You can do this with the perl pacakge manager for your % interpreter. -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % Open a terminal or command window, and then enter on the % command line (the dollar represents your prompt): -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % On \GNU/Linux and MAC: |$ cpanm SpeL::Wizard|\\ -% On Strawberry perl: |$ cpan SpeL::Wizard|\\ -% On ActiveState perl: |$ ppm install SpeL-Wizard| -% \end{spelchunk} +% For Strawberry perl: |$ cpan SpeL::Wizard|\\ +% For ActiveState perl: |$ ppm install SpeL-Wizard| +% } % -% \begin{spelchunk} +% \<<<{ % The script \spelpl{} will be installed on your system. Make sure % it is on your search path. -% \end{spelchunk} +% } % % \subsubsection{The configuration file} +% % \begin{spelchunk} % Finally, you need to provide \spelpl{} with an appropriate % config-file, named |tts.conf| that sets up the text-to-speech conversion. @@ -773,12 +732,12 @@ % \end{Verbatim} % \end{spelchunk} % -% \begin{spelchunk} +% \<<<{ % The tts configuration parameter defines the speech engine to use. % The languagetags section defines how the babel languages are mapped to % internationalization codes (also known as locales). % The voices section specifies what voice to use for a specific language. -% \end{spelchunk} +% } % % \begin{spelchunk} % An environment variable can specify where your config file is @@ -789,12 +748,12 @@ % \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 +% |.spel_wizard| of your home-folder (or |%userprofile%| on % MS-Windows), or it will take the default that came with the % |SpeL::Wizard| module. % \end{spelchunk} % -% \begin{spelchunk} +% \<<<{ % Be aware that you need to install your text-to-speech tool yourself % according to the documentation provided by the tool provider. % In addition, make sure it the executable is in your search path. In @@ -802,79 +761,78 @@ % will need to get an account on their cloud platform and setup % credentials and whatever is needed to get going. Providing % assistance for this is beyond the aim of this manual. -% \end{spelchunk} +% } % % \subsection{The PDF viewer} % -% \begin{spelchunk} -% You need to make sure you have a PDF-viewer that supports links -% containing 'run' tags. E.g., xpdf \cite{XPDF} does not, evince -% \cite{EVINCE} complains about security risks, but okular -% \cite{OKULAR} and Adobe Reader \cite{ADOBEREADER} do. So does -% PDF-XChange Viewer \cite{PDFXCHANGE}. -% \end{spelchunk} +% \<<<{ +% You need to make sure you have a PDF-viewer that supports file links +% E.g., xpdf \cite{XPDF} does not, but evince \cite{EVINCE}, okular +% \cite{OKULAR} and Adobe Reader \cite{ADOBEREADER} do. +% } % % \subsection{The media player} -% \begin{spelchunk} +% \<<<{ % When clicking a \spelatex-enabled item in your PDF-file, your media % player is started to play the |.ogg| or |.m3u|-file. On GNU/Linux % most media players work fine (SoX, totem, vlc, \ldots). -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % On windows, we recommend using vlc. It works out of the box. % When usign the stock Windows Media Player, you will need to add % every folder that contains a PDF you'd like to have read, to your % Media Player library. Search the internet to find instructions on % that and be prepared: in line with Microsoft's standard practice it % is well hidden in the interface. -% \end{spelchunk} +% } +% +% \<<<{ +% If you gave the |server| option to the \spelatex{} package, then your +% favorite webbrowser will be started to download and play the file. +% If you move it out of your way, you can avoid that it jumps in front of +% your text every time again. +% } % % \section{Usage} % % \subsection{Preparing your document source} % \begin{spelchunk} % Using the \spelatex{} package is very simple. Just load the package's -% style file using an appropriate |\usepackage{spel}|. +% style file using an appropriate |\usepackage{spelatex}|. % \end{spelchunk} % -% \begin{spelchunk} -% In case you are not using Org-mode, there are $5$ things to do: -% \end{spelchunk} +% \<<<{ +% There are $5$ things to do: +% } % \begin{enumerate} -% \spelitem{Treat the defunct implicit spelchunks} -% \spelitem{Treat the explicit spelchunks} -% \spelitem{Manually provide text to read when needed} +% \spelitem{Treat the defunct implicit spelchunks.} +% \spelitem{Treat the explicit spelchunks.} +% \spelitem{Manually provide text to read when needed.} % \spelitem{Provide audiodescriptions or preprocessing instructions -% for your typesetting macros} +% for your typesetting macros.} % \spelitem{Provide audiodescriptions or preprocessing instructions -% for your typesetting environments} +% for your typesetting environments.} % \end{enumerate} % -% \begin{spelchunk} -% Steps 1 and 2 can be done automatically for you by using Org-mode in -% Emacs and using the proper |spel| exporter. -% Steps 3, 4 and 5 are up to you. In this section, we assume you are -% executing all 5 steps manually and therefore, we will explain all -% required macros. -% \end{spelchunk} +% We will now explain all required macros. % % \subsubsection{Treat the implicit spelchunks} -% \begin{spelchunk} +% \<<<{ % The texts of chapter, (sub)section titles, a.s.o. will be formatted % automatically such that they are hyperlinked to the appropriate % audio file. Therefore, this step was not mentioned above. It is done % automatically for you by using the \spelatex{} package. -% \end{spelchunk} +% } % -% \begin{spelchunk} +% \<<<{ % You only need to cover your \emph{defunct implicit spelchunks}:\\ % \DescribeMacro{\spelitem} % Use this macro instead of the \texttt{\textbackslash{}item} macro to make % sure your list environments are converted to speech chunks % appropriately. -% \end{spelchunk} +% } % % \begin{spelchunk} % Example: @@ -897,35 +855,36 @@ % \spelitem[orange]{an orange round fruit} % \end{description} % \end{Verbatim} -% Note that the spel exporter in Org-mode takes care of all this -% boilerplate work. % \end{spelchunk} % % \subsubsection{Treat the explicit spelchunks} -% -% \begin{spelchunk} +% \label{sec:explicitspelchunks} +% \<<<{ % \DescribeEnv{spelchunk} % Use this environment to embed the chunks of text in that you want % to generate audio for. In case the content is an equation, a % figure or a table, we recommend specifying |arealink| as the % optional argument to the |spelchunk| environment. It makes the % entire equation an active hyperlink. -% \end{spelchunk} +% Note that you cannot specify an |arealink| when the area to be covered is +% vertical-mode object. In common language: put your |arealink| |spelchunk| +% environments inside a |center| environment and not the other way around. +% } % -% \begin{spelchunk} +% \<<<{ % Example:\\ -% {\footnotesize (note: the example below is not \spelatex{}-enabled because it -% generates internal package problems)} -% \end{spelchunk} +% {\footnotesize (note: the example below is not \spelatex{}-enabled +% in this manual because it generates internal package problems)} +% } % \begin{Verbatim} % \begin{spelchunk} -% An orderinary paragraph must be embedded in this environment. +% An ordinary paragraph must be embedded in this environment. % The same holds for equations! However, then we recommend using % the |arealink| option, as that makes the full area of the % equation clickable and avoids an empty white line before the % equation. % \end{spelchunk} -% \begin{spelchunk}[arealink] +% \begin{spelchunk[arealink] % \begin{align} % E &= m c^2\\ % e^{j\pi} &= -1 @@ -952,12 +911,12 @@ % % \begin{spelchunk} % Example:\\ -% {\footnotesize (note: the example below is not \spelatex{}-enabled because it +% {\footnotesize (note: the example below is again not \spelatex{}-enabled because it % generates internal package problems)} % \end{spelchunk} % \begin{Verbatim} % \begin{spelchunk} -% An orderinary paragraph must be embedded in this environment. +% An ordinary paragraph must be embedded in this environment. % \end{spelchunk} % \begin{spelchunkad} % Do not forget to embed ordinary paragraphs in this environment. @@ -975,7 +934,7 @@ % % \begin{spelchunk} % Example:\\ -% {\footnotesize (note: the example below is not \spelatex{}-enabled because it +% {\footnotesize (note: the example below is for a third time not \spelatex{}-enabled because it % generates internal package problems)} % \end{spelchunk} % \begin{Verbatim} @@ -989,6 +948,39 @@ % \end{spelchunkad} % \end{Verbatim} % +% \subsubsection{Use the shorthand \texttt{\textbackslash <<<}-macro} +% +% \<<<{ +% \DescribeMacro{\<<<} +% This macro takes the text to be read-out loud as an +% argument. It is a shorthand for the |spelchunk| +% environment. Options you would have given to the |spelchunk| +% environment can be given as an optional argument to this macro. +% } +% +% \<<<{ +% Retaking the example of section~\ref{sec:explicitspelchunks}, +% using the shorthand, we obtain:\\ +% {\footnotesize (note: the example below is once again not \spelatex{}-enabled +% in this manual because it generates internal package problems)} +% } +% \begin{Verbatim} +% \<<<{ +% An ordinary paragraph must be embedded in this macro. +% 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. +% } +% \<<<[arealink]{ +% \begin{align} +% E &= m c^2\\ +% e^{j\pi} &= -1 +% \end{align} +% } +% \end{Verbatim} +% +% % \subsubsection{Provide descriptions for typesetting macros} % % \DescribeMacro{\spelmacad} @@ -1127,13 +1119,13 @@ % % \DescribeMacro{\setdesc} % \begin{spelchunk} -% This macro typesets an enumeration set and makes sure \spelpl{} +% This macro typesets a definition set and makes sure \spelpl{} % can read it properly. % \end{spelchunk} % \begin{spelchunk} % \begin{Verbatim} % \begin{equation} -% P = \setdesc{ n \in N \mid n \text{~is prime} } +% P = \setdesc{ n \in \mathbb{N} \mid n \text{~is prime} } % \end{equation} % \end{Verbatim} % \end{spelchunk} @@ -1181,10 +1173,13 @@ % \begin{VerbatimOut}[gobble=4]{Example/example.tex} % \documentclass{article} % -% \usepackage[dutch,english]{babel} % load babel before spel to avoid +% \usepackage[dutch,english]{babel} % load babel before spelatex to avoid % % option clash! % \selectlanguage{english} -% \usepackage[format=ogg]{spelatex} +% \usepackage[format=ogg, +% server=https://ctan.org/tex-archive/macros/latex/contrib/spelatex/Example +% ] +% {spelatex} % % \newrobustcmd\CTAN{CTAN} % \spelmacad{CTAN}{see-tan} @@ -1193,7 +1188,7 @@ % % \title{\spelatex{} Example} % \author{Walter Daems and Paul Levrie} -% \date{2011/04/12} +% \date{2024/09/09} % \setlength\parindent{0em} % \setlength\parskip{1ex} % @@ -1203,10 +1198,10 @@ % % \section{Introduction} % -% \begin{spelchunk} -% This file is just a simple showcase of the features of \spelatex. +% \<<<{ +% This file is just a simple showcase of the features of \spelatex{}. % Below, you'll find examples of: -% \end{spelchunk} +% } % % \begin{itemize} % \spelitem{a simple equation} @@ -1215,20 +1210,25 @@ % % \section{A simple equation} % \label{eqn:simple} -% \begin{spelchunk} +% \<<<{ % Consider the following simple definition of a polynomial function and % check its spoken version by clicking on it. -% \end{spelchunk} -% \begin{spelchunk}[arealink] +% } +% \<<<[arealink]{ % \begin{equation} -% f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 23 +% f(x) = x^{5}- x^4 + 7 x^3 + 3 x^2 - 8 x + 25 % \end{equation} -% \end{spelchunk} -% \begin{spelchunk} +% } +% \<<<{ % This seems a simple equation, however, it is not so straightforward % for an automated reader, to read it correctly. -% \end{spelchunk} +% } % +% \section{Remark} +% \<<<{ +% Instead of the \texttt{\textbackslash{}<<<} macro, one can also use the +% spelchunk environment. We did this in the next sections. +% } % \section{A more complex equation} % \newcommand\xx[2]{\ensuremath{#1_{#2}}} % \spelmacad{xx}[2]{#1 #2} @@ -1259,8 +1259,9 @@ % y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t) % \] % \end{spelchunk} - +% % \selectlanguage{english} +% % \section{And some extras} % \subsection{Citations} % \begin{spelchunk} @@ -1274,6 +1275,8 @@ % section~\ref{eqn:complex}. % \end{spelchunk} % +% \selectlanguage{dutch} +% % \bibliographystyle{alpha} % % \begin{thebibliography}{99} @@ -1292,10 +1295,11 @@ % % \end{document} % \end{VerbatimOut} +% \footnotesize % \VerbatimInput[frame=lines,numbers=left,gobble=0]{Example/example.tex} -% +% \normalsize % \section{Demo} -% +% \label{sec:demo} % \newcommand\rd[1]{\ensuremath{\mathrm{d}#1}} % \spelmacad{rd}[1]{d of #1} % \newcommand\xx[2]{\ensuremath{#1_{#2}}} @@ -1369,14 +1373,14 @@ % \begin{spelchunk} % Euler's identity: % \end{spelchunk} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{equation} % e^{j \pi} + 1 = 0 % \end{equation} % \end{spelchunk} % % \subsubsection{A rather well-known definite integral} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{equation} % \int_{-\infty}^\infty e^{-x^2}\,\rd{x} = \sqrt{\pi} % \end{equation} @@ -1391,7 +1395,7 @@ % \begin{spelchunk}[arealink] % \begin{align} % P &= \setenum{ 2, 3, 5, 7, 11, 13, \ldots }\\ -% P &= \setdesc{ n \in N \mid n \text{~is prime}} +% P &= \setdesc{ n \in \mathbb{N} \mid n \text{~is prime}} % \end{align} % \end{spelchunk} % @@ -1429,43 +1433,44 @@ % \end{spelchunk} % \begin{figure}[h] % \setlength{\unitlength}{4mm} -% \begin{spelchunk} % \begin{center} +% \begin{spelchunk}[arealink] % \begin{picture}(24,2) % \put(0,0.8){$x[n]$} % \put(2,1){\vector(1,0){3}} % \put(5,0){\framebox(5,2){$H(z)$}} % \put(10,1){\vector(1,0){3}} -% \put(13,0){\framebox(5,2){$G(z) \ast F(z)$}} +% \put(13,0){\framebox(5,2){$G(z) \cdot F(z)$}} % \put(18,1){\vector(1,0){3}} % \put(22,0.8){$y[n]$} % \end{picture} +% \end{spelchunk} % \end{center} -% \end{spelchunk} % \begin{spelchunkad} % The discrete-time input signal x is fed through a filter H of % z. The intermediate output signal of the filter H of z is fed into -% another filter whose transfer function is the convolution of G of -% z and F of z. This resuspel in the discrete-time output signal y. +% another filter whose transfer function is the product of G of +% z and F of z. This results in the discrete-time output signal y. % \end{spelchunkad} % \caption{A block diagram of the filter system} % \label{fig:blockdiagram} % \end{figure} % % \subsubsection{Tables} -% \begin{spelchunk} -% \begin{center} +% \<<<{Tables can also be equiped with a sensible description:} +% \begin{center} +% \begin{spelchunk}[arealink] % \begin{tabular}{lcc} % Food & Sweet & Bitter \\ % \hline -% apple & $\bullet$ & \\ +% apples & $\bullet$ & \\ % unsweetened coffee & & $\bullet$\\ % cake & $\bullet$ & \\ % chocolate & $\bullet$ & $\bullet$ \\ % \hline % \end{tabular} -% \end{center} -% \end{spelchunk} +% \end{spelchunk} +% \end{center} % \begin{spelchunkad} % This table indicates the sweetness and bitterness for several food % products. @@ -1481,50 +1486,46 @@ % to $\tan \alpha = -\frac{t}{2}$, the equation of the reflected % ray is given by % \end{spelchunk} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{equation} % y-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t) % \end{equation} % \end{spelchunk} -% % \begin{spelchunk} % The $x$-coordinate of the point of intersection of the reflected ray % with a fixed line $y=u$ satisfies: % \end{spelchunk} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \begin{equation} % u-9+\frac{t^2}{4} = -\frac{4t}{4-t^2} \cdot (x-t) % \label{eqn:refray} % \end{equation} % \end{spelchunk} -% % \begin{spelchunk} % We calculate the minimal value of this $x$ for varying $t$, by % differentiating (\ref{eqn:refray}) with respect to $t$ and assuming % that $\frac{\rd{x}}{\rd{t}}=0$: % \end{spelchunk} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \[ % \frac{t}{2} = -\frac{4(4+t^2)}{(4-t^2)^2} (x-t) - % \frac{4t}{4-t^2} \cdot (-1) \ \ \ \Leftrightarrow \ \ \ x= % 3\frac{t}{2}-\frac{t^3}{8} % \] % \end{spelchunk} -% % \begin{spelchunk} % Inserting in the equation containing $u$ gives us the relation % between $t$ and $u$: % \end{spelchunk} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \[ % u = 9- 3 \frac{t^2}{4} % \] % \end{spelchunk} -% -% \begin{spelchunk} +%% \begin{spelchunk} % This leads to a system of parametric equations for the caustic: % \end{spelchunk} -% \begin{spelchunk} +% \begin{spelchunk}[arealink] % \[ % \left\{\begin{array}{l} % x = 3\frac{t}{2}-\frac{t^3}{8} \\[0.3cm] @@ -1537,7 +1538,6 @@ % \end{array} \right. % \] % \end{spelchunk} -% % \begin{spelchunk} % It is now easy to eliminate the parameter $t$. As you can see, $t % = \frac{6 x}{y}$. Inserting into the equation for $y$ gives us the @@ -1583,6 +1583,7 @@ \RequirePackage{hyperref} \RequirePackage{xcolor} \RequirePackage{ifthen} +\RequirePackage{verbatim} \RequirePackage{fancyvrb} \RequirePackage{newfile} \RequirePackage{rotating} @@ -1602,7 +1603,6 @@ urlcolor=black} \RequirePackage{kvoptions} \RequirePackage{xkeyval} -\RequirePackage{marginnote} % \end{macrocode} % % \subsection{Options} @@ -1613,9 +1613,10 @@ prefix=spel@ } \DeclareStringOption[ogg]{format} +\DeclareStringOption[local]{server} +\DeclareStringOption[full]{markervisibility} \DeclareBoolOption[false]{disabled} \DeclareBoolOption[false]{extramath} -\DeclareBoolOption[false]{propermath} \ProcessKeyvalOptions* % \end{macrocode} % @@ -1627,12 +1628,6 @@ \DeclareRobustCommand{\spelatex}{S\kern-0.3ex\raisebox{-0.1ex}{\rotatebox{-15}{p}}\kern-0.25ex\raisebox{0.1ex}{\rotatebox{10}{e}}\kern-0.1ex\LaTeX} % \end{macrocode} % \end{macro} -% \begin{macro}{\spelbox} -% This is the official \spelbox{} logo. -% \begin{macrocode} -\DeclareRobustCommand{\spelbox}{S\kern-0.3ex\raisebox{-0.1ex}{\rotatebox{-15}{p}}\kern-0.25ex\raisebox{0.1ex}{\rotatebox{10}{e}}\kern-0.1exLbo\raisebox{-0.2ex}{x}} -% \end{macrocode} -% \end{macro} % \begin{macro}{\spelpl} % This is the official \spelpl{} logo. % \begin{macrocode} @@ -1674,6 +1669,10 @@ \addtostream{spelidx}{format|\spel@format} \addtostream{spelidx}{audiodir|\audiodir} \addtostream{spelidx}{chunkdir|\chunkdir} +\addtostream{spelidx}{server|\spel@server} +\ExplSyntaxOn +\newcommand\linksdir{\str_if_eq:VnTF{\spel@server}{local}{./\audiodir}{\spel@server/\audiodir}} +\ExplSyntaxOff % \end{macrocode} % % To ease writing to the speech index stream, we define a |\spelidxwrite| @@ -1774,7 +1773,29 @@ \AddBabelHook{informspel}{write}{\spel@idxwrite{language}{\languagename}} \EnableBabelHook{informspel} % \end{macrocode} -% +% +% \subsection{Setting up the visibility} +% +% \begin{macrocode} +\ExplSyntaxOn +\definecolor{faintgray}{rgb}{0.9,0.9,0.9} +\str_if_eq:VnTF{\spel@markervisibility}{none}{ + \colorlet{spel@color@right}{white} + \colorlet{spel@color@left}{white} +}{} +\str_if_eq:VnTF{\spel@markervisibility}{onlygroups}{ + \colorlet{spel@color@right}{black!25} + \colorlet{spel@color@left}{white} +}{} +\str_if_eq:VnTF{\spel@markervisibility}{full}{ + \colorlet{spel@color@right}{black!25} + \colorlet{spel@color@left}{black!25} +}{} +\ExplSyntaxOff +% \end{macrocode} +% +% +% % \subsection{Generating speech chunks --- implicitly} % \subsubsection{Auxiliary macros} % We define a macro to generate wrappers for single-line text elements. @@ -1789,7 +1810,7 @@ \expandafter\let\csname spel@@#1\expandafter\endcsname\csname #1\endcsname \expandafter\gdef\csname #1\endcsname##1{% \spel@chunkwrite{#1}{##1} - \csname spel@@#1\endcsname{\href{run:\audiodir/#1.\spel@format}{##1}} + \csname spel@@#1\endcsname{\href{\linksdir/#1.\spel@format}{##1}} } \expandafter\AtBeginDocument{ \spel@idxwrite{#1}{#1} @@ -1846,7 +1867,7 @@ \let\spel@@part\@part \def\@part[#1]#2{% \setcounter{spel@chunk}{0}% need this because counter resetting fails - \spel@@part[#1]{\href{run:\audiodir/\spel@@optpart.\spel@format}{#2}}% + \spel@@part[#1]{\href{\linksdir/\spel@@optpart.\spel@format}{#2}}% \spel@idxwrite{part \thepart}{\spel@@optpart}% \spel@chunkwrite{\spel@@optpart}{#2}% } @@ -1863,7 +1884,7 @@ \stepcounter{spel@spart}% \setcounter{spel@chunk}{0}% need this because counter resetting fails \spel@@spart{% - \href{run:\audiodir/\spel@@optpart star-\thespel@spart.\spel@format}{#1}}% + \href{\linksdir/\spel@@optpart star-\thespel@spart.\spel@format}{#1}}% \spel@idxwrite{part}{\spel@@optpart star-\thespel@spart}% \spel@chunkwrite{\spel@@optpart star-\thespel@spart}{#1}% } @@ -1881,7 +1902,7 @@ \def\@chapter[#1]#2{% \setcounter{spel@chunk}{0}% need this because counter resetting fails \spel@@chapter[#1]{% - \href{run:\audiodir/\spel@@optpart\thechapter.\spel@format}{#2}}% + \href{\linksdir/\spel@@optpart\thechapter.\spel@format}{#2}}% \spel@idxwrite{chapter \thechapter}{\spel@@optpart\thechapter}% \spel@chunkwrite{\spel@@optpart\thechapter}{#2}% } @@ -1901,7 +1922,7 @@ \stepcounter{spel@schapter}% \setcounter{spel@chunk}{0}% need this because counter resetting fails \spel@@schapter{% - \href{run:\audiodir/\spel@@optpart star-\thespel@schapter.\spel@format}{#1}}% + \href{\linksdir/\spel@@optpart star-\thespel@schapter.\spel@format}{#1}}% \spel@idxwrite{chapter}{\spel@@optpart star-\thespel@schapter}% \spel@chunkwrite{\spel@@optpart star-\thespel@schapter}{#1}% } @@ -1922,8 +1943,8 @@ \fi% \setcounter{spel@chunk}{0}% need this because counter resetting fails \spel@@sect{#1}{#2}{#3}{#4}{#5}{#6}[#7]{% - \href{run:\audiodir/\spel@@optpart\thesubparagraph.\spel@format}{#8}\hfill% - \href{run:\audiodir/\spel@@optpart\thesubparagraph.m3u}{\textcolor{black!25}{$\triangleright$}}}% + \href{\linksdir/\spel@@optpart\thesubparagraph.\spel@format}{#8}\hfill% + \href{\linksdir/\spel@@optpart\thesubparagraph.m3u}{\textcolor{spel@color@right}{$\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}% @@ -1941,7 +1962,7 @@ \stepcounter{spel@ssect}% %\setcounter{spel@chunk}{0}% need this because counter resetting fails \spel@@ssect{#1}{#2}{#3}{#4}{% - \href{run:\audiodir/\spel@@optpart\thesubparagraph-star-\thespel@ssect.\spel@format}% + \href{\linksdir/\spel@@optpart\thesubparagraph-star-\thespel@ssect.\spel@format}% {#5}}% \spel@idxwrite{section}{\spel@@optpart\thesubparagraph-star-\thespel@ssect}% \spel@chunkwrite{\spel@@optpart\thesubparagraph-star-\thespel@ssect}{#5}% @@ -1963,7 +1984,7 @@ \stepcounter{spel@footnote}% \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}% \spel@@fntext{% - \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/footnote-\thespel@footnote.\spel@format}{\usebox\spel@mptbox}#1}% + \hspace*{-\spel@mptboxwidth}\href{\linksdir/footnote-\thespel@footnote.\spel@format}{\usebox\spel@mptbox}#1}% \spel@idxwrite{footnote}{footnote-\thespel@footnote}% \spel@chunkwrite{footnote-\thespel@footnote}{#1}% } @@ -2004,7 +2025,7 @@ \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}% \spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}% \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1}% - \item \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#1} + \item \hspace*{-\spel@mptboxwidth}\href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#1} % \end{macrocode} % \end{macro} % @@ -2017,7 +2038,7 @@ \settowidth\spel@mptboxwidth{\usebox\spel@mptbox}% \spel@idxwrite{item}{\spel@@optpart\thesubparagraph-\thespel@chunk}% \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#1 . #2}% -\item[#1] \hspace*{-\spel@mptboxwidth}\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#2} +\item[#1] \hspace*{-\spel@mptboxwidth}\href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}#2} % \end{macrocode} % \end{macro} % @@ -2031,7 +2052,7 @@ \stepcounter{spel@chunk}% \spel@idxwrite{caption}{\spel@@optpart\thesubparagraph-\thespel@chunk}% \spel@chunkwrite{\spel@@optpart\thesubparagraph-\thespel@chunk}{#2}% - \spel@@caption[#1]{\protect\href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{#2}} + \spel@@caption[#1]{\protect\href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{#2}} } \fi % \end{macrocode} @@ -2046,7 +2067,7 @@ % \begin{macrocode} \newlength\spel@mptboxwidth \newsavebox\spel@mptbox -\savebox\spel@mptbox{\textcolor{black!25}{$\qquad$}} +\savebox\spel@mptbox{\textcolor{spel@color@left}{\quad\strut\tiny\raisebox{0.4ex}{$\triangleright$}\,}} \newif\ifspel@chunkarealink \define@key{spelchunk}{arealink}[]{\spel@chunkarealinktrue} \ifspel@disabled\def\spelchunk{}\else @@ -2061,10 +2082,10 @@ \end{VerbatimOut}% \catcode`\^^M=5\relax% \ifspel@chunkarealink% - \href{run:\audiodir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}}% + \href{\linksdir/\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}% + \hspace*{-\spel@mptboxwidth}\href{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}% \fi% \spel@chunkarealinkfalse% }% @@ -2092,6 +2113,47 @@ % \end{macrocode} % \end{macro} % +% \begin{macrocode} +\ExplSyntaxOn +\NewDocumentCommand{\spelchunkatom}{O{}m}{ + \stepcounter{spel@chunk}% + \spel@idxwrite{chunk}{\spel@@optpart\thesubparagraph-\thespel@chunk}% + \setkeys{spelchunk}{#1} + \scantokens{ + \makeatletter + \begin{spelverbatimwrite}{\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk.tex} + #2 + \end{spelverbatimwrite} + \makeatother + } + \ifspel@chunkarealink% + \href{\linksdir/\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{\linksdir/\spel@@optpart\thesubparagraph-\thespel@chunk.\spel@format}{\usebox\spel@mptbox}\input{./\chunkdir/\spel@@optpart\thesubparagraph-\thespel@chunk}% + \fi% + \spel@chunkarealinkfalse% +} + +\def\spelverbatimwrite#1{% + \@bsphack + \openoutputfile{#1}{chunk}% + \def\verbatim@processline{\addtostream{chunk}{\the\verbatim@line}}% + \let\do\@makeother\dospecials + \catcode`\^^M\active \catcode`\^^I=12 + \verbatim@start}% +\def\endspelverbatimwrite{% + \closeoutputstream{chunk}% + \@esphack% +} +\ifspel@disabled + \newcommand\<<<[2][]{#2} +\else + \def\<<<{\spelchunkatom} +\fi +\ExplSyntaxOff +% \end{macrocode} +% % \subsubsection{Explicit spelchunks} % % \begin{environment}{spelchunkad} @@ -2117,6 +2179,7 @@ % \subsection{Helping the wizard to read our chunks} % % \subsubsection{Listing macros that are to be preprocessed} +% \begin{macro}{\spelmacpp} % Some \LaTeX{} or \TeX commands are only for layout purposes and are % totally not content related. They do not contribute to what must be % read. On the contrary, they make it hard for the \spelpl{} parser to @@ -2130,7 +2193,6 @@ % oriented, it makes sense to provide a macro that registers them as % pure type-setting macros and use that macro to cover the examples % mentioned above. -% \begin{macro}{\spelmacpp} % \begin{macrocode} \ExplSyntaxOn \NewDocumentCommand{\spelmacpp}{moom} @@ -2163,6 +2225,8 @@ \spelmacpp{textit}[1]{keep} \spelmacpp{texttt}[1]{keep} \spelmacpp{textbf}[1]{keep} +\spelmacpp{mathbb}[1]{keep} +\spelmacpp{mathcal}[1]{keep} \spelmacpp{quad}{} \spelmacpp{qquad}{} \spelmacpp{displaystyle}{} @@ -2179,6 +2243,7 @@ % \end{macrocode} % % \subsubsection{Listing environments that are to be ignored} +% \begin{macro}{\spelenvpp} % Some \LaTeX{} or \TeX environments are only for layout purposes and are % totally not content related. They do not contribute to what must be % read. On the contrary, they make it hard for the \spelpl{} parser to @@ -2191,7 +2256,6 @@ % oriented, it makes sense to provide a macro that registers them as % pure type-setting macros and use that macro to cover the examples % mentioned above. -% \begin{macro}{\spelenvpp} % \begin{macrocode} \ExplSyntaxOn \NewDocumentCommand{\spelenvpp}{moom} @@ -2240,7 +2304,6 @@ % ignored: % \begin{macrocode} \spelmacad{spelatex}{spee-lay-tech} -\spelmacad{spelbox}{spel-box} \spelmacad{spelpl}{spel wizzard dot pl} \spelmacad{LaTeX}{lay-tech} \spelmacad{TeX}{tech} @@ -2335,7 +2398,7 @@ % % \section{TODO} % \begin{spelchunk}[arealink] -% As long as there are things on my todo list, We have a reason to +% As long as there are things on our todo list, we have a reason to % live. % \end{spelchunk} % \begin{itemize} @@ -2374,22 +2437,6 @@ % \newblock \url{https://www.winehq.org} % \newblock online, accessed in June 2024. % -% \bibitem{ORGMODE} -% Org Mode --- your life in plain text. -% \newblock \url{https://orgmode.org/}. -% \newblock online, accessed in May 2024. -% -% \bibitem{EMACS} -% The Emacs An extensible, customizable, free text editor --- and -% more. -% \newblock \url{https://www.gnu.org/software/emacs/}. -% \newblock online, accessed in May 2024. -% -% \bibitem{OXSPELATEX} -% Org Mode SpeLaTeX Exporter --- SpeLaTeX made easy. -% \newblock \url{https://www.melpa.org/#/ox-spelatex} -% \newblock (not yet online) -% % \bibitem{SPEL} % SpeL --- Speech-enabled \LaTeX. % \newblock \url{https://ctan.org/pkg/spel} @@ -2445,11 +2492,6 @@ % \newblock \url{https://okular.kde.org}. % \newblock online, accessed in May 2024. % -% \bibitem{PDFXCHANGE} -% PDF XChange Viewer, a PDF reader from Tracker Software. -% \newblock \url{https://www.pdf-xchange.com/} -% \newblock online, accessed in May 2024. -% % \end{thebibliography} % % \Finale |