optionally use KaTeX for math in html

LiberalArtist · LiberalArtist · commit 5d73fbfaeb0a · 2023-11-18T01:09:11.000-05:00
- Detect when KaTeX is available and use it. Add the variables KATEX,
  KATEX_FLAGS, and KATEX_CSS for configuration. Add KaTeX definitions
  for macros needed for compatibility.
    Mf-stex, math/Makefile, math/katexmacros
- Add --use-katex, --katex-css-link-file, and --katex-finished to
  html-prep. Use &lt;!DOCTYPE html&gt;. Emit a link to katex.css when
  applicable. Adjust emit-math and punt-to-latex for KaTeX backend.
  Report lack of support for \epsfbox{} and the eqnarray* environment
  when using KaTeX. Add special handling for the "ghost" \Rightarrow
  so that it will match the selected backend's \Rightarrow.
    src/html-prep.ss, inputs/scheme.hsty
- Support the macros \LaTeX and \KaTeX.
    inputs/scheme.sty, inputs/scheme.hsty
- Update documentation and build with KaTeX. Add .gitignore to avoid
  committing generated intermediate files.
    Makefile.template, doc/Makefile, doc/stex.stex, doc/stex.pdf,
    doc/stex.html, doc/stex.katex-css-link, doc/.gitignore
- Increment version to 1.3.
    src/VERSION
diff --git a/Makefile.template b/Makefile.template
@@ -17,6 +17,8 @@ bib =
 # define index if an index is to be generated
 # index=yes
 
+# override katex variables here if desired
+
 include $(STEXLIB)/Mf-stex
 
 # define or override suffixes here
diff --git a/Mf-stex b/Mf-stex
@@ -28,6 +28,30 @@ else
   fixbibtex = $(STEXLIB)/$m/fixbibtex
 endif
 
+ifeq ($(origin KATEX), undefined)
+KATEX:=$(if $(shell command -v katex),katex,)
+endif
+ifneq ($(strip $(KATEX)),)
+  ifeq ($(strip $(KATEX_CSS)),)
+    # try to infer KATEX_CSS
+    katexrealpath:=$(realpath $(shell command -v $(KATEX)))
+    katexrealdir:=$(dir $(katexrealpath))
+    ifeq ($(katexrealpath),)
+      # can't infer; complain below
+    else ifneq ($(realpath $(katexrealdir)/dist/katex.css),)
+      # NPM installation layout (also release tarballs)
+      KATEX_CSS=$(katexrealdir)/dist/katex.css
+    else ifneq ($(realpath $(katexrealdir)/katex.css),)
+      # Debian installation layout
+      KATEX_CSS=$(katexrealdir)/katex.css
+    endif
+    ifeq ($(strip $(KATEX_CSS)),)
+      $(error cannot find KATEX_CSS for KATEX=$(KATEX))
+    endif
+  endif
+endif
+export KATEX KATEX_FLAGS
+
 mathdir=math/$(x)
 mathfiles=$(mathdir)/mathfiles
 
@@ -104,7 +128,30 @@ $(x).firstrun: $(texsrc)
 
 all.tex: $(texsrc)
 
+ifeq ($(strip $(KATEX)),)
 $(x).html: $(x).mathrun
+else
+$(x).hfourthrun: $(x).mathrun $(x).katex-css-link
+	$(Hprep) --mathdir $(mathdir) --use-katex --katex-finished --katex-css-link-file $(x).katex-css-link $(x)
+	chmod 444 *.html
+	touch $(x).hfourthrun
+
+# a project may supply one with content to override the default
+$(x).katex-css-link:
+	touch $(x).katex-css-link
+
+ifeq ($(strip $(KATEX_CSS)),no)
+$(x).html: $(x).hfourthrun
+else
+$(x).html: $(x).hfourthrun katex
+
+katex:
+	mkdir -p katex
+	cp $(KATEX_CSS) katex/katex.css
+	(cd katex; (cd $(dir $(KATEX_CSS)); tar -cf - --dereference fonts) | tar -xpf -)
+	chmod u+w katex/katex.css katex/fonts
+endif
+endif
 
 $(x).mathrun: gifs $(mathfiles)
 	@(cd $(mathdir); make)
@@ -121,20 +168,22 @@ math:
 $(mathfiles): $(x).hthirdrun $(figps)
 	echo -n gifs= > $(mathfiles)
 	(cd $(mathdir); echo *.tex | sed -e "s/\.tex/.gif/g") >> $(mathfiles)
+	echo -n htmls= >> $(mathfiles)
+	(cd $(mathdir); echo *.katex | sed -e "s/\.katex/.html/g") >> $(mathfiles)
 
 $(x).hthirdrun: $(x).hsecondrun
-	$(Hprep) --mathdir $(mathdir) $(x)
+	$(Hprep) --mathdir $(mathdir) $(if $(strip $(KATEX)),--use-katex,) $(x)
 	chmod 444 *.html
 	touch $(x).hthirdrun
 
 $(x).hsecondrun: $(x).hfirstrun
-	$(Hprep) --mathdir $(mathdir) $(x)
+	$(Hprep) --mathdir $(mathdir) $(if $(strip $(KATEX)),--use-katex,) $(x)
 	chmod 444 *.html
 	touch $(x).hsecondrun
 
 $(x).hfirstrun: math $(x).thirdrun
-	(if [ ! -e $(mathdir) ] ; then mkdir -p -m u=rwx,g=srx,o=rx $(mathdir); ln -s ../Makefile ../mathmacros $(mathdir); fi)
-	$(Hprep) --mathdir $(mathdir) $(x)
+	(if [ ! -e $(mathdir) ] ; then mkdir -p -m u=rwx,g=srx,o=rx $(mathdir); ln -s ../Makefile ../mathmacros ../katexmacros $(mathdir); fi)
+	$(Hprep) --mathdir $(mathdir) $(if $(strip $(KATEX)),--use-katex,) $(x)
 	touch $(x).hfirstrun
 
 spell: $(spellobj)
@@ -145,7 +194,7 @@ $(x).spell: $(x).bbl $(x).tex
 
 clean: $(x).clean
 	-/bin/rm -f *.log *.dvi *.aux *.out *.toc *.tmp *.idx *.ilg *.ind *.blg *.bbl *.rfm *.sfm *.firstrun *.secondrun *.thirdrun
-	-/bin/rm -f *.haux *.htoc *.hidx *.hfirstrun *.hsecondrun *.hthirdrun *.mathrun
+	-/bin/rm -f *.haux *.htoc *.hidx *.hfirstrun *.hsecondrun *.hthirdrun *.mathrun *.hfourthrun
 	-/bin/rm -f *.tex
 
 reallyclean: clean $(x).reallyclean
diff --git a/doc/.gitignore b/doc/.gitignore
@@ -0,0 +1,11 @@
+gifs/
+math/
+*.tex
+*.log
+*[.h]aux
+*[.h]toc
+*[.h]firstrun
+*[.h]secondrun
+*[.h]thirdrun
+*.hfourthrun
+*.mathrun
diff --git a/doc/Makefile b/doc/Makefile
@@ -17,6 +17,9 @@ bib =
 # define index if an index is to be generated
 # index=yes
 
+# override katex variables here if desired
+KATEX_CSS=no # see comment in stex.katex-css-link
+
 include $(STEXLIB)/Mf-stex
 
 # define or override suffixes here
diff --git a/doc/stex.html b/doc/stex.html
diff --git a/doc/stex.katex-css-link b/doc/stex.katex-css-link
@@ -0,0 +1,22 @@
+<!--
+    A built copy of stex.html is checked in to the Git repository, and it
+    ought to be readable without having to install or use stex (since it tells
+    you how to do that). However, checking in the fonts needed for KaTeX would
+    roughly double the size of the stex repository, even though the fonts are
+    not especially large in absolute terms.
+
+    Instead, this file overrides the default link to katex.css to load it, and
+    the fonts it uses, externally.  The `KATEX_CSS=no` line in the makefile
+    accordingly instructs stex not to copy the CSS and fonts into the build.
+
+    Under other circumstances, the default behavior of stex is preferrable: in
+    particular, it ensures that the version of katex.css matches the version
+    of KaTeX used to typeset the document.
+
+    Another option would be to define `KATEX_FLAGS=--format mathml` and rely
+    solely on the native support in recent browsers and operating systems.
+-->
+<link rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.css"
+      integrity="sha384-OH8qNTHoMMVNVcKdKewlipV4SErXqccxxlg6HC9Cwjr5oZu2AdBej1TndeCirael"
+      crossorigin="anonymous" />
diff --git a/doc/stex.pdf b/doc/stex.pdf
diff --git a/doc/stex.stex b/doc/stex.stex
@@ -42,27 +42,29 @@ items, such as make files, make-file templates, class files, and style
 files.
 The two main programs are \textbf{scheme-prep} and \textbf{html-prep}.
 \textbf{scheme-prep} performs a conversion from ``stex''-formatted files
-into latex-formatted files, while \textbf{html-prep} converts (some)
-latex-formatted files into html-formatted files.
+into \LaTeX-formatted files, while \textbf{html-prep} converts (some)
+\LaTeX-formatted files into html-formatted files.
 
-An stex file is really just a latex file extended with a handful of
+An stex file is really just a \LaTeX\ file extended with a handful of
 commands for including Scheme code (or pretty much any other kind of code,
 as long as you don't plan to use the Scheme-specific transcript support)
 in a document, plus a couple of additional features rather arbitrarily
 thrown in.
 
-The subset of latex-formatted files \textbf{html-prep} is capable of
+The subset of \LaTeX-formatted files \textbf{html-prep} is capable of
 handling is rather small but has nevertheless been useful for our
 purposes, which include producing html versions of a couple of books
 (\emph{The Scheme Programming Language}, Editions 2--4 and the Chez Scheme
-User's Guides for Versions 6--9), the scheme.com web site, class websites,
+User's Guides for Versions 6--10), the scheme.com web site, class websites,
 class assignments, and various other documents.
 
 \section{Installation}
 
 A prerequisite to building and using stex is to have Chez Scheme
 installed on your system.
 You'll also need pdflatex, dvips, ghostscript, and netpbm.
+Additionally, you may want to have \KaTeX\ installed: see ``Math in HTML''
+below.
 We've run stex under Linux and OS X but have not tried to run it under
 Windows.
 
@@ -618,4 +620,60 @@ a & b & c & d \\
 \end{tabular}
 \end{quotation}
 
+\section{Math in HTML}
+
+A few very simple uses of \LaTeX's math mode are converted to HTML directly by
+\textbf{html-prep}. For typesetting non-trivial math, there are two strategies
+available:
+
+\begin{enumerate}
+  \item Originally, stex used \LaTeX\ to render math to GIF images.
+  \item Optionally, stex can use \KaTeX, which generates MathML and/or HTML.
+\end{enumerate}
+
+Using \KaTeX\ makes the rendered math accessible to assistive technologies,
+CSS, and other browser features. It also tends to look better than math in
+GIFs.  However, a few features that stex supports when rendering to GIFs,
+notably including \scheme{\epsfbox\schlbrace\schrbrace} and the
+\scheme{eqnarray*} environment, are not currently supported when rendering with
+\KaTeX.
+
+By default, stex will use \KaTeX\ if the ``katex'' command is found; otherwise,
+it will automatically fall back to generating GIFs. To prevent stex from using
+\KaTeX\ even if it is available, use \scheme{make KATEX=} or define
+\scheme{KATEX} as empty in your makefile before including Mf-stex. The same
+mechanisms can be used to supply a non-default ``katex'' command or even to
+require that \KaTeX\ be present, e.g.\ by writing:
+
+\begin{quotation}
+\begin{verbatim}
+KATEX:=$(if $(shell command -v katex),katex,$(error katex not found))
+\end{verbatim}
+\end{quotation}
+
+The variable \scheme{KATEX_FLAGS} may be used to supply additional options for
+\KaTeX.
+
+The output of \KaTeX\ requires supporting CSS and font files. (Notably, it does
+not require JavaScript. It is also possible to supply non-default options to
+create output that can work without CSS and fonts by relying solely on the
+native support for MathML in recent browsers and operating systems.) By
+default, stex will attempt to find these files relative to the ``katex''
+command, and it should be able to handle the installation layouts used by both
+Node.js and Debian. If the files cannot be found automatically, you will need
+to define \scheme{KATEX_CSS}, either at the command line or in your makefile
+(before including Mf-stex): likely values include
+``./node\_modules/katex/dist/katex.css'' and
+``/usr/share/javascript/katex/katex.css''.
+
+By default, stex copies the needed CSS and font files into a directory named
+``katex'' alongside the generated HTML files: when using \KaTeX, you need to
+install this directory or upload it to your web server.
+
+As a special case, defining \scheme{KATEX_CSS=no} instructs stex not to copy
+these files. If you use this option, you may also want to override the default
+HTML \scheme{link} element used to load the CSS by creating a non-empty file
+with the base name of your document and the extension ``.katex-css-link'': for
+an example, see the ``stex.katex-css-link'' file used for this document.
+
 \end{document}
diff --git a/inputs/scheme.hsty b/inputs/scheme.hsty
@@ -31,7 +31,7 @@
 \def\schunderscore{\raw{_}}
 \def\becomes{$\rightarrow$}
 \def\is{$\Rightarrow$}
-\def\si{\raw{<img src="gifs/ghostRightarrow.gif">}}
+\def\si{\schemeghostRightarrow} % handled specially by html-prep
 \def\var#1{\emph{#1}}
 
 % frame="border" rules="all" makes mozilla do it right
@@ -40,3 +40,10 @@
 \def\endrepl{\raw{</td>}}
 \def\startinteraction{\raw{<td align="right"><table rules="all" border="1"><tr><td>}}
 \def\endinteraction{\raw{</td></tr></table></td></tr></table>}}
+
+% This seemingly circular definition works because the \KaTeX inside
+% math mode is expanded with a different definition: either the
+% primitive from KaTeX or, if rendering without KaTeX, the definition
+% from scheme.sty.
+\def\KaTeX{$\mbox{\KaTeX}$}
+\def\LaTeX{$\mbox{\LaTeX}$}
diff --git a/inputs/scheme.sty b/inputs/scheme.sty
@@ -54,3 +54,13 @@
 \def\beforeschemedisplay{\penalty-100\vskip\parskip\vskip5pt}
 \def\afterschemedisplay{\penalty-200\vskip5pt}
 
+% From test/screenshotter/test.tex in the KaTeX source code, which says:
+% > Based on LaTeX's definition of \LaTeX, with L changed to K and kerns
+% > changed as in src/macros.js
+\DeclareRobustCommand{\KaTeX}{\mbox{%
+K\kern-.17em%
+{\sbox0 T\vbox to\ht0{\hbox%
+  {\fontsize{.75em}{1em}\selectfont A}%
+\vss}}%
+\kern-.15em%
+\TeX}}
diff --git a/math/Makefile b/math/Makefile
@@ -1,9 +1,10 @@
 include mathfiles
 
 density=-r90x90
+runkatex=$(KATEX) $(KATEX_FLAGS) --macro-file katexmacros --trust
 
 .SUFFIXES:
-.SUFFIXES: .tex .gif
+.SUFFIXES: .tex .gif .katex .html
 
 # translate ps file to ppm, crop to minimum background, and translate ppm
 # to gif with white (background) transparent
@@ -19,8 +20,18 @@ density=-r90x90
 	/bin/rm -f $*.dvi $*.log $*.aux
 	test -f $*.gif && chmod 644 $*.gif
 
+.katex.html:
+	$(runkatex) -i $*.katex -o $*.html
+	test -f $*.html && chmod 644 $*.html
+
+ifeq ($(strip $(KATEX)),)
 all: ${gifs}
+else
+all: ${htmls}
+endif
 
 ${gifs}: mathmacros
 
-clean: ; /bin/rm -f *.gif Make.out
+${htmls}: katexmacros
+
+clean: ; /bin/rm -f *.gif *.html Make.out
diff --git a/math/katexmacros b/math/katexmacros
@@ -0,0 +1,2 @@
+\mbox:\text{#1}
+\emph:\textit{#1}
diff --git a/src/VERSION b/src/VERSION
@@ -1 +1 @@
-1.2
+1.3
diff --git a/src/html-prep.ss b/src/html-prep.ss
