From 730c38819ceb25485b894b1f8f9cfdaed45317b4 Mon Sep 17 00:00:00 2001 From: Richard Zach Date: Thu, 24 Oct 2024 15:24:25 -0600 Subject: [PATCH] update for BookML to 10.1; more detail in accessibility notes --- Bookml.mk | 27 ++++++ README.md | 14 +++ fitchml.sty | 12 +-- forallx-yyc-accessibility.tex | 152 ++++++++++++++++++++++---------- forallx-yyc-interpretations.tex | 7 +- forallx-yyc-truthtables.tex | 12 ++- forallxyyc-html.tex | 1 + forallxyyc.sty | 8 +- 8 files changed, 167 insertions(+), 66 deletions(-) create mode 100644 Bookml.mk diff --git a/Bookml.mk b/Bookml.mk new file mode 100644 index 0000000..8d5c1af --- /dev/null +++ b/Bookml.mk @@ -0,0 +1,27 @@ +### CONFIGURATION +# Remove the initial '#' and change the value to customise the build process +# See CONFIGURATION in bookml/bookml.mk for all the options +# +# Options can also be customized on the command line, for instance +# make SPLITAT= singlepage.zip +# will compile singlepage.tex into a single page +# +# For example: remove '#' below to split your document by chapter + +# split at chapters +SPLITAT = chapter +# includestyles, otherwise fitch.sty is not processed and we get no +# proofs +# --nomathtex to leave out the tex code in ALT tags on math elements +# --nocomments to remove comments from HTML +LATEXMLEXTRAFLAGS = --includestyles --nocomments +LATEXMLPOSTEXTRAFLAGS = --pmml --nomathtex --css=forallxyyc.css --css=fitchml.css + +# Only convert the HTML driver not all the other TEX files +SOURCES = forallxyyc-html.tex +### END CONFIGURATION + +include bookml/bookml.mk + +# You may also override SPLITAT and other options for a single file, as follows: +#singlepage.zip: SPLITAT= diff --git a/README.md b/README.md index 9eaaa5f..f7d7576 100644 --- a/README.md +++ b/README.md @@ -126,6 +126,20 @@ to get the connectives to be ∼, &, ⊃, ≡ instead of ¬, ∧, →, ↔, and atomic formulas _Lab_ instead of _L(a,b)_, copy `forallxyyc-local-sample.sty` to that file. +## Convert to HTML + +To convert the book to HTML: + +- Install [LaTeXML](https://math.nist.gov/~BMiller/LaTeXML/). +- Install [BookML](https://vlmantova.github.io/bookml/) and its + dependencies. If your source files live in, say, `~/forallx-yyc` you + should have a subdirectory `~/forallx-yyc/bookml`. +- run `make -f Bookml.mk` from inside `~/forallx-yyc`. + +If this works, your HTML files can be found in +`~/forallx-yyc/auxdir/html/forallxyyc-html/` and the SCORM package in +`~/forallx-yyc/SCORM.forallxyyc-html.zip`. + ## Credits and License _forall x: Calgary_ is based on [_forall x: diff --git a/fitchml.sty b/fitchml.sty index 6ebdaa2..f9e1757 100644 --- a/fitchml.sty +++ b/fitchml.sty @@ -43,7 +43,7 @@ \} \def\nd@pline#1{\\ensuremath{\nd@num{#1}}\} \def\nd@scope{% - \\
% + \\
\% \iffmlClose close subproof, \global\fmlClosefalse @@ -53,12 +53,12 @@ \global\fmlOpenfalse \fi \arabic{nd@scope}% - \
\} + \\
\} % cant get this to work \def\nd@just#1{% \% - \
% - #1\
\} + \
\% + #1\\
\} \def\PR{\by{\PR\}{}} \def\AS{\by{\AS\}{}} @@ -99,10 +99,10 @@ % \def\nd@g#1{\nd@f{\makebox[\nd@indent][c]{$#1$}}} \def\nd@g#1{} % Guards not supported! % \def\nd@f#1{\raisebox{0pt}[0pt][0pt]{$#1$}} -\def\nd@f#1{\
\ensuremath{#1}\
} % \raisebox{0pt}[0pt][0pt]{$#1$}} +\def\nd@f#1{\
\\ensuremath{#1}\\
} % \raisebox{0pt}[0pt][0pt]{$#1$}} % \def\nd@u#1{\makebox[0pt][l]{\settowidth{\nd@dim}{\nd@f{#1}}% % \addtolength{\nd@dim}{2\nd@hsep}\hspace{-\nd@hsep}\rule[-\nd@depthdim]{\nd@dim}{\nd@thickness}}\nd@f{#1}} -\def\nd@u#1{\
\ensuremath{#1}\
} +\def\nd@u#1{\
\\ensuremath{#1}\\
} % \def\nd@by#1#2{\ifx\nd@x#2\nd@x\gdef\nd@byt{\mbox{#1}}\else\gdef\nd@byt{\mbox{#1, \ndref{#2}}}\fi} \def\nd@by#1#2{\ifx\nd@x#2\nd@x\gdef\nd@byt{#1}\else\gdef\nd@byt{#1 \ndref{#2}}\fi} \ No newline at end of file diff --git a/forallx-yyc-accessibility.tex b/forallx-yyc-accessibility.tex index 7102cf0..0138802 100644 --- a/forallx-yyc-accessibility.tex +++ b/forallx-yyc-accessibility.tex @@ -4,8 +4,18 @@ \chapter{Notes on accessibility} Special attention has been paid to make this HTML version as accessible as possible, especially to readers using Assistive -Technology (AT), such as screen readers. It has, however, not -been extensively tested. If you are using it with a screen reader or +Technology (AT), such as screen readers like +\href{https://www.nvaccess.org/download/}{NVDA} +and +\href{https://www.freedomscientific.com/products/software/jaws/}{JAWS}. +Screen readers are software designed to enable users with low or no +vision to access and navigate web pages like this book. Some sighted +users also sometimes prefer text-to-speech (TTS) software to read web +pages aloud. TTS software has fewer features than screen readers +designed for non-sighted users and may not convert everything in this +book to audio. + +If you are using the HTML version of this book with a screen reader or Braille terminal, or are helping a student who relies on such tools (e.g., as instructor or accessibility advisor), and you have feedback please \href{mailto:rzach@ucalgary.ca}{get in touch}! @@ -23,55 +33,51 @@ \chapter{Notes on accessibility} beginning of the content, past the navigation sidebar and style buttons. The buttons are, in order: \begin{itemize} - \item `toggle sidebar' to turn the navigation bar on or off; - \item `font settings' for font size, serif or sans serif font, and + \item ``toggle sidebar'' to turn the navigation bar on or off; + \item ``font settings'' for font size, serif or sans serif font, and light, sepia, or dark modes; - \item `download' for links to download the PDF versions; and - \item `information about the toolbar' for a popup that shows + \item ``download'' for links to download the PDF versions; and + \item ``information about the toolbar'' for a popup that shows keyboard shortcuts for navigation. \end{itemize} Those keyboard shortcuts are: left and right arrow for moving to the previous and the next page, and `s' to toggle the navigation sidebar. -\paragraph{Symbols and formulas} All logical symbols and formulas in -this book are converted to MathML and displayed using +\paragraph{Symbols and formulas} + +Logical symbols and formulas in this book are converted to +\href{https://www.w3.org/Math/}{MathML} and displayed using \href{https://www.mathjax.org/}{MathJax}. MathJax provides additional \href{https://docs.mathjax.org/en/latest/basic/accessibility.html}{accessibility -features} for formulas, which are found in the MathJax context -menu---activate/right click on any formula to activate it. If your -screen reader does not read out formulas such as $\forall x(A(x) \land -B(x))$ you may need to activate Speech Output in the Speech submenu of -the MathJax accessibility menu. - -For reference, here is a table of all the symbols used in the text, -how they are (probably?) pronounced, and what they are called in the -text. In the rightmost column we provide a suggested way to enter them -using ASCII characters, if inserting special symbols (in a homework -assignment or email to your instructor, say) is not an option. +features} for formulas, which are found in the MathJax context menu. +With a mouse, you can right click on any formula to activate it. +Screen readers will announce that formulas can be activated (e.g., +NVDA says ``application clickable'' before every formula to indicate +the presence of the MathJax menu.) If your screen reader does not read +out formulas such as $\forall x(A(x) \land B(x))$ you may need to +activate Speech Output in the Speech submenu of the MathJax +Accessibility menu and reload the page. -\begin{tabular}{lllll} - \lxBeginTableHead{}Symbol\lxTableColumnHead{} & Pronounciation\lxTableColumnHead{} & Meaning\lxTableColumnHead{} & ASCII equivalent\lxTableColumnHead{}\\ - \hline\lxEndTableHead - $\enot$ & not sign & logical not & \verb+~+ or \verb+-+\\ - $\eor$ & or & logical or & \verb+\/+\\ - $\eand$ & and & logical and & \verb+/\+ or \verb+&+\\ - $\eif$ & right arrow & conditional & \verb+->+ or \verb+>+\\ - $\eiff$ & left right arrow & biconditional & \verb+<->+ or \verb+<>+\\ - $\ered$ & up tack & contradiction & \verb+_|_+ or \verb+!?+\\ - $\forall$ & for all & universal quantifier & \verb|A| or \verb|@|\\ - $\exists$ & there exists & existential quantifier & \verb|E| or \verb|3|\\ - $\therefore$ & therefore & therefore & \verb|:.|\\ - $\proves$ & right tack & proves & \verb+|-+\\ - $\nproves$ & does not prove & does not prove & \verb+|/-+\\ - $\entails$ & true & entails & \verb+|=+\\ - $\nentails$ & not true & does not entail & \verb+|/=+\\ - $\ebox$ & white square & necessary & \verb+[]+\\ - $\ediamond$ & white diamond & possible & \verb+<>+ -\end{tabular} +Here are some of the more common symbols. Different screen readers and +TTS applications will pronouce them differently, and sometimes not at +all. After each symbol, we provide the customary pronounciation used +by logicians. +\begin{itemize} + \item Uppercase and lowercase italic letters like $A$ (``upper A'') + and $x$ (``lower x'') + \item Uppercase and lowercase script letters like $\metav{A}$ + (``script upper A'') and $\metav{x}$ (``script lower x'') + \item Logical connectives: $\enot$ (``not''), $\eor$ (``or''), + $\eand$ (``and''), $\eif$ (``only if''), $\eiff$ (``if and only if''), $\ered$ (``contradiction'') + \item Quantifiers: $\forall$ (``for all''), $\exists$ (``there exists'') + \item Metatheoretical symbols: $\therefore$ (``therefore''), + $\proves$ (``proves''), $\nproves$ (``does not prove''), $\entails$ (``entails''), $\nentails$ (``does not entail'') + \item Modal operators: $\ebox$ (``box''), $\ediamond$ (``diamond'') +\end{itemize} Subscripts should be pronounced by screen readers, although -if the subscript is a number, they may not be. They can be -represented by an underline, e.g., $A_2$ as \verb|A_2|. +they may not indicate that they are subscripts. The formula $A_2$ may +be read out as ``upper A sub 2'' or just as ``A2''. The expressions `\blank{}' and `\ifeff' (`if' with two `f's) are used throughout the textbook. In the HTML version, `\blank{}' includes an @@ -79,7 +85,7 @@ \chapter{Notes on accessibility} out loud. The abbreviation `\ifeff' is short for `if and only if'. In the HTML version it is coded using an invisible zero-space word joiner character which should make screen readers pronounce `\ifeff' as -`if-eff'. +`if-eff' or `aye-eff-eff'. \paragraph{Proofs} The natural deduction proofs in \cref{ch.NDTFL,ch.NDFOL,ch.ML} use vertical lines to indicate where @@ -87,7 +93,7 @@ \chapter{Notes on accessibility} assumption line of the subproof to its last line and are displayed between the line numbers and the formulas in any given line. This makes proofs a special challenge for users with low vision or complete -loss of vision. +loss of vision. To make these proofs accessible in this HTML version, proofs are coded as tables. Each table line has four columns: the line number, a @@ -133,6 +139,62 @@ \chapter{Notes on accessibility} different subproofs. If you cannot see the subproof lines, you have to pay special attention to how the subproof level numbers change \emph{and} when a formula is an assumption. A screen reader should -announce line 7 as ``7, close subproof, 2, open subproof, $X$, AS.'' -The abbreviations `\PR' (for `Premise') and `\AS' (for `Assumption') -are coded in the HTML version using the `\verb|abbr|' tag. \ No newline at end of file +read line 7 approximately as: ``7, close subproof, 2, open subproof, +upper X, AS.'' The abbreviations `\PR' (for `Premise') and `\AS' (for +`Assumption') are coded in the HTML version using the `\verb|abbr|' +tag. + +Note that simple text-to-speech applications may not read out complex +tables such as the ones containing proofs or truth tables at all. + +\paragraph{Diagrams} + +The text also contains a few diagrams. In the HTML version, these are +provided with image descriptions, e.g., +\begin{center} +\begin{tikzpicture} + \node[circle, grey_shape] (cat1) {A}; + \node[right=10pt of cat1, diamond, phantom_shape] (cat2) { } ; + \node[right=10pt of cat2, circle, white_shape] (cat3) {C} ; + \node[right=10pt of cat3, white_shape] (cat4) {D}; +\end{tikzpicture} +\bmlDescription{There are three shapes: the first shape is a grey +circle labelled A, some empty space, the second shape is a white +circle labelled C, and the fourth a white square labelled D.} +\end{center} +The image description here should read: ``There are three shapes: the +first shape is a grey circle labelled A, some empty space, the second +shape is a white circle labelled C, and the fourth a white square +labelled~D.'' + +\paragraph{Table of symbols} + +What follows is a table of all the symbols used in the text, how they +are most likely to be pronounced by screen readers, and what they are +called in the text. In the rightmost column we provide a suggested way +to enter them using ASCII characters, if inserting special symbols (in +a homework assignment or email to your instructor, say) is not an +option. + +\begin{tabular}{lllll} + \lxBeginTableHead{}Symbol\lxTableColumnHead{} & Pronounciation\lxTableColumnHead{} & Meaning\lxTableColumnHead{} & ASCII equivalent\lxTableColumnHead{}\\ + \hline\lxEndTableHead + $\enot$ & not sign & logical not & \verb+~+ or \verb+-+\\ + $\eor$ & or & logical or & \verb+\/+\\ + $\eand$ & and & logical and & \verb+/\+ or \verb+&+\\ + $\eif$ & right arrow & conditional & \verb+->+ or \verb+>+\\ + $\eiff$ & left right arrow & biconditional & \verb+<->+ or \verb+<>+\\ + $\ered$ & up tack & contradiction & \verb+_|_+ or \verb+!?+\\ + $\forall$ & for all & universal quantifier & \verb|A| or \verb|@|\\ + $\exists$ & there exists & existential quantifier & \verb|E| or \verb|3|\\ + $\therefore$ & therefore & therefore & \verb|:.|\\ + $\proves$ & right tack & proves & \verb+|-+\\ + $\nproves$ & does not prove & does not prove & \verb+|/-+\\ + $\entails$ & true & entails & \verb+|=+\\ + $\nentails$ & not true & does not entail & \verb+|/=+\\ + $\ebox$ & white square & necessary & \verb+[]+\\ + $\ediamond$ & white diamond & possible & \verb+<>+ +\end{tabular} + +Subscripts can be represented by an underline, e.g., $A_2$ as +\verb|A_2|. diff --git a/forallx-yyc-interpretations.tex b/forallx-yyc-interpretations.tex index d4924b1..bda703e 100644 --- a/forallx-yyc-interpretations.tex +++ b/forallx-yyc-interpretations.tex @@ -164,9 +164,6 @@ \section{Interpretations} stipulate that `$\atom{R}{x,y}$' is to hold of $x$ and $y$ \ifeff{} there is an arrow running from $x$ to $y$ in our diagram. As an example, we might offer: \begin{center} -\begin{arialabel}{The numbers 1, 2, 3, and 4 are connected - by arrows. There are arrows from 1 to 2 and 3, from 2 to 3, from 3 to - 4, and from 4 to 1.} \begin{tikzpicture} \node (atom1) at (0,2) {$1$}; \node (atom2) at (2,2) {$2$}; @@ -178,7 +175,9 @@ \section{Interpretations} \draw[->, thick] (atom4)--(atom1); \draw[->, thick] (atom1) -- (atom3); \end{tikzpicture} -\end{arialabel} +\bmlDescription{The numbers 1, 2, 3, and 4 are connected +by arrows. There are arrows from 1 to 2 and 3, from 2 to 3, from 3 to +4, and from 4 to 1.} \end{center} This diagram could be used to describe an interpretation whose domain is the first four positive whole numbers, and which interprets `$\atom{R}{x,y}$' as being true of and only of: \begin{center} diff --git a/forallx-yyc-truthtables.tex b/forallx-yyc-truthtables.tex index 43a8340..7eb12f5 100644 --- a/forallx-yyc-truthtables.tex +++ b/forallx-yyc-truthtables.tex @@ -149,14 +149,13 @@ \section{Indicative versus subjunctive conditionals}\label{s:IndicativeSubjuncti As it happens, Lara has drawn the following: \begin{center} -\begin{arialabel}{There are three shapes: the first shape is a grey circle labelled A, some empty space, the second shape is a white circle labelled C, and the fourth a white square labelled D.} \begin{tikzpicture} \node[circle, grey_shape] (cat1) {A}; \node[right=10pt of cat1, diamond, phantom_shape] (cat2) { } ; \node[right=10pt of cat2, circle, white_shape] (cat3) {C} ; \node[right=10pt of cat3, white_shape] (cat4) {D}; \end{tikzpicture} -\end{arialabel} +\bmlDescription{There are three shapes: the first shape is a grey circle labelled A, some empty space, the second shape is a white circle labelled C, and the fourth a white square labelled D.} \end{center} \noindent In this case, our claim is surely true. Shapes C and D are not grey, and so can hardly present \emph{counterexamples} to our claim. Shape A \emph{is} grey, but fortunately it is also circular. So our claim has no counterexamples. It must be true. That means that each of the following \emph{instances} of our claim must be true too: @@ -174,17 +173,16 @@ \section{Indicative versus subjunctive conditionals}\label{s:IndicativeSubjuncti However, if Lara had drawn a fourth shape, thus: \begin{center} -\begin{arialabel}{There are four shapes: the first shape is - a grey circle labelled A, the second a grey square labelled B, the - third a white circle labelled C, and the fourth a white square - labelled D.} \begin{tikzpicture} \node[circle, grey_shape] (cat1) {A}; \node[right=10pt of cat1, grey_shape] (cat2) {B}; \node[right=10pt of cat2, circle, white_shape] (cat3) {C}; \node[right=10pt of cat3, white_shape] (cat4) {D}; \end{tikzpicture} -\end{arialabel} +\bmlDescription{There are four shapes: the first shape is +a grey circle labelled A, the second a grey square labelled B, the +third a white circle labelled C, and the fourth a white square +labelled D.} \end{center} \noindent then our claim would have been false. So this claim must also be false: diff --git a/forallxyyc-html.tex b/forallxyyc-html.tex index 704d781..6a9f148 100644 --- a/forallxyyc-html.tex +++ b/forallxyyc-html.tex @@ -4,6 +4,7 @@ \documentclass{book} \usepackage{bookml/bookml} +\bmlImageEnvironment{tikzpicture} \RequirePackage{xcolor,tabularx,wrapfig} \definecolor{lyallpink}{RGB}{222,31,149} diff --git a/forallxyyc.sty b/forallxyyc.sty index cdc6bef..faef946 100644 --- a/forallxyyc.sty +++ b/forallxyyc.sty @@ -112,7 +112,7 @@ % create a blank that SRs read out as "blank" \iflatexml -\newcommand*{\blank}{\underline{blank}\bmlPlusClass{fxblank}} +\newcommand*{\blank}{\underline{blank~}\bmlPlusClass{fxblank}} \else \newcommand*{\blank}{\underline{\hspace*{2.5em}}} \fi @@ -314,9 +314,9 @@ \usepackage{tikz} \usetikzlibrary{arrows,positioning,shapes} -\tikzset{phantom_shape/.style={thick, fill=black!0, minimum width=30pt, minimum height=30pt}, % TB: renders the shape invisible +\tikzset{phantom_shape/.style={thick, fill=none, minimum width=30pt, minimum height=30pt}, % TB: renders the shape invisible grey_shape/.style={thick, fill=black!20, draw, minimum width=30pt, minimum height=30pt}, % TB: renders a light grey shape with a black outline - white_shape/.style={thick, fill=black!0, draw, minimum width=30pt, minimum height=30pt} % TB: renders a white shape with a black outline + white_shape/.style={thick, fill=none, draw, minimum width=30pt, minimum height=30pt} % TB: renders a white shape with a black outline } % **************************************** @@ -372,7 +372,7 @@ % aria-label environment to provide accessible descriptions for inline % SVG diagrams \iflatexml - \newenvironment{arialabel}[1]{\
\\
} + \newenvironment{arialabel}[1]{\\\} \else \newenvironment{arialabel}[1]{}{} \fi