optionally use KaTeX for csug and release_notes

KaTeX renders LaTeX math ahead-of-time to MathML and/or HTML.
Its output is accessible to screen readers and other tools
(instead of appearing as "<graphic>"), and it also does not
suffer from the pixelation of math rendered to GIFs.

Also, use scheme.sty and scheme.hsty from stex instead of
stale copies with ad-hoc changes.

Depends on dybvig/stex#7

Author: LiberalArtist

.gitignore

@@ -24,8 +24,10 @@
 /xc-*/
 /em-*/
 *.*run
+*.katex-css-link
 /csug/math/
 /csug/gifs/
+/csug/katex/
 /csug/Makefile
 /csug/*.aux
 /csug/*.html
@@ -50,6 +52,7 @@
 /csug/primdata.ss
 /release_notes/math/
 /release_notes/gifs/
+/release_notes/katex/
 /release_notes/Makefile
 /release_notes/*.tex
 /release_notes/*.aux

BUILDING

@@ -307,7 +307,7 @@ The makefile supports several targets:
  * `make docs`
 
    Runs the build plus generates HTML and PDF versions of the Chez
-   Scheme Users Guide and the release notes. Unlike the other build
+   Scheme User's Guide and the release notes. Unlike the other build
    targets, the documentation is not built in the workarea, but rather
    in the "csug" and "release_notes" directories (where "configure" is
    run).
@@ -320,6 +320,14 @@ The makefile supports several targets:
 
     * ppmtogif and pnmcrop (from Netpbm)
 
+    * Optionally, KaTeX (for better math in HTML)
+
+   To use KaTeX but not copy the supporting CSS and font files
+   (e.g. because you wish to link to a copy already installed on your
+   system), use `make docs KATEX_CSS=no`. See also the documentation
+   in the "stex/doc" directory for further details and additional
+   configuration options.
+
    An X11 installation is not required, but ppmtogif does require an
    "rgb.txt" file, which it will automatically locate in the common
    X11 installation locations. If ppmtogif fails because it cannot
@@ -330,6 +338,16 @@ The makefile supports several targets:
    installation, then it might contain an "rgb.txt" in the directory
    identified by the `VIMRUNTIME` environment variable.
 
+ * `make csug` or `make release_notes`
+
+   Like `make docs`, but builds only the Chez Scheme User's Guide or
+   the release notes, respectively.
+
+ * `sudo make install-docs` (or `install-csug` or `install-release_notes`)
+
+   Like `make docs` (or `make csug` or `make release_notes`, respectively),
+   but also installs the built documentation.
+
  * `make clean`
 
    Removes all built elements from the workarea, and then removes

build.zuo

@@ -245,14 +245,26 @@
     (define name-sym (string->symbol name))
     (define (run-make target)
       (check-not-kernel-only)
+      ;; Note: build.bat on Windows does not currently configure these
+      ;; settings, so only evaluate (hash-ref config ...) when trying to
+      ;; build a target, not while merely generating the list of targets.
+      (define install-dir
+        (hash-ref config install-dir-key))
+      (define other-install-dir-key
+        (car (remove install-dir-key doc-install-dir-keys)))
+      (define other-install-dir
+        (hash-ref config other-install-dir-key))
       (define (->rel-shell pth)
         (string->shell (find-relative-path doc-dir pth)))
       (shell/wait "make"
                   (~a "m=" m)
                   (~a "srcdir=" (->rel-shell (at-source name)))
-                  (~a "installdir="
-                      (->rel-shell (hash-ref config install-dir-key)))
+                  (~a "installdir=" (->rel-shell install-dir))
                   (~a "STEXLIB=" (->rel-shell stexlib))
+                  (~a other-install-dir-key "=" (->rel-shell other-install-dir))
+                  (~a "rel" other-install-dir-key "="
+                      (string->shell (find-relative-path install-dir
+                                                         other-install-dir)))
                   target
                   (hash 'dir doc-dir)))
     `([:target ,mf-out (,mf-in)

csug/csug.css

@@ -33,3 +33,5 @@ h1, h2, h3, h4 {font-weight: bold}
 
 table.indent {margin-left: 20px}
 
+.schemedisplay { line-height: 1.0625; }
+.schemedisplay .katex { font-size: 1em; }

csug/csug.stex

@@ -53,7 +53,7 @@
 
 % Just don't care about small overflows, most of the time:
 \iflatex
-\hfuzz=16.0pt
+\hfuzz=26.0pt
 \fi
 
 \iflatex

csug/csug8.cls

@@ -376,7 +376,11 @@
 %%% index
 \newenvironment{theindex}
                {\if@openright\cleardoublepage\else\clearpage\fi
-                \begingroup\raggedright\schemeindexsize\footnotesize
+                \begingroup\raggedright\footnotesize
+                % tighten spacing for entries:
+                % may need to adjust this for future changes in stex
+                \def\scheme##1{\mbox{\fontsize{7}{8}\ttfamily\frenchspacing\spaceskip=0.5\fontdimen2\font plus \fontdimen3\font minus 0.5\fontdimen4\font##1}}
+                \def\var##1{{\footnotesize\textit{##1}}}
                 \columnseprule \z@
                 \columnsep 35\p@
                 \twocolumn[\plainchapterhead{\indexname}]%
@@ -457,6 +461,8 @@
 \def\categorymodule{module}
 \def\categoryftype{ftype}
 
+%%% summary of forms
+% see also summary.stex and summary.ss
 \newwrite\forms
 \openout\forms=\jobname.rfm
 % \formsummary{sort key}{type}{form}{label}
@@ -471,7 +477,11 @@
   \hbox to 5pc{#2\ \hfil}%
   \hfil #3}}
 \newenvironment{thesummary}
-  {\begingroup\schemesummarysize\small\bigskip
+  {\begingroup\small\bigskip%
+   % tighten spacing to fit entries on one line:
+   % may need to adjust this for future changes in stex
+   \def\scheme##1{\mbox{\fontsize{8}{9}\ttfamily\frenchspacing\spaceskip=0.5\fontdimen2\font plus \fontdimen3\font minus 0.5\fontdimen4\font##1}}%
+   \def\var##1{{\footnotesize\textit{##1}}}%
    \sfentry{{\slshape Form}}{{\slshape Category}}{{\slshape Page}}
    \kern3pt\hrule\kern3pt}
   {\endgroup}

csug/scheme.hsty

@@ -1,5 +1,7 @@
 srcdir=oops-missing-srcdir
 installdir=oops-missing-installdir
+InstallReleaseNotes=oops-missing-InstallReleaseNotes
+relInstallReleaseNotes=oops-missing-relInstallReleaseNotes
 m=oops-missing-m
 STEXLIB=oops-missing-stexlib
 # Zuo overrides the above variables when running `make`
@@ -17,18 +19,6 @@ DIR=$(shell basename `pwd`)
 
 target: canned logcheck1 logcheck2 checklibs $(x).html $(x).pdf
 
-install: target
-	$(INSTALL) -m 2755 -d $(installdir)
-	$(INSTALL) -m 0644 --ifdiff *.html *.css $(installdir)
-	$(INSTALL) -m 0644 --ifdiff csug.pdf $(installdir)/csug10_0.pdf
-	$(INSTALL) -m 2755 -d $(installdir)/canned
-	$(INSTALL) -m 0644 --ifdiff canned/* $(installdir)/canned
-	$(INSTALL) -m 2755 -d $(installdir)/gifs
-	$(INSTALL) -m 0644 --ifdiff gifs/*.gif $(installdir)/gifs
-	$(INSTALL) -m 2755 -d $(installdir)/$(mathdir)
-	$(INSTALL) -m 0644 --ifdiff $(mathdir)/*.gif $(installdir)/$(mathdir)
-	(cd $(installdir); ln -s -f $(x).html index.html)
-
 # thrice is not enough when starting from scratch
 logcheck1: $(x).thirdrun
 	@if [ -n "`grep 'Warning: Label(s) may have changed' $(x).log`" ] ; then\
@@ -50,14 +40,43 @@ logcheck2: $(x).thirdrun
 
 include $(STEXLIB)/Mf-stex
 
+install: target
+	$(INSTALL) -m 2755 -d $(installdir)
+	$(INSTALL) -m 0644 --ifdiff *.html *.css $(installdir)
+	$(INSTALL) -m 0644 --ifdiff csug.pdf $(installdir)/csug10_0.pdf
+	$(INSTALL) -m 2755 -d $(installdir)/canned
+	$(INSTALL) -m 0644 --ifdiff canned/* $(installdir)/canned
+	$(INSTALL) -m 2755 -d $(installdir)/gifs
+	$(INSTALL) -m 0644 --ifdiff gifs/*.gif $(installdir)/gifs
+ifeq ($(strip $(KATEX)),)
+	$(INSTALL) -m 2755 -d $(installdir)/$(mathdir)
+	$(INSTALL) -m 0644 --ifdiff $(mathdir)/*.gif $(installdir)/$(mathdir)
+else ifneq ($(strip $(KATEX_CSS)),no)
+# if already installed release_notes, share katex.css and fonts
+	(if $(if $(findstring Windows,$(OS)),[ ! "windows" ],[ -e $(InstallReleaseNotes)/katex/katex.css ] && [ ! -L $(InstallReleaseNotes)/katex ]) ; \
+	 then \
+	   (cd $(installdir); ln -s -f $(relInstallReleaseNotes)/katex katex) ; \
+	 else \
+	   $(INSTALL) -m 2755 -d $(installdir)/katex/fonts ; \
+	   $(INSTALL) -m 0644 --ifdiff katex/katex.css $(installdir)/katex/katex.css ; \
+	   $(INSTALL) -m 0644 --ifdiff katex/fonts/* $(installdir)/katex/fonts ; \
+	 fi)
+endif
+ifeq ($(OS),Windows_NT)
+	cp $(installdir)/$(x).html $(installdir)/index.html
+else
+	(cd $(installdir); ln -s -f $(x).html index.html)
+endif
+
+
 stexsrc = csug.stex title.stex copyright.stex contents.stex\
  preface.stex intro.stex use.stex expeditor.stex debug.stex foreign.stex\
  binding.stex control.stex objects.stex numeric.stex io.stex\
  libraries.stex syntax.stex system.stex smgmt.stex threads.stex\
  compat.stex bibliography.stex summary.stex
 texsrc = ${stexsrc:%.stex=%.tex}
 
-moresrc = tspl4-prep.stex priminfo.ss docond.ss csug8.cls csug8.hcls csug810.clo scheme.sty csug.bib \
+moresrc = tspl4-prep.stex priminfo.ss docond.ss csug8.cls csug8.hcls csug810.clo csug.bib \
  setup.ss summary.ss tspl.bst
 
 $(stexsrc) $(moresrc):
@@ -136,9 +155,14 @@ $(x).hprethirdrun: $(x).hsecondrun
 	cat tspl.haux >> $x.haux
 	touch $(x).hprethirdrun
 
+$(x).hfourthrun: $(x).hprefourthrun
+$(x).hprefourthrun: $(x).hthirdrun
+	cat tspl.haux >> $x.haux
+	touch $(x).hprefourthrun
+
 $(x).prefirstrun: $(texsrc) csug8.cls csug810.clo
 
-$(x).firstrun: scheme.sty
+$(x).firstrun:
 
 tspl.aux: ${TSPLdir}/tspl.aux
 	cat ${TSPLdir}/*.aux | grep '\\newlabel' | \

csug/scheme.sty

@@ -1,5 +1,7 @@
 srcdir=oops-missing-srcdir
 installdir=oops-missing-installdir
+InstallCSUG=oops-missing-InstallCSUG
+relInstallCSUG=oops-missing-relInstallCSUG
 m=oops-missing-m
 STEXLIB=oops-missing-stexlib
 # Zuo overrides the above variables when running `make`
@@ -25,7 +27,7 @@ bib =
 include $(STEXLIB)/Mf-stex
 
 srcs = $(x).stex releasenotes.cls releasenotes.hcls \
-  macros.stex releasenotes.css scheme.sty
+  macros.stex releasenotes.css
 
 # define or override suffixes here
 
@@ -42,10 +44,22 @@ install: $x.pdf $x.html
          fi)
 	$(INSTALL) -m 2755 -d $(installdir)/gifs
 	$(INSTALL) -m 0644 --ifdiff gifs/*.gif $(installdir)/gifs
-	$(INSTALL) -m 2755 -d $(installdir)/math
 	-rm -rf $(installdir)/$(mathdir)
+ifeq ($(strip $(KATEX)),)
+	$(INSTALL) -m 2755 -d $(installdir)/math
 	$(INSTALL) -m 2755 -d $(installdir)/$(mathdir)
 	if [ -e $(mathdir)/0.gif ] ; then $(INSTALL) -m 0644 $(mathdir)/*.gif $(installdir)/$(mathdir) ; fi
+else ifneq ($(strip $(KATEX_CSS)),no)
+# if already installed csug, share katex.css and fonts
+	(if $(if $(findstring Windows,$(OS)),[ ! "windows" ],[ -e $(InstallCSUG)/katex/katex.css ] && [ ! -L $(InstallCSUG)/katex ]) ; \
+	 then \
+	   (cd $(installdir); ln -s -f $(relInstallCSUG)/katex katex) ; \
+	 else \
+	   $(INSTALL) -m 2755 -d $(installdir)/katex/fonts ; \
+	   $(INSTALL) -m 0644 --ifdiff katex/katex.css $(installdir)/katex/katex.css ; \
+	   $(INSTALL) -m 0644 --ifdiff katex/fonts/* $(installdir)/katex/fonts ; \
+	 fi)
+endif
 
 # define any dependencies here
 

makefiles/Makefile-csug.in

@@ -55,3 +55,5 @@ table.indent {margin-left: 20px}
 .tag{ color: navy; font-weight: bold; }
 .entity{ color: purple; font-weight: bold; }
 .errflag{ color: red; font-weight: bold; }
+.schemedisplay { line-height: 1.0625; }
+.schemedisplay .katex { font-size: 1em; }